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

package/dist/{session-channel.d.ts → render-channel.d.ts}

@@ -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,26 +32,27 @@
  * 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 type { IncomingMessage } from 'node:http';
-import type { Duplex } from 'node:stream';
-import type { JsonObject, ReservedChannelValidator, SanitizeCausedBy, SessionStackEntry } from '@ggui-ai/protocol';
-import type { AuthAdapter, SessionStore, SessionStreamBuffer, StreamEnvelopeInput, StreamFanout, TelemetrySink } from '@ggui-ai/mcp-server-core';
-import type { Logger } from './logger.js';
+import type { AuthAdapter, RenderStore, SessionStreamBuffer, StreamEnvelopeInput, StreamFanout, TelemetrySink } from "@ggui-ai/mcp-server-core";
+import type { JsonObject, Render, ReservedChannelValidator, SanitizeCausedBy } from "@ggui-ai/protocol";
+import type { WebSocketMessage } from "@ggui-ai/protocol/transport/websocket";
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+import type { Logger } from "./logger.js";
 /** Default URL path for the channel endpoint. Operators can override. */
-export declare const DEFAULT_SESSION_CHANNEL_PATH = "/ws";
+export declare const DEFAULT_RENDER_CHANNEL_PATH = "/ws";
 /**
  * Opt-in plumbing for the `channel_subscribe` polling loop. When this
- * field is set on {@link SessionChannelOptions}, channel subscribes
+ * field is set on {@link RenderChannelOptions}, channel subscribes
  * whose `source.tool` is in {@link allowlist} are accepted and the
  * server begins polling. When absent, every `channel_subscribe`
  * returns `CHANNEL_NOT_LOCAL` so the iframe falls back to direct
  * polling via the MCP host proxy.
  */
