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

package/dist/channels/props-update.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `props_update` channel handler — factored out of `runtime.ts` into
+ * the `@ggui-ai/channel-client` layer.
+ *
+ * Receives a `{stackItemId, props}` payload from the live channel, validates
+ * the new props against the stack item's cached `propsSpec`, patches
+ * the in-model entry, and re-applies the renderer so React picks up
+ * the change.
+ *
+ * Skips when:
+ *   - `stackItemId` is empty or not a string.
+ *   - `props` is null / not an object (defensive — server can't emit
+ *     this shape, but the dispatcher routes the frame on type alone).
+ *   - No matching stack item exists (server raced ahead of our pop).
+ *   - The matched item is `mcpApps` / `system` (no `propsSpec`; server
+ *     should never emit `props_update` for these).
+ *   - The new props fail validation against the cached spec.
+ *
+ * An OPTIONAL polling descriptor provides a fallback transport —
+ * when `polling` is supplied at factory time, `PollingTransport`
+ * polls `/api/bootstrap/<shortCode>` and synthesizes a frame
+ * whenever `propsJson` diffs from the last seen hash. WS hosts are
+ * unaffected (the `polling` descriptor is inert under `WSTransport`).
+ */
+import type { ChannelHandler } from '@ggui-ai/channel-client';
+import type { PropsUpdatePayload } from '@ggui-ai/protocol';
+import type { StackRenderer } from '../stack-item-renderer.js';
+import type { StackModel } from '../stack.js';
+export interface PropsUpdateHandlerDeps {
+    readonly stackModel: StackModel;
+    readonly getStackRenderer: () => StackRenderer;
+    /**
+     * Optional polling fallback URL. When the registry's chosen transport
+     * is `PollingTransport` (e.g. bootstrap missing wsUrl, or
+     * `FailoverHandle` swapped WS → polling after a hard failure), this
+     * URL is fetched on each tick. The response body is expected to carry
+     * `propsJson` + `stackItemId` (the same shape `/api/bootstrap/<code>`
+     * returns); the handler diffs `propsJson` between ticks and synthesizes
+     * a `props_update` frame whenever it changes. WS hosts ignore this
+     * descriptor (polling is inert under `WSTransport`).
+     *
+     * Producer: server stamps `bootstrap.pollingUrl` on the bootstrap
+     * envelope. Consumer: iframe-runtime threads it here at handler
+     * registration time. Absent → no polling fallback (WS-only mode).
+     */
+    readonly pollingUrl?: string;
+    /**
+     * Polling cadence in milliseconds. Defaults to 2000ms per the B5
+     * plan (well inside the 10s drain-claim budget; 5 ticks of safety).
+     */
+    readonly pollingIntervalMs?: number;
+}
+export declare function createPropsUpdateHandler(deps: PropsUpdateHandlerDeps): ChannelHandler<PropsUpdatePayload>;

package/dist/channels/props-update.js

