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

package/dist/canvas/nav-stack.js

@@ -1,172 +0,0 @@
-/**
- * NavStackModel.
- *
- * Canvas-local navigation stack. **Distinct from the server's
- * `StackModel`**:
- *
- *   - Server's `StackModel` (`@ggui-ai/iframe-runtime/stack.ts`)
- *     tracks every stack item the agent has pushed in this session.
- *     The durable shape; mutated only by server-side push/pop/replace
- *     deliveries.
- *   - NavStackModel tracks the USER'S NAVIGATION HISTORY through
- *     those items. When the user back-navigates, the popped item
- *     leaves navStack but stays in server's StackModel.
- *
- * These can diverge:
- *
- *   ```
- *   server StackModel:  [a, b, c]   ← all items the agent has pushed
- *   navStack:           [a, b]      ← user has back-navigated away from c
- *   activeItem:         b           ← top of navStack; the mounted screen
- *   ```
- *
- * The server-side `activeStackItemId` field (on AckPayload +
- * SessionRecord) follows navStack-top via `canvas_navigated` outbound
- * envelopes, so `ggui_consume` returns actions for the active item
- * regardless of what the agent has pushed since.
- *
- * Pure model — no DOM, no React. Methods return the new state (or
- * mutate in-place; v1 mutates for simplicity since the canvas shell
- * holds the only reference). The renderer consumes the model via a
- * version counter (bumped on every mutation) so React picks up
- * changes without deep equality.
- *
- * Two listener seams (distinct semantics):
- *
- *   - `onMutation` fires on EVERY state mutation including in-place
- *     replace (ggui_update patch). The canvas shell uses this to
- *     re-read the version counter and re-render — without it, a
- *     props-only update on the active item bumps the version but
- *     React never schedules a render and the screen shows stale props.
- *   - `onNavChange` fires only when the active item actually changes
- *     (new push, pop, reset that lands on a different top). The
- *     live-channel `canvas_navigated` envelope is emitted from here, so
- *     an in-place replace doesn't spuriously tell the server the
- *     user back-navigated.
- */
-export class NavStackModel {
-    items = [];
-    mutationListener = null;
-    navChangeListener = null;
-    versionCounter = 0;
-    /**
-     * Replace the entire nav stack. Used on subscribe ack to seed
-     * navStack from the server's `activeStackItemId` + the snapshot's
-     * stack array.
-     */
-    reset(items) {
-        const previous = this.peek();
-        this.items = [...items];
-        this.versionCounter += 1;
-        this.mutationListener?.();
-        this.navChangeListener?.({
-            direction: 'forward',
-            activeItemId: this.peek()?.id ?? null,
-            previousActiveItemId: previous?.id ?? null,
-        });
-    }
-    /**
-     * Append an item to the top. Called when a `stack_item_appended`
-     * envelope arrives (server pushed a new item).
-     *
-     * If an item with the same id already exists, the existing entry is
-     * REPLACED IN PLACE (preserves nav position) — matches the server-
-     * side StackModel's upsert semantics so `ggui_update` patches don't
-     * shift the user's nav state. The mutation listener still fires (so
-     * React re-renders with the new props) but the nav-change listener
-     * is suppressed (active item hasn't changed).
-     */
-    push(item) {
-        const existingIdx = this.items.findIndex((i) => i.id === item.id);
-        if (existingIdx >= 0) {
-            this.items[existingIdx] = item;
-            this.versionCounter += 1;
-            this.mutationListener?.();
-            return;
-        }
-        const previous = this.peek();
-        this.items.push(item);
-        this.versionCounter += 1;
-        this.mutationListener?.();
-        this.navChangeListener?.({
-            direction: 'forward',
-            activeItemId: item.id,
-            previousActiveItemId: previous?.id ?? null,
-        });
-    }
-    /**
-     * Pop the top item. Returns the new active item (or null if the
-     * stack is now empty). No-op if already empty.
-     */
-    pop() {
-        if (this.items.length === 0)
-            return null;
-        const popped = this.items.pop() ?? null;
-        this.versionCounter += 1;
-        const active = this.peek();
-        this.mutationListener?.();
-        this.navChangeListener?.({
-            direction: 'back',
-            activeItemId: active?.id ?? null,
-            previousActiveItemId: popped?.id ?? null,
-        });
-        return active;
-    }
-    /** Top of the nav stack (the currently-mounted item), or null when empty. */
-    peek() {
-        return this.items[this.items.length - 1] ?? null;
-    }
-    /** Read-only snapshot of the full nav stack in order (root → top). */
-    snapshot() {
-        return this.items;
-    }
-    /** Item count. */
-    size() {
-        return this.items.length;
-    }
-    /**
-     * Monotonic mutation counter — bumped on every push/pop/reset.
-     * React consumers can use this as the `useSyncExternalStore`
-     * snapshot value: comparing version numbers is O(1).
-     */
-    version() {
-        return this.versionCounter;
-    }
-    /**
-     * Install a listener that fires on every state mutation (push, pop,
-     * reset, in-place replace). React consumers bridge this to a
-     * version-counter `useState` so the component re-renders for every
-     * change — including in-place replaces from `ggui_update` patches
-     * where the active item is unchanged but its props have moved.
-     *
-     * Single-subscriber model — the canvas shell is the only caller.
-     * Returns an unsubscribe function.
-     */
-    onMutation(listener) {
-        this.mutationListener = listener;
-        return () => {
-            if (this.mutationListener === listener)
-                this.mutationListener = null;
-        };
-    }
-    /**
-     * Install a listener that fires only on nav-changing mutations
-     * (push of new id, pop, reset). Used by the canvas shell to emit
-     * the live-channel `canvas_navigated` envelope so the server can
-     * update `activeStackItemId` and abort in-flight cold-gen for the
-     * previous active item.
-     *
-     * In-place replaces from `ggui_update` patches do NOT fire this
-     * listener — the active item hasn't moved. Use {@link onMutation}
-     * for React re-render signaling.
-     *
-     * Single-subscriber model. Returns an unsubscribe function.
-     */
-    onNavChange(listener) {
-        this.navChangeListener = listener;
-        return () => {
-            if (this.navChangeListener === listener)
-                this.navChangeListener = null;
-        };
-    }
-}

