oui-spec 0.2.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,22 +1,26 @@
 'use strict';
 
-var chunkHK7OXB2W_cjs = require('../chunk-HK7OXB2W.cjs');
-var chunk3DCIL4FV_cjs = require('../chunk-3DCIL4FV.cjs');
-require('../chunk-MTMEW6MM.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 chunkHK7OXB2W_cjs.createOUI; }
+  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 chunkHK7OXB2W_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,8 +1,8 @@
 import { OUISurface } from '../spec/index.cjs';
-export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from '../spec/index.cjs';
-import { D as DefinedSurface, O as OUIBranded } from '../define-surface-D6XPtoqu.cjs';
-export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, c as ObservationDefinition, S as SurfaceDefinition, d as defineSurface } from '../define-surface-D6XPtoqu.cjs';
-import { S as SocketLike, c as OUITransportConfig, b as OUITransport } from '../websocket-CrI0yRNo.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';
 
 /**
  * Compile-time validation for a createOUI configuration.
@@ -49,7 +49,11 @@ type IsEmpty<T extends readonly unknown[]> = T extends readonly [] ? true : fals
 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 — the only supported way to instantiate OUI.
+ * 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
  *
@@ -72,8 +76,8 @@ type ValidateSurfaceIds<TIds extends readonly string[]> = IsEmpty<TIds> extends
  *   transport, because `OUITransport` values are branded and only this module
  *   brands them.
  *
- *   OUI owns the result path. Results return through the observation channel,
- *   as `use-surface` already implements. An integrator cannot add a parallel
+ *   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
@@ -117,7 +121,10 @@ interface OUIInstance {
     readonly manifests: readonly OUISurface[];
     /** Register every surface and connect. */
     start(): Promise<void>;
-    /** Deregister every surface and disconnect. */
+    /**
+     * 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;

package/dist/core/index.d.ts

@@ -1,8 +1,8 @@
 import { OUISurface } from '../spec/index.js';
-export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from '../spec/index.js';
-import { D as DefinedSurface, O as OUIBranded } from '../define-surface-DXBop-uB.js';
-export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, c as ObservationDefinition, S as SurfaceDefinition, d as defineSurface } from '../define-surface-DXBop-uB.js';
-import { S as SocketLike, c as OUITransportConfig, b as OUITransport } from '../websocket-CiWvkaz_.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';
 
 /**
  * Compile-time validation for a createOUI configuration.
@@ -49,7 +49,11 @@ type IsEmpty<T extends readonly unknown[]> = T extends readonly [] ? true : fals
 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 — the only supported way to instantiate OUI.
+ * 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
  *
@@ -72,8 +76,8 @@ type ValidateSurfaceIds<TIds extends readonly string[]> = IsEmpty<TIds> extends
  *   transport, because `OUITransport` values are branded and only this module
  *   brands them.
  *
- *   OUI owns the result path. Results return through the observation channel,
- *   as `use-surface` already implements. An integrator cannot add a parallel
+ *   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
@@ -117,7 +121,10 @@ interface OUIInstance {
     readonly manifests: readonly OUISurface[];
     /** Register every surface and connect. */
     start(): Promise<void>;
