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

package/dist/canvas/display-mode-policy.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Display-mode escalation policy.
+ *
+ * Pure functions that decide which `ui/request-display-mode` value the
+ * canvas should request based on:
+ *   - the host's declared `availableDisplayModes` (from `McpUiHostContext`)
+ *   - the canvas's content state (empty vs. has-content)
+ *   - the host's current `displayMode`
+ *
+ * The rules implement this core matrix:
+ *
+ *   ┌─────────────────────────────┬──────────────────────────┐
+ *   │ canvas state                │ requested target         │
+ *   ├─────────────────────────────┼──────────────────────────┤
+ *   │ mounted, navStack empty     │ pip (fallback inline)    │
+ *   │ navStack has ≥1 item        │ fullscreen (then pip,    │
+ *   │                             │ then inline)             │
+ *   └─────────────────────────────┴──────────────────────────┘
+ *
+ *   - Never request `fullscreen` when the canvas is empty (taking over
+ *     the whole screen to show a single pill is hostile UX).
+ *   - For content state, prefer `fullscreen` > `pip` > `inline`.
+ *   - `inline` is the silent fallback when neither `pip` nor
+ *     `fullscreen` is available — the canvas renders inside whatever
+ *     box the host gives it, no escalation request fires.
+ *
+ * Boundary discipline:
+ *
+ *   - No DOM, no postMessage, no React. The reconciler returns a
+ *     decision ('request X' or 'do nothing'); the caller fires the
+ *     request via the iframe-runtime's existing
+ *     `requestDisplayModeInParent()` seam.
+ *   - No HTTP, no IO. Every input is a value; the function is
+ *     referentially transparent so tests don't need mocks.
+ *   - No subscriptions, no listeners. The reconciler is called by the
+ *     canvas shell at navStack transitions + on
+ *     `ui/notifications/host-context-changed` notifications.
+ *
+ * Why pure functions: the policy IS the contract between the host's
+ * capability surface and ggui's user-experience guarantees. Testing it
+ * exhaustively requires nothing but a value-in / value-out matrix.
+ */
+import type { McpUiDisplayMode } from '@ggui-ai/protocol';
+/**
+ * What the canvas should request when navStack is empty (just the
+ * animator pill visible). Never returns `'fullscreen'` — fullscreen
+ * with no content is hostile UX.
+ *
+ *   - `['pip']` or supersets containing pip → `'pip'`
+ *   - everything else → `'inline'`
+ *
+ * Treats absent / empty `available` as `['inline']`-only.
+ */
+export declare function pickEmptyStateMode(available: readonly McpUiDisplayMode[] | undefined): McpUiDisplayMode;
+/**
+ * What the canvas should request when navStack has ≥1 item (content
+ * is visible; pill compressed into navbar). Prefers `fullscreen` for
+ * the most prominent presentation; falls back to `pip` then `inline`.
+ *
+ *   - `'fullscreen'` if available
+ *   - else `'pip'` if available
+ *   - else `'inline'`
+ *
+ * Treats absent / empty `available` as `['inline']`-only.
+ */
+export declare function pickContentStateMode(available: readonly McpUiDisplayMode[] | undefined): McpUiDisplayMode;
+/**
+ * Decision for the reconciler. The canvas calls
+ * {@link reconcileDisplayMode} on every state change; the result tells
+ * it whether to fire a `ui/request-display-mode` postMessage.
+ *
+ *   - `{ kind: 'noop' }` — already at target; nothing to do. Skips
+ *     postMessage + audit envelope traffic.
+ *   - `{ kind: 'request', mode }` — fire the request.
+ */
+export type DisplayModeDecision = {
+    readonly kind: 'noop';
+} | {
+    readonly kind: 'request';
+    readonly mode: McpUiDisplayMode;
+};
+/**
+ * State the reconciler considers.
+ *
+ *   - `available` — host's declared `availableDisplayModes`.
+ *   - `current` — host's current `displayMode`.
+ *   - `contentState` — whether the canvas's navStack has content.
+ */
+export interface DisplayModePolicyInput {
+    readonly available: readonly McpUiDisplayMode[] | undefined;
+    readonly current: McpUiDisplayMode | undefined;
+    readonly contentState: 'empty' | 'has-content';
+}
+/**
+ * Compute whether a display-mode change should be requested. Returns
+ * `noop` when current already matches the policy target (saves
+ * postMessage round-trips + audit-envelope noise on no-ops).
+ *
+ * When `current` is undefined (host hasn't reported a mode yet), the
+ * reconciler treats it as `'inline'` and fires a request to the
+ * policy target — matches the worst-case assumption that the host
+ * started in inline.
+ */
+export declare function reconcileDisplayMode(input: DisplayModePolicyInput): DisplayModeDecision;

