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

package/dist/observability.d.ts

@@ -7,7 +7,7 @@
  *     protocol violation or transport error).
  *   - `ObservabilityEvent` fires on HAPPY PATHS + failures alike
  *     (telemetry + inspection signal the host can display in a
- *     SessionInspector-style view).
+ *     RenderInspector-style view).
  *
  * The host wrapper passes events through to `onObserve` opaquely.
  *
@@ -30,7 +30,7 @@
 export type ObservabilityEvent = WiredToolInvokedEvent | ContractErrorEmittedEvent | SchemaVersionMismatchEvent | SubscribeFailedEvent | AuthRequiredEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | UnknownObservabilityEvent;
 /**
  * Fired when a wired action successfully dispatched to a registered
- * MCP tool. Hosts surface this as a dispatch row in SessionInspector.
+ * MCP tool. Hosts surface this as a dispatch row in RenderInspector.
  * Emitted by the server-side router (session-channel.ts) via
  * postMessage relay through the renderer.
  *
@@ -137,14 +137,14 @@ export interface AuthRequiredEvent {
 /**
  * Fired by the channel-transport router when it picks a transport
  * for a `streamSpec[ch].source.tool` channel. Hosts can inspect the
- * WS-vs-poll decision per channel in the SessionInspector activity
+ * WS-vs-poll decision per channel in the RenderInspector activity
  * feed.
  *
  * @public
  */
 export interface ChannelTransportPickedEvent {
     readonly kind: 'channel-transport-picked';
-    readonly stackItemId: string;
+    readonly renderId: string;
     readonly channelName: string;
     readonly transport: 'ws' | 'poll';
 }
