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

package/dist/wire-config.d.ts

@@ -1,26 +1,12 @@
 /**
- * Per-stack-item `WireConfig` factory for the renderer iframe.
+ * Per-render `WireConfig` factory for the renderer iframe.
  *
- * The renderer iframe uses a standalone
- * `scopeWireConfig(root, item, internals)` function plus the
- * `RootWireConfigBundle.buildScopedConfig(item)` closure returned
- * from `buildRootWireConfig` — there is no scoping method on the
- * public `WireConfig` shape.
- *
- * Why per-item scoping:
- *   - A stacked/chat-style UI keeps older cards rendered beneath the
- *     top one. A `useAction('submit')` call inside an older card MUST
- *     emit with THAT card's `stackItemId` + `tool` + `actionSpec` — not the
- *     top-of-stack's. Without per-item scoping, contract enforcement
- *     would reject cross-stack dispatches as "wrong contract" OR the
- *     wrong tool would be invoked server-side.
- *
- * Construction: the renderer builds ONE top-level bundle at boot
- * (`buildRootWireConfig`), which returns `{config, buildScopedConfig}`.
- * The runtime's `stackCtx.getScopedWireConfig` calls
- * `buildScopedConfig(item)` per stack entry; each
- * `<GguiWireProvider>` wraps a stack item with the resulting scoped
- * config.
+ * The renderer iframe mounts EXACTLY ONE {@link Render} per iframe
+ * post-render-identity-collapse (2026-05-27). There is no per-item
+ * scoping factory anymore — the WireConfig is built once at boot,
+ * keyed by the bootstrap's `renderId`, and the active render's
+ * `actionSpec` is wired in via the {@link buildRootWireConfig}'s
+ * `getCurrentRender` thunk.
  *
  * Outbound dispatch uses `buildActionEnvelope` (from
  * `@ggui-ai/wire`) + `validateOutboundActionEnvelope` + a direct
@@ -29,16 +15,17 @@
  * The `WireConfig` shape lives in `@ggui-ai/wire`. This module
  * implements against that interface.
  */
-import type { ActionSpec, SessionStackEntry, StreamEnvelope } from '@ggui-ai/protocol';
+import type { ActionEnvelope, Render, StreamEnvelope } from '@ggui-ai/protocol';
+import type { RenderSeedInput } from './types.js';
 import { ClientContractViolationError, type WireConfig } from '@ggui-ai/wire';
 import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
 /**
  * Outbound send surface — the minimal shape wire-config calls on the
  * WS transport. Pre-B3b this read off `Pick<RendererWebSocketManager,
- * 'send'>`; post-B3b the WS lives inside `@ggui-ai/channel-client`,
+ * 'send'>`; post-B3b the WS lives inside `@ggui-ai/live-channel`,
  * but wire-config doesn't import the gadget directly — it consumes
  * the shape via this local type so tests can stub `{send: vi.fn()}`
- * without dragging in the channel-client types.
+ * without dragging in the live-channel types.
  *
  * Frames sent here are always `{type: 'action', payload: ...}` or
  * `{type: 'feedback', payload: ...}` envelopes — wire-config never
@@ -61,7 +48,7 @@ import type { ObservabilityEmitter } from './observability.js';
  *   `subscribe()` → first `ack` → render stack items → mount
  *   `mountProvisional` → it then calls `streamBus.subscribe('_ggui:
  *   preview', …)`. Server-side replay frames for `_ggui:preview` (the
- *   provisional A2UI preamble fired during the agent's `ggui_push`
+ *   provisional A2UI preamble fired during the agent's `ggui_render`
  *   BEFORE the user's browser navigated to the viewer) arrive over the
  *   WS in the window between ack-resolve and the provisional mount —
  *   they hit `emit()` before any listener has subscribed. Without a
@@ -98,15 +85,16 @@ export declare class StreamBus {
     emit(envelope: StreamEnvelope): void;
 }
 export interface BuildRootWireConfigOptions {
-    readonly sessionId: string;
+    readonly renderId: string;
     readonly appId: string;
     /**
-     * Stack snapshot reader. The config's default (unscoped) `dispatch`
-     * reads the top of stack; callers route most dispatches through
-     * `scopeWireConfig(root, item)` for per-item targeting, but the
-     * default is kept for standalone-render paths.
+     * Read the currently-mounted {@link Render}. The config's `dispatch`
+     * resolves the active render's `actionSpec` through this thunk so
+     * the `tool` + outbound validator stay coherent across props_update
+     * patches (which replace the render reference) without rebuilding
+     * the WireConfig.
      */