package/dist/canvas/display-mode-policy.js

@@ -0,0 +1,98 @@
+/**
+ * Display-mode escalation policy.
+ *
+ * Pure functions that decide which `ui/request-display-mode` value the
+ * canvas should request based on:
+ *   - the host's declared `availableDisplayModes` (from `McpUiHostContext`)
+ *   - the canvas's content state (empty vs. has-content)
+ *   - the host's current `displayMode`
+ *
+ * The rules implement this core matrix:
+ *
+ *   ┌─────────────────────────────┬──────────────────────────┐
+ *   │ canvas state                │ requested target         │
+ *   ├─────────────────────────────┼──────────────────────────┤
+ *   │ mounted, navStack empty     │ pip (fallback inline)    │
+ *   │ navStack has ≥1 item        │ fullscreen (then pip,    │
+ *   │                             │ then inline)             │
+ *   └─────────────────────────────┴──────────────────────────┘
+ *
+ *   - Never request `fullscreen` when the canvas is empty (taking over
+ *     the whole screen to show a single pill is hostile UX).
+ *   - For content state, prefer `fullscreen` > `pip` > `inline`.
+ *   - `inline` is the silent fallback when neither `pip` nor
+ *     `fullscreen` is available — the canvas renders inside whatever
+ *     box the host gives it, no escalation request fires.
+ *
+ * Boundary discipline:
+ *
+ *   - No DOM, no postMessage, no React. The reconciler returns a
+ *     decision ('request X' or 'do nothing'); the caller fires the
+ *     request via the iframe-runtime's existing
+ *     `requestDisplayModeInParent()` seam.
+ *   - No HTTP, no IO. Every input is a value; the function is
+ *     referentially transparent so tests don't need mocks.
+ *   - No subscriptions, no listeners. The reconciler is called by the
+ *     canvas shell at navStack transitions + on
+ *     `ui/notifications/host-context-changed` notifications.
+ *
+ * Why pure functions: the policy IS the contract between the host's
+ * capability surface and ggui's user-experience guarantees. Testing it
+ * exhaustively requires nothing but a value-in / value-out matrix.
+ */
+/**
+ * What the canvas should request when navStack is empty (just the
+ * animator pill visible). Never returns `'fullscreen'` — fullscreen
+ * with no content is hostile UX.
+ *
+ *   - `['pip']` or supersets containing pip → `'pip'`
+ *   - everything else → `'inline'`
+ *
+ * Treats absent / empty `available` as `['inline']`-only.
+ */
+export function pickEmptyStateMode(available) {
+    if (!available || available.length === 0)
+        return 'inline';
+    if (available.includes('pip'))
+        return 'pip';
+    return 'inline';
+}
+/**
+ * What the canvas should request when navStack has ≥1 item (content
+ * is visible; pill compressed into navbar). Prefers `fullscreen` for
+ * the most prominent presentation; falls back to `pip` then `inline`.
+ *
+ *   - `'fullscreen'` if available
+ *   - else `'pip'` if available
+ *   - else `'inline'`
+ *
+ * Treats absent / empty `available` as `['inline']`-only.
+ */
+export function pickContentStateMode(available) {
+    if (!available || available.length === 0)
+        return 'inline';
+    if (available.includes('fullscreen'))
+        return 'fullscreen';
+    if (available.includes('pip'))
+        return 'pip';
+    return 'inline';
+}
+/**
+ * Compute whether a display-mode change should be requested. Returns
+ * `noop` when current already matches the policy target (saves
+ * postMessage round-trips + audit-envelope noise on no-ops).
+ *
+ * When `current` is undefined (host hasn't reported a mode yet), the
+ * reconciler treats it as `'inline'` and fires a request to the
+ * policy target — matches the worst-case assumption that the host
+ * started in inline.
+ */
+export function reconcileDisplayMode(input) {
+    const target = input.contentState === 'empty'
+        ? pickEmptyStateMode(input.available)
+        : pickContentStateMode(input.available);
+    const current = input.current ?? 'inline';
+    if (current === target)
+        return { kind: 'noop' };
+    return { kind: 'request', mode: target };
+}

