oui-spec 0.1.0 → 0.3.0

package/dist/{chunk-3DCIL4FV.cjs → chunk-ZKM4XWAB.cjs}

@@ -10,5 +10,5 @@ var OUI_PROTOCOL_EVENTS = {
 };
 
 exports.OUI_PROTOCOL_EVENTS = OUI_PROTOCOL_EVENTS;
-//# sourceMappingURL=chunk-3DCIL4FV.cjs.map
-//# sourceMappingURL=chunk-3DCIL4FV.cjs.map
+//# sourceMappingURL=chunk-ZKM4XWAB.cjs.map
+//# sourceMappingURL=chunk-ZKM4XWAB.cjs.map

package/dist/chunk-ZKM4XWAB.cjs.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-ZKM4XWAB.cjs","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/core/index.cjs

@@ -1,17 +1,26 @@
 'use strict';
 
-var chunkLEXIU2MH_cjs = require('../chunk-LEXIU2MH.cjs');
-var chunk3DCIL4FV_cjs = require('../chunk-3DCIL4FV.cjs');
+var chunkKNWGQRXL_cjs = require('../chunk-KNWGQRXL.cjs');
+var chunkZKM4XWAB_cjs = require('../chunk-ZKM4XWAB.cjs');
+require('../chunk-DCVVTP3V.cjs');
 
 
 
