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

package/dist/validation.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Renderer-local contract-validation seam.
+ *
+ * Every wire-traffic check in the iframe-runtime routes through this
+ * module. Its two jobs:
+ *
+ *   1. **Precompiled-validator substitution (A4 / CSP fix).** The
+ *      renderer iframe runs under a strict CSP with no `'unsafe-eval'`,
+ *      so it cannot call `ajv.compile()` (codegen via `new Function`).
+ *      The server precompiles each contract sub-schema into an
+ *      eval-free ESM validator module and ships them on the bootstrap;
+ *      {@link loadCompiledValidators} loads them into a
+ *      {@link CompiledValidatorSet} which {@link setActiveValidatorSet}
+ *      installs here. Each validator below passes the matching
+ *      precompiled `ValidateFunction` into the protocol validator,
+ *      which uses it INSTEAD of compiling the schema in-iframe.
+ *      A defensive try/catch degrades to permissive if the protocol
+ *      validator still throws (precompiled validator absent + CSP
+ *      blocks the `ajv.compile()` fallback) — a dispatched action
+ *      beats a silently-dropped one.
+ *
+ *   2. **Reserved-channel validator composition** — A2UI default for
+ *      `_ggui:preview` composed with any bootstrap-supplied overrides.
+ *
+ * The renderer owns reserved-channel validation. The `<McpAppIframe>`
+ * host wrapper explicitly does NOT run this path — its only contract is
+ * the postMessage bridge to the renderer iframe.
+ */
+import type { ActionSpec, ActionEnvelope, ContextSpec, JsonObject, PropsSpec, ReservedChannelValidator, StreamSpec, ValidationResult } from '@ggui-ai/protocol';
+import type { CompiledValidatorSet } from './compiled-validators.js';
+/**
+ * Install the precompiled validators loaded from the bootstrap. Called
+ * once per boot (both `bootProduction` and `bootSelfContained`), after
+ * the bootstrap is parsed. A single set per iframe document — one
+ * session, one active contract.
+ */
+export declare function setActiveValidatorSet(set: CompiledValidatorSet | undefined): void;
+/**
+ * Merge two reserved-validator maps. Override keys WIN on conflict.
+ * The renderer ships an A2UI default for `_ggui:preview`; the
+ * bootstrap MAY replace it by key (not yet wired on the producer
+ * side — reserved as an extensibility slot).
+ */
+export declare function mergeReservedValidators(base: ReadonlyMap<string, ReservedChannelValidator> | undefined, override: ReadonlyMap<string, ReservedChannelValidator> | undefined): ReadonlyMap<string, ReservedChannelValidator> | undefined;
+export interface RendererValidatorContext {
+    /**
+     * Composed reserved-channel validators resolved once at boot.
+     * Passed through to `validateStreamData`'s `extraReservedValidators`
+     * param. `undefined` is honest-permissive (matches the pre-Item-4
+     * behavior; useful for test harnesses).
+     */
+    readonly reservedValidators: ReadonlyMap<string, ReservedChannelValidator> | undefined;
+}
+/**
+ * Validate an outbound {@link ActionEnvelope} before emitting over the
+ * live channel. Symmetric with the server's inbound enforcement.
+ *
+ * `actionSpec === undefined` = permissive (the server's "no contract to
+ * enforce" posture). Uses the precompiled action validators when
+ * present so the dispatch never trips the iframe's no-`unsafe-eval` CSP.
+ */
+export declare function validateOutboundActionEnvelope(actionSpec: ActionSpec | undefined, envelope: ActionEnvelope): ValidationResult;
+/**
+ * Validate an inbound stream-channel delivery before applying it to
+ * stack-item state. Known reserved channels (`_ggui:*`) validate even
+ * when the target stack item has no declared `streamSpec` — the
+ * payload shape is server-owned; user channels stay permissive without
+ * a contract.
+ */
+export declare function validateInboundStreamPayload(streamSpec: StreamSpec | undefined, channelName: string, payload: unknown, ctx: RendererValidatorContext): ValidationResult;
+/**
+ * Validate an inbound `props_update` payload before patching a stack
+ * item's props. Server already runs `assertPropsContract` on the emit
+ * path; this client-side revalidation is defense-in-depth for
+ * spec-versioning drift (server snapshot ≠ client cached spec).
+ */
+export declare function validateInboundPropsPayload(propsSpec: PropsSpec | undefined, props: JsonObject): ValidationResult;
+/**
+ * Validate a contextSpec slot value before the observer posts a
+ * `ui/update-model-context` envelope. Uses the precompiled context
+ * validators when present so the gate never trips the CSP.
+ */
+export declare function validateContextValue(spec: ContextSpec, slotName: string, value: unknown): ValidationResult;