@@ -159,7 +159,7 @@ export interface ChannelTransportPickedEvent {
  */
 export interface ChannelTransportFallbackEvent {
     readonly kind: 'channel-transport-fallback';
-    readonly stackItemId: string;
+    readonly renderId: string;
     readonly channelName: string;
     readonly reason: 'ws-disconnect' | 'channel-not-local';
 }
@@ -171,7 +171,7 @@ export interface ChannelTransportFallbackEvent {
  */
 export interface ChannelTransportResubscribedEvent {
     readonly kind: 'channel-transport-resubscribed';
-    readonly stackItemId: string;
+    readonly renderId: string;
     readonly channelName: string;
 }
 /**

package/dist/protocol-error.d.ts

@@ -33,7 +33,7 @@ import { ClientContractViolationError } from '@ggui-ai/wire';
  * Consolidates three sources:
  *
  *   1. **Parse-time failures** — every member of
- *      `BootstrapParseFailureReason` (`MISSING_TOOL_OUTPUT` /
+ *      `McpAppAiGguiMetaParseFailureReason` (`MISSING_TOOL_OUTPUT` /
  *      `MISSING_META_GGUI_BOOTSTRAP` / `MALFORMED_BOOTSTRAP` /
  *      `EXPIRED_BOOTSTRAP`). `MISSING_META_GGUI_BOOTSTRAP` and
  *      `BOOTSTRAP_META_MISSING` are synonyms — the latter is the
@@ -43,15 +43,15 @@ import { ClientContractViolationError } from '@ggui-ai/wire';
  *      / `WS_HANDSHAKE_FAILED`. Matches `RendererBootFailureReason`.
  *
  *   3. **Transport-observable failures** — `BUNDLE_FETCH_FAILED` /
- *      `CSP_VIOLATION` / `SESSION_NOT_FOUND` / `AUTH_REJECTED`. These
+ *      `CSP_VIOLATION` / `RENDER_NOT_FOUND` / `AUTH_REJECTED`. These
  *      fire before the renderer parse path runs, so they're authored
- *      here rather than inside `BootstrapParseFailureReason`.
+ *      here rather than inside `McpAppAiGguiMetaParseFailureReason`.
  *
  * `(string & {})` tail keeps the union extensibly-closed — new wire
  * codes can land without a client bump, while IDE autocomplete
  * surfaces the canonical set.
  */
-export type BootstrapFailureReason = 'MISSING_TOOL_OUTPUT' | 'MISSING_META_GGUI_BOOTSTRAP' | 'BOOTSTRAP_META_MISSING' | 'MALFORMED_BOOTSTRAP' | 'EXPIRED_BOOTSTRAP' | 'UI_INITIALIZE_FAILED' | 'WS_HANDSHAKE_FAILED' | 'UPGRADE_REQUIRED' | 'BUNDLE_FETCH_FAILED' | 'CSP_VIOLATION' | 'SESSION_NOT_FOUND' | 'AUTH_REJECTED' | (string & {});
+export type BootstrapFailureReason = 'MISSING_TOOL_OUTPUT' | 'MISSING_META_GGUI_BOOTSTRAP' | 'BOOTSTRAP_META_MISSING' | 'MALFORMED_BOOTSTRAP' | 'EXPIRED_BOOTSTRAP' | 'UI_INITIALIZE_FAILED' | 'WS_HANDSHAKE_FAILED' | 'UPGRADE_REQUIRED' | 'BUNDLE_FETCH_FAILED' | 'CSP_VIOLATION' | 'RENDER_NOT_FOUND' | 'AUTH_REJECTED' | (string & {});
 /**
  * Every error the renderer surfaces outward flows through this union.
  *
@@ -61,7 +61,7 @@ export type BootstrapFailureReason = 'MISSING_TOOL_OUTPUT' | 'MISSING_META_GGUI_
  *                    Includes `retryable` so hosts can decide to reconnect
  *                    vs. give up.
  *   - `auth`       — session / token rejection pre-handshake.
- *                    `SESSION_NOT_FOUND` / `TOKEN_EXPIRED` /
+ *                    `RENDER_NOT_FOUND` / `TOKEN_EXPIRED` /
  *                    `AUTH_REJECTED` — all terminal; hosts typically
  *                    escalate to a login flow.
  *   - `protocol`   — envelope / session-mismatch failures post-handshake.
@@ -87,7 +87,7 @@ export type ProtocolError = {
     readonly message?: string;
 } | {
     readonly kind: 'auth';
-    readonly code: 'SESSION_NOT_FOUND' | 'TOKEN_EXPIRED' | 'AUTH_REJECTED';
+    readonly code: 'RENDER_NOT_FOUND' | 'TOKEN_EXPIRED' | 'AUTH_REJECTED';
     readonly message?: string;
 } | {
     readonly kind: 'protocol';
@@ -196,4 +196,4 @@ export declare function fromTransportFailure(code: 'DISCONNECTED' | 'TIMEOUT', r
  * Build a `ProtocolError` of kind 'auth' — session / token rejection
  * pre-handshake.
  */
-export declare function fromAuthFailure(code: 'SESSION_NOT_FOUND' | 'TOKEN_EXPIRED' | 'AUTH_REJECTED', message?: string): ProtocolError;
+export declare function fromAuthFailure(code: 'RENDER_NOT_FOUND' | 'TOKEN_EXPIRED' | 'AUTH_REJECTED', message?: string): ProtocolError;

package/dist/provisional-renderer.d.ts

@@ -25,7 +25,7 @@
  *     loading fallback until A2UI's `root` fragment arrives; then
  *     the adjacency tree paints.
  *   - `suspend()` hides the surface (used when the authoritative
- *     render takes over — the stack-item dispatcher in Commit 4
+ *     render takes over — the render dispatcher in Commit 4
  *     toggles this on ReactComponentRenderer mount).
  *   - `resume()` re-shows. Envelopes keep accumulating in state
  *     while suspended, matching host-SDK behavior.

package/dist/provisional-renderer.js

@@ -25,7 +25,7 @@
  *     loading fallback until A2UI's `root` fragment arrives; then
  *     the adjacency tree paints.
  *   - `suspend()` hides the surface (used when the authoritative
- *     render takes over — the stack-item dispatcher in Commit 4
+ *     render takes over — the render dispatcher in Commit 4
  *     toggles this on ReactComponentRenderer mount).
  *   - `resume()` re-shows. Envelopes keep accumulating in state
  *     while suspended, matching host-SDK behavior.

package/dist/react-renderer.d.ts

@@ -10,12 +10,12 @@
  *
  * Lifecycle seams:
  *
- *   - `mount(container, stackItem)` — replace the container's
+ *   - `mount(container, render)` — replace the container's
  *     children with a React root rendering the compiled component.
  *     Returns a `ReactRootMount` handle; callers use `update()` to
  *     swap props without re-evaluating the module, `unmount()` to
  *     tear down.
- *   - `update(stackItem)` — swap props (and/or componentCode). When
+ *   - `update(render)` — swap props (and/or componentCode). When
  *     componentCode changes, re-evaluates; when only props change,
  *     re-renders the existing component tree with new props.
  *   - `unmount()` — `root.unmount()` + detach observability.
@@ -23,8 +23,8 @@
  * Error handling — ErrorBoundary with auto-retry (AUTO_RETRY_LIMIT +
  * AUTO_RETRY_DELAY) matches the `ReactComponentRenderer` contract.
  * On terminal error, the callback `onRequestRepair` fires; the
- * stack-item dispatcher wires this to the `ggui:request-repair`
- * live-channel envelope `StackItemRenderer` dispatches.
+ * render dispatcher (`render-item.ts`) wires this to the
+ * `ggui:request-repair` live-channel envelope it dispatches.
  *
  * No JSX in this file — the mount-root code uses
  * `React.createElement` + `React.Fragment` directly so the renderer's
@@ -33,13 +33,12 @@
 import React, { type ReactNode } from 'react';
 export interface ReactRootMountOptions {
     /**
-     * Stack item whose componentCode + props drive the mount. Only
+     * Render whose componentCode + props drive the mount. Only
      * `componentCode` + `props` are read here; the caller is
      * responsible for wrapping this with a `<GguiWireProvider>` at the
-     * higher-level dispatcher (see `stack-item-renderer.ts` in Commit
-     * 4).
+     * higher-level dispatcher (see `render-item.ts`).
      */
-    readonly stackItem: {
+    readonly render: {
         readonly id?: string;
         readonly componentCode: string;
         readonly props?: Record<string, unknown>;
@@ -56,9 +55,9 @@ export interface ReactRootMountOptions {
     readonly onRequestRepair?: (error: Error) => void;
     /**
      * Children injected BETWEEN the mount DOM (scope + CSS) and the
-     * evaluated component element. The caller's stack-item renderer
+     * evaluated component element. The caller's render dispatcher
      * uses this to wrap the eval'd component in `<GguiWireProvider>`
-     * so wire hooks resolve per-item contracts.
+     * so wire hooks resolve per-render contracts.
      *
      * When `undefined`, the evaluated component renders directly.
      */
@@ -87,7 +86,7 @@ export interface ReactRootMount {
     readonly currentCode: string | null;
 }
 /**
- * Mount a React root inside `container` and render `stackItem`'s
+ * Mount a React root inside `container` and render `render`'s
  * compiled componentCode. The container is fully owned after this
  * call (existing children are replaced).
  */

package/dist/react-renderer.js

@@ -10,12 +10,12 @@
  *
  * Lifecycle seams:
  *
- *   - `mount(container, stackItem)` — replace the container's
+ *   - `mount(container, render)` — replace the container's
  *     children with a React root rendering the compiled component.
  *     Returns a `ReactRootMount` handle; callers use `update()` to
  *     swap props without re-evaluating the module, `unmount()` to
  *     tear down.
- *   - `update(stackItem)` — swap props (and/or componentCode). When
+ *   - `update(render)` — swap props (and/or componentCode). When
  *     componentCode changes, re-evaluates; when only props change,
  *     re-renders the existing component tree with new props.
  *   - `unmount()` — `root.unmount()` + detach observability.
@@ -23,8 +23,8 @@
  * Error handling — ErrorBoundary with auto-retry (AUTO_RETRY_LIMIT +
  * AUTO_RETRY_DELAY) matches the `ReactComponentRenderer` contract.
  * On terminal error, the callback `onRequestRepair` fires; the
- * stack-item dispatcher wires this to the `ggui:request-repair`
- * live-channel envelope `StackItemRenderer` dispatches.
+ * render dispatcher (`render-item.ts`) wires this to the
+ * `ggui:request-repair` live-channel envelope it dispatches.
  *
  * No JSX in this file — the mount-root code uses
  * `React.createElement` + `React.Fragment` directly so the renderer's
@@ -183,7 +183,7 @@ class RcrErrorBoundary extends Component {
     }
 }
 /**
- * Mount a React root inside `container` and render `stackItem`'s
+ * Mount a React root inside `container` and render `render`'s
  * compiled componentCode. The container is fully owned after this
  * call (existing children are replaced).
  */
@@ -257,7 +257,7 @@ export async function mountReactRoot(container, opts) {
         }
         const componentElement = currentComponent === null
             ? null
-            : createElement(currentComponent, opts.stackItem.props ?? {});
+            : createElement(currentComponent, opts.render.props ?? {});
         const wrapped = opts.renderWrapper && componentElement !== null
             ? opts.renderWrapper(componentElement)
             : componentElement;
@@ -271,7 +271,7 @@ export async function mountReactRoot(container, opts) {
         }, createElement(Fragment, null, wrapped))));
     }
     async function initialEvaluate() {
-        const code = currentOpts.stackItem.componentCode ?? '';
+        const code = currentOpts.render.componentCode ?? '';
         if (code.trim().length === 0) {
             currentComponent = null;
             currentCode = null;
@@ -305,7 +305,7 @@ export async function mountReactRoot(container, opts) {
         async update(next) {
             const prevCode = currentCode;
             currentOpts = next;
-            const nextCode = next.stackItem.componentCode ?? '';
+            const nextCode = next.render.componentCode ?? '';
             // Props-only change — skip module eval. Re-render with new props.
             if (nextCode === prevCode && currentComponent !== null) {
                 renderTree(currentOpts);

package/dist/registry-subscribe.d.ts

@@ -1,15 +1,15 @@
 import type { AckPayload, ContractErrorPayload } from '@ggui-ai/protocol';
 import type { ConnectionStatus } from '@ggui-ai/protocol/transport/websocket';
-import type { GguiBootstrapMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
-import type { ChannelRegistry, WsTransportHandle } from '@ggui-ai/channel-client';
+import type { McpAppAiGguiRenderMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
+import type { ChannelRegistry, RegistryPollingOptions, WsTransportHandle } from '@ggui-ai/live-channel';
 import { type ProtocolErrorEmitter } from './protocol-error.js';
 import type { ObservabilityEmitter } from './observability.js';
 /**
  * Result of a successful handshake — the live typed transport handle
  * plus the resolved `AckPayload` from the first ack frame. The caller
- * attaches `handle` to the triad's outbound send surface (via the
- * BufferedManagerShim flush) and applies `ack.stack` to the stack
- * model.
+ * attaches `handle` to the renderer's outbound send surface (via the
+ * BufferedManagerShim flush) and applies `ack.render` to the mounted
+ * render slot.
  */
 export interface RegistrySubscribeHandle {
     readonly handle: WsTransportHandle;
@@ -20,7 +20,14 @@ export interface RegistrySubscribeHandle {
  * concrete implementations; tests pass mocks via the `connectFn` seam.
  */
 export interface ConnectViaRegistryOptions {
-    readonly bootstrap: GguiBootstrapMeta;
+    /**
+     * Render slice (`McpAppAiGguiRenderMeta`) — the live-channel
+     * credentials this subscribe path actually needs: `renderId`,
+     * `appId`, `wsUrl`, `wsToken`. The rest of the slice (codeUrl /
+     * propsJson / contextSlots / etc.) is load-bearing only for the
+     * renderer / mount layer.
+     */
+    readonly meta: McpAppAiGguiRenderMeta;
     readonly registry: ChannelRegistry;
     /**
      * Fires on every transport-status transition mapped onto the
@@ -61,17 +68,28 @@ export interface ConnectViaRegistryOptions {
      * Optional post-handshake ack callback. Fires for every ack frame
      * AFTER the initial handshake settled — i.e. on every reconnect's
      * subscribe ack. The runtime uses this to reapply the server's
-     * authoritative `stack` snapshot so a push or update that landed
+     * authoritative `render` snapshot so a render or update that landed
      * during a WS dropout window flows back into the iframe on
      * reconnect.
      *
-     * Idempotent at the runtime layer: `stackModel.setAll(ack.stack)`
-     * is a snapshot replace. Channels re-subscribed by
+     * Idempotent at the runtime layer: `applyRender(ack.render)` patches
+     * in place. Channels re-subscribed by
      * `ChannelTransportRouter.onWsStatusChange('connected')` upstream
      * of this callback, so the per-channel transport state is already
      * coherent by the time the resubscribe-ack arrives.
      */
     readonly onResubscribeAck?: (ack: AckPayload) => void;
+    /**
+     * Registry-level polling descriptor (R6). When supplied, the live-
+     * channel's `FailoverHandle` uses this as its polling fallback when
+     * `WSTransport` reaches `'failed'`. Absent → no polling fallback
+     * (WS-only mode; once WS is exhausted, handlers stay inert).
+     *
+     * Composed at the runtime layer from `meta.pollingUrl` +
+     * `meta.lastSequence` (cursor seed) — the live-channel itself is
+     * URL- and shape-agnostic.
+     */
+    readonly polling?: RegistryPollingOptions;
 }
 /**
  * Open the WS via the registry, send subscribe (composed by the

package/dist/registry-subscribe.js

@@ -1,21 +1,21 @@
 /**
  * Registry-driven subscribe orchestration — owns the renderer's
- * "I have a parsed bootstrap, now drive the live-channel handshake to
- * first ack" flow on top of `ChannelRegistry.bind()`.
+ * "I have a parsed render-meta, now drive the live-channel handshake
+ * to first ack" flow on top of `ChannelRegistry.bind()`.
  *
  * Replaces the pre-B3b `subscribe()` helper + the `RendererWebSocketManager`
  * lifecycle class. The two retired modules paired a hand-rolled WS
  * manager with a separate handshake helper; B3b unifies both behind
- * the `@ggui-ai/channel-client` library so every WS frame type (push,
+ * the `@ggui-ai/live-channel` library so every WS frame type (push,
  * data, props_update, drain_ack, channel_payload, channel_error,
  * system, feedback) flows through one registry-owned transport.
  *
  * Composition:
  *
  *   1. Caller-supplied `ChannelRegistry` (populated by `runtime.ts`'s
- *      triad-wiring `setup()` with every handler the iframe routes).
- *   2. Compose the WS URL with the bootstrap token threaded as a
- *      `?bootstrap=<encoded>` query string (mirrors the pre-B3b
+ *      renderer-hooks `setup()` with every handler the iframe routes).
+ *   2. Compose the WS URL with the WS auth token threaded as a
+ *      `?wsToken=<encoded>` query string (mirrors the pre-B3b
  *      `composeWsUrl` shape so server-side upgrade-path auth keeps
  *      working).
  *   3. Register `ack` + `error` handlers on the registry BEFORE bind
@@ -23,7 +23,9 @@
  *      handshake-resolver closure.
  *   4. Call `registry.bind({bootstrap, onStatusChange})` and capture
  *      the returned typed `WsTransportHandle` (narrow on
- *      `handle.kind === 'ws'`).
+ *      `handle.kind === 'ws'`). The live-channel's `bootstrap`
+ *      argument is its own internal name; the field on the wire is
+ *      `wsToken`.
  *
  * The handshake resolves on the first `ack` (with the symmetric
  * `CLIENT_SUPPORTED_VERSIONS` check) or rejects on:
@@ -43,15 +45,15 @@ import { CLIENT_SUPPORTED_VERSIONS, UPGRADE_REQUIRED } from '@ggui-ai/protocol/v
 import { UpgradeRequiredError } from '@ggui-ai/protocol/errors/version-mismatch';
 import { fromAuthFailure, fromTransportFailure, fromUpgradeRequired, } from './protocol-error.js';
 /**
- * Compose the WebSocket URL with the bootstrap token threaded as a
+ * Compose the WebSocket URL with the WS auth token threaded as a
  * query parameter. Servers that authenticate the upgrade path read
  * the token from here; the same value also rides inside the subscribe
  * payload so server-side handlers that consume credentials on the
  * subscribe frame see it too.
  */
-function composeWsUrl(base, bootstrap) {
+function composeWsUrl(base, wsToken) {
     const sep = base.indexOf('?') >= 0 ? '&' : '?';
-    return `${base}${sep}bootstrap=${encodeURIComponent(bootstrap)}`;
+    return `${base}${sep}wsToken=${encodeURIComponent(wsToken)}`;
 }
 /**
  * Lift a server-emitted `{type:'error'}` frame into the appropriate
@@ -92,12 +94,12 @@ function normalizeObservedVersion(value) {
 }
 /**
  * Map a pre-ack `error` frame onto a non-UPGRADE_REQUIRED ProtocolError.
- * `SESSION_NOT_FOUND` / `AUTH_REJECTED` → `'auth'`; every other code
+ * `RENDER_NOT_FOUND` / `AUTH_REJECTED` → `'auth'`; every other code
  * → `'protocol'` with the extensibly-closed tail carrying the wire code
  * verbatim.
  */
 function classifyPreAckError(payload) {
-    if (payload.code === 'SESSION_NOT_FOUND' || payload.code === 'AUTH_REJECTED') {
+    if (payload.code === 'RENDER_NOT_FOUND' || payload.code === 'AUTH_REJECTED') {
         return fromAuthFailure(payload.code, payload.message);
     }
     if (payload.code === 'TOKEN_EXPIRED') {
@@ -130,14 +132,14 @@ export function connectViaRegistry(opts) {
         let seenOpen = false;
         const emitProtocolError = opts.onProtocolError ?? (() => { });
         const emitObserve = opts.onObserve ?? (() => { });
-        // Defense-in-depth — live mode requires both wsUrl + token. The
+        // Defense-in-depth — live mode requires both wsUrl + wsToken. The
         // caller validates this before invoking; reject early with a
         // typed transport failure if either is missing.
-        const wsUrl = opts.bootstrap.wsUrl;
-        const token = opts.bootstrap.token;
+        const wsUrl = opts.meta.wsUrl;
+        const wsToken = opts.meta.wsToken;
         if (typeof wsUrl !== 'string' || wsUrl.length === 0 ||
-            typeof token !== 'string' || token.length === 0) {
-            const err = new Error('connectViaRegistry: bootstrap missing wsUrl/token — live-mode required');
+            typeof wsToken !== 'string' || wsToken.length === 0) {
+            const err = new Error('connectViaRegistry: render-meta missing wsUrl/wsToken — live-mode required');
             emitProtocolError(fromTransportFailure('DISCONNECTED', false, err.message));
             reject(err);
             return;
@@ -265,29 +267,32 @@ export function connectViaRegistry(opts) {
                 reject(new Error('connectViaRegistry: transport went to failed state before ack'));
             }
         };
-        const composedUrl = composeWsUrl(wsUrl, token);
-        // `bind()` selects the transport (WS for wsUrl+token bootstraps;
-        // the registry's selection logic narrows on bootstrap shape) and
-        // starts it. We override `bootstrap.wsUrl` with the composed URL
-        // so the registry's WS transport gets the token-threaded variant.
+        const composedUrl = composeWsUrl(wsUrl, wsToken);
+        // `bind()` selects the transport (WS for wsUrl+wsToken sessions;
+        // the live-channel narrows on its `bootstrap` shape) and starts
+        // it. We override `session.wsUrl` with the composed URL so the
+        // registry's WS transport gets the wsToken-threaded variant. The
+        // live-channel's `bootstrap` arg is its internal name; the field
+        // on the wire is `wsToken`.
         void opts.registry
             .bind({
             bootstrap: {
                 wsUrl: composedUrl,
-                token,
-                sessionId: opts.bootstrap.sessionId,
-                appId: opts.bootstrap.appId,
+                wsToken,
+                renderId: opts.meta.renderId,
+                appId: opts.meta.appId,
             },
             onStatusChange: mappedStatusCallback,
+            ...(opts.polling !== undefined ? { polling: opts.polling } : {}),
         })
             .then((bound) => {
-            // bound is `AnyTransportHandle`. Composed URL + token means
+            // bound is `AnyTransportHandle`. Composed URL + wsToken means
             // the registry selected WSTransport — `kind === 'ws'` is the
             // structural invariant. Narrow defensively.
             if (bound.kind !== 'ws') {
                 if (!settled) {
                     settled = true;
-                    reject(new Error("connectViaRegistry: registry returned non-ws transport despite wsUrl+token bootstrap"));
+                    reject(new Error("connectViaRegistry: registry returned non-ws transport despite wsUrl+wsToken render-meta"));
                 }
                 return;
             }

package/dist/render-item.d.ts

@@ -0,0 +1,83 @@
+import type { ReactNode } from 'react';
+import type { Render } from '@ggui-ai/protocol';
+import type { RenderSeedInput } from './types.js';
+import { type WireConfig } from '@ggui-ai/wire';
+import type { StreamBus } from './wire-config.js';
+export interface RenderItemOptions {
+    /** The render to mount. */
+    readonly render: Render | RenderSeedInput;
+    /** Wire config for this render — caller pre-scopes via the runtime's
+     *  `buildScopedConfig(render)` (see
+     *  `wire-config.ts::RootWireConfigBundle`). `null` ⇒ the component
+     *  mounts without a wire provider (standalone — matches today's
+     *  DynamicComponent fallback when no GguiSession parent is present). */
+    readonly scopedWireConfig: WireConfig | null;
+    /** Shared stream bus — provisional renderer subscribes to
+     *  `_ggui:preview` for this render. */
+    readonly streamBus: StreamBus;
+    /** Render id — used by the mcp-apps iframe host for proxy URLs. */
+    readonly renderId: string;
+    /**
+     * 3rd-party gadget package names whose direct imports the rewriter
+     * must resolve to per-package shims. FALLBACK source used only when
+     * the render carries no `gadgetDescriptors` sidecar — i.e. the static
+     * seed mount ({@link RenderSeedInput}, which has no descriptors). The
+     * caller threads the bootstrap's `meta.gadgets` package names here so a
+     * generated component importing a non-STDLIB gadget on a no-WS host
+     * (claude.ai / ChatGPT) still resolves its shim on first paint. A
+     * WS-delivered full `Render` carries `gadgetDescriptors` and ignores
+     * this. STDLIB `@ggui-ai/gadgets` is always rewritten regardless.
+     */
+    readonly gadgetPackages?: readonly string[];
+    /** ggui-server base URL (for mcp-apps proxy). Empty = same-origin. */
+    readonly mcpAppsServerBaseUrl?: string;
+    /** Theme id passed to ReactComponentRenderer for scoped CSS. */
+    readonly themeId?: string;
+    /**
+     * Theme color mode. Resolves the dark variant of `themeId` when set
+     * to `'dark'`. Falls through to `'light'` if absent — matches the
+     * design registry's `getTheme(id, mode?)` default.
+     */
+    readonly themeMode?: 'light' | 'dark';
+    readonly cssOverrides?: string;
+    readonly onError?: (err: Error) => void;
+    readonly onRequestRepair?: (err: Error) => void;
+    /**
+     * Optional outer wrapper applied AROUND the GguiWireProvider — used
+     * by `bootProduction` to install the `<ContextStateHost>` provider
+     * tree. Composition order:
+     *
+     *     wrapOuter(<GguiWireProvider><userComponent/></GguiWireProvider>)
+     *
+     * `wrapOuter` returns the wrapped node; passing `undefined` is
+     * equivalent to the identity function (no extra wrapping). The
+     * self-contained boot path inlines its own ContextStateHost via the
+     * top-level `renderWrapper`; this seam exists for the WS-driven
+     * renderer path where the per-render React mount is the only mount
+     * surface.
+     */
+    readonly wrapOuter?: (mountedTree: ReactNode) => ReactNode;
+}
+/**
+ * Discriminator for WHICH renderer is currently mounted under this
+ * render handle. Transitions: 'provisional' → 'react' when
+ * componentCode lands; 'react' → 'react' on code/prop updates;
+ * 'mcpApps' is terminal for its lifetime (mcp-apps renders never
+ * become components + vice versa).
+ */
+type MountedKind = 'provisional' | 'react' | 'mcpApps' | 'system' | 'none';
+export interface RenderItemHandle {
+    /**
+     * Apply an update to the render handle. Kind changes (e.g.
+     * provisional → react when componentCode lands) tear down the old
+     * mount and stand up the replacement; same-kind updates route to
+     * the inner renderer's `update()`.
+     */
+    update(next: RenderItemOptions): Promise<void>;
+    /** Tear down the active mount + unsubscribe from the StreamBus. */
+    unmount(): void;
+    /** Current render kind. Test-only — not load-bearing. */
+    readonly kind: MountedKind;
+}
+export declare function mountRender(container: HTMLElement, opts: RenderItemOptions): Promise<RenderItemHandle>;
+export {};