+Object.defineProperty(exports, "createOUI", {
+  enumerable: true,
+  get: function () { return chunkKNWGQRXL_cjs.createOUI; }
+});
+Object.defineProperty(exports, "createSurfaceRuntime", {
+  enumerable: true,
+  get: function () { return chunkKNWGQRXL_cjs.createSurfaceRuntime; }
+});
 Object.defineProperty(exports, "defineSurface", {
   enumerable: true,
-  get: function () { return chunkLEXIU2MH_cjs.defineSurface; }
+  get: function () { return chunkKNWGQRXL_cjs.defineSurface; }
 });
 Object.defineProperty(exports, "OUI_PROTOCOL_EVENTS", {
   enumerable: true,
-  get: function () { return chunk3DCIL4FV_cjs.OUI_PROTOCOL_EVENTS; }
+  get: function () { return chunkZKM4XWAB_cjs.OUI_PROTOCOL_EVENTS; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/core/index.d.cts

@@ -1,120 +1,141 @@
-import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface } from '../spec/index.cjs';
-export { OUIAction, OUIActionRequest, OUIActionResult, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from '../spec/index.cjs';
+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--2lZGB7Z.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--2lZGB7Z.cjs';
+import { S as SocketLike, d as OUITransportConfig, c as OUITransport } from '../websocket-YfWILdZ4.cjs';
 
 /**
- * Configuration for defining an OUI surface with handlers.
- * This is the "integration file" an app provides — it declares both
- * the schema (what the agent sees) and the implementation (what executes).
+ * Compile-time validation for a createOUI configuration.
+ *
+ * These types resolve to a descriptive error type when a rule is broken, so the
+ * failure surfaces at the call site with a message naming the offending id —
+ * not as `Type 'X' is not assignable to type 'never'`.
+ *
+ * Everything here was previously a runtime `throw` inside defineSurface, or
+ * nothing at all. A duplicate action id threw when the surface was constructed,
+ * which in a React app means at render, in a browser, after a deploy. The same
+ * mistake is now a red squiggle.
  */
-interface SurfaceDefinition<TContext = unknown> {
-    id: string;
-    name: string;
-    description: string;
-    version?: string;
-    activation?: OUIActivation;
-    actions: ActionDefinition<TContext>[];
-    observations?: ObservationDefinition[];
-    metadata?: Record<string, unknown>;
-}
+/** A readable compile error. The message lands in the tooltip. */
+type OUIConfigError<TMessage extends string> = {
+    readonly __ouiError: TMessage;
+};
+/** Ids appearing more than once in a tuple of string literals. */
+type Duplicates<T extends readonly string[], Seen extends string = never> = T extends readonly [
+    infer Head extends string,
+    ...infer Rest extends readonly string[]
+] ? Head extends Seen ? Head | Duplicates<Rest, Seen | Head> : Duplicates<Rest, Seen | Head> : never;
 /**
- * Polling config with an optional resolve handler.
- * The spec's OUIActionPolling is the manifest shape (no functions).
- * The core extends it with the resolve implementation for the runtime.
+ * `never` when every id is unique, otherwise the duplicated ids.
+ * Exported for tests — a validation type nobody can assert against is a
+ * validation type nobody can trust.
  */
-interface ActionPollingConfig<TContext = unknown> extends OUIActionPolling {
-    /**
-     * Called on each poll interval. Receives the dispatch result from the handler
-     * plus the current context. Return { done: true, data } to stop polling,
-     * or { done: false, data } to continue.
-     */
-    resolve?: (dispatchResult: unknown, context: TContext) => Promise<{
-        done: boolean;
-        data: unknown;
-    }>;
-}
+type DuplicateIds<T extends readonly string[]> = Duplicates<T>;
+type IsEmpty<T extends readonly unknown[]> = T extends readonly [] ? true : false;
 /**
- * An action definition includes both the schema (for the agent) and
- * the handler (for execution). This is the single source of truth —
- * no separate YAML, no separate listener, no drift possible.
+ * Validate the surface list, returning the config type when it passes and an
+ * OUIConfigError when it does not.
+ *
+ * The rules, and why each exists:
+ *
+ *   Non-empty — an OUI instance with no surfaces registers nothing and
+ *   dispatches nowhere. It looks connected and does nothing, which is the
+ *   failure mode this whole design is trying to eliminate.
+ *
+ *   Unique surface ids — registration is keyed by surface id, so a duplicate
+ *   silently replaces the first surface's manifest. The agent then sees one
+ *   surface's actions attributed to the other.
  */
-interface ActionDefinition<TContext = unknown> {
-    id: string;
-    description: string;
-    input: JSONSchema;
-    output?: JSONSchema;
-    confirm?: boolean;
-    async?: boolean;
+type ValidateSurfaceIds<TIds extends readonly string[]> = IsEmpty<TIds> extends true ? OUIConfigError<"createOUI requires at least one surface. An instance with no surfaces registers nothing and dispatches nowhere."> : [DuplicateIds<TIds>] extends [never] ? unknown : OUIConfigError<`Duplicate surface id: "${DuplicateIds<TIds>}". Surface registration is keyed by id, so the second would silently replace the first.`>;
+
+/**
+ * createOUI — a fixed set of surfaces announced over one socket.
+ *
+ * For a client whose surfaces come and go (a React app, where a page's
+ * surfaces mount with the page), use `createSurfaceRuntime` instead: it keeps
+ * the client's own record of what is mounted and answers every request.
+ *
+ * WHY THIS EXISTS
+ *
+ * OUI shipped a correct protocol and a correct transport, and its first
+ * integrator used neither. studio-ui imported only the `SocketLike` TYPE from
+ * oui-spec and rebuilt the wire by hand: a literal map of protocol types to
+ * socket names, `oui:` hardcoded so the configurable namespace was unreachable,
+ * payload interfaces re-declared on the server, and an `action:result` channel
+ * mapped but never sent — duplicating the observation channel that already
+ * carries results.
+ *
+ * Nothing was wrong with the spec. Nothing enforced it. Structural typing meant
+ * every hand-rolled piece type-checked, and both ends agreed only by the
+ * coincidence of matching string literals. Rename one and the other keeps
+ * compiling and silently stops receiving.
+ *
+ * So the requirements are gated here:
+ *
+ *   OUI owns the wire. The integrator provides a socket; it cannot provide a
+ *   transport, because `OUITransport` values are branded and only this module
+ *   brands them.
+ *
+ *   OUI owns the result path. Every dispatch carries a requestId and is
+ *   answered on OUI's result channel. An integrator cannot add a parallel
+ *   channel because it cannot construct a transport to add one to.
+ *
+ *   The integrator owns content. Surfaces, action schemas, observation schemas
+ *   and handlers all arrive through `defineSurface`, whose output is branded —
+ *   so a plain object shaped like a surface will not compile.
+ *
+ *   Violations fail at compile time with a message naming the offending id.
+ */
+
+/** A transport OUI constructed. Integrators cannot produce one. */
+type OwnedTransport = OUITransport & OUIBranded<"transport">;
+/** Surface ids as literal types, for the duplicate check. */
+type SurfaceIds<T extends readonly DefinedSurface<never>[]> = {
+    [K in keyof T]: T[K]["id"];
+};
+interface OUIConfig<TSurfaces extends readonly DefinedSurface<never>[]> {
     /**
-     * Polling/subscription config for async actions.
-     * After the handler returns, the OUI runtime starts polling or subscribing
-     * and pushes observation updates until the operation completes.
-     * Extends the spec's OUIActionPolling with an optional resolve handler.
+     * The socket OUI will speak over. The integrator owns the connection —
+     * auth, reconnection, lifecycle — and OUI owns what travels on it.
      */
-    polling?: ActionPollingConfig<TContext>;
-    usage?: string;
-    preconditions?: string;
-    estimatedDuration?: string;
-    tags?: string[];
+    socket: SocketLike;
     /**
-     * The handler that executes when the agent invokes this action.
-     * Receives typed params and a context object (app-specific state/utilities).
-     * Returns a result that the agent sees as the tool output.
+     * Surfaces produced by `defineSurface`. A plain object with the same shape
+     * will not compile: DefinedSurface is branded.
      */
-    handler: (params: Record<string, unknown>, context: TContext) => Promise<ActionHandlerResult>;
-}
-interface ActionHandlerResult {
-    success: boolean;
-    data?: unknown;
-    error?: {
-        code: string;
-        message: string;
-        details?: unknown;
+    surfaces: TSurfaces;
+    /**
+     * Wire configuration. `namespace` defaults to 'oui' and is the supported way
+     * to change the event prefix — hardcoding it at the call site is what made
+     * this option unreachable in the first integration.
+     */
+    transport?: Omit<OUITransportConfig, "namespace"> & {
+        namespace?: string;
     };
-    /** For async actions: metadata passed to the polling resolver */
-    dispatchMeta?: Record<string, unknown>;
 }
-interface ObservationDefinition {
-    id: string;
-    description: string;
-    schema: JSONSchema;
-    /** Function that returns the current observation value */
-    getValue?: () => unknown;
+/** A live OUI instance. */
+interface OUIInstance {
+    /** The transport OUI owns. Exposed for wiring, not for reimplementation. */
+    readonly transport: OwnedTransport;
+    /** Manifests for every registered surface, as the agent sees them. */
+    readonly manifests: readonly OUISurface[];
+    /** Register every surface and connect. */
+    start(): Promise<void>;
+    /**
+     * Deregister every surface and detach OUI from the socket. The socket stays
+     * connected: the integrator owns it, and other code may share it.
+     */
+    stop(): void;
+    /** Look up a registered surface by id. */
+    getSurface(id: string): DefinedSurface<never> | undefined;
 }
 /**
- * Define an OUI surface — the single entry point for integrating
- * an application feature with the OUI protocol.
- *
- * This function validates the definition and returns a typed surface
- * object that can be registered with an agent runtime or transport layer.
+ * Instantiate OUI.
  *
- * @example
- * ```typescript
- * const mySurface = defineSurface({
- *   id: 'my-feature',
- *   name: 'My Feature',
- *   description: 'Does something cool',
- *   actions: [
- *     {
- *       id: 'do_thing',
- *       description: 'Does the thing',
- *       input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
- *       handler: async (params) => {
- *         const result = await doTheThing(params.name);
- *         return { success: true, data: result };
- *       },
- *     },
- *   ],
- * });
- * ```
+ * `const` on the type parameter captures surface ids as literal types, which is
+ * what allows duplicate detection to name the offending id rather than failing
+ * with an unassignable-to-never error.
  */
-declare function defineSurface<TContext = unknown>(definition: SurfaceDefinition<TContext>): DefinedSurface<TContext>;
-/** A fully defined surface with both manifest extraction and execution capabilities */
-interface DefinedSurface<TContext = unknown> extends SurfaceDefinition<TContext> {
-    toManifest(): OUISurface;
-    executeAction(actionId: string, params: Record<string, unknown>, context: TContext): Promise<ActionHandlerResult>;
-    getActionIds(): string[];
-    /** Get the polling config for an action (if async) */
-    getPollingConfig(actionId: string): OUIActionPolling | undefined;
-}
+declare function createOUI<const TSurfaces extends readonly DefinedSurface<never>[]>(config: OUIConfig<TSurfaces> & ValidateSurfaceIds<SurfaceIds<TSurfaces>>): OUIInstance;
 
-export { type ActionDefinition, type ActionHandlerResult, type ActionPollingConfig, type DefinedSurface, JSONSchema, OUIActivation, OUISurface, type ObservationDefinition, type SurfaceDefinition, defineSurface };
+export { DefinedSurface, type DuplicateIds, OUIBranded, type OUIConfig, type OUIConfigError, type OUIInstance, OUISurface, type OwnedTransport, type ValidateSurfaceIds, createOUI };

package/dist/core/index.d.ts

@@ -1,120 +1,141 @@
-import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface } from '../spec/index.js';
-export { OUIAction, OUIActionRequest, OUIActionResult, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from '../spec/index.js';
+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-Dj_nhd7r.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-Dj_nhd7r.js';
+import { S as SocketLike, d as OUITransportConfig, c as OUITransport } from '../websocket-c5tIUWY5.js';
 
 /**
- * Configuration for defining an OUI surface with handlers.
- * This is the "integration file" an app provides — it declares both
- * the schema (what the agent sees) and the implementation (what executes).
+ * Compile-time validation for a createOUI configuration.
+ *
+ * These types resolve to a descriptive error type when a rule is broken, so the
+ * failure surfaces at the call site with a message naming the offending id —
+ * not as `Type 'X' is not assignable to type 'never'`.
+ *
+ * Everything here was previously a runtime `throw` inside defineSurface, or
+ * nothing at all. A duplicate action id threw when the surface was constructed,
+ * which in a React app means at render, in a browser, after a deploy. The same
+ * mistake is now a red squiggle.
  */
-interface SurfaceDefinition<TContext = unknown> {
-    id: string;
-    name: string;
-    description: string;
-    version?: string;
-    activation?: OUIActivation;
-    actions: ActionDefinition<TContext>[];
-    observations?: ObservationDefinition[];
-    metadata?: Record<string, unknown>;
-}
+/** A readable compile error. The message lands in the tooltip. */
+type OUIConfigError<TMessage extends string> = {
+    readonly __ouiError: TMessage;
+};
+/** Ids appearing more than once in a tuple of string literals. */
+type Duplicates<T extends readonly string[], Seen extends string = never> = T extends readonly [
+    infer Head extends string,
+    ...infer Rest extends readonly string[]
+] ? Head extends Seen ? Head | Duplicates<Rest, Seen | Head> : Duplicates<Rest, Seen | Head> : never;
 /**
- * Polling config with an optional resolve handler.
- * The spec's OUIActionPolling is the manifest shape (no functions).
- * The core extends it with the resolve implementation for the runtime.
+ * `never` when every id is unique, otherwise the duplicated ids.
+ * Exported for tests — a validation type nobody can assert against is a
+ * validation type nobody can trust.
  */
-interface ActionPollingConfig<TContext = unknown> extends OUIActionPolling {
-    /**
-     * Called on each poll interval. Receives the dispatch result from the handler
-     * plus the current context. Return { done: true, data } to stop polling,
-     * or { done: false, data } to continue.
-     */
-    resolve?: (dispatchResult: unknown, context: TContext) => Promise<{
-        done: boolean;
-        data: unknown;
-    }>;
-}
+type DuplicateIds<T extends readonly string[]> = Duplicates<T>;
+type IsEmpty<T extends readonly unknown[]> = T extends readonly [] ? true : false;
 /**
- * An action definition includes both the schema (for the agent) and
- * the handler (for execution). This is the single source of truth —
- * no separate YAML, no separate listener, no drift possible.
+ * Validate the surface list, returning the config type when it passes and an
+ * OUIConfigError when it does not.
+ *
+ * The rules, and why each exists:
+ *
+ *   Non-empty — an OUI instance with no surfaces registers nothing and
+ *   dispatches nowhere. It looks connected and does nothing, which is the
+ *   failure mode this whole design is trying to eliminate.
+ *
+ *   Unique surface ids — registration is keyed by surface id, so a duplicate
+ *   silently replaces the first surface's manifest. The agent then sees one
+ *   surface's actions attributed to the other.
  */
-interface ActionDefinition<TContext = unknown> {
-    id: string;
-    description: string;
-    input: JSONSchema;
-    output?: JSONSchema;
-    confirm?: boolean;
-    async?: boolean;
+type ValidateSurfaceIds<TIds extends readonly string[]> = IsEmpty<TIds> extends true ? OUIConfigError<"createOUI requires at least one surface. An instance with no surfaces registers nothing and dispatches nowhere."> : [DuplicateIds<TIds>] extends [never] ? unknown : OUIConfigError<`Duplicate surface id: "${DuplicateIds<TIds>}". Surface registration is keyed by id, so the second would silently replace the first.`>;
+
+/**
+ * createOUI — a fixed set of surfaces announced over one socket.
+ *
+ * For a client whose surfaces come and go (a React app, where a page's
+ * surfaces mount with the page), use `createSurfaceRuntime` instead: it keeps
+ * the client's own record of what is mounted and answers every request.
+ *
+ * WHY THIS EXISTS
+ *
+ * OUI shipped a correct protocol and a correct transport, and its first
+ * integrator used neither. studio-ui imported only the `SocketLike` TYPE from
+ * oui-spec and rebuilt the wire by hand: a literal map of protocol types to
+ * socket names, `oui:` hardcoded so the configurable namespace was unreachable,
+ * payload interfaces re-declared on the server, and an `action:result` channel
+ * mapped but never sent — duplicating the observation channel that already
+ * carries results.
+ *
+ * Nothing was wrong with the spec. Nothing enforced it. Structural typing meant
+ * every hand-rolled piece type-checked, and both ends agreed only by the
+ * coincidence of matching string literals. Rename one and the other keeps
+ * compiling and silently stops receiving.
+ *
+ * So the requirements are gated here:
+ *
+ *   OUI owns the wire. The integrator provides a socket; it cannot provide a
+ *   transport, because `OUITransport` values are branded and only this module
+ *   brands them.
+ *
+ *   OUI owns the result path. Every dispatch carries a requestId and is
+ *   answered on OUI's result channel. An integrator cannot add a parallel
+ *   channel because it cannot construct a transport to add one to.
+ *
+ *   The integrator owns content. Surfaces, action schemas, observation schemas
+ *   and handlers all arrive through `defineSurface`, whose output is branded —
+ *   so a plain object shaped like a surface will not compile.
+ *
+ *   Violations fail at compile time with a message naming the offending id.
+ */
+
+/** A transport OUI constructed. Integrators cannot produce one. */
+type OwnedTransport = OUITransport & OUIBranded<"transport">;
+/** Surface ids as literal types, for the duplicate check. */
+type SurfaceIds<T extends readonly DefinedSurface<never>[]> = {
+    [K in keyof T]: T[K]["id"];
+};
+interface OUIConfig<TSurfaces extends readonly DefinedSurface<never>[]> {
     /**
-     * Polling/subscription config for async actions.
-     * After the handler returns, the OUI runtime starts polling or subscribing
-     * and pushes observation updates until the operation completes.
-     * Extends the spec's OUIActionPolling with an optional resolve handler.
+     * The socket OUI will speak over. The integrator owns the connection —
+     * auth, reconnection, lifecycle — and OUI owns what travels on it.
      */
-    polling?: ActionPollingConfig<TContext>;
-    usage?: string;
-    preconditions?: string;
-    estimatedDuration?: string;
-    tags?: string[];
+    socket: SocketLike;
     /**
-     * The handler that executes when the agent invokes this action.
-     * Receives typed params and a context object (app-specific state/utilities).
-     * Returns a result that the agent sees as the tool output.
+     * Surfaces produced by `defineSurface`. A plain object with the same shape
+     * will not compile: DefinedSurface is branded.
      */
-    handler: (params: Record<string, unknown>, context: TContext) => Promise<ActionHandlerResult>;
-}
-interface ActionHandlerResult {
-    success: boolean;
-    data?: unknown;
-    error?: {
-        code: string;
-        message: string;
-        details?: unknown;
+    surfaces: TSurfaces;
+    /**
+     * Wire configuration. `namespace` defaults to 'oui' and is the supported way
+     * to change the event prefix — hardcoding it at the call site is what made
+     * this option unreachable in the first integration.
+     */
+    transport?: Omit<OUITransportConfig, "namespace"> & {
+        namespace?: string;
     };
-    /** For async actions: metadata passed to the polling resolver */
-    dispatchMeta?: Record<string, unknown>;
 }
-interface ObservationDefinition {
-    id: string;
-    description: string;
-    schema: JSONSchema;
-    /** Function that returns the current observation value */
-    getValue?: () => unknown;
+/** A live OUI instance. */
+interface OUIInstance {
+    /** The transport OUI owns. Exposed for wiring, not for reimplementation. */
+    readonly transport: OwnedTransport;
+    /** Manifests for every registered surface, as the agent sees them. */
+    readonly manifests: readonly OUISurface[];
+    /** Register every surface and connect. */
+    start(): Promise<void>;
+    /**
+     * Deregister every surface and detach OUI from the socket. The socket stays
+     * connected: the integrator owns it, and other code may share it.
+     */
+    stop(): void;
+    /** Look up a registered surface by id. */
+    getSurface(id: string): DefinedSurface<never> | undefined;
 }
 /**
- * Define an OUI surface — the single entry point for integrating
- * an application feature with the OUI protocol.
- *
- * This function validates the definition and returns a typed surface
- * object that can be registered with an agent runtime or transport layer.
+ * Instantiate OUI.
  *
- * @example
- * ```typescript
- * const mySurface = defineSurface({
- *   id: 'my-feature',
- *   name: 'My Feature',
- *   description: 'Does something cool',
- *   actions: [
- *     {
- *       id: 'do_thing',
- *       description: 'Does the thing',
- *       input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
- *       handler: async (params) => {
- *         const result = await doTheThing(params.name);
- *         return { success: true, data: result };
- *       },
- *     },
- *   ],
- * });
- * ```
+ * `const` on the type parameter captures surface ids as literal types, which is
+ * what allows duplicate detection to name the offending id rather than failing
+ * with an unassignable-to-never error.
  */
-declare function defineSurface<TContext = unknown>(definition: SurfaceDefinition<TContext>): DefinedSurface<TContext>;
-/** A fully defined surface with both manifest extraction and execution capabilities */
-interface DefinedSurface<TContext = unknown> extends SurfaceDefinition<TContext> {
-    toManifest(): OUISurface;
-    executeAction(actionId: string, params: Record<string, unknown>, context: TContext): Promise<ActionHandlerResult>;
-    getActionIds(): string[];
-    /** Get the polling config for an action (if async) */
-    getPollingConfig(actionId: string): OUIActionPolling | undefined;
-}
+declare function createOUI<const TSurfaces extends readonly DefinedSurface<never>[]>(config: OUIConfig<TSurfaces> & ValidateSurfaceIds<SurfaceIds<TSurfaces>>): OUIInstance;
 
-export { type ActionDefinition, type ActionHandlerResult, type ActionPollingConfig, type DefinedSurface, JSONSchema, OUIActivation, OUISurface, type ObservationDefinition, type SurfaceDefinition, defineSurface };
+export { DefinedSurface, type DuplicateIds, OUIBranded, type OUIConfig, type OUIConfigError, type OUIInstance, OUISurface, type OwnedTransport, type ValidateSurfaceIds, createOUI };

package/dist/core/index.js

@@ -1,4 +1,5 @@
-export { defineSurface } from '../chunk-JO5LGOB6.js';
-export { OUI_PROTOCOL_EVENTS } from '../chunk-CVUUSPF4.js';
+export { createOUI, createSurfaceRuntime, defineSurface } from '../chunk-TRNVXAB5.js';
+export { OUI_PROTOCOL_EVENTS } from '../chunk-BMCL2K74.js';
+import '../chunk-F3WKIRAU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.cjs

@@ -1,35 +1,56 @@
 'use strict';
 
-var chunkLEXIU2MH_cjs = require('./chunk-LEXIU2MH.cjs');
-var chunk3DCIL4FV_cjs = require('./chunk-3DCIL4FV.cjs');
-var chunk2ON5IEXB_cjs = require('./chunk-2ON5IEXB.cjs');
-var chunkWZXUKJ7E_cjs = require('./chunk-WZXUKJ7E.cjs');
+var chunkKNWGQRXL_cjs = require('./chunk-KNWGQRXL.cjs');
+var chunkZKM4XWAB_cjs = require('./chunk-ZKM4XWAB.cjs');
+var chunkF3SKRAGU_cjs = require('./chunk-F3SKRAGU.cjs');
+var chunkROGKEMLL_cjs = require('./chunk-ROGKEMLL.cjs');
+var chunkDCVVTP3V_cjs = require('./chunk-DCVVTP3V.cjs');
 
 
 
+Object.defineProperty(exports, "createOUI", {
+  enumerable: true,
+  get: function () { return chunkKNWGQRXL_cjs.createOUI; }
+});
+Object.defineProperty(exports, "createSurfaceRuntime", {
+  enumerable: true,
+  get: function () { return chunkKNWGQRXL_cjs.createSurfaceRuntime; }
+});
 Object.defineProperty(exports, "defineSurface", {
   enumerable: true,
-  get: function () { return chunkLEXIU2MH_cjs.defineSurface; }
+  get: function () { return chunkKNWGQRXL_cjs.defineSurface; }
 });
 Object.defineProperty(exports, "OUI_PROTOCOL_EVENTS", {
   enumerable: true,
-  get: function () { return chunk3DCIL4FV_cjs.OUI_PROTOCOL_EVENTS; }
+  get: function () { return chunkZKM4XWAB_cjs.OUI_PROTOCOL_EVENTS; }
+});
+Object.defineProperty(exports, "SurfaceRuntimeProvider", {
+  enumerable: true,
+  get: function () { return chunkF3SKRAGU_cjs.SurfaceRuntimeProvider; }
 });
 Object.defineProperty(exports, "useObservation", {
   enumerable: true,
-  get: function () { return chunk2ON5IEXB_cjs.useObservation; }
+  get: function () { return chunkF3SKRAGU_cjs.useObservation; }
 });
 Object.defineProperty(exports, "useSurface", {
   enumerable: true,
-  get: function () { return chunk2ON5IEXB_cjs.useSurface; }
+  get: function () { return chunkF3SKRAGU_cjs.useSurface; }
+});
+Object.defineProperty(exports, "useSurfaceHold", {
+  enumerable: true,
+  get: function () { return chunkF3SKRAGU_cjs.useSurfaceHold; }
+});
+Object.defineProperty(exports, "useSurfaceRuntime", {
+  enumerable: true,
+  get: function () { return chunkF3SKRAGU_cjs.useSurfaceRuntime; }
 });
 Object.defineProperty(exports, "createDirectTransportPair", {
   enumerable: true,
-  get: function () { return chunkWZXUKJ7E_cjs.createDirectTransportPair; }
+  get: function () { return chunkROGKEMLL_cjs.createDirectTransportPair; }
 });
 Object.defineProperty(exports, "createWebSocketTransport", {
   enumerable: true,
-  get: function () { return chunkWZXUKJ7E_cjs.createWebSocketTransport; }
+  get: function () { return chunkDCVVTP3V_cjs.createWebSocketTransport; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map