@ggui-ai/iframe-runtime 0.2.0-alpha.4 → 0.4.0-rc.0

package/dist/runtime.d.ts

@@ -1,6 +1,7 @@
-import type { DrainAckPayload, Render } from '@ggui-ai/protocol';
+import type { DrainAckPayload, GguiSession } from '@ggui-ai/protocol';
 import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
-import type { ValidatedMcpAppAiGguiMeta, RenderSeedInput } from './types.js';
+import { type McpAppAiGguiRenderMeta, type McpAppBootstrapFailedMessage, type McpAppRendererReadyMessage } from '@ggui-ai/protocol/integrations/mcp-apps';
+import type { GguiSessionSeedInput } from './types.js';
 import type { McpAppAiGguiMetaParseFailureReason } from './types.js';
 import { App } from '@modelcontextprotocol/ext-apps';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
@@ -40,8 +41,8 @@ export type ConnectAppResult = {
  * 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
+ * @internal — the production caller is `bootSequence` (reached via
+ *   `bootProduction`); tests inject directly to
  *   drive outbound `tools/call` through a `MockTransport`-bound App
  *   without invoking the full boot pipeline.
  */
@@ -60,10 +61,14 @@ export declare function __resetAppForTest(): void;
  * codes.
  */
 export type RendererBootFailureReason = McpAppAiGguiMetaParseFailureReason | 'UI_INITIALIZE_FAILED' | 'WS_HANDSHAKE_FAILED' | 'UPGRADE_REQUIRED';
-export interface RendererBootFailedMessage {
-    readonly type: 'ggui:bootstrap-failed';
+/**
+ * The renderer's emission-side narrowing of the protocol-owned
+ * {@link McpAppBootstrapFailedMessage} envelope: same wire shape, but
+ * `reason` is pinned to the closed {@link RendererBootFailureReason}
+ * union so every emission site stays exhaustive-checkable.
+ */
+export interface RendererBootFailedMessage extends McpAppBootstrapFailedMessage {
     readonly reason: RendererBootFailureReason;
-    readonly message: string;
 }
 export interface BootSequenceOptions {
     readonly doc: Document;
@@ -97,10 +102,7 @@ export interface BootSequenceOptions {
      * Notify-parent hook. Default posts to `window.parent`; tests
      * inject a recorder.
      */
-    readonly notifyParent: (msg: RendererBootFailedMessage | {
-        type: 'ggui:renderer-ready';
-        version: string;
-    }) => void;
+    readonly notifyParent: (msg: RendererBootFailedMessage | McpAppRendererReadyMessage) => void;
     /**
      * Optional typed {@link import('./protocol-error.js').ProtocolError}
      * sink. Every bootstrap-failure path fires this in parallel with
@@ -113,17 +115,14 @@ export interface BootSequenceOptions {
      * 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.
+     *   - `auth-required` — fired by the system channel handler when an
+     *     `auth_required` system frame arrives.
+     *   - `channel-transport-*` — fired by the channel-transport router
+     *     on per-channel transport picks / fallbacks / resubscribes.
      *
      * Absent = observability emission skipped entirely (matches the
      * ProtocolError posture; the `<McpAppIframe>` host wrapper decides
@@ -143,7 +142,7 @@ export interface BootSequenceOptions {
      *
      * 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.
+     *   2a. `code-ready` — after first ack folds the initial render.
      *   2b. `error` — paired with every `ggui:bootstrap-failed` emission;
      *       `error.code` mirrors the legacy envelope's `reason`.
      *
@@ -153,9 +152,9 @@ export interface BootSequenceOptions {
     /**
      * 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
+     * (2) mounts the single render into the renderer's slot on
+     * first ack + re-applies on every subsequent render; (3) routes
+     * inbound `data` / `props_update` frames through the
      * supplied wire config + StreamBus.
      *
      * When absent (default), the boot sequence runs the placeholder
@@ -177,7 +176,7 @@ export interface BootSequenceOptions {
      * runs — spec mandates `ui/initialize` regardless of how slice meta
      * arrives, and `hostContext` is captured from `app.getHostContext()`.
      */
-    readonly preResolvedMeta?: ValidatedMcpAppAiGguiMeta;
+    readonly preResolvedMeta?: McpAppAiGguiRenderMeta;
     /**
      * How long to wait for the spec-canonical `ui/notifications/tool-result`
      * notification (Tier 2 of the resolver chain) before failing with
@@ -205,14 +204,14 @@ export interface RendererHooks {
      * with `StackRenderer`.
      *
      * `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).
+     * the channel handlers (system `auth-required`) and the
+     * channel-transport router (`channel-transport-*`). Absent = those
+     * sites run silent (the connect-time emission sites —
+     * `connectViaRegistry`'s version + subscribe events — still fire
+     * via their own emitters).
      */
     setup(params: {
-        readonly meta: ValidatedMcpAppAiGguiMeta;
+        readonly meta: McpAppAiGguiRenderMeta;
         readonly renderInto: HTMLElement;
         readonly statusRefs: StatusRefs;
         readonly onObserve?: ObservabilityEmitter;
@@ -241,14 +240,14 @@ export interface RendererHandle {
      * Shared by the `render` and `props_update` channel handlers so React
      * updates flow through one path.
      */
-    applyRender(render: Render | RenderSeedInput): Promise<void>;
+    applyRender(render: GguiSession | GguiSessionSeedInput): 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;
+    getCurrentGguiSession(): GguiSession | GguiSessionSeedInput | null;
     readonly validatorCtx: RendererValidatorContext;
     /**
      * Send surface for outbound frames. Wired by `setup()` to the WS
@@ -272,7 +271,7 @@ export interface RendererHandle {
     /**
      * Channel-client registry holding handlers for every WS frame type
      * the iframe routes (`render`, `data`, `props_update`, `drain_ack`,
-     * `channel_payload`, `channel_error`, `system`, `feedback`). The
+     * `channel_payload`, `channel_error`, `system`). The
      * registry-bound transport is the sole dispatch surface — frames
      * arrive directly through registered handlers, no longer through a
      * separate `onMessage` callback.
@@ -306,20 +305,9 @@ export interface BootSequenceResult {
      * render; this replaces the earlier `StackModel` return that wrapped
      * a multi-item model.
      */
-    readonly mountedRender: Render | RenderSeedInput | null;
+    readonly mountedRender: GguiSession | GguiSessionSeedInput | null;
 }
 export declare function bootSequence(opts: BootSequenceOptions): Promise<BootSequenceResult>;
-/**
- * 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 SelfContainedMcpAppAiGguiMeta = ValidatedMcpAppAiGguiMeta;
 /**
  * Read `globalThis.__GGUI_META__` synchronously, validate against
  * the unified slice-meta shape, and return the typed meta (or null
@@ -331,11 +319,11 @@ export type SelfContainedMcpAppAiGguiMeta = ValidatedMcpAppAiGguiMeta;
  * reader contract — the autostart resolver only needs the "valid
  * meta or fall through" signal.
  */
-export declare function readSelfContainedMeta(): SelfContainedMcpAppAiGguiMeta | null;
+export declare function readSelfContainedMeta(): McpAppAiGguiRenderMeta | 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
+ * {@link GguiSessionSeedInput} the mount surface can paint immediately,
+ * BEFORE the authoritative wire `GguiSession` 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).
  *
@@ -348,11 +336,11 @@ export declare function readSelfContainedMeta(): SelfContainedMcpAppAiGguiMeta |
  * 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).
+ * ack reconciles the seed to a full `GguiSession` (no fabrication).
  */
-export declare function buildRenderSeedInput(meta: SelfContainedMcpAppAiGguiMeta): Promise<RenderSeedInput | null>;
+export declare function buildGguiSessionSeedInput(meta: McpAppAiGguiRenderMeta): Promise<GguiSessionSeedInput | null>;
 /**
- * Extract a {@link SelfContainedMcpAppAiGguiMeta} from a
+ * Extract a {@link McpAppAiGguiRenderMeta} 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.
@@ -365,9 +353,9 @@ export declare function buildRenderSeedInput(meta: SelfContainedMcpAppAiGguiMeta
  * lagged the protocol" bug class: shell + runtime drift becomes
  * impossible because the shell never inspects the slice-meta shape.
  */
-export declare function extractMetaFromToolResult(params: unknown): SelfContainedMcpAppAiGguiMeta | null;
+export declare function extractMetaFromToolResult(params: unknown): McpAppAiGguiRenderMeta | null;
 /**
- * Render a wired-action's `data` payload as a short inline string
+ * Render a submit-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.
@@ -378,15 +366,15 @@ export declare function extractMetaFromToolResult(params: unknown): SelfContaine
  * the LLM think every dispatch was a contentless "Please proceed
  * with **<intent>**" request.
  */
-export declare function formatWiredActionDataInline(data: unknown): string;
+export declare function formatSubmitActionDataInline(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.
+ * user-driven gesture (submit-action 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
@@ -398,72 +386,58 @@ export declare function emitAudit(args: {
     readonly toolName: string;
     readonly kind: 'dispatch' | 'openLink' | 'requestDisplayMode';
     readonly payload: Record<string, unknown>;
-    readonly renderId: string;
+    readonly sessionId: 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 renderId: string;
-    readonly appId: 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). RenderInspector loses
- * Pattern α observability for now; re-add via a dedicated audit-only
- * gesture kind if operators need it.
+ * Dispatch a submit-action via the empirically-validated bridge
+ * chain (validated against claude.ai): a `tools/call` to
+ * {@link toolName} (the `ggui_runtime_submit_action` receiver)
+ * appends the gesture to the render's consume pipe, paired with a
+ * silent `ui/update-model-context` prime and — only when the server
+ * reports no active `ggui_consume` long-poll — a `ui/message`
+ * doorbell so a fresh agent turn drains the pipe. Hosts MUST honor
+ * `_meta.ui.visibility:['app']` per spec §401, otherwise the
+ * `tools/call` is silently rejected (probe found this empirically).
  *
  * @internal — exported for unit tests.
  */
-export declare function fireDirectToolCall(args: {
-    readonly targetToolName: string;
+export declare function dispatchSubmitAction(args: {
+    readonly toolName: string;
+    readonly intent: string;
     readonly data: unknown;
+    readonly sessionId: string;
+    readonly appId: string;
 }): 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.
+ * Resolve the name of the spec-canonical submit-action receiver tool
+ * the dispatch path targets with `tools/call`.
  *
  * @internal — exported for unit tests + production reuse.
  */
 export declare function resolveDispatchToolName(): string;
 /**
+ * Routing helper for `WireConfig.dispatch` — every user action takes
+ * the same path: enqueue the gesture onto the render's pending-event
+ * pipe via `submit_action`. The agent retrieves it EXCLUSIVELY via
+ * `ggui_consume` — the gesture never travels inline, so there is no
+ * `nextStep` hint to forward client-side (the server derives the
+ * agent-facing hint from the render's `actionSpec[name].nextStep`
+ * when it builds the consume event).
+ *
+ * Lives as a named export (rather than a closure body inside the
+ * boot path) so production + tests exercise the same code path.
+ *
  * @internal — exported for unit tests + production reuse.
  */
 export declare function routeDispatch(args: {
     readonly actionName: string;
     readonly data: unknown;
     readonly meta: {
-        readonly renderId: string;
+        readonly sessionId: string;
         readonly appId: string;
-        readonly appCallableTools?: readonly string[];
-        readonly actionNextSteps?: Readonly<Record<string, string>>;
     };
     readonly dispatchToolName: string;
 }): void;
@@ -476,7 +450,7 @@ export declare function routeDispatch(args: {
 export declare function openLinkInParent(args: {
     readonly toolName: string;
     readonly url: string;
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly appId: string;
 }): void;
 /**
@@ -489,7 +463,7 @@ export declare function openLinkInParent(args: {
 export declare function requestDisplayModeInParent(args: {
     readonly toolName: string;
     readonly mode: 'fullscreen' | 'pip' | 'inline';
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly appId: string;
 }): void;
 /**
@@ -529,7 +503,7 @@ export declare function requestDisplayModeInParent(args: {
 /** @internal — exported for unit tests. */
 export declare function installAnchorClickInterceptor(args: {
     readonly dispatchToolName: string;
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly appId: string;
 }): void;
 /**
@@ -565,12 +539,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 `renderId`/`appId` if they ever differed).
+ * mount's `sessionId`/`appId` if they ever differed).
  */
 /** @internal — exported for unit tests. */
 export declare function installFullscreenInterceptors(args: {
     readonly dispatchToolName: string;
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly appId: string;
 }): void;
 /**