@ggui-ai/mcp-server 0.2.0-alpha.3 → 0.3.0-rc.0

package/dist/mcp-apps-outbound.js

@@ -32,8 +32,8 @@
  *   same `@ggui-ai/mcp-server` instance that mints the bootstrap.
  */
 import { deriveBundleOrigins, deriveContractBundle, derivePublicEnvProjection, deriveRenderMeta, findBlueprintExact, } from "@ggui-ai/mcp-server-handlers/renders";
-import { deriveContextDefault } from "@ggui-ai/protocol";
-import { GGUI_RENDER_RESOURCE_MIME, GGUI_RENDER_RESOURCE_URI, MCP_APPS_UI_CAPABILITY, MCP_APP_AI_GGUI_RENDER_META_KEY, deriveContextName, } from "@ggui-ai/protocol/integrations/mcp-apps";
+import { deriveContextDefault, isRecord } from "@ggui-ai/protocol";
+import { GGUI_RENDER_RESOURCE_MIME, GGUI_RENDER_RESOURCE_URI, MCP_APPS_UI_CAPABILITY, MCP_APP_AI_GGUI_RENDER_META_KEY, MCP_APP_BOOTSTRAP_FAILED_TYPE, deriveContextName, } 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";
@@ -41,23 +41,25 @@ import { createHash } from "node:crypto";
  * Thin-shell body served from `ui://ggui/render` (C8 pivot).
  *
  * **Architectural role.** The shell is a ~30 LOC bootstrap wrapper -
- * it runs a minimal `ui/initialize` preflight to read the
- * `ai.ggui/render.runtimeUrl` slice field, then dynamic-script-loads
- * the `@ggui-ai/iframe-runtime` bundle from that URL. Every rendering
- * concern - WS open, subscribe, render mount, component code eval,
- * adapter install - belongs to the renderer bundle (shipped C7a-d),
- * not here.
+ * it runs the `ui/initialize` + `ui/notifications/initialized`
+ * handshake, then waits for the host's spec-canonical
+ * `ui/notifications/tool-result` notification carrying the
+ * `ai.ggui/render` slice in `_meta`, and dynamic-script-loads the
+ * `@ggui-ai/iframe-runtime` bundle from the slice's `runtimeUrl`.
+ * Every rendering concern - WS open, subscribe, render mount,
+ * 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 the
  * `ai.ggui/render.runtimeUrl` slice field and the shell picks it up
- * from the first `ui/initialize` response - origin-agnostic, works
+ * from the tool-result `_meta` slice - 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">`").
+ * HTML loads it via `<script type="module" src=".../iframe-runtime.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
@@ -70,31 +72,30 @@ import { createHash } from "node:crypto";
  * surface to the parent via
  * `postMessage({type:'ggui:bootstrap-failed', reason, message}, '*')`:
  *
- *   - `BOOTSTRAP_META_MISSING` - `ui/initialize` returned without a
- *     valid `ai.ggui/render` slice OR without a `runtimeUrl` field on
- *     it.
+ *   - `MALFORMED_BOOTSTRAP` - the tool-result `_meta` slice arrived
+ *     without a valid `ai.ggui/render` envelope or `runtimeUrl`.
  *   - `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
+ * Post-renderer failures (WS handshake / auth / render-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).
+ * emits the same `ggui:bootstrap-failed` envelope.
  *
  * **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
