oui-spec 0.4.1 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationSnapshot, OUIObservationUpdate, OUIProtocolEvent, OUISurface, OUISurfaceDeregistration, OUISurfaceRegistration, OUISurfaceSnapshot, OUI_PROTOCOL_EVENTS } from './spec/index.js';
-export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, D as DefinedSurface, M as MountedSurface, O as OUIBranded, c as ObservationDefinition, S as SettleOptions, d as SurfaceDefinition, e as SurfaceRuntime, f as SurfaceRuntimeOptions, g as createSurfaceRuntime, h as defineSurface } from './surface-runtime-DeByfbKg.js';
+export { ARGS_HASH_PATTERN, JSONSchema, OUIAction, OUIActionApproval, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIApprovalGrant, OUIEffectKind, OUIObservation, OUIObservationSnapshot, OUIObservationUpdate, OUIProtocolEvent, OUISurface, OUISurfaceDeregistration, OUISurfaceRegistration, OUISurfaceSnapshot, OUI_EFFECT_ACCESS, OUI_EFFECT_KINDS, OUI_PROTOCOL_EVENTS, argsHash, canonicalJson, effectAccess, requiresApproval } from './spec/index.js';
+export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, D as DefinedSurface, M as MountedSurface, O as OUIBranded, c as ObservationDefinition, S as SettleOptions, d as SurfaceDefinition, e as SurfaceRuntime, f as SurfaceRuntimeOptions, g as createSurfaceRuntime, h as defineSurface } from './surface-runtime-CS0rByFQ.js';
 export { DuplicateIds, OUIConfig, OUIConfigError, OUIInstance, OwnedTransport, ValidateSurfaceIds, createOUI } from './core/index.js';
 export { SurfaceRuntimeProvider, SurfaceRuntimeProviderProps, UseSurfaceOptions, UseSurfaceResult, useObservation, useSurface, useSurfaceHold, useSurfaceRuntime } from './react/index.js';
 export { O as OUIActionHandler, a as OUIObservationHandler, b as OUIResultHandler, c as OUITransport, d as OUITransportConfig, S as SocketLike, e as createWebSocketTransport } from './websocket-c5tIUWY5.js';

package/dist/index.js

@@ -1,7 +1,7 @@
-export { createOUI, createSurfaceRuntime, defineSurface } from './chunk-UQLG55ST.js';
-export { OUI_PROTOCOL_EVENTS } from './chunk-BMCL2K74.js';
+export { createOUI, createSurfaceRuntime, defineSurface } from './chunk-6ZIKO7MG.js';
+export { ARGS_HASH_PATTERN, OUI_EFFECT_ACCESS, OUI_EFFECT_KINDS, OUI_PROTOCOL_EVENTS, argsHash, canonicalJson, effectAccess, requiresApproval } from './chunk-BNGJJM3T.js';
 export { SurfaceRuntimeProvider, useObservation, useSurface, useSurfaceHold, useSurfaceRuntime } from './chunk-NYCJZQSP.js';
 export { createDirectTransportPair } from './chunk-IIZ6HL2L.js';
