@ggui-ai/iframe-runtime 0.7.0 → 0.8.0

package/dist/meta-parse.d.ts

@@ -11,9 +11,9 @@ import type { McpAppAiGguiMetaParseResult } from './types.js';
  *     direct-call callers like `parseMetaFromGlobal` / tests; the
  *     envelope-driven extractors already enforce this in the protocol-
  *     level parser).
- *   - At least one of `{live mode (wsUrl+wsToken), codeUrl, kind}` MUST
- *     be present. Without any mode discriminator the iframe has nothing
- *     to mount.
+ *   - At least one of `{live mode (wsUrl+wsToken), codeUrl, codeB64,
+ *     kind}` MUST be present. Without any mode discriminator the iframe
+ *     has nothing to mount.
  */
 export declare function validateMeta(meta: McpAppAiGguiRenderMeta): McpAppAiGguiMetaParseResult;
 /**

package/dist/meta-parse.js

@@ -40,9 +40,10 @@
  *
  *   - **live** — slice has `wsUrl` + `wsToken`; runtime opens
  *     live-channel WS and renders agent-driven frames.
- *   - **static-component** — slice has `codeUrl`; runtime fetches
- *     the content-addressable URL, dynamic-imports the React
- *     component, mounts it, never opens WS.
+ *   - **static-component** — slice has `codeUrl` (runtime fetches the
+ *     content-addressable URL) and/or `codeB64` (runtime decodes the
+ *     inline bytes, no fetch); mounts the React component, never
+ *     opens WS.
  *   - **system-card** — slice has `kind`; runtime maps to a
  *     built-in component via the system-card registry.
  *
@@ -177,9 +178,9 @@ function projectPublicEnv(raw) {
  *
  * Invariants enforced here that the combiner doesn't:
  *   - `expiresAt` (when present) MUST parse to a valid timestamp. If
- *     in the past AND the slice carries static content (codeUrl / kind),
- *     DEGRADE to static-only (drop `wsUrl` / `wsToken` / `expiresAt`);
- *     otherwise return EXPIRED_BOOTSTRAP.
+ *     in the past AND the slice carries static content (codeUrl /
+ *     codeB64 / kind), DEGRADE to static-only (drop `wsUrl` /
+ *     `wsToken` / `expiresAt`); otherwise return EXPIRED_BOOTSTRAP.
  *   - `gadgets` / `publicEnv` / `permissionsPolicy` /
  *     `streamWebSocketLocalTools` / `contextSlots` get defensive
  *     entry-level validation; malformed → defaulted.
@@ -260,6 +261,7 @@ function projectMeta(meta, hasStaticContent) {
             : {}),
         ...(meta.codeUrl !== undefined ? { codeUrl: meta.codeUrl } : {}),
         ...(meta.codeHash !== undefined ? { codeHash: meta.codeHash } : {}),
+        ...(meta.codeB64 !== undefined ? { codeB64: meta.codeB64 } : {}),
         ...(meta.kind !== undefined ? { kind: meta.kind } : {}),
     };
     return { ok: true, meta: projected };
@@ -275,9 +277,9 @@ function projectMeta(meta, hasStaticContent) {
  *     direct-call callers like `parseMetaFromGlobal` / tests; the
  *     envelope-driven extractors already enforce this in the protocol-
  *     level parser).
- *   - At least one of `{live mode (wsUrl+wsToken), codeUrl, kind}` MUST
- *     be present. Without any mode discriminator the iframe has nothing
- *     to mount.
+ *   - At least one of `{live mode (wsUrl+wsToken), codeUrl, codeB64,
+ *     kind}` MUST be present. Without any mode discriminator the iframe
+ *     has nothing to mount.
  */
 export function validateMeta(meta) {
     // `runtimeUrl` is a hard wire-required field on every render slice
@@ -292,8 +294,9 @@ export function validateMeta(meta) {
     }
     const hasLive = isNonEmptyString(meta.wsUrl) && isNonEmptyString(meta.wsToken);
     const hasCodeUrl = isNonEmptyString(meta.codeUrl);
+    const hasCodeB64 = isNonEmptyString(meta.codeB64);
     const hasKind = isNonEmptyString(meta.kind);
-    const hasStaticContent = hasCodeUrl || hasKind;
+    const hasStaticContent = hasCodeUrl || hasCodeB64 || hasKind;
     if (!hasLive && !hasStaticContent) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }

package/dist/react-renderer.js

