@ggui-ai/mcp-server 0.8.0 → 0.10.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, resolveSliceTheme, 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, escapeInlineScript, 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);
   }
 }
@@ -255,33 +287,92 @@ window.addEventListener('message',function(ev){
     // at the top level.
     var specMeta=readMetaFromCallToolResult(m.params);
     if(specMeta){mountFromMeta(specMeta);return;}
-    // R5 (2026-05-26) -- the /r/<shortCode> HTTP fallback was removed
-    // along with the bearer-by-obscurity model. Hosts that strip
-    // _meta on the tool-result wire have no fallback path here;
-    // spec-canonical hosts deliver meta inline and land in the branch
-    // above.
+    // Read-plane door (ggui#537). A server running the read-plane-only
+    // posture publishes only the view's IDENTITY on the result -- the
+    // ui:// locator on structuredContent.resourceUri and the spec
+    // pointer _meta.ui.resourceUri -- and no bootstrap material. The
+    // per-render resource that locator names is the self-contained
+    // shell, whose document inlines the very envelope this shell needs;
+    // ask the HOST to read it (resources/read, proxied by the host's
+    // own MCP client -- no fetch from this sandbox, so a host CSP with
+    // no connect-src to the server is not in the way). R5 (2026-05-26)
+    // removed the /r/<shortCode> HTTP fallback with the bearer-by-
+    // obscurity model; this door is the spec-canonical replacement.
+    var locator=readLocatorFromCallToolResult(m.params);
+    if(locator){mountFromLocator(locator);return;}
   }
 });
-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)));
-});
+function readLocatorFromCallToolResult(params){
+  if(!params||typeof params!=='object')return null;
+  var sc=params.structuredContent, meta=params._meta, uri=null;
+  if(sc&&typeof sc==='object'&&typeof sc.resourceUri==='string')uri=sc.resourceUri;
+  else if(meta&&typeof meta==='object'&&meta.ui&&typeof meta.ui==='object'&&typeof meta.ui.resourceUri==='string')uri=meta.ui.resourceUri;
+  if(!uri||uri.indexOf('ui://ggui/render/')!==0)return null;
+  return uri;
+}
+function envelopeFromResourceDoc(text){
+  // The per-render self-contained shell inlines its envelope on ONE
+  // line inside its meta script tag: globalThis.__GGUI_META__ = {...};
+  // (protocol gguiShellHtml). The JSON is angle-bracket-escaped by the
+  // assembler, so the first ';' followed by the closing script tag
+  // after the marker is the terminator.
+  if(typeof text!=='string')return null;
+  var marker='globalThis.__GGUI_META__ = ';
+  var start=text.indexOf(marker);
+  if(start<0)return null;
+  start+=marker.length;
+  var end=text.indexOf(';<'+'/script>',start);
+  if(end<0)return null;
+  try{var env=JSON.parse(text.slice(start,end));}catch(e){return null;}
+  return (env&&typeof env==='object'&&env['ai.ggui/render']&&typeof env['ai.ggui/render'].runtimeUrl==='string')?env:null;
+}
+async function mountFromLocator(uri){
+  if(mounted)return;
+  setOverlay('Resolving view…');
+  var res;
+  try{res=await postRpc('resources/read',{uri:uri});}
+  catch(e){
+    var rmsg='READ_DOOR_FAILED: the host could not read '+uri+' -- '+(e&&e.message||JSON.stringify(e));
+    showFailure('This view could not be resolved',rmsg,function(){mountFromLocator(uri);});
+    postBootstrapFailed('MALFORMED_BOOTSTRAP',rmsg);
+    return;
+  }
+  var c=res&&res.contents&&res.contents[0];
+  var env=envelopeFromResourceDoc(c&&c.text);
+  if(!env){
+    var emsg='MALFORMED_BOOTSTRAP: resource '+uri+' carried no ai.ggui/render envelope with a runtimeUrl.';
+    showFailure('This view could not start',emsg,function(){mountFromLocator(uri);});
+    postBootstrapFailed('MALFORMED_BOOTSTRAP',emsg);
+    return;
+  }
+  mountFromMeta(env);
+}
+// 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
@@ -313,10 +404,15 @@ postRpc('ui/initialize',{
 // diverged. Painting the served document's own surface here removes the
 // dependency on a browser honoring iframe transparency.
 //
-// Value-resolution only — no `--ggui-*` token added or renamed. The
-// constant itself lives with the protocol host-helper (the shared
-// self-contained-shell assembler paints the same surface); imported
-// above and reused here for the thin postMessage shell.
+// The paint is inline, so no stylesheet `background` rule can undo
+// it — which is why the constant's `var()` chain opens with the
+// `--ggui-shell-background` override point: content that KNOWS its
+// host composites behind the document (the runtime's system-card
+// layer inside Claude) sets that property from its stylesheet and
+// the inline value re-resolves to transparent in place. See
+// `GGUI_RENDER_SHELL_SURFACE` in the protocol host-helper (the
+// shared self-contained-shell assembler paints the same surface);
+// imported above and reused here for the thin postMessage shell.
 // `#ggui-root` here is LOAD-BEARING for the shell script (NOT a React
 // mount target): the inline script grabs it as `rootEl` for the
 // pre-mount overlays ("Initializing…", "Waiting for tool result…",
@@ -431,9 +527,16 @@ try{
  * 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="height:100%;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;height:100%;min-height:480px;background-color:${GGUI_RENDER_SHELL_SURFACE}"><div id="ggui-root" data-ggui-shell="inline" style="height:100%;min-height:480px"></div>
+<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>`;
 }
@@ -483,7 +586,19 @@ 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 connect URLs (`wsUrl`, `sseUrl`,
+ * `pollingUrl`) — each parseable entry's origin is unioned into
+ * `connectDomains` (deduplicated), scheme preserved (`ws`/`wss` are
+ * WHATWG special schemes, so a `wss://` entry contributes its
+ * `wss://` origin). Same-origin deployments add nothing new;
+ * split-origin live channels or session APIs would otherwise be
+ * silently blocked by `connect-src` on spec-compliant hosts —
+ * WebSocket, EventSource, and fetch are all connect-src-governed,
+ * and the base's ws-twin flip only covers the base's own host.
+ */
+extraConnectUrls) {
     const source = publicBaseUrl ?? runtimeUrl;
     if (!source)
         return undefined;
@@ -492,10 +607,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],
                 },
             },
