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

package/dist/mcp-apps-outbound.js

@@ -1,16 +1,16 @@
 /**
  * MCP Apps outbound wiring — the server-side half of the
- * `ggui_push -> ui://ggui/session -> iframe -> live channel` delivery path.
+ * `ggui_render -> ui://ggui/render -> 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
+ *   2. Register `ui://ggui/render` 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.
+ *      `ggui_render` result.
  *
  * Boundary discipline:
  *
@@ -31,28 +31,29 @@
  *   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';
+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 { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerAppResource } from "@modelcontextprotocol/ext-apps/server";
+import { createHash } from "node:crypto";
 /**
- * Thin-shell body served from `ui://ggui/session` (C8 pivot).
+ * 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
- * `_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,
+ * 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.
  *
  * **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.
+ * 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
+ * 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
@@ -70,7 +71,8 @@ import { MCP_APPS_UI_CAPABILITY, GGUI_SESSION_RESOURCE_URI, GGUI_SESSION_RESOURC
  * `postMessage({type:'ggui:bootstrap-failed', reason, message}, '*')`:
  *
  *   - `BOOTSTRAP_META_MISSING` - `ui/initialize` returned without a
- *     valid `_meta.ggui.bootstrap` OR without a `runtimeUrl` field.
+ *     valid `ai.ggui/render` slice OR without a `runtimeUrl` field on
+ *     it.
  *   - `BUNDLE_FETCH_FAILED` - `<script src>` errored (network failure,
  *     404, CSP reject with an observable `error` event).
  *
@@ -117,19 +119,30 @@ import { MCP_APPS_UI_CAPABILITY, GGUI_SESSION_RESOURCE_URI, GGUI_SESSION_RESOURC
  * `mcp-apps-outbound.test.ts` drift test recomputes the hash and fails
  * loudly if they diverge.
  */
-const GGUI_SESSION_SHELL_SCRIPT_BODY = `
+const GGUI_RENDER_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.
+// 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.
 // 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.
+//
+// R5 (2026-05-26): the historic /r/<shortCode> HTTP fallback was
+// removed along with the bearer-by-obscurity model -- hosts that strip
+// _meta no longer have a recovery path here. Spec-canonical hosts
+// deliver _meta inline and are unaffected.
+//
+// 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.
 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';
@@ -148,29 +161,6 @@ function postRpc(method,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
@@ -179,24 +169,23 @@ function postBootstrapFailed(reason,message){
   // times out. Reason codes match BootstrapFailureReason.
   try{window.parent.postMessage({type:'ggui:bootstrap-failed',reason:reason,message:message},'*');}catch(e){}
 }
-async function mountFromBootstrap(bootstrap){
+async function mountFromMeta(envelope){
   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'){
+  // Slice envelope shape (Phase B): { "ai.ggui/render": { renderId,
+  // 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
+  // optional; the runtime decides at boot time based on the meta
+  // it reads from window.__GGUI_META__.
+  var renderSlice=envelope&&envelope['ai.ggui/render'];
+  var runtimeUrl=renderSlice&&renderSlice.runtimeUrl;
+  if(!envelope||typeof runtimeUrl!=='string'){
     setOverlay('Bootstrap payload malformed.');
     postBootstrapFailed('BOOTSTRAP_MALFORMED','Bootstrap payload malformed.');
     return;
   }
   setOverlay('Loading UI…');
-  window.__GGUI_BOOTSTRAP__=bootstrap;
+  window.__GGUI_META__=envelope;
   // 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
@@ -216,7 +205,7 @@ async function mountFromBootstrap(bootstrap){
     // console -- the bundle ships ACAO=* so credentialed mode is
     // unnecessary.
     s.crossOrigin='anonymous';
-    s.src=bootstrap.runtimeUrl;
+    s.src=runtimeUrl;
     s.onload=function(){mounted=true;};
     s.onerror=function(e){
       var msg='Runtime bundle failed to load: '+(e&&e.message||'script error');
@@ -231,56 +220,34 @@ async function mountFromBootstrap(bootstrap){
     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){
+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;
-  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;
+  // 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 hasGguiMetaPlaceholder(result){
+function hasAiGguiMetaPlaceholder(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.
+  // "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;
-  var ggui=meta.ggui;
-  return !!ggui&&typeof ggui==='object';
+  return 'ai.ggui/render' in meta;
 }
-function readBootstrapFromCallToolResult(params){
+function readMetaFromCallToolResult(params){
   // MCP Apps spec (specification/2026-01-26/apps.mdx:1145-1155):
   //   ui/notifications/tool-result
   //   params: CallToolResult  // Standard MCP type
@@ -288,20 +255,14 @@ function readBootstrapFromCallToolResult(params){
   // 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.
+  // slice-envelope 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;
+  var renderSlice=meta['ai.ggui/render'];
+  if(!renderSlice||typeof renderSlice!=='object')return null;
+  if(typeof renderSlice.runtimeUrl!=='string')return null;
+  return meta;
 }
 window.addEventListener('message',function(ev){
   var m=ev&&ev.data;
@@ -315,20 +276,19 @@ window.addEventListener('message',function(ev){
     // 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
+    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=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);
+    var bb=readMetaFromInitResult(m.params);
+    if(bb){mountFromMeta(bb);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.
   }
 });
 setOverlay('Initializing…');
@@ -342,26 +302,24 @@ postRpc('ui/initialize',{
 }).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
+  // 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=readBootstrapFromInitResult(result);
-  if(b){mountFromBootstrap(b);return;}
+  var b=readMetaFromInitResult(result);
+  if(b){mountFromMeta(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';
+  // (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-bootstrap convention land here.
+  // implement the reading-B inline-meta convention land here.
   setOverlay('Waiting for tool result…');
 }).catch(function(e){
   clearTimeout(initTimer);
@@ -369,13 +327,13 @@ postRpc('ui/initialize',{
 });
 })();
 `;