-    /** Deregister every surface and disconnect. */
+    /**
+     * 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;

package/dist/core/index.js

@@ -1,5 +1,5 @@
-export { createOUI, defineSurface } from '../chunk-ILUTAHUJ.js';
-export { OUI_PROTOCOL_EVENTS } from '../chunk-CVUUSPF4.js';
-import '../chunk-YDMGV72W.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,40 +1,56 @@
 'use strict';
 
-var chunkHK7OXB2W_cjs = require('./chunk-HK7OXB2W.cjs');
-var chunk3DCIL4FV_cjs = require('./chunk-3DCIL4FV.cjs');
-var chunk2ON5IEXB_cjs = require('./chunk-2ON5IEXB.cjs');
-var chunk5TQ6AVQH_cjs = require('./chunk-5TQ6AVQH.cjs');
-var chunkMTMEW6MM_cjs = require('./chunk-MTMEW6MM.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 chunkHK7OXB2W_cjs.createOUI; }
+  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 chunkHK7OXB2W_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 chunk5TQ6AVQH_cjs.createDirectTransportPair; }
+  get: function () { return chunkROGKEMLL_cjs.createDirectTransportPair; }
 });
 Object.defineProperty(exports, "createWebSocketTransport", {
   enumerable: true,
-  get: function () { return chunkMTMEW6MM_cjs.createWebSocketTransport; }
+  get: function () { return chunkDCVVTP3V_cjs.createWebSocketTransport; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -1,6 +1,7 @@
-export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurface, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from './spec/index.cjs';
-export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, D as DefinedSurface, O as OUIBranded, c as ObservationDefinition, S as SurfaceDefinition, d as defineSurface } from './define-surface-D6XPtoqu.cjs';
+export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationSnapshot, OUIObservationUpdate, OUIProtocolEvent, OUISurface, OUISurfaceDeregistration, OUISurfaceRegistration, OUISurfaceSnapshot, OUI_PROTOCOL_EVENTS } from './spec/index.cjs';
+export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, D as DefinedSurface, M as MountedSurface, O as OUIBranded, c as ObservationDefinition, S as SettleOptions, d as SurfaceDefinition, e as SurfaceRuntime, f as SurfaceRuntimeOptions, g as createSurfaceRuntime, h as defineSurface } from './surface-runtime--2lZGB7Z.cjs';
 export { DuplicateIds, OUIConfig, OUIConfigError, OUIInstance, OwnedTransport, ValidateSurfaceIds, createOUI } from './core/index.cjs';
-export { UseSurfaceOptions, useObservation, useSurface } from './react/index.cjs';
-export { O as OUIActionHandler, a as OUIObservationHandler, b as OUITransport, c as OUITransportConfig, S as SocketLike, d as createWebSocketTransport } from './websocket-CrI0yRNo.cjs';
+export { SurfaceRuntimeProvider, SurfaceRuntimeProviderProps, UseSurfaceOptions, UseSurfaceResult, useObservation, useSurface, useSurfaceHold, useSurfaceRuntime } from './react/index.cjs';
+export { O as OUIActionHandler, a as OUIObservationHandler, b as OUIResultHandler, c as OUITransport, d as OUITransportConfig, S as SocketLike, e as createWebSocketTransport } from './websocket-YfWILdZ4.cjs';
 export { createDirectTransportPair } from './transport/index.cjs';
+import 'react';

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurface, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from './spec/index.js';
-export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, D as DefinedSurface, O as OUIBranded, c as ObservationDefinition, S as SurfaceDefinition, d as defineSurface } from './define-surface-DXBop-uB.js';
+export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationSnapshot, OUIObservationUpdate, OUIProtocolEvent, OUISurface, OUISurfaceDeregistration, OUISurfaceRegistration, OUISurfaceSnapshot, OUI_PROTOCOL_EVENTS } from './spec/index.js';
+export { A as ActionDefinition, a as ActionHandlerResult, b as ActionPollingConfig, D as DefinedSurface, M as MountedSurface, O as OUIBranded, c as ObservationDefinition, S as SettleOptions, d as SurfaceDefinition, e as SurfaceRuntime, f as SurfaceRuntimeOptions, g as createSurfaceRuntime, h as defineSurface } from './surface-runtime-Dj_nhd7r.js';
 export { DuplicateIds, OUIConfig, OUIConfigError, OUIInstance, OwnedTransport, ValidateSurfaceIds, createOUI } from './core/index.js';
-export { UseSurfaceOptions, useObservation, useSurface } from './react/index.js';
-export { O as OUIActionHandler, a as OUIObservationHandler, b as OUITransport, c as OUITransportConfig, S as SocketLike, d as createWebSocketTransport } from './websocket-CiWvkaz_.js';
+export { SurfaceRuntimeProvider, SurfaceRuntimeProviderProps, UseSurfaceOptions, UseSurfaceResult, useObservation, useSurface, useSurfaceHold, useSurfaceRuntime } from './react/index.js';
+export { O as OUIActionHandler, a as OUIObservationHandler, b as OUIResultHandler, c as OUITransport, d as OUITransportConfig, S as SocketLike, e as createWebSocketTransport } from './websocket-c5tIUWY5.js';
 export { createDirectTransportPair } from './transport/index.js';
+import 'react';

package/dist/index.js

@@ -1,7 +1,7 @@
-export { createOUI, defineSurface } from './chunk-ILUTAHUJ.js';
-export { OUI_PROTOCOL_EVENTS } from './chunk-CVUUSPF4.js';
-export { useObservation, useSurface } from './chunk-UIGRLZOX.js';
-export { createDirectTransportPair } from './chunk-O6EI77LD.js';
-export { createWebSocketTransport } from './chunk-YDMGV72W.js';
+export { createOUI, createSurfaceRuntime, defineSurface } from './chunk-TRNVXAB5.js';
+export { OUI_PROTOCOL_EVENTS } from './chunk-BMCL2K74.js';
+export { SurfaceRuntimeProvider, useObservation, useSurface, useSurfaceHold, useSurfaceRuntime } from './chunk-NYCJZQSP.js';
+export { createDirectTransportPair } from './chunk-IIZ6HL2L.js';
+export { createWebSocketTransport } from './chunk-F3WKIRAU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/react/index.cjs

@@ -1,16 +1,28 @@
 'use strict';
 
-var chunk2ON5IEXB_cjs = require('../chunk-2ON5IEXB.cjs');
+var chunkF3SKRAGU_cjs = require('../chunk-F3SKRAGU.cjs');
 
 
 
+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; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/react/index.d.cts

@@ -1,62 +1,45 @@
-import { OUIActionRequest, OUISurface } from '../spec/index.cjs';
-import { D as DefinedSurface } from '../define-surface-D6XPtoqu.cjs';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { OUIActionResult } from '../spec/index.cjs';
+import { e as SurfaceRuntime, D as DefinedSurface } from '../surface-runtime--2lZGB7Z.cjs';
+import '../websocket-YfWILdZ4.cjs';
 
-/**
- * Configuration for the useSurface hook.
- */
+interface SurfaceRuntimeProviderProps {
+    runtime: SurfaceRuntime;
+    children?: ReactNode;
+}
+/** Makes one surface runtime available to every `useSurface` below it. */
+declare function SurfaceRuntimeProvider({ runtime, children, }: SurfaceRuntimeProviderProps): react.FunctionComponentElement<react.ProviderProps<SurfaceRuntime | null>>;
+/** The surface runtime from the nearest `SurfaceRuntimeProvider`. */
+declare function useSurfaceRuntime(): SurfaceRuntime;
 interface UseSurfaceOptions<TContext> {
     /** The defined surface (from defineSurface()) */
     surface: DefinedSurface<TContext>;
-    /** The context passed to action handlers (app state, utilities, etc.) */
+    /** Passed to action handlers. Read when an action runs, so it is always current. */
     context: TContext;
-    /** Transport send function — how to send protocol events to the agent runtime */
-    send: (event: {
-        type: string;
-        payload: unknown;
-    }) => void;
-    /** Whether the surface is currently active (respects activation conditions) */
+    /** Mount the surface only while true. Default true. */
     active?: boolean;
 }
