@ggui-ai/iframe-runtime 0.25.0 → 0.27.0

package/dist/runtime.d.ts

@@ -29,14 +29,16 @@ import type { DrainAckPayload, JsonValue, JsonObject, GguiSession } from '@ggui-
 import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
 import { type McpAppAiGguiRenderMeta, type McpAppBootstrapFailedMessage, type McpAppRendererReadyMessage } from '@ggui-ai/protocol/integrations/mcp-apps';
 import type { GguiSessionSeedInput } from './types.js';
-import type { McpAppAiGguiMetaParseFailureReason } from './types.js';
+import type { HeldCredential, McpAppAiGguiMetaParseFailureReason, ViewRoot } from './types.js';
+import type { ViewRootHolder } from './view-root.js';
+import { type StreamSeqTracker } from './stream-seq.js';
 import { App } from '@modelcontextprotocol/ext-apps';
 import type { McpUiDisplayMode } from '@modelcontextprotocol/ext-apps';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { GadgetPackageRegistry } from './globals.js';
 import { StreamBus } from './wire-config.js';
 import { type ChannelTransportRouter } from './channel-transport.js';
-import { ChannelRegistry } from '@ggui-ai/live-channel';
+import type { ChannelHandler } from '@ggui-ai/live-channel';
 import { type TelemetrySink } from './runtime-telemetry.js';
 import { type ConnectFn } from './registry-subscribe.js';
 import { type StatusRefs } from './status-dom.js';
@@ -45,6 +47,7 @@ import type { WireConfig } from '@ggui-ai/wire';
 import { type ProtocolErrorEmitter } from './protocol-error.js';
 import { type ObservabilityEmitter } from './observability.js';
 import { type LifecycleEmitter } from './lifecycle.js';
+import { type ContextSnapshotPoster } from './context-observer.js';
 /**
  * Drain-ack listener registry. Module-scoped so the dispatch path can
  * register a frame-listener without threading it through the renderer.
@@ -337,8 +340,10 @@ export interface BootSequenceOptions {
      * canonical async toolresult) are skipped. The App handshake still
      * runs — spec mandates `ui/initialize` regardless of how slice meta
      * arrives, and `hostContext` is captured from `app.getHostContext()`.
+     * The slice's held credential, when it has one, is refreshed exactly
+     * as a slice this boot resolved itself (ggui#1496).
      */
-    readonly preResolvedMeta?: McpAppAiGguiRenderMeta;
+    readonly preResolved?: BootMeta;
     /**
      * Autostart-layer pre-resolution of the read-plane door (ggui#537):
      * a tool result that arrived before `bootSequence` ran carried the
@@ -347,9 +352,17 @@ export interface BootSequenceOptions {
      * before the App is connected, so the locator is threaded here and
      * resolved via {@link resolveMetaViaReadDoor} right after the
      * handshake, ahead of the Tier 2 tool-result wait. Ignored when
-     * `preResolvedMeta` is set.
+     * `preResolved` is set.
      */
     readonly preResolvedLocator?: string;
+    /**
+     * Test seam for the boot refresh's waits (ggui#1496): the retry delay's
+     * `sleep` and `random`. Defaults to a `setTimeout` wait and `Math.random`.
+     */
+    readonly credentialTiming?: {
+        readonly sleep?: (ms: number) => Promise<void>;
+        readonly random?: () => number;
+    };
     /**
      * How long to wait for the spec-canonical `ui/notifications/tool-result`
      * notification (Tier 2 of the resolver chain) before failing with
@@ -358,6 +371,12 @@ export interface BootSequenceOptions {
      * timeout so the spec doesn't hang.
      */
     readonly toolResultTimeoutMs?: number;
