@ggui-ai/iframe-runtime 0.15.0 → 0.17.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, AppThemeMemberStrippedEvent, 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,23 @@ 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;
+/**
+ * The read door KEPT the slice's theme but stripped top-level members
+ * this release does not name (ggui#1093 belt, VERSION-POLICY §3.6):
+ * report the member names to the embedding host so a newer writer's
+ * member is visible, not swallowed. Passed as `onStrippedThemeMembers`
+ * on every `parseMcpAppAiGguiRenderMeta` call in this package.
+ */
+export declare function reportStrippedThemeMembers(keys: 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,27 @@ 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] });
+}
+/**
+ * The read door KEPT the slice's theme but stripped top-level members
+ * this release does not name (ggui#1093 belt, VERSION-POLICY §3.6):
+ * report the member names to the embedding host so a newer writer's
+ * member is visible, not swallowed. Passed as `onStrippedThemeMembers`
+ * on every `parseMcpAppAiGguiRenderMeta` call in this package.
+ */
+export function reportStrippedThemeMembers(keys) {
+    postObservabilityToParent({ kind: 'app-theme-member-stripped', keys: [...keys] });
+}
 /**
  * Parse the render slice from `globalThis.__GGUI_META__` — the
  * synchronous self-contained shell delivery channel.
@@ -345,7 +367,10 @@ export function parseMetaFromGlobal() {
     if (!isPlainObject(raw)) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }
-    const parsed = parseMcpAppAiGguiRenderMeta(raw);
+    const parsed = parseMcpAppAiGguiRenderMeta(raw, {
+        onInvalidTheme: reportInvalidAppTheme,
+        onStrippedThemeMembers: reportStrippedThemeMembers,
+    });
     if (!parsed.ok) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }
@@ -396,7 +421,10 @@ 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,
+        onStrippedThemeMembers: reportStrippedThemeMembers,
+    });
     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 | AppThemeMemberStrippedEvent | ThemeReinjectFailedEvent | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | RelayDeadTapEvent | ComponentEmptyEvent | UnknownObservabilityEvent;
 /**
  * Fired when the protocol-version handshake rejects the connection.
  * Parallel to `UpgradeRequiredError` — the host can choose to render
@@ -295,6 +295,25 @@ export interface RelayDeadTapEvent {
     readonly sessionId?: string;
     readonly appId?: string;
 }
+/**
+ * The mount painted NOTHING (ggui#1103): the renderer held no component,
+ * so the scope element carries only its stylesheet — a blank card, with no
+ * error boundary to catch anything (the boundary wraps a null child). The
+ * host is told which mount moment it was and why, because a card that
+ * renders nothing is invisible on every other channel: `reason: 'no-code'`
+ * is a payload that carried no component code, `'eval-failed'` a module
+ * that threw while evaluating. Names the moment only — never the code, the
+ * props or the error text, which stay in the operator-visible console line.
+ *
+ * @public
+ */
+export interface ComponentEmptyEvent {
+    readonly kind: 'component-empty';
+    /** Which lifecycle moment painted nothing. */
+    readonly where: 'mount' | 'update';
+    /** Why the renderer held no component. */
+    readonly reason: 'no-code' | 'eval-failed';
+}
 /**
  * Catch-all branch for event kinds the host's typings don't recognize.
  * Lets the union stay extensible without forcing protocol-version
@@ -303,6 +322,59 @@ 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 render slice's `theme` carried top-level members THIS release does
+ * not name (ggui#1093 belt, VERSION-POLICY §3.6): the read door kept the
+ * theme and stripped them, and the card says which — a newer writer's
+ * member is never silently swallowed. `keys` are the member names only,
+ * never their content.
+ *
+ * @public
+ */
+export interface AppThemeMemberStrippedEvent {
+    readonly kind: 'app-theme-member-stripped';
+    readonly keys: 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
@@ -113,6 +95,8 @@ export interface ReactRootMountOptions {
      */
     readonly hostPalette?: Readonly<Record<string, string>>;
     readonly cssOverrides?: string;
+    /** `fill` — the root is the whole canvas: no silhouette, fills the page (ggui#1041; from the host's `displayMode`). */
+    readonly fit?: 'fill';
     readonly onError?: (error: Error) => void;
     /**
      * Children injected BETWEEN the mount DOM (scope + CSS) and the

package/dist/react-renderer.js

@@ -31,7 +31,8 @@
  */
 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 { postObservabilityToParent } from './observability.js';
+import { stripMarkers, rewriteImports, composeThemeCss, } 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
@@ -66,11 +67,6 @@ function makeScopeClass() {
  * 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).
 // =============================================================================
@@ -109,7 +105,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 +122,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 +147,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,57 +310,29 @@ 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);
-        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 = 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 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';
+        // ONE composition (`@ggui-ai/design/rendering` `composeThemeCss`): the
+        // scoped tree block — compiled ladder < host palette < overlays[m] <
+        // cssVariables < cssOverrides, then the mode's keyframes and the
+        // frameless rule. The `:root` chrome block below and an evaluator's
+        // page are the same function's other layers, so no two paints can
+        // disagree on a token (ggui#1020: a judge that composed its own
+        // scored an ink-on-ink hero readable).
+        const themeCss = composeThemeCss({
+            layer: 'tree',
+            scopeClass,
+            mode: m,
+            ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
+            ...(opts.hostPalette !== undefined ? { hostPalette: opts.hostPalette } : {}),
+            ...(opts.appTheme !== undefined ? { appTheme: opts.appTheme } : {}),
+            ...(opts.cssOverrides !== undefined ? { cssOverrides: opts.cssOverrides } : {}),
+            ...(opts.fit !== undefined ? { fit: opts.fit } : {}),
+        });
         // 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,37 +343,20 @@ 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);
-            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 = 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}}`;
-            }
+            // Same ladder, same mode as the scoped block above — the
+            // standalone viewer's body chrome and its tree content resolve
+            // the same values.
+            // BODY-CHROME ONLY — the same composer's `chrome` layer: the ladder,
+            // the host palette, `color-scheme` + the app theme's variable layers
+            // (no keyframes, no overrides); tree content resolves the scoped block
+            // above, which wins by document order.
+            const rootCss = composeThemeCss({
+                layer: 'chrome',
+                mode: m,
+                ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
+                ...(opts.hostPalette !== undefined ? { hostPalette: opts.hostPalette } : {}),
+                ...(opts.appTheme !== undefined ? { appTheme: opts.appTheme } : {}),
+            });
             const styleId = 'ggui-theme-vars';
             let styleEl = document.getElementById(styleId);
             if (!styleEl) {
@@ -426,17 +377,51 @@ 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), createElement(RcrErrorBoundary, {
             key: currentCode?.length ?? 0,
             ...(opts.onError ? { onError: opts.onError } : {}),
         }, createElement(Fragment, null, wrapped))));
     }
+    /**
+     * The mount painted NOTHING (ggui#1103). `wrapped` is `null` whenever the
+     * renderer holds no component, so the scope element carries only its
+     * `<style>`: height 0, no text, and the error boundary never engages —
+     * it wraps a null child. Every such moment is reported on all three
+     * channels (an operator-visible console line, the caller's `onError`, the
+     * host's observability seam), because until now the two empty-code paths
+     * were silent on ALL of them and an empty card could not be told apart
+     * from a card whose module threw. Never carries the code or the props.
+     */
+    function reportNoComponent(where, reason, error, onError) {
+        if (reason === 'eval-failed') {
+            // eslint-disable-next-line no-console -- operator-visible failure signal
+            console.error(`[ggui] mountReactRoot: the ${where} painted nothing (eval-failed) —`, error);
+        }
+        else {
+            // A payload that carried no code is not an exception — nothing threw,
+            // and `onError` stays the caller's "the component failed" channel, so a
+            // host that paints an error panel does not paint one here. It is still
+            // operator-visible, and the host still hears it on the seam below.
+            // eslint-disable-next-line no-console -- operator-visible failure signal
+            console.warn(`[ggui] mountReactRoot: the ${where} painted nothing (no-code) — ${error.message}`);
+        }
+        try {
+            postObservabilityToParent({ kind: 'component-empty', where, reason });
+        }
+        catch {
+            // The host seam is best-effort: a blocked postMessage must not turn a
+            // blank card into a thrown mount.
+        }
+        if (reason === 'eval-failed')
+            onError?.(error);
+    }
     async function initialEvaluate() {
         const code = currentOpts.render.componentCode ?? '';
         if (code.trim().length === 0) {
             currentComponent = null;
             currentCode = null;
             renderTree(currentOpts);
+            reportNoComponent('mount', 'no-code', new Error('mount carried no component code'), currentOpts.onError);
             return;
         }
         try {
@@ -450,12 +435,10 @@ export async function mountReactRoot(container, opts) {
             // not enough on its own — not every mount path wires one, so
             // without this log a mount with a broken component renders a
             // blank iframe and emits nothing.
-            // eslint-disable-next-line no-console -- operator-visible failure signal
-            console.error('[ggui] mountReactRoot: component evaluation failed —', e);
             currentComponent = null;
             currentCode = null;
             renderTree(currentOpts);
-            currentOpts.onError?.(e);
+            reportNoComponent('mount', 'eval-failed', e, currentOpts.onError);
         }
     }
     await initialEvaluate();
@@ -476,6 +459,7 @@ export async function mountReactRoot(container, opts) {
                 currentComponent = null;
                 currentCode = null;
                 renderTree(currentOpts);
+                reportNoComponent('update', 'no-code', new Error('update carried no component code'), next.onError);
                 return;
             }
             try {
@@ -488,7 +472,7 @@ export async function mountReactRoot(container, opts) {
                 currentComponent = null;
                 currentCode = null;
                 renderTree(currentOpts);
-                next.onError?.(e);
+                reportNoComponent('update', 'eval-failed', e, next.onError);
             }
         },
         unmount() {

package/dist/render-item.d.ts

@@ -47,20 +47,19 @@ 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 mounted root fills its surface without a silhouette of its own (ggui#1041):
+     * set when the host's context says `displayMode: 'fullscreen'` — a canvas panel
+     * is the chrome. Absent for inline mounts.
      */
-    readonly appTheme?: {
-        readonly mode: 'light' | 'dark';
-        readonly cssVariables: Record<string, string>;
-        readonly base?: NonNullable<AppTheme['base']>;
-    };
+    readonly fit?: 'fill';
+    /**
+     * 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?: AppTheme;
     /**
      * Host-announced palette, pre-mapped onto `--ggui-*` tokens by the
      * host-palette bridge. Forwarded to

package/dist/render-item.js

@@ -183,6 +183,10 @@ export async function mountRender(container, opts) {
             ...(currentOpts.cssOverrides !== undefined
                 ? { cssOverrides: currentOpts.cssOverrides }
                 : {}),
+            // The host's canvas is the chrome (ggui#1041): `fit` MUST cross this
+            // boundary like every other compose option — ggui#1073 shipped
+            // without it, and every served hello composed as an inline card.
+            ...(currentOpts.fit !== undefined ? { fit: currentOpts.fit } : {}),
             ...(currentOpts.onError !== undefined ? { onError: currentOpts.onError } : {}),
             renderWrapper: wrapInScopedProvider,
         });
@@ -249,6 +253,7 @@ export async function mountRender(container, opts) {
                     ...(next.appTheme !== undefined ? { appTheme: next.appTheme } : {}),
                     ...(next.hostPalette !== undefined ? { hostPalette: next.hostPalette } : {}),
                     ...(next.cssOverrides !== undefined ? { cssOverrides: next.cssOverrides } : {}),
+                    ...(next.fit !== undefined ? { fit: next.fit } : {}),
                     ...(next.onError !== undefined ? { onError: next.onError } : {}),
                     renderWrapper: wrapInScopedProvider,
                 });