+interface UseSurfaceResult {
+    surfaceId: string;
+    /** Record an observation value on this surface. Unchanged values are ignored. */
+    pushObservation(observationId: string, value: unknown): void;
+    /** Run one of this surface's actions locally, exactly as a dispatched request would. */
+    execute(actionId: string, params?: Record<string, unknown>): Promise<OUIActionResult>;
+}
 /**
- * useSurface — registers an OUI surface with the agent runtime and handles
- * incoming action requests by executing them locally and pushing observation
- * updates. Actions are dispatched one-way (no request/response correlation).
- *
- * After an action handler executes, if the action has a polling config, the
- * hook starts a polling loop that pushes observation updates until the
- * operation completes or times out.
- *
- * @example
- * ```tsx
- * function DataVizPage() {
- *   const { state, updateState, goToStep } = useDataVizWizard();
- *
- *   useSurface({
- *     surface: datavizSurface,
- *     context: { state, updateState, goToStep },
- *     send: agentTransport.send,
- *     active: true,
- *   });
- *
- *   return <DataVizWizard />;
- * }
- * ```
+ * Mount a surface into the client's surface runtime for as long as the
+ * component is mounted (and `active`). The runtime answers dispatched requests
+ * for it, so the component needs no listener of its own.
  */
-declare function useSurface<TContext>(options: UseSurfaceOptions<TContext>): {
-    handleActionRequest: (request: OUIActionRequest) => Promise<void>;
-    surfaceId: string;
-    manifest: OUISurface;
-    /** Manually stop polling for a specific action */
-    stopPolling: (actionId: string) => void;
-    /** Stop all active pollers */
-    stopAllPolling: () => void;
-};
+declare function useSurface<TContext>(options: UseSurfaceOptions<TContext>): UseSurfaceResult;
+/** Keep an observation on a mounted surface equal to `value`. */
+declare function useObservation(surface: Pick<UseSurfaceResult, "pushObservation">, observationId: string, value: unknown): void;
 /**
- * Helper to push an observation update to the agent runtime.
+ * Keep the UI unsettled while `busy` is true: an action's result waits for it.
+ * For work mounting cannot show, such as a route's code or a page's data still
+ * loading.
  */
