oui-spec 0.2.0 → 0.4.0

package/README.md

@@ -36,37 +36,43 @@ OUI     + UI App        = any agent can control the UI
 flowchart TD
     Agent[Agent Runtime / LLM]
     Manifest[OUI Manifest]
-    Dispatch[Dispatch Channel]
-    Observe[Observation Channel]
+    Runtime[Client Surface Runtime]
     Surface[UI Surface]
     App[Application State]
 
     Agent -->|reads| Manifest
-    Agent -->|fire-and-forget action| Dispatch
-    Dispatch -->|WebSocket| Surface
-    Surface -->|executes handler| App
-    App -->|state changes| Surface
-    Surface -->|pushes observations| Observe
-    Observe -->|WebSocket| Agent
+    Agent -->|action request + requestId| Runtime
+    Runtime -->|runs handler| Surface
+    Surface -->|changes| App
+    App -->|UI settles| Runtime
+    Runtime -->|action result + surfaces after it| Agent
 ```
 
-### Fully Async. Fully Stateless. No Waiting.
+### Every Action Is Answered
 
-OUI uses **two one-way channels** — not request/response. This is the critical architectural decision:
+Every action request carries a `requestId`, and the client answers it exactly
+once with an `OUIActionResult` (spec §7.3):
 
-| Channel         | Direction       | Purpose                              |
-| --------------- | --------------- | ------------------------------------ |
-| **Dispatch**    | Server → Client | Fire action instructions at the UI   |
-| **Observation** | Client → Server | Push state updates back to the agent |
+| Event                | Direction        | Carries                                                                                              |
+| -------------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
+| `{ns}:dispatch`      | runtime → client | `OUIActionRequest` — `requestId`, `surfaceId`, `actionId`, `params`                                  |
+| `{ns}:action:result` | client → runtime | `OUIActionResult` — success or error, and the client's surfaces and observations once the UI settled |
+| `{ns}:observation`   | client → runtime | state updates as they happen                                                                         |
 
-The agent runtime (e.g., a Lambda function) dispatches an action and **terminates immediately**. It does not wait for a response. The browser executes the action, starts any async work, and pushes observation updates over the observation channel as results arrive. The agent picks up those observations on its next invocation.
+The result includes what the client can do **after** the action. An action can
+change that: navigating unmounts one page's surfaces and mounts another's. An
+agent that only knew the capability set from before the action would be acting
+on the page it just left.
 
-This means:
+An async action (`async: true`) is acknowledged at once with `interim: true`,
+and answered a second time, under the same `requestId`, when its polling
+finishes. Progress in between is published as observations.
 
-- **No Lambda waiting** — no 30-second timeouts holding a connection open
-- **No request/response correlation** — no correlation IDs, no pending promises
-- **No WebSocket held open by the server** — the server writes and disconnects
-- **Long-running operations work naturally** — the UI polls or subscribes and pushes status updates over time
+An earlier version of this package had no result channel: dispatch was
+fire-and-forget and results were expected to arrive as observations. An agent
+could not tell whether an action ran, and its integrator reported success
+before the browser had done anything. The spec always required a result; the
+package now implements it.
 
 ---
 
@@ -118,48 +124,51 @@ export const counterSurface = defineSurface({
 });
 ```
 
-Then instantiate OUI. **`createOUI` is the only supported integration path** — it owns the wire so you never implement the protocol yourself:
+Then create **one surface runtime per client** and provide it at the root. The
+runtime keeps the client's own record of what is mounted, answers every request
+that arrives on the socket, and produces the snapshot an agent works from:
 
-```typescript
-// oui.ts
-import { createOUI } from "oui-spec/core";
-import { counterSurface } from "./counter.surface";
-import { socket } from "./my-socket"; // your connection, your auth, your lifecycle
+```tsx
+// App.tsx
+import { createSurfaceRuntime } from "oui-spec/core";
+import { SurfaceRuntimeProvider } from "oui-spec/react";
 
-export const oui = createOUI({
-  socket, // you own the connection
-  surfaces: [counterSurface], // you own what exists
-});
+const runtime = createSurfaceRuntime({ socket }); // your connection, your auth
 