@@ -518,21 +649,53 @@ export function registerGguiRenderResource(server, shellHtml = GGUI_RENDER_SHELL
  * declaration at all and spec-compliant hosts applied the
  * restrictive default (`connect-src 'none'`).
  */
-runtimeUrl) {
-    const cspMeta = buildCspMeta(publicBaseUrl, runtimeUrl);
+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,
@@ -541,7 +704,44 @@ runtimeUrl) {
                 ...(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
@@ -650,7 +850,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.
@@ -661,6 +865,11 @@ export function buildSelfContainedShell(opts) {
                 ...(opts.codeHash !== undefined ? { codeHash: opts.codeHash } : {}),
             }
             : {}),
+        // Strict-CSP module-variant twin — only WITH a raw static carrier
+        // (the protocol parser drops it otherwise).
+        ...(!isSystem && (hasCodeUrl || hasCodeB64) && opts.codeModuleUrl !== undefined
+            ? { codeModuleUrl: opts.codeModuleUrl }
+            : {}),
         ...(!isSystem && hasCodeB64 ? { codeB64: opts.codeB64 } : {}),
         ...(opts.propsJson !== undefined ? { propsJson: opts.propsJson } : {}),
         ...(opts.contextSlots !== undefined && opts.contextSlots.length > 0
@@ -692,7 +901,12 @@ export function buildSelfContainedShell(opts) {
     // standalone served iframe (claude.ai per-render resource shells,
     // `/r/<shortCode>`), never inlined into a host page — so it paints
     // its own theme-surface backdrop. See `GguiShellHtmlOptions` for the
-    // Safari white-canvas rationale.
+    // Safari white-canvas rationale. System-kind renders keep this
+    // posture too: the surface paint resolves through the
+    // `--ggui-shell-background` override point, so the card layer —
+    // the only layer that can detect a compositing host at runtime —
+    // drops the backdrop to transparent itself where that is right,
+    // and every other context keeps the per-browser-consistent paint.
     return gguiShellHtml(bootstrap, { background: "surface" });
 }
 /**
@@ -959,18 +1173,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,
                     ],
@@ -1389,6 +1609,7 @@ export function registerGguiRenderResourceTemplate(server, opts) {
         // the mount.
         let codeUrl;
         let codeHash;
+        let codeModuleUrl;
         let contractHash;
         let validatorsUrl;
         if (!isSystem && opts.codeStore && opts.codeBaseUrl) {
@@ -1398,6 +1619,13 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                 codeHash = hash;
                 const base = opts.codeBaseUrl.replace(/\/$/, "");
                 codeUrl = `${base}/code/${hash}.js`;
+                // Strict-CSP module-variant twin (ggui#522 slice 2) — a
+                // decline (`undefined`) just means the blob ladder carries it.
+                codeModuleUrl = opts.mintCodeModuleUrl?.({
+                    code: picked.componentCode,
+                    hash,
+                    base,
+                });
             }
             catch (cause) {
                 channelFault ??= { cause };
@@ -1476,6 +1704,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
@@ -1513,6 +1755,7 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                         ? {
                             codeUrl,
                             ...(codeHash !== undefined ? { codeHash } : {}),
+                            ...(codeModuleUrl !== undefined ? { codeModuleUrl } : {}),
                         }
                         : {}),
                     // Inline fetch-free channel (size-capped, projected by
@@ -1530,26 +1773,34 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                     ...(wsExpiresAt !== undefined ? { expiresAt: wsExpiresAt } : {}),
                 }
                 : {}),
-            ...(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 }
-                : {}),
+            // Layered theme — the SAME resolver the tool-result slice uses
+            // (live pick > per-render override on this render > static
+            // ggui.json), so a `ggui_render({ themeId })` override survives a
+            // mount-by-read (ggui#539). The picked source IS the committed
+            // render, so its `themeId` is the override the emitter read at
+            // commit time — component variant only, exactly the emitter's
+            // own narrowing (render.ts resultMeta): mcpApps / system renders
+            // carry no user-facing theme. Keys stay absent when unresolved.
+            ...resolveSliceTheme(opts, picked.source.type !== "mcpApps" && picked.source.type !== "system"
+                ? picked.source.themeId
+                : undefined),
+            // 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,
         });
@@ -1563,21 +1814,128 @@ 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 live-channel +
+        // session-API URLs so their origins ride `connectDomains`
+        // (WebSocket, EventSource, and fetch are all connect-src-governed).
+        // The stamped `wsUrl` MUST be its own entry: CSP never
+        // cross-translates `https://` ↔ `wss://`, and the base's ws-twin
+        // flip only covers deployments whose base origin IS the ws host —
+        // when `publicBaseUrl` is absent and the runtime bundle lives on
+        // an assets CDN origin, the flip declares the CDN's wss twin while
+        // the actual socket host goes undeclared and the live channel dies
+        // in the mounted iframe (#479, observed as the cloud-render
+        // capstone's CSP block). Same-origin stamps dedupe to the
+        // registration-time declaration.
+        const renderCspBase = sessionApiUrls !== undefined || wsUrl !== undefined
+            ? buildCspMeta(opts.publicBaseUrl, opts.runtimeUrl, [
+                wsUrl,
+                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
@@ -1610,6 +1968,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) {
@@ -1669,8 +2059,10 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                 appId: opts.defaultAppIdFallback,
                 blueprint,
                 runtimeUrl: opts.runtimeUrl,
-                ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
-                ...(opts.themeMode !== undefined ? { themeMode: opts.themeMode } : {}),
+                // No render row exists on this branch, so there is no
+                // per-render override to honor — but the live pick still beats
+                // the static preset, same resolver as every other shell.
+                ...resolveSliceTheme(opts, undefined),
                 ...(opts.codeStore !== undefined ? { codeStore: opts.codeStore } : {}),
                 ...(opts.codeBaseUrl !== undefined ? { codeBaseUrl: opts.codeBaseUrl } : {}),
             });
@@ -1797,8 +2189,9 @@ export function installMcpAppsOutbound(server, opts = {}) {
     // 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.
-    registerGguiRenderResource(server, opts.shellHtml, opts.publicBaseUrl, opts.selfContained?.runtimeUrl);
+    const shellResourceUri = registerGguiRenderResource(server, opts.shellHtml, opts.publicBaseUrl, opts.selfContained?.runtimeUrl, opts.extraConnectUrls);
     if (opts.selfContained) {
         registerGguiRenderResourceTemplate(server, opts.selfContained);
     }
+    return { shellResourceUri };
 }