package/dist/channels/push.d.ts

@@ -1,47 +0,0 @@
-/**
- * `push` channel handler — folds an inbound `push` frame into the
- * stack model, re-renders the placeholder DOM, refreshes the status
- * line, then (when triad wiring is present) applies the new stack
- * through the React renderer + activates the channel-transport router
- * against the new top of stack.
- *
- * The placeholder side-effects (stack model upsert + DOM render +
- * status update) are unconditional — they're load-bearing for the
- * C7a-era specs that boot WITHOUT triad wiring (boot.test.ts in
- * particular). Triad-only consumers (production runtime) pass the
- * `getStackRenderer` + `getChannelTransport` thunks; tests that
- * exercise the placeholder path only leave them off.
- *
- * Pre-B3b: the placeholder fold lived in a separate
- * `handleServerMessage` call in `runtime.ts`, fired before triad
- * dispatch. B3b absorbed both into this single handler so the
- * registry-owned WS transport is the sole dispatch site.
- */
-import type { ChannelHandler } from '@ggui-ai/channel-client';
-import type { PushPayload } from '@ggui-ai/protocol';
-import type { ChannelTransportRouter } from '../channel-transport.js';
-import type { StackRenderer } from '../stack-item-renderer.js';
-import type { StackModel } from '../stack.js';
-import { type StatusRefs } from '../status-dom.js';
-export interface PushHandlerDeps {
-    readonly stackModel: StackModel;
-    /**
-     * Status DOM refs the placeholder fold updates. Required — even
-     * triad-mode consumers want the status text to reflect the live
-     * count for operator-visible boot debugging.
-     */
-    readonly statusRefs: StatusRefs;
-    /**
-     * Triad-mode hook — returns the React stack renderer. Absent in
-     * placeholder-only mode (tests, and callers that don't mount the
-     * React stack).
-     */
-    readonly getStackRenderer?: () => StackRenderer;
-    /**
-     * Triad-mode hook — returns the per-channel transport router so the
-     * push handler can activate / tear down `source.tool` channels on
-     * the new top of stack. Absent in placeholder-only mode.
-     */
-    readonly getChannelTransport?: () => ChannelTransportRouter;
-}
-export declare function createPushHandler(deps: PushHandlerDeps): ChannelHandler<PushPayload>;

package/dist/channels/push.js