+ * posture - the shell still MUST NOT mutate render 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.
+ * preflight to complete the MCP Apps handshake (hosts release the
+ * tool-result notification only after `ui/notifications/initialized`);
+ * 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
@@ -104,9 +105,9 @@ import { createHash } from "node:crypto";
 /**
  * Inline body of the thin shell's bootstrap `<script>` block.
  *
- * Split from {@link GGUI_SESSION_SHELL_HTML} so the exact bytes the
+ * Split from {@link GGUI_RENDER_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}.
+ * for CSP-hash purposes — see {@link GGUI_RENDER_SHELL_SCRIPT_HASH}.
  *
  * The browser's CSP `'sha256-...'` source-expression is computed over
  * the literal text content of the `<script>` element (everything
@@ -114,10 +115,11 @@ import { createHash } from "node:crypto";
  * 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.
+ * {@link GGUI_RENDER_SHELL_SCRIPT_HASH} is DERIVED from this constant
+ * at module load, so edits here propagate to the CSP hash
+ * automatically. The `mcp-apps-outbound.test.ts` drift test recomputes
+ * the hash from the assembled shell HTML and fails loudly if the body
+ * and the HTML assembly ever disagree.
  */
 const GGUI_RENDER_SHELL_SCRIPT_BODY = `
 (function(){'use strict';
@@ -127,9 +129,8 @@ const GGUI_RENDER_SHELL_SCRIPT_BODY = `
 //   2. iframe -> host: ui/notifications/initialized
 //   3. host -> iframe: ui/notifications/tool-result (per CallToolResult)
 // On tool-result, read the slice envelope from _meta (spec-canonical
-// CallToolResult _meta at the top level, or the first-party
-// params.toolOutput._meta shape), set window.__GGUI_META__ to the
-// envelope, fetch runtime as blob, inject as script.
+// CallToolResult _meta at the top level), set window.__GGUI_META__ to
+// the envelope, 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.
@@ -142,7 +143,7 @@ const GGUI_RENDER_SHELL_SCRIPT_BODY = `
 // Phase B (2026-05-27): the historic two-slice envelope
 // (\`ai.ggui/session\` + \`ai.ggui/stack-item\`) collapsed to ONE flat
 // \`ai.ggui/render\` slice. runtimeUrl now lives directly on the
-// render slice; renderId is the canonical identity.
+// render slice; sessionId is the canonical identity.
 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';
@@ -167,11 +168,11 @@ function postBootstrapFailed(reason,message){
   // 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){}
+  try{window.parent.postMessage({type:'${MCP_APP_BOOTSTRAP_FAILED_TYPE}',reason:reason,message:message},'*');}catch(e){}
 }
 async function mountFromMeta(envelope){
   if(mounted)return;
-  // Slice envelope shape (Phase B): { "ai.ggui/render": { renderId,
+  // Slice envelope shape (Phase B): { "ai.ggui/render": { sessionId,
   // appId, runtimeUrl, ... } }. runtimeUrl on the render slice is
   // the only load-bearing field at the shell layer — it tells us
   // which iframe-runtime bundle to fetch. Everything else is
@@ -181,7 +182,7 @@ async function mountFromMeta(envelope){
   var runtimeUrl=renderSlice&&renderSlice.runtimeUrl;
   if(!envelope||typeof runtimeUrl!=='string'){
     setOverlay('Bootstrap payload malformed.');
-    postBootstrapFailed('BOOTSTRAP_MALFORMED','Bootstrap payload malformed.');
+    postBootstrapFailed('MALFORMED_BOOTSTRAP','Bootstrap payload malformed.');
     return;
   }
   setOverlay('Loading UI…');
@@ -220,42 +221,17 @@ async function mountFromMeta(envelope){
     postBootstrapFailed('BUNDLE_FETCH_FAILED',msg);
   }
 }
-function readMetaFromInitResult(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;
-  // Single slice-envelope key (Phase B: ai.ggui/render). Only the
-  // render slice's runtimeUrl is load-bearing at the shell layer;
-  // the runtime reads everything else off window.__GGUI_META__
-  // after we set it.
-  var renderSlice=meta['ai.ggui/render'];
-  if(!renderSlice||typeof renderSlice!=='object')return null;
-  if(typeof renderSlice.runtimeUrl!=='string')return null;
-  return meta;
-}
-function hasAiGguiMetaPlaceholder(result){
-  // Detect the protocol-violation case where the host signaled
-  // "I tried to deliver meta" (toolOutput._meta carries an
-  // ai.ggui/render key) but it's malformed. Fail-fast with
-  // BOOTSTRAP_META_MISSING rather than waiting 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;
-  return 'ai.ggui/render' in meta;
-}
 function readMetaFromCallToolResult(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
-  // slice-envelope material here.
+  // level. Spec-compliant hosts (Claude Desktop, claude.ai
+  // Connector, Claude Code) deliver slice-envelope material here.
+  // Single slice-envelope key (Phase B: ai.ggui/render). Only the
+  // render slice's runtimeUrl is load-bearing at the shell layer;
+  // the runtime reads everything else off window.__GGUI_META__
+  // after we set it.
   if(!params||typeof params!=='object')return null;
   var meta=params._meta;
   if(!meta||typeof meta!=='object')return null;
@@ -274,21 +250,14 @@ window.addEventListener('message',function(ev){
   }
   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=readMetaFromCallToolResult(m.params);
-    if(specB){mountFromMeta(specB);return;}
-    // First-party McpAppIframe convention: slice envelope nested under
-    // params.toolOutput._meta. First-party hosts (Studio, Portal,
-    // console) use this shape for both init-response and post-init
-    // notification.
-    var bb=readMetaFromInitResult(m.params);
-    if(bb){mountFromMeta(bb);return;}
+    // at the top level.
+    var specMeta=readMetaFromCallToolResult(m.params);
+    if(specMeta){mountFromMeta(specMeta);return;}
     // R5 (2026-05-26) -- the /r/<shortCode> HTTP fallback was removed
     // along with the bearer-by-obscurity model. Hosts that strip
     // _meta on the tool-result wire have no fallback path here;
-    // spec-canonical hosts deliver meta inline and land in the two
-    // branches above.
+    // spec-canonical hosts deliver meta inline and land in the branch
+    // above.
   }
 });
 setOverlay('Initializing…');
@@ -297,29 +266,15 @@ var initTimer=setTimeout(function(){
 },3000);
 postRpc('ui/initialize',{
   appCapabilities:{},
-  appInfo:{name:'ggui-session',version:'1.0.0'},
+  appInfo:{name:'ggui-render',version:'1.0.0'},
   protocolVersion:'2026-01-26'
-}).then(function(result){
+}).then(function(){
   clearTimeout(initTimer);
   postNotification('ui/notifications/initialized',{});
-  // Path B: slice envelope inline in ui/initialize result. Hosts
-  // using <McpAppIframe>'s first-party dispatch deliver meta here
-  // and never send a separate ui/notifications/tool-result.
-  var b=readMetaFromInitResult(result);
-  if(b){mountFromMeta(b);return;}
-  // Protocol-violation surface: host signalled an attempt
-  // (toolOutput._meta carries ai.ggui/render) but it's malformed.
-  // Fail fast so hosts pinning a typed error envelope don't sit on
-  // the Path-A waiting overlay forever.
-  if(hasAiGguiMetaPlaceholder(result)){
-    var msg='ui/initialize result missing valid ai.ggui/render.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-meta convention land here.
+  // 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);
@@ -327,9 +282,50 @@ postRpc('ui/initialize',{
 });
 })();
 `;
