@ggui-ai/iframe-runtime 0.2.0-alpha.4 → 0.3.0-rc.0

package/dist/runtime.js

@@ -1,3 +1,4 @@
+import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, } from '@ggui-ai/protocol/integrations/mcp-apps';
 import { parseMetaFromGlobal, parseMetaFromToolResult, } from './meta-parse.js';
 import { projectHostContext } from '@ggui-ai/protocol';
 import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
@@ -5,7 +6,7 @@ import { applyHostContextStyling, attachListener as attachHostContextListener, s
 import { buildRootWireConfig, StreamBus, } from './wire-config.js';
 import { createChannelTransportRouter, } from './channel-transport.js';
 import { ChannelRegistry } from '@ggui-ai/live-channel';
-import { createChannelErrorHandler, createChannelPayloadHandler, createDataHandler, createDrainAckHandler, createFeedbackHandler, createPropsUpdateHandler, createRenderHandler, createSystemHandler, } from './channels/index.js';
+import { createChannelErrorHandler, createChannelPayloadHandler, createDataHandler, createDrainAckHandler, createPropsUpdateHandler, createRenderHandler, createSystemHandler, } from './channels/index.js';
 import { connectViaRegistry, } from './registry-subscribe.js';
 import { buildEventsPolling } from './events-polling.js';
 import { ensureStatusDom, setStatus, setConnectedStatus, } from './status-dom.js';
@@ -16,15 +17,7 @@ import { fromBootstrapFailure, } from './protocol-error.js';
 import { postObservabilityToParent, } from './observability.js';
 import { makeLifecycleEvent, postLifecycleToParent, } from './lifecycle.js';
 import { contextSlotLastValues, createContextStateHost, installContextRegistry, reemitLastContextValues, } from './context-observer.js';
-// =============================================================================
-// Build-time-stamped renderer version. Surfaced to the parent in the
-// `ggui:renderer-ready` notification so hosts (and console views)
-// can correlate runtime behavior with a specific bundle.
-//
-// Hard-coded to the package.json version; future build tooling can
-// substitute via esbuild `define` if a non-package value is wanted.
-// =============================================================================
-const RENDERER_VERSION = '0.1.0';
+const RENDERER_VERSION = typeof __GGUI_RUNTIME_VERSION__ === 'string' ? __GGUI_RUNTIME_VERSION__ : 'dev';
 /**
  * How long the spec-canonical postMessage tier (Tier 3 in
  * `bootSequence`'s resolver chain + the autostart resolver's race
@@ -82,7 +75,7 @@ const APP_INFO = { name: 'ggui-iframe-runtime', version: RENDERER_VERSION };
  * `ui/initialize` so spec-compliant hosts know `ui/request-display-mode`
  * requests for these values are honored. The runtime emits
  * `ui/request-display-mode` from the `Element.requestFullscreen`
- * interceptor + the canvas-mode display-mode escalation policy; both
+ * interceptor + the display-mode escalation policy; both
  * target this enum.
  */
 const APP_CAPABILITIES = {
@@ -100,14 +93,14 @@ function createDefaultApp() {
     return { app, transport };
 }
 /**
- * Module-level connected App handle. Set by `bootProduction` /
- * `bootSelfContained` once `app.connect()` resolves; consumed by the
+ * Module-level connected App handle. Set by `bootSequence` once
+ * `app.connect()` resolves; consumed by the
  * outbound dispatch path (`tools/call` via `app.callServerTool`) so
  * spec-compliant frame routing is used in place of the legacy
  * hand-rolled JSON-RPC pump.
  *
  * `null` between the moment the module loads and the moment one of
- * the boot paths assigns it — `dispatchWiredAction`'s callsites are
+ * the boot paths assigns it — `dispatchSubmitAction`'s callsites are
  * gated on this, so calls fired pre-boot drop with a console warning.
  */
 let currentApp = null;
@@ -117,8 +110,8 @@ let currentApp = null;
  * a replace only happens in tests that reuse the module across
  * scenarios (and want each spec to bind its own App).
  *
- * @internal — production callers are the boot paths
- *   (`bootProduction`, `bootSelfContained`); tests inject directly to
+ * @internal — the production caller is `bootSequence` (reached via
+ *   `bootProduction`); tests inject directly to
  *   drive outbound `tools/call` through a `MockTransport`-bound App
  *   without invoking the full boot pipeline.
  */
@@ -165,7 +158,11 @@ async function connectApp(app, transport) {
  */
 function postRendererReady() {
     try {
-        window.parent.postMessage({ type: 'ggui:renderer-ready', version: RENDERER_VERSION }, '*');
+        const envelope = {
+            type: MCP_APP_RENDERER_READY_TYPE,
+            version: RENDERER_VERSION,
+        };
+        window.parent.postMessage(envelope, '*');
     }
     catch {
         // postMessage failure here means the parent is unreachable; the
@@ -177,7 +174,7 @@ function postRendererReady() {
 function postBootFailure(reason, message) {
     try {
         const envelope = {
-            type: 'ggui:bootstrap-failed',
+            type: MCP_APP_BOOTSTRAP_FAILED_TYPE,
             reason,
             message,
         };
@@ -204,7 +201,7 @@ export async function bootSequence(opts) {
     // `onError` callback.
     const emitBootFailure = (reason, message) => {
         notifyParent({
-            type: 'ggui:bootstrap-failed',
+            type: MCP_APP_BOOTSTRAP_FAILED_TYPE,
             // The legacy envelope's reason type is `RendererBootFailureReason`
             // (a subset of `BootstrapFailureReason`). Every value we emit here
             // is a member of that subset; the cast is a narrow-to-narrow
@@ -223,7 +220,7 @@ export async function bootSequence(opts) {
     // `BootSequenceResult`.
     let mountedRender = null;
     setStatus(refs, 'Negotiating with host…', 'connecting');
-    notifyParent({ type: 'ggui:renderer-ready', version: RENDERER_VERSION });
+    notifyParent({ type: MCP_APP_RENDERER_READY_TYPE, version: RENDERER_VERSION });
     // Lifecycle `mounting` — the renderer is alive + status DOM is up,
     // but no IO has run yet. Hosts mirroring lifecycle to outer DOM see
     // this transition concurrent with `ggui:renderer-ready`. Idempotent
@@ -256,7 +253,7 @@ export async function bootSequence(opts) {
         return { ok: false, mountedRender };
     }
     // Connected — expose the App on the module-level slot so outbound
-    // `tools/call` (dispatchWiredAction, channel-transport router)
+    // `tools/call` (dispatchSubmitAction, channel-transport router)
     // routes through `app.callServerTool` instead of the legacy raw
     // postMessage pump. Idempotent: re-boot with the same App is a
     // no-op; a different App throws (the iframe is single-tenant).
@@ -273,7 +270,7 @@ export async function bootSequence(opts) {
     //
     //   Tier 1  parseMetaFromGlobal — synchronous `__GGUI_META__` inline
     //           global. Self-contained shells (`buildSelfContainedHtml`,
-    //           per-session resource shells) populate this before this
+    //           per-render resource shells) populate this before this
     //           bundle's `<script type="module">` evaluates.
     //           Opportunistic — its absence (the common case for
     //           postMessage-delivered hosts) never surfaces as a parse
@@ -351,10 +348,10 @@ export async function bootSequence(opts) {
     setActiveValidatorSet(await loadCompiledValidatorsFromUrl(meta.validatorsUrl));
     // Pin — this iframe binds to exactly one render id for its lifetime
     // (post-render-identity-collapse each iframe = one mounted render,
-    // per [[kill-displaymode-divergence]]). The bootstrap's `renderId`
+    // per [[kill-displaymode-divergence]]). The bootstrap's `sessionId`
     // is the pin; the render handler drops any frame addressed
     // elsewhere.
-    const pinnedRenderId = meta.renderId;
+    const pinnedSessionId = meta.sessionId;
     // Renderer wiring — when supplied, the handler routes frames through
     // the single-render mount surface + WireConfig + StreamBus. When
     // absent, the placeholder path runs (boot.test.ts relies on the
@@ -365,12 +362,12 @@ export async function bootSequence(opts) {
     const renderer = rendererHooks !== undefined
         ? rendererHooks.setup({
             meta,
-            renderInto: refs.stack,
+            renderInto: refs.renderRoot,
             statusRefs: refs,
             ...(onObserve !== undefined ? { onObserve } : {}),
         })
         : null;
-    setStatus(refs, `Connecting to ${meta.renderId}…`, 'connecting');
+    setStatus(refs, `Connecting to ${meta.sessionId}…`, 'connecting');
     // Boot-without-renderer path: we still need a ChannelRegistry to
     // receive frames, because the registry is the only dispatch
     // surface. Build a minimal one with just the `render` placeholder
@@ -381,13 +378,13 @@ export async function bootSequence(opts) {
         ? createPlaceholderRegistry({
             meta,
             statusRefs: refs,
-            pinnedRenderId,
+            pinnedSessionId,
         })
         : null;
     const activeRegistry = renderer?.channelRegistry ?? placeholderRegistry;
     /**
      * Apply an ack's render snapshot to the runtime — when the ack
-     * carries a render matching `pinnedRenderId`, mount it through the
+     * carries a render matching `pinnedSessionId`, mount it through the
      * renderer. Used by:
      *
      *   - The initial bootSequence path (first ack after subscribe).
@@ -399,13 +396,13 @@ export async function bootSequence(opts) {
      * Idempotent on identical inputs — `applyRender` patches in place
      * via {@link RenderItemHandle.update} when called with the same
      * render id; `channelTransport.applyRender` is server-side
-     * idempotent on the (renderId, channelName) tuple.
+     * idempotent on the (sessionId, channelName) tuple.
      */
     const applyAck = async (ackPayload) => {
-        const target = ackPayload.render;
+        const target = ackPayload.session;
         if (target === undefined)
             return;
-        if (target.id !== pinnedRenderId) {
+        if (target.id !== pinnedSessionId) {
             // Server's snapshot is for a different render — likely a stale
             // re-subscribe after the server pruned ours. Nothing to mount.
             return;
@@ -415,7 +412,7 @@ export async function bootSequence(opts) {
             await renderer.applyRender(target);
             if (target.type !== 'mcpApps' && target.type !== 'system') {
                 renderer.channelTransport.applyRender({
-                    renderId: target.id,
+                    sessionId: target.id,
                     ...(target.streamSpec !== undefined
                         ? { streamSpec: target.streamSpec }
                         : {}),
@@ -432,7 +429,7 @@ export async function bootSequence(opts) {
         if (codeReadyEmitted)
             return;
         codeReadyEmitted = true;
-        onLifecycle?.(makeLifecycleEvent('code-ready', { renderId: meta.renderId }));
+        onLifecycle?.(makeLifecycleEvent('code-ready', { sessionId: meta.sessionId }));
     };
     // Mode discriminators. The mount surface is DECOUPLED from the live
     // channel: static content (codeUrl/kind) paints immediately with no WS;
@@ -450,7 +447,7 @@ export async function bootSequence(opts) {
     // ggui live channel (claude.ai / ChatGPT / Claude Desktop), AND the
     // instant first paint for first-party hosts that ALSO open a WS (the
     // WS ack then reconciles in place — `applyRender` is idempotent on the
-    // pinned renderId, and the ack's componentCode is byte-identical to the
+    // pinned sessionId, and the ack's componentCode is byte-identical to the
     // seed's `codeUrl` bytes, so it's a props-only update, no remount).
     if (renderer !== null && hasStaticContent) {
         // Await the 3rd-party gadget merge before first paint when the
@@ -462,7 +459,7 @@ export async function bootSequence(opts) {
         }
         let seed = null;
         try {
-            seed = await buildRenderSeedInput(meta);
+            seed = await buildGguiSessionSeedInput(meta);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -504,7 +501,7 @@ export async function bootSequence(opts) {
         // (no-op) echo. WS hosts get the real echo on the live-trio path below.
         if (parsed.hostContext !== undefined) {
             seedHostContext({
-                renderId: meta.renderId,
+                sessionId: meta.sessionId,
                 send: () => { },
                 initial: parsed.hostContext,
             });
@@ -534,9 +531,8 @@ export async function bootSequence(opts) {
             // + version + protocol errors on its own, we just plumb them
             // along.
             ...(onProtocolError !== undefined ? { onProtocolError } : {}),
-            // Forward observability emissions (schema-version-mismatch,
-            // subscribe-failed). The renderer owns `contract-error-emitted`
-            // via the data channel handler; connectFn owns the other two.
+            // Forward observability emissions — connectFn owns the
+            // schema-version-mismatch + subscribe-failed kinds.
             ...(onObserve !== undefined ? { onObserve } : {}),
             // Reconnect-with-rebootstrap — on every ack received AFTER the
             // initial handshake settled, reapply the server's authoritative
@@ -547,7 +543,7 @@ export async function bootSequence(opts) {
             },
             // R7 — registry-level events-polling fallback. Composed once at
             // bind time from `meta.pollingUrl` (server-stamped wsToken-
-            // gated /api/renders/<id>/events URL) + `meta.lastSequence`
+            // gated /api/sessions/<id>/events URL) + `meta.lastSequence`
             // (cursor seed). FailoverHandle uses this when WS reaches
             // 'failed'; absent → no polling fallback (WS-only mode).
             //
@@ -599,7 +595,7 @@ export async function bootSequence(opts) {
         return { ok: false, mountedRender };
     }
     // Attach the live transport handle to the renderer — flushes any
-    // buffered outbound frames (feedback / action) that were queued
+    // buffered outbound `action` frames that were queued
     // while the subscribe handshake completed. `handle.handle.send` is
     // the canonical send surface for the bound WS transport.
     if (renderer !== null && rendererHooks?.attachManager !== undefined) {
@@ -613,7 +609,7 @@ export async function bootSequence(opts) {
     // didn't emit a HostContext (parsed.hostContext === undefined).
     if (parsed.hostContext !== undefined) {
         seedHostContext({
-            renderId: meta.renderId,
+            sessionId: meta.sessionId,
             send: (msg) => handle.handle.send(msg),
             initial: parsed.hostContext,
         });
@@ -624,7 +620,7 @@ export async function bootSequence(opts) {
         attachHostContextListener({ app });
     }
     // First ack — apply the server's render snapshot (when matching
-    // `pinnedRenderId`) and mount it. Reuses the same `applyAck` helper
+    // `pinnedSessionId`) and mount it. Reuses the same `applyAck` helper
     // the reconnect-rebootstrap path uses — so a server-restart-driven
     // snapshot replay and the first-boot snapshot apply flow through
     // one implementation.
@@ -641,7 +637,7 @@ export async function bootSequence(opts) {
 /**
  * Build a minimal `ChannelRegistry` for boot paths without renderer
  * wiring (boot.test.ts + the C7a placeholder-only spec). The registry
- * carries just the `push` handler — which logs status but does not
+ * carries just the `render` handler — which logs status but does not
  * mount React — so consumers can observe bootstrap-orchestration
  * outcomes without paying React import cost. Every other frame type
  * silently drops. Production boots through `bootProduction` which
@@ -652,7 +648,7 @@ function createPlaceholderRegistry(params) {
         subscribeFrameBuilder: () => ({
             type: 'subscribe',
             payload: {
-                renderId: params.meta.renderId,
+                sessionId: params.meta.sessionId,
                 appId: params.meta.appId,
                 ...(params.meta.wsToken !== undefined
                     ? { wsToken: params.meta.wsToken }
@@ -662,25 +658,23 @@ function createPlaceholderRegistry(params) {
     });
     registry.register(createRenderHandler({
         statusRefs: params.statusRefs,
-        pinnedRenderId: params.pinnedRenderId,
+        pinnedSessionId: params.pinnedSessionId,
     }));
     return registry;
 }
 /**
  * Frame dispatch lives inside `@ggui-ai/live-channel`'s
  * `ChannelRegistry`. Every WS frame type (`render`, `data`,
- * `props_update`, `drain_ack`, `feedback`, `channel_payload`,
+ * `props_update`, `drain_ack`, `channel_payload`,
  * `channel_error`, `system`) has a registered handler in
  * `channels/*.ts`; the registry's bound transport routes inbound
- * frames directly to them. Observability emissions
- * (`contract-error-emitted`, `auth-required`) are now inside the
- * data + system handlers respectively.
+ * frames directly to them. Observability emission (`auth-required`)
+ * is inside the system handler.
  *
  * The pre-B3b helpers (`handleServerMessage`, `handleRendererMessage`,
- * `handleObservableMessage`, `emitContractErrorFromDataFrame`,
- * `emitAuthRequiredFromSystemFrame`, `BufferedManagerShim`) lived
- * here and have been retired — see commit message + plan B3b for the
- * full retirement notes.
+ * `handleObservableMessage`, `emitAuthRequiredFromSystemFrame`,
+ * `BufferedManagerShim`) lived here and have been retired — see
+ * commit message + plan B3b for the full retirement notes.
  */
 /**
  * Type guard for the `UpgradeRequiredError` class without importing
@@ -701,6 +695,38 @@ function shouldAutostart() {
         return true;
     return process.env?.GGUI_RENDERER_AUTOSTART !== 'false';
 }
+// =============================================================================
+// Self-contained bootstrap (`window.__GGUI_META__`).
+//
+// The default boot path (postMessage `ui/initialize` → parse the
+// `_meta["ai.ggui/render"]` slice → open WebSocket → subscribe →
+// render from frames) is strictly first-party: it requires the host to
+// speak ggui's custom postMessage protocol AND a reachable live-channel
+// WebSocket the renderer can subscribe against. MCP Apps hosts in the
+// wild (Claude Desktop, claude.ai web) speak only the canonical MCP
+// Apps lifecycle and have no commitment to forward the slice key back
+// through `ui/initialize`. The full first-party path stays intact for
+// callers that own both ends; this self-contained path is what makes
+// the same runtime bundle work in third-party MCP Apps hosts.
+//
+// Contract: when the embedding HTML inlines a global of shape
+//   { sessionId: string, appId: string, componentCode: string }
+// (where `componentCode` is base64-encoded compiled ES module source
+// of a React component) BEFORE this bundle's `<script type="module">`
+// executes, the runtime takes over synchronously, mounts the compiled
+// component, and never speaks postMessage / opens a WebSocket. The
+// global is read at module load — a global set later (via deferred
+// scripts, async imports) is too late and the runtime falls through
+// to the legacy postMessage path.
+//
+// `componentCode` carries base64 because the embedding HTML inlines
+// it as a JS string literal next to other `<script>` content; raw
+// JS source contains every character that breaks string-literal
+// embedding (quotes, backticks, `</script>`, newlines, backslash
+// escapes). Base64 sidesteps every escape concern with a 4/3 size
+// overhead that's negligible compared to the network/round-trip
+// savings of skipping postMessage + WS bootstrap.
+// =============================================================================
 /**
  * Read `globalThis.__GGUI_META__` synchronously, validate against
  * the unified slice-meta shape, and return the typed meta (or null
@@ -740,8 +766,8 @@ function parseSeedProps(propsJson) {
 }
 /**
  * Project the inline `__GGUI_META__` bootstrap into a
- * {@link RenderSeedInput} the mount surface can paint immediately,
- * BEFORE the authoritative wire `Render` arrives over the WS — and with
+ * {@link GguiSessionSeedInput} the mount surface can paint immediately,
+ * BEFORE the authoritative wire `GguiSession` arrives over the WS — and with
  * no WS at all for spec-compliant MCP-Apps hosts that expose no ggui
  * live channel (claude.ai / ChatGPT / Claude Desktop).
  *
@@ -754,14 +780,14 @@ function parseSeedProps(propsJson) {
  * nothing to seed — the first WS ack mounts it). Throws when a `codeUrl`
  * fetch fails so the caller can surface a typed boot failure. The four
  * server-assigned ledger fields are intentionally absent — the first
- * ack reconciles the seed to a full `Render` (no fabrication).
+ * ack reconciles the seed to a full `GguiSession` (no fabrication).
  */
-export async function buildRenderSeedInput(meta) {
+export async function buildGguiSessionSeedInput(meta) {
     const props = parseSeedProps(meta.propsJson);
     // System-card mode — `kind` keyed against the built-in registry.
     if (meta.kind !== undefined) {
         return {
-            id: meta.renderId,
+            id: meta.sessionId,
             appId: meta.appId,
             type: 'system',
             kind: meta.kind,
@@ -773,18 +799,18 @@ export async function buildRenderSeedInput(meta) {
         return null;
     const res = await fetch(meta.codeUrl);
     if (!res.ok) {
-        throw new Error(`buildRenderSeedInput: codeUrl fetch failed (${res.status}): ${meta.codeUrl}`);
+        throw new Error(`buildGguiSessionSeedInput: codeUrl fetch failed (${res.status}): ${meta.codeUrl}`);
     }
     const componentCode = await res.text();
     return {
-        id: meta.renderId,
+        id: meta.sessionId,
         appId: meta.appId,
         componentCode,
         ...(props !== undefined ? { props } : {}),
     };
 }
 /**
- * Extract a {@link SelfContainedMcpAppAiGguiMeta} from a
+ * Extract a {@link McpAppAiGguiRenderMeta} from a
  * `ui/notifications/tool-result` JSON-RPC params payload — the
  * postMessage delivery shape MCP Apps hosts (Claude Desktop, claude.ai
  * web) use to push the active tool's `_meta` to the iframe.
@@ -903,19 +929,19 @@ function awaitToolResultMeta(timeoutMs) {
 /**
  * Module-level guard for the App-mediated post-mount toolresult
  * re-listener. Ensures exactly one persistent
- * `app.addEventListener('toolresult', …)` registration even when
- * `bootSelfContained` is called multiple times (e.g. an agent fires a
- * second `ggui_render` and we re-mount).
+ * `app.addEventListener('toolresult', …)` registration even across
+ * re-mounts (e.g. an agent fires a second `ggui_render` and the
+ * listener re-applies through the published `applyRender`).
  */
 let postMountListenerInstalled = false;
 /**
  * Module-level handle to the active renderer's `applyRender`, published
  * by `bootProduction`'s `setup()` once the renderer is built. The
  * module-level {@link installPostMountListener} resolves this to re-mount
- * on a host-re-emitted tool-result WITHOUT a fresh boot — no second mount
- * stack, no second WS. This is the no-WS live-re-render channel for
+ * on a host-re-emitted tool-result WITHOUT a fresh boot — no second mount,
+ * no second WS. This is the no-WS live-re-render channel for
  * spec-compliant MCP-Apps hosts (claude.ai / ChatGPT / Claude Desktop)
- * that re-broadcast the tool-result instead of pushing a WS frame.
+ * that re-broadcast the tool-result instead of sending a WS render frame.
  *
  * `null` until a renderer is published (e.g. unit tests that drive
  * `bootSequence` with no renderer never set it → the listener no-ops).
@@ -933,12 +959,12 @@ let anchorClickInterceptInstalled = false;
  * Module-level guard for {@link installFullscreenInterceptors}. The
  * fullscreen interceptors REPLACE prototype methods on `Element` and
  * `Document`; re-overriding on every re-mount would chain wrappers
- * and (if the captured `args` differ) leak stale `renderId`/`appId`.
+ * and (if the captured `args` differ) leak stale `sessionId`/`appId`.
  * The guard ensures exactly one prototype patch.
  */
 let fullscreenInterceptInstalled = false;
 /**
- * Compute a short deterministic action-id from a wired-action
+ * Compute a short deterministic action-id from a submit-action
  * payload. FNV-1a 32-bit, 8 hex chars — not cryptographically
  * strong, just collision-resistant enough for in-flight
  * correlation between the silent context-update and the loud
@@ -953,7 +979,7 @@ function fnv1aHex(payload) {
     return (hash >>> 0).toString(16).padStart(8, '0');
 }
 /**
- * Render a wired-action's `data` payload as a short inline string
+ * Render a submit-action's `data` payload as a short inline string
  * for embedding in a `ui/message` consent prompt. Goal: human-
  * readable, not a JSON dump. Falls back to truncated JSON for
  * nested values so the prompt doesn't drop information silently.
@@ -964,7 +990,7 @@ function fnv1aHex(payload) {
  * the LLM think every dispatch was a contentless "Please proceed
  * with **<intent>**" request.
  */
-export function formatWiredActionDataInline(data) {
+export function formatSubmitActionDataInline(data) {
     if (data === null || data === undefined)
         return '';
     // Bare primitives: render verbatim. Strings unquoted (most legible
@@ -1002,37 +1028,6 @@ export function formatWiredActionDataInline(data) {
     });
     return parts.join(', ');
 }
-/**
- * Dispatch a wired-action via the empirically-validated bridge
- * chain (validated against claude.ai):
- *
- *   1. `tools/call` to {@link toolName} with the action envelope
- *      — server-side gateway log + audit. Hosts MUST honor
- *      `_meta.ui.visibility:['app']` per spec §401, otherwise the
- *      call is silently rejected (probe found this empirically).
- *   2. `ui/update-model-context` (silent) — drops a structured
- *      `[ggui:pending-action]` payload into the LLM's persistent
- *      context. Carries the exact intent + data + actionId so the
- *      LLM has unambiguous tool args (no natural-language
- *      paraphrase risk).
- *   3. `ui/message` (consent prompt) — natural-language
- *      authorization the user confirms in chat. Spec §1032 + §401
- *      together: this is the prompt-injection firewall — the
- *      iframe can ASK the LLM to act, but the user is the one who
- *      introduces the message into the LLM's context.
- *
- * Why all three: the probe empirically proved that `tools/call`
- * alone never reaches the LLM (host-side scope:['app'] firewall),
- * and `ui/message` alone forces the LLM to parse natural language
- * for tool args (lossy + hallucination-prone). Pairing them with
- * a hash-bound id (#3) gives the LLM both verifiable args AND
- * explicit user authorization.
- *
- * Parts 2+3 fail-soft: if the host rejects either, the user can
- * still observe the click via #1's audit log on the server side,
- * but the LLM won't act on it. Acceptable degraded UX vs. the
- * pre-bridge "silent button click" status quo.
- */
 /**
  * Post an arbitrary JSON-RPC envelope to the iframe's parent
  * window. Internal helper shared across {@link emitAudit} (the
@@ -1125,7 +1120,7 @@ const productionContextSnapshotPoster = {
             params: {
                 name: 'ggui_runtime_sync_context',
                 arguments: {
-                    renderId: params.renderId,
+                    sessionId: params.sessionId,
                     appId: params.appId,
                     snapshot: params.snapshot,
                 },
@@ -1136,7 +1131,7 @@ const productionContextSnapshotPoster = {
 /**
  * Outbound `tools/call` shim. Routes through the spec-canonical
  * `app.callServerTool` API on the module-level App handle. Production
- * always has the handle set (bootSequence / bootSelfContained call
+ * always has the handle set (`bootSequence` calls
  * `setCurrentApp(app)` after handshake); tests that exercise dispatch
  * routing install one explicitly via {@link setCurrentApp} bound to
  * a `MockTransport`.
@@ -1179,10 +1174,10 @@ async function callServerToolSpec(toolName, args) {
  * Fire a single canonical action envelope (`tools/call
  * ggui_runtime_submit_action`) carrying the typed `{kind, payload, …}` shape
  * defined in `@ggui-ai/protocol/integrations/mcp-apps`. Every
- * user-driven gesture (Pattern α/β dispatch, native-idiom anchor click,
- * native-idiom fullscreen request) calls this alongside its primary
- * host effect, so operators get **uniform server-side observability**
- * across every gesture kind.
+ * user-driven gesture (submit-action dispatch, native-idiom anchor
+ * click, native-idiom fullscreen request) calls this alongside its
+ * primary host effect, so operators get **uniform server-side
+ * observability** across every gesture kind.
  *
  * Fail-soft: a rejected audit fire MUST NOT block the primary host
  * effect. Detached-parent / host-rejected audit envelopes are
@@ -1200,7 +1195,7 @@ export function emitAudit(args) {
             arguments: {
                 kind: args.kind,
                 payload: args.payload,
-                renderId: args.renderId,
+                sessionId: args.sessionId,
                 appId: args.appId,
                 actionId: args.actionId,
                 firedAt: args.firedAt,
@@ -1391,7 +1386,7 @@ function readLocalUiContext() {
  * consume loop has ended, e.g. after a page reload). The gesture is
  * ALREADY on the pipe from the just-completed `submit_action` append;
  * this doorbell only wakes a fresh agent turn so it calls
- * `ggui_consume({renderId})` to drain it.
+ * `ggui_consume({sessionId})` to drain it.
  *
  * SINGLE SOURCE OF TRUTH: the pipe. This carries ONLY a pointer to the
  * render — never the action payload or uiContext. Carrying the payload
@@ -1422,34 +1417,34 @@ function emitUserActionDoorbell(args) {
     // Prose + XML tags only, no fenced ```json``` block: a verbatim copy
     // of a tool-call wire shape trips claude.ai's prompt-injection
     // classifier even on the user-trusted `ui/message` channel.
-    const nextArgs = JSON.stringify({ renderId: args.renderId });
+    const nextArgs = JSON.stringify({ sessionId: args.sessionId });
     const text = [
         `Your REQUIRED FIRST TOOL CALL is ggui_consume with arguments ${nextArgs}. Call it NOW to retrieve and process the pending interaction. Do not respond conversationally; do not summarize. Issue the tool call as your next action.`,
         '',
         `<ggui_directive kind="user-action">`,
-        `  <render_id>${args.renderId}</render_id>`,
+        `  <session_id>${args.sessionId}</session_id>`,
         `  <next_tool>ggui_consume</next_tool>`,
         `  <next_args>${nextArgs}</next_args>`,
         `</ggui_directive>`,
         '',
-        `The user interacted with render ${args.renderId} while no ggui_consume long-poll was active. The gesture is queued on the consume pipe for that render — it is NOT in this message. After ggui_consume returns, react to the returned event with the appropriate domain tool, then call ggui_update on the SAME renderId (${args.renderId}).`,
+        `The user interacted with render ${args.sessionId} while no ggui_consume long-poll was active. The gesture is queued on the consume pipe for that render — it is NOT in this message. After ggui_consume returns, react to the returned event with the appropriate domain tool, then call ggui_update on the SAME sessionId (${args.sessionId}).`,
     ].join('\n');
     // Structured mirror of the directive for ggui-aware programmatic
     // consumers. OPTIONAL — nothing in the loop depends on a server-side
     // parse of this; an `_meta`-agnostic host acts on the text above
     // alone. Typed against the protocol interface (no runtime guard
     // exists — the shape is locked at compile time here).
-    const description = `User interacted with render ${args.renderId}; call ggui_consume to retrieve and process it.`;
+    const description = `User interacted with render ${args.sessionId}; call ggui_consume to retrieve and process it.`;
     const userAction = {
         kind: 'user-action',
         description,
-        renderId: args.renderId,
+        sessionId: args.sessionId,
         actionId: args.actionId,
         submittedAt: args.submittedAt,
         intent: args.intent,
         nextStep: {
             tool: 'ggui_consume',
-            args: { renderId: args.renderId },
+            args: { sessionId: args.sessionId },
         },
     };
     // RAW postMessage — NOT `app.sendMessage`. The doorbell MUST bypass
@@ -1494,14 +1489,26 @@ function emitUserActionDoorbell(args) {
         },
     });
 }
-/** @internal — exported for unit tests. */
-export function dispatchWiredAction(args) {
+/**
+ * Dispatch a submit-action via the empirically-validated bridge
+ * chain (validated against claude.ai): a `tools/call` to
+ * {@link toolName} (the `ggui_runtime_submit_action` receiver)
+ * appends the gesture to the render's consume pipe, paired with a
+ * silent `ui/update-model-context` prime and — only when the server
+ * reports no active `ggui_consume` long-poll — a `ui/message`
+ * doorbell so a fresh agent turn drains the pipe. Hosts MUST honor
+ * `_meta.ui.visibility:['app']` per spec §401, otherwise the
+ * `tools/call` is silently rejected (probe found this empirically).
+ *
+ * @internal — exported for unit tests.
+ */
+export function dispatchSubmitAction(args) {
     if (typeof window === 'undefined')
         return;
-    const { toolName, intent, data, renderId, appId } = args;
+    const { toolName, intent, data, sessionId, appId } = args;
     const firedAt = new Date().toISOString();
     const actionId = fnv1aHex(`${intent}|${JSON.stringify(data ?? null)}|${firedAt}`);
-    const inlineData = formatWiredActionDataInline(data);
+    const inlineData = formatSubmitActionDataInline(data);
     const dataPart = inlineData === '' ? '' : ` (${inlineData})`;
     const uiContext = readLocalUiContext();
     // (1) Silent context update — fires FIRST and ALWAYS. Primes the
@@ -1517,7 +1524,7 @@ export function dispatchWiredAction(args) {
                     intent,
                     data: data ?? null,
                     firedAt,
-                    renderId,
+                    sessionId,
                     appId,
                 })}`,
             },
@@ -1556,7 +1563,7 @@ export function dispatchWiredAction(args) {
                     actionData: data ?? null,
                     uiContext,
                 },
-                renderId,
+                sessionId,
                 appId,
                 actionId,
                 firedAt,
@@ -1572,7 +1579,7 @@ export function dispatchWiredAction(args) {
                 showActionToast(`💬 ${intent}${dataPart} — agent not listening, sent to chat`, 'action_required');
                 emitUserActionDoorbell({
                     intent,
-                    renderId,
+                    sessionId,
                     actionId,
                     submittedAt: firedAt,
                 });
@@ -1590,57 +1597,8 @@ export function dispatchWiredAction(args) {
     })();
 }
 /**
- * Fire a wired action via Pattern α — direct `tools/call` against a
- * same-server, app-visible target tool. The iframe is allowed to fire
- * the tool directly from this server connection per MCP-Apps spec
- * §2026-01-26 visibility rules. Skips the submit_action pipe entirely:
- * the tool fires without the agent's involvement (the whole point of
- * Pattern α), chat stays clean.
- *
- * PIPE-2 design note: Pattern α deliberately does NOT fire
- * `submit_action` — a pipe append would queue the gesture for the
- * agent's `ggui_consume` long-poll, causing double-processing
- * (host's tool relay AND agent's reaction). RenderInspector loses
- * Pattern α observability for now; re-add via a dedicated audit-only
- * gesture kind if operators need it.
- *
- * @internal — exported for unit tests.
- */
-export function fireDirectToolCall(args) {
-    if (typeof window === 'undefined')
-        return;
-    const { targetToolName, data } = args;
-    // Direct tools/call — fires on the same MCP server connection the
-    // iframe was bootstrapped against. Spec §2026-01-26: "app"
-    // visibility tools are callable by the app from the same server
-    // connection only.
-    postToParent({
-        jsonrpc: '2.0',
-        id: Math.floor(Math.random() * 1e9),
-        method: 'tools/call',
-        params: {
-            name: targetToolName,
-            arguments: (data ?? {}),
-        },
-    });
-}
-/**
- * Pure routing helper for `WireConfig.dispatch` — chooses Pattern α
- * (direct `tools/call`) when the action's wired tool is in
- * `appCallableTools`, otherwise falls back to Pattern β (the 3-message
- * bridge).
- *
- * The routing logic was previously inlined as a closure body inside
- * `bootSelfContained`'s `wireConfig.dispatch`, with a verbatim
- * re-creation in `__tests__/dispatch-routing.test.ts`. Tests could
- * pass against stale code if either drifted. Extraction means
- * production + tests now exercise the same code path.
- *
- * Pattern α (same-server, app-visible target tool): chat stays clean,
- * no LLM consent loop. Pattern β (anything else: cross-server tool, no
- * wired tool, or tool not in `appCallableTools`): the canonical
- * 3-message workaround the LLM brokers when the tool isn't directly
- * callable from the iframe.
+ * Resolve the name of the spec-canonical submit-action receiver tool
+ * the dispatch path targets with `tools/call`.
  *
  * @internal — exported for unit tests + production reuse.
  */
@@ -1659,34 +1617,28 @@ export function resolveDispatchToolName() {
         : 'ggui_runtime_submit_action';
 }
 /**
+ * Routing helper for `WireConfig.dispatch` — every user action takes
+ * the same path: enqueue the gesture onto the render's pending-event
+ * pipe via `submit_action`. The agent retrieves it EXCLUSIVELY via
+ * `ggui_consume` — the gesture never travels inline, so there is no
+ * `nextStep` hint to forward client-side (the server derives the
+ * agent-facing hint from the render's `actionSpec[name].nextStep`
+ * when it builds the consume event).
+ *
+ * Lives as a named export (rather than a closure body inside the
+ * boot path) so production + tests exercise the same code path.
+ *
  * @internal — exported for unit tests + production reuse.
  */
 export function routeDispatch(args) {
     const { actionName, data, meta, dispatchToolName } = args;
-    const tool = meta.actionNextSteps?.[actionName];
-    const appCallable = typeof tool === 'string' &&
-        (meta.appCallableTools ?? []).includes(tool);
-    if (appCallable && tool !== undefined) {
-        fireDirectToolCall({
-            targetToolName: tool,
-            data,
-        });
-    }
-    else {
-        // Pattern β: enqueue the gesture onto the render's pending-event
-        // pipe via `submit_action`. The agent retrieves it EXCLUSIVELY via
-        // `ggui_consume` — the gesture never travels inline, so there is no
-        // `nextStep` hint to forward (the doorbell carries only a pointer to
-        // the render). This branch is also where
-        // `actionSpec[*].dispatch.kind === 'agent'` lands.
-        dispatchWiredAction({
-            toolName: dispatchToolName,
-            intent: actionName,
-            data,
-            renderId: meta.renderId,
-            appId: meta.appId,
-        });
-    }
+    dispatchSubmitAction({
+        toolName: dispatchToolName,
+        intent: actionName,
+        data,
+        sessionId: meta.sessionId,
+        appId: meta.appId,
+    });
 }
 /**
  * `ui/open-link` direct dispatch helper — used by the anchor-click
@@ -1697,7 +1649,7 @@ export function routeDispatch(args) {
 export function openLinkInParent(args) {
     if (typeof window === 'undefined')
         return;
-    const { toolName, url, renderId, appId } = args;
+    const { toolName, url, sessionId, appId } = args;
     if (typeof url !== 'string' || url.length === 0) {
         throw new RangeError('wire.openLink(url): `url` must be a non-empty string.');
     }
@@ -1707,7 +1659,7 @@ export function openLinkInParent(args) {
         toolName,
         kind: 'openLink',
         payload: { url },
-        renderId,
+        sessionId,
         appId,
         actionId,
         firedAt,
@@ -1724,14 +1676,14 @@ export function openLinkInParent(args) {
 export function requestDisplayModeInParent(args) {
     if (typeof window === 'undefined')
         return;
-    const { toolName, mode, renderId, appId } = args;
+    const { toolName, mode, sessionId, appId } = args;
     const firedAt = new Date().toISOString();
     const actionId = fnv1aHex(`requestDisplayMode|${mode}|${firedAt}`);
     emitAudit({
         toolName,
         kind: 'requestDisplayMode',
         payload: { mode },
-        renderId,
+        sessionId,
         appId,
         actionId,
         firedAt,
@@ -1781,7 +1733,7 @@ export function installAnchorClickInterceptor(args) {
     if (typeof document === 'undefined')
         return;
     anchorClickInterceptInstalled = true;
-    const { dispatchToolName, renderId, appId } = args;
+    const { dispatchToolName, sessionId, appId } = args;
     const onClick = (event) => {
         if (event.defaultPrevented)
             return;
@@ -1826,7 +1778,7 @@ export function installAnchorClickInterceptor(args) {
         openLinkInParent({
             toolName: dispatchToolName,
             url: absoluteHref,
-            renderId,
+            sessionId,
             appId,
         });
     };
@@ -1866,7 +1818,7 @@ export function installAnchorClickInterceptor(args) {
  *
  * Idempotent: the {@link fullscreenInterceptInstalled} guard prevents
  * re-mounts from chaining wrappers (which would also leak the prior
- * mount's `renderId`/`appId` if they ever differed).
+ * mount's `sessionId`/`appId` if they ever differed).
  */
 /** @internal — exported for unit tests. */
 export function installFullscreenInterceptors(args) {
@@ -1878,12 +1830,12 @@ export function installFullscreenInterceptors(args) {
         return;
     }
     fullscreenInterceptInstalled = true;
-    const { dispatchToolName, renderId, appId } = args;
+    const { dispatchToolName, sessionId, appId } = args;
     Element.prototype.requestFullscreen = function (_options) {
         requestDisplayModeInParent({
             toolName: dispatchToolName,
             mode: 'fullscreen',
-            renderId,
+            sessionId,
             appId,
         });
         return Promise.resolve();
@@ -1892,7 +1844,7 @@ export function installFullscreenInterceptors(args) {
         requestDisplayModeInParent({
             toolName: dispatchToolName,
             mode: 'inline',
-            renderId,
+            sessionId,
             appId,
         });
         return Promise.resolve();
@@ -1912,24 +1864,24 @@ export function __resetInterceptorsForTest() {
  * Install a persistent `app.addEventListener('toolresult', …)` listener
  * that catches `ui/notifications/tool-result` notifications arriving
  * AFTER the initial mount. Each new tool-result that carries a
- * different bootstrap (different renderId / codeUrl / kind) triggers
- * a re-mount via {@link bootSelfContained}. This closes the boot-only-
+ * different bootstrap (different sessionId / codeUrl / kind) triggers
+ * a re-mount through the published `applyRender`. This closes the boot-only-
  * listener gap that prevented live re-render when an agent issued
  * a second `ggui_render` to the same render-resource.
  *
  * Idempotent: subsequent calls no-op via {@link postMountListenerInstalled}.
  *
- * Why module-level vs scoped to a single mount: bootSelfContained may
- * itself trigger a re-mount, and the listener should outlive any
- * single mount cycle. The guard ensures we don't stack listeners
- * across re-mounts.
+ * Why module-level vs scoped to a single mount: re-mounts re-apply
+ * through `applyRender` while the listener stays live, and the
+ * listener should outlive any single mount cycle. The guard ensures
+ * we don't stack listeners across re-mounts.
  *
  * Spec-canonical (post-Phase-1.19b.3): the previous hand-rolled
  * `window.addEventListener('message', …)` is gone; App handles every
  * inbound `ui/notifications/tool-result` envelope and dispatches via
  * its event system. Per-iframe single-tenancy means the App handle
- * comes from `getCurrentApp()` — set by bootSelfContained's own
- * connect path before this helper runs.
+ * comes from `getCurrentApp()` — set by `bootSequence`'s connect
+ * path before this helper runs.
  */
 function installPostMountListener() {
     if (postMountListenerInstalled)
@@ -1952,9 +1904,9 @@ function installPostMountListener() {
         // claude.ai) often emit the initial meta WITHOUT the wsUrl+token
         // pair (the Anthropic SDK strips `_meta` from tool results), then
         // refetch + re-emit the FULL envelope. The two envelopes share
-        // renderId/kind/codeUrl/propsJson but differ on the live trio —
+        // sessionId/kind/codeUrl/propsJson but differ on the live trio —
         // without trio in the key, the second arrival deduped silently and
-        // bootSelfContained never opened the WS, so `ggui_update` props_update
+        // the re-mount never opened the WS, so `ggui_update` props_update
         // frames fanned to zero subscribers.
         const liveTrio = typeof meta.wsUrl === 'string' &&
             meta.wsUrl.length > 0 &&
@@ -1963,7 +1915,7 @@ function installPostMountListener() {
             ? 'live'
             : '-';
         const key = [
-            meta.renderId,
+            meta.sessionId,
             meta.kind ?? '-',
             meta.codeUrl ?? '-',
             meta.propsJson ?? '-',
@@ -1980,7 +1932,7 @@ function installPostMountListener() {
         const apply = activeApplyRender;
         if (apply === null)
             return; // no renderer published yet — no-op safely
-        void buildRenderSeedInput(meta).then((seed) => {
+        void buildGguiSessionSeedInput(meta).then((seed) => {
             if (seed === null)
                 return;
             void apply(seed).then(() => {
@@ -1990,7 +1942,7 @@ function installPostMountListener() {
                 // the regular debounced flow once the component mutates values.
                 // Filter to slot names declared by the FRESHLY mounted contract.
                 const activeSlotNames = new Set((meta.contextSlots ?? []).map((s) => s.name));
-                reemitLastContextValues(productionContextSnapshotPoster, activeSlotNames, { renderId: meta.renderId, appId: meta.appId });
+                reemitLastContextValues(productionContextSnapshotPoster, activeSlotNames, { sessionId: meta.sessionId, appId: meta.appId });
             });
         });
     });
@@ -1998,7 +1950,7 @@ function installPostMountListener() {
 /**
  * Detect a live-channel bootstrap shape inlined onto `__GGUI_META__`.
  * The first-party render shells (`/r/<shortCode>`,
- * `ui://ggui/render/<renderId>`, the embedded-ui RenderViewer's thin
+ * `ui://ggui/render/<sessionId>`, the embedded-ui GguiSessionViewer's thin
  * shell) populate this synchronously before the runtime loads.
  *
  * Post-Phase-B the global carries a slice ENVELOPE (same shape as the
@@ -2032,8 +1984,8 @@ function readLiveBootstrapShape() {
         renderBag['wsUrl'].length > 0 &&
         typeof renderBag['wsToken'] === 'string' &&
         renderBag['wsToken'].length > 0 &&
-        typeof renderBag['renderId'] === 'string' &&
-        renderBag['renderId'].length > 0 &&
+        typeof renderBag['sessionId'] === 'string' &&
+        renderBag['sessionId'].length > 0 &&
         typeof renderBag['appId'] === 'string' &&
         renderBag['appId'].length > 0);
 }
@@ -2059,7 +2011,7 @@ function runBootProduction(preResolvedMeta) {
         app,
         transport,
         notifyParent: (msg) => {
-            if (msg.type === 'ggui:renderer-ready') {
+            if (msg.type === MCP_APP_RENDERER_READY_TYPE) {
                 postRendererReady();
                 return;
             }
@@ -2124,8 +2076,9 @@ async function bootProduction(opts) {
         import('@ggui-ai/design/interact'),
         import('@ggui-ai/design/tokens'),
         import('@ggui-ai/wire'),
-        // STDLIB gadget hooks. See the `bootSelfContained` callsite
-        // above for the rationale.
+        // STDLIB gadget hooks — seeds `__ggui__.gadgets` synchronously in
+        // the registry composition below, so a generated component's
+        // gadget data-URL shims resolve at mount time.
         import('@ggui-ai/gadgets'),
     ]);
     const [globalsMod, gadgetLoaderMod] = await Promise.all([
@@ -2136,11 +2089,10 @@ async function bootProduction(opts) {
     // + wire config on demand inside bootSequence.
     const renderer = {
         setup: ({ meta, renderInto, statusRefs, onObserve }) => {
-            // Post-Phase-B `meta` is the flat render slice — `renderId` /
+            // Post-Phase-B `meta` is the flat render slice — `sessionId` /
             // `appId` / `runtimeUrl` / `wsUrl` / `wsToken` / `themeId` /
-            // `gadgets` / `publicEnv` / `contextSlots` / `actionNextSteps` /
-            // `appCallableTools` / `streamWebSocketLocalTools` all live
-            // directly on `meta`.
+            // `gadgets` / `publicEnv` / `contextSlots` /
+            // `streamWebSocketLocalTools` all live directly on `meta`.
             // Compose the gadget registry: STDLIB seed PLUS any
             // operator-registered wrappers carried on the bootstrap.
             // Awaited inside the synchronous `setup` callback via an IIFE
@@ -2196,7 +2148,7 @@ async function bootProduction(opts) {
             });
             // Install the React Context registry + build a ContextStateHost
             // so the WS-driven shells (Studio, Portal, OSS console)
-            // participate in contextSpec the same way `bootSelfContained`
+            // participate in contextSpec the same way the static-seed mount
             // does. Without this the WS-driven path installed neither —
             // `globalThis.__ggui__.contexts` stayed empty, the boilerplate's
             // destructure resolved to `undefined`, and any declared
@@ -2215,7 +2167,7 @@ async function bootProduction(opts) {
                     ? console.warn.bind(console)
                     : undefined,
                 identity: {
-                    renderId: meta.renderId,
+                    sessionId: meta.sessionId,
                     appId: meta.appId,
                 },
             });
@@ -2247,17 +2199,18 @@ async function bootProduction(opts) {
             };
             // Spec-canonical outbound dispatch. The WS pipe is for streamSpec
             // subscriptions ONLY (inbound `ggui_emit` fanout + `props_update` +
-            // `render` + `data` + `feedback` + `drain_ack` + `channel_payload`).
+            // `render` + `data` + `drain_ack` + `channel_payload`).
             // Outbound user actions go through the MCP-Apps host relay per
             // spec §401: postMessage `tools/call:ggui_runtime_submit_action`
             // to the parent → `AppRenderer.onCallTool` → sample agent's
             // `/relay/tools-call` → ggui MCP server →
             // `createGguiSubmitActionHandler.append` → `pendingEventConsumer`
             // → `ggui_consume` wakes the agent. The server's WS
-            // `handleInboundAction` writes to the session ledger only — no
+            // `handleInboundAction` writes to the render ledger only — no
             // downstream consumer — so the WS action path silently drops
-            // clicks. `routeDispatch` is the same helper `bootSelfContained`
-            // uses; threading it here aligns LIVE-mode with self-contained.
+            // clicks. `routeDispatch` is the shared named-export helper
+            // (production + tests exercise the same code path); threading it
+            // here keeps LIVE-mode on the canonical dispatch pipeline.
             // Single mounted render — populated by `applyRender` on the first
             // render frame. The wire config + data channel handler read it
             // through `currentRender`-returning thunks so they always see the
@@ -2271,26 +2224,25 @@ async function bootProduction(opts) {
             // through this single surface — the WS-ack render, the inline
             // static seed, and re-mounts — has anchor-click + fullscreen
             // capture live before the first `applyRender`. Pre-consolidation
-            // these lived only in `bootSelfContained`; the WS-driven path
-            // installed neither, so anchor clicks + fullscreen requests in a
-            // live-rendered component silently no-op'd.
+            // these lived only in the retired self-contained boot path; the
+            // WS-driven path installed neither, so anchor clicks + fullscreen
+            // requests in a live-rendered component silently no-op'd.
             installAnchorClickInterceptor({
                 dispatchToolName,
-                renderId: meta.renderId,
+                sessionId: meta.sessionId,
                 appId: meta.appId,
             });
             installFullscreenInterceptors({
                 dispatchToolName,
-                renderId: meta.renderId,
+                sessionId: meta.sessionId,
                 appId: meta.appId,
             });
             const rootConfig = buildRootWireConfig({
-                renderId: meta.renderId,
+                sessionId: meta.sessionId,
                 appId: meta.appId,
-                getCurrentRender: () => currentRender,
+                getCurrentGguiSession: () => currentRender,
                 manager,
                 streamBus,
-                ...(onObserve !== undefined ? { onObserve } : {}),
                 onDispatchEnvelope: (envelope) => {
                     if (envelope.type !== 'data:submit')
                         return;
@@ -2304,14 +2256,8 @@ async function bootProduction(opts) {
                         actionName: payload.action,
                         data: payload.data,
                         meta: {
-                            renderId: meta.renderId,
+                            sessionId: meta.sessionId,
                             appId: meta.appId,
-                            ...(meta.appCallableTools !== undefined
-                                ? { appCallableTools: meta.appCallableTools }
-                                : {}),
-                            ...(meta.actionNextSteps !== undefined
-                                ? { actionNextSteps: meta.actionNextSteps }
-                                : {}),
                         },
                         dispatchToolName,
                     });
@@ -2338,7 +2284,7 @@ async function bootProduction(opts) {
             // host has its own contract (adapter-boundary rule).
             // Post-render-identity-collapse the WireConfig is bound to the
             // single render at boot, so there's no per-render scope factory
-            // — every dispatch resolves through `getCurrentRender`.
+            // — every dispatch resolves through `getCurrentGguiSession`.
             const buildScopedWireFor = (render) => {
                 if (render.type === 'mcpApps' || render.type === 'system')
                     return null;
@@ -2350,19 +2296,18 @@ async function bootProduction(opts) {
             // Without this, react-renderer.ts falls back to
             // `getScopedCssTokens` (no preset) and the iframe renders with
             // the default ggui theme even when `_meta["ai.ggui/render"].themeId`
-            // is `'indigo'`. Sibling `bootSelfContained` path threads the
-            // same fields onto its `mountOpts` for parity.
+            // is `'indigo'`.
             const buildOpts = (render) => {
                 const wrapOuter = buildOuterWrapper(render);
                 return {
                     render,
                     scopedWireConfig: buildScopedWireFor(render),
                     streamBus,
-                    renderId: meta.renderId,
+                    sessionId: meta.sessionId,
                     // Thread the bootstrap's 3rd-party gadget packages so the import
                     // rewriter resolves non-STDLIB gadget imports even for a static
                     // seed mount (which carries no gadgetDescriptors). A full
-                    // WS-delivered Render carries gadgetDescriptors and ignores this.
+                    // WS-delivered GguiSession carries gadgetDescriptors and ignores this.
                     ...(meta.gadgets !== undefined
                         ? { gadgetPackages: meta.gadgets.map((g) => g.package) }
                         : {}),
@@ -2370,6 +2315,13 @@ async function bootProduction(opts) {
                     ...(meta.themeMode !== undefined
                         ? { themeMode: meta.themeMode }
                         : {}),
+                    // Per-app theme overlay (St3 M2.2). Threaded straight from the
+                    // bootstrap's `_meta["ai.ggui/render"].theme` (typed `AppTheme`,
+                    // already injection-validated by the wire parser) onto the mount
+                    // options so the renderer applies the `--ggui-*` overrides +
+                    // `color-scheme` at `:root`. THEME IS COMPONENT-ONLY — system
+                    // cards theme via the SystemCardHost/ThemeProvider path.
+                    ...(meta.theme !== undefined ? { appTheme: meta.theme } : {}),
                     ...(wrapOuter !== undefined ? { wrapOuter } : {}),
                 };
             };
@@ -2399,7 +2351,7 @@ async function bootProduction(opts) {
             // the listener re-mounts through THIS `applyRender` — no fresh boot,
             // no second WS. The no-WS live-re-render channel; for WS hosts the
             // render-frame handler already covers re-render, so it's a
-            // redundant-safe fallback (guarded by the renderId pin + liveTrio
+            // redundant-safe fallback (guarded by the sessionId pin + liveTrio
             // dedupe). Runs only on the production renderer path (tests that
             // drive bootSequence without a renderer never reach setup()).
             activeApplyRender = applyRender;
@@ -2420,7 +2372,7 @@ async function bootProduction(opts) {
             // frame handler (which calls `channelTransport.applyRender` on
             // every render fold).
             const channelTransport = createChannelTransportRouter({
-                renderId: meta.renderId,
+                sessionId: meta.sessionId,
                 appId: meta.appId,
                 ...(meta.streamWebSocketLocalTools !== undefined
                     ? {
@@ -2432,8 +2384,8 @@ async function bootProduction(opts) {
                     // Iframe-polling transport — `tools/call` against the
                     // parent MCP host via `app.callServerTool` (spec-canonical)
                     // when the App handle is set; falls back to raw postMessage
-                    // pre-handshake or in tests. Pattern α direct call (no LLM
-                    // consent loop). Returns the tool's structuredContent (or
+                    // pre-handshake or in tests. Direct call (no LLM consent
+                    // loop). Returns the tool's structuredContent (or
                     // `content[0]` if that's where the payload landed) as a
                     // JsonValue. On RPC error we throw — the router catches
                     // and silently retries on the next tick.
@@ -2476,7 +2428,7 @@ async function bootProduction(opts) {
                 subscribeFrameBuilder: () => ({
                     type: 'subscribe',
                     payload: {
-                        renderId: meta.renderId,
+                        sessionId: meta.sessionId,
                         appId: meta.appId,
                         ...(meta.wsToken !== undefined
                             ? { wsToken: meta.wsToken }
@@ -2486,22 +2438,20 @@ async function bootProduction(opts) {
             });
             channelRegistry.register(createRenderHandler({
                 statusRefs,
-                pinnedRenderId: meta.renderId,
+                pinnedSessionId: meta.sessionId,
                 applyRender,
                 getChannelTransport: () => channelTransport,
             }));
             channelRegistry.register(createDataHandler({
-                getCurrentRender: () => currentRender,
+                getCurrentGguiSession: () => currentRender,
                 streamBus,
                 validatorCtx,
-                ...(onObserve !== undefined ? { onObserve } : {}),
             }));
             channelRegistry.register(createPropsUpdateHandler({
-                getCurrentRender: () => currentRender,
+                getCurrentGguiSession: () => currentRender,
                 applyRender,
             }));
             channelRegistry.register(createDrainAckHandler({ dispatch: dispatchDrainAck }));
-            channelRegistry.register(createFeedbackHandler());
             channelRegistry.register(createChannelPayloadHandler({
                 getChannelTransport: () => channelTransport,
             }));
@@ -2515,7 +2465,7 @@ async function bootProduction(opts) {
                 rootWireConfig: rootConfig,
                 streamBus,
                 applyRender,
-                getCurrentRender: () => currentRender,
+                getCurrentGguiSession: () => currentRender,
                 validatorCtx,
                 manager,
                 channelTransport,