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

package/dist/provisional-renderer.js

@@ -0,0 +1,323 @@
+/**
+ * Provisional (A2UI preview) renderer for the iframe runtime.
+ *
+ * Port of `@ggui-ai/react::components/ProvisionalRenderer.tsx` with
+ * the React-hook consumer stripped. The A2UI reduce + adjacency-list
+ * render is preserved verbatim; the inputs + mount lifecycle differ:
+ *
+ *   - Host-SDK version reads via `useChannelStream(PREVIEW_CHANNEL)`
+ *     (a React hook subscribed to a live-channel bridge event).
+ *   - Iframe-renderer version is driven by an explicit
+ *     `pushEnvelope(env)` entry point invoked by `subscribe.ts` on
+ *     every validated inbound `data` envelope whose channel is
+ *     `_ggui:preview`. The caller (runtime.ts) forwards envelopes
+ *     after the reserved-channel A2UI validator has accepted them.
+ *
+ * Visual language: `PreviewSurface` / `PreviewFragmentEnter` /
+ * `StreamingText` from `@ggui-ai/design/preview`; primitive mapping
+ * from `@ggui-ai/design/primitives`. Matches the host-SDK output
+ * 1:1 — operator-visible preview DOM is identical on both paths.
+ *
+ * Lifecycle:
+ *
+ *   - `mountProvisional(container)` → `{pushEnvelope, suspend,
+ *     resume, unmount}` handle. The container renders the default
+ *     loading fallback until A2UI's `root` fragment arrives; then
+ *     the adjacency tree paints.
+ *   - `suspend()` hides the surface (used when the authoritative
+ *     render takes over — the stack-item dispatcher in Commit 4
+ *     toggles this on ReactComponentRenderer mount).
+ *   - `resume()` re-shows. Envelopes keep accumulating in state
+ *     while suspended, matching host-SDK behavior.
+ */
+import React, { createElement, Fragment, useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+/**
+ * Spec-canonical A2UI preview channel name (from
+ * `@ggui-ai/protocol::PREVIEW_CHANNEL`). Inlined here so this
+ * module's runtime imports stay off the protocol root barrel —
+ * importing the constant from `@ggui-ai/protocol` pulls in
+ * `openrouter-models` + the entire zod validation graph via the
+ * root re-export chain, adding ~250 KB gz to the renderer bundle.
+ * The value is a stable string literal (`isKnownReservedChannel`
+ * and the spec both reference `_ggui:preview` directly); re-declaring
+ * it here is shape-preserving and covered by the structural-lock
+ * test in the source module.
+ */
+const PREVIEW_CHANNEL = '_ggui:preview';
+import { parseServerMessage, } from '@ggui-ai/preview-a2ui';
+import { Button, Card, Checkbox, Divider, Heading, Icon, Image, Input, Row, Select, Spinner, Stack, Text, } from '@ggui-ai/design/primitives';
+import { PreviewFragmentEnter, PreviewSurface, StreamingText, } from '@ggui-ai/design/preview';
+const A2UI_ROOT_ID = 'root';
+const EMPTY_STATE = {
+    surfaceId: null,
+    fragments: new Map(),
+};
+function reduce(state, msg) {
+    if ('createSurface' in msg) {
+        return {
+            surfaceId: msg.createSurface.surfaceId,
+            fragments: new Map(),
+        };
+    }
+    if ('updateComponents' in msg) {
+        if (state.surfaceId !== msg.updateComponents.surfaceId)
+            return state;
+        const next = new Map(state.fragments);
+        for (const component of msg.updateComponents.components) {
+            next.set(component.id, component);
+        }
+        return { ...state, fragments: next };
+    }
+    if ('deleteSurface' in msg) {
+        if (state.surfaceId !== msg.deleteSurface.surfaceId)
+            return state;
+        return EMPTY_STATE;
+    }
+    return state;
+}
+function reduceAll(envelopes) {
+    let state = EMPTY_STATE;
+    for (const envelope of envelopes) {
+        const parsed = parseServerMessage(envelope.payload);
+        if (!parsed.ok)
+            continue;
+        state = reduce(state, parsed.value);
+    }
+    return state;
+}
+// =============================================================================
+// A2UI component → primitives renderer — ports renderComponent verbatim.
+// =============================================================================
+function UnresolvedPlaceholder() {
+    return createElement('div', {
+        style: {
+            minHeight: 24,
+            minWidth: 32,
+            borderRadius: 'var(--ggui-shape-radius-sm, 4px)',
+            backgroundColor: 'var(--ggui-color-outlineVariant, rgba(148, 163, 184, 0.18))',
+        },
+        'aria-hidden': 'true',
+    });
+}
+function UnsupportedComponentShell({ name }) {
+    return createElement(Card, { padding: 12, shadow: 'none', border: true }, createElement(Text, { variant: 'caption' }, `[${name}]`));
+}
+// Stable noop so React doesn't warn about switching onChange identity.
+function noopOnChange() {
+    // intentionally empty — provisional controls are non-interactive
+}
+function renderComponent(component, all) {
+    const resolveChildren = (childIds) => {
+        if (!childIds)
+            return [];
+        return childIds.map((id) => {
+            const child = all.get(id);
+            if (!child)
+                return createElement(UnresolvedPlaceholder, { key: id });
+            return renderComponent(child, all);
+        });
+    };
+    const { id } = component;
+    const wrap = (children) => createElement(PreviewFragmentEnter, { key: id, children });
+    switch (component.component) {
+        case 'Row':
+            return wrap(createElement(Row, {
+                gap: component.gap,
+                align: component.align ?? 'stretch',
+                justify: component.justify ?? 'start',
+            }, ...resolveChildren(component.children)));
+        case 'Column':
+            return wrap(createElement(Stack, {
+                direction: 'vertical',
+                gap: component.gap,
+                align: component.align ?? 'stretch',
+                justify: component.justify ?? 'start',
+            }, ...resolveChildren(component.children)));
+        case 'List':
+            return wrap(createElement(Stack, { direction: 'vertical', gap: 8 }, ...resolveChildren(component.children)));
+        case 'Card': {
+            const child = component.child ? all.get(component.child) : undefined;
+            const cardContent = component.child && !child
+                ? createElement(UnresolvedPlaceholder)
+                : child
+                    ? renderComponent(child, all)
+                    : null;
+            return wrap(createElement(Card, { padding: 16, shadow: 'sm' }, cardContent));
+        }
+        case 'Divider':
+            return wrap(createElement(Divider, { orientation: component.orientation ?? 'horizontal' }));
+        case 'Text': {
+            const variant = component.variant ?? 'body';
+            const headingMatch = /^h([1-6])$/.exec(variant);
+            if (headingMatch) {
+                const level = Number(headingMatch[1]);
+                return wrap(createElement(Heading, { level }, createElement(StreamingText, null, component.text)));
+            }
+            const textVariant = variant === 'label' || variant === 'caption' ? variant : 'body';
+            return wrap(createElement(Text, { variant: textVariant }, createElement(StreamingText, null, component.text)));
+        }
+        case 'Image':
+            return wrap(createElement(Image, { src: component.src, alt: component.alt ?? '' }));
+        case 'Icon':
+            return wrap(createElement(Icon, { name: component.name }));
+        case 'Button':
+            return wrap(createElement(Button, { disabled: true }, component.label));
+        case 'TextField':
+            return wrap(createElement(Input, {
+                disabled: true,
+                label: component.label,
+                placeholder: component.placeholder,
+                value: component.value ?? '',
+                onChange: noopOnChange,
+            }));
+        case 'CheckBox':
+            return wrap(createElement(Checkbox, {
+                disabled: true,
+                label: component.label ?? '',
+                checked: component.checked ?? false,
+                onChange: noopOnChange,
+            }));
+        case 'ChoicePicker': {
+            const options = component.options ?? [];
+            return wrap(createElement(Select, {
+                disabled: true,
+                label: component.label,
+                value: component.value ?? '',
+                options,
+                onChange: noopOnChange,
+            }));
+        }
+        default: {
+            const unknown = component;
+            return wrap(createElement(UnsupportedComponentShell, { name: unknown.component }));
+        }
+    }
+}
+/**
+ * Inner React component — drives the adjacency-list render against
+ * the accumulated envelope list. Re-render on suspend/resume or on
+ * new envelope is governed by the component's own useState setter in
+ * `ProvisionalController`.
+ */
+function ProvisionalRoot({ envelopes, suspended, fallback }) {
+    const state = reduceAll(envelopes);
+    if (suspended)
+        return null;
+    const root = state.fragments.get(A2UI_ROOT_ID);
+    if (!root) {
+        return createElement(Fragment, null, fallback ?? createElement(DefaultFallback));
+    }
+    return createElement(PreviewSurface, null, renderComponent(root, state.fragments));
+}
+function DefaultFallback() {
+    return createElement('div', {
+        style: {
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            minHeight: 80,
+        },
+    }, createElement(Spinner));
+}
+function ProvisionalController({ controlRef, onAttach, fallback, }) {
+    const [envelopes, setEnvelopes] = useState([]);
+    const [suspended, setSuspended] = useState(false);
+    useEffect(() => {
+        controlRef.current = {
+            pushEnvelope: (env) => {
+                if (env.channel !== PREVIEW_CHANNEL)
+                    return;
+                setEnvelopes((prev) => [...prev, env]);
+            },
+            suspend: () => setSuspended(true),
+            resume: () => setSuspended(false),
+        };
+        onAttach?.();
+        return () => {
+            controlRef.current = null;
+        };
+    }, [controlRef, onAttach]);
+    return createElement(ProvisionalRoot, {
+        envelopes,
+        suspended,
+        ...(fallback !== undefined ? { fallback } : {}),
+    });
+}
+/**
+ * Mount the provisional surface into `container`. Returns a handle
+ * callers use to push envelopes + suspend/resume + unmount.
+ *
+ * Synchronous-ish — the React root renders on next microtask, so
+ * the `controlRef` is populated by the time the caller's next
+ * microtask runs. Tests use `await Promise.resolve()` to sync.
+ */
+export function mountProvisional(container, opts = {}) {
+    container.replaceChildren();
+    const root = createRoot(container);
+    const controlRef = { current: null };
+    // Buffer envelopes that arrive before React's first effect runs.
+    // Once `controlRef.current` exists we drain the buffer in order;
+    // same for suspend/resume calls. Matches ProvisionalRenderer's
+    // pre-mount semantics (envelopes are reduced in arrival order
+    // regardless of mount timing).
+    //
+    // Drain trigger: React fires `onAttach` from the controller's
+    // `useEffect` once `controlRef.current` is populated. Pre-fix this
+    // path scheduled `queueMicrotask(drainPending)` from `pushEnvelope`,
+    // which raced React's commit — when the microtask won, the queue
+    // was abandoned because `controlRef.current` was still null and the
+    // microtask never re-fired. The reserved-channel replay path on the
+    // iframe-runtime delivers WS frames synchronously from the WS
+    // message handler, so this race fired every time on a freshly-
+    // navigated viewer.
+    const pending = [];
+    let pendingSuspendState = null;
+    function drainPending() {
+        const ref = controlRef.current;
+        if (ref === null)
+            return;
+        for (const env of pending)
+            ref.pushEnvelope(env);
+        pending.length = 0;
+        if (pendingSuspendState === true)
+            ref.suspend();
+        if (pendingSuspendState === false)
+            ref.resume();
+        pendingSuspendState = null;
+    }
+    root.render(createElement(ProvisionalController, {
+        controlRef,
+        onAttach: drainPending,
+        ...(opts.fallback !== undefined ? { fallback: opts.fallback } : {}),
+    }));
+    return {
+        pushEnvelope(envelope) {
+            if (controlRef.current === null) {
+                pending.push(envelope);
+                return;
+            }
+            controlRef.current.pushEnvelope(envelope);
+        },
+        suspend() {
+            if (controlRef.current === null) {
+                pendingSuspendState = true;
+                return;
+            }
+            controlRef.current.suspend();
+        },
+        resume() {
+            if (controlRef.current === null) {
+                pendingSuspendState = false;
+                return;
+            }
+            controlRef.current.resume();
+        },
+        unmount() {
+            root.unmount();
+            container.replaceChildren();
+        },
+    };
+}
+// Re-export React for internal symmetry with react-renderer.ts.
+export { React };

package/dist/react-renderer.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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, { type ReactNode } from 'react';
+export interface ReactRootMountOptions {
+    /**
+     * Stack item whose componentCode + props drive the mount. Only
+     * `componentCode` + `props` are read here; the caller is
+     * responsible for wrapping this with a `<GguiWireProvider>` at the
+     * higher-level dispatcher (see `stack-item-renderer.ts` in Commit
+     * 4).
+     */
+    readonly stackItem: {
+        readonly id?: string;
+        readonly componentCode: string;
+        readonly props?: Record<string, unknown>;
+    };
+    readonly themeId?: string;
+    /**
+     * Theme color mode resolved for this mount. Forwards to
+     * `getScopedThemeCss` / `getThemeCss` so the dark variant of the
+     * registered theme paints when the operator selected it.
+     */
+    readonly themeMode?: 'light' | 'dark';
+    readonly cssOverrides?: string;
+    readonly onError?: (error: Error) => void;
+    readonly onRequestRepair?: (error: Error) => void;
+    /**
+     * Children injected BETWEEN the mount DOM (scope + CSS) and the
+     * evaluated component element. The caller's stack-item renderer
+     * uses this to wrap the eval'd component in `<GguiWireProvider>`
+     * so wire hooks resolve per-item contracts.
+     *
+     * When `undefined`, the evaluated component renders directly.
+     */
+    readonly renderWrapper?: (mountedComponent: ReactNode) => ReactNode;
+    /**
+     * Bare npm package names of the operator-registered 3rd-party gadget
+     * packages reachable in this session (GG.8.2). Forwarded to
+     * `rewriteImports` so each direct gadget import resolves to its
+     * per-package data-URL shim. Sourced from the bootstrap's `gadgets`
+     * channel; `@ggui-ai/gadgets` (STDLIB) is always rewritten and need
+     * not appear here.
+     */
+    readonly gadgetPackages?: readonly string[];
+}
+export interface ReactRootMount {
+    /**
+     * Swap props (and/or componentCode). When componentCode changes,
+     * the module is re-evaluated. Pure-props changes skip the
+     * evaluation and re-render with new props — matches RCR's
+     * `useEffect([code])` dependency behavior.
+     */
+    update(next: ReactRootMountOptions): Promise<void>;
+    /** Tear down the React root + release retained state. */
+    unmount(): void;
+    /** Current component code (useful for tests + audit). */
+    readonly currentCode: string | 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 declare function mountReactRoot(container: HTMLElement, opts: ReactRootMountOptions): Promise<ReactRootMount>;
+export { React };