-export interface SessionChannelLocalToolsOptions {
+export interface RenderChannelLocalToolsOptions {
     /**
      * Whitelist of `source.tool` names this channel can poll. Must mirror
      * the value the host advertises on
@@ -92,13 +93,13 @@ export interface SessionChannelLocalToolsOptions {
  * message (`SubscribePayload.bootstrap`). When present:
  *
  *   1. `verify(token)` is called. Must return the bound
- *      `{sessionId, appId}` on success, or `null` on any failure
+ *      `{renderId, appId}` on success, or `null` on any failure
  *      (invalid sig, expired, wrong kind, replayed, etc.).
- *   2. The bound `sessionId` MUST match the one on the subscribe
+ *   2. The bound `renderId` MUST match the one on the subscribe
  *      payload. Mismatches are rejected with a clean error.
  *   3. On success, the server mints a reconnect credential via
- *      `issueSessionToken(sessionId, appId)` and returns it in
- *      `AckPayload.sessionToken`. The iframe stores this for WS
+ *      `issueSessionToken(renderId, appId)` and returns it in
+ *      `AckPayload.renderToken`. The iframe stores this for WS
  *      reconnects via the normal bearer path.
  *
  * Bootstrap auth is MUTUALLY EXCLUSIVE with the upstream `AuthAdapter`
@@ -118,16 +119,16 @@ export interface SessionChannelLocalToolsOptions {
  * handshake. Past expiry, the iframe MAY refresh via the
  * {@link refresh} surface; past the refresh window, fresh handshake.
  */
-export type SessionChannelBootstrapVerifyResult = {
+export type RenderChannelBootstrapVerifyResult = {
     readonly ok: true;
-    readonly sessionId: string;
+    readonly renderId: string;
     readonly appId: string;
 } | {
     readonly ok: false;
-    readonly reason: 'expired' | 'invalid';
+    readonly reason: "expired" | "invalid";
 };
 /**
- * Result of {@link SessionChannelBootstrap.refresh}.
+ * Result of {@link RenderChannelBootstrap.refresh}.
  *
  *   - `ok: true`: caller swaps the old envelope for `token` and resumes.
  *   - `ok: false`: caller MUST re-handshake (refresh window closed,
@@ -139,9 +140,9 @@ export type SessionChannelBootstrapRefreshResult = {
     readonly expiresAt: string;
 } | {
     readonly ok: false;
-    readonly reason: 'window_closed' | 'invalid';
+    readonly reason: "window_closed" | "invalid";
 };
-export interface SessionChannelBootstrap {
+export interface RenderChannelBootstrap {
     /**
      * Verify a `SubscribePayload.bootstrap` token.
      *
@@ -151,23 +152,23 @@ export interface SessionChannelBootstrap {
      * `BOOTSTRAP_INVALID` for tamper / format / kind failures (no
      * refresh on those).
      */
-    verify(token: string): SessionChannelBootstrapVerifyResult;
+    verify(token: string): RenderChannelBootstrapVerifyResult;
     /**
      * Mint a longer-lived reconnect credential to return in
-     * `AckPayload.sessionToken`. Called only after a successful
+     * `AckPayload.renderToken`. Called only after a successful
      * `verify()` on a bootstrap subscribe.
      */
-    issueSessionToken(sessionId: string, appId: string): string;
+    issueSessionToken(renderId: string, appId: string): string;
     /**
      * Refresh a (possibly-expired-but-signature-valid) bootstrap envelope
      * into a new envelope with a fresh TTL. Used by the
      * `ggui_runtime_refresh_bootstrap` MCP tool — iframes that see their
      * bootstrap drift out of the TTL window swap in the refreshed
-     * envelope without going back through `ggui_push`.
+     * envelope without going back through `ggui_render`.
      *
      * Stateless: verifies HMAC against the same secret used at mint,
      * checks the refresh window against the ORIGINAL `iat`, and mints
-     * a fresh bootstrap envelope bound to the SAME `(sessionId, appId)`.
+     * a fresh bootstrap envelope bound to the SAME `(renderId, appId)`.
      * Past the refresh window the result is `{ok:false, reason:
      * 'window_closed'}`; tampered envelopes are `{ok:false, reason:
      * 'invalid'}`.
@@ -176,7 +177,7 @@ export interface SessionChannelBootstrap {
 }
 /**
  * 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).
  */
@@ -221,7 +222,7 @@ export declare const DEFAULT_WIRED_TOOL_TIMEOUT_MS = 30000;
  * shape every shared handler — ggui-native AND mounted — accepts. It
  * stays narrow on purpose (`appId`, `requestId`, optional `apiKeyHash`)
  * so the surface a host implements is stable. Wired-action runtime
- * fields (`sessionId`, `stackItemId`, `sendPropsUpdate`) are dispatcher-
+ * fields (`renderId`, `renderId`, `sendPropsUpdate`) are dispatcher-
  * specific — only mount tools invoked through the wired-action router
  * see them, only at dispatch time. Passing them as a third arg to
  * `invoke` keeps the canonical handler shape untouched and makes
@@ -230,32 +231,24 @@ export declare const DEFAULT_WIRED_TOOL_TIMEOUT_MS = 30000;
  * The composer in `mcp-mounts.ts::composeWiredActionRouterFromMounts`
  * synthesizes a runtime ctx for the mount handler that satisfies
  * `HandlerContext` AND structurally carries these wired fields, so a
- * mount fixture can read `ctx.sendPropsUpdate` / `ctx.stackItemId` from the
+ * mount fixture can read `ctx.sendPropsUpdate` / `ctx.renderId` from the
  * same `ctx` argument the canonical `HandlerContext` sig types — no
  * cast, no widening of the static type.
  */
 export interface WiredActionContext {
-    /** The session this dispatch is bound to. Sourced from the live
-     * subscriber + the action envelope's spoof-guarded `sessionId`. */
-    readonly sessionId: string;
-    /** The active stack item's stackItemId at dispatch time. Mounts that
-     * fire `sendPropsUpdate` typically pass this verbatim — only a
-     * mount that intentionally targets a sibling stack entry would
-     * pick a different value. */
-    readonly stackItemId: string;
-    /**
-     * Push a `{type:'props_update', payload:{stackItemId, props}}` frame to
-     * every live subscriber bound to this dispatcher's `sessionId`. The
-     * call closes over the `SessionChannelServer.sendPropsUpdate` method,
-     * scoped to the active session for safety — even if a buggy mount
-     * picks a `stackItemId` that doesn't exist on the session, the channel
-     * server's own validation no-ops the fan-out (same posture as
-     * `notifyStackPush` orphan handling).
+    /** The render this dispatch is bound to. Sourced from the live
+     * subscriber + the action envelope's spoof-guarded `renderId`. */
+    readonly renderId: string;
+    /**
+     * Push a `{type:'props_update', payload:{renderId, props}}` frame to
+     * every live subscriber bound to this dispatcher's `renderId`. The
+     * call closes over the `RenderChannelServer.sendPropsUpdate` method,
+     * scoped to the active render for safety.
      *
      * Best-effort: per-subscriber send failures are swallowed; a closed
      * socket is a no-op.
      */
-    sendPropsUpdate(stackItemId: string, props: JsonObject): void;
+    sendPropsUpdate(props: JsonObject): void;
 }
 export interface WiredActionRouter {
     /** Returns `true` when the named tool has a registered handler. Used
@@ -278,9 +271,9 @@ export interface WiredActionRouter {
      */
     invoke(toolName: string, input: Record<string, unknown>, ctx: WiredActionContext): Promise<unknown>;
 }
-export interface SessionChannelOptions {
-    /** Required — the session backing store (typically `InMemorySessionStore`). */
-    readonly sessionStore: SessionStore;
+export interface RenderChannelOptions {
+    /** Required — the render backing store (typically `InMemoryRenderStore`). */
+    readonly renderStore: RenderStore;
     /**
      * Required — the same `AuthAdapter` the `/mcp` endpoint uses. Any
      * failure during `subscribe` rejects the upgrade with HTTP 401.
@@ -319,16 +312,16 @@ export interface SessionChannelOptions {
     /**
      * Optional bootstrap-auth plumbing. When present, the channel
      * accepts `SubscribePayload.bootstrap` and issues reconnect
-     * credentials in `AckPayload.sessionToken`. When absent, bootstrap
+     * credentials in `AckPayload.renderToken`. When absent, bootstrap
      * tokens are rejected with `BOOTSTRAP_NOT_SUPPORTED`.
      */
-    readonly bootstrap?: SessionChannelBootstrap;
+    readonly bootstrap?: RenderChannelBootstrap;
     /**
      * Optional console cookie-auth plumbing. When present, the
      * channel upgrade looks for the configured cookie on the incoming
      * request. A valid cookie binds the identity as a `builder` and
-     * scopes the subscriber to the cookie's `sessionId` — any
-     * `subscribe.sessionId` mismatch is rejected with
+     * scopes the subscriber to the cookie's `renderId` — any
+     * `subscribe.renderId` mismatch is rejected with
      * `DEVTOOL_COOKIE_SESSION_MISMATCH`.
      *
      * Absent = cookie auth disabled on this channel. Cookies are never
@@ -339,7 +332,7 @@ export interface SessionChannelOptions {
      * bootstrap path (via `?bootstrap=` query) wins; cookie is only
      * consulted for standard upgrades.
      */
-    readonly cookieAuth?: SessionChannelCookieAuth;
+    readonly cookieAuth?: RenderChannelCookieAuth;
     /**
      * Opt-in wired-action dispatch router. When present, validated
      * `data:submit` envelopes whose declared `actionSpec[name]
@@ -373,7 +366,7 @@ export interface SessionChannelOptions {
      *
      * The contract-error envelope flows on `_ggui:contract-error` with
      * `replay: 'all'`, so anything that lands in `causedBy` persists in
-     * the session ring buffer and surfaces in SessionInspector. Accepting
+     * the session ring buffer and surfaces in RenderInspector. Accepting
      * raw `err.stack` verbatim is a credential-leak footgun; the default
      * sanitizer is load-bearing.
      */
@@ -422,7 +415,7 @@ export interface SessionChannelOptions {
      * `handshake.serverCapabilities.streamWebSocketLocalTools` so iframe
      * + server agree on which channels use the WS fan-out path.
      */
-    readonly streamWebSocketLocalTools?: SessionChannelLocalToolsOptions;
+    readonly streamWebSocketLocalTools?: RenderChannelLocalToolsOptions;
     /**
      * Protocol-version handshake policy. Governs server behavior when a
      * subscribe declares a `supportedVersions` list that does NOT
@@ -448,31 +441,63 @@ export interface SessionChannelOptions {
      * not a schema change — the wire fields and error code ship
      * identically in both modes.
      */
-    readonly versionPolicy?: 'advisory' | 'reject';
+    readonly versionPolicy?: "advisory" | "reject";
+    /**
+     * Optional hook fired synchronously when the local subscriber count
+     * for `renderId` transitions 0 → 1 (the first subscriber for that
+     * session connects to this server instance).
+     *
+     * Hosted deployments use this to lazily SUBSCRIBE to the per-session
+     * cross-pod broadcast channel (e.g. Redis pub/sub); OSS has no use
+     * for it (in-process broadcasts already route via
+     * {@link RenderChannelServer.sendPropsUpdate}). Bounding pubsub
+     * fan-in to only sessions a pod actually holds connections for is a
+     * correctness requirement, not an optimization — without it every
+     * pod receives every other pod's broadcast for every active session.
+     *
+     * Best-effort: a thrown callback is logged and swallowed.
+     * `register()` MUST NOT fail because of a hook error or the
+     * `wsSubscribers` set would drift out of sync with the real socket
+     * lifecycle.
+     *
+     * Concurrent register/unregister for the same renderId are serialized
+     * by the channel's single-threaded WS event loop; hook implementations
+     * do not need their own mutex for the 0↔1 transition.
+     */
+    readonly onFirstSubscriber?: (renderId: string) => void;
+    /**
+     * Optional hook fired synchronously when the local subscriber count
+     * for `renderId` transitions 1 → 0 (the last subscriber for that
+     * session disconnects).
+     *
+     * Symmetric with {@link onFirstSubscriber}; same best-effort posture
+     * and single-threaded serialization guarantee.
+     */
+    readonly onLastSubscriberGone?: (renderId: string) => void;
 }
 /**
  * Cookie-based authentication for the live-channel upgrade. Used
  * exclusively by the same-origin console viewer; see
  * `console-auth.ts` for the single consumer today.
  */
-export interface SessionChannelCookieAuth {
+export interface RenderChannelCookieAuth {
     /**
      * Read the raw cookie value for THIS server's console cookie
      * from the incoming request headers. Returns `null` when the
      * cookie is absent or malformed.
      */
-    readCookie(headers: import('node:http').IncomingHttpHeaders): string | null;
+    readCookie(headers: import("node:http").IncomingHttpHeaders): string | null;
     /**
      * Verify a cookie value and return the bound session/app. Returns
      * `null` on any failure (signature, expiry, wrong kind). Never
      * throws.
      */
     verify(cookieValue: string): {
-        sessionId: string;
+        renderId: string;
         appId: string;
     } | null;
 }
-export interface SessionChannelServer {
+export interface RenderChannelServer {
     /** The URL path the channel accepts upgrade requests on. */
     readonly path: string;
     /**
@@ -482,7 +507,7 @@ export interface SessionChannelServer {
      */
     handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void;
     /**
-     * Deliver a stream envelope to every subscriber of `delivery.sessionId`.
+     * Deliver a stream envelope to every subscriber of `delivery.renderId`.
      *
      * Outbound fan-out enforcement point — the delivery's `payload` is
      * validated against the active stack item's streamSpec via
@@ -513,44 +538,44 @@ export interface SessionChannelServer {
         seq: number;
     }>;
     /**
-     * Fan a `{type:'push', payload:{stackItem, matchType?}}` wire frame
-     * to every subscriber currently bound to `sessionId`. Use this to
-     * notify already-subscribed clients about a stack mutation that
-     * happened AFTER they subscribed — the initial `ack.stack` snapshot
+     * Fan a `{type:'render', payload:{render, matchType?}}` wire frame
+     * to every subscriber currently bound to `renderId`. Use this to
+     * notify already-subscribed clients about a render-commit that
+     * happened AFTER they subscribed — the initial `ack.render` snapshot
      * covers state at subscribe time only, so without an explicit notify
-     * a second-turn `appendStackItem` is invisible to the live client.
+     * a second-turn `commit` is invisible to the live client.
      *
      * The `B1` regression context (2026-04-22 QA pass): the chat surface
-     * in `/chat` reuses one session across turns. The first turn's push
-     * subscribed AFTER `appendStackItem` ran, so the ack carried the
-     * entry. The second turn's push appended on the live session — the
+     * in `/chat` reuses one render across turns. The first turn's render
+     * subscribed AFTER `commit` ran, so the ack carried the
+     * entry. The second turn's commit landed on the live render — the
      * subscriber never heard about the new entry, the inline UI slot
-     * stayed in "Waiting for session channel replay…" indefinitely.
-     * `notifyStackPush` closes that gap. Best-effort: per-subscriber
+     * stayed in "Waiting for render channel replay…" indefinitely.
+     * `notifyRenderPush` closes that gap. Best-effort: per-subscriber
      * send failures are swallowed (same posture as `sendToSession`).
      *
      * NOT durable. Frames are not stamped through the replay buffer —
-     * fresh subscribers still get the current stack via `ack.stack` on
-     * subscribe. A new tab opening mid-session reads the latest stack
+     * fresh subscribers still get the current render via `ack.render` on
+     * subscribe. A new tab opening mid-render reads the latest render
      * from the snapshot; live tabs read the delta from this notify.
      *
      * Subscribers received via `register()` are tracked in
      * `subscribersBySession`; this helper iterates the bound set and
      * skips closed sockets via the `send()` helper's existing guard.
      * Callers ARE responsible for ordering — call after the underlying
-     * `sessionStore.appendStackItem` resolves so the snapshot a
+     * `renderStore.commit` resolves so the snapshot a
      * concurrent fresh subscriber observes still includes the entry.
      */
-    notifyStackPush(sessionId: string, stackItem: SessionStackEntry, matchType?: string): void;
+    notifyRenderPush(renderId: string, render: Render, matchType?: string): void;
     /**
-     * Prime every declared streamSpec channel on `stackItem` that carries a
+     * Prime every declared streamSpec channel on `render` that carries a
      * `tool` refresh hint. Invokes each refresh tool via the bound
      * wiredActionRouter with the empty refresh input, validates the result
      * against the channel's schema, and fans it out so subscribers see an
      * initial value instead of `latest = undefined`.
      *
-     * Intended for seed-a-session mount paths (console try-live, agent-
-     * initiated bootstraps that append a stack item without a driving
+     * Intended for seed-a-render mount paths (console try-live, agent-
+     * initiated bootstraps that mint a render without a driving
      * action). Without this, blueprints with `streamSpec[channel].tool`
      * render their empty-state branch because the channel has no live
      * delivery — operators see "waiting for data" UI even when the
@@ -559,41 +584,41 @@ export interface SessionChannelServer {
      * Same isolation posture as the action-driven refresh pass: one
      * broken refresh MUST NOT block others; per-channel failures log a
      * warning but don't throw. No-op when no wiredActionRouter is
-     * configured, when `stackItem.streamSpec` is absent, or when every
+     * configured, when `render.streamSpec` is absent, or when every
      * channel lacks a `.tool` hint.
      *
-     * Ordering: callers should invoke AFTER the stack item is persisted
-     * so `sendToSession`'s active-stack-item lookup resolves. The
+     * Ordering: callers should invoke AFTER the render is persisted
+     * so `sendToSession`'s active-render lookup resolves. The
      * `try-live` endpoint awaits this before returning the shortCode so
      * the viewer SPA subscribes with the initial envelope already
-     * buffered on the session's stream-buffer replay state.
+     * buffered on the render's stream-buffer replay state.
      */
-    primeStreams(sessionId: string, stackItem: SessionStackEntry): Promise<void>;
+    primeStreams(renderId: string, render: Render): Promise<void>;
     /**
-     * Fan a `{type:'props_update', payload:{stackItemId, props}}` wire frame
-     * to every subscriber currently bound to `sessionId`. Mount tools
+     * Fan a `{type:'props_update', payload:{renderId, props}}` wire frame
+     * to every subscriber currently bound to `renderId`. Mount tools
      * dispatched through {@link WiredActionRouter} call this via
      * `WiredActionContext.sendPropsUpdate` so a wired action that
      * mutates server-side state can replace renderer props in-place
      * without going through a refresh-stream tool.
      *
-     * Validation posture (mirrors `notifyStackPush`'s "best-effort orphan
+     * Validation posture (mirrors `notifyRenderPush`'s "best-effort orphan
      * no-op"):
-     *   1. Look up the session via `sessionStore.get`. Absent → log
+     *   1. Look up the session via `renderStore.get`. Absent → log
      *      `session_channel_props_update_orphan` and return — the wire
      *      validator on the renderer side would reject a frame for an
      *      unknown session anyway.
-     *   2. Look up the target stack entry by `stackItemId` in the loaded
+     *   2. Look up the target stack entry by `renderId` in the loaded
      *      session's stack. Absent → log
      *      `session_channel_props_update_pageid_unknown` and return.
      *   3. Iterate the flat WS-subscriber set, filter to subscribers
-     *      whose `sessionId` matches, and `send()` the frame. Closed
+     *      whose `renderId` matches, and `send()` the frame. Closed
      *      sockets are skipped silently by `send()`.
      *
      * NOT routed through StreamFanout — `type: 'props_update'` is a
      * distinct WebSocket message type, not a stream envelope. Stream
      * envelopes flow on `data` frames and have a `seq` cursor; props
-     * updates are ephemeral and follow `notifyStackPush`'s pattern
+     * updates are ephemeral and follow `notifyRenderPush`'s pattern
      * (live-only, no replay-buffer stamping). A new subscriber that
      * connects mid-session reads current `props` from the stack
      * snapshot delivered in `ack.stack`.
@@ -601,17 +626,17 @@ export interface SessionChannelServer {
      * Schema validation against `propsSpec`: NOT enforced server-side
      * here. The renderer validates inbound props via
      * `validateInboundPropsPayload` against the cached
-     * `stackItem.propsSpec` before applying — defense-in-depth at the
+     * `render.propsSpec` before applying — defense-in-depth at the
      * receiving boundary. Server-side enforcement is reserved for the
      * future agent-driven `ggui_update` path; the mount-tool seam is
      * trusted-runtime today (mounts execute in-process, same trust
      * boundary as ggui-native handlers).
      */
-    sendPropsUpdate(sessionId: string, stackItemId: string, props: JsonObject): Promise<void>;
+    sendPropsUpdate(renderId: string, props: JsonObject): Promise<void>;
     /**
-     * Fan a `{type:'drain_ack', payload:{sessionId, appId, stackItemId,
+     * Fan a `{type:'drain_ack', payload:{renderId, appId, renderId,
      * eventId, drainedAt}}` wire frame to every subscriber currently
-     * bound to `sessionId`.
+     * bound to `renderId`.
      *
      * Fired by `createGguiConsumeHandler` once per drained
      * `PendingEvent` so the iframe-runtime can cancel the matching
@@ -619,19 +644,37 @@ export interface SessionChannelServer {
      * Implements the `DrainAckNotifier` contract from
      * `@ggui-ai/mcp-server-handlers`.
      *
-     * Same posture as `notifyStackPush` / `sendPropsUpdate` — live-only,
+     * Same posture as `notifyRenderPush` / `sendPropsUpdate` — live-only,
      * no replay-buffer stamping. Subscribers that connect AFTER the
      * drain see the next consume's snapshot rather than the missed
      * frame; the iframe's claim timer + atomic-pop primitive backstop
      * any frame loss.
      */
     sendDrainAck(args: {
-        readonly sessionId: string;
+        readonly renderId: string;
         readonly appId: string;
-        readonly stackItemId: string;
         readonly eventId: string;
         readonly drainedAt: string;
     }): void;
+    /**
+     * Fan a server-frame to every local WS subscriber bound to
+     * `renderId`. Skips replay-buffer stamping, RenderStore lookups,
+     * and contract validation — the caller is the one that originally
+     * validated + persisted the underlying mutation. This surface is the
+     * cloud adapter's path for delivering already-validated frames that
+     * arrived via an external pubsub layer (Redis from another pod).
+     *
+     * Internal adapter use only. NOT part of the published ggui
+     * protocol, NOT stable across versions, NOT exposed to MCP / wire
+     * callers. The publisher is responsible for ensuring `frame` is
+     * wire-valid; this method does not re-validate.
+     *
+     * No-op when no local subscriber is bound to `renderId`. Closed
+     * sockets are skipped silently by the underlying `send()` helper —
+     * same posture as `sendPropsUpdate` / `notifyRenderPush`. Per-
+     * subscriber send failures are logged but never propagated.
+     */
+    externalBroadcast(renderId: string, frame: WebSocketMessage): void;
     /** Number of live subscribers. Useful for health / debug introspection. */
     readonly subscriberCount: number;
     /** Number of distinct sessions with at least one subscriber. */
@@ -645,7 +688,7 @@ export interface SessionChannelServer {
  * Build an OSS live-channel server. The returned object is designed to be
  * composed into `createGguiServer` — see `server.ts` for the wire-up.
  */
-export declare function createSessionChannelServer(opts: SessionChannelOptions): SessionChannelServer;
+export declare function createRenderChannelServer(opts: RenderChannelOptions): RenderChannelServer;
 /** Fabricate a request id for live-channel ops so logs correlate. */
 export declare function newRequestId(): string;
-//# sourceMappingURL=session-channel.d.ts.map
+//# sourceMappingURL=render-channel.d.ts.map

package/dist/render-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-channel.d.ts","sourceRoot":"","sources":["../src/render-channel.ts"],"names":[],"mappings":"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"}