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

package/dist/server.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Absolute filesystem path to the built iframe-runtime bundle
+ * (`dist/iframe-runtime.js`).
+ *
+ *   - Contents: single self-contained ESM module — React + ReactDOM +
+ *     `@ggui-ai/wire` + `@ggui-ai/design` + `@ggui-ai/preview-a2ui` +
+ *     protocol zod transitives all bundled in.
+ *   - Written by `esbuild.config.mjs`
+ *     (`pnpm --filter @ggui-ai/iframe-runtime build`).
+ *   - Served by `@ggui-ai/mcp-server` at `/_ggui/iframe-runtime.js`
+ *     under the `runtime: true` config branch.
+ *
+ * If the file does not exist at runtime (operator forgot to run
+ * `pnpm build`), the mcp-server's static route should surface a
+ * clear "run `pnpm build`" 503 rather than silently 404ing — that
+ * decision lives in mcp-server, not here.
+ */
+export declare const RUNTIME_BUNDLE_FILE: string;
+/**
+ * The same path exposed as a directory for
+ * `express.static(RUNTIME_DIST_DIR)` — when the mcp-server mount
+ * prefers the static-middleware shape over explicit `sendFile`.
+ * Either approach works; both point at the same bundle file.
+ */
+export declare const RUNTIME_DIST_DIR: string;
+/**
+ * The default same-origin URL under which the mcp-server publishes
+ * the bundle. Canonical string so producers (server config) and
+ * consumers (shell HTML) agree on one spelling.
+ *
+ * Operators who serve the bundle from a different origin (CDN,
+ * proxy) override this by setting the MCP server's `runtime.path`
+ * config — the shell always reads the URL from
+ * `bootstrap.runtimeUrl`, never hardcodes it.
+ */
+export declare const RUNTIME_BUNDLE_URL_PATH: "/_ggui/iframe-runtime.js";

package/dist/server.js

@@ -0,0 +1,72 @@
+/**
+ * Server-side export for `@ggui-ai/iframe-runtime`.
+ *
+ * This module is imported by `@ggui-ai/mcp-server` to locate the built
+ * iframe-runtime bundle on disk — exposed via an `express.static`-style
+ * file handler at `/_ggui/iframe-runtime.js`. It contains **no browser
+ * code** — never import React, DOM types, or anything from
+ * `src/runtime.ts` here.
+ *
+ * Rationale for the `./server` export split mirrors `@ggui-ai/console`:
+ *
+ *   - The iframe runtime bundle lives in `dist/iframe-runtime.js`
+ *     (esbuild output: single self-contained ESM module).
+ *   - The server helper ships from `dist/server.js` (tsc output).
+ *   - mcp-server only needs a path string
+ *     ({@link RUNTIME_BUNDLE_FILE}) plus a type. Keeping those
+ *     apart from the iframe runtime lets consumers import
+ *     `@ggui-ai/iframe-runtime/server` without pulling React / ReactDOM /
+ *     the full browser graph through their module graph.
+ *
+ * If you add more server-side helpers (e.g. CSP directives, SRI hash
+ * pre-computation), land them here — NOT in `src/runtime.ts` or
+ * `src/index.ts`.
+ */
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+/**
+ * Resolve the directory where this compiled module ends up at runtime.
+ * `dist/server.js` is the canonical location (tsc's `outDir`); the
+ * bundle (`dist/iframe-runtime.js`) is a sibling written by esbuild.
+ *
+ * Computed via `import.meta.url` so the resolver is independent of
+ * CWD — consumers mount this server inside CLIs, Lambdas, and tests
+ * with arbitrary working directories.
+ */
+const here = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Absolute filesystem path to the built iframe-runtime bundle
+ * (`dist/iframe-runtime.js`).
+ *
+ *   - Contents: single self-contained ESM module — React + ReactDOM +
+ *     `@ggui-ai/wire` + `@ggui-ai/design` + `@ggui-ai/preview-a2ui` +
+ *     protocol zod transitives all bundled in.
+ *   - Written by `esbuild.config.mjs`
+ *     (`pnpm --filter @ggui-ai/iframe-runtime build`).
+ *   - Served by `@ggui-ai/mcp-server` at `/_ggui/iframe-runtime.js`
+ *     under the `runtime: true` config branch.
+ *
+ * If the file does not exist at runtime (operator forgot to run
+ * `pnpm build`), the mcp-server's static route should surface a
+ * clear "run `pnpm build`" 503 rather than silently 404ing — that
+ * decision lives in mcp-server, not here.
+ */
+export const RUNTIME_BUNDLE_FILE = path.resolve(here, 'iframe-runtime.js');
+/**
+ * The same path exposed as a directory for
+ * `express.static(RUNTIME_DIST_DIR)` — when the mcp-server mount
+ * prefers the static-middleware shape over explicit `sendFile`.
+ * Either approach works; both point at the same bundle file.
+ */
+export const RUNTIME_DIST_DIR = path.dirname(RUNTIME_BUNDLE_FILE);
+/**
+ * The default same-origin URL under which the mcp-server publishes
+ * the bundle. Canonical string so producers (server config) and
+ * consumers (shell HTML) agree on one spelling.
+ *
+ * Operators who serve the bundle from a different origin (CDN,
+ * proxy) override this by setting the MCP server's `runtime.path`
+ * config — the shell always reads the URL from
+ * `bootstrap.runtimeUrl`, never hardcodes it.
+ */
+export const RUNTIME_BUNDLE_URL_PATH = '/_ggui/iframe-runtime.js';