+    /**
+     * Test seam for the view's key root (ggui#1415): the holder the boot and
+     * every later tool result offer their slice's root to. Defaults to the
+     * document's one holder.
+     */
+    readonly viewRoots?: ViewRootHolder;
 }
 /**
  * Renderer hooks. The real iframe boot plumbs these via
@@ -449,20 +468,23 @@ export interface RendererHandle {
      */
     readonly channelTransport: ChannelTransportRouter;
     /**
-     * Channel-client registry holding handlers for every WS frame type
-     * the iframe routes (`render`, `data`, `props_update`, `drain_ack`,
-     * `channel_payload`, `channel_error`). The
-     * registry-bound transport is the sole dispatch surface — frames
-     * arrive directly through registered handlers, no longer through a
+     * The handlers for every frame type the iframe routes (`render`,
+     * `data`, `props_update`, `drain_ack`, `channel_payload`,
+     * `channel_error`). Frames arrive directly through them, not through a
      * separate `onMessage` callback.
      *
-     * `bootSequence` calls `registry.bind(...)` indirectly through the
-     * `connectFn` seam after `setup()` returns. Post-bind, registration
-     * of new handlers is frozen (the registry guards against it); the
-     * `subscribe-handshake` handlers (`ack`, `error`) are added by
-     * `connectViaRegistry` and consumed during handshake resolution.
+     * `bootSequence`'s ladder set (ggui#1496) registers these same objects
+     * on each ladder's registry, one per credential, behind a gate that
+     * lets only the ladder holding the data deliver. `connectViaRegistry`
+     * adds the per-ladder `subscribe-handshake` handlers (`ack`, `error`).
+     */
+    readonly channelHandlers: readonly ChannelHandler[];
+    /**
+     * The view's stream cursor (ggui#1496): the highest stamped `data`
+     * envelope `seq` applied. The `data` handler dedupes on it, and a new
+     * subscribe resumes the stream from it (`fromSeq`).
      */
-    readonly channelRegistry: ChannelRegistry;
+    readonly streamSeq: StreamSeqTracker;
     /**
      * 3rd-party gadget-package merge promise. `installGlobalRegistry`
      * seeds `__ggui__.gadgets` synchronously with the STDLIB namespace;
@@ -488,18 +510,35 @@ export interface BootSequenceResult {
     readonly mountedRender: GguiSession | GguiSessionSeedInput | null;
 }
 export declare function bootSequence(opts: BootSequenceOptions): Promise<BootSequenceResult>;
+/**
+ * A resolved boot slice (ggui#1496): the meta to mount, and the expired
+ * live credential the parse held back from it, when there was one. Every
+ * boot resolver returns this, so the held credential survives every path
+ * to {@link bootSequence}, which refreshes it once through the host.
+ */
+export interface BootMeta {
+    readonly meta: McpAppAiGguiRenderMeta;
+    readonly held?: HeldCredential;
+    /** The slice's view key root, when it carries one (ggui#1415). */
+    readonly viewRoot?: ViewRoot;
+}
+/**
+ * The bridge rung's `tools/call` over the host relay (ggui#1415): every
+ * `ggui_runtime_pull` it sends goes through {@link withViewProof}.
+ *
+ * @internal — exported for unit tests + production reuse.
+ */
+export declare function bridgeCallToolVia(app: App): (name: string, args: Record<string, unknown>) => ReturnType<App['callServerTool']>;
 /**
  * Read `globalThis.__GGUI_META__` synchronously, validate against
- * the unified slice-meta shape, and return the typed meta (or null
+ * the unified slice-meta shape, and return the boot slice (or null
  * on absence / malformation).
  *
- * Thin wrapper around {@link parseMetaFromGlobal}; preserved for
- * back-compat (downstream consumers + tests). Returns `null` instead
- * of {@link McpAppAiGguiMetaParseResult} to match the historical
- * reader contract — the autostart resolver only needs the "valid
- * meta or fall through" signal.
+ * Thin wrapper around {@link parseMetaFromGlobal}. Returns `null`
+ * instead of {@link McpAppAiGguiMetaParseResult} because the autostart
+ * resolver only needs the "a slice to boot, or fall through" signal.
  */
-export declare function readSelfContainedMeta(): McpAppAiGguiRenderMeta | null;
+export declare function readSelfContainedMeta(): BootMeta | null;
 /**
  * Project the inline `__GGUI_META__` bootstrap into a
  * {@link GguiSessionSeedInput} the mount surface can paint immediately,
@@ -565,7 +604,7 @@ export declare function hasStaticContentMeta(meta: McpAppAiGguiRenderMeta): bool
  * lagged the protocol" bug class: shell + runtime drift becomes
  * impossible because the shell never inspects the slice-meta shape.
  */
-export declare function extractMetaFromToolResult(params: unknown): McpAppAiGguiRenderMeta | null;
+export declare function extractMetaFromToolResult(params: unknown): BootMeta | null;
 /**
  * Drain `window.__GGUI_PENDING_TOOL_RESULTS__` — the buffer the
  * minimal shell populates while messages arrive between
@@ -584,7 +623,7 @@ export declare function extractMetaFromToolResult(params: unknown): McpAppAiGgui
  * notifications, in arrival order (shells cap it newest-biased). The
  * runtime reads it once at autostart.
  */
