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

package/dist/index.d.ts

@@ -19,7 +19,7 @@
  *     postMessage envelope shape parents observe on boot failure.
  *   - `ProtocolError` — canonical typed union for every failure
  *     the renderer classifies outward, wired to the postMessage
- *     envelope and the `_ggui:contract-error` WS channel.
+ *     envelope.
  *   - `BootstrapFailureReason` — extensibly-closed union of every
  *     reason the 'bootstrap' variant can carry. Consolidates
  *     parse-time and post-parse codes in one place. (Wire-visible
@@ -34,10 +34,10 @@
  */
 export type { McpAppAiGguiMetaParseFailureReason, McpAppAiGguiMetaParseResult, } from './types.js';
 export { parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './meta-parse.js';
-export type { RendererBootFailureReason, RendererBootFailedMessage, SelfContainedMcpAppAiGguiMeta, } from './runtime.js';
+export type { RendererBootFailureReason, RendererBootFailedMessage, } from './runtime.js';
 export type { ProtocolError, ProtocolErrorEmitter, BootstrapFailureReason, } from './protocol-error.js';
-export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromContractErrorPayload, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
-export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, WiredToolInvokedEvent, ContractErrorEmittedEvent, SchemaVersionMismatchEvent, SubscribeFailedEvent, AuthRequiredEvent, UnknownObservabilityEvent, } from './observability.js';
+export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
+export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, SubscribeFailedEvent, AuthRequiredEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, UnknownObservabilityEvent, } from './observability.js';
 export { postObservabilityToParent } from './observability.js';
 export type { LifecycleEmitter } from './lifecycle.js';
 export { postLifecycleToParent, makeLifecycleEvent } from './lifecycle.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './meta-parse.js';
-export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromContractErrorPayload, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
+export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
 export { postObservabilityToParent } from './observability.js';
 export { postLifecycleToParent, makeLifecycleEvent } from './lifecycle.js';

package/dist/lifecycle.d.ts

@@ -20,7 +20,7 @@
  *
  * @public
  */
