@ggui-ai/iframe-runtime 0.1.0-rc.1 → 0.2.0-alpha.1

package/README.md

@@ -4,7 +4,7 @@ The iframe-local runtime for [ggui](https://ggui.ai).
 
 A self-contained ESM bundle that boots inside an MCP Apps host iframe,
 runs the protocol-version handshake, opens the live-channel WebSocket,
-and renders the ggui session stack. It bundles React, ReactDOM, and the
+and mounts the rendered UI. It bundles React, ReactDOM, and the
 ggui design system inside the artifact so generated component code has a
 single seam to read from.
 
@@ -16,17 +16,18 @@ exists for host apps, the `<McpAppIframe>` wrapper, and tests.
 
 For host-side code that needs to validate or react to runtime state:
 
-- `parseBootstrap` (and `parseBootstrapFrom*` variants) —
-  parse and validate a session bootstrap before spawning the iframe.
+- `parseMetaFromGlobal` / `parseMetaFromToolResult` —
+  parse and validate a render bootstrap before spawning the iframe.
 - `ProtocolError` and the `from*` constructors — the canonical typed
   union for every failure the renderer classifies outward.
 - `ObservabilityEvent` / `postObservabilityToParent` — the renderer →
   host telemetry seam.
 - `LifecycleEmitter` / `postLifecycleToParent` — lifecycle events.
 
-Internal runtime types (`RendererWebSocketManager`, `StackModel`, the
-boot sequence) are deliberately not exported — they are an internal
-implementation contract, not a public API.
+Internal runtime types (`bootSequence`, `connectViaRegistry`, the
+per-channel handler factories, and the single-item render mount) are
+deliberately not exported — they are an internal implementation
+contract, not a public API.
 
 ## License
 

package/dist/channel-transport.d.ts

@@ -19,7 +19,7 @@
  *     for any tool the agent has access to, including third-party
  *     MCP servers the local pod can't subscribe-for.
  *
- * The dispatch decision is per-channel + per-render (each new push
+ * The dispatch decision is per-channel + per-render (each new render
  * brings a potentially-new contract; we re-run the routing). The
  * StreamBus + `useStream(channel)` API stay unchanged — the router
  * adapts payloads from both transports into the same envelope shape
@@ -36,7 +36,7 @@
  * on the {@link RendererWebSocketManager}. The router only watches
  * status transitions; it doesn't own the reconnect schedule.
  *
- * **Idempotence** — re-subscribing the same `(stackItemId, channelName)`
+ * **Idempotence** — re-subscribing the same `(renderId, channelName)`
  * pair is server-side idempotent (the server's `ChannelSubscriptionState`
  * replaces in place). Clients can re-send on reconnect without bookkeeping
  * a "did we already subscribe?" gate.
@@ -83,9 +83,9 @@ export type ToolsCallInvoker = (args: {
  * Options for {@link createChannelTransportRouter}.
  */
 export interface ChannelTransportRouterOptions {
-    /** Session id the router scopes channel_subscribe frames against. */
-    readonly sessionId: string;
-    /** App (tenant) id paired with sessionId on the subscribe frame. */
+    /** Render id the router scopes channel_subscribe frames against. */
+    readonly renderId: string;
+    /** App (tenant) id paired with renderId on the subscribe frame. */
     readonly appId: string;
     /**
      * Allowlist of `source.tool` names this server can subscribe-for
@@ -121,17 +121,17 @@ export interface ChannelTransportRouterOptions {
  */
 export type ChannelTransportEvent = {
     readonly kind: 'channel-transport-picked';
-    readonly stackItemId: string;
+    readonly renderId: string;
     readonly channelName: string;
     readonly transport: 'ws' | 'poll';
 } | {
     readonly kind: 'channel-transport-fallback';
-    readonly stackItemId: string;
+    readonly renderId: string;
     readonly channelName: string;
     readonly reason: 'ws-disconnect' | 'channel-not-local';
 } | {
     readonly kind: 'channel-transport-resubscribed';
-    readonly stackItemId: string;
+    readonly renderId: string;
     readonly channelName: string;
 };
 /**
@@ -139,16 +139,16 @@ export type ChannelTransportEvent = {
  */
 export interface ChannelTransportRouter {
     /**
-     * Apply a new stack item's `streamSpec`. Idempotent against
-     * re-applying the same shape (no churn). Channels added/removed
-     * across renders fire transport pick / teardown accordingly.
+     * Apply a new render's `streamSpec`. Idempotent against re-applying
+     * the same shape (no churn). Channels added/removed across renders
+     * fire transport pick / teardown accordingly.
      *
      * The legacy `data` frame path on `streamSpec[ch]` entries
      * WITHOUT `source.tool` is unaffected — the router only manages
      * the source-fed subset.
      */
-    readonly applyStackItem: (item: {
-        readonly stackItemId: string;
+    readonly applyRender: (render: {
+        readonly renderId: string;
         readonly streamSpec?: StreamSpec;
     }) => void;
     /**
@@ -168,14 +168,14 @@ export interface ChannelTransportRouter {
     readonly onWsStatusChange: (status: 'connecting' | 'connected' | 'disconnected' | 'reconnecting') => void;
     /**
      * Tear down every active subscription + timer. Called on
-     * `triadWiring.teardown`.
+     * `renderer.teardown`.
      */
     readonly dispose: () => void;
 }
 /**
  * Factory.
  *
- * Per-channel transport routing — owns the `(stackItemId, channelName)`
+ * Per-channel transport routing — owns the `(renderId, channelName)`
  * registry, the WS-vs-poll decision per channel, and the cross-state
  * transitions (disconnect → poll fallback, reconnect → re-subscribe).
  */

package/dist/channel-transport.js

@@ -10,13 +10,13 @@ export const DEFAULT_IFRAME_POLL_INTERVAL_MS = 10_000;
 /**
  * Factory.
  *
- * Per-channel transport routing — owns the `(stackItemId, channelName)`
+ * Per-channel transport routing — owns the `(renderId, channelName)`
  * registry, the WS-vs-poll decision per channel, and the cross-state
  * transitions (disconnect → poll fallback, reconnect → re-subscribe).
  */
 export function createChannelTransportRouter(opts) {
     /**
-     * Registry keyed by `${stackItemId}:${channelName}`. The composite
+     * Registry keyed by `${renderId}:${channelName}`. The composite
      * key matches the server-side `channelSubs` map shape exactly, so
      * test snapshots line up.
      */
@@ -27,15 +27,15 @@ export function createChannelTransportRouter(opts) {
      * WS lifecycle flag. We start in `'connected'` because the router
      * is created AFTER the subscribe ack — the runtime's bootSequence
      * resolves `subscribeFn(...)` before threading the manager into
-     * triadWiring's `attachManager` (where the router is constructed).
+     * renderer's `attachManager` (where the router is constructed).
      * Status transitions update this; the router uses it to decide
      * whether to start WS subscribes or skip straight to polling.
      */
     let wsStatus = 'connected';
     let disposed = false;
     const observe = opts.onObserve ?? (() => { });
-    function keyOf(stackItemId, channelName) {
-        return `${stackItemId}:${channelName}`;
+    function keyOf(renderId, channelName) {
+        return `${renderId}:${channelName}`;
     }
     function stopPolling(state) {
         if (state.pollTimer !== null) {
@@ -45,7 +45,7 @@ export function createChannelTransportRouter(opts) {
     }
     function emitToBus(state, payload, complete) {
         const envelope = {
-            sessionId: opts.sessionId,
+            renderId: state.renderId,
             channel: state.channelName,
             mode: state.mode,
             payload,
@@ -90,16 +90,15 @@ export function createChannelTransportRouter(opts) {
     }
     /**
      * Send a `channel_subscribe` WS frame. Server-side bookkeeping is
-     * idempotent on `(sessionId, stackItemId, channelName)`, so re-sends
-     * on reconnect are safe.
+     * idempotent on `(renderId, channelName)`, so re-sends on reconnect
+     * are safe.
      */
     function sendSubscribe(state) {
         opts.send({
             type: 'channel_subscribe',
             payload: {
-                sessionId: opts.sessionId,
+                renderId: state.renderId,
                 appId: opts.appId,
-                stackItemId: state.stackItemId,
                 channelName: state.channelName,
                 ...(state.args !== undefined ? { args: { ...state.args } } : {}),
             },
@@ -115,9 +114,8 @@ export function createChannelTransportRouter(opts) {
         opts.send({
             type: 'channel_unsubscribe',
             payload: {
-                sessionId: opts.sessionId,
+                renderId: state.renderId,
                 appId: opts.appId,
-                stackItemId: state.stackItemId,
                 channelName: state.channelName,
             },
         });
@@ -139,7 +137,7 @@ export function createChannelTransportRouter(opts) {
                 sendSubscribe(state);
                 observe({
                     kind: 'channel-transport-picked',
-                    stackItemId: state.stackItemId,
+                    renderId: state.renderId,
                     channelName: state.channelName,
                     transport: 'ws',
                 });
@@ -150,7 +148,7 @@ export function createChannelTransportRouter(opts) {
             startPolling(state);
             observe({
                 kind: 'channel-transport-picked',
-                stackItemId: state.stackItemId,
+                renderId: state.renderId,
                 channelName: state.channelName,
                 transport: 'poll',
             });
@@ -159,17 +157,17 @@ export function createChannelTransportRouter(opts) {
         startPolling(state);
         observe({
             kind: 'channel-transport-picked',
-            stackItemId: state.stackItemId,
+            renderId: state.renderId,
             channelName: state.channelName,
             transport: 'poll',
         });
     }
     return {
-        applyStackItem: (item) => {
+        applyRender: (render) => {
             if (disposed)
                 return;
             const seenKeys = new Set();
-            const spec = item.streamSpec ?? {};
+            const spec = render.streamSpec ?? {};
             for (const [channelName, entry] of Object.entries(spec)) {
                 const source = entry.source;
                 // Channels without a `source.tool` declaration stay on the
@@ -186,18 +184,18 @@ export function createChannelTransportRouter(opts) {
                 const channelArgs = source.args !== undefined && source.args !== null
                     ? source.args
                     : undefined;
-                const k = keyOf(item.stackItemId, channelName);
+                const k = keyOf(render.renderId, channelName);
                 seenKeys.add(k);
                 const existing = channels.get(k);
                 if (existing !== undefined) {
-                    // Same (stackItemId, channelName) — leave the transport
+                    // Same (renderId, channelName) — leave the transport
                     // bookkeeping alone. Spec changes that flip preferWs
-                    // mid-session are out of 1c scope (would require
+                    // mid-render are out of 1c scope (would require
                     // re-handshake).
                     continue;
                 }
                 const state = {
-                    stackItemId: item.stackItemId,
+                    renderId: render.renderId,
                     channelName,
                     toolName,
                     ...(channelArgs !== undefined ? { args: channelArgs } : {}),
@@ -210,13 +208,12 @@ export function createChannelTransportRouter(opts) {
                 channels.set(k, state);
                 activate(state);
             }
-            // Tear down any channel for THIS stack item that's no longer in
-            // the spec. Channels for OTHER stack items stay — they belong
-            // to other items that haven't been re-applied yet. Stack-pop /
-            // close-session paths call `dispose()` for the wholesale
-            // teardown.
+            // Tear down any channel for THIS render that's no longer in the
+            // spec. Channels for OTHER renders stay — they belong to other
+            // mounts that haven't been re-applied yet. Close-render paths
+            // call `dispose()` for the wholesale teardown.
             for (const [k, state] of channels) {
-                if (state.stackItemId === item.stackItemId &&
+                if (state.renderId === render.renderId &&
                     !seenKeys.has(k)) {
                     stopPolling(state);
                     sendUnsubscribe(state);
@@ -229,7 +226,7 @@ export function createChannelTransportRouter(opts) {
                 return false;
             if (msg.type === 'channel_payload') {
                 const p = msg.payload;
-                const k = keyOf(p.stackItemId, p.channelName);
+                const k = keyOf(p.renderId, p.channelName);
                 const state = channels.get(k);
                 if (state === undefined)
                     return false;
@@ -247,9 +244,9 @@ export function createChannelTransportRouter(opts) {
             if (msg.type === 'channel_error') {
                 const p = msg.payload;
                 // Locate by `channelName` only — the error payload doesn't
-                // carry `stackItemId`. We match by channel-name across active
+                // carry `renderId`. We match by channel-name across active
                 // items and apply the permanent-fallback flag to the matching
-                // entries. Same channel name across stack items is rare; the
+                // entries. Same channel name across renders is rare; the
                 // policy is conservative (fall back ALL matches rather than
                 // miss one).
                 for (const state of channels.values()) {
@@ -257,12 +254,12 @@ export function createChannelTransportRouter(opts) {
                         continue;
                     if (p.code === 'CHANNEL_NOT_LOCAL' ||
                         p.code === 'CHANNEL_UNKNOWN' ||
-                        p.code === 'STACK_ITEM_NOT_FOUND') {
+                        p.code === 'RENDER_NOT_FOUND') {
                         state.permanentPollFallback = true;
                         startPolling(state);
                         observe({
                             kind: 'channel-transport-fallback',
-                            stackItemId: state.stackItemId,
+                            renderId: state.renderId,
                             channelName: state.channelName,
                             reason: 'channel-not-local',
                         });
@@ -301,7 +298,7 @@ export function createChannelTransportRouter(opts) {
                         startPolling(state);
                         observe({
                             kind: 'channel-transport-fallback',
-                            stackItemId: state.stackItemId,
+                            renderId: state.renderId,
                             channelName: state.channelName,
                             reason: 'ws-disconnect',
                         });
@@ -313,7 +310,7 @@ export function createChannelTransportRouter(opts) {
                 (prevStatus === 'disconnected' || prevStatus === 'reconnecting')) {
                 // Reconnected. Re-send `channel_subscribe` for every
                 // WS-preferring channel. Server is idempotent on the (session,
-                // stackItem, channel) triple, so duplicates are safe. We
+                // render, channel) tuple, so duplicates are safe. We
                 // intentionally LEAVE the polling fallback running until the
                 // first `channel_payload` lands — bridges the gap where the
                 // server's first post-reconnect poll cycle hasn't fired yet.
@@ -325,7 +322,7 @@ export function createChannelTransportRouter(opts) {
                     sendSubscribe(state);
                     observe({
                         kind: 'channel-transport-resubscribed',
-                        stackItemId: state.stackItemId,
+                        renderId: state.renderId,
                         channelName: state.channelName,
                     });
                 }

package/dist/channels/channel-payload.d.ts

@@ -7,10 +7,10 @@
  * passthrough — the router parses the frame contents against its
  * subscription map and dispatches to the matching consumer.
  *
- * Factored out of `handleTriadMessage` as part of the B3a handler
+ * Factored out of `handleRendererMessage` as part of the B3a handler
  * extraction.
  */
-import type { ChannelHandler } from '@ggui-ai/channel-client';
+import type { ChannelHandler } from '@ggui-ai/live-channel';
 import type { ChannelErrorPayload, ChannelPayloadFrame } from '@ggui-ai/protocol';
 import type { ChannelTransportRouter } from '../channel-transport.js';
 export interface ChannelRouterHandlerDeps {

package/dist/channels/channel-payload.js

@@ -7,7 +7,7 @@
  * passthrough — the router parses the frame contents against its
  * subscription map and dispatches to the matching consumer.
  *
- * Factored out of `handleTriadMessage` as part of the B3a handler
+ * Factored out of `handleRendererMessage` as part of the B3a handler
  * extraction.
  */
 export function createChannelPayloadHandler(deps) {

package/dist/channels/data.d.ts

@@ -1,6 +1,6 @@
 /**
  * `data` channel handler — validates inbound stream-envelope payloads
- * against the active stack item's `streamSpec`, then fans the validated
+ * against the active render's `streamSpec`, then fans the validated
  * envelope out via `streamBus`. Invalid payloads drop silently
  * (matching `GguiSession.handleServerMessage`'s surfacing policy —
  * the violation is already logged by the validator).
@@ -11,18 +11,24 @@
  * in `runtime.ts` as part of the B3b cleanup — the handler is now the
  * sole dispatch surface for `data` frames.
  *
- * Factored out of `handleTriadMessage` as part of the B3a handler
- * extraction; expanded in B3b to absorb the observability-axis
- * emission previously fired in parallel from `bootSequence`.
+ * Post-stack-removal (2026-05-27): the active render is read through
+ * the caller-supplied `getCurrentRender` thunk instead of via a
+ * `StackModel.snapshot()` walk — the iframe holds exactly one mounted
+ * render, so the lookup is direct.
  */
-import type { ChannelHandler } from '@ggui-ai/channel-client';
-import { type CanvasLifecyclePayload, type StreamEnvelope } from '@ggui-ai/protocol';
+import type { ChannelHandler } from '@ggui-ai/live-channel';
+import { type Render, type StreamEnvelope } from '@ggui-ai/protocol';
+import type { RenderSeedInput } from '../types.js';
 import type { ObservabilityEmitter } from '../observability.js';
-import type { StackModel } from '../stack.js';
 import { type RendererValidatorContext } from '../validation.js';
 import type { StreamBus } from '../wire-config.js';
 export interface DataHandlerDeps {
-    readonly stackModel: StackModel;
+    /**
+     * Read the currently-mounted render. Returns `null` when no render
+     * has been mounted yet — data frames received pre-mount have no
+     * streamSpec to validate against and silently drop.
+     */
+    readonly getCurrentRender: () => Render | RenderSeedInput | null;
     readonly streamBus: StreamBus;
     readonly validatorCtx: RendererValidatorContext;
     /**
@@ -33,16 +39,5 @@ export interface DataHandlerDeps {
      * bound).
      */
     readonly onObserve?: ObservabilityEmitter;
-    /**
-     * Optional canvas-mode lifecycle sink. When present, every envelope
-     * on the reserved `_ggui:lifecycle` channel fires this callback
-     * with the parsed payload. Production wires it to mount.tsx's
-     * AnimatorEventBus so the animator pill state machine advances.
-     * Non-canvas iframes leave it absent and the envelopes drop
-     * silently — `validateInboundStreamPayload` rejects lifecycle
-     * payloads when no reserved validator is registered for them
-     * client-side, so they never reach `streamBus.emit` either.
-     */
-    readonly onCanvasLifecycle?: (payload: CanvasLifecyclePayload) => void;
 }
 export declare function createDataHandler(deps: DataHandlerDeps): ChannelHandler<StreamEnvelope>;

package/dist/channels/data.js

@@ -1,6 +1,6 @@
 /**
  * `data` channel handler — validates inbound stream-envelope payloads
- * against the active stack item's `streamSpec`, then fans the validated
+ * against the active render's `streamSpec`, then fans the validated
  * envelope out via `streamBus`. Invalid payloads drop silently
  * (matching `GguiSession.handleServerMessage`'s surfacing policy —
  * the violation is already logged by the validator).
@@ -11,11 +11,12 @@
  * in `runtime.ts` as part of the B3b cleanup — the handler is now the
  * sole dispatch surface for `data` frames.
  *
- * Factored out of `handleTriadMessage` as part of the B3a handler
- * extraction; expanded in B3b to absorb the observability-axis
- * emission previously fired in parallel from `bootSequence`.
+ * Post-stack-removal (2026-05-27): the active render is read through
+ * the caller-supplied `getCurrentRender` thunk instead of via a
+ * `StackModel.snapshot()` walk — the iframe holds exactly one mounted
+ * render, so the lookup is direct.
  */
-import { CONTRACT_ERROR_CHANNEL, LIFECYCLE_CHANNEL, } from '@ggui-ai/protocol';
+import { CONTRACT_ERROR_CHANNEL, } from '@ggui-ai/protocol';
 import { validateInboundStreamPayload, } from '../validation.js';
 export function createDataHandler(deps) {
     return {
@@ -36,32 +37,13 @@ export function createDataHandler(deps) {
                 deps.onObserve !== undefined) {
                 emitContractErrorFromDataFrame(envelope, deps.onObserve);
             }
-            // Canvas-mode lifecycle
-            // envelopes — fires BEFORE validation for the same reason as
-            // the contract-error path: the wire shape is server-owned, and
-            // any reachable envelope is a server-emitted signal. The
-            // payload's `kind` discriminator narrows downstream; the
-            // animator host treats unknown kinds as no-ops. Invalid shapes
-            // silently drop here (typeof check) — defensive against future
-            // wire shape drift.
-            if (envelope.channel === LIFECYCLE_CHANNEL &&
-                deps.onCanvasLifecycle !== undefined) {
-                const payload = envelope.payload;
-                if (payload !== null &&
-                    typeof payload === 'object' &&
-                    !Array.isArray(payload) &&
-                    typeof payload.kind === 'string') {
-                    deps.onCanvasLifecycle(payload);
-                }
-            }
-            // Active stack item carries the streamSpec — mirrors
-            // `GguiSession.handleServerMessage`. Top of stack only.
-            const snapshot = deps.stackModel.snapshot();
-            const activeItem = snapshot[snapshot.length - 1];
-            const streamSpec = activeItem !== undefined &&
-                activeItem.type !== 'mcpApps' &&
-                activeItem.type !== 'system'
-                ? activeItem.streamSpec
+            // Active render carries the streamSpec — mirrors
+            // `GguiSession.handleServerMessage`.
+            const activeRender = deps.getCurrentRender();
+            const streamSpec = activeRender !== null &&
+                activeRender.type !== 'mcpApps' &&
+                activeRender.type !== 'system'
+                ? activeRender.streamSpec
                 : undefined;
             const result = validateInboundStreamPayload(streamSpec, envelope.channel, envelope.payload, deps.validatorCtx);
             if (!result.valid)

package/dist/channels/drain-ack.d.ts

@@ -1,11 +1,11 @@
 /**
  * `drain_ack` channel handler — factored out of `runtime.ts` into
- * the `@ggui-ai/channel-client` layer. The `onMessage` body fans the
+ * the `@ggui-ai/live-channel` layer. The `onMessage` body fans the
  * payload out to the module-scoped `subscribeDrainAck` listener
  * registry so per-action state machines stay decoupled from how the
  * frame arrives on the wire.
  */
-import type { ChannelHandler } from '@ggui-ai/channel-client';
+import type { ChannelHandler } from '@ggui-ai/live-channel';
 import type { DrainAckPayload } from '@ggui-ai/protocol';
 export interface DrainAckHandlerDeps {
     readonly dispatch: (payload: DrainAckPayload) => void;

package/dist/channels/drain-ack.js

@@ -1,6 +1,6 @@
 /**
  * `drain_ack` channel handler — factored out of `runtime.ts` into
- * the `@ggui-ai/channel-client` layer. The `onMessage` body fans the
+ * the `@ggui-ai/live-channel` layer. The `onMessage` body fans the
  * payload out to the module-scoped `subscribeDrainAck` listener
  * registry so per-action state machines stay decoupled from how the
  * frame arrives on the wire.

package/dist/channels/feedback.d.ts

@@ -9,6 +9,6 @@
  * "no handler for type 'feedback'" warnings — the silence is
  * intentional, the handler documents that.
  */
-import type { ChannelHandler } from '@ggui-ai/channel-client';
+import type { ChannelHandler } from '@ggui-ai/live-channel';
 import type { JsonObject } from '@ggui-ai/protocol';
 export declare function createFeedbackHandler(): ChannelHandler<JsonObject>;

package/dist/channels/index.d.ts

@@ -1,6 +1,6 @@
 export { createPropsUpdateHandler, type PropsUpdateHandlerDeps, } from './props-update.js';
 export { createDrainAckHandler, type DrainAckHandlerDeps, } from './drain-ack.js';
-export { createPushHandler, type PushHandlerDeps } from './push.js';
+export { createRenderHandler, type RenderHandlerDeps } from './render-frame.js';
 export { createDataHandler, type DataHandlerDeps } from './data.js';
 export { createFeedbackHandler } from './feedback.js';
 export { createChannelPayloadHandler, createChannelErrorHandler, type ChannelRouterHandlerDeps, } from './channel-payload.js';

package/dist/channels/index.js

@@ -1,6 +1,6 @@
 export { createPropsUpdateHandler, } from './props-update.js';
 export { createDrainAckHandler, } from './drain-ack.js';
-export { createPushHandler } from './push.js';
+export { createRenderHandler } from './render-frame.js';
 export { createDataHandler } from './data.js';
 export { createFeedbackHandler } from './feedback.js';
 export { createChannelPayloadHandler, createChannelErrorHandler, } from './channel-payload.js';

package/dist/channels/props-update.d.ts

@@ -1,53 +1,49 @@
 /**
- * `props_update` channel handler — factored out of `runtime.ts` into
- * the `@ggui-ai/channel-client` layer.
+ * `props_update` channel handler — patches the currently-mounted
+ * render's props in place via the renderer's `applyRender`
+ * callback.
  *
- * Receives a `{stackItemId, props}` payload from the live channel, validates
- * the new props against the stack item's cached `propsSpec`, patches
- * the in-model entry, and re-applies the renderer so React picks up
- * the change.
+ * Post-stack-removal (2026-05-27): each iframe holds exactly one
+ * mounted render. The handler reads the current render via
+ * `getCurrentRender()`, validates the inbound props against its
+ * cached `propsSpec`, and re-applies the patched render through
+ * `applyRender` — the same callback the render handler uses, so the
+ * React update surface is unified.
  *
  * Skips when:
- *   - `stackItemId` is empty or not a string.
+ *   - `renderId` is empty or not a string.
  *   - `props` is null / not an object (defensive — server can't emit
  *     this shape, but the dispatcher routes the frame on type alone).
- *   - No matching stack item exists (server raced ahead of our pop).
- *   - The matched item is `mcpApps` / `system` (no `propsSpec`; server
- *     should never emit `props_update` for these).
+ *   - No render is currently mounted (`getCurrentRender` returns null).
+ *   - The current render's id doesn't match `payload.renderId` —
+ *     the server may have raced ahead of an in-flight render swap.
+ *   - The current render is `mcpApps` / `system` (no `propsSpec`;
+ *     server should never emit `props_update` for these).
  *   - The new props fail validation against the cached spec.
  *
- * An OPTIONAL polling descriptor provides a fallback transport —
- * when `polling` is supplied at factory time, `PollingTransport`
- * polls `/api/bootstrap/<shortCode>` and synthesizes a frame
- * whenever `propsJson` diffs from the last seen hash. WS hosts are
- * unaffected (the `polling` descriptor is inert under `WSTransport`).
+ * R6 (2026-05-26) retired the per-handler polling descriptor. Polling
+ * is now registry-level — the iframe-runtime composes the
+ * `/api/renders/:id/state?wsToken=<token>` URL and a snapshot-parsing
+ * function once at bind time (see `runtime.ts`); a single fetch per
+ * tick projects the slice envelope into per-handler frames the
+ * `PollingTransport` dispatches.
  */
-import type { ChannelHandler } from '@ggui-ai/channel-client';
-import type { PropsUpdatePayload } from '@ggui-ai/protocol';
-import type { StackRenderer } from '../stack-item-renderer.js';
-import type { StackModel } from '../stack.js';
+import type { ChannelHandler } from '@ggui-ai/live-channel';
+import type { PropsUpdatePayload, Render } from '@ggui-ai/protocol';
+import type { RenderSeedInput } from '../types.js';
 export interface PropsUpdateHandlerDeps {
-    readonly stackModel: StackModel;
-    readonly getStackRenderer: () => StackRenderer;
     /**
-     * Optional polling fallback URL. When the registry's chosen transport
-     * is `PollingTransport` (e.g. bootstrap missing wsUrl, or
-     * `FailoverHandle` swapped WS → polling after a hard failure), this
-     * URL is fetched on each tick. The response body is expected to carry
-     * `propsJson` + `stackItemId` (the same shape `/api/bootstrap/<code>`
-     * returns); the handler diffs `propsJson` between ticks and synthesizes
-     * a `props_update` frame whenever it changes. WS hosts ignore this
-     * descriptor (polling is inert under `WSTransport`).
-     *
-     * Producer: server stamps `bootstrap.pollingUrl` on the bootstrap
-     * envelope. Consumer: iframe-runtime threads it here at handler
-     * registration time. Absent → no polling fallback (WS-only mode).
+     * Read the currently-mounted render. Returns `null` when no
+     * render has been mounted yet (the first render frame hasn't landed)
+     * or after teardown. The handler short-circuits on `null` —
+     * `props_update` before the first render frame has no React tree to
+     * patch.
      */
-    readonly pollingUrl?: string;
+    readonly getCurrentRender: () => Render | RenderSeedInput | null;
     /**
-     * Polling cadence in milliseconds. Defaults to 2000ms per the B5
-     * plan (well inside the 10s drain-claim budget; 5 ticks of safety).
+     * Re-apply the patched render to the single mount slot. Shared with
+     * the render-frame handler so React updates flow through one path.
      */
-    readonly pollingIntervalMs?: number;
+    readonly applyRender: (render: Render | RenderSeedInput) => Promise<void>;
 }
 export declare function createPropsUpdateHandler(deps: PropsUpdateHandlerDeps): ChannelHandler<PropsUpdatePayload>;