+// `--ggui-color-surface` is injected at `:root` on this document's
+// `<head>` by the iframe-runtime at boot (react-renderer.ts ->
+// `<style id="ggui-theme-vars">`), so the `var()` resolves to the
+// active theme's exact per-mode surface color at runtime. The static
+// `#1e293b` fallback (the dark-mode surface) covers the pre-resolve
+// first paint + browsers that drop unresolved custom properties.
+//
+// # Why paint the document background here (Safari white-canvas fix)
+//
+// This shell is ALWAYS the **top-level document of a standalone served
+// iframe** (`ui://ggui/render`, the `/r/<shortCode>` viewer, the
+// sandbox-proxy inner-iframe `srcdoc`). It is NEVER inlined into a host
+// page — the host wrapper (`<McpAppIframe>`) only ever loads it AS an
+// iframe document, never as part of its own DOM. So painting `html` /
+// `body` here is structurally unreachable by inline embedding and
+// cannot impose a background on a host page.
+//
+// The design scope root (`.ggui-rcr-*`) and the sandbox-proxy outer
+// document stay `background-color: transparent` by design (so a host
+// themeing the chat surface shows through AROUND the rendered content).
+// But nothing painted the rendered-content document's OWN backdrop:
+// Chrome composited the transparent iframe document over the dark host
+// app behind it (looked dark), while Safari renders a transparent
+// iframe document's backdrop as the opaque UA `Canvas` color (white) —
+// the per-browser divergence the bug reported. The component itself
+// themed correctly (its scoped vars resolve); only the page behind it
+// diverged. Painting the served document's own surface here removes the
+// dependency on a browser honoring iframe transparency.
+//
+// Value-resolution only — no `--ggui-*` token added or renamed.
+const GGUI_RENDER_SHELL_SURFACE = `var(--ggui-color-surface, #1e293b)`;
+// `#ggui-root` here is LOAD-BEARING for the shell script (NOT a React
+// mount target): the inline script grabs it as `rootEl` for the
+// pre-mount overlays ("Initializing…", "Waiting for tool result…",
+// bootstrap-failure messages) and clears it before injecting the
+// runtime bundle. The runtime itself mounts into its own
+// `<ul data-ggui-session-root>` appended to `document.body`
+// (iframe-runtime `status-dom.ts#ensureStatusDom`), so `#ggui-root`
+// stays empty after a successful mount — that is expected, not a bug.
+// The self-contained shell (`buildSelfContainedShell`) has no overlay
+// script and therefore no anchor div at all.
 export const GGUI_RENDER_SHELL_HTML = `<!doctype html>
-<html lang="en" style="height:100%"><head><meta charset="utf-8"><title>ggui render</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>
+<html lang="en" style="height:100%;background-color:${GGUI_RENDER_SHELL_SURFACE}"><head><meta charset="utf-8"><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="thin" style="height:100%;min-height:480px"></div>
 <script>${GGUI_RENDER_SHELL_SCRIPT_BODY}</script></body></html>`;
 /**
  * CSP `script-src` source expression that authorises the inline
@@ -359,7 +355,7 @@ export const GGUI_RENDER_SHELL_HTML = `<!doctype html>
  * # Where it gets used
  *
  * `console-headers.ts::DEVTOOL_CSP` appends this expression to its
- * `script-src` directive. Hosted closed-runtime session-resource
+ * `script-src` directive. Hosted closed-runtime render-resource
  * endpoints have their own CSP and serve the same shell — that path
  * needs the same expression added; tracked separately.
  *
@@ -377,7 +373,7 @@ export const GGUI_RENDER_SHELL_SCRIPT_HASH = `'sha256-${createHash("sha256")
  * Register `ui://ggui/render` 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.
+ * body. Per-render 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
@@ -412,10 +408,10 @@ function buildCspMeta(publicBaseUrl,
  * same-origin deployments, e.g. `ggui serve` on `127.0.0.1`), derive
  * the CSP block from `runtimeUrl`. The runtime + WS + state endpoints
  * all live on the runtime's origin in same-origin deployments, so
- * declaring it covers every fetch the canvas iframe makes.
+ * declaring it covers every fetch the sandboxed iframe makes.
  *
  * Without this fallback, local dev with cross-origin sandbox proxies
- * (sample-agent's `:7790/sandbox.html` writing the canvas HTML that
+ * (sample-agent's `:7790/sandbox.html` writing the sandbox HTML that
  * references `:6786/_ggui/iframe-runtime.js`) trips a `script-src`
  * violation that blanks the iframe — verified live 2026-05-27.
  */
