oui-spec 0.1.0 → 0.3.0

package/dist/websocket-YfWILdZ4.d.cts

@@ -0,0 +1,96 @@
+import { OUIActionRequest, OUIActionResult, OUIObservationUpdate, OUISurface } from './spec/index.cjs';
+
+/**
+ * OUI Transport — the wire protocol between agent runtime and surfaces.
+ *
+ * - 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.
+ *
+ * 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 {
+    /** 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) */
+    onObservation(handler: OUIObservationHandler): () => void;
+    /** Register a surface manifest (client → server) */
+    registerSurface(surface: OUISurface): void;
+    /** Deregister a surface (client → server) */
+    deregisterSurface(surfaceId: string): void;
+    /** Receive surface registrations (server side) */
+    onSurfaceRegister(handler: (surface: OUISurface) => void): () => void;
+    /** Receive surface deregistrations (server side) */
+    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 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;
+/**
+ * Transport configuration options.
+ */
+interface OUITransportConfig {
+    /** Namespace prefix for events (default: 'oui') */
+    namespace?: string;
+    /** Connection timeout in ms */
+    connectTimeoutMs?: number;
+    /** Whether to buffer outbound messages while disconnected */
+    bufferWhileDisconnected?: boolean;
+    /** Max buffer size (messages dropped after this) */
+    maxBufferSize?: number;
+}
+
+/**
+ * WebSocket transport using Socket.IO.
+ * Maps OUI protocol events to socket events with a configurable namespace prefix.
+ *
+ * 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;
+/**
+ * Minimal socket interface — compatible with Socket.IO client or server socket.
+ * Only the methods OUI actually uses.
+ */
+interface SocketLike {
+    readonly connected?: boolean;
+    emit(event: string, data: unknown): void;
+    on(event: string, handler: (...args: any[]) => void): void;
+    off(event: string, handler: (...args: any[]) => void): void;
+    once(event: string, handler: (...args: any[]) => void): void;
+    connect?(): void;
+    disconnect?(): void;
+}
+
+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-c5tIUWY5.d.ts

@@ -0,0 +1,96 @@
+import { OUIActionRequest, OUIActionResult, OUIObservationUpdate, OUISurface } from './spec/index.js';
+
+/**
+ * OUI Transport — the wire protocol between agent runtime and surfaces.
+ *
+ * - 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.
+ *
+ * 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 {
+    /** 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) */
+    onObservation(handler: OUIObservationHandler): () => void;
+    /** Register a surface manifest (client → server) */
+    registerSurface(surface: OUISurface): void;
+    /** Deregister a surface (client → server) */
+    deregisterSurface(surfaceId: string): void;
+    /** Receive surface registrations (server side) */
+    onSurfaceRegister(handler: (surface: OUISurface) => void): () => void;
+    /** Receive surface deregistrations (server side) */
+    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 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;
+/**
+ * Transport configuration options.
+ */
+interface OUITransportConfig {
+    /** Namespace prefix for events (default: 'oui') */
+    namespace?: string;
+    /** Connection timeout in ms */
+    connectTimeoutMs?: number;
+    /** Whether to buffer outbound messages while disconnected */
+    bufferWhileDisconnected?: boolean;
+    /** Max buffer size (messages dropped after this) */
+    maxBufferSize?: number;
+}
+
+/**
+ * WebSocket transport using Socket.IO.
+ * Maps OUI protocol events to socket events with a configurable namespace prefix.
+ *
+ * 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;
+/**
+ * Minimal socket interface — compatible with Socket.IO client or server socket.
+ * Only the methods OUI actually uses.
+ */
+interface SocketLike {
+    readonly connected?: boolean;
+    emit(event: string, data: unknown): void;
+    on(event: string, handler: (...args: any[]) => void): void;
+    off(event: string, handler: (...args: any[]) => void): void;
+    once(event: string, handler: (...args: any[]) => void): void;
+    connect?(): void;
+    disconnect?(): void;
+}
+
+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.1.0",
+  "version": "0.3.0",
   "description": "OUI — The OpenUI Specification. A machine-readable contract for agent-controllable user interfaces.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -69,12 +69,13 @@
   ],
   "scripts": {
     "build": "tsup",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && npm run typecheck:contract",
     "lint": "eslint src",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepare": "husky",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "typecheck:contract": "tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution bundler __tests__/create-oui.compile.test-d.ts"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
@@ -85,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"