@ggui-ai/iframe-runtime 0.6.3 → 0.8.0

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { DrainAckPayload, GguiSession } from '@ggui-ai/protocol';
+import type { DrainAckPayload, JsonValue, JsonObject, GguiSession } from '@ggui-ai/protocol';
 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';
@@ -71,6 +71,19 @@ export interface RendererBootFailedMessage extends McpAppBootstrapFailedMessage
     readonly reason: RendererBootFailureReason;
 }
 export interface BootSequenceOptions {
+    /**
+     * Document the boot path mounts into — the render root, and the
+     * toast announcer's live regions.
+     *
+     * MUST be the global `document` in any real deployment. The toast +
+     * cue surface reads the global directly, and production passes the
+     * global here (see `runBootProduction`), so the two are one object.
+     * A caller handing a DIFFERENT document pre-registers the live
+     * regions somewhere no announcement will ever reach; the surface then
+     * falls back to creating them in the global document at the moment of
+     * the first message, which is precisely the same-tick creation that
+     * loses that first announcement.
+     */
     readonly doc: Document;
     /**
      * Spec-canonical {@link App} instance + its {@link Transport}.
@@ -119,14 +132,17 @@ export interface BootSequenceOptions {
      *     emission on UPGRADE_REQUIRED.
      *   - `subscribe-failed` — forwarded from subscribe's emission on
      *     transient reconnect transitions.
-     *   - `auth-required` — fired by the system channel handler when an
-     *     `auth_required` system frame arrives.
      *   - `channel-transport-*` — fired by the channel-transport router
      *     on per-channel transport picks / fallbacks / resubscribes.
      *
-     * Absent = observability emission skipped entirely (matches the
-     * ProtocolError posture; the `<McpAppIframe>` host wrapper decides
-     * whether to bind this via its `onObserve` prop).
+     * Absent = observability emission for the events above is skipped
+     * entirely (matches the ProtocolError posture; the `<McpAppIframe>`
+     * host wrapper decides whether to bind this via its `onObserve`
+     * prop). Exception: `relay-incapability` events do NOT flow through
+     * this seam — they originate in module-level gesture-dispatch code
+     * outside the boot graph (it runs independently of any given boot
+     * call) and always ride the postMessage-to-parent default, whether
+     * or not this option is bound.
      */
     readonly onObserve?: ObservabilityEmitter;
     /**
@@ -204,9 +220,8 @@ export interface RendererHooks {
      * with `StackRenderer`.
      *
      * `onObserve` — optional observability emitter threaded down to
-     * the channel handlers (system `auth-required`) and the
-     * channel-transport router (`channel-transport-*`). Absent = those
-     * sites run silent (the connect-time emission sites —
+     * the channel-transport router (`channel-transport-*`). Absent =
+     * those sites run silent (the connect-time emission sites —
      * `connectViaRegistry`'s version + subscribe events — still fire
      * via their own emitters).
      */
@@ -271,7 +286,7 @@ export interface RendererHandle {
     /**
      * Channel-client registry holding handlers for every WS frame type
      * the iframe routes (`render`, `data`, `props_update`, `drain_ack`,
-     * `channel_payload`, `channel_error`, `system`). The
+     * `channel_payload`, `channel_error`). The
      * registry-bound transport is the sole dispatch surface — frames
      * arrive directly through registered handlers, no longer through a
      * separate `onMessage` callback.
@@ -327,18 +342,39 @@ export declare function readSelfContainedMeta(): McpAppAiGguiRenderMeta | null;
  * no WS at all for spec-compliant MCP-Apps hosts that expose no ggui
  * live channel (claude.ai / ChatGPT / Claude Desktop).
  *
- * Two static-content shapes (the autostart discriminator):
+ * Three static-content shapes (the autostart discriminator), in
+ * priority order:
  *   - `kind`    → a system-card seed (`type:'system'`); no fetch.
+ *   - `codeB64` → a compiled-component seed carried inline; DECODED,
+ *     never fetched. Preferred over `codeUrl` when both are present —
+ *     the inline bytes exist precisely for hosts whose iframe CSP
+ *     blocks the fetch.
  *   - `codeUrl` → a compiled-component seed; fetches the
  *     content-addressable component bytes.
  *
- * Returns `null` when the meta carries NEITHER (a live-only meta has
+ * Returns `null` when the meta carries NONE (a live-only meta has
  * nothing to seed — the first WS ack mounts it). Throws when a `codeUrl`
- * fetch fails so the caller can surface a typed boot failure. The four
- * server-assigned ledger fields are intentionally absent — the first
- * ack reconciles the seed to a full `GguiSession` (no fabrication).
+ * fetch fails or `codeB64` is not valid base64 so the caller can
+ * surface a typed boot failure. The four server-assigned ledger fields
+ * are intentionally absent — the first ack reconciles the seed to a
+ * full `GguiSession` (no fabrication).
  */
 export declare function buildGguiSessionSeedInput(meta: McpAppAiGguiRenderMeta): Promise<GguiSessionSeedInput | null>;
+/**
+ * Does this slice carry STATIC content the mount surface can paint
+ * without any network round-trip authorization — `codeUrl` (fetched),
+ * `codeB64` (decoded inline), or `kind` (built-in registry)?
+ *
+ * The ONE discriminator `bootSequence` consults when deciding whether
+ * the static seed-mount path runs. `codeB64` counting here is
+ * load-bearing for fetch-blocked hosts: their meta carries codeB64
+ * PLUS a live trio the iframe can never connect, and missing the
+ * inline arm would skip the only paint path and die on the dead WS.
+ * Mirrors `validateMeta`'s static-content arm (meta-parse.ts) and the
+ * protocol host-helper's `hasMountModeDiscriminator` — drift among
+ * the three IS the historical bug class, hence the named export.
+ */
+export declare function hasStaticContentMeta(meta: McpAppAiGguiRenderMeta): boolean;
 /**
  * Extract a {@link McpAppAiGguiRenderMeta} from a
  * `ui/notifications/tool-result` JSON-RPC params payload — the
@@ -354,6 +390,25 @@ export declare function buildGguiSessionSeedInput(meta: McpAppAiGguiRenderMeta):
  * impossible because the shell never inspects the slice-meta shape.
  */
 export declare function extractMetaFromToolResult(params: unknown): McpAppAiGguiRenderMeta | null;
+/**
+ * Drain `window.__GGUI_PENDING_TOOL_RESULTS__` — the buffer the
+ * minimal shell populates while messages arrive between
+ * shell-load and runtime-load. Returns the NEWEST valid slice meta
+ * (each new tool-result supersedes the previous — every emission
+ * carries complete state, so last-wins loses nothing). Newest-first
+ * matters on the inline-runtime shell: its preflight completes the
+ * handshake BEFORE the large bundle parses, so a render AND a
+ * follow-up update can both land in the buffer during parse — booting
+ * the oldest would paint stale props and drop the update forever
+ * (buffered entries never reach the post-mount listener; it hears
+ * only post-App arrivals).
+ *
+ * The shell-side buffer contract: an array whose ELEMENTS are the raw
+ * JSON-RPC `params` values of `ui/notifications/tool-result`
+ * notifications, in arrival order (shells cap it newest-biased). The
+ * runtime reads it once at autostart.
+ */
+export declare function readPendingToolResults(): McpAppAiGguiRenderMeta | null;
 /**
  * Render a submit-action's `data` payload as a short inline string
  * for embedding in a `ui/message` consent prompt. Goal: human-
@@ -391,6 +446,45 @@ export declare function emitAudit(args: {
     readonly actionId: string;
     readonly firedAt: string;
 }): void;
+/**
+ * The announcer's two live regions, keyed by politeness (ggui#447).
+ *
+ * Two regions rather than one with a swapped `aria-live`: politeness is
+ * read when a region is REGISTERED, so a screen reader that already
+ * mapped a node as polite is not guaranteed to notice it turning
+ * assertive in the same mutation that delivers the text. Fixed
+ * politeness per node removes the question.
+ */
+interface ToastLiveRegions {
+    /** `role="status"` — queued behind whatever is being read. */
+    readonly polite: HTMLElement;
+    /** `role="alert"` — interrupts. Failure + action-required classes. */
+    readonly assertive: HTMLElement;
+}
+/**
+ * Ensure the pair of live regions the toast surface announces through.
+ *
+ * MUST be called before the first message can land — a live region
+ * created in the same tick as its first content is a region the screen
+ * reader was never watching, and that first announcement is lost. The
+ * boot path calls this at the same point it mounts the render root, so
+ * every toast (at minimum a user gesture away) lands in a region that
+ * has been registered for many frames. The toast + cue paths call it
+ * again defensively; it is idempotent per document.
+ *
+ * Visually hidden rather than `display:none`: a region that is not
+ * rendered is not in the accessibility tree, and content added to it is
+ * never announced. The clip rectangle keeps it out of the visual layout
+ * while leaving it live.
+ *
+ * Returns `null` when the document has no body yet — nothing to attach
+ * to, and no announcement is possible.
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function ensureToastAnnouncer(doc: Document): ToastLiveRegions | null;
+/** @internal — exported for unit tests to reset module state. */
+export declare function __resetRelayNoticeForTest(): void;
 /**
  * Dispatch a submit-action via the empirically-validated bridge
  * chain (validated against claude.ai): a `tools/call` to
@@ -411,6 +505,65 @@ export declare function dispatchSubmitAction(args: {
     readonly sessionId: string;
     readonly appId: string;
 }): void;
+/**
+ * Channel-transport router's `tools/call` invoker (ggui#440) —
+ * iframe-polling transport, `tools/call` against the parent MCP host
+ * via `app.callServerTool` (spec-canonical) when the App handle is
+ * set; falls back to raw postMessage pre-handshake or in tests.
+ * Direct call (no LLM consent loop). Returns the tool's
+ * structuredContent (or `content[0]` if that's where the payload
+ * landed) as a `JsonValue`. On RPC error we throw — the router
+ * catches and silently retries on the next tick.
+ *
+ * Once a REAL gesture has confirmed this host can't relay (the latch
+ * above — set only after {@link dispatchSubmitAction} actually tried
+ * and failed on a host with no `serverTools` advertised, with
+ * capabilities already captured, AND the failure was relay-shaped —
+ * not a well-formed `{ok:false}` result; see `isRelayShapedFailure`),
+ * every subsequent poll will fail identically.
+ *
+ * This guard does NOT stop the router's poll loop, and nothing here
+ * should ever be written so that it could (ggui#443). It does two
+ * things. It makes each doomed tick CHEAP — the poll throws before
+ * the `callServerToolSpec` round-trip. And, by throwing the typed
+ * {@link RelayIncapableError} rather than a bare `Error`, it tells
+ * the router WHICH KIND of failure this is: `channel-transport.ts`'s
+ * tick classifies structural rejections apart from transient ones and
+ * drops the channel to a slow probe cadence, emitting one
+ * `channel-poll-degraded` event per transition. The first poll that
+ * succeeds after the latch clears restores the normal cadence and
+ * emits `channel-poll-recovered`.
+ *
+ * The channel keeps probing throughout, which is what makes that
+ * recovery possible: the latch clears only when a call succeeds, and
+ * only an attempt can discover that. A channel stopped on structural
+ * failure could never come back.
+ *
+ * Keyed on the LATCH, not on `hostCanRelayToolCalls()` directly: raw
+ * advertisement absence never changes after boot, so gating on it
+ * here would throw pre-attempt for the LIFE OF THE SESSION on any
+ * host that under-advertises but genuinely proxies `tools/call`
+ * (ggui's own embed host pre-Task-2 is exactly this case) — silently
+ * killing working channel polls forever. That is "absence of a
+ * capability blocks an attempt", which the fail-safe constraint
+ * forbids. The latch implies `!hostCanRelayToolCalls()` (it only
+ * ever sets inside that guard), so testing it alone is sufficient —
+ * a host that never fails a real gesture never latches, and its
+ * channels keep working.
+ *
+ * Extracted to a named export (rather than an inline closure inside
+ * `bootProduction`) so unit tests can drive it directly through the
+ * lightweight `MockTransport` harness — `bootProduction` dynamic-
+ * imports the full react/design/wire module graph, which is too
+ * heavy to exercise from a spec file (see
+ * `boot-production-context.test.ts`'s docstring for precedent).
+ *
+ * @internal — exported for unit tests + production reuse.
+ */
+export declare function channelToolsCall(args: {
+    readonly toolName: string;
+    readonly args: JsonObject;
+}): Promise<JsonValue>;
 /**
  * Resolve the name of the spec-canonical submit-action receiver tool
  * the dispatch path targets with `tools/call`.