-    readonly getStack: () => readonly SessionStackEntry[];
+    readonly getCurrentRender: () => Render | RenderSeedInput | null;
     /** Handle to the renderer's WS manager; used for outbound `action` + `feedback` frames. */
     readonly manager: RendererSendSurface;
     /** Shared bus for inbound stream deliveries. */
@@ -154,61 +142,45 @@ export interface BuildRootWireConfigOptions {
      * (host inspector vs operator telemetry).
      */
     readonly onObserve?: ObservabilityEmitter;
-}
-/**
- * Paired root config + scope factory returned by `buildRootWireConfig`.
- *
- * {@link WireConfig} itself carries no `scope(item)` method — the
- * interface is the minimum contract generated code needs, and
- * per-item scoping is a RENDERER concern. Callers that need
- * per-item scoping — currently only the renderer's `bootProduction`
- * via `stackCtx.getScopedWireConfig` — use `buildScopedConfig(item)`
- * on the returned `RootWireConfigBundle`.
- *
- * The scope-factory is PAIRED with the root construction so the
- * `dispatchByItem` / `getStack` internals stay encapsulated — they
- * aren't exported from this module and never leak into the public
- * WireConfig shape.
- */
-export interface RootWireConfigBundle {
-    readonly config: WireConfig;
     /**
-     * Build a per-stack-item scoped `WireConfig`. Only `dispatch` is
-     * overridden — every other seam (subscribe, app/session/auth) stays
-     * shared via spread from the root.
+     * Optional outbound action sink. When provided, REPLACES the
+     * default WS-frame send (`manager.send({type:'action', payload})`).
+     *
+     * The WS live-channel exists for streamSpec subscriptions (inbound
+     * `ggui_emit` fanout + `props_update` + `push` + `data` + `feedback`
+     * + `drain_ack` + `channel_payload`). Outbound user actions belong
+     * on a different pipe — per MCP-Apps spec §401, the iframe relays
+     * `tools/call:ggui_runtime_submit_action` through the host (the
+     * `_meta.ui.visibility:['app']` channel), and the server's MCP
+     * handler appends to `pendingEventConsumer` so `ggui_consume`
+     * wakes the agent.
+     *
+     * The default `manager.send({type:'action'})` path writes to the
+     * session ledger only — it has no downstream consumer in OSS (no
+     * `wiredActionRouter`, no bridge to `pendingEventConsumer`).
+     * Production callers MUST supply this option to reach the agent.
+     *
+     * Called AFTER outbound validation passes. Receives the validated
+     * {@link ActionEnvelope}; caller extracts payload.action +
+     * payload.data + slice meta to route via the host's tools/call
+     * relay (see iframe-runtime's `routeDispatch`).
+     *
+     * Tests omit this opt to exercise the legacy WS-frame path.
      */
-    readonly buildScopedConfig: (item: {
-        readonly stackItemId?: string;
-        readonly contractHash?: string;
-        readonly actionSpec?: ActionSpec;
-    }) => WireConfig;
+    readonly onDispatchEnvelope?: (envelope: ActionEnvelope) => void;
 }
 /**
- * Build the unscoped root `WireConfig` + its scope-factory closure.
+ * Build the per-render `WireConfig` for the iframe runtime.
  * Bootstraps the renderer's outbound emission + inbound subscription
- * seams.
+ * seams. Returns a `WireConfig` keyed by the bootstrap's `renderId`;
+ * the active render's `actionSpec` is resolved through the
+ * {@link BuildRootWireConfigOptions.getCurrentRender} thunk on every
+ * dispatch so props_update patches don't require rebuilding the
+ * config.
  *
- * Returns a {@link RootWireConfigBundle} rather than a bare
- * `WireConfig` — the scope factory is paired with the root so
- * `dispatchByItem` internals don't leak onto the public WireConfig
- * shape. `scopeWireConfig` (the exported standalone) is the low-level
- * primitive; `buildScopedConfig` is the pre-bound convenience.
- */
-export declare function buildRootWireConfig(opts: BuildRootWireConfigOptions): RootWireConfigBundle;
-/**
- * Produce a per-item scoped `WireConfig`. The only override is
- * `dispatch` — every other seam (subscribe) stays shared.
+ * Post-render-identity-collapse (2026-05-27): no per-item scope
+ * factory — each iframe mounts exactly one render. The earlier
+ * `RootWireConfigBundle` / `scopeWireConfig` / `buildScopedConfig`
+ * indirection collapsed to a single `WireConfig`.
  */