package/dist/validation.js

@@ -0,0 +1,106 @@
+import { isKnownReservedChannel, validateActionEnvelope, validateContextData, validatePropsData, validateStreamData, } from '@ggui-ai/protocol';
+// =============================================================================
+// Active precompiled-validator set
+// =============================================================================
+/**
+ * Boot-installed precompiled validators for the active stack item's
+ * contract. `undefined` until {@link setActiveValidatorSet} runs (and
+ * in unit tests, which exercise the in-iframe compilation fallback).
+ */
+let activeValidatorSet;
+/**
+ * Install the precompiled validators loaded from the bootstrap. Called
+ * once per boot (both `bootProduction` and `bootSelfContained`), after
+ * the bootstrap is parsed. A single set per iframe document — one
+ * session, one active contract.
+ */
+export function setActiveValidatorSet(set) {
+    activeValidatorSet = set;
+}
+const VALID = { valid: true, violations: [] };
+/**
+ * Run a protocol validator, degrading to permissive if it throws. The
+ * only throw path is the CSP `EvalError` from an `ajv.compile()`
+ * fallback when no precompiled validator covered the surface — better a
+ * dispatched action than a crash that silently drops it.
+ */
+function guarded(label, run) {
+    try {
+        return run();
+    }
+    catch (err) {
+        if (typeof console !== 'undefined') {
+            console.warn(`[ggui:validation] ${label}: validator unavailable (no precompiled validator + CSP blocks in-iframe compile) — allowing through`, err);
+        }
+        return VALID;
+    }
+}
+// =============================================================================
+// Reserved validator map composition
+// =============================================================================
+/**
+ * Merge two reserved-validator maps. Override keys WIN on conflict.
+ * The renderer ships an A2UI default for `_ggui:preview`; the
+ * bootstrap MAY replace it by key (not yet wired on the producer
+ * side — reserved as an extensibility slot).
+ */
+export function mergeReservedValidators(base, override) {
+    if (!base && !override)
+        return undefined;
+    if (!base)
+        return override;
+    if (!override)
+        return base;
+    const merged = new Map(base);
+    for (const [key, validator] of override) {
+        merged.set(key, validator);
+    }
+    return merged;
+}
+/**
+ * Validate an outbound {@link ActionEnvelope} before emitting over the
+ * live channel. Symmetric with the server's inbound enforcement.
+ *
+ * `actionSpec === undefined` = permissive (the server's "no contract to
+ * enforce" posture). Uses the precompiled action validators when
+ * present so the dispatch never trips the iframe's no-`unsafe-eval` CSP.
+ */
+export function validateOutboundActionEnvelope(actionSpec, envelope) {
+    return guarded('outbound-action', () => validateActionEnvelope(envelope, actionSpec, activeValidatorSet?.actions));
+}
+/**
+ * Validate an inbound stream-channel delivery before applying it to
+ * stack-item state. Known reserved channels (`_ggui:*`) validate even
+ * when the target stack item has no declared `streamSpec` — the
+ * payload shape is server-owned; user channels stay permissive without
+ * a contract.
+ */
+export function validateInboundStreamPayload(streamSpec, channelName, payload, ctx) {
+    return guarded('inbound-stream', () => {
+        if (isKnownReservedChannel(channelName)) {
+            return validateStreamData(channelName, payload, streamSpec ?? {}, ctx.reservedValidators, activeValidatorSet?.streams);
+        }
+        if (!streamSpec)
+            return VALID;
+        return validateStreamData(channelName, payload, streamSpec, ctx.reservedValidators, activeValidatorSet?.streams);
+    });
+}
+/**
+ * Validate an inbound `props_update` payload before patching a stack
+ * item's props. Server already runs `assertPropsContract` on the emit
+ * path; this client-side revalidation is defense-in-depth for
+ * spec-versioning drift (server snapshot ≠ client cached spec).
+ */
+export function validateInboundPropsPayload(propsSpec, props) {
+    if (!propsSpec)
+        return VALID;
+    return guarded('inbound-props', () => validatePropsData(props, propsSpec, activeValidatorSet?.props));
+}
+/**
+ * Validate a contextSpec slot value before the observer posts a
+ * `ui/update-model-context` envelope. Uses the precompiled context
+ * validators when present so the gate never trips the CSP.
+ */
+export function validateContextValue(spec, slotName, value) {
+    return guarded('context-slot', () => validateContextData(slotName, value, spec, activeValidatorSet?.context));
+}

