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

package/dist/runtime.d.ts

@@ -1,22 +1,23 @@
-import type { DrainAckPayload } from '@ggui-ai/protocol';
+import type { DrainAckPayload, Render } from '@ggui-ai/protocol';
 import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
-import type { GguiBootstrapMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
-import { StackModel } from './stack.js';
-import type { BootstrapParseFailureReason } from './types.js';
+import type { ValidatedMcpAppAiGguiMeta, RenderSeedInput } from './types.js';
+import type { McpAppAiGguiMetaParseFailureReason } from './types.js';
+import { App } from '@modelcontextprotocol/ext-apps';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { GadgetPackageRegistry } from './globals.js';
 import { StreamBus } from './wire-config.js';
 import { type ChannelTransportRouter } from './channel-transport.js';
-import { ChannelRegistry } from '@ggui-ai/channel-client';
+import { ChannelRegistry } from '@ggui-ai/live-channel';
 import { type ConnectFn } from './registry-subscribe.js';
 import { type StatusRefs } from './status-dom.js';
 import { type RendererValidatorContext } from './validation.js';
-import { StackRenderer } from './stack-item-renderer.js';
 import type { WireConfig } from '@ggui-ai/wire';
 import { type ProtocolErrorEmitter } from './protocol-error.js';
 import { type ObservabilityEmitter } from './observability.js';
 import { type LifecycleEmitter } from './lifecycle.js';
 /**
  * Drain-ack listener registry. Module-scoped so the dispatch path can
- * register a frame-listener without threading it through the triad.
+ * register a frame-listener without threading it through the renderer.
  * Listeners are called in registration order on every inbound
  * `{type:'drain_ack'}` WS frame; a listener returning `true` claims
  * the frame (no further listeners fire). The active listener dismisses
@@ -27,24 +28,38 @@ import { type LifecycleEmitter } from './lifecycle.js';
  */
 type DrainAckListener = (payload: DrainAckPayload) => boolean | void;
 export declare function subscribeDrainAck(listener: DrainAckListener): () => void;
-interface JsonRpcResponse {
-    readonly jsonrpc?: string;
-    readonly id?: number;
-    readonly result?: unknown;
-    readonly error?: {
-        readonly code?: number;
-        readonly message?: string;
-    };
-}
+export type ConnectAppResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Assign the module-level App handle. Replaces any previous handle —
+ * production runs bootSequence exactly once per iframe lifecycle, so
+ * a replace only happens in tests that reuse the module across
+ * scenarios (and want each spec to bind its own App).
+ *
+ * @internal — production callers are the boot paths
+ *   (`bootProduction`, `bootSelfContained`); tests inject directly to
+ *   drive outbound `tools/call` through a `MockTransport`-bound App
+ *   without invoking the full boot pipeline.
+ */
+export declare function setCurrentApp(app: App): void;
+/**
+ * @internal — exported for unit tests to reset module state between
+ * scenarios.
+ */
+export declare function __resetAppForTest(): void;
 /**
  * Closed union of failure reasons surfaceable from the boot path.
- * Maps the parse reasons (`BootstrapParseFailureReason`) plus three
- * boot-orchestration reasons that don't have a canonical wire code.
- * The broader `BootstrapFailureReason` extensibly-closed union in
- * `protocol-error.ts` folds these together with transport-observable
+ * Maps the parse reasons (`McpAppAiGguiMetaParseFailureReason`) plus
+ * three boot-orchestration reasons that don't have a canonical wire
+ * code. The broader `BootstrapFailureReason` extensibly-closed union
+ * in `protocol-error.ts` folds these together with transport-observable
  * codes.
  */
-export type RendererBootFailureReason = BootstrapParseFailureReason | 'UI_INITIALIZE_FAILED' | 'WS_HANDSHAKE_FAILED' | 'UPGRADE_REQUIRED';
+export type RendererBootFailureReason = McpAppAiGguiMetaParseFailureReason | 'UI_INITIALIZE_FAILED' | 'WS_HANDSHAKE_FAILED' | 'UPGRADE_REQUIRED';
 export interface RendererBootFailedMessage {
     readonly type: 'ggui:bootstrap-failed';
     readonly reason: RendererBootFailureReason;
@@ -53,17 +68,27 @@ export interface RendererBootFailedMessage {
 export interface BootSequenceOptions {
     readonly doc: Document;
     /**
-     * Issue `ui/initialize` against the parent host and return its
-     * response. The default uses `makeJsonRpcCaller()` against
-     * `window.parent`; tests inject a mock that returns a canned
-     * `JsonRpcResponse`.
+     * Spec-canonical {@link App} instance + its {@link Transport}.
+     * `bootSequence` calls `app.connect(transport)` synchronously after
+     * the toolresult listener is installed (one-shot semantics: see
+     * App's `_assertHandlerTiming` warning — handlers registered AFTER
+     * connect risk missing the host's notification).
+     *
+     * Production passes the default (constructed against `window.parent`);
+     * tests inject `MockTransport` + a fresh App so the orchestration
+     * can be driven deterministically without `window.postMessage`.
+     *
+     * `App.connect` throws on initialize failure — bootSequence catches
+     * + surfaces the rejection's `message` on the `UI_INITIALIZE_FAILED`
+     * bootstrap envelope.
      */
-    readonly callUiInitialize: () => Promise<JsonRpcResponse>;
+    readonly app: App;
+    readonly transport: Transport;
     /**
      * Stand-in for the package's own `connectViaRegistry()`. Tests inject
      * a mock so the boot smoke spec doesn't need a mock-WebSocket layer
      * — the WS lifecycle is already covered by `registry-subscribe.test.ts`
-     * and `@ggui-ai/channel-client`'s transport tests.
+     * and `@ggui-ai/live-channel`'s transport tests.
      *
      * Default: `connectViaRegistry` from `./registry-subscribe.js`.
      */
@@ -126,10 +151,10 @@ export interface BootSequenceOptions {
      */
     readonly onLifecycle?: LifecycleEmitter;
     /**
-     * Optional triad-wiring hook. When present, the boot sequence:
-     * (1) calls `triadWiring.setup()` after bootstrap parse;
-     * (2) replaces the placeholder `renderStackInto` path with the
-     * real `StackRenderer` on ack + subsequent pushes; (3) routes
+     * Optional renderer hook. When present, the boot sequence:
+     * (1) calls `renderer.setup()` after bootstrap parse;
+     * (2) mounts the single stack entry into the renderer's slot on
+     * first ack + re-applies on every subsequent push; (3) routes
      * inbound `data` / `props_update` / `feedback` frames through the
      * supplied wire config + StreamBus.
      *
@@ -138,46 +163,46 @@ export interface BootSequenceOptions {
      * without pulling React + design + wire into the spec's import
      * graph.
      */
-    readonly triadWiring?: TriadWiringHooks;
+    readonly renderer?: RendererHooks;
     /**
-     * Optional canvas-mount hook. When the parsed bootstrap carries
-     * `canvasMode: true` AND this hook is supplied, bootSequence mounts
-     * the React-tree {@link CanvasShell} into `refs.stack` via the hook
-     * and substitutes the hook's `contentEl` as the `renderInto`
-     * passed to `triadWiring.setup()` — so the existing per-stack-item
-     * renderer writes into the canvas's content slot rather than the
-     * raw status DOM. Subsequent ack/push frames sync into the returned
-     * {@link CanvasMountHandle.navStack}.
+     * Slice meta resolved BEFORE bootSequence — the autostart layer
+     * (in `runtime.ts`'s autostart resolver) catches an inline
+     * `__GGUI_META__` global or a buffered `ui/notifications/tool-result`
+     * postMessage early, parses it, and threads the result here so
+     * bootSequence doesn't re-await the same postMessage (the autostart
+     * has already drained it).
      *
-     * Absent OR `bootstrap.canvasMode !== true` ⇒ the inline path
-     * (per-push iframe).
+     * When present, both internal resolver tiers (inline global, spec-
+     * canonical async toolresult) are skipped. The App handshake still
+     * runs — spec mandates `ui/initialize` regardless of how slice meta
+     * arrives, and `hostContext` is captured from `app.getHostContext()`.
+     */
+    readonly preResolvedMeta?: ValidatedMcpAppAiGguiMeta;
+    /**
+     * How long to wait for the spec-canonical `ui/notifications/tool-result`
+     * notification (Tier 2 of the resolver chain) before failing with
+     * the synchronous tier's parse reason. Defaults to
+     * {@link POSTMESSAGE_BOOT_TIMEOUT_MS}; tests override to a short
+     * timeout so the spec doesn't hang.
      */
-    readonly canvasMount?: CanvasMountHook;
+    readonly toolResultTimeoutMs?: number;
 }
 /**
- * Hook signature for the canvas-mode mount. Production wires this
- * through `bootProduction` (where React + canvas modules are already
- * dynamic-imported); tests pass a stub that fakes the React tree.
- */
-export type CanvasMountHook = (params: {
-    readonly mountTarget: HTMLElement;
-    readonly callbacks: import('./canvas/mount.js').CanvasMountCallbacks;
-}) => import('./canvas/mount.js').CanvasMountHandle;
-/**
- * Renderer-triad wiring hooks. The real iframe boot plumbs these via
+ * Renderer hooks. The real iframe boot plumbs these via
  * `autoBootSequence` below; tests may pass their own fakes when
  * exercising the full flow.
  */
-export interface TriadWiringHooks {
+export interface RendererHooks {
     /**
      * Called after bootstrap parse succeeds. Return value threads the
-     * root `WireConfig` + `StackRenderer` back into the runtime so the
-     * server-message handler can route frames through them.
+     * root `WireConfig` + the single-render mount surface back into the
+     * runtime so the channel handlers can route frames through them.
      *
-     * `renderInto` — a DOM element the stack renderer owns. The
-     * placeholder `<ul data-ggui-stack>` is NOT reused; the triad
-     * renderer mounts React roots per stack item into dedicated
-     * containers (see `containerFor` below).
+     * `renderInto` — a DOM element the renderer owns. Post-stack-removal
+     * (2026-05-27) the iframe-runtime mounts exactly one React tree
+     * directly into `renderInto`; the earlier per-render
+     * `<div data-ggui-stack-item-root>` containers were retired along
+     * with `StackRenderer`.
      *
      * `onObserve` — optional observability emitter threaded down to
      * the root wire config so `wired-tool-invoked` events fire on
@@ -187,37 +212,43 @@ export interface TriadWiringHooks {
      * own emitters).
      */
     setup(params: {
-        readonly bootstrap: GguiBootstrapMeta;
-        readonly stackModel: StackModel;
+        readonly meta: ValidatedMcpAppAiGguiMeta;
         readonly renderInto: HTMLElement;
         readonly statusRefs: StatusRefs;
         readonly onObserve?: ObservabilityEmitter;
-        /**
-         * Canvas-mode lifecycle sink. When wired,
-         * the triad's `data` channel handler forwards every envelope on
-         * the reserved `_ggui:lifecycle` channel to this callback so the
-         * canvas animator state machine advances. Absent ⇒ envelopes
-         * still emit on `streamBus` for declarative consumers but no
-         * animator-side dispatch fires (non-canvas iframes).
-         */
-        readonly onCanvasLifecycle?: (payload: import('@ggui-ai/protocol').CanvasLifecyclePayload) => void;
-    }): TriadHandle;
+    }): RendererHandle;
     /**
-     * Bind the real WS manager into the triad AFTER `connectFn` resolves.
+     * Bind the real WS manager into the renderer AFTER `connectFn` resolves.
      * The `setup()` step supplies a buffering shim — this hook flushes
-     * the buffer + swaps in the real send surface. Optional: a triad
+     * the buffer + swaps in the real send surface. Optional: a renderer
      * that doesn't emit outbound frames can skip.
      */
-    attachManager?(handle: TriadHandle, realManager: {
+    attachManager?(handle: RendererHandle, realManager: {
         send: (msg: WebSocketMessage) => void;
     }): void;
     /** Optional cleanup — called on boot failure paths. */
-    teardown?(handle: TriadHandle): void;
+    teardown?(handle: RendererHandle): void;
 }
-export interface TriadHandle {
+export interface RendererHandle {
     readonly rootWireConfig: WireConfig;
     readonly streamBus: StreamBus;
-    readonly stackRenderer: StackRenderer;
+    /**
+     * Apply (mount-or-update) a render to the single mount slot.
+     * First call mounts the React tree into `renderInto`; subsequent
+     * calls re-apply through {@link RenderItemHandle.update} (same kind ⇒
+     * in-place; kind transition ⇒ tear-down + remount).
+     *
+     * Shared by the `render` and `props_update` channel handlers so React
+     * updates flow through one path.
+     */
+    applyRender(render: Render | RenderSeedInput): Promise<void>;
+    /**
+     * Read the currently-mounted render. `null` until the first
+     * render frame lands. Read by the `props_update` + `data` channel
+     * handlers to validate inbound payloads against the active render's
+     * `propsSpec` / `streamSpec`.
+     */
+    getCurrentRender(): Render | RenderSeedInput | null;
     readonly validatorCtx: RendererValidatorContext;
     /**
      * Send surface for outbound frames. Wired by `setup()` to the WS
@@ -229,11 +260,10 @@ export interface TriadHandle {
     };
     /**
      * Per-channel transport router. When the bootstrap carries
-     * `streamWebSocketLocalTools` and the active
-     * stack item declares `streamSpec[ch].source.tool`, the router
-     * decides per-channel between WS subscribe + iframe-polling
-     * fallback. Updated on every push via the stackRenderer's
-     * `applyStack` hook.
+     * `streamWebSocketLocalTools` and the active render declares
+     * `streamSpec[ch].source.tool`, the router decides per-channel
+     * between WS subscribe + iframe-polling fallback. Updated on every
+     * render frame via the render handler.
      *
      * Always present — the router gracefully no-ops when no channel
      * declares `source.tool` (legacy data-frame path is unaffected).
@@ -241,7 +271,7 @@ export interface TriadHandle {
     readonly channelTransport: ChannelTransportRouter;
     /**
      * Channel-client registry holding handlers for every WS frame type
-     * the iframe routes (`push`, `data`, `props_update`, `drain_ack`,
+     * the iframe routes (`render`, `data`, `props_update`, `drain_ack`,
      * `channel_payload`, `channel_error`, `system`, `feedback`). The
      * registry-bound transport is the sole dispatch surface — frames
      * arrive directly through registered handlers, no longer through a
@@ -254,56 +284,88 @@ export interface TriadHandle {
      * `connectViaRegistry` and consumed during handshake resolution.
      */
     readonly channelRegistry: ChannelRegistry;
+    /**
+     * 3rd-party gadget-package merge promise. `installGlobalRegistry`
+     * seeds `__ggui__.gadgets` synchronously with the STDLIB namespace;
+     * operator-registered packages merge in asynchronously. A static seed
+     * mount MUST `await` this (when the bootstrap declares `gadgets`)
+     * before the first `applyRender`, so a generated component importing a
+     * 3rd-party gadget sees a fully-populated catalog on first paint
+     * (otherwise the per-package data-URL shim resolves to `undefined` and
+     * crashes). Resolves to the STDLIB-only registry when no 3rd-party
+     * packages were declared.
+     */
+    readonly composedGadgets: Promise<GadgetPackageRegistry>;
 }
 export interface BootSequenceResult {
     readonly ok: boolean;
-    readonly stack: StackModel;
+    /**
+     * The render that ended up mounted in this iframe, or `null` if
+     * the boot path bailed before the first ack landed. Post-render-
+     * identity-collapse (2026-05-27) every iframe holds at most one
+     * render; this replaces the earlier `StackModel` return that wrapped
+     * a multi-item model.
+     */
+    readonly mountedRender: Render | RenderSeedInput | null;
 }
 export declare function bootSequence(opts: BootSequenceOptions): Promise<BootSequenceResult>;
 /**
- * Self-contained bootstrap shape — alias for the protocol's unified
- * {@link GguiBootstrapMeta}. Earlier versions of this module had
- * separate `SelfContainedComponentBootstrap` /
- * `SelfContainedSystemBootstrap` narrowings; the protocol's
- * `GguiBootstrapMeta` now carries `codeUrl` / `kind` / `themeId`
- * / `themeMode` / `propsJson` directly (alongside the existing
- * live-mode `wsUrl` / `token` / `expiresAt` fields), so a single
- * shared validator ({@link validateBootstrapMeta} in `bootstrap.ts`)
- * can produce the full envelope from any of three delivery channels.
+ * Self-contained slice-meta shape — alias for {@link
+ * ValidatedMcpAppAiGguiMeta}. Post-Phase-B every delivery channel
+ * produces a single `McpAppAiGguiRenderMeta` slice.
  *
  * The export is kept so downstream consumers (`@ggui-ai/iframe-runtime`
  * barrel, dependent test suites) don't break.
  *
  * @public
  */
-export type SelfContainedBootstrap = GguiBootstrapMeta;
+export type SelfContainedMcpAppAiGguiMeta = ValidatedMcpAppAiGguiMeta;
 /**
- * Read `globalThis.__GGUI_BOOTSTRAP__` synchronously, validate against
- * the unified bootstrap shape, and return the typed bootstrap (or null
+ * Read `globalThis.__GGUI_META__` synchronously, validate against
+ * the unified slice-meta shape, and return the typed meta (or null
  * on absence / malformation).
  *
- * Thin wrapper around {@link parseBootstrapFromGlobal}; preserved for
+ * Thin wrapper around {@link parseMetaFromGlobal}; preserved for
  * back-compat (downstream consumers + tests). Returns `null` instead
- * of `BootstrapParseResult` to match the historical reader contract
- * — the autostart resolver only needs the "valid bootstrap or fall
- * through" signal.
+ * of {@link McpAppAiGguiMetaParseResult} to match the historical
+ * reader contract — the autostart resolver only needs the "valid
+ * meta or fall through" signal.
+ */
+export declare function readSelfContainedMeta(): SelfContainedMcpAppAiGguiMeta | null;
+/**
+ * Project the inline `__GGUI_META__` bootstrap into a
+ * {@link RenderSeedInput} the mount surface can paint immediately,
+ * BEFORE the authoritative wire `Render` arrives over the WS — and with
+ * no WS at all for spec-compliant MCP-Apps hosts that expose no ggui
+ * live channel (claude.ai / ChatGPT / Claude Desktop).
+ *
+ * Two static-content shapes (the autostart discriminator):
+ *   - `kind`    → a system-card seed (`type:'system'`); no fetch.
+ *   - `codeUrl` → a compiled-component seed; fetches the
+ *     content-addressable component bytes.
+ *
+ * Returns `null` when the meta carries NEITHER (a live-only meta has
+ * nothing to seed — the first WS ack mounts it). Throws when a `codeUrl`
+ * fetch fails so the caller can surface a typed boot failure. The four
+ * server-assigned ledger fields are intentionally absent — the first
+ * ack reconciles the seed to a full `Render` (no fabrication).
  */
-export declare function readSelfContainedBootstrap(): SelfContainedBootstrap | null;
+export declare function buildRenderSeedInput(meta: SelfContainedMcpAppAiGguiMeta): Promise<RenderSeedInput | null>;
 /**
- * Extract a {@link SelfContainedBootstrap} from a
+ * Extract a {@link SelfContainedMcpAppAiGguiMeta} from a
  * `ui/notifications/tool-result` JSON-RPC params payload — the
  * postMessage delivery shape MCP Apps hosts (Claude Desktop, claude.ai
  * web) use to push the active tool's `_meta` to the iframe.
  *
- * Thin wrapper around {@link parseBootstrapFromToolResult}; same
- * back-compat motivation as {@link readSelfContainedBootstrap}.
+ * Thin wrapper around {@link parseMetaFromToolResult}; same
+ * back-compat motivation as {@link readSelfContainedMeta}.
  *
  * Owning this extraction inside the runtime (instead of in the shell
  * HTML) is the architectural cure for the "shell-side validator
  * lagged the protocol" bug class: shell + runtime drift becomes
- * impossible because the shell never inspects the bootstrap shape.
+ * impossible because the shell never inspects the slice-meta shape.
  */
-export declare function extractBootstrapFromToolResult(params: unknown): SelfContainedBootstrap | null;
+export declare function extractMetaFromToolResult(params: unknown): SelfContainedMcpAppAiGguiMeta | null;
 /**
  * Render a wired-action's `data` payload as a short inline string
  * for embedding in a `ui/message` consent prompt. Goal: human-
@@ -336,8 +398,7 @@ export declare function emitAudit(args: {
     readonly toolName: string;
     readonly kind: 'dispatch' | 'openLink' | 'requestDisplayMode';
     readonly payload: Record<string, unknown>;
-    readonly sessionId: string;
-    readonly stackItemId?: string;
+    readonly renderId: string;
     readonly appId: string;
     readonly actionId: string;
     readonly firedAt: string;
@@ -347,16 +408,8 @@ export declare function dispatchWiredAction(args: {
     readonly toolName: string;
     readonly intent: string;
     readonly data: unknown;
-    readonly sessionId: string;
-    readonly stackItemId?: string;
+    readonly renderId: string;
     readonly appId: string;
-    /**
-     * Optional `actionSpec[intent].nextStep` hint forwarded by the
-     * caller. Surfaced on the inline-userAction envelope when the pipe
-     * isn't available, so the agent has a strong steer toward the right
-     * tool.
-     */
-    readonly nextStep?: string;
 }): void;
 /**
  * Fire a wired action via Pattern α — direct `tools/call` against a
@@ -369,7 +422,7 @@ export declare function dispatchWiredAction(args: {
  * PIPE-2 design note: Pattern α deliberately does NOT fire
  * `submit_action` — a pipe append would queue the gesture for the
  * agent's `ggui_consume` long-poll, causing double-processing
- * (host's tool relay AND agent's reaction). SessionInspector loses
+ * (host's tool relay AND agent's reaction). RenderInspector loses
  * Pattern α observability for now; re-add via a dedicated audit-only
  * gesture kind if operators need it.
  *
@@ -399,12 +452,15 @@ export declare function fireDirectToolCall(args: {
  *
  * @internal — exported for unit tests + production reuse.
  */
+export declare function resolveDispatchToolName(): string;
+/**
+ * @internal — exported for unit tests + production reuse.
+ */
 export declare function routeDispatch(args: {
     readonly actionName: string;
     readonly data: unknown;
-    readonly bootstrap: {
-        readonly sessionId: string;
-        readonly stackItemId?: string;
+    readonly meta: {
+        readonly renderId: string;
         readonly appId: string;
         readonly appCallableTools?: readonly string[];
         readonly actionNextSteps?: Readonly<Record<string, string>>;
@@ -420,8 +476,7 @@ export declare function routeDispatch(args: {
 export declare function openLinkInParent(args: {
     readonly toolName: string;
     readonly url: string;
-    readonly sessionId: string;
-    readonly stackItemId?: string;
+    readonly renderId: string;
     readonly appId: string;
 }): void;
 /**
@@ -434,8 +489,7 @@ export declare function openLinkInParent(args: {
 export declare function requestDisplayModeInParent(args: {
     readonly toolName: string;
     readonly mode: 'fullscreen' | 'pip' | 'inline';
-    readonly sessionId: string;
-    readonly stackItemId?: string;
+    readonly renderId: string;
     readonly appId: string;
 }): void;
 /**
@@ -475,8 +529,7 @@ export declare function requestDisplayModeInParent(args: {
 /** @internal — exported for unit tests. */
 export declare function installAnchorClickInterceptor(args: {
     readonly dispatchToolName: string;
-    readonly sessionId: string;
-    readonly stackItemId?: string;
+    readonly renderId: string;
     readonly appId: string;
 }): void;
 /**
@@ -512,13 +565,12 @@ export declare function installAnchorClickInterceptor(args: {
  *
  * Idempotent: the {@link fullscreenInterceptInstalled} guard prevents
  * re-mounts from chaining wrappers (which would also leak the prior
- * mount's `sessionId`/`appId` if they ever differed).
+ * mount's `renderId`/`appId` if they ever differed).
  */
 /** @internal — exported for unit tests. */
 export declare function installFullscreenInterceptors(args: {
     readonly dispatchToolName: string;
-    readonly sessionId: string;
-    readonly stackItemId?: string;
+    readonly renderId: string;
     readonly appId: string;
 }): void;
 /**