oui-spec 0.1.0

package/dist/transport/index.d.ts

@@ -0,0 +1,91 @@
+import { 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
+ *
+ * NO request/response. NO correlation IDs. NO waiting.
+ * The Lambda dispatches and terminates. The browser processes and pushes state.
+ */
+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) */
+    onAction(handler: OUIActionHandler): () => 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(): void;
+    onConnectionChange(handler: (connected: boolean) => void): () => void;
+}
+/** Handler for incoming action dispatches (client side) */
+type OUIActionHandler = (surfaceId: string, actionId: string, params: Record<string, unknown>) => 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 dispatches 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 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)
+ */
+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;
+}
+
+/**
+ * Direct transport — for same-process communication.
+ * Used for API surfaces (where the agent runtime and surface are in the same Lambda)
+ * and for testing (where you want synchronous, in-memory communication).
+ *
+ * Creates a paired (server, client) transport where messages sent on one
+ * side are immediately received on the other.
+ */
+declare function createDirectTransportPair(): {
+    server: OUITransport;
+    client: OUITransport;
+};
+
+export { type OUIActionHandler, type OUIObservationHandler, type OUITransport, type OUITransportConfig, type SocketLike, createDirectTransportPair, createWebSocketTransport };

package/dist/transport/index.js

@@ -0,0 +1,3 @@
+export { createDirectTransportPair, createWebSocketTransport } from '../chunk-7EXSMPGR.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/transport/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "oui-spec",
+  "version": "0.1.0",
+  "description": "OUI — The OpenUI Specification. A machine-readable contract for agent-controllable user interfaces.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./spec": {
+      "types": "./dist/spec/index.d.ts",
+      "import": "./dist/spec/index.js",
+      "require": "./dist/spec/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "require": "./dist/core/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.cjs"
+    },
+    "./transport": {
+      "types": "./dist/transport/index.d.ts",
+      "import": "./dist/transport/index.js",
+      "require": "./dist/transport/index.cjs"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "spec": [
+        "dist/spec/index.d.ts"
+      ],
+      "core": [
+        "dist/core/index.d.ts"
+      ],
+      "react": [
+        "dist/react/index.d.ts"
+      ],
+      "transport": [
+        "dist/transport/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "spec"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wesreid/oui.git"
+  },
+  "keywords": [
+    "oui",
+    "openui",
+    "ai",
+    "agent",
+    "ui",
+    "specification",
+    "protocol"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepare": "husky",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.9.6",
+    "react": "^19.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md}": [
+      "prettier --write"
+    ]
+  }
+}