-declare function useObservation(surfaceId: string, observationId: string, value: unknown, send: (event: {
-    type: string;
-    payload: unknown;
-}) => void): void;
+declare function useSurfaceHold(busy: boolean): void;
 
-export { type UseSurfaceOptions, useObservation, useSurface };
+export { SurfaceRuntimeProvider, type SurfaceRuntimeProviderProps, type UseSurfaceOptions, type UseSurfaceResult, useObservation, useSurface, useSurfaceHold, useSurfaceRuntime };

package/dist/react/index.d.ts

@@ -1,62 +1,45 @@
-import { OUIActionRequest, OUISurface } from '../spec/index.js';
-import { D as DefinedSurface } from '../define-surface-DXBop-uB.js';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { OUIActionResult } from '../spec/index.js';
+import { e as SurfaceRuntime, D as DefinedSurface } from '../surface-runtime-Dj_nhd7r.js';
+import '../websocket-c5tIUWY5.js';
 
-/**
- * Configuration for the useSurface hook.
- */
+interface SurfaceRuntimeProviderProps {
+    runtime: SurfaceRuntime;
+    children?: ReactNode;
+}
+/** Makes one surface runtime available to every `useSurface` below it. */
+declare function SurfaceRuntimeProvider({ runtime, children, }: SurfaceRuntimeProviderProps): react.FunctionComponentElement<react.ProviderProps<SurfaceRuntime | null>>;
+/** The surface runtime from the nearest `SurfaceRuntimeProvider`. */
+declare function useSurfaceRuntime(): SurfaceRuntime;
 interface UseSurfaceOptions<TContext> {
     /** The defined surface (from defineSurface()) */
     surface: DefinedSurface<TContext>;
-    /** The context passed to action handlers (app state, utilities, etc.) */
+    /** Passed to action handlers. Read when an action runs, so it is always current. */
     context: TContext;
-    /** Transport send function — how to send protocol events to the agent runtime */
-    send: (event: {
-        type: string;
-        payload: unknown;
-    }) => void;
-    /** Whether the surface is currently active (respects activation conditions) */
+    /** Mount the surface only while true. Default true. */
     active?: boolean;
 }
+interface UseSurfaceResult {
+    surfaceId: string;
+    /** Record an observation value on this surface. Unchanged values are ignored. */
+    pushObservation(observationId: string, value: unknown): void;
+    /** Run one of this surface's actions locally, exactly as a dispatched request would. */
+    execute(actionId: string, params?: Record<string, unknown>): Promise<OUIActionResult>;
+}
 /**
- * useSurface — registers an OUI surface with the agent runtime and handles
- * incoming action requests by executing them locally and pushing observation
- * updates. Actions are dispatched one-way (no request/response correlation).
- *
- * After an action handler executes, if the action has a polling config, the
- * hook starts a polling loop that pushes observation updates until the
- * operation completes or times out.
- *
- * @example
- * ```tsx
- * function DataVizPage() {
- *   const { state, updateState, goToStep } = useDataVizWizard();
- *
- *   useSurface({
- *     surface: datavizSurface,
- *     context: { state, updateState, goToStep },
- *     send: agentTransport.send,
- *     active: true,
- *   });
- *
- *   return <DataVizWizard />;
- * }
- * ```
+ * Mount a surface into the client's surface runtime for as long as the
+ * component is mounted (and `active`). The runtime answers dispatched requests
+ * for it, so the component needs no listener of its own.
  */
-declare function useSurface<TContext>(options: UseSurfaceOptions<TContext>): {
-    handleActionRequest: (request: OUIActionRequest) => Promise<void>;
-    surfaceId: string;
-    manifest: OUISurface;
-    /** Manually stop polling for a specific action */
-    stopPolling: (actionId: string) => void;
-    /** Stop all active pollers */
-    stopAllPolling: () => void;
-};
+declare function useSurface<TContext>(options: UseSurfaceOptions<TContext>): UseSurfaceResult;
+/** Keep an observation on a mounted surface equal to `value`. */
+declare function useObservation(surface: Pick<UseSurfaceResult, "pushObservation">, observationId: string, value: unknown): void;
 /**
- * Helper to push an observation update to the agent runtime.
+ * Keep the UI unsettled while `busy` is true: an action's result waits for it.
+ * For work mounting cannot show, such as a route's code or a page's data still
+ * loading.
  */
