oui-spec 0.4.0 → 0.5.0

package/dist/chunk-XUX4XVP3.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transport/websocket.ts"],"names":[],"mappings":"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","file":"chunk-XUX4XVP3.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  OUIActionApproval,\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            ...(isApproval(data.approval)\n              ? {\n                  approval: {\n                    approvalId: data.approval.approvalId,\n                    argsHash: data.approval.argsHash,\n                  },\n                }\n              : {}),\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\n/** An approval as the wire carries it; anything else is dropped, so the runtime treats the request as unapproved. */\nfunction isApproval(value: unknown): value is OUIActionApproval {\n  const a = value as Partial<OUIActionApproval> | null | undefined;\n  return (\n    !!a &&\n    typeof a.approvalId === \"string\" &&\n    !!a.approvalId &&\n    typeof a.argsHash === \"string\"\n  );\n}\n"]}

package/dist/core/index.cjs

@@ -1,26 +1,26 @@
 'use strict';
 
-var chunkDGMKSJTY_cjs = require('../chunk-DGMKSJTY.cjs');
-var chunkZKM4XWAB_cjs = require('../chunk-ZKM4XWAB.cjs');
-require('../chunk-DCVVTP3V.cjs');
+var chunk27CBVTA4_cjs = require('../chunk-27CBVTA4.cjs');
+var chunk2AISUNMW_cjs = require('../chunk-2AISUNMW.cjs');
+require('../chunk-XUX4XVP3.cjs');
 
 
 
 Object.defineProperty(exports, "createOUI", {
   enumerable: true,
-  get: function () { return chunkDGMKSJTY_cjs.createOUI; }
+  get: function () { return chunk27CBVTA4_cjs.createOUI; }
 });
 Object.defineProperty(exports, "createSurfaceRuntime", {
   enumerable: true,
-  get: function () { return chunkDGMKSJTY_cjs.createSurfaceRuntime; }
+  get: function () { return chunk27CBVTA4_cjs.createSurfaceRuntime; }
 });
 Object.defineProperty(exports, "defineSurface", {
   enumerable: true,
-  get: function () { return chunkDGMKSJTY_cjs.defineSurface; }
+  get: function () { return chunk27CBVTA4_cjs.defineSurface; }
 });
 Object.defineProperty(exports, "OUI_PROTOCOL_EVENTS", {
   enumerable: true,
-  get: function () { return chunkZKM4XWAB_cjs.OUI_PROTOCOL_EVENTS; }
+  get: function () { return chunk2AISUNMW_cjs.OUI_PROTOCOL_EVENTS; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/core/index.d.cts

@@ -1,7 +1,7 @@
 import { OUISurface } from '../spec/index.cjs';
 export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationSnapshot, OUIObservationUpdate, OUIProtocolEvent, OUISurfaceDeregistration, OUISurfaceRegistration, OUISurfaceSnapshot, OUI_PROTOCOL_EVENTS } from '../spec/index.cjs';
-import { D as DefinedSurface, O as OUIBranded } from '../surface-runtime-BzIKgL_I.cjs';
-export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, M as MountedSurface, c as ObservationDefinition, S as SettleOptions, d as SurfaceDefinition, e as SurfaceRuntime, f as SurfaceRuntimeOptions, g as createSurfaceRuntime, h as defineSurface } from '../surface-runtime-BzIKgL_I.cjs';
+import { D as DefinedSurface, O as OUIBranded } from '../surface-runtime-lqXn221P.cjs';
+export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, M as MountedSurface, c as ObservationDefinition, S as SettleOptions, d as SurfaceDefinition, e as SurfaceRuntime, f as SurfaceRuntimeOptions, g as createSurfaceRuntime, h as defineSurface } from '../surface-runtime-lqXn221P.cjs';
 import { S as SocketLike, d as OUITransportConfig, c as OUITransport } from '../websocket-YfWILdZ4.cjs';
 
 /**

package/dist/core/index.d.ts

@@ -1,7 +1,7 @@
 import { OUISurface } from '../spec/index.js';
 export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationSnapshot, OUIObservationUpdate, OUIProtocolEvent, OUISurfaceDeregistration, OUISurfaceRegistration, OUISurfaceSnapshot, OUI_PROTOCOL_EVENTS } from '../spec/index.js';
-import { D as DefinedSurface, O as OUIBranded } from '../surface-runtime-DeByfbKg.js';
-export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, M as MountedSurface, 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';
+import { D as DefinedSurface, O as OUIBranded } from '../surface-runtime-CS0rByFQ.js';
+export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, M as MountedSurface, 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';
 import { S as SocketLike, d as OUITransportConfig, c as OUITransport } from '../websocket-c5tIUWY5.js';
 
 /**

package/dist/core/index.js

@@ -1,5 +1,5 @@
-export { createOUI, createSurfaceRuntime, defineSurface } from '../chunk-GXTNZ44I.js';
-export { OUI_PROTOCOL_EVENTS } from '../chunk-BMCL2K74.js';
-import '../chunk-F3WKIRAU.js';
+export { createOUI, createSurfaceRuntime, defineSurface } from '../chunk-6ZIKO7MG.js';
+export { OUI_PROTOCOL_EVENTS } from '../chunk-BNGJJM3T.js';
+import '../chunk-UKKITNZK.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.cjs

@@ -1,28 +1,56 @@
 'use strict';
 
-var chunkDGMKSJTY_cjs = require('./chunk-DGMKSJTY.cjs');
-var chunkZKM4XWAB_cjs = require('./chunk-ZKM4XWAB.cjs');
+var chunk27CBVTA4_cjs = require('./chunk-27CBVTA4.cjs');
+var chunk2AISUNMW_cjs = require('./chunk-2AISUNMW.cjs');
 var chunkF3SKRAGU_cjs = require('./chunk-F3SKRAGU.cjs');
 var chunkROGKEMLL_cjs = require('./chunk-ROGKEMLL.cjs');
-var chunkDCVVTP3V_cjs = require('./chunk-DCVVTP3V.cjs');
+var chunkXUX4XVP3_cjs = require('./chunk-XUX4XVP3.cjs');
 
 
 
 Object.defineProperty(exports, "createOUI", {
   enumerable: true,
-  get: function () { return chunkDGMKSJTY_cjs.createOUI; }
+  get: function () { return chunk27CBVTA4_cjs.createOUI; }
 });
 Object.defineProperty(exports, "createSurfaceRuntime", {
   enumerable: true,
-  get: function () { return chunkDGMKSJTY_cjs.createSurfaceRuntime; }
+  get: function () { return chunk27CBVTA4_cjs.createSurfaceRuntime; }
 });
 Object.defineProperty(exports, "defineSurface", {
   enumerable: true,
-  get: function () { return chunkDGMKSJTY_cjs.defineSurface; }
+  get: function () { return chunk27CBVTA4_cjs.defineSurface; }
+});
+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; }
 });
 Object.defineProperty(exports, "SurfaceRuntimeProvider", {
   enumerable: true,
@@ -50,7 +78,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/index.d.cts

@@ -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.cjs';
-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-BzIKgL_I.cjs';
+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.cjs';
+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-lqXn221P.cjs';
 export { DuplicateIds, OUIConfig, OUIConfigError, OUIInstance, OwnedTransport, ValidateSurfaceIds, createOUI } from './core/index.cjs';
 export { SurfaceRuntimeProvider, SurfaceRuntimeProviderProps, UseSurfaceOptions, UseSurfaceResult, useObservation, useSurface, useSurfaceHold, useSurfaceRuntime } from './react/index.cjs';
 export { O as OUIActionHandler, a as OUIObservationHandler, b as OUIResultHandler, c as OUITransport, d as OUITransportConfig, S as SocketLike, e as createWebSocketTransport } from './websocket-YfWILdZ4.cjs';

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-GXTNZ44I.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.0",
-  "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": {
     "*": {