@@ -0,0 +1,130 @@
+/**
+ * `props_update` channel handler — factored out of `runtime.ts` into
+ * the `@ggui-ai/channel-client` layer.
+ *
+ * Receives a `{stackItemId, props}` payload from the live channel, validates
+ * the new props against the stack item's cached `propsSpec`, patches
+ * the in-model entry, and re-applies the renderer so React picks up
+ * the change.
+ *
+ * Skips when:
+ *   - `stackItemId` is empty or not a string.
+ *   - `props` is null / not an object (defensive — server can't emit
+ *     this shape, but the dispatcher routes the frame on type alone).
+ *   - No matching stack item exists (server raced ahead of our pop).
+ *   - The matched item is `mcpApps` / `system` (no `propsSpec`; server
+ *     should never emit `props_update` for these).
+ *   - The new props fail validation against the cached spec.
+ *
+ * An OPTIONAL polling descriptor provides a fallback transport —
+ * when `polling` is supplied at factory time, `PollingTransport`
+ * polls `/api/bootstrap/<shortCode>` and synthesizes a frame
+ * whenever `propsJson` diffs from the last seen hash. WS hosts are
+ * unaffected (the `polling` descriptor is inert under `WSTransport`).
+ */
+import { validateInboundPropsPayload } from '../validation.js';
+const DEFAULT_POLLING_INTERVAL_MS = 2000;
+/**
+ * Tiny FNV-1a 32-bit hash — stable, no protocol dep, ~5 LOC. We only
+ * need diff detection (not collision resistance), so the trade-off is
+ * fine. Returns a hex string for human-readable logs.
+ */
+function fnv1a(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        // 32-bit FNV prime multiplication via additive bit-shifts.
+        hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0;
+    }
+    return hash.toString(16);
+}
+export function createPropsUpdateHandler(deps) {
+    const polling = buildPollingDescriptor(deps);
+    return {
+        type: 'props_update',
+        onMessage: async (payload) => {
+            const { stackItemId, props } = payload;
+            if (typeof stackItemId !== 'string' || stackItemId.length === 0)
+                return;
+            if (props === null || typeof props !== 'object')
+                return;
+            const target = deps.stackModel
+                .snapshot()
+                .find((item) => item.id === stackItemId);
+            if (target === undefined)
+                return;
+            if (target.type === 'mcpApps' || target.type === 'system')
+                return;
+            const result = validateInboundPropsPayload(target.propsSpec, props);
+            if (!result.valid)
+                return;
+            const nextSnapshot = deps.stackModel
+                .snapshot()
+                .map((item) => {
+                if (item.id !== stackItemId)
+                    return item;
+                if (item.type === 'mcpApps' || item.type === 'system')
+                    return item;
+                return { ...item, props };
+            });
+            deps.stackModel.setAll(nextSnapshot);
+            await deps.getStackRenderer().applyStack(deps.stackModel.snapshot());
+        },
+        ...(polling !== undefined ? { polling } : {}),
+    };
+}
+function buildPollingDescriptor(deps) {
+    const { pollingUrl } = deps;
+    if (typeof pollingUrl !== 'string' || pollingUrl.length === 0) {
+        return undefined;
+    }
+    const url = pollingUrl;
+    // Closure state — last-seen propsJson hash + last-seen stackItemId.
+    // Diff detection: emit only on change. First-poll fires (lastSeenHash
+    // is null initially) so the iframe gets the current props as its
+    // starting state when WS is absent.
+    let lastSeenHash = null;
+    let lastSeenStackItemId = null;
+    return {
+        url,
+        intervalMs: deps.pollingIntervalMs ?? DEFAULT_POLLING_INTERVAL_MS,
+        parse: (body) => {
+            if (body === null || typeof body !== 'object')
+                return null;
+            const propsJson = body.propsJson;
+            const bootstrapStackItemId = body
+                .stackItemId;
+            if (typeof propsJson !== 'string' ||
+                typeof bootstrapStackItemId !== 'string' ||
+                bootstrapStackItemId.length === 0) {
+                return null;
+            }
+            const hash = fnv1a(propsJson);
+            if (hash === lastSeenHash &&
+                bootstrapStackItemId === lastSeenStackItemId) {
+                return null; // Unchanged — skip dispatch.
+            }
+            lastSeenHash = hash;
+            lastSeenStackItemId = bootstrapStackItemId;
+            let parsedProps;
+            try {
+                parsedProps = JSON.parse(propsJson);
+            }
+            catch {
+                return null;
+            }
+            if (parsedProps === null ||
+                typeof parsedProps !== 'object' ||
+                Array.isArray(parsedProps)) {
+                return null;
+            }
+            // JSON.parse of an object literal yields a JsonObject by
+            // construction — JSON only carries JsonValue-compatible
+            // structure. Narrow to the protocol's typed shape.
+            return {
+                stackItemId: bootstrapStackItemId,
+                props: parsedProps,
+            };
+        },
+    };
+}

package/dist/channels/push.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `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

@@ -0,0 +1,54 @@
+/**
+ * `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/channels/system.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `system` channel handler — emits the `auth-required` observability
+ * event when the server signals an OAuth consent flow.
+ *
+ * Absorbed from `handleObservableMessage` in `runtime.ts`. The
+ * handler is now the sole dispatch surface for `system` frames in
+ * the iframe runtime; other system actions (e.g.
+ * `credential_ready`) have downstream listeners elsewhere and are
+ * intentionally skipped at this layer.
+ *
+ * Skip conditions (all silent — host gets no row, which is the
+ * correct behaviour: a system frame the host can't act on shouldn't
+ * surface as a spurious consent overlay trigger):
+ *   - `action !== 'auth_required'` — e.g. `'credential_ready'` is a
+ *     different downstream signal.
+ *   - `consentUrl` absent — the host cannot redirect the user without
+ *     it, so there's nothing actionable to surface.
+ *   - `onObserve` absent — the observation has nowhere to go.
+ */
+import type { ChannelHandler } from '@ggui-ai/channel-client';
+import type { SystemPayload } from '@ggui-ai/protocol';
+import type { ObservabilityEmitter } from '../observability.js';
+export interface SystemHandlerDeps {
+    readonly onObserve?: ObservabilityEmitter;
+}
+export declare function createSystemHandler(deps: SystemHandlerDeps): ChannelHandler<SystemPayload>;

