@ggui-ai/mcp-server 0.7.0 → 0.9.0

package/dist/mcp-apps-outbound.js

@@ -27,13 +27,13 @@
  *   The thin shell is static content; it depends on nothing except the
  *   MIME constant and the HTML. Keeping it next to the registration
  *   means a future refactor of the shell edits one file. The
- *   `@ggui-ai/react` package does NOT ship the shell as a separate
+ *   `@ggui-ai/mcp-apps-react` package does NOT ship the shell as a separate
  *   build target — per the design lock, the shell is served by the
  *   same `@ggui-ai/mcp-server` instance that mints the bootstrap.
  */
-import { deriveBundleOrigins, deriveContractBundle, derivePublicEnvProjection, deriveRenderMeta, filterDescriptorsToContract, findBlueprintExact, } from "@ggui-ai/mcp-server-handlers/renders";
+import { deriveBundleOrigins, deriveContractBundle, derivePublicEnvProjection, deriveRenderMeta, filterDescriptorsToContract, findBlueprintExact, spreadRenderMetaViewOntoSlice, wsOriginToHttpOrigin, } from "@ggui-ai/mcp-server-handlers/renders";
 import { RESOURCE_NOT_FOUND_MESSAGE, deriveContextDefault, isRecord, resolveAppGadgets, resourceReadErrorToJsonRpc, } from "@ggui-ai/protocol";
-import { GGUI_RENDER_RESOURCE_MIME, GGUI_RENDER_RESOURCE_URI, GGUI_RENDER_SHELL_SURFACE, MCP_APPS_UI_CAPABILITY, MCP_APP_BOOTSTRAP_FAILED_TYPE, asGguiRenderBootstrap, deriveContextName, gguiShellHtml, toMcpAppEnvelope, } from "@ggui-ai/protocol/integrations/mcp-apps";
+import { GGUI_RENDER_RESOURCE_MIME, GGUI_RENDER_RESOURCE_URI, GGUI_RENDER_SHELL_SURFACE, MCP_APPS_UI_CAPABILITY, MCP_APP_BOOTSTRAP_FAILED_TYPE, asGguiRenderBootstrap, composeSessionApiUrls, deriveContextName, escapeInlineScript, gguiShellHtml, parseEpochUri, toMcpAppEnvelope, } from "@ggui-ai/protocol/integrations/mcp-apps";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerAppResource } from "@modelcontextprotocol/ext-apps/server";
 import { createHash } from "node:crypto";
@@ -150,9 +150,39 @@ var rpcId=1,pending={};
 var rootEl=document.getElementById('ggui-root');
 rootEl.style.cssText='display:flex;flex-direction:column;height:100%;min-height:300px;margin:0';
 var mounted=false;
+var lastEnvelope=null;
+// Text color pairs with the shell surface: themed var when the runtime
+// injected theme CSS, else the light-on-dark fallback matching the
+// shell's static #1e293b pre-theme surface. The old hardcoded #666 was
+// illegible on that dark fallback (#481).
+var SHELL_FG='var(--ggui-color-onSurface,#e2e8f0)';
 function setOverlay(text){
   if(mounted)return;
-  rootEl.innerHTML='<div style="font:14px system-ui,sans-serif;padding:24px;color:#666">'+text+'</div>';
+  rootEl.innerHTML='<div style="font:13px system-ui,sans-serif;padding:24px;color:'+SHELL_FG+';opacity:.55">'+text+'</div>';
+}
+function escText(s){
+  return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');
+}
+// Terminal failure card (#481): plain-language summary, diagnostic
+// reachable but collapsed, Retry only when a retry can actually work.
+// Same visual vocabulary as the runtime's React error boundary so the
+// two error surfaces read as one system.
+function showFailure(summary,detail,retry){
+  if(mounted)return;
+  rootEl.innerHTML=''+
+    '<div style="display:flex;flex-direction:column;align-items:center;justify-content:center;gap:10px;padding:32px 24px;min-height:160px;font-family:system-ui,sans-serif;color:'+SHELL_FG+';text-align:center">'+
+      '<div style="font-size:14px;font-weight:600">'+escText(summary)+'</div>'+
+      '<div style="font-size:12px;opacity:.65;max-width:320px;line-height:1.45">The interface could not start. The conversation is unaffected — you can also just ask for the view again.</div>'+
+      (retry?'<button id="ggui-shell-retry" style="margin-top:2px;padding:7px 18px;border-radius:8px;border:1px solid currentColor;background:transparent;color:inherit;opacity:.75;font:500 13px system-ui,sans-serif;cursor:pointer">Retry</button>':'')+
+      '<details style="margin-top:6px;max-width:340px;width:100%;text-align:left;opacity:.75">'+
+        '<summary style="cursor:pointer;font-size:12px">Details</summary>'+
+        '<pre style="margin:6px 0 0;font:11px/1.5 ui-monospace,Menlo,monospace;white-space:pre-wrap;word-break:break-word">'+escText(detail)+'</pre>'+
+      '</details>'+
+    '</div>';
+  if(retry){
+    var b=document.getElementById('ggui-shell-retry');
+    if(b)b.onclick=retry;
+  }
 }
 function postNotification(method,params){
   try{window.parent.postMessage({jsonrpc:'2.0',method:method,params:params||{}},'*');}catch(e){}
@@ -183,10 +213,12 @@ async function mountFromMeta(envelope){
   var renderSlice=envelope&&envelope['ai.ggui/render'];
   var runtimeUrl=renderSlice&&renderSlice.runtimeUrl;
   if(!envelope||typeof runtimeUrl!=='string'){
-    setOverlay('Bootstrap payload malformed.');
+    // No retry: without a valid envelope there is nothing to re-run.
+    showFailure('This view could not start','MALFORMED_BOOTSTRAP: bootstrap payload malformed (no ai.ggui/render slice with a runtimeUrl).',null);
     postBootstrapFailed('MALFORMED_BOOTSTRAP','Bootstrap payload malformed.');
     return;
   }
+  lastEnvelope=envelope;
   setOverlay('Loading UI…');
   window.__GGUI_META__=envelope;
   // Load the runtime bundle via a direct cross-origin script tag
@@ -212,14 +244,14 @@ async function mountFromMeta(envelope){
     s.onload=function(){mounted=true;};
     s.onerror=function(e){
       var msg='Runtime bundle failed to load: '+(e&&e.message||'script error');
-      setOverlay(msg);
+      showFailure('This view could not load','BUNDLE_FETCH_FAILED: '+msg,function(){mountFromMeta(lastEnvelope);});
       postBootstrapFailed('BUNDLE_FETCH_FAILED',msg);
     };
     rootEl.innerHTML='';
     document.body.appendChild(s);
   }catch(e){
     var msg='Runtime bundle failed to load: '+(e&&e.message||e);
-    setOverlay(msg);
+    showFailure('This view could not load','BUNDLE_FETCH_FAILED: '+msg,function(){mountFromMeta(lastEnvelope);});
     postBootstrapFailed('BUNDLE_FETCH_FAILED',msg);
   }
 }
@@ -262,26 +294,32 @@ window.addEventListener('message',function(ev){
     // above.
   }
 });