-export const GGUI_SESSION_SHELL_HTML = `<!doctype html>
-<html lang="en" style="height:100%"><head><meta charset="utf-8"><title>ggui session</title></head>
+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>
-<script>${GGUI_SESSION_SHELL_SCRIPT_BODY}</script></body></html>`;
+<script>${GGUI_RENDER_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
+ * `<script>` block of {@link GGUI_RENDER_SHELL_HTML} when it executes
  * inside an iframe whose CSP is inherited from a parent host.
  *
  * # Why this exists
@@ -412,11 +370,11 @@ export const GGUI_SESSION_SHELL_HTML = `<!doctype html>
  * 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')}'`;
+export const GGUI_RENDER_SHELL_SCRIPT_HASH = `'sha256-${createHash("sha256")
+    .update(GGUI_RENDER_SHELL_SCRIPT_BODY)
+    .digest("base64")}'`;
 /**
- * Register `ui://ggui/session` as a readable resource on an `McpServer`.
+ * 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.
@@ -448,13 +406,27 @@ export const GGUI_SESSION_SHELL_SCRIPT_HASH = `'sha256-${createHash('sha256')
  * 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)
+function buildCspMeta(publicBaseUrl, 
+/**
+ * Local-dev fallback: when `publicBaseUrl` is absent (first-party
+ * 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.
+ *
+ * Without this fallback, local dev with cross-origin sandbox proxies
+ * (sample-agent's `:7790/sandbox.html` writing the canvas HTML that
+ * references `:6786/_ggui/iframe-runtime.js`) trips a `script-src`
+ * violation that blanks the iframe — verified live 2026-05-27.
+ */
+runtimeUrl) {
+    const source = publicBaseUrl ?? runtimeUrl;
+    if (!source)
         return undefined;
     try {
-        const parsed = new URL(publicBaseUrl);
+        const parsed = new URL(source);
         const origin = parsed.origin;
-        const wsScheme = parsed.protocol === 'https:' ? 'wss:' : 'ws:';
+        const wsScheme = parsed.protocol === "https:" ? "wss:" : "ws:";
         const wsOrigin = `${wsScheme}//${parsed.host}`;
         return {
             ui: {
@@ -469,7 +441,7 @@ function buildCspMeta(publicBaseUrl) {
         return undefined;
     }
 }
-export function registerGguiSessionResource(server, shellHtml = GGUI_SESSION_SHELL_HTML, publicBaseUrl) {
+export function registerGguiRenderResource(server, shellHtml = GGUI_RENDER_SHELL_HTML, publicBaseUrl) {
     let cspMeta;
     if (publicBaseUrl) {
         try {
@@ -484,7 +456,7 @@ export function registerGguiSessionResource(server, shellHtml = GGUI_SESSION_SHE
             // 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 wsScheme = parsed.protocol === "https:" ? "wss:" : "ws:";
             const wsOrigin = `${wsScheme}//${parsed.host}`;
             cspMeta = {
                 ui: {
@@ -503,17 +475,23 @@ export function registerGguiSessionResource(server, shellHtml = GGUI_SESSION_SHE
             cspMeta = undefined;
         }
     }
-    server.registerResource('ggui-session', GGUI_SESSION_RESOURCE_URI, {
+    // `registerAppResource` (from `@modelcontextprotocol/ext-apps/server`)
+    // defaults `mimeType` to `RESOURCE_MIME_TYPE` — the same
+    // `text/html;profile=mcp-app` value `GGUI_RENDER_RESOURCE_MIME`
+    // carries. Letting the canonical helper own the default means the
+    // mimeType string lives in ONE place across the ecosystem (the SDK)
+    // rather than duplicated in our protocol package.
+    registerAppResource(server, "ggui-render", GGUI_RENDER_RESOURCE_URI, {
         // `title` / `description` show up in MCP clients that surface
         // resource metadata. Short + concrete.
-        title: 'ggui 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,
+        title: "ggui render",
+        description: "Thin-shell iframe bundle that bootstraps a ggui render. MCP Apps hosts fetch this when they see `_meta.ui.resourceUri` on a ggui_render result.",
+        mimeType: GGUI_RENDER_RESOURCE_MIME,
     }, async (uri) => ({
         contents: [
             {
                 uri: uri.href,
-                mimeType: GGUI_SESSION_RESOURCE_MIME,
+                mimeType: GGUI_RENDER_RESOURCE_MIME,
                 text: shellHtml,
                 ...(cspMeta !== undefined ? { _meta: cspMeta } : {}),
             },
@@ -542,7 +520,7 @@ export function advertiseMcpAppsUiCapability(server) {
  * 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__`
+ * compiled component (base64) + session ids 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
@@ -569,79 +547,41 @@ export function buildSelfContainedShell(opts) {
     // (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');
-    }
+    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;
     if (!isSystem && !hasCodeUrl && !hasLive) {
-        throw new Error('buildSelfContainedShell: at least one of `codeUrl`, `systemKind`, or live-mode (`wsUrl` + `token`) must be set');
+        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,
+    // Build the single render slice (Phase B: ai.ggui/render collapsed
+    // the prior ai.ggui/session + ai.ggui/stack-item pair into one flat
+    // shape). The inline global carries the SAME shape as the wire
+    // `_meta` envelope so the iframe-runtime's `parseMetaFromGlobal`
+    // defers to the same `parseMcpAppAiGguiRenderMeta` parser the
+    // postMessage paths use. `runtimeUrl` is required across all modes
+    // (the shell-bundled script tag fetches the runtime from there).
+    const render = {
+        renderId: opts.renderId,
         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.
+        // Symmetric with the `ai.ggui/render` wire-slice `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 }
-            : {}),
+        ...(opts.gadgets !== undefined && opts.gadgets.length > 0 ? { gadgets: opts.gadgets } : {}),
         // Server-filtered public env values that declared wrappers'
         // `requires` cover. Symmetric forward; without it, wrappers
         // calling `getPublicEnv()` throw at hook-mount on the
@@ -649,14 +589,54 @@ export function buildSelfContainedShell(opts) {
         ...(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
+        // Live-mode trio. The iframe-runtime rejects half-live envelopes
+        // (`wsUrl XOR wsToken` 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.
+        // but is part of the live trio at emit time. The `opts.token`
+        // input is renamed to `wsToken` on the slice for wire-field parity.
         ...(opts.wsUrl !== undefined ? { wsUrl: opts.wsUrl } : {}),
-        ...(opts.token !== undefined ? { token: opts.token } : {}),
+        ...(opts.token !== undefined ? { wsToken: opts.token } : {}),
         ...(opts.expiresAt !== undefined ? { expiresAt: opts.expiresAt } : {}),
+        // Polling fallback URL — lights up `@ggui-ai/live-channel`'s
+        // events-polling transport when WS is unavailable. Absent ⇒
+        // WS-only mode (legacy behavior). See SelfContainedShellInputs
+        // .pollingUrl for the URL shape.
+        ...(opts.pollingUrl !== undefined ? { pollingUrl: opts.pollingUrl } : {}),
+        ...(opts.lastSequence !== undefined ? { lastSequence: opts.lastSequence } : {}),
+        // Visible-bits surface — what the iframe is mounting right now.
+        // Static-content discriminators (codeUrl / kind) are mutually
+        // exclusive; the iframe-runtime rejects the both-set mix.
+        ...(isSystem ? { kind: opts.systemKind } : {}),
+        ...(!isSystem && hasCodeUrl
+            ? {
+                codeUrl: opts.codeUrl,
+                ...(opts.codeHash !== undefined ? { codeHash: opts.codeHash } : {}),
+            }
+            : {}),
+        ...(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 }
+            : {}),
+        // Content-addressable contract-validator bundle. Iframe-runtime
+        // fetches `validatorsUrl` + dynamic-imports to resolve
+        // validators. Omitted when the contract declares no
+        // runtime-validated schema OR when the server has no CodeStore
+        // wired for the bundle write.
+        ...(opts.contractHash !== undefined && opts.validatorsUrl !== undefined
+            ? {
+                contractHash: opts.contractHash,
+                validatorsUrl: opts.validatorsUrl,
+            }
+            : {}),
+    };
+    // Same wire shape as `_meta` — the iframe-runtime's global parser
+    // reuses `parseMcpAppAiGguiRenderMeta` for the single render slice.
+    const bootstrap = {
+        [MCP_APP_AI_GGUI_RENDER_META_KEY]: render,
     };
     // JSON.stringify produces valid JS, but `<` / `>` / `&` / `U+2028`
     // / `U+2029` can break HTML or JS parsers when embedded inline.
@@ -664,131 +644,131 @@ export function buildSelfContainedShell(opts) {
     // 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');
+        .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;');
+        .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>
+<html lang="en"><head><meta charset="utf-8"><title>ggui render</title></head>
 <body>
 <div id="ggui-root" data-ggui-shell="self-contained"></div>
-<script>window.__GGUI_BOOTSTRAP__ = ${json};</script>
+<script>window.__GGUI_META__ = ${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
+ * Minimal "loading" HTML served when a per-render resource is fetched
+ * for a render whose visible-bits surface 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
+ * Hosts SHOULD re-fetch when they observe additional `ggui_render`
+ * results on the same render — the per-call `_meta.ui.resourceUri`
+ * value stays stable across commits for a render, so re-fetching the
  * same URI returns fresher HTML on the second try.
  *
  * @public
  */
-export function buildSelfContainedLoadingShell(sessionId) {
+export function buildSelfContainedLoadingShell(renderId) {
     return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><title>ggui session</title></head>
+<html lang="en"><head><meta charset="utf-8"><title>ggui render</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>
+<div id="ggui-root" data-ggui-shell="loading" data-ggui-render-id="${renderId
+        .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) {
+function pickComponentFromRender(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;
+    if (render.type === "system") {
+        if (typeof render.kind === "string" && render.kind.length > 0) {
             return {
-                id: entry.id,
-                componentCode: code,
+                id: render.id,
+                kind: render.kind,
                 ...(props !== undefined ? { props } : {}),
-                source: entry,
+                source: render,
             };
         }
+        return null;
+    }
+    const code = render.componentCode;
+    if (typeof code === "string" && code.length > 0) {
+        return {
+            id: render.id,
+            componentCode: code,
+            ...(props !== undefined ? { props } : {}),
+            source: render,
+        };
     }
     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.
+ * Register a `ui://ggui/render/{renderId}` 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_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:
+ * Per-call `_meta.ui.resourceUri` (stamped by `ggui_render.resultMeta`)
+ * pins the URI to a specific renderId; 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:
- *   - 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.
+ *   - Render 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.
  *
  * Returns nothing; mutates the server in place.
  *
  * @public
  */
-export function registerGguiSessionResourceTemplate(server, opts) {
+export function registerGguiRenderResourceTemplate(server, opts) {
     // TWO templates registered against the same handler core:
     //
-    //   1. Single-segment legacy URI — `ui://ggui/session/{sessionId}`.
+    //   1. Single-segment legacy URI — `ui://ggui/render/{renderId}`.
     //      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).
+    //      still rehydrate (loading shell on render miss).
     //
-    //   2. Two-segment resume URI — `ui://ggui/session/{sessionId}/
-    //      {blueprintKey}`. Stamped by every push since the resume
+    //   2. Two-segment resume URI — `ui://ggui/render/{renderId}/
+    //      {blueprintKey}`. Stamped by every render since the resume
     //      contract landed. Carries enough state for the handler to do:
-    //      (a) parallel session + blueprint registry lookup (no data
+    //      (a) parallel render + blueprint registry lookup (no data
     //      dependency between them), (b) registry-only fallback when
-    //      the session is gone but the blueprint is still cached
+    //      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_SESSION_RESOURCE_URI}/{sessionId}`, {
-        // No list-callback — the resource set is unbounded per session
-        // count, and `resources/list` would leak session ids across
+    const legacyTemplate = new ResourceTemplate(`${GGUI_RENDER_RESOURCE_URI}/{renderId}`, {
+        // 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_SESSION_RESOURCE_URI}/{sessionId}/{blueprintKey}`, { list: undefined });
+    const resumeTemplate = new ResourceTemplate(`${GGUI_RENDER_RESOURCE_URI}/{renderId}/{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'`)
@@ -796,8 +776,8 @@ export function registerGguiSessionResourceTemplate(server, opts) {
     // 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);
+    // `ui://ggui/render` resource; this is the per-call mirror.
+    const templateCspMeta = buildCspMeta(opts.publicBaseUrl, opts.runtimeUrl);
     /**
      * Merge gadget-declared origins from
      * {@link deriveBundleOrigins} into the base `templateCspMeta`. The
@@ -816,10 +796,7 @@ export function registerGguiSessionResourceTemplate(server, opts) {
         return {
             ui: {
                 csp: {
-                    connectDomains: [
-                        ...templateCspMeta.ui.csp.connectDomains,
-                        ...gadgetOrigins.connect,
-                    ],
+                    connectDomains: [...templateCspMeta.ui.csp.connectDomains, ...gadgetOrigins.connect],
                     resourceDomains: [
                         ...templateCspMeta.ui.csp.resourceDomains,
                         ...gadgetOrigins.script,
@@ -833,117 +810,93 @@ export function registerGguiSessionResourceTemplate(server, opts) {
         contents: [
             {
                 uri: uri.href,
-                mimeType: GGUI_SESSION_RESOURCE_MIME,
+                mimeType: GGUI_RENDER_RESOURCE_MIME,
                 text,
                 ...(cspMeta !== undefined ? { _meta: cspMeta } : {}),
             },
         ],
     });
-    const loadingShell = (uri, sessionId) => shellContents(uri, buildSelfContainedLoadingShell(sessionId));
+    const loadingShell = (uri, renderId) => shellContents(uri, buildSelfContainedLoadingShell(renderId));
     // 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 renderIdRaw = variables["renderId"];
+        const renderId = Array.isArray(renderIdRaw) ? renderIdRaw[0] : renderIdRaw;
+        if (typeof renderId !== "string" || renderId.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),
+        const blueprintKeyRaw = variables["blueprintKey"];
+        const blueprintKey = Array.isArray(blueprintKeyRaw) ? blueprintKeyRaw[0] : blueprintKeyRaw;
+        const hasResumeKey = typeof blueprintKey === "string" && blueprintKey.length > 0;
+        // Parallel lookup. The render and the blueprint registry are
+        // independent — even though the render's componentCode could feed
+        // the renderable directly, we ALSO want the blueprint entry as a
+        // registry-only fallback when the render is gone but the blueprint
+        // 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)
+                ? 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
+        // Happy path: render present and renderable. Mount with the live
+        // state (current props, current contextSpec values).
+        if (stored) {
+            const picked = pickComponentFromRender(stored.render);
+            if (picked) {
+                // Project the active render to the transport-agnostic bootstrap
+                // view — same source of truth the render-mutation handler 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.
+                const view = deriveRenderMeta(picked.source);
+                const isSystem = picked.kind !== undefined;
+                // Static-component delivery via codeUrl. 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;
+                let contractHash;
+                let validatorsUrl;
                 if (!isSystem && opts.codeStore && opts.codeBaseUrl) {
                     try {
-                        const hash = opts.codeStore.hashOf(top.componentCode);
-                        await opts.codeStore.put(hash, top.componentCode);
+                        const hash = opts.codeStore.hashOf(picked.componentCode);
+                        await opts.codeStore.put(hash, picked.componentCode);
                         codeHash = hash;
-                        const base = opts.codeBaseUrl.replace(/\/$/, '');
+                        const base = opts.codeBaseUrl.replace(/\/$/, "");
                         codeUrl = `${base}/code/${hash}.js`;
                     }
                     catch {
                         // Silent — falls through to loading shell below.
                     }
+                    // Content-addressable contract-validator bundle (#109).
+                    try {
+                        const bundle = await deriveContractBundle(picked.source);
+                        if (bundle) {
+                            await opts.codeStore.put(bundle.contractHash, bundle.bundleSource);
+                            contractHash = bundle.contractHash;
+                            const base = opts.codeBaseUrl.replace(/\/$/, "");
+                            validatorsUrl = `${base}/contract/${bundle.contractHash}.js`;
+                        }
+                    }
+                    catch {
+                        // Silent — bundle write failure degrades to no client-side
+                        // validators (server-side gate is authoritative).
+                    }
                 }
                 if (!isSystem && codeUrl === undefined) {
-                    // Compiled-component item but no codeUrl channel available —
-                    // emit the loading shell so the operator can refresh once
+                    // 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, sessionId);
+                    return loadingShell(uri, renderId);
                 }
                 // Project the wrapper catalog AND the union-filtered
                 // publicEnv onto the inline bootstrap so the resource-served
@@ -953,47 +906,66 @@ export function registerGguiSessionResourceTemplate(server, opts) {
                 let resourcePublicEnv;
                 if (opts.appMetadataStore) {
                     try {
-                        const appRecord = await opts.appMetadataStore.get(session.appId);
-                        resourcePublicEnv = derivePublicEnvProjection(top.source, appRecord?.publicEnv);
+                        const appRecord = await opts.appMetadataStore.get(stored.appId);
+                        resourcePublicEnv = derivePublicEnvProjection(picked.source, appRecord?.publicEnv);
                     }
                     catch {
                         // Silent — wrappers calling getPublicEnv throw clearly.
                     }
                 }
+                // Live-channel bootstrap — when the operator wired
+                // {@link GguiRenderResourceTemplateOptions.mintWsToken}, mint a
+                // wsToken for this render so the iframe-runtime opens a
+                // WebSocket on mount and receives `props_update` frames.
+                // Without this, the resource shell renders in static-component
+                // mode only — `ggui_update` server-side mutations never
+                // visibly reach the live iframe (hosts must re-fetch
+                // `resources/read` after every update tool result to see new
+                // state).
+                let wsUrl;
+                let wsToken;
+                if (opts.mintWsToken) {
+                    try {
+                        const minted = opts.mintWsToken(renderId, stored.appId);
+                        wsUrl = minted.wsUrl;
+                        wsToken = minted.token;
+                    }
+                    catch {
+                        // Silent — falls back to static-component mode.
+                    }
+                }
                 const html = buildSelfContainedShell({
-                    sessionId,
-                    appId: session.appId,
+                    renderId,
+                    appId: stored.appId,
                     ...(isSystem
-                        ? { systemKind: top.kind }
+                        ? { systemKind: picked.kind }
                         : {
                             codeUrl: codeUrl,
                             ...(codeHash !== undefined ? { codeHash } : {}),
                         }),
                     runtimeUrl: opts.runtimeUrl,
-                    stackItemId: top.id,
+                    ...(wsUrl !== undefined && wsToken !== undefined
+                        ? { wsUrl, token: wsToken }
+                        : {}),
                     ...(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.actionNextSteps !== undefined ? { actionNextSteps: view.actionNextSteps } : {}),
+                    ...(view.contextSlots !== undefined ? { contextSlots: view.contextSlots } : {}),
                     ...(view.permissionsPolicy !== undefined
                         ? { permissionsPolicy: view.permissionsPolicy }
                         : {}),
-                    ...(view.gadgets !== undefined &&
-                        view.gadgets.length > 0
+                    ...(view.gadgets !== undefined && view.gadgets.length > 0
                         ? { gadgets: view.gadgets }
                         : {}),
-                    ...(view.compiledValidators !== undefined
-                        ? { compiledValidators: view.compiledValidators }
+                    ...(contractHash !== undefined && validatorsUrl !== undefined
+                        ? { contractHash, validatorsUrl }
                         : {}),
-                    ...(resourcePublicEnv !== undefined &&
-                        Object.keys(resourcePublicEnv).length > 0
+                    ...(resourcePublicEnv !== undefined && Object.keys(resourcePublicEnv).length > 0
                         ? { publicEnv: resourcePublicEnv }
                         : {}),
+                    // R6 — ledger cursor stamp for polling-cursor alignment.
+                    lastSequence: stored.eventSequence,
                 });
                 // Augment per-call CSP with gadget-declared bundle / style /
                 // API origins. Without this, claude.ai's iframe CSP only allows
@@ -1004,11 +976,11 @@ export function registerGguiSessionResourceTemplate(server, opts) {
                 // "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);
+                const gadgetOrigins = deriveBundleOrigins(picked.source);
                 return shellContents(uri, html, augmentCspMeta(gadgetOrigins));
             }
         }
-        // Registry-only fallback: session is gone (TTL / restart) but the
+        // Registry-only fallback: render 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
@@ -1016,7 +988,7 @@ export function registerGguiSessionResourceTemplate(server, opts) {
         // shell.
         if (blueprint && opts.defaultAppIdFallback) {
             const html = await buildShellFromBlueprint({
-                sessionId,
+                renderId,
                 appId: opts.defaultAppIdFallback,
                 blueprint,
                 runtimeUrl: opts.runtimeUrl,
@@ -1030,27 +1002,27 @@ export function registerGguiSessionResourceTemplate(server, opts) {
             }
             // Fallthrough to loading shell when codeStore isn't wired.
         }
-        return loadingShell(uri, sessionId);
+        return loadingShell(uri, renderId);
     }
-    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,
+    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, {
-        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,
+    server.registerResource("ggui-session-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.",
+        mimeType: GGUI_RENDER_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
+ * Synthesize a shell from a registry-only blueprint (no live render).
+ * Used when chat-history rehydrate finds the render evicted but the
  * blueprint registry still holds the entry. Renders the same
- * componentCode the original push generated, seeded with the
+ * componentCode the original commit 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.
+ * values) is lost in this path; that's the cost of render eviction.
  *
  * Internal — exported nowhere because the only safe trigger path is
  * inside the resource handler with the resume URI shape (URI carries
@@ -1062,14 +1034,12 @@ async function buildShellFromBlueprint(args) {
         return undefined;
     }
     const contract = blueprint.contract ?? {};
-    const propsSpec = 'props' in contract && contract.props !== undefined
+    const propsSpec = "props" in contract && contract.props !== undefined
         ? contract.props
         : undefined;
-    const propsJson = propsSpec
-        ? JSON.stringify(deriveDefaultPropsValues(propsSpec))
-        : undefined;
+    const propsJson = propsSpec ? JSON.stringify(deriveDefaultPropsValues(propsSpec)) : undefined;
     const contextSlots = deriveDefaultContextSlots(contract.contextSpec);
-    const actionNextSteps = 'actionSpec' in contract && contract.actionSpec !== undefined
+    const actionNextSteps = "actionSpec" in contract && contract.actionSpec !== undefined
         ? deriveWiredActionToolsFromSpec(contract.actionSpec)
         : undefined;
     let codeUrl;
@@ -1077,14 +1047,14 @@ async function buildShellFromBlueprint(args) {
     try {
         codeHash = args.codeStore.hashOf(blueprint.componentCode);
         await args.codeStore.put(codeHash, blueprint.componentCode);
-        const base = args.codeBaseUrl.replace(/\/$/, '');
+        const base = args.codeBaseUrl.replace(/\/$/, "");
         codeUrl = `${base}/code/${codeHash}.js`;
     }
     catch {
         return undefined;
     }
     return buildSelfContainedShell({
-        sessionId: args.sessionId,
+        renderId: args.renderId,
         appId: args.appId,
         codeUrl,
         codeHash,
@@ -1113,11 +1083,11 @@ function deriveDefaultContextSlots(spec) {
         return undefined;
     const collected = [];
     for (const [name, entry] of Object.entries(spec)) {
-        if (!entry || typeof entry !== 'object')
+        if (!entry || typeof entry !== "object")
             continue;
         if (entry.schema === undefined || entry.schema === null)
             continue;
-        if (typeof entry.schema !== 'object')
+        if (typeof entry.schema !== "object")
             continue;
         const fallback = deriveContextDefault(entry);
         collected.push({
@@ -1134,8 +1104,8 @@ function deriveWiredActionToolsFromSpec(spec) {
     const collected = {};
     for (const [name, entry] of Object.entries(spec)) {
         if (entry &&
-            typeof entry === 'object' &&
-            typeof entry.nextStep === 'string' &&
+            typeof entry === "object" &&
+            typeof entry.nextStep === "string" &&
             entry.nextStep.length > 0) {
             collected[name] = entry.nextStep;
         }
@@ -1144,20 +1114,20 @@ function deriveWiredActionToolsFromSpec(spec) {
 }
 /**
  * Apply the full MCP Apps outbound wiring to a fresh `McpServer` - both
- * the capability advertisement and the `ui://ggui/session` resource. The
+ * the capability advertisement and the `ui://ggui/render` 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
+ * When `selfContained` is supplied, ALSO registers the per-render
+ * `ui://ggui/render/{renderId}` 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);
+    registerGguiRenderResource(server, opts.shellHtml, opts.publicBaseUrl);
     if (opts.selfContained) {
-        registerGguiSessionResourceTemplate(server, opts.selfContained);
+        registerGguiRenderResourceTemplate(server, opts.selfContained);
     }
 }