oui-spec 0.2.0 → 0.4.0

package/dist/{define-surface-DXBop-uB.d.ts → surface-runtime-DeByfbKg.d.ts}

@@ -1,4 +1,5 @@
-import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface } from './spec/index.js';
+import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult } from './spec/index.js';
+import { S as SocketLike, d as OUITransportConfig } from './websocket-c5tIUWY5.js';
 
 /**
  * Nominal branding for values OUI must construct itself.
@@ -148,4 +149,103 @@ interface DefinedSurface<TContext = unknown> extends SurfaceDefinition<TContext>
     getPollingConfig(actionId: string): OUIActionPolling | undefined;
 }
 
-export { type ActionDefinition as A, type DefinedSurface as D, type OUIBranded as O, type SurfaceDefinition as S, type ActionHandlerResult as a, type ActionPollingConfig as b, type ObservationDefinition as c, defineSurface as d };
+/**
+ * The client-side surface runtime.
+ *
+ * Holds the surfaces a client has mounted, answers every action request with a
+ * result, and produces the snapshot an agent runtime works from.
+ *
+ * WHY THIS EXISTS
+ *
+ * The first integration kept no client-side record of what was mounted. Each
+ * surface hook registered itself with a server-side registry and listened for
+ * dispatches on its own. Three things followed:
+ *
+ * - The registry was the only record of what the client could do, and it lost
+ *   entries: a dead socket's cleanup removed a live tab's registration, and the
+ *   browser never registered again. The agent then had no UI tools at all.
+ * - Nothing answered a dispatch. The agent was told an action succeeded before
+ *   the client had run it, and never saw the page an action led to.
+ * - Every hook listened independently, through two paths, so one dispatch ran
+ *   twice and nothing de-duplicated it.
+ *
+ * Here the client is the record. `snapshot()` is what the client can do right
+ * now, and every request is run once, waited on until the UI settles, and
+ * answered with its result and the snapshot after it.
+ */
+
+interface SettleOptions {
+    /**
+     * The UI counts as settled once nothing has mounted, unmounted or changed an
+     * observation for this long, and no hold is open. Default 250 ms.
+     */
+    quietMs?: number;
+    /** Give up waiting after this long and answer with `settled: false`. Default 5000 ms. */
+    timeoutMs?: number;
+}
+interface SurfaceRuntimeOptions {
+    /** The socket to answer requests on. Can be set or replaced later with `attach`. */
+    socket?: SocketLike | null;
+    /** Wire configuration for the transport the runtime builds on the socket. */
+    transport?: OUITransportConfig;
+    /**
+     * Also announce registrations and observations over the transport, for agent
+     * runtimes that keep a server-side registry. Default true.
+     *
+     * An agent runtime that takes the client's snapshot instead (sent with each
+     * turn, and returned on every result) has no use for them: set false.
+     */
+    announce?: boolean;
+    settle?: SettleOptions;
+    /** How many answered request ids to remember, for de-duplication. Default 500. */
+    dedupeWindow?: number;
+    /**
+     * Decides whether a request that arrived on the socket may run at all. A
+     * refused request is neither run nor answered, and is logged.
+     *
+     * The server should be the only sender of action requests, but a client can
+     * also check that a request is one it expects: for example, only while its
+     * agent has a turn in progress. Requests passed to `execute` directly are
+     * not checked; they come from the application itself.
+     */
+    accept?: (request: OUIActionRequest) => boolean;
+}
+interface MountedSurface {
+    readonly surfaceId: string;
+    /** Record an observation value. A no-op once unmounted. */
+    pushObservation(observationId: string, value: unknown): void;
+    /** Remove this mount. Other mounts of the same surface id are unaffected. */
+    unmount(): void;
+}
+interface SurfaceRuntime {
+    /**
+     * Mount a surface. `getContext` is read when an action runs, so handlers see
+     * the latest state rather than the state at mount time.
+     *
+     * Mounting the same surface id twice is allowed (React StrictMode does it on
+     * every mount); the most recent mount serves its actions.
+     */
+    mount<TContext>(surface: DefinedSurface<TContext>, getContext: () => TContext): MountedSurface;
+    /** Answer requests arriving on this socket (null detaches). */
+    attach(socket: SocketLike | null): void;
+    /** What the client can do right now. */
+    snapshot(): OUISurfaceSnapshot;
+    /**
+     * Run a request once and resolve with its result. A request id seen before
+     * resolves with the first result instead of running again.
+     */
+    execute(request: OUIActionRequest): Promise<OUIActionResult>;
+    /**
+     * Keep the UI unsettled until the returned function is called. For work an
+     * action starts that mounting and unmounting cannot show, such as a route's
+     * code still loading or a page fetching the data it will display.
+     */
+    hold(): () => void;
+    /** Called whenever the snapshot changes. */
+    subscribe(listener: () => void): () => void;
+    /** Stop polling, detach from the socket and forget every mount. */
+    dispose(): void;
+}
+declare function createSurfaceRuntime(options?: SurfaceRuntimeOptions): SurfaceRuntime;
+
+export { type ActionDefinition as A, type DefinedSurface as D, type MountedSurface as M, type OUIBranded as O, type SettleOptions as S, type ActionHandlerResult as a, type ActionPollingConfig as b, type ObservationDefinition as c, type SurfaceDefinition as d, type SurfaceRuntime as e, type SurfaceRuntimeOptions as f, createSurfaceRuntime as g, defineSurface as h };

