@ggui-ai/mcp-server 0.8.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, 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);
   }
 }
@@ -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
@@ -431,9 +469,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 +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;
@@ -492,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],
                 },
             },
@@ -518,21 +589,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 +644,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 +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.
@@ -959,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,
                     ],
@@ -1476,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
@@ -1532,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,
         });
@@ -1563,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
@@ -1610,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) {
@@ -1797,8 +2092,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 };
 }

package/dist/mcp-endpoint-routes.d.ts

@@ -46,6 +46,22 @@ interface PerAppRouting {
     readonly pathPrefix?: string;
     readonly authorize?: (urlAppId: string, identity: AuthResult) => Promise<void>;
 }
+/**
+ * Return shape for an `errorMapper` hook — a domain error mapped onto
+ * an HTTP/JSON-RPC response triple, with optional response headers.
+ *
+ * `headers` is deliberately generic HTTP plumbing (e.g. `Retry-After`
+ * on a `503`), not a deployment-specific concept — any operator
+ * mapping a domain error to a status code that conventionally carries
+ * a header can use it.
+ */
+export interface ErrorMapperResult {
+    readonly status: number;
+    readonly code: number;
+    readonly message: string;
+    /** Response headers to set before the JSON body is written. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
 interface MountOptions {
     /** Express app to mount onto. */
     readonly app: Express;
@@ -79,11 +95,7 @@ interface MountOptions {
     /** Operator-configured issuer URL override (OAuth). */
     readonly oauthIssuerUrl?: string;
     /** Operator-supplied error → HTTP/JSON-RPC mapping hook. */
-    readonly errorMapper?: (err: unknown) => {
-        readonly status: number;
-        readonly code: number;
-        readonly message: string;
-    } | undefined;
+    readonly errorMapper?: (err: unknown) => ErrorMapperResult | undefined;
     /**
      * Per-boot `buildMcpServer` options. Assembled once by the composer
      * (every input is fixed at composition time); the handler spreads a

package/dist/mcp-endpoint-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-endpoint-routes.d.ts","sourceRoot":"","sources":["../src/mcp-endpoint-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElF,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAM7F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,sFAAsF;AACtF,UAAU,aAAa;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IACjF,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAChD,qDAAqD;IACrD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC3D,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,CACrB,GAAG,EAAE,OAAO,KACT;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC9F;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;CACjD;AAyBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA4U1D"}
+{"version":3,"file":"mcp-endpoint-routes.d.ts","sourceRoot":"","sources":["../src/mcp-endpoint-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElF,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAM7F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,sFAAsF;AACtF,UAAU,aAAa;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IACjF,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAChD,qDAAqD;IACrD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC3D,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,iBAAiB,GAAG,SAAS,CAAC;IACvE;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;CACjD;AAyBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA2U1D"}

package/dist/mcp-endpoint-routes.js

@@ -235,6 +235,8 @@ export function mountMcpEndpoints(opts) {
                     }
                 }
                 if (mapped) {
+                    if (mapped.headers)
+                        res.set(mapped.headers);
                     res.status(mapped.status).json({
                         jsonrpc: "2.0",
                         error: { code: mapped.code, message: mapped.message },