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

package/dist/status-dom.d.ts

@@ -26,7 +26,7 @@
  *   - `initializing` — legacy alias for `idle`.
  *   - `connecting` — ui/initialize fired or WS handshake in flight.
  *   - `connected` — first ack landed + every subsequent successful
- *     push.
+ *     render.
  *   - `reconnecting` — WS dropped; reconnect ladder running.
  *   - `disconnected` — terminal close + ladder exhausted.
  *   - `upgrade-required` — version handshake failed.
@@ -41,21 +41,21 @@ export type StatusKind = 'idle' | 'initializing' | 'connecting' | 'connected' |
  * Refs handed back from {@link ensureStatusDom}. `status` is a detached
  * element kept for backward compatibility with channel handlers that
  * still pass `refs.status` through; it is NEVER appended to the
- * document, so production iframes carry no diagnostic banner. `stack`
- * is the React mount target — appended to `document.body` so renderer
- * wiring has a container.
+ * document, so production iframes carry no diagnostic banner.
+ * `renderRoot` is the React mount target — appended to `document.body`
+ * so renderer wiring has a container.
  */
 export interface StatusRefs {
     readonly status: HTMLElement;
-    readonly stack: HTMLElement;
+    readonly renderRoot: HTMLElement;
 }
 /**
- * Build the React mount target. Reuses pre-existing `[data-ggui-stack]`
- * if the shell already wrote one (cf. `buildSelfContainedShell`); else
- * creates a fresh `<ul data-ggui-stack>` and appends it to `<body>`.
- * The companion `status` element is created detached and never
- * appended — consumers that still pass it through `StatusRefs` see no
- * visible effect.
+ * Build the React mount target. Reuses a pre-existing
+ * `[data-ggui-session-root]` if one was already written; else creates a
+ * fresh `<ul data-ggui-session-root>` and appends it to `<body>`. The
+ * companion `status` element is created detached and never appended —
+ * consumers that still pass it through `StatusRefs` see no visible
+ * effect.
  *
  * The `<ul>` element name is preserved (legacy from the stack-of-N
  * placeholder render path) but only ever holds a single React mount
@@ -72,6 +72,6 @@ export declare function setStatus(refs: StatusRefs, text: string, state: StatusK
  * Log the "connected" transition. Post-stack-removal the iframe always
  * holds exactly one item; the message stays bare ("Connected.") since
  * there's no count to surface. Consumers (devtools, e2e specs
- * intercepting `console.log`) get a stable string on every push.
+ * intercepting `console.log`) get a stable string on every render.
  */
 export declare function setConnectedStatus(refs: StatusRefs): void;

package/dist/status-dom.js

