@ggui-ai/iframe-runtime 0.16.0 → 0.18.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, FontFaceBlockedEvent, AppThemeInvalidEvent, ThemeReinjectFailedEvent, 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/meta-parse.d.ts

@@ -25,6 +25,14 @@ export declare function validateMeta(meta: McpAppAiGguiRenderMeta): McpAppAiGgui
  * 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

@@ -335,6 +335,16 @@ export function validateMeta(meta) {
 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.
@@ -357,7 +367,10 @@ export function parseMetaFromGlobal() {
     if (!isPlainObject(raw)) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }
-    const parsed = parseMcpAppAiGguiRenderMeta(raw, { onInvalidTheme: reportInvalidAppTheme });
+    const parsed = parseMcpAppAiGguiRenderMeta(raw, {
+        onInvalidTheme: reportInvalidAppTheme,
+        onStrippedThemeMembers: reportStrippedThemeMembers,
+    });
     if (!parsed.ok) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }
@@ -408,7 +421,10 @@ export function parseMetaFromToolResult(params) {
         return { ok: false, reason: 'MISSING_META_GGUI_BOOTSTRAP' };
     }
     const meta = topMeta;
-    const parsed = parseMcpAppAiGguiRenderMeta(meta, { onInvalidTheme: reportInvalidAppTheme });
+    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 | FontFaceBlockedEvent | AppThemeInvalidEvent | ThemeReinjectFailedEvent | 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
@@ -332,6 +351,19 @@ 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 /

package/dist/react-renderer.d.ts

@@ -95,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
@@ -127,6 +129,15 @@ export interface ReactRootMount {
     unmount(): void;
     /** Current component code (useful for tests + audit). */
     readonly currentCode: string | null;
+    /**
+     * Whether this mount HOLDS a component — i.e. whether the tree it renders
+     * is anything but its own stylesheet (ggui#1103). `applyRender` succeeding
+     * is not the same fact: a payload with no code, or a module that threw,
+     * leaves the scope element carrying only its `<style>`, and a caller that
+     * treats "a render was applied" as "something painted" retires the host's
+     * waiting indicator over a blank card.
+     */
+    readonly painted: boolean;
 }
 /**
  * Mount a React root inside `container` and render `render`'s

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, framelessSuppressionRule, 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).
 // =============================================================================
@@ -320,46 +316,23 @@ export async function mountReactRoot(container, opts) {
         // 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
-            // 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)}}`;
-        }
-        // 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) : ''}`
-            : '';
+        // 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)
@@ -373,31 +346,17 @@ export async function mountReactRoot(container, opts) {
             // 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:
-                // slice wins, host fallback). Keeps the embedding shell's
-                // body font/color/background coherent with the tree.
-                rootCss += `:root{${toCssDecls(opts.hostPalette)}}`;
-            }
-            // 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}}`;
+            // 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) {
@@ -418,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 ?? ''}${appTrailingCss}`), 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 {
@@ -442,16 +435,17 @@ 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();
     return {
+        get painted() {
+            return currentComponent !== null;
+        },
         get currentCode() {
             return currentCode;
         },
@@ -468,6 +462,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 {
@@ -480,7 +475,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

@@ -46,6 +46,12 @@ export interface RenderItemOptions {
      * design registry's `getTheme(id, mode?)` default.
      */
     readonly themeMode?: 'light' | 'dark';
+    /**
+     * 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 fit?: 'fill';
     /**
      * The per-app theme (protocol's `AppTheme`, ggui#987 v2) forwarded
      * verbatim to {@link ReactRootMountOptions.appTheme}: the renderer
@@ -100,6 +106,14 @@ export interface RenderItemHandle {
     unmount(): void;
     /** Current render kind. Test-only — not load-bearing. */
     readonly kind: MountedKind;
+    /**
+     * Whether the active mount PAINTS something (ggui#1103). A provisional,
+     * system or MCP-app mount always does; a React mount does only while it
+     * holds a component. The runtime reads this to decide whether the served
+     * shell's waiting indicator has become a lie — "a render was applied" is
+     * not that fact.
+     */
+    readonly painted: boolean;
 }
 export declare function mountRender(container: HTMLElement, opts: RenderItemOptions): Promise<RenderItemHandle>;
 export {};

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,
         });
@@ -218,6 +222,11 @@ export async function mountRender(container, opts) {
         get kind() {
             return currentKind;
         },
+        get painted() {
+            if (currentKind === 'react')
+                return reactMount?.painted === true;
+            return currentKind !== 'none';
+        },
         async update(next) {
             const prevKind = currentKind;
             currentOpts = next;
@@ -249,6 +258,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,
                 });

package/dist/runtime.d.ts

@@ -31,6 +31,7 @@ import { type McpAppAiGguiRenderMeta, type McpAppBootstrapFailedMessage, type Mc
 import type { GguiSessionSeedInput } from './types.js';
 import type { McpAppAiGguiMetaParseFailureReason } from './types.js';
 import { App } from '@modelcontextprotocol/ext-apps';
+import type { McpUiDisplayMode } from '@modelcontextprotocol/ext-apps';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { GadgetPackageRegistry } from './globals.js';
 import { StreamBus } from './wire-config.js';
@@ -107,6 +108,14 @@ export declare function setCurrentApp(app: App): void;
  *   App); production caller is `buildOpts` inside `bootSequence`.
  */
 export declare function hostAnnouncedThemeMode(): 'light' | 'dark' | undefined;
