@ggui-ai/iframe-runtime 0.1.0-rc.1

package/dist/wire-config.js

@@ -0,0 +1,290 @@
+import { ClientContractViolationError, buildActionEnvelope, } from '@ggui-ai/wire';
+import { validateOutboundActionEnvelope } from './validation.js';
+import { defaultProtocolErrorEmitter, fromClientContractViolation, } from './protocol-error.js';
+// =============================================================================
+// StreamBus — the in-renderer bridge between inbound `data` frames
+// and per-component `useStream(channel)` subscribers.
+// =============================================================================
+/**
+ * Reserved-channel namespace prefix (mirror of
+ * `@ggui-ai/protocol::RESERVED_CHANNEL_PREFIX`). Inlined to avoid
+ * widening the protocol import surface here — the constant is
+ * load-bearing for the late-subscriber replay rule below; equality
+ * with the protocol export is locked by the StreamBus tests.
+ */
+const RESERVED_CHANNEL_PREFIX = '_ggui:';
+/**
+ * Per-channel ring cap for late-subscriber replay on reserved channels.
+ * Mirrors the server-side `DEFAULT_SESSION_STREAM_BUFFER_MAX` posture:
+ * bounded so a long-lived iframe can't grow memory unbounded if a
+ * reserved channel emits in a hot loop.
+ *
+ * 256 is enough headroom for the deterministic A2UI emitter (one frame
+ * per fragment, ~5–15 frames per push) plus several refresh cycles, and
+ * still fits comfortably in memory.
+ */
+const RESERVED_CHANNEL_REPLAY_MAX = 256;
+/**
+ * Tiny fan-out bus keyed by channel name. `subscribe.ts`'s inbound-
+ * message handler pushes validated `data` envelopes here; wire's
+ * `useStream(channel)` subscribes per-component via the config's
+ * `subscribe()` method.
+ *
+ * Late-subscriber replay for reserved channels:
+ *
+ *   The renderer iframe boots in a strict ordering:
+ *   `subscribe()` → first `ack` → render stack items → mount
+ *   `mountProvisional` → it then calls `streamBus.subscribe('_ggui:
+ *   preview', …)`. Server-side replay frames for `_ggui:preview` (the
+ *   provisional A2UI preamble fired during the agent's `ggui_push`
+ *   BEFORE the user's browser navigated to the viewer) arrive over the
+ *   WS in the window between ack-resolve and the provisional mount —
+ *   they hit `emit()` before any listener has subscribed. Without a
+ *   bounded reserved-channel ring, those frames vanish and the preview
+ *   surface stays stuck on the spinner.
+ *
+ *   Server-owned `_ggui:*` channels are buffered in a per-channel ring
+ *   capped at {@link RESERVED_CHANNEL_REPLAY_MAX}. New subscribers
+ *   receive the buffered envelopes synchronously before the unsubscribe
+ *   handle returns — same mental model as the server-side
+ *   `SessionStreamBuffer.replay(...)` walk over reserved channels at
+ *   ack time, but mirrored at the inner bus boundary so the host
+ *   transport stays portable (Claude Desktop / ChatGPT / Cursor /
+ *   `<McpAppIframe>` all behave the same).
+ *
+ *   Agent-declared (non-reserved) channels are NOT buffered here. Their
+ *   replay is the server's job — the renderer's `subscribe()` handshake
+ *   pulls history per `streamSpec.replay` policy when reconnecting with
+ *   `fromSeq`. Buffering them at this layer would double-count and
+ *   change the semantics of agent contracts.
+ *
+ * No observable mutation outside the renderer boundary — the bus is
+ * internal plumbing.
+ */
+export class StreamBus {
+    listeners = new Map();
+    /**
+     * Per-channel bounded ring of envelopes for reserved (`_ggui:*`)
+     * channels only. FIFO eviction at `RESERVED_CHANNEL_REPLAY_MAX`.
+     * Replayed to every new subscriber for that channel.
+     */
+    reservedReplay = new Map();
+    subscribe(channel, listener) {
+        let bucket = this.listeners.get(channel);
+        if (bucket === undefined) {
+            bucket = new Set();
+            this.listeners.set(channel, bucket);
+        }
+        bucket.add(listener);
+        // Replay buffered reserved-channel envelopes BEFORE returning the
+        // unsubscribe handle so the new listener is fully caught up by the
+        // time `subscribe()` returns. Order matches arrival order at
+        // `emit()` (FIFO ring).
+        if (channel.startsWith(RESERVED_CHANNEL_PREFIX)) {
+            const ring = this.reservedReplay.get(channel);
+            if (ring !== undefined) {
+                for (const env of ring) {
+                    listener(env);
+                }
+            }
+        }
+        return () => {
+            const current = this.listeners.get(channel);
+            if (current === undefined)
+                return;
+            current.delete(listener);
+            if (current.size === 0)
+                this.listeners.delete(channel);
+        };
+    }
+    emit(envelope) {
+        if (envelope.channel.startsWith(RESERVED_CHANNEL_PREFIX)) {
+            let ring = this.reservedReplay.get(envelope.channel);
+            if (ring === undefined) {
+                ring = [];
+                this.reservedReplay.set(envelope.channel, ring);
+            }
+            ring.push(envelope);
+            if (ring.length > RESERVED_CHANNEL_REPLAY_MAX) {
+                // FIFO drop — keeps the most recent
+                // `RESERVED_CHANNEL_REPLAY_MAX` frames. Late subscribers may
+                // miss the createSurface fragment if the ring overflows (would
+                // render as Spinner-stuck), but that's an upper-bound contract
+                // on a bounded buffer, not a silent failure mode in practice.
+                ring.shift();
+            }
+        }
+        const bucket = this.listeners.get(envelope.channel);
+        if (bucket === undefined)
+            return;
+        for (const listener of bucket) {
+            listener(envelope);
+        }
+    }
+}
+/**
+ * Build the unscoped root `WireConfig` + its scope-factory closure.
+ * Bootstraps the renderer's outbound emission + inbound subscription
+ * seams.
+ *
+ * Returns a {@link RootWireConfigBundle} rather than a bare
+ * `WireConfig` — the scope factory is paired with the root so
+ * `dispatchByItem` internals don't leak onto the public WireConfig
+ * shape. `scopeWireConfig` (the exported standalone) is the low-level
+ * primitive; `buildScopedConfig` is the pre-bound convenience.
+ */
+export function buildRootWireConfig(opts) {
+    const clientSeqBox = { current: 0 };
+    function nextSeq() {
+        clientSeqBox.current += 1;
+        return clientSeqBox.current;
+    }
+    const emitProtocolError = opts.onProtocolError ?? defaultProtocolErrorEmitter;
+    const emitObserve = opts.onObserve ?? (() => { });
+    function surfaceViolation(err) {
+        // Dual emission — the narrow `onContractViolation` sink stays
+        // for in-renderer tests that assert the raw class shape; the
+        // typed `onProtocolError` sink receives the widened
+        // ProtocolError ('kind: protocol' / code: CLIENT_CONTRACT_VIOLATION)
+        // that the `<McpAppIframe>` host wrapper surfaces via `onError`.
+        if (opts.onContractViolation) {
+            opts.onContractViolation(err);
+        }
+        else if (opts.onProtocolError === undefined) {
+            // No caller-supplied sink at all → operator-visible fallback so
+            // dev consoles see the violation. Matches
+            // `GguiSession.surfaceContractViolation`'s console.warn posture.
+            // eslint-disable-next-line no-console
+            console.warn('[ggui:contract] ' + err.message, {
+                direction: err.direction,
+                violations: err.violations,
+            });
+        }
+        emitProtocolError(fromClientContractViolation(err));
+    }
+    function dispatchByItem(actionName, data, ctx) {
+        const envelope = buildActionEnvelope({
+            sessionId: opts.sessionId,
+            type: 'data:submit',
+            payload: {
+                action: actionName,
+                data: data,
+                ...(ctx.tool ? { tool: ctx.tool } : {}),
+            },
+            stackIndex: ctx.stackIndex,
+            ...(ctx.stackItemId ? { stackItemId: ctx.stackItemId } : {}),
+            clientSeq: nextSeq(),
+        });
+        const result = validateOutboundActionEnvelope(ctx.actionSpec, envelope);
+        if (!result.valid) {
+            surfaceViolation(new ClientContractViolationError('outbound-action', result.violations));
+            return;
+        }
+        sendActionEnvelope(opts.manager, envelope);
+        // Observability: a wired-tool dispatch is a `data:submit` whose
+        // resolved action has a `tool` binding. Plain agent-routed actions
+        // (no `tool` on the actionSpec) fire a `dispatch` activity row in
+        // the console via the session-side ring buffer; only wired tools
+        // get this observability event. The server separately emits the
+        // operational telemetry variant on its TelemetrySink.
+        if (ctx.tool !== undefined) {
+            emitObserve({
+                kind: 'wired-tool-invoked',
+                toolName: ctx.tool,
+                actionName,
+                dispatchedAt: new Date().toISOString(),
+            });
+        }
+    }
+    const root = {
+        app: { appId: opts.appId, appName: opts.appId },
+        session: { sessionId: opts.sessionId, isConnected: true },
+        auth: { isAuthenticated: false },
+        dispatch: (actionName, data) => {
+            // Unscoped fallback — resolve from top of stack. Matches
+            // `GguiSession.wireConfig.dispatch` (the non-scoped path).
+            const stack = opts.getStack();
+            const activeItem = stack[stack.length - 1];
+            const activeIndex = stack.length > 0 ? stack.length - 1 : 0;
+            // McpApps + system items never carry `actionSpec` (their wire is
+            // owned by their own host) — narrow before reading.
+            const activeActionSpec = activeItem !== undefined &&
+                activeItem.type !== 'mcpApps' &&
+                activeItem.type !== 'system'
+                ? activeItem.actionSpec
+                : undefined;
+            const entry = activeActionSpec?.[actionName];
+            const tool = entry?.nextStep;
+            dispatchByItem(actionName, data, {
+                stackItemId: activeItem?.id,
+                stackIndex: activeIndex,
+                ...(tool !== undefined ? { tool } : {}),
+                ...(activeActionSpec !== undefined
+                    ? { actionSpec: activeActionSpec }
+                    : {}),
+            });
+        },
+        subscribe: (channelName, handler) => {
+            return opts.streamBus.subscribe(channelName, (env) => {
+                // `WireConfig<DataContract>.subscribe`'s handler expects a
+                // `StreamDelivery<unknown>`; the bus ships the raw envelope
+                // payload unmodified. The type-level `unknown` narrowing
+                // lives on the caller's generic boundary (useStream /
+                // useContract).
+                handler({
+                    payload: env.payload,
+                    mode: env.mode,
+                    ...(env.complete !== undefined ? { complete: env.complete } : {}),
+                });
+            });
+        },
+        // `callWiredTool` is retired — `agentTools` is now a catalog the
+        // AGENT invokes; the component never reaches the underlying tool
+        // from inside the renderer. Cross-refs surface via
+        // `actionSpec[*].nextStep` (event metadata) and
+        // `streamSpec[*].source.tool` (channel data source).
+    };
+    // `WireConfig` carries no `scope(item)` method.
+    // Callers that want a per-item config use `buildScopedConfig(item)`
+    // on the returned bundle, which bakes in the `dispatchByItem` +
+    // `getStack` internals so they never leak onto the public
+    // WireConfig shape.
+    const buildScopedConfig = (item) => scopeWireConfig(root, item, {
+        getStack: opts.getStack,
+        dispatchByItem,
+    });
+    return { config: root, buildScopedConfig };
+}
+/**
+ * Produce a per-item scoped `WireConfig`. The only override is
+ * `dispatch` — every other seam (subscribe) stays shared.
+ */
+export function scopeWireConfig(root, item, internals) {
+    return {
+        ...root,
+        dispatch: (actionName, data) => {
+            const entry = item.actionSpec?.[actionName];
+            const tool = entry?.nextStep;
+            const stack = internals.getStack();
+            const idx = stack.findIndex((s) => s.id === item.stackItemId);
+            internals.dispatchByItem(actionName, data, {
+                ...(item.stackItemId !== undefined ? { stackItemId: item.stackItemId } : {}),
+                stackIndex: idx >= 0 ? idx : 0,
+                ...(tool !== undefined ? { tool } : {}),
+                ...(item.actionSpec !== undefined ? { actionSpec: item.actionSpec } : {}),
+            });
+        },
+    };
+}
+// =============================================================================
+// Outbound envelope emission
+// =============================================================================
+/**
+ * Send a validated action envelope over the live channel. The WS frame shape
+ * is `{type:'action', payload: envelope}` — matches today's
+ * `useWebSocket.sendAction` exactly, so wire-emitted dispatches from
+ * the renderer are byte-equivalent to `GguiSession`-emitted ones.
+ */
+function sendActionEnvelope(manager, envelope) {
+    manager.send({ type: 'action', payload: envelope });
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@ggui-ai/iframe-runtime",
+  "version": "0.1.0-rc.1",
+  "description": "The iframe-local ggui runtime: a self-contained ESM bundle that boots inside an MCP Apps host iframe, runs the protocol-version handshake, opens the live-channel WebSocket, and renders the session stack. Bundles React, ReactDOM, and the ggui design system so generated component code has a single seam to read from.",
+  "keywords": [
+    "ggui",
+    "mcp",
+    "mcp-apps",
+    "iframe",
+    "runtime",
+    "react"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./runtime.js": {
+      "default": "./dist/iframe-runtime.js"
+    }
+  },
+  "dependencies": {
+    "qrcode-generator": "^2.0.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@ggui-ai/channel-client": "0.1.0-rc.1",
+    "@ggui-ai/gadgets": "0.1.0-rc.1",
+    "@ggui-ai/preview-a2ui": "0.1.0-rc.1",
+    "@ggui-ai/protocol": "0.1.0-rc.1",
+    "@ggui-ai/design": "0.1.0-rc.1",
+    "@ggui-ai/wire": "0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "esbuild": "^0.25.12",
+    "jsdom": "^24.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ggui-ai/ggui.git",
+    "directory": "packages/iframe-runtime"
+  },
+  "homepage": "https://github.com/ggui-ai/ggui/tree/main/packages/iframe-runtime",
+  "bugs": {
+    "url": "https://github.com/ggui-ai/ggui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "ggui contributors <hello@ggui.ai>",
+  "scripts": {
+    "build": "node esbuild.config.mjs && tsc -p tsconfig.types.json && pnpm run check:bundle-size",
+    "check:bundle-size": "tsx scripts/check-bundle-size.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}