package/dist/stack-item-renderer.d.ts

@@ -0,0 +1,103 @@
+import type { ReactNode } from 'react';
+import type { SessionStackEntry } from '@ggui-ai/protocol';
+import { type WireConfig } from '@ggui-ai/wire';
+import type { StreamBus } from './wire-config.js';
+export interface StackItemRendererOptions {
+    /** The stack item to render. */
+    readonly stackItem: SessionStackEntry;
+    /** Wire config for this item — pre-scoped via the renderer's
+     *  `buildScopedConfig(item)` (see
+     *  `wire-config.ts::RootWireConfigBundle`). */
+    readonly scopedWireConfig: WireConfig | null;
+    /** Shared stream bus — provisional renderer subscribes to
+     *  `_ggui:preview` for this item. */
+    readonly streamBus: StreamBus;
+    /** Session id — used by the mcp-apps iframe host for proxy URLs. */
+    readonly sessionId: string;
+    /** ggui-server base URL (for mcp-apps proxy). Empty = same-origin. */
+    readonly mcpAppsServerBaseUrl?: string;
+    /** Theme id passed to ReactComponentRenderer for scoped CSS. */
+    readonly themeId?: string;
+    /**
+     * Theme color mode. Resolves the dark variant of `themeId` when set
+     * to `'dark'`. Falls through to `'light'` if absent — matches the
+     * design registry's `getTheme(id, mode?)` default.
+     */
+    readonly themeMode?: 'light' | 'dark';
+    readonly cssOverrides?: string;
+    readonly onError?: (err: Error) => void;
+    readonly onRequestRepair?: (err: Error) => void;
+    /**
+     * Optional outer wrapper applied AROUND the GguiWireProvider — used
+     * by `bootProduction` to install the `<ContextStateHost>` provider
+     * tree. Composition order:
+     *
+     *     wrapOuter(<GguiWireProvider><userComponent/></GguiWireProvider>)
+     *
+     * `wrapOuter` returns the wrapped node; passing `undefined` is
+     * equivalent to the identity function (no extra wrapping). The
+     * self-contained boot path inlines its own ContextStateHost via the
+     * top-level `renderWrapper`; this seam exists for the WS-driven
+     * triad path where the per-item React mount is the only mount
+     * surface.
+     */
+    readonly wrapOuter?: (mountedTree: ReactNode) => ReactNode;
+}
+/**
+ * Discriminator for WHICH renderer is currently mounted under this
+ * stack-item handle. Transitions: 'provisional' → 'react' when
+ * componentCode lands; 'react' → 'react' on code/prop updates;
+ * 'mcpApps' is terminal for its lifetime (mcp-apps items never
+ * become components + vice versa).
+ */
+type MountedKind = 'provisional' | 'react' | 'mcpApps' | 'none';
+export interface StackItemHandle {
+    /**
+     * Apply an update to the stack-item handle. Kind changes (e.g.
+     * provisional → react when componentCode lands) tear down the old
+     * mount and stand up the replacement; same-kind updates route to
+     * the inner renderer's `update()`.
+     */
+    update(next: StackItemRendererOptions): Promise<void>;
+    /** Tear down the active mount + unsubscribe from the StreamBus. */
+    unmount(): void;
+    /** Current render kind. Test-only — not load-bearing. */
+    readonly kind: MountedKind;
+}
+export declare function renderStackItem(container: HTMLElement, opts: StackItemRendererOptions): Promise<StackItemHandle>;
+export interface StackRenderContext {
+    readonly containerFor: (stackItemId: string) => HTMLElement;
+    readonly getScopedWireConfig: (item: SessionStackEntry) => WireConfig | null;
+    readonly streamBus: StreamBus;
+    readonly sessionId: string;
+    readonly mcpAppsServerBaseUrl?: string;
+    readonly themeId?: string;
+    /** Theme color mode — see {@link StackItemRendererOptions.themeMode}. */
+    readonly themeMode?: 'light' | 'dark';
+    readonly onError?: (err: Error) => void;
+    readonly onRequestRepair?: (err: Error) => void;
+    /**
+     * Optional outer wrapper for each stack-item React mount — see
+     * {@link StackItemRendererOptions.wrapOuter}. `bootProduction` uses
+     * this to inject `<ContextStateHost>` around every per-item React
+     * root, mirroring the wrap `bootSelfContained` performs at its
+     * single React root. Returning the input unchanged is equivalent
+     * to passing `undefined`.
+     */
+    readonly getOuterWrapper?: (item: SessionStackEntry) => ((mountedTree: ReactNode) => ReactNode) | undefined;
+}
+/**
+ * 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 declare class StackRenderer {
+    private readonly ctx;
+    private handles;
+    constructor(ctx: StackRenderContext);
+    applyStack(stack: readonly SessionStackEntry[]): Promise<void>;
+    unmountAll(): void;
+}
+export {};

package/dist/stack-item-renderer.js

@@ -0,0 +1,270 @@
+/**
+ * Stack-item dispatcher — routes each SessionStackEntry to the
+ * appropriate renderer based on its discriminator.
+ *
+ * The dispatch tree mirrors `@ggui-ai/react::DynamicComponent` +
+ * `McpAppsStackItemRenderer`:
+ *
+ *   - `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
+ *     `<GguiWireProvider config={scopedConfig}>` through the
+ *     `renderWrapper` seam.
+ *
+ * Per-item 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.
+ *
+ * StreamBus integration:
+ *
+ *   The dispatcher subscribes the mounted provisional renderer to
+ *   `_ggui:preview` envelopes via the caller-provided StreamBus. On
+ *   ReactComponentRenderer mount (componentCode lands), the
+ *   provisional surface is `suspend()`-ed so the authoritative render
+ *   takes over — matches DynamicComponent's componentCode-present
+ *   gate.
+ */
+import { createElement } from 'react';
+import { GguiWireProvider } from '@ggui-ai/wire';
+import { mountReactRoot } from './react-renderer.js';
+import { mountProvisional, } from './provisional-renderer.js';
+import { mountMcpAppIframe, } from './mcp-app-iframe-host.js';
+// =============================================================================
+// Kind detection
+// =============================================================================
+function detectKind(stackItem) {
+    if (stackItem.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;
+    if (typeof code === 'string' && code.trim().length > 0)
+        return 'react';
+    return 'provisional';
+}
+// =============================================================================
+// Mount
+// =============================================================================
+export async function renderStackItem(container, opts) {
+    let currentOpts = opts;
+    let currentKind = 'none';
+    let reactMount = null;
+    let provisionalMount = null;
+    let mcpMount = null;
+    let previewUnsubscribe = null;
+    function teardown() {
+        if (reactMount !== null) {
+            reactMount.unmount();
+            reactMount = null;
+        }
+        if (provisionalMount !== null) {
+            provisionalMount.unmount();
+            provisionalMount = null;
+        }
+        if (mcpMount !== null) {
+            mcpMount.unmount();
+            mcpMount = null;
+        }
+        if (previewUnsubscribe !== null) {
+            previewUnsubscribe();
+            previewUnsubscribe = null;
+        }
+        currentKind = 'none';
+    }
+    async function mountByKind(kind) {
+        if (kind === 'mcpApps') {
+            // SessionStackEntry narrows to McpAppsStackItem when type='mcpApps'.
+            const item = currentOpts.stackItem;
+            mcpMount = mountMcpAppIframe(container, {
+                stackItem: item,
+                sessionId: currentOpts.sessionId,
+                ...(currentOpts.mcpAppsServerBaseUrl !== undefined
+                    ? { serverBaseUrl: currentOpts.mcpAppsServerBaseUrl }
+                    : {}),
+            });
+            currentKind = 'mcpApps';
+            return;
+        }
+        if (kind === 'provisional') {
+            provisionalMount = mountProvisional(container);
+            previewUnsubscribe = currentOpts.streamBus.subscribe('_ggui:preview', (env) => {
+                provisionalMount?.pushEnvelope(env);
+            });
+            currentKind = 'provisional';
+            return;
+        }
+        // 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')
+            return;
+        // GG.8.2 — gadget package names from the item'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;
+        reactMount = await mountReactRoot(container, {
+            stackItem: {
+                ...(item.id !== undefined ? { id: item.id } : {}),
+                componentCode: item.componentCode ?? '',
+                ...(item.props !== undefined
+                    ? { props: item.props }
+                    : {}),
+            },
+            ...(gadgetPackages !== undefined ? { gadgetPackages } : {}),
+            ...(currentOpts.themeId !== undefined ? { themeId: currentOpts.themeId } : {}),
+            ...(currentOpts.themeMode !== undefined ? { themeMode: currentOpts.themeMode } : {}),
+            ...(currentOpts.cssOverrides !== undefined
+                ? { cssOverrides: currentOpts.cssOverrides }
+                : {}),
+            ...(currentOpts.onError !== undefined ? { onError: currentOpts.onError } : {}),
+            ...(currentOpts.onRequestRepair !== undefined
+                ? { onRequestRepair: currentOpts.onRequestRepair }
+                : {}),
+            renderWrapper: wrapInScopedProvider,
+        });
+        currentKind = 'react';
+    }
+    /**
+     * Wrap the mounted component in `<GguiWireProvider
+     * config={scopedConfig}>` when the caller supplied one. Without a
+     * scoped config, the component renders standalone — matches
+     * today's DynamicComponent fallback when no GguiSession parent is
+     * present.
+     *
+     * Composition order (outer → inner):
+     *
+     *     wrapOuter(<GguiWireProvider><userComponent/></GguiWireProvider>)
+     *
+     * `wrapOuter` is supplied by `bootProduction` to install the
+     * `<ContextStateHost>` provider tree around the per-item React
+     * mount. When absent, the wire provider is the only wrapper.
+     */
+    function wrapInScopedProvider(mountedComponent) {
+        const wireWrapped = currentOpts.scopedWireConfig === null
+            ? mountedComponent
+            : createElement(GguiWireProvider, { config: currentOpts.scopedWireConfig, children: mountedComponent });
+        return currentOpts.wrapOuter !== undefined
+            ? currentOpts.wrapOuter(wireWrapped)
+            : wireWrapped;
+    }
+    // Initial mount.
+    const initialKind = detectKind(opts.stackItem);
+    await mountByKind(initialKind);
+    return {
+        get kind() {
+            return currentKind;
+        },
+        async update(next) {
+            const prevKind = currentKind;
+            currentOpts = next;
+            const nextKind = detectKind(next.stackItem);
+            if (nextKind !== prevKind) {
+                // Kind changed — tear down old + mount new.
+                teardown();
+                await mountByKind(nextKind);
+                return;
+            }
+            // 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')
+                    return;
+                await reactMount.update({
+                    stackItem: {
+                        ...(item.id !== undefined ? { id: item.id } : {}),
+                        componentCode: item.componentCode ?? '',
+                        ...(item.props !== undefined
+                            ? { props: item.props }
+                            : {}),
+                    },
+                    ...(next.themeId !== undefined ? { themeId: next.themeId } : {}),
+                    ...(next.themeMode !== undefined ? { themeMode: next.themeMode } : {}),
+                    ...(next.cssOverrides !== undefined ? { cssOverrides: next.cssOverrides } : {}),
+                    ...(next.onError !== undefined ? { onError: next.onError } : {}),
+                    ...(next.onRequestRepair !== undefined
+                        ? { onRequestRepair: next.onRequestRepair }
+                        : {}),
+                    renderWrapper: wrapInScopedProvider,
+                });
+            }
+            // provisional / mcpApps same-kind: no in-place update surface.
+            // Provisional keeps accumulating envelopes; mcpApps iframe
+            // doesn't rebind its src during its lifetime.
+        },
+        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();
+    }
+}