+/**
+ * The host's announced display mode, from the same pre-merged host context the
+ * theme mode reads (ggui#1041). `fullscreen` means the host shows this page as
+ * the whole of a canvas — the runtime then composes the tree with `fit: 'fill'`
+ * so the mounted root drops its own silhouette and fills the page; anything
+ * else (or an absent context) keeps the inline card.
+ */
+export declare function hostAnnouncedDisplayMode(): McpUiDisplayMode | undefined;
 /**
  * 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):
@@ -412,6 +421,14 @@ export interface RendererHandle {
      * `propsSpec` / `streamSpec`.
      */
     getCurrentGguiSession(): GguiSession | GguiSessionSeedInput | null;
+    /**
+     * Whether the mounted render PAINTS something (ggui#1103) — false while no
+     * render has mounted, and false for a mount holding no component (a payload
+     * with no code, or a module that threw). Read by the boot to decide whether
+     * the served shell's waiting indicator has become a lie; "a render was
+     * applied" is a different fact and was the one being used.
+     */
+    painted(): boolean;
     readonly validatorCtx: RendererValidatorContext;
     /**
      * Send surface for outbound frames. Wired by `setup()` to the WS

package/dist/runtime.js

@@ -30,8 +30,9 @@ import './zod-jitless.js';
 import { runtimeConnectionWriter } from './connection.js';
 import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, parseMcpAppAiGguiRenderMeta, readGguiShellEnvelope, } from '@ggui-ai/protocol/integrations/mcp-apps';
 import { effectiveThemeId, effectiveThemeMode, } from '@ggui-ai/protocol/integrations/theme-binding';
-import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, reportInvalidAppTheme, } from './meta-parse.js';
+import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, reportInvalidAppTheme, reportStrippedThemeMembers, } from './meta-parse.js';
 import { projectHostContext } from '@ggui-ai/protocol/wire';
+import { installDismissIntentListener } from './dismiss-intent.js';
 import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
 import { applyHostContextStyling, attachListener as attachHostContextListener, seed as seedHostContext, subscribeThemeChange as subscribeHostThemeChange, } from './host-context-emitter.js';
 import { mapHostPaletteToGguiVars } from './host-palette-bridge.js';
@@ -203,6 +204,16 @@ export function hostAnnouncedThemeMode() {
     const theme = currentApp?.getHostContext()?.theme;
     return theme === 'light' || theme === 'dark' ? theme : undefined;
 }
+/**
+ * The host's announced display mode, from the same pre-merged host context the
+ * theme mode reads (ggui#1041). `fullscreen` means the host shows this page as
+ * the whole of a canvas — the runtime then composes the tree with `fit: 'fill'`
+ * so the mounted root drops its own silhouette and fills the page; anything
+ * else (or an absent context) keeps the inline card.
+ */
+export function hostAnnouncedDisplayMode() {
+    return currentApp?.getHostContext()?.displayMode;
+}
 /**
  * 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):
@@ -363,6 +374,13 @@ export async function bootSequence(opts) {
         onLifecycle?.(makeLifecycleEvent('error', { error: { code: reason, message } }));
     };
     const refs = ensureStatusDom(doc);
+    // ggui#1109: a key pressed inside the card's document never reaches the page
+    // around it, so a dismiss gesture died here — which is the moment a user who
+    // just clicked the card presses Escape. The card forwards the INTENT and
+    // never acts on it; the host owns what dismissal means, and ignoring is
+    // conformant. Installed before any mount, because the gesture can precede
+    // the first frame.
+    installDismissIntentListener(doc);
     // Live regions up BEFORE anything can announce through them
     // (ggui#447). A region created in the same tick as its first message
     // is a region no screen reader was watching yet, and that first
@@ -642,6 +660,7 @@ export async function bootSequence(opts) {
         mountedRender = target;
         if (renderer !== null) {
             await renderer.applyRender(target);
+            retireStandbyIfPainted();
             if (target.type !== 'mcpApps' && target.type !== 'system') {
                 renderer.channelTransport.applyRender({
                     sessionId: target.id,
@@ -661,11 +680,42 @@ export async function bootSequence(opts) {
         if (codeReadyEmitted)
             return;
         codeReadyEmitted = true;
-        // First real paint — the served shell's working-state mark (#667)
-        // becomes a lie the moment content lands.
-        retireShellLoadingIndicator(doc);
+        // The served shell's working-state mark (#667) is retired by PAINT, not by
+        // this event (ggui#1103): `code-ready` fires after a render was APPLIED,
+        // and applying succeeds when the mount holds no component — so retiring
+        // here left a blank box with no indicator, indistinguishable from a card
+        // still negotiating. `code-ready` itself keeps firing exactly where it did:
+        // hosts pin selectors on it (E2E specs, accessibility scanners).
+        retireStandbyIfPainted();
         onLifecycle?.(makeLifecycleEvent('code-ready', { sessionId: meta.sessionId }));
     };
+    /**
+     * Retire the shell's standby ONLY when the mount paints something, and say
+     * so when a boot reaches its end painting nothing (ggui#1103). Three states
+     * that looked alike — negotiating, empty, painted — now read apart: the
+     * standby means "still coming", its absence with content means the card,
+     * its absence with a said status means "nothing to show".
+     */
+    let saidNothingToShow = false;
+    function retireStandbyIfPainted() {
+        if (renderer !== null && renderer.painted()) {
+            retireShellLoadingIndicator(doc);
+            // A frame that lands after we said there was nothing withdraws the
+            // sentence — the card is the answer now.
+            if (saidNothingToShow) {
+                saidNothingToShow = false;
+                setConnectedStatus(refs);
+            }
+            return;
+        }
+        if (!codeReadyEmitted)
+            return; // still coming — the standby is honest
+        retireShellLoadingIndicator(doc);
+        if (!saidNothingToShow) {
+            saidNothingToShow = true;
+            setStatus(refs, 'Nothing to show for this card.', 'idle');
+        }
+    }
     // Mode discriminators. The mount surface is DECOUPLED from the live
     // channel: static content (codeUrl/codeB64/kind) paints immediately
     // with no WS; the live trio (wsUrl+wsToken) is an OPTIONAL
