oui-spec 0.1.0 → 0.2.0

package/README.md

@@ -118,26 +118,42 @@ 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:
+
+```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
+
+export const oui = createOUI({
+  socket, // you own the connection
+  surfaces: [counterSurface], // you own what exists
+});
+
+await oui.start(); // registers every surface and connects
+```
+
 ```tsx
 // CounterPage.tsx
 import { useSurface, useObservation } from "oui-spec/react";
 import { counterSurface } from "./counter.surface";
+import { oui } from "./oui";
 
-function CounterPage({ transport }) {
+function CounterPage() {
   const [count, setCount] = useState(0);
 
-  const { handleActionRequest } = useSurface({
+  useSurface({
     surface: counterSurface,
     context: { count, setCount },
-    send: transport.send,
+    send: oui.transport.send,
   });
 
-  // Push observation whenever count changes
   useObservation(
     counterSurface.id,
     "current_value",
     { value: count },
-    transport.send,
+    oui.transport.send,
   );
 
   return <div>Count: {count}</div>;
@@ -148,6 +164,67 @@ That's it. The agent now sees a `counter` surface with two tools (`increment`, `
 
 ---
 
+## The Integration Contract
+
+OUI owns the protocol. You own the connection and the content. That split is
+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    |
+
+`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.
+
+### What you own
+
+|                     | Owned by the integrator                      |
+| ------------------- | -------------------------------------------- |
+| Connection          | The `socket` — auth, reconnection, lifecycle |
+| Surfaces            | What exists, via `defineSurface`             |
+| Action schemas      | `input` / `output` JSON Schema per action    |
+| Observation schemas | `schema` per observation                     |
+| Handlers            | What actually executes                       |
+
+### Requirements enforced at compile time
+
+`createOUI` will not compile unless every requirement is met:
+
+```typescript
+createOUI({ socket, surfaces: [alpha, alpha] });
+// ✗ Duplicate surface id: "alpha". Registration is keyed by id,
+//   so the second would silently replace the first.
+
+createOUI({ socket, surfaces: [] });
+// ✗ createOUI requires at least one surface. An instance with no
+//   surfaces registers nothing and dispatches nowhere.
+
+createOUI({ surfaces: [alpha] });
+// ✗ Property 'socket' is missing.
+
+createOUI({ socket, surfaces: [{ id: "x", name: "X" /* ... */ }] });
+// ✗ Property '[OUI_BRAND]' is missing — surfaces must come from defineSurface.
+
+const mine: OwnedTransport = createWebSocketTransport(socket);
+// ✗ Property '[OUI_BRAND]' is missing in type 'OUITransport'.
+```
+
+Duplicate action and observation ids within a surface are validated by
+`defineSurface`. Surface-level rules are checked by the type system, so they
+fail in your editor rather than at render time in a browser after a deploy.
+
+---
+
 ## Architecture
 
 ### Two One-Way Channels
@@ -564,19 +641,25 @@ The agent can orchestrate the full wizard: select data → configure chart → f
 The `oui-spec` package exposes subpath exports for granular imports:
 
 ```typescript
-import { defineSurface } from "oui-spec/core";
-import { useSurface } from "oui-spec/react";
-import { createWebSocketTransport } from "oui-spec/transport";
+import { createOUI, defineSurface } from "oui-spec/core";
+import { useSurface, useObservation } from "oui-spec/react";
+import type { SocketLike } from "oui-spec/transport";
 import type { OUISurface, OUIAction } from "oui-spec/spec";
 
 // Or import everything from the root