-await oui.start(); // registers every surface and connects
+export function App() {
+  return (
+    <SurfaceRuntimeProvider runtime={runtime}>
+      <CounterPage />
+    </SurfaceRuntimeProvider>
+  );
+}
 ```
 
 ```tsx
 // CounterPage.tsx
 import { useSurface, useObservation } from "oui-spec/react";
 import { counterSurface } from "./counter.surface";
-import { oui } from "./oui";
 
 function CounterPage() {
   const [count, setCount] = useState(0);
 
-  useSurface({
+  // Mounted while the page is. The runtime answers requests for it.
+  const surface = useSurface({
     surface: counterSurface,
     context: { count, setCount },
-    send: oui.transport.send,
   });
 
-  useObservation(
-    counterSurface.id,
-    "current_value",
-    { value: count },
-    oui.transport.send,
-  );
+  useObservation(surface, "current_value", { value: count });
 
   return <div>Count: {count}</div>;
 }
 ```
 
+`runtime.snapshot()` returns `{ surfaces, observations }` for everything
+mounted. An agent runtime that keeps no registry of its own can take it with
+each request (for example, with each chat turn); set `announce: false` and the
+runtime sends nothing but results over the socket.
+
 That's it. The agent now sees a `counter` surface with two tools (`increment`, `reset`) and one live observation (`current_value`).
 
 ---
@@ -171,20 +180,19 @@ enforced by the type system, not by documentation.
 
 ### What OUI owns — and you cannot reimplement
 
-|                    | Owned by OUI                                                                                     |
-| ------------------ | ------------------------------------------------------------------------------------------------ |
-| Socket event names | `{ns}:dispatch`, `{ns}:observation`, `{ns}:surface:register`, `{ns}:surface:deregister`          |
-| Namespace prefix   | `transport.namespace`, default `'oui'`                                                           |
-| Payload shapes     | `OUIActionRequest`, `OUIObservationUpdate`, `OUISurfaceRegistration`, `OUISurfaceDeregistration` |
-| Result routing     | Action results return through the **observation channel** — there is no separate result event    |
+|                    | Owned by OUI                                                                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| Socket event names | `{ns}:dispatch`, `{ns}:action:result`, `{ns}:observation`, `{ns}:surface:register`, `{ns}:surface:deregister`       |
+| Namespace prefix   | `transport.namespace`, default `'oui'`                                                                              |
+| Payload shapes     | `OUIActionRequest`, `OUIActionResult`, `OUIObservationUpdate`, `OUISurfaceRegistration`, `OUISurfaceDeregistration` |
+| Result routing     | One `{ns}:action:result` per request, correlated by `requestId`                                                     |
 
 `OUIInstance.transport` is a branded `OwnedTransport`. Only `createOUI`
 produces one, so a transport you construct by hand cannot be substituted for
 it. This is deliberate: an early integrator satisfied every type in this
-package without calling any of its runtime, rebuilt the wire by hand, hardcoded
-the namespace, and added a redundant result channel beside the observation
-channel that already carried results. Both ends then agreed only by the
-coincidence of matching string literals.
+package without calling any of its runtime, rebuilt the wire by hand and
+hardcoded the namespace. Both ends then agreed only by the coincidence of
+matching string literals.
 
 ### What you own
 
@@ -227,44 +235,35 @@ fail in your editor rather than at render time in a browser after a deploy.
 
 ## Architecture
 
-### Two One-Way Channels
+### Request and Result
 
 ```mermaid
 sequenceDiagram
-    participant Lambda as Agent Lambda
+    participant Agent as Agent Runtime
     participant WS as WebSocket Server
-    participant Browser as Browser / UI
-
-    Note over Lambda: Agent decides to act
-    Lambda->>WS: dispatch(surfaceId, actionId, params)
-    Note over Lambda: Lambda terminates immediately
-
-    WS->>Browser: oui:dispatch event
-    Note over Browser: Handler executes
-    Note over Browser: Async work begins
-
-    loop Polling / Subscribe
-        Browser->>Browser: Check job status
-        Browser->>WS: oui:observation (interim update)
-    end
-
-    Browser->>WS: oui:observation (final result)
-    Note over Lambda: Next invocation reads observations
+    participant Browser as Browser (surface runtime)
+
+    Agent->>WS: oui:dispatch { requestId, surfaceId, actionId, params }
+    WS->>Browser: oui:dispatch
+    Note over Browser: Handler runs once (de-duplicated by requestId)
+    Note over Browser: Waits until the UI settles
+    Browser->>WS: oui:action:result { requestId, success, data, surfaces, observations }
+    WS->>Agent: result for requestId
 ```
 
-The dispatch channel carries action instructions **downward** (server → client). The observation channel carries state updates **upward** (client → server). They never mix. There is no concept of "waiting for a response."
-
-### Why Not Request/Response?
-
-In a typical agent architecture:
+The client waits for the UI to settle before answering: nothing mounted,
+unmounted or changed an observation for a quiet window (250 ms by default), and
+no hold open. A component whose work mounting cannot show, such as a route's
+code or a page's data still loading, keeps the result waiting with
+`useSurfaceHold(isLoading)`. If the deadline passes first, the result says
+`settled: false`.
 
-1. The agent runs in a Lambda (or similar serverless function)
-2. The Lambda has a 30-second timeout
-3. The UI operation might take 2 minutes (file upload, ML inference, user confirmation)
+### Long operations
 
-Request/response forces the Lambda to hold a connection open until the operation completes. That either times out or requires expensive long-running compute.
-
-OUI's two-channel model means the Lambda does O(1) work — write a message to the dispatch channel and exit. The browser handles the rest on its own timeline and pushes results as observations. The agent reads those observations whenever it runs next.
+The result of an async action is its acknowledgment: the job was started, and
+here is its id. The agent is not held until a two-minute render finishes. The
+client polls or subscribes, publishes progress as observations, and sends the
+request's final result when the job ends.
 
 ---
 
@@ -561,55 +560,27 @@ export const datavizSurface = defineSurface<DataVizContext>({
 ### Using the Surface in React
 
 ```tsx
-// DataVizPage.tsx
+// DataVizPage.tsx — rendered inside a SurfaceRuntimeProvider
 import { useSurface, useObservation } from "oui-spec/react";
-import { createWebSocketTransport } from "oui-spec/transport";
 import { datavizSurface } from "./dataviz.surface";
 
 export function DataVizPage() {
   const { state, updateState, api } = useDataVizWizard();
-  const transport = useTransport(); // your app's transport setup
 
-  const { handleActionRequest } = useSurface({
+  const surface = useSurface({
     surface: datavizSurface,
     context: { state, updateState, api },
-    send: transport.pushObservation,
-    active: true,
   });
 
-  // Push observations whenever relevant state changes
-  useObservation(
-    datavizSurface.id,
-    "wizard_state",
-    {
-      step: state.step,
-      selectedDatasetId: state.selectedDataset?.id,
-      chartConfig: state.chartConfig,
-      filters: state.filters,
-      renderedChartUrl: state.renderedChart?.imageUrl,
-    },
-    transport.pushObservation,
-  );
-
-  useObservation(
-    datavizSurface.id,
-    "available_datasets",
-    state.datasets,
-    transport.pushObservation,
-  );
-
-  // Wire transport to surface
-  useEffect(() => {
-    return transport.onAction((surfaceId, actionId, params) => {
-      handleActionRequest({
-        surfaceId,
-        actionId,
-        params,
-        requestId: "",
-        timestamp: Date.now(),
-      });
-    });
-  }, [handleActionRequest, transport]);
+  // Keep observations equal to the state they describe
+  useObservation(surface, "wizard_state", {
+    step: state.step,
+    selectedDatasetId: state.selectedDataset?.id,
+    chartConfig: state.chartConfig,
+    filters: state.filters,
+    renderedChartUrl: state.renderedChart?.imageUrl,
+  });
+  useObservation(surface, "available_datasets", state.datasets);
 
   return <DataVizWizardUI state={state} />;
 }
@@ -699,7 +670,7 @@ They even share JSON Schema for parameter validation — a deliberate design cho
 | **Async operations**   | Poll screenshots               | Poll DOM                  | Not built-in              | Declarative polling runtime             |
 | **Consent model**      | Everything visible             | Everything in DOM         | Server declares tools     | App declares surface                    |
 | **Framework coupling** | None                           | Tight (HTML-specific)     | None                      | None (spec is universal)                |
-| **Complex workflows**  | Dozens of screenshots          | Dozens of selectors       | Multiple tool calls       | Multiple dispatches + observations      |
+| **Complex workflows**  | Dozens of screenshots          | Dozens of selectors       | Multiple tool calls       | Multiple requests, each answered        |
 
 ---
 
@@ -708,8 +679,8 @@ They even share JSON Schema for parameter validation — a deliberate design cho
 1. **App-declared, not inferred.** The application explicitly states what it supports. Agents don't guess from pixels or DOM.
 2. **Semantic, not structural.** Actions are named operations (`render_chart`), not DOM paths (`click #btn-render`).
 3. **Typed end-to-end.** Inputs and outputs use JSON Schema. The agent knows exactly what to send and expect.
-4. **Fully async.** Dispatch is fire-and-forget. Results arrive as observations. No blocking, no timeouts.
-5. **Two channels, one direction each.** Dispatch goes down. Observations go up. Never mixed.
+4. **Every action is answered.** One result per request, correlated by `requestId`, carrying what the client can do after it. Long jobs are acknowledged at once and answered again when they finish.
+5. **The client is the record.** The client's surface runtime knows what is mounted; an agent can take its snapshot rather than trust a registry that can drift from it.
 6. **Framework-agnostic.** The spec works with React, Vue, Svelte, vanilla JS, native apps — anything that can handle a function call and emit an event.
 7. **Observable.** The agent reads relevant state without screenshots. The app pushes state changes when they happen.
 8. **Consent-based.** The app controls what's exposed. Users and developers decide what agents can do.
@@ -731,6 +702,7 @@ They even share JSON Schema for parameter validation — a deliberate design cho
 - [x] `oui-spec/react` — `useSurface()` hook + observation helpers
 - [x] `oui-spec/transport` — WebSocket + Direct transports
 - [x] `createOUI()` — gated instantiation; integration requirements enforced at compile time
+- [x] `createSurfaceRuntime()` — client-side record of mounted surfaces; every request answered with a result and the snapshot after it
 - [ ] `oui-spec/devtools` — Surface inspector / debugger
 - [ ] `oui-spec/vue` — Vue bindings
 - [ ] `oui-spec/validator` — Runtime schema validation

package/dist/{chunk-CVUUSPF4.js → chunk-BMCL2K74.js}

@@ -8,5 +8,5 @@ var OUI_PROTOCOL_EVENTS = {
 };
 
 export { OUI_PROTOCOL_EVENTS };
-//# sourceMappingURL=chunk-CVUUSPF4.js.map
-//# sourceMappingURL=chunk-CVUUSPF4.js.map
+//# sourceMappingURL=chunk-BMCL2K74.js.map
+//# sourceMappingURL=chunk-BMCL2K74.js.map

package/dist/chunk-BMCL2K74.js.map

@@ -0,0 +1 @@
+{"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-MTMEW6MM.cjs → chunk-DCVVTP3V.cjs}

@@ -8,17 +8,28 @@ function createWebSocketTransport(socket, config) {
   const shouldBuffer = config?.bufferWhileDisconnected ?? true;
   let connected = socket.connected ?? false;
   const connectionHandlers = [];
-  socket.on("connect", () => {
+  const attached = [];
+  function listen(event, handler) {
+    socket.on(event, handler);
+    const entry = { event, handler };
+    attached.push(entry);
+    return () => {
+      socket.off(event, handler);
+      const i = attached.indexOf(entry);
+      if (i >= 0) attached.splice(i, 1);
+    };
+  }
+  listen("connect", () => {
     connected = true;
-    connectionHandlers.forEach((h) => h(true));
     if (shouldBuffer) {
       while (buffer.length > 0) {
         const msg = buffer.shift();
         socket.emit(msg.event, msg.data);
       }
     }
+    connectionHandlers.forEach((h) => h(true));
   });
-  socket.on("disconnect", () => {
+  listen("disconnect", () => {
     connected = false;
     connectionHandlers.forEach((h) => h(false));
   });
@@ -30,25 +41,50 @@ function createWebSocketTransport(socket, config) {
     }
   }
   return {
-    // ─── Dispatch Channel ───────────────────────────────────────
-    dispatch(surfaceId, actionId, params) {
-      emit(`${ns}:dispatch`, { surfaceId, actionId, params, timestamp: Date.now() });
+    // ─── Dispatch ───────────────────────────────────────────────
+    dispatch(request) {
+      emit(`${ns}:dispatch`, request);
     },
     onAction(handler) {
-      const listener = (data) => {
-        handler(data.surfaceId, data.actionId, data.params);
-      };
-      socket.on(`${ns}:dispatch`, listener);
-      return () => socket.off(`${ns}:dispatch`, listener);
+      return listen(
+        `${ns}:dispatch`,
+        (data) => {
+          if (!data || typeof data.requestId !== "string" || !data.requestId || typeof data.surfaceId !== "string" || typeof data.actionId !== "string") {
+            console.warn(
+              "[OUI] Dropped a dispatch without requestId/surfaceId/actionId",
+              data
+            );
+            return;
+          }
+          handler({
+            requestId: data.requestId,
+            surfaceId: data.surfaceId,
+            actionId: data.actionId,
+            params: data.params ?? {},
+            timestamp: data.timestamp ?? Date.now()
+          });
+        }
+      );
+    },
+    // ─── Result ─────────────────────────────────────────────────
+    sendResult(result) {
+      emit(`${ns}:action:result`, result);
+    },
+    onResult(handler) {
+      return listen(
+        `${ns}:action:result`,
+        (data) => handler(data)
+      );
     },
     // ─── Observation Channel ────────────────────────────────────
     pushObservation(update) {
       emit(`${ns}:observation`, update);
     },
     onObservation(handler) {
-      const listener = (data) => handler(data);
-      socket.on(`${ns}:observation`, listener);
-      return () => socket.off(`${ns}:observation`, listener);
+      return listen(
+        `${ns}:observation`,
+        (data) => handler(data)
+      );
     },
     // ─── Surface Lifecycle ──────────────────────────────────────
     registerSurface(surface) {
@@ -58,14 +94,16 @@ function createWebSocketTransport(socket, config) {
       emit(`${ns}:surface:deregister`, { surfaceId, timestamp: Date.now() });
     },
     onSurfaceRegister(handler) {
-      const listener = (data) => handler(data.surface);
-      socket.on(`${ns}:surface:register`, listener);
-      return () => socket.off(`${ns}:surface:register`, listener);
+      return listen(
+        `${ns}:surface:register`,
+        (data) => handler(data.surface)
+      );
     },
     onSurfaceDeregister(handler) {
-      const listener = (data) => handler(data.surfaceId);
-      socket.on(`${ns}:surface:deregister`, listener);
-      return () => socket.off(`${ns}:surface:deregister`, listener);
+      return listen(
+        `${ns}:surface:deregister`,
+        (data) => handler(data.surfaceId)
+      );
     },
     // ─── Connection ─────────────────────────────────────────────
     get connected() {
@@ -75,7 +113,11 @@ function createWebSocketTransport(socket, config) {
       if (connected) return;
       return new Promise((resolve, reject) => {
         const timeout = setTimeout(() => {
-          reject(new Error(`OUI transport connect timeout (${config?.connectTimeoutMs ?? 1e4}ms)`));
+          reject(
+            new Error(
+              `OUI transport connect timeout (${config?.connectTimeoutMs ?? 1e4}ms)`
+            )
+          );
         }, config?.connectTimeoutMs ?? 1e4);
         socket.once("connect", () => {
           clearTimeout(timeout);
@@ -97,10 +139,17 @@ function createWebSocketTransport(socket, config) {
         const idx = connectionHandlers.indexOf(handler);
         if (idx >= 0) connectionHandlers.splice(idx, 1);
       };
+    },
+    dispose() {
+      for (const { event, handler } of attached.splice(0)) {
+        socket.off(event, handler);
+      }
+      connectionHandlers.length = 0;
+      buffer.length = 0;
     }
   };
 }
 
 exports.createWebSocketTransport = createWebSocketTransport;
-//# sourceMappingURL=chunk-MTMEW6MM.cjs.map
-//# sourceMappingURL=chunk-MTMEW6MM.cjs.map
+//# sourceMappingURL=chunk-DCVVTP3V.cjs.map
+//# sourceMappingURL=chunk-DCVVTP3V.cjs.map

package/dist/chunk-DCVVTP3V.cjs.map

@@ -0,0 +1 @@
+{"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"]}