package/dist/channels/system.js

@@ -0,0 +1,44 @@
+/**
+ * `system` channel handler — emits the `auth-required` observability
+ * event when the server signals an OAuth consent flow.
+ *
+ * Absorbed from `handleObservableMessage` in `runtime.ts`. The
+ * handler is now the sole dispatch surface for `system` frames in
+ * the iframe runtime; other system actions (e.g.
+ * `credential_ready`) have downstream listeners elsewhere and are
+ * intentionally skipped at this layer.
+ *
+ * Skip conditions (all silent — host gets no row, which is the
+ * correct behaviour: a system frame the host can't act on shouldn't
+ * surface as a spurious consent overlay trigger):
+ *   - `action !== 'auth_required'` — e.g. `'credential_ready'` is a
+ *     different downstream signal.
+ *   - `consentUrl` absent — the host cannot redirect the user without
+ *     it, so there's nothing actionable to surface.
+ *   - `onObserve` absent — the observation has nowhere to go.
+ */
+export function createSystemHandler(deps) {
+    return {
+        type: 'system',
+        onMessage: (payload) => {
+            if (deps.onObserve === undefined)
+                return;
+            emitAuthRequiredFromSystemFrame(payload, deps.onObserve);
+        },
+    };
+}
+function emitAuthRequiredFromSystemFrame(payload, emit) {
+    if (payload.action !== 'auth_required')
+        return;
+    if (typeof payload.consentUrl !== 'string' || payload.consentUrl.length === 0)
+        return;
+    const event = {
+        kind: 'auth-required',
+        provider: payload.serviceId,
+        authUrl: payload.consentUrl,
+        ...(payload.displayName !== undefined ? { displayName: payload.displayName } : {}),
+        ...(payload.scopes !== undefined ? { scopes: payload.scopes } : {}),
+        ...(payload.message !== undefined ? { message: payload.message } : {}),
+    };
+    emit(event);
+}

package/dist/compiled-validators.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Loader for precompiled, eval-free contract validators.
+ *
+ * The renderer iframe runs under a strict CSP with no `'unsafe-eval'`,
+ * so it cannot call `ajv.compile()` (which builds validators via
+ * `new Function`). The server precompiles each contract sub-schema into
+ * a standalone, self-contained ESM validator-module source string and
+ * ships them on the bootstrap as `compiledValidators`. This module
+ * loads each source via a `blob:` dynamic import — governed by
+ * `script-src` (which permits `blob:`), not by `unsafe-eval` — and
+ * exposes the resulting `ValidateFunction`s as a
+ * {@link CompiledValidatorSet}.
+ */
+import type { CompiledContractValidators } from '@ggui-ai/protocol/integrations/mcp-apps';
+import type { ValidateFunction } from '@ggui-ai/protocol';
+/**
+ * Precompiled validators for the active stack item's contract, keyed to
+ * match the four runtime-validated surfaces. `props` is a single
+ * validator (the synthesized props wrapper); the other three are keyed
+ * by action name / channel name / slot name.
+ */
+export interface CompiledValidatorSet {
+    readonly props?: ValidateFunction;
+    readonly actions: ReadonlyMap<string, ValidateFunction>;
+    readonly streams: ReadonlyMap<string, ValidateFunction>;
+    readonly context: ReadonlyMap<string, ValidateFunction>;
+}
+/**
+ * An empty set — no precompiled validators. Callers fall back to
+ * in-iframe `ajv.compile()`, which the CSP may then block; the empty
+ * set is the honest "nothing precompiled" state, not a fix on its own.
+ */
+export declare const EMPTY_COMPILED_VALIDATOR_SET: CompiledValidatorSet;
+/**
+ * Load every precompiled validator on the bootstrap into a
+ * {@link CompiledValidatorSet}. Each module loads independently; one
+ * failure never blocks the others. Returns the empty set when the
+ * bootstrap carries no `compiledValidators`.
+ */
+export declare function loadCompiledValidators(meta: CompiledContractValidators | undefined, warn?: (message: string, detail: unknown) => void): Promise<CompiledValidatorSet>;

