@ggui-ai/mcp-server 0.1.0-rc.1

package/dist/mcp-apps-outbound.js

@@ -0,0 +1,1163 @@
+/**
+ * MCP Apps outbound wiring — the server-side half of the
+ * `ggui_push -> ui://ggui/session -> iframe -> live channel` delivery path.
+ *
+ * Responsibilities of this module (and nothing else):
+ *
+ *   1. Advertise the `io.modelcontextprotocol/ui` capability on every
+ *      fresh `McpServer` instance so MCP Apps hosts know the server
+ *      speaks the UI extension.
+ *   2. Register `ui://ggui/session` as a static resource servable via
+ *      MCP `resources/read`. The resource body is the thin-shell HTML
+ *      hosts sandbox-render when they see `_meta.ui.resourceUri` on a
+ *      `ggui_push` result.
+ *
+ * Boundary discipline:
+ *
+ *   - This module imports from `@ggui-ai/protocol/integrations/mcp-apps`
+ *     (the subpath). It does NOT expose MCP-Apps-specific shapes back
+ *     into `build-mcp.ts`, `server.ts`, or the blueprint handlers.
+ *   - Capability advertisement and resource registration are the ONLY
+ *     server-wide concerns here. Bootstrap-token mint + live-channel
+ *     bootstrap-auth live in separate slices of the same overall
+ *     outbound path.
+ *
+ * Why the shell body lives here:
+ *
+ *   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
+ *   build target — per the design lock, the shell is served by the
+ *   same `@ggui-ai/mcp-server` instance that mints the bootstrap.
+ */
+import { createHash } from 'node:crypto';
+import { ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { deriveContextDefault, } from '@ggui-ai/protocol';
+import { deriveStackItemBootstrapView, derivePublicEnvProjection, deriveBundleOrigins, findBlueprintExact, } from '@ggui-ai/mcp-server-handlers/session-mutations';
+import { MCP_APPS_UI_CAPABILITY, GGUI_SESSION_RESOURCE_URI, GGUI_SESSION_RESOURCE_MIME, deriveContextName, } from '@ggui-ai/protocol/integrations/mcp-apps';
+/**
+ * Thin-shell body served from `ui://ggui/session` (C8 pivot).
+ *
+ * **Architectural role.** The shell is a ~30 LOC bootstrap wrapper -
+ * it runs a minimal `ui/initialize` preflight to read
+ * `_meta.ggui.bootstrap.runtimeUrl`, then dynamic-script-loads the
+ * `@ggui-ai/iframe-runtime` bundle from that URL. Every rendering
+ * concern - WS open, subscribe, stack render, component code eval,
+ * adapter install - belongs to the renderer bundle (shipped C7a-d),
+ * not here.
+ *
+ * **Why bootstrap-driven URL.** `srcdoc` iframes have `about:srcdoc`
+ * as their URL, so relative paths can't resolve to the MCP server's
+ * HTTP listener. The server-controlled `runtimeUrl` lands on
+ * `_meta.ggui.bootstrap.runtimeUrl` and the shell picks it up from
+ * the first `ui/initialize` response - origin-agnostic, works under
+ * OSS same-origin AND hosted-cloud CDN deployments.
+ *
+ * **Why `<script type="module">`.** `@ggui-ai/iframe-runtime` is bundled as
+ * ESM (its own runtime.ts:5 declares the contract: "the thin-shell
+ * HTML loads it via `<script type="module" src=".../renderer.js">`").
+ * Loading the bundle as a classic `<script src=...>` throws
+ * `SyntaxError: Unexpected token 'export'` synchronously when the
+ * browser parses the bundle - the renderer never executes, the
+ * lifecycle never advances past `mounting`, and any host-side spec
+ * pinning `data-ggui-mcp-app-iframe-lifecycle="code-ready"` hangs
+ * to timeout. The shell honours the renderer's published contract by
+ * setting `s.type='module'` before assigning `s.src`.
+ *
+ * **Failure envelope (C8 Deliverable 4).** Pre-renderer failures
+ * surface to the parent via
+ * `postMessage({type:'ggui:bootstrap-failed', reason, message}, '*')`:
+ *
+ *   - `BOOTSTRAP_META_MISSING` - `ui/initialize` returned without a
+ *     valid `_meta.ggui.bootstrap` OR without a `runtimeUrl` field.
+ *   - `BUNDLE_FETCH_FAILED` - `<script src>` errored (network failure,
+ *     404, CSP reject with an observable `error` event).
+ *
+ * Post-renderer failures (WS handshake / auth / session-mismatch) are
+ * the renderer bundle's responsibility - `runtime.ts::postBootFailure`
+ * emits the same `ggui:bootstrap-failed` envelope AND, for post-WS-open
+ * failures, a `_ggui:contract-error` envelope on the live channel per
+ * `ContractErrorCode` additions (C8 Commit 1/3).
+ *
+ * **Adapter boundary unchanged.** The preflight's `message` listener
+ * routes ONLY responses to its own pending JSON-RPC ids. MCP Apps
+ * lifecycle notifications from the host (`ui/notifications/message`,
+ * `ui/update-model-context`) are dropped. This mirrors the pre-C8
+ * posture - the shell still MUST NOT mutate session state from
+ * arbitrary host messages. ADAPTER BOUNDARY enforced by the
+ * `pending[m.id]` route-by-id check.
+ *
+ * **Double `ui/initialize` is intentional.** The shell runs a minimal
+ * preflight solely to fetch `runtimeUrl`; the renderer bundle's
+ * autostart path runs its own `ui/initialize` for the full bootstrap
+ * parse. MCP Apps hosts handle repeats idempotently - the preflight's
+ * cost is a single postMessage round-trip.
+ *
+ * Exported as a string constant for tests; not part of the public
+ * package API. Vanilla JS, no build step, no external deps. The shell
+ * must work in any browser that implements MCP Apps; no modern-ES
+ * features.
+ */
+/**
+ * Inline body of the thin shell's bootstrap `<script>` block.
+ *
+ * Split from {@link GGUI_SESSION_SHELL_HTML} so the exact bytes the
+ * browser sees inside the `<script>...</script>` tag are addressable
+ * for CSP-hash purposes — see {@link GGUI_SESSION_SHELL_SCRIPT_HASH}.
+ *
+ * The browser's CSP `'sha256-...'` source-expression is computed over
+ * the literal text content of the `<script>` element (everything
+ * between the opening and closing tags, including leading and trailing
+ * whitespace inside). Concatenating this constant unchanged into the
+ * shell HTML means the runtime hash and the constant-time hash agree.
+ *
+ * NEVER mutate this constant without also bumping
+ * {@link GGUI_SESSION_SHELL_SCRIPT_HASH} — the
+ * `mcp-apps-outbound.test.ts` drift test recomputes the hash and fails
+ * loudly if they diverge.
+ */
+const GGUI_SESSION_SHELL_SCRIPT_BODY = `
+(function(){'use strict';
+// MCP Apps shell. Speaks the canonical postMessage protocol from
+// @modelcontextprotocol/ext-apps:
+//   1. iframe -> host: ui/initialize
+//   2. iframe -> host: ui/notifications/initialized
+//   3. host -> iframe: ui/notifications/tool-result (per CallToolResult)
+// On tool-result, derive base URL + shortCode from structuredContent,
+// fetch JSON bootstrap (componentCode + ids + runtimeUrl), set
+// window.__GGUI_BOOTSTRAP__, fetch runtime as blob, inject as script.
+// Runtime auto-mounts inline. No nested iframe (claudemcpcontent.com
+// CSP frame-src forbids cross-origin frames). State machine matches
+// buildSelfContainedShell so the same runtime mounts both paths.
+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;
+function setOverlay(text){
+  if(mounted)return;
+  rootEl.innerHTML='<div style="font:14px system-ui,sans-serif;padding:24px;color:#666">'+text+'</div>';
+}
+function postNotification(method,params){
+  try{window.parent.postMessage({jsonrpc:'2.0',method:method,params:params||{}},'*');}catch(e){}
+}
+function postRpc(method,params){
+  return new Promise(function(res,rej){
+    var id=rpcId++;pending[id]={res:res,rej:rej};
+    try{window.parent.postMessage({jsonrpc:'2.0',id:id,method:method,params:params||{}},'*');}
+    catch(e){delete pending[id];rej(e);}
+  });
+}
+function readToolResult(p){
+  if(!p)return null;
+  var sc=p.structuredContent;
+  if(sc&&typeof sc.url==='string'&&typeof sc.shortCode==='string'){
+    return {url:sc.url,shortCode:sc.shortCode};
+  }
+  if(Array.isArray(p.content)){
+    for(var i=0;i<p.content.length;i++){
+      var c=p.content[i];
+      if(c&&c.type==='text'&&typeof c.text==='string'){
+        try{var j=JSON.parse(c.text);
+          if(j&&typeof j.url==='string'&&typeof j.shortCode==='string'){
+            return {url:j.url,shortCode:j.shortCode};
+          }
+        }catch(e){}
+      }
+    }
+  }
+  return null;
+}
+function deriveBase(url){
+  try{var u=new URL(url);return u.origin;}catch(e){return null;}
+}
+function postBootstrapFailed(reason,message){
+  // Surface every shell-layer bootstrap-failure path as a typed
+  // RendererBootFailedMessage envelope so hosts pinning the C9
+  // error pane (McpAppIframe onError, IframeErrorPane) see the
+  // failure instead of staring at the inert overlay until the test
+  // times out. Reason codes match BootstrapFailureReason.
+  try{window.parent.postMessage({type:'ggui:bootstrap-failed',reason:reason,message:message},'*');}catch(e){}
+}
+async function mountFromBootstrap(bootstrap){
+  if(mounted)return;
+  // runtimeUrl is the only load-bearing field at the shell layer —
+  // it tells us which iframe-runtime bundle to fetch. componentCode
+  // is OPTIONAL: present in self-contained-mode bootstraps (the
+  // runtime renders the inlined code without WS), absent in
+  // GguiBootstrapMeta-shaped bootstraps (the runtime opens the WS
+  // subscription via wsUrl+token to receive the stack). Either is
+  // valid; the runtime decides at boot time. Rejecting on missing
+  // componentCode silently breaks every Path B GguiBootstrapMeta
+  // delivery, which is the whole point of the inline-bootstrap path.
+  if(!bootstrap||typeof bootstrap.runtimeUrl!=='string'){
+    setOverlay('Bootstrap payload malformed.');
+    postBootstrapFailed('BOOTSTRAP_MALFORMED','Bootstrap payload malformed.');
+    return;
+  }
+  setOverlay('Loading UI…');
+  window.__GGUI_BOOTSTRAP__=bootstrap;
+  // Load the runtime bundle via a direct cross-origin script tag
+  // (governed by CSP script-src) instead of fetch + Blob (governed by
+  // CSP connect-src). claude.ai's claudemcpcontent.com iframe CSP
+  // forbids cross-origin connect-src so fetch throws TypeError
+  // 'Failed to fetch', but allows cross-origin script-src when the
+  // bundle responds with the right CORS headers (the iframe-runtime
+  // mount sets them). The self-contained shell already uses this
+  // pattern; legacy postMessage shell now matches it.
+  try{
+    var s=document.createElement('script');
+    s.type='module';
+    // crossorigin=anonymous opts into CORS-mode error reporting.
+    // Without it, cross-origin script tags get a sanitized
+    // "script error" with no details, masking the real cause
+    // (CSP block, CORS reject, module-evaluation throw). With it,
+    // the error event surfaces the actual message in the iframe
+    // console -- the bundle ships ACAO=* so credentialed mode is
+    // unnecessary.
+    s.crossOrigin='anonymous';
+    s.src=bootstrap.runtimeUrl;
+    s.onload=function(){mounted=true;};
+    s.onerror=function(e){
+      var msg='Runtime bundle failed to load: '+(e&&e.message||'script error');
+      setOverlay(msg);
+      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);
+    postBootstrapFailed('BUNDLE_FETCH_FAILED',msg);
+  }
+}
+async function mount(toolResult){
+  if(mounted)return;
+  var base=deriveBase(toolResult.url);
+  if(!base){setOverlay('Invalid URL in tool result.');return;}
+  setOverlay('Loading UI…');
+  var bootstrap;
+  try{
+    var bRes=await fetch(base+'/api/bootstrap/'+encodeURIComponent(toolResult.shortCode),{
+      cache:'no-store',
+      headers:{accept:'application/json'},
+    });
+    if(!bRes.ok){setOverlay('Bootstrap fetch failed: HTTP '+bRes.status);return;}
+    bootstrap=await bRes.json();
+  }catch(e){setOverlay('Bootstrap fetch error: '+(e&&e.message||e));return;}
+  return mountFromBootstrap(bootstrap);
+}
+function readBootstrapFromInitResult(result){
+  if(!result||typeof result!=='object')return null;
+  var toolOutput=result.toolOutput;
+  if(!toolOutput||typeof toolOutput!=='object')return null;
+  var meta=toolOutput._meta;
+  if(!meta||typeof meta!=='object')return null;
+  var ggui=meta.ggui;
+  if(!ggui||typeof ggui!=='object')return null;
+  var b=ggui.bootstrap;
+  if(!b||typeof b!=='object')return null;
+  // Same loosening as mountFromBootstrap: only runtimeUrl is required
+  // here. GguiBootstrapMeta forwarded by first-party McpAppIframe
+  // hosts omits componentCode by design (the runtime fetches the
+  // stack via
+  // wsUrl+token). Requiring componentCode at the shell layer turned
+  // every Path B inline-bootstrap delivery into a silent reject.
+  if(typeof b.runtimeUrl!=='string')return null;
+  return b;
+}
+function hasGguiMetaPlaceholder(result){
+  // Detect the protocol-violation case where the host signaled
+  // "I tried to deliver bootstrap" (toolOutput._meta.ggui exists)
+  // but the bootstrap field itself is absent or malformed. In that
+  // shape, we fail-fast with BOOTSTRAP_META_MISSING rather than
+  // sitting in the Path-A waiting state forever.
+  if(!result||typeof result!=='object')return false;
+  var toolOutput=result.toolOutput;
+  if(!toolOutput||typeof toolOutput!=='object')return false;
+  var meta=toolOutput._meta;
+  if(!meta||typeof meta!=='object')return false;
+  var ggui=meta.ggui;
+  return !!ggui&&typeof ggui==='object';
+}
+function readBootstrapFromCallToolResult(params){
+  // MCP Apps spec (specification/2026-01-26/apps.mdx:1145-1155):
+  //   ui/notifications/tool-result
+  //   params: CallToolResult  // Standard MCP type
+  // So params IS the CallToolResult and _meta lives at the top
+  // level (NOT under params.toolOutput, which is where the
+  // first-party McpAppIframe convention wraps it). Spec-compliant
+  // hosts (Claude Desktop, claude.ai Connector, Claude Code) deliver
+  // bootstrap material here.
+  if(!params||typeof params!=='object')return null;
+  var meta=params._meta;
+  if(!meta||typeof meta!=='object')return null;
+  var ggui=meta.ggui;
+  if(!ggui||typeof ggui!=='object')return null;
+  var b=ggui.bootstrap;
+  if(!b||typeof b!=='object')return null;
+  // Same loosening as readBootstrapFromInitResult / mountFromBootstrap:
+  // only runtimeUrl is required at the shell layer. componentCode is
+  // optional (absent for GguiBootstrapMeta-shaped bootstraps that
+  // open WS via wsUrl+token).
+  if(typeof b.runtimeUrl!=='string')return null;
+  return b;
+}
+window.addEventListener('message',function(ev){
+  var m=ev&&ev.data;
+  if(!m||m.jsonrpc!=='2.0')return;
+  if(m.id!=null&&pending[m.id]){
+    var p=pending[m.id];delete pending[m.id];
+    if(m.error)p.rej(m.error);else p.res(m.result);
+    return;
+  }
+  if(m.method==='ui/notifications/tool-result'){
+    // Spec-compliant hosts: m.params IS the CallToolResult; _meta is
+    // at the top level. Try this FIRST so Claude Desktop / claude.ai
+    // Connector / Claude Code land here.
+    var specB=readBootstrapFromCallToolResult(m.params);
+    if(specB){mountFromBootstrap(specB);return;}
+    // First-party McpAppIframe convention: bootstrap nested under
+    // params.toolOutput._meta. First-party hosts (Studio, Portal,
+    // console) use this shape for both init-response and post-init
+    // notification.
+    var bb=readBootstrapFromInitResult(m.params);
+    if(bb){mountFromBootstrap(bb);return;}
+    // Path A (last-resort fallback): host posts structuredContent.
+    // {url, shortCode}; shell fetches /api/bootstrap/<shortCode>
+    // over HTTP. The OSS server doesn't mount that endpoint, so this
+    // path is effectively dead unless a hosted operator wires it.
+    var tr=readToolResult(m.params);
+    if(tr)mount(tr);
+  }
+});
+setOverlay('Initializing…');
+var initTimer=setTimeout(function(){
+  setOverlay('Host did not respond to ui/initialize within 3s.');
+},3000);
+postRpc('ui/initialize',{
+  appCapabilities:{},
+  appInfo:{name:'ggui-session',version:'1.0.0'},
+  protocolVersion:'2026-01-26'
+}).then(function(result){
+  clearTimeout(initTimer);
+  postNotification('ui/notifications/initialized',{});
+  // Path B: bootstrap inline in ui/initialize result. Hosts using
+  // <McpAppIframe>'s first-party dispatch deliver bootstrap meta here
+  // and never send a separate ui/notifications/tool-result.
+  var b=readBootstrapFromInitResult(result);
+  if(b){mountFromBootstrap(b);return;}
+  // Protocol-violation surface: host signalled an attempt
+  // (toolOutput._meta.ggui exists) but bootstrap is missing or
+  // malformed. Fail fast so hosts pinning a typed error envelope
+  // don't sit on the Path-A waiting overlay forever. Only fires
+  // when the meta placeholder is present — a fully absent _meta.ggui
+  // still falls through to Path A waiting.
+  if(hasGguiMetaPlaceholder(result)){
+    var msg='ui/initialize result missing _meta.ggui.bootstrap or runtimeUrl';
+    setOverlay(msg);
+    postBootstrapFailed('BOOTSTRAP_META_MISSING',msg);
+    return;
+  }
+  // Path A: wait for the host to send ui/notifications/tool-result
+  // with structuredContent.{url, shortCode}. MCP Apps hosts that don't
+  // implement the reading-B inline-bootstrap convention land here.
+  setOverlay('Waiting for tool result…');
+}).catch(function(e){
+  clearTimeout(initTimer);
+  setOverlay('ui/initialize failed: '+(e&&e.message||JSON.stringify(e)));
+});
+})();
+`;
+export const GGUI_SESSION_SHELL_HTML = `<!doctype html>
+<html lang="en" style="height:100%"><head><meta charset="utf-8"><title>ggui session</title></head>
+<body style="margin:0;height:100%;min-height:480px"><div id="ggui-root" data-ggui-shell="thin" style="height:100%;min-height:480px"></div>
+<script>${GGUI_SESSION_SHELL_SCRIPT_BODY}</script></body></html>`;
+/**
+ * CSP `script-src` source expression that authorises the inline
+ * `<script>` block of {@link GGUI_SESSION_SHELL_HTML} when it executes
+ * inside an iframe whose CSP is inherited from a parent host.
+ *
+ * # Why this exists
+ *
+ * The console's `<McpAppIframe>` mounts the production shell via
+ * `srcdoc`. The `about:srcdoc` iframe inherits the parent console
+ * SPA's CSP, which intentionally forbids `'unsafe-inline'` for
+ * `script-src` (`packages/mcp-server/src/console-headers.ts` —
+ * "If a future slice needs inline bootstrapping, add a nonce —
+ * NEVER `'unsafe-inline'` for scripts."). Without an authorising
+ * source expression for this exact script body, the inline shell
+ * is blocked at parse time and the renderer is never fetched. The
+ * lifecycle protocol never advances past `mounting`; specs pinning
+ * `data-ggui-mcp-app-iframe-lifecycle="code-ready"` time out.
+ *
+ * Hash CSP is the right shape here: the shell body is **static**
+ * and known at build time, and a hash binds the policy to the
+ * exact bytes — narrower than `'unsafe-inline'`, narrower than a
+ * runtime-generated nonce. If the shell body changes, the hash
+ * changes; the drift test in `mcp-apps-outbound.test.ts` catches
+ * a stale value.
+ *
+ * # Where it gets used
+ *
+ * `console-headers.ts::DEVTOOL_CSP` appends this expression to its
+ * `script-src` directive. Hosted closed-runtime session-resource
+ * endpoints have their own CSP and serve the same shell — that path
+ * needs the same expression added; tracked separately.
+ *
+ * # What an MCP Apps host (Claude Desktop etc.) does
+ *
+ * Production hosts set their own CSP on the iframe document — that
+ * surface is opaque to ggui. This expression is for the FIRST-PARTY
+ * path where the host is `<McpAppIframe>` and the parent SPA owns
+ * the CSP it inherits.
+ */
+export const GGUI_SESSION_SHELL_SCRIPT_HASH = `'sha256-${createHash('sha256')
+    .update(GGUI_SESSION_SHELL_SCRIPT_BODY)
+    .digest('base64')}'`;
+/**
+ * Register `ui://ggui/session` as a readable resource on an `McpServer`.
+ *
+ * The resource is STATIC - `resources/read` always returns the same
+ * body. Per-session state lives on the live channel, not in the resource.
+ *
+ * When `publicBaseUrl` is supplied, the resource content carries
+ * `_meta.ui.csp.{connectDomains,resourceDomains}` per the MCP Apps spec
+ * (specification/2026-01-26/apps.mdx:300-317). The shell needs to fetch
+ * the iframe-runtime bundle and open a WebSocket back to the same
+ * origin; without these declarations the host applies the default CSP
+ * (`connect-src 'none'`) and both are blocked.
+ *
+ * Without `publicBaseUrl`, the `_meta.ui.csp` block is omitted — falls
+ * back to the spec's restrictive default which is fine for first-party
+ * same-origin hosts (Studio/Portal/console) where the parent SPA owns
+ * the iframe CSP via `<McpAppIframe>`.
+ *
+ * Returns nothing; the registration mutates the server in place.
+ */
+/**
+ * Build the `_meta.ui.csp.{connectDomains,resourceDomains}` block from
+ * an absolute `publicBaseUrl`. Same shape every resource that serves a
+ * shell bootstrap needs: the iframe must `script-src` + `connect-src`
+ * the runtime bundle, and `wss-src` the live-channel socket. CSP rules
+ * do NOT cross-translate `https://` ↔ `wss://`, so the HTTPS origin
+ * AND its `wss://` twin are both declared.
+ *
+ * Returns `undefined` when `publicBaseUrl` is absent or malformed —
+ * the caller omits the `_meta` block entirely in that case, falling
+ * back to the host's default CSP (fine for same-origin hosts;
+ * restrictive for cross-origin claude.ai-style hosts).
+ */
+function buildCspMeta(publicBaseUrl) {
+    if (!publicBaseUrl)
+        return undefined;
+    try {
+        const parsed = new URL(publicBaseUrl);
+        const origin = parsed.origin;
+        const wsScheme = parsed.protocol === 'https:' ? 'wss:' : 'ws:';
+        const wsOrigin = `${wsScheme}//${parsed.host}`;
+        return {
+            ui: {
+                csp: {
+                    connectDomains: [origin, wsOrigin],
+                    resourceDomains: [origin],
+                },
+            },
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function registerGguiSessionResource(server, shellHtml = GGUI_SESSION_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;
+        }
+    }
+    server.registerResource('ggui-session', GGUI_SESSION_RESOURCE_URI, {
+        // `title` / `description` show up in MCP clients that surface
+        // resource metadata. Short + concrete.
+        title: 'ggui session',
+        description: 'Thin-shell iframe bundle that bootstraps a ggui session. MCP Apps hosts fetch this when they see `_meta.ui.resourceUri` on a ggui_push result.',
+        mimeType: GGUI_SESSION_RESOURCE_MIME,
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: GGUI_SESSION_RESOURCE_MIME,
+                text: shellHtml,
+                ...(cspMeta !== undefined ? { _meta: cspMeta } : {}),
+            },
+        ],
+    }));
+}
+/**
+ * Advertise the `io.modelcontextprotocol/ui` extension capability on
+ * an `McpServer`'s underlying `Server`. Idempotent - calling twice on
+ * the same server leaves the capability advertised once.
+ *
+ * We use the `experimental` capability slot (present in every MCP SDK
+ * release) rather than `extensions` (post-1.x addition) for broadest
+ * client compat. The capability *name* is what matters to hosts; the
+ * container field is a pragmatic choice we can migrate if the spec
+ * settles on `extensions` later.
+ */
+export function advertiseMcpAppsUiCapability(server) {
+    server.server.registerCapabilities({
+        experimental: {
+            [MCP_APPS_UI_CAPABILITY]: {},
+        },
+    });
+}
+/**
+ * Build the self-contained shell HTML for a given session.
+ *
+ * The returned HTML is a complete, standalone document: it inlines the
+ * compiled component (base64) + session ids in a `window.__GGUI_BOOTSTRAP__`
+ * global, then loads the iframe-runtime bundle via `<script type="module"
+ * src={runtimeUrl}>`. The runtime takes over synchronously on import,
+ * mounts the component, and the iframe paints WITHOUT any further server
+ * round-trip.
+ *
+ * Pure function — no DOM access, no I/O, no `crypto` randomness. Same
+ * inputs always produce identical bytes (modulo input ordering of the
+ * bootstrap object's optional fields), which makes the output cacheable
+ * and testable.
+ *
+ * Escapes that matter:
+ *   - HTML-entity-escapes the bootstrap JSON for `<` `>` `&` so a
+ *     malicious appId / sessionId can't break out of the script tag.
+ *   - The componentCode is base64-encoded by the caller before the JSON
+ *     stringification runs, so even a raw `</script>` sequence in the
+ *     compiled source can't break the surrounding HTML.
+ *
+ * @public
+ */
+export function buildSelfContainedShell(opts) {
+    // Discriminate between three modes: system-card, static-component
+    // (codeUrl), or live (wsUrl + token). At least one mode MUST be set —
+    // the builder rejects an empty bootstrap. Multiple modes may coexist
+    // (e.g. codeUrl + live-mode credentials for an iframe that mounts
+    // statically but subscribes for updates); the iframe-runtime parser
+    // 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 hasLive = typeof opts.wsUrl === 'string' && opts.wsUrl.length > 0
+        && typeof opts.token === 'string' && opts.token.length > 0;
+    const isCanvas = opts.canvasMode === true;
+    if (isCanvas && (isSystem || hasCodeUrl || opts.stackItemId !== undefined)) {
+        throw new Error('buildSelfContainedShell: canvasMode is mutually exclusive with `systemKind`, `codeUrl`, and `stackItemId` — canvas iframes are session-scoped and render via the live channel, not a pre-pinned stack item');
+    }
+    if (isCanvas && !hasLive) {
+        throw new Error('buildSelfContainedShell: canvasMode requires the live-mode trio (`wsUrl` + `token` + `expiresAt`) — the canvas iframe receives stack items via the live channel, not static inlining');
+    }
+    if (!isSystem && !hasCodeUrl && !hasLive) {
+        throw new Error('buildSelfContainedShell: at least one of `codeUrl`, `systemKind`, or live-mode (`wsUrl` + `token`) must be set');
+    }
+    // Inject `runtimeUrl` + the three bootstrap-derivation fields
+    // (`appCallableTools`, `actionNextSteps`, `contextSlots`) into the
+    // inline bootstrap so the iframe-runtime's bootstrap validator
+    // (which requires `runtimeUrl` across all modes + makes
+    // `appCallableTools`/`actionNextSteps`/`contextSlots` observable on
+    // the self-contained path) accepts the envelope. Omitting
+    // `runtimeUrl` from the inline JSON makes every `/r/<shortCode>`
+    // direct-preview a blank white page because `parseBootstrap`
+    // rejects it as MALFORMED.
+    const bootstrap = {
+        sessionId: opts.sessionId,
+        appId: opts.appId,
+        runtimeUrl: opts.runtimeUrl,
+        // Static-content discriminators — system-card and codeUrl are
+        // mutually exclusive (the iframe-runtime rejects the both-set mix
+        // as MALFORMED). Live-mode credentials (wsUrl/token below) may
+        // coexist with either or stand alone.
+        ...(isSystem ? { kind: opts.systemKind } : {}),
+        ...(!isSystem && hasCodeUrl
+            ? {
+                codeUrl: opts.codeUrl,
+                ...(opts.codeHash !== undefined ? { codeHash: opts.codeHash } : {}),
+            }
+            : {}),
+        ...(opts.stackItemId !== undefined ? { stackItemId: opts.stackItemId } : {}),
+        ...(isCanvas ? { canvasMode: true } : {}),
+        ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
+        ...(opts.themeMode !== undefined ? { themeMode: opts.themeMode } : {}),
+        ...(opts.propsJson !== undefined ? { propsJson: opts.propsJson } : {}),
+        ...(opts.appCallableTools !== undefined && opts.appCallableTools.length > 0
+            ? { appCallableTools: opts.appCallableTools }
+            : {}),
+        ...(opts.actionNextSteps !== undefined &&
+            Object.keys(opts.actionNextSteps).length > 0
+            ? { actionNextSteps: opts.actionNextSteps }
+            : {}),
+        ...(opts.contextSlots !== undefined && opts.contextSlots.length > 0
+            ? { contextSlots: opts.contextSlots }
+            : {}),
+        ...(opts.permissionsPolicy !== undefined && opts.permissionsPolicy.length > 0
+            ? { permissionsPolicy: opts.permissionsPolicy }
+            : {}),
+        // Wrapper catalog the iframe-runtime dynamic-imports at boot.
+        // Symmetric with `_meta.ggui.bootstrap`'s `gadgets` field.
+        // Without this forward, the self-contained shell path
+        // (/r/<shortCode>, resources/read) would render as STDLIB-only —
+        // wrapper-using contracts (Leaflet, Mapbox) destructure unknown
+        // hooks at runtime.
+        ...(opts.gadgets !== undefined && opts.gadgets.length > 0
+            ? { gadgets: opts.gadgets }
+            : {}),
+        // Precompiled, eval-free contract validators. Symmetric forward
+        // for the self-contained shell — the renderer iframe's strict CSP
+        // blocks runtime `ajv.compile()`, so it loads these modules via
+        // `blob:` import. Omitted when the contract declares no
+        // runtime-validated schema.
+        ...(opts.compiledValidators !== undefined
+            ? { compiledValidators: opts.compiledValidators }
+            : {}),
+        // Server-filtered public env values that declared wrappers'
+        // `requires` cover. Symmetric forward; without it, wrappers
+        // calling `getPublicEnv()` throw at hook-mount on the
+        // self-contained shell path.
+        ...(opts.publicEnv !== undefined && Object.keys(opts.publicEnv).length > 0
+            ? { publicEnv: opts.publicEnv }
+            : {}),
+        // Live-mode trio. parseBootstrap rejects half-live envelopes
+        // (`wsUrl XOR token` MALFORMED), so we forward all three together
+        // or none at all — the caller is responsible for pairing them at
+        // mint time. `expiresAt` is degrade-able (past-due → static-only)
+        // but is part of the live trio at emit time.
+        ...(opts.wsUrl !== undefined ? { wsUrl: opts.wsUrl } : {}),
+        ...(opts.token !== undefined ? { token: opts.token } : {}),
+        ...(opts.expiresAt !== undefined ? { expiresAt: opts.expiresAt } : {}),
+    };
+    // JSON.stringify produces valid JS, but `<` / `>` / `&` / `U+2028`
+    // / `U+2029` can break HTML or JS parsers when embedded inline.
+    // Escape them. `U+2028` / `U+2029` are JS-source line terminators
+    // that JSON allows but JS parsers historically choked on; modern
+    // engines accept them in strings but the escape is cheap insurance.
+    const json = JSON.stringify(bootstrap)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+    // HTML-escape the runtimeUrl for the `src` attribute. Server
+    // operators control this string but a defensive escape avoids any
+    // surprise if a future code path lets user-derived data flow here.
+    const safeRuntimeUrl = opts.runtimeUrl
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>ggui session</title></head>
+<body>
+<div id="ggui-root" data-ggui-shell="self-contained"></div>
+<script>window.__GGUI_BOOTSTRAP__ = ${json};</script>
+<script type="module" crossorigin="anonymous" src="${safeRuntimeUrl}"></script>
+</body></html>`;
+}
+/**
+ * Minimal "loading" HTML served when a per-session resource is fetched
+ * for a session whose top stack item has no componentCode yet
+ * (placeholder, generation in flight). Renders a tiny status surface
+ * so hosts that pin lifecycle selectors don't see a blank document.
+ *
+ * Hosts SHOULD re-fetch when they observe additional `ggui_push`
+ * results on the same session — the per-call `_meta.ui.resourceUri`
+ * value stays stable across pushes for a session, so re-fetching the
+ * same URI returns fresher HTML on the second try.
+ *
+ * @public
+ */
+export function buildSelfContainedLoadingShell(sessionId) {
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>ggui session</title></head>
+<body>
+<div id="ggui-root" data-ggui-shell="loading" data-ggui-session-id="${sessionId
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')}">Generating UI…</div>
+</body></html>`;
+}
+function pickTopComponentItem(stack) {
+    for (let i = stack.length - 1; i >= 0; i -= 1) {
+        const entry = stack[i];
+        if (!entry || entry.type === 'mcpApps')
+            continue;
+        const props = entry.props !== undefined &&
+            entry.props !== null &&
+            typeof entry.props === 'object' &&
+            !Array.isArray(entry.props)
+            ? entry.props
+            : undefined;
+        if (entry.type === 'system') {
+            if (typeof entry.kind === 'string' && entry.kind.length > 0) {
+                return {
+                    id: entry.id,
+                    kind: entry.kind,
+                    ...(props !== undefined ? { props } : {}),
+                    source: entry,
+                };
+            }
+            continue;
+        }
+        const code = entry.componentCode;
+        if (typeof code === 'string' && code.length > 0) {
+            return {
+                id: entry.id,
+                componentCode: code,
+                ...(props !== undefined ? { props } : {}),
+                source: entry,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Register a `ui://ggui/session/{sessionId}` resource template. Each
+ * `resources/read` request is resolved by looking up the session in the
+ * store, picking the topmost component stack item, and returning the
+ * self-contained shell with that componentCode inlined.
+ *
+ * Per-call `_meta.ui.resourceUri` (stamped by `ggui_push.resultMeta`)
+ * pins the URI to a specific sessionId; hosts fetch THAT URI rather
+ * than the static `ui://ggui/session` one. Both registrations co-exist:
+ * legacy postMessage shell at the static URI, self-contained shell at
+ * the templated URI.
+ *
+ * Failure modes:
+ *   - Session not found → loading shell (host re-fetches; absent
+ *     session is a transient state immediately after `ggui_push`).
+ *   - Session found, no componentCode yet → loading shell.
+ *   - Session found, componentCode present → self-contained shell.
+ *
+ * Returns nothing; mutates the server in place.
+ *
+ * @public
+ */
+export function registerGguiSessionResourceTemplate(server, opts) {
+    // TWO templates registered against the same handler core:
+    //
+    //   1. Single-segment legacy URI — `ui://ggui/session/{sessionId}`.
+    //      Pre-resume-contract chats in claude.ai's history persisted
+    //      this shape; we keep the registration so historical messages
+    //      still rehydrate (loading shell on session miss).
+    //
+    //   2. Two-segment resume URI — `ui://ggui/session/{sessionId}/
+    //      {blueprintKey}`. Stamped by every push since the resume
+    //      contract landed. Carries enough state for the handler to do:
+    //      (a) parallel session + blueprint registry lookup (no data
+    //      dependency between them), (b) registry-only fallback when
+    //      the session is gone but the blueprint is still cached
+    //      (renders the original card with default props/context
+    //      instead of the dead loading shell).
+    const legacyTemplate = new ResourceTemplate(`${GGUI_SESSION_RESOURCE_URI}/{sessionId}`, {
+        // No list-callback — the resource set is unbounded per session
+        // count, and `resources/list` would leak session ids across
+        // tenants. Hosts discover specific URIs via per-call `_meta.ui.
+        // resourceUri` instead.
+        list: undefined,
+    });
+    const resumeTemplate = new ResourceTemplate(`${GGUI_SESSION_RESOURCE_URI}/{sessionId}/{blueprintKey}`, { list: undefined });
+    // CSP-meta block forwarded on every shell response when the
+    // template was wired with `publicBaseUrl`. claude.ai's iframe
+    // applies the host's restrictive default (`connect-src 'none'`)
+    // unless the resource declares `_meta.ui.csp.connectDomains` —
+    // without that the `<script type="module" src=runtimeUrl>` tag
+    // fails with a generic "script error" since cross-origin script
+    // loading is blocked. Same shape declared on the static
+    // `ui://ggui/session` resource; this is the per-call mirror.
+    const templateCspMeta = buildCspMeta(opts.publicBaseUrl);
+    /**
+     * Merge gadget-declared origins from
+     * {@link deriveBundleOrigins} into the base `templateCspMeta`. The
+     * base only carries the publicBaseUrl origin (HTTPS + WSS); without
+     * the per-stack-item augmentation, gadget bundle / style / API
+     * origins (Leaflet tiles, Mapbox API, Stripe SDK, …) are blocked by
+     * 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).
+     */
+    const augmentCspMeta = (gadgetOrigins) => {
+        if (templateCspMeta === undefined)
+            return undefined;
+        if (gadgetOrigins === undefined)
+            return templateCspMeta;
+        return {
+            ui: {
+                csp: {
+                    connectDomains: [
+                        ...templateCspMeta.ui.csp.connectDomains,
+                        ...gadgetOrigins.connect,
+                    ],
+                    resourceDomains: [
+                        ...templateCspMeta.ui.csp.resourceDomains,
+                        ...gadgetOrigins.script,
+                        ...gadgetOrigins.style,
+                    ],
+                },
+            },
+        };
+    };
+    const shellContents = (uri, text, cspMeta = templateCspMeta) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: GGUI_SESSION_RESOURCE_MIME,
+                text,
+                ...(cspMeta !== undefined ? { _meta: cspMeta } : {}),
+            },
+        ],
+    });
+    const loadingShell = (uri, sessionId) => shellContents(uri, buildSelfContainedLoadingShell(sessionId));
+    // 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;
+        if (typeof sessionId !== 'string' || sessionId.length === 0) {
+            return loadingShell(uri, 'unknown');
+        }
+        const blueprintKeyRaw = variables['blueprintKey'];
+        const blueprintKey = Array.isArray(blueprintKeyRaw)
+            ? blueprintKeyRaw[0]
+            : blueprintKeyRaw;
+        const hasResumeKey = typeof blueprintKey === 'string' && blueprintKey.length > 0;
+        // Parallel lookup. The session and the blueprint registry are
+        // independent — even though `session.stack[top].componentCode`
+        // could feed the renderable directly, we ALSO want the blueprint
+        // entry as a registry-only fallback when the session is gone but
+        // the blueprint is still cached (chat-history rehydrate after
+        // session TTL or process restart).
+        const [session, blueprint] = await Promise.all([
+            opts.sessionStore.get(sessionId),
+            hasResumeKey && opts.vectorStore && opts.defaultAppIdFallback
+                ? findBlueprintExact({ vectorStore: opts.vectorStore }, opts.defaultAppIdFallback, 'template', blueprintKey)
+                : Promise.resolve(null),
+        ]);
+        // Canvas-mode branch: session-scoped
+        // iframe that renders {@link CanvasShell} and subscribes to
+        // the live channel for stack-item delivery. The bootstrap carries
+        // `canvasMode: true` + live-mode trio (wsUrl/token/expiresAt) and
+        // NO stackItemId / codeUrl / systemKind — the iframe-runtime
+        // mounts the canvas and waits for `push` envelopes rather than
+        // rendering a pinned static item.
+        //
+        // Falls through to the legacy single-item path when `mintBootstrap`
+        // isn't wired (canvas can't function without WS credentials, and
+        // serving a pinned stack item is strictly better than a dead
+        // loading shell).
+        if (session && session.mcpAppsMode === 'canvas' && opts.mintBootstrap) {
+            let creds = null;
+            try {
+                creds = await opts.mintBootstrap(sessionId, session.appId);
+            }
+            catch {
+                creds = null;
+            }
+            if (creds) {
+                const html = buildSelfContainedShell({
+                    sessionId,
+                    appId: session.appId,
+                    canvasMode: true,
+                    runtimeUrl: opts.runtimeUrl,
+                    wsUrl: creds.wsUrl,
+                    token: creds.token,
+                    expiresAt: creds.expiresAt,
+                    ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
+                    ...(opts.themeMode !== undefined ? { themeMode: opts.themeMode } : {}),
+                });
+                return shellContents(uri, html);
+            }
+            // mintBootstrap returned null / threw — fall through to legacy
+            // path below. Logs are silent at this layer; deployment-level
+            // metrics (cloud) catch the degradation rate.
+        }
+        // Happy path: session present, top stack item renderable. Mount
+        // with the live state (current props, current contextSpec values).
+        if (session) {
+            const top = pickTopComponentItem(session.stack);
+            if (top) {
+                // Project the active stack item to the transport-agnostic
+                // bootstrap view — same source of truth `push.ts` and
+                // `/r/<shortCode>` consume. Carries permissionsPolicy when
+                // clientCapabilities declares permissions. The MCP Apps
+                // resource path emits this only into the inline bootstrap
+                // (the browser-enforced gate ultimately comes from the host's
+                // `allow=""` attribute when the host translates
+                // `_meta.ui.permissions` — set by McpAppIframe consumers).
+                const view = deriveStackItemBootstrapView(top.source);
+                const isSystem = top.kind !== undefined;
+                // Static-component delivery via codeUrl (T3-1, 2026-05-13). The
+                // compiled-component path mints a content-addressable URL the
+                // iframe-runtime fetches at boot; the loading shell takes over
+                // when codeStore + codeBaseUrl aren't wired.
+                let codeUrl;
+                let codeHash;
+                if (!isSystem && opts.codeStore && opts.codeBaseUrl) {
+                    try {
+                        const hash = opts.codeStore.hashOf(top.componentCode);
+                        await opts.codeStore.put(hash, top.componentCode);
+                        codeHash = hash;
+                        const base = opts.codeBaseUrl.replace(/\/$/, '');
+                        codeUrl = `${base}/code/${hash}.js`;
+                    }
+                    catch {
+                        // Silent — falls through to loading shell below.
+                    }
+                }
+                if (!isSystem && codeUrl === undefined) {
+                    // Compiled-component item but no codeUrl channel available —
+                    // emit the loading shell so the operator can refresh once
+                    // codeStore is wired. Direct-render `/r/<shortCode>` falls
+                    // through to live-mode instead; this MCP-resource path has
+                    // no WS-mode fallback (resources/read is one-shot).
+                    return loadingShell(uri, sessionId);
+                }
+                // Project the wrapper catalog AND the union-filtered
+                // publicEnv onto the inline bootstrap so the resource-served
+                // iframe matches the MCP-Apps postMessage path. Without this,
+                // wrapper-using contracts rendered through `resources/read`
+                // mount as STDLIB-only.
+                let resourcePublicEnv;
+                if (opts.appMetadataStore) {
+                    try {
+                        const appRecord = await opts.appMetadataStore.get(session.appId);
+                        resourcePublicEnv = derivePublicEnvProjection(top.source, appRecord?.publicEnv);
+                    }
+                    catch {
+                        // Silent — wrappers calling getPublicEnv throw clearly.
+                    }
+                }
+                const html = buildSelfContainedShell({
+                    sessionId,
+                    appId: session.appId,
+                    ...(isSystem
+                        ? { systemKind: top.kind }
+                        : {
+                            codeUrl: codeUrl,
+                            ...(codeHash !== undefined ? { codeHash } : {}),
+                        }),
+                    runtimeUrl: opts.runtimeUrl,
+                    stackItemId: top.id,
+                    ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
+                    ...(opts.themeMode !== undefined ? { themeMode: opts.themeMode } : {}),
+                    ...(view.propsJson !== undefined ? { propsJson: view.propsJson } : {}),
+                    ...(view.actionNextSteps !== undefined
+                        ? { actionNextSteps: view.actionNextSteps }
+                        : {}),
+                    ...(view.contextSlots !== undefined
+                        ? { contextSlots: view.contextSlots }
+                        : {}),
+                    ...(view.permissionsPolicy !== undefined
+                        ? { permissionsPolicy: view.permissionsPolicy }
+                        : {}),
+                    ...(view.gadgets !== undefined &&
+                        view.gadgets.length > 0
+                        ? { gadgets: view.gadgets }
+                        : {}),
+                    ...(view.compiledValidators !== undefined
+                        ? { compiledValidators: view.compiledValidators }
+                        : {}),
+                    ...(resourcePublicEnv !== undefined &&
+                        Object.keys(resourcePublicEnv).length > 0
+                        ? { publicEnv: resourcePublicEnv }
+                        : {}),
+                });
+                // Augment per-call CSP with gadget-declared bundle / style /
+                // API origins. Without this, claude.ai's iframe CSP only allows
+                // the publicBaseUrl origin, so Leaflet wrapper bundles fetched
+                // from registry.ggui.ai, leaflet.css fetched from same, and
+                // OSM tile requests to tile.openstreetmap.org all get blocked
+                // → the component throws and the React error boundary renders
+                // "Something went wrong." The /r/<shortCode> HTTP path already
+                // derives these via deriveBundleOrigins; this is the per-call
+                // resource mirror.
+                const gadgetOrigins = deriveBundleOrigins(top.source);
+                return shellContents(uri, html, augmentCspMeta(gadgetOrigins));
+            }
+        }
+        // Registry-only fallback: session is gone (TTL / restart) but the
+        // blueprint is still in the registry. Synthesize the shell from
+        // the blueprint's componentCode + propsSpec defaults — strictly
+        // worse than the live mount (no current props, no preserved
+        // context state), but strictly better than the dead loading
+        // shell.
+        if (blueprint && opts.defaultAppIdFallback) {
+            const html = await buildShellFromBlueprint({
+                sessionId,
+                appId: opts.defaultAppIdFallback,
+                blueprint,
+                runtimeUrl: opts.runtimeUrl,
+                ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
+                ...(opts.themeMode !== undefined ? { themeMode: opts.themeMode } : {}),
+                ...(opts.codeStore !== undefined ? { codeStore: opts.codeStore } : {}),
+                ...(opts.codeBaseUrl !== undefined ? { codeBaseUrl: opts.codeBaseUrl } : {}),
+            });
+            if (html !== undefined) {
+                return shellContents(uri, html);
+            }
+            // Fallthrough to loading shell when codeStore isn't wired.
+        }
+        return loadingShell(uri, sessionId);
+    }
+    server.registerResource('ggui-session-self-contained', legacyTemplate, {
+        title: 'ggui session (self-contained, legacy URI)',
+        description: 'Per-session self-contained shell — single-segment URI shape predating the resume contract. Falls back to loading shell when the session is gone (no blueprintKey to do registry-only render).',
+        mimeType: GGUI_SESSION_RESOURCE_MIME,
+    }, handle);
+    server.registerResource('ggui-session-self-contained-resume', resumeTemplate, {
+        title: 'ggui session (self-contained, resume URI)',
+        description: 'Per-session self-contained shell — two-segment URI shape carrying both sessionId AND blueprintKey. Resource handler runs Promise.all over session + registry; falls back to registry-only static render when the session has been evicted but the blueprint is still cached.',
+        mimeType: GGUI_SESSION_RESOURCE_MIME,
+    }, handle);
+}
+/**
+ * Synthesize a shell from a registry-only blueprint (no live session).
+ * Used when chat-history rehydrate finds the session evicted but the
+ * blueprint registry still holds the entry. Renders the same
+ * componentCode the original push generated, seeded with the
+ * contract's declared `propsSpec` defaults + `contextSpec` defaults.
+ * Live state (the user's interactive edits, last-known context
+ * values) is lost in this path; that's the cost of session eviction.
+ *
+ * Internal — exported nowhere because the only safe trigger path is
+ * inside the resource handler with the resume URI shape (URI carries
+ * the blueprintKey that bounds which blueprint we render).
+ */
+async function buildShellFromBlueprint(args) {
+    const { blueprint } = args;
+    if (!args.codeStore || !args.codeBaseUrl) {
+        return undefined;
+    }
+    const contract = blueprint.contract ?? {};
+    const propsSpec = 'props' in contract && contract.props !== undefined
+        ? contract.props
+        : undefined;
+    const propsJson = propsSpec
+        ? JSON.stringify(deriveDefaultPropsValues(propsSpec))
+        : undefined;
+    const contextSlots = deriveDefaultContextSlots(contract.contextSpec);
+    const actionNextSteps = 'actionSpec' in contract && contract.actionSpec !== undefined
+        ? deriveWiredActionToolsFromSpec(contract.actionSpec)
+        : undefined;
+    let codeUrl;
+    let codeHash;
+    try {
+        codeHash = args.codeStore.hashOf(blueprint.componentCode);
+        await args.codeStore.put(codeHash, blueprint.componentCode);
+        const base = args.codeBaseUrl.replace(/\/$/, '');
+        codeUrl = `${base}/code/${codeHash}.js`;
+    }
+    catch {
+        return undefined;
+    }
+    return buildSelfContainedShell({
+        sessionId: args.sessionId,
+        appId: args.appId,
+        codeUrl,
+        codeHash,
+        runtimeUrl: args.runtimeUrl,
+        ...(args.themeId !== undefined ? { themeId: args.themeId } : {}),
+        ...(args.themeMode !== undefined ? { themeMode: args.themeMode } : {}),
+        ...(propsJson !== undefined ? { propsJson } : {}),
+        ...(contextSlots !== undefined ? { contextSlots } : {}),
+        ...(actionNextSteps !== undefined ? { actionNextSteps } : {}),
+    });
+}
+function deriveDefaultPropsValues(spec) {
+    const out = {};
+    for (const [name, entry] of Object.entries(spec.properties)) {
+        if (entry.default !== undefined) {
+            out[name] = entry.default;
+        }
+        else if (entry.schema && entry.schema.default !== undefined) {
+            out[name] = entry.schema.default;
+        }
+    }
+    return out;
+}
+function deriveDefaultContextSlots(spec) {
+    if (!spec)
+        return undefined;
+    const collected = [];
+    for (const [name, entry] of Object.entries(spec)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        if (entry.schema === undefined || entry.schema === null)
+            continue;
+        if (typeof entry.schema !== 'object')
+            continue;
+        const fallback = deriveContextDefault(entry);
+        collected.push({
+            name,
+            contextName: deriveContextName(name),
+            schema: entry.schema,
+            default: fallback === undefined ? null : fallback,
+            ...(entry.debounceMs !== undefined ? { debounceMs: entry.debounceMs } : {}),
+        });
+    }
+    return collected.length > 0 ? collected : undefined;
+}
+function deriveWiredActionToolsFromSpec(spec) {
+    const collected = {};
+    for (const [name, entry] of Object.entries(spec)) {
+        if (entry &&
+            typeof entry === 'object' &&
+            typeof entry.nextStep === 'string' &&
+            entry.nextStep.length > 0) {
+            collected[name] = entry.nextStep;
+        }
+    }
+    return Object.keys(collected).length > 0 ? collected : undefined;
+}
+/**
+ * Apply the full MCP Apps outbound wiring to a fresh `McpServer` - both
+ * the capability advertisement and the `ui://ggui/session` resource. The
+ * single entry-point `build-mcp.ts` calls so request-path wiring stays
+ * one line.
+ *
+ * When `selfContained` is supplied, ALSO registers the per-session
+ * `ui://ggui/session/{sessionId}` resource template that serves the
+ * self-contained shell (the path third-party MCP Apps hosts use). The
+ * legacy static URI registration is unconditional — first-party hosts
+ * (Studio, Portal, console) still rely on the postMessage path.
+ */
+export function installMcpAppsOutbound(server, opts = {}) {
+    advertiseMcpAppsUiCapability(server);
+    registerGguiSessionResource(server, opts.shellHtml, opts.publicBaseUrl);
+    if (opts.selfContained) {
+        registerGguiSessionResourceTemplate(server, opts.selfContained);
+    }
+}