-export declare function scopeWireConfig(root: WireConfig, item: {
-    stackItemId?: string;
-    contractHash?: string;
-    actionSpec?: ActionSpec;
-}, internals: {
-    getStack: () => readonly SessionStackEntry[];
-    dispatchByItem: (actionName: string, data: unknown, ctx: {
-        stackItemId?: string;
-        stackIndex: number;
-        tool?: string;
-        actionSpec?: ActionSpec;
-    }) => void;
-}): WireConfig;
+export declare function buildRootWireConfig(opts: BuildRootWireConfigOptions): WireConfig;

package/dist/wire-config.js

@@ -36,7 +36,7 @@ const RESERVED_CHANNEL_REPLAY_MAX = 256;
  *   `subscribe()` → first `ack` → render stack items → mount
  *   `mountProvisional` → it then calls `streamBus.subscribe('_ggui:
  *   preview', …)`. Server-side replay frames for `_ggui:preview` (the
- *   provisional A2UI preamble fired during the agent's `ggui_push`
+ *   provisional A2UI preamble fired during the agent's `ggui_render`
  *   BEFORE the user's browser navigated to the viewer) arrive over the
  *   WS in the window between ack-resolve and the provisional mount —
  *   they hit `emit()` before any listener has subscribed. Without a
@@ -123,15 +123,18 @@ export class StreamBus {
     }
 }
 /**
- * Build the unscoped root `WireConfig` + its scope-factory closure.
+ * Build the per-render `WireConfig` for the iframe runtime.
  * Bootstraps the renderer's outbound emission + inbound subscription
- * seams.
+ * seams. Returns a `WireConfig` keyed by the bootstrap's `renderId`;
+ * the active render's `actionSpec` is resolved through the
+ * {@link BuildRootWireConfigOptions.getCurrentRender} thunk on every
+ * dispatch so props_update patches don't require rebuilding the
+ * config.
  *
- * Returns a {@link RootWireConfigBundle} rather than a bare
- * `WireConfig` — the scope factory is paired with the root so
- * `dispatchByItem` internals don't leak onto the public WireConfig
- * shape. `scopeWireConfig` (the exported standalone) is the low-level
- * primitive; `buildScopedConfig` is the pre-bound convenience.
+ * Post-render-identity-collapse (2026-05-27): no per-item scope
+ * factory — each iframe mounts exactly one render. The earlier
+ * `RootWireConfigBundle` / `scopeWireConfig` / `buildScopedConfig`
+ * indirection collapsed to a single `WireConfig`.
  */
 export function buildRootWireConfig(opts) {
     const clientSeqBox = { current: 0 };
@@ -162,67 +165,63 @@ export function buildRootWireConfig(opts) {
         }
         emitProtocolError(fromClientContractViolation(err));
     }