-declare function useObservation(surfaceId: string, observationId: string, value: unknown, send: (event: {
-    type: string;
-    payload: unknown;
-}) => void): void;
+declare function useSurfaceHold(busy: boolean): void;
 
-export { type UseSurfaceOptions, useObservation, useSurface };
+export { SurfaceRuntimeProvider, type SurfaceRuntimeProviderProps, type UseSurfaceOptions, type UseSurfaceResult, useObservation, useSurface, useSurfaceHold, useSurfaceRuntime };

package/dist/react/index.js

@@ -1,3 +1,3 @@
-export { useObservation, useSurface } from '../chunk-UIGRLZOX.js';
+export { SurfaceRuntimeProvider, useObservation, useSurface, useSurfaceHold, useSurfaceRuntime } from '../chunk-NYCJZQSP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/spec/index.cjs

@@ -1,12 +1,12 @@
 'use strict';
 
-var chunk3DCIL4FV_cjs = require('../chunk-3DCIL4FV.cjs');
+var chunkZKM4XWAB_cjs = require('../chunk-ZKM4XWAB.cjs');
 
 
 
 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/spec/index.d.cts

@@ -127,7 +127,7 @@ interface OUIObservation {
     /** JSON Schema for the observation's value */
     schema: JSONSchema;
     /** How frequently this observation updates */
-    updateFrequency?: 'realtime' | 'on-change' | 'polling';
+    updateFrequency?: "realtime" | "on-change" | "polling";
 }
 /**
  * Activation conditions — when a surface is available to the agent.
@@ -184,6 +184,34 @@ interface OUIActionResult {
     durationMs?: number;
     /** Timestamp of the result */
     timestamp: number;
+    /**
+     * The surfaces active on the client once the action's effects settled.
+     *
+     * An action can change what the agent is able to do next: navigating
+     * unmounts one page's surfaces and mounts another's. Without this, the agent
+     * would act on the capability set it had before the action, which is the
+     * set the action just replaced.
+     */
+    surfaces?: OUISurface[];
+    /** Latest observation values per surface once the action's effects settled. */
+    observations?: OUIObservationSnapshot;
+    /**
+     * False when the client's deadline passed before its UI settled, so
+     * `surfaces` and `observations` may still be changing. Absent or true
+     * otherwise.
+     */
+    settled?: boolean;
+}
+/** Latest observation values, keyed by surface id and then observation id. */
+type OUIObservationSnapshot = Record<string, Record<string, unknown>>;
+/**
+ * What a client can do right now: the surfaces it has mounted and their latest
+ * observation values. A client sends this to its agent runtime (for example,
+ * with each turn), and returns it on every action result.
+ */
+interface OUISurfaceSnapshot {
+    surfaces: OUISurface[];
+    observations: OUIObservationSnapshot;
 }
 /**
  * An observation update pushed from the surface to the agent.
@@ -220,19 +248,19 @@ interface OUISurfaceDeregistration {
  * All protocol events exchanged between agent runtime and surfaces.
  */
 type OUIProtocolEvent = {
-    type: 'surface:register';
+    type: "surface:register";
     payload: OUISurfaceRegistration;
 } | {
-    type: 'surface:deregister';
+    type: "surface:deregister";
     payload: OUISurfaceDeregistration;
 } | {
-    type: 'action:request';
+    type: "action:request";
     payload: OUIActionRequest;
 } | {
-    type: 'action:result';
+    type: "action:result";
     payload: OUIActionResult;
 } | {
-    type: 'observation:update';
+    type: "observation:update";
     payload: OUIObservationUpdate;
 };
 /**
@@ -246,4 +274,4 @@ declare const OUI_PROTOCOL_EVENTS: {
     readonly OBSERVATION_UPDATE: "observation:update";
 };
 
-export { type JSONSchema, type OUIAction, type OUIActionPolling, type OUIActionRequest, type OUIActionResult, type OUIActivation, type OUIObservation, type OUIObservationUpdate, type OUIProtocolEvent, type OUISurface, type OUISurfaceDeregistration, type OUISurfaceRegistration, OUI_PROTOCOL_EVENTS };
+export { type JSONSchema, type OUIAction, type OUIActionPolling, type OUIActionRequest, type OUIActionResult, type OUIActivation, type OUIObservation, type OUIObservationSnapshot, type OUIObservationUpdate, type OUIProtocolEvent, type OUISurface, type OUISurfaceDeregistration, type OUISurfaceRegistration, type OUISurfaceSnapshot, OUI_PROTOCOL_EVENTS };