-import type { McpAppLifecycleEvent, McpAppLifecycleState } from '@ggui-ai/protocol/integrations/mcp-apps';
+import { type McpAppLifecycleEvent, type McpAppLifecycleState } from '@ggui-ai/protocol/integrations/mcp-apps';
 /**
  * Caller sink for lifecycle events. Mirrors the
  * {@link import('./observability.js').ObservabilityEmitter} posture —
@@ -52,13 +52,13 @@ export declare function postLifecycleToParent(event: McpAppLifecycleEvent): void
  * Build a lifecycle event payload. Centralises the `state` →
  * `McpAppLifecycleEvent` projection so call sites in
  * `runtime.ts` don't repeat the `{state, ...optional}` shape and so
- * the additive-extension semantic of `renderId` / `error` is
+ * the additive-extension semantic of `sessionId` / `error` is
  * single-sourced.
  *
  * @public
  */
 export declare function makeLifecycleEvent(state: McpAppLifecycleState, options?: {
-    readonly renderId?: string;
+    readonly sessionId?: string;
     readonly error?: {
         readonly code: string;
         readonly message: string;

package/dist/lifecycle.js

@@ -1,3 +1,26 @@
+/**
+ * Renderer-side emission of MCP App lifecycle events — the postMessage
+ * envelope the iframe posts to its parent on every mount-state
+ * transition. Mirrors the `<McpAppIframe>` host's outer-DOM mirror
+ * (`data-ggui-mcp-app-iframe-lifecycle="<state>"`); together they form
+ * a first-class wire surface so observers (E2E tests, accessibility
+ * scanners, third-party hosts, console inspectors) can read mount
+ * state without reaching into iframe-internal DOM.
+ *
+ * Lives here (not in `runtime.ts`) so spec-level tests can import the
+ * helper without dragging in the runtime's autostart side effects.
+ *
+ * **Producer obligations** (locked by
+ * {@link import('@ggui-ai/protocol/integrations/mcp-apps').McpAppLifecycleMessage}):
+ *   - `mounting` MUST fire before bundle eval / first WS attempt.
+ *   - Exactly one terminal state (`code-ready` or `error`) MUST follow
+ *     for every successful boot attempt.
+ *   - `disconnected` MAY follow `code-ready` on WS close; a subsequent
+ *     `code-ready` MAY follow on successful reconnect (not required).
+ *
+ * @public
+ */
+import { MCP_APP_LIFECYCLE_TYPE, } from '@ggui-ai/protocol/integrations/mcp-apps';
 /**
  * Default emitter — posts a {@link McpAppLifecycleMessage} envelope to
  * `window.parent`. Mirrors `postObservabilityToParent` /
@@ -13,7 +36,7 @@
 export function postLifecycleToParent(event) {
     if (typeof window === 'undefined' || window.parent === null)
         return;
-    const message = { type: 'ggui:lifecycle', event };
+    const message = { type: MCP_APP_LIFECYCLE_TYPE, event };
     try {
         window.parent.postMessage(message, '*');
     }
@@ -26,7 +49,7 @@ export function postLifecycleToParent(event) {
  * Build a lifecycle event payload. Centralises the `state` →
  * `McpAppLifecycleEvent` projection so call sites in
  * `runtime.ts` don't repeat the `{state, ...optional}` shape and so
- * the additive-extension semantic of `renderId` / `error` is
+ * the additive-extension semantic of `sessionId` / `error` is
  * single-sourced.
  *
  * @public
@@ -34,15 +57,15 @@ export function postLifecycleToParent(event) {
 export function makeLifecycleEvent(state, options) {
     // Avoid emitting `undefined` keys — the protocol's structural lock
     // (mcp-apps.test.ts "shape lock") asserts a populated event has
-    // exactly state + renderId + error keys, not an Object.keys-
+    // exactly state + sessionId + error keys, not an Object.keys-
     // observable `undefined` field.
     if (options === undefined)
         return { state };
-    const { renderId, error } = options;
+    const { sessionId, error } = options;
     return {
         state,
-        ...(typeof renderId === 'string' && renderId.length > 0
-            ? { renderId }
+        ...(typeof sessionId === 'string' && sessionId.length > 0
+            ? { sessionId }
             : {}),
         ...(error !== undefined ? { error } : {}),
     };

package/dist/mcp-app-iframe-host.d.ts

@@ -15,10 +15,10 @@
  *
  * Adapter-boundary rule (ENFORCED):
  *   - MCP Apps lifecycle messages from the embedded iframe do NOT
- *     mutate the outer ggui session state / contracts — the host
- *     never forwards them to ggui-server as session-level events.
+ *     mutate the outer ggui render state / contracts — the host
+ *     never forwards them to ggui-server as render-level events.
  *   - `ui/initialize` intentionally DOES NOT forward outer ggui
- *     session state (stack, actionSpec, streamSpec) to the iframe.
+ *     render state (actionSpec, streamSpec) to the iframe.
  *
  * On detach, a host-initiated `ui/resource-teardown` notification
  * is posted to the iframe BEFORE the element leaves the DOM so the
@@ -30,16 +30,16 @@
  * iframe can in turn render a `ui://ggui/render` resource via its
  * own host implementation. That recursion stays bounded because
  * each nested iframe runs the same adapter-boundary rule — outer
- * ggui state never leaks into the inner renderer's session through
+ * ggui state never leaks into the inner renderer's render through
  * this host path. Host-to-host sandboxing is browser-enforced by
  * the iframe's `sandbox="allow-scripts"` attribute.
  */
-import type { McpAppsRender } from '@ggui-ai/protocol/integrations/mcp-apps';
+import type { McpAppsGguiSession } from '@ggui-ai/protocol/integrations/mcp-apps';
 export interface McpAppIframeMountOptions {
-    readonly render: McpAppsRender;
-    /** Render id — threaded into the proxy URL so server-side
+    readonly render: McpAppsGguiSession;
+    /** GguiSession id — threaded into the proxy URL so server-side
      *  connector scoping works. */
-    readonly renderId: string;
+    readonly sessionId: string;
     /**
      * Base URL of the ggui server (origin). The host appends
      *  `/mcp-apps/resource` + `/mcp-apps/tools-call` to this. Should

package/dist/mcp-app-iframe-host.js

@@ -12,7 +12,7 @@ const DEFAULT_THEME = {
 function composeResourceUrl(opts) {
     const base = opts.serverBaseUrl.replace(/\/$/, '');
     const qs = new URLSearchParams({
-        render: opts.renderId,
+        session: opts.sessionId,
         item: opts.itemId,
     });
     return `${base}/mcp-apps/resource?${qs.toString()}`;
@@ -58,7 +58,7 @@ export function mountMcpAppIframe(container, opts) {
     const serverBaseUrl = opts.serverBaseUrl ?? '';
     const resourceUrl = composeResourceUrl({
         serverBaseUrl,
-        renderId: opts.renderId,
+        sessionId: opts.sessionId,
         itemId: opts.render.id,
     });
     const toolsCallUrl = composeToolsCallUrl(serverBaseUrl);
@@ -70,7 +70,7 @@ export function mountMcpAppIframe(container, opts) {
     };
     const iframe = container.ownerDocument.createElement('iframe');
     iframe.setAttribute('data-ggui-mcp-apps', 'iframe');
-    iframe.setAttribute('data-ggui-render-id', opts.render.id);
+    iframe.setAttribute('data-ggui-session-id', opts.render.id);
     iframe.setAttribute('data-ggui-connector-id', opts.render.source.connectorId);
     iframe.src = resourceUrl;
     iframe.title = opts.render.description ?? 'MCP App';
@@ -139,7 +139,7 @@ export function mountMcpAppIframe(container, opts) {
                         method: 'POST',
                         headers: { 'Content-Type': 'application/json' },
                         body: JSON.stringify({
-                            render: opts.renderId,
+                            session: opts.sessionId,
                             item: opts.render.id,
                             tool,
                             arguments: args,

package/dist/meta-parse.d.ts

@@ -32,10 +32,9 @@ export declare function validateMeta(meta: McpAppAiGguiRenderMeta): McpAppAiGgui
 export declare function parseMetaFromGlobal(): McpAppAiGguiMetaParseResult;
 /**
  * Parse the render slice from a `ui/notifications/tool-result`
- * postMessage params payload. Looks at BOTH the spec-canonical
- * location (`params._meta`) and the Reading-B `<McpAppIframe>`
- * convention (`params.toolOutput._meta`) — Claude Desktop / claude.ai
- * Connector use the first; first-party hosts the second.
+ * postMessage params payload. `params` is a `CallToolResult` per the
+ * MCP-Apps spec, so the slice envelope lives at the spec-canonical
+ * top-level `params._meta` — the only accepted location.
  *
  * Used by the runtime's autostart resolver as the second / third boot
  * source (drained from the pre-runtime-load buffer or caught by the

package/dist/meta-parse.js

@@ -14,12 +14,10 @@
  *      JSON-RPC round-trip.
  *   2. `ui/notifications/tool-result` postMessage — spec-canonical
  *      per MCP-Apps SEP-1865. `params` is a `CallToolResult` per the
- *      spec, so slices live under `params._meta`. We also accept
- *      `params.toolOutput._meta` as a back-compat aliased shape
- *      (some in-house emitters wrap the CallToolResult inside a
- *      `toolOutput` field). Spec-strict hosts (`<AppRenderer>` from
- *      `@mcp-ui/client`, ChatGPT MCP-Apps connector, claude.ai)
- *      deliver slice meta through this channel exclusively.
+ *      spec, so slices live under `params._meta`. Hosts (`<AppRenderer>`
+ *      from `@mcp-ui/client`, the RN `<McpAppIframe>`, ChatGPT MCP-Apps
+ *      connector, claude.ai) deliver slice meta through this channel
+ *      exclusively.
  *
  * Each extractor reaches the `_meta` object and calls the protocol's
  * {@link parseMcpAppAiGguiRenderMeta} to produce a typed slice.
@@ -27,8 +25,7 @@
  * {@link validateMeta} layers in mode-discriminator + expiresAt
  * expiration checks and field-level defensive parsing for the
  * optional containers (`contextSlots`, `gadgets`, `publicEnv`,
- * `permissionsPolicy`, `appCallableTools`, `actionNextSteps`,
- * `streamWebSocketLocalTools`).
+ * `permissionsPolicy`, `streamWebSocketLocalTools`).
  *
  * Reading-B (`result.toolOutput._meta` on the `ui/initialize`
  * response) was retired in Phase 1.19b.3 — the
@@ -183,10 +180,9 @@ function projectPublicEnv(raw) {
  *     in the past AND the slice carries static content (codeUrl / kind),
  *     DEGRADE to static-only (drop `wsUrl` / `wsToken` / `expiresAt`);
  *     otherwise return EXPIRED_BOOTSTRAP.
- *   - `gadgets` / `publicEnv` / `appCallableTools` /
- *     `permissionsPolicy` / `streamWebSocketLocalTools` /
- *     `contextSlots` / `actionNextSteps` get defensive entry-level
- *     validation; malformed → defaulted.
+ *   - `gadgets` / `publicEnv` / `permissionsPolicy` /
+ *     `streamWebSocketLocalTools` / `contextSlots` get defensive
+ *     entry-level validation; malformed → defaulted.
  */
 function projectMeta(meta, hasStaticContent) {
     let expiresAt = meta.expiresAt;
@@ -208,11 +204,6 @@ function projectMeta(meta, hasStaticContent) {
     }
     const gadgets = projectGadgets(meta.gadgets);
     const publicEnv = projectPublicEnv(meta.publicEnv);
-    const appCallableToolsRaw = meta.appCallableTools;
-    const appCallableTools = Array.isArray(appCallableToolsRaw) &&
-        appCallableToolsRaw.every((s) => typeof s === 'string')
-        ? appCallableToolsRaw
-        : [];
     const permissionsPolicyRaw = meta.permissionsPolicy;
     const permissionsPolicy = Array.isArray(permissionsPolicyRaw) &&
         permissionsPolicyRaw.every((s) => typeof s === 'string' && s.length > 0)
@@ -231,18 +222,11 @@ function projectMeta(meta, hasStaticContent) {
     const themeMode = themeModeRaw === 'light' || themeModeRaw === 'dark'
         ? themeModeRaw
         : undefined;
-    const actionNextStepsRaw = meta.actionNextSteps;
-    let actionNextSteps;
-    if (isPlainObject(actionNextStepsRaw) &&
-        Object.values(actionNextStepsRaw).every((v) => typeof v === 'string')) {
-        actionNextSteps = actionNextStepsRaw;
-    }
     const contextSlots = projectContextSlots(meta.contextSlots);
     const projected = {
-        renderId: meta.renderId,
+        sessionId: meta.sessionId,
         appId: meta.appId,
         runtimeUrl: meta.runtimeUrl,
-        appCallableTools,
         ...(dropLiveCreds
             ? {}
             : {
@@ -256,6 +240,9 @@ function projectMeta(meta, hasStaticContent) {
             : {}),
         ...(meta.themeId !== undefined ? { themeId: meta.themeId } : {}),
         ...(themeMode !== undefined ? { themeMode } : {}),
+        // Per-app theme overlay carried through verbatim. Already validated
+        // via `appThemeSchema` by the wire parser, so no re-validation here.
+        ...(meta.theme !== undefined ? { theme: meta.theme } : {}),
         ...(gadgets !== undefined ? { gadgets } : {}),
         ...(publicEnv !== undefined ? { publicEnv } : {}),
         ...(streamWebSocketLocalTools !== undefined
@@ -264,7 +251,6 @@ function projectMeta(meta, hasStaticContent) {
         ...(permissionsPolicy !== undefined ? { permissionsPolicy } : {}),
         ...(meta.lastSequence !== undefined ? { lastSequence: meta.lastSequence } : {}),
         ...(meta.propsJson !== undefined ? { propsJson: meta.propsJson } : {}),
-        ...(actionNextSteps !== undefined ? { actionNextSteps } : {}),
         ...(contextSlots !== undefined ? { contextSlots } : {}),
         ...(meta.contractHash !== undefined && meta.validatorsUrl !== undefined
             ? {
@@ -349,10 +335,9 @@ export function parseMetaFromGlobal() {
 }
 /**
  * Parse the render slice from a `ui/notifications/tool-result`
- * postMessage params payload. Looks at BOTH the spec-canonical
- * location (`params._meta`) and the Reading-B `<McpAppIframe>`
- * convention (`params.toolOutput._meta`) — Claude Desktop / claude.ai
- * Connector use the first; first-party hosts the second.
+ * postMessage params payload. `params` is a `CallToolResult` per the
+ * MCP-Apps spec, so the slice envelope lives at the spec-canonical
+ * top-level `params._meta` — the only accepted location.
  *
  * Used by the runtime's autostart resolver as the second / third boot
  * source (drained from the pre-runtime-load buffer or caught by the
@@ -362,23 +347,11 @@ export function parseMetaFromToolResult(params) {
     if (!isPlainObject(params)) {
         return { ok: false, reason: 'MISSING_TOOL_OUTPUT' };
     }
-    let meta;
     const topMeta = params['_meta'];
-    if (isPlainObject(topMeta)) {
-        meta = topMeta;
-    }
-    else {
-        const toolOutput = params['toolOutput'];
-        if (isPlainObject(toolOutput)) {
-            const nestedMeta = toolOutput['_meta'];
-            if (isPlainObject(nestedMeta)) {
-                meta = nestedMeta;
-            }
-        }
-    }
-    if (meta === undefined) {
+    if (!isPlainObject(topMeta)) {
         return { ok: false, reason: 'MISSING_META_GGUI_BOOTSTRAP' };
     }
+    const meta = topMeta;
     const parsed = parseMcpAppAiGguiRenderMeta(meta);
     if (!parsed.ok) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };

package/dist/observability.d.ts

@@ -1,3 +1,4 @@
+import { MCP_APP_OBSERVE_TYPE } from '@ggui-ai/protocol/integrations/mcp-apps';
 /**
  * Observability events emitted by the renderer iframe → surfaced to
  * the MCP Apps host via the `<McpAppIframe>` wrapper's `onObserve`
@@ -23,39 +24,16 @@
  *   - `@ggui-ai/iframe-runtime` owns this union, NOT `@ggui-ai/protocol`.
  *     Observability events are a renderer ↔ host implementation seam,
  *     not a wire-format contract between arbitrary protocol peers, so
- *     they stay out of the protocol package.
+ *     they stay out of the protocol package. The ENVELOPE TAG
+ *     (`ggui:observe`) IS protocol-owned, though — it belongs to the
+ *     renderer → host postMessage envelope family
+ *     (`MCP_APP_OBSERVE_TYPE` in
+ *     `@ggui-ai/protocol/integrations/mcp-apps`), so hosts on every
+ *     platform classify it from one vocabulary.
  *
  * @public
  */
-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 RenderInspector.
- * Emitted by the server-side router (session-channel.ts) via
- * postMessage relay through the renderer.
- *
- * @public
- */
-export interface WiredToolInvokedEvent {
-    readonly kind: 'wired-tool-invoked';
-    readonly toolName: string;
-    readonly actionName?: string;
-    readonly dispatchedAt: string;
-    readonly latencyMs?: number;
-}
-/**
- * Fired when the server emits a `_ggui:contract-error` envelope on
- * the live channel. Mirrors the envelope's `code` field for host-side
- * inspection without requiring the host to parse channel frames.
- *
- * @public
- */
-export interface ContractErrorEmittedEvent {
-    readonly kind: 'contract-error-emitted';
-    readonly code: string;
-    readonly toolName: string;
-    readonly actionName?: string;
-}
+export type ObservabilityEvent = SchemaVersionMismatchEvent | SubscribeFailedEvent | AuthRequiredEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | UnknownObservabilityEvent;
 /**
  * Fired when the protocol-version handshake rejects the connection.
  * Parallel to `UpgradeRequiredError` — the host can choose to render
@@ -72,7 +50,7 @@ export interface SchemaVersionMismatchEvent {
 }
 /**
  * Fired when subscribe fails for any reason the renderer classifies
- * as non-fatal to the session (e.g., transient network jitter that
+ * as non-fatal to the render (e.g., transient network jitter that
  * the reconnect ladder is handling). Terminal subscribe failures
  * still route through `ProtocolError`.
  *
@@ -86,7 +64,7 @@ export interface SubscribeFailedEvent {
 /**
  * Fired when the server emits a `system` frame with
  * `action: 'auth_required'` — the agent needs the end-user to authorize
- * an OAuth service (Google, Slack, etc.) before a wired tool can
+ * an OAuth service (Google, Slack, etc.) before its tool call can
  * proceed. The host listens via `<McpAppIframe onObserve>` and renders
  * a consent overlay OUTSIDE the iframe, then redirects the user to
  * `authUrl` to complete the OAuth flow.
@@ -144,7 +122,7 @@ export interface AuthRequiredEvent {
  */
 export interface ChannelTransportPickedEvent {
     readonly kind: 'channel-transport-picked';
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly channelName: string;
     readonly transport: 'ws' | 'poll';
 }
@@ -159,7 +137,7 @@ export interface ChannelTransportPickedEvent {
  */
 export interface ChannelTransportFallbackEvent {
     readonly kind: 'channel-transport-fallback';
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly channelName: string;
     readonly reason: 'ws-disconnect' | 'channel-not-local';
 }
@@ -171,7 +149,7 @@ export interface ChannelTransportFallbackEvent {
  */
 export interface ChannelTransportResubscribedEvent {
     readonly kind: 'channel-transport-resubscribed';
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly channelName: string;
 }
 /**
@@ -194,7 +172,7 @@ export interface UnknownObservabilityEvent {
  * @public
  */
 export interface ObservabilityMessage {
-    readonly type: 'ggui:observe';
+    readonly type: typeof MCP_APP_OBSERVE_TYPE;
     readonly event: ObservabilityEvent;
 }
 /**

package/dist/observability.js

@@ -1,3 +1,4 @@
+import { MCP_APP_OBSERVE_TYPE } from '@ggui-ai/protocol/integrations/mcp-apps';
 /**
  * Default emitter — posts an {@link ObservabilityMessage} to
  * `window.parent`. Mirrors `postBootFailure` / `postRendererReady`
@@ -17,7 +18,7 @@ export function postObservabilityToParent(event) {
     // install.
     if (typeof window === 'undefined' || window.parent === null)
         return;
-    const message = { type: 'ggui:observe', event };
+    const message = { type: MCP_APP_OBSERVE_TYPE, event };
     try {
         window.parent.postMessage(message, '*');
     }

package/dist/protocol-error.d.ts

@@ -1,16 +1,19 @@
 /**
  * `ProtocolError` typed union — canonical shape for every error the
- * renderer surfaces OUTWARD: to the host page via postMessage, to the
- * session via the `_ggui:contract-error` channel, and to the
- * in-iframe status DOM.
+ * renderer surfaces OUTWARD: to the host page via postMessage and to
+ * the in-iframe status DOM.
  *
  * The transport wiring around this union:
  *
- *   - `postMessage({type:'ggui:protocol-error', error})` for every
- *     boot-path failure; the `_ggui:contract-error` envelope on the
- *     live channel for session-bound failures.
+ *   - Boot-path failures reach the host page via the protocol-owned
+ *     `postMessage({type:'ggui:bootstrap-failed', reason, message})`
+ *     envelope (`MCP_APP_BOOTSTRAP_FAILED_TYPE`). There is NO
+ *     `ggui:protocol-error`
+ *     postMessage envelope — the typed union itself travels only
+ *     through the in-process {@link ProtocolErrorEmitter} seam.
  *   - `<McpAppIframe onError={(err: ProtocolError) => …}>` surfaces
- *     these to embedding apps.
+ *     these to embedding apps (the host wrapper bridges the emitter
+ *     seam / the bootstrap-failed envelope to its `onError` prop).
  *
  * The union is the failure-mode axis of `WireConfig`'s contract:
  * named parties = renderer ↔ host; obligation = the renderer emits a
@@ -25,7 +28,6 @@
  * fields) is fully closed — drift there is a real shape change, not
  * a new code.
  */
-import type { ContractErrorPayload } from '@ggui-ai/protocol';
 import { ClientContractViolationError } from '@ggui-ai/wire';
 /**
  * Closed-or-extensibly-closed union of bootstrap-failure reasons.
@@ -43,7 +45,7 @@ import { ClientContractViolationError } from '@ggui-ai/wire';
  *      / `WS_HANDSHAKE_FAILED`. Matches `RendererBootFailureReason`.
  *
  *   3. **Transport-observable failures** — `BUNDLE_FETCH_FAILED` /
- *      `CSP_VIOLATION` / `RENDER_NOT_FOUND` / `AUTH_REJECTED`. These
+ *      `CSP_VIOLATION` / `SESSION_NOT_FOUND` / `AUTH_REJECTED`. These
  *      fire before the renderer parse path runs, so they're authored
  *      here rather than inside `McpAppAiGguiMetaParseFailureReason`.
  *
@@ -51,7 +53,14 @@ import { ClientContractViolationError } from '@ggui-ai/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' | 'RENDER_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' | 'SESSION_NOT_FOUND' | 'AUTH_REJECTED' | (string & {});
+/**
+ * Pre-ack auth-class error codes — the codes first-party servers
+ * ACTUALLY emit on the WS error frame before `ack` (SPEC §12.2.3).
+ * The phantom `AUTH_REJECTED` / `TOKEN_EXPIRED` arms (no first-party
+ * server ever minted them) were deleted in draft-2026-06-12.
+ */
+export type AuthFailureCode = 'SESSION_NOT_FOUND' | 'BOOTSTRAP_EXPIRED' | 'BOOTSTRAP_INVALID' | 'BOOTSTRAP_SESSION_MISMATCH' | 'BOOTSTRAP_APP_MISMATCH' | 'UNAUTHENTICATED';
 /**
  * Every error the renderer surfaces outward flows through this union.
  *
@@ -60,18 +69,20 @@ export type BootstrapFailureReason = 'MISSING_TOOL_OUTPUT' | 'MISSING_META_GGUI_
  *   - `transport`  — WebSocket-level failure (DISCONNECTED / TIMEOUT).
  *                    Includes `retryable` so hosts can decide to reconnect
  *                    vs. give up.
- *   - `auth`       — session / token rejection pre-handshake.
- *                    `RENDER_NOT_FOUND` / `TOKEN_EXPIRED` /
- *                    `AUTH_REJECTED` — all terminal; hosts typically
- *                    escalate to a login flow.
- *   - `protocol`   — envelope / session-mismatch failures post-handshake.
+ *   - `auth`       — session / ws-token rejection pre-ack, carrying
+ *                    the server's REAL §12.2.3 vocabulary:
+ *                    `SESSION_NOT_FOUND`, the `BOOTSTRAP_*` ws-token
+ *                    family, and `UNAUTHENTICATED`. `BOOTSTRAP_EXPIRED`
+ *                    has a refresh path (`ggui_runtime_refresh_ws_token`);
+ *                    the rest are terminal — hosts typically escalate
+ *                    to a re-render / login flow.
+ *   - `protocol`   — envelope / render-mismatch failures post-handshake.
  *                    Extensibly-closed on `code` because servers may
  *                    introduce new codes without a client bump.
  *                    `details` carries opaque structured context.
- *   - `contract`   — client-contract violation. Payload matches the
- *                    protocol-owned `ContractErrorPayload` so the
- *                    `_ggui:contract-error` envelope shape flows
- *                    unchanged through this variant.
+ *                    Client-side contract violations ride this variant
+ *                    as `code: 'CLIENT_CONTRACT_VIOLATION'` (see
+ *                    {@link fromClientContractViolation}).
  *   - `bootstrap`  — anything in {@link BootstrapFailureReason}.
  *   - `version`    — `UPGRADE_REQUIRED` path (handshake rejection).
  *                    `serverVersion` may be absent on the wire; callers
@@ -87,16 +98,13 @@ export type ProtocolError = {
     readonly message?: string;
 } | {
     readonly kind: 'auth';
-    readonly code: 'RENDER_NOT_FOUND' | 'TOKEN_EXPIRED' | 'AUTH_REJECTED';
+    readonly code: AuthFailureCode;
     readonly message?: string;
 } | {
     readonly kind: 'protocol';
     readonly code: 'SESSION_MISMATCH' | 'APP_MISMATCH' | 'MALFORMED_ENVELOPE' | (string & {});
     readonly message?: string;
     readonly details?: unknown;
-} | {
-    readonly kind: 'contract';
-    readonly payload: ContractErrorPayload;
 } | {
     readonly kind: 'bootstrap';
     readonly reason: BootstrapFailureReason;
@@ -115,9 +123,7 @@ export type ProtocolError = {
  *
  * This is OPTIONAL on every emitter site — the default is a tagged
  * `console.warn` so operators see the error in dev. The
- * `<McpAppIframe>` host wrapper bridges this to its `onError` prop;
- * session-bound variants are ALSO routed to the
- * `_ggui:contract-error` envelope over the WebSocket.
+ * `<McpAppIframe>` host wrapper bridges this to its `onError` prop.
  *
  * Handlers MUST NOT throw — the emitter already fired the renderer's
  * own fallback path; a throwing handler would mask the real error.
@@ -127,7 +133,7 @@ export type ProtocolError = {
 export type ProtocolErrorEmitter = (err: ProtocolError) => void;
 /**
  * Default emitter — operator-visible `console.warn` with a grep-
- * friendly tag. Identical posture to `GguiSession.surfaceContractViolation`'s
+ * friendly tag. Identical posture to `GguiRender.surfaceContractViolation`'s
  * console.warn fallback. Callers override by injecting their own.
  */
 export declare function defaultProtocolErrorEmitter(err: ProtocolError): void;
@@ -137,28 +143,12 @@ export declare function defaultProtocolErrorEmitter(err: ProtocolError): void;
  * outbound action, or when an inbound stream / props payload fails the
  * local validator) onto a `ProtocolError`.
  *
- * Client-side violations do NOT ride the server-emitted
- * `_ggui:contract-error` envelope — that shape (`ContractErrorPayload`)
- * is tool-failure-scoped and authored by the session-channel router.
- * A client-side violation is a DIFFERENT category: nothing reached the
- * tool. We surface it as `{kind: 'protocol'; code:
+ * A client-side violation never left the renderer — nothing reached
+ * the server. We surface it as `{kind: 'protocol'; code:
  * 'CLIENT_CONTRACT_VIOLATION'}` with structured `details` so hosts can
  * render the same summary that `console.warn` would have produced.
- *
- * Server-emitted `ContractErrorPayload` landing on
- * `_ggui:contract-error` rides the separate `{kind: 'contract'}`
- * variant — that path activates when the renderer observes the
- * reserved channel.
  */
 export declare function fromClientContractViolation(err: ClientContractViolationError): ProtocolError;
-/**
- * Wrap a server-emitted `ContractErrorPayload` (received over the
- * reserved `_ggui:contract-error` channel) as the 'contract' variant.
- * Trivial wrapper — exists so call sites produce the union via a
- * factory rather than an object literal (keeps emission uniform and
- * makes grep for creation sites exact).
- */
-export declare function fromContractErrorPayload(payload: ContractErrorPayload): ProtocolError;
 /**
  * Build a `ProtocolError` of kind 'version' from the existing
  * `UpgradeRequiredError` class. Matches the `liftUpgradeRequiredFromError`
@@ -193,7 +183,7 @@ export declare function fromUnknown(raw: unknown): ProtocolError;
  */
 export declare function fromTransportFailure(code: 'DISCONNECTED' | 'TIMEOUT', retryable: boolean, message?: string): ProtocolError;
 /**
- * Build a `ProtocolError` of kind 'auth' — session / token rejection
- * pre-handshake.
+ * Build a `ProtocolError` of kind 'auth' — session / ws-token rejection
+ * pre-ack (see {@link AuthFailureCode}).
  */
-export declare function fromAuthFailure(code: 'RENDER_NOT_FOUND' | 'TOKEN_EXPIRED' | 'AUTH_REJECTED', message?: string): ProtocolError;
+export declare function fromAuthFailure(code: AuthFailureCode, message?: string): ProtocolError;