-import { defineSurface, useSurface, createWebSocketTransport } from "oui-spec";
+import { createOUI, defineSurface, useSurface } from "oui-spec";
 ```
 
+`oui-spec/transport` also exports `createWebSocketTransport` and
+`createDirectTransportPair`. These exist for tests and for embedding OUI in a
+runtime that owns its own wiring — they are **not** the integration path, and
+they return a plain `OUITransport` rather than the branded `OwnedTransport` that
+OUI's own APIs accept. If you are integrating an application, use `createOUI`.
+
 | Subpath              | Description                                                                  |
 | -------------------- | ---------------------------------------------------------------------------- |
 | `oui-spec/spec`      | TypeScript types + JSON Schema for the OUI specification. Zero runtime deps. |
-| `oui-spec/core`      | `defineSurface()`, manifest extraction, action execution, polling config.    |
+| `oui-spec/core`      | `createOUI()`, `defineSurface()`, manifest extraction, action execution.     |
 | `oui-spec/react`     | `useSurface()` hook, `useObservation()` helper. React bindings.              |
 | `oui-spec/transport` | Two-channel transport layer. WebSocket (Socket.IO), direct (in-memory).      |
 
@@ -632,6 +715,7 @@ They even share JSON Schema for parameter validation — a deliberate design cho
 8. **Consent-based.** The app controls what's exposed. Users and developers decide what agents can do.
 9. **Composable.** Multiple surfaces coexist. A complex app exposes many surfaces (one per feature/page).
 10. **Complementary.** OUI doesn't replace OpenAPI, MCP, or any other standard. It fills the "UI control" gap they leave open.
+11. **Unbypassable.** A contract an integrator can satisfy without using is not a contract. OUI brands the values it owns with a `unique symbol`, so structural typing cannot be used to substitute a hand-rolled transport or surface. Requirements fail at compile time, with the offending id named.
 
 ---
 
@@ -646,6 +730,7 @@ They even share JSON Schema for parameter validation — a deliberate design cho
 - [x] `oui-spec/core` — `defineSurface()` + manifest extraction
 - [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
 - [ ] `oui-spec/devtools` — Surface inspector / debugger
 - [ ] `oui-spec/vue` — Vue bindings
 - [ ] `oui-spec/validator` — Runtime schema validation

package/dist/chunk-5TQ6AVQH.cjs

@@ -0,0 +1,108 @@
+'use strict';
+
+// src/transport/direct.ts
+function createDirectTransportPair() {
+  const actionHandlers = [];
+  const observationHandlers = [];
+  const surfaceRegisterHandlers = [];
+  const surfaceDeregisterHandlers = [];
+  const server = {
+    dispatch(surfaceId, actionId, params) {
+      actionHandlers.forEach((h) => h(surfaceId, actionId, params));
+    },
+    onAction() {
+      return () => {
+      };
+    },
+    // Server doesn't receive dispatches
+    pushObservation() {
+    },
+    // Server doesn't push observations
+    onObservation(handler) {
+      observationHandlers.push(handler);
+      return () => {
+        const i = observationHandlers.indexOf(handler);
+        if (i >= 0) observationHandlers.splice(i, 1);
+      };
+    },
+    registerSurface() {
+    },
+    deregisterSurface() {
+    },
+    onSurfaceRegister(handler) {
+      surfaceRegisterHandlers.push(handler);
+      return () => {
+        const i = surfaceRegisterHandlers.indexOf(handler);
+        if (i >= 0) surfaceRegisterHandlers.splice(i, 1);
+      };
+    },
+    onSurfaceDeregister(handler) {
+      surfaceDeregisterHandlers.push(handler);
+      return () => {
+        const i = surfaceDeregisterHandlers.indexOf(handler);
+        if (i >= 0) surfaceDeregisterHandlers.splice(i, 1);
+      };
+    },
+    get connected() {
+      return true;
+    },
+    async connect() {
+    },
+    disconnect() {
+    },
+    onConnectionChange() {
+      return () => {
+      };
+    }
+  };
+  const client = {
+    dispatch() {
+    },
+    // Client doesn't dispatch
+    onAction(handler) {
+      actionHandlers.push(handler);
+      return () => {
+        const i = actionHandlers.indexOf(handler);
+        if (i >= 0) actionHandlers.splice(i, 1);
+      };
+    },
+    pushObservation(update) {
+      observationHandlers.forEach((h) => h(update));
+    },
+    onObservation() {
+      return () => {
+      };
+    },
+    // Client doesn't receive observations
+    registerSurface(surface) {
+      surfaceRegisterHandlers.forEach((h) => h(surface));
+    },
+    deregisterSurface(surfaceId) {
+      surfaceDeregisterHandlers.forEach((h) => h(surfaceId));
+    },
+    onSurfaceRegister() {
+      return () => {
+      };
+    },
+    onSurfaceDeregister() {
+      return () => {
+      };
+    },
+    get connected() {
+      return true;
+    },
+    async connect() {
+    },
+    disconnect() {
+    },
+    onConnectionChange() {
+      return () => {
+      };
+    }
+  };
+  return { server, client };
+}
+
+exports.createDirectTransportPair = createDirectTransportPair;
+//# sourceMappingURL=chunk-5TQ6AVQH.cjs.map
+//# sourceMappingURL=chunk-5TQ6AVQH.cjs.map

package/dist/chunk-5TQ6AVQH.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transport/direct.ts"],"names":[],"mappings":"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","file":"chunk-5TQ6AVQH.cjs","sourcesContent":["import type { OUITransport, OUIActionHandler, OUIObservationHandler } from './types.js';\nimport type { OUISurface, OUIObservationUpdate } from '../spec/index.js';\n\n/**\n * Direct transport — for same-process communication.\n * Used for API surfaces (where the agent runtime and surface are in the same Lambda)\n * and for testing (where you want synchronous, in-memory communication).\n *\n * Creates a paired (server, client) transport where messages sent on one\n * side are immediately received on the other.\n */\nexport function createDirectTransportPair(): { server: OUITransport; client: OUITransport } {\n  const actionHandlers: OUIActionHandler[] = [];\n  const observationHandlers: OUIObservationHandler[] = [];\n  const surfaceRegisterHandlers: Array<(s: OUISurface) => void> = [];\n  const surfaceDeregisterHandlers: Array<(id: string) => void> = [];\n\n  const server: OUITransport = {\n    dispatch(surfaceId, actionId, params) {\n      // Server dispatches → client receives\n      actionHandlers.forEach(h => h(surfaceId, actionId, params));\n    },\n    onAction() { return () => {}; }, // Server doesn't receive dispatches\n    pushObservation() {}, // Server doesn't push observations\n    onObservation(handler) {\n      observationHandlers.push(handler);\n      return () => { const i = observationHandlers.indexOf(handler); if (i >= 0) observationHandlers.splice(i, 1); };\n    },\n    registerSurface() {},\n    deregisterSurface() {},\n    onSurfaceRegister(handler) {\n      surfaceRegisterHandlers.push(handler);\n      return () => { const i = surfaceRegisterHandlers.indexOf(handler); if (i >= 0) surfaceRegisterHandlers.splice(i, 1); };\n    },\n    onSurfaceDeregister(handler) {\n      surfaceDeregisterHandlers.push(handler);\n      return () => { const i = surfaceDeregisterHandlers.indexOf(handler); if (i >= 0) surfaceDeregisterHandlers.splice(i, 1); };\n    },\n    get connected() { return true; },\n    async connect() {},\n    disconnect() {},\n    onConnectionChange() { return () => {}; },\n  };\n\n  const client: OUITransport = {\n    dispatch() {}, // Client doesn't dispatch\n    onAction(handler) {\n      actionHandlers.push(handler);\n      return () => { const i = actionHandlers.indexOf(handler); if (i >= 0) actionHandlers.splice(i, 1); };\n    },\n    pushObservation(update: OUIObservationUpdate) {\n      // Client pushes → server receives\n      observationHandlers.forEach(h => h(update));\n    },\n    onObservation() { return () => {}; }, // Client doesn't receive observations\n    registerSurface(surface) {\n      surfaceRegisterHandlers.forEach(h => h(surface));\n    },\n    deregisterSurface(surfaceId) {\n      surfaceDeregisterHandlers.forEach(h => h(surfaceId));\n    },\n    onSurfaceRegister() { return () => {}; },\n    onSurfaceDeregister() { return () => {}; },\n    get connected() { return true; },\n    async connect() {},\n    disconnect() {},\n    onConnectionChange() { return () => {}; },\n  };\n\n  return { server, client };\n}\n"]}

package/dist/{chunk-LEXIU2MH.cjs → chunk-HK7OXB2W.cjs}

@@ -1,11 +1,20 @@
 'use strict';
 
+var chunkMTMEW6MM_cjs = require('./chunk-MTMEW6MM.cjs');
+
+// src/core/brand.ts
+function brand(value) {
+  return value;
+}
+
 // src/core/define-surface.ts
 function defineSurface(definition) {
   const actionIds = /* @__PURE__ */ new Set();
   for (const action of definition.actions) {
     if (actionIds.has(action.id)) {
-      throw new Error(`[OUI] Duplicate action ID "${action.id}" in surface "${definition.id}"`);
+      throw new Error(
+        `[OUI] Duplicate action ID "${action.id}" in surface "${definition.id}"`
+      );
     }
     actionIds.add(action.id);
   }
@@ -13,12 +22,14 @@ function defineSurface(definition) {
     const obsIds = /* @__PURE__ */ new Set();
     for (const obs of definition.observations) {
       if (obsIds.has(obs.id)) {
-        throw new Error(`[OUI] Duplicate observation ID "${obs.id}" in surface "${definition.id}"`);
+        throw new Error(
+          `[OUI] Duplicate observation ID "${obs.id}" in surface "${definition.id}"`
+        );
       }
       obsIds.add(obs.id);
     }
   }
-  return {
+  return brand({
     ...definition,
     /** Extract the manifest (schema only, no handlers) for transmission to the agent runtime */
     toManifest() {
@@ -37,7 +48,13 @@ function defineSurface(definition) {
     async executeAction(actionId, params, context) {
       const action = definition.actions.find((a) => a.id === actionId);
       if (!action) {
-        return { success: false, error: { code: "ACTION_NOT_FOUND", message: `Action "${actionId}" not found on surface "${definition.id}"` } };
+        return {
+          success: false,
+          error: {
+            code: "ACTION_NOT_FOUND",
+            message: `Action "${actionId}" not found on surface "${definition.id}"`
+          }
+        };
       }
       try {
         return await action.handler(params, context);
@@ -60,7 +77,7 @@ function defineSurface(definition) {
       const action = definition.actions.find((a) => a.id === actionId);
       return action?.polling;
     }
-  };
+  });
 }
 function actionToManifest(action) {
   return {
@@ -85,6 +102,56 @@ function obsToManifest(obs) {
   };
 }
 
+// src/core/create-oui.ts
+function createOUI(config) {
+  const {
+    socket,
+    surfaces,
+    transport: transportConfig
+  } = config;
+  if (!socket) {
+    throw new Error(
+      "[OUI] createOUI requires a socket. OUI owns the wire; the integrator owns the connection."
+    );
+  }
+  if (!Array.isArray(surfaces) || surfaces.length === 0) {
+    throw new Error("[OUI] createOUI requires at least one surface.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const surface of surfaces) {
+    if (seen.has(surface.id)) {
+      throw new Error(
+        `[OUI] Duplicate surface id "${surface.id}". Registration is keyed by id, so the second would replace the first.`
+      );
+    }
+    seen.add(surface.id);
+  }
+  const transport = brand(
+    chunkMTMEW6MM_cjs.createWebSocketTransport(socket, transportConfig)
+  );
+  const byId = new Map(surfaces.map((s) => [s.id, s]));
+  return {
+    transport,
+    manifests: surfaces.map((s) => s.toManifest()),
+    async start() {
+      await transport.connect();
+      for (const surface of surfaces) {
+        transport.registerSurface(surface.toManifest());
+      }
+    },
+    stop() {
+      for (const surface of surfaces) {
+        transport.deregisterSurface(surface.id);
+      }
+      transport.disconnect();
+    },
+    getSurface(id) {
+      return byId.get(id);
+    }
+  };
+}
+
+exports.createOUI = createOUI;
 exports.defineSurface = defineSurface;
-//# sourceMappingURL=chunk-LEXIU2MH.cjs.map
-//# sourceMappingURL=chunk-LEXIU2MH.cjs.map
+//# sourceMappingURL=chunk-HK7OXB2W.cjs.map
+//# sourceMappingURL=chunk-HK7OXB2W.cjs.map

package/dist/chunk-HK7OXB2W.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/brand.ts","../src/core/define-surface.ts","../src/core/create-oui.ts"],"names":["createWebSocketTransport"],"mappings":"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","file":"chunk-HK7OXB2W.cjs","sourcesContent":["/**\n * Nominal branding for values OUI must construct itself.\n *\n * Structural typing means any object with the right shape satisfies an\n * interface. That is how Closure Studio ended up hand-rolling OUI's transport:\n * `SocketLike` was importable, `OUITransport` was a plain interface, so an\n * integrator could satisfy every type without ever calling OUI. The result was\n * a second implementation of the wire — hardcoded namespace, re-declared\n * payload types on the server, and a dead `action:result` mapping alongside the\n * observation channel that already carried results.\n *\n * A unique symbol cannot be produced outside this module. Branding the types\n * OUI owns turns \"you should use our constructor\" into \"you cannot compile\n * without it\".\n */\n\ndeclare const OUI_BRAND: unique symbol;\n\n/** Marks a value as constructed by OUI itself. */\nexport interface OUIBranded<TKind extends string> {\n  readonly [OUI_BRAND]: TKind;\n}\n\n/**\n * Attach the brand at runtime. The property does not exist at runtime — the\n * symbol is declare-only — so this is a type-level assertion with no cost.\n */\nexport function brand<TKind extends string, T>(\n  value: T,\n): T & OUIBranded<TKind> {\n  return value as T & OUIBranded<TKind>;\n}\n","import type {\n  OUISurface,\n  OUIAction,\n  OUIObservation,\n  OUIActivation,\n  OUIActionPolling,\n  JSONSchema,\n} from \"../spec/index.js\";\nimport { brand, type OUIBranded } from \"./brand.js\";\n\n/**\n * Configuration for defining an OUI surface with handlers.\n * This is the \"integration file\" an app provides — it declares both\n * the schema (what the agent sees) and the implementation (what executes).\n */\nexport interface SurfaceDefinition<TContext = unknown> {\n  id: string;\n  name: string;\n  description: string;\n  version?: string;\n  activation?: OUIActivation;\n  actions: ActionDefinition<TContext>[];\n  observations?: ObservationDefinition[];\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Polling config with an optional resolve handler.\n * The spec's OUIActionPolling is the manifest shape (no functions).\n * The core extends it with the resolve implementation for the runtime.\n */\nexport interface ActionPollingConfig<\n  TContext = unknown,\n> extends OUIActionPolling {\n  /**\n   * Called on each poll interval. Receives the dispatch result from the handler\n   * plus the current context. Return { done: true, data } to stop polling,\n   * or { done: false, data } to continue.\n   */\n  resolve?: (\n    dispatchResult: unknown,\n    context: TContext,\n  ) => Promise<{ done: boolean; data: unknown }>;\n}\n\n/**\n * An action definition includes both the schema (for the agent) and\n * the handler (for execution). This is the single source of truth —\n * no separate YAML, no separate listener, no drift possible.\n */\nexport interface ActionDefinition<TContext = unknown> {\n  id: string;\n  description: string;\n  input: JSONSchema;\n  output?: JSONSchema;\n  confirm?: boolean;\n  async?: boolean;\n\n  /**\n   * Polling/subscription config for async actions.\n   * After the handler returns, the OUI runtime starts polling or subscribing\n   * and pushes observation updates until the operation completes.\n   * Extends the spec's OUIActionPolling with an optional resolve handler.\n   */\n  polling?: ActionPollingConfig<TContext>;\n\n  usage?: string;\n  preconditions?: string;\n  estimatedDuration?: string;\n  tags?: string[];\n\n  /**\n   * The handler that executes when the agent invokes this action.\n   * Receives typed params and a context object (app-specific state/utilities).\n   * Returns a result that the agent sees as the tool output.\n   */\n  handler: (\n    params: Record<string, unknown>,\n    context: TContext,\n  ) => Promise<ActionHandlerResult>;\n}\n\nexport interface ActionHandlerResult {\n  success: boolean;\n  data?: unknown;\n  error?: { code: string; message: string; details?: unknown };\n  /** For async actions: metadata passed to the polling resolver */\n  dispatchMeta?: Record<string, unknown>;\n}\n\nexport interface ObservationDefinition {\n  id: string;\n  description: string;\n  schema: JSONSchema;\n  /** Function that returns the current observation value */\n  getValue?: () => unknown;\n}\n\n/**\n * Define an OUI surface — the single entry point for integrating\n * an application feature with the OUI protocol.\n *\n * This function validates the definition and returns a typed surface\n * object that can be registered with an agent runtime or transport layer.\n *\n * @example\n * ```typescript\n * const mySurface = defineSurface({\n *   id: 'my-feature',\n *   name: 'My Feature',\n *   description: 'Does something cool',\n *   actions: [\n *     {\n *       id: 'do_thing',\n *       description: 'Does the thing',\n *       input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },\n *       handler: async (params) => {\n *         const result = await doTheThing(params.name);\n *         return { success: true, data: result };\n *       },\n *     },\n *   ],\n * });\n * ```\n */\nexport function defineSurface<\n  TContext = unknown,\n  const TId extends string = string,\n>(\n  definition: SurfaceDefinition<TContext> & { id: TId },\n): DefinedSurface<TContext> & { id: TId } {\n  // Validate: no duplicate action IDs\n  const actionIds = new Set<string>();\n  for (const action of definition.actions) {\n    if (actionIds.has(action.id)) {\n      throw new Error(\n        `[OUI] Duplicate action ID \"${action.id}\" in surface \"${definition.id}\"`,\n      );\n    }\n    actionIds.add(action.id);\n  }\n\n  // Validate: no duplicate observation IDs\n  if (definition.observations) {\n    const obsIds = new Set<string>();\n    for (const obs of definition.observations) {\n      if (obsIds.has(obs.id)) {\n        throw new Error(\n          `[OUI] Duplicate observation ID \"${obs.id}\" in surface \"${definition.id}\"`,\n        );\n      }\n      obsIds.add(obs.id);\n    }\n  }\n\n  return brand<\"surface\", unknown>({\n    ...definition,\n\n    /** Extract the manifest (schema only, no handlers) for transmission to the agent runtime */\n    toManifest(): OUISurface {\n      return {\n        id: definition.id,\n        name: definition.name,\n        description: definition.description,\n        version: definition.version,\n        activation: definition.activation,\n        actions: definition.actions.map(actionToManifest),\n        observations: definition.observations?.map(obsToManifest),\n        metadata: definition.metadata,\n      };\n    },\n\n    /** Execute an action by ID with the given params and context */\n    async executeAction(\n      actionId: string,\n      params: Record<string, unknown>,\n      context: TContext,\n    ): Promise<ActionHandlerResult> {\n      const action = definition.actions.find((a) => a.id === actionId);\n      if (!action) {\n        return {\n          success: false,\n          error: {\n            code: \"ACTION_NOT_FOUND\",\n            message: `Action \"${actionId}\" not found on surface \"${definition.id}\"`,\n          },\n        };\n      }\n      try {\n        return await action.handler(params, context);\n      } catch (err) {\n        return {\n          success: false,\n          error: {\n            code: \"ACTION_EXECUTION_ERROR\",\n            message: err instanceof Error ? err.message : String(err),\n          },\n        };\n      }\n    },\n\n    /** Get all action IDs */\n    getActionIds(): string[] {\n      return definition.actions.map((a) => a.id);\n    },\n\n    /** Get the polling config for an action (if async) */\n    getPollingConfig(actionId: string): OUIActionPolling | undefined {\n      const action = definition.actions.find((a) => a.id === actionId);\n      return action?.polling;\n    },\n  }) as DefinedSurface<TContext> & { id: TId };\n}\n\n/** A fully defined surface with both manifest extraction and execution capabilities */\n/**\n * Branded so it can only come from `defineSurface`.\n *\n * Without the brand a plain object literal satisfies this interface\n * structurally, which is how an integrator can assemble a surface that never\n * ran defineSurface's duplicate-id checks and never produced a real manifest.\n */\nexport interface DefinedSurface<TContext = unknown>\n  extends SurfaceDefinition<TContext>, OUIBranded<\"surface\"> {\n  toManifest(): OUISurface;\n  executeAction(\n    actionId: string,\n    params: Record<string, unknown>,\n    context: TContext,\n  ): Promise<ActionHandlerResult>;\n  getActionIds(): string[];\n  /** Get the polling config for an action (if async) */\n  getPollingConfig(actionId: string): OUIActionPolling | undefined;\n}\n\n// ─── Internal helpers ────────────────────────────────────────────────────────\n\nfunction actionToManifest<T>(action: ActionDefinition<T>): OUIAction {\n  return {\n    id: action.id,\n    description: action.description,\n    input: action.input,\n    output: action.output,\n    confirm: action.confirm,\n    async: action.async,\n    polling: action.polling,\n    usage: action.usage,\n    preconditions: action.preconditions,\n    estimatedDuration: action.estimatedDuration,\n    tags: action.tags,\n  };\n}\n\nfunction obsToManifest(obs: ObservationDefinition): OUIObservation {\n  return {\n    id: obs.id,\n    description: obs.description,\n    schema: obs.schema,\n  };\n}\n","/**\n * createOUI — the only supported way to instantiate OUI.\n *\n * WHY THIS EXISTS\n *\n * OUI shipped a correct protocol and a correct transport, and its first\n * integrator used neither. studio-ui imported only the `SocketLike` TYPE from\n * oui-spec and rebuilt the wire by hand: a literal map of protocol types to\n * socket names, `oui:` hardcoded so the configurable namespace was unreachable,\n * payload interfaces re-declared on the server, and an `action:result` channel\n * mapped but never sent — duplicating the observation channel that already\n * carries results.\n *\n * Nothing was wrong with the spec. Nothing enforced it. Structural typing meant\n * every hand-rolled piece type-checked, and both ends agreed only by the\n * coincidence of matching string literals. Rename one and the other keeps\n * compiling and silently stops receiving.\n *\n * So the requirements are gated here:\n *\n *   OUI owns the wire. The integrator provides a socket; it cannot provide a\n *   transport, because `OUITransport` values are branded and only this module\n *   brands them.\n *\n *   OUI owns the result path. Results return through the observation channel,\n *   as `use-surface` already implements. An integrator cannot add a parallel\n *   channel because it cannot construct a transport to add one to.\n *\n *   The integrator owns content. Surfaces, action schemas, observation schemas\n *   and handlers all arrive through `defineSurface`, whose output is branded —\n *   so a plain object shaped like a surface will not compile.\n *\n *   Violations fail at compile time with a message naming the offending id.\n */\nimport type { OUITransport, OUITransportConfig } from \"../transport/types.js\";\nimport type { SocketLike } from \"../transport/websocket.js\";\nimport { createWebSocketTransport } from \"../transport/websocket.js\";\nimport type { DefinedSurface } from \"./define-surface.js\";\nimport { brand, type OUIBranded } from \"./brand.js\";\nimport type { OUIConfigError, ValidateSurfaceIds } from \"./validate.js\";\nimport type { OUISurface } from \"../spec/index.js\";\n\n/** A transport OUI constructed. Integrators cannot produce one. */\nexport type OwnedTransport = OUITransport & OUIBranded<\"transport\">;\n\n/** Surface ids as literal types, for the duplicate check. */\ntype SurfaceIds<T extends readonly DefinedSurface<never>[]> = {\n  [K in keyof T]: T[K][\"id\"];\n};\n\nexport interface OUIConfig<TSurfaces extends readonly DefinedSurface<never>[]> {\n  /**\n   * The socket OUI will speak over. The integrator owns the connection —\n   * auth, reconnection, lifecycle — and OUI owns what travels on it.\n   */\n  socket: SocketLike;\n\n  /**\n   * Surfaces produced by `defineSurface`. A plain object with the same shape\n   * will not compile: DefinedSurface is branded.\n   */\n  surfaces: TSurfaces;\n\n  /**\n   * Wire configuration. `namespace` defaults to 'oui' and is the supported way\n   * to change the event prefix — hardcoding it at the call site is what made\n   * this option unreachable in the first integration.\n   */\n  transport?: Omit<OUITransportConfig, \"namespace\"> & { namespace?: string };\n}\n\n/** A live OUI instance. */\nexport interface OUIInstance {\n  /** The transport OUI owns. Exposed for wiring, not for reimplementation. */\n  readonly transport: OwnedTransport;\n\n  /** Manifests for every registered surface, as the agent sees them. */\n  readonly manifests: readonly OUISurface[];\n\n  /** Register every surface and connect. */\n  start(): Promise<void>;\n\n  /** Deregister every surface and disconnect. */\n  stop(): void;\n\n  /** Look up a registered surface by id. */\n  getSurface(id: string): DefinedSurface<never> | undefined;\n}\n\n/**\n * Instantiate OUI.\n *\n * `const` on the type parameter captures surface ids as literal types, which is\n * what allows duplicate detection to name the offending id rather than failing\n * with an unassignable-to-never error.\n */\nexport function createOUI<\n  const TSurfaces extends readonly DefinedSurface<never>[],\n>(\n  config: OUIConfig<TSurfaces> & ValidateSurfaceIds<SurfaceIds<TSurfaces>>,\n): OUIInstance {\n  const {\n    socket,\n    surfaces,\n    transport: transportConfig,\n  } = config as OUIConfig<TSurfaces>;\n\n  // Defensive, not decorative: the compile-time checks only bind when a caller\n  // passes literals. A surface list assembled at runtime, or JS with no types\n  // at all, reaches here unchecked.\n  if (!socket) {\n    throw new Error(\n      \"[OUI] createOUI requires a socket. OUI owns the wire; the integrator owns the connection.\",\n    );\n  }\n  if (!Array.isArray(surfaces) || surfaces.length === 0) {\n    throw new Error(\"[OUI] createOUI requires at least one surface.\");\n  }\n\n  const seen = new Set<string>();\n  for (const surface of surfaces) {\n    if (seen.has(surface.id)) {\n      throw new Error(\n        `[OUI] Duplicate surface id \"${surface.id}\". Registration is keyed by id, so the second would replace the first.`,\n      );\n    }\n    seen.add(surface.id);\n  }\n\n  const transport = brand<\"transport\", OUITransport>(\n    createWebSocketTransport(socket, transportConfig),\n  );\n\n  const byId = new Map(surfaces.map((s) => [s.id, s] as const));\n\n  return {\n    transport,\n    manifests: surfaces.map((s) => s.toManifest()),\n\n    async start() {\n      await transport.connect();\n      for (const surface of surfaces) {\n        transport.registerSurface(surface.toManifest());\n      }\n    },\n\n    stop() {\n      for (const surface of surfaces) {\n        transport.deregisterSurface(surface.id);\n      }\n      transport.disconnect();\n    },\n\n    getSurface(id) {\n      return byId.get(id);\n    },\n  };\n}\n\n/** Re-exported so integrators can name the error type in tests. */\nexport type { OUIConfigError };\n"]}

