oui-spec 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,4 +1,7 @@
-export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurface, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from './spec/index.cjs';
-export { ActionDefinition, ActionHandlerResult, ActionPollingConfig, DefinedSurface, ObservationDefinition, SurfaceDefinition, defineSurface } from './core/index.cjs';
-export { UseSurfaceOptions, useObservation, useSurface } from './react/index.cjs';
-export { OUIActionHandler, OUIObservationHandler, OUITransport, OUITransportConfig, SocketLike, createDirectTransportPair, createWebSocketTransport } from './transport/index.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 { 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,4 +1,7 @@
-export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurface, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from './spec/index.js';
-export { ActionDefinition, ActionHandlerResult, ActionPollingConfig, DefinedSurface, ObservationDefinition, SurfaceDefinition, defineSurface } from './core/index.js';
-export { UseSurfaceOptions, useObservation, useSurface } from './react/index.js';
-export { OUIActionHandler, OUIObservationHandler, OUITransport, OUITransportConfig, SocketLike, createDirectTransportPair, createWebSocketTransport } from './transport/index.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 { 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,6 +1,7 @@
-export { defineSurface } from './chunk-JO5LGOB6.js';
-export { OUI_PROTOCOL_EVENTS } from './chunk-CVUUSPF4.js';
-export { useObservation, useSurface } from './chunk-UIGRLZOX.js';
-export { createDirectTransportPair, createWebSocketTransport } from './chunk-7EXSMPGR.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 { DefinedSurface } from '../core/index.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 { DefinedSurface } from '../core/index.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 };

package/dist/spec/index.d.ts

@@ -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 };

package/dist/spec/index.js

@@ -1,3 +1,3 @@
-export { OUI_PROTOCOL_EVENTS } from '../chunk-CVUUSPF4.js';
+export { OUI_PROTOCOL_EVENTS } from '../chunk-BMCL2K74.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map