package/dist/canvas/mount.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Canvas mount — wires the React-tree CanvasShell into bootProduction.
+ *
+ * The canvas-mode iframe is session-scoped — a single React root lives
+ * for the lifetime of the session, with the active stack item rendered
+ * inside its content slot. This module bridges the React/DOM boundary
+ * for that mount:
+ *
+ *   - Renders `<CanvasShell>` into a host-supplied DOM element.
+ *   - Exposes a stable `contentEl` div via `renderActiveItem` that the
+ *     existing stack renderer can write into (one slot, swapped per
+ *     navStack-top transition).
+ *   - Returns a `NavStackModel` so the caller (bootSequence) can keep
+ *     it synced with the server's stack snapshots on every ack.
+ *   - Returns a dispose handle that unmounts the React tree on
+ *     teardown.
+ *
+ * Why this lives next to `canvas-shell.tsx` instead of `runtime.ts`:
+ * keeps the DOM/React seam co-located with the shell so anyone adding
+ * a new piece of canvas chrome sees the wiring point. `runtime.ts`
+ * already pulls React + design under a dynamic import — this file
+ * piggybacks on those modules being available at call time, taking
+ * them as constructor args rather than top-level imports.
+ */
+import type { CanvasLifecyclePayload, McpUiDisplayMode, SessionStackEntry } from '@ggui-ai/protocol';
+import type { AnimatorEventStream } from './animator/animator-host.js';
+import type { AnimatorEvent } from './animator/state-machine.js';
+import { NavStackModel } from './nav-stack.js';
+/**
+ * Multi-subscriber AnimatorEventStream backed by a Set of listeners.
+ * Boot publishes via `publish(event)`; the shell's AnimatorHost
+ * subscribes through the {@link AnimatorEventStream} interface.
+ *
+ * Kept small and inline because the only call site is `mountCanvas`
+ * — extracting it to its own file would be ceremony.
+ */
+export declare class AnimatorEventBus implements AnimatorEventStream {
+    private readonly listeners;
+    subscribe: (listener: (event: AnimatorEvent) => void) => (() => void);
+    publish(event: AnimatorEvent): void;
+    /**
+     * Translate a wire-shape {@link CanvasLifecyclePayload} from the
+     * `_ggui:lifecycle` channel into the matching {@link AnimatorEvent}
+     * variant and publish. The wire union is closed, so the switch is
+     * exhaustive.
+     */
+    publishLifecycle(payload: CanvasLifecyclePayload): void;
+}
+/**
+ * Minimal React/ReactDOM surface the mount needs. Constructor accepts
+ * pre-imported modules so it doesn't duplicate the dynamic-import
+ * graph runtime.ts already pays for. Type loose-typed because tests
+ * may pass stubs; production wires the real `react` + `react-dom/client`.
+ */
+export interface CanvasMountReactDeps {
+    readonly react: typeof import('react');
+    readonly reactDomClient: typeof import('react-dom/client');
+}
+/**
+ * Side-effecting callbacks the canvas shell threads up to the boot
+ * layer. The boot layer owns the live-channel transport so it knows how
+ * to emit envelopes; this module knows nothing about WS.
+ */
+export interface CanvasMountCallbacks {
+    /**
+     * Fire a `ui/request-display-mode` postMessage to the host. The
+     * shell calls this when the display-mode policy says to escalate
+     * (e.g. content state ⇒ fullscreen). Boot wires it to the existing
+     * `requestDisplayModeInParent` helper.
+     */
+    readonly onRequestDisplayMode?: (mode: McpUiDisplayMode) => void;
+    /**
+     * Fire when the user back-navigates. Boot wires this to the
+     * live-channel `canvas_navigated` envelope so the server can update
+     * its `activeStackItemId` + abort in-flight cold-gen for the popped
+     * item.
+     */
+    readonly onBackGesture?: (args: {
+        readonly previousActiveItemId: string;
+        readonly activeItemId: string | null;
+    }) => void;
+}
+export interface CanvasMountHandle {
+    /**
+     * The NavStackModel the shell renders from. Boot syncs this with
+     * the server's stack snapshot on every ack via `setStack()`.
+     */
+    readonly navStack: NavStackModel;
+    /**
+     * Bus for live-channel lifecycle envelopes. Boot calls
+     * `events.publish(event)` when an `_ggui:lifecycle` envelope arrives
+     * on the WS; AnimatorHost subscribes through the read-side
+     * {@link AnimatorEventStream} interface.
+     */
+    readonly events: AnimatorEventBus;
+    /**
+     * Stable DOM element the stack renderer writes into. Mirrors the
+     * shape of the legacy `refs.stack` element — bootSequence hands
+     * this to `triadWiring.setup({ renderInto })` instead of the raw
+     * `refs.stack`. The shell guarantees only the active stack item's
+     * subtree lives here at any moment.
+     */
+    readonly contentEl: HTMLElement;
+    /**
+     * Replace the entire nav stack. Used on the first ack (seed from
+     * snapshot) AND on every subsequent ack that delivers a fresh
+     * stack array.
+     */
+    setStack(stack: readonly SessionStackEntry[]): void;
+    /**
+     * Push a single item — used by the live-channel `push` envelope path
+     * where the server delivers one item at a time after the canvas is
+     * up. Idempotent in-place replace on duplicate id (matches server
+     * upsert semantics).
+     */
+    pushItem(item: SessionStackEntry): void;
+    /**
+     * Update the host's currently-reported display mode. Boot calls
+     * this when the host's `host-context-changed` notification arrives,
+     * so the policy reconciles against the latest mode.
+     */
+    setDisplayMode(mode: McpUiDisplayMode | undefined): void;
+    /**
+     * Update the host's declared `availableDisplayModes`. Same
+     * provenance as `setDisplayMode` — comes from
+     * `host-context-changed` payloads.
+     */
+    setAvailableDisplayModes(available: readonly McpUiDisplayMode[] | undefined): void;
+    /**
+     * Register a cleanup callback that fires when {@link dispose} runs.
+     * Used by boot to attach external teardown (e.g., the
+     * host-context-emitter local subscription's unsubscribe fn) to the
+     * canvas lifecycle so a re-mount doesn't leak the prior callback.
+     * Idempotent re-registration is fine; each fires exactly once on
+     * the first dispose.
+     */
+    registerCleanup(fn: () => void): void;
+    /**
+     * React unmount + cleanup. Called by `triadWiring.teardown` on
+     * boot-failure / explicit dispose paths. Also fires every
+     * registered cleanup callback in registration order.
+     */
+    dispose(): void;
+}
+/**
+ * Mount the canvas shell into `mountTarget`. The shell takes over
+ * `mountTarget`'s child layout — boot SHOULD pass an empty container
+ * (`refs.stack`), not the document root.
+ */
+export declare function mountCanvas(mountTarget: HTMLElement, deps: CanvasMountReactDeps, callbacks?: CanvasMountCallbacks): CanvasMountHandle;

