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

package/dist/host-context-emitter.js

@@ -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 { applyDocumentTheme, applyHostFonts, applyHostStyleVariables, } from '@modelcontextprotocol/ext-apps';
 import { hostContextProjectionsEqual, projectHostContext, } from '@ggui-ai/protocol';
 let state = null;
 // =============================================================================
@@ -48,15 +64,15 @@ let state = null;
  * 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 function seed(args) {
     // First seed — record state + emit initial.
     if (state === null) {
         state = {
-            sessionId: args.sessionId,
+            renderId: args.renderId,
             send: args.send,
             current: args.initial,
             listener: null,
@@ -72,13 +88,17 @@ export function seed(args) {
     }
 }
 /**
- * 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 function attachListener(targetWindow = window) {
+export function attachListener(optsOrWindow = window) {
     if (state === null) {
         // Not yet seeded — listener can't usefully fire (no send seam).
         // Caller should `seed()` first; this defensive bail keeps the
@@ -87,19 +107,48 @@ export function attachListener(targetWindow = window) {
     }
     if (state.listener !== null)
         return;
+    // Back-compat: callers that pass a bare `Window` (the pre-1.19b.3
+    // signature, still used by tests) take the raw-listener path.
+    const isWindowArg = optsOrWindow !== null
+        && typeof optsOrWindow === 'object'
+        && 'addEventListener' in optsOrWindow
+        && 'removeEventListener' in optsOrWindow
+        && !('app' in optsOrWindow);
+    const opts = isWindowArg
+        ? { targetWindow: optsOrWindow }
+        : optsOrWindow;
+    if (opts.app !== undefined) {
+        const handler = (params) => {
+            handleHostContextChangedParams(params);
+        };
+        opts.app.addEventListener('hostcontextchanged', handler);
+        state.listener = {
+            kind: 'app',
+            off: () => opts.app.removeEventListener('hostcontextchanged', handler),
+        };
+        return;
+    }
+    const targetWindow = opts.targetWindow ?? window;
     const listener = (ev) => {
         handleHostContextChangedMessage(ev.data);
     };
-    state.listener = listener;
     targetWindow.addEventListener('message', listener);
+    state.listener = {
+        kind: 'window',
+        off: () => targetWindow.removeEventListener('message', listener),
+    };
 }
 /**
  * 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 function detach(targetWindow = window) {
+export function detach(_targetWindow = window) {
     if (state !== null && state.listener !== null) {
-        targetWindow.removeEventListener('message', state.listener);
+        state.listener.off();
     }
     state = null;
     // Reset the local subscriber set too — module-level state is the
@@ -142,6 +191,68 @@ export function subscribeLocal(listener) {
     };
 }
 // =============================================================================
+// DOM application — spec-canonical theme / styles / fonts.
+// =============================================================================
+/**
+ * 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 function applyHostContextStyling(raw) {
+    if (!isPlainObject(raw))
+        return;
+    const ctx = raw;
+    try {
+        if (ctx.theme === 'light' || ctx.theme === 'dark') {
+            applyDocumentTheme(ctx.theme);
+        }
+    }
+    catch {
+        // jsdom may not implement every documentElement API the helper
+        // touches; swallow + carry on with the remaining fields.
+    }
+    try {
+        const variables = ctx.styles?.variables;
+        if (variables !== undefined && variables !== null) {
+            applyHostStyleVariables(variables);
+        }
+    }
+    catch {
+        // Same posture — best-effort. A subscriber throwing must not stop
+        // the WS-echo half of the listener.
+    }
+    try {
+        const fontsCss = ctx.styles?.css?.fonts;
+        if (typeof fontsCss === 'string' && fontsCss.length > 0) {
+            applyHostFonts(fontsCss);
+        }
+    }
+    catch {
+        // applyHostFonts injects a <style> tag; jsdom may reject the
+        // operation under strict modes. Swallow.
+    }
+    // safeAreaInsets — the spec carries these for mobile chrome
+    // letterboxing. ext-apps doesn't ship a canonical helper (apps
+    // typically apply per-component); the system-card reference applies
+    // as root padding. ggui's iframe contains LLM-generated UI which has
+    // its own responsive concerns — skip safe-area for now; revisit when
+    // a concrete mobile use case appears.
+}
+// =============================================================================
 // Internals
 // =============================================================================
 function isPlainObject(value) {
@@ -150,15 +261,13 @@ function isPlainObject(value) {
 /**
  * Process an incoming postMessage payload. Filters to JSON-RPC
  * notifications with method `ui/notifications/host-context-changed`;
- * everything else is ignored. The notification's `params` is a partial
- * `McpUiHostContext` — we project and merge into the held value.
+ * everything else is ignored. Delegates to {@link handleHostContextChangedParams}
+ * once the envelope shape is validated.
  *
- * Exported via `attachListener` indirection; isolated here so it's
- * unit-testable without dispatching real `MessageEvent`s.
+ * Used by the legacy `window.message` listener path; App's event surface
+ * skips this filter (App's own dispatch has already matched the method).
  */
 function handleHostContextChangedMessage(raw) {
-    if (state === null)
-        return;
     if (!isPlainObject(raw))
         return;
     if (raw['method'] !== 'ui/notifications/host-context-changed')
@@ -166,6 +275,27 @@ function handleHostContextChangedMessage(raw) {
     const params = raw['params'];
     if (!isPlainObject(params))
         return;
+    handleHostContextChangedParams(params);
+}
+/**
+ * Apply a `ui/notifications/host-context-changed` params payload to
+ * the iframe DOM + projection state + WS-echo. Called by both delivery
+ * paths (raw window.message in tests / App's `hostcontextchanged`
+ * event in production) once they've extracted the partial-context
+ * payload.
+ *
+ * Exported (module-private) so the App listener can call directly
+ * without re-validating the JSON-RPC envelope.
+ */
+function handleHostContextChangedParams(params) {
+    if (state === null)
+        return;
+    // Apply spec-canonical theme/styles/fonts to the iframe DOM BEFORE
+    // the WS-echo path. The DOM-apply path covers fields the projection
+    // drops (theme, styles) so the LLM-generated UI inside the iframe
+    // re-paints to match a host theme switch even when nothing
+    // projection-visible changed (e.g., dark/light toggle).
+    applyHostContextStyling(params);
     // Spec: the notification's params carry a partial McpUiHostContext.
     // Project it (defensive — malformed inputs drop to undefined fields)
     // and merge with the held projection so a partial update overlays
@@ -186,7 +316,7 @@ function emit() {
         state.send({
             type: 'host_context_observed',
             payload: {
-                sessionId: state.sessionId,
+                renderId: state.renderId,
                 hostContext: state.current,
             },
         });