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

package/dist/{session-channel.js → render-channel.js}

@@ -4,7 +4,7 @@
  * The live channel is where the typed-channel contract is enforced on
  * live traffic between the server and the user. It co-hosts on the
  * same Express server as `/mcp` and reuses the same
- * `@ggui-ai/mcp-server-handlers/session-mutations` helpers that the
+ * `@ggui-ai/mcp-server-handlers/renders` helpers that the
  * closed hosted server consumes.
  *
  * Scope:
@@ -14,15 +14,15 @@
  *   - `action` → inbound user action carried as an {@link ActionEnvelope}.
  *     Gated through `assertEventAllowed` (allowlist) +
  *     `assertActionContract` (payload, for data:submit). Persisted to
- *     SessionStore as a typed session event.
+ *     RenderStore as a typed session event.
  *   - `ping`/`pong` → heartbeat parity with hosted.
  *   - `close`/socket-close → clean subscriber teardown.
- *   - `sendToSession(sessionId, data)` → outbound fan-out API for
+ *   - `sendToSession(renderId, data)` → outbound fan-out API for
  *     mutation handlers (ggui_emit / connector `ctx.send`). Validated
  *     through `assertStreamContract` before delivery.
  *
  * `props_update`: mount handlers dispatched through the wired-action
- * router can call `ctx.sendPropsUpdate(stackItemId, props)` to fan a
+ * router can call `ctx.sendPropsUpdate(renderId, props)` to fan a
  * `{type:'props_update'}` frame to live subscribers without going
  * through a refresh-stream path. Reaches the renderer's existing
  * `props_update` branch in `iframe-runtime` and applies new props
@@ -32,31 +32,51 @@
  * Not handled here:
  *
  *   - Pattern-B daemon-agent notification stream (GET /mcp SSE).
- *   - Short-lived session-token mint/consume — that's ggui_push-gated.
+ *   - Short-lived session-token mint/consume — that's ggui_render-gated.
  *     Dev-mode auth (any bearer via existing AuthAdapter) matches the
  *     `/mcp` endpoint's shape and is operator-replaceable.
  */
-import { randomUUID } from 'node:crypto';
-import { WebSocketServer } from 'ws';
-import { CONTRACT_ERROR_CHANNEL, ContractViolationError, EMPTY_REFRESH_INPUT, PROTOCOL_SCHEMA_VERSION, UPGRADE_REQUIRED, makeContractErrorPayload, sanitizeCausedBy as defaultSanitizeCausedBy, } from '@ggui-ai/protocol';
-import { InMemorySessionStreamBuffer, InProcessStreamFanout, NoopTelemetrySink, } from '@ggui-ai/mcp-server-core/in-memory';
-import { assertActionContract, assertEventAllowed, assertStreamContract, EventNotAllowedError, } from '@ggui-ai/mcp-server-handlers/session-mutations';
-import { resolveIdentityFromHeaders, UnauthenticatedError, } from './auth.js';
+import { InMemorySessionStreamBuffer, InProcessStreamFanout, NoopTelemetrySink, } from "@ggui-ai/mcp-server-core/in-memory";
+import { assertActionContract, assertStreamContract } from "@ggui-ai/mcp-server-handlers/renders";
+import { CONTRACT_ERROR_CHANNEL, ContractViolationError, sanitizeCausedBy as defaultSanitizeCausedBy, EMPTY_REFRESH_INPUT, makeContractErrorPayload, PROTOCOL_SCHEMA_VERSION, UPGRADE_REQUIRED, } from "@ggui-ai/protocol";
+import { randomUUID } from "node:crypto";
+import { WebSocketServer } from "ws";
+import { resolveIdentityFromHeaders, UnauthenticatedError } from "./auth.js";
+// `assertEventAllowed` + `EventNotAllowedError` were removed from
+// `@ggui-ai/mcp-server-handlers/renders` in Phase B alongside
+// the session-stack collapse — the event-allowlist concept on a
+// `StackItem.subscription` no longer has a wire shape to bind to.
+// Local stand-ins keep the inbound-action allowlist call sites
+// compiling until the event-allowlist semantics are re-thought in a
+// follow-up slice (see "B.2d render-channel inbound-action allowlist
+// deferred" in the report).
+class EventNotAllowedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EventNotAllowedError";
+    }
+}
+function assertEventAllowed(_subscription, _type) {
+    // No-op: pre-Phase-B this read `StackItem.subscription` and rejected
+    // event types not on the allowlist. Post-collapse there's no
+    // subscription field on `Render`; the gate is deferred to a follow-up
+    // slice that defines per-render event policy on the new wire shape.
+}
 /** Default URL path for the channel endpoint. Operators can override. */
-export const DEFAULT_SESSION_CHANNEL_PATH = '/ws';
+export const DEFAULT_RENDER_CHANNEL_PATH = "/ws";
 /**
  * Default + boundary cadence for the channel-subscribe polling loop.
  * Server-authoritative: clients propose `pollIntervalMs` on
  * `channel_subscribe`, server clamps to [floorMs, ceilingMs] and
  * defaults to `defaultMs` when absent. Conservative defaults — operators
- * tune via {@link SessionChannelLocalToolsOptions.pollCadence}.
+ * tune via {@link RenderChannelLocalToolsOptions.pollCadence}.
  */
 const DEFAULT_CHANNEL_POLL_FLOOR_MS = 1_000;
 const DEFAULT_CHANNEL_POLL_CEILING_MS = 60_000;
 const DEFAULT_CHANNEL_POLL_DEFAULT_MS = 10_000;
 /**
  * Default timeout for a single wired-tool invocation, in ms. Operators
- * override via {@link SessionChannelOptions.wiredActionTimeoutMs}; the
+ * override via {@link RenderChannelOptions.wiredActionTimeoutMs}; the
  * 30 s ceiling is a honest non-promise: long-running tools MUST design
  * their own completion path (streaming, polling).
  */
