@ggui-ai/iframe-runtime 0.9.0 → 0.10.0

package/dist/meta-parse.d.ts

@@ -30,6 +30,19 @@ export declare function validateMeta(meta: McpAppAiGguiRenderMeta): McpAppAiGgui
  * so the runtime can mount without any postMessage round-trip.
  */
 export declare function parseMetaFromGlobal(): McpAppAiGguiMetaParseResult;
+/**
+ * The `ui://ggui/render/…` LOCATOR a tool result publishes when a server
+ * runs the read-plane-only posture (`withholdResultMeta`, guuey#209 C3 /
+ * ggui#537): the bootstrap material is absent, but the view's durable
+ * identity rides `structuredContent.resourceUri` (ggui-aware hosts) and
+ * the spec-canonical `_meta.ui.resourceUri` (MCP Apps hosts) — same
+ * value, either slot. The runtime resolves such a result through the
+ * read-plane door (`app.readServerResource` → the per-render
+ * self-contained shell → its inlined envelope). `null` for anything else
+ * — a result that carries the slice inline never needs this, and a
+ * result with neither is not a view.
+ */
+export declare function extractLocatorFromToolResult(params: unknown): string | null;
 /**
  * Parse the render slice from a `ui/notifications/tool-result`
  * postMessage params payload. `params` is a `CallToolResult` per the

package/dist/meta-parse.js

@@ -274,6 +274,11 @@ function projectMeta(meta, hasStaticContent) {
             : {}),
         ...(meta.codeUrl !== undefined ? { codeUrl: meta.codeUrl } : {}),
         ...(meta.codeHash !== undefined ? { codeHash: meta.codeHash } : {}),
+        // Strict-CSP module-variant twin (ggui#522 slice 2). The protocol
+        // parser already enforces the with-a-raw-carrier pairing.
+        ...(meta.codeModuleUrl !== undefined
+            ? { codeModuleUrl: meta.codeModuleUrl }
+            : {}),
         ...(meta.codeB64 !== undefined ? { codeB64: meta.codeB64 } : {}),
         ...(meta.kind !== undefined ? { kind: meta.kind } : {}),
     };
@@ -349,6 +354,29 @@ export function parseMetaFromGlobal() {
     }
     return validateMeta(parsed.meta);
 }
+/**
+ * The `ui://ggui/render/…` LOCATOR a tool result publishes when a server
+ * runs the read-plane-only posture (`withholdResultMeta`, guuey#209 C3 /
+ * ggui#537): the bootstrap material is absent, but the view's durable
+ * identity rides `structuredContent.resourceUri` (ggui-aware hosts) and
+ * the spec-canonical `_meta.ui.resourceUri` (MCP Apps hosts) — same
+ * value, either slot. The runtime resolves such a result through the
+ * read-plane door (`app.readServerResource` → the per-render
+ * self-contained shell → its inlined envelope). `null` for anything else
+ * — a result that carries the slice inline never needs this, and a
+ * result with neither is not a view.
+ */
+export function extractLocatorFromToolResult(params) {
+    if (!isPlainObject(params))
+        return null;
+    const sc = params['structuredContent'];
+    const fromStructured = isPlainObject(sc) && typeof sc['resourceUri'] === 'string' ? sc['resourceUri'] : null;
+    const meta = params['_meta'];
+    const ui = isPlainObject(meta) ? meta['ui'] : undefined;
+    const fromUi = isPlainObject(ui) && typeof ui['resourceUri'] === 'string' ? ui['resourceUri'] : null;
+    const uri = fromStructured ?? fromUi;
+    return uri !== null && uri.startsWith('ui://ggui/render/') ? uri : null;
+}
 /**
  * Parse the render slice from a `ui/notifications/tool-result`
  * postMessage params payload. `params` is a `CallToolResult` per the

package/dist/react-renderer.d.ts

@@ -41,6 +41,18 @@ export interface ReactRootMountOptions {
         readonly id?: string;
         readonly componentCode: string;
         readonly props?: Record<string, unknown>;
+        /**
+         * Strict-CSP module variant of `componentCode` (ggui#522 slice 2):
+         * a server-side import-rewritten twin of the SAME bytes, directly
+         * `import()`able (its imports resolve to static shim assets on an
+         * allowed origin — no `data:`, no `blob:`, no eval). Tried FIRST;
+         * any failure falls through to the blob/inline ladder on the raw
+         * bytes. Callers MUST pass it only when it names exactly these
+         * `componentCode` bytes — a stale variant would paint the WRONG
+         * component, not fail (the runtime's dispatcher guards this by
+         * attaching it to the inline seed only).
+         */
+        readonly codeModuleUrl?: string;
     };
     readonly themeId?: string;
     /**

package/dist/react-renderer.js

@@ -235,6 +235,30 @@ export async function mountReactRoot(container, opts) {
                 ? { gadgetPackages: currentOpts.gadgetPackages }
                 : {}),
         }));
+        // Asset-module path (ggui#522 slice 2) — FIRST when the mount
+        // carries the strict-CSP variant URL: a plain https module import,
+        // legal under `script-src` origins alone, no scheme sources, no
+        // eval. Under a strict host CSP it is the ONLY path that works;
+        // under a permissive one it costs a CDN round-trip on cold cache
+        // and nothing on warm (the URL is immutable). Any failure — CSP
+        // block, network fault, a 404 from a redeployed variant family —
+        // falls through to the raw-bytes ladder below. No document latch
+        // on failure: unlike the per-evaluation blob probe, this branch
+        // runs only when componentCode changes (rare — usually once per
+        // mount), so the retry cost is one fetch, and the failure classes
+        // (transient network vs permanent CSP) are indistinguishable in
+        // the import error anyway.
+        const moduleUrl = currentOpts.render.codeModuleUrl;
+        if (moduleUrl !== undefined) {
+            try {
+                const mod = (await import(
+                /* webpackIgnore: true */ /* @vite-ignore */ moduleUrl));
+                return pick(mod);
+            }
+            catch {
+                // Fall through — the raw bytes are the authoritative carrier.
+            }
+        }
         // Once URL-scheme module loading has been proven blocked in this
         // document, go straight to inline execution — the CSP verdict
         // cannot change within the document's lifetime.