package/dist/{chunk-JO5LGOB6.js → chunk-ILUTAHUJ.js}

@@ -1,9 +1,18 @@
+import { createWebSocketTransport } from './chunk-YDMGV72W.js';
+
+// src/core/brand.ts
+function brand(value) {
+  return value;
+}
+
 // src/core/define-surface.ts
 function defineSurface(definition) {
   const actionIds = /* @__PURE__ */ new Set();
   for (const action of definition.actions) {
     if (actionIds.has(action.id)) {
-      throw new Error(`[OUI] Duplicate action ID "${action.id}" in surface "${definition.id}"`);
+      throw new Error(
+        `[OUI] Duplicate action ID "${action.id}" in surface "${definition.id}"`
+      );
     }
     actionIds.add(action.id);
   }
@@ -11,12 +20,14 @@ function defineSurface(definition) {
     const obsIds = /* @__PURE__ */ new Set();
     for (const obs of definition.observations) {
       if (obsIds.has(obs.id)) {
-        throw new Error(`[OUI] Duplicate observation ID "${obs.id}" in surface "${definition.id}"`);
+        throw new Error(
+          `[OUI] Duplicate observation ID "${obs.id}" in surface "${definition.id}"`
+        );
       }
       obsIds.add(obs.id);
     }
   }
-  return {
+  return brand({
     ...definition,
     /** Extract the manifest (schema only, no handlers) for transmission to the agent runtime */
     toManifest() {
@@ -35,7 +46,13 @@ function defineSurface(definition) {
     async executeAction(actionId, params, context) {
       const action = definition.actions.find((a) => a.id === actionId);
       if (!action) {
-        return { success: false, error: { code: "ACTION_NOT_FOUND", message: `Action "${actionId}" not found on surface "${definition.id}"` } };
+        return {
+          success: false,
+          error: {
+            code: "ACTION_NOT_FOUND",
+            message: `Action "${actionId}" not found on surface "${definition.id}"`
+          }
+        };
       }
       try {
         return await action.handler(params, context);
@@ -58,7 +75,7 @@ function defineSurface(definition) {
       const action = definition.actions.find((a) => a.id === actionId);
       return action?.polling;
     }
-  };
+  });
 }
 function actionToManifest(action) {
   return {
@@ -83,6 +100,55 @@ function obsToManifest(obs) {
   };
 }
 
-export { defineSurface };
-//# sourceMappingURL=chunk-JO5LGOB6.js.map
-//# sourceMappingURL=chunk-JO5LGOB6.js.map
+// src/core/create-oui.ts
+function createOUI(config) {
+  const {
+    socket,
+    surfaces,
+    transport: transportConfig
+  } = config;
+  if (!socket) {
+    throw new Error(
+      "[OUI] createOUI requires a socket. OUI owns the wire; the integrator owns the connection."
+    );
+  }
+  if (!Array.isArray(surfaces) || surfaces.length === 0) {
+    throw new Error("[OUI] createOUI requires at least one surface.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const surface of surfaces) {
+    if (seen.has(surface.id)) {
+      throw new Error(
+        `[OUI] Duplicate surface id "${surface.id}". Registration is keyed by id, so the second would replace the first.`
+      );
+    }
+    seen.add(surface.id);
+  }
+  const transport = brand(
+    createWebSocketTransport(socket, transportConfig)
+  );
+  const byId = new Map(surfaces.map((s) => [s.id, s]));
+  return {
+    transport,
+    manifests: surfaces.map((s) => s.toManifest()),
+    async start() {
+      await transport.connect();
+      for (const surface of surfaces) {
+        transport.registerSurface(surface.toManifest());
+      }
+    },
+    stop() {
+      for (const surface of surfaces) {
+        transport.deregisterSurface(surface.id);
+      }
+      transport.disconnect();
+    },
+    getSurface(id) {
+      return byId.get(id);
+    }
+  };
+}
+
+export { createOUI, defineSurface };
+//# sourceMappingURL=chunk-ILUTAHUJ.js.map
+//# sourceMappingURL=chunk-ILUTAHUJ.js.map

package/dist/chunk-ILUTAHUJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/brand.ts","../src/core/define-surface.ts","../src/core/create-oui.ts"],"names":[],"mappings":"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","file":"chunk-ILUTAHUJ.js","sourcesContent":["/**\n * Nominal branding for values OUI must construct itself.\n *\n * Structural typing means any object with the right shape satisfies an\n * interface. That is how Closure Studio ended up hand-rolling OUI's transport:\n * `SocketLike` was importable, `OUITransport` was a plain interface, so an\n * integrator could satisfy every type without ever calling OUI. The result was\n * a second implementation of the wire — hardcoded namespace, re-declared\n * payload types on the server, and a dead `action:result` mapping alongside the\n * observation channel that already carried results.\n *\n * A unique symbol cannot be produced outside this module. Branding the types\n * OUI owns turns \"you should use our constructor\" into \"you cannot compile\n * without it\".\n */\n\ndeclare const OUI_BRAND: unique symbol;\n\n/** Marks a value as constructed by OUI itself. */\nexport interface OUIBranded<TKind extends string> {\n  readonly [OUI_BRAND]: TKind;\n}\n\n/**\n * Attach the brand at runtime. The property does not exist at runtime — the\n * symbol is declare-only — so this is a type-level assertion with no cost.\n */\nexport function brand<TKind extends string, T>(\n  value: T,\n): T & OUIBranded<TKind> {\n  return value as T & OUIBranded<TKind>;\n}\n","import type {\n  OUISurface,\n  OUIAction,\n  OUIObservation,\n  OUIActivation,\n  OUIActionPolling,\n  JSONSchema,\n} from \"../spec/index.js\";\nimport { brand, type OUIBranded } from \"./brand.js\";\n\n/**\n * Configuration for defining an OUI surface with handlers.\n * This is the \"integration file\" an app provides — it declares both\n * the schema (what the agent sees) and the implementation (what executes).\n */\nexport interface SurfaceDefinition<TContext = unknown> {\n  id: string;\n  name: string;\n  description: string;\n  version?: string;\n  activation?: OUIActivation;\n  actions: ActionDefinition<TContext>[];\n  observations?: ObservationDefinition[];\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Polling config with an optional resolve handler.\n * The spec's OUIActionPolling is the manifest shape (no functions).\n * The core extends it with the resolve implementation for the runtime.\n */\nexport interface ActionPollingConfig<\n  TContext = unknown,\n> extends OUIActionPolling {\n  /**\n   * Called on each poll interval. Receives the dispatch result from the handler\n   * plus the current context. Return { done: true, data } to stop polling,\n   * or { done: false, data } to continue.\n   */\n  resolve?: (\n    dispatchResult: unknown,\n    context: TContext,\n  ) => Promise<{ done: boolean; data: unknown }>;\n}\n\n/**\n * An action definition includes both the schema (for the agent) and\n * the handler (for execution). This is the single source of truth —\n * no separate YAML, no separate listener, no drift possible.\n */\nexport interface ActionDefinition<TContext = unknown> {\n  id: string;\n  description: string;\n  input: JSONSchema;\n  output?: JSONSchema;\n  confirm?: boolean;\n  async?: boolean;\n\n  /**\n   * Polling/subscription config for async actions.\n   * After the handler returns, the OUI runtime starts polling or subscribing\n   * and pushes observation updates until the operation completes.\n   * Extends the spec's OUIActionPolling with an optional resolve handler.\n   */\n  polling?: ActionPollingConfig<TContext>;\n\n  usage?: string;\n  preconditions?: string;\n  estimatedDuration?: string;\n  tags?: string[];\n\n  /**\n   * The handler that executes when the agent invokes this action.\n   * Receives typed params and a context object (app-specific state/utilities).\n   * Returns a result that the agent sees as the tool output.\n   */\n  handler: (\n    params: Record<string, unknown>,\n    context: TContext,\n  ) => Promise<ActionHandlerResult>;\n}\n\nexport interface ActionHandlerResult {\n  success: boolean;\n  data?: unknown;\n  error?: { code: string; message: string; details?: unknown };\n  /** For async actions: metadata passed to the polling resolver */\n  dispatchMeta?: Record<string, unknown>;\n}\n\nexport interface ObservationDefinition {\n  id: string;\n  description: string;\n  schema: JSONSchema;\n  /** Function that returns the current observation value */\n  getValue?: () => unknown;\n}\n\n/**\n * Define an OUI surface — the single entry point for integrating\n * an application feature with the OUI protocol.\n *\n * This function validates the definition and returns a typed surface\n * object that can be registered with an agent runtime or transport layer.\n *\n * @example\n * ```typescript\n * const mySurface = defineSurface({\n *   id: 'my-feature',\n *   name: 'My Feature',\n *   description: 'Does something cool',\n *   actions: [\n *     {\n *       id: 'do_thing',\n *       description: 'Does the thing',\n *       input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },\n *       handler: async (params) => {\n *         const result = await doTheThing(params.name);\n *         return { success: true, data: result };\n *       },\n *     },\n *   ],\n * });\n * ```\n */\nexport function defineSurface<\n  TContext = unknown,\n  const TId extends string = string,\n>(\n  definition: SurfaceDefinition<TContext> & { id: TId },\n): DefinedSurface<TContext> & { id: TId } {\n  // Validate: no duplicate action IDs\n  const actionIds = new Set<string>();\n  for (const action of definition.actions) {\n    if (actionIds.has(action.id)) {\n      throw new Error(\n        `[OUI] Duplicate action ID \"${action.id}\" in surface \"${definition.id}\"`,\n      );\n    }\n    actionIds.add(action.id);\n  }\n\n  // Validate: no duplicate observation IDs\n  if (definition.observations) {\n    const obsIds = new Set<string>();\n    for (const obs of definition.observations) {\n      if (obsIds.has(obs.id)) {\n        throw new Error(\n          `[OUI] Duplicate observation ID \"${obs.id}\" in surface \"${definition.id}\"`,\n        );\n      }\n      obsIds.add(obs.id);\n    }\n  }\n\n  return brand<\"surface\", unknown>({\n    ...definition,\n\n    /** Extract the manifest (schema only, no handlers) for transmission to the agent runtime */\n    toManifest(): OUISurface {\n      return {\n        id: definition.id,\n        name: definition.name,\n        description: definition.description,\n        version: definition.version,\n        activation: definition.activation,\n        actions: definition.actions.map(actionToManifest),\n        observations: definition.observations?.map(obsToManifest),\n        metadata: definition.metadata,\n      };\n    },\n\n    /** Execute an action by ID with the given params and context */\n    async executeAction(\n      actionId: string,\n      params: Record<string, unknown>,\n      context: TContext,\n    ): Promise<ActionHandlerResult> {\n      const action = definition.actions.find((a) => a.id === actionId);\n      if (!action) {\n        return {\n          success: false,\n          error: {\n            code: \"ACTION_NOT_FOUND\",\n            message: `Action \"${actionId}\" not found on surface \"${definition.id}\"`,\n          },\n        };\n      }\n      try {\n        return await action.handler(params, context);\n      } catch (err) {\n        return {\n          success: false,\n          error: {\n            code: \"ACTION_EXECUTION_ERROR\",\n            message: err instanceof Error ? err.message : String(err),\n          },\n        };\n      }\n    },\n\n    /** Get all action IDs */\n    getActionIds(): string[] {\n      return definition.actions.map((a) => a.id);\n    },\n\n    /** Get the polling config for an action (if async) */\n    getPollingConfig(actionId: string): OUIActionPolling | undefined {\n      const action = definition.actions.find((a) => a.id === actionId);\n      return action?.polling;\n    },\n  }) as DefinedSurface<TContext> & { id: TId };\n}\n\n/** A fully defined surface with both manifest extraction and execution capabilities */\n/**\n * Branded so it can only come from `defineSurface`.\n *\n * Without the brand a plain object literal satisfies this interface\n * structurally, which is how an integrator can assemble a surface that never\n * ran defineSurface's duplicate-id checks and never produced a real manifest.\n */\nexport interface DefinedSurface<TContext = unknown>\n  extends SurfaceDefinition<TContext>, OUIBranded<\"surface\"> {\n  toManifest(): OUISurface;\n  executeAction(\n    actionId: string,\n    params: Record<string, unknown>,\n    context: TContext,\n  ): Promise<ActionHandlerResult>;\n  getActionIds(): string[];\n  /** Get the polling config for an action (if async) */\n  getPollingConfig(actionId: string): OUIActionPolling | undefined;\n}\n\n// ─── Internal helpers ────────────────────────────────────────────────────────\n\nfunction actionToManifest<T>(action: ActionDefinition<T>): OUIAction {\n  return {\n    id: action.id,\n    description: action.description,\n    input: action.input,\n    output: action.output,\n    confirm: action.confirm,\n    async: action.async,\n    polling: action.polling,\n    usage: action.usage,\n    preconditions: action.preconditions,\n    estimatedDuration: action.estimatedDuration,\n    tags: action.tags,\n  };\n}\n\nfunction obsToManifest(obs: ObservationDefinition): OUIObservation {\n  return {\n    id: obs.id,\n    description: obs.description,\n    schema: obs.schema,\n  };\n}\n","/**\n * createOUI — the only supported way to instantiate OUI.\n *\n * WHY THIS EXISTS\n *\n * OUI shipped a correct protocol and a correct transport, and its first\n * integrator used neither. studio-ui imported only the `SocketLike` TYPE from\n * oui-spec and rebuilt the wire by hand: a literal map of protocol types to\n * socket names, `oui:` hardcoded so the configurable namespace was unreachable,\n * payload interfaces re-declared on the server, and an `action:result` channel\n * mapped but never sent — duplicating the observation channel that already\n * carries results.\n *\n * Nothing was wrong with the spec. Nothing enforced it. Structural typing meant\n * every hand-rolled piece type-checked, and both ends agreed only by the\n * coincidence of matching string literals. Rename one and the other keeps\n * compiling and silently stops receiving.\n *\n * So the requirements are gated here:\n *\n *   OUI owns the wire. The integrator provides a socket; it cannot provide a\n *   transport, because `OUITransport` values are branded and only this module\n *   brands them.\n *\n *   OUI owns the result path. Results return through the observation channel,\n *   as `use-surface` already implements. An integrator cannot add a parallel\n *   channel because it cannot construct a transport to add one to.\n *\n *   The integrator owns content. Surfaces, action schemas, observation schemas\n *   and handlers all arrive through `defineSurface`, whose output is branded —\n *   so a plain object shaped like a surface will not compile.\n *\n *   Violations fail at compile time with a message naming the offending id.\n */\nimport type { OUITransport, OUITransportConfig } from \"../transport/types.js\";\nimport type { SocketLike } from \"../transport/websocket.js\";\nimport { createWebSocketTransport } from \"../transport/websocket.js\";\nimport type { DefinedSurface } from \"./define-surface.js\";\nimport { brand, type OUIBranded } from \"./brand.js\";\nimport type { OUIConfigError, ValidateSurfaceIds } from \"./validate.js\";\nimport type { OUISurface } from \"../spec/index.js\";\n\n/** A transport OUI constructed. Integrators cannot produce one. */\nexport type OwnedTransport = OUITransport & OUIBranded<\"transport\">;\n\n/** Surface ids as literal types, for the duplicate check. */\ntype SurfaceIds<T extends readonly DefinedSurface<never>[]> = {\n  [K in keyof T]: T[K][\"id\"];\n};\n\nexport interface OUIConfig<TSurfaces extends readonly DefinedSurface<never>[]> {\n  /**\n   * The socket OUI will speak over. The integrator owns the connection —\n   * auth, reconnection, lifecycle — and OUI owns what travels on it.\n   */\n  socket: SocketLike;\n\n  /**\n   * Surfaces produced by `defineSurface`. A plain object with the same shape\n   * will not compile: DefinedSurface is branded.\n   */\n  surfaces: TSurfaces;\n\n  /**\n   * Wire configuration. `namespace` defaults to 'oui' and is the supported way\n   * to change the event prefix — hardcoding it at the call site is what made\n   * this option unreachable in the first integration.\n   */\n  transport?: Omit<OUITransportConfig, \"namespace\"> & { namespace?: string };\n}\n\n/** A live OUI instance. */\nexport interface OUIInstance {\n  /** The transport OUI owns. Exposed for wiring, not for reimplementation. */\n  readonly transport: OwnedTransport;\n\n  /** Manifests for every registered surface, as the agent sees them. */\n  readonly manifests: readonly OUISurface[];\n\n  /** Register every surface and connect. */\n  start(): Promise<void>;\n\n  /** Deregister every surface and disconnect. */\n  stop(): void;\n\n  /** Look up a registered surface by id. */\n  getSurface(id: string): DefinedSurface<never> | undefined;\n}\n\n/**\n * Instantiate OUI.\n *\n * `const` on the type parameter captures surface ids as literal types, which is\n * what allows duplicate detection to name the offending id rather than failing\n * with an unassignable-to-never error.\n */\nexport function createOUI<\n  const TSurfaces extends readonly DefinedSurface<never>[],\n>(\n  config: OUIConfig<TSurfaces> & ValidateSurfaceIds<SurfaceIds<TSurfaces>>,\n): OUIInstance {\n  const {\n    socket,\n    surfaces,\n    transport: transportConfig,\n  } = config as OUIConfig<TSurfaces>;\n\n  // Defensive, not decorative: the compile-time checks only bind when a caller\n  // passes literals. A surface list assembled at runtime, or JS with no types\n  // at all, reaches here unchecked.\n  if (!socket) {\n    throw new Error(\n      \"[OUI] createOUI requires a socket. OUI owns the wire; the integrator owns the connection.\",\n    );\n  }\n  if (!Array.isArray(surfaces) || surfaces.length === 0) {\n    throw new Error(\"[OUI] createOUI requires at least one surface.\");\n  }\n\n  const seen = new Set<string>();\n  for (const surface of surfaces) {\n    if (seen.has(surface.id)) {\n      throw new Error(\n        `[OUI] Duplicate surface id \"${surface.id}\". Registration is keyed by id, so the second would replace the first.`,\n      );\n    }\n    seen.add(surface.id);\n  }\n\n  const transport = brand<\"transport\", OUITransport>(\n    createWebSocketTransport(socket, transportConfig),\n  );\n\n  const byId = new Map(surfaces.map((s) => [s.id, s] as const));\n\n  return {\n    transport,\n    manifests: surfaces.map((s) => s.toManifest()),\n\n    async start() {\n      await transport.connect();\n      for (const surface of surfaces) {\n        transport.registerSurface(surface.toManifest());\n      }\n    },\n\n    stop() {\n      for (const surface of surfaces) {\n        transport.deregisterSurface(surface.id);\n      }\n      transport.disconnect();\n    },\n\n    getSurface(id) {\n      return byId.get(id);\n    },\n  };\n}\n\n/** Re-exported so integrators can name the error type in tests. */\nexport type { OUIConfigError };\n"]}