@@ -735,6 +785,7 @@ export async function bootSequence(opts) {
         if (seed !== null) {
             await renderer.applyRender(seed);
             mountedRender = seed;
+            retireStandbyIfPainted();
             emitCodeReadyOnce();
         }
     }
@@ -1347,7 +1398,10 @@ export async function resolveMetaViaReadDoor(app, locator) {
     const envelope = readGguiShellEnvelope(text);
     if (envelope === undefined)
         return null;
-    const parsed = parseMcpAppAiGguiRenderMeta(envelope, { onInvalidTheme: reportInvalidAppTheme });
+    const parsed = parseMcpAppAiGguiRenderMeta(envelope, {
+        onInvalidTheme: reportInvalidAppTheme,
+        onStrippedThemeMembers: reportStrippedThemeMembers,
+    });
     if (!parsed.ok || parsed.meta === undefined)
         return null;
     const validated = validateMeta(parsed.meta);
@@ -3874,6 +3928,10 @@ async function bootProduction(opts) {
                         const themeMode = resolveMountThemeMode(meta);
                         return themeMode !== undefined ? { themeMode } : {};
                     })(),
+                    // The host's canvas is the chrome (ggui#1041): a `fullscreen` display mode
+                    // composes the tree with `fit: 'fill'`; the hostcontextchanged re-injection
+                    // below picks up a flip exactly as it does the theme mode.
+                    ...(hostAnnouncedDisplayMode() === 'fullscreen' ? { fit: 'fill' } : {}),
                     // Per-app theme (ggui#987 v2). Threaded straight from the
                     // bootstrap's `_meta["ai.ggui/render"].theme` (typed `AppTheme`,
                     // already injection-validated by the wire parser) onto the mount
@@ -4067,6 +4125,7 @@ async function bootProduction(opts) {
                 getChannelTransport: () => channelTransport,
             }));
             return {
+                painted: () => renderHandle?.painted === true,
                 rootWireConfig: rootConfig,
                 streamBus,
                 applyRender,

package/dist/status-dom.js

@@ -35,6 +35,13 @@ export function ensureStatusDom(doc) {
         (() => {
             const el = doc.createElement('ul');
             el.setAttribute('data-ggui-session-root', '');
+            // The list is the runtime's mount target, not a list: without this
+            // reset the browser's defaults (16 px margins, a 40 px indent, disc
+            // bullets) sat inside every compact card's iframe — the card 40 px
+            // right of the pane edge and 32 px taller than its box (ggui#1096).
+            el.style.margin = '0';
+            el.style.padding = '0';
+            el.style.listStyle = 'none';
             doc.body.appendChild(el);
             return el;
         })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/iframe-runtime",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "The iframe-local ggui runtime: a self-contained ESM bundle that boots inside an MCP Apps host iframe, runs the protocol-version handshake, opens the live-channel WebSocket, and mounts the rendered UI. Bundles React, ReactDOM, and the ggui design system so generated component code has a single seam to read from.",
   "keywords": [
     "ggui",
@@ -41,12 +41,12 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.16.0",
-    "@ggui-ai/live-channel": "0.16.0",
-    "@ggui-ai/preview-a2ui": "0.16.0",
-    "@ggui-ai/gadgets": "0.16.0",
-    "@ggui-ai/protocol": "0.16.0",
-    "@ggui-ai/wire": "0.16.0"
+    "@ggui-ai/gadgets": "0.18.0",
+    "@ggui-ai/design": "0.18.0",
+    "@ggui-ai/live-channel": "0.18.0",
+    "@ggui-ai/preview-a2ui": "0.18.0",
+    "@ggui-ai/protocol": "0.18.0",
+    "@ggui-ai/wire": "0.18.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0"