@ggui-ai/protocol 0.1.0-rc.1 → 0.2.0-alpha.1

package/dist/integrations/mcp-apps.d.ts

@@ -9,8 +9,9 @@
  * ```ts
  * import {
  *   MCP_APPS_UI_CAPABILITY,
- *   GGUI_SESSION_RESOURCE_URI,
- *   type GguiBootstrapMeta,
+ *   GGUI_RENDER_RESOURCE_URI,
+ *   parseMcpAppAiGguiRenderMeta,
+ *   type McpAppAiGguiRenderMeta,
  * } from '@ggui-ai/protocol/integrations/mcp-apps';
  * ```
  *
@@ -20,7 +21,7 @@
  * drift is bounded to callers that explicitly import from here.
  *
  * Core still carries two fields that make the bootstrap flow work —
- * `SubscribePayload.bootstrap?: string` and `AckPayload.sessionToken?:
+ * `SubscribePayload.bootstrap?: string` and `AckPayload.renderToken?:
  * string`. Those are deliberately framed as **general transport bootstrap
  * credentials** (opaque strings), not MCP-Apps-specific. Any future
  * bootstrap mechanism (short-code auto-login, signed-URL bootstrap, etc.)
@@ -35,26 +36,26 @@ import type { JsonObject, JsonSchema, JsonValue } from '../types/data-contract.j
 export declare const MCP_APPS_UI_CAPABILITY: "io.modelcontextprotocol/ui";
 /**
  * The single MCP Apps resource URI ggui exposes for outbound delivery.
- * `ggui_push` is the sole tool declaration that carries this in its
+ * `ggui_render` is the sole tool declaration that carries this in its
  * `_meta.ui.resourceUri`. No other ggui tool gets a resource URI —
- * `ggui_push` is the single outbound entry point.
+ * `ggui_render` is the single outbound entry point.
  */
-export declare const GGUI_SESSION_RESOURCE_URI: "ui://ggui/session";
+export declare const GGUI_RENDER_RESOURCE_URI: "ui://ggui/render";
 /**
- * MIME type for the `ui://ggui/session` resource. Per MCP Apps spec, UI
+ * MIME type for the `ui://ggui/render` resource. Per MCP Apps spec, UI
  * resources carry the `text/html` base type with a `profile=mcp-app`
  * parameter so hosts that don't support MCP Apps don't accidentally
  * render them as plain HTML.
  */
-export declare const GGUI_SESSION_RESOURCE_MIME: "text/html;profile=mcp-app";
+export declare const GGUI_RENDER_RESOURCE_MIME: "text/html;profile=mcp-app";
 /**
  * The single `_meta.ui.resourceUri` value ggui uses across every MCP Apps
  * host surface. Exposed as a named constant so tool-declaration code,
  * resource-serving code, and tests all agree on one spelling.
  */
