@ggui-ai/iframe-runtime 0.9.0 → 0.11.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;
     /**
@@ -50,17 +62,37 @@ export interface ReactRootMountOptions {
      */
     readonly themeMode?: 'light' | 'dark';
     /**
-     * Per-app theme overlay applied at the iframe's `:root` AFTER the base
-     * token block, so the operator-supplied `--ggui-*` values win the
-     * cascade (a partial set — unset vars keep their token defaults). 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.
+     * 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.
+     *
+     * 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.
      */
     readonly appTheme?: {
         readonly mode: 'light' | 'dark';
         readonly cssVariables: Record<string, string>;
     };
+    /**
+     * Host-announced palette, already translated onto `--ggui-*` tokens
+     * (see `host-palette-bridge.ts` — the spec `--color-*` vocabulary
+     * never reaches this layer). Merged into the scoped token block
+     * after the base block and BEFORE `appTheme`, so it repaints only
+     * the slots no operator theme re-specifies (ggui#572; precedence
+     * per the ggui#573 ruling above). Values are sanitized by the
+     * bridge before they get here — host input never reaches this
+     * string-join raw.
+     */
+    readonly hostPalette?: Readonly<Record<string, string>>;
     readonly cssOverrides?: string;
     readonly onError?: (error: Error) => void;
     /**

package/dist/react-renderer.js

@@ -59,6 +59,18 @@ function makeScopeClass() {
     scopeCounter += 1;
     return `ggui-rcr-${scopeCounter}`;
 }
+/**
+ * Join a custom-property record into CSS declarations. Values were
+ * validated injection-safe upstream (appTheme: write-side
+ * `appThemeSchema` + the wire parser; hostPalette: the host-palette
+ * 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).
 // =============================================================================
@@ -235,6 +247,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 +314,33 @@ 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.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}}`;
+        }
         // 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)
@@ -294,14 +354,21 @@ export async function mountReactRoot(container, opts) {
             let rootCss = 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 = 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-*)`.
+                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.

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;
     /**
@@ -47,6 +56,14 @@ export interface RenderItemOptions {
         readonly mode: 'light' | 'dark';
         readonly cssVariables: Record<string, string>;
     };
+    /**
+     * Host-announced palette, pre-mapped onto `--ggui-*` tokens by the
+     * host-palette bridge. Forwarded to
+     * {@link ReactRootMountOptions.hostPalette}: the fallback layer
+     * beneath `appTheme` in the scoped token block (ggui#572, merge
+     * order per the ggui#573 ruling — slice wins, host fallback).
+     */
+    readonly hostPalette?: Readonly<Record<string, string>>;
     readonly cssOverrides?: string;
     readonly onError?: (err: Error) => void;
     /**

package/dist/render-item.js

@@ -169,11 +169,17 @@ 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 } : {}),
             ...(currentOpts.themeMode !== undefined ? { themeMode: currentOpts.themeMode } : {}),
             ...(currentOpts.appTheme !== undefined ? { appTheme: currentOpts.appTheme } : {}),
+            ...(currentOpts.hostPalette !== undefined
+                ? { hostPalette: currentOpts.hostPalette }
+                : {}),
             ...(currentOpts.cssOverrides !== undefined
                 ? { cssOverrides: currentOpts.cssOverrides }
                 : {}),
@@ -234,10 +240,14 @@ 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 } : {}),
                     ...(next.appTheme !== undefined ? { appTheme: next.appTheme } : {}),
+                    ...(next.hostPalette !== undefined ? { hostPalette: next.hostPalette } : {}),
                     ...(next.cssOverrides !== undefined ? { cssOverrides: next.cssOverrides } : {}),
                     ...(next.onError !== undefined ? { onError: next.onError } : {}),
                     renderWrapper: wrapInScopedProvider,

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,110 @@ 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;
+/**
+ * Resolve the mount's base-stylesheet color mode from the slice, with
+ * the host as the final fallback (ggui#589, completing the ggui#551
+ * precedence ruling — "slice wins, host is the fallback, absent ≠
+ * light"):
+ *
+ *   stamped `themeMode`  >  `theme.mode` (the slice theme OBJECT)  >
+ *   host-announced theme  >  undefined
+ *
+ * The middle leg is the ggui#589 fix: a render envelope carrying a
+ * per-app theme (`theme: {mode, cssVariables}`) but no top-level
+ * `themeMode` is still a slice-stamped mode opinion — before this,
+ * the base token ladder ignored it and painted the LIGHT token set
+ * under a dark overlay whenever the host (correctly, per the
+ * adapter-boundary doctrine in the native host helpers) announced no
+ * `hostContext.theme`: a light skeleton in a dark skin. The theme
+ * object's own `mode` already drove `color-scheme`; now it also
+ * selects the ladder.
+ *
+ * `undefined` still means "no opinion anywhere" — the renderer's
+ * default applies; never coerced to `'light'`.
+ *
+ * @internal — exported for unit tests; production caller is
+ *   `buildOpts` inside `bootSequence`.
+ */
+export declare function resolveMountThemeMode(meta: {
+    readonly themeMode?: 'light' | 'dark';
+    readonly theme?: {
+        readonly mode: 'light' | 'dark';
+        readonly cssVariables?: Record<string, string>;
+    };
+}): 'light' | 'dark' | undefined;
+/**
+ * Resolve the mount's base-theme id from the slice (ggui#589 ask 3):
+ *
+ *   stamped `themeId`  >  `theme.name` (the slice theme OBJECT's name)
+ *   >  undefined (renderer default ladder)
+ *
+ * The name leg makes a slice theme whose `name` matches a REGISTERED
+ * theme id select that theme as the BASE token ladder — the overlay's
+ * cssVariables still apply above it, so the base carries the full
+ * brand ramp coverage a sparse overlay cannot (the "only the mapped
+ * vars carry brand" store-frame class). An unregistered name is
+ * harmless by construction: `getScopedThemeCss` falls back to the
+ * default theme, which is byte-identical to the no-themeId path
+ * (`getScopedCssTokens` ≡ `getScopedThemeCss(default)`), so a slice
+ * naming its theme "My Custom" renders exactly as before.
+ *
+ * @internal — exported for unit tests; production caller is
+ *   `buildOpts` inside `bootSequence`.
+ */
+export declare function resolveMountThemeId(meta: {
+    readonly themeId?: string;
+    readonly theme?: {
+        readonly name?: string;
+        readonly mode?: 'light' | 'dark';
+        readonly cssVariables?: Record<string, string>;
+    };
+}): string | undefined;
+/**
+ * The host's announced palette, read from the connected App's
+ * pre-merged hostContext and translated onto `--ggui-*` tokens by the
+ * host-palette bridge. `undefined` when no App is connected, the host
+ * sent no `styles.variables`, or nothing in it maps/survives
+ * sanitization — callers spread-skip the option, exactly like
+ * {@link hostAnnouncedThemeMode}.
+ *
+ * This is the palette input leg of host-theme adaptation (ggui#572,
+ * the color analog of #551's mode leg above): the spec `--color-*`
+ * variables land as inline custom properties on `<html>` via the
+ * canonical ext-apps helper, but nothing ggui renders consumes that
+ * vocabulary, and the scoped token block shadows root inheritance
+ * anyway — so without this mapping a host palette repaints nothing.
+ * `buildOpts` threads it onto the mount options; the renderer merges
+ * it as the fallback layer BENEATH the slice's own theme (ggui#573
+ * ruling: slice wins, host fallback).
+ *
+ * @internal — exported for unit tests (`setCurrentApp` injects the
+ *   App); production caller is `buildOpts` inside `bootSequence`.
+ */
+export declare function hostAnnouncedPalette(): Readonly<Record<string, string>> | undefined;
 /**
  * @internal — exported for unit tests to reset module state between
  * scenarios.
@@ -193,6 +324,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 +551,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-
@@ -649,7 +814,7 @@ export declare function requestDisplayModeInParent(args: {
  * or honor an upstream `defaultPrevented` from a higher-priority
  * handler.
  *
- * Idempotent: re-mounts (via `installPostMountListener`) call this
+ * Idempotent: re-mounts (via `installPersistentToolResultListener`) call this
  * helper again; the {@link anchorClickInterceptInstalled} guard makes
  * subsequent calls a no-op.
  */