package/dist/canvas/mount.js

@@ -0,0 +1,202 @@
+/**
+ * Canvas mount — wires the React-tree CanvasShell into bootProduction.
+ *
+ * The canvas-mode iframe is session-scoped — a single React root lives
+ * for the lifetime of the session, with the active stack item rendered
+ * inside its content slot. This module bridges the React/DOM boundary
+ * for that mount:
+ *
+ *   - Renders `<CanvasShell>` into a host-supplied DOM element.
+ *   - Exposes a stable `contentEl` div via `renderActiveItem` that the
+ *     existing stack renderer can write into (one slot, swapped per
+ *     navStack-top transition).
+ *   - Returns a `NavStackModel` so the caller (bootSequence) can keep
+ *     it synced with the server's stack snapshots on every ack.
+ *   - Returns a dispose handle that unmounts the React tree on
+ *     teardown.
+ *
+ * Why this lives next to `canvas-shell.tsx` instead of `runtime.ts`:
+ * keeps the DOM/React seam co-located with the shell so anyone adding
+ * a new piece of canvas chrome sees the wiring point. `runtime.ts`
+ * already pulls React + design under a dynamic import — this file
+ * piggybacks on those modules being available at call time, taking
+ * them as constructor args rather than top-level imports.
+ */
+import { CanvasShell } from './canvas-shell.js';
+import { NavStackModel } from './nav-stack.js';
+/**
+ * Multi-subscriber AnimatorEventStream backed by a Set of listeners.
+ * Boot publishes via `publish(event)`; the shell's AnimatorHost
+ * subscribes through the {@link AnimatorEventStream} interface.
+ *
+ * Kept small and inline because the only call site is `mountCanvas`
+ * — extracting it to its own file would be ceremony.
+ */
+export class AnimatorEventBus {
+    listeners = new Set();
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    publish(event) {
+        for (const fn of this.listeners)
+            fn(event);
+    }
+    /**
+     * Translate a wire-shape {@link CanvasLifecyclePayload} from the
+     * `_ggui:lifecycle` channel into the matching {@link AnimatorEvent}
+     * variant and publish. The wire union is closed, so the switch is
+     * exhaustive.
+     */
+    publishLifecycle(payload) {
+        switch (payload.kind) {
+            case 'handshake_started':
+                this.publish({ kind: 'handshake_started', payload });
+                return;
+            case 'handshake_completed':
+                this.publish({ kind: 'handshake_completed', payload });
+                return;
+            case 'push_started':
+                this.publish({ kind: 'push_started', payload });
+                return;
+            case 'consume_polling':
+                this.publish({ kind: 'consume_polling', payload });
+                return;
+        }
+    }
+}
+/**
+ * Mount the canvas shell into `mountTarget`. The shell takes over
+ * `mountTarget`'s child layout — boot SHOULD pass an empty container
+ * (`refs.stack`), not the document root.
+ */
+export function mountCanvas(mountTarget, deps, callbacks = {}) {
+    const navStack = new NavStackModel();
+    const events = new AnimatorEventBus();
+    const cleanups = [];
+    // The content element is stable across re-renders — we keep a
+    // single div and let the existing stack renderer mutate it. The
+    // shell receives `() => contentSlot` as `renderActiveItem`.
+    const contentEl = mountTarget.ownerDocument.createElement('div');
+    contentEl.setAttribute('data-ggui-canvas-content-slot', 'true');
+    contentEl.style.width = '100%';
+    contentEl.style.height = '100%';
+    // Mutable display-mode state lives in closure refs. The Wrapper
+    // captures a useState setter on first render; external setters
+    // route through it to push updates into React. Single consumer so
+    // a Set+broadcast pattern would be over-built — one nullable ref
+    // matches the architecture exactly.
+    let availableDisplayModes;
+    let currentDisplayMode;
+    let setWrapperState = null;
+    const bumpState = () => {
+        setWrapperState?.({
+            available: availableDisplayModes,
+            current: currentDisplayMode,
+        });
+    };
+    const { react, reactDomClient } = deps;
+    const root = reactDomClient.createRoot(mountTarget);
+    function Wrapper() {
+        const [state, setState] = react.useState({
+            available: availableDisplayModes,
+            current: currentDisplayMode,
+        });
+        react.useEffect(() => {
+            setWrapperState = setState;
+            return () => {
+                if (setWrapperState === setState)
+                    setWrapperState = null;
+            };
+        }, []);
+        const props = {
+            navStack,
+            events,
+            ...(state.available !== undefined
+                ? { availableDisplayModes: state.available }
+                : {}),
+            ...(state.current !== undefined
+                ? { currentDisplayMode: state.current }
+                : {}),
+            onRequestDisplayMode: (mode) => {
+                callbacks.onRequestDisplayMode?.(mode);
+            },
+            onBackGesture: (args) => {
+                callbacks.onBackGesture?.(args);
+            },
+            renderActiveItem: () => {
+                // Render the content slot DIV via a portal-ish ref pattern —
+                // we wrap it in a no-op React element that mounts the
+                // existing DOM node. Avoids React owning the slot's children
+                // (the stack renderer writes them imperatively).
+                return react.createElement(SlotMount, { node: contentEl });
+            },
+        };
+        return react.createElement(CanvasShell, props);
+    }
+    function SlotMount({ node }) {
+        const hostRef = react.useRef(null);
+        react.useEffect(() => {
+            const host = hostRef.current;
+            if (host === null)
+                return undefined;
+            host.appendChild(node);
+            return () => {
+                if (node.parentNode === host)
+                    host.removeChild(node);
+            };
+        }, [node]);
+        return react.createElement('div', {
+            ref: hostRef,
+            style: { width: '100%', height: '100%' },
+        });
+    }
+    // React 18+ createRoot.render. The `unstable_strictMode` etc. are
+    // host-supplied; we don't opt into them here.
+    root.render(react.createElement(Wrapper, null));
+    return {
+        navStack,
+        events,
+        contentEl,
+        setStack(stack) {
+            navStack.reset(stack);
+        },
+        pushItem(item) {
+            navStack.push(item);
+        },
+        setDisplayMode(mode) {
+            currentDisplayMode = mode;
+            bumpState();
+        },
+        setAvailableDisplayModes(available) {
+            availableDisplayModes = available;
+            bumpState();
+        },
+        registerCleanup(fn) {
+            cleanups.push(fn);
+        },
+        dispose() {
+            // Run external cleanups first so subscribers that touch the
+            // navStack / events bus get a chance to detach before React
+            // tears down its tree underneath them.
+            while (cleanups.length > 0) {
+                const fn = cleanups.shift();
+                try {
+                    fn?.();
+                }
+                catch {
+                    // Cleanup threw — keep going so one bad callback doesn't
+                    // strand the rest.
+                }
+            }
+            try {
+                root.unmount();
+            }
+            catch {
+                // React already unmounted (e.g. host removed the iframe).
+            }
+        },
+    };
+}