-export declare const GGUI_PUSH_UI_META: {
-    /** Resource URI hosts fetch via `resources/read` on a `ggui_push` tool call. */
-    readonly resourceUri: "ui://ggui/session";
+export declare const GGUI_RENDER_UI_META: {
+    /** Resource URI hosts fetch via `resources/read` on a `ggui_render` tool call. */
+    readonly resourceUri: "ui://ggui/render";
     /** Only `"model"` — outer agent can call, iframe views cannot. */
     readonly visibility: readonly ["model"];
 };
@@ -66,525 +67,19 @@ export declare const GGUI_PUSH_UI_META: {
  */
 export type McpAppsToolVisibility = 'model' | 'app';
 /**
- * The bootstrap material an MCP Apps view (iframe) needs to mount a
- * ggui-rendered UI. Lives under `_meta.ggui.bootstrap` on the
- * `ggui_push` tool result — **not** on `structuredContent`.
- *
- * **Not model-visible.** Agents SHOULD NOT consume these fields. They are
- * scoped to the view lifecycle and carry credentials the model has no
- * legitimate use for. The split between `structuredContent` (model-facing)
- * and `_meta.ggui.bootstrap` (view-facing) is the protocol-level isolation
- * that keeps WebSocket credentials out of conversation transcripts.
- *
- * **Three boot modes share this single shape**, distinguished by which
- * of the three optional discriminator fields is populated:
- *
- * | Mode             | Discriminator     | What the view does                                  |
- * | ---------------- | ----------------- | --------------------------------------------------- |
- * | live             | `wsUrl` + `token` | Open live-channel WS, subscribe, render agent frames |
- * | static-component | `codeUrl`         | Fetch + mount compiled React component, no WS       |
- * | system-card      | `kind`            | Mount built-in system card by registry id, no WS    |
- *
- * **Mutual-exclusion contract.** A consumer-acceptable bootstrap MUST
- * carry at least one of `{wsUrl-with-token, codeUrl, kind}`.
- * Multiple may coexist (e.g. a server emitting both `codeUrl`
- * AND `wsUrl+token` lets the runtime pick — current iframe-runtime
- * priority is code-then-system-then-live), but at least one MUST
- * be present. A bootstrap with none is MALFORMED.
- *
- * **Live-mode auth semantics** (only relevant when `wsUrl` + `token`
- * are present):
- *   - `token` is session-scoped, short-TTL, single-use on initial
- *     `subscribe`. Consumed at the first bootstrap-auth'd subscribe and
- *     cannot be reused.
- *   - `expiresAt` lets the view skip an obviously-stale bootstrap without
- *     a round-trip. Servers reject expired tokens anyway; this is UX
- *     sugar, not a security control.
- *   - For reconnects, the view should use the longer-lived `sessionToken`
- *     the server issues on the successful bootstrap-auth ack — see
- *     {@link AckPayload.sessionToken}.
- *
- * **Live-mode example:**
- * ```json
- * {
- *   "sessionId": "sess_001", "appId": "app_001",
- *   "runtimeUrl": "/_ggui/iframe-runtime.js",
- *   "wsUrl": "wss://server.example/ws",
- *   "token": "tok_abc", "expiresAt": "2099-01-01T00:00:00.000Z"
- * }
- * ```
- *
- * **Static-component example:**
- * ```json
- * {
- *   "sessionId": "sess_001", "appId": "app_001",
- *   "runtimeUrl": "/_ggui/iframe-runtime.js",
- *   "codeUrl": "https://server.example/code/sha256:abc.js",
- *   "codeHash": "sha256:abc...",
- *   "themeId": "indigo", "propsJson": "{\"name\":\"Ada\"}"
- * }
- * ```
+ * Phase B render-identity collapse — the previously two-slice wire
+ * (`ai.ggui/session` + `ai.ggui/stack-item`) is merged into ONE slice
+ * (`ai.ggui/render`). Consumers parse with {@link parseMcpAppAiGguiRenderMeta}
+ * and read fields directly off the {@link McpAppAiGguiRenderMeta} struct.
  *
- * **System-card example:**
- * ```json
- * {
- *   "sessionId": "sess_001", "appId": "app_001",
- *   "runtimeUrl": "/_ggui/iframe-runtime.js",
- *   "kind": "loading"
- * }
- * ```
+ * Why the merge: every "session" wrapped exactly one stack item post-
+ * Phase-A, so the two slices were always activated in lock-step. The
+ * pair-holder added ceremony with no signal. Flat is the honest shape.
  */
-export interface GguiBootstrapMeta {
-    /**
-     * WebSocket URL the view opens for live mode (e.g.
-     * `wss://server.example/ws`). REQUIRED in live mode; absent in
-     * static-component and system-card modes. When present, MUST be
-     * paired with a non-empty `token` — half-live (one without the
-     * other) is MALFORMED.
-     */
-    readonly wsUrl?: string;
-    /**
-     * Short-TTL single-use bootstrap token, passed as
-     * `SubscribePayload.bootstrap`. REQUIRED in live mode; absent in
-     * the other modes.
-     */
-    readonly token?: string;
-    /**
-     * ISO 8601 UTC timestamp after which the token is no longer accepted.
-     * Optional; meaningful only in live mode (the token it pairs with
-     * may be unbounded TTL when this is absent).
-     */
-    readonly expiresAt?: string;
-    /**
-     * Session id the token binds to. Repeated here (also present on
-     * `structuredContent.sessionId`) so the view has everything it needs
-     * to subscribe from `_meta.ggui.bootstrap` alone — no need to cross-
-     * reference structuredContent. Keeps the view-side boot code small.
-     */
-    readonly sessionId: string;
-    /**
-     * App (tenant) id the token binds to. Required in the subscribe
-     * payload; not necessarily appropriate for structuredContent
-     * (tenant identity is app-facing bootstrap metadata, not typically
-     * part of an agent's typed output surface).
-     */
-    readonly appId: string;
-    /**
-     * URL of the iframe-runtime bundle the iframe should fetch. The
-     * thin-shell HTML's inline JS dynamically appends
-     * `<script src={runtimeUrl}>` to load the runtime. Server controls
-     * this per-session so the shell works in `srcdoc` iframes (which
-     * have no origin of their own) and across local / cloud
-     * deployments.
-     *
-     * OSS `ggui serve` resolves this to `/_ggui/iframe-runtime.js` —
-     * same-origin as the MCP server's HTTP listener. Hosted cloud
-     * serves from a dedicated CDN route. Either way, the server OWNS
-     * the string; the shell does not guess, concatenate, or fall back
-     * to a bundled default.
-     *
-     * Named parties: **server** produces; **thin shell** consumes;
-     * **iframe runtime bundle** is what the URL resolves to. Failure
-     * mode on fetch error: runtime surfaces a `BUNDLE_FETCH_FAILED`
-     * bootstrap failure via `postMessage({type:'ggui:bootstrap-failed',
-     * reason, message})` to the parent (C8 commit 3). Absent or empty
-     * at parse-time is `BOOTSTRAP_META_MISSING` — the shell rejects
-     * the bootstrap without attempting a script load.
-     *
-     * C8 (2026-04-23) made this required. Pre-C8 servers that emit
-     * bootstraps without `runtimeUrl` are incompatible with the
-     * post-C8 thin-shell HTML — the shell pivot (`~175` → `~30` LOC
-     * wrapper) moved all rendering logic out of the shell into the
-     * separately-served iframe-runtime bundle, so the URL is now
-     * load-bearing.
-     * @public
-     */
-    readonly runtimeUrl: string;
-    /**
-     * Optional polling fallback URL the iframe-runtime fetches when its
-     * WebSocket transport is unavailable or fails. Points at the same
-     * `/api/bootstrap/<shortCode>` endpoint the iframe used to initially
-     * load the bootstrap envelope — polling re-fetches it and the
-     * iframe-runtime diffs the `propsJson` field to synthesize
-     * `props_update` frames for live re-render.
-     *
-     * Empirically required for MCP-Apps hosts whose iframe sandbox
-     * blocks `wss://` at the CSP layer regardless of our
-     * `_meta.ui.csp.connectDomains` declaration (Claude Desktop is the
-     * known case; claude.ai Connector honors WS). Without this field,
-     * polling has no URL to hit and live updates silently no-op when
-     * WS is unavailable.
-     *
-     * Producer: server's `/api/bootstrap/<shortCode>` endpoint stamps
-     * this on the response body — same origin as the request, same
-     * shortCode in the path. Consumer: iframe-runtime threads this
-     * through `createPropsUpdateHandler({pollingUrl})` so
-     * `PollingTransport` has a URL to fetch.
-     *
-     * Absent → no polling fallback. WS-only mode is fine for hosts
-     * whose CSP permits `wss://`.
-     *
-     * @public
-     */
-    readonly pollingUrl?: string;
-    /**
-     * Names of same-server tools whose `_meta.ui.visibility` includes
-     * `"app"` and are therefore directly callable from this iframe via
-     * `tools/call` (per MCP-Apps spec §2026-01-26 Visibility rules:
-     * "app" = callable by the app from the same server connection only;
-     * cross-server tool calls are always blocked).
-     *
-     * Used by the iframe-runtime as a capability fingerprint — telemetry
-     * and debug surfaces consult it to know which tool names are reachable
-     * over the host's same-server `tools/call` path (e.g. the iframe-
-     * internal `ggui_runtime_submit_action` and `ggui_runtime_sync_context`
-     * relays). It is NOT consulted to choose a dispatch routing strategy:
-     * every user gesture flows through `ggui_runtime_submit_action`, lands
-     * on the per-stack-item pending-events pipe, and is drained by the
-     * agent's `ggui_consume` long-poll on the next turn. Actions ALWAYS
-     * drive turns through consume — there is no synchronous server-side
-     * dispatch in agent-mediated deployments.
-     *
-     * Producers SHOULD include every same-server-app-visible tool;
-     * consumers MUST treat an absent field as an empty list (legacy
-     * bootstrap envelopes predating this addition).
-     *
-     * @public
-     */
-    readonly appCallableTools?: readonly string[];
-    /**
-     * Per-action `nextStep` hint mapping for the active stack item's
-     * `actionSpec`. Maps `actionName → toolName` where `toolName` is the
-     * value of `actionSpec[name].nextStep` — the optional hint naming the
-     * tool the agent SHOULD call next when the action fires. Only entries
-     * whose `actionSpec[name].nextStep` is declared are projected; actions
-     * without a hint are omitted from the map.
-     *
-     * Producer: server's push handler at push time, sourced from the
-     * resolved stack item's `actionSpec`. Consumer: iframe-runtime, which
-     * mirrors the hint onto outbound `_meta.ggui.userAction` fall-through
-     * envelopes (the inline variant in {@link InlineUserActionMeta.nextStep})
-     * so the agent gets a strong tool-choice steer when chat-shortcut
-     * fallback fires.
-     *
-     * Absent / empty mapping ⇒ no per-action hints; the iframe omits
-     * `nextStep` from the fall-through envelope and the agent picks the
-     * next tool freely.
-     *
-     * @public
-     */
-    readonly actionNextSteps?: Readonly<Record<string, string>>;
-    /**
-     * Per-slot data for the active stack item's `contextSpec`. Each entry
-     * carries the slot name + the JsonSchema for runtime validation +
-     * optional debounceMs override + optional default value.
-     *
-     * Producer: server's push handler at push time, derived from
-     * `activeStackItem.contextSpec`. Consumer: iframe-runtime, which (at
-     * boot) synthesizes one `React.createContext(default)` per entry and
-     * registers it under `globalThis.__ggui__.contexts[contextName]`. The
-     * boilerplate destructures the registered Contexts so the LLM has
-     * them in scope without any import line.
-     *
-     * Absent → empty list; the runtime synthesizes no Contexts; the
-     * `globalThis.__ggui__.contexts` registry is `{}`.
-     *
-     * @public
-     */
-    readonly contextSlots?: ReadonlyArray<{
-        /** Slot key — camelCase JS identifier from `contextSpec`. */
-        readonly name: string;
-        /** PascalCase Context name auto-derived from `name`. The runtime
-         * uses this as the key in `globalThis.__ggui__.contexts`. The
-         * boilerplate uses it in destructuring lines. */
-        readonly contextName: string;
-        /** JsonSchema for the slot value — used by the runtime observer
-         * to validate Provider values before posting `ui/update-model-context`. */
-        readonly schema: JsonSchema;
-        /** Initial value for the slot's React Context Provider. Always
-         * populated by the server via {@link deriveContextDefault}: the
-         * authored `entry.default` if present, otherwise a schema-typed
-         * fallback (`''` / `0` / `false` / `[]` / `{}` / `null`). The
-         * runtime owns useState per slot, so the Provider seed is load-
-         * bearing — `undefined` here would mean
-         * the iframe boots with an indeterminate Provider value. */
-        readonly default: JsonValue;
-        /** Per-slot debounce override in milliseconds. Omitted → runtime
-         * applies `DEFAULT_CONTEXT_DEBOUNCE_MS` (300). `0` = immediate. */
-        readonly debounceMs?: number;
-    }>;
-    /**
-     * Optional stack-item pin. When present, the renderer binds to a
-     * single `StackItem` (identified by `id`) instead of the full session
-     * stack — enables per-card iframes (per-item session-resource
-     * endpoint + renderer single-item mode).
-     *
-     * Absent → renderer renders the whole session stack (default).
-     * Present → renderer filters to `session.stack.find(i => i.id === stackItemId)`
-     * and ignores the rest. Subsequent live-channel updates for other stack
-     * ids are delivered but not rendered.
-     *
-     * Resource URI convention: per-item shells are served at
-     * `ggui://session/<sessionId>/item/<stackItemId>`; whole-session
-     * shells remain at `ggui://session/<sessionId>`.
-     *
-     * The `stackItemId` is the opaque string MCP hosts receive on a
-     * `ggui_push` tool result's `stackItemId` field (or equivalently the
-     * `StackItem.id` in session state). Renderers that don't recognize
-     * the field SHOULD ignore it (falls back to whole-session rendering)
-     * — shape-preserving extensibility is the contract.
-     *
-     * @public
-     */
-    readonly stackItemId?: string;
-    /**
-     * Content-addressable URL the runtime fetches the compiled ES module
-     * from. The discriminator for **static-component** boot mode (2026-05-13
-     * — the inline base64 `componentCode` channel was retired in favor of
-     * always-by-URL delivery).
-     *
-     * Producer: server. Computes `sha256(componentCode)`, writes the bytes
-     * to its `CodeStore`, then emits the URL here. URL shape is
-     * `<publicBaseUrl>/code/<hash>.js` for OSS or `<cdn>/code/<hash>.js`
-     * for hosted cloud — the renderer doesn't care which origin,
-     * `fetch(codeUrl)` works the same.
-     *
-     * Consumer: iframe runtime. Fetches + dynamic-imports the URL. The
-     * response is `Cache-Control: immutable`, so subsequent pushes with
-     * identical code hit the browser cache (and any CDN edge).
-     *
-     * Mutually exclusive at the discriminator level with `wsUrl+token`
-     * (live mode) and `kind` (system-card mode). When `codeStore` isn't
-     * wired, push falls back to live-mode (wsUrl+token) for delivery via
-     * the live-channel stack update.
-     *
-     * @public
-     */
-    readonly codeUrl?: string;
-    /**
-     * Hex-encoded sha256 of the code bytes the URL serves.
-     * Surfaced separately from `codeUrl` so consumers can verify
-     * content integrity (the URL already encodes it, but parsing the
-     * URL is fragile across CDN configurations) and so the agent can
-     * inspect deduplication signals across pushes without parsing the
-     * URL.
-     *
-     * Always paired with `codeUrl`: present together or absent together.
-     *
-     * @public
-     */
-    readonly codeHash?: string;
-    /**
-     * Discriminator for **system-card** boot mode. Stable identifier the
-     * runtime maps via the system-card registry to a built-in component
-     * (no ESM source on the wire). When present, the view does NOT open
-     * a WebSocket — mounting is purely registry-lookup.
-     *
-     * Mutually exclusive at the discriminator level with `codeUrl`
-     * (static-component mode) and `wsUrl+token` (live mode).
-     *
-     * @public
-     */
-    readonly kind?: string;
-    /**
-     * Theme preset id forwarded to the renderer (`getTheme(id)`).
-     * Optional; absent → renderer uses its baked default theme. Used
-     * by the self-contained shell so `ggui.json#theme` takes effect
-     * across both the WS-driven and self-contained paths.
-     *
-     * @public
-     */
-    readonly themeId?: string;
-    /**
-     * Theme color mode (`'light'` | `'dark'`) forwarded to the renderer.
-     * The runtime resolves the dark variant of {@link themeId} via
-     * `getTheme(id, 'dark')` when set; absent / unknown value falls
-     * back to `'light'`.
-     *
-     * @public
-     */
-    readonly themeMode?: 'light' | 'dark';
-    /**
-     * Pre-serialized props for the rendered component (JSON string).
-     * Optional; absent → renderer falls back to empty props. Carried
-     * as a string to sidestep XSS-defensive escape concerns when the
-     * bootstrap is inlined as a JS literal in the self-contained shell.
-     *
-     * @public
-     */
-    readonly propsJson?: string;
-    /**
-     * Permissions-Policy directive list derived from the active stack item's
-     * `DataContract.clientCapabilities.gadgets[*].permission` field.
-     * Browser-capability names (`'camera'`, `'microphone'`,
-     * `'geolocation'`, `'clipboard-write'`, `'clipboard-read'`,
-     * `'notifications'`, …) or arbitrary identifiers for custom
-     * platforms; the host union-deduplicates and emits these as the
-     * iframe's `Permissions-Policy` HTTP header (public-render path)
-     * or `_meta.ui.permissions` (MCP-Apps embedded path).
-     *
-     * The bootstrap MIRRORS the same list inline so the iframe-runtime
-     * can surface the requested set to in-iframe debug overlays /
-     * permission-aware UI. The BROWSER-enforced gate, however, comes
-     * from the parent-page transport (HTTP header or iframe attribute)
-     * — the iframe-runtime itself cannot change Permissions-Policy
-     * post-load; it can only react to what the parent already granted.
-     *
-     * Absent / empty → no permissions requested (default-deny posture).
-     *
-     * @public
-     */
-    readonly permissionsPolicy?: readonly string[];
-    /**
-     * Mirror of
-     * `handshakeOutput.serverCapabilities.streamWebSocketLocalTools` on
-     * the bootstrap envelope, so the iframe-runtime's per-channel
-     * transport router can decide WS-subscribe vs iframe-polling for
-     * each `streamSpec[ch].source.tool` without re-querying the
-     * handshake.
-     *
-     * Producer: the server's push handler at push time, sourced from
-     * `GguiPushHandlerDeps.streamWebSocketLocalTools` (which mirrors the
-     * resolver on the handshake handler). Consumer: iframe-runtime's
-     * channel-transport module, which:
-     *
-     *   - For each `streamSpec[ch]` with `source.tool` declared AND that
-     *     tool name is in this list → fire a `channel_subscribe` WS
-     *     frame; wait for `channel_payload` deliveries.
-     *   - Otherwise → start a per-channel iframe polling loop (default
-     *     10s cadence) that invokes `tools/call` directly through the
-     *     MCP host proxy.
-     *
-     * Absent ⇒ universal iframe-polling fallback (no channel uses the
-     * WS-subscribe path). Present + empty array ⇒ same behavior; the
-     * empty list still says "the WS-subscribe path is supported but no
-     * tool is local".
-     *
-     * @public
-     */
-    readonly streamWebSocketLocalTools?: readonly string[];
-    /**
-     * When `true`, this bootstrap describes a
-     * SESSION-SCOPED canvas iframe (one per session) rather than a
-     * per-stack-item iframe. The canvas:
-     *
-     *   - Subscribes session-wide on the live channel (no `stackItemId` filter).
-     *   - Renders a navigable stack of items, not a single pinned entry.
-     *   - Owns its own chrome — the ggui animator pill + navbar.
-     *   - Requests `pip` / `fullscreen` display modes from the host based
-     *     on stack state.
-     *
-     * Mutually exclusive with `stackItemId`: a canvas iframe never pins
-     * to a single item. Defensive parsers SHOULD reject bootstraps with
-     * both fields set, but the protocol does not require them to.
-     *
-     * Absent / false ⇒ existing inline iframe behavior. Required to be
-     * explicit (rather than overloading absent-`stackItemId`) because
-     * legacy multi-item mode (Studio/Portal/console) ALSO uses
-     * absent-`stackItemId`; the explicit flag disambiguates.
-     */
-    readonly canvasMode?: boolean;
-    /**
-     * Resolved gadget catalog the iframe-runtime dynamically
-     * imports at boot to populate `globalThis.__ggui__.gadgets`.
-     *
-     * One entry per registered gadget **package** (GG.8.2 — the channel
-     * is per-package, not per-hook: a package's whole module namespace
-     * is loaded once and stored under `__ggui__.gadgets[package]`, so
-     * every hook AND component export the package ships is reachable).
-     * STDLIB exports (the 7 first-party browser-capability hooks shipped
-     * by `@ggui-ai/gadgets`) are seeded unconditionally and need NOT
-     * appear here — only operator-registered 3rd-party packages (Leaflet,
-     * Mapbox, …) do. This list is what makes registered packages
-     * reachable inside the iframe.
-     *
-     * Producer: server's bootstrap builder, sourced from
-     * `App.gadgets`. Consumer: iframe-runtime's
-     * `loadGadgetRegistry()` which `await import(target)`s each
-     * package once and stores the module namespace under the
-     * package-name slot.
-     *
-     * Absent or empty → only STDLIB exports are reachable. Generated
-     * components that import an unregistered gadget package fail at the
-     * iframe's ESM module-eval (the rewriter has no shim for it).
-     *
-     * @public
-     */
-    readonly gadgets?: ReadonlyArray<{
-        /** Bare npm package name (e.g. `@my-org/leaflet`). REQUIRED — it
-         * is the registry key the iframe-runtime stores the loaded module
-         * namespace under at `globalThis.__ggui__.gadgets[package]`, and
-         * the bare-specifier load source when `bundleUrl` is absent. */
-        readonly package: string;
-        /** ggui-hosted ESM bundle URL — preferred load source when present
-         * (same-origin posture, CSP-friendly). The iframe
-         * `await import(this)`; absent → the iframe imports the bare
-         * `package` specifier. */
-        readonly bundleUrl?: string;
-        /** SHA-384 SRI hash of the bundle (`sha384-<base64>`).
-         * When present alongside `bundleUrl`, iframe-runtime routes the
-         * load through a `<link rel="modulepreload" integrity>` gate so
-         * the browser refuses execution on hash mismatch. Absent → fall
-         * back to integrity-less dynamic `import()` (back-compat for
-         * in-tree packages and hand-authored ggui.json refs). */
-        readonly bundleSri?: string;
-    }>;
-    /**
-     * Public env values the iframe-runtime installs at
-     * `globalThis.__ggui__.publicEnv` for wrapper hooks to read via
-     * `getPublicEnv(key)`. Keys MUST match
-     * `PUBLIC_ENV_APP_KEY_RE` (`^GGUI_PUBLIC_APP_[A-Z0-9_]+$` — exported
-     * from `@ggui-ai/protocol`). The prefix is the security boundary:
-     * "public" means visible to anyone with iframe-source access.
-     *
-     * Filtered by the producer (push handler) to the **union of
-     * `wrapper.requires` across declared wrappers** — minimum-disclosure
-     * principle. Keys an iframe's wrappers don't ask for never reach
-     * the iframe.
-     *
-     * Producer: server's bootstrap builder, sourced from
-     * `App.publicEnv` cross-referenced against the declared wrappers'
-     * `requires`. Consumer: iframe-runtime's `installGlobalRegistry`
-     * which plants the map verbatim at `__ggui__.publicEnv`.
-     *
-     * Defensive parse: `parseBootstrap` re-validates every key against
-     * the regex; one bad key collapses the whole field to `undefined`
-     * (matches the `gadgets` / `contextSlots` parser posture).
-     *
-     * Absent or empty → no wrapper-readable env values; only wrappers
-     * with no `requires` declarations can mount.
-     *
-     * @public
-     */
-    readonly publicEnv?: Readonly<Record<string, string>>;
-    /**
-     * Precompiled, eval-free runtime validators for the active stack
-     * item's contract specs. See {@link CompiledContractValidators}.
-     *
-     * Why precompiled: the renderer iframe runs under a strict CSP with
-     * no `'unsafe-eval'`, so it cannot compile JSON Schemas at runtime
-     * (`ajv.compile` builds validators via `new Function`, which the CSP
-     * blocks with `EvalError`). Compilation happens server-side at push
-     * time — where the contract schema is fixed and `eval` is legal —
-     * and the iframe loads each module via a `blob:` dynamic import
-     * (governed by `script-src`, not `unsafe-eval`) and only ever RUNS
-     * the validator.
-     *
-     * Producer: server push handler, via `compileValidatorModule` from
-     * `@ggui-ai/protocol`. Consumer: iframe-runtime's wire + channel
-     * validation layer.
-     *
-     * Absent → no precompiled validators shipped; the iframe falls back
-     * to the server as the sole contract authority (the push-time
-     * `assertActionContract` gate still enforces outbound actions).
-     *
-     * @public
-     */
-    readonly compiledValidators?: CompiledContractValidators;
-}
 /**
  * Precompiled, eval-free validators for a contract's runtime-validated
- * specs — see {@link GguiBootstrapMeta.compiledValidators}.
+ * specs — served at `_meta["ai.ggui/contract"].validatorsUrl` as the
+ * `default` export of a content-addressable ES module.
  *
  * Each value is the SOURCE TEXT of an ES module whose `default` export
  * is an Ajv validator function (`(data) => boolean`, carrying
@@ -627,19 +122,260 @@ export interface CompiledContractValidators {
  */
 export declare function deriveContextName(slotKey: string): string;
 /**
- * Shape of the `_meta` field on a `ggui_push` tool result when the server
- * is the MCP Apps outbound host. Wrapping the bootstrap under `_meta.ggui.*`
- * keeps ggui's namespace distinct from MCP Apps' own `_meta.ui.*` on the
- * tool declaration side.
- *
- * Hosts forward `_meta` alongside `structuredContent` when they pass tool
- * output into `ui/initialize`; the view reads `_meta.ggui.bootstrap` from
- * the initialization context.
+ * `_meta` key carrying the full render slice. Single source of truth
+ * post-Phase-B: identity, boot wiring, live-channel auth, capability
+ * advertisements, current render state, contract pointer, and component-
+ * mode discriminator.
+ *
+ * @public
+ */
+export declare const MCP_APP_AI_GGUI_RENDER_META_KEY: "ai.ggui/render";
+/**
+ * Single entry in the {@link McpAppAiGguiRenderMeta.gadgets} catalog.
+ * One per registered gadget package — the iframe-runtime
+ * dynamic-imports each at boot and stores the loaded namespace under
+ * `globalThis.__ggui__.gadgets[package]`.
+ *
+ * @public
  */
-export interface PushResultMeta {
-    readonly ggui: {
-        readonly bootstrap: GguiBootstrapMeta;
-    };
+export interface McpAppGadgetRef {
+    /** Bare npm package name (e.g. `@my-org/leaflet`). REQUIRED — it
+     * is the registry key the iframe-runtime stores the loaded module
+     * namespace under at `globalThis.__ggui__.gadgets[package]`, and
+     * the bare-specifier load source when `bundleUrl` is absent. */
+    readonly package: string;
+    /** ggui-hosted ESM bundle URL — preferred load source when present
+     * (same-origin posture, CSP-friendly). The iframe `await import(this)`;
+     * absent → the iframe imports the bare `package` specifier. */
+    readonly bundleUrl?: string;
+    /** SHA-384 SRI hash of the bundle (`sha384-<base64>`).
+     * When present alongside `bundleUrl`, iframe-runtime routes the
+     * load through a `<link rel="modulepreload" integrity>` gate so
+     * the browser refuses execution on hash mismatch. */
+    readonly bundleSri?: string;
+}
+/**
+ * Single entry in {@link McpAppAiGguiRenderMeta.contextSlots}.
+ * One per `contextSpec` slot — the iframe-runtime synthesizes one
+ * `React.createContext(default)` per entry at boot.
+ *
+ * @public
+ */
+export interface McpAppContextSlot {
+    /** Slot key — camelCase JS identifier from `contextSpec`. */
+    readonly name: string;
+    /** PascalCase Context name auto-derived from `name`. Used as the
+     * registry key in `globalThis.__ggui__.contexts`. */
+    readonly contextName: string;
+    /** JsonSchema for the slot value — used by the runtime observer to
+     * validate Provider values before posting `ui/update-model-context`. */
+    readonly schema: JsonSchema;
+    /** Initial Provider value. Always populated by the server. */
+    readonly default: JsonValue;
+    /** Per-slot debounce override in milliseconds. Omitted → runtime
+     * applies `DEFAULT_CONTEXT_DEBOUNCE_MS` (300). `0` = immediate. */
+    readonly debounceMs?: number;
+}
+/**
+ * The full render slice — flat post-Phase-B. Identity + boot wiring +
+ * live-channel auth + capability advertisements + render state +
+ * contract pointer + component-mode discriminator.
+ *
+ * **Identity.** `renderId` is the value an iframe's bootstrap meta and
+ * every wire reference (props_update, consume, update) keys by. The
+ * value is the same one stack items carried as `stackItemId` pre-Phase-B;
+ * the rename reflects the conceptual collapse (no enclosing vessel).
+ *
+ * **Live-channel auth.** `wsUrl` + `wsToken` are paired — both present
+ * or both absent; `expiresAt` is informational. `wsToken` is the opaque
+ * WS auth credential the iframe threads on the WebSocket upgrade as
+ * `?wsToken=<encoded>` and inside `SubscribePayload.wsToken`.
+ *
+ * **Polling-fallback URL.** When WS is blocked at the host CSP layer
+ * the iframe polls `pollingUrl` (server-stamped post-Phase-B as
+ * `/api/renders/<renderId>/events?wsToken=<token>`). The iframe-runtime
+ * composes per-tick `&sinceSequence=<cursor>&limit=<N>` against this
+ * base; companion to `lastSequence` which seeds the initial cursor.
+ *
+ * **Mode discriminator.** At least one of `{ codeUrl, kind, wsUrl-with-token }`
+ * MUST be present for the iframe to mount. `kind` and `codeUrl` are
+ * mutually exclusive (kind = system-card mode; codeUrl = static-component
+ * mode; live-channel = absent both).
+ *
+ * @public
+ */
+export interface McpAppAiGguiRenderMeta {
+    readonly renderId: string;
+    readonly appId: string;
+    readonly runtimeUrl: string;
+    readonly wsUrl?: string;
+    readonly wsToken?: string;
+    readonly expiresAt?: string;
+    readonly pollingUrl?: string;
+    readonly themeId?: string;
+    readonly themeMode?: 'light' | 'dark';
+    readonly gadgets?: ReadonlyArray<McpAppGadgetRef>;
+    readonly publicEnv?: Readonly<Record<string, string>>;
+    readonly streamWebSocketLocalTools?: readonly string[];
+    readonly appCallableTools?: readonly string[];
+    readonly permissionsPolicy?: readonly string[];
+    /**
+     * Monotonic sequence number of the most-recent event applied to
+     * this render's event ledger. Stamped on every emission (render,
+     * update, `GET /api/renders/:id/state` read, MCP `resources/read`
+     * of `ui://ggui/render/<id>`). Consumers use it to initialize
+     * polling cursors aligned with the event ledger — see the
+     * `/api/renders/:id/events?sinceSequence=N` endpoint that reads
+     * from a cursor.
+     */
+    readonly lastSequence?: number;
+    readonly propsJson?: string;
+    readonly actionNextSteps?: Readonly<Record<string, string>>;
+    readonly contextSlots?: ReadonlyArray<McpAppContextSlot>;
+    readonly contractHash?: string;
+    readonly validatorsUrl?: string;
+    readonly codeUrl?: string;
+    readonly codeHash?: string;
+    readonly kind?: string;
+}
+/**
+ * Discriminated result of {@link parseMcpAppAiGguiRenderMeta}. The parser
+ * does structural slice-shape validation only — `MALFORMED_RENDER`
+ * surfaces a structurally-invalid slice (wrong type, missing required
+ * identity, paired fields half-present, mutually-exclusive fields both
+ * present). Missing key entirely is NOT a failure; the "is the slice
+ * required for THIS consumer" gate lives in consumer-side mount check.
+ *
+ * @public
+ */
+export type ParseMcpAppAiGguiRenderMetaResult = {
+    readonly ok: true;
+    readonly meta?: McpAppAiGguiRenderMeta;
+} | {
+    readonly ok: false;
+    readonly reason: 'MALFORMED_RENDER';
+};
+/**
+ * Read the `ai.ggui/render` slice off a parsed JSON-RPC `_meta` object.
+ *
+ * Structural validation only. Missing key returns `{ok: true, meta: undefined}`
+ * — not a failure. Required-fields gate (renderId / appId / runtimeUrl)
+ * fires only when the key is present. Field-level optional-field
+ * defensive parsing (e.g. context-slot schema narrowing, expiresAt date
+ * parse) lives downstream in the iframe-runtime's `validateMeta`.
+ *
+ * @public
+ */
+export declare function parseMcpAppAiGguiRenderMeta(meta: unknown): ParseMcpAppAiGguiRenderMetaResult;
+/**
+ * Emitter convenience — wrap a server-built {@link McpAppAiGguiRenderMeta}
+ * slice as the wire `_meta` envelope under the canonical key constant.
+ *
+ * @public
+ */
+export declare function toMcpAppEnvelope(render: McpAppAiGguiRenderMeta): Record<string, unknown>;
+/**
+ * `_meta` key carrying host-supplied conversation-grouping metadata on
+ * every inbound `tools/call` request. Captured ONCE on the first call
+ * that materializes a ggui render row and persisted as opt-in identity
+ * for later rehydration.
+ *
+ * Hosts that don't set this key produce one-shot renders — they work
+ * fine for a single chat turn but cannot be re-listed or restored after
+ * the host closes the conversation surface. Opt-in is the whole design:
+ * hosts that want resume thread their conversation id here; hosts that
+ * don't get the simple write-only path.
+ *
+ * @public
+ */
+export declare const MCP_APP_AI_GGUI_HOST_SESSION_META_KEY: "ai.ggui/host-session";
+/**
+ * Host-supplied conversation-grouping slice. Sent on the request `_meta`
+ * of the first `ggui_*` tool call that creates a ggui render; subsequent
+ * calls naming the same render ignore the field — set-at-creation,
+ * immutable.
+ *
+ * Opaque grouping key, NOT a credential. Auth still comes from the
+ * caller's identity (API key, OAuth bearer, cookie). `hostSessionId`
+ * scopes which renders the authenticated caller can rehydrate; it
+ * does NOT itself authorize access.
+ *
+ * Both fields are required when the slice is present. A slice with a
+ * missing/empty field is treated as absent (degrades to one-shot).
+ *
+ * @public
+ */
+export interface McpAppAiGguiHostSessionMeta {
+    /**
+     * Stable host identifier — e.g. `'sample'`, `'claude.ai'`, `'chatgpt'`.
+     * Used to partition `hostSessionId` namespace so the same chat-id
+     * across two different hosts cannot alias.
+     */
+    readonly hostName: string;
+    /**
+     * Host's grouping key for "this conversation" — opaque to ggui.
+     * Typically: claude.ai thread id, ChatGPT chat id, sample-agent
+     * chatSessionId. The server treats it as an opaque string.
+     */
+    readonly hostSessionId: string;
+}
+/**
+ * Discriminated result of {@link parseMcpAppAiGguiHostSessionMeta}.
+ *
+ * Three outcomes:
+ *   - `ok: true, hostSession: <slice>` — slice present + well-formed.
+ *   - `ok: true, hostSession: undefined` — slice absent (host opted out
+ *     of rehydration). Caller proceeds without it; the render it
+ *     creates is one-shot.
+ *   - `ok: false` — slice present but structurally invalid. Caller's
+ *     choice whether to reject the request or proceed as "absent".
+ *     The handler MAY log + proceed; this is host implementor error,
+ *     not a security boundary.
+ *
+ * @public
+ */
+export type ParseMcpAppAiGguiHostSessionMetaResult = {
+    readonly ok: true;
+    readonly hostSession?: McpAppAiGguiHostSessionMeta;
+} | {
+    readonly ok: false;
+    readonly reason: 'MALFORMED_HOST_SESSION';
+};
+/**
+ * Read the `ai.ggui/host-session` slice off a parsed inbound `_meta`
+ * object. Structural validation only — `hostName` + `hostSessionId`
+ * both required and non-empty. Both missing entirely returns
+ * `{ok: true, hostSession: undefined}` (the documented opt-out path).
+ *
+ * @public
+ */
+export declare function parseMcpAppAiGguiHostSessionMeta(meta: unknown): ParseMcpAppAiGguiHostSessionMetaResult;
+/**
+ * Wire shape of one row in `ggui_list_renders` output. Mirrors the
+ * handler's Zod-described `renders[*]`. Surfaced at the protocol level
+ * so non-handler consumers (sample-agent's `/chat/restore` server, future
+ * host SDK helpers) can import a single typed shape instead of
+ * redeclaring it — preventing drift if the handler ever grows fields.
+ *
+ * `wsToken` + `wsTokenExpiresAt` are populated when the deployment
+ * wired a `mintWsToken` seam on the handler — otherwise the lean
+ * summary path returns them absent.
+ *
+ * Post-Phase-B: `sessionId` → `renderId`; the old `stackItemCount` is
+ * dropped (every render is exactly one item — Phase B collapsed the
+ * vessel).
+ *
+ * @public
+ */
+export interface RenderSummaryWire {
+    readonly renderId: string;
+    readonly hostName?: string;
+    readonly hostSessionId?: string;
+    readonly createdAt: string;
+    readonly lastActivityAt: string;
+    readonly status: string;
+    readonly wsToken?: string;
+    readonly wsTokenExpiresAt?: string;
 }
 /**
  * CSP metadata copied from an MCP Apps resource declaration.
@@ -673,7 +409,7 @@ export interface McpAppsContainerDimensions {
 /**
  * Locator for the source of an embedded MCP App.
  *
- * Persists STABLE identity (not a raw URL) so session state survives
+ * Persists STABLE identity (not a raw URL) so render state survives
  * source-server endpoint changes. The runtime `ConnectorRegistry`
  * resolves `connectorId` to the actual endpoint at render time.
  */
@@ -688,22 +424,21 @@ export interface McpAppsSource {
     readonly resourceUri: string;
 }
 /**
- * Stack-item variant: an embedded third-party MCP App iframe.
+ * Render variant: an embedded third-party MCP App iframe.
  *
  * **Locator-oriented, not content-oriented.** Persisted state carries
  * `source` (connector identity) + declared CSP/permissions/dimensions
- * metadata; resource BYTES are not stored in session state by default.
+ * metadata; resource BYTES are not stored in render state by default.
  * The `@ggui-ai/mcp-server` resource-proxy route fetches the bytes
  * on-demand via `resources/read` against the source server.
  *
- * **Union safety.** Fields that exist on the {@link StackItem}
- * (generated / native component) variant are declared here as
- * `?: never` so consumers that access them via optional chaining on
- * `SessionStackEntry` still typecheck cleanly. Those fields semantically
- * DO NOT exist on McpAppsStackItem — the `?: never` typing encodes the
- * "structurally absent" guarantee.
+ * **Union safety.** Fields that exist on the {@link ComponentRender}
+ * variant are declared here as `?: never` so consumers that access them
+ * via optional chaining on `Render` still typecheck cleanly. Those
+ * fields semantically DO NOT exist on McpAppsRender — the `?: never`
+ * typing encodes the "structurally absent" guarantee.
  */
-export interface McpAppsStackItem {
+export interface McpAppsRender {
     /** Discriminator — required on this variant. */
     readonly type: 'mcpApps';
     readonly id: string;
@@ -717,9 +452,9 @@ export interface McpAppsStackItem {
     readonly containerDimensions?: McpAppsContainerDimensions;
     /**
      * Optional integrity pin — sha256 of the resource bytes computed at
-     * push time. The resource-proxy route verifies the re-fetched
-     * content against this hash; a mismatch breaks the stack item
-     * LOUDLY rather than silently serving mutated content.
+     * render time. The resource-proxy route verifies the re-fetched
+     * content against this hash; a mismatch breaks the render LOUDLY
+     * rather than silently serving mutated content.
      */
     readonly resourceHash?: string;
     /**
@@ -745,18 +480,18 @@ export interface McpAppsStackItem {
     readonly clientCapabilities?: never;
 }
 /**
- * Type guard: narrows a `SessionStackEntry` (or unknown) to
- * {@link McpAppsStackItem}. Uses the discriminator.
+ * Type guard: narrows a `Render` (or unknown) to {@link McpAppsRender}.
+ * Uses the discriminator.
  */
-export declare function isMcpAppsStackItem(entry: unknown): entry is McpAppsStackItem;
+export declare function isMcpAppsRender(entry: unknown): entry is McpAppsRender;
 /**
- * Structural validator for an `McpAppsStackItem` — not a Zod schema
+ * Structural validator for an `McpAppsRender` — not a Zod schema
  * so we don't force a Zod dependency here. Returns null on failure
  * (caller maps to an appropriate error code). Required when accepting
  * one over the wire from an agent: the discriminator alone isn't
  * enough.
  */
-export declare function validateMcpAppsStackItem(input: unknown): McpAppsStackItem | null;
+export declare function validateMcpAppsRender(input: unknown): McpAppsRender | null;
 /**
  * Lifecycle states the renderer transitions through inside an MCP Apps
  * iframe. Closed union — adding a new state is a protocol-version-
@@ -788,7 +523,7 @@ export declare function validateMcpAppsStackItem(input: unknown): McpAppsStackIt
  *   A host that observes only `mounting` and never a follow-up state
  *   has a renderer that crashed before posting code-ready/error.
  * - `code-ready` — happy-path terminal state. Bundle evaluated, React
- *   tree mounted, WS connected, first stack ack folded. Equivalent of
+ *   tree mounted, WS connected, first render ack folded. Equivalent of
  *   the in-iframe `data-ggui-status="connected"`.
  * - `error` — terminal failure. Pairs with the existing
  *   `ggui:bootstrap-failed` postMessage envelope which carries the
@@ -809,9 +544,9 @@ export type McpAppLifecycleState = 'mounting' | 'code-ready' | 'error' | 'discon
  *
  * Fields:
  *   - `state` — required. The lifecycle state being entered.
- *   - `stackItemId` — optional. When present, the lifecycle pertains
- *     to a specific stack item (per-card iframes via single-item
- *     mode). Absent → whole-renderer lifecycle.
+ *   - `renderId` — optional. When present, the lifecycle pertains to a
+ *     specific render (per-card iframes via single-item mode).
+ *     Absent → whole-renderer lifecycle.
  *   - `error` — optional, only meaningful when `state === 'error'`.
  *     Mirrors the `ggui:bootstrap-failed` postMessage envelope's
  *     `reason` + `message` so a single `ggui:lifecycle` listener can
@@ -830,7 +565,7 @@ export type McpAppLifecycleState = 'mounting' | 'code-ready' | 'error' | 'discon
  */
 export interface McpAppLifecycleEvent {
     readonly state: McpAppLifecycleState;
-    readonly stackItemId?: string;
+    readonly renderId?: string;
     readonly error?: {
         readonly code: string;
         readonly message: string;
@@ -914,24 +649,13 @@ export declare const MCP_APP_LIFECYCLE_STATES: readonly McpAppLifecycleState[];
  *   - Outer envelope is an object with `type === 'ggui:lifecycle'`.
  *   - `event` is an object with `state` matching {@link
  *     MCP_APP_LIFECYCLE_STATES}.
- *   - If `stackItemId` is present, it is a non-empty string.
+ *   - If `renderId` is present, it is a non-empty string.
  *   - If `error` is present, it is an object with string `code` +
  *     `message`.
  *
  * @public
  */
 export declare function isMcpAppLifecycleMessage(message: unknown): message is McpAppLifecycleMessage;
-/**
- * Type guard for recognizing a `ggui_push` result `_meta` that carries a
- * bootstrap block. Handy for views / tests that receive the raw result.
- *
- * Validates the three-mode discriminator: a well-formed bootstrap MUST
- * carry `runtimeUrl` + `sessionId` + `appId` AND at least one of
- * `{wsUrl, codeUrl, kind}` as a non-empty string. Live mode
- * additionally requires `token` to pair with `wsUrl` — half-live
- * (one without the other) is rejected as MALFORMED.
- */
-export declare function hasPushBootstrapMeta(meta: unknown): meta is PushResultMeta;
 /**
  * Discriminator for the user-action envelope delivered via
  * `ggui_runtime_submit_action` over the MCP Apps host-relay path
@@ -957,7 +681,7 @@ export declare function hasPushBootstrapMeta(meta: unknown): meta is PushResultM
  * Audit is **fail-soft** at the client: if the `tools/call` envelope
  * fails to deliver (host rejects, postMessage on detached parent), the
  * primary host effect MUST still proceed. The audit miss surfaces as a
- * diagnostic on the operator side (gap in the SessionInspector activity
+ * diagnostic on the operator side (gap in the RenderInspector activity
  * row), not as a user-facing failure. This mirrors today's `dispatch`
  * audit-fire posture so semantics stay uniform.
  *
@@ -1023,21 +747,26 @@ export type SubmitActionEnvelope = {
  * Per-kind semantics:
  *
  *   - `kind === 'dispatch'`: server appends a consume-entry onto the
- *     stackItem-keyed pending-events pipe (`{type:'action', stackItemId,
+ *     render-keyed pending-events pipe (`{type:'action', renderId,
  *     intent, actionData, uiContext, actionId, firedAt}`) so the agent's
- *     `ggui_consume` long-poll unblocks in the same chat turn. When the
- *     pipe is closed/missing (popped/closed/never opened), the handler
- *     returns `{ok:false, code:'PIPE_NOT_FOUND'}` and the iframe-runtime
- *     falls through to a `ui/message` envelope carrying
- *     `_meta.ggui.userAction` (see {@link GguiUserActionMeta}) so the
- *     gesture still reaches the agent on its next turn.
+ *     `ggui_consume` long-poll unblocks in the same chat turn. The
+ *     handler's response carries `consumerPresent` — whether a
+ *     `ggui_consume` long-poll is currently listening on this render's
+ *     pipe. When `consumerPresent === false` (no loop is listening —
+ *     e.g. the agent's persistent consume loop ended after a page
+ *     reload), the iframe-runtime ALSO emits a `ui/message` doorbell
+ *     carrying `content[0]._meta["ai.ggui/userAction"]` (see
+ *     {@link GguiUserActionMeta}) so a fresh agent turn calls
+ *     `ggui_consume({renderId})` to drain the just-enqueued gesture.
+ *     The doorbell is a PURE POINTER — the gesture stays solely on the
+ *     pipe, making the action exactly-once.
  *   - `kind ∈ {'openLink','requestDisplayMode'}`: pure audit — the
  *     user-visible host effect already fired iframe-side via
  *     `ui/open-link` / `ui/request-display-mode`. The server records
- *     the gesture for the SessionInspector feed.
+ *     the gesture for the RenderInspector feed.
  *
  * Required fields:
- *   - `sessionId` / `appId`: bootstrap-issued; server cross-checks.
+ *   - `renderId` / `appId`: bootstrap-issued; server cross-checks.
  *   - `actionId`: 8-hex correlation hash (FNV-1a of intent + data + firedAt
  *     for `dispatch`, kind + payload + firedAt for the host-control kinds).
  *     Lets the host LLM cross-verify a `[ggui:pending-action]` context entry
@@ -1050,17 +779,7 @@ export type SubmitActionEnvelope = {
  * shape — see {@link SubmitActionEnvelope}.
  */
 export type GguiSubmitActionInput = SubmitActionEnvelope & {
-    readonly sessionId: string;
-    /**
-     * Active stack item id. Optional because the iframe-runtime boots
-     * into a stack-item context only when the host minted one via
-     * `ggui_push` — boot scenarios like system-cards or pre-push
-     * provisional previews don't carry one. Required when
-     * `kind === 'dispatch'` (the kind that needs to land in the
-     * stackItem-keyed pending-event pipe); the server-side handler
-     * rejects dispatch envelopes missing this field.
-     */
-    readonly stackItemId?: string;
+    readonly renderId: string;
     readonly appId: string;
     readonly actionId: string;
     readonly firedAt: string;
@@ -1085,134 +804,58 @@ export declare const SUBMIT_ACTION_KINDS: readonly ["dispatch", "openLink", "req
  */
 export declare function isGguiSubmitActionInput(value: unknown): value is GguiSubmitActionInput;
 /**
- * Discriminator the iframe-runtime stamps on a `ui/message` envelope's
- * `params._meta.ggui.userAction` when a user gesture inside a ggui-
- * rendered iframe needs to flow to the agent through chat (rather than
- * direct WS drain via `ggui_consume`).
- *
- * Discriminated by `kind`:
- *
- *   - **`'queued'`** — pipe HAS the event; agent should call
- *     `ggui_consume({stackItemId})` to drain. The prepared call lives
- *     in `nextStep` as `{tool: 'ggui_consume', args: {stackItemId}}`
- *     so the SDK can dispatch verbatim without arg-construction.
- *
- *   - **`'inline'`** — pipe is GONE (popped / session closed / never
- *     opened). Action data is carried inline in `payload`. The agent
- *     MUST act on this directly; calling `ggui_consume` for this
- *     `stackItemId` would return empty.
- *
- * The accompanying `ui/message` text mirrors the structure in human-
- * readable form so agnostic LLMs without `_meta` awareness still get
- * the right instruction.
- *
- * **Presence is the fingerprint** — agnostic hosts ignore the field;
- * ggui-aware consumers route via {@link isGguiUserActionMeta}.
- *
- * Unified shape with a `kind` discriminator (`queued` | `inline`)
- * parallels the protocol's other discriminated unions, e.g.
- * {@link SubmitActionEnvelope}'s `kind`.
- *
- * @public
- */
-export type GguiUserActionMeta = QueuedUserActionMeta | InlineUserActionMeta;
-/**
- * `_meta.ggui.userAction` variant — pipe has the event; agent dispatches
- * the prepared `ggui_consume` call to drain. See {@link GguiUserActionMeta}.
+ * `content[0]._meta["ai.ggui/userAction"]` — a PURE DOORBELL.
+ *
+ * Spec-canonical extension point: MCP Apps closes `params._meta` via
+ * `additionalProperties: false`, but each content block has its own
+ * open `_meta` record (per the base MCP spec). The `ai.ggui/*` key
+ * prefix matches our other protocol extensions
+ * (`ai.ggui/render`, `ai.ggui/bootstrap`, etc.).
+ *
+ * Stamped by the iframe-runtime on a `ui/message` envelope when a user
+ * gesture needs to wake the agent because no `ggui_consume` long-poll is
+ * currently listening (the agent's persistent consume loop has ended —
+ * e.g. after a page reload). The gesture itself was ALREADY enqueued onto
+ * the render's server-side pending-event pipe by the iframe's
+ * `ggui_runtime_submit_action` call (relayed by the host) BEFORE this
+ * notification fired; this slice's only job is to make a fresh agent turn
+ * call `ggui_consume({renderId})` to drain it.
+ *
+ * SINGLE SOURCE OF TRUTH: the pending-event queue. This slice carries ONLY
+ * a pointer to the render whose queue holds the gesture — never the action
+ * payload. The agent retrieves the action EXCLUSIVELY via `ggui_consume`.
+ * Carrying the payload here would let the agent both act on it AND drain
+ * the queue = a double-trigger; the pointer-only shape makes the action
+ * exactly-once.
+ *
+ * `intent` is metadata (which `actionSpec[*]` entry fired) — NOT the
+ * actionable data. The agent can't react meaningfully on `intent` alone
+ * (it lacks the `actionData` payload), so its presence doesn't tempt a
+ * pre-consume action.
+ *
+ * **The directive lives in the `ui/message` TEXT, not here.** The
+ * iframe-runtime authors a `ui/message` whose human-readable text
+ * carries the full "call `ggui_consume`" directive — that text is what
+ * EVERY host (claude.ai, chatgpt.com, ggui-aware SDKs) forwards to the
+ * model. This `_meta` slice is the OPTIONAL structured mirror for
+ * ggui-aware programmatic consumers; an `_meta`-agnostic host ignores
+ * it and acts on the text alone. No part of the loop depends on a
+ * server-side parse of this slice.
  *
  * @public
  */
-export interface QueuedUserActionMeta {
-    readonly kind: 'queued';
-    /**
-     * Human-readable one-liner summary for logs / SDK debug surfaces.
-     * Mirrors the chat-visible text but as a structured field so
-     * consumers don't need to parse natural language.
-     */
+export interface GguiUserActionMeta {
+    readonly kind: 'user-action';
     readonly description: string;
-    /** Stack item the gesture targeted. */
-    readonly stackItemId: string;
-    /** 8-hex FNV-1a correlation id of the gesture. */
+    readonly renderId: string;
     readonly actionId: string;
-    /** ISO 8601 UTC timestamp of the gesture (iframe local clock). */
     readonly submittedAt: string;
-    /** Which `actionSpec[*]` entry the iframe dispatched against. */
     readonly intent: string;
-    /**
-     * Prepared tool call the agent SHOULD dispatch verbatim. Embeds the
-     * `stackItemId` so the SDK doesn't have to thread it manually —
-     * reduces "wrong/missing args" failure modes.
-     */
     readonly nextStep: {
         readonly tool: 'ggui_consume';
         readonly args: {
-            readonly stackItemId: string;
+            readonly renderId: string;
         };
     };
 }
-/**
- * `_meta.ggui.userAction` variant — pipe is gone; action + ui context
- * delivered inline. Agent acts on `payload` directly; MUST NOT call
- * `ggui_consume` for `stackItemId` (no pipe to drain).
- *
- * `nextStep` is optional — when the original `actionSpec[intent]` declared
- * a `nextStep` (the bound agent tool), it's surfaced here as a string
- * hint so the LLM has a strong steer toward the right tool. When the
- * contract author left `nextStep` undeclared, the agent is fully free
- * to choose how to react.
- *
- * @public
- */
-export interface InlineUserActionMeta {
-    readonly kind: 'inline';
-    /**
-     * Human-readable one-liner summary for logs / SDK debug surfaces.
-     */
-    readonly description: string;
-    /** Stack item the gesture targeted. */
-    readonly stackItemId: string;
-    /** 8-hex FNV-1a correlation id of the gesture. */
-    readonly actionId: string;
-    /** ISO 8601 UTC timestamp of the gesture (iframe local clock). */
-    readonly submittedAt: string;
-    /** Which `actionSpec[*]` entry the iframe dispatched against. */
-    readonly intent: string;
-    /**
-     * Both halves of the gesture, captured atomically at gesture time:
-     *
-     *   - `actionData` — typed payload satisfying `actionSpec[intent].schema`.
-     *                    `null` for no-payload gestures (bare button click).
-     *   - `uiContext`  — snapshot of the iframe's contextSpec values at
-     *                    the moment the user fired the gesture. Typed by
-     *                    the contract's `contextSpec`.
-     *
-     * The pair is the SEMANTIC UNIT — what the user did AND what they
-     * were looking at when they did it. Captured at gesture time (not
-     * drain time) for honest history.
-     */
-    readonly payload: {
-        readonly actionData: JsonValue | null;
-        readonly uiContext: JsonObject;
-    };
-    /**
-     * Optional hint: the agent tool the original `actionSpec[intent].nextStep`
-     * declared. Present when the contract bound this intent to a specific
-     * tool; absent when the author left it free. The agent reads this as
-     * a strong suggestion, not a binding directive (in the inline case
-     * the LLM composes the call, including any context-derived args).
-     */
-    readonly nextStep?: string;
-}
-/**
- * Type guard for {@link GguiUserActionMeta}. Validates the
- * discriminated shape on a `ui/message` envelope's
- * `params._meta.ggui.userAction` field.
- *
- * Designed for `_meta.ggui.userAction`-aware consumers (sample agent
- * dispatcher, e2e assertions, future SDKs) to route deterministically
- * without speculative shape coercion.
- *
- * @public
- */
-export declare function isGguiUserActionMeta(meta: unknown): meta is GguiUserActionMeta;
 //# sourceMappingURL=mcp-apps.d.ts.map