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

package/dist/{stack-item-renderer.js → render-item.js}

@@ -1,27 +1,32 @@
 /**
- * Stack-item dispatcher — routes each SessionStackEntry to the
+ * Render dispatcher — routes a single {@link Render} to the
  * appropriate renderer based on its discriminator.
  *
+ * Post-render-identity-collapse (2026-05-27): the iframe-runtime mounts
+ * EXACTLY ONE render per iframe, in a single container. This module
+ * exposes one entry point — {@link mountRender} — that returns a
+ * {@link RenderItemHandle} the runtime uses to apply subsequent
+ * patches (props_update) or unmount on teardown. The earlier
+ * `StackRenderer` / `StackRenderContext` orchestrator (a stack-of-N
+ * map keyed by item id) was retired along with `StackModel`.
+ *
  * The dispatch tree mirrors `@ggui-ai/react::DynamicComponent` +
- * `McpAppsStackItemRenderer`:
+ * `GguiRender`'s MCP-Apps branch:
  *
  *   - `type === 'mcpApps'` → `mountMcpAppIframe` (vanilla iframe
  *     host; the recursive foreign-MCP-App path).
  *   - `componentCode` empty OR absent → `mountProvisional` (A2UI
  *     preview fed by the `_ggui:preview` reserved channel).
- *   - otherwise → `mountReactRoot` with a per-item `WireConfig`
- *     built via the renderer's `buildScopedConfig(item)` closure.
- *     The mounted component is wrapped in
+ *   - otherwise → `mountReactRoot` with a per-render `WireConfig`
+ *     built by the caller. The mounted component is wrapped in
  *     `<GguiWireProvider config={scopedConfig}>` through the
  *     `renderWrapper` seam.
  *
- * Per-item lifecycle:
+ * Per-render lifecycle:
  *
- *   Each stack entry owns a SINGLE `StackItemHandle` for its visible
- *   lifetime. When the entry gets replaced in-place (push matched by
- *   id), the dispatcher transitions the existing handle rather than
- *   unmount + remount — props-only changes skip the React eval; kind
- *   changes unmount the current and mount the replacement.
+ *   The handle's `update()` either transitions in-place (props-only,
+ *   same kind) or tears down + remounts (kind changed — provisional
+ *   → react when componentCode lands).
  *
  * StreamBus integration:
  *
@@ -40,16 +45,17 @@ import { mountMcpAppIframe, } from './mcp-app-iframe-host.js';
 // =============================================================================
 // Kind detection
 // =============================================================================
-function detectKind(stackItem) {
-    if (stackItem.type === 'mcpApps')
+function detectKind(render) {
+    if (render.type === 'mcpApps')
         return 'mcpApps';
-    // System items don't route through this stack-item dispatcher — the
-    // self-contained boot path renders them via `SystemCardHost` directly.
-    // If one accidentally lands here, fall through to provisional so the
-    // user at least sees the A2UI placeholder rather than a crash.
-    if (stackItem.type === 'system')
-        return 'provisional';
-    const code = stackItem.componentCode;
+    // System renders mount via the built-in `SystemCardHost` registry
+    // (the `'system'` branch in `mountByKind`). This is the single mount
+    // surface for server-emitted `kind` cards post boot-consolidation —
+    // the old self-contained path that hand-rolled `SystemCardHost` is
+    // gone, so this MUST route to `'system'`, not the A2UI placeholder.
+    if (render.type === 'system')
+        return 'system';
+    const code = render.componentCode;
     if (typeof code === 'string' && code.trim().length > 0)
         return 'react';
     return 'provisional';
@@ -57,13 +63,18 @@ function detectKind(stackItem) {
 // =============================================================================
 // Mount
 // =============================================================================
-export async function renderStackItem(container, opts) {
+export async function mountRender(container, opts) {
     let currentOpts = opts;
     let currentKind = 'none';
     let reactMount = null;
     let provisionalMount = null;
     let mcpMount = null;
     let previewUnsubscribe = null;
+    // System-card mount (type:'system'). The render-only `SystemCardHost`
+    // tree has no wire/context wrap; we hold the react-dom Root for
+    // teardown + a re-render closure for same-kind prop updates.
+    let systemRoot = null;
+    let systemRerender = null;
     function teardown() {
         if (reactMount !== null) {
             reactMount.unmount();
@@ -77,6 +88,11 @@ export async function renderStackItem(container, opts) {
             mcpMount.unmount();
             mcpMount = null;
         }
+        if (systemRoot !== null) {
+            systemRoot.unmount();
+            systemRoot = null;
+            systemRerender = null;
+        }
         if (previewUnsubscribe !== null) {
             previewUnsubscribe();
             previewUnsubscribe = null;
@@ -85,11 +101,11 @@ export async function renderStackItem(container, opts) {
     }
     async function mountByKind(kind) {
         if (kind === 'mcpApps') {
-            // SessionStackEntry narrows to McpAppsStackItem when type='mcpApps'.
-            const item = currentOpts.stackItem;
+            // Render narrows to McpAppsRender when type='mcpApps'.
+            const render = currentOpts.render;
             mcpMount = mountMcpAppIframe(container, {
-                stackItem: item,
-                sessionId: currentOpts.sessionId,
+                render,
+                renderId: currentOpts.renderId,
                 ...(currentOpts.mcpAppsServerBaseUrl !== undefined
                     ? { serverBaseUrl: currentOpts.mcpAppsServerBaseUrl }
                     : {}),
@@ -97,6 +113,39 @@ export async function renderStackItem(container, opts) {
             currentKind = 'mcpApps';
             return;
         }
+        if (kind === 'system') {
+            // System card — server-emitted `kind` mapped to a built-in
+            // `.tsx` via `SystemCardHost`. Render-only: no `__ggui__` shim,
+            // no GguiWireProvider, no contextSpec wrap (system cards don't
+            // dispatch wire actions or read contexts). The registry handles
+            // unknown kinds via a typed fallback. Dynamic-import keeps the
+            // system-cards module out of the base graph (boot.test.ts +
+            // non-system mounts never pull it).
+            const render = currentOpts.render;
+            if (render.type !== 'system')
+                return;
+            const [reactDomClient, systemCardsMod] = await Promise.all([
+                import('react-dom/client'),
+                import('./system-cards/index.js'),
+            ]);
+            const root = reactDomClient.createRoot(container);
+            const renderCard = (r) => {
+                if (r.type !== 'system')
+                    return;
+                root.render(createElement(systemCardsMod.SystemCardHost, {
+                    kind: r.kind,
+                    props: r.props ?? {},
+                    ...(currentOpts.themeId !== undefined
+                        ? { themeId: currentOpts.themeId }
+                        : {}),
+                }));
+            };
+            renderCard(render);
+            systemRoot = root;
+            systemRerender = renderCard;
+            currentKind = 'system';
+            return;
+        }
         if (kind === 'provisional') {
             provisionalMount = mountProvisional(container);
             previewUnsubscribe = currentOpts.streamBus.subscribe('_ggui:preview', (env) => {
@@ -107,21 +156,21 @@ export async function renderStackItem(container, opts) {
         }
         // kind === 'react' — detectKind guarantees a generated component
         // variant (no mcpApps, no system) by this point.
-        const item = currentOpts.stackItem;
-        if (item.type === 'mcpApps' || item.type === 'system')
+        const render = currentOpts.render;
+        if (render.type === 'mcpApps' || render.type === 'system')
             return;
-        // GG.8.2 — gadget package names from the item's descriptor sidecar
+        // GG.8.2 — gadget package names from the render's descriptor sidecar
         // so the rewriter resolves each direct gadget import to its
         // per-package shim. STDLIB `@ggui-ai/gadgets` is always rewritten.
-        const gadgetPackages = 'gadgetDescriptors' in item && item.gadgetDescriptors !== undefined
-            ? item.gadgetDescriptors.map((d) => d.package)
-            : undefined;
+        const gadgetPackages = 'gadgetDescriptors' in render && render.gadgetDescriptors !== undefined
+            ? render.gadgetDescriptors.map((d) => d.package)
+            : currentOpts.gadgetPackages;
         reactMount = await mountReactRoot(container, {
-            stackItem: {
-                ...(item.id !== undefined ? { id: item.id } : {}),
-                componentCode: item.componentCode ?? '',
-                ...(item.props !== undefined
-                    ? { props: item.props }
+            render: {
+                ...(render.id !== undefined ? { id: render.id } : {}),
+                componentCode: render.componentCode ?? '',
+                ...(render.props !== undefined
+                    ? { props: render.props }
                     : {}),
             },
             ...(gadgetPackages !== undefined ? { gadgetPackages } : {}),
@@ -150,7 +199,7 @@ export async function renderStackItem(container, opts) {
      *     wrapOuter(<GguiWireProvider><userComponent/></GguiWireProvider>)
      *
      * `wrapOuter` is supplied by `bootProduction` to install the
-     * `<ContextStateHost>` provider tree around the per-item React
+     * `<ContextStateHost>` provider tree around the per-render React
      * mount. When absent, the wire provider is the only wrapper.
      */
     function wrapInScopedProvider(mountedComponent) {
@@ -162,7 +211,7 @@ export async function renderStackItem(container, opts) {
             : wireWrapped;
     }
     // Initial mount.
-    const initialKind = detectKind(opts.stackItem);
+    const initialKind = detectKind(opts.render);
     await mountByKind(initialKind);
     return {
         get kind() {
@@ -171,7 +220,7 @@ export async function renderStackItem(container, opts) {
         async update(next) {
             const prevKind = currentKind;
             currentOpts = next;
-            const nextKind = detectKind(next.stackItem);
+            const nextKind = detectKind(next.render);
             if (nextKind !== prevKind) {
                 // Kind changed — tear down old + mount new.
                 teardown();
@@ -180,15 +229,15 @@ export async function renderStackItem(container, opts) {
             }
             // Same-kind update — route to the inner renderer's update.
             if (nextKind === 'react' && reactMount !== null) {
-                const item = next.stackItem;
-                if (item.type === 'mcpApps' || item.type === 'system')
+                const render = next.render;
+                if (render.type === 'mcpApps' || render.type === 'system')
                     return;
                 await reactMount.update({
-                    stackItem: {
-                        ...(item.id !== undefined ? { id: item.id } : {}),
-                        componentCode: item.componentCode ?? '',
-                        ...(item.props !== undefined
-                            ? { props: item.props }
+                    render: {
+                        ...(render.id !== undefined ? { id: render.id } : {}),
+                        componentCode: render.componentCode ?? '',
+                        ...(render.props !== undefined
+                            ? { props: render.props }
                             : {}),
                     },
                     ...(next.themeId !== undefined ? { themeId: next.themeId } : {}),
@@ -200,6 +249,17 @@ export async function renderStackItem(container, opts) {
                         : {}),
                     renderWrapper: wrapInScopedProvider,
                 });
+                return;
+            }
+            // Same-kind system update — re-render the card with new props
+            // through the retained root (no teardown). System cards are
+            // pure functions of (kind, props); a props delta just re-renders.
+            if (nextKind === 'system' && systemRerender !== null) {
+                const render = next.render;
+                if (render.type !== 'system')
+                    return;
+                systemRerender(render);
+                return;
             }
             // provisional / mcpApps same-kind: no in-place update surface.
             // Provisional keeps accumulating envelopes; mcpApps iframe
@@ -208,63 +268,3 @@ export async function renderStackItem(container, opts) {
         unmount: teardown,
     };
 }
-/**
- * Minimal stack-level orchestrator — keyed by stackItem.id, mounts
- * new items, updates existing ones, unmounts removed ones.
- *
- * The production renderer tree uses this; tests can drive the
- * individual `renderStackItem` entry point directly.
- */
-export class StackRenderer {
-    ctx;
-    handles = new Map();
-    constructor(ctx) {
-        this.ctx = ctx;
-    }
-    async applyStack(stack) {
-        const nextIds = new Set(stack.map((s) => s.id));
-        // Unmount removed items.
-        for (const [id, handle] of this.handles) {
-            if (!nextIds.has(id)) {
-                handle.unmount();
-                this.handles.delete(id);
-            }
-        }
-        // Mount or update each item in stack order.
-        for (const item of stack) {
-            const container = this.ctx.containerFor(item.id);
-            const scopedWireConfig = this.ctx.getScopedWireConfig(item);
-            const wrapOuter = this.ctx.getOuterWrapper?.(item);
-            const opts = {
-                stackItem: item,
-                scopedWireConfig,
-                streamBus: this.ctx.streamBus,
-                sessionId: this.ctx.sessionId,
-                ...(this.ctx.mcpAppsServerBaseUrl !== undefined
-                    ? { mcpAppsServerBaseUrl: this.ctx.mcpAppsServerBaseUrl }
-                    : {}),
-                ...(this.ctx.themeId !== undefined ? { themeId: this.ctx.themeId } : {}),
-                ...(this.ctx.themeMode !== undefined ? { themeMode: this.ctx.themeMode } : {}),
-                ...(this.ctx.onError !== undefined ? { onError: this.ctx.onError } : {}),
-                ...(this.ctx.onRequestRepair !== undefined
-                    ? { onRequestRepair: this.ctx.onRequestRepair }
-                    : {}),
-                ...(wrapOuter !== undefined ? { wrapOuter } : {}),
-            };
-            const existing = this.handles.get(item.id);
-            if (existing === undefined) {
-                const handle = await renderStackItem(container, opts);
-                this.handles.set(item.id, handle);
-            }
-            else {
-                await existing.update(opts);
-            }
-        }
-    }
-    unmountAll() {
-        for (const handle of this.handles.values()) {
-            handle.unmount();
-        }
-        this.handles.clear();
-    }
-}