@ggui-ai/iframe-runtime 0.10.0 → 0.11.0

package/dist/react-renderer.d.ts

@@ -62,17 +62,37 @@ export interface ReactRootMountOptions {
      */
     readonly themeMode?: 'light' | 'dark';
     /**
-     * Per-app theme overlay applied at the iframe's `:root` AFTER the base
-     * token block, so the operator-supplied `--ggui-*` values win the
-     * cascade (a partial set — unset vars keep their token defaults). A
-     * structural subset of protocol's `AppTheme` (`name` is display-only,
-     * not needed at render). `mode` drives `color-scheme` so native
-     * controls / scrollbars / canvas pick up dark vs light.
+     * Per-app theme overlay — a partial set of `--ggui-*` values; unset
+     * vars keep their token defaults. Merged INTO the scoped in-body
+     * token block after the base block (and after `hostPalette`), which
+     * is the only placement that can recolor tree content: a `:root`-only
+     * append is cascade-dead for components — the scoped block sits later
+     * in document order and re-specifies every token (browser-verified,
+     * see the scoped-merge comment in `renderTree`). The `:root` append
+     * still happens, but for body chrome only. A structural subset of
+     * protocol's `AppTheme` (`name` is display-only, not needed at
+     * render). `mode` drives `color-scheme` so native controls /
+     * scrollbars / canvas pick up dark vs light.
+     *
+     * Precedence (ggui#573 ruling): base tokens < `hostPalette` <
+     * `appTheme` < `cssOverrides` — the slice's stamped theme always
+     * wins; the host palette is the fallback layer beneath it.
      */
     readonly appTheme?: {
         readonly mode: 'light' | 'dark';
         readonly cssVariables: Record<string, string>;
     };
+    /**
+     * Host-announced palette, already translated onto `--ggui-*` tokens
+     * (see `host-palette-bridge.ts` — the spec `--color-*` vocabulary
+     * never reaches this layer). Merged into the scoped token block
+     * after the base block and BEFORE `appTheme`, so it repaints only
+     * the slots no operator theme re-specifies (ggui#572; precedence
+     * per the ggui#573 ruling above). Values are sanitized by the
+     * bridge before they get here — host input never reaches this
+     * string-join raw.
+     */
+    readonly hostPalette?: Readonly<Record<string, string>>;
     readonly cssOverrides?: string;
     readonly onError?: (error: Error) => void;
     /**

package/dist/react-renderer.js

@@ -59,6 +59,18 @@ function makeScopeClass() {
     scopeCounter += 1;
     return `ggui-rcr-${scopeCounter}`;
 }
+/**
+ * Join a custom-property record into CSS declarations. Values were
+ * validated injection-safe upstream (appTheme: write-side
+ * `appThemeSchema` + the wire parser; hostPalette: the host-palette
+ * bridge's sanitizer), so the string-join is safe — do NOT
+ * re-sanitize here.
+ */
+function toCssDecls(vars) {
+    return Object.entries(vars)
+        .map(([k, v]) => `${k}: ${v};`)
+        .join('');
+}
 // =============================================================================
 // Error boundary — port of RCR's internal ErrorBoundary (L68–203).
 // =============================================================================
@@ -305,10 +317,16 @@ export async function mountReactRoot(container, opts) {
         let themeCss = 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
+            // re-specifies every token), BEFORE the appTheme overlay so the
+            // slice's stamped theme wins by document order. Keys + values
+            // arrive pre-sanitized from the host-palette bridge.
+            themeCss += `.${scopeClass}{${toCssDecls(opts.hostPalette)}}`;
+        }
         if (opts.appTheme) {
-            const decls = Object.entries(opts.appTheme.cssVariables)
-                .map(([k, v]) => `${k}: ${v};`)
-                .join('');
+            const decls = toCssDecls(opts.appTheme.cssVariables);
             // The overlay must be merged HERE, into the scoped style that
             // mounts INSIDE the scope div — the `:root` append below is
             // cascade-dead for tree content: the in-scope block sits later
@@ -316,9 +334,11 @@ export async function mountReactRoot(container, opts) {
             // specificity the base scoped tokens always win over a head-level
             // override (browser-verified in rnd/gen-ui/beauty/experiments/001,
             // the probe sequence that found this). Appended AFTER the base
-            // block and BEFORE `cssOverrides`, so: base < operator overlay <
-            // explicit overrides. Values validated injection-safe upstream
-            // (same guarantee the `:root` append cites).
+            // block + host palette and BEFORE `cssOverrides`, so: base <
+            // host palette < operator overlay < explicit overrides
+            // (ggui#573: slice wins, host fallback). Values validated
+            // injection-safe upstream (same guarantee the `:root` append
+            // cites).
             themeCss += `.${scopeClass}{${decls}}`;
         }
         // Also inject theme CSS at `:root` on `document.head`. The scoped
@@ -334,10 +354,15 @@ export async function mountReactRoot(container, opts) {
             let rootCss = 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:
+                // slice wins, host fallback). Keeps the embedding shell's
+                // body font/color/background coherent with the tree.
+                rootCss += `:root{${toCssDecls(opts.hostPalette)}}`;
+            }
             if (opts.appTheme) {
-                const decls = Object.entries(opts.appTheme.cssVariables)
-                    .map(([k, v]) => `${k}: ${v};`)
-                    .join('');
+                const decls = toCssDecls(opts.appTheme.cssVariables);
                 // BODY-CHROME ONLY. This `:root` append themes the embedding
                 // shell's body styles (font/color/background outside the scope
                 // div). It does NOT reach tree content — the scoped in-body

package/dist/render-item.d.ts

@@ -56,6 +56,14 @@ export interface RenderItemOptions {
         readonly mode: 'light' | 'dark';
         readonly cssVariables: Record<string, string>;
     };
+    /**
+     * Host-announced palette, pre-mapped onto `--ggui-*` tokens by the
+     * host-palette bridge. Forwarded to
+     * {@link ReactRootMountOptions.hostPalette}: the fallback layer
+     * beneath `appTheme` in the scoped token block (ggui#572, merge
+     * order per the ggui#573 ruling — slice wins, host fallback).
+     */
+    readonly hostPalette?: Readonly<Record<string, string>>;
     readonly cssOverrides?: string;
     readonly onError?: (err: Error) => void;
     /**

package/dist/render-item.js

@@ -177,6 +177,9 @@ export async function mountRender(container, opts) {
             ...(currentOpts.themeId !== undefined ? { themeId: currentOpts.themeId } : {}),
             ...(currentOpts.themeMode !== undefined ? { themeMode: currentOpts.themeMode } : {}),
             ...(currentOpts.appTheme !== undefined ? { appTheme: currentOpts.appTheme } : {}),
+            ...(currentOpts.hostPalette !== undefined
+                ? { hostPalette: currentOpts.hostPalette }
+                : {}),
             ...(currentOpts.cssOverrides !== undefined
                 ? { cssOverrides: currentOpts.cssOverrides }
                 : {}),
@@ -244,6 +247,7 @@ export async function mountRender(container, opts) {
                     ...(next.themeId !== undefined ? { themeId: next.themeId } : {}),
                     ...(next.themeMode !== undefined ? { themeMode: next.themeMode } : {}),
                     ...(next.appTheme !== undefined ? { appTheme: next.appTheme } : {}),
+                    ...(next.hostPalette !== undefined ? { hostPalette: next.hostPalette } : {}),
                     ...(next.cssOverrides !== undefined ? { cssOverrides: next.cssOverrides } : {}),
                     ...(next.onError !== undefined ? { onError: next.onError } : {}),
                     renderWrapper: wrapInScopedProvider,

package/dist/runtime.d.ts

@@ -97,6 +97,87 @@ export declare function setCurrentApp(app: App): void;
  *   App); production caller is `buildOpts` inside `bootSequence`.
  */
 export declare function hostAnnouncedThemeMode(): 'light' | 'dark' | 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 declare function resolveMountThemeMode(meta: {
+    readonly themeMode?: 'light' | 'dark';
+    readonly theme?: {
+        readonly mode: 'light' | 'dark';
+        readonly cssVariables?: Record<string, string>;
+    };
+}): 'light' | 'dark' | undefined;
+/**
+ * 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 declare function resolveMountThemeId(meta: {
+    readonly themeId?: string;
+    readonly theme?: {
+        readonly name?: string;
+        readonly mode?: 'light' | 'dark';
+        readonly cssVariables?: Record<string, string>;
+    };
+}): string | undefined;
+/**
+ * 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 declare function hostAnnouncedPalette(): Readonly<Record<string, string>> | undefined;
 /**
  * @internal — exported for unit tests to reset module state between
  * scenarios.
@@ -733,7 +814,7 @@ export declare 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.
  */

package/dist/runtime.js

@@ -32,6 +32,7 @@ import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolRes
 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';
@@ -87,7 +88,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 +187,80 @@ 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) {
+    return meta.themeMode ?? meta.theme?.mode ?? 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) {
+    return meta.themeId ?? 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 +389,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 +1342,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 +1366,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.
  */
@@ -2813,7 +2898,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 +3039,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 +3068,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 +3112,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;
@@ -3461,13 +3559,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 +3583,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 +3615,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/iframe-runtime",
-  "version": "0.10.0",
+  "version": "0.11.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/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"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0"