package/dist/compiled-validators.js

@@ -0,0 +1,74 @@
+import { loadModule } from '@ggui-ai/design/module-loader';
+/**
+ * An empty set — no precompiled validators. Callers fall back to
+ * in-iframe `ajv.compile()`, which the CSP may then block; the empty
+ * set is the honest "nothing precompiled" state, not a fix on its own.
+ */
+export const EMPTY_COMPILED_VALIDATOR_SET = {
+    actions: new Map(),
+    streams: new Map(),
+    context: new Map(),
+};
+/** A precompiled validator module's `default` export is an Ajv
+ * standalone validate function. The runtime check is a `typeof`
+ * function test; the assertion that it is specifically a
+ * `ValidateFunction` is sound because the server emitted it as one. */
+function isValidateFunction(value) {
+    return typeof value === 'function';
+}
+/**
+ * Load one ESM validator-module source into a `ValidateFunction` via a
+ * `blob:` dynamic import. Returns `undefined` on any failure — a
+ * missing validator degrades to the in-iframe fallback rather than
+ * crashing the boot.
+ */
+async function loadOne(source, label, warn) {
+    try {
+        const mod = await loadModule(source);
+        const fn = mod['default'];
+        if (!isValidateFunction(fn)) {
+            warn?.(`[ggui:validators] ${label}: module has no default-export function`, mod);
+            return undefined;
+        }
+        return fn;
+    }
+    catch (err) {
+        warn?.(`[ggui:validators] ${label}: failed to load precompiled validator`, err);
+        return undefined;
+    }
+}
+/**
+ * Load every precompiled validator on the bootstrap into a
+ * {@link CompiledValidatorSet}. Each module loads independently; one
+ * failure never blocks the others. Returns the empty set when the
+ * bootstrap carries no `compiledValidators`.
+ */
+export async function loadCompiledValidators(meta, warn) {
+    if (meta === undefined)
+        return EMPTY_COMPILED_VALIDATOR_SET;
+    const loadGroup = async (group, kind) => {
+        const map = new Map();
+        if (group === undefined)
+            return map;
+        await Promise.all(Object.entries(group).map(async ([name, source]) => {
+            const fn = await loadOne(source, `${kind}.${name}`, warn);
+            if (fn !== undefined)
+                map.set(name, fn);
+        }));
+        return map;
+    };
+    const [props, actions, streams, context] = await Promise.all([
+        meta.props !== undefined
+            ? loadOne(meta.props, 'props', warn)
+            : Promise.resolve(undefined),
+        loadGroup(meta.actions, 'action'),
+        loadGroup(meta.streams, 'stream'),
+        loadGroup(meta.context, 'context'),
+    ]);
+    return {
+        ...(props !== undefined ? { props } : {}),
+        actions,
+        streams,
+        context,
+    };
+}

