@ggui-ai/iframe-runtime 0.8.0 → 0.10.0

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-