-setOverlay('Initializing…');
-var initTimer=setTimeout(function(){
-  setOverlay('Host did not respond to ui/initialize within 3s.');
-},3000);
-postRpc('ui/initialize',{
-  appCapabilities:{},
-  appInfo:{name:'ggui-render',version:'1.0.0'},
-  protocolVersion:'2026-01-26'
-}).then(function(){
-  clearTimeout(initTimer);
-  postNotification('ui/notifications/initialized',{});
-  // Wait for the host to send ui/notifications/tool-result carrying
-  // the slice envelope in _meta — the spec-canonical delivery channel.
-  // The ui/initialize result itself carries no slice meta (the
-  // McpUiInitializeResult schema defines no such field).
-  setOverlay('Waiting for tool result…');
-}).catch(function(e){
-  clearTimeout(initTimer);
-  setOverlay('ui/initialize failed: '+(e&&e.message||JSON.stringify(e)));
-});
+// Named so the failure card's Retry can re-run the whole handshake —
+// a host that missed or rejected the first ui/initialize may answer a
+// second (observed with hosts that attach their listener late).
+function startInit(){
+  setOverlay('Initializing…');
+  var initTimer=setTimeout(function(){
+    showFailure('This view did not hear back from its host','INIT_TIMEOUT: no response to ui/initialize within 3s.',startInit);
+  },3000);
+  postRpc('ui/initialize',{
+    appCapabilities:{},
+    appInfo:{name:'ggui-render',version:'1.0.0'},
+    protocolVersion:'2026-01-26'
+  }).then(function(){
+    clearTimeout(initTimer);
+    postNotification('ui/notifications/initialized',{});
+    // Wait for the host to send ui/notifications/tool-result carrying
+    // the slice envelope in _meta — the spec-canonical delivery channel.
+    // The ui/initialize result itself carries no slice meta (the
+    // McpUiInitializeResult schema defines no such field).
+    setOverlay('Waiting for tool result…');
+  }).catch(function(e){
+    clearTimeout(initTimer);
+    showFailure('This view could not connect to its host','ui/initialize failed: '+(e&&e.message||JSON.stringify(e)),startInit);
+  });
+}
+startInit();
 })();
 `;
 // `--ggui-color-surface` is injected at `:root` on this document's
@@ -373,6 +411,77 @@ export const GGUI_RENDER_SHELL_HTML = `<!doctype html>
 export const GGUI_RENDER_SHELL_SCRIPT_HASH = `'sha256-${createHash("sha256")
     .update(GGUI_RENDER_SHELL_SCRIPT_BODY)
     .digest("base64")}'`;
