@ggui-ai/iframe-runtime 0.1.0-rc.1

package/dist/runtime.d.ts

@@ -0,0 +1,531 @@
+import type { DrainAckPayload } 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 { StreamBus } from './wire-config.js';
+import { type ChannelTransportRouter } from './channel-transport.js';
+import { ChannelRegistry } from '@ggui-ai/channel-client';
+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.
+ * 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
+ * the matching per-action toast keyed on `eventId`.
+ *
+ * Listener faults are absorbed so a buggy subscriber can't take down
+ * the WS dispatch loop.
+ */
+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;
+    };
+}
+/**
+ * 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
+ * codes.
+ */
+export type RendererBootFailureReason = BootstrapParseFailureReason | 'UI_INITIALIZE_FAILED' | 'WS_HANDSHAKE_FAILED' | 'UPGRADE_REQUIRED';
+export interface RendererBootFailedMessage {
+    readonly type: 'ggui:bootstrap-failed';
+    readonly reason: RendererBootFailureReason;
+    readonly message: string;
+}
+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`.
+     */
+    readonly callUiInitialize: () => Promise<JsonRpcResponse>;
+    /**
+     * 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.
+     *
+     * Default: `connectViaRegistry` from `./registry-subscribe.js`.
+     */
+    readonly connectFn?: ConnectFn;
+    /**
+     * Notify-parent hook. Default posts to `window.parent`; tests
+     * inject a recorder.
+     */
+    readonly notifyParent: (msg: RendererBootFailedMessage | {
+        type: 'ggui:renderer-ready';
+        version: string;
+    }) => void;
+    /**
+     * Optional typed {@link import('./protocol-error.js').ProtocolError}
+     * sink. Every bootstrap-failure path fires this in parallel with
+     * `notifyParent` so the `<McpAppIframe>` host wrapper's `onError`
+     * prop receives typed errors. Absent = typed emission is skipped
+     * (the narrow `RendererBootFailedMessage` path is unchanged).
+     */
+    readonly onProtocolError?: ProtocolErrorEmitter;
+    /**
+     * Optional {@link ObservabilityEmitter} sink. Fires for every
+     * renderer-observed event flow the host inspector cares about:
+     *
+     *   - `contract-error-emitted` — whenever a `_ggui:contract-error`
+     *     envelope arrives on the live channel.
+     *   - `schema-version-mismatch` — forwarded from subscribe's own
+     *     emission on UPGRADE_REQUIRED.
+     *   - `subscribe-failed` — forwarded from subscribe's emission on
+     *     transient reconnect transitions.
+     *
+     * `wired-tool-invoked` is emitted from the wire config's outbound
+     * dispatch path (see `buildRootWireConfig`'s `onObserve`), NOT from
+     * here — the `data:submit` envelope hasn't passed through this
+     * handler when it fires.
+     *
+     * Absent = observability emission skipped entirely (matches the
+     * ProtocolError posture; the `<McpAppIframe>` host wrapper decides
+     * whether to bind this via its `onObserve` prop).
+     */
+    readonly onObserve?: ObservabilityEmitter;
+    /**
+     * Optional {@link LifecycleEmitter} sink. Fires on every renderer
+     * mount-state transition (`mounting` → `code-ready` | `error`,
+     * later `disconnected`). Production binds the postMessage-to-parent
+     * default {@link postLifecycleToParent}; tests inject a recorder.
+     *
+     * Absent = lifecycle emission skipped entirely. The legacy
+     * postMessage envelopes (`ggui:renderer-ready`,
+     * `ggui:bootstrap-failed`) STAY emitted regardless — lifecycle is
+     * an additive surface, not a replacement.
+     *
+     * Sequence the renderer guarantees when this is bound:
+     *   1. `mounting` — before any IO, paired with `ggui:renderer-ready`.
+     *   2a. `code-ready` — after first ack folds the initial stack.
+     *   2b. `error` — paired with every `ggui:bootstrap-failed` emission;
+     *       `error.code` mirrors the legacy envelope's `reason`.
+     *
+     * @public
+     */
+    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
+     * inbound `data` / `props_update` / `feedback` frames through the
+     * supplied wire config + StreamBus.
+     *
+     * When absent (default), the boot sequence runs the placeholder
+     * path — used by `boot.test.ts` to exercise the orchestration
+     * without pulling React + design + wire into the spec's import
+     * graph.
+     */
+    readonly triadWiring?: TriadWiringHooks;
+    /**
+     * 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}.
+     *
+     * Absent OR `bootstrap.canvasMode !== true` ⇒ the inline path
+     * (per-push iframe).
+     */
+    readonly canvasMount?: CanvasMountHook;
+}
+/**
+ * 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
+ * `autoBootSequence` below; tests may pass their own fakes when
+ * exercising the full flow.
+ */
+export interface TriadWiringHooks {
+    /**
+     * 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.
+     *
+     * `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).
+     *
+     * `onObserve` — optional observability emitter threaded down to
+     * the root wire config so `wired-tool-invoked` events fire on
+     * every successful outbound wired-action dispatch. Absent = the
+     * wire config runs with a no-op observer (the other emission sites
+     * — subscribe.ts, handleObservableMessage — still fire via their
+     * own emitters).
+     */
+    setup(params: {
+        readonly bootstrap: GguiBootstrapMeta;
+        readonly stackModel: StackModel;
+        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;
+    /**
+     * Bind the real WS manager into the triad AFTER `connectFn` resolves.
+     * The `setup()` step supplies a buffering shim — this hook flushes
+     * the buffer + swaps in the real send surface. Optional: a triad
+     * that doesn't emit outbound frames can skip.
+     */
+    attachManager?(handle: TriadHandle, realManager: {
+        send: (msg: WebSocketMessage) => void;
+    }): void;
+    /** Optional cleanup — called on boot failure paths. */
+    teardown?(handle: TriadHandle): void;
+}
+export interface TriadHandle {
+    readonly rootWireConfig: WireConfig;
+    readonly streamBus: StreamBus;
+    readonly stackRenderer: StackRenderer;
+    readonly validatorCtx: RendererValidatorContext;
+    /**
+     * Send surface for outbound frames. Wired by `setup()` to the WS
+     * manager obtained AFTER subscribe; initial setup supplies a
+     * buffering shim that flushes on the first `send()`-ready moment.
+     */
+    readonly manager: {
+        send: (msg: WebSocketMessage) => void;
+    };
+    /**
+     * 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.
+     *
+     * Always present — the router gracefully no-ops when no channel
+     * declares `source.tool` (legacy data-frame path is unaffected).
+     */
+    readonly channelTransport: ChannelTransportRouter;
+    /**
+     * Channel-client registry holding handlers for every WS frame type
+     * the iframe routes (`push`, `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
+     * separate `onMessage` callback.
+     *
+     * `bootSequence` calls `registry.bind(...)` indirectly through the
+     * `connectFn` seam after `setup()` returns. Post-bind, registration
+     * of new handlers is frozen (the registry guards against it); the
+     * `subscribe-handshake` handlers (`ack`, `error`) are added by
+     * `connectViaRegistry` and consumed during handshake resolution.
+     */
+    readonly channelRegistry: ChannelRegistry;
+}
+export interface BootSequenceResult {
+    readonly ok: boolean;
+    readonly stack: StackModel;
+}
+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.
+ *
+ * The export is kept so downstream consumers (`@ggui-ai/iframe-runtime`
+ * barrel, dependent test suites) don't break.
+ *
+ * @public
+ */
+export type SelfContainedBootstrap = GguiBootstrapMeta;
+/**
+ * Read `globalThis.__GGUI_BOOTSTRAP__` synchronously, validate against
+ * the unified bootstrap shape, and return the typed bootstrap (or null
+ * on absence / malformation).
+ *
+ * Thin wrapper around {@link parseBootstrapFromGlobal}; 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.
+ */
+export declare function readSelfContainedBootstrap(): SelfContainedBootstrap | null;
+/**
+ * Extract a {@link SelfContainedBootstrap} 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}.
+ *
+ * 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.
+ */
+export declare function extractBootstrapFromToolResult(params: unknown): SelfContainedBootstrap | null;
+/**
+ * Render a wired-action's `data` payload as a short inline string
+ * for embedding in a `ui/message` consent prompt. Goal: human-
+ * readable, not a JSON dump. Falls back to truncated JSON for
+ * nested values so the prompt doesn't drop information silently.
+ *
+ * Exported for unit-testing — an earlier implementation returned `''`
+ * for primitive payloads (strings/numbers/booleans), which silently
+ * vaporised the chip's actual text from the consent prompt and made
+ * the LLM think every dispatch was a contentless "Please proceed
+ * with **<intent>**" request.
+ */
+export declare function formatWiredActionDataInline(data: unknown): string;
+/**
+ * Fire a single canonical action envelope (`tools/call
+ * ggui_runtime_submit_action`) carrying the typed `{kind, payload, …}` shape
+ * defined in `@ggui-ai/protocol/integrations/mcp-apps`. Every
+ * user-driven gesture (Pattern α/β dispatch, native-idiom anchor click,
+ * native-idiom fullscreen request) calls this alongside its primary
+ * host effect, so operators get **uniform server-side observability**
+ * across every gesture kind.
+ *
+ * Fail-soft: a rejected audit fire MUST NOT block the primary host
+ * effect. Detached-parent / host-rejected audit envelopes are
+ * dropped silently here; the primary effect proceeds via its own
+ * `postToParent` call from the caller.
+ */
+/** @internal — exported for unit tests. */
+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 appId: string;
+    readonly actionId: string;
+    readonly firedAt: string;
+}): void;
+/** @internal — exported for unit tests. */
+export declare function dispatchWiredAction(args: {
+    readonly toolName: string;
+    readonly intent: string;
+    readonly data: unknown;
+    readonly sessionId: string;
+    readonly stackItemId?: 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
+ * same-server, app-visible target tool. The iframe is allowed to fire
+ * the tool directly from this server connection per MCP-Apps spec
+ * §2026-01-26 visibility rules. Skips the submit_action pipe entirely:
+ * the tool fires without the agent's involvement (the whole point of
+ * Pattern α), chat stays clean.
+ *
+ * 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
+ * Pattern α observability for now; re-add via a dedicated audit-only
+ * gesture kind if operators need it.
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function fireDirectToolCall(args: {
+    readonly targetToolName: string;
+    readonly data: unknown;
+}): void;
+/**
+ * Pure routing helper for `WireConfig.dispatch` — chooses Pattern α
+ * (direct `tools/call`) when the action's wired tool is in
+ * `appCallableTools`, otherwise falls back to Pattern β (the 3-message
+ * bridge).
+ *
+ * The routing logic was previously inlined as a closure body inside
+ * `bootSelfContained`'s `wireConfig.dispatch`, with a verbatim
+ * re-creation in `__tests__/dispatch-routing.test.ts`. Tests could
+ * pass against stale code if either drifted. Extraction means
+ * production + tests now exercise the same code path.
+ *
+ * Pattern α (same-server, app-visible target tool): chat stays clean,
+ * no LLM consent loop. Pattern β (anything else: cross-server tool, no
+ * wired tool, or tool not in `appCallableTools`): the canonical
+ * 3-message workaround the LLM brokers when the tool isn't directly
+ * callable from the iframe.
+ *
+ * @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 appId: string;
+        readonly appCallableTools?: readonly string[];
+        readonly actionNextSteps?: Readonly<Record<string, string>>;
+    };
+    readonly dispatchToolName: string;
+}): void;
+/**
+ * `ui/open-link` direct dispatch helper — used by the anchor-click
+ * interceptor. Fires a parallel `kind:'openLink'` audit so operators
+ * retain uniform observability across every gesture kind.
+ */
+/** @internal — exported for unit tests. */
+export declare function openLinkInParent(args: {
+    readonly toolName: string;
+    readonly url: string;
+    readonly sessionId: string;
+    readonly stackItemId?: string;
+    readonly appId: string;
+}): void;
+/**
+ * `ui/request-display-mode` direct dispatch helper — used by the
+ * `Element.requestFullscreen` / `Document.exitFullscreen`
+ * interceptors. Fires a parallel `kind:'requestDisplayMode'` audit so
+ * operators retain uniform observability across every gesture kind.
+ */
+/** @internal — exported for unit tests. */
+export declare function requestDisplayModeInParent(args: {
+    readonly toolName: string;
+    readonly mode: 'fullscreen' | 'pip' | 'inline';
+    readonly sessionId: string;
+    readonly stackItemId?: string;
+    readonly appId: string;
+}): void;
+/**
+ * Native-idiom interceptor for anchor clicks.
+ *
+ * Install a capture-phase `click` listener on `document` that traps
+ * clicks targeting an `<a href>` whose href is an external (cross-
+ * origin OR `target="_blank"`) http(s) URL. Intercepted clicks are
+ * routed through {@link openLinkInParent} — full audit envelope +
+ * `ui/open-link` postMessage. Generated components use plain
+ * `<a href="https://example.com" target="_blank">`; the runtime
+ * intercepts the click and routes it to the host.
+ *
+ * Decision rules (DOM event → routing):
+ *   - No anchor in ancestor chain → skip (nothing to do).
+ *   - `event.defaultPrevented` → skip (component handler already
+ *     consumed the click; respect its choice).
+ *   - href starts with `#` → skip (same-document fragment; preserve
+ *     bookmark / scroll-into-view behavior).
+ *   - href scheme is not `http(s):` → skip (`mailto:`, `tel:`,
+ *     `javascript:`, `data:` are out of the spec's domain).
+ *   - href origin === `window.location.origin` AND `target !== '_blank'`
+ *     → skip (in-frame navigation; preserve SPA links).
+ *   - Otherwise → preventDefault + fire {@link openLinkInParent}.
+ *
+ * Capture phase is load-bearing: component-defined `onClick` handlers
+ * may call `preventDefault()`, which would mask the native intercept
+ * if the listener were on the bubble phase. By running first, we
+ * either intercept (then component handlers see `defaultPrevented`)
+ * or honor an upstream `defaultPrevented` from a higher-priority
+ * handler.
+ *
+ * Idempotent: re-mounts (via `installPostMountListener`) call this
+ * helper again; the {@link anchorClickInterceptInstalled} guard makes
+ * subsequent calls a no-op.
+ */
+/** @internal — exported for unit tests. */
+export declare function installAnchorClickInterceptor(args: {
+    readonly dispatchToolName: string;
+    readonly sessionId: string;
+    readonly stackItemId?: string;
+    readonly appId: string;
+}): void;
+/**
+ * Native-idiom interceptor for the Fullscreen API.
+ *
+ * Override `Element.prototype.requestFullscreen` and
+ * `Document.prototype.exitFullscreen` so generated components calling
+ * either go through {@link requestDisplayModeInParent} (fires the
+ * `ui/request-display-mode` postMessage + paired audit envelope).
+ *
+ * The native fullscreen API would not work from inside the iframe
+ * regardless — sandboxed iframes need an explicit
+ * `allow="fullscreen"` permission, and even when granted the host
+ * (claude.ai, ggui demo shell) typically owns the chrome. Routing
+ * through the parent host lets it decide the actual presentation
+ * (true fullscreen, modal, expanded panel).
+ *
+ * Both overrides return `Promise.resolve()` so callers using the
+ * standard `.then()` / `await` form don't break. The native call is
+ * NOT delegated — there's no useful behavior to preserve and a real
+ * native fullscreen attempt would race with the host's handling.
+ *
+ * Mode mapping:
+ *   - `requestFullscreen()` → `mode: 'fullscreen'`
+ *   - `exitFullscreen()`    → `mode: 'inline'` (symmetric inverse
+ *     in the existing `requestDisplayModeInParent` mode union).
+ *
+ * Note: `'pip'` is YAGNI for v1. There's no clean native API for
+ * arbitrary-content Picture-in-Picture (Document PiP exists but is
+ * Chromium-only and requires an explicit container handoff); we
+ * surface the postMessage `mode: 'pip'` only when a future native
+ * idiom emerges.
+ *
+ * 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).
+ */
+/** @internal — exported for unit tests. */
+export declare function installFullscreenInterceptors(args: {
+    readonly dispatchToolName: string;
+    readonly sessionId: string;
+    readonly stackItemId?: string;
+    readonly appId: string;
+}): void;
+/**
+ * @internal — exposed for tests to reset module-level interceptor
+ * guards between specs. Production code never calls this; resetting
+ * during a real iframe lifecycle would cause stacked click listeners
+ * (the prior listener is NOT removed by the reset, only forgotten).
+ */
+export declare function __resetInterceptorsForTest(): void;
+export {};