package/dist/stack.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Stack state + structural-placeholder DOM rendering.
+ *
+ * This module owns the placeholder render path: each stack item is
+ * drawn as a structural placeholder showing id + description/prompt.
+ * The React mount path that executes `componentCode` lives elsewhere
+ * and swaps in over the same DOM seam.
+ *
+ * The model + the DOM render are split so:
+ *   - `StackModel` is testable in isolation (no DOM needed for unit
+ *     tests around upsert / replace / clear semantics);
+ *   - `renderStackInto(el, model)` is the only place that touches DOM,
+ *     making it the seam the React mount path swaps out without
+ *     disturbing the WS message handler.
+ *
+ * Stack ordering follows the wire shape: the ack's initial `stack` is
+ * displayed in array order; each `push` either replaces an item with
+ * the same id (preserving its position) or appends at the tail.
+ */
+import type { SessionStackEntry } from '@ggui-ai/protocol';
+/**
+ * Construction options for {@link StackModel}.
+ *
+ * @public
+ */
+export interface StackModelOptions {
+    /**
+     * When present, the model renders only the single stack entry with
+     * this `id` — the rest of the session stack is filtered out on
+     * `setAll` and `upsert` ignores every entry whose id ≠ this value.
+     * Enables single-item renderer mode, driven by the
+     * `bootstrap.stackItemId` field set on a per-item session
+     * resource.
+     *
+     * Absent → multi-item mode: the model renders the entire stack as
+     * the server delivers it.
+     *
+     * The filter is immutable for a model's lifetime (no setter).
+     * Consumers that need a different filter MUST construct a new
+     * model — matches the "model is the truth" doctrine below and
+     * makes filter-change intent explicit in code review.
+     */
+    readonly filterToItemId?: string;
+}
+/**
+ * In-memory model of the visible stack. Owned by the runtime; mutated
+ * via the methods (no setter — keeps the "model is the truth" doctrine
+ * obvious in code reviews).
+ */
+export declare class StackModel {
+    private items;
+    private readonly filterToItemId;
+    constructor(options?: StackModelOptions);
+    /**
+     * Replace the entire stack — used after the subscribe ack lands.
+     *
+     * Under `filterToItemId` (single-item mode), the incoming list is
+     * filtered to just the matching entry. If no entry matches, the
+     * model ends up empty — the server no longer includes the pinned
+     * item and the renderer's empty-state is the correct surface.
+     */
+    setAll(items: readonly SessionStackEntry[]): void;
+    /**
+     * Upsert a stack item. If an entry with the same id already exists
+     * its slot is replaced in place (preserves ordering); otherwise the
+     * item is appended at the tail. Mirrors `GguiSession.tsx`'s push
+     * reducer.
+     *
+     * Under `filterToItemId` (single-item mode): entries whose id does
+     * not match the filter are ignored. The renderer's live-channel
+     * subscription still delivers every push for the session (subscribe
+     * remains session-scoped); this filter is the client-side pin that
+     * keeps the per-card iframe bound to its one stack entry.
+     */
+    upsert(item: SessionStackEntry): void;
+    /** Read-only view — callers MUST NOT mutate. */
+    snapshot(): readonly SessionStackEntry[];
+    /** Item count — convenience for status-line rendering. */
+    size(): number;
+}
+/**
+ * Render the stack model into the target list element as structural
+ * `<li data-ggui-stack-item="<id>">` placeholders. Idempotent — every
+ * call replaces the element's children based on the current model.
+ *
+ * The DOM shape (data attributes + classnames) is intentionally
+ * stable: E2E tests and the React-mount path both need to address
+ * stack-item rows by `data-ggui-stack-item` selector.
+ */
+export declare function renderStackInto(target: HTMLElement, model: StackModel): void;