-    function dispatchByItem(actionName, data, ctx) {
-        const envelope = buildActionEnvelope({
-            sessionId: opts.sessionId,
-            type: 'data:submit',
-            payload: {
-                action: actionName,
-                data: data,
-                ...(ctx.tool ? { tool: ctx.tool } : {}),
-            },
-            stackIndex: ctx.stackIndex,
-            ...(ctx.stackItemId ? { stackItemId: ctx.stackItemId } : {}),
-            clientSeq: nextSeq(),
-        });
-        const result = validateOutboundActionEnvelope(ctx.actionSpec, envelope);
-        if (!result.valid) {
-            surfaceViolation(new ClientContractViolationError('outbound-action', result.violations));
-            return;
-        }
-        sendActionEnvelope(opts.manager, envelope);
-        // Observability: a wired-tool dispatch is a `data:submit` whose
-        // resolved action has a `tool` binding. Plain agent-routed actions
-        // (no `tool` on the actionSpec) fire a `dispatch` activity row in
-        // the console via the session-side ring buffer; only wired tools
-        // get this observability event. The server separately emits the
-        // operational telemetry variant on its TelemetrySink.
-        if (ctx.tool !== undefined) {
-            emitObserve({
-                kind: 'wired-tool-invoked',
-                toolName: ctx.tool,
-                actionName,
-                dispatchedAt: new Date().toISOString(),
-            });
-        }
-    }
-    const root = {
+    return {
         app: { appId: opts.appId, appName: opts.appId },
-        session: { sessionId: opts.sessionId, isConnected: true },
+        render: { renderId: opts.renderId, isConnected: true },
         auth: { isAuthenticated: false },
         dispatch: (actionName, data) => {
-            // Unscoped fallback — resolve from top of stack. Matches
-            // `GguiSession.wireConfig.dispatch` (the non-scoped path).
-            const stack = opts.getStack();
-            const activeItem = stack[stack.length - 1];
-            const activeIndex = stack.length > 0 ? stack.length - 1 : 0;
-            // McpApps + system items never carry `actionSpec` (their wire is
-            // owned by their own host) — narrow before reading.
-            const activeActionSpec = activeItem !== undefined &&
-                activeItem.type !== 'mcpApps' &&
-                activeItem.type !== 'system'
-                ? activeItem.actionSpec
+            // Resolve the active render's actionSpec on every dispatch.
+            // Per-render lifecycle: props_update patches replace the render
+            // reference; reading through the thunk keeps the tool binding
+            // + outbound validator coherent without rebuilding the config.
+            const currentRender = opts.getCurrentRender();
+            const activeActionSpec = currentRender !== null &&
+                currentRender.type !== 'mcpApps' &&
+                currentRender.type !== 'system'
+                ? currentRender.actionSpec
                 : undefined;
             const entry = activeActionSpec?.[actionName];
             const tool = entry?.nextStep;
-            dispatchByItem(actionName, data, {
-                stackItemId: activeItem?.id,
-                stackIndex: activeIndex,
-                ...(tool !== undefined ? { tool } : {}),
-                ...(activeActionSpec !== undefined
-                    ? { actionSpec: activeActionSpec }
-                    : {}),
+            const envelope = buildActionEnvelope({
+                renderId: opts.renderId,
+                type: 'data:submit',
+                payload: {
+                    action: actionName,
+                    data: data,
+                    ...(tool ? { tool } : {}),
+                },
+                clientSeq: nextSeq(),
             });
+            const result = validateOutboundActionEnvelope(activeActionSpec, envelope);
+            if (!result.valid) {
+                surfaceViolation(new ClientContractViolationError('outbound-action', result.violations));
+                return;
+            }
+            if (opts.onDispatchEnvelope !== undefined) {
+                // Spec-canonical path — the iframe-runtime's LIVE-mode boot
+                // wires this to `routeDispatch`, which postMessages
+                // `tools/call:ggui_runtime_submit_action` through the MCP-Apps
+                // host relay. The default WS-frame send below is retained for
+                // tests + legacy callers that don't relay tools/call.
+                opts.onDispatchEnvelope(envelope);
+            }
+            else {
+                sendActionEnvelope(opts.manager, envelope);
+            }
+            // Observability: a wired-tool dispatch is a `data:submit` whose
+            // resolved action has a `tool` binding. Plain agent-routed actions
+            // (no `tool` on the actionSpec) fire a `dispatch` activity row in
+            // the console via the session-side ring buffer; only wired tools
+            // get this observability event. The server separately emits the
+            // operational telemetry variant on its TelemetrySink.
+            if (tool !== undefined) {
+                emitObserve({
+                    kind: 'wired-tool-invoked',
+                    toolName: tool,
+                    actionName,
+                    dispatchedAt: new Date().toISOString(),
+                });
+            }
         },
         subscribe: (channelName, handler) => {
             return opts.streamBus.subscribe(channelName, (env) => {
@@ -244,37 +243,6 @@ export function buildRootWireConfig(opts) {
         // `actionSpec[*].nextStep` (event metadata) and
         // `streamSpec[*].source.tool` (channel data source).
     };
-    // `WireConfig` carries no `scope(item)` method.
-    // Callers that want a per-item config use `buildScopedConfig(item)`
-    // on the returned bundle, which bakes in the `dispatchByItem` +
-    // `getStack` internals so they never leak onto the public
-    // WireConfig shape.
-    const buildScopedConfig = (item) => scopeWireConfig(root, item, {
-        getStack: opts.getStack,
-        dispatchByItem,
-    });
-    return { config: root, buildScopedConfig };
-}
-/**
- * Produce a per-item scoped `WireConfig`. The only override is
- * `dispatch` — every other seam (subscribe) stays shared.
- */
-export function scopeWireConfig(root, item, internals) {
-    return {
-        ...root,
-        dispatch: (actionName, data) => {
-            const entry = item.actionSpec?.[actionName];
-            const tool = entry?.nextStep;
-            const stack = internals.getStack();
-            const idx = stack.findIndex((s) => s.id === item.stackItemId);
-            internals.dispatchByItem(actionName, data, {
-                ...(item.stackItemId !== undefined ? { stackItemId: item.stackItemId } : {}),
-                stackIndex: idx >= 0 ? idx : 0,
-                ...(tool !== undefined ? { tool } : {}),
-                ...(item.actionSpec !== undefined ? { actionSpec: item.actionSpec } : {}),
-            });
-        },
-    };
 }
 // =============================================================================
 // Outbound envelope emission

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ggui-ai/iframe-runtime",
-  "version": "0.1.0-rc.3",
-  "description": "The iframe-local ggui runtime: 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 session stack. Bundles React, ReactDOM, and the ggui design system so generated component code has a single seam to read from.",
+  "version": "0.2.0-alpha.3",
+  "description": "The iframe-local ggui runtime: a self-contained ESM bundle that boots inside an MCP Apps host iframe, runs the protocol-version handshake, opens the live-channel WebSocket, and mounts the rendered UI. Bundles React, ReactDOM, and the ggui design system so generated component code has a single seam to read from.",
   "keywords": [
     "ggui",
     "mcp",
@@ -34,15 +34,16 @@
     }
   },
   "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.2",
     "qrcode-generator": "^2.0.4",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@ggui-ai/channel-client": "0.1.0-rc.3",
-    "@ggui-ai/gadgets": "0.1.0-rc.3",
-    "@ggui-ai/design": "0.1.0-rc.3",
-    "@ggui-ai/preview-a2ui": "0.1.0-rc.3",
-    "@ggui-ai/protocol": "0.1.0-rc.3",
-    "@ggui-ai/wire": "0.1.0-rc.3"
+    "@ggui-ai/live-channel": "0.2.0-alpha.3",
+    "@ggui-ai/gadgets": "0.2.0-alpha.3",
+    "@ggui-ai/design": "0.2.0-alpha.3",
+    "@ggui-ai/preview-a2ui": "0.2.0-alpha.3",
+    "@ggui-ai/protocol": "0.2.0-alpha.3",
+    "@ggui-ai/wire": "0.2.0-alpha.3"
   },
   "devDependencies": {
     "@testing-library/react": "^16.0.0",

package/dist/bootstrap.d.ts

@@ -1,72 +0,0 @@
-import type { BootstrapParseResult } from './types.js';
-/**
- * Shared validator core. Accepts an unwrapped bootstrap object (NOT
- * the full `_meta.ggui.bootstrap` envelope — the caller has already
- * stripped envelopes down to this layer).
- *
- * Validates the three-mode discriminator + the optional fields per
- * the {@link GguiBootstrapMeta} contract. Returns a discriminated
- * {@link BootstrapParseResult} the caller surfaces verbatim.
- *
- * Invariants enforced here (see module docblock for the wire contract):
- *   - `runtimeUrl` MUST be a non-empty string. All three modes need
- *     it because the shell dynamic-script-loads the runtime bundle
- *     from this URL.
- *   - `sessionId` + `appId` MUST be non-empty strings.
- *   - At least one of `{wsUrl-with-token, codeUrl, kind}` MUST be
- *     present as a non-empty string. Half-live (wsUrl without token)
- *     is MALFORMED.
- *   - `expiresAt`, when present + relevant (live mode), MUST parse
- *     to a future timestamp.
- */
-export declare function validateBootstrapMeta(raw: unknown): BootstrapParseResult;
-/**
- * Parse a bootstrap from a `ui/initialize` postMessage response. The
- * argument is the JSON-RPC `result` field — typically
- * `{ toolOutput: { _meta: { ggui: { bootstrap: {...} } }, structuredContent: ... } }`.
- *
- * Used by the runtime's legacy `bootProduction` path (live-mode WS
- * subscription). Spec-canonical for first-party `<McpAppIframe>`
- * Reading-B hosts (Studio, Portal, console).
- */
-export declare function parseBootstrapFromUiInitialize(uiInitializeResult: unknown): BootstrapParseResult;
-/**
- * Back-compat alias for {@link parseBootstrapFromUiInitialize}.
- *
- * `parseBootstrap` was the original name when the iframe-runtime
- * accepted only the ui/initialize envelope. The parser was later
- * generalized to three envelope shapes (ui/initialize,
- * `__GGUI_BOOTSTRAP__` global, postMessage tool-result), each with its
- * own thin extractor; the shared {@link validateBootstrapMeta} core
- * does the per-envelope shape validation. The original function name
- * is kept exported so downstream consumers (`@ggui-ai/react`, runtime
- * call sites) don't need a sweep — the name still resolves to the
- * same behavior.
- */
-export declare const parseBootstrap: typeof parseBootstrapFromUiInitialize;
-/**
- * Parse a bootstrap from `globalThis.__GGUI_BOOTSTRAP__` — the
- * synchronous self-contained shell delivery channel. Returns
- * `MALFORMED_BOOTSTRAP` when the global is absent OR not an object;
- * the caller falls through to a postMessage path on either signal.
- *
- * Used by the runtime's autostart resolver as the highest-priority
- * boot source: per-session shells (`/r/<shortCode>`,
- * `ui://ggui/session/<sessionId>`) populate this synchronously
- * BEFORE the runtime bundle's `<script type="module">` evaluates,
- * so the runtime can mount without any postMessage round-trip.
- */
-export declare function parseBootstrapFromGlobal(): BootstrapParseResult;
-/**
- * Parse a bootstrap from a `ui/notifications/tool-result` postMessage
- * params payload. Looks at BOTH the spec-canonical location
- * (`params._meta.ggui.bootstrap`) and the Reading-B `<McpAppIframe>`
- * convention (`params.toolOutput._meta.ggui.bootstrap`) — Claude
- * Desktop / claude.ai Connector use the first; first-party hosts the
- * second.
- *
- * Used by the runtime's autostart resolver as the second / third
- * boot source (drained from the pre-runtime-load buffer or caught by
- * the live message listener).
- */
-export declare function parseBootstrapFromToolResult(params: unknown): BootstrapParseResult;