@ggui-ai/iframe-runtime 0.15.0 → 0.16.0

package/dist/index.d.ts

@@ -37,7 +37,7 @@ export { parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './m
 export type { RendererBootFailureReason, RendererBootFailedMessage, } from './runtime.js';
 export type { ProtocolError, ProtocolErrorEmitter, BootstrapFailureReason, } from './protocol-error.js';
 export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
-export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayDeadTapEvent, RelayIncapabilityEvent, RelayLatchTrigger, UnknownObservabilityEvent, } from './observability.js';
+export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, FontFaceBlockedEvent, AppThemeInvalidEvent, ThemeReinjectFailedEvent, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayDeadTapEvent, RelayIncapabilityEvent, RelayLatchTrigger, UnknownObservabilityEvent, } from './observability.js';
 export { isObservabilityMessage, isRelayDeadTapEvent, isRelayIncapabilityEvent, postObservabilityToParent, } from './observability.js';
 export type { LifecycleEmitter } from './lifecycle.js';
 export { postLifecycleToParent, makeLifecycleEvent } from './lifecycle.js';

package/dist/mcp-app-iframe-host.d.ts

@@ -50,6 +50,21 @@ export interface McpAppIframeMountOptions {
     /** Optional locale; defaults to `navigator.language` when
      *  available. */
     readonly locale?: string;
+    /**
+     * The color mode this host paints around the card (ggui#987 §4: the
+     * embedding host owns runtime mode). Announced as
+     * `hostContext.theme`; the card's ladder, overlay and `color-scheme`
+     * follow it. Omit to announce nothing — the card falls back to the
+     * slice's stamped mode.
+     */
+    readonly theme?: 'light' | 'dark';
+    /**
+     * `@font-face` rules the card may install (ggui#987 §5), announced
+     * as `hostContext.styles.css.fonts`. The card's CSP decides whether
+     * each `src` loads; a refused face is reported back as
+     * `font-face-blocked`.
+     */
+    readonly fonts?: string;
 }
 export interface McpAppIframeMount {
     /** Tear down — posts `ui/resource-teardown` then removes the iframe. */

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

@@ -113,7 +113,9 @@ export function mountMcpAppIframe(container, opts) {
                 // `hostCapabilities` + `hostContext`; the pre-App draft shape
                 // fails that gate and kills the embedded mount. Adapter
                 // boundary — `hostContext` carries `{locale,
-                // containerDimensions}` ONLY (no outer ggui render state).
+                // containerDimensions}` plus the host's OWN `theme` / fonts
+                // when the embedder passed them (ggui#987 §4/§5); never any
+                // outer ggui render state.
                 const requestedRaw = req.params?.['protocolVersion'];
                 const requested = typeof requestedRaw === 'string' && requestedRaw.length > 0
                     ? requestedRaw
@@ -133,6 +135,8 @@ export function mountMcpAppIframe(container, opts) {
                         locale: opts.locale ??
                             (typeof navigator !== 'undefined' ? navigator.language : 'en-US'),
                         containerDimensions: dims,
+                        ...(opts.theme !== undefined ? { theme: opts.theme } : {}),
+                        ...(opts.fonts !== undefined ? { styles: { css: { fonts: opts.fonts } } } : {}),
                     },
                 };
                 response = { jsonrpc: '2.0', id, result };

package/dist/meta-parse.d.ts

@@ -16,6 +16,15 @@ import type { McpAppAiGguiMetaParseResult } from './types.js';
  *     has nothing to mount.
  */
 export declare function validateMeta(meta: McpAppAiGguiRenderMeta): McpAppAiGguiMetaParseResult;
+/**
+ * The wire parser refused the slice's `theme` (ggui#987 §3.4): report it
+ * to the embedding host as `app-theme-invalid` and mount without it. A
+ * write door should have refused this upstream — the event is the
+ * operator's pointer to the door that did not. Passed as
+ * `onInvalidTheme` on every `parseMcpAppAiGguiRenderMeta` call in this
+ * package.
+ */
+export declare function reportInvalidAppTheme(issues: readonly string[]): void;
 /**
  * Parse the render slice from `globalThis.__GGUI_META__` — the
  * synchronous self-contained shell delivery channel.

package/dist/meta-parse.js

@@ -52,6 +52,7 @@
  */
 import { PUBLIC_ENV_APP_KEY_RE } from '@ggui-ai/protocol/wire';
 import { parseMcpAppAiGguiRenderMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
+import { postObservabilityToParent } from './observability.js';
 /**
  * Type guard — true iff `value` is a non-null, non-array plain object.
  */
@@ -323,6 +324,17 @@ export function validateMeta(meta) {
         return result;
     return { ok: true, meta: result.meta };
 }
+/**
+ * The wire parser refused the slice's `theme` (ggui#987 §3.4): report it
+ * to the embedding host as `app-theme-invalid` and mount without it. A
+ * write door should have refused this upstream — the event is the
+ * operator's pointer to the door that did not. Passed as
+ * `onInvalidTheme` on every `parseMcpAppAiGguiRenderMeta` call in this
+ * package.
+ */
+export function reportInvalidAppTheme(issues) {
+    postObservabilityToParent({ kind: 'app-theme-invalid', issues: [...issues] });
+}
 /**
  * Parse the render slice from `globalThis.__GGUI_META__` — the
  * synchronous self-contained shell delivery channel.
@@ -345,7 +357,7 @@ export function parseMetaFromGlobal() {
     if (!isPlainObject(raw)) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }
-    const parsed = parseMcpAppAiGguiRenderMeta(raw);
+    const parsed = parseMcpAppAiGguiRenderMeta(raw, { onInvalidTheme: reportInvalidAppTheme });
     if (!parsed.ok) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }
@@ -396,7 +408,7 @@ export function parseMetaFromToolResult(params) {
         return { ok: false, reason: 'MISSING_META_GGUI_BOOTSTRAP' };
     }
     const meta = topMeta;
-    const parsed = parseMcpAppAiGguiRenderMeta(meta);
+    const parsed = parseMcpAppAiGguiRenderMeta(meta, { onInvalidTheme: reportInvalidAppTheme });
     if (!parsed.ok) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }

package/dist/observability.d.ts

@@ -33,7 +33,7 @@ import { MCP_APP_OBSERVE_TYPE } from '@ggui-ai/protocol/integrations/mcp-apps';
  *
  * @public
  */
-export type ObservabilityEvent = SchemaVersionMismatchEvent | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | RelayDeadTapEvent | UnknownObservabilityEvent;
+export type ObservabilityEvent = SchemaVersionMismatchEvent | FontFaceBlockedEvent | AppThemeInvalidEvent | ThemeReinjectFailedEvent | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | RelayDeadTapEvent | UnknownObservabilityEvent;
 /**
  * Fired when the protocol-version handshake rejects the connection.
  * Parallel to `UpgradeRequiredError` — the host can choose to render
@@ -303,6 +303,46 @@ export interface RelayDeadTapEvent {
  *
  * @public
  */
+/**
+ * A host-delivered `@font-face` src the document's CSP refused
+ * (ggui#987 §5): the card installed the host's `styles.css.fonts`, the
+ * browser blocked the fetch under `font-src`, and the family will fall
+ * back to its stack. Reported ONCE per (family, host) per document —
+ * the operator's signal that the shell's `font-src` allowlist and the
+ * host's font origin disagree.
+ *
+ * @public
+ */
+export interface FontFaceBlockedEvent {
+    readonly kind: 'font-face-blocked';
+    /** The `font-family` the refused `@font-face` block declared. */
+    readonly family: string;
+    /** Host of the blocked `src` URL (`blockedURI`, origin-stripped by CSP). */
+    readonly host: string;
+}
+/**
+ * The render slice carried a `theme` the wire schema refused (ggui#987
+ * §3.4): the parser dropped it and the card painted the compiled ladder
+ * alone. `issues` are the schema's own messages — the operator's
+ * pointer to what the write door should have refused.
+ *
+ * @public
+ */
+export interface AppThemeInvalidEvent {
+    readonly kind: 'app-theme-invalid';
+    readonly issues: readonly string[];
+}
+/**
+ * The live re-injection on a host theme flip (ggui#987 §4) failed: the
+ * renderer's update rejected, so the card kept its previous overlay /
+ * ladder / `color-scheme`. `message` is the rejection's.
+ *
+ * @public
+ */
+export interface ThemeReinjectFailedEvent {
+    readonly kind: 'theme-reinject-failed';
+    readonly message: string;
+}
 export interface UnknownObservabilityEvent {
     readonly kind: string & {};
     readonly [field: string]: unknown;

package/dist/react-renderer.d.ts

@@ -63,44 +63,26 @@ export interface ReactRootMountOptions {
      */
     readonly themeMode?: 'light' | 'dark';
     /**
-     * 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.
+     * The per-app theme (protocol's `AppTheme`, ggui#987 v2): BOTH modes'
+     * derived `--ggui-*` projections (`overlays.light` / `overlays.dark`),
+     * optional mode-agnostic `cssVariables`, per-mode `keyframes`, and
+     * the `frameless` flag. The renderer injects the overlay for the
+     * EFFECTIVE mode (`themeMode`, host-owned per §4; absent ⇒ light) —
+     * a mode switch re-paints from the retained other set with no
+     * network activity. Merged INTO the scoped in-body token block, 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, for body chrome only.
      *
-     * 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.
+     * Injection order (§3.3), one document-order cascade:
+     * compiled ladder (`themeId` ?? default) < `hostPalette` <
+     * `overlays[mode]` < `cssVariables` < `cssOverrides`, then
+     * `keyframes[mode]` and the frameless rule. Values are injection-
+     * safe by the wire schema — never re-validated here.
      */
-    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?: NonNullable<AppTheme['base']>;
-    };
+    readonly appTheme?: AppTheme;
     /**
      * Host-announced palette, already translated onto `--ggui-*` tokens
      * (see `host-palette-bridge.ts` — the spec `--color-*` vocabulary

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, assembleDeliveredThemeCss, getThemeCss, getCssTokens, } from '@ggui-ai/design/rendering';
+import { stripMarkers, rewriteImports, getScopedThemeCss, getScopedCssTokens, framelessSuppressionRule, 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
@@ -109,7 +109,7 @@ class RcrErrorBoundary extends Component {
         // The two fallback UIs match the host-SDK error boundary
         // verbatim (same inline styles so operator-visible DOM is
         // identical between the host-SDK and iframe-renderer paths).
-        // Colors inherit the themed body (`--ggui-color-onSurface`) with
+        // Colors inherit the themed body (`--ggui-color-onContainer`) with
         // opacity for hierarchy — hardcoded white-alpha text was
         // illegible on light shells (#481); the boundary must stay
         // readable on WHATEVER background the theme painted, including
@@ -126,7 +126,7 @@ class RcrErrorBoundary extends Component {
                     gap: 8,
                     fontFamily: FONT,
                     fontSize: 13,
-                    color: 'var(--ggui-color-onSurface, inherit)',
+                    color: 'var(--ggui-color-onContainer, inherit)',
                     opacity: 0.6,
                 },
             }, createElement('div', {
@@ -151,7 +151,7 @@ class RcrErrorBoundary extends Component {
                 gap: 12,
                 textAlign: 'center',
                 fontFamily: FONT,
-                color: 'var(--ggui-color-onSurface, inherit)',
+                color: 'var(--ggui-color-onContainer, inherit)',
             },
         }, createElement('div', {
             style: {
@@ -314,33 +314,15 @@ export async function mountReactRoot(container, opts) {
         }
     }
     function renderTree(opts) {
-        // 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, {
-                    // ggui#613 residual 2 — the two former v1 deltas ride:
-                    // the active mode's keyframes block + the frameless
-                    // silhouette suppression, both same-rule as compiled.
-                    keyframes: opts.themeMode === 'dark'
-                        ? deliveredBase.keyframes?.dark
-                        : deliveredBase.keyframes?.light,
-                    frameless: deliveredBase.frameless,
-                })
-            : opts.themeId
-                ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
-                : getScopedCssTokens(scopeClass, opts.themeMode);
+        // The effective mode (ggui#987 §4: the host owns it; the runtime
+        // resolves it ONCE into `themeMode`). Absent means no opinion
+        // anywhere — the light ladder paints, and every mode-keyed layer
+        // below selects with the same `m`, so the ladder, the overlay, the
+        // keyframes and `color-scheme` can never disagree.
+        const m = opts.themeMode ?? 'light';
+        let themeCss = opts.themeId
+            ? getScopedThemeCss(opts.themeId, scopeClass, m)
+            : getScopedCssTokens(scopeClass, m);
         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
@@ -349,22 +331,35 @@ export async function mountReactRoot(container, opts) {
             // arrive pre-sanitized from the host-palette bridge.
             themeCss += `.${scopeClass}{${toCssDecls(opts.hostPalette)}}`;
         }
-        if (opts.appTheme) {
-            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
-            // in document order than anything in `<head>`, so at equal
-            // 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 + 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}}`;
-        }
+        // The per-app theme's two variable layers, in this order: the
+        // derived projection for the effective mode, then the mode-agnostic
+        // `cssVariables` above it. Both 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 in document order than anything in `<head>`, so at
+        // equal 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 + host palette and BEFORE `cssOverrides`:
+        // compiled < host palette < overlays[m] < cssVariables < overrides
+        // (ggui#573: slice wins, host fallback). Values validated
+        // injection-safe upstream (same guarantee the `:root` append cites).
+        const appVarBlocks = opts.appTheme
+            ? [opts.appTheme.overlays[m], opts.appTheme.cssVariables]
+                .filter((vars) => vars !== undefined)
+                .map((vars) => `.${scopeClass}{${toCssDecls(vars)}}`)
+                .join('')
+            : '';
+        themeCss += appVarBlocks;
+        // Trailing rules (§3.3): the effective mode's `@keyframes` block and
+        // the frameless silhouette suppression — the SAME rule text the
+        // compiled path emits for `$metadata.frameless` — after
+        // `cssOverrides`, so an override can never be shadowed by them.
+        // Keyframes ride VERBATIM: their admission is the write door's
+        // (`appThemeSchema.keyframes`), not re-checked here.
+        const appTrailingCss = opts.appTheme
+            ? `${opts.appTheme.keyframes?.[m] ?? ''}${opts.appTheme.frameless === true ? framelessSuppressionRule(scopeClass) : ''}`
+            : '';
         // Also inject theme CSS at `:root` on `document.head`. The scoped
         // injection above isolates token resolution to the React tree, but
         // the embedding shell's body styles (font-family, color, background)
@@ -375,17 +370,10 @@ export async function mountReactRoot(container, opts) {
         // `ThemeProvider` so a Studio/Portal context with both runtime + RP
         // active doesn't double-stack.
         if (typeof document !== 'undefined') {
-            // ggui#613 residual 5: under a DELIVERED base the body-chrome
-            // ladder is the delivered set too — mirroring the scoped ternary
-            // above — so the standalone viewer's body chrome and its tree
-            // content resolve the same values. Pre-fix this started from the
-            // compiled/default ladder regardless, and body chrome painted the
-            // default brand under a registered theme.
-            let rootCss = deliveredBase !== undefined
-                ? `:root{${toCssDecls(opts.themeMode === 'dark' ? deliveredBase.dark : deliveredBase.light)}}`
-                : opts.themeId
-                    ? getThemeCss(opts.themeId, opts.themeMode)
-                    : getCssTokens(opts.themeMode);
+            // Same ladder, same mode as the scoped block above — the
+            // standalone viewer's body chrome and its tree content resolve
+            // the same values.
+            let rootCss = opts.themeId ? getThemeCss(opts.themeId, m) : getCssTokens(m);
             if (opts.hostPalette) {
                 // BODY-CHROME ONLY, same as the appTheme `:root` append below —
                 // and beneath it, mirroring the scoped-block order (#573:
@@ -393,19 +381,23 @@ export async function mountReactRoot(container, opts) {
                 // body font/color/background coherent with the tree.
                 rootCss += `:root{${toCssDecls(opts.hostPalette)}}`;
             }
-            if (opts.appTheme) {
-                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
-                // token block wins by document order (see the scoped merge in
-                // `renderTree`, and rnd/gen-ui/beauty/experiments/001 for the
-                // probe that falsified the old "inherits into the tree" claim).
-                // Values were validated injection-safe upstream (write-side
-                // `appThemeSchema` + the wire parser re-validates), so the
-                // string-join here is safe — do NOT re-sanitize.
-                rootCss += `:root{color-scheme:${opts.appTheme.mode};${decls}}`;
-            }
+            // BODY-CHROME ONLY. `color-scheme` follows the effective mode so
+            // native controls / scrollbars / canvas agree with the ladder
+            // painted; the app theme's two variable layers ride the same
+            // block, in the scoped order. None of this reaches tree content —
+            // the scoped in-body token block wins by document order (see the
+            // scoped merge above, and rnd/gen-ui/beauty/experiments/001 for
+            // the probe that falsified the old "inherits into the tree"
+            // claim). Values were validated injection-safe upstream (write-
+            // side `appThemeSchema` + the wire parser re-validates), so the
+            // string-join here is safe — do NOT re-sanitize.
+            const rootAppDecls = opts.appTheme
+                ? [opts.appTheme.overlays[m], opts.appTheme.cssVariables]
+                    .filter((vars) => vars !== undefined)
+                    .map(toCssDecls)
+                    .join('')
+                : '';
+            rootCss += `:root{color-scheme:${m};${rootAppDecls}}`;
             const styleId = 'ggui-theme-vars';
             let styleEl = document.getElementById(styleId);
             if (!styleEl) {
@@ -426,7 +418,7 @@ export async function mountReactRoot(container, opts) {
         // The scope `<div>` + inline `<style>` + error-boundary-wrapped
         // children match RCR L376–383. `key={currentCode?.length}` mirrors
         // RCR's "reset boundary when code changes" heuristic.
-        root.render(createElement('div', { className: scopeClass }, createElement('style', null, `${themeCss}${opts.cssOverrides ?? ''}`), createElement(RcrErrorBoundary, {
+        root.render(createElement('div', { className: scopeClass }, createElement('style', null, `${themeCss}${opts.cssOverrides ?? ''}${appTrailingCss}`), createElement(RcrErrorBoundary, {
             key: currentCode?.length ?? 0,
             ...(opts.onError ? { onError: opts.onError } : {}),
         }, createElement(Fragment, null, wrapped))));

package/dist/render-item.d.ts

@@ -47,20 +47,13 @@ export interface RenderItemOptions {
      */
     readonly themeMode?: 'light' | 'dark';
     /**
-     * Per-app theme overlay forwarded to {@link ReactRootMountOptions.appTheme}
-     * 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}).
+     * The per-app theme (protocol's `AppTheme`, ggui#987 v2) forwarded
+     * verbatim to {@link ReactRootMountOptions.appTheme}: the renderer
+     * injects the overlay for the effective `themeMode` into the scoped
+     * block and at `:root`. Sourced from the bootstrap's
+     * `_meta["ai.ggui/render"].theme`.
      */
-    readonly appTheme?: {
-        readonly mode: 'light' | 'dark';
-        readonly cssVariables: Record<string, string>;
-        readonly base?: NonNullable<AppTheme['base']>;
-    };
+    readonly appTheme?: AppTheme;
     /**
      * Host-announced palette, pre-mapped onto `--ggui-*` tokens by the
      * host-palette bridge. Forwarded to

package/dist/runtime.d.ts

@@ -97,36 +97,32 @@ export declare function setCurrentApp(app: App): void;
  * `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`.
  */
 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"):
+ * 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`.
@@ -134,36 +130,24 @@ export declare function hostAnnouncedThemeMode(): 'light' | 'dark' | undefined;
 export declare function resolveMountThemeMode(meta: {
     readonly themeMode?: 'light' | 'dark';
     readonly theme?: {
-        readonly mode: 'light' | 'dark';
-        readonly cssVariables?: Record<string, string>;
+        readonly mode?: 'light' | 'dark';
     };
 }): 'light' | 'dark' | undefined;
 /**
- * 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`.
  */
 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