@@ -32,7 +32,18 @@
 import React, { Component, createElement, Fragment, } from 'react';
 import { createRoot } from 'react-dom/client';
 import { stripMarkers, rewriteImports, getScopedThemeCss, getScopedCssTokens, getThemeCss, getCssTokens, } from '@ggui-ai/design/rendering';
-import { hoistImports, loadModule } from '@ggui-ai/design/module-loader';
+import { hoistImports, loadModule, loadModuleInline, probeUrlModuleLoad, } from '@ggui-ai/design/module-loader';
+/**
+ * Document-lifetime verdict: URL-scheme module loading (`blob:` main
+ * module + `data:` import shims) is blocked by the host CSP. Set only
+ * when the inline path succeeded where the URL path failed AND the
+ * known-good `probeUrlModuleLoad()` module ALSO fails — an arbitrary
+ * module's failure is not CSP evidence (an import-shim allowlist miss
+ * rejects blob-instantiation of that one module while URL loading is
+ * healthy, and latching on it would force every later evaluation in
+ * the document onto the inline path's narrower semantics).
+ */
+let urlModuleLoadBlocked = false;
 // =============================================================================
 // Scope class helpers — port of RCR's `makeScopeClass` + counter.
 // =============================================================================
@@ -177,25 +188,66 @@ export async function mountReactRoot(container, opts) {
         }
         // 1. Strip metadata markers (__GGUI_META__ / __GGUI_STREAM_SPEC__).
         const cleaned = stripMarkers(resolved);
-        // 2. Hoist imports above var declarations.
+        // 2. Hoist imports above var declarations. Load-bearing for BOTH
+        //    execution paths: the inline transform places its bindings at
+        //    the import statement's position, so a pre-import statement
+        //    referencing an imported name needs the hoist exactly as the
+        //    real module semantics do.
         const hoisted = hoistImports(cleaned);