-export { createWebSocketTransport } from './chunk-F3WKIRAU.js';
+export { createWebSocketTransport } from './chunk-UKKITNZK.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/react/index.d.cts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { OUIActionResult } from '../spec/index.cjs';
-import { e as SurfaceRuntime, D as DefinedSurface } from '../surface-runtime-BzIKgL_I.cjs';
+import { e as SurfaceRuntime, D as DefinedSurface } from '../surface-runtime-lqXn221P.cjs';
 import '../websocket-YfWILdZ4.cjs';
 
 interface SurfaceRuntimeProviderProps {

package/dist/react/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { OUIActionResult } from '../spec/index.js';
-import { e as SurfaceRuntime, D as DefinedSurface } from '../surface-runtime-DeByfbKg.js';
+import { e as SurfaceRuntime, D as DefinedSurface } from '../surface-runtime-CS0rByFQ.js';
 import '../websocket-c5tIUWY5.js';
 
 interface SurfaceRuntimeProviderProps {

package/dist/spec/index.cjs

@@ -1,12 +1,40 @@
 'use strict';
 
-var chunkZKM4XWAB_cjs = require('../chunk-ZKM4XWAB.cjs');
+var chunk2AISUNMW_cjs = require('../chunk-2AISUNMW.cjs');
 
 
 
+Object.defineProperty(exports, "ARGS_HASH_PATTERN", {
+  enumerable: true,
+  get: function () { return chunk2AISUNMW_cjs.ARGS_HASH_PATTERN; }
+});
+Object.defineProperty(exports, "OUI_EFFECT_ACCESS", {
+  enumerable: true,
+  get: function () { return chunk2AISUNMW_cjs.OUI_EFFECT_ACCESS; }
+});
+Object.defineProperty(exports, "OUI_EFFECT_KINDS", {
+  enumerable: true,
+  get: function () { return chunk2AISUNMW_cjs.OUI_EFFECT_KINDS; }
+});
 Object.defineProperty(exports, "OUI_PROTOCOL_EVENTS", {
   enumerable: true,
-  get: function () { return chunkZKM4XWAB_cjs.OUI_PROTOCOL_EVENTS; }
+  get: function () { return chunk2AISUNMW_cjs.OUI_PROTOCOL_EVENTS; }
+});
+Object.defineProperty(exports, "argsHash", {
+  enumerable: true,
+  get: function () { return chunk2AISUNMW_cjs.argsHash; }
+});
+Object.defineProperty(exports, "canonicalJson", {
+  enumerable: true,
+  get: function () { return chunk2AISUNMW_cjs.canonicalJson; }
+});
+Object.defineProperty(exports, "effectAccess", {
+  enumerable: true,
+  get: function () { return chunk2AISUNMW_cjs.effectAccess; }
+});
+Object.defineProperty(exports, "requiresApproval", {
+  enumerable: true,
+  get: function () { return chunk2AISUNMW_cjs.requiresApproval; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/spec/index.d.cts

@@ -1,3 +1,74 @@
+/**
+ * Approvals: an irreversible action runs only on an approval the user gave,
+ * bound to the exact request.
+ *
+ * An agent runtime stops at an action that needs approval and shows the user
+ * a confirmation. Its approval store issues a single-use grant when the user
+ * confirms, and the request that then reaches the tab carries `approval:
+ * { approvalId, argsHash }`. The surface runtime runs the action only when
+ * that matches a grant this tab received from the user's own confirmation.
+ *
+ * Everything that checks a request computes the same args hash: SHA-256 over
+ * the RFC 8785 (JCS) canonical JSON of its params, lowercase hex. The
+ * published vectors (`oui-spec/approval-vectors.json`) hold every
+ * implementation, in any language, to it.
+ */
+/**
+ * What using an action does. One vocabulary for every kind of action, so an
+ * action is told apart by what it changes:
+ *
+ * | Effect | What it changes | Access |
+ * |---|---|---|
+ * | `view`, `selection`, `navigate`, `open` | What is shown | read |
+ * | `edit` | The document, one undo step | write |
+ * | `file` | Imports or exports a file | write |
+ * | `mutate` | Backend data, through an API operation | write |
+ * | `job` | Starts work that outlives the call | write |
+ * | `transaction` | An irreversible external act: an order, a payment, a send, a publish | write, approved |
+ */
+type OUIEffectKind = "view" | "selection" | "navigate" | "open" | "edit" | "file" | "mutate" | "job" | "transaction";
+/** Every effect, in the order of the table above. */
+declare const OUI_EFFECT_KINDS: readonly OUIEffectKind[];
+/** Whether an effect only changes what is shown, or changes something. */
+declare const OUI_EFFECT_ACCESS: Readonly<Record<OUIEffectKind, "read" | "write">>;
+/** `read` or `write`. An action that declares no effect is a `write`: nothing says it only shows. */
+declare function effectAccess(effect: OUIEffectKind | undefined): "read" | "write";
+/**
+ * Whether running an action needs the user's approval of the exact request: a
+ * `transaction` always, and a `write` declared destructive. An agent
+ * runtime's policy may require it of more; nothing waives these.
+ */
+declare function requiresApproval(effect: OUIEffectKind | undefined, destructive?: boolean): boolean;
+/** What a request for an approved action carries. */
+interface OUIActionApproval {
+    approvalId: string;
+    /** `argsHash(params)` of the request the user approved. */
+    argsHash: string;
+}
+/** A grant this tab holds: the user approved this request here. */
+interface OUIApprovalGrant extends OUIActionApproval {
+    /** Epoch ms after which the grant no longer admits anything. */
+    expiresAt: number;
+}
+/** An args hash: 64 lowercase hex digits. */
+declare const ARGS_HASH_PATTERN: RegExp;
+/**
+ * The RFC 8785 canonical form of a JSON value:
+ * - object members sorted by their names' UTF-16 code units, with no
+ *   whitespace;
+ * - numbers in ECMAScript's shortest round-trip form (`-0` is `0`);
+ * - strings escaped as ECMAScript's `JSON.stringify` escapes them.
+ *
+ * The value must be I-JSON (RFC 7493): anything JSON cannot carry — `NaN`,
+ * infinities, `undefined` outside an object member, a bigint, a function, a
+ * symbol, a class instance, or a string with a lone surrogate — is refused
+ * rather than hashed as something the other end never receives. An object
+ * member whose value is `undefined` is left out, as it is on the wire.
+ */
+declare function canonicalJson(value: unknown): string;
+/** SHA-256 of the canonical JSON of a request's params, lowercase hex. Runs wherever WebCrypto does. */
+declare function argsHash(params: unknown): Promise<string>;
+
 /**
  * OUI — Open UI Specification
  *
@@ -92,11 +163,23 @@ interface OUIAction {
     id: string;
     /** Human-readable description — this is what the LLM reads to decide when to use it */
     description: string;
+    /** The action's name as a person reads it, for a confirmation the user approves. */
+    title?: string;
+    /**
+     * What using the action does. A `transaction` runs only on the user's
+     * approval of the exact request (see `requiresApproval`). Undeclared counts
+     * as a write.
+     */
+    effect?: OUIEffectKind;
     /** JSON Schema for the action's input parameters */
     input: JSONSchema;
     /** JSON Schema for the action's return value (optional — agent still gets the result) */
     output?: JSONSchema;
-    /** If true, the agent runtime should confirm with the user before executing */
+    /**
+     * Destructive: the action removes or replaces something the person made.
+     * Unless its effect only reads, it runs only on the user's approval of the
+     * exact request, which the surface runtime checks before it runs.
+     */
     confirm?: boolean;
     /** If true, the action is async — returns immediately with a job/tracking ID */
     async?: boolean;
@@ -159,6 +242,12 @@ interface OUIActionRequest {
     params: Record<string, unknown>;
     /** Timestamp of the request */
     timestamp: number;
+    /**
+     * The user's approval this request runs on, for an action that needs one.
+     * The surface runtime runs such an action only when this matches a grant
+     * the tab received from the user's own confirmation, for exactly `params`.
+     */
+    approval?: OUIActionApproval;
 }
 /**
  * The result of an action execution, returned from the surface to the agent.
@@ -274,4 +363,4 @@ declare const OUI_PROTOCOL_EVENTS: {
     readonly OBSERVATION_UPDATE: "observation:update";
 };
 
-export { type JSONSchema, type OUIAction, type OUIActionPolling, type OUIActionRequest, type OUIActionResult, type OUIActivation, type OUIObservation, type OUIObservationSnapshot, type OUIObservationUpdate, type OUIProtocolEvent, type OUISurface, type OUISurfaceDeregistration, type OUISurfaceRegistration, type OUISurfaceSnapshot, OUI_PROTOCOL_EVENTS };
+export { ARGS_HASH_PATTERN, type JSONSchema, type OUIAction, type OUIActionApproval, type OUIActionPolling, type OUIActionRequest, type OUIActionResult, type OUIActivation, type OUIApprovalGrant, type OUIEffectKind, type OUIObservation, type OUIObservationSnapshot, type OUIObservationUpdate, type OUIProtocolEvent, type OUISurface, type OUISurfaceDeregistration, type OUISurfaceRegistration, type OUISurfaceSnapshot, OUI_EFFECT_ACCESS, OUI_EFFECT_KINDS, OUI_PROTOCOL_EVENTS, argsHash, canonicalJson, effectAccess, requiresApproval };

package/dist/spec/index.d.ts

@@ -1,3 +1,74 @@
+/**
+ * Approvals: an irreversible action runs only on an approval the user gave,
+ * bound to the exact request.
+ *
+ * An agent runtime stops at an action that needs approval and shows the user
+ * a confirmation. Its approval store issues a single-use grant when the user
+ * confirms, and the request that then reaches the tab carries `approval:
+ * { approvalId, argsHash }`. The surface runtime runs the action only when
+ * that matches a grant this tab received from the user's own confirmation.
+ *
+ * Everything that checks a request computes the same args hash: SHA-256 over
+ * the RFC 8785 (JCS) canonical JSON of its params, lowercase hex. The
+ * published vectors (`oui-spec/approval-vectors.json`) hold every
+ * implementation, in any language, to it.
+ */
+/**
+ * What using an action does. One vocabulary for every kind of action, so an
+ * action is told apart by what it changes:
+ *
+ * | Effect | What it changes | Access |
+ * |---|---|---|
+ * | `view`, `selection`, `navigate`, `open` | What is shown | read |
+ * | `edit` | The document, one undo step | write |
+ * | `file` | Imports or exports a file | write |
+ * | `mutate` | Backend data, through an API operation | write |
+ * | `job` | Starts work that outlives the call | write |
+ * | `transaction` | An irreversible external act: an order, a payment, a send, a publish | write, approved |
+ */
+type OUIEffectKind = "view" | "selection" | "navigate" | "open" | "edit" | "file" | "mutate" | "job" | "transaction";
+/** Every effect, in the order of the table above. */
+declare const OUI_EFFECT_KINDS: readonly OUIEffectKind[];
+/** Whether an effect only changes what is shown, or changes something. */
+declare const OUI_EFFECT_ACCESS: Readonly<Record<OUIEffectKind, "read" | "write">>;
+/** `read` or `write`. An action that declares no effect is a `write`: nothing says it only shows. */
+declare function effectAccess(effect: OUIEffectKind | undefined): "read" | "write";
+/**
+ * Whether running an action needs the user's approval of the exact request: a
+ * `transaction` always, and a `write` declared destructive. An agent
+ * runtime's policy may require it of more; nothing waives these.
+ */
+declare function requiresApproval(effect: OUIEffectKind | undefined, destructive?: boolean): boolean;
+/** What a request for an approved action carries. */
+interface OUIActionApproval {
+    approvalId: string;
+    /** `argsHash(params)` of the request the user approved. */
+    argsHash: string;
+}
+/** A grant this tab holds: the user approved this request here. */
+interface OUIApprovalGrant extends OUIActionApproval {
+    /** Epoch ms after which the grant no longer admits anything. */
+    expiresAt: number;
+}
+/** An args hash: 64 lowercase hex digits. */
+declare const ARGS_HASH_PATTERN: RegExp;
+/**
+ * The RFC 8785 canonical form of a JSON value:
+ * - object members sorted by their names' UTF-16 code units, with no
+ *   whitespace;
+ * - numbers in ECMAScript's shortest round-trip form (`-0` is `0`);
+ * - strings escaped as ECMAScript's `JSON.stringify` escapes them.
+ *
+ * The value must be I-JSON (RFC 7493): anything JSON cannot carry — `NaN`,
+ * infinities, `undefined` outside an object member, a bigint, a function, a
+ * symbol, a class instance, or a string with a lone surrogate — is refused
+ * rather than hashed as something the other end never receives. An object
+ * member whose value is `undefined` is left out, as it is on the wire.
+ */
+declare function canonicalJson(value: unknown): string;
+/** SHA-256 of the canonical JSON of a request's params, lowercase hex. Runs wherever WebCrypto does. */
+declare function argsHash(params: unknown): Promise<string>;
+
 /**
  * OUI — Open UI Specification
  *
@@ -92,11 +163,23 @@ interface OUIAction {
     id: string;
     /** Human-readable description — this is what the LLM reads to decide when to use it */
     description: string;
+    /** The action's name as a person reads it, for a confirmation the user approves. */
+    title?: string;
+    /**
+     * What using the action does. A `transaction` runs only on the user's
+     * approval of the exact request (see `requiresApproval`). Undeclared counts
+     * as a write.
+     */
+    effect?: OUIEffectKind;
     /** JSON Schema for the action's input parameters */
     input: JSONSchema;
     /** JSON Schema for the action's return value (optional — agent still gets the result) */
     output?: JSONSchema;
-    /** If true, the agent runtime should confirm with the user before executing */
+    /**
+     * Destructive: the action removes or replaces something the person made.
+     * Unless its effect only reads, it runs only on the user's approval of the
+     * exact request, which the surface runtime checks before it runs.
+     */
     confirm?: boolean;
     /** If true, the action is async — returns immediately with a job/tracking ID */
     async?: boolean;
@@ -159,6 +242,12 @@ interface OUIActionRequest {
     params: Record<string, unknown>;
     /** Timestamp of the request */
     timestamp: number;
+    /**
+     * The user's approval this request runs on, for an action that needs one.
+     * The surface runtime runs such an action only when this matches a grant
+     * the tab received from the user's own confirmation, for exactly `params`.
+     */
+    approval?: OUIActionApproval;
 }
 /**
  * The result of an action execution, returned from the surface to the agent.
@@ -274,4 +363,4 @@ declare const OUI_PROTOCOL_EVENTS: {
     readonly OBSERVATION_UPDATE: "observation:update";
 };
 
-export { type JSONSchema, type OUIAction, type OUIActionPolling, type OUIActionRequest, type OUIActionResult, type OUIActivation, type OUIObservation, type OUIObservationSnapshot, type OUIObservationUpdate, type OUIProtocolEvent, type OUISurface, type OUISurfaceDeregistration, type OUISurfaceRegistration, type OUISurfaceSnapshot, OUI_PROTOCOL_EVENTS };
+export { ARGS_HASH_PATTERN, type JSONSchema, type OUIAction, type OUIActionApproval, type OUIActionPolling, type OUIActionRequest, type OUIActionResult, type OUIActivation, type OUIApprovalGrant, type OUIEffectKind, type OUIObservation, type OUIObservationSnapshot, type OUIObservationUpdate, type OUIProtocolEvent, type OUISurface, type OUISurfaceDeregistration, type OUISurfaceRegistration, type OUISurfaceSnapshot, OUI_EFFECT_ACCESS, OUI_EFFECT_KINDS, OUI_PROTOCOL_EVENTS, argsHash, canonicalJson, effectAccess, requiresApproval };

package/dist/spec/index.js

@@ -1,3 +1,3 @@
-export { OUI_PROTOCOL_EVENTS } from '../chunk-BMCL2K74.js';
+export { ARGS_HASH_PATTERN, OUI_EFFECT_ACCESS, OUI_EFFECT_KINDS, OUI_PROTOCOL_EVENTS, argsHash, canonicalJson, effectAccess, requiresApproval } from '../chunk-BNGJJM3T.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{surface-runtime-DeByfbKg.d.ts → surface-runtime-CS0rByFQ.d.ts}

@@ -1,4 +1,4 @@
-import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult } from './spec/index.js';
+import { OUIEffectKind, JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult, OUIApprovalGrant } from './spec/index.js';
 import { S as SocketLike, d as OUITransportConfig } from './websocket-c5tIUWY5.js';
 
 /**
@@ -61,8 +61,13 @@ interface ActionPollingConfig<TContext = unknown> extends OUIActionPolling {
 interface ActionDefinition<TContext = unknown> {
     id: string;
     description: string;
+    /** Its name as a person reads it, for a confirmation the user approves. */
+    title?: string;
+    /** What using it does; a `transaction` runs only on the user's approval of the exact request. */
+    effect?: OUIEffectKind;
     input: JSONSchema;
     output?: JSONSchema;
+    /** Destructive: it runs only on the user's approval of the exact request, unless it only reads. */
     confirm?: boolean;
     async?: boolean;
     /**
@@ -241,6 +246,14 @@ interface SurfaceRuntime {
      * code still loading or a page fetching the data it will display.
      */
     hold(): () => void;
+    /**
+     * Record that the user approved one request, here, through their own
+     * confirmation (the agent runtime's approval store answered it to this tab).
+     * An action that needs approval — a `transaction`, or a destructive write —
+     * runs only on a request whose `approval` matches an unused, unexpired grant
+     * for exactly its params. Each grant admits one request.
+     */
+    grantApproval(grant: OUIApprovalGrant): void;
     /** Called whenever the snapshot changes. */
     subscribe(listener: () => void): () => void;
     /** Stop polling, detach from the socket and forget every mount. */

package/dist/{surface-runtime-BzIKgL_I.d.cts → surface-runtime-lqXn221P.d.cts}

@@ -1,4 +1,4 @@
-import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult } from './spec/index.cjs';
+import { OUIEffectKind, JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult, OUIApprovalGrant } from './spec/index.cjs';
 import { S as SocketLike, d as OUITransportConfig } from './websocket-YfWILdZ4.cjs';
 
 /**
@@ -61,8 +61,13 @@ interface ActionPollingConfig<TContext = unknown> extends OUIActionPolling {
 interface ActionDefinition<TContext = unknown> {
     id: string;
     description: string;
+    /** Its name as a person reads it, for a confirmation the user approves. */
+    title?: string;
+    /** What using it does; a `transaction` runs only on the user's approval of the exact request. */
+    effect?: OUIEffectKind;
     input: JSONSchema;
     output?: JSONSchema;
+    /** Destructive: it runs only on the user's approval of the exact request, unless it only reads. */
     confirm?: boolean;
     async?: boolean;
     /**
@@ -241,6 +246,14 @@ interface SurfaceRuntime {
      * code still loading or a page fetching the data it will display.
      */
     hold(): () => void;
+    /**
+     * Record that the user approved one request, here, through their own
+     * confirmation (the agent runtime's approval store answered it to this tab).
+     * An action that needs approval — a `transaction`, or a destructive write —
+     * runs only on a request whose `approval` matches an unused, unexpired grant
+     * for exactly its params. Each grant admits one request.
+     */
+    grantApproval(grant: OUIApprovalGrant): void;
     /** Called whenever the snapshot changes. */
     subscribe(listener: () => void): () => void;
     /** Stop polling, detach from the socket and forget every mount. */

package/dist/transport/index.cjs

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

package/dist/transport/index.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oui-spec",
-  "version": "0.4.1",
-  "description": "OUI — The OpenUI Specification. A machine-readable contract for agent-controllable user interfaces.",
+  "version": "0.5.0",
+  "description": "OUI \u2014 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",
@@ -30,7 +30,8 @@
       "types": "./dist/transport/index.d.ts",
       "import": "./dist/transport/index.js",
       "require": "./dist/transport/index.cjs"
-    }
+    },
+    "./approval-vectors.json": "./spec/approval-vectors.json"
   },
   "typesVersions": {
     "*": {

package/spec/approval-vectors.json

@@ -0,0 +1,88 @@
+{
+  "version": 1,
+  "algorithm": "SHA-256 over the RFC 8785 (JCS) canonical JSON of the value, UTF-8 encoded; lowercase hex",
+  "use": "The approval args hash. Every implementation (an agent runtime, an approval store, the browser runtime, a gateway in another language) parses each `json`, canonicalizes it to exactly `canonical`, and hashes it to exactly `sha256`; it refuses every `invalid` input.",
+  "provenance": "Canonical forms derived by hand from RFC 8785 §3.2 and Appendix B; hashes computed with Python hashlib over those forms, independently of any implementation under test.",
+  "vectors": [
+    {
+      "name": "key order",
+      "json": "{\"b\":2,\"a\":1,\"c\":{\"z\":true,\"y\":null,\"x\":[3,2,1]}}",
+      "canonical": "{\"a\":1,\"b\":2,\"c\":{\"x\":[3,2,1],\"y\":null,\"z\":true}}",
+      "sha256": "a3e834099e840d9028fa0c005d117ffd5ae99f8275223ae3b64121241290958d"
+    },
+    {
+      "name": "key order by UTF-16 code units, not code points (RFC 8785 §3.2.3)",
+      "json": "{\"\\u20ac\":\"Euro Sign\",\"\\r\":\"Carriage Return\",\"\\ufb33\":\"Hebrew Letter Dalet With Dagesh\",\"1\":\"One\",\"\\ud83d\\ude00\":\"Emoji: Grinning Face\",\"\\u0080\":\"Control\",\"\\u00f6\":\"Latin Small Letter O With Diaeresis\"}",
+      "canonical": "{\"\\r\":\"Carriage Return\",\"1\":\"One\",\"€\":\"Control\",\"ö\":\"Latin Small Letter O With Diaeresis\",\"€\":\"Euro Sign\",\"😀\":\"Emoji: Grinning Face\",\"דּ\":\"Hebrew Letter Dalet With Dagesh\"}",
+      "sha256": "5e321556d22018a9656991a9e94f77ec175fa193e52a2429d312f8419ec8b08c"
+    },
+    {
+      "name": "key order with digits, capitals and underscore",
+      "json": "{\"aa\":1,\"a\":2,\"b\":3,\"A\":4,\"_\":5,\"10\":6,\"9\":7}",
+      "canonical": "{\"10\":6,\"9\":7,\"A\":4,\"_\":5,\"a\":2,\"aa\":1,\"b\":3}",
+      "sha256": "e395d6cbc8557fd7b4e4dd42af7c48c30fb4d5ec7da43567ccf39bc322ff9804"
+    },
+    {
+      "name": "RFC 8785 §3.2.2 example: numbers, string escapes, literals",
+      "json": "{\"numbers\":[333333333.33333329,1E30,4.50,2e-3,0.000000000000000000000000001],\"string\":\"\\u20ac$\\u000F\\u000aA'\\u0042\\u0022\\u005c\\\\\\\"\\/\",\"literals\":[null,true,false]}",
+      "canonical": "{\"literals\":[null,true,false],\"numbers\":[333333333.3333333,1e+30,4.5,0.002,1e-27],\"string\":\"€$\\u000f\\nA'B\\\"\\\\\\\\\\\"/\"}",
+      "sha256": "2d5e01a318d0f0879ab568c4be289c8b1f64ef8921a53c6277d5e069978baacb"
+    },
+    {
+      "name": "numbers: RFC 8785 Appendix B and ECMAScript formatting",
+      "json": "[0,-0,5e-324,-5e-324,1.7976931348623157e308,9007199254740992,1e21,999999999999999900000,0.000001,9.999999999999997e-7,1e-7,100,1.5,-1.5,123456789012345680000,1E2,0.1,-0.0000123]",
+      "canonical": "[0,0,5e-324,-5e-324,1.7976931348623157e+308,9007199254740992,1e+21,999999999999999900000,0.000001,9.999999999999997e-7,1e-7,100,1.5,-1.5,123456789012345680000,100,0.1,-0.0000123]",
+      "sha256": "6f4a14dff8d80f1da955de6c0dc2099dd8a65c8538b4cbcabf4dbf92323832d6"
+    },
+    {
+      "name": "nested arrays",
+      "json": "{\"a\":[[],[[]],[1,[2,[3,{}]]],[{\"b\":[],\"a\":{}}]]}",
+      "canonical": "{\"a\":[[],[[]],[1,[2,[3,{}]]],[{\"a\":{},\"b\":[]}]]}",
+      "sha256": "f5cb025d9d4301d5b460a2919d5d5c21856faef0fba5a987555d8be6e36cfc1a"
+    },
+    {
+      "name": "empty object",
+      "json": "{}",
+      "canonical": "{}",
+      "sha256": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
+    },
+    {
+      "name": "empty members",
+      "json": "{ \"c\" : \"\", \"b\" : [ ], \"a\" : { } }",
+      "canonical": "{\"a\":{},\"b\":[],\"c\":\"\"}",
+      "sha256": "e052004170cc85d084722ffe760c499548014bfdbdf5275548b688255770dfc2"
+    },
+    {
+      "name": "Unicode and control characters in strings",
+      "json": "{\"s\":\"line1\\nline2\\ttab \\u0000 \\u001f \\u007f \\u2028 \\b\\f\\r é 中文 \\ud83d\\ude00 \\\"q\\\" \\\\ \\/\"}",
+      "canonical": "{\"s\":\"line1\\nline2\\ttab \\u0000 \\u001f  
 \\b\\f\\r é 中文 😀 \\\"q\\\" \\\\ /\"}",
+      "sha256": "0704f4e91b2358f88126313e3d01b58887d0222527f54a365f7c47284701f77b"
+    },
+    {
+      "name": "a tool call's arguments",
+      "json": "{\"to\":\"cfo@desk.example\",\"reportId\":\"q3-2026\",\"amount\":1250.5,\"lines\":[{\"sku\":\"A-1\",\"qty\":2},{\"qty\":1,\"sku\":\"B-7\"}],\"note\":null,\"urgent\":false}",
+      "canonical": "{\"amount\":1250.5,\"lines\":[{\"qty\":2,\"sku\":\"A-1\"},{\"qty\":1,\"sku\":\"B-7\"}],\"note\":null,\"reportId\":\"q3-2026\",\"to\":\"cfo@desk.example\",\"urgent\":false}",
+      "sha256": "9fca331ee3441ff41fb72daf559bb93cb062624683e896fad0ba11f1ebfa39b3"
+    },
+    {
+      "name": "an order",
+      "json": "{\"side\":\"buy\",\"symbol\":\"ACME\",\"quantity\":100,\"limitPrice\":12.34,\"timeInForce\":\"day\"}",
+      "canonical": "{\"limitPrice\":12.34,\"quantity\":100,\"side\":\"buy\",\"symbol\":\"ACME\",\"timeInForce\":\"day\"}",
+      "sha256": "95d63838fb17517676ce7070891709fc5fdb1bc21bd378f44f20aa1e463d7024"
+    }
+  ],
+  "invalid": [
+    {
+      "name": "a lone high surrogate",
+      "json": "{\"s\":\"\\ud800\"}"
+    },
+    {
+      "name": "a lone low surrogate",
+      "json": "{\"s\":\"a\\udc00b\"}"
+    },
+    {
+      "name": "a lone surrogate in a key",
+      "json": "{\"\\udbff\":1}"
+    }
+  ]
+}

package/dist/chunk-BMCL2K74.js

@@ -1,12 +0,0 @@
-// src/spec/types.ts
-var OUI_PROTOCOL_EVENTS = {
-  SURFACE_REGISTER: "surface:register",
-  SURFACE_DEREGISTER: "surface:deregister",
-  ACTION_REQUEST: "action:request",
-  ACTION_RESULT: "action:result",
-  OBSERVATION_UPDATE: "observation:update"
-};
-
-export { OUI_PROTOCOL_EVENTS };
-//# sourceMappingURL=chunk-BMCL2K74.js.map
-//# sourceMappingURL=chunk-BMCL2K74.js.map

package/dist/chunk-BMCL2K74.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/spec/types.ts"],"names":[],"mappings":";AAiUO,IAAM,mBAAA,GAAsB;AAAA,EACjC,gBAAA,EAAkB,kBAAA;AAAA,EAClB,kBAAA,EAAoB,oBAAA;AAAA,EACpB,cAAA,EAAgB,gBAAA;AAAA,EAChB,aAAA,EAAe,eAAA;AAAA,EACf,kBAAA,EAAoB;AACtB","file":"chunk-BMCL2K74.js","sourcesContent":["/**\n * OUI — Open UI Specification\n *\n * The machine-readable contract for agent-controllable user interfaces.\n * Any UI application that implements this interface can be controlled by\n * any OUI-compatible agent runtime.\n */\n\n/** JSON Schema type (subset used by OUI) */\nexport type JSONSchema = {\n  type?: string | string[];\n  properties?: Record<string, JSONSchema>;\n  items?: JSONSchema;\n  required?: string[];\n  enum?: (string | number | boolean)[];\n  description?: string;\n  default?: unknown;\n  oneOf?: JSONSchema[];\n  anyOf?: JSONSchema[];\n  allOf?: JSONSchema[];\n  const?: unknown;\n  minimum?: number;\n  maximum?: number;\n  minLength?: number;\n  maxLength?: number;\n  pattern?: string;\n  format?: string;\n  additionalProperties?: boolean | JSONSchema;\n};\n\n/**\n * A Surface is a controllable boundary within an application.\n * It declares what an agent can do (actions), what it can observe (state),\n * and when it's available (activation conditions).\n *\n * Think of it as \"one page\" or \"one feature\" of an application, described\n * in a way that an agent can understand and operate.\n */\nexport interface OUISurface {\n  /** Unique identifier for this surface (e.g., 'dataviz-wizard', 'document-editor') */\n  id: string;\n\n  /** Human-readable name */\n  name: string;\n\n  /** Description of what this surface does — included in agent context */\n  description: string;\n\n  /** Version of this surface's contract (semver) */\n  version?: string;\n\n  /** Actions the agent can invoke on this surface */\n  actions: OUIAction[];\n\n  /** Observable state the agent can read */\n  observations?: OUIObservation[];\n\n  /** When this surface is active/available */\n  activation?: OUIActivation;\n\n  /** Additional metadata for agent context */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Declarative polling configuration for async actions.\n * The OUI runtime in the browser manages the polling lifecycle automatically\n * after the action handler returns its dispatch result.\n */\nexport interface OUIActionPolling {\n  /** How often to check (milliseconds) */\n  intervalMs: number;\n\n  /** Max poll attempts before giving up (optional) */\n  maxAttempts?: number;\n\n  /** Max total duration before giving up in ms (alternative to maxAttempts) */\n  maxDurationMs?: number;\n\n  /**\n   * Subscribe to a realtime event instead of polling.\n   * If provided, the runtime listens for this event instead of using setInterval.\n   * More efficient when realtime infrastructure exists.\n   */\n  subscribe?: {\n    /** Event name to listen for */\n    event: string;\n    /**\n     * Filter to match the event. Values prefixed with '$dispatchResult.'\n     * are resolved from the handler's return value.\n     * Example: { jobId: '$dispatchResult.jobId' }\n     */\n    filter?: Record<string, unknown>;\n  };\n}\n\n/**\n * An Action is a single operation an agent can perform on a surface.\n * Each action becomes a \"tool\" that the LLM can call.\n *\n * The action's handler executes in the UI (or API) and returns a result\n * that the agent sees as the tool's output.\n */\nexport interface OUIAction {\n  /** Unique action identifier (becomes the tool name) */\n  id: string;\n\n  /** Human-readable description — this is what the LLM reads to decide when to use it */\n  description: string;\n\n  /** JSON Schema for the action's input parameters */\n  input: JSONSchema;\n\n  /** JSON Schema for the action's return value (optional — agent still gets the result) */\n  output?: JSONSchema;\n\n  /** If true, the agent runtime should confirm with the user before executing */\n  confirm?: boolean;\n\n  /** If true, the action is async — returns immediately with a job/tracking ID */\n  async?: boolean;\n\n  /** Declarative polling configuration — runtime manages the polling lifecycle after dispatch */\n  polling?: OUIActionPolling;\n\n  /** Human-readable hint about when this action is appropriate to use */\n  usage?: string;\n\n  /**\n   * Preconditions that should be met before this action is called.\n   * Expressed as a description (for the LLM) not as executable logic.\n   */\n  preconditions?: string;\n\n  /** Estimated duration hint (e.g., \"instant\", \"2-5s\", \"30-120s\") */\n  estimatedDuration?: string;\n\n  /** Tags for categorization */\n  tags?: string[];\n}\n\n/**\n * An Observation is a piece of application state that the agent can read.\n * Observations are pushed to the agent in real-time as the app state changes,\n * giving it situational awareness without needing screenshots.\n */\nexport interface OUIObservation {\n  /** Unique identifier for this observation */\n  id: string;\n\n  /** Description of what this observation represents */\n  description: string;\n\n  /** JSON Schema for the observation's value */\n  schema: JSONSchema;\n\n  /** How frequently this observation updates */\n  updateFrequency?: \"realtime\" | \"on-change\" | \"polling\";\n}\n\n/**\n * Activation conditions — when a surface is available to the agent.\n * A surface might only be active on a specific page, when certain\n * entities are loaded, or under specific application states.\n */\nexport interface OUIActivation {\n  /** URL path(s) where this surface is active */\n  routes?: string | string[];\n\n  /** Entity type/ID that must be present for this surface to activate */\n  entity?: {\n    type: string;\n    id?: string;\n  };\n\n  /** Custom predicate description (for documentation, not execution) */\n  condition?: string;\n}\n\n// ─── Protocol Types ──────────────────────────────────────────────────────────\n\n/**\n * A request from the agent runtime to execute an action on a surface.\n */\nexport interface OUIActionRequest {\n  /** Unique request ID for correlation */\n  requestId: string;\n\n  /** Which surface this request targets */\n  surfaceId: string;\n\n  /** Which action to invoke */\n  actionId: string;\n\n  /** The action's input parameters (validated against the action's input schema) */\n  params: Record<string, unknown>;\n\n  /** Timestamp of the request */\n  timestamp: number;\n}\n\n/**\n * The result of an action execution, returned from the surface to the agent.\n */\nexport interface OUIActionResult {\n  /** Correlates to the request */\n  requestId: string;\n\n  /** Whether the action succeeded */\n  success: boolean;\n\n  /** The action's return data (if successful) */\n  data?: unknown;\n\n  /** Error information (if failed) */\n  error?: {\n    code: string;\n    message: string;\n    details?: unknown;\n  };\n\n  /** Progress indicator for interim polling results (0-100) */\n  progress?: number;\n\n  /** Whether this is an interim update (polling still in progress) or final */\n  interim?: boolean;\n\n  /** Duration of execution in milliseconds */\n  durationMs?: number;\n\n  /** Timestamp of the result */\n  timestamp: number;\n\n  /**\n   * The surfaces active on the client once the action's effects settled.\n   *\n   * An action can change what the agent is able to do next: navigating\n   * unmounts one page's surfaces and mounts another's. Without this, the agent\n   * would act on the capability set it had before the action, which is the\n   * set the action just replaced.\n   */\n  surfaces?: OUISurface[];\n\n  /** Latest observation values per surface once the action's effects settled. */\n  observations?: OUIObservationSnapshot;\n\n  /**\n   * False when the client's deadline passed before its UI settled, so\n   * `surfaces` and `observations` may still be changing. Absent or true\n   * otherwise.\n   */\n  settled?: boolean;\n}\n\n/** Latest observation values, keyed by surface id and then observation id. */\nexport type OUIObservationSnapshot = Record<string, Record<string, unknown>>;\n\n/**\n * What a client can do right now: the surfaces it has mounted and their latest\n * observation values. A client sends this to its agent runtime (for example,\n * with each turn), and returns it on every action result.\n */\nexport interface OUISurfaceSnapshot {\n  surfaces: OUISurface[];\n  observations: OUIObservationSnapshot;\n}\n\n/**\n * An observation update pushed from the surface to the agent.\n */\nexport interface OUIObservationUpdate {\n  /** Which surface this observation belongs to */\n  surfaceId: string;\n\n  /** Which observation updated */\n  observationId: string;\n\n  /** The new value */\n  value: unknown;\n\n  /** Timestamp of the update */\n  timestamp: number;\n}\n\n/**\n * Surface registration event — sent when a surface becomes active.\n */\nexport interface OUISurfaceRegistration {\n  /** The full surface manifest */\n  surface: OUISurface;\n\n  /** Timestamp of registration */\n  timestamp: number;\n}\n\n/**\n * Surface deregistration event — sent when a surface becomes inactive.\n */\nexport interface OUISurfaceDeregistration {\n  /** Which surface is being deregistered */\n  surfaceId: string;\n\n  /** Timestamp */\n  timestamp: number;\n}\n\n// ─── Transport Protocol Events ───────────────────────────────────────────────\n\n/**\n * All protocol events exchanged between agent runtime and surfaces.\n */\nexport type OUIProtocolEvent =\n  | { type: \"surface:register\"; payload: OUISurfaceRegistration }\n  | { type: \"surface:deregister\"; payload: OUISurfaceDeregistration }\n  | { type: \"action:request\"; payload: OUIActionRequest }\n  | { type: \"action:result\"; payload: OUIActionResult }\n  | { type: \"observation:update\"; payload: OUIObservationUpdate };\n\n/**\n * Protocol event type strings (for type guards and routing).\n */\nexport const OUI_PROTOCOL_EVENTS = {\n  SURFACE_REGISTER: \"surface:register\",\n  SURFACE_DEREGISTER: \"surface:deregister\",\n  ACTION_REQUEST: \"action:request\",\n  ACTION_RESULT: \"action:result\",\n  OBSERVATION_UPDATE: \"observation:update\",\n} as const;\n"]}

package/dist/chunk-DCVVTP3V.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/transport/websocket.ts"],"names":[],"mappings":"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","file":"chunk-DCVVTP3V.cjs","sourcesContent":["import type {\n  OUITransport,\n  OUITransportConfig,\n  OUIActionHandler,\n  OUIObservationHandler,\n  OUIResultHandler,\n} from \"./types.js\";\nimport type {\n  OUISurface,\n  OUIObservationUpdate,\n  OUIActionRequest,\n  OUIActionResult,\n} from \"../spec/index.js\";\n\n/**\n * WebSocket transport using Socket.IO.\n * Maps OUI protocol events to socket events with a configurable namespace prefix.\n *\n * Events:\n *   {ns}:dispatch            — action request   (runtime → client)\n *   {ns}:action:result       — action result    (client → runtime)\n *   {ns}:observation         — observation      (client → runtime)\n *   {ns}:surface:register    — registration     (client → runtime)\n *   {ns}:surface:deregister  — deregistration   (client → runtime)\n */\nexport function createWebSocketTransport(\n  socket: SocketLike,\n  config?: OUITransportConfig,\n): OUITransport {\n  const ns = config?.namespace ?? \"oui\";\n  const buffer: Array<{ event: string; data: unknown }> = [];\n  const maxBuffer = config?.maxBufferSize ?? 100;\n  const shouldBuffer = config?.bufferWhileDisconnected ?? true;\n\n  let connected = socket.connected ?? false;\n  const connectionHandlers: Array<(c: boolean) => void> = [];\n\n  // Every listener this transport attaches, so dispose() can remove exactly\n  // these and nothing the integrator attached to the same socket.\n  const attached: Array<{ event: string; handler: (...args: any[]) => void }> =\n    [];\n  function listen(\n    event: string,\n    handler: (...args: any[]) => void,\n  ): () => void {\n    socket.on(event, handler);\n    const entry = { event, handler };\n    attached.push(entry);\n    return () => {\n      socket.off(event, handler);\n      const i = attached.indexOf(entry);\n      if (i >= 0) attached.splice(i, 1);\n    };\n  }\n\n  listen(\"connect\", () => {\n    connected = true;\n    // Flush before announcing: anything queued while offline was sent earlier\n    // than whatever a connection handler is about to send.\n    if (shouldBuffer) {\n      while (buffer.length > 0) {\n        const msg = buffer.shift()!;\n        socket.emit(msg.event, msg.data);\n      }\n    }\n    connectionHandlers.forEach((h) => h(true));\n  });\n\n  listen(\"disconnect\", () => {\n    connected = false;\n    connectionHandlers.forEach((h) => h(false));\n  });\n\n  function emit(event: string, data: unknown) {\n    if (connected) {\n      socket.emit(event, data);\n    } else if (shouldBuffer && buffer.length < maxBuffer) {\n      buffer.push({ event, data });\n    }\n  }\n\n  return {\n    // ─── Dispatch ───────────────────────────────────────────────\n    dispatch(request: OUIActionRequest) {\n      emit(`${ns}:dispatch`, request);\n    },\n\n    onAction(handler: OUIActionHandler) {\n      return listen(\n        `${ns}:dispatch`,\n        (data: Partial<OUIActionRequest> | undefined) => {\n          // A request without a requestId cannot be answered, and answering is\n          // the contract. Refuse it loudly rather than run an action whose\n          // result has nowhere to go.\n          if (\n            !data ||\n            typeof data.requestId !== \"string\" ||\n            !data.requestId ||\n            typeof data.surfaceId !== \"string\" ||\n            typeof data.actionId !== \"string\"\n          ) {\n            console.warn(\n              \"[OUI] Dropped a dispatch without requestId/surfaceId/actionId\",\n              data,\n            );\n            return;\n          }\n          handler({\n            requestId: data.requestId,\n            surfaceId: data.surfaceId,\n            actionId: data.actionId,\n            params: data.params ?? {},\n            timestamp: data.timestamp ?? Date.now(),\n          });\n        },\n      );\n    },\n\n    // ─── Result ─────────────────────────────────────────────────\n    sendResult(result: OUIActionResult) {\n      emit(`${ns}:action:result`, result);\n    },\n\n    onResult(handler: OUIResultHandler) {\n      return listen(`${ns}:action:result`, (data: OUIActionResult) =>\n        handler(data),\n      );\n    },\n\n    // ─── Observation Channel ────────────────────────────────────\n    pushObservation(update: OUIObservationUpdate) {\n      emit(`${ns}:observation`, update);\n    },\n\n    onObservation(handler: OUIObservationHandler) {\n      return listen(`${ns}:observation`, (data: OUIObservationUpdate) =>\n        handler(data),\n      );\n    },\n\n    // ─── Surface Lifecycle ──────────────────────────────────────\n    registerSurface(surface: OUISurface) {\n      emit(`${ns}:surface:register`, { surface, timestamp: Date.now() });\n    },\n\n    deregisterSurface(surfaceId: string) {\n      emit(`${ns}:surface:deregister`, { surfaceId, timestamp: Date.now() });\n    },\n\n    onSurfaceRegister(handler: (surface: OUISurface) => void) {\n      return listen(`${ns}:surface:register`, (data: { surface: OUISurface }) =>\n        handler(data.surface),\n      );\n    },\n\n    onSurfaceDeregister(handler: (surfaceId: string) => void) {\n      return listen(`${ns}:surface:deregister`, (data: { surfaceId: string }) =>\n        handler(data.surfaceId),\n      );\n    },\n\n    // ─── Connection ─────────────────────────────────────────────\n    get connected() {\n      return connected;\n    },\n\n    async connect() {\n      if (connected) return;\n      return new Promise<void>((resolve, reject) => {\n        const timeout = setTimeout(() => {\n          reject(\n            new Error(\n              `OUI transport connect timeout (${config?.connectTimeoutMs ?? 10000}ms)`,\n            ),\n          );\n        }, config?.connectTimeoutMs ?? 10000);\n\n        socket.once(\"connect\", () => {\n          clearTimeout(timeout);\n          resolve();\n        });\n\n        if (typeof socket.connect === \"function\") {\n          socket.connect();\n        }\n      });\n    },\n\n    disconnect() {\n      if (typeof socket.disconnect === \"function\") {\n        socket.disconnect();\n      }\n    },\n\n    onConnectionChange(handler: (c: boolean) => void) {\n      connectionHandlers.push(handler);\n      return () => {\n        const idx = connectionHandlers.indexOf(handler);\n        if (idx >= 0) connectionHandlers.splice(idx, 1);\n      };\n    },\n\n    dispose() {\n      for (const { event, handler } of attached.splice(0)) {\n        socket.off(event, handler);\n      }\n      connectionHandlers.length = 0;\n      buffer.length = 0;\n    },\n  };\n}\n\n/**\n * Minimal socket interface — compatible with Socket.IO client or server socket.\n * Only the methods OUI actually uses.\n */\nexport interface SocketLike {\n  readonly connected?: boolean;\n  emit(event: string, data: unknown): void;\n  on(event: string, handler: (...args: any[]) => void): void;\n  off(event: string, handler: (...args: any[]) => void): void;\n  once(event: string, handler: (...args: any[]) => void): void;\n  connect?(): void;\n  disconnect?(): void;\n}\n"]}