package/dist/wire-config.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Per-stack-item `WireConfig` factory for the renderer iframe.
+ *
+ * The renderer iframe uses a standalone
+ * `scopeWireConfig(root, item, internals)` function plus the
+ * `RootWireConfigBundle.buildScopedConfig(item)` closure returned
+ * from `buildRootWireConfig` — there is no scoping method on the
+ * public `WireConfig` shape.
+ *
+ * Why per-item scoping:
+ *   - A stacked/chat-style UI keeps older cards rendered beneath the
+ *     top one. A `useAction('submit')` call inside an older card MUST
+ *     emit with THAT card's `stackItemId` + `tool` + `actionSpec` — not the
+ *     top-of-stack's. Without per-item scoping, contract enforcement
+ *     would reject cross-stack dispatches as "wrong contract" OR the
+ *     wrong tool would be invoked server-side.
+ *
+ * Construction: the renderer builds ONE top-level bundle at boot
+ * (`buildRootWireConfig`), which returns `{config, buildScopedConfig}`.
+ * The runtime's `stackCtx.getScopedWireConfig` calls
+ * `buildScopedConfig(item)` per stack entry; each
+ * `<GguiWireProvider>` wraps a stack item with the resulting scoped
+ * config.
+ *
+ * Outbound dispatch uses `buildActionEnvelope` (from
+ * `@ggui-ai/wire`) + `validateOutboundActionEnvelope` + a direct
+ * `manager.send({type:'action', payload})`.
+ *
+ * The `WireConfig` shape lives in `@ggui-ai/wire`. This module
+ * implements against that interface.
+ */
+import type { ActionSpec, SessionStackEntry, StreamEnvelope } from '@ggui-ai/protocol';
+import { ClientContractViolationError, type WireConfig } from '@ggui-ai/wire';
+import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
+/**
+ * Outbound send surface — the minimal shape wire-config calls on the
+ * WS transport. Pre-B3b this read off `Pick<RendererWebSocketManager,
+ * 'send'>`; post-B3b the WS lives inside `@ggui-ai/channel-client`,
+ * but wire-config doesn't import the gadget directly — it consumes
+ * the shape via this local type so tests can stub `{send: vi.fn()}`
+ * without dragging in the channel-client types.
+ *
+ * Frames sent here are always `{type: 'action', payload: ...}` or
+ * `{type: 'feedback', payload: ...}` envelopes — wire-config never
+ * sends transport-layer frames (`ping`, `subscribe`).
+ */
+export interface RendererSendSurface {
+    readonly send: (message: WebSocketMessage) => void;
+}
+import { type ProtocolErrorEmitter } from './protocol-error.js';
+import type { ObservabilityEmitter } from './observability.js';
+/**
+ * Tiny fan-out bus keyed by channel name. `subscribe.ts`'s inbound-
+ * message handler pushes validated `data` envelopes here; wire's
+ * `useStream(channel)` subscribes per-component via the config's
+ * `subscribe()` method.
+ *
+ * Late-subscriber replay for reserved channels:
+ *
+ *   The renderer iframe boots in a strict ordering:
+ *   `subscribe()` → first `ack` → render stack items → mount
+ *   `mountProvisional` → it then calls `streamBus.subscribe('_ggui:
+ *   preview', …)`. Server-side replay frames for `_ggui:preview` (the
+ *   provisional A2UI preamble fired during the agent's `ggui_push`
+ *   BEFORE the user's browser navigated to the viewer) arrive over the
+ *   WS in the window between ack-resolve and the provisional mount —
+ *   they hit `emit()` before any listener has subscribed. Without a
+ *   bounded reserved-channel ring, those frames vanish and the preview
+ *   surface stays stuck on the spinner.
+ *
+ *   Server-owned `_ggui:*` channels are buffered in a per-channel ring
+ *   capped at {@link RESERVED_CHANNEL_REPLAY_MAX}. New subscribers
+ *   receive the buffered envelopes synchronously before the unsubscribe
+ *   handle returns — same mental model as the server-side
+ *   `SessionStreamBuffer.replay(...)` walk over reserved channels at
+ *   ack time, but mirrored at the inner bus boundary so the host
+ *   transport stays portable (Claude Desktop / ChatGPT / Cursor /
+ *   `<McpAppIframe>` all behave the same).
+ *
+ *   Agent-declared (non-reserved) channels are NOT buffered here. Their
+ *   replay is the server's job — the renderer's `subscribe()` handshake
+ *   pulls history per `streamSpec.replay` policy when reconnecting with
+ *   `fromSeq`. Buffering them at this layer would double-count and
+ *   change the semantics of agent contracts.
+ *
+ * No observable mutation outside the renderer boundary — the bus is
+ * internal plumbing.
+ */
+export declare class StreamBus {
+    private listeners;
+    /**
+     * Per-channel bounded ring of envelopes for reserved (`_ggui:*`)
+     * channels only. FIFO eviction at `RESERVED_CHANNEL_REPLAY_MAX`.
+     * Replayed to every new subscriber for that channel.
+     */
+    private reservedReplay;
+    subscribe(channel: string, listener: (env: StreamEnvelope) => void): () => void;
+    emit(envelope: StreamEnvelope): void;
+}
+export interface BuildRootWireConfigOptions {
+    readonly sessionId: string;
+    readonly appId: string;
+    /**
+     * Stack snapshot reader. The config's default (unscoped) `dispatch`
+     * reads the top of stack; callers route most dispatches through
+     * `scopeWireConfig(root, item)` for per-item targeting, but the
+     * default is kept for standalone-render paths.
+     */
+    readonly getStack: () => readonly SessionStackEntry[];
+    /** Handle to the renderer's WS manager; used for outbound `action` + `feedback` frames. */
+    readonly manager: RendererSendSurface;
+    /** Shared bus for inbound stream deliveries. */
+    readonly streamBus: StreamBus;
+    /**
+     * Optional sink for contract violations. Default: tagged
+     * `console.warn`. Tests inject a recorder. Matches
+     * `GguiSession.onError` semantics on the client-contract path.
+     *
+     * Prefer {@link onProtocolError} for new integrations — it receives
+     * the widened {@link ProtocolError} union that covers every error
+     * the renderer classifies (transport, auth, protocol, contract,
+     * bootstrap, version, unknown). The narrow `onContractViolation`
+     * sink stays for in-renderer tests that assert the raw class shape;
+     * every violation is ALSO forwarded through `onProtocolError` so
+     * external consumers can observe one seam.
+     */
+    readonly onContractViolation?: (err: ClientContractViolationError) => void;
+    /**
+     * Optional sink for every typed {@link ProtocolError} the renderer
+     * classifies. Default: {@link defaultProtocolErrorEmitter}
+     * (`console.warn` with a grep-friendly tag). The `<McpAppIframe>`
+     * host wrapper wires this to its `onError` prop; session-bound
+     * variants are ALSO mirrored to the `_ggui:contract-error` WS
+     * envelope.
+     *
+     * The emitter fires for CLIENT-side contract violations (via
+     * `fromClientContractViolation`). Other sites (subscribe failures,
+     * upgrade-required, transport errors, server-emitted
+     * contract-error envelopes) plumb through the same emitter without
+     * a shape change.
+     */
+    readonly onProtocolError?: ProtocolErrorEmitter;
+    /**
+     * Optional {@link ObservabilityEmitter} sink. Fires a
+     * `wired-tool-invoked` event every time {@link dispatchByItem}
+     * successfully sends a wired-action envelope (i.e. the ctx's
+     * resolved `tool` is populated AND outbound validation passed).
+     *
+     * The event is client-side — `dispatchedAt` records when the
+     * envelope left the renderer, NOT when the server's router
+     * completed the tool. The SERVER independently emits a
+     * `wired-tool.invoked` telemetry event on its own sink for
+     * operational metrics; the two surfaces are deliberately separate
+     * (host inspector vs operator telemetry).
+     */
+    readonly onObserve?: ObservabilityEmitter;
+}
+/**
+ * Paired root config + scope factory returned by `buildRootWireConfig`.
+ *
+ * {@link WireConfig} itself carries no `scope(item)` method — the
+ * interface is the minimum contract generated code needs, and
+ * per-item scoping is a RENDERER concern. Callers that need
+ * per-item scoping — currently only the renderer's `bootProduction`
+ * via `stackCtx.getScopedWireConfig` — use `buildScopedConfig(item)`
+ * on the returned `RootWireConfigBundle`.
+ *
+ * The scope-factory is PAIRED with the root construction so the
+ * `dispatchByItem` / `getStack` internals stay encapsulated — they
+ * aren't exported from this module and never leak into the public
+ * WireConfig shape.
+ */
+export interface RootWireConfigBundle {
+    readonly config: WireConfig;
+    /**
+     * Build a per-stack-item scoped `WireConfig`. Only `dispatch` is
+     * overridden — every other seam (subscribe, app/session/auth) stays
+     * shared via spread from the root.
+     */
+    readonly buildScopedConfig: (item: {
+        readonly stackItemId?: string;
+        readonly contractHash?: string;
+        readonly actionSpec?: ActionSpec;
+    }) => WireConfig;
+}
+/**
+ * Build the unscoped root `WireConfig` + its scope-factory closure.
+ * Bootstraps the renderer's outbound emission + inbound subscription
+ * seams.
+ *
+ * Returns a {@link RootWireConfigBundle} rather than a bare
+ * `WireConfig` — the scope factory is paired with the root so
+ * `dispatchByItem` internals don't leak onto the public WireConfig
+ * shape. `scopeWireConfig` (the exported standalone) is the low-level
+ * primitive; `buildScopedConfig` is the pre-bound convenience.
+ */
+export declare function buildRootWireConfig(opts: BuildRootWireConfigOptions): RootWireConfigBundle;
+/**
+ * Produce a per-item scoped `WireConfig`. The only override is
+ * `dispatch` — every other seam (subscribe) stays shared.
+ */
+export declare function scopeWireConfig(root: WireConfig, item: {
+    stackItemId?: string;
+    contractHash?: string;
+    actionSpec?: ActionSpec;
+}, internals: {
+    getStack: () => readonly SessionStackEntry[];
+    dispatchByItem: (actionName: string, data: unknown, ctx: {
+        stackItemId?: string;
+        stackIndex: number;
+        tool?: string;
+        actionSpec?: ActionSpec;
+    }) => void;
+}): WireConfig;