@@ -1,54 +0,0 @@
-/**
- * `push` channel handler — folds an inbound `push` frame into the
- * stack model, re-renders the placeholder DOM, refreshes the status
- * line, then (when triad wiring is present) applies the new stack
- * through the React renderer + activates the channel-transport router
- * against the new top of stack.
- *
- * The placeholder side-effects (stack model upsert + DOM render +
- * status update) are unconditional — they're load-bearing for the
- * C7a-era specs that boot WITHOUT triad wiring (boot.test.ts in
- * particular). Triad-only consumers (production runtime) pass the
- * `getStackRenderer` + `getChannelTransport` thunks; tests that
- * exercise the placeholder path only leave them off.
- *
- * Pre-B3b: the placeholder fold lived in a separate
- * `handleServerMessage` call in `runtime.ts`, fired before triad
- * dispatch. B3b absorbed both into this single handler so the
- * registry-owned WS transport is the sole dispatch site.
- */
-import { refreshStackDom, setConnectedStatus, } from '../status-dom.js';
-export function createPushHandler(deps) {
-    return {
-        type: 'push',
-        onMessage: async (payload) => {
-            // 1. Placeholder fold — unconditional. Mirrors the pre-B3b
-            //    handleServerMessage path so non-triad consumers see the
-            //    correct stack count + placeholder DOM.
-            deps.stackModel.upsert(payload.stackItem);
-            refreshStackDom(deps.statusRefs, deps.stackModel);
-            setConnectedStatus(deps.statusRefs, deps.stackModel);
-            // 2. Triad-mode work — only fires when the production runtime
-            //    supplied the renderer + transport thunks.
-            const stackRenderer = deps.getStackRenderer?.();
-            const channelTransport = deps.getChannelTransport?.();
-            if (stackRenderer === undefined)
-                return;
-            const snapshot = deps.stackModel.snapshot();
-            await stackRenderer.applyStack(snapshot);
-            if (channelTransport === undefined)
-                return;
-            const top = snapshot[snapshot.length - 1];
-            if (top !== undefined &&
-                top.type !== 'mcpApps' &&
-                top.type !== 'system') {
-                channelTransport.applyStackItem({
-                    stackItemId: top.id,
-                    ...(top.streamSpec !== undefined
-                        ? { streamSpec: top.streamSpec }
-                        : {}),
-                });
-            }
-        },
-    };
-}

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

@@ -1,103 +0,0 @@
-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.d.ts

@@ -1,90 +0,0 @@
-/**
- * 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;

package/dist/stack.js

@@ -1,118 +0,0 @@
-/**
- * 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 class StackModel {
-    items = [];
-    filterToItemId;
-    constructor(options = {}) {
-        this.filterToItemId = options.filterToItemId;
-    }
-    /**
-     * 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) {
-        if (this.filterToItemId !== undefined) {
-            const target = this.filterToItemId;
-            this.items = items.filter((item) => item.id === target);
-            return;
-        }
-        this.items = [...items];
-    }
-    /**
-     * 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) {
-        if (this.filterToItemId !== undefined && item.id !== this.filterToItemId) {
-            return;
-        }
-        const idx = this.items.findIndex((existing) => existing.id === item.id);
-        if (idx >= 0) {
-            const next = [...this.items];
-            next[idx] = item;
-            this.items = next;
-            return;
-        }
-        this.items = [...this.items, item];
-    }
-    /** Read-only view — callers MUST NOT mutate. */
-    snapshot() {
-        return this.items;
-    }
-    /** Item count — convenience for status-line rendering. */
-    size() {
-        return this.items.length;
-    }
-}
-/**
- * Best-effort textual label for a stack item — title-ish for the
- * placeholder UI. Tries `description` → `prompt` → a generic fallback.
- *
- * The wire shape keeps these fields optional on every entry kind
- * (generated, McpApps), so the absence-handling has to be honest.
- */
-function labelFor(item) {
-    if (typeof item.description === 'string' && item.description.length > 0) {
-        return item.description;
-    }
-    // Only generated component items carry `prompt`. McpApps + system
-    // variants surface their own description (or a generic fallback).
-    if (item.type !== 'mcpApps' && item.type !== 'system') {
-        if (typeof item.prompt === 'string' && item.prompt.length > 0) {
-            return item.prompt;
-        }
-    }
-    return '(untitled stack item)';
-}
-/**
- * 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 function renderStackInto(target, model) {
-    // Replace children rather than mutate-in-place — the placeholder
-    // doesn't need diffing, and the wire-frame burst rate is low enough
-    // (push events arrive roughly per agent turn) that full-replace is
-    // cheap.
-    target.replaceChildren();
-    const items = model.snapshot();
-    if (items.length === 0) {
-        const empty = target.ownerDocument.createElement('li');
-        empty.textContent = '(no stack items yet)';
-        empty.setAttribute('data-ggui-empty', 'true');
-        target.appendChild(empty);
-        return;
-    }
-    for (const item of items) {
-        const li = target.ownerDocument.createElement('li');
-        li.setAttribute('data-ggui-stack-item', item.id);
-        const idEl = target.ownerDocument.createElement('span');
-        idEl.className = 'id';
-        idEl.textContent = item.id;
-        li.appendChild(idEl);
-        const labelEl = target.ownerDocument.createElement('span');
-        labelEl.className = 'label';
-        labelEl.textContent = labelFor(item);
-        li.appendChild(labelEl);
-        target.appendChild(li);
-    }
-}