@ggui-ai/iframe-runtime 0.24.0 → 0.26.0

package/dist/runtime-telemetry.js

@@ -1,24 +1,58 @@
+import { RUNTIME_TELEMETRY_KINDS, } from '@ggui-ai/protocol/runtime-telemetry';
 import { RUNTIME_TELEMETRY_MAX_EVENTS } from '@ggui-ai/protocol/wire';
 const FIRST_FLUSH_DELAY_MS = 4_000;
 const FLUSH_THROTTLE_MS = 8_000;
-const MAX_FLUSHES_PER_SESSION = 12;
+const MAX_HEALTH_FLUSHES_PER_SESSION = 8;
+const MAX_DIAGNOSTIC_FLUSHES_PER_SESSION = 4;
 const MAX_DETAIL_CHARS = 500;
+/** The kind vocabulary (`@ggui-ai/protocol/runtime-telemetry`, ggui#1381), indexed by kind. */
+const SPEC_BY_KIND = new Map(RUNTIME_TELEMETRY_KINDS.map((s) => [s.kind, s]));
+const ID_DETAIL = /^[A-Za-z0-9_.:-]{1,128}$/;
+function isBooleansObject(detail) {
+    let parsed;
+    try {
+        parsed = JSON.parse(detail);
+    }
+    catch {
+        return false;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return false;
+    const values = Object.values(parsed);
+    return values.length > 0 && values.every((v) => typeof v === 'boolean');
+}
+/** The detail a kind may carry, or `undefined` when its shape does not admit this one. */
+function admittedDetail(spec, detail) {
+    if (detail === undefined || spec === undefined)
+        return undefined;
+    switch (spec.detail) {
+        case 'none':
+            return undefined;
+        case 'id':
+            return ID_DETAIL.test(detail) ? detail : undefined;
+        case 'booleans':
+            return detail.length <= MAX_DETAIL_CHARS && isBooleansObject(detail) ? detail : undefined;
+        case 'fields':
+            return detail.slice(0, MAX_DETAIL_CHARS);
+    }
+}
 export function createTelemetrySink(opts) {
     const bootAt = Date.now();
-    const buffer = [];
-    let flushes = 0;
+    const batches = {
+        health: { events: [], flushes: 0, maxFlushes: MAX_HEALTH_FLUSHES_PER_SESSION },
+        diagnostic: { events: [], flushes: 0, maxFlushes: MAX_DIAGNOSTIC_FLUSHES_PER_SESSION },
+    };
+    const order = ['health', 'diagnostic'];
     let timer = null;
     let disposed = false;
     let firstFlushDone = false;
-    const flush = () => {
-        timer = null;
-        if (disposed || buffer.length === 0)
-            return;
-        if (flushes >= MAX_FLUSHES_PER_SESSION)
+    const canFlush = (b) => batches[b].events.length > 0 && batches[b].flushes < batches[b].maxFlushes;
+    const send = (b) => {
+        if (!canFlush(b))
             return;
-        flushes += 1;
-        firstFlushDone = true;
-        const events = buffer.splice(0, buffer.length);
+        const batch = batches[b];
+        batch.flushes += 1;
+        const events = batch.events.splice(0, batch.events.length);
         void opts
             .callTool({
             name: 'ggui_runtime_telemetry',
@@ -29,39 +63,44 @@ export function createTelemetrySink(opts) {
             // cause the failures it exists to report.
         });
     };
+    const flush = () => {
+        timer = null;
+        if (disposed)
+            return;
+        firstFlushDone = true;
+        for (const b of order)
+            send(b);
+    };
     const scheduleFlush = () => {
         if (disposed || timer !== null)
             return;
-        if (flushes >= MAX_FLUSHES_PER_SESSION)
+        if (!order.some(canFlush))
             return;
         timer = setTimeout(flush, firstFlushDone ? FLUSH_THROTTLE_MS : FIRST_FLUSH_DELAY_MS);
     };
-    const record = (kind, detail) => {
+    const append = (kind, detail) => {
         if (disposed)
             return;
-        if (buffer.length >= RUNTIME_TELEMETRY_MAX_EVENTS)
-            buffer.shift();
-        buffer.push({
+        const spec = SPEC_BY_KIND.get(kind);
+        // An unlisted kind (a caller past the types) travels as diagnostic, and without its detail.
+        const batch = batches[spec?.batch ?? 'diagnostic'];
+        if (batch.events.length >= RUNTIME_TELEMETRY_MAX_EVENTS)
+            batch.events.shift();
+        const kept = admittedDetail(spec, detail);
+        batch.events.push({
             at: Math.max(0, Date.now() - bootAt),
             kind: kind.slice(0, 64),
-            ...(detail !== undefined ? { detail: detail.slice(0, MAX_DETAIL_CHARS) } : {}),
+            ...(kept !== undefined ? { detail: kept } : {}),
         });
         scheduleFlush();
     };
-    const fieldsToDetail = (fields) => {
-        try {
-            return JSON.stringify(fields).slice(0, MAX_DETAIL_CHARS);
-        }
-        catch {
-            return '[unserializable]';
-        }
-    };
+    const onChannelEvent = (event) => append(event, undefined);
     return {
-        record,
+        record: (kind, detail) => append(kind, detail),
         channelLogger: {
-            info: (event, fields) => record(event, fieldsToDetail(fields)),
-            warn: (event, fields) => record(event, fieldsToDetail(fields)),
-            debug: (event, fields) => record(event, fieldsToDetail(fields)),
+            info: onChannelEvent,
+            warn: onChannelEvent,
+            debug: onChannelEvent,
         },
         dispose() {
             disposed = true;

package/dist/runtime.d.ts

@@ -29,14 +29,17 @@ 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';
 import { type RendererValidatorContext } from './validation.js';
@@ -44,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.
@@ -92,12 +96,10 @@ export declare function setCurrentApp(app: App): void;
  * the spec's `'light' | 'dark'` literals (dropped, never guessed —
  * the same tolerant posture as `projectHostContext`).
  *
- * This is the INPUT leg of host-theme adaptation
- * (rnd/gen-ui/beauty/experiments/002-host-theme-adaptation.md, ggui#551):
+ * This is the INPUT leg of host-theme adaptation (ggui#551):
  * `hostContext.theme` alone reaches only `data-theme` +
  * `color-scheme` via `applyDocumentTheme` — nothing in the token
- * pipeline keys off it, so a dark host painted the light ladder
- * (host-fit 46.0 vs 87.7 with the dark ladder, probe `cc728a8eb`).
+ * pipeline keys off it, so a dark host painted the light ladder.
  * Under ggui#987 §4 the embedding host OWNS runtime mode: when it
  * announces one, `buildOpts` paints it over every stamped opinion; the
  * stamped layers decide only when the host is silent. Read live from
@@ -338,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
@@ -348,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
@@ -359,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
@@ -450,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 channelRegistry: ChannelRegistry;
+    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 streamSeq: StreamSeqTracker;
     /**
      * 3rd-party gadget-package merge promise. `installGlobalRegistry`
      * seeds `__ggui__.gadgets` synchronously with the STDLIB namespace;
@@ -489,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,
@@ -566,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
@@ -585,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
@@ -608,20 +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>;
 /**
- * Render a submit-action's `data` payload as a short inline string
- * for embedding in a `ui/message` consent prompt. Goal: human-
- * readable, not a JSON dump. Falls back to truncated JSON for
- * nested values so the prompt doesn't drop information silently.
+ * Production {@link ContextSnapshotPoster} — the seam the
+ * context-observer factories consume. Splits the two destinations:
  *
- * Exported for unit-testing — an earlier implementation returned `''`
- * for primitive payloads (strings/numbers/booleans), which silently
- * vaporised the chip's actual text from the consent prompt and made
- * the LLM think every dispatch was a contentless "Please proceed
- * with **<intent>**" request.
+ *   - `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).
  */
-export declare function formatSubmitActionDataInline(data: unknown): string;
+/** @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
@@ -683,6 +721,76 @@ interface ToastLiveRegions {
  * @internal — exported for unit tests.
  */
 export declare function ensureToastAnnouncer(doc: Document): ToastLiveRegions | null;
+/**
+ * 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 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.
+ *  - Doesn't interfere with the component tree the generator owns.
+ *  - Survives React mount transitions inside the iframe.
+ *
+ * Single global toast (per iframe). Auto-dismisses after 2.5s on
+ * `success` / `fallback` outcomes. A successful dispatch draws nothing
+ * here (ggui#1444): its "sending" is spoken only (see
+ * {@link GESTURE_COPY}).
+ *
+ * The visible element is only half the surface (ggui#447). Every
+ * message is also spoken through {@link ensureToastAnnouncer}'s live
+ * regions, and the element itself is hidden from the accessibility
+ * tree so the sentence is not read twice. The one exception is
+ * `action_required`, the only toast the user must OPERATE: it re-enters
+ * the tree as a named button with a tab stop, because a dismissal that
+ * needs a mouse is a dismissal some users cannot perform.
+ *
+ * @internal — runtime-layer concern.
+ */
+/**
+ * The `label` an action declares on the render's `actionSpec`, trimmed, or
+ * `undefined` when the render declares none (or is a system / MCP-Apps
+ * render, which carries no actionSpec). By contract the label is the
+ * control's own copy, so it is the one name for a tap a visitor may read
+ * (see {@link GESTURE_COPY}).
+ *
+ * @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
@@ -694,6 +802,12 @@ export declare function ensureToastAnnouncer(doc: Document): ToastLiveRegions |
  */
 export declare function resetRelayLatchForBoot(): void;
 /** @internal — exported for unit tests to reset module state. */
+/**
+ * Test-only: install the telemetry sink the runtime records into (normally
+ * set once at boot), so a test can observe the events a code path posts.
+ * `null` restores the no-sink state.
+ */
+export declare function __setTelemetrySinkForTest(sink: TelemetrySink | null): void;
 export declare function __resetRelayNoticeForTest(): void;
 /**
  * Dispatch a submit-action via the empirically-validated bridge
@@ -714,6 +828,8 @@ export declare function dispatchSubmitAction(args: {
     readonly data: unknown;
     readonly sessionId: string;
     readonly appId: string;
+    /** The action's declared `label`, when it has one — see {@link GESTURE_COPY}. */
+    readonly label?: string;
 }): void;
 /**
  * Channel-transport router's `tools/call` invoker (ggui#440) —
@@ -809,6 +925,8 @@ export declare function routeDispatch(args: {
         readonly appId: string;
     };
     readonly dispatchToolName: string;
+    /** The action's declared `label` (visitor copy by contract), when it has one. */
+    readonly label?: string;
 }): void;
 /**
  * `ui/open-link` direct dispatch helper — used by the anchor-click