package/dist/canvas/nav-stack.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 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.
+ */
+import type { SessionStackEntry } from '@ggui-ai/protocol';
+/**
+ * Listener for nav-changing mutations (push of new id, pop, reset to
+ * a different top). The canvas shell threads this into the live-channel
+ * `canvas_navigated` envelope so the server can update
+ * `activeStackItemId` and abort in-flight cold-gen for items the user
+ * has navigated away from.
+ */
+export type NavStackChangeListener = (event: {
+    readonly direction: 'forward' | 'back';
+    readonly activeItemId: string | null;
+    readonly previousActiveItemId: string | null;
+}) => void;
+/**
+ * Listener for any state mutation. Distinct from
+ * {@link NavStackChangeListener} so React consumers can bridge to a
+ * version counter — in-place replaces (ggui_update) mutate state
+ * without changing the active item, and React still needs to re-render
+ * to pick up the new props.
+ */
+export type NavStackMutationListener = () => void;
+export declare class NavStackModel {
+    private items;
+    private mutationListener;
+    private navChangeListener;
+    private versionCounter;
+    /**
+     * Replace the entire nav stack. Used on subscribe ack to seed
+     * navStack from the server's `activeStackItemId` + the snapshot's
+     * stack array.
+     */
+    reset(items: readonly SessionStackEntry[]): void;
+    /**
+     * 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: SessionStackEntry): void;
+    /**
+     * Pop the top item. Returns the new active item (or null if the
+     * stack is now empty). No-op if already empty.
+     */
+    pop(): SessionStackEntry | null;
+    /** Top of the nav stack (the currently-mounted item), or null when empty. */
+    peek(): SessionStackEntry | null;
+    /** Read-only snapshot of the full nav stack in order (root → top). */
+    snapshot(): readonly SessionStackEntry[];
+    /** Item count. */
+    size(): number;
+    /**
+     * 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(): number;
+    /**
+     * 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: NavStackMutationListener): () => void;
+    /**
+     * 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: NavStackChangeListener): () => void;
+}