-        // 3. Rewrite bare specifiers to data-url shims reading from
-        //    `globalThis.__ggui__`. The __ggui__ registry is installed
-        //    by `runtime.ts::bootSequence` BEFORE any mountReactRoot call
-        //    — see globals.ts docstring on TOCTOU ordering.
-        const rewritten = rewriteImports(hoisted, {
-            mode: 'data-url',
-            gadgetPackages: currentOpts.gadgetPackages,
-        });
-        // 4. Dynamically import the module.
-        const mod = await loadModule(rewritten);
-        // 5. Extract default export (or first function export).
-        const Comp = (mod.default ??
-            Object.values(mod).find((v) => typeof v === 'function'));
-        if (Comp === undefined) {
-            throw new Error('Module does not export a default component');
+        const pick = (mod) => {
+            const Comp = (mod.default ??
+                Object.values(mod).find((v) => typeof v === 'function'));
+            if (Comp === undefined) {
+                throw new Error('Module does not export a default component');
+            }
+            return Comp;
+        };
+        const evaluateInline = () => pick(loadModuleInline(hoisted, {
+            ...(currentOpts.gadgetPackages !== undefined
+                ? { gadgetPackages: currentOpts.gadgetPackages }
+                : {}),
+        }));
+        // 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.
+        if (urlModuleLoadBlocked) {
+            return evaluateInline();
+        }
+        try {
+            // 3. Rewrite bare specifiers to data-url shims reading from
+            //    `globalThis.__ggui__`. The __ggui__ registry is installed
+            //    by `runtime.ts::bootSequence` BEFORE any mountReactRoot call
+            //    — see globals.ts docstring on TOCTOU ordering.
+            const rewritten = rewriteImports(hoisted, {
+                mode: 'data-url',
+                gadgetPackages: currentOpts.gadgetPackages,
+            });
+            // 4. Dynamically import the module.
+            const mod = await loadModule(rewritten);
+            // 5. Extract default export (or first function export).
+            return pick(mod);
+        }
+        catch (urlError) {
+            // A host CSP granting only 'unsafe-inline' rejects the blob:/
+            // data: imports above. Attempt the inline classic-script path;
+            // a buggy component fails on both paths, and the original error
+            // is the honest one to surface.
+            try {
+                const Comp = evaluateInline();
+                // Latch the inline path for the rest of the document ONLY on
+                // proven CSP evidence: the known-good probe module must also
+                // fail. A module-specific blob failure (import-shim allowlist
+                // drift) leaves the latch off so the next evaluation gets real
+                // module semantics again.
+                if (!(await probeUrlModuleLoad())) {
+                    urlModuleLoadBlocked = true;
+                }
+                return Comp;
+            }
+            catch {
+                throw urlError;
+            }
         }
-        return Comp;
     }
     function renderTree(opts) {
         const themeCss = opts.themeId

package/dist/runtime.d.ts

@@ -342,18 +342,39 @@ export declare function readSelfContainedMeta(): McpAppAiGguiRenderMeta | null;
  * no WS at all for spec-compliant MCP-Apps hosts that expose no ggui
  * live channel (claude.ai / ChatGPT / Claude Desktop).
  *
- * Two static-content shapes (the autostart discriminator):
+ * Three static-content shapes (the autostart discriminator), in
+ * priority order:
  *   - `kind`    → a system-card seed (`type:'system'`); no fetch.
+ *   - `codeB64` → a compiled-component seed carried inline; DECODED,
+ *     never fetched. Preferred over `codeUrl` when both are present —
+ *     the inline bytes exist precisely for hosts whose iframe CSP
+ *     blocks the fetch.
  *   - `codeUrl` → a compiled-component seed; fetches the
  *     content-addressable component bytes.
  *
- * Returns `null` when the meta carries NEITHER (a live-only meta has
+ * Returns `null` when the meta carries NONE (a live-only meta has
  * nothing to seed — the first WS ack mounts it). Throws when a `codeUrl`
- * fetch fails so the caller can surface a typed boot failure. The four
- * server-assigned ledger fields are intentionally absent — the first
- * ack reconciles the seed to a full `GguiSession` (no fabrication).
+ * fetch fails or `codeB64` is not valid base64 so the caller can
+ * surface a typed boot failure. The four server-assigned ledger fields
+ * are intentionally absent — the first ack reconciles the seed to a
+ * full `GguiSession` (no fabrication).
  */
 export declare function buildGguiSessionSeedInput(meta: McpAppAiGguiRenderMeta): Promise<GguiSessionSeedInput | null>;
+/**
+ * Does this slice carry STATIC content the mount surface can paint
+ * without any network round-trip authorization — `codeUrl` (fetched),
+ * `codeB64` (decoded inline), or `kind` (built-in registry)?
+ *
+ * The ONE discriminator `bootSequence` consults when deciding whether
+ * the static seed-mount path runs. `codeB64` counting here is
+ * load-bearing for fetch-blocked hosts: their meta carries codeB64
+ * PLUS a live trio the iframe can never connect, and missing the
+ * inline arm would skip the only paint path and die on the dead WS.
+ * Mirrors `validateMeta`'s static-content arm (meta-parse.ts) and the
+ * protocol host-helper's `hasMountModeDiscriminator` — drift among
+ * the three IS the historical bug class, hence the named export.
+ */
+export declare function hasStaticContentMeta(meta: McpAppAiGguiRenderMeta): boolean;
 /**
  * Extract a {@link McpAppAiGguiRenderMeta} from a
  * `ui/notifications/tool-result` JSON-RPC params payload — the
@@ -369,6 +390,25 @@ export declare function buildGguiSessionSeedInput(meta: McpAppAiGguiRenderMeta):
  * impossible because the shell never inspects the slice-meta shape.
  */
 export declare function extractMetaFromToolResult(params: unknown): McpAppAiGguiRenderMeta | null;
+/**
+ * Drain `window.__GGUI_PENDING_TOOL_RESULTS__` — the buffer the
+ * minimal shell populates while messages arrive between
+ * shell-load and runtime-load. Returns the NEWEST valid slice meta
+ * (each new tool-result supersedes the previous — every emission
+ * carries complete state, so last-wins loses nothing). Newest-first
+ * matters on the inline-runtime shell: its preflight completes the
+ * handshake BEFORE the large bundle parses, so a render AND a
+ * follow-up update can both land in the buffer during parse — booting
+ * the oldest would paint stale props and drop the update forever
+ * (buffered entries never reach the post-mount listener; it hears
+ * only post-App arrivals).
+ *
+ * The shell-side buffer contract: an array whose ELEMENTS are the raw
+ * JSON-RPC `params` values of `ui/notifications/tool-result`
+ * notifications, in arrival order (shells cap it newest-biased). The
+ * runtime reads it once at autostart.
+ */
+export declare function readPendingToolResults(): 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

@@ -461,12 +461,12 @@ export async function bootSequence(opts) {
         onLifecycle?.(makeLifecycleEvent('code-ready', { sessionId: meta.sessionId }));
     };
     // Mode discriminators. The mount surface is DECOUPLED from the live
-    // channel: static content (codeUrl/kind) paints immediately with no WS;
-    // the live trio (wsUrl+wsToken) is an OPTIONAL enhancement that
-    // delivers props_update / data / re-render frames. A bootstrap with
-    // NEITHER has nothing to show and nowhere to subscribe.
-    const hasStaticContent = (typeof meta.codeUrl === 'string' && meta.codeUrl.length > 0) ||
-        (typeof meta.kind === 'string' && meta.kind.length > 0);
+    // channel: static content (codeUrl/codeB64/kind) paints immediately
+    // with no WS; the live trio (wsUrl+wsToken) is an OPTIONAL
+    // enhancement that delivers props_update / data / re-render frames.
+    // A bootstrap with NEITHER has nothing to show and nowhere to
+    // subscribe.
+    const hasStaticContent = hasStaticContentMeta(meta);
     const hasLiveTrio = typeof meta.wsUrl === 'string' &&
         meta.wsUrl.length > 0 &&
         typeof meta.wsToken === 'string' &&
@@ -517,7 +517,7 @@ export async function bootSequence(opts) {
     // misconfiguration — surface a typed boot failure.
     if (!hasLiveTrio) {
         if (mountedRender === null) {
-            const message = 'bootstrap carries neither static content (codeUrl/kind) nor a live trio (wsUrl/wsToken)';
+            const message = 'bootstrap carries neither static content (codeUrl/codeB64/kind) nor a live trio (wsUrl/wsToken)';
             setStatus(refs, message, 'error');
             emitBootFailure('MISSING_META_GGUI_BOOTSTRAP', message);
             return { ok: false, mountedRender };
@@ -801,16 +801,22 @@ function parseSeedProps(propsJson) {
  * no WS at all for spec-compliant MCP-Apps hosts that expose no ggui
  * live channel (claude.ai / ChatGPT / Claude Desktop).
  *
- * Two static-content shapes (the autostart discriminator):
+ * Three static-content shapes (the autostart discriminator), in
+ * priority order:
  *   - `kind`    → a system-card seed (`type:'system'`); no fetch.
+ *   - `codeB64` → a compiled-component seed carried inline; DECODED,
+ *     never fetched. Preferred over `codeUrl` when both are present —
+ *     the inline bytes exist precisely for hosts whose iframe CSP
+ *     blocks the fetch.
  *   - `codeUrl` → a compiled-component seed; fetches the
  *     content-addressable component bytes.
  *
- * Returns `null` when the meta carries NEITHER (a live-only meta has
+ * Returns `null` when the meta carries NONE (a live-only meta has
  * nothing to seed — the first WS ack mounts it). Throws when a `codeUrl`
- * fetch fails so the caller can surface a typed boot failure. The four
- * server-assigned ledger fields are intentionally absent — the first
- * ack reconciles the seed to a full `GguiSession` (no fabrication).
+ * fetch fails or `codeB64` is not valid base64 so the caller can
+ * surface a typed boot failure. The four server-assigned ledger fields
+ * are intentionally absent — the first ack reconciles the seed to a
+ * full `GguiSession` (no fabrication).
  */
 export async function buildGguiSessionSeedInput(meta) {
     const props = parseSeedProps(meta.propsJson);
@@ -824,6 +830,15 @@ export async function buildGguiSessionSeedInput(meta) {
             ...(props !== undefined ? { props } : {}),
         };
     }
+    // Inline compiled-component mode — decode, no network.
+    if (meta.codeB64 !== undefined) {
+        return {
+            id: meta.sessionId,
+            appId: meta.appId,
+            componentCode: decodeCodeB64(meta.codeB64),
+            ...(props !== undefined ? { props } : {}),
+        };
+    }
     // Compiled-component mode — fetch the content-addressable bytes.
     if (meta.codeUrl === undefined)
         return null;
@@ -839,6 +854,45 @@ export async function buildGguiSessionSeedInput(meta) {
         ...(props !== undefined ? { props } : {}),
     };
 }
+/**
+ * Does this slice carry STATIC content the mount surface can paint
+ * without any network round-trip authorization — `codeUrl` (fetched),
+ * `codeB64` (decoded inline), or `kind` (built-in registry)?
+ *
+ * The ONE discriminator `bootSequence` consults when deciding whether
+ * the static seed-mount path runs. `codeB64` counting here is
+ * load-bearing for fetch-blocked hosts: their meta carries codeB64
+ * PLUS a live trio the iframe can never connect, and missing the
+ * inline arm would skip the only paint path and die on the dead WS.
+ * Mirrors `validateMeta`'s static-content arm (meta-parse.ts) and the
+ * protocol host-helper's `hasMountModeDiscriminator` — drift among
+ * the three IS the historical bug class, hence the named export.
+ */
+export function hasStaticContentMeta(meta) {
+    return ((typeof meta.codeUrl === 'string' && meta.codeUrl.length > 0) ||
+        (typeof meta.codeB64 === 'string' && meta.codeB64.length > 0) ||
+        (typeof meta.kind === 'string' && meta.kind.length > 0));
+}
+/**
+ * Decode a `codeB64` slice field to UTF-8 component source. `atob`
+ * yields a byte string; routing through `TextDecoder` restores
+ * multi-byte characters (component source is UTF-8 — string literals
+ * carry emoji, quotes, non-Latin text). Throws a labeled error on
+ * malformed base64 so the boot-failure surface names the field.
+ */
+function decodeCodeB64(codeB64) {
+    try {
+        const byteString = atob(codeB64);
+        const bytes = new Uint8Array(byteString.length);
+        for (let i = 0; i < byteString.length; i++) {
+            bytes[i] = byteString.charCodeAt(i);
+        }
+        return new TextDecoder().decode(bytes);
+    }
+    catch (cause) {
+        throw new Error('buildGguiSessionSeedInput: codeB64 is not valid base64', { cause });
+    }
+}
 /**
  * Extract a {@link McpAppAiGguiRenderMeta} from a
  * `ui/notifications/tool-result` JSON-RPC params payload — the
@@ -860,23 +914,29 @@ export function extractMetaFromToolResult(params) {
 /**
  * Drain `window.__GGUI_PENDING_TOOL_RESULTS__` — the buffer the
  * minimal shell populates while messages arrive between
- * shell-load and runtime-load. Returns the first valid slice meta
- * found; later params (if any) are dropped (each new tool-result
- * supersedes the previous).
- *
- * The shell-side buffer contract: an array of
- * `{params: unknown}`-shaped JSON-RPC params from
- * `ui/notifications/tool-result` notifications, populated in
- * arrival order. The runtime drains it on first read.
- */
-function readPendingToolResults() {
+ * shell-load and runtime-load. Returns the NEWEST valid slice meta
+ * (each new tool-result supersedes the previous — every emission
+ * carries complete state, so last-wins loses nothing). Newest-first
+ * matters on the inline-runtime shell: its preflight completes the
+ * handshake BEFORE the large bundle parses, so a render AND a
+ * follow-up update can both land in the buffer during parse — booting
+ * the oldest would paint stale props and drop the update forever
+ * (buffered entries never reach the post-mount listener; it hears
+ * only post-App arrivals).
+ *
+ * The shell-side buffer contract: an array whose ELEMENTS are the raw
+ * JSON-RPC `params` values of `ui/notifications/tool-result`
+ * notifications, in arrival order (shells cap it newest-biased). The
+ * runtime reads it once at autostart.
+ */
+export function readPendingToolResults() {
     if (typeof window === 'undefined')
         return null;
     const raw = window.__GGUI_PENDING_TOOL_RESULTS__;
     if (!Array.isArray(raw) || raw.length === 0)
         return null;
-    for (const params of raw) {
-        const meta = extractMetaFromToolResult(params);
+    for (let i = raw.length - 1; i >= 0; i--) {
+        const meta = extractMetaFromToolResult(raw[i]);
         if (meta !== null)
             return meta;
     }
@@ -2609,6 +2669,10 @@ function installPostMountListener() {
             meta.sessionId,
             meta.kind ?? '-',
             meta.codeUrl ?? '-',
+            // Inline code participates like codeUrl: an update that ships new
+            // component bytes (re-generation) must re-mount even when
+            // sessionId + props are unchanged.
+            meta.codeB64 ?? '-',
             meta.propsJson ?? '-',
             liveTrio,
         ].join('|');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/iframe-runtime",
-  "version": "0.7.0",
+  "version": "0.8.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",
@@ -35,12 +35,12 @@
     "qrcode-generator": "^2.0.4",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@ggui-ai/live-channel": "0.7.0",
-    "@ggui-ai/gadgets": "0.7.0",
-    "@ggui-ai/design": "0.7.0",
-    "@ggui-ai/preview-a2ui": "0.7.0",
-    "@ggui-ai/protocol": "0.7.0",
-    "@ggui-ai/wire": "0.7.0"
+    "@ggui-ai/live-channel": "0.8.0",
+    "@ggui-ai/gadgets": "0.8.0",
+    "@ggui-ai/design": "0.8.0",
+    "@ggui-ai/protocol": "0.8.0",
+    "@ggui-ai/preview-a2ui": "0.8.0",
+    "@ggui-ai/wire": "0.8.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0"