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

package/dist/canvas/nav-stack.js

@@ -0,0 +1,172 @@
+/**
+ * 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/channel-transport.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Per-channel transport router.
+ *
+ * Owns the runtime-side half of the dual-transport stream-channel
+ * negotiation. For each `streamSpec[channelName]` entry that
+ * declares a `source.tool`, the router picks ONE of two transports
+ * per channel:
+ *
+ *   - **WS subscribe** — when `source.tool` is in the bootstrap's
+ *     `streamWebSocketLocalTools` allowlist. The router sends a
+ *     `channel_subscribe` WS frame; the server polls the tool and
+ *     fans out `channel_payload` frames. Cheapest path: zero LLM
+ *     traffic, zero parent-iframe postMessage round-trips per
+ *     payload.
+ *
+ *   - **Iframe polling** — fallback for every other channel. The
+ *     router runs a setInterval that fires `tools/call` against
+ *     the parent MCP host (Pattern α — direct, no bridge). Works
+ *     for any tool the agent has access to, including third-party
+ *     MCP servers the local pod can't subscribe-for.
+ *
+ * The dispatch decision is per-channel + per-render (each new push
+ * brings a potentially-new contract; we re-run the routing). The
+ * StreamBus + `useStream(channel)` API stay unchanged — the router
+ * adapts payloads from both transports into the same envelope shape
+ * the bus already accepts.
+ *
+ * **Reconnect handling** — when the WS drops, every WS-bound channel:
+ *   1. Immediately falls back to iframe polling (no delay). The user
+ *      keeps seeing fresh data while the WS reconnect ladder runs.
+ *   2. On successful reconnect → re-send `channel_subscribe`. On the
+ *      first `channel_payload` from that channel, cancel the polling
+ *      fallback (don't double-deliver).
+ *
+ * The WS-level exponential backoff (1s → 2s → 4s → ... cap 60s) lives
+ * on the {@link RendererWebSocketManager}. The router only watches
+ * status transitions; it doesn't own the reconnect schedule.
+ *
+ * **Idempotence** — re-subscribing the same `(stackItemId, channelName)`
+ * pair is server-side idempotent (the server's `ChannelSubscriptionState`
+ * replaces in place). Clients can re-send on reconnect without bookkeeping
+ * a "did we already subscribe?" gate.
+ *
+ * **Boundary** — this module produces a `StreamEnvelope` for every payload
+ * (both transports) and emits on the supplied bus. It does NOT validate
+ * payloads against `streamSpec[ch].schema` — the existing
+ * `validateInboundStreamPayload` path in `runtime.ts` does that on the
+ * `data` frame side. For WS `channel_payload` frames we route directly
+ * to the bus because the SERVER has already validated server-side; for
+ * iframe-poll payloads we trust the tool's return value (matches today's
+ * un-routed channel posture pre-1c, where any payload that landed on the
+ * data frame was treated as authoritative).
+ */
+import type { JsonObject, JsonValue, StreamSpec } from '@ggui-ai/protocol';
+import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
+import type { StreamBus } from './wire-config.js';
+/**
+ * Default polling cadence for the iframe-polling transport (ms).
+ * Mirrors the server-side default on
+ * {@link DEFAULT_CHANNEL_POLL_DEFAULT_MS} in
+ * `packages/mcp-server/src/session-channel.ts`. Conservative: 10s
+ * matches a "data is fresh enough" bar without burning the parent
+ * host's `tools/call` quota.
+ */
+export declare const DEFAULT_IFRAME_POLL_INTERVAL_MS = 10000;
+/**
+ * Sender for outbound WS frames. The renderer's
+ * {@link RendererWebSocketManager.send} fits structurally — pass
+ * `manager.send.bind(manager)` or the buffered manager shim.
+ */
+export type WsSender = (msg: WebSocketMessage) => void;
+/**
+ * Iframe → parent `tools/call` invoker. Resolves with the tool's
+ * structured-content output (parsed `JsonValue`) or rejects on
+ * transport-level failure. The router will swallow the failure +
+ * keep the poll loop running (next tick may succeed).
+ */
+export type ToolsCallInvoker = (args: {
+    readonly toolName: string;
+    readonly args: JsonObject;
+}) => Promise<JsonValue>;
+/**
+ * Options for {@link createChannelTransportRouter}.
+ */
+export interface ChannelTransportRouterOptions {
+    /** Session id the router scopes channel_subscribe frames against. */
+    readonly sessionId: string;
+    /** App (tenant) id paired with sessionId on the subscribe frame. */
+    readonly appId: string;
+    /**
+     * Allowlist of `source.tool` names this server can subscribe-for
+     * over WS. From `bootstrap.streamWebSocketLocalTools`. Absent or
+     * empty ⇒ every channel routes through the iframe-poll fallback.
+     */
+    readonly streamWebSocketLocalTools?: readonly string[];
+    /** Outbound WS sender. */
+    readonly send: WsSender;
+    /** Iframe → parent `tools/call` proxy. */
+    readonly toolsCall: ToolsCallInvoker;
+    /** StreamBus the router emits envelopes onto. */
+    readonly streamBus: StreamBus;
+    /**
+     * Default poll cadence (ms) for the iframe-polling transport.
+     * Overridden per-channel via `streamSpec[name].source.pollIntervalMs`
+     * when authored. Falls back to {@link DEFAULT_IFRAME_POLL_INTERVAL_MS}
+     * when neither the spec nor the option supplies one.
+     */
+    readonly defaultPollIntervalMs?: number;
+    /**
+     * Observability sink — fires once per transport pick + once per
+     * disconnect/reconnect-fallback transition. Optional; absent ⇒
+     * silent.
+     */
+    readonly onObserve?: (event: ChannelTransportEvent) => void;
+}
+/**
+ * Observability events the router emits. Hosts that wire `onObserve`
+ * see these alongside the renderer's other observability events
+ * (`subscribe-failed`, `wired-tool-invoked`, …). The shape stays
+ * narrow + non-breaking so future events can extend the union.
+ */
+export type ChannelTransportEvent = {
+    readonly kind: 'channel-transport-picked';
+    readonly stackItemId: string;
+    readonly channelName: string;
+    readonly transport: 'ws' | 'poll';
+} | {
+    readonly kind: 'channel-transport-fallback';
+    readonly stackItemId: string;
+    readonly channelName: string;
+    readonly reason: 'ws-disconnect' | 'channel-not-local';
+} | {
+    readonly kind: 'channel-transport-resubscribed';
+    readonly stackItemId: string;
+    readonly channelName: string;
+};
+/**
+ * Router handle returned by {@link createChannelTransportRouter}.
+ */
+export interface ChannelTransportRouter {
+    /**
+     * Apply a new stack item's `streamSpec`. Idempotent against
+     * re-applying the same shape (no churn). Channels added/removed
+     * across renders fire transport pick / teardown accordingly.
+     *
+     * The legacy `data` frame path on `streamSpec[ch]` entries
+     * WITHOUT `source.tool` is unaffected — the router only manages
+     * the source-fed subset.
+     */
+    readonly applyStackItem: (item: {
+        readonly stackItemId: string;
+        readonly streamSpec?: StreamSpec;
+    }) => void;
+    /**
+     * Forward a single inbound WS frame. The router consumes
+     * `channel_payload` + `channel_error` types and ignores everything
+     * else. Returns `true` iff the frame was consumed (so the caller
+     * can short-circuit), `false` otherwise.
+     */
+    readonly handleWsFrame: (msg: WebSocketMessage) => boolean;
+    /**
+     * Notify the router of a WS connection status transition. Used to:
+     *   - On `'disconnected'` / `'reconnecting'`: start polling fallback
+     *     for every WS-bound channel (no delay).
+     *   - On `'connected'` AFTER a prior disconnect: re-send
+     *     `channel_subscribe` for every WS-bound channel.
+     */
+    readonly onWsStatusChange: (status: 'connecting' | 'connected' | 'disconnected' | 'reconnecting') => void;
+    /**
+     * Tear down every active subscription + timer. Called on
+     * `triadWiring.teardown`.
+     */
+    readonly dispose: () => void;
+}
+/**
+ * Factory.
+ *
+ * Per-channel transport routing — owns the `(stackItemId, channelName)`
+ * registry, the WS-vs-poll decision per channel, and the cross-state
+ * transitions (disconnect → poll fallback, reconnect → re-subscribe).
+ */
+export declare function createChannelTransportRouter(opts: ChannelTransportRouterOptions): ChannelTransportRouter;