@@ -517,10 +513,10 @@ export function advertiseMcpAppsUiCapability(server) {
     });
 }
 /**
- * Build the self-contained shell HTML for a given session.
+ * Build the self-contained shell HTML for a given render.
  *
  * The returned HTML is a complete, standalone document: it inlines the
- * compiled component (base64) + session ids in a `window.__GGUI_META__`
+ * compiled component (base64) + the render id in a `window.__GGUI_META__`
  * 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
@@ -564,14 +560,15 @@ export function buildSelfContainedShell(opts) {
     // postMessage paths use. `runtimeUrl` is required across all modes
     // (the shell-bundled script tag fetches the runtime from there).
     const render = {
-        renderId: opts.renderId,
+        sessionId: opts.sessionId,
         appId: opts.appId,
         runtimeUrl: opts.runtimeUrl,
         ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
         ...(opts.themeMode !== undefined ? { themeMode: opts.themeMode } : {}),
-        ...(opts.appCallableTools !== undefined && opts.appCallableTools.length > 0
-            ? { appCallableTools: opts.appCallableTools }
-            : {}),
+        // Per-app theme overlay — same field the MCP-Apps `_meta` slice
+        // carries, forwarded onto the inline bootstrap so the self-contained
+        // shell applies the operator overlay too.
+        ...(opts.theme !== undefined ? { theme: opts.theme } : {}),
         ...(opts.permissionsPolicy !== undefined && opts.permissionsPolicy.length > 0
             ? { permissionsPolicy: opts.permissionsPolicy }
             : {}),
@@ -615,9 +612,6 @@ export function buildSelfContainedShell(opts) {
             }
             : {}),
         ...(opts.propsJson !== undefined ? { propsJson: opts.propsJson } : {}),
-        ...(opts.actionNextSteps !== undefined && Object.keys(opts.actionNextSteps).length > 0
-            ? { actionNextSteps: opts.actionNextSteps }
-            : {}),
         ...(opts.contextSlots !== undefined && opts.contextSlots.length > 0
             ? { contextSlots: opts.contextSlots }
             : {}),
@@ -657,10 +651,26 @@ export function buildSelfContainedShell(opts) {
         .replace(/"/g, "&quot;")
         .replace(/</g, "&lt;")
         .replace(/>/g, "&gt;");
+    // Standalone served-iframe document — paint its own surface backdrop
+    // so the canvas behind the rendered component never depends on a
+    // browser honoring iframe transparency (the Safari white-canvas bug).
+    // Same gating rationale as `GGUI_RENDER_SHELL_HTML`: this is ALWAYS a
+    // top-level iframe document (the `__GGUI_META__` self-contained shell
+    // for claude.ai / per-render resource shells), never inlined into a
+    // host page, so painting `html`/`body` here cannot regress inline
+    // embedding. `var(--ggui-color-surface, …)` resolves to the active
+    // theme's per-mode surface once the iframe-runtime injects the `:root`
+    // theme vars; the static dark fallback covers pre-resolve paint.
+    // No anchor div: the iframe-runtime never mounts into a server-
+    // provided container — it appends its own `<ul data-ggui-session-root>`
+    // mount target to `document.body` at boot (iframe-runtime
+    // `status-dom.ts#ensureStatusDom`). The thin postMessage shell's
+    // `#ggui-root` is different: its inline script uses that div for
+    // pre-mount overlays, which this shell has none of (the runtime boots
+    // synchronously from the inline `__GGUI_META__` global).
     return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><title>ggui render</title></head>
-<body>
-<div id="ggui-root" data-ggui-shell="self-contained"></div>
+<html lang="en" style="background-color:${GGUI_RENDER_SHELL_SURFACE}"><head><meta charset="utf-8"><title>ggui render</title></head>
+<body style="background-color:${GGUI_RENDER_SHELL_SURFACE}">
 <script>window.__GGUI_META__ = ${json};</script>
 <script type="module" crossorigin="anonymous" src="${safeRuntimeUrl}"></script>
 </body></html>`;
@@ -678,29 +688,27 @@ export function buildSelfContainedShell(opts) {
  *
  * @public
  */