package/dist/context-observer.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Runtime owns Provider tree + useState per slot.
+ *
+ * **Architecture:**
+ *
+ * 1. At iframe boot, for each slot declared in the bootstrap's
+ *    `contextSlots`, the runtime synthesizes one
+ *    `React.createContext([default, () => {}])` and registers it under
+ *    `globalThis.__ggui__.contexts[contextName]`. The Context value
+ *    type is `readonly [value, setter]` — same shape `useState`
+ *    returns — so the wire-package `useGguiContext` hook can read it
+ *    via plain `useContext`.
+ * 2. The runtime mounts the user's component INSIDE a nested tree of
+ *    `<SingleSlotProvider>`s. Each SingleSlotProvider owns the slot's
+ *    `useState`, debounces value changes, validates against the slot's
+ *    `schema`, and posts `ui/update-model-context` to the parent.
+ * 3. The Provider value passed downward is `[value, setValue] as const`
+ *    — the user component reads both via
+ *    `const [v, setV] = useGguiContext<T>(slotName)` (auto-generated
+ *    by the boilerplate, one line per declared slot).
+ * 4. The last-emitted value per slot lives in a module-level
+ *    `Map<slotName, value>` so the reconnect path can re-emit after a
+ *    re-mount.
+ *
+ * **Why the runtime hoists the Provider tree.** An earlier design had
+ * the boilerplate emit `useState` + `<Provider>` wraps INSIDE the user
+ * component's return; the runtime mounted observers as SIBLINGS,
+ * outside the user component, which meant every observer's
+ * `useContext` read the `createContext(default)` argument — never the
+ * live Provider value. The fix is to move both useState AND the
+ * Provider into the runtime layer; the user component now reads via a
+ * plain `useContext`-backed hook (`useGguiContext`).
+ *
+ * **Idempotency on re-mount.** Context references must stay stable
+ * across re-mounts so the LLM's destructured component code keeps
+ * working. {@link ensureContext} reuses an existing entry by
+ * `contextName` and only creates when absent. The `setter` placeholder
+ * stored alongside the default is overwritten at mount time by each
+ * SingleSlotProvider's real `setValue`.
+ *
+ * **JSON safety.** Each post validates the value against the slot's
+ * `schema` via {@link validateContextValue}. Mismatches log a dev-only
+ * `console.warn` and drop silently in production (per Q4 design lock).
+ */
+import type { Context, ReactElement, ReactNode } from 'react';
+import type { JsonSchema } from '@ggui-ai/protocol';
+import type { GguiContextRegistry } from './globals.js';
+/**
+ * Wire-shape entry for a single contextSpec slot, mirrored from
+ * {@link import('@ggui-ai/protocol/integrations/mcp-apps').GguiBootstrapMeta.contextSlots}.
+ */
+export interface ContextSlotInfo {
+    readonly name: string;
+    readonly contextName: string;
+    readonly schema: JsonSchema;
+    /** Provider seed value. Always populated by the server — the
+     * runtime owns useState per slot, so the seed is load-bearing. */
+    readonly default: unknown;
+    readonly debounceMs?: number;
+}
+/**
+ * Resolved slot metadata after the runtime has synthesized (or reused)
+ * the React Context object. Carried into {@link SingleSlotProvider} so
+ * the Provider can reuse the same Context reference across renders.
+ */
+export interface ResolvedContextSlot {
+    readonly name: string;
+    readonly contextName: string;
+    readonly schema: JsonSchema;
+    readonly debounceMs: number;
+    readonly default: unknown;
+    readonly contextRef: Context<readonly [unknown, (next: unknown) => void]>;
+}
+/**
+ * Module-level map keyed by `name` (the camelCase slot key, NOT the
+ * PascalCase contextName) tracking the most-recently-emitted value
+ * per slot. Used by the reconnect re-emission path so a new mount
+ * after WS reopen seeds the LLM context with the last-known values.
+ *
+ * Exported for unit tests.
+ */
+export declare const contextSlotLastValues: Map<string, unknown>;
+/**
+ * Ensure a React Context is registered for `slot.contextName`. Idempotent —
+ * an entry already in the registry is REUSED (the LLM's destructured
+ * Context reference must remain stable across re-mounts). Only the
+ * absent case calls `react.createContext`.
+ *
+ * The Context value shape is `readonly [value, setter]` — same as
+ * `useState`, so the user-component's `useGguiContext` hook reads it
+ * via plain `useContext`. The setter stored at registration time is a
+ * no-op placeholder — each {@link SingleSlotProvider} mount overwrites
+ * it via the Provider's `value` prop.
+ *
+ * Returns the resolved slot with the live Context reference attached.
+ */
+export declare function ensureContext(registry: GguiContextRegistry, reactMod: {
+    createContext: <T>(defaultValue: T) => Context<T>;
+}, slot: ContextSlotInfo): ResolvedContextSlot;
+/**
+ * Install React Context objects for every entry in `slots` into
+ * `registry`. Returns the resolved slot list so callers can mount one
+ * SingleSlotProvider per entry. Idempotent — slots whose `contextName`
+ * is already in the registry reuse the existing Context.
+ */
+export declare function installContextRegistry(registry: GguiContextRegistry, reactMod: {
+    createContext: <T>(defaultValue: T) => Context<T>;
+}, slots: ReadonlyArray<ContextSlotInfo>): ReadonlyArray<ResolvedContextSlot>;
+/**
+ * Identity bundle carried alongside every snapshot post. The runtime
+ * captures these from the bootstrap envelope at boot and threads
+ * them through `createContextStateHost` so each snapshot's two
+ * destinations (host + server) carry the same authoritative session
+ * binding. Absent on dev / test code paths that don't have a real
+ * bootstrap; the server mirror is skipped in that case.
+ */
+export interface ContextPostIdentity {
+    readonly sessionId: string;
+    readonly appId: string;
+    readonly stackItemId: string;
+}
+/**
+ * React surface the host factories need. Production callers pass
+ * `typeof import('react')` directly; tests pass the same namespace
+ * (the real `react` module). Picking specific keys from the React
+ * module type lets the factories accept the namespace without
+ * hand-rolling structural-compat shims.
+ */
+export type ReactCoreForHost = Pick<typeof import('react'), 'createElement' | 'Fragment' | 'useState' | 'useEffect' | 'useRef'>;
+/**
+ * Build the `<SingleSlotProvider>` React component — owns one slot's
+ * useState + observer + Provider wrap. The runtime composes one of
+ * these per declared slot (via {@link createContextStateHost}).
+ *
+ * Built as a factory so the runtime can pass dependencies (`react`,
+ * `postToParent`, `consoleWarn`) without re-importing in this module
+ * — keeps the file pure and unit-testable.
+ *
+ * Exported because `__tests__/context-observer.test.ts` mounts it
+ * standalone to verify the value→post→Provider cycle.
+ */
+export declare function createSingleSlotProvider(deps: {
+    readonly react: ReactCoreForHost;
+    readonly postToParent: (envelope: unknown) => void;
+    readonly consoleWarn?: (...args: unknown[]) => void;
+    /** Identity bundle threaded into every snapshot post — server
+     *  mirror skipped when undefined. */
+    readonly identity?: ContextPostIdentity;
+}): (props: {
+    readonly slot: ResolvedContextSlot;
+    readonly children?: ReactNode;
+}) => ReactElement;
+/**
+ * Build the `ContextStateHost` component — composes
+ * {@link createSingleSlotProvider} once per declared slot to nest
+ * Providers around the user's component.
+ *
+ * The composed shape is:
+ *
+ * ```tsx
+ * <SingleSlotProvider slot={slots[0]}>
+ *   <SingleSlotProvider slot={slots[1]}>
+ *     {userComponent}
+ *   </SingleSlotProvider>
+ * </SingleSlotProvider>
+ * ```
+ *
+ * Outermost Provider = first declared slot. Order doesn't affect
+ * `useGguiContext` lookups (each Context is independent), but it's
+ * stable for snapshot debugging.
+ *
+ * When `slots` is empty, the host renders children unchanged (no
+ * extra wrapper).
+ */
+export declare function createContextStateHost(deps: {
+    readonly react: ReactCoreForHost;
+    readonly postToParent: (envelope: unknown) => void;
+    readonly consoleWarn?: (...args: unknown[]) => void;
+    /** Identity bundle for the server-mirror destination. Threaded
+     *  unchanged into `createSingleSlotProvider` so every slot's debounced
+     *  post carries the same authoritative session binding. */
+    readonly identity?: ContextPostIdentity;
+}): (props: {
+    readonly slots: ReadonlyArray<ResolvedContextSlot>;
+    readonly children: ReactNode;
+}) => ReactElement;
+/**
+ * Walk {@link contextSlotLastValues} and re-post each entry to the
+ * parent, filtered to slot names that the new mount actually
+ * declares. Used by the re-mount path — when a fresh boot completes
+ * after the previous mount torn down, re-seed the LLM context with
+ * the LAST values from the previous mount.
+ *
+ * Filter behavior. An earlier version walked the whole map without
+ * filtering, which leaked stale values across contracts: a re-mount
+ * with a different `contextSpec` (different slot names) re-emitted
+ * entries the new contract didn't declare. The current signature takes
+ * the active slot names; entries whose key is NOT in the set get
+ * dropped from the map AND skipped on emit.
+ *
+ * Pass `undefined` to skip filtering (kept for tests that exercise the
+ * bare module). Runtime call sites pass the active slots so the leak
+ * path is closed by construction.
+ */
+export declare function reemitLastContextValues(postToParent: (envelope: unknown) => void, activeSlotNames?: ReadonlySet<string>, identity?: ContextPostIdentity): void;