@@ -72,7 +92,7 @@ class WiredToolTimeoutError extends Error {
     timeoutMs;
     constructor(toolName, timeoutMs) {
         super(`Wired tool '${toolName}' did not complete within ${timeoutMs}ms`);
-        this.name = 'WiredToolTimeoutError';
+        this.name = "WiredToolTimeoutError";
         this.toolName = toolName;
         this.timeoutMs = timeoutMs;
     }
@@ -81,8 +101,8 @@ class WiredToolTimeoutError extends Error {
  * Build an OSS live-channel server. The returned object is designed to be
  * composed into `createGguiServer` — see `server.ts` for the wire-up.
  */
-export function createSessionChannelServer(opts) {
-    const path = opts.path ?? DEFAULT_SESSION_CHANNEL_PATH;
+export function createRenderChannelServer(opts) {
+    const path = opts.path ?? DEFAULT_RENDER_CHANNEL_PATH;
     // Outbound stream buffer — owns seq assignment + bounded replay
     // storage. Default is in-memory; operators swap via `opts.streamBuffer`.
     const streamBuffer = opts.streamBuffer ?? new InMemorySessionStreamBuffer();
@@ -120,6 +140,15 @@ export function createSessionChannelServer(opts) {
     const wsSubscribers = new Set();
     /** ws → subscriber reverse index so socket-close can look up cheaply. */
     const subscribersByWs = new WeakMap();
+    /**
+     * Per-session local subscriber count. Drives the {@link
+     * RenderChannelOptions.onFirstSubscriber} / `onLastSubscriberGone`
+     * 0↔1 transition hooks used by cloud adapters for per-session
+     * cross-pod pub/sub channel scoping. Distinct from the
+     * `sessionCount` getter — that walks `wsSubscribers` on demand;
+     * this map is the registration-time counter the hooks key off.
+     */
+    const sessionCountById = new Map();
     /**
      * Pump live frames from the StreamFanout iterator out to this
      * subscriber's WS. Started fire-and-forget by `register`; ends when
@@ -147,12 +176,12 @@ export function createSessionChannelServer(opts) {
                     await sub.iter.return?.();
                     return;
                 }
-                send(sub.ws, { type: 'data', payload: value });
+                send(sub.ws, { type: "data", payload: value });
             }
         }
         catch (err) {
-            opts.logger.warn('session_channel_pump_failed', {
-                sessionId: sub.sessionId,
+            opts.logger.warn("session_channel_pump_failed", {
+                renderId: sub.renderId,
                 error: String(err),
             });
         }
@@ -160,6 +189,24 @@ export function createSessionChannelServer(opts) {
     function register(sub) {
         wsSubscribers.add(sub);
         subscribersByWs.set(sub.ws, sub);
+        // Per-session count bookkeeping + 0→1 hook for cloud pubsub
+        // adapter scoping. Increment FIRST so the hook sees the up-to-date
+        // state; hook fires only on the transition (prevCount === 0).
+        const prevCount = sessionCountById.get(sub.renderId) ?? 0;
+        sessionCountById.set(sub.renderId, prevCount + 1);
+        if (prevCount === 0 && opts.onFirstSubscriber) {
+            try {
+                opts.onFirstSubscriber(sub.renderId);
+            }
+            catch (err) {
+                // Best-effort: a thrown hook MUST NOT corrupt the
+                // wsSubscribers set vs the real socket lifecycle.
+                opts.logger.warn("session_channel_on_first_subscriber_threw", {
+                    renderId: sub.renderId,
+                    error: String(err),
+                });
+            }
+        }
         // Start the pump loop. Fire-and-forget — pump errors are logged
         // inside pumpSubscriber, never propagated.
         void pumpSubscriber(sub);
@@ -170,6 +217,25 @@ export function createSessionChannelServer(opts) {
             return;
         subscribersByWs.delete(ws);
         wsSubscribers.delete(sub);
+        // Per-session count bookkeeping + 1→0 hook (symmetric with register).
+        const prevCount = sessionCountById.get(sub.renderId) ?? 0;
+        if (prevCount <= 1) {
+            sessionCountById.delete(sub.renderId);
+            if (prevCount === 1 && opts.onLastSubscriberGone) {
+                try {
+                    opts.onLastSubscriberGone(sub.renderId);
+                }
+                catch (err) {
+                    opts.logger.warn("session_channel_on_last_subscriber_gone_threw", {
+                        renderId: sub.renderId,
+                        error: String(err),
+                    });
+                }
+            }
+        }
+        else {
+            sessionCountById.set(sub.renderId, prevCount - 1);
+        }
         // Ending the iter terminates pumpSubscriber AND unregisters this
         // subscriber from the StreamFanout. Idempotent on the seam side
         // (close-after-return is a no-op).
@@ -190,12 +256,12 @@ export function createSessionChannelServer(opts) {
             ws.send(JSON.stringify(msg));
         }
         catch (err) {
-            opts.logger.warn('session_channel_send_failed', { error: String(err) });
+            opts.logger.warn("session_channel_send_failed", { error: String(err) });
         }
     }
     function sendError(ws, code, message, requestId, details) {
         send(ws, {
-            type: 'error',
+            type: "error",
             payload: { code, message, ...(details !== undefined ? { details } : {}) },
             ...(requestId ? { requestId } : {}),
         });
@@ -206,20 +272,20 @@ export function createSessionChannelServer(opts) {
      * AND emits the appropriate error frame when:
      *
      *   - the socket has no bound subscriber (NOT_SUBSCRIBED)
-     *   - payload.sessionId doesn't match the subscriber binding
+     *   - payload.renderId doesn't match the subscriber binding
      *     (SESSION_MISMATCH)
      *
      * Subscriber binding is the authoritative tenancy scope. The wire
-     * payload's sessionId is belt-and-suspenders so the error message
+     * payload's renderId is belt-and-suspenders so the error message
      * can be specific; appId narrows transparently via the binding.
      */
     function checkSubscriberTenancy(ws, sub, payload, messageType, requestId) {
         if (!sub) {
-            sendError(ws, 'NOT_SUBSCRIBED', `Send a 'subscribe' message first before '${messageType}'`, requestId);
+            sendError(ws, "NOT_SUBSCRIBED", `Send a 'subscribe' message first before '${messageType}'`, requestId);
             return false;
         }
-        if (payload.sessionId !== sub.sessionId) {
-            sendError(ws, 'SESSION_MISMATCH', `${messageType} payload sessionId '${payload.sessionId}' does not match subscriber session '${sub.sessionId}'`, requestId);
+        if (payload.renderId !== sub.renderId) {
+            sendError(ws, "SESSION_MISMATCH", `${messageType} payload id '${payload.renderId ?? "<missing>"}' does not match subscriber render '${sub.renderId}'`, requestId);
             return false;
         }
         return true;
@@ -232,14 +298,14 @@ export function createSessionChannelServer(opts) {
      * new shape; the next round-trip re-emits whatever the persistence
      * layer lost.
      */
-    async function applySessionPatch(sessionId, appId, messageType, patch) {
+    async function applySessionPatch(renderId, appId, messageType, patch) {
         try {
-            await opts.sessionStore.update(sessionId, patch);
+            await opts.renderStore.update(renderId, patch);
         }
         catch (err) {
-            opts.logger.warn('session_channel_observation_persist_failed', {
+            opts.logger.warn("session_channel_observation_persist_failed", {
                 messageType,
-                sessionId,
+                renderId,
                 appId,
                 error: err instanceof Error ? err.message : String(err),
             });
@@ -248,19 +314,19 @@ export function createSessionChannelServer(opts) {
     /**
      * Emit a `channel_error` frame to a specific subscriber. Used by the
      * `channel_subscribe` handler for both subscribe-time rejections
-     * (`CHANNEL_UNKNOWN`, `CHANNEL_NOT_LOCAL`, `STACK_ITEM_NOT_FOUND`,
+     * (`CHANNEL_UNKNOWN`, `CHANNEL_NOT_LOCAL`, `RENDER_NOT_FOUND`,
      * `SUBSCRIBE_UNAUTHORIZED`) AND poll-time failures (`POLL_FAILED`).
      *
      * Direct-to-WS, not via fanOut — channel_error frames are
      * per-subscriber and not stored in the replay buffer. A new
-     * subscriber on the same session will re-subscribe and discover the
+     * subscriber on the same render will re-subscribe and discover the
      * same error itself.
      */
-    function sendChannelError(ws, sessionId, channelName, code, message, requestId, details) {
+    function sendChannelError(ws, renderId, channelName, code, message, requestId, details) {
         send(ws, {
-            type: 'channel_error',
+            type: "channel_error",
             payload: {
-                sessionId,
+                renderId,
                 channelName,
                 code,
                 message,
@@ -276,7 +342,7 @@ export function createSessionChannelServer(opts) {
      * docstring — clients propose, server clamps.
      */
     function clampPollInterval(supplied) {
-        if (typeof supplied !== 'number' || !Number.isFinite(supplied)) {
+        if (typeof supplied !== "number" || !Number.isFinite(supplied)) {
             return pollDefaultMs;
         }
         if (supplied < pollFloorMs)
@@ -310,11 +376,10 @@ export function createSessionChannelServer(opts) {
                 return;
             state.seq += 1;
             send(sub.ws, {
-                type: 'channel_payload',
+                type: "channel_payload",
                 payload: {
-                    sessionId: sub.sessionId,
+                    renderId: sub.renderId,
                     appId: sub.appId,
-                    stackItemId: state.stackItemId,
                     channelName: state.channelName,
                     seq: state.seq,
                     ts: new Date().toISOString(),
@@ -323,7 +388,7 @@ export function createSessionChannelServer(opts) {
                     // append semantics declare `mode: 'append'` on streamSpec;
                     // honoring that is the iframe-runtime's concern at fold
                     // time. See `ChannelPayloadFrame.mode`.
-                    mode: 'replace',
+                    mode: "replace",
                     payload: output,
                 },
             });
@@ -331,14 +396,13 @@ export function createSessionChannelServer(opts) {
         catch (err) {
             if (sub.ws.readyState !== sub.ws.OPEN)
                 return;
-            sendChannelError(sub.ws, sub.sessionId, state.channelName, 'POLL_FAILED', err instanceof Error ? err.message : String(err), undefined, 
+            sendChannelError(sub.ws, sub.renderId, state.channelName, "POLL_FAILED", err instanceof Error ? err.message : String(err), undefined, 
             // causedBy slot — sanitized for credential safety in the same
             // posture as wired-tool's TOOL_THREW emission.
             sanitize(err instanceof Error ? (err.stack ?? err.message) : String(err)));
-            opts.logger.warn('session_channel_channel_poll_failed', {
-                sessionId: sub.sessionId,
+            opts.logger.warn("session_channel_channel_poll_failed", {
+                renderId: sub.renderId,
                 appId: sub.appId,
-                stackItemId: state.stackItemId,
                 channelName: state.channelName,
                 toolName: state.toolName,
                 error: String(err),
@@ -349,63 +413,54 @@ export function createSessionChannelServer(opts) {
      * Handle a `channel_subscribe` message. Validates the request,
      * resolves the channel's `source.tool` against the configured
      * allowlist, and schedules a polling loop. Idempotent on
-     * `${stackItemId}:${channelName}` — a re-subscribe replaces any
+     * `${renderId}:${channelName}` — a re-subscribe replaces any
      * existing interval rather than running two in parallel.
      */
     async function handleChannelSubscribe(ws, sub, message) {
         const payload = message.payload;
-        // sessionId match — the spoof guard at every wire-input boundary.
+        // renderId match — the spoof guard at every wire-input boundary.
         // A subscriber bound to session A can't drive a subscribe for
         // session B even if they crafted the inbound payload.
-        if (payload.sessionId !== sub.sessionId) {
-            sendChannelError(ws, payload.sessionId, payload.channelName, 'SUBSCRIBE_UNAUTHORIZED', `Subscriber is bound to session '${sub.sessionId}' but channel_subscribe targets '${payload.sessionId}'`, message.requestId);
+        if (payload.renderId !== sub.renderId) {
+            sendChannelError(ws, payload.renderId, payload.channelName, "SUBSCRIBE_UNAUTHORIZED", `Subscriber is bound to session '${sub.renderId}' but channel_subscribe targets '${payload.renderId}'`, message.requestId);
             return;
         }
         // Without an `streamWebSocketLocalTools` allowlist, no channel
         // can be subscribed locally. The iframe must fall back to direct
         // polling via the MCP host proxy.
         if (!localTools) {
-            sendChannelError(ws, payload.sessionId, payload.channelName, 'CHANNEL_NOT_LOCAL', 'This server has no streamWebSocketLocalTools allowlist; iframe must poll the source tool directly.', message.requestId);
+            sendChannelError(ws, payload.renderId, payload.channelName, "CHANNEL_NOT_LOCAL", "This server has no streamWebSocketLocalTools allowlist; iframe must poll the source tool directly.", message.requestId);
             return;
         }
-        // Resolve `streamSpec[channelName].source.tool` against the active
-        // stack item. The reverse-index lookup is O(1); we then load the
-        // session + look up the stack entry by id.
-        const indexEntry = await opts.sessionStore.getSessionByStackItemId(payload.stackItemId);
-        if (!indexEntry || indexEntry.sessionId !== sub.sessionId) {
-            sendChannelError(ws, payload.sessionId, payload.channelName, 'STACK_ITEM_NOT_FOUND', `Stack item '${payload.stackItemId}' not found on session '${payload.sessionId}'`, message.requestId);
-            return;
-        }
-        const session = await opts.sessionStore.get(indexEntry.sessionId);
-        if (!session) {
-            sendChannelError(ws, payload.sessionId, payload.channelName, 'STACK_ITEM_NOT_FOUND', `Session '${indexEntry.sessionId}' no longer exists`, message.requestId);
-            return;
-        }
-        const stackItem = session.stack.find((it) => it.id === payload.stackItemId);
-        if (!stackItem) {
-            sendChannelError(ws, payload.sessionId, payload.channelName, 'STACK_ITEM_NOT_FOUND', `Stack item '${payload.stackItemId}' not found on session '${payload.sessionId}'`, message.requestId);
+        // Phase B: a render IS the addressable unit. The prior
+        // reverse-index lookup collapses — `renderStore.get` resolves
+        // the render directly.
+        const stored = await opts.renderStore.get(payload.renderId);
+        if (!stored || stored.id !== sub.renderId) {
+            sendChannelError(ws, payload.renderId, payload.channelName, "RENDER_NOT_FOUND", `Render '${payload.renderId}' not found on subscriber '${sub.renderId}'`, message.requestId);
             return;
         }
+        const render = stored.render;
         // Channel entry resolution. mcpApps / system variants have no
         // streamSpec so the field reads back as undefined — same code
         // path as a component variant without the channel declared.
-        const streamSpec = stackItem.type === 'mcpApps' || stackItem.type === 'system'
+        const streamSpec = render.type === "mcpApps" || render.type === "system"
             ? undefined
-            : stackItem.streamSpec;
+            : render.streamSpec;
         const channelEntry = streamSpec?.[payload.channelName];
         if (!channelEntry || !channelEntry.source) {
-            sendChannelError(ws, payload.sessionId, payload.channelName, 'CHANNEL_UNKNOWN', `streamSpec['${payload.channelName}'] not declared OR has no source.tool on stack item '${payload.stackItemId}'`, message.requestId);
+            sendChannelError(ws, payload.renderId, payload.channelName, "CHANNEL_UNKNOWN", `streamSpec['${payload.channelName}'] not declared OR has no source.tool on render '${payload.renderId}'`, message.requestId);
             return;
         }
         const sourceTool = channelEntry.source.tool;
         if (!localToolsAllowlist.has(sourceTool)) {
-            sendChannelError(ws, payload.sessionId, payload.channelName, 'CHANNEL_NOT_LOCAL', `source.tool '${sourceTool}' is not in streamWebSocketLocalTools; iframe must poll directly`, message.requestId);
+            sendChannelError(ws, payload.renderId, payload.channelName, "CHANNEL_NOT_LOCAL", `source.tool '${sourceTool}' is not in streamWebSocketLocalTools; iframe must poll directly`, message.requestId);
             return;
         }
         // Validation passed — schedule (or re-schedule) the polling loop.
-        const channelKey = `${payload.stackItemId}:${payload.channelName}`;
+        const channelKey = `${payload.renderId}:${payload.channelName}`;
         // Idempotent replace: a reconnect that re-subscribes the same
-        // (stackItem, channel) pair gets a fresh timer + zeroed seq. The
+        // (render, channel) pair gets a fresh timer + zeroed seq. The
         // client's gap-detection treats it as a new stream from the
         // server's perspective; client-side reconnect logic owns
         // continuity if the channel was declared `mode: 'append'`.
@@ -439,17 +494,16 @@ export function createSessionChannelServer(opts) {
         const state = {
             pollIntervalMs,
             toolName: sourceTool,
-            stackItemId: payload.stackItemId,
+            renderId: payload.renderId,
             channelName: payload.channelName,
             args: mergedArgs,
             seq: 0,
             timer,
         };
         sub.channelSubs.set(channelKey, state);
-        opts.logger.info('session_channel_channel_subscribe', {
-            sessionId: sub.sessionId,
+        opts.logger.info("render_channel_channel_subscribe", {
+            renderId: sub.renderId,
             appId: sub.appId,
-            stackItemId: payload.stackItemId,
             channelName: payload.channelName,
             toolName: sourceTool,
             pollIntervalMs,
@@ -468,22 +522,21 @@ export function createSessionChannelServer(opts) {
      */
     function handleChannelUnsubscribe(_ws, sub, message) {
         const payload = message.payload;
-        if (payload.sessionId !== sub.sessionId) {
+        if (payload.renderId !== sub.renderId) {
             // No-op silently — the canonical "spoof guard" code path is in
             // channel_subscribe; unsubscribe gets no error frame to avoid
             // leaking cross-session existence.
             return;
         }
-        const channelKey = `${payload.stackItemId}:${payload.channelName}`;
+        const channelKey = `${payload.renderId}:${payload.channelName}`;
         const existing = sub.channelSubs.get(channelKey);
         if (!existing)
             return;
         clearInterval(existing.timer);
         sub.channelSubs.delete(channelKey);
-        opts.logger.info('session_channel_channel_unsubscribe', {
-            sessionId: sub.sessionId,
+        opts.logger.info("render_channel_channel_unsubscribe", {
+            renderId: sub.renderId,
             appId: sub.appId,
-            stackItemId: payload.stackItemId,
             channelName: payload.channelName,
         });
     }
@@ -510,7 +563,7 @@ export function createSessionChannelServer(opts) {
         // because publish() never throws on the in-process impl, and a hosted
         // RedisPubSubFanout failure here would already be persisted to the
         // SessionStreamBuffer for replay-recovery on reconnect.
-        void streamFanout.publish({ sessionId: envelope.sessionId, envelope });
+        void streamFanout.publish({ renderId: envelope.renderId, envelope });
         return { seq: envelope.seq };
     }
     /**
@@ -519,7 +572,7 @@ export function createSessionChannelServer(opts) {
      * dispatch path calls this from `catch` branches; a second failure
      * would be a footgun.
      */
-    function emitContractError(sessionId, activeStreamSpec, payload) {
+    function emitContractError(renderId, activeStreamSpec, payload) {
         try {
             // Central stamp — re-emit through makeContractErrorPayload so
             // every contract-error envelope carries the current stamped
@@ -533,12 +586,8 @@ export function createSessionChannelServer(opts) {
                 toolName: payload.toolName,
                 error: payload.error,
                 timestamp: payload.timestamp,
-                ...(payload.actionName !== undefined
-                    ? { actionName: payload.actionName }
-                    : {}),
-                ...(payload.sourceAction !== undefined
-                    ? { sourceAction: payload.sourceAction }
-                    : {}),
+                ...(payload.actionName !== undefined ? { actionName: payload.actionName } : {}),
+                ...(payload.sourceAction !== undefined ? { sourceAction: payload.sourceAction } : {}),
             });
             // Fire-and-forget: emitContractError is called from sync `catch`
             // branches and a second async failure here would be a footgun.
@@ -546,13 +595,13 @@ export function createSessionChannelServer(opts) {
             // says publish never throws on InProcess impl, and a hosted
             // RedisPubSubFanout failure is recoverable via replay-on-reconnect.
             void fanOut({
-                sessionId,
+                renderId,
                 channel: CONTRACT_ERROR_CHANNEL,
-                mode: 'append',
+                mode: "append",
                 payload: stamped,
             }, activeStreamSpec).catch((err) => {
-                opts.logger.error('session_channel_contract_error_emit_failed', {
-                    sessionId,
+                opts.logger.error("session_channel_contract_error_emit_failed", {
+                    renderId,
                     toolName: payload.toolName,
                     code: payload.error.code,
                     error: String(err),
@@ -560,8 +609,8 @@ export function createSessionChannelServer(opts) {
             });
         }
         catch (err) {
-            opts.logger.error('session_channel_contract_error_emit_failed', {
-                sessionId,
+            opts.logger.error("session_channel_contract_error_emit_failed", {
+                renderId,
                 toolName: payload.toolName,
                 code: payload.error.code,
                 error: String(err),
@@ -598,52 +647,41 @@ export function createSessionChannelServer(opts) {
         }
     }
     /**
-     * Internal impl behind the public {@link SessionChannelServer.sendPropsUpdate}.
+     * Internal impl behind the public {@link RenderChannelServer.sendPropsUpdate}.
      * Extracted as a closure-level function so the wired-action dispatcher
      * can build a `WiredActionContext.sendPropsUpdate` that closes over the
      * same logic without forward-referencing the returned object. Best-
      * effort + orphan-tolerant per the docstring on the public method.
      */
-    async function sendPropsUpdateImpl(sessionId, stackItemId, props) {
-        let session;
+    async function sendPropsUpdateImpl(renderId, props) {
+        let stored;
         try {
-            session = await opts.sessionStore.get(sessionId);
+            stored = await opts.renderStore.get(renderId);
         }
         catch (err) {
-            opts.logger.warn('session_channel_props_update_lookup_failed', {
-                sessionId,
-                stackItemId,
+            opts.logger.warn("render_channel_props_update_lookup_failed", {
+                renderId,
                 error: String(err),
             });
             return;
         }
-        if (!session) {
-            opts.logger.warn('session_channel_props_update_orphan', {
-                sessionId,
-                stackItemId,
-            });
-            return;
-        }
-        const targetIndex = session.stack.findIndex((item) => item.id === stackItemId);
-        if (targetIndex < 0) {
-            opts.logger.warn('session_channel_props_update_pageid_unknown', {
-                sessionId,
-                stackItemId,
-                stackSize: session.stack.length,
+        if (!stored) {
+            opts.logger.warn("render_channel_props_update_orphan", {
+                renderId,
             });
             return;
         }
-        // Filter the flat WS-subscriber set by sessionId; same posture as
-        // `notifyStackPush`. `send()` already silently skips closed sockets
+        // Filter the flat WS-subscriber set by renderId; same posture as
+        // `notifyRenderPush`. `send()` already silently skips closed sockets
         // and logs (but doesn't throw on) per-subscriber send failures, so
         // the caller's mount-handler path can't be made to fail by a dead
         // WebSocket.
         for (const sub of wsSubscribers) {
-            if (sub.sessionId !== sessionId)
+            if (sub.renderId !== renderId)
                 continue;
             send(sub.ws, {
-                type: 'props_update',
-                payload: { stackItemId, props },
+                type: "props_update",
+                payload: { renderId, props },
             });
         }
     }
@@ -667,12 +705,17 @@ export function createSessionChannelServer(opts) {
      * need filter args should inline the action + refresh into a single
      * tool that returns the new state.
      */
-    async function dispatchWiredAction(session, activeItem, envelope, dispatchedAt) {
+    async function dispatchWiredAction(stored, activeItem, envelope, dispatchedAt) {
+        // Post-Phase-B, the active "session" is just the stored render's
+        // id. Keep a `session` alias inside the body so the existing
+        // `session.id` references stay readable without a wholesale
+        // re-name pass.
+        const session = stored;
         const router = opts.wiredActionRouter;
-        if (!router || !activeItem || envelope.type !== 'data:submit')
+        if (!router || !activeItem || envelope.type !== "data:submit")
             return;
         const payload = envelope.payload;
-        if (!payload || typeof payload.action !== 'string')
+        if (!payload || typeof payload.action !== "string")
             return;
         // Disagreement policy — the server-side enforcement point for the
         // `client wins` rule documented on `ActionEventValue.tool`. Prefer
@@ -683,32 +726,34 @@ export function createSessionChannelServer(opts) {
         // client is the source of truth for what the user actually saw.
         // Cross-validation against the agent's tracked contract happens on
         // the agent-SDK side, not here.
-        const actionEntry = activeItem.actionSpec?.[payload.action];
+        // actionSpec / streamSpec only exist on ComponentRender. The
+        // mcpApps / system variants narrow them to undefined.
+        const componentItem = activeItem.type === "mcpApps" || activeItem.type === "system" ? undefined : activeItem;
+        const actionEntry = componentItem?.actionSpec?.[payload.action];
         const serverDeclaredTool = actionEntry?.nextStep;
-        const declaredTool = (typeof payload.tool === 'string' && payload.tool.length > 0
-            ? payload.tool
-            : undefined) ?? serverDeclaredTool;
+        const declaredTool = (typeof payload.tool === "string" && payload.tool.length > 0 ? payload.tool : undefined) ??
+            serverDeclaredTool;
         if (!declaredTool)
             return;
         const actionName = payload.action;
-        const input = payload.data && typeof payload.data === 'object' && !Array.isArray(payload.data)
+        const input = payload.data && typeof payload.data === "object" && !Array.isArray(payload.data)
             ? payload.data
             : {};
         const timeoutMs = opts.wiredActionTimeoutMs ?? DEFAULT_WIRED_TOOL_TIMEOUT_MS;
-        const streamSpec = activeItem.streamSpec;
+        const streamSpec = componentItem?.streamSpec;
         if (!router.has(declaredTool)) {
             emitContractError(session.id, streamSpec, {
                 toolName: declaredTool,
                 actionName,
-                sourceAction: { type: 'wired-action', dispatchedAt },
+                sourceAction: { type: "wired-action", dispatchedAt },
                 error: {
-                    code: 'TOOL_NOT_FOUND',
+                    code: "TOOL_NOT_FOUND",
                     message: `wiredActionRouter has no handler for tool '${declaredTool}'`,
                 },
                 timestamp: new Date().toISOString(),
             });
-            opts.logger.warn('session_channel_wired_tool_not_found', {
-                sessionId: session.id,
+            opts.logger.warn("session_channel_wired_tool_not_found", {
+                renderId: session.id,
                 toolName: declaredTool,
                 actionName,
             });
@@ -717,15 +762,14 @@ export function createSessionChannelServer(opts) {
         // Build the wired-action context the router hands the mount tool.
         // `sendPropsUpdate` closes over the active
         // `session.id` so a buggy mount can't accidentally cross-deliver to
-        // another session by passing a foreign sessionId. The same ctx is
+        // another session by passing a foreign renderId. The same ctx is
         // reused for the refresh-stream pass below — a refresh tool that
         // wants to fire props_update can do so, though the canonical site
         // is the action tool itself.
         const wiredCtx = {
-            sessionId: session.id,
-            stackItemId: activeItem.id,
-            sendPropsUpdate(targetStackItemId, props) {
-                void sendPropsUpdateImpl(session.id, targetStackItemId, props);
+            renderId: session.id,
+            sendPropsUpdate(props) {
+                void sendPropsUpdateImpl(session.id, props);
             },
         };
         const invokeStartedAt = Date.now();
@@ -733,22 +777,20 @@ export function createSessionChannelServer(opts) {
             await invokeWithTimeout(router, declaredTool, input, wiredCtx, timeoutMs);
         }
         catch (err) {
-            const code = err instanceof WiredToolTimeoutError ? 'TOOL_TIMEOUT' : 'TOOL_THREW';
+            const code = err instanceof WiredToolTimeoutError ? "TOOL_TIMEOUT" : "TOOL_THREW";
             emitContractError(session.id, streamSpec, {
                 toolName: declaredTool,
                 actionName,
-                sourceAction: { type: 'wired-action', dispatchedAt },
+                sourceAction: { type: "wired-action", dispatchedAt },
                 error: {
                     code,
                     message: err instanceof Error ? err.message : String(err),
-                    ...(err instanceof Error && err.stack
-                        ? { causedBy: sanitize(err.stack) }
-                        : {}),
+                    ...(err instanceof Error && err.stack ? { causedBy: sanitize(err.stack) } : {}),
                 },
                 timestamp: new Date().toISOString(),
             });
-            opts.logger.warn('session_channel_wired_tool_failed', {
-                sessionId: session.id,
+            opts.logger.warn("session_channel_wired_tool_failed", {
+                renderId: session.id,
                 toolName: declaredTool,
                 actionName,
                 code,
@@ -761,12 +803,12 @@ export function createSessionChannelServer(opts) {
         // sink MUST NOT block the refresh pass. Attribute set is kept
         // flat + primitive-only per TelemetryEvent.attributes shape.
         telemetry.emit({
-            name: 'wired-tool.invoked',
+            name: "wired-tool.invoked",
             at: Date.now(),
             attributes: {
                 toolName: declaredTool,
                 actionName,
-                sessionId: session.id,
+                renderId: session.id,
                 latencyMs: Date.now() - invokeStartedAt,
             },
         });
@@ -784,9 +826,9 @@ export function createSessionChannelServer(opts) {
                 emitContractError(session.id, streamSpec, {
                     toolName: refreshTool,
                     actionName,
-                    sourceAction: { type: 'refresh-stream', dispatchedAt },
+                    sourceAction: { type: "refresh-stream", dispatchedAt },
                     error: {
-                        code: 'TOOL_NOT_FOUND',
+                        code: "TOOL_NOT_FOUND",
                         message: `wiredActionRouter has no handler for refresh tool '${refreshTool}' (channel '${channelName}')`,
                     },
                     timestamp: new Date().toISOString(),
@@ -803,22 +845,20 @@ export function createSessionChannelServer(opts) {
                 output = await invokeWithTimeout(router, refreshTool, EMPTY_REFRESH_INPUT, wiredCtx, timeoutMs);
             }
             catch (err) {
-                const code = err instanceof WiredToolTimeoutError ? 'TOOL_TIMEOUT' : 'TOOL_THREW';
+                const code = err instanceof WiredToolTimeoutError ? "TOOL_TIMEOUT" : "TOOL_THREW";
                 emitContractError(session.id, streamSpec, {
                     toolName: refreshTool,
                     actionName,
-                    sourceAction: { type: 'refresh-stream', dispatchedAt },
+                    sourceAction: { type: "refresh-stream", dispatchedAt },
                     error: {
                         code,
                         message: err instanceof Error ? err.message : String(err),
-                        ...(err instanceof Error && err.stack
-                            ? { causedBy: sanitize(err.stack) }
-                            : {}),
+                        ...(err instanceof Error && err.stack ? { causedBy: sanitize(err.stack) } : {}),
                     },
                     timestamp: new Date().toISOString(),
                 });
-                opts.logger.warn('session_channel_refresh_tool_failed', {
-                    sessionId: session.id,
+                opts.logger.warn("session_channel_refresh_tool_failed", {
+                    renderId: session.id,
                     toolName: refreshTool,
                     channel: channelName,
                     code,
@@ -834,15 +874,15 @@ export function createSessionChannelServer(opts) {
                     emitContractError(session.id, streamSpec, {
                         toolName: refreshTool,
                         actionName,
-                        sourceAction: { type: 'refresh-stream', dispatchedAt },
+                        sourceAction: { type: "refresh-stream", dispatchedAt },
                         error: {
-                            code: 'SCHEMA_VIOLATION',
+                            code: "SCHEMA_VIOLATION",
                             message: err.message,
                         },
                         timestamp: new Date().toISOString(),
                     });
-                    opts.logger.warn('session_channel_refresh_schema_violation', {
-                        sessionId: session.id,
+                    opts.logger.warn("session_channel_refresh_schema_violation", {
+                        renderId: session.id,
                         toolName: refreshTool,
                         channel: channelName,
                         violations: err.violations,
@@ -853,9 +893,9 @@ export function createSessionChannelServer(opts) {
             }
             try {
                 await fanOut({
-                    sessionId: session.id,
+                    renderId: session.id,
                     channel: channelName,
-                    mode: channelEntry?.mode ?? 'append',
+                    mode: channelEntry?.mode ?? "append",
                     payload: output,
                 }, streamSpec);
             }
@@ -864,8 +904,8 @@ export function createSessionChannelServer(opts) {
                 // is buffer-internal (e.g., record() invariant violation). Log
                 // but don't propagate — a single broken channel must not take
                 // down the session.
-                opts.logger.error('session_channel_refresh_emit_failed', {
-                    sessionId: session.id,
+                opts.logger.error("session_channel_refresh_emit_failed", {
+                    renderId: session.id,
                     toolName: refreshTool,
                     channel: channelName,
                     error: String(err),
@@ -874,40 +914,40 @@ export function createSessionChannelServer(opts) {
         }
     }
     async function resolveIdentityFromUpgrade(req) {
-        const url = new URL(req.url ?? '/', 'http://localhost');
-        // Bootstrap gate: when `?bootstrap=` is present AND the channel is
-        // configured with bootstrap plumbing, skip the AuthAdapter entirely
-        // at upgrade. The real identity is established in handleSubscribe
-        // when the subscribe payload's `bootstrap` token is verified
-        // (single-use jti claimed there). This is how MCP Apps iframes
-        // connect — they can't set Authorization headers, and the token
-        // model is subscribe-scoped anyway.
+        const url = new URL(req.url ?? "/", "http://localhost");
+        // WS-token gate: when `?wsToken=` is present AND the channel is
+        // configured with ws-token-auth plumbing, skip the AuthAdapter
+        // entirely at upgrade. The real identity is established in
+        // handleSubscribe when the subscribe payload's `wsToken` is
+        // verified. This is how MCP Apps iframes connect — they can't set
+        // Authorization headers, and the token model is subscribe-scoped
+        // anyway.
         //
         // URL-gate here is NOT verification — it's a "don't reject the
         // upgrade for missing bearer" signal. The real verify runs at
         // subscribe time; an invalid token reaches that point and is
         // rejected with BOOTSTRAP_INVALID.
-        if (opts.bootstrap && url.searchParams.has('bootstrap')) {
+        if (opts.bootstrap && url.searchParams.has("wsToken")) {
             return {
                 identity: {
-                    kind: 'user',
-                    userId: '__bootstrap_pending__',
-                    workspaceId: '__bootstrap_pending__',
+                    kind: "user",
+                    userId: "__bootstrap_pending__",
+                    workspaceId: "__bootstrap_pending__",
                     roles: [],
                 },
-                source: 'apikey',
+                source: "apikey",
             };
         }
         // Embedded-ui cookie gate. Consulted ONLY when the channel is
         // configured with cookie-auth plumbing AND no bootstrap is in
         // play. Unlike bootstrap, cookies ARE verified here: the single
         // consumer (console SPA) sets the cookie out-of-band via
-        // `POST /ggui/console/session-cookie` and we do want to
+        // `POST /ggui/console/render-cookie` and we do want to
         // reject the upgrade cleanly (HTTP 401 → browser WS error) when
         // the cookie is stale/missing, not carry a doomed handshake into
         // subscribe where the error surface is worse.
         //
-        // On success, we stash the bound `{sessionId, appId}` on the
+        // On success, we stash the bound `{renderId, appId}` on the
         // request so `handleSubscribe` can enforce that the subscribe
         // payload targets exactly those values. No synthesis from the
         // AuthAdapter — cookies ARE the auth signal.
@@ -918,14 +958,14 @@ export function createSessionChannelServer(opts) {
                 if (bound) {
                     req.__gguiCookieBound = bound;
                     return {
-                        identity: { kind: 'builder' },
-                        source: 'apikey',
+                        identity: { kind: "builder" },
+                        source: "apikey",
                     };
                 }
                 // Cookie present but invalid — do NOT fall through to the
                 // bearer path. An invalid cookie is a same-origin user error,
                 // not a pass-through condition.
-                throw new UnauthenticatedError('console cookie invalid');
+                throw new UnauthenticatedError("console cookie invalid");
             }
             // No cookie present → fall through to bearer path below. Mixed
             // deployments (pairing-token bearer + same-origin cookie for
@@ -935,33 +975,28 @@ export function createSessionChannelServer(opts) {
         // to `?token=<jwt>` for web clients, matching the convention most
         // session-channel endpoints ship with. Server-side clients (Node
         // `ws`, tests) continue to set the header directly.
-        if (!req.headers['authorization']) {
-            const token = url.searchParams.get('token');
+        if (!req.headers["authorization"]) {
+            const token = url.searchParams.get("token");
             if (token) {
-                req.headers['authorization'] = `Bearer ${token}`;
+                req.headers["authorization"] = `Bearer ${token}`;
             }
         }
         return resolveIdentityFromHeaders(opts.auth, req.headers, req.socket?.remoteAddress ?? undefined);
     }
     /**
-     * Resolve the stack item the event claims to originate from, using the
-     * SAME authoritative index as the hosted ingress (`gguiEvent.context
-     * .stackIndex`, falling back to `session.currentStackIndex`). If the
-     * session has popped forward between emit and ingress, validating
-     * against the newer stack item would reject legitimate in-flight
-     * actions — the doctrine pins context.stackIndex as the truth.
+     * Resolve the active render variant for contract enforcement. Phase
+     * B collapsed the prior (stack, currentStackIndex) lookup — a render
+     * IS the addressable unit, so the active render is the stored render
+     * itself. MCP Apps / system variants narrow to `undefined` so
+     * upstream enforcement skips (allowlist + actionSpec checks are
+     * no-ops when no `ComponentRender` is active).
      */
-    function resolveActiveStackItem(session, stackIndex) {
-        if (stackIndex < 0 || stackIndex >= session.stack.length)
+    function resolveActiveRender(render) {
+        if (!render)
             return undefined;
-        const entry = session.stack[stackIndex];
-        // MCP Apps items don't participate in ggui's contract enforcement —
-        // they're embedded vendor iframes with their own contract. Return
-        // `undefined` so upstream enforcement skips (allowlist + actionSpec
-        // checks are no-ops when no ComponentStackItem is active).
-        if (entry.type === 'mcpApps' || entry.type === 'system')
+        if (render.type === "mcpApps" || render.type === "system")
             return undefined;
-        return entry;
+        return render;
     }
     /**
      * Handle an inbound `action` message — the canonical flat
@@ -975,83 +1010,80 @@ export function createSessionChannelServer(opts) {
      */
     async function handleInboundAction(ws, sub, message) {
         const envelope = message.payload;
-        // Spoof guard — envelope.sessionId is REQUIRED on the wire and
+        // Spoof guard — envelope.renderId is REQUIRED on the wire and
         // MUST match the subscriber's bound session.
-        if (envelope.sessionId !== sub.sessionId) {
-            sendError(ws, 'SESSION_MISMATCH', `Action targets session '${envelope.sessionId}' but this socket is subscribed to '${sub.sessionId}'`, message.requestId);
+        if (envelope.renderId !== sub.renderId) {
+            sendError(ws, "SESSION_MISMATCH", `Action targets session '${envelope.renderId}' but this socket is subscribed to '${sub.renderId}'`, message.requestId);
             return;
         }
-        const session = await opts.sessionStore.get(sub.sessionId);
-        if (!session) {
-            sendError(ws, 'SESSION_NOT_FOUND', `Session ${sub.sessionId} no longer exists`, message.requestId);
+        const stored = await opts.renderStore.get(sub.renderId);
+        if (!stored) {
+            sendError(ws, "RENDER_NOT_FOUND", `Render ${sub.renderId} no longer exists`, message.requestId);
             return;
         }
-        // Stack routing: ActionEnvelope may carry stackIndex OR stackItemId.
-        // When both are present, stackItemId wins (doctrine-aligned — stable
-        // identity beats positional index). When neither is present, fall
-        // back to session.currentStackIndex.
-        let stackIndex = envelope.stackIndex ?? session.currentStackIndex;
-        if (envelope.stackItemId !== undefined) {
-            const byId = session.stack.findIndex((s) => s.id === envelope.stackItemId);
-            if (byId >= 0)
-                stackIndex = byId;
-        }
-        const activeItem = resolveActiveStackItem(session, stackIndex);
+        // Phase B: a render IS the addressable unit. The prior stack
+        // routing (stackIndex / cross-stack pickIds) collapses — the
+        // resolved render itself is the active item.
+        const activeItem = resolveActiveRender(stored.render);
         // ── Two-step enforcement ──
-        //   1. allowlist via assertEventAllowed
+        //   1. allowlist via assertEventAllowed (Phase B: no-op stub —
+        //      Render no longer carries a `subscription` allowlist;
+        //      reinstating per-render event policy is deferred.)
         //   2. actionSpec payload check via assertActionContract (data:submit)
         // Envelope.payload for data:submit carries the ActionEventValue
         // shape (`{action, data?, tool?}`).
         try {
-            assertEventAllowed(activeItem?.subscription, envelope.type);
+            assertEventAllowed(undefined, envelope.type);
         }
         catch (err) {
             if (err instanceof EventNotAllowedError) {
-                opts.logger.warn('session_channel_event_not_allowed', {
-                    sessionId: sub.sessionId,
-                    eventType: err.eventType,
-                    allowedEvents: err.allowedEvents,
-                    envelope: 'action',
+                opts.logger.warn("render_channel_event_not_allowed", {
+                    renderId: sub.renderId,
+                    envelope: "action",
+                    error: err.message,
                 });
-                sendError(ws, 'EVENT_NOT_ALLOWED', err.message, message.requestId, err.toErrorData());
+                sendError(ws, "EVENT_NOT_ALLOWED", err.message, message.requestId);
                 return;
             }
             throw err;
         }
-        if (envelope.type === 'data:submit') {
+        if (envelope.type === "data:submit") {
             try {
-                assertActionContract(activeItem?.actionSpec, envelope.payload);
+                const activeActionSpec = activeItem && activeItem.type !== "mcpApps" && activeItem.type !== "system"
+                    ? activeItem.actionSpec
+                    : undefined;
+                assertActionContract(activeActionSpec, envelope.payload);
             }
             catch (err) {
                 if (err instanceof ContractViolationError) {
-                    opts.logger.warn('session_channel_contract_violation', {
-                        sessionId: sub.sessionId,
+                    opts.logger.warn("session_channel_contract_violation", {
+                        renderId: sub.renderId,
                         violations: err.violations,
-                        envelope: 'action',
+                        envelope: "action",
                     });
-                    sendError(ws, 'CONTRACT_VIOLATION', err.message, message.requestId, err.toErrorData());
+                    sendError(ws, "CONTRACT_VIOLATION", err.message, message.requestId, err.toErrorData());
                     return;
                 }
                 throw err;
             }
         }
-        // Persist the envelope. SessionStore.appendEvent assigns a monotonic
+        // Persist the envelope. RenderStore.appendEvent assigns a monotonic
         // seq the client acks back with so reconnects can resume via `fromSeq`.
         const dispatchedAt = new Date().toISOString();
         let seq;
         try {
-            seq = await opts.sessionStore.appendEvent({
-                sessionId: sub.sessionId,
-                type: 'user.submitted',
+            seq = await opts.renderStore.appendEvent({
+                renderId: sub.renderId,
+                type: "user.submitted",
                 data: envelope,
             });
         }
         catch (err) {
-            opts.logger.error('session_channel_append_failed', {
-                sessionId: sub.sessionId,
+            opts.logger.error("session_channel_append_failed", {
+                renderId: sub.renderId,
                 error: String(err),
             });
-            sendError(ws, 'APPEND_FAILED', err instanceof Error ? err.message : String(err), message.requestId);
+            sendError(ws, "APPEND_FAILED", err instanceof Error ? err.message : String(err), message.requestId);
             return;
         }
         // wiredActionRouter — fire any declared action-tool +
@@ -1065,7 +1097,7 @@ export function createSessionChannelServer(opts) {
         // catches every failure and emits contract-error envelopes; a
         // throw out of this call would be a platform bug and we'd rather
         // see it in tests than silently drop.
-        await dispatchWiredAction(session, activeItem, envelope, dispatchedAt);
+        await dispatchWiredAction(stored, activeItem, envelope, dispatchedAt);
         // StreamFanout pump-drain: dispatchWiredAction's internal fanOut
         // calls `streamFanout.publish()` which queues envelopes into the
         // pump's async iterator. The pump's `await iter.next()` resolves
@@ -1079,7 +1111,7 @@ export function createSessionChannelServer(opts) {
         // independent signals.
         await new Promise((resolve) => setImmediate(resolve));
         send(ws, {
-            type: 'ack',
+            type: "ack",
             payload: { sequence: seq, timestamp: Date.now() },
             ...(message.requestId ? { requestId: message.requestId } : {}),
         });
@@ -1099,7 +1131,7 @@ export function createSessionChannelServer(opts) {
         //     pre-handshake.
         //
         // Placed FIRST — before bootstrap verify (which consumes the
-        // single-use bootstrap token per the SessionChannelBootstrap
+        // single-use bootstrap token per the RenderChannelBootstrap
         // docstring) and before session lookup/creation (DB work).
         // Bootstrap iframes with a version mismatch must retry with a
         // fresh bootstrap token; burning the token on a mismatch the
@@ -1108,21 +1140,21 @@ export function createSessionChannelServer(opts) {
         if (Array.isArray(payload.supportedVersions) &&
             payload.supportedVersions.length > 0 &&
             !payload.supportedVersions.includes(PROTOCOL_SCHEMA_VERSION)) {
-            const policy = opts.versionPolicy ?? 'reject';
+            const policy = opts.versionPolicy ?? "reject";
             sendError(ws, UPGRADE_REQUIRED, `Server speaks ${PROTOCOL_SCHEMA_VERSION}; client declared ` +
-                `supportedVersions=[${payload.supportedVersions.join(', ')}].`, message.requestId, {
+                `supportedVersions=[${payload.supportedVersions.join(", ")}].`, message.requestId, {
                 serverVersion: PROTOCOL_SCHEMA_VERSION,
                 clientSupportedVersions: payload.supportedVersions,
                 policy,
             });
-            opts.logger.warn('session_channel_version_mismatch', {
-                sessionId: payload.sessionId,
+            opts.logger.warn("session_channel_version_mismatch", {
+                renderId: payload.renderId,
                 appId: payload.appId,
                 serverVersion: PROTOCOL_SCHEMA_VERSION,
                 clientSupportedVersions: payload.supportedVersions,
                 policy,
             });
-            if (policy === 'reject') {
+            if (policy === "reject") {
                 try {
                     ws.close();
                 }
@@ -1132,22 +1164,22 @@ export function createSessionChannelServer(opts) {
             }
             return;
         }
-        // Bootstrap-auth path. When `payload.bootstrap` is present, the
-        // MCP Apps iframe is asking us to authenticate it via the
-        // short-lived token minted by `ggui_push`. This REPLACES the
-        // upgrade-time AuthAdapter identity — iframes don't carry bearer
-        // tokens. Mutually-exclusive on purpose.
+        // WS-token-auth path. When `payload.wsToken` is present, the MCP
+        // Apps iframe is asking us to authenticate it via the short-lived
+        // token minted by `ggui_render`. This REPLACES the upgrade-time
+        // AuthAdapter identity — iframes don't carry bearer tokens.
+        // Mutually-exclusive on purpose.
         let effectiveIdentity = identity;
         let mintedSessionToken;
-        if (typeof payload.bootstrap === 'string' && payload.bootstrap.length > 0) {
+        if (typeof payload.wsToken === "string" && payload.wsToken.length > 0) {
             if (!opts.bootstrap) {
-                sendError(ws, 'BOOTSTRAP_NOT_SUPPORTED', 'This server was not configured with bootstrap-auth plumbing', message.requestId);
+                sendError(ws, "BOOTSTRAP_NOT_SUPPORTED", "This server was not configured with ws-token-auth plumbing", message.requestId);
                 return;
             }
-            const verifyResult = opts.bootstrap.verify(payload.bootstrap);
+            const verifyResult = opts.bootstrap.verify(payload.wsToken);
             if (!verifyResult.ok) {
-                opts.logger.warn('session_channel_bootstrap_rejected', {
-                    sessionId: payload.sessionId,
+                opts.logger.warn("session_channel_bootstrap_rejected", {
+                    renderId: payload.renderId,
                     appId: payload.appId,
                     reason: verifyResult.reason,
                 });
@@ -1157,21 +1189,21 @@ export function createSessionChannelServer(opts) {
                 // (no refresh path); expired-but-signed envelopes emit the
                 // dedicated BOOTSTRAP_EXPIRED so the client knows to call
                 // `ggui_runtime_refresh_bootstrap`.
-                if (verifyResult.reason === 'expired') {
-                    sendError(ws, 'BOOTSTRAP_EXPIRED', 'Bootstrap token expired — call ggui_runtime_refresh_bootstrap or re-handshake', message.requestId);
+                if (verifyResult.reason === "expired") {
+                    sendError(ws, "BOOTSTRAP_EXPIRED", "Bootstrap token expired — call ggui_runtime_refresh_bootstrap or re-handshake", message.requestId);
                 }
                 else {
-                    sendError(ws, 'BOOTSTRAP_INVALID', 'Bootstrap token invalid (bad signature, malformed, or wrong kind)', message.requestId);
+                    sendError(ws, "BOOTSTRAP_INVALID", "Bootstrap token invalid (bad signature, malformed, or wrong kind)", message.requestId);
                 }
                 return;
             }
-            const bound = { sessionId: verifyResult.sessionId, appId: verifyResult.appId };
-            if (bound.sessionId !== payload.sessionId) {
-                sendError(ws, 'BOOTSTRAP_SESSION_MISMATCH', `Bootstrap token is bound to session '${bound.sessionId}' but subscribe targets '${payload.sessionId}'`, message.requestId);
+            const bound = { renderId: verifyResult.renderId, appId: verifyResult.appId };
+            if (bound.renderId !== payload.renderId) {
+                sendError(ws, "BOOTSTRAP_SESSION_MISMATCH", `Bootstrap token is bound to session '${bound.renderId}' but subscribe targets '${payload.renderId}'`, message.requestId);
                 return;
             }
             if (bound.appId !== payload.appId) {
-                sendError(ws, 'BOOTSTRAP_APP_MISMATCH', `Bootstrap token is bound to app '${bound.appId}' but subscribe targets '${payload.appId}'`, message.requestId);
+                sendError(ws, "BOOTSTRAP_APP_MISMATCH", `Bootstrap token is bound to app '${bound.appId}' but subscribe targets '${payload.appId}'`, message.requestId);
                 return;
             }
             // Synthesize a minimal AuthResult from the bootstrap claims.
@@ -1180,75 +1212,47 @@ export function createSessionChannelServer(opts) {
             // citizen for the lifetime of this subscription.
             effectiveIdentity = {
                 identity: {
-                    kind: 'user',
-                    userId: bound.sessionId,
+                    kind: "user",
+                    userId: bound.renderId,
                     workspaceId: bound.appId,
                     roles: [],
                 },
-                source: 'apikey',
+                source: "apikey",
             };
             // Mint the reconnect credential now — before create/observe
             // work — so a downstream failure doesn't leave the client with
             // no way to resume.
-            mintedSessionToken = opts.bootstrap.issueSessionToken(bound.sessionId, bound.appId);
-            opts.logger.info('session_channel_bootstrap_accepted', {
-                sessionId: bound.sessionId,
+            mintedSessionToken = opts.bootstrap.issueSessionToken(bound.renderId, bound.appId);
+            opts.logger.info("session_channel_bootstrap_accepted", {
+                renderId: bound.renderId,
                 appId: bound.appId,
             });
         }
         // Dev-mode session provisioning: look up first; if not present,
         // create with the client-provided id via the widened
         // CreateSessionInput.id seam. Matches the hosted model's shape
-        // (agent creates via ggui_push → client subscribes) in a single
+        // (agent creates via ggui_render → client subscribes) in a single
         // step — production deployments tighten this by supplying an
-        // AuthAdapter that mints session-scoped tokens on push.
-        let session = await opts.sessionStore.get(payload.sessionId);
+        // AuthAdapter that mints session-scoped tokens on render.
+        let session = await opts.renderStore.get(payload.renderId);
         if (session) {
             if (session.appId !== payload.appId) {
-                sendError(ws, 'APP_MISMATCH', `Session ${payload.sessionId} belongs to a different app`, message.requestId);
+                sendError(ws, "APP_MISMATCH", `Session ${payload.renderId} belongs to a different app`, message.requestId);
                 return;
             }
         }
         else {
             try {
-                session = await opts.sessionStore.create({
-                    id: payload.sessionId,
+                session = await opts.renderStore.create({
+                    id: payload.renderId,
                     appId: payload.appId,
                 });
             }
             catch (err) {
-                sendError(ws, 'SESSION_CREATE_FAILED', err instanceof Error ? err.message : String(err), message.requestId);
+                sendError(ws, "SESSION_CREATE_FAILED", err instanceof Error ? err.message : String(err), message.requestId);
                 return;
             }
         }
-        // Canvas mode: flip `canvasLoaded`
-        // on the first session-wide subscribe so push.ts's resultMeta
-        // detects `canvasOwnsRender === true` for the next push. Until
-        // we flip this, push.ts falls back to the inline path (per-push
-        // resourceUri), which would defeat the canvas model.
-        //
-        // Idempotent — only writes when the flag isn't already true. The
-        // subscribe-ack semantics make this the canonical "canvas iframe
-        // is alive + subscribed" signal; a host that reconnects re-fires
-        // this no-op write.
-        if (session.mcpAppsMode === 'canvas' &&
-            session.canvasLoaded !== true) {
-            try {
-                session = await opts.sessionStore.update(session.id, {
-                    canvasLoaded: true,
-                });
-            }
-            catch (err) {
-                opts.logger.warn('session_channel_canvas_loaded_flip_failed', {
-                    sessionId: session.id,
-                    appId: session.appId,
-                    error: err instanceof Error ? err.message : String(err),
-                });
-                // Degraded mode — canvasLoaded stays false; push.ts continues
-                // the inline path until a future subscribe succeeds. NOT a
-                // fatal error — the subscribe itself is unaffected.
-            }
-        }
         // Snapshot the outbound-stream cursor BEFORE registering the
         // subscriber. Any concurrent producer that calls sendToSession
         // between here and registration gets seq > snapshotSeq, so the
@@ -1257,45 +1261,39 @@ export function createSessionChannelServer(opts) {
         // This is race-safe in single-threaded JS: the next few lines run
         // synchronously up to `register(sub)`, and fan-out's per-subscriber
         // `seq <= replayCompletedSeq` guard takes care of the window.
-        const snapshotSeq = await streamBuffer.currentSeq(session.id);
-        // Resolve active stack item's streamSpec for per-channel replay
-        // policy. If the stack is empty or the index is out of range, no
-        // spec is known — replay contributes nothing.
-        const activeIndex = session.currentStackIndex;
-        const activeItem = activeIndex >= 0 && activeIndex < session.stack.length
-            ? session.stack[activeIndex]
-            : undefined;
+        // Local alias for the resolved row (handleSubscribe's `session`
+        // local IS a `StoredRender` post-collapse; rename kept narrow to
+        // avoid a wholesale identifier sweep in this slice).
+        const stored = session;
+        const snapshotSeq = await streamBuffer.currentSeq(stored.id);
+        // Phase B: a render IS the addressable unit, so the active item
+        // is the resolved render's visible-bits surface itself.
+        const activeItem = stored.render;
         // Reconnect: `fromSeq` present → replay per policy on declared
         // AND reserved channels. Fresh subscribe: `fromSeq` absent →
         // call with `fromSeq=0` + NO spec, so the buffer's spec-channel
         // walk contributes nothing (preserving the "initial state comes
-        // from ack.stack[].props; stream channels are for updates
-        // after" doctrine for agent-declared channels) but the
-        // reserved-channel walk still surfaces server-pushed state that
-        // landed before the subscriber attached. The provisional
-        // preview channel (`_ggui:preview`) is the load-bearing case:
-        // an agent's `ggui_push` kicks off preview emission BEFORE the
-        // user's browser navigates to the viewer, so without this the
-        // late subscriber sees no preview at all.
-        const activeStreamSpec = activeItem !== undefined &&
-            activeItem.type !== 'mcpApps' &&
-            activeItem.type !== 'system'
+        // from ack.render.props; stream channels are for updates after"
+        // doctrine for agent-declared channels) but the reserved-channel
+        // walk still surfaces server-pushed state that landed before the
+        // subscriber attached.
+        const activeStreamSpec = activeItem.type !== "mcpApps" && activeItem.type !== "system"
             ? activeItem.streamSpec
             : undefined;
         const replay = payload.fromSeq !== undefined
-            ? await streamBuffer.replay(session.id, payload.fromSeq, activeStreamSpec)
-            : await streamBuffer.replay(session.id, 0, undefined);
+            ? await streamBuffer.replay(stored.id, payload.fromSeq, activeStreamSpec)
+            : await streamBuffer.replay(stored.id, 0, undefined);
         // Subscribe to the StreamFanout BEFORE constructing the Subscriber:
         // the seam returns an AsyncIterable whose iterator we hand off; the
         // pump loop in `register` consumes it. Eager registration on the
         // seam side means any concurrent `streamFanout.publish` from this
         // point onward queues into our iterator — paired with the
         // replayCompletedSeq cursor below, that's race-free.
-        const fanoutIter = streamFanout.subscribe(session.id)[Symbol.asyncIterator]();
+        const fanoutIter = streamFanout.subscribe(stored.id)[Symbol.asyncIterator]();
         const sub = {
             ws,
-            sessionId: session.id,
-            appId: session.appId,
+            renderId: stored.id,
+            appId: stored.appId,
             identity: effectiveIdentity,
             connectedAt: Date.now(),
             replayCompletedSeq: snapshotSeq,
@@ -1306,9 +1304,9 @@ export function createSessionChannelServer(opts) {
             channelSubs: new Map(),
         };
         register(sub);
-        opts.logger.info('session_channel_subscribed', {
-            sessionId: session.id,
-            appId: session.appId,
+        opts.logger.info("render_channel_subscribed", {
+            renderId: stored.id,
+            appId: stored.appId,
             identityKind: effectiveIdentity.identity.kind,
             fromSeq: payload.fromSeq,
             snapshotSeq,
@@ -1317,9 +1315,9 @@ export function createSessionChannelServer(opts) {
             bootstrap: mintedSessionToken !== undefined,
         });
         const ackPayload = {
-            sequence: session.eventSequence,
+            sequence: stored.eventSequence,
             timestamp: Date.now(),
-            stack: session.stack,
+            render: stored.render,
             streamSeq: snapshotSeq,
             // Advertise the server's protocol version on every successful
             // subscribe ack (SPEC §11.2.2). Clients whose
@@ -1328,15 +1326,56 @@ export function createSessionChannelServer(opts) {
             // the handshake ignore the field (legacy-pass-through).
             serverVersion: PROTOCOL_SCHEMA_VERSION,
             ...(replay?.truncated ? { replayTruncated: true } : {}),
-            ...(mintedSessionToken !== undefined
-                ? { sessionToken: mintedSessionToken }
-                : {}),
+            ...(mintedSessionToken !== undefined ? { renderToken: mintedSessionToken } : {}),
         };
         send(ws, {
-            type: 'ack',
+            type: "ack",
             payload: ackPayload,
             ...(message.requestId ? { requestId: message.requestId } : {}),
         });
+        // R7 — RenderEvent ledger replay. When `payload.sinceSequence` is
+        // present, fetch events with `seq > sinceSequence` from the per-
+        // render ledger and emit each as a `render_event` wire frame
+        // BEFORE the per-channel stream-buffer replay. Consumers dispatch
+        // by `event.type` to fold the wire-frame-equivalent handler
+        // (push/props_update/etc.) — same cursor model as the HTTP
+        // `/api/renders/:id/events?sinceSequence=N` endpoint.
+        //
+        // Horizon gate: a cursor below the server's replay horizon OR
+        // above `lastSequence` (stale from a different deployment) emits
+        // an error frame with `code: 'REPLAY_HORIZON_PASSED'` and skips
+        // the replay. Client recovery: re-mount from a fresh /state read.
+        if (payload.sinceSequence !== undefined) {
+            const sinceSeq = payload.sinceSequence;
+            if (sinceSeq < 0 || !Number.isInteger(sinceSeq)) {
+                sendError(ws, "INVALID_SINCE_SEQUENCE", "sinceSequence must be a non-negative integer", message.requestId);
+            }
+            else {
+                const ledger = await opts.renderStore.listEventsSince(session.id, sinceSeq, 
+                // Server-side cap matches the HTTP route's default (100).
+                // Stress + replay-from-zero workloads cap here.
+                100);
+                if (ledger === null) {
+                    // Session disappeared between resolve and ledger read —
+                    // already handled by the broader error envelope path; nothing
+                    // to do here.
+                }
+                else if (sinceSeq > ledger.lastSequence || sinceSeq < ledger.horizonSeq) {
+                    sendError(ws, "REPLAY_HORIZON_PASSED", `cursor ${sinceSeq} is outside replayable range [${ledger.horizonSeq}, ${ledger.lastSequence}]`, message.requestId, { currentSequence: ledger.lastSequence });
+                }
+                else {
+                    for (const event of ledger.events) {
+                        // RenderEvent is now the wire-shape ledger primitive
+                        // (Wave 7 of flatten-render-identity, 2026-05-28); no
+                        // projection — emit the store's row directly.
+                        send(ws, {
+                            type: "render_event",
+                            payload: event,
+                        });
+                    }
+                }
+            }
+        }
         // Send replay frames AFTER the ack. Ordering by `seq` ASC — the
         // buffer returns them pre-sorted. Client sees ack(streamSeq=N) →
         // up to N replay `data` frames → live tail (seq > N). No explicit
@@ -1344,7 +1383,7 @@ export function createSessionChannelServer(opts) {
         // the single source of truth for ordering.
         if (replay) {
             for (const env of replay.envelopes) {
-                send(ws, { type: 'data', payload: env });
+                send(ws, { type: "data", payload: env });
             }
         }
     }
@@ -1355,21 +1394,21 @@ export function createSessionChannelServer(opts) {
             message = JSON.parse(raw);
         }
         catch {
-            sendError(ws, 'INVALID_JSON', 'Message is not valid JSON');
+            sendError(ws, "INVALID_JSON", "Message is not valid JSON");
             return;
         }
-        if (!message || typeof message !== 'object' || typeof message.type !== 'string') {
-            sendError(ws, 'INVALID_MESSAGE', 'Message is missing a `type` discriminator');
+        if (!message || typeof message !== "object" || typeof message.type !== "string") {
+            sendError(ws, "INVALID_MESSAGE", "Message is missing a `type` discriminator");
             return;
         }
         switch (message.type) {
-            case 'subscribe': {
+            case "subscribe": {
                 // `subscribe` is the only message allowed before identity is
                 // bound to a session. Identity was already resolved at upgrade
                 // time; we just need to register the subscriber.
                 const identity = pendingIdentity.get(ws);
                 if (!identity) {
-                    sendError(ws, 'UNAUTHENTICATED', 'No identity bound to this socket', message.requestId);
+                    sendError(ws, "UNAUTHENTICATED", "No identity bound to this socket", message.requestId);
                     return;
                 }
                 // Cookie-scope enforcement: when the upgrade was authenticated
@@ -1378,12 +1417,12 @@ export function createSessionChannelServer(opts) {
                 // session A can't be used to open session B.
                 const cookieBound = pendingCookieBinding.get(ws);
                 if (cookieBound) {
-                    if (message.payload.sessionId !== cookieBound.sessionId) {
-                        sendError(ws, 'DEVTOOL_COOKIE_SESSION_MISMATCH', `Embedded-ui cookie is bound to session '${cookieBound.sessionId}' but subscribe targets '${message.payload.sessionId}'`, message.requestId);
+                    if (message.payload.renderId !== cookieBound.renderId) {
+                        sendError(ws, "DEVTOOL_COOKIE_SESSION_MISMATCH", `Embedded-ui cookie is bound to session '${cookieBound.renderId}' but subscribe targets '${message.payload.renderId}'`, message.requestId);
                         return;
                     }
                     if (message.payload.appId !== cookieBound.appId) {
-                        sendError(ws, 'DEVTOOL_COOKIE_APP_MISMATCH', `Embedded-ui cookie is bound to app '${cookieBound.appId}' but subscribe targets '${message.payload.appId}'`, message.requestId);
+                        sendError(ws, "DEVTOOL_COOKIE_APP_MISMATCH", `Embedded-ui cookie is bound to app '${cookieBound.appId}' but subscribe targets '${message.payload.appId}'`, message.requestId);
                         return;
                     }
                 }
@@ -1392,34 +1431,34 @@ export function createSessionChannelServer(opts) {
                 pendingCookieBinding.delete(ws);
                 return;
             }
-            case 'ping':
+            case "ping":
                 send(ws, {
-                    type: 'pong',
+                    type: "pong",
                     payload: {},
                     ...(message.requestId ? { requestId: message.requestId } : {}),
                 });
                 return;
-            case 'close':
+            case "close":
                 // Explicit close from client — unregister + close the socket.
                 if (sub)
                     unregister(ws);
-                ws.close(1000, 'client_close');
+                ws.close(1000, "client_close");
                 return;
-            case 'action':
+            case "action":
                 if (!sub) {
-                    sendError(ws, 'NOT_SUBSCRIBED', "Send a 'subscribe' message first before 'action'", message.requestId);
+                    sendError(ws, "NOT_SUBSCRIBED", "Send a 'subscribe' message first before 'action'", message.requestId);
                     return;
                 }
                 await handleInboundAction(ws, sub, message);
                 return;
-            case 'channel_subscribe':
+            case "channel_subscribe":
                 if (!sub) {
-                    sendError(ws, 'NOT_SUBSCRIBED', "Send a 'subscribe' message first before 'channel_subscribe'", message.requestId);
+                    sendError(ws, "NOT_SUBSCRIBED", "Send a 'subscribe' message first before 'channel_subscribe'", message.requestId);
                     return;
                 }
                 await handleChannelSubscribe(ws, sub, message);
                 return;
-            case 'channel_unsubscribe':
+            case "channel_unsubscribe":
                 if (!sub) {
                     // No subscriber → nothing was subscribed → no-op silently.
                     // Returning an error would leak "is this socket subscribed"
@@ -1428,7 +1467,7 @@ export function createSessionChannelServer(opts) {
                 }
                 handleChannelUnsubscribe(ws, sub, message);
                 return;
-            case 'host_context_observed':
+            case "host_context_observed":
                 // The iframe-runtime echoes its captured `McpUiHostContext`
                 // after `ui/initialize` resolves and on every
                 // `ui/notifications/host-context-changed` notification. Persist
@@ -1438,44 +1477,25 @@ export function createSessionChannelServer(opts) {
                 if (!checkSubscriberTenancy(ws, sub, message.payload, message.type, message.requestId)) {
                     return;
                 }
-                await applySessionPatch(sub.sessionId, sub.appId, message.type, { hostContext: message.payload.hostContext, lastActivityAt: Date.now() });
-                return;
-            case 'canvas_navigated':
-                // The iframe-runtime's CanvasShell fires this when the user
-                // back-navigates in the canvas (popping a stack item from the
-                // local NavStackModel). The server updates
-                // `session.activeStackItemId` to the new top so
-                // `ggui_consume`'s active-pipe resolution stays in sync with
-                // what the user is looking at. AbortSignal wiring for in-
-                // flight cold-gen on the popped item is a follow-up — the
-                // server-side gen orchestrator (push.ts handler) doesn't yet
-                // expose a per-stack-item AbortController registry to this
-                // routing layer.
-                if (!checkSubscriberTenancy(ws, sub, message.payload, message.type, message.requestId)) {
-                    return;
-                }
-                await applySessionPatch(sub.sessionId, sub.appId, message.type, {
-                    activeStackItemId: message.payload.activeItemId,
+                await applySessionPatch(sub.renderId, sub.appId, message.type, {
+                    hostContext: message.payload.hostContext,
                     lastActivityAt: Date.now(),
                 });
                 return;
-            case 'pop':
-            case 'get_stack':
-            case 'generate':
-            case 'feedback':
+            case "feedback":
                 // Require an active subscription for operational messages.
                 if (!sub) {
-                    sendError(ws, 'NOT_SUBSCRIBED', `Send a 'subscribe' message first before '${message.type}'`, message.requestId);
+                    sendError(ws, "NOT_SUBSCRIBED", `Send a 'subscribe' message first before '${message.type}'`, message.requestId);
                     return;
                 }
                 // These OSS channel handlers land incrementally once the
                 // matching shared handlers exist in @ggui-ai/mcp-server-handlers.
                 // For now the ingress point is documented but rejected with a
                 // clear code so clients don't assume silent success.
-                sendError(ws, 'NOT_IMPLEMENTED', `'${message.type}' not yet handled on the OSS channel server`, message.requestId);
+                sendError(ws, "NOT_IMPLEMENTED", `'${message.type}' not yet handled on the OSS channel server`, message.requestId);
                 return;
             default:
-                sendError(ws, 'UNSUPPORTED_MESSAGE', `Unsupported message type: ${String(message.type)}`, message.requestId);
+                sendError(ws, "UNSUPPORTED_MESSAGE", `Unsupported message type: ${String(message.type)}`, message.requestId);
         }
     }
     /**
@@ -1487,13 +1507,13 @@ export function createSessionChannelServer(opts) {
     const pendingIdentity = new WeakMap();
     /**
      * Embedded-ui cookie binding established at upgrade. When present,
-     * `handleSubscribe` enforces `subscribe.sessionId === bound.sessionId`
+     * `handleSubscribe` enforces `subscribe.renderId === bound.renderId`
      * so a valid cookie can't be used to open a session it wasn't
      * issued for. Parallel to {@link pendingIdentity} — same lifetime,
      * same WeakMap rationale.
      */
     const pendingCookieBinding = new WeakMap();
-    wss.on('connection', (ws, req) => {
+    wss.on("connection", (ws, req) => {
         // Bind the resolved identity from the upgrade phase. It was
         // attached to the request object in handleUpgrade.
         const identity = req.__gguiIdentity;
@@ -1503,22 +1523,22 @@ export function createSessionChannelServer(opts) {
         const cookieBound = req.__gguiCookieBound;
         if (cookieBound)
             pendingCookieBinding.set(ws, cookieBound);
-        ws.on('message', (raw) => {
+        ws.on("message", (raw) => {
             // `ws.on('message')` delivers Buffer/ArrayBuffer/Buffer[] depending
             // on frame type; normalize to string.
-            const text = typeof raw === 'string' ? raw : raw.toString('utf8');
+            const text = typeof raw === "string" ? raw : raw.toString("utf8");
             onMessage(ws, text).catch((err) => {
-                opts.logger.error('session_channel_message_failed', {
+                opts.logger.error("session_channel_message_failed", {
                     error: String(err),
                 });
             });
         });
-        ws.on('close', () => {
+        ws.on("close", () => {
             unregister(ws);
             pendingIdentity.delete(ws);
         });
-        ws.on('error', (err) => {
-            opts.logger.warn('session_channel_socket_error', { error: String(err) });
+        ws.on("error", (err) => {
+            opts.logger.warn("session_channel_socket_error", { error: String(err) });
         });
     });
     return {
@@ -1532,27 +1552,26 @@ export function createSessionChannelServer(opts) {
                 req.__gguiIdentity = identity;
                 wss.handleUpgrade(req, socket, head, (ws) => {
                     // Expose `upgradeReq` for the connection handler.
-                    wss.emit('connection', ws, req);
+                    wss.emit("connection", ws, req);
                 });
             })
                 .catch((err) => {
                 if (err instanceof UnauthenticatedError) {
-                    opts.logger.warn('session_channel_auth_failed', {
+                    opts.logger.warn("session_channel_auth_failed", {
                         reason: err.message,
                     });
-                    socket.write('HTTP/1.1 401 Unauthorized\r\n' +
-                        'Connection: close\r\n' +
-                        'Content-Type: text/plain\r\n\r\n' +
-                        'Unauthorized: ' +
+                    socket.write("HTTP/1.1 401 Unauthorized\r\n" +
+                        "Connection: close\r\n" +
+                        "Content-Type: text/plain\r\n\r\n" +
+                        "Unauthorized: " +
                         err.message +
-                        '\r\n');
+                        "\r\n");
                 }
                 else {
-                    opts.logger.error('session_channel_upgrade_failed', {
+                    opts.logger.error("session_channel_upgrade_failed", {
                         error: String(err),
                     });
-                    socket.write('HTTP/1.1 500 Internal Server Error\r\n' +
-                        'Connection: close\r\n\r\n');
+                    socket.write("HTTP/1.1 500 Internal Server Error\r\n" + "Connection: close\r\n\r\n");
                 }
                 socket.destroy();
             });
@@ -1560,60 +1579,48 @@ export function createSessionChannelServer(opts) {
         async sendToSession(delivery) {
             // Outbound fan-out enforcement (defense-in-depth parity with
             // hosted `handle-data.ts`). Re-validates the delivery's payload
-            // against the active stack item's streamSpec BEFORE delivery —
-            // so a future OSS mutation handler that bypasses the emit-side
-            // check can't fan out malformed data to subscribers. Throws
+            // against the render's streamSpec BEFORE delivery — so a future
+            // OSS mutation handler that bypasses the emit-side check can't
+            // fan out malformed data to subscribers. Throws
             // ContractViolationError{tool:'ggui_emit'} on violation;
             // caller decides what to do (log, rethrow, wrap).
-            const session = await opts.sessionStore.get(delivery.sessionId);
-            const activeIndex = session?.currentStackIndex ?? -1;
-            const activeEntry = session && activeIndex >= 0 && activeIndex < session.stack.length
-                ? session.stack[activeIndex]
-                : undefined;
-            const streamSpec = activeEntry !== undefined &&
-                activeEntry.type !== 'mcpApps' &&
-                activeEntry.type !== 'system'
+            const stored = await opts.renderStore.get(delivery.renderId);
+            const activeEntry = stored?.render;
+            const streamSpec = activeEntry !== undefined && activeEntry.type !== "mcpApps" && activeEntry.type !== "system"
                 ? activeEntry.streamSpec
                 : undefined;
             assertStreamContract(streamSpec, delivery.channel, delivery.payload, opts.extraReservedValidators);
             return fanOut(delivery, streamSpec);
         },
-        notifyStackPush(sessionId, stackItem, matchType) {
+        notifyRenderPush(renderId, render, matchType) {
             // Best-effort fan-out to every live subscriber bound to this
-            // session. NOT routed through the replay buffer — see the
-            // `notifyStackPush` JSDoc on the interface for why fresh
-            // subscribers rely on `ack.stack` instead of a replay frame.
-            // NOT routed through StreamFanout either — `type: 'push'` is a
-            // distinct WebSocket message type, not a stream envelope, so it
-            // sits outside the seam's contract. Filter the flat WS-subscriber
-            // set by sessionId; N is typically 1-2 (multi-tab session sharing).
-            const payload = matchType !== undefined ? { stackItem, matchType } : { stackItem };
+            // render. NOT routed through the replay buffer — see the
+            // `notifyRenderPush` JSDoc on the interface for why fresh
+            // subscribers rely on `ack.render` instead of a replay frame.
+            // NOT routed through StreamFanout either — `type: 'render'` is a
+            // distinct WebSocket message type. Filter the flat WS-subscriber
+            // set by renderId; N is typically 1-2 (multi-tab render sharing).
+            const payload = matchType !== undefined ? { render, matchType } : { render };
             for (const sub of wsSubscribers) {
-                if (sub.sessionId !== sessionId)
+                if (sub.renderId !== renderId)
                     continue;
-                // `send()` already silently skips closed sockets and logs
-                // (but doesn't throw on) per-subscriber send failures, so the
-                // caller's `appendStackItem` path can't be made to fail by a
-                // dead WebSocket.
-                send(sub.ws, { type: 'push', payload });
+                send(sub.ws, { type: "render", payload });
             }
         },
-        async primeStreams(sessionId, stackItem) {
+        async primeStreams(renderId, render) {
             const router = opts.wiredActionRouter;
-            const streamSpec = 'streamSpec' in stackItem ? stackItem.streamSpec : undefined;
+            const streamSpec = "streamSpec" in render ? render.streamSpec : undefined;
             if (!router || !streamSpec)
                 return;
             const timeoutMs = opts.wiredActionTimeoutMs ?? DEFAULT_WIRED_TOOL_TIMEOUT_MS;
             // Build the same wired-action ctx the dispatcher uses.
-            // Prime-time invocations reuse the seam so a refresh
-            // tool that fires `sendPropsUpdate` on cold-start works the same
-            // way as one fired post-action. `stackItemId` is the primed stack
-            // item's id; closures lock to the caller-supplied sessionId.
+            // Prime-time invocations reuse the seam so a refresh tool that
+            // fires `sendPropsUpdate` on cold-start works the same way as
+            // one fired post-action.
             const wiredCtx = {
-                sessionId,
-                stackItemId: stackItem.id,
-                sendPropsUpdate(targetStackItemId, props) {
-                    void sendPropsUpdateImpl(sessionId, targetStackItemId, props);
+                renderId,
+                sendPropsUpdate(props) {
+                    void sendPropsUpdateImpl(renderId, props);
                 },
             };
             for (const [channelName, channelEntry] of Object.entries(streamSpec)) {
@@ -1621,8 +1628,8 @@ export function createSessionChannelServer(opts) {
                 if (!refreshTool)
                     continue;
                 if (!router.has(refreshTool)) {
-                    opts.logger.warn('session_channel_prime_tool_not_found', {
-                        sessionId,
+                    opts.logger.warn("render_channel_prime_tool_not_found", {
+                        renderId,
                         toolName: refreshTool,
                         channel: channelName,
                     });
@@ -1633,8 +1640,8 @@ export function createSessionChannelServer(opts) {
                     output = await invokeWithTimeout(router, refreshTool, EMPTY_REFRESH_INPUT, wiredCtx, timeoutMs);
                 }
                 catch (err) {
-                    opts.logger.warn('session_channel_prime_tool_failed', {
-                        sessionId,
+                    opts.logger.warn("render_channel_prime_tool_failed", {
+                        renderId,
                         toolName: refreshTool,
                         channel: channelName,
                         error: String(err),
@@ -1645,8 +1652,8 @@ export function createSessionChannelServer(opts) {
                     assertStreamContract(streamSpec, channelName, output, opts.extraReservedValidators);
                 }
                 catch (err) {
-                    opts.logger.warn('session_channel_prime_schema_violation', {
-                        sessionId,
+                    opts.logger.warn("render_channel_prime_schema_violation", {
+                        renderId,
                         toolName: refreshTool,
                         channel: channelName,
                         error: String(err),
@@ -1655,15 +1662,15 @@ export function createSessionChannelServer(opts) {
                 }
                 try {
                     await fanOut({
-                        sessionId,
+                        renderId,
                         channel: channelName,
-                        mode: channelEntry?.mode ?? 'append',
+                        mode: channelEntry?.mode ?? "append",
                         payload: output,
                     }, streamSpec);
                 }
                 catch (err) {
-                    opts.logger.error('session_channel_prime_emit_failed', {
-                        sessionId,
+                    opts.logger.error("render_channel_prime_emit_failed", {
+                        renderId,
                         toolName: refreshTool,
                         channel: channelName,
                         error: String(err),
@@ -1671,41 +1678,53 @@ export function createSessionChannelServer(opts) {
                 }
             }
         },
-        sendPropsUpdate(sessionId, stackItemId, props) {
+        sendPropsUpdate(renderId, props) {
             // Public entry point — delegates to the closure-level impl that
             // the wired-action dispatcher's `WiredActionContext.sendPropsUpdate`
             // also calls. Returns the impl's promise so the caller can await
-            // session-store lookup completion if desired (the wiredCtx call
-            // site fire-and-forgets via `void`).
-            return sendPropsUpdateImpl(sessionId, stackItemId, props);
+            // store-lookup completion if desired (the wiredCtx call site
+            // fire-and-forgets via `void`).
+            return sendPropsUpdateImpl(renderId, props);
         },
-        sendDrainAck({ sessionId, appId, stackItemId, eventId, drainedAt }) {
+        sendDrainAck({ renderId, appId, eventId, drainedAt }) {
             // Server-side fan-out for the action-drain ack.
-            // Filter the flat WS-subscriber set by sessionId (same posture
+            // Filter the flat WS-subscriber set by renderId (same posture
             // as `sendPropsUpdate`). No persistence; subscribers that
             // missed the frame fall back to their 10s claim timer, which
-            // the atomic pop resolves cleanly. `send()` already silently
-            // skips closed sockets and absorbs per-subscriber send
-            // failures.
+            // the atomic pop resolves cleanly.
             for (const sub of wsSubscribers) {
-                if (sub.sessionId !== sessionId)
+                if (sub.renderId !== renderId)
                     continue;
                 send(sub.ws, {
-                    type: 'drain_ack',
-                    payload: { sessionId, appId, stackItemId, eventId, drainedAt },
+                    type: "drain_ack",
+                    payload: { renderId, appId, eventId, drainedAt },
                 });
             }
         },
+        externalBroadcast(renderId, frame) {
+            // Walk the flat subscriber set; filter to matching renderId.
+            // `send()` already guards closed sockets and logs (but doesn't
+            // throw on) per-subscriber failures, so the caller (a cloud
+            // pubsub on-message handler) can't be made to fail by a dead
+            // WebSocket. No RenderStore lookup — the publisher already
+            // validated; this seam is the cross-pod delivery path, not the
+            // re-validation point.
+            for (const sub of wsSubscribers) {
+                if (sub.renderId !== renderId)
+                    continue;
+                send(sub.ws, frame);
+            }
+        },
         get subscriberCount() {
             return wsSubscribers.size;
         },
         get sessionCount() {
             // Distinct session count across live WS subscribers. With
-            // multi-tab sessions, two subscribers may share a sessionId —
+            // multi-tab sessions, two subscribers may share a renderId —
             // dedupe before counting.
             const sessions = new Set();
             for (const sub of wsSubscribers)
-                sessions.add(sub.sessionId);
+                sessions.add(sub.renderId);
             return sessions.size;
         },
         async close() {
@@ -1726,9 +1745,9 @@ export function createSessionChannelServer(opts) {
             // case and the wrong signal for client reconnect logic.
             const sessions = new Set();
             for (const sub of wsSubscribers) {
-                sessions.add(sub.sessionId);
+                sessions.add(sub.renderId);
                 try {
-                    sub.ws.close(1012, 'service_restart');
+                    sub.ws.close(1012, "service_restart");
                 }
                 catch {
                     /* best-effort */
@@ -1741,7 +1760,7 @@ export function createSessionChannelServer(opts) {
             // unregister race). For InProcessStreamFanout this is a no-op
             // when there are no subscribers; for hosted bindings it ensures
             // the per-session pub/sub channel teardown fires.
-            await Promise.all(Array.from(sessions, (sessionId) => streamFanout.close(sessionId).catch(() => {
+            await Promise.all(Array.from(sessions, (renderId) => streamFanout.close(renderId).catch(() => {
                 /* best-effort */
             })));
             await new Promise((resolve) => {