@@ -18,23 +18,23 @@
  * shape.
  */
 /**
- * Build the React mount target. Reuses pre-existing `[data-ggui-stack]`
- * if the shell already wrote one (cf. `buildSelfContainedShell`); else
- * creates a fresh `<ul data-ggui-stack>` and appends it to `<body>`.
- * The companion `status` element is created detached and never
- * appended — consumers that still pass it through `StatusRefs` see no
- * visible effect.
+ * Build the React mount target. Reuses a pre-existing
+ * `[data-ggui-session-root]` if one was already written; else creates a
+ * fresh `<ul data-ggui-session-root>` and appends it to `<body>`. The
+ * companion `status` element is created detached and never appended —
+ * consumers that still pass it through `StatusRefs` see no visible
+ * effect.
  *
  * The `<ul>` element name is preserved (legacy from the stack-of-N
  * placeholder render path) but only ever holds a single React mount
  * subtree post-stack-removal.
  */
 export function ensureStatusDom(doc) {
-    const existingStack = doc.querySelector('[data-ggui-stack]');
-    const stack = existingStack ??
+    const existingRoot = doc.querySelector('[data-ggui-session-root]');
+    const renderRoot = existingRoot ??
         (() => {
             const el = doc.createElement('ul');
-            el.setAttribute('data-ggui-stack', '');
+            el.setAttribute('data-ggui-session-root', '');
             doc.body.appendChild(el);
             return el;
         })();
@@ -44,7 +44,7 @@ export function ensureStatusDom(doc) {
     const status = doc.createElement('div');
     status.setAttribute('data-ggui-status', 'idle');
     status.setAttribute('aria-hidden', 'true');
-    return { status, stack };
+    return { status, renderRoot };
 }
 /**
  * Log a status transition. The element is mutated for backward compat
@@ -61,7 +61,7 @@ export function setStatus(refs, text, state) {
  * Log the "connected" transition. Post-stack-removal the iframe always
  * holds exactly one item; the message stays bare ("Connected.") since
  * there's no count to surface. Consumers (devtools, e2e specs
- * intercepting `console.log`) get a stable string on every push.
+ * intercepting `console.log`) get a stable string on every render.
  */
 export function setConnectedStatus(refs) {
     setStatus(refs, 'Connected.', 'connected');

package/dist/system-cards/NoCredentialsCard.d.ts

@@ -1,7 +1,7 @@
 /**
  * No-credentials system card.
  *
- * Rendered when the server processed a `ggui_render` for a session whose
+ * Rendered when the server processed a `ggui_render` for a render whose
  * LLM credentials are missing or unresolvable. The user needs to open
  * the server's `/settings` page in a real browser tab to paste an API
  * key.

package/dist/system-cards/NoCredentialsCard.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * No-credentials system card.
  *
- * Rendered when the server processed a `ggui_render` for a session whose
+ * Rendered when the server processed a `ggui_render` for a render whose
  * LLM credentials are missing or unresolvable. The user needs to open
  * the server's `/settings` page in a real browser tab to paste an API
  * key.

package/dist/system-cards/ProtocolProbeCard.d.ts

@@ -4,24 +4,20 @@
  * Diagnostic + regression fixture exercising every gesture surface
  * the iframe runtime routes:
  *
- *   1. **Pattern β bridge** — `tools/call ggui_runtime_submit_action` (audit) +
- *      `ui/update-model-context` (silent context) + `ui/message`
- *      (consent prompt). Fires for cross-server / non-app-visible
- *      `actionSpec[name].dispatch.tool` targets, OR any
- *      `dispatch.kind === 'agent'` entry. Empirical-first reproduction
- *      of the production `dispatchWiredAction` path.
- *   2. **Pattern α direct fire** — `tools/call ggui_runtime_submit_action`
- *      (audit) + `tools/call <T>` (direct, no consent prompt). Fires
- *      for same-server, app-visible target tools. Probes against
- *      `ggui_runtime_submit_action` itself (the only universally-app-visible
- *      tool the iframe can be sure exists).
- *   3. **Native-idiom: anchor click** — `ui/open-link` paired with
+ *   1. **Submit-action bridge** — `tools/call ggui_runtime_submit_action`
+ *      (audit) + `ui/update-model-context` (silent context) +
+ *      `ui/message` (consent prompt). Fires for every
+ *      `actionSpec[name]` dispatch — the gesture queues on the
+ *      render's consume pipe for the agent (`nextStep` is an advisory
+ *      hint, never a client-side route). Empirical-first reproduction
+ *      of the production `dispatchSubmitAction` path.
+ *   2. **Native-idiom: anchor click** — `ui/open-link` paired with
  *      `kind: 'openLink'` audit. Triggered by the runtime's
  *      capture-phase `<a href>` interceptor (cross-origin or
  *      `target="_blank"`). The probe row simulates the postMessage
  *      directly so the operator sees the envelope without needing to
  *      click an anchor.
- *   4. **Native-idiom: fullscreen** — `ui/request-display-mode` +
+ *   3. **Native-idiom: fullscreen** — `ui/request-display-mode` +
  *      `kind: 'requestDisplayMode'` audit. Triggered by the runtime's
  *      `Element.prototype.requestFullscreen` /
  *      `Document.prototype.exitFullscreen` overrides. The probe row
@@ -35,8 +31,8 @@
  * host-issued request seen while the card is mounted.
  *
  * Why this lives outside the wire-context: system cards (`kind:
- * 'mcp-apps-probe'`, `'no-credentials'`, …) mount in a render-only
- * branch of `bootSelfContained` that does NOT install
+ * 'mcp-apps-probe'`, `'no-credentials'`, …) mount in render-item's
+ * `kind === 'system'` branch, which does NOT install
  * `<GguiWireProvider>` — they exist precisely to surface protocol
  * state when the wire-context might not be live (auth missing,
  * compile failed, etc.). The probe card mirrors the postMessage
@@ -50,12 +46,12 @@
  * reject `tools/call` from views for tools without `'app'` in
  * visibility — claude.ai silently dropped the call. The original
  * probe diagnosed the gap; the routing simplification work landed
- * Pattern α / Pattern β / native idioms in response.
+ * the submit-action bridge + native idioms in response.
  */
 import * as React from 'react';
 export interface ProtocolProbeCardProps {
     /**
-     * Optional: the original prompt that triggered the probe push.
+     * Optional: the original prompt that triggered the probe render.
      * Surfaced as a footnote so the card matches the framing of other
      * system cards (`NoCredentialsCard`).
      */

package/dist/system-cards/ProtocolProbeCard.js

@@ -5,24 +5,20 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Diagnostic + regression fixture exercising every gesture surface
  * the iframe runtime routes:
  *
- *   1. **Pattern β bridge** — `tools/call ggui_runtime_submit_action` (audit) +
- *      `ui/update-model-context` (silent context) + `ui/message`
- *      (consent prompt). Fires for cross-server / non-app-visible
- *      `actionSpec[name].dispatch.tool` targets, OR any
- *      `dispatch.kind === 'agent'` entry. Empirical-first reproduction
- *      of the production `dispatchWiredAction` path.
- *   2. **Pattern α direct fire** — `tools/call ggui_runtime_submit_action`
- *      (audit) + `tools/call <T>` (direct, no consent prompt). Fires
- *      for same-server, app-visible target tools. Probes against
- *      `ggui_runtime_submit_action` itself (the only universally-app-visible
- *      tool the iframe can be sure exists).
- *   3. **Native-idiom: anchor click** — `ui/open-link` paired with
+ *   1. **Submit-action bridge** — `tools/call ggui_runtime_submit_action`
+ *      (audit) + `ui/update-model-context` (silent context) +
+ *      `ui/message` (consent prompt). Fires for every
+ *      `actionSpec[name]` dispatch — the gesture queues on the
+ *      render's consume pipe for the agent (`nextStep` is an advisory
+ *      hint, never a client-side route). Empirical-first reproduction
+ *      of the production `dispatchSubmitAction` path.
+ *   2. **Native-idiom: anchor click** — `ui/open-link` paired with
  *      `kind: 'openLink'` audit. Triggered by the runtime's
  *      capture-phase `<a href>` interceptor (cross-origin or
  *      `target="_blank"`). The probe row simulates the postMessage
  *      directly so the operator sees the envelope without needing to
  *      click an anchor.
- *   4. **Native-idiom: fullscreen** — `ui/request-display-mode` +
+ *   3. **Native-idiom: fullscreen** — `ui/request-display-mode` +
  *      `kind: 'requestDisplayMode'` audit. Triggered by the runtime's
  *      `Element.prototype.requestFullscreen` /
  *      `Document.prototype.exitFullscreen` overrides. The probe row
@@ -36,8 +32,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * host-issued request seen while the card is mounted.
  *
  * Why this lives outside the wire-context: system cards (`kind:
- * 'mcp-apps-probe'`, `'no-credentials'`, …) mount in a render-only
- * branch of `bootSelfContained` that does NOT install
+ * 'mcp-apps-probe'`, `'no-credentials'`, …) mount in render-item's
+ * `kind === 'system'` branch, which does NOT install
  * `<GguiWireProvider>` — they exist precisely to surface protocol
  * state when the wire-context might not be live (auth missing,
  * compile failed, etc.). The probe card mirrors the postMessage
@@ -51,7 +47,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * reject `tools/call` from views for tools without `'app'` in
  * visibility — claude.ai silently dropped the call. The original
  * probe diagnosed the gap; the routing simplification work landed
- * Pattern α / Pattern β / native idioms in response.
+ * the submit-action bridge + native idioms in response.
  */
 import * as React from 'react';
 import { Card, Stack, Heading, Text, Button, Badge, } from '@ggui-ai/design/primitives';
@@ -190,7 +186,7 @@ function defaultParams(method) {
         case 'ui/request-display-mode':
             return { mode: 'fullscreen' };
         case 'tools/call':
-            // Mirror `runtime.ts::emitAudit` + `runtime.ts::dispatchWiredAction`
+            // Mirror `runtime.ts::emitAudit` + `runtime.ts::dispatchSubmitAction`
             // so this probe empirically validates the canonical
             // `GguiUserActionInput` envelope (SPEC §4.6, see
             // `@ggui-ai/protocol/integrations/mcp-apps`). `ggui_runtime_submit_action`
@@ -200,9 +196,9 @@ function defaultParams(method) {
             // a tool result; the host forwards that result to this iframe
             // via the JSON-RPC response matching our outbound id.
             //
-            // The probe uses `kind: 'dispatch'` so the chained Pattern β
-            // 3-message follow-up (`ui/update-model-context` + `ui/message`)
-            // semantically matches a real wired-action click.
+            // The probe uses `kind: 'dispatch'` so the chained 3-message
+            // follow-up (`ui/update-model-context` + `ui/message`)
+            // semantically matches a real submit-action click.
             return {
                 name: 'ggui_runtime_submit_action',
                 arguments: {
@@ -211,7 +207,7 @@ function defaultParams(method) {
                         intent: 'probe-click',
                         data: { note: 'hello from the protocol probe' },
                     },
-                    renderId: 'probe-render',
+                    sessionId: 'probe-render',
                     appId: 'probe-app',
                     actionId: '00000000', // overwritten in onClick with real FNV-1a
                     firedAt: new Date().toISOString(),
@@ -222,7 +218,7 @@ function defaultParams(method) {
 /**
  * Compute a short deterministic action-id from an action payload.
  * FNV-1a 32-bit, 8 hex chars — not cryptographically strong, just
- * collision-resistant enough for in-flight wired-action correlation.
+ * collision-resistant enough for in-flight submit-action correlation.
  *
  * Why hash (vs. random UUID): the id reproduces from
  * `{intent, data, firedAt}` so both the silent context-update AND
@@ -312,8 +308,8 @@ function ProbeButtonRow({ method, description, call, }) {
                 const args = params
                     .arguments ?? {};
                 // New gesture-envelope shape (SPEC §4.6): `{kind, payload,
-                // renderId, appId, actionId, firedAt}`. For Pattern β the
-                // `payload` carries `{intent, data}`.
+                // sessionId, appId, actionId, firedAt}`. For dispatch
+                // gestures the `payload` carries `{intent, data}`.
                 const payload = args['payload'] ?? {};
                 const intent = String(payload['intent'] ?? '?');
                 const data = payload['data'];
@@ -420,7 +416,7 @@ export function ProtocolProbeCard({ intent, }) {
                             }, children: [_jsx(Heading, { level: 3, children: "MCP Apps protocol probe" }), _jsx(Badge, { variant: "info", children: "diagnostic" })] }), _jsxs(Text, { style: {
                                 color: 'var(--ggui-color-onSurfaceVariant, #52525b)',
                                 lineHeight: '1.55',
-                            }, children: ["One button per primary host effect emitted by the iframe runtime's gesture surfaces (Pattern \u03B1 / Pattern \u03B2 / native- idiom interceptors). Click each to verify which methods this host honors. The", _jsx("code", { children: "tools/call" }), " row chains the full Pattern \u03B2 bridge (audit + context + consent), reproducing the production", _jsx("code", { children: "dispatchWiredAction" }), " envelope shape verbatim. The receive log below captures every notification the host emits while this card is mounted."] })] }), _jsxs(Stack, { gap: "md", children: [_jsx(ProbeButtonRow, { method: "ui/message", description: "Pattern \u03B2 step 3 \u2014 consent-gated user authorization. Host pre-fills + waits for user confirm before the LLM acts on the paired pending-action context.", call: call }), _jsx(ProbeButtonRow, { method: "ui/update-model-context", description: "Pattern \u03B2 step 2 \u2014 silent structured `[ggui:pending-action]` context drop. LLM honors on next turn. No immediate UI.", call: call }), _jsx(ProbeButtonRow, { method: "ui/open-link", description: "Native-idiom anchor click interceptor primary effect. Opens ggui.ai in the host's browser / new tab. Real iframe code triggers via `<a href target='_blank'>` or cross-origin href.", call: call }), _jsx(ProbeButtonRow, { method: "ui/request-display-mode", description: "Native-idiom fullscreen interceptor primary effect. Request fullscreen \u2014 real iframe code calls `el.requestFullscreen()`; the runtime overrides the prototype to route through here.", call: call }), _jsx(ProbeButtonRow, { method: "tools/call", description: "Pattern \u03B2 full bridge: `tools/call ggui_runtime_submit_action` (audit, kind:'dispatch') + `ui/update-model-context` + `ui/message`. Spec \u00A7401 requires `_meta.ui.visibility:['app']` on the receiving tool. Pattern \u03B1 (direct fire to a same-server app-visible target) would skip steps 2+3 and add a second `tools/call` to the target tool instead.", call: call })] }), _jsxs(Stack, { gap: "sm", children: [_jsxs("div", { style: {
+                            }, children: ["One button per primary host effect emitted by the iframe runtime's gesture surfaces (submit-action bridge / native- idiom interceptors). Click each to verify which methods this host honors. The", _jsx("code", { children: "tools/call" }), " row chains the full submit-action bridge (audit + context + consent), reproducing the production ", _jsx("code", { children: "dispatchSubmitAction" }), " envelope shape verbatim. The receive log below captures every notification the host emits while this card is mounted."] })] }), _jsxs(Stack, { gap: "md", children: [_jsx(ProbeButtonRow, { method: "ui/message", description: "Submit-action bridge step 3 \u2014 consent-gated user authorization. Host pre-fills + waits for user confirm before the LLM acts on the paired pending-action context.", call: call }), _jsx(ProbeButtonRow, { method: "ui/update-model-context", description: "Submit-action bridge step 2 \u2014 silent structured `[ggui:pending-action]` context drop. LLM honors on next turn. No immediate UI.", call: call }), _jsx(ProbeButtonRow, { method: "ui/open-link", description: "Native-idiom anchor click interceptor primary effect. Opens ggui.ai in the host's browser / new tab. Real iframe code triggers via `<a href target='_blank'>` or cross-origin href.", call: call }), _jsx(ProbeButtonRow, { method: "ui/request-display-mode", description: "Native-idiom fullscreen interceptor primary effect. Request fullscreen \u2014 real iframe code calls `el.requestFullscreen()`; the runtime overrides the prototype to route through here.", call: call }), _jsx(ProbeButtonRow, { method: "tools/call", description: "Full submit-action bridge: `tools/call ggui_runtime_submit_action` (audit, kind:'dispatch') + `ui/update-model-context` + `ui/message`. Spec \u00A7401 requires `_meta.ui.visibility:['app']` on the receiving tool.", call: call })] }), _jsxs(Stack, { gap: "sm", children: [_jsxs("div", { style: {
                                 display: 'flex',
                                 alignItems: 'baseline',
                                 justifyContent: 'space-between',

package/dist/system-cards/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * System-card registry.
  *
- * Central mapping from `SystemRender.kind` (a stable wire string)
+ * Central mapping from `SystemGguiSession.kind` (a stable wire string)
  * to a real React component bundled inside the iframe-runtime. The
  * runtime's self-contained boot path looks up the kind here when it
  * sees a render with `type: 'system'`. Unknown kinds fall through
@@ -13,7 +13,7 @@
  *   1. Author `MyNewCard.tsx` in this directory.
  *   2. Add an entry to {@link SYSTEM_CARD_REGISTRY} below.
  *   3. (Optional) Add the new kind string to
- *      `SystemRenderKind` in `@ggui-ai/protocol` for IDE autocomplete.
+ *      `SystemGguiSessionKind` in `@ggui-ai/protocol` for IDE autocomplete.
  */
 import * as React from 'react';
 import { NoCredentialsCard, type NoCredentialsCardProps } from './NoCredentialsCard.js';
@@ -28,7 +28,7 @@ import { ProtocolProbeCard, type ProtocolProbeCardProps } from './ProtocolProbeC
 export type SystemCardComponent = React.ComponentType<Record<string, unknown>>;
 /**
  * Registered system-card kinds. Keep keys aligned with
- * `SystemRenderKind` in `@ggui-ai/protocol` so wire + bundle stay
+ * `SystemGguiSessionKind` in `@ggui-ai/protocol` so wire + bundle stay
  * in sync. New kinds added without a registry entry render as
  * {@link UnknownSystemCard}.
  */
@@ -39,8 +39,8 @@ export declare const SYSTEM_CARD_REGISTRY: Record<string, SystemCardComponent>;
  */
 export declare function renderSystemCard(kind: string, props: Record<string, unknown>): React.ReactElement;
 /**
- * Top-level mount component the runtime renders for system stack
- * items. Wraps the resolved card in a {@link ThemeProvider} so design
+ * Top-level mount component the runtime renders for system
+ * renders. Wraps the resolved card in a {@link ThemeProvider} so design
  * tokens (`var(--ggui-*)`) resolve at `:root` even though the host's
  * shell HTML doesn't pre-stamp them. Idempotent across remounts —
  * shares the `ggui-theme-vars` style id with the rest of the design

package/dist/system-cards/index.js

@@ -1,7 +1,7 @@
 /**
  * System-card registry.
  *
- * Central mapping from `SystemRender.kind` (a stable wire string)
+ * Central mapping from `SystemGguiSession.kind` (a stable wire string)
  * to a real React component bundled inside the iframe-runtime. The
  * runtime's self-contained boot path looks up the kind here when it
  * sees a render with `type: 'system'`. Unknown kinds fall through
@@ -13,7 +13,7 @@
  *   1. Author `MyNewCard.tsx` in this directory.
  *   2. Add an entry to {@link SYSTEM_CARD_REGISTRY} below.
  *   3. (Optional) Add the new kind string to
- *      `SystemRenderKind` in `@ggui-ai/protocol` for IDE autocomplete.
+ *      `SystemGguiSessionKind` in `@ggui-ai/protocol` for IDE autocomplete.
  */
 import * as React from 'react';
 import { ThemeProvider, lightTheme, darkTheme } from '@ggui-ai/design/themes';
@@ -64,7 +64,7 @@ function UnknownSystemCard({ kind, props, }) {
 }
 /**
  * Registered system-card kinds. Keep keys aligned with
- * `SystemRenderKind` in `@ggui-ai/protocol` so wire + bundle stay
+ * `SystemGguiSessionKind` in `@ggui-ai/protocol` so wire + bundle stay
  * in sync. New kinds added without a registry entry render as
  * {@link UnknownSystemCard}.
  */
@@ -96,8 +96,8 @@ export function renderSystemCard(kind, props) {
     return React.createElement(UnknownSystemCard, { kind, props });
 }
 /**
- * Top-level mount component the runtime renders for system stack
- * items. Wraps the resolved card in a {@link ThemeProvider} so design
+ * Top-level mount component the runtime renders for system
+ * renders. Wraps the resolved card in a {@link ThemeProvider} so design
  * tokens (`var(--ggui-*)`) resolve at `:root` even though the host's
  * shell HTML doesn't pre-stamp them. Idempotent across remounts —
  * shares the `ggui-theme-vars` style id with the rest of the design

package/dist/types.d.ts

@@ -15,42 +15,33 @@
  * declared the manager's constructor bag has been retired.
  */
 import type { McpAppAiGguiRenderMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
-import type { HostContextProjection, ComponentRender, SystemRender } from '@ggui-ai/protocol';
-/**
- * Post-Phase-B alias kept for ergonomic call sites — the wire-side
- * `McpAppAiGguiRenderMeta` is the single source of truth, and the
- * "validated" qualifier is a no-op now (no nested-optional-session
- * narrowing left after the slice merge). Future callers SHOULD prefer
- * `McpAppAiGguiRenderMeta` directly; the alias persists so the rename
- * sweep can land incrementally without churn at every call site.
- */
-export type ValidatedMcpAppAiGguiMeta = McpAppAiGguiRenderMeta;
+import type { HostContextProjection, ComponentGguiSession, SystemGguiSession } from '@ggui-ai/protocol';
 /**
  * The four server-assigned ledger fields on every wire-delivered
- * {@link Render}. They're stamped by the server's per-render event
+ * {@link GguiSession}. They're stamped by the server's per-render event
  * ledger — NOT derivable from the inline `__GGUI_META__` bootstrap.
  */
-type RenderLedgerFields = 'eventSequence' | 'createdAt' | 'lastActivityAt' | 'expiresAt';
+type GguiSessionLedgerFields = 'eventSequence' | 'createdAt' | 'lastActivityAt' | 'expiresAt';
 /**
  * The mount surface's INPUT contract — what `mountRender` / `applyRender`
- * accept. It is a {@link Render} minus the four server-assigned ledger
- * fields ({@link RenderLedgerFields}), so the runtime can mount the
+ * accept. It is a {@link GguiSession} minus the four server-assigned ledger
+ * fields ({@link GguiSessionLedgerFields}), so the runtime can mount the
  * compiled component (or system card) carried inline by the resource
- * shell BEFORE the authoritative wire `Render` arrives over the WS.
+ * shell BEFORE the authoritative wire `GguiSession` arrives over the WS.
  *
- * A full `Render` is assignable to `RenderSeedInput` (it carries every
+ * A full `GguiSession` is assignable to `GguiSessionSeedInput` (it carries every
  * field plus the ledger), so the WS-ack reconcile path passes a real
- * `Render` here unchanged; the inline-seed path passes the projection
- * built by `buildRenderSeedInput`. We do NOT fabricate the ledger fields
+ * `GguiSession` here unchanged; the inline-seed path passes the projection
+ * built by `buildGguiSessionSeedInput`. We do NOT fabricate the ledger fields
  * (Strict-Typing-First / no-type-laundering) — the first ack replaces
- * the seed with the authoritative `Render`.
+ * the seed with the authoritative `GguiSession`.
  *
- * Carries the SAME contract-spec fields a full `ComponentRender` does
+ * Carries the SAME contract-spec fields a full `ComponentGguiSession` does
  * (`propsSpec` / `streamSpec` / `actionSpec`), as `undefined` on a
  * seed — so the channel handlers that read those after the
  * `type !== 'mcpApps' && type !== 'system'` narrowing stay type-clean.
  */
-export type RenderSeedInput = Omit<ComponentRender, RenderLedgerFields> | Omit<SystemRender, RenderLedgerFields>;
+export type GguiSessionSeedInput = Omit<ComponentGguiSession, GguiSessionLedgerFields> | Omit<SystemGguiSession, GguiSessionLedgerFields>;
 /**
  * Why a slice-meta parse can fail. Closed union — every value is a
  * canonical reason the renderer surfaces to the host via postMessage.
@@ -60,13 +51,16 @@ export type RenderSeedInput = Omit<ComponentRender, RenderLedgerFields> | Omit<S
  * `CSP_VIOLATION`, etc) live on the broader `BootstrapFailureReason`
  * union in `protocol-error.ts`. The four parse-time outcomes:
  *
- *   - `MISSING_TOOL_OUTPUT` — host echoed `ui/initialize` without a
- *     `result.toolOutput` object at all.
- *   - `MISSING_META_GGUI_BOOTSTRAP` — `result.toolOutput` exists but
- *     `_meta["ai.ggui/render"]` is absent. The on-wire synonym is
- *     `BOOTSTRAP_META_MISSING`. (Name retained pre-R4 for the
- *     observability + host-postMessage protocol; cosmetic rename is
+ *   - `MISSING_TOOL_OUTPUT` — the tool-result notification's `params`
+ *     was not an object (no `CallToolResult` to read). (Name predates
+ *     the spec-canonical top-level `_meta` reading; retained for the
+ *     observability + host-postMessage protocol — cosmetic rename is
  *     deferred.)
+ *   - `MISSING_META_GGUI_BOOTSTRAP` — `params` is an object but
+ *     `params._meta` is absent or carries no `ai.ggui/render` slice.
+ *     The on-wire synonym is `BOOTSTRAP_META_MISSING`. (Name retained
+ *     pre-R4 for the observability + host-postMessage protocol;
+ *     cosmetic rename is deferred.)
  *   - `MALFORMED_BOOTSTRAP` — slice is present but fails business
  *     rules (no live mode and no static content, mode discriminators
  *     mutually exclusive, structural rejection by the combiner).
@@ -81,17 +75,18 @@ export type McpAppAiGguiMetaParseFailureReason = 'MISSING_TOOL_OUTPUT' | 'MISSIN
  * bundle).
  *
  * The `ok: true` arm carries the validated {@link McpAppAiGguiRenderMeta}
- * slice and optionally a `hostContext: HostContextProjection`. When the
- * meta is extracted from the `ui/initialize` response (Reading-A path),
- * the parser opportunistically projects the surrounding
- * `McpUiHostContext` into this field so the runtime can:
- *   - drive canvas-mode display-mode escalation
+ * slice and optionally a `hostContext: HostContextProjection`. The
+ * producer is the boot path in `runtime.ts`, which projects
+ * `app.getHostContext()` (the App class's spec-canonical
+ * `ui/initialize` capture plus its `hostcontextchanged` listener)
+ * into this field so the runtime can:
+ *   - drive display-mode escalation (MCP Apps inline/fullscreen/pip)
  *   - echo to the server (live-channel `host_context_observed` envelope)
  *   - feed the agent on next handshake/consume
  *
  * Capture is best-effort: a malformed `HostContext` never blocks the
- * slice parse. Absent for the other extraction paths
- * (`__GGUI_META__` global, `ui/notifications/tool-result`) — those
+ * slice parse. The envelope extractors themselves (`__GGUI_META__`
+ * global, `ui/notifications/tool-result`) never populate it — those
  * envelopes don't carry HostContext.
  */
 export type McpAppAiGguiMetaParseResult = {

package/dist/validation.d.ts

@@ -30,9 +30,8 @@ import type { ActionSpec, ActionEnvelope, ContextSpec, JsonObject, PropsSpec, Re
 import type { CompiledValidatorSet } from './compiled-validators.js';
 /**
  * Install the precompiled validators loaded from the bootstrap. Called
- * once per boot (both `bootProduction` and `bootSelfContained`), after
- * the bootstrap is parsed. A single set per iframe document — one
- * session, one active contract.
+ * once per boot (by `bootSequence`), after the bootstrap is parsed. A
+ * single set per iframe document — one render, one active contract.
  */
 export declare function setActiveValidatorSet(set: CompiledValidatorSet | undefined): void;
 /**
@@ -69,8 +68,8 @@ export declare function validateOutboundActionEnvelope(actionSpec: ActionSpec |
  */
 export declare function validateInboundStreamPayload(streamSpec: StreamSpec | undefined, channelName: string, payload: unknown, ctx: RendererValidatorContext): ValidationResult;
 /**
- * Validate an inbound `props_update` payload before patching a stack
- * item's props. Server already runs `assertPropsContract` on the emit
+ * Validate an inbound `props_update` payload before patching a
+ * render's props. Server already runs `assertPropsContract` on the emit
  * path; this client-side revalidation is defense-in-depth for
  * spec-versioning drift (server snapshot ≠ client cached spec).
  */

package/dist/validation.js

@@ -3,16 +3,15 @@ import { isKnownReservedChannel, validateActionEnvelope, validateContextData, va
 // Active precompiled-validator set
 // =============================================================================
 /**
- * Boot-installed precompiled validators for the active stack item's
+ * Boot-installed precompiled validators for the active render's
  * contract. `undefined` until {@link setActiveValidatorSet} runs (and
  * in unit tests, which exercise the in-iframe compilation fallback).
  */
 let activeValidatorSet;
 /**
  * Install the precompiled validators loaded from the bootstrap. Called
- * once per boot (both `bootProduction` and `bootSelfContained`), after
- * the bootstrap is parsed. A single set per iframe document — one
- * session, one active contract.
+ * once per boot (by `bootSequence`), after the bootstrap is parsed. A
+ * single set per iframe document — one render, one active contract.
  */
 export function setActiveValidatorSet(set) {
     activeValidatorSet = set;
@@ -86,8 +85,8 @@ export function validateInboundStreamPayload(streamSpec, channelName, payload, c
     });
 }
 /**
- * Validate an inbound `props_update` payload before patching a stack
- * item's props. Server already runs `assertPropsContract` on the emit
+ * Validate an inbound `props_update` payload before patching a
+ * render's props. Server already runs `assertPropsContract` on the emit
  * path; this client-side revalidation is defense-in-depth for
  * spec-versioning drift (server snapshot ≠ client cached spec).
  */