-export declare function readPendingToolResults(): McpAppAiGguiRenderMeta | null;
+export declare function readPendingToolResults(): BootMeta | null;
 /**
  * Sibling of {@link readPendingToolResults} for the read-plane-only
  * posture (ggui#537): the NEWEST buffered tool result that carries a
@@ -607,7 +646,20 @@ export declare function readPendingToolResultLocator(): string | null;
  * slice would be. `null` on any miss (host cannot proxy reads, resource
  * gone, no envelope) — the caller's other tiers still decide.
  */
-export declare function resolveMetaViaReadDoor(app: App, locator: string): Promise<McpAppAiGguiRenderMeta | null>;
+export declare function resolveMetaViaReadDoor(app: App, locator: string): Promise<BootMeta | null>;
+/**
+ * Production {@link ContextSnapshotPoster} — the seam the
+ * context-observer factories consume. Splits the two destinations:
+ *
+ *   - `postUpdateModelContext` → spec-canonical
+ *     `app.updateModelContext(...)` (via {@link callAppUpdateModelContext}).
+ *   - `postContextMirror` → raw `tools/call ggui_runtime_sync_context`
+ *     via {@link postToParent} (the host-relay mirror path; not yet
+ *     migrated to `app.callServerTool` — see emitAudit for the same
+ *     posture).
+ */
+/** @internal — exported for unit tests. */
+export declare const productionContextSnapshotPoster: ContextSnapshotPoster;
 /**
  * Fire a single canonical action envelope (`tools/call
  * ggui_runtime_submit_action`) carrying the typed `{kind, payload, …}` shape
@@ -670,17 +722,21 @@ interface ToastLiveRegions {
  */
 export declare function ensureToastAnnouncer(doc: Document): ToastLiveRegions | null;
 /**
- * Lightweight toast UX surface for dispatched actions. Renders a
- * fixed-position element at the bottom of the iframe so the user
- * gets immediate visual feedback that their gesture was registered
- * — "→ Sending action: archive" → "✓ Queued — agent will react"
- * (or "💬 Sent to chat" on ui/message fallback).
+ * The drawn toast for a dispatched action: a fixed-position element at
+ * the bottom of the iframe, drawn only when the visitor has to know or do
+ * something (the copy is {@link GESTURE_COPY}). Two kinds reach it:
+ *   - `'error'` — the gesture did not go through: the relay refused it or
+ *     could not be reached, or the card's own contract refused it. Nothing
+ *     reached the pipe, so no `ui/message` doorbell fires (SPEC §4.7
+ *     "Failure-soft client posture");
+ *   - `'action_required'` — the gesture is queued but no consumer is
+ *     listening and this host cannot take (or refused) the wake-up, so the
+ *     visitor must send a message to continue.
+ * A tap that went through, or a wake-up the host took, is spoken, never
+ * drawn.
  *
- * Without this, the iframe is silent during dispatch. User clicks
- * and waits, with no way to distinguish "click was received but the
- * agent is busy" from "click was lost". Especially load-bearing in
- * the consume-pipe vs ui/message dual-path era — the toast tells
- * the user which path the gesture actually took.
+ * Without it, a failed gesture would be silent: the visitor could not tell
+ * "the agent is busy" from "the tap was lost".
  *
  * Direct DOM (not React-managed) because:
  *  - Works during boot before React mounts.
@@ -712,6 +768,29 @@ export declare function ensureToastAnnouncer(doc: Document): ToastLiveRegions |
  * @internal — exported for unit tests.
  */
 export declare function declaredActionLabel(render: GguiSession | GguiSessionSeedInput | null, actionName: string): string | undefined;
+/** @internal — exported for unit tests. */
+export declare function isActionSpentByRefusal(renderId: string, actionName: string): boolean;
+/**
+ * ggui#1424 — a post-ack `error` frame from the live channel. The channel
+ * door refuses a second gesture on a spent one-shot with its
+ * CONTRACT_VIOLATION frame and a violation at `actionSpec.<name>.oneShot`;
+ * that one means done, the same as the tool answer. Any other error frame
+ * changes nothing here.
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function handlePostAckErrorFrame(renderId: string, payload: {
+    readonly code: string;
+    readonly message?: string;
+    readonly details?: unknown;
+}): void;
+/**
+ * The toast for a tap the outbound contract check refused (ggui#1536): the
+ * ordinary error toast, named by the action's declared label.
+ *
+ * @internal — exported for unit tests + production reuse.
+ */
+export declare function showRefusedDispatchToast(label: string | undefined): void;
 /**
  * Boot-time reset of the relay latch (ggui#670 Phase 3). A latch
  * standing from a prior mount in a re-booted document is closed through