@ggui-ai/iframe-runtime 0.15.0 → 0.16.0

package/dist/runtime.js

@@ -27,13 +27,13 @@
 // FIRST import on purpose — declares zod jitless before any
 // schema-defining dependency initializes (see zod-jitless.ts).
 import './zod-jitless.js';
-import { connectionStore } from './connection.js';
+import { runtimeConnectionWriter } from './connection.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 { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, reportInvalidAppTheme, } from './meta-parse.js';
 import { projectHostContext } from '@ggui-ai/protocol/wire';
 import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
-import { applyHostContextStyling, attachListener as attachHostContextListener, seed as seedHostContext, } from './host-context-emitter.js';
+import { applyHostContextStyling, attachListener as attachHostContextListener, seed as seedHostContext, subscribeThemeChange as subscribeHostThemeChange, } 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';
@@ -171,6 +171,11 @@ export function setCurrentApp(app) {
 function getCurrentApp() {
     return currentApp;
 }
+/**
+ * The live theme re-injection's subscription (ggui#987 §4), held so a
+ * re-entered boot replaces it instead of stacking a second subscriber.
+ */
+let activeThemeUnsubscribe = null;
 /**
  * The host's announced color mode, read from the connected App's
  * pre-merged hostContext (`ui/initialize` result, kept current by the
@@ -185,10 +190,11 @@ function getCurrentApp() {
  * `color-scheme` via `applyDocumentTheme` — nothing in the token
  * pipeline keys off it, so a dark host painted the light ladder
  * (host-fit 46.0 vs 87.7 with the dark ladder, probe `cc728a8eb`).
- * `buildOpts` consumes this ONLY when the slice stamps no `themeMode`:
- * every operator layer (live provider > per-render override > app
- * default > server default) still wins by being stamped; the host
- * fills the gap where no operator had an opinion.
+ * Under ggui#987 §4 the embedding host OWNS runtime mode: when it
+ * announces one, `buildOpts` paints it over every stamped opinion; the
+ * stamped layers decide only when the host is silent. Read live from
+ * the App's pre-merged hostContext, so a `hostcontextchanged` flip
+ * re-resolves on the next `buildOpts`.
  *
  * @internal — exported for unit tests (`setCurrentApp` injects the
  *   App); production caller is `buildOpts` inside `bootSequence`.
@@ -198,36 +204,30 @@ export function hostAnnouncedThemeMode() {
     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"):
+ * Resolve the mount's color mode (ggui#987 §4 — the embedding host owns
+ * runtime mode; the app theme's `mode` is a DEFAULT, never a pin):
  *
- *   stamped `themeMode`  >  `theme.mode` (the slice theme OBJECT)  >
- *   host-announced theme  >  undefined
+ *   host-announced theme  >  stamped `themeMode`  >  `theme.mode`
+ *   (the app theme's default)  >  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.
+ * A card that ignored the host's announced mode painted a light
+ * skeleton inside a dark chat — the host's word is what the user
+ * actually sees around the card. The stamped layers (live provider >
+ * per-render override > app default > server default) decide only when
+ * the host is silent, which is the adapter-boundary case (a host
+ * helper that announces no `hostContext.theme`).
  *
  * `undefined` still means "no opinion anywhere" — the renderer's
- * default applies; never coerced to `'light'`.
+ * default applies; never coerced to `'light'` here (ggui#551).
  *
  * @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.
+    // total order (@ggui-ai/protocol/integrations/theme-binding) — 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,
@@ -235,20 +235,14 @@ export function resolveMountThemeMode(meta) {
     });
 }
 /**
- * Resolve the mount's base-theme id from the slice (ggui#589 ask 3):
+ * Resolve the mount's compiled-ladder id from the slice (ggui#987 D2):
  *
- *   stamped `themeId`  >  `theme.name` (the slice theme OBJECT's name)
- *   >  undefined (renderer default ladder)
+ *   stamped `themeId`  >  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.
+ * The app theme's `name` is a LABEL the author's tooling reads back —
+ * it never selects a ladder. An app theme carries its own full
+ * projection (`overlays`, exactly the manifest minus the floor), so
+ * there is no coverage gap for a compiled theme to fill beneath it.
  *
  * @internal — exported for unit tests; production caller is
  *   `buildOpts` inside `bootSequence`.
@@ -256,10 +250,7 @@ export function resolveMountThemeMode(meta) {
 export function resolveMountThemeId(meta) {
     // Client projection of the normative theme-binding order — see
     // resolveMountThemeMode above.
-    return effectiveThemeId({
-        stamped: meta.themeId,
-        sidecarName: meta.theme?.name,
-    });
+    return effectiveThemeId({ stamped: meta.themeId });
 }
 /**
  * The host's announced palette, read from the connected App's
@@ -461,7 +452,7 @@ export async function bootSequence(opts) {
     // `tools/call` (dispatchSubmitAction, channel-transport router)
     // routes through `app.callServerTool` instead of the legacy raw
     // postMessage pump. Idempotent: re-boot with the same App is a
-    // no-op; a different App throws (the iframe is single-tenant).
+    // no-op; a different App throws (the iframe is single-app).
     setCurrentApp(app);
     // Slice-meta resolution — spec-canonical primary, no in-house
     // Reading-B (retired Phase 1.19b.3 with the App-class swap; the
@@ -1356,7 +1347,7 @@ export async function resolveMetaViaReadDoor(app, locator) {
     const envelope = readGguiShellEnvelope(text);
     if (envelope === undefined)
         return null;
-    const parsed = parseMcpAppAiGguiRenderMeta(envelope);
+    const parsed = parseMcpAppAiGguiRenderMeta(envelope, { onInvalidTheme: reportInvalidAppTheme });
     if (!parsed.ok || parsed.meta === undefined)
         return null;
     const validated = validateMeta(parsed.meta);
@@ -1406,7 +1397,7 @@ function awaitToolResultMeta(timeoutMs) {
  * 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
+ * (a re-booted document in tests; production is single-app per
  * iframe) always gets its own registration, never a stale latch.
  */
 const persistentToolResultListenerApps = new WeakSet();
@@ -1883,7 +1874,7 @@ function applyFreezeCue(root) {
         fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
         fontSize: '11px',
         fontWeight: '600',
-        color: 'var(--ggui-color-onSurface, inherit)',
+        color: 'var(--ggui-color-onContainer, inherit)',
         background: 'rgba(128,128,128,0.16)',
         border: '1px solid currentColor',
         opacity: '0.85',
@@ -2320,7 +2311,7 @@ let relayLatchTrigger;
 let relayLatchScope = {};
 function transitionRelayLatch(next, trigger, scope = {}) {
     relayIncapabilityAnnounced = next;
-    connectionStore.set(!next);
+    runtimeConnectionWriter().set(!next);
     if (next && trigger !== undefined) {
         relayLatchedAt = Date.now();
         relayDeadTaps = 0;
@@ -2435,6 +2426,10 @@ function isRelayNoticeVisible() {
  * @internal — exported for unit tests.
  */
 export function resetRelayLatchForBoot() {
+    // The runtime's claim on the document's connection writer is taken HERE,
+    // eagerly, before any transition (ggui#843): a second runtime in this
+    // document fails at boot naming itself, never continuing unclaimed.
+    runtimeConnectionWriter();
     if (typeof document !== 'undefined') {
         const el = document.getElementById(ACTION_TOAST_ID);
         if (el !== null && el.hasAttribute(RELAY_NOTICE_ATTR))
@@ -2445,14 +2440,14 @@ export function resetRelayLatchForBoot() {
         transitionRelayLatch(false);
     }
     else {
-        connectionStore.set(true);
+        runtimeConnectionWriter().set(true);
     }
 }
 /**
  * Module-level handle to the CURRENT boot's telemetry sink so
  * module-scope paths (the doorbell emitter below) can report without
  * threading the sink through every call chain. Per-iframe
- * single-tenancy makes a single slot correct — same justification as
+ * single-app scope makes a single slot correct — same justification as
  * `getCurrentApp()`.
  */
 let currentTelemetrySink = null;
@@ -2540,7 +2535,7 @@ function resetRelayCueThrottles() {
 /** @internal — exported for unit tests to reset module state. */
 export function __resetRelayNoticeForTest() {
     relayIncapabilityAnnounced = false;
-    connectionStore.set(true);
+    runtimeConnectionWriter().set(true);
     relayLatchedAt = undefined;
     relayDeadTaps = 0;
     relayLatchTrigger = undefined;
@@ -3712,10 +3707,10 @@ async function bootProduction(opts) {
             // 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
+            // hoist note in server.ts). A deployment composing its own `handlers`
+            // IS such a 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
+            // open design leg) therefore requires the server-side 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` +
@@ -3864,29 +3859,27 @@ async function bootProduction(opts) {
                         !('createdAt' in render)
                         ? { codeModuleUrl: meta.codeModuleUrl }
                         : {}),
-                    // 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).
+                    // Compiled ladder (see `resolveMountThemeId`): the stamped
+                    // themeId alone; absent = the renderer's default ladder.
                     ...(() => {
                         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".
+                    // Mode (ggui#987 §4 — see `resolveMountThemeMode`): host-
+                    // announced theme > stamped `themeMode` > the app theme's
+                    // default `mode`. Absent everywhere means "no opinion", not
+                    // "light". Re-resolved on every buildOpts, so the live
+                    // hostcontextchanged re-injection below picks up a flip.
                     ...(() => {
                         const themeMode = resolveMountThemeMode(meta);
                         return themeMode !== undefined ? { themeMode } : {};
                     })(),
-                    // Per-app theme overlay (St3 M2.2). Threaded straight from the
+                    // Per-app theme (ggui#987 v2). Threaded straight from the
                     // bootstrap's `_meta["ai.ggui/render"].theme` (typed `AppTheme`,
                     // already injection-validated by the wire parser) onto the mount
-                    // options so the renderer applies the `--ggui-*` overrides +
-                    // `color-scheme` at `:root`. THEME IS COMPONENT-ONLY — system
-                    // cards theme via the SystemCardHost/ThemeProvider path.
+                    // options; the renderer injects the effective mode's overlay
+                    // into the scoped block + `: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
@@ -3912,14 +3905,52 @@ async function bootProduction(opts) {
              * layer just calls `applyRender(render)` without owning
              * lifecycle state.
              */
+            // Every in-place update of the mounted slot goes through ONE
+            // chain: the WS render-frame / props_update path and the live
+            // theme re-injection below are independent callers, and the
+            // handle's `update` has no lock of its own — serializing them
+            // here is what keeps a host flip landing mid-render from
+            // interleaving two updates.
+            let updateChain = Promise.resolve();
+            const queueUpdate = (opts) => {
+                const run = updateChain.then(async () => {
+                    if (renderHandle === null)
+                        return;
+                    await renderHandle.update(opts());
+                });
+                updateChain = run.catch(() => undefined);
+                return run;
+            };
             const applyRender = async (render) => {
                 currentRender = render;
                 if (renderHandle === null) {
                     renderHandle = await mountRender(renderInto, buildOpts(render));
                     return;
                 }
-                await renderHandle.update(buildOpts(render));
+                await queueUpdate(() => buildOpts(render));
             };
+            // Live re-injection (ggui#987 §4): the host owns runtime mode and
+            // may flip it mid-session. The trigger is the emitter's THEME
+            // subscription — the raw `theme` / `styles` payload — because the
+            // host-context projection excludes both by design and its
+            // equality gate would never fire for a theme-only flip. The App
+            // pre-merges the new hostContext before the emitter fans out, so
+            // re-running `buildOpts` on the CURRENT render re-resolves mode +
+            // palette and the renderer repaints from the retained other
+            // overlay — no fetch, no remount. A rejection is reported to the
+            // embedding host, never dropped on the floor.
+            activeThemeUnsubscribe?.();
+            activeThemeUnsubscribe = subscribeHostThemeChange(() => {
+                if (renderHandle === null || currentRender === null)
+                    return;
+                const render = currentRender;
+                queueUpdate(() => buildOpts(render)).catch((err) => {
+                    postObservabilityToParent({
+                        kind: 'theme-reinject-failed',
+                        message: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            });
             // 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

package/dist/system-cards/NoCredentialsCard.js

@@ -36,7 +36,7 @@ function GguiWordmark() {
     // off-white in dark). `gray-300` flips too — the gray scale in
     // `darkTheme` is intentionally inverted, so the wordmark's
     // contrasting "chrome" tone reads correctly under either theme.
-    const ink = 'var(--ggui-color-onSurface, #292929)';
+    const ink = 'var(--ggui-color-onContainer, #292929)';
     const chrome = 'var(--ggui-color-neutral-300, #d1d5db)';
     return (_jsxs("svg", { viewBox: "0 0 224 50", width: "72", height: "16", role: "img", "aria-label": "ggui", style: { display: 'block', flexShrink: 0 }, children: [_jsx("path", { d: "M 0 0 H 50 V 25 H 25 V 50 H 0 Z", fill: chrome }), _jsx("rect", { x: "33", y: "33", width: "17", height: "17", fill: ink }), _jsx("path", { d: "M 58 0 H 108 V 25 H 83 V 50 H 58 Z", fill: ink }), _jsx("rect", { x: "91", y: "33", width: "17", height: "17", fill: chrome }), _jsx("path", { d: "M 141 50 C 154.807 50 166 38.8071 166 25 V 0 H 116 V 25 C 116 38.8071 127.193 50 141 50 Z", fill: ink }), _jsx("rect", { x: "174", y: "0", width: "50", height: "50", fill: chrome })] }));
 }
@@ -87,10 +87,10 @@ export function NoCredentialsCard({ settingsUrl, intent, }) {
     // INVERTED in darkTheme so `gray-100` is light-on-dark when in
     // dark mode and dark-on-light when in light mode).
     //
-    //   - `--ggui-color-surface` — opaque card surface (white in light,
+    //   - `--ggui-color-container` — opaque card surface (white in light,
     //     slate-800 in dark). Used for the URL block + QR backdrop.
-    //   - `--ggui-color-onSurface` — high-contrast body text.
-    //   - `--ggui-color-onSurfaceVariant` — muted captions/headings.
+    //   - `--ggui-color-onContainer` — high-contrast body text.
+    //   - `--ggui-color-onSunken` — muted captions/headings.
     //   - `--ggui-color-neutral-100` — subtle tinted background that
     //     auto-flips. Used for the inner "details" panel — slightly
     //     differentiated from outer transparent canvas without being
@@ -103,7 +103,7 @@ export function NoCredentialsCard({ settingsUrl, intent, }) {
     // background creates a card-on-card look. Padding stays so content
     // doesn't crowd the iframe edges. Outside Claude (preview iframe,
     // console inspector), the ThemeProvider's body background is the
-    // theme's `--ggui-color-surface`, so a transparent card just
+    // theme's `--ggui-color-container`, so a transparent card just
     // shows the theme's canvas behind it — also fine.
     _jsx(Card, { padding: "lg", border: false, shadow: "none", style: { backgroundColor: 'transparent' }, children: _jsxs(Stack, { gap: "lg", children: [_jsxs(Stack, { gap: "md", children: [_jsxs("div", { style: {
                                 display: 'flex',
@@ -118,11 +118,11 @@ export function NoCredentialsCard({ settingsUrl, intent, }) {
                             }, children: [_jsx(Heading, { level: 3, children: "Connect an LLM provider" }), _jsx("code", { style: {
                                         fontFamily: 'var(--ggui-font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace)',
                                         fontSize: 'var(--ggui-font-size-xs, 11px)',
-                                        color: 'var(--ggui-color-onSurfaceVariant, #71717a)',
+                                        color: 'var(--ggui-color-onSunken, #71717a)',
                                         opacity: 0.7,
                                         userSelect: 'all',
                                     }, title: "iframe-runtime build identifier \u2014 useful for diagnosing stale caches", children: BUILD_ID })] }), _jsx(Text, { style: {
-                                color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                color: 'var(--ggui-color-onSunken, #52525b)',
                                 lineHeight: '1.55',
                             }, children: "ggui needs an LLM key to render UIs. Open this server\u2019s settings page to paste an Anthropic, OpenAI, Google, or OpenRouter API key." })] }), _jsx("div", { style: {
                         display: 'flex',
@@ -148,7 +148,7 @@ export function NoCredentialsCard({ settingsUrl, intent, }) {
                                             borderRadius: 'var(--ggui-shape-radius-sm, 6px)',
                                             lineHeight: 0,
                                         }, children: _jsx(QrCode, { value: settingsUrl, size: 120, foreground: "#000000", background: "#ffffff" }) }), _jsx(Text, { size: "xs", style: {
-                                            color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                            color: 'var(--ggui-color-onSunken, #52525b)',
                                             fontSize: 'var(--ggui-font-size-xs, 11px)',
                                             textAlign: 'center',
                                         }, children: "Scan with your phone" })] }), _jsxs("div", { style: {
@@ -158,7 +158,7 @@ export function NoCredentialsCard({ settingsUrl, intent, }) {
                                     flex: '1 1 240px',
                                     minWidth: '200px',
                                 }, children: [_jsx(Text, { size: "xs", style: {
-                                            color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                            color: 'var(--ggui-color-onSunken, #52525b)',
                                             fontWeight: 'var(--ggui-font-weight-semibold, 600)',
                                             textTransform: 'uppercase',
                                             letterSpacing: '0.06em',
@@ -166,11 +166,11 @@ export function NoCredentialsCard({ settingsUrl, intent, }) {
                                         }, children: "Or open this URL in your browser" }), _jsx("div", { style: {
                                             fontFamily: 'var(--ggui-font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace)',
                                             fontSize: 'var(--ggui-font-size-sm, 13px)',
-                                            color: 'var(--ggui-color-onSurface, #111)',
+                                            color: 'var(--ggui-color-onContainer, #111)',
                                             wordBreak: 'break-all',
                                             userSelect: 'all',
                                             padding: 'var(--ggui-spacing-3, 12px)',
-                                            background: 'var(--ggui-color-surface, #fff)',
+                                            background: 'var(--ggui-color-container, #fff)',
                                             border: '1px solid var(--ggui-color-neutral-200, #e4e4e7)',
                                             borderRadius: 'var(--ggui-shape-radius-sm, 6px)',
                                             lineHeight: '1.45',
@@ -180,10 +180,10 @@ export function NoCredentialsCard({ settingsUrl, intent, }) {
                                             gap: 'var(--ggui-spacing-3, 12px)',
                                             flexWrap: 'wrap',
                                         }, children: [_jsx(Button, { variant: "primary", size: "md", onClick: onPrimary, disabled: ctaDisabled, children: ctaLabel }), ctaState === 'idle' || ctaState === 'working' ? (_jsx(Text, { size: "xs", style: {
-                                                    color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                                    color: 'var(--ggui-color-onSunken, #52525b)',
                                                     opacity: 0.85,
                                                 }, children: "or tap-and-hold the URL above to copy" })) : null] })] })] }) }), intent ? (_jsxs(Text, { size: "xs", style: {
-                        color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                        color: 'var(--ggui-color-onSunken, #52525b)',
                         opacity: 0.7,
                     }, children: ["Pending prompt: ", intent] })) : null] }) }));
 }

package/dist/system-cards/ProtocolProbeCard.js

@@ -372,7 +372,7 @@ function ProbeButtonRow({ method, description, call, }) {
             padding: 'var(--ggui-spacing-3, 12px)',
             borderRadius: 'var(--ggui-shape-radius-md, 10px)',
             border: '1px solid var(--ggui-color-neutral-200, #e4e4e7)',
-            background: 'var(--ggui-color-surface, #fff)',
+            background: 'var(--ggui-color-container, #fff)',
         }, children: [_jsxs("div", { style: {
                     display: 'flex',
                     alignItems: 'center',
@@ -382,10 +382,10 @@ function ProbeButtonRow({ method, description, call, }) {
                 }, children: [_jsx("code", { style: {
                             fontFamily: 'var(--ggui-font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace)',
                             fontSize: 'var(--ggui-font-size-sm, 13px)',
-                            color: 'var(--ggui-color-onSurface, #111)',
+                            color: 'var(--ggui-color-onContainer, #111)',
                             fontWeight: 'var(--ggui-font-weight-semibold, 600)',
                         }, children: method }), statusBadge] }), _jsx(Text, { size: "xs", style: {
-                    color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                    color: 'var(--ggui-color-onSunken, #52525b)',
                     fontSize: 'var(--ggui-font-size-xs, 11px)',
                 }, children: description }), _jsx("div", { style: { display: 'flex', gap: 'var(--ggui-spacing-2, 8px)' }, children: _jsx(Button, { variant: "primary", size: "sm", onClick: onClick, disabled: outcome.state === 'pending', children: buttonLabel }) }), outcome.state === 'success' || outcome.state === 'error' ? (_jsx("pre", { style: {
                     margin: 0,
@@ -393,7 +393,7 @@ function ProbeButtonRow({ method, description, call, }) {
                     fontSize: 'var(--ggui-font-size-xs, 11px)',
                     color: outcome.state === 'error'
                         ? 'var(--ggui-color-warning-500, #b45309)'
-                        : 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                        : 'var(--ggui-color-onSunken, #52525b)',
                     background: 'var(--ggui-color-neutral-100, #f4f4f5)',
                     padding: 'var(--ggui-spacing-2, 8px)',
                     borderRadius: 'var(--ggui-shape-radius-sm, 6px)',
@@ -414,7 +414,7 @@ export function ProtocolProbeCard({ intent, }) {
                                 gap: 'var(--ggui-spacing-3, 12px)',
                                 flexWrap: 'wrap',
                             }, children: [_jsx(Heading, { level: 3, children: "MCP Apps protocol probe" }), _jsx(Badge, { variant: "info", children: "diagnostic" })] }), _jsxs(Text, { style: {
-                                color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                color: 'var(--ggui-color-onSunken, #52525b)',
                                 lineHeight: '1.55',
                             }, children: ["One button per primary host effect emitted by the iframe runtime's gesture surfaces (submit-action bridge / native- idiom interceptors). Click each to verify which methods this host honors. The", _jsx("code", { children: "tools/call" }), " row chains the full submit-action bridge (audit + context + consent), reproducing the production ", _jsx("code", { children: "dispatchSubmitAction" }), " envelope shape verbatim. The receive log below captures every notification the host emits while this card is mounted."] })] }), _jsxs(Stack, { gap: "md", children: [_jsx(ProbeButtonRow, { method: "ui/message", description: "Submit-action bridge step 3 \u2014 consent-gated user authorization. Host pre-fills + waits for user confirm before the LLM acts on the paired pending-action context.", call: call }), _jsx(ProbeButtonRow, { method: "ui/update-model-context", description: "Submit-action bridge step 2 \u2014 silent structured `[ggui:pending-action]` context drop. LLM honors on next turn. No immediate UI.", call: call }), _jsx(ProbeButtonRow, { method: "ui/open-link", description: "Native-idiom anchor click interceptor primary effect. Opens ggui.ai in the host's browser / new tab. Real iframe code triggers via `<a href target='_blank'>` or cross-origin href.", call: call }), _jsx(ProbeButtonRow, { method: "ui/request-display-mode", description: "Native-idiom fullscreen interceptor primary effect. Request fullscreen \u2014 real iframe code calls `el.requestFullscreen()`; the runtime overrides the prototype to route through here.", call: call }), _jsx(ProbeButtonRow, { method: "tools/call", description: "Full submit-action bridge: `tools/call ggui_runtime_submit_action` (audit, kind:'dispatch') + `ui/update-model-context` + `ui/message`. Spec \u00A7401 requires `_meta.ui.visibility:['app']` on the receiving tool.", call: call })] }), _jsxs(Stack, { gap: "sm", children: [_jsxs("div", { style: {
                                 display: 'flex',
@@ -422,10 +422,10 @@ export function ProtocolProbeCard({ intent, }) {
                                 justifyContent: 'space-between',
                                 gap: 'var(--ggui-spacing-3, 12px)',
                             }, children: [_jsx(Heading, { level: 4, children: "Receive log" }), _jsxs(Text, { size: "xs", style: {
-                                        color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                        color: 'var(--ggui-color-onSunken, #52525b)',
                                         fontSize: 'var(--ggui-font-size-xs, 11px)',
                                     }, children: [log.length, " ", log.length === 1 ? 'event' : 'events'] })] }), log.length === 0 ? (_jsx(Text, { size: "xs", style: {
-                                color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                color: 'var(--ggui-color-onSunken, #52525b)',
                                 fontStyle: 'italic',
                             }, children: "No host notifications observed yet. Click a probe button or wait for the host to emit one." })) : (_jsx("div", { style: {
                                 display: 'flex',
@@ -443,17 +443,17 @@ export function ProtocolProbeCard({ intent, }) {
                                 }, children: [_jsxs("summary", { style: {
                                             cursor: 'pointer',
                                             padding: 'var(--ggui-spacing-1, 4px) 0',
-                                            color: 'var(--ggui-color-onSurface, #111)',
+                                            color: 'var(--ggui-color-onContainer, #111)',
                                         }, children: [_jsx("span", { style: {
-                                                    color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                                    color: 'var(--ggui-color-onSunken, #52525b)',
                                                     marginRight: '8px',
                                                 }, children: entry.tsIso.slice(11, 19) }), _jsx("span", { style: { fontWeight: 600 }, children: entry.method })] }), _jsx("pre", { style: {
                                             margin: '4px 0 0 16px',
                                             whiteSpace: 'pre-wrap',
                                             wordBreak: 'break-word',
-                                            color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                                            color: 'var(--ggui-color-onSunken, #52525b)',
                                         }, children: JSON.stringify(entry.params, null, 2) })] }, entry.id))) }))] }), intent ? (_jsxs(Text, { size: "xs", style: {
-                        color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+                        color: 'var(--ggui-color-onSunken, #52525b)',
                         opacity: 0.7,
                     }, children: ["Triggered by: ", intent] })) : null] }) }));
 }

package/dist/system-cards/QrCode.js

@@ -22,7 +22,7 @@ import qrcodeFactory from 'qrcode-generator';
  * fails (e.g., URL too long for any error-correction level) so the
  * caller can render a fallback.
  */
-export function QrCode({ value, size = 128, errorCorrection = 'M', foreground = 'var(--ggui-color-onSurface, #18181b)', background = 'var(--ggui-color-surface, #ffffff)', ariaLabel, }) {
+export function QrCode({ value, size = 128, errorCorrection = 'M', foreground = 'var(--ggui-color-onContainer, #18181b)', background = 'var(--ggui-color-container, #ffffff)', ariaLabel, }) {
     const moduleMatrix = React.useMemo(() => {
         try {
             // typeNumber=0 lets the encoder pick the smallest fit. The

package/dist/system-cards/index.js

@@ -50,8 +50,8 @@ function UnknownSystemCard({ kind, props, }) {
             border: '1px solid var(--ggui-color-outlineVariant, #e4e4e7)',
             borderRadius: 'var(--ggui-shape-radius-md, 10px)',
             fontFamily: 'var(--ggui-font-family-sans, -apple-system, BlinkMacSystemFont, sans-serif)',
-            background: 'var(--ggui-color-surfaceVariant, #f4f4f5)',
-            color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
+            background: 'var(--ggui-color-sunken, #f4f4f5)',
+            color: 'var(--ggui-color-onSunken, #52525b)',
         },
     }, React.createElement('div', { style: { fontWeight: 600, marginBottom: 8 } }, `Unknown system card: ${kind}`), React.createElement('div', {
         style: {

package/dist/wire-config.d.ts

@@ -98,8 +98,8 @@ export interface BuildRootWireConfigOptions {
      * 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.
+     * channel deliberately does not bridge — a deployment composing its own
+     * `handlers` 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.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/iframe-runtime",
-  "version": "0.15.0",
+  "version": "0.16.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",
@@ -41,12 +41,12 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.15.0",
-    "@ggui-ai/gadgets": "0.15.0",
-    "@ggui-ai/live-channel": "0.15.0",
-    "@ggui-ai/preview-a2ui": "0.15.0",
-    "@ggui-ai/protocol": "0.15.0",
-    "@ggui-ai/wire": "0.15.0"
+    "@ggui-ai/design": "0.16.0",
+    "@ggui-ai/live-channel": "0.16.0",
+    "@ggui-ai/preview-a2ui": "0.16.0",
+    "@ggui-ai/gadgets": "0.16.0",
+    "@ggui-ai/protocol": "0.16.0",
+    "@ggui-ai/wire": "0.16.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0"