+/**
+ * Bootstrap `<script>` body of the INLINE-RUNTIME shell (see
+ * {@link buildInlineRenderShellHtml}). Runs BEFORE the (large) inline
+ * runtime module parses and does exactly two things:
+ *
+ *  1. Installs the `window.__GGUI_PENDING_TOOL_RESULTS__` buffer the
+ *     iframe-runtime's autostart drains (`readPendingToolResults`
+ *     contract: an array whose elements are the RAW
+ *     `ui/notifications/tool-result` JSON-RPC `params` values, arrival
+ *     order, capped so a long-lived host session cannot grow it
+ *     unboundedly).
+ *  2. Sends the `ui/initialize` → `ui/notifications/initialized`
+ *     preflight. Load-bearing against a mutual 30s stall: spec hosts
+ *     gate tool-result delivery BEHIND the handshake, while the
+ *     runtime's autostart waits for a tool-result before its own
+ *     handshake runs. The runtime repeats `ui/initialize` when it
+ *     boots; MCP Apps hosts handle the repeat idempotently (same
+ *     preflight pattern as the thin shell above).
+ *
+ * No overlay, no meta inspection, no runtime loading — the runtime is
+ * inline in the same document and owns everything else.
+ */
+const GGUI_INLINE_SHELL_BUFFER_SCRIPT_BODY = `
+(function(){'use strict';
+var buf=window.__GGUI_PENDING_TOOL_RESULTS__=window.__GGUI_PENDING_TOOL_RESULTS__||[];
+window.addEventListener('message',function(ev){
+  var m=ev&&ev.data;
+  if(!m||m.jsonrpc!=='2.0'||m.method!=='ui/notifications/tool-result')return;
+  buf.push(m.params);
+  if(buf.length>8)buf.splice(0,buf.length-8);
+});
+try{
+  window.parent.postMessage({jsonrpc:'2.0',id:'ggui-inline-preflight',method:'ui/initialize',params:{appCapabilities:{},appInfo:{name:'ggui-render',version:'1.0.0'},protocolVersion:'2026-01-26'}},'*');
+  window.parent.postMessage({jsonrpc:'2.0',method:'ui/notifications/initialized',params:{}},'*');
+}catch(e){}
+})();
+`;
+/**
+ * Build the INLINE-RUNTIME static shell: a standalone document carrying
+ * the iframe-runtime bundle in its own bytes instead of an external
+ * `<script src>` tag. For MCP Apps hosts whose iframe CSP forbids
+ * external `script-src` while permitting inline scripts — the thin
+ * postMessage shell can never load its runtime there, so the shell IS
+ * the runtime.
+ *
+ * Per-render state does NOT live here (same posture as the thin
+ * shell): the host delivers it via `ui/notifications/tool-result`,
+ * caught either by the buffer script (pre-parse arrivals) or by the
+ * runtime's own autostart listener. Live-channel / codeUrl fetches are
+ * unavailable under the CSP this shell targets; delivered meta is
+ * expected to carry the fetch-free channels (inline `codeB64`, inline
+ * `propsJson`).
+ *
+ * Served per-mount via `installMcpAppsOutbound({ shellHtml })` — the
+ * module-level thin-shell constants (and their pinned CSP hash) are
+ * deliberately untouched.
+ */
+export function buildInlineRenderShellHtml(runtimeSource) {
+    // No anchor div: the runtime appends its own mount target to
+    // `document.body` at boot, so a thin-shell-style `#ggui-root`
+    // placeholder here would just stack empty space ABOVE the rendered
+    // card (min-height'd blank div + content below it — the "long upper
+    // space" bug from the first claude.ai live test). Same
+    // no-container posture as `gguiShellHtml`; the shell marker rides
+    // on `<body>`.
+    return `<!doctype html>
+<html lang="en" style="background-color:${GGUI_RENDER_SHELL_SURFACE}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="light dark"><title>ggui render</title></head>
+<body style="margin:0;background-color:${GGUI_RENDER_SHELL_SURFACE}" data-ggui-shell="inline">
+<script>${GGUI_INLINE_SHELL_BUFFER_SCRIPT_BODY}</script>
+<script type="module" data-ggui-runtime="inline">${escapeInlineScript(runtimeSource)}</script></body></html>`;
+}
 /**
  * Register `ui://ggui/render` as a readable resource on an `McpServer`.
  *
@@ -419,7 +528,17 @@ function buildCspMeta(publicBaseUrl,
  * references `:6786/_ggui/iframe-runtime.js`) trips a `script-src`
  * violation that blanks the iframe — verified live 2026-05-27.
  */
-runtimeUrl) {
+runtimeUrl, 
+/**
+ * Origins of server-stamped fetch/stream URLs (`sseUrl`,
+ * `pollingUrl`) — each parseable entry's origin is unioned into
+ * `connectDomains` (deduplicated). Same-origin deployments add
+ * nothing new; split-origin session APIs (dedicated streaming host)
+ * would otherwise be silently blocked by `connect-src` on
+ * spec-compliant hosts — EventSource and fetch are both
+ * connect-src-governed.
+ */
+extraConnectUrls) {
     const source = publicBaseUrl ?? runtimeUrl;
     if (!source)
         return undefined;
@@ -428,10 +547,26 @@ runtimeUrl) {
         const origin = parsed.origin;
         const wsScheme = parsed.protocol === "https:" ? "wss:" : "ws:";
         const wsOrigin = `${wsScheme}//${parsed.host}`;
+        const connectDomains = [origin, wsOrigin];
+        for (const url of extraConnectUrls ?? []) {
+            if (url === undefined)
+                continue;
+            let extraOrigin;
+            try {
+                extraOrigin = new URL(url).origin;
+            }
+            catch {
+                // Unparseable stamped URL — nothing to declare for it; the
+                // base declaration stands.
+                continue;
+            }
+            if (!connectDomains.includes(extraOrigin))
+                connectDomains.push(extraOrigin);
+        }
         return {
             ui: {
                 csp: {
-                    connectDomains: [origin, wsOrigin],
+                    connectDomains,
                     resourceDomains: [origin],
                 },
             },
@@ -441,53 +576,66 @@ runtimeUrl) {
         return undefined;
     }
 }