package/dist/transport/index.cjs

@@ -1,17 +1,17 @@
 'use strict';
 
-var chunk5TQ6AVQH_cjs = require('../chunk-5TQ6AVQH.cjs');
-var chunkMTMEW6MM_cjs = require('../chunk-MTMEW6MM.cjs');
+var chunkROGKEMLL_cjs = require('../chunk-ROGKEMLL.cjs');
+var chunkDCVVTP3V_cjs = require('../chunk-DCVVTP3V.cjs');
 
 
 
 Object.defineProperty(exports, "createDirectTransportPair", {
   enumerable: true,
-  get: function () { return chunk5TQ6AVQH_cjs.createDirectTransportPair; }
+  get: function () { return chunkROGKEMLL_cjs.createDirectTransportPair; }
 });
 Object.defineProperty(exports, "createWebSocketTransport", {
   enumerable: true,
-  get: function () { return chunkMTMEW6MM_cjs.createWebSocketTransport; }
+  get: function () { return chunkDCVVTP3V_cjs.createWebSocketTransport; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/transport/index.d.cts

@@ -1,5 +1,5 @@
-import { b as OUITransport } from '../websocket-CrI0yRNo.cjs';
-export { O as OUIActionHandler, a as OUIObservationHandler, c as OUITransportConfig, S as SocketLike, d as createWebSocketTransport } from '../websocket-CrI0yRNo.cjs';
+import { c as OUITransport } from '../websocket-YfWILdZ4.cjs';
+export { O as OUIActionHandler, a as OUIObservationHandler, b as OUIResultHandler, d as OUITransportConfig, S as SocketLike, e as createWebSocketTransport } from '../websocket-YfWILdZ4.cjs';
 import '../spec/index.cjs';
 
 /**

package/dist/transport/index.d.ts

@@ -1,5 +1,5 @@
-import { b as OUITransport } from '../websocket-CiWvkaz_.js';
-export { O as OUIActionHandler, a as OUIObservationHandler, c as OUITransportConfig, S as SocketLike, d as createWebSocketTransport } from '../websocket-CiWvkaz_.js';
+import { c as OUITransport } from '../websocket-c5tIUWY5.js';
+export { O as OUIActionHandler, a as OUIObservationHandler, b as OUIResultHandler, d as OUITransportConfig, S as SocketLike, e as createWebSocketTransport } from '../websocket-c5tIUWY5.js';
 import '../spec/index.js';
 
 /**

package/dist/transport/index.js

@@ -1,4 +1,4 @@
-export { createDirectTransportPair } from '../chunk-O6EI77LD.js';
-export { createWebSocketTransport } from '../chunk-YDMGV72W.js';
+export { createDirectTransportPair } from '../chunk-IIZ6HL2L.js';
+export { createWebSocketTransport } from '../chunk-F3WKIRAU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{websocket-CrI0yRNo.d.cts → websocket-YfWILdZ4.d.cts}

@@ -1,20 +1,28 @@
-import { OUIObservationUpdate, OUISurface } from './spec/index.cjs';
+import { OUIActionRequest, OUIActionResult, OUIObservationUpdate, OUISurface } from './spec/index.cjs';
 
 /**
  * OUI Transport — the wire protocol between agent runtime and surfaces.
  *
- * Two one-way channels:
- * - Dispatch channel (server → client): sends action instructions
- * - Observation channel (client → server): pushes state updates
+ * - Dispatch (runtime → client): an `OUIActionRequest`, carrying a `requestId`.
+ * - Result (client → runtime): the `OUIActionResult` for that `requestId`.
+ * - Observations (client → runtime): state updates pushed as they happen.
+ * - Surface lifecycle (client → runtime): registration, for runtimes that keep
+ *   a server-side registry. A runtime can instead take the client's snapshot.
  *
- * NO request/response. NO correlation IDs. NO waiting.
- * The Lambda dispatches and terminates. The browser processes and pushes state.
+ * Every dispatch is answered by exactly one result. An earlier version of this
+ * transport had no correlation id and no result channel, so an agent could
+ * never learn whether its action ran, and was told it succeeded before the
+ * client had done anything.
  */
 interface OUITransport {
-    /** Dispatch an action to a surface (one-way, fire-and-forget) */
-    dispatch(surfaceId: string, actionId: string, params: Record<string, unknown>): void;
-    /** Receive dispatched actions (surface/client side) */
+    /** Send an action request to the client. */
+    dispatch(request: OUIActionRequest): void;
+    /** Receive action requests (client side). */
     onAction(handler: OUIActionHandler): () => void;
+    /** Answer an action request (client side). */
+    sendResult(result: OUIActionResult): void;
+    /** Receive action results (runtime side). */
+    onResult(handler: OUIResultHandler): () => void;
     /** Push an observation update from the surface to the agent runtime */
     pushObservation(update: OUIObservationUpdate): void;
     /** Receive observation updates (runtime/server side) */
@@ -29,11 +37,20 @@ interface OUITransport {
     onSurfaceDeregister(handler: (surfaceId: string) => void): () => void;
     readonly connected: boolean;
     connect(): Promise<void>;
+    /** Disconnect the underlying socket. The integrator owns the socket: prefer `dispose`. */
     disconnect(): void;
     onConnectionChange(handler: (connected: boolean) => void): () => void;
+    /**
+     * Detach every listener this transport attached to its socket, and leave the
+     * socket connected. A socket outlives the transports built on it; without
+     * this, each one leaked its connection listeners onto the shared socket.
+     */
+    dispose(): void;
 }
-/** Handler for incoming action dispatches (client side) */
-type OUIActionHandler = (surfaceId: string, actionId: string, params: Record<string, unknown>) => void;
+/** Handler for incoming action requests (client side) */
+type OUIActionHandler = (request: OUIActionRequest) => void;
+/** Handler for incoming action results (runtime side) */
+type OUIResultHandler = (result: OUIActionResult) => void;
 /** Handler for incoming observation updates (server side) */
 type OUIObservationHandler = (update: OUIObservationUpdate) => void;
 /**
@@ -44,7 +61,7 @@ interface OUITransportConfig {
     namespace?: string;
     /** Connection timeout in ms */
     connectTimeoutMs?: number;
-    /** Whether to buffer dispatches while disconnected */
+    /** Whether to buffer outbound messages while disconnected */
     bufferWhileDisconnected?: boolean;
     /** Max buffer size (messages dropped after this) */
     maxBufferSize?: number;
@@ -54,11 +71,12 @@ interface OUITransportConfig {
  * WebSocket transport using Socket.IO.
  * Maps OUI protocol events to socket events with a configurable namespace prefix.
  *
- * Events emitted:
- *   {ns}:dispatch        — action dispatch (server → client)
- *   {ns}:observation     — observation update (client → server)
- *   {ns}:surface:register   — surface registration (client → server)
- *   {ns}:surface:deregister — surface deregistration (client → server)
+ * Events:
+ *   {ns}:dispatch            — action request   (runtime → client)
+ *   {ns}:action:result       — action result    (client → runtime)
+ *   {ns}:observation         — observation      (client → runtime)
+ *   {ns}:surface:register    — registration     (client → runtime)
+ *   {ns}:surface:deregister  — deregistration   (client → runtime)
  */
 declare function createWebSocketTransport(socket: SocketLike, config?: OUITransportConfig): OUITransport;
 /**
@@ -75,4 +93,4 @@ interface SocketLike {
     disconnect?(): void;
 }
 
-export { type OUIActionHandler as O, type SocketLike as S, type OUIObservationHandler as a, type OUITransport as b, type OUITransportConfig as c, createWebSocketTransport as d };
+export { type OUIActionHandler as O, type SocketLike as S, type OUIObservationHandler as a, type OUIResultHandler as b, type OUITransport as c, type OUITransportConfig as d, createWebSocketTransport as e };

package/dist/{websocket-CiWvkaz_.d.ts → websocket-c5tIUWY5.d.ts}

@@ -1,20 +1,28 @@
-import { OUIObservationUpdate, OUISurface } from './spec/index.js';
+import { OUIActionRequest, OUIActionResult, OUIObservationUpdate, OUISurface } from './spec/index.js';
 
 /**
  * OUI Transport — the wire protocol between agent runtime and surfaces.
  *
- * Two one-way channels:
- * - Dispatch channel (server → client): sends action instructions
- * - Observation channel (client → server): pushes state updates
+ * - Dispatch (runtime → client): an `OUIActionRequest`, carrying a `requestId`.
+ * - Result (client → runtime): the `OUIActionResult` for that `requestId`.
+ * - Observations (client → runtime): state updates pushed as they happen.
+ * - Surface lifecycle (client → runtime): registration, for runtimes that keep
+ *   a server-side registry. A runtime can instead take the client's snapshot.
  *
- * NO request/response. NO correlation IDs. NO waiting.
- * The Lambda dispatches and terminates. The browser processes and pushes state.
+ * Every dispatch is answered by exactly one result. An earlier version of this
+ * transport had no correlation id and no result channel, so an agent could
+ * never learn whether its action ran, and was told it succeeded before the
+ * client had done anything.
  */
 interface OUITransport {
-    /** Dispatch an action to a surface (one-way, fire-and-forget) */
-    dispatch(surfaceId: string, actionId: string, params: Record<string, unknown>): void;
-    /** Receive dispatched actions (surface/client side) */
+    /** Send an action request to the client. */
+    dispatch(request: OUIActionRequest): void;
+    /** Receive action requests (client side). */
     onAction(handler: OUIActionHandler): () => void;
+    /** Answer an action request (client side). */
+    sendResult(result: OUIActionResult): void;
+    /** Receive action results (runtime side). */
+    onResult(handler: OUIResultHandler): () => void;
     /** Push an observation update from the surface to the agent runtime */
     pushObservation(update: OUIObservationUpdate): void;
     /** Receive observation updates (runtime/server side) */
@@ -29,11 +37,20 @@ interface OUITransport {
     onSurfaceDeregister(handler: (surfaceId: string) => void): () => void;
     readonly connected: boolean;
     connect(): Promise<void>;
+    /** Disconnect the underlying socket. The integrator owns the socket: prefer `dispose`. */
     disconnect(): void;
     onConnectionChange(handler: (connected: boolean) => void): () => void;
+    /**
+     * Detach every listener this transport attached to its socket, and leave the
+     * socket connected. A socket outlives the transports built on it; without
+     * this, each one leaked its connection listeners onto the shared socket.
+     */
+    dispose(): void;
 }
-/** Handler for incoming action dispatches (client side) */
-type OUIActionHandler = (surfaceId: string, actionId: string, params: Record<string, unknown>) => void;
+/** Handler for incoming action requests (client side) */
+type OUIActionHandler = (request: OUIActionRequest) => void;
+/** Handler for incoming action results (runtime side) */
+type OUIResultHandler = (result: OUIActionResult) => void;
 /** Handler for incoming observation updates (server side) */
 type OUIObservationHandler = (update: OUIObservationUpdate) => void;
 /**
@@ -44,7 +61,7 @@ interface OUITransportConfig {
     namespace?: string;
     /** Connection timeout in ms */
     connectTimeoutMs?: number;
-    /** Whether to buffer dispatches while disconnected */
+    /** Whether to buffer outbound messages while disconnected */
     bufferWhileDisconnected?: boolean;
     /** Max buffer size (messages dropped after this) */
     maxBufferSize?: number;
@@ -54,11 +71,12 @@ interface OUITransportConfig {
  * WebSocket transport using Socket.IO.
  * Maps OUI protocol events to socket events with a configurable namespace prefix.
  *
- * Events emitted:
- *   {ns}:dispatch        — action dispatch (server → client)
- *   {ns}:observation     — observation update (client → server)
- *   {ns}:surface:register   — surface registration (client → server)
- *   {ns}:surface:deregister — surface deregistration (client → server)
+ * Events:
+ *   {ns}:dispatch            — action request   (runtime → client)
+ *   {ns}:action:result       — action result    (client → runtime)
+ *   {ns}:observation         — observation      (client → runtime)
+ *   {ns}:surface:register    — registration     (client → runtime)
+ *   {ns}:surface:deregister  — deregistration   (client → runtime)
  */
 declare function createWebSocketTransport(socket: SocketLike, config?: OUITransportConfig): OUITransport;
 /**
@@ -75,4 +93,4 @@ interface SocketLike {
     disconnect?(): void;
 }
 
-export { type OUIActionHandler as O, type SocketLike as S, type OUIObservationHandler as a, type OUITransport as b, type OUITransportConfig as c, createWebSocketTransport as d };
+export { type OUIActionHandler as O, type SocketLike as S, type OUIObservationHandler as a, type OUIResultHandler as b, type OUITransport as c, type OUITransportConfig as d, createWebSocketTransport as e };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oui-spec",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "OUI — The OpenUI Specification. A machine-readable contract for agent-controllable user interfaces.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -86,14 +86,18 @@
     }
   },
   "devDependencies": {
+    "@testing-library/react": "^16.3.3",
     "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.3.0",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "eslint": "^9.0.0",
     "husky": "^9.1.7",
+    "jsdom": "^26.1.0",
     "lint-staged": "^16.4.0",
     "prettier": "^3.9.6",
     "react": "^19.0.0",
+    "react-dom": "^19.3.0",
     "tsup": "^8.4.0",
     "typescript": "^5.8.0",
     "vitest": "^3.0.0"