@@ -278,9 +302,25 @@ export async function mountReactRoot(container, opts) {
         }
     }
     function renderTree(opts) {
-        const themeCss = opts.themeId
+        let themeCss = opts.themeId
             ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
             : getScopedCssTokens(scopeClass, opts.themeMode);
+        if (opts.appTheme) {
+            const decls = Object.entries(opts.appTheme.cssVariables)
+                .map(([k, v]) => `${k}: ${v};`)
+                .join('');
+            // 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 and BEFORE `cssOverrides`, so: base < operator overlay <
+            // explicit overrides. Values validated injection-safe upstream
+            // (same guarantee the `:root` append cites).
+            themeCss += `.${scopeClass}{${decls}}`;
+        }
         // Also inject theme CSS at `:root` on `document.head`. The scoped
         // injection above isolates token resolution to the React tree, but
         // the embedding shell's body styles (font-family, color, background)
@@ -298,10 +338,12 @@ export async function mountReactRoot(container, opts) {
                 const decls = Object.entries(opts.appTheme.cssVariables)
                     .map(([k, v]) => `${k}: ${v};`)
                     .join('');
-                // Appended AFTER the base block → the per-app overlay wins; it is a
-                // partial set (unset vars keep their token defaults). CSS custom
-                // properties at :root inherit into the scoped React tree, so this
-                // alone is sufficient for the component to resolve `var(--ggui-*)`.
+                // 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.

package/dist/render-item.d.ts

@@ -29,6 +29,15 @@ export interface RenderItemOptions {
      * this. STDLIB `@ggui-ai/gadgets` is always rewritten regardless.
      */
     readonly gadgetPackages?: readonly string[];
+    /**
+     * Strict-CSP module variant of the render's `componentCode`
+     * (ggui#522 slice 2), forwarded to
+     * {@link ReactRootMountOptions.render.codeModuleUrl}. The CALLER
+     * owns the bytes↔URL association: pass it only when it names
+     * exactly `render.componentCode`'s bytes (the runtime attaches it
+     * to the inline seed mount only — a WS-delivered render drops it).
+     */
+    readonly codeModuleUrl?: string;
     /** Theme id passed to ReactComponentRenderer for scoped CSS. */
     readonly themeId?: string;
     /**

package/dist/render-item.js

@@ -169,6 +169,9 @@ export async function mountRender(container, opts) {
                 ...(render.props !== undefined
                     ? { props: render.props }
                     : {}),
+                ...(currentOpts.codeModuleUrl !== undefined
+                    ? { codeModuleUrl: currentOpts.codeModuleUrl }
+                    : {}),
             },
             ...(gadgetPackages !== undefined ? { gadgetPackages } : {}),
             ...(currentOpts.themeId !== undefined ? { themeId: currentOpts.themeId } : {}),
@@ -234,6 +237,9 @@ export async function mountRender(container, opts) {
                         ...(render.props !== undefined
                             ? { props: render.props }
                             : {}),
+                        ...(next.codeModuleUrl !== undefined
+                            ? { codeModuleUrl: next.codeModuleUrl }
+                            : {}),
                     },
                     ...(next.themeId !== undefined ? { themeId: next.themeId } : {}),
                     ...(next.themeMode !== undefined ? { themeMode: next.themeMode } : {}),

package/dist/runtime.d.ts

@@ -1,3 +1,30 @@
+/**
+ * `@ggui-ai/iframe-runtime` iframe runtime entry.
+ *
+ * This is the file esbuild bundles into `dist/iframe-runtime.js`. The
+ * thin-shell HTML loads it via `<script type="module" src=".../iframe-runtime.js">`;
+ * on import the side-effects below take over: build a status DOM,
+ * postMessage `ui/initialize` to the parent, parse the bootstrap, open
+ * the WebSocket, run the version handshake, and mount the render
+ * placeholder.
+ *
+ * Boot sequence:
+ *   - Boot from the `_meta["ai.ggui/render"]` slice received via
+ *     `ui/initialize`.
+ *   - Open the WebSocket, run the subscribe handshake.
+ *   - Mount the render — either a structural placeholder or, when
+ *     the renderer hooks are wired, a React mount of `componentCode`.
+ *
+ * The runtime advertises its build version via a post-`ui/initialize`
+ * notification (`ggui:renderer-ready`).
+ *
+ * Failure surfacing: every parse / handshake failure goes to two
+ * places — (1) the in-iframe status line (operator-visible) and
+ * (2) a parent-bound `postMessage({type:'ggui:bootstrap-failed', ...})`.
+ * The post-message envelope is consumed by the `<McpAppIframe>` host
+ * wrapper, which routes it to the host's `onError` callback.
+ */
+import './zod-jitless.js';
 import type { DrainAckPayload, JsonValue, JsonObject, GguiSession } from '@ggui-ai/protocol';
 import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
 import { type McpAppAiGguiRenderMeta, type McpAppBootstrapFailedMessage, type McpAppRendererReadyMessage } from '@ggui-ai/protocol/integrations/mcp-apps';
@@ -47,6 +74,29 @@ export type ConnectAppResult = {
  *   without invoking the full boot pipeline.
  */
 export declare function setCurrentApp(app: App): void;
+/**
+ * The host's announced color mode, read from the connected App's
+ * pre-merged hostContext (`ui/initialize` result, kept current by the
+ * App across `host-context-changed`). `undefined` when no App is
+ * connected, the host sent no `theme`, or it sent something outside
+ * the spec's `'light' | 'dark'` literals (dropped, never guessed —
+ * the same tolerant posture as `projectHostContext`).
+ *
+ * This is the INPUT leg of host-theme adaptation
+ * (rnd/gen-ui/beauty/experiments/002-host-theme-adaptation.md, ggui#551):
+ * `hostContext.theme` alone reaches only `data-theme` +
+ * `color-scheme` via `applyDocumentTheme` — nothing in the token
+ * pipeline keys off it, so a dark host painted the light ladder
+ * (host-fit 46.0 vs 87.7 with the dark ladder, probe `cc728a8eb`).
+ * `buildOpts` consumes this ONLY when the slice stamps no `themeMode`:
+ * every operator layer (live provider > per-render override > app
+ * default > server default) still wins by being stamped; the host
+ * fills the gap where no operator had an opinion.
+ *
+ * @internal — exported for unit tests (`setCurrentApp` injects the
+ *   App); production caller is `buildOpts` inside `bootSequence`.
+ */
+export declare function hostAnnouncedThemeMode(): 'light' | 'dark' | undefined;
 /**
  * @internal — exported for unit tests to reset module state between
  * scenarios.
@@ -193,6 +243,17 @@ export interface BootSequenceOptions {
      * arrives, and `hostContext` is captured from `app.getHostContext()`.
      */
     readonly preResolvedMeta?: McpAppAiGguiRenderMeta;
+    /**
+     * Autostart-layer pre-resolution of the read-plane door (ggui#537):
+     * a tool result that arrived before `bootSequence` ran carried the
+     * view's LOCATOR (`ui://ggui/render/…`) but no bootstrap material —
+     * the read-plane-only posture. The runtime cannot read the resource
+     * before the App is connected, so the locator is threaded here and
+     * resolved via {@link resolveMetaViaReadDoor} right after the
+     * handshake, ahead of the Tier 2 tool-result wait. Ignored when
+     * `preResolvedMeta` is set.
+     */
+    readonly preResolvedLocator?: string;
     /**
      * How long to wait for the spec-canonical `ui/notifications/tool-result`
      * notification (Tier 2 of the resolver chain) before failing with
@@ -409,6 +470,29 @@ export declare function extractMetaFromToolResult(params: unknown): McpAppAiGgui
  * runtime reads it once at autostart.
  */
 export declare function readPendingToolResults(): McpAppAiGguiRenderMeta | null;
+/**
+ * Sibling of {@link readPendingToolResults} for the read-plane-only
+ * posture (ggui#537): the NEWEST buffered tool result that carries a
+ * `ui://ggui/render/…` locator but no bootstrap material. Consulted only
+ * when the buffer yielded no inline slice; the autostart threads it to
+ * `bootSequence` as `preResolvedLocator`, resolved after the handshake.
+ */
+export declare function readPendingToolResultLocator(): string | null;
+/**
+ * The read-plane door (ggui#537). A server running the read-plane-only
+ * posture publishes only the view's identity on the tool result — the
+ * `ui://ggui/render/…` locator — and no bootstrap material; the
+ * per-render resource that locator names is the self-contained shell,
+ * whose document inlines the very envelope this runtime boots from.
+ * Ask the HOST to read it (`app.readServerResource` → `resources/read`,
+ * proxied by the host's own MCP client — no fetch from this sandbox, so
+ * a host CSP without `connect-src` to the server is not in the way),
+ * recover the envelope with the protocol's writer/reader pair
+ * ({@link readGguiShellEnvelope}), and validate it exactly as an inline
+ * slice would be. `null` on any miss (host cannot proxy reads, resource
+ * gone, no envelope) — the caller's other tiers still decide.
+ */
+export declare function resolveMetaViaReadDoor(app: App, locator: string): Promise<McpAppAiGguiRenderMeta | null>;
 /**
  * Render a submit-action's `data` payload as a short inline string
  * for embedding in a `ui/message` consent prompt. Goal: human-

package/dist/runtime.js

@@ -1,5 +1,34 @@
-import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, } from '@ggui-ai/protocol/integrations/mcp-apps';
-import { parseMetaFromGlobal, parseMetaFromToolResult, } from './meta-parse.js';
+/**
+ * `@ggui-ai/iframe-runtime` iframe runtime entry.
+ *
+ * This is the file esbuild bundles into `dist/iframe-runtime.js`. The
+ * thin-shell HTML loads it via `<script type="module" src=".../iframe-runtime.js">`;
+ * on import the side-effects below take over: build a status DOM,
+ * postMessage `ui/initialize` to the parent, parse the bootstrap, open
+ * the WebSocket, run the version handshake, and mount the render
+ * placeholder.
+ *
+ * Boot sequence:
+ *   - Boot from the `_meta["ai.ggui/render"]` slice received via
+ *     `ui/initialize`.
+ *   - Open the WebSocket, run the subscribe handshake.
+ *   - Mount the render — either a structural placeholder or, when
+ *     the renderer hooks are wired, a React mount of `componentCode`.
+ *
+ * The runtime advertises its build version via a post-`ui/initialize`
+ * notification (`ggui:renderer-ready`).
+ *
+ * Failure surfacing: every parse / handshake failure goes to two
+ * places — (1) the in-iframe status line (operator-visible) and
+ * (2) a parent-bound `postMessage({type:'ggui:bootstrap-failed', ...})`.
+ * The post-message envelope is consumed by the `<McpAppIframe>` host
+ * wrapper, which routes it to the host's `onError` callback.
+ */
+// FIRST import on purpose — declares zod jitless before any
+// schema-defining dependency initializes (see zod-jitless.ts).
+import './zod-jitless.js';
+import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, parseMcpAppAiGguiRenderMeta, readGguiShellEnvelope, } from '@ggui-ai/protocol/integrations/mcp-apps';
+import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './meta-parse.js';
 import { projectHostContext } from '@ggui-ai/protocol';
 import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
 import { applyHostContextStyling, attachListener as attachHostContextListener, seed as seedHostContext, } from './host-context-emitter.js';
@@ -131,6 +160,32 @@ export function setCurrentApp(app) {
 function getCurrentApp() {
     return currentApp;
 }
+/**
+ * The host's announced color mode, read from the connected App's
+ * pre-merged hostContext (`ui/initialize` result, kept current by the
+ * App across `host-context-changed`). `undefined` when no App is
+ * connected, the host sent no `theme`, or it sent something outside
+ * the spec's `'light' | 'dark'` literals (dropped, never guessed —
+ * the same tolerant posture as `projectHostContext`).
+ *
+ * This is the INPUT leg of host-theme adaptation
+ * (rnd/gen-ui/beauty/experiments/002-host-theme-adaptation.md, ggui#551):
+ * `hostContext.theme` alone reaches only `data-theme` +
+ * `color-scheme` via `applyDocumentTheme` — nothing in the token
+ * pipeline keys off it, so a dark host painted the light ladder
+ * (host-fit 46.0 vs 87.7 with the dark ladder, probe `cc728a8eb`).
+ * `buildOpts` consumes this ONLY when the slice stamps no `themeMode`:
+ * every operator layer (live provider > per-render override > app
+ * default > server default) still wins by being stamped; the host
+ * fills the gap where no operator had an opinion.
+ *
+ * @internal — exported for unit tests (`setCurrentApp` injects the
+ *   App); production caller is `buildOpts` inside `bootSequence`.
+ */
+export function hostAnnouncedThemeMode() {
+    const theme = currentApp?.getHostContext()?.theme;
+    return theme === 'light' || theme === 'dark' ? theme : undefined;
+}
 /**
  * @internal — exported for unit tests to reset module state between
  * scenarios.
@@ -314,7 +369,16 @@ export async function bootSequence(opts) {
             parsed = inline;
         }
         else {
-            const fromToolResult = await toolResultPromise;
+            // Tier 1.5 — the read-plane door (ggui#537). A pre-boot tool
+            // result named the view but carried no material; now that the
+            // App is connected, resolve the locator through the host's
+            // `resources/read` proxy. One round trip, ahead of the Tier 2
+            // wait; a miss falls through to Tier 2 unchanged (its listener
+            // is already armed and resolves locator-only arrivals too).
+            const viaDoor = opts.preResolvedLocator !== undefined
+                ? await resolveMetaViaReadDoor(app, opts.preResolvedLocator)
+                : null;
+            const fromToolResult = viaDoor ?? (await toolResultPromise);
             if (fromToolResult !== null) {
                 parsed = { ok: true, meta: fromToolResult };
             }
@@ -1052,6 +1116,26 @@ export function readPendingToolResults() {
     }
     return null;
 }
+/**
+ * Sibling of {@link readPendingToolResults} for the read-plane-only
+ * posture (ggui#537): the NEWEST buffered tool result that carries a
+ * `ui://ggui/render/…` locator but no bootstrap material. Consulted only
+ * when the buffer yielded no inline slice; the autostart threads it to
+ * `bootSequence` as `preResolvedLocator`, resolved after the handshake.
+ */
+export function readPendingToolResultLocator() {
+    if (typeof window === 'undefined')
+        return null;
+    const raw = window.__GGUI_PENDING_TOOL_RESULTS__;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    for (let i = raw.length - 1; i >= 0; i--) {
+        const locator = extractLocatorFromToolResult(raw[i]);
+        if (locator !== null)
+            return locator;
+    }
+    return null;
+}
 /**
  * Listen for a `ui/notifications/tool-result` notification via the
  * App's spec-canonical event surface and resolve to the extracted
@@ -1067,36 +1151,75 @@ export function readPendingToolResults() {
 function awaitToolResultMetaFromApp(app, timeoutMs) {
     return new Promise((resolve) => {
         let settled = false;
-        const handler = (params) => {
+        const settle = (value) => {
             if (settled)
                 return;
-            const meta = extractMetaFromToolResult(params);
-            if (meta === null)
-                return;
             settled = true;
             app.removeEventListener('toolresult', handler);
             clearTimeout(timer);
-            resolve(meta);
+            resolve(value);
         };
-        app.addEventListener('toolresult', handler);
-        const timer = setTimeout(() => {
+        const handler = (params) => {
             if (settled)
                 return;
-            settled = true;
-            app.removeEventListener('toolresult', handler);
-            resolve(null);
-        }, timeoutMs);
+            const meta = extractMetaFromToolResult(params);
+            if (meta !== null) {
+                settle(meta);
+                return;
+            }
+            // Read-plane door (ggui#537): identity-only result → resolve the
+            // locator through the host's `resources/read` proxy. Async, and
+            // it never settles `null` — a later result carrying the slice
+            // inline (or the timeout) still decides.
+            const locator = extractLocatorFromToolResult(params);
+            if (locator === null)
+                return;
+            void resolveMetaViaReadDoor(app, locator).then((resolved) => {
+                if (resolved !== null)
+                    settle(resolved);
+            });
+        };
+        app.addEventListener('toolresult', handler);
+        const timer = setTimeout(() => settle(null), timeoutMs);
     });
 }
 /**
- * Pre-handshake variant — listens to raw `window.message` for the
- * autostart layer. Used BEFORE the App is constructed, so this can't
- * route through `app.addEventListener`. Pairs with the minimal-shell
- * pattern: the shell buffers any tool-results that arrived BEFORE
- * runtime load (read via {@link readPendingToolResults}); this
- * listener catches the ones that arrive AFTER the bundle parses but
- * BEFORE bootSequence runs.
- */
+ * The read-plane door (ggui#537). A server running the read-plane-only
+ * posture publishes only the view's identity on the tool result — the
+ * `ui://ggui/render/…` locator — and no bootstrap material; the
+ * per-render resource that locator names is the self-contained shell,
+ * whose document inlines the very envelope this runtime boots from.
+ * Ask the HOST to read it (`app.readServerResource` → `resources/read`,
+ * proxied by the host's own MCP client — no fetch from this sandbox, so
+ * a host CSP without `connect-src` to the server is not in the way),
+ * recover the envelope with the protocol's writer/reader pair
+ * ({@link readGguiShellEnvelope}), and validate it exactly as an inline
+ * slice would be. `null` on any miss (host cannot proxy reads, resource
+ * gone, no envelope) — the caller's other tiers still decide.
+ */
+export async function resolveMetaViaReadDoor(app, locator) {
+    let text;
+    try {
+        const res = await app.readServerResource({ uri: locator });
+        const first = res.contents[0];
+        text = first !== undefined && 'text' in first && typeof first.text === 'string' ? first.text : undefined;
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console -- operator-visible: the door is a boot tier, its miss must be legible
+        console.warn(`[ggui-runtime] read-plane door: host could not read ${locator} — ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    if (text === undefined)
+        return null;
+    const envelope = readGguiShellEnvelope(text);
+    if (envelope === undefined)
+        return null;
+    const parsed = parseMcpAppAiGguiRenderMeta(envelope);
+    if (!parsed.ok || parsed.meta === undefined)
+        return null;
+    const validated = validateMeta(parsed.meta);
+    return validated.ok ? validated.meta : null;
+}
 function awaitToolResultMeta(timeoutMs) {
     if (typeof window === 'undefined')
         return Promise.resolve(null);
@@ -1119,8 +1242,17 @@ function awaitToolResultMeta(timeoutMs) {
                 return;
             }
             const meta = extractMetaFromToolResult(m.params);
-            if (meta !== null)
-                settle(meta);
+            if (meta !== null) {
+                settle({ kind: 'meta', meta });
+                return;
+            }
+            // Identity-only result (ggui#537): settle NOW with the locator so
+            // boot starts immediately and the door runs after the handshake —
+            // waiting the full timeout for a slice this posture never sends
+            // would cost every spec-host view 30 s for nothing.
+            const locator = extractLocatorFromToolResult(m.params);
+            if (locator !== null)
+                settle({ kind: 'locator', locator });
         };
         window.addEventListener('message', onMessage);
         const timer = setTimeout(() => settle(null), timeoutMs);
@@ -2969,7 +3101,7 @@ function readLiveBootstrapShape() {
  * re-await the same postMessage or re-parse the same global), saving
  * up to the 30s postMessage timeout for spec-strict hosts.
  */
-function runBootProduction(preResolvedMeta) {
+function runBootProduction(preResolvedMeta, preResolvedLocator) {
     const { app, transport } = createDefaultApp();
     void bootProduction({
         doc: document,
@@ -2985,6 +3117,7 @@ function runBootProduction(preResolvedMeta) {
         onObserve: postObservabilityToParent,
         onLifecycle: postLifecycleToParent,
         ...(preResolvedMeta !== undefined ? { preResolvedMeta } : {}),
+        ...(preResolvedLocator !== undefined ? { preResolvedLocator } : {}),
     });
 }
 if (shouldAutostart() && typeof window !== 'undefined') {
@@ -3015,15 +3148,26 @@ if (shouldAutostart() && typeof window !== 'undefined') {
     }
     else {
         const buffered = readPendingToolResults();
+        const bufferedLocator = buffered === null ? readPendingToolResultLocator() : null;
         if (buffered !== null) {
             runBootProduction(buffered);
         }
+        else if (bufferedLocator !== null) {
+            // Read-plane-only posture (ggui#537): the buffered result named
+            // the view; the door resolves it right after the handshake.
+            runBootProduction(undefined, bufferedLocator);
+        }
         else if (readLiveBootstrapShape()) {
             runBootProduction();
         }
         else {
-            void awaitToolResultMeta(POSTMESSAGE_BOOT_TIMEOUT_MS).then((postMessageMeta) => {
-                runBootProduction(postMessageMeta ?? undefined);
+            void awaitToolResultMeta(POSTMESSAGE_BOOT_TIMEOUT_MS).then((pre) => {
+                if (pre === null)
+                    runBootProduction();
+                else if (pre.kind === 'meta')
+                    runBootProduction(pre.meta);
+                else
+                    runBootProduction(undefined, pre.locator);
             });
         }
     }
@@ -3302,10 +3446,30 @@ async function bootProduction(opts) {
                     ...(meta.gadgets !== undefined
                         ? { gadgetPackages: meta.gadgets.map((g) => g.package) }
                         : {}),
-                    ...(meta.themeId !== undefined ? { themeId: meta.themeId } : {}),
-                    ...(meta.themeMode !== undefined
-                        ? { themeMode: meta.themeMode }
+                    // Strict-CSP module variant (ggui#522 slice 2) — attached to
+                    // the INLINE SEED mount only, detected by the absence of the
+                    // server-assigned ledger fields (`buildGguiSessionSeedInput`
+                    // omits them; every wire-delivered GguiSession carries them).
+                    // The variant URL names the SEEDED bytes: a WS-delivered
+                    // body may differ, and importing a stale variant would paint
+                    // the WRONG component rather than fail. A WS redelivery of
+                    // the SAME bytes loses nothing — same code ⇒ the renderer
+                    // skips re-evaluation entirely.
+                    ...(meta.codeModuleUrl !== undefined &&
+                        render.type !== 'mcpApps' &&
+                        render.type !== 'system' &&
+                        !('createdAt' in render)
+                        ? { codeModuleUrl: meta.codeModuleUrl }
                         : {}),
+                    ...(meta.themeId !== undefined ? { themeId: meta.themeId } : {}),
+                    // Mode: the slice's stamped `themeMode` (every operator layer
+                    // resolves into it) wins; when absent, the HOST's announced
+                    // theme fills the gap (ggui#551 — see `hostAnnouncedThemeMode`).
+                    // Absent-in-slice means "no operator opinion", not "light".
+                    ...(() => {
+                        const themeMode = meta.themeMode ?? hostAnnouncedThemeMode();
+                        return themeMode !== undefined ? { themeMode } : {};
+                    })(),
                     // Per-app theme overlay (St3 M2.2). Threaded straight from the
                     // bootstrap's `_meta["ai.ggui/render"].theme` (typed `AppTheme`,
                     // already injection-validated by the wire parser) onto the mount
@@ -3493,5 +3657,8 @@ async function bootProduction(opts) {
         ...(opts.preResolvedMeta !== undefined
             ? { preResolvedMeta: opts.preResolvedMeta }
             : {}),
+        ...(opts.preResolvedLocator !== undefined
+            ? { preResolvedLocator: opts.preResolvedLocator }
+            : {}),
     });
 }

package/dist/server.d.ts

@@ -34,3 +34,22 @@ export declare const RUNTIME_DIST_DIR: string;
  * `bootstrap.runtimeUrl`, never hardcodes it.
  */
 export declare const RUNTIME_BUNDLE_URL_PATH: "/_ggui/iframe-runtime.js";
+/**
+ * Directory of the static shim modules (`dist/shims/<name>.js`) the
+ * build emits alongside the bundle (ggui#522 slice 2 — `asset-url`
+ * delivery). The mcp-server captures these files at composition and
+ * serves them under `/_ggui/shims/<runtime-hash>/<name>.js` with the
+ * same immutable posture as the hashed bundle route: the shims ship in
+ * the same dist as the bundle, so the bundle's content hash versions
+ * both — a shim-affecting change in the design package also changes
+ * the bundle bytes.
+ */
+export declare const RUNTIME_SHIMS_DIR: string;
+/**
+ * The URL prefix under which the mcp-server publishes the shim
+ * directory family. The full shim directory for a given build is
+ * `<origin>${RUNTIME_SHIMS_URL_PREFIX}/<runtime-hash>` — the server-
+ * side `asset-url` rewrite composes shim URLs on it, and the shim
+ * route parses it back.
+ */
+export declare const RUNTIME_SHIMS_URL_PREFIX: "/_ggui/shims";