-export function registerGguiRenderResource(server, shellHtml = GGUI_RENDER_SHELL_HTML, publicBaseUrl) {
-    let cspMeta;
-    if (publicBaseUrl) {
-        try {
-            const parsed = new URL(publicBaseUrl);
-            const origin = parsed.origin;
-            // CSP `connect-src` does NOT cross-translate between `https://`
-            // and `wss://` — they're independent URL schemes for the
-            // browser's URL-match algorithm. Declaring ONLY the HTTPS
-            // origin will leave WebSocket subscribes (`wss://<same-host>/ws`)
-            // blocked by hosts that compose strict CSPs from this
-            // `connectDomains` list (claude.ai's iframe is the live
-            // diagnosis case). Declare BOTH schemes so the same physical
-            // origin is reachable via HTTPS (`/api/bootstrap`, `/_ggui/
-            // iframe-runtime.js`) AND wss (live-channel subscribe).
-            const wsScheme = parsed.protocol === "https:" ? "wss:" : "ws:";
-            const wsOrigin = `${wsScheme}//${parsed.host}`;
-            cspMeta = {
-                ui: {
-                    csp: {
-                        connectDomains: [origin, wsOrigin],
-                        resourceDomains: [origin],
-                    },
-                },
-            };
-        }
-        catch {
-            // Malformed `publicBaseUrl` — leave `_meta.ui.csp` off rather
-            // than emitting a broken declaration. The host falls back to its
-            // restrictive default and operators get the same observable
-            // failure they'd get from any other malformed URL setting.
-            cspMeta = undefined;
-        }
-    }
+export function registerGguiRenderResource(server, shellHtml = GGUI_RENDER_SHELL_HTML, publicBaseUrl, 
+/**
+ * Absolute runtime-bundle URL used as the CSP-declaration fallback
+ * when `publicBaseUrl` is absent — same posture as the per-render
+ * template registration ({@link buildCspMeta}'s second parameter).
+ * Deployments that publish an absolute `runtime.url` but
+ * deliberately do NOT set `publicBaseUrl` (it also feeds
+ * Origin/Host enforcement and OAuth) still get
+ * `_meta.ui.csp.{connectDomains,resourceDomains}` on the static
+ * resource read; before this fallback those reads carried no
+ * declaration at all and spec-compliant hosts applied the
+ * restrictive default (`connect-src 'none'`).
+ */
+runtimeUrl, 
+/**
+ * Additional URLs whose origins the mounted iframe must be able to
+ * `connect-src` — unioned into `connectDomains` by
+ * {@link buildCspMeta}. The load-bearing entries are the live-channel
+ * origins (`wsUrl` + its ws→http origin flip): the STATIC shell is
+ * the resource cross-origin hosts (claude.ai) mount and derive the
+ * frame CSP from, so origins declared only on per-render resources
+ * never reach the frame. Without these, deployments that set no
+ * `publicBaseUrl` (the cloud pod — it feeds Origin/Host enforcement)
+ * declare only the runtime-CDN origin and every SSE / HTTP-polling /
+ * WS rung of the failover ladder is CSP-blocked in the mounted
+ * iframe — observed live on claude.ai (#471 round 11: frame booted
+ * with `connect-src assets.mcp.ggui.ai` only).
+ */
+extraConnectUrls) {
+    const cspMeta = buildCspMeta(publicBaseUrl, runtimeUrl, extraConnectUrls);
+    // Content-addressed shell URI (2026-08-12, the stale-shell bust).
+    // Hosts cache the prefetched shell keyed on the RESOURCE URI —
+    // claude.ai's backend was observed serving days-old shell bytes
+    // across our deploys, fresh pages, and connector re-connects,
+    // because `ui://ggui/render` never changes. Hash the FULL SERVED
+    // REPRESENTATION — shell bytes (wrapper + any inlined runtime) AND
+    // the `_meta.ui.csp` declaration — into the advertised URI so any
+    // change a host may have cached mints a NEW URI, and an unchanged
+    // one never does; the same content-address discipline the hashed
+    // `/_ggui/iframe-runtime.<sha12>.js` HTTP route applies one layer
+    // down. The meta MUST be in the hash input: hosts cache the
+    // declaration alongside the bytes (claude.ai derives the frame's
+    // connect-src from it), so a meta-only change — e.g. adding the
+    // live-channel origins to `connectDomains` — would otherwise ship a
+    // new policy under an old URI and never reach cached frames. The
+    // bare URI stays registered for grandfathered sessions and hosts
+    // that read it directly.
+    const shellHash = createHash("sha256")
+        .update(shellHtml)
+        .update(JSON.stringify(cspMeta ?? null))
+        .digest("hex")
+        .slice(0, 12);
+    const versionedUri = `${GGUI_RENDER_RESOURCE_URI}/rt-${shellHash}`;
     // `registerAppResource` (from `@modelcontextprotocol/ext-apps/server`)
     // defaults `mimeType` to `RESOURCE_MIME_TYPE` — the same
     // `text/html;profile=mcp-app` value `GGUI_RENDER_RESOURCE_MIME`
     // carries. Letting the canonical helper own the default means the
     // mimeType string lives in ONE place across the ecosystem (the SDK)
     // rather than duplicated in our protocol package.
-    registerAppResource(server, "ggui-render", GGUI_RENDER_RESOURCE_URI, {
-        // `title` / `description` show up in MCP clients that surface
-        // resource metadata. Short + concrete.
-        title: "ggui render",
-        description: "Thin-shell iframe bundle that bootstraps a ggui render. MCP Apps hosts fetch this when they see `_meta.ui.resourceUri` on a ggui_render result.",
-        mimeType: GGUI_RENDER_RESOURCE_MIME,
-    }, async (uri) => ({
+    const serveShell = async (uri) => ({
         contents: [
             {
                 uri: uri.href,
@@ -496,7 +644,44 @@ export function registerGguiRenderResource(server, shellHtml = GGUI_RENDER_SHELL
                 ...(cspMeta !== undefined ? { _meta: cspMeta } : {}),
             },
         ],
-    }));
+    });
+    registerAppResource(server, "ggui-render", GGUI_RENDER_RESOURCE_URI, {
+        // `title` / `description` show up in MCP clients that surface
+        // resource metadata. Short + concrete.
+        title: "ggui render",
+        description: "Thin-shell iframe bundle that bootstraps a ggui render. MCP Apps hosts fetch this when they see `_meta.ui.resourceUri` on a ggui_render result.",
+        mimeType: GGUI_RENDER_RESOURCE_MIME,
+    }, serveShell);
+    registerAppResource(server, "ggui-render-versioned", versionedUri, {
+        title: "ggui render (content-addressed)",
+        description: "Content-addressed twin of ui://ggui/render — the URI embeds the shell-bytes hash so host prefetch caches miss exactly when the shell changed. Tool declarations advertise THIS URI.",
+        mimeType: GGUI_RENDER_RESOURCE_MIME,
+    }, serveShell);
+    // STALE-HASH grandfather template — `rt-{shellHash}` for ANY hash.
+    // Hosts snapshot tool declarations (claude.ai stores the connector's
+    // tool list server-side), so after a shell-changing deploy they keep
+    // asking for the PREVIOUS deploy's versioned URI. Without this
+    // template that read falls through to the per-session
+    // `ui://ggui/render/{sessionId}` template (a bare `rt-abc…` segment
+    // parses as a sessionId), resolves no render, and the host shows
+    // "unable to reach" — observed live on claude.ai the first deploy
+    // after the URI scheme changed (#471 round 12). Serving the CURRENT
+    // shell under the stale URI restores the pre-content-addressing
+    // behavior for stale hosts (at worst they cache today's shell under
+    // yesterday's key) while fresh declarations keep the cache-bust
+    // property. MUST register before the session templates
+    // (`installMcpAppsOutbound` orders this call first; the SDK matches
+    // templates in registration order).
+    server.registerResource("ggui-render-versioned-grandfather", new ResourceTemplate(`${GGUI_RENDER_RESOURCE_URI}/rt-{shellHash}`, {
+        // No list-callback — same posture as the session templates; the
+        // canonical URI is the one advertised on tool declarations.
+        list: undefined,
+    }), {
+        title: "ggui render (content-addressed, any revision)",
+        description: "Grandfather route for content-addressed shell URIs from earlier deploys — hosts holding a stale tool-declaration snapshot read their old rt-<hash> URI and receive the CURRENT shell.",
+        mimeType: GGUI_RENDER_RESOURCE_MIME,
+    }, serveShell);
+    return versionedUri;
 }
 /**
  * Advertise the `io.modelcontextprotocol/ui` extension capability on
@@ -549,12 +734,13 @@ export function buildSelfContainedShell(opts) {
     // picks per its priority order.
     const isSystem = typeof opts.systemKind === "string" && opts.systemKind.length > 0;
     const hasCodeUrl = typeof opts.codeUrl === "string" && opts.codeUrl.length > 0;
+    const hasCodeB64 = typeof opts.codeB64 === "string" && opts.codeB64.length > 0;
     const hasLive = typeof opts.wsUrl === "string" &&
         opts.wsUrl.length > 0 &&
         typeof opts.token === "string" &&
         opts.token.length > 0;
-    if (!isSystem && !hasCodeUrl && !hasLive) {
-        throw new Error("buildSelfContainedShell: at least one of `codeUrl`, `systemKind`, or live-mode (`wsUrl` + `token`) must be set");
+    if (!isSystem && !hasCodeUrl && !hasCodeB64 && !hasLive) {
+        throw new Error("buildSelfContainedShell: at least one of `codeUrl`, `codeB64`, `systemKind`, or live-mode (`wsUrl` + `token`) must be set");
     }
     // Build the single render slice (Phase B: ai.ggui/render collapsed
     // the prior ai.ggui/session + ai.ggui/stack-item pair into one flat
@@ -604,7 +790,11 @@ export function buildSelfContainedShell(opts) {
         // WS-only mode (legacy behavior). See SelfContainedShellInputs
         // .pollingUrl for the URL shape.
         ...(opts.pollingUrl !== undefined ? { pollingUrl: opts.pollingUrl } : {}),
+        // SSE middle rung — same stamping posture as pollingUrl. See
+        // SelfContainedShellInputs.sseUrl for the stream contract.
+        ...(opts.sseUrl !== undefined ? { sseUrl: opts.sseUrl } : {}),
         ...(opts.lastSequence !== undefined ? { lastSequence: opts.lastSequence } : {}),
+        ...(opts.epoch !== undefined ? { epoch: opts.epoch } : {}),
         // Visible-bits surface — what the iframe is mounting right now.
         // Static-content discriminators (codeUrl / kind) are mutually
         // exclusive; the iframe-runtime rejects the both-set mix.
@@ -615,6 +805,7 @@ export function buildSelfContainedShell(opts) {
                 ...(opts.codeHash !== undefined ? { codeHash: opts.codeHash } : {}),
             }
             : {}),
+        ...(!isSystem && hasCodeB64 ? { codeB64: opts.codeB64 } : {}),
         ...(opts.propsJson !== undefined ? { propsJson: opts.propsJson } : {}),
         ...(opts.contextSlots !== undefined && opts.contextSlots.length > 0
             ? { contextSlots: opts.contextSlots }
@@ -912,18 +1103,24 @@ export function registerGguiRenderResourceTemplate(server, opts) {
      * claude.ai's iframe CSP and the component fails to render. Returns
      * `undefined` when there's no base CSP at all (publicBaseUrl
      * absent — first-party same-origin host).
+     *
+     * `base` defaults to the registration-time `templateCspMeta`;
+     * `serveMount` passes a per-render base recomputed with the stamped
+     * session-API URLs (`sseUrl` / `pollingUrl`) so their origins ride
+     * `connectDomains` even when they differ from the publicBaseUrl
+     * origin (ws→http origin-flip fallback).
      */
-    const augmentCspMeta = (gadgetOrigins) => {
-        if (templateCspMeta === undefined)
+    const augmentCspMeta = (gadgetOrigins, base = templateCspMeta) => {
+        if (base === undefined)
             return undefined;
         if (gadgetOrigins === undefined)
-            return templateCspMeta;
+            return base;
         return {
             ui: {
                 csp: {
-                    connectDomains: [...templateCspMeta.ui.csp.connectDomains, ...gadgetOrigins.connect],
+                    connectDomains: [...base.ui.csp.connectDomains, ...gadgetOrigins.connect],
                     resourceDomains: [
-                        ...templateCspMeta.ui.csp.resourceDomains,
+                        ...base.ui.csp.resourceDomains,
                         ...gadgetOrigins.script,
                         ...gadgetOrigins.style,
                     ],
@@ -1429,6 +1626,20 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                 channelFault ??= { cause };
             }
         }
+        // Token-bearing session-API URL pair (pollingUrl + sseUrl) —
+        // composed via the protocol's ONE composer so this surface cannot
+        // drift from the render/update resultMeta stamping. Stamped only
+        // when the mint above produced a token (both URLs embed it); base
+        // = publicBaseUrl when configured, else the ws→http origin flip
+        // of the minted wsUrl (session API served on the WS origin — OSS
+        // defaults + the cloud pod's single ingress).
+        let sessionApiUrls;
+        if (wsToken !== undefined) {
+            const base = opts.publicBaseUrl ?? (wsUrl !== undefined ? wsOriginToHttpOrigin(wsUrl) : undefined);
+            if (base !== undefined) {
+                sessionApiUrls = composeSessionApiUrls(base, sessionId, wsToken);
+            }
+        }
         // Mount-mode gate (below the live-channel mint): a compiled
         // component needs ONE of the two channels. A deployment that wires
         // no codeStore (codeUrl === undefined) but DOES wire mintWsToken
@@ -1448,7 +1659,10 @@ export function registerGguiRenderResourceTemplate(server, opts) {
         // else produced a channel. Anywhere above this line the same fault
         // may have been survivable, and on a deployment wiring both
         // channels it usually is.
-        if (!isSystem && codeUrl === undefined && (wsUrl === undefined || wsToken === undefined)) {
+        if (!isSystem &&
+            codeUrl === undefined &&
+            view.codeB64 === undefined &&
+            (wsUrl === undefined || wsToken === undefined)) {
             if (channelFault !== undefined)
                 throw channelFault.cause;
             throw new ResourceReadFailure(NO_DELIVERY_CHANNEL_FAILURE);
@@ -1458,15 +1672,20 @@ export function registerGguiRenderResourceTemplate(server, opts) {
             appId: accessibleStored.appId,
             ...(isSystem
                 ? { systemKind: picked.kind }
-                : codeUrl !== undefined
-                    ? {
-                        codeUrl,
-                        ...(codeHash !== undefined ? { codeHash } : {}),
-                    }
-                    : // No static codeUrl → live-mode (wsUrl + token spread below)
-                        // carries the render; buildSelfContainedShell accepts
-                        // live-mode without codeUrl.
-                        {}),
+                : {
+                    ...(codeUrl !== undefined
+                        ? {
+                            codeUrl,
+                            ...(codeHash !== undefined ? { codeHash } : {}),
+                        }
+                        : {}),
+                    // Inline fetch-free channel (size-capped, projected by
+                    // `deriveRenderMeta`). Independent of the codeStore, so a
+                    // dead/unwired store still yields a mountable shell — and
+                    // hosts whose iframe CSP blocks the codeUrl fetch decode
+                    // this instead.
+                    ...(view.codeB64 !== undefined ? { codeB64: view.codeB64 } : {}),
+                }),
             runtimeUrl: opts.runtimeUrl,
             ...(wsUrl !== undefined && wsToken !== undefined
                 ? {
@@ -1477,24 +1696,23 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                 : {}),
             ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
             ...(opts.themeMode !== undefined ? { themeMode: opts.themeMode } : {}),
-            // Per-app theme overlay projected by `deriveRenderMeta` from
-            // the render's `theme` sidecar — forwarded so the
-            // resource-served iframe matches the postMessage path.
-            ...(view.theme !== undefined ? { theme: view.theme } : {}),
-            ...(view.propsJson !== undefined ? { propsJson: view.propsJson } : {}),
-            ...(view.contextSlots !== undefined ? { contextSlots: view.contextSlots } : {}),
-            ...(view.permissionsPolicy !== undefined
-                ? { permissionsPolicy: view.permissionsPolicy }
-                : {}),
-            ...(view.gadgets !== undefined && view.gadgets.length > 0
-                ? { gadgets: view.gadgets }
-                : {}),
+            // State + policy view fields (theme overlay, propsJson,
+            // contextSlots, permissionsPolicy, gadgets, #483 epoch) — ONE
+            // shared spread so the resource-served shell cannot drift from
+            // the postMessage-path emitters.
+            ...spreadRenderMetaViewOntoSlice(view),
             ...(contractHash !== undefined && validatorsUrl !== undefined
                 ? { contractHash, validatorsUrl }
                 : {}),
             ...(resourcePublicEnv !== undefined && Object.keys(resourcePublicEnv).length > 0
                 ? { publicEnv: resourcePublicEnv }
                 : {}),
+            // Token-bearing HTTP fallback rungs — present exactly when the
+            // mint above produced a token and a base resolved (see the
+            // composition above the mount-mode gate).
+            ...(sessionApiUrls !== undefined
+                ? { pollingUrl: sessionApiUrls.pollingUrl, sseUrl: sessionApiUrls.sseUrl }
+                : {}),
             // R6 — ledger cursor stamp for polling-cursor alignment.
             lastSequence: accessibleStored.eventSequence,
         });
@@ -1508,21 +1726,121 @@ export function registerGguiRenderResourceTemplate(server, opts) {
         // derives these via deriveBundleOrigins; this is the per-call
         // resource mirror.
         const gadgetOrigins = deriveBundleOrigins(picked.source);
-        return shellContents(uri, html, augmentCspMeta(gadgetOrigins));
+        // Per-render CSP base: recompute with the stamped session-API
+        // URLs so their origins ride `connectDomains` (EventSource +
+        // fetch are connect-src-governed). Same-origin stamps dedupe to
+        // the registration-time declaration; a base derived from the
+        // wsUrl origin flip (publicBaseUrl absent) adds the flip origin
+        // that would otherwise be silently blocked.
+        const renderCspBase = sessionApiUrls !== undefined
+            ? buildCspMeta(opts.publicBaseUrl, opts.runtimeUrl, [
+                sessionApiUrls.sseUrl,
+                sessionApiUrls.pollingUrl,
+            ])
+            : templateCspMeta;
+        return shellContents(uri, html, augmentCspMeta(gadgetOrigins, renderCspBase));
+    }
+    /**
+     * Reconstruct the props of history record `#epoch` from the event
+     * ledger (#483): walk ascending, apply every `ui.updated`, and stop
+     * at the `ui.reminted` boundary that LEAVES the pinned epoch
+     * (`data.epoch === epoch + 1`) — so the record includes the amends
+     * made during its reign, matching the live freeze semantics
+     * (state-at-supersession). Returns `null` when the walk cannot reach
+     * the boundary (ledger horizon evicted the record's reign) — the
+     * caller surfaces the standard not-found posture; the record aged
+     * out of what this server can serve.
+     */
+    async function reconstructPropsAtEpoch(sessionId, epoch) {
+        let since = 0;
+        let currentProps = null;
+        for (;;) {
+            const page = await opts.renderStore.listEventsSince(sessionId, since, 200);
+            if (page === null || page.events.length === 0)
+                return null;
+            for (const event of page.events) {
+                if (event.type === "ui.updated") {
+                    const data = event.data;
+                    // Epoch-stamped filtering: the update that MINTS epoch N+1
+                    // appends its props event (stamped N+1) BEFORE the N+1
+                    // boundary — those props belong to the NEXT record, never
+                    // to #N. Pre-#483 events carry no stamp and read as
+                    // belonging to the then-current (≤ pinned) epoch.
+                    if ((data.epoch ?? 0) <= epoch) {
+                        currentProps = data.props;
+                    }
+                }
+                else if (event.type === "ui.reminted") {
+                    const data = event.data;
+                    if (data.epoch === epoch + 1)
+                        return currentProps;
+                }
+                since = event.seq;
+            }
+            if (!page.hasMore && page.lastSequence <= since)
+                return null;
+        }
     }
     // Single shared handler powers both templates. `blueprintKey` is
     // optional in the variables map — present for the resume URI shape,
     // absent for the legacy single-segment shape.
     async function handle(uri, variables) {
         const sessionIdRaw = variables["sessionId"];
-        const sessionId = Array.isArray(sessionIdRaw) ? sessionIdRaw[0] : sessionIdRaw;
+        let sessionId = Array.isArray(sessionIdRaw) ? sessionIdRaw[0] : sessionIdRaw;
+        const blueprintKeyRaw = variables["blueprintKey"];
+        let blueprintKey = Array.isArray(blueprintKeyRaw) ? blueprintKeyRaw[0] : blueprintKeyRaw;
+        // Epoch pin (#483): `…#N` names the immutable history record N;
+        // bare names the live head. Depending on the transport's URL
+        // handling the pin may arrive as `uri.hash`, glued RAW onto the
+        // last matched variable, or PERCENT-ENCODED inside it (`%23N`) —
+        // resolve all three tolerantly via the one seam, cleaning the
+        // variable either way.
+        const parsePin = (segment) => {
+            const direct = parseEpochUri(segment);
+            if (direct.epoch !== undefined) {
+                return { base: direct.baseUri, epoch: direct.epoch };
+            }
+            try {
+                const decoded = decodeURIComponent(segment);
+                if (decoded !== segment) {
+                    const parsed = parseEpochUri(decoded);
+                    if (parsed.epoch !== undefined) {
+                        return { base: parsed.baseUri, epoch: parsed.epoch };
+                    }
+                }
+            }
+            catch {
+                // Malformed percent-encoding — not a pin; segment passes
+                // through whole (same tolerant posture as parseEpochUri).
+            }
+            return { base: segment };
+        };
+        // ALWAYS clean the variables (transports have been observed to
+        // deliver the pin BOTH as uri.hash and glued raw onto the matched
+        // variable); the pin resolves from whichever source carried it.
+        let pinnedEpoch;
+        if (uri.hash.length > 1) {
+            pinnedEpoch = parseEpochUri(`x${uri.hash}`).epoch;
+        }
+        if (typeof blueprintKey === "string") {
+            const parsed = parsePin(blueprintKey);
+            if (parsed.epoch !== undefined) {
+                pinnedEpoch = pinnedEpoch ?? parsed.epoch;
+                blueprintKey = parsed.base;
+            }
+        }
+        if (typeof sessionId === "string") {
+            const parsed = parsePin(sessionId);
+            if (parsed.epoch !== undefined) {
+                pinnedEpoch = pinnedEpoch ?? parsed.epoch;
+                sessionId = parsed.base;
+            }
+        }
         if (typeof sessionId !== "string" || sessionId.length === 0) {
             // A URI with no session segment names no locator, which is the
             // same thing as naming one that does not exist.
             throw new ResourceReadFailure(NOT_FOUND_FAILURE);
         }
-        const blueprintKeyRaw = variables["blueprintKey"];
-        const blueprintKey = Array.isArray(blueprintKeyRaw) ? blueprintKeyRaw[0] : blueprintKeyRaw;
         const hasResumeKey = typeof blueprintKey === "string" && blueprintKey.length > 0;
         // The failure this read ends in if nothing mounts. Seeded from a
         // property of the SERVER, never of the locator, so a caller cannot
@@ -1555,6 +1873,38 @@ export function registerGguiRenderResourceTemplate(server, opts) {
             })
             ? stored
             : null;
+        // Pinned history read (#483): `#N` where N is a SUPERSEDED epoch
+        // reconstructs that record's props from the ledger and serves a
+        // shell frozen at them. N === head falls through to the live
+        // mount (the pinned URI of the current head IS the head); N >
+        // head names a record that does not exist.
+        if (accessibleStored && pinnedEpoch !== undefined) {
+            const headEpoch = accessibleStored.render.epoch ?? 0;
+            if (pinnedEpoch > headEpoch) {
+                throw new ResourceReadFailure(NOT_FOUND_FAILURE);
+            }
+            if (pinnedEpoch < headEpoch && accessibleStored.render.type !== "mcpApps") {
+                const historicalProps = await reconstructPropsAtEpoch(sessionId, pinnedEpoch);
+                if (historicalProps === null) {
+                    // The record's reign aged out of the ledger horizon — this
+                    // server can no longer serve it. Same terminal posture as a
+                    // locator that never existed (see #483 SPEC note).
+                    throw new ResourceReadFailure(failure);
+                }
+                const pinnedRow = {
+                    ...accessibleStored,
+                    render: {
+                        ...accessibleStored.render,
+                        props: historicalProps,
+                        epoch: pinnedEpoch,
+                    },
+                };
+                const served = await serveMount(uri, sessionId, pinnedRow);
+                if (served !== null)
+                    return served;
+                throw new ResourceReadFailure(failure);
+            }
+        }
         // Live state first: render present and renderable mounts with the
         // current props + current contextSpec values.
         if (accessibleStored) {
@@ -1738,8 +2088,13 @@ function deriveDefaultContextSlots(spec) {
  */
 export function installMcpAppsOutbound(server, opts = {}) {
     advertiseMcpAppsUiCapability(server);
-    registerGguiRenderResource(server, opts.shellHtml, opts.publicBaseUrl);
+    // The self-contained template's absolute runtimeUrl doubles as the
+    // static registration's CSP-declaration fallback — deployments that
+    // set no `publicBaseUrl` (it also feeds Origin/Host enforcement +
+    // OAuth) still declare their origin to spec-compliant hosts.
+    const shellResourceUri = registerGguiRenderResource(server, opts.shellHtml, opts.publicBaseUrl, opts.selfContained?.runtimeUrl, opts.extraConnectUrls);
     if (opts.selfContained) {
         registerGguiRenderResourceTemplate(server, opts.selfContained);
     }
+    return { shellResourceUri };
 }