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

package/dist/react-renderer.js

@@ -0,0 +1,343 @@
+/**
+ * React component renderer for the iframe runtime.
+ *
+ * Port of `@ggui-ai/react::components/ReactComponentRenderer.tsx` (L10-384)
+ * with the enclosing React component stripped — the iframe runtime
+ * does not have an outer React tree; it owns the root `createRoot`
+ * mount itself. The inner eval + data-URL-shim + error-boundary
+ * pattern is preserved verbatim so today's generated code (which
+ * reads `globalThis.__ggui__` via the shim rewrite) keeps working.
+ *
+ * Lifecycle seams:
+ *
+ *   - `mount(container, stackItem)` — replace the container's
+ *     children with a React root rendering the compiled component.
+ *     Returns a `ReactRootMount` handle; callers use `update()` to
+ *     swap props without re-evaluating the module, `unmount()` to
+ *     tear down.
+ *   - `update(stackItem)` — swap props (and/or componentCode). When
+ *     componentCode changes, re-evaluates; when only props change,
+ *     re-renders the existing component tree with new props.
+ *   - `unmount()` — `root.unmount()` + detach observability.
+ *
+ * Error handling — ErrorBoundary with auto-retry (AUTO_RETRY_LIMIT +
+ * AUTO_RETRY_DELAY) matches the `ReactComponentRenderer` contract.
+ * On terminal error, the callback `onRequestRepair` fires; the
+ * stack-item dispatcher wires this to the `ggui:request-repair`
+ * live-channel envelope `StackItemRenderer` dispatches.
+ *
+ * No JSX in this file — the mount-root code uses
+ * `React.createElement` + `React.Fragment` directly so the renderer's
+ * TypeScript config doesn't need a JSX runtime plumbing.
+ */
+import React, { Component, createElement, Fragment, } from 'react';
+import { createRoot } from 'react-dom/client';
+import { stripMarkers, rewriteImports, getScopedThemeCss, getScopedCssTokens, getThemeCss, getCssTokens, } from '@ggui-ai/design/rendering';
+import { hoistImports, loadModule } from '@ggui-ai/design/module-loader';
+// =============================================================================
+// Scope class helpers — port of RCR's `makeScopeClass` + counter.
+// =============================================================================
+let scopeCounter = 0;
+/**
+ * Generate a CSS-safe scope class. The iframe-internal mount doesn't
+ * have access to React's `useId` (we're not inside a React tree at
+ * the call site), so the counter is the always-available fallback.
+ * `data-` attribute wrapping plus the counter-based class is fine —
+ * only one ReactRootMount exists per iframe by construction.
+ */
+function makeScopeClass() {
+    scopeCounter += 1;
+    return `ggui-rcr-${scopeCounter}`;
+}
+// =============================================================================
+// Error boundary — port of RCR's internal ErrorBoundary (L68–203).
+// =============================================================================
+const AUTO_RETRY_LIMIT = 1;
+const AUTO_RETRY_DELAY = 500;
+class RcrErrorBoundary extends Component {
+    state = {
+        error: null,
+        catchCount: 0,
+        autoRetrying: false,
+        repairRequested: false,
+    };
+    retryTimer = null;
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    componentDidCatch(error, _info) {
+        const nextCount = this.state.catchCount + 1;
+        this.setState({ catchCount: nextCount });
+        if (nextCount <= AUTO_RETRY_LIMIT) {
+            this.setState({ autoRetrying: true });
+            this.retryTimer = setTimeout(() => {
+                this.setState({ error: null, autoRetrying: false });
+            }, AUTO_RETRY_DELAY);
+            return;
+        }
+        this.props.onError?.(error);
+        if (this.props.onRequestRepair && !this.state.repairRequested) {
+            this.setState({ repairRequested: true });
+            this.props.onRequestRepair(error);
+        }
+    }
+    componentWillUnmount() {
+        if (this.retryTimer !== null)
+            clearTimeout(this.retryTimer);
+    }
+    render() {
+        const { error, autoRetrying, repairRequested, catchCount } = this.state;
+        if (error === null)
+            return this.props.children;
+        // The three fallback UIs match the host-SDK error boundary
+        // verbatim (same inline styles so operator-visible DOM is
+        // identical between the host-SDK and iframe-renderer paths).
+        const FONT = '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+        if (autoRetrying) {
+            return createElement('div', {
+                style: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    padding: 24,
+                    minHeight: 80,
+                    gap: 8,
+                    fontFamily: FONT,
+                    fontSize: 13,
+                    color: 'rgba(255,255,255,0.4)',
+                },
+            }, createElement('div', {
+                style: {
+                    width: 16,
+                    height: 16,
+                    border: '2px solid rgba(255,255,255,0.15)',
+                    borderTopColor: 'rgba(255,255,255,0.5)',
+                    borderRadius: '50%',
+                    animation: 'ggui-err-spin 0.6s linear infinite',
+                },
+            }), 'Retrying...', createElement('style', null, '@keyframes ggui-err-spin { to { transform: rotate(360deg); } }'));
+        }
+        if (repairRequested) {
+            return createElement('div', {
+                style: {
+                    display: 'flex',
+                    flexDirection: 'column',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    padding: '32px 24px',
+                    minHeight: 120,
+                    gap: 10,
+                    textAlign: 'center',
+                    fontFamily: FONT,
+                },
+            }, createElement('div', {
+                style: {
+                    width: 16,
+                    height: 16,
+                    border: '2px solid rgba(139,92,246,0.2)',
+                    borderTopColor: 'rgba(139,92,246,0.7)',
+                    borderRadius: '50%',
+                    animation: 'ggui-err-spin 0.8s linear infinite',
+                },
+            }), createElement('div', { style: { fontSize: 13, color: 'rgba(255,255,255,0.5)' } }, 'Repairing component...'), createElement('style', null, '@keyframes ggui-err-spin { to { transform: rotate(360deg); } }'));
+        }
+        return createElement('div', {
+            style: {
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                justifyContent: 'center',
+                padding: '32px 24px',
+                minHeight: 120,
+                gap: 12,
+                textAlign: 'center',
+                fontFamily: FONT,
+            },
+        }, createElement('div', {
+            style: {
+                width: 48,
+                height: 48,
+                borderRadius: 14,
+                background: 'rgba(239, 68, 68, 0.1)',
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                fontSize: 22,
+            },
+        }, '!'), createElement('div', { style: { fontSize: 14, fontWeight: 600, color: 'rgba(255,255,255,0.8)' } }, 'Something went wrong'), createElement('div', { style: { fontSize: 12, color: 'rgba(255,255,255,0.4)', maxWidth: 280, lineHeight: 1.4 } }, 'This component encountered an error. Try asking for a different view.'), createElement('button', {
+            onClick: () => this.setState({ error: null, catchCount: 0, repairRequested: false }),
+            style: {
+                marginTop: 4,
+                padding: '8px 20px',
+                borderRadius: 8,
+                border: '1px solid rgba(255,255,255,0.15)',
+                background: 'rgba(255,255,255,0.08)',
+                color: 'rgba(255,255,255,0.7)',
+                fontSize: 13,
+                fontWeight: 500,
+                cursor: 'pointer',
+            },
+        }, 'Retry'), catchCount > 1
+            ? createElement('div', { style: { fontSize: 11, color: 'rgba(255,255,255,0.2)' } }, error.message)
+            : null);
+    }
+}
+/**
+ * Mount a React root inside `container` and render `stackItem`'s
+ * compiled componentCode. The container is fully owned after this
+ * call (existing children are replaced).
+ */
+export async function mountReactRoot(container, opts) {
+    container.replaceChildren();
+    const root = createRoot(container);
+    const scopeClass = makeScopeClass();
+    let currentOpts = opts;
+    let currentCode = null;
+    let currentComponent = null;
+    async function evaluate(code) {
+        // 0. If code is a URL (S3 presigned), fetch the bytes first.
+        //    Matches RCR's first-step URL-fetch guard verbatim.
+        let resolved = code;
+        if (code.startsWith('https://')) {
+            const response = await fetch(code);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch component code: ${response.status}`);
+            }
+            resolved = await response.text();
+        }
+        // 1. Strip metadata markers (__GGUI_META__ / __GGUI_STREAM_SPEC__).
+        const cleaned = stripMarkers(resolved);
+        // 2. Hoist imports above var declarations.
+        const hoisted = hoistImports(cleaned);
+        // 3. Rewrite bare specifiers to data-url shims reading from
+        //    `globalThis.__ggui__`. The __ggui__ registry is installed
+        //    by `runtime.ts::bootSequence` BEFORE any mountReactRoot call
+        //    — see globals.ts docstring on TOCTOU ordering.
+        const rewritten = rewriteImports(hoisted, {
+            mode: 'data-url',
+            gadgetPackages: currentOpts.gadgetPackages,
+        });
+        // 4. Dynamically import the module.
+        const mod = await loadModule(rewritten);
+        // 5. Extract default export (or first function export).
+        const Comp = (mod.default ??
+            Object.values(mod).find((v) => typeof v === 'function'));
+        if (Comp === undefined) {
+            throw new Error('Module does not export a default component');
+        }
+        return Comp;
+    }
+    function renderTree(opts) {
+        const themeCss = opts.themeId
+            ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
+            : getScopedCssTokens(scopeClass, opts.themeMode);
+        // Also inject theme CSS at `:root` on `document.head`. The scoped
+        // injection above isolates token resolution to the React tree, but
+        // the embedding shell's body styles (font-family, color, background)
+        // resolve against `:root` — without this, body chrome falls back to
+        // the inline-style defaults (-apple-system, etc.) even when the
+        // tree itself paints correctly. Idempotent — last mount wins on
+        // repeat calls. Same shared id as `@ggui-ai/design/themes`'
+        // `ThemeProvider` so a Studio/Portal context with both runtime + RP
+        // active doesn't double-stack.
+        if (typeof document !== 'undefined') {
+            const rootCss = opts.themeId
+                ? getThemeCss(opts.themeId, opts.themeMode)
+                : getCssTokens(opts.themeMode);
+            const styleId = 'ggui-theme-vars';
+            let styleEl = document.getElementById(styleId);
+            if (!styleEl) {
+                styleEl = document.createElement('style');
+                styleEl.id = styleId;
+                document.head.appendChild(styleEl);
+            }
+            if (styleEl.textContent !== rootCss) {
+                styleEl.textContent = rootCss;
+            }
+        }
+        const componentElement = currentComponent === null
+            ? null
+            : createElement(currentComponent, opts.stackItem.props ?? {});
+        const wrapped = opts.renderWrapper && componentElement !== null
+            ? opts.renderWrapper(componentElement)
+            : componentElement;
+        // The scope `<div>` + inline `<style>` + error-boundary-wrapped
+        // children match RCR L376–383. `key={currentCode?.length}` mirrors
+        // RCR's "reset boundary when code changes" heuristic.
+        root.render(createElement('div', { className: scopeClass }, createElement('style', null, `${themeCss}${opts.cssOverrides ?? ''}`), createElement(RcrErrorBoundary, {
+            key: currentCode?.length ?? 0,
+            ...(opts.onError ? { onError: opts.onError } : {}),
+            ...(opts.onRequestRepair ? { onRequestRepair: opts.onRequestRepair } : {}),
+        }, createElement(Fragment, null, wrapped))));
+    }
+    async function initialEvaluate() {
+        const code = currentOpts.stackItem.componentCode ?? '';
+        if (code.trim().length === 0) {
+            currentComponent = null;
+            currentCode = null;
+            renderTree(currentOpts);
+            return;
+        }
+        try {
+            currentComponent = await evaluate(code);
+            currentCode = code;
+            renderTree(currentOpts);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            // Fail-loud on eval errors. The OPTIONAL `onError` callback is
+            // not enough on its own — bootSelfContained doesn't wire one,
+            // so without this log a self-contained mount with a broken
+            // component renders a blank iframe and emits nothing.
+            // eslint-disable-next-line no-console -- operator-visible failure signal
+            console.error('[ggui] mountReactRoot: component evaluation failed —', e);
+            currentComponent = null;
+            currentCode = null;
+            renderTree(currentOpts);
+            currentOpts.onError?.(e);
+        }
+    }
+    await initialEvaluate();
+    return {
+        get currentCode() {
+            return currentCode;
+        },
+        async update(next) {
+            const prevCode = currentCode;
+            currentOpts = next;
+            const nextCode = next.stackItem.componentCode ?? '';
+            // Props-only change — skip module eval. Re-render with new props.
+            if (nextCode === prevCode && currentComponent !== null) {
+                renderTree(currentOpts);
+                return;
+            }
+            if (nextCode.trim().length === 0) {
+                currentComponent = null;
+                currentCode = null;
+                renderTree(currentOpts);
+                return;
+            }
+            try {
+                currentComponent = await evaluate(nextCode);
+                currentCode = nextCode;
+                renderTree(currentOpts);
+            }
+            catch (err) {
+                const e = err instanceof Error ? err : new Error(String(err));
+                currentComponent = null;
+                currentCode = null;
+                renderTree(currentOpts);
+                next.onError?.(e);
+            }
+        },
+        unmount() {
+            root.unmount();
+            container.replaceChildren();
+        },
+    };
+}
+// Re-export React so downstream renderer modules can import it via
+// the same module specifier as the mount consumer without a separate
+// `react` import (keeps the dependency graph flat inside the renderer
+// package).
+export { React };

package/dist/registry-subscribe.d.ts

@@ -0,0 +1,102 @@
+import type { AckPayload, ContractErrorPayload } from '@ggui-ai/protocol';
+import type { ConnectionStatus } from '@ggui-ai/protocol/transport/websocket';
+import type { GguiBootstrapMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
+import type { ChannelRegistry, WsTransportHandle } from '@ggui-ai/channel-client';
+import { type ProtocolErrorEmitter } from './protocol-error.js';
+import type { ObservabilityEmitter } from './observability.js';
+/**
+ * Result of a successful handshake — the live typed transport handle
+ * plus the resolved `AckPayload` from the first ack frame. The caller
+ * attaches `handle` to the triad's outbound send surface (via the
+ * BufferedManagerShim flush) and applies `ack.stack` to the stack
+ * model.
+ */
+export interface RegistrySubscribeHandle {
+    readonly handle: WsTransportHandle;
+    readonly ack: AckPayload;
+}
+/**
+ * Caller-provided callbacks. The runtime's `bootSequence` owns the
+ * concrete implementations; tests pass mocks via the `connectFn` seam.
+ */
+export interface ConnectViaRegistryOptions {
+    readonly bootstrap: GguiBootstrapMeta;
+    readonly registry: ChannelRegistry;
+    /**
+     * Fires on every transport-status transition mapped onto the
+     * protocol-level `ConnectionStatus` axis. The mapping is:
+     *
+     *   - First `'connecting'` after construction → `'connecting'`.
+     *   - First `'open'` → `'connected'`.
+     *   - `'closed'` after a prior `'open'` (drop) → `'disconnected'`.
+     *   - `'connecting'` after a prior `'open'` (reconnect attempt) →
+     *     `'reconnecting'`.
+     *   - `'failed'` → `'disconnected'` (terminal — the reconnect ladder
+     *     gave up). Also rejects the handshake promise pre-ack.
+     *
+     * The mapping is load-bearing for the renderer's status DOM logic
+     * (which already keyed off `ConnectionStatus`) and the
+     * `subscribe-failed` observability emission rule (fires on
+     * `'reconnecting'` only).
+     */
+    readonly onStatusChange: (status: ConnectionStatus) => void;
+    /**
+     * Optional typed {@link ProtocolError} sink. Pre-ack `error`
+     * frames are classified through this emitter in parallel with the
+     * throw/reject path.
+     */
+    readonly onProtocolError?: ProtocolErrorEmitter;
+    /**
+     * Optional {@link ObservabilityEmitter} sink. Two events flow:
+     *
+     *   - `schema-version-mismatch` — on every UPGRADE_REQUIRED
+     *     classification (client-side ack-mismatch + server-emitted
+     *     error frame).
+     *   - `subscribe-failed` — on non-terminal transport status
+     *     transitions to `'reconnecting'`. Terminal failures route
+     *     through the ProtocolError path only.
+     */
+    readonly onObserve?: ObservabilityEmitter;
+    /**
+     * Optional post-handshake ack callback. Fires for every ack frame
+     * AFTER the initial handshake settled — i.e. on every reconnect's
+     * subscribe ack. The runtime uses this to reapply the server's
+     * authoritative `stack` snapshot so a push or update that landed
+     * during a WS dropout window flows back into the iframe on
+     * reconnect.
+     *
+     * Idempotent at the runtime layer: `stackModel.setAll(ack.stack)`
+     * is a snapshot replace. Channels re-subscribed by
+     * `ChannelTransportRouter.onWsStatusChange('connected')` upstream
+     * of this callback, so the per-channel transport state is already
+     * coherent by the time the resubscribe-ack arrives.
+     */
+    readonly onResubscribeAck?: (ack: AckPayload) => void;
+}
+/**
+ * Open the WS via the registry, send subscribe (composed by the
+ * registry's `subscribeFrameBuilder`), await the first `ack`. Resolves
+ * with `{ handle, ack }` on success; rejects with
+ * `UpgradeRequiredError` on a version-handshake failure (either side);
+ * rejects with a plain `Error` on any other server-emitted pre-ack
+ * error.
+ *
+ * Once the promise settles, subsequent server frames flow through the
+ * registered channel handlers (props_update, drain_ack, push, data,
+ * etc.) — there is no longer a separate `onMessage` callback fanning
+ * frames across multiple handler chains.
+ */
+export declare function connectViaRegistry(opts: ConnectViaRegistryOptions): Promise<RegistrySubscribeHandle>;
+/**
+ * Default `connectFn` seam — tests can swap this for a fake to drive
+ * the handshake without a real WebSocket. The renderer's `bootSequence`
+ * accepts an optional override via the `BootSequenceOptions.connectFn`
+ * field; the default below points back at this module's
+ * `connectViaRegistry` export.
+ */
+export type ConnectFn = typeof connectViaRegistry;
+/**
+ * Type re-export for callers that want to thread the handle type
+ * through their own seams (e.g. `bootSequence`'s shim attach).
+ */
+export type { WsTransportHandle, ContractErrorPayload };