@ggui-ai/iframe-runtime 0.14.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

@@ -50,8 +50,9 @@
  * At least one mode MUST be present. Half-live (wsUrl without wsToken)
  * is structurally rejected by the combiner.
  */
-import { PUBLIC_ENV_APP_KEY_RE } from '@ggui-ai/protocol';
+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
@@ -179,15 +179,29 @@ export interface UiFeedbackEvent {
     readonly toolName?: string;
 }
 /**
- * The evidence that latched a relay dead zone (ggui#599 cycle-2):
- * `'confirmed-refusal'` — the relay answered a declared refusal code
- * (helper-minted; outranks any positive advertisement), vs
- * `'advert-silent'` — the host never advertised `serverTools` and the
- * attempt failed relay-shaped.
+ * The evidence that latched a relay dead zone:
+ *   - `'confirmed-refusal'` — the relay answered a declared refusal code
+ *     (helper-minted; outranks any positive advertisement) (ggui#599
+ *     cycle-2);
+ *   - `'advert-silent'` — the host never advertised `serverTools` and
+ *     the attempt failed relay-shaped;
+ *   - `'boot-failed'` — the mandatory `ui/initialize` handshake did not
+ *     complete (refused, timed out, or the transport failed), so
+ *     nothing can ever be delivered in this document (ggui#830). Not a
+ *     probe the runtime minted: the outcome of the one request every
+ *     session begins with — the strongest confirmed outcome there is.
+ *     It clears the only way a handshake failure can: the next boot's
+ *     close edge.
+ *
+ * The union is closed per renderer version; nothing in a host branches
+ * on the trigger (the first-party host passes it through untouched) —
+ * the edge is the fact, the trigger is why. A host that does branch on
+ * it should treat a value it does not know as "latched, reason
+ * unknown", never as "not latched".
  *
  * @public
  */
-export type RelayLatchTrigger = 'confirmed-refusal' | 'advert-silent';
+export type RelayLatchTrigger = 'confirmed-refusal' | 'advert-silent' | 'boot-failed';
 /**
  * Fired at the two transition edges of the renderer's
  * relay-incapability latch — the runtime's confirmed determination
@@ -195,7 +209,9 @@ export type RelayLatchTrigger = 'confirmed-refusal' | 'advert-silent';
  *
  *   - `'latched'` — a real user gesture just failed relay-shaped on a
  *     host whose captured capability handshake never advertised
- *     `serverTools`, or the relay answered a declared refusal code.
+ *     `serverTools`, or the relay answered a declared refusal code, or
+ *     the host refused `ui/initialize` itself (`'boot-failed'`,
+ *     ggui#830 — no gesture is needed to know nothing can be delivered).
  *     The runtime now treats relay as confirmed-unavailable: it shows
  *     one persistent explanation, arms the dead-zone cue for every
  *     later gesture, and channel polls fail fast without a transport
@@ -214,9 +230,11 @@ export type RelayLatchTrigger = 'confirmed-refusal' | 'advert-silent';
  * a latch standing from a prior mount closes it with a `'cleared'`
  * edge before the new session starts.
  *
- * Always emitted via the postMessage-to-parent default — the emission
- * sites live in module-level gesture-dispatch code outside the boot
- * graph, so they never flow through an injected `onObserve` sink.
+ * Always emitted via the postMessage-to-parent default, by rule — the
+ * gesture-dispatch emission sites run outside any given boot call, and
+ * the boot-graph site (the `boot-failed` edge, ggui#830) follows the
+ * same rule — so these edges never flow through an injected
+ * `onObserve` sink and a host reads every edge the same way.
  *
  * @public
  */
@@ -249,9 +267,10 @@ export type RelayIncapabilityEvent = {
  * document (pulse, spoken cue, fallback toast); this event makes the
  * attempt COUNTABLE by the host.
  *
- * Contract: exactly one per gesture attempted while latched whose
- * attempt comes back undelivered (relay-shaped failure or a declared
- * refusal); never emitted off-latch, and never from the channel
+ * Contract: exactly one per gesture whose UNDELIVERED outcome
+ * (relay-shaped failure or a declared refusal) lands while the latch
+ * stands — an in-flight gesture that raced the latching one counts;
+ * never emitted off-latch, and never from the channel
  * router's fail-fast ticks. Counted at the outcome, not the tap: the
  * gesture that latched the zone is the `'latched'` edge and the gesture
  * that heals it is the `'cleared'` edge — neither is a dead tap.
@@ -284,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/provisional-renderer.d.ts

@@ -31,7 +31,7 @@
  *     while suspended, matching host-SDK behavior.
  */
 import React, { type ReactNode } from 'react';
-import type { StreamEnvelope } from '@ggui-ai/protocol';
+import type { StreamEnvelope } from '@ggui-ai/protocol/wire';
 export interface ProvisionalMount {
     /**
      * Feed a stream envelope. Ignores non-PREVIEW_CHANNEL envelopes

package/dist/react-renderer.d.ts

@@ -30,7 +30,7 @@
  * TypeScript config doesn't need a JSX runtime plumbing.
  */
 import React, { type ReactNode } from 'react';
-import type { AppTheme } from '@ggui-ai/protocol';
+import type { AppTheme } from '@ggui-ai/protocol/wire';
 export interface ReactRootMountOptions {
     /**
      * GguiSession whose componentCode + props drive the mount. Only
@@ -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/registry-subscribe.d.ts

@@ -1,4 +1,4 @@
-import type { AckPayload } from '@ggui-ai/protocol';
+import type { AckPayload } from '@ggui-ai/protocol/wire';
 import type { ConnectionStatus } from '@ggui-ai/protocol/transport/websocket';
 import type { McpAppAiGguiRenderMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
 import type { AnyTransportHandle, ChannelLogger, ChannelRegistry, RegistryPollingOptions, RegistrySseOptions, WsTransportHandle } from '@ggui-ai/live-channel';

package/dist/render-item.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { AppTheme, GguiSession } from '@ggui-ai/protocol';
+import type { AppTheme, GguiSession } from '@ggui-ai/protocol/wire';
 import type { GguiSessionSeedInput } from './types.js';
 import { type WireConfig } from '@ggui-ai/wire';
 import type { StreamBus } from './wire-config.js';
@@ -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-telemetry.js

@@ -1,4 +1,4 @@
-import { RUNTIME_TELEMETRY_MAX_EVENTS } from '@ggui-ai/protocol';
+import { RUNTIME_TELEMETRY_MAX_EVENTS } from '@ggui-ai/protocol/wire';
 const FIRST_FLUSH_DELAY_MS = 4_000;
 const FLUSH_THROTTLE_MS = 8_000;
 const MAX_FLUSHES_PER_SESSION = 12;