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

package/dist/events-polling.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Registry-level events-polling composition for the iframe-runtime (R7).
+ *
+ * The R7 cursor-replay model — paired transport of the
+ * `/api/renders/:renderId/events?sinceSequence=N&limit=100` HTTP endpoint
+ * + the WS subscribe `sinceSequence` cursor. Both transports replay
+ * from the same RenderEvent ledger; the polling client uses HTTP, the
+ * live client uses WS, and they SHARE the cursor model. Switching
+ * transports does not lose events.
+ *
+ * Semantics (vs. R6 snapshot-polling):
+ *   - **URL** — `/api/renders/<renderId>/events?wsToken=<token>` with
+ *     `sinceSequence` and `limit` added per tick.
+ *   - **Interval** — fixed 2000ms (mirrors R6's default).
+ *   - **parseSnapshot** — reads the `EventsResponse` envelope, dispatches
+ *     each event by `event.type` to the registered ChannelHandler (e.g.
+ *     `render` → render handler; `props_update` → props_update handler),
+ *     and advances the cursor to `lastSequence`.
+ *   - **REPLAY_HORIZON_PASSED** — when the server returns 410 the
+ *     parser can't fold; the consumer must re-mount from a fresh
+ *     `/state` snapshot. Today the polling transport's `parseSnapshot`
+ *     only sees the body, so we emit a synthetic `error` frame for the
+ *     registry to surface upward.
+ *
+ * # Anthropic first-mount race fix
+ *
+ * Iframes mounted inside the Anthropic SDK lose `__GGUI_META__` because
+ * the SDK strips `_meta` from `tools/call` responses before forwarding
+ * the structured-content shell to the iframe. R5's documented gap was
+ * that the first push's payload never reached the iframe.
+ *
+ * R7's principled fix: the same /events endpoint that powers polling
+ * ALSO serves the cold-mount path. An iframe booting without inline
+ * meta calls `/events?sinceSequence=0&limit=1` to fetch the first
+ * render event from the ledger; the wsToken comes from the iframe's
+ * URL query string (the server stamps it on the resource URI when
+ * minting the render tool result, preserved across the Anthropic SDK
+ * strip). One unified cursor model handles cold-mount, polling
+ * fallback, and live updates.
+ */
+import type { RegistryPollingOptions } from '@ggui-ai/live-channel';
+export interface BuildEventsPollingOptions {
+    /**
+     * Base URL the polling tick reads from. The composer appends
+     * `&sinceSequence=<cursor>&limit=<limit>` per tick. Typically the
+     * `/api/renders/<renderId>/events?wsToken=<token>` URL the iframe
+     * derived from the render slice. Must already include a `?` or `&`
+     * separator-ready terminator; we add the cursor params with
+     * `&` if the URL contains `?`, else `?`.
+     */
+    readonly baseUrl: string;
+    /**
+     * Optional cursor seed — initial value of `sinceSequence` on the
+     * first tick. Typically threaded from `render.lastSequence` so the
+     * cold-mount-after-WS-fail path picks up where the snapshot left
+     * off. Defaults to `0` (replay everything still retained).
+     */
+    readonly initialSinceSequence?: number;
+    /**
+     * Optional poll cadence override. Defaults to 2000ms.
+     */
+    readonly intervalMs?: number;
+    /**
+     * Optional per-page event cap. Defaults to 100 (matches server
+     * default). The polling transport handles pagination by re-polling
+     * on the next tick when `hasMore` is true — we don't loop within a
+     * single tick to keep latency bounded.
+     */
+    readonly limit?: number;
+}
+/**
+ * Build a {@link RegistryPollingOptions} descriptor that reads
+ * `/api/renders/:renderId/events?sinceSequence=N&limit=M` and dispatches
+ * each `RenderEvent` by `event.type` to the registry's matching
+ * channel handler. Cursor advances per-tick to the server's
+ * `lastSequence`.
+ *
+ * # Per-tick URL composition
+ *
+ * The transport calls `polling.url` verbatim. Because the cursor
+ * changes per tick we can't fix a single URL at build time; instead we
+ * implement a single-tick read by mutating a closure-scoped cursor
+ * and recomputing the URL inside `parseSnapshot`. But `parseSnapshot`
+ * gets the BODY, not the URL — so this design uses a layered approach:
+ * the URL on the descriptor IS the cursor-aware URL composed inside a
+ * proxy fetch wrapper layer above. For now, this implementation
+ * returns the cursor-aware URL via a synchronous re-composition each
+ * tick (the transport calls fetch ONCE per tick).
+ *
+ * Implementation note: `RegistryPollingOptions.url` is a static string
+ * on the type, but we need a per-tick re-computation. We achieve this
+ * via a `Proxy` getter on the returned object — each access of `url`
+ * pulls the live cursor and composes the URL anew.
+ */
+export declare function buildEventsPolling(opts: BuildEventsPollingOptions): RegistryPollingOptions;

package/dist/events-polling.js

@@ -0,0 +1,143 @@
+const DEFAULT_EVENTS_POLL_INTERVAL_MS = 2000;
+const DEFAULT_EVENTS_PAGE_LIMIT = 100;
+/**
+ * Compose the per-tick URL with `&sinceSequence=N&limit=M` appended.
+ * The base URL may or may not already carry a query string; we pick
+ * the right separator.
+ */
+function composeTickUrl(baseUrl, sinceSequence, limit) {
+    const sep = baseUrl.includes('?') ? '&' : '?';
+    return `${baseUrl}${sep}sinceSequence=${sinceSequence}&limit=${limit}`;
+}
+/**
+ * Type guard for the EventsResponse envelope shape. Defends against
+ * server bugs / proxy interference that could feed the parser
+ * non-conforming JSON.
+ */
+function isEventsResponse(body) {
+    if (body === null || typeof body !== 'object')
+        return false;
+    const obj = body;
+    if (!Array.isArray(obj['events']))
+        return false;
+    if (typeof obj['lastSequence'] !== 'number')
+        return false;
+    if (typeof obj['hasMore'] !== 'boolean')
+        return false;
+    return true;
+}
+/**
+ * Type guard for one RenderEvent in the events array.
+ */
+function isRenderEvent(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const obj = value;
+    if (typeof obj['seq'] !== 'number')
+        return false;
+    if (typeof obj['timestamp'] !== 'string')
+        return false;
+    if (typeof obj['type'] !== 'string')
+        return false;
+    // `data` is intentionally unconstrained — typed at the
+    // consumer-side handler that dispatches on `type`.
+    return true;
+}
+/**
+ * Build a {@link RegistryPollingOptions} descriptor that reads
+ * `/api/renders/:renderId/events?sinceSequence=N&limit=M` and dispatches
+ * each `RenderEvent` by `event.type` to the registry's matching
+ * channel handler. Cursor advances per-tick to the server's
+ * `lastSequence`.
+ *
+ * # Per-tick URL composition
+ *
+ * The transport calls `polling.url` verbatim. Because the cursor
+ * changes per tick we can't fix a single URL at build time; instead we
+ * implement a single-tick read by mutating a closure-scoped cursor
+ * and recomputing the URL inside `parseSnapshot`. But `parseSnapshot`
+ * gets the BODY, not the URL — so this design uses a layered approach:
+ * the URL on the descriptor IS the cursor-aware URL composed inside a
+ * proxy fetch wrapper layer above. For now, this implementation
+ * returns the cursor-aware URL via a synchronous re-composition each
+ * tick (the transport calls fetch ONCE per tick).
+ *
+ * Implementation note: `RegistryPollingOptions.url` is a static string
+ * on the type, but we need a per-tick re-computation. We achieve this
+ * via a `Proxy` getter on the returned object — each access of `url`
+ * pulls the live cursor and composes the URL anew.
+ */
+export function buildEventsPolling(opts) {
+    let cursor = opts.initialSinceSequence ?? 0;
+    const limit = opts.limit ?? DEFAULT_EVENTS_PAGE_LIMIT;
+    const intervalMs = opts.intervalMs ?? DEFAULT_EVENTS_POLL_INTERVAL_MS;
+    // Each `url` access recomputes from the current cursor. The
+    // PollingTransport's tick calls `polling.url` once per fetch.
+    const descriptor = Object.create(null);
+    Object.defineProperty(descriptor, 'url', {
+        enumerable: true,
+        get: () => composeTickUrl(opts.baseUrl, cursor, limit),
+    });
+    Object.defineProperty(descriptor, 'intervalMs', {
+        enumerable: true,
+        value: intervalMs,
+    });
+    Object.defineProperty(descriptor, 'parseSnapshot', {
+        enumerable: true,
+        value: (body) => {
+            // 410 case manifests as a body that doesn't match the
+            // EventsResponse shape (`{reason: 'REPLAY_HORIZON_PASSED',
+            // currentSequence}`). Surface a synthetic `error` frame so the
+            // registry's error handler can fire the re-mount signal.
+            if (body !== null &&
+                typeof body === 'object' &&
+                body.reason === 'REPLAY_HORIZON_PASSED') {
+                const cs = body.currentSequence;
+                const currentSequence = typeof cs === 'number' ? cs : 0;
+                // Reset cursor to the server's high-water mark; next tick
+                // starts fresh from there. Consumers handle the re-mount via
+                // the error channel.
+                cursor = currentSequence;
+                const errorFrame = {
+                    type: 'error',
+                    payload: {
+                        code: 'REPLAY_HORIZON_PASSED',
+                        message: `events polling cursor outside replayable range; reset to ${currentSequence}`,
+                        details: { currentSequence },
+                    },
+                };
+                return { error: errorFrame };
+            }
+            if (!isEventsResponse(body))
+                return null;
+            // Advance cursor even on empty pages — the server's high-water
+            // mark moves with /state reads too.
+            cursor = body.lastSequence;
+            if (body.events.length === 0) {
+                // Nothing to dispatch; the empty object signals "snapshot
+                // parsed but no handlers matched today's keys" (distinct from
+                // `null` = no change).
+                return {};
+            }
+            // Group events by type. The registry-level polling transport
+            // calls one handler per type; if multiple events share a type
+            // we'd lose deliveries. Today's wire frame types
+            // (render/props_update) are typically distinct per tick at the
+            // expected 2s cadence, but the protocol allows multiple of the
+            // same type. Honest workaround: dispatch the LAST event of each
+            // type and rely on the consumer's idempotency. Future R8: extend
+            // the dispatch shape to a list per type.
+            const frames = {};
+            for (const event of body.events) {
+                if (!isRenderEvent(event))
+                    continue;
+                frames[event.type] = {
+                    type: event.type,
+                    payload: event.data,
+                };
+            }
+            return frames;
+        },
+    });
+    return descriptor;
+}

package/dist/gadget-loader.d.ts

@@ -38,7 +38,7 @@
 import type { GadgetPackageRegistry, ModuleNamespace } from './globals.js';
 /**
  * Minimal shape consumed by the loader — mirrors the protocol's
- * `GguiBootstrapMeta.gadgets[*]` entry but typed locally so the loader
+ * `McpAppAiGguiRenderMeta.gadgets[*]` entry but typed locally so the loader
  * is testable without dragging the protocol package into unit setups.
  */
 export interface GadgetRegistration {

package/dist/globals.d.ts

@@ -35,10 +35,10 @@
  * means the registry MUST be populated BEFORE any `loadModule()` call
  * evaluates generated code. The boot orchestration in
  * `runtime.ts::bootSequence` enforces this by calling
- * `installGlobalRegistry()` BEFORE the subscribe ack's first stack
- * item renders. Race-free: Node/browser event loop is single-threaded
- * and no other code runs between `installGlobalRegistry()` and the
- * first stack-item render invocation.
+ * `installGlobalRegistry()` BEFORE the subscribe ack's render mounts.
+ * Race-free: Node/browser event loop is single-threaded and no other
+ * code runs between `installGlobalRegistry()` and the first render
+ * invocation.
  */
 import type { Context } from 'react';
 /**

package/dist/host-context-emitter.d.ts

@@ -1,42 +1,58 @@
 /**
- * Host-context emitter.
+ * Host-context emitter + DOM application.
  *
  * Responsibilities:
  *
  *   1. Hold the latest `HostContextProjection` the runtime has captured.
- *      Seeded from the iframe's `ui/initialize` response (Reading-A
- *      path, via `parseBootstrapFromUiInitialize`); updated on every
+ *      Seeded from the App's `ui/initialize` capture
+ *      (`app.getHostContext()`); updated on every
  *      `ui/notifications/host-context-changed` postMessage from the host.
  *   2. Echo each fresh value as a `type: 'host_context_observed'`
  *      WebSocket envelope so the server can persist it on
- *      `SessionRecord.hostContext` for agent visibility.
+ *      `RenderRecord.hostContext` for agent visibility.
  *   3. Suppress no-op re-emissions (via deep-equality on the projection
  *      shape) — avoids server-side write traffic when a notification
  *      arrives but no projection-visible field actually changed (e.g.,
  *      the host's `theme` updated but ggui doesn't project theme).
+ *   4. Apply host theme + styles + fonts to the iframe DOM via the
+ *      spec-canonical {@link applyDocumentTheme} /
+ *      {@link applyHostStyleVariables} / {@link applyHostFonts} helpers
+ *      from `@modelcontextprotocol/ext-apps`. Fires on EVERY raw
+ *      `McpUiHostContext` the runtime observes (initial + change
+ *      notifications). The application path is INDEPENDENT of the
+ *      WS-echo path — projection drops `theme` / `styles` (they live in
+ *      ggui's own theming pipeline), but the DOM still needs them to
+ *      render the host's native primitives consistently.
  *
  * Lifecycle:
  *
- *   - Initial seed: `seed(projection, sessionId)` called from
+ *   - Initial seed: `seed(projection, renderId)` called from
  *     `bootProduction` right after the WS transport is attached and we
- *     know the initial projection from `parseBootstrap.hostContext`.
+ *     know the initial projection from `projectHostContext(app.getHostContext())`.
+ *     {@link applyHostContextStyling} fires separately from
+ *     `bootSequence` against the RAW `app.getHostContext()` so the
+ *     spec-canonical helpers see the full `McpUiHostContext`
+ *     (projection drops fields they need).
  *   - Live updates: `attachListener()` installs a `window`-scoped
  *     `message` listener for the spec-defined notification method
  *     `'ui/notifications/host-context-changed'`. The notification's
- *     `params` carry a partial `McpUiHostContext`; we merge into the
- *     held projection and emit if changed.
+ *     `params` carry a partial `McpUiHostContext`; we apply the raw
+ *     fields to the DOM, merge the projection into the held value,
+ *     and WS-echo if the projection changed.
  *   - Teardown: `detach()` removes the listener and clears state.
  *     Used by tests + future host-switch flows.
  *
  * Why a dedicated module:
  *
- *   - `runtime.ts` is already ~3100 lines; adding another postMessage
+ *   - `runtime.ts` is already ~3500 lines; adding another postMessage
  *     listener + state slot bloats it.
- *   - The emission policy (seed + change-merge + dedupe) is testable in
- *     isolation without the WS transport / bootstrap parse / DOM mount.
+ *   - The emission policy (seed + change-merge + dedupe) + DOM-apply
+ *     policy is testable in isolation without the WS transport /
+ *     slice-meta parse / DOM mount.
  *   - Future widening (echo more fields, debounce burst changes, etc.)
  *     happens in one place.
  */
+import { type App } from '@modelcontextprotocol/ext-apps';
 import { type HostContextObservedPayload, type HostContextProjection } from '@ggui-ai/protocol';
 /**
  * Function the emitter calls to ship a `host_context_observed` envelope.
@@ -60,28 +76,56 @@ export type HostContextSendFn = (msg: {
  * the same projection) suppresses the duplicate emission via the
  * equality check.
  *
- * Re-seeding with a DIFFERENT `sessionId` is undefined behavior; the
- * iframe-runtime is one-session-per-mount by construction. Tests
- * exercising multi-session flows MUST call `detach()` between seeds.
+ * Re-seeding with a DIFFERENT `renderId` is undefined behavior; the
+ * iframe-runtime is one-render-per-mount by construction. Tests
+ * exercising multi-render flows MUST call `detach()` between seeds.
  */
 export declare function seed(args: {
-    readonly sessionId: string;
+    readonly renderId: string;
     readonly send: HostContextSendFn;
     readonly initial: HostContextProjection;
 }): void;
+export interface AttachListenerOptions {
+    /**
+     * Bind via the spec-canonical `App.addEventListener('hostcontextchanged')`
+     * event surface. Production wires this — App's onEventDispatch
+     * pre-merges the params into its internal `_hostContext` before
+     * our handler runs, so `app.getHostContext()` is always fresh by
+     * the time we project + WS-echo.
+     *
+     * When omitted, falls back to a raw `window.addEventListener('message')`
+     * listener (the pre-1.19b.3 behavior). Tests rely on this — they
+     * dispatch `MessageEvent`s directly instead of constructing a
+     * connected App.
+     */
+    readonly app?: App;
+    /**
+     * Target window for the legacy raw-listener fallback. Ignored when
+     * {@link AttachListenerOptions.app} is set. Defaults to `window`.
+     */
+    readonly targetWindow?: Window;
+}
 /**
- * Install the `host-context-changed` notification listener on the
- * iframe `window`. Safe to call multiple times — duplicate listeners
- * are deduped via `state.listener !== null` guard.
+ * Install the `host-context-changed` notification listener. When the
+ * {@link AttachListenerOptions.app} handle is supplied, uses App's
+ * spec-canonical event surface; otherwise falls back to a raw
+ * `window.message` listener (tests use this).
+ *
+ * Safe to call multiple times — duplicate listeners are deduped via
+ * `state.listener !== null` guard.
  *
  * Detaches when `detach()` is called or when the module is torn down.
  */
-export declare function attachListener(targetWindow?: Window): void;
+export declare function attachListener(optsOrWindow?: AttachListenerOptions | Window): void;
 /**
  * Tear down: remove the listener, clear module state. Called from
  * unit tests between scenarios and from the future host-switch flow.
+ *
+ * The `targetWindow` parameter is no longer used (the listener handle
+ * carries its own cleanup closure); preserved as an optional arg for
+ * back-compat with existing test code.
  */
-export declare function detach(targetWindow?: Window): void;
+export declare function detach(_targetWindow?: Window): void;
 /**
  * Test-only read of the current held projection. Production code
  * MUST NOT depend on this; the emitter is fire-and-forget by design.
@@ -89,3 +133,23 @@ export declare function detach(targetWindow?: Window): void;
  */
 export declare function _peekCurrent(): HostContextProjection | undefined;
 export declare function subscribeLocal(listener: (projection: HostContextProjection) => void): () => void;
+/**
+ * Apply the host's `theme`, `styles.variables`, `styles.css.fonts`, and
+ * `safeAreaInsets` to the iframe DOM via the canonical
+ * `@modelcontextprotocol/ext-apps` helpers. Defensive in two ways:
+ *
+ *   1. Accepts `unknown` so callers (the listener; `bootSequence`'s
+ *      initial-application path) don't have to gate-check before calling.
+ *   2. Per-field optionality is respected — every helper is called only
+ *      when the corresponding field is present + structurally valid.
+ *      Malformed input drops the field silently rather than throwing
+ *      and breaking the boot.
+ *
+ * Fire-and-forget: a helper throwing (e.g. when running outside a
+ * browser DOM context, or under jsdom limits) is caught + swallowed so
+ * the WS-echo path stays alive. Theme application is a UX nicety,
+ * never load-bearing for agent visibility.
+ *
+ * @public
+ */
+export declare function applyHostContextStyling(raw: unknown): void;