-export function buildSelfContainedLoadingShell(renderId) {
+export function buildSelfContainedLoadingShell(sessionId) {
+    // Standalone served-iframe loading document — same surface-backdrop
+    // paint + gating as the thin/self-contained shells so the canvas is
+    // dark while the render is still in flight (no Safari white flash).
     return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><title>ggui render</title></head>
-<body>
-<div id="ggui-root" data-ggui-shell="loading" data-ggui-render-id="${renderId
+<html lang="en" style="background-color:${GGUI_RENDER_SHELL_SURFACE}"><head><meta charset="utf-8"><title>ggui render</title></head>
+<body style="background-color:${GGUI_RENDER_SHELL_SURFACE}">
+<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 pickComponentFromRender(render) {
+function pickComponentFromGguiSession(render) {
     if (!render)
         return null;
     if (render.type === "mcpApps")
         return null;
     const propsRaw = "props" in render ? render.props : undefined;
-    const props = propsRaw !== undefined &&
-        propsRaw !== null &&
-        typeof propsRaw === "object" &&
-        !Array.isArray(propsRaw)
-        ? propsRaw
-        : undefined;
+    const props = isRecord(propsRaw) ? propsRaw : undefined;
     if (render.type === "system") {
         if (typeof render.kind === "string" && render.kind.length > 0) {
             return {
@@ -724,22 +732,22 @@ function pickComponentFromRender(render) {
     return null;
 }
 /**
- * Register a `ui://ggui/render/{renderId}` resource template. Each
+ * Register a `ui://ggui/render/{sessionId}` resource template. Each
  * `resources/read` request is resolved by looking up the render in the
  * store and returning the self-contained shell with that
  * componentCode inlined.
  *
  * Per-call `_meta.ui.resourceUri` (stamped by `ggui_render.resultMeta`)
- * pins the URI to a specific renderId; hosts fetch THAT URI rather
+ * pins the URI to a specific sessionId; hosts fetch THAT URI rather
  * than the static `ui://ggui/render` one. Both registrations co-exist:
  * legacy postMessage shell at the static URI, self-contained shell at
  * the templated URI.
  *
  * Failure modes:
- *   - Render not found → loading shell (host re-fetches; absent
+ *   - GguiSession not found → loading shell (host re-fetches; absent
  *     render is a transient state immediately after `ggui_render`).
- *   - Render found, no componentCode yet → loading shell.
- *   - Render found, componentCode present → self-contained shell.
+ *   - GguiSession found, no componentCode yet → loading shell.
+ *   - GguiSession found, componentCode present → self-contained shell.
  *
  * Returns nothing; mutates the server in place.
  *
@@ -748,12 +756,12 @@ function pickComponentFromRender(render) {
 export function registerGguiRenderResourceTemplate(server, opts) {
     // TWO templates registered against the same handler core:
     //
-    //   1. Single-segment legacy URI — `ui://ggui/render/{renderId}`.
+    //   1. Single-segment legacy URI — `ui://ggui/render/{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 render miss).
     //
-    //   2. Two-segment resume URI — `ui://ggui/render/{renderId}/
+    //   2. Two-segment resume URI — `ui://ggui/render/{sessionId}/
     //      {blueprintKey}`. Stamped by every render since the resume
     //      contract landed. Carries enough state for the handler to do:
     //      (a) parallel render + blueprint registry lookup (no data
@@ -761,14 +769,14 @@ export function registerGguiRenderResourceTemplate(server, opts) {
     //      the render 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_RENDER_RESOURCE_URI}/{renderId}`, {
+    const legacyTemplate = new ResourceTemplate(`${GGUI_RENDER_RESOURCE_URI}/{sessionId}`, {
         // No list-callback — the resource set is unbounded per render
         // count, and `resources/list` would leak render ids across
         // tenants. Hosts discover specific URIs via per-call `_meta.ui.
         // resourceUri` instead.
         list: undefined,
     });
-    const resumeTemplate = new ResourceTemplate(`${GGUI_RENDER_RESOURCE_URI}/{renderId}/{blueprintKey}`, { list: undefined });
+    const resumeTemplate = new ResourceTemplate(`${GGUI_RENDER_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'`)
@@ -782,7 +790,7 @@ export function registerGguiRenderResourceTemplate(server, opts) {
      * 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
+     * the per-render 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
@@ -816,14 +824,14 @@ export function registerGguiRenderResourceTemplate(server, opts) {
             },
         ],
     });
-    const loadingShell = (uri, renderId) => shellContents(uri, buildSelfContainedLoadingShell(renderId));
+    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 renderIdRaw = variables["renderId"];
-        const renderId = Array.isArray(renderIdRaw) ? renderIdRaw[0] : renderIdRaw;
-        if (typeof renderId !== "string" || renderId.length === 0) {
+        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"];
@@ -836,15 +844,18 @@ export function registerGguiRenderResourceTemplate(server, opts) {
         // is still cached (chat-history rehydrate after render TTL or
         // process restart).
         const [stored, blueprint] = await Promise.all([
-            opts.renderStore.get(renderId),
-            hasResumeKey && opts.vectorStore && opts.defaultAppIdFallback
-                ? findBlueprintExact({ vectorStore: opts.vectorStore }, opts.defaultAppIdFallback, "template", blueprintKey)
+            opts.renderStore.get(sessionId),
+            hasResumeKey && opts.vectorStore && opts.index && opts.defaultAppIdFallback
+                ? findBlueprintExact({ vectorStore: opts.vectorStore, index: opts.index }, opts.defaultAppIdFallback, "template", 
+                // Resume URI carries only a contract hash — omit variantKey
+                // so the lookup resolves the default variant.
+                blueprintKey)
                 : Promise.resolve(null),
         ]);
         // Happy path: render present and renderable. Mount with the live
         // state (current props, current contextSpec values).
         if (stored) {
-            const picked = pickComponentFromRender(stored.render);
+            const picked = pickComponentFromGguiSession(stored.render);
             if (picked) {
                 // Project the active render to the transport-agnostic bootstrap
                 // view — same source of truth the render-mutation handler and
@@ -890,14 +901,14 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                         // validators (server-side gate is authoritative).
                     }
                 }
-                if (!isSystem && codeUrl === undefined) {
-                    // Compiled-component render 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, renderId);
-                }
+                // The codeUrl gate is applied AFTER the live-channel mint below, so
+                // a render with no static codeUrl still mounts via live-mode
+                // (wsUrl + wsToken) instead of stalling on the loading shell —
+                // parity with the `/r/<shortCode>` path. (See the gate after the
+                // mint.) This matters for deployments that wire `mintWsToken` but no
+                // `codeStore`/`codeBaseUrl` (e.g. the cloud pod): the agent-server
+                // inlines THIS resource, so without the fallback every cloud render
+                // hung on the dead "Generating UI…" shell.
                 // 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,
@@ -924,33 +935,59 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                 // state).
                 let wsUrl;
                 let wsToken;
+                let wsExpiresAt;
                 if (opts.mintWsToken) {
                     try {
-                        const minted = opts.mintWsToken(renderId, stored.appId);
+                        const minted = opts.mintWsToken(sessionId, stored.appId);
                         wsUrl = minted.wsUrl;
                         wsToken = minted.token;
+                        // Forward the token TTL so the iframe-runtime can degrade to
+                        // static-only mode once it lapses (parity with the render-tool
+                        // slice projection, render.ts). Dropping it left the live-mode
+                        // resource shell unable to know when its WS token expired.
+                        wsExpiresAt = minted.expiresAt;
                     }
                     catch {
                         // Silent — falls back to static-component mode.
                     }
                 }
+                // Mount-mode gate (moved below the live-channel mint): emit the
+                // loading shell ONLY when NEITHER a static codeUrl channel NOR a
+                // live-channel wsToken is available. A deployment that wires no
+                // codeStore (codeUrl === undefined) but DOES wire mintWsToken now
+                // mounts via live-mode rather than hanging on "Generating UI…".
+                if (!isSystem && codeUrl === undefined && (wsUrl === undefined || wsToken === undefined)) {
+                    return loadingShell(uri, sessionId);
+                }
                 const html = buildSelfContainedShell({
-                    renderId,
+                    sessionId,
                     appId: stored.appId,
                     ...(isSystem
                         ? { systemKind: picked.kind }
-                        : {
-                            codeUrl: codeUrl,
-                            ...(codeHash !== undefined ? { codeHash } : {}),
-                        }),
+                        : codeUrl !== undefined
+                            ? {
+                                codeUrl,
+                                ...(codeHash !== undefined ? { codeHash } : {}),
+                            }
+                            : // No static codeUrl → live-mode (wsUrl + token spread below)
+                                // carries the render; buildSelfContainedShell accepts
+                                // live-mode without codeUrl.
+                                {}),
                     runtimeUrl: opts.runtimeUrl,
                     ...(wsUrl !== undefined && wsToken !== undefined
-                        ? { wsUrl, token: wsToken }
+                        ? {
+                            wsUrl,
+                            token: wsToken,
+                            ...(wsExpiresAt !== undefined ? { expiresAt: wsExpiresAt } : {}),
+                        }
                         : {}),
                     ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
                     ...(opts.themeMode !== undefined ? { themeMode: opts.themeMode } : {}),
+                    // Per-app theme overlay projected by `deriveRenderMeta` from
+                    // the render's `theme` sidecar — forwarded so the
+                    // resource-served iframe matches the postMessage path.
+                    ...(view.theme !== undefined ? { theme: view.theme } : {}),
                     ...(view.propsJson !== undefined ? { propsJson: view.propsJson } : {}),
-                    ...(view.actionNextSteps !== undefined ? { actionNextSteps: view.actionNextSteps } : {}),
                     ...(view.contextSlots !== undefined ? { contextSlots: view.contextSlots } : {}),
                     ...(view.permissionsPolicy !== undefined
                         ? { permissionsPolicy: view.permissionsPolicy }
@@ -988,7 +1025,7 @@ export function registerGguiRenderResourceTemplate(server, opts) {
         // shell.
         if (blueprint && opts.defaultAppIdFallback) {
             const html = await buildShellFromBlueprint({
-                renderId,
+                sessionId,
                 appId: opts.defaultAppIdFallback,
                 blueprint,
                 runtimeUrl: opts.runtimeUrl,
@@ -1002,16 +1039,16 @@ export function registerGguiRenderResourceTemplate(server, opts) {
             }
             // Fallthrough to loading shell when codeStore isn't wired.
         }
-        return loadingShell(uri, renderId);
+        return loadingShell(uri, sessionId);
     }
     server.registerResource("ggui-render-self-contained", legacyTemplate, {
         title: "ggui render (self-contained, legacy URI)",
         description: "Per-render self-contained shell — single-segment URI shape predating the resume contract. Falls back to loading shell when the render is gone (no blueprintKey to do registry-only render).",
         mimeType: GGUI_RENDER_RESOURCE_MIME,
     }, handle);
-    server.registerResource("ggui-session-self-contained-resume", resumeTemplate, {
+    server.registerResource("ggui-render-self-contained-resume", resumeTemplate, {
         title: "ggui render (self-contained, resume URI)",
-        description: "Per-render self-contained shell — two-segment URI shape carrying both renderId AND blueprintKey. Resource handler runs Promise.all over render + registry; falls back to registry-only static render when the render has been evicted but the blueprint is still cached.",
+        description: "Per-render self-contained shell — two-segment URI shape carrying both sessionId AND blueprintKey. Resource handler runs Promise.all over render + registry; falls back to registry-only static render when the render has been evicted but the blueprint is still cached.",
         mimeType: GGUI_RENDER_RESOURCE_MIME,
     }, handle);
 }
@@ -1039,9 +1076,6 @@ async function buildShellFromBlueprint(args) {
         : 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 {
@@ -1054,7 +1088,7 @@ async function buildShellFromBlueprint(args) {
         return undefined;
     }
     return buildSelfContainedShell({
-        renderId: args.renderId,
+        sessionId: args.sessionId,
         appId: args.appId,
         codeUrl,
         codeHash,
@@ -1063,7 +1097,6 @@ async function buildShellFromBlueprint(args) {
         ...(args.themeMode !== undefined ? { themeMode: args.themeMode } : {}),
         ...(propsJson !== undefined ? { propsJson } : {}),
         ...(contextSlots !== undefined ? { contextSlots } : {}),
-        ...(actionNextSteps !== undefined ? { actionNextSteps } : {}),
     });
 }
 function deriveDefaultPropsValues(spec) {
@@ -1100,18 +1133,6 @@ function deriveDefaultContextSlots(spec) {
     }
     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/render` resource. The
@@ -1119,7 +1140,7 @@ function deriveWiredActionToolsFromSpec(spec) {
  * one line.
  *
  * When `selfContained` is supplied, ALSO registers the per-render
- * `ui://ggui/render/{renderId}` resource template that serves the
+ * `ui://ggui/render/{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.