oui-spec 0.2.0 → 0.4.0

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-GXTNZ44I.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 chunkDGMKSJTY_cjs = require('./chunk-DGMKSJTY.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 chunkDGMKSJTY_cjs.createOUI; }
+});
+Object.defineProperty(exports, "createSurfaceRuntime", {
+  enumerable: true,
+  get: function () { return chunkDGMKSJTY_cjs.createSurfaceRuntime; }
 });
 Object.defineProperty(exports, "defineSurface", {
   enumerable: true,
-  get: function () { return chunkHK7OXB2W_cjs.defineSurface; }
+  get: function () { return chunkDGMKSJTY_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-BzIKgL_I.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-DeByfbKg.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-GXTNZ44I.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-BzIKgL_I.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-DeByfbKg.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

package/dist/{define-surface-D6XPtoqu.d.cts → surface-runtime-BzIKgL_I.d.cts}

@@ -1,4 +1,5 @@
-import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface } from './spec/index.cjs';
+import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult } from './spec/index.cjs';
+import { S as SocketLike, d as OUITransportConfig } from './websocket-YfWILdZ4.cjs';
 
 /**
  * Nominal branding for values OUI must construct itself.
@@ -148,4 +149,103 @@ interface DefinedSurface<TContext = unknown> extends SurfaceDefinition<TContext>
     getPollingConfig(actionId: string): OUIActionPolling | undefined;
 }
 
-export { type ActionDefinition as A, type DefinedSurface as D, type OUIBranded as O, type SurfaceDefinition as S, type ActionHandlerResult as a, type ActionPollingConfig as b, type ObservationDefinition as c, defineSurface as d };
+/**
+ * The client-side surface runtime.
+ *
+ * Holds the surfaces a client has mounted, answers every action request with a
+ * result, and produces the snapshot an agent runtime works from.
+ *
+ * WHY THIS EXISTS
+ *
+ * The first integration kept no client-side record of what was mounted. Each
+ * surface hook registered itself with a server-side registry and listened for
+ * dispatches on its own. Three things followed:
+ *
+ * - The registry was the only record of what the client could do, and it lost
+ *   entries: a dead socket's cleanup removed a live tab's registration, and the
+ *   browser never registered again. The agent then had no UI tools at all.
+ * - Nothing answered a dispatch. The agent was told an action succeeded before
+ *   the client had run it, and never saw the page an action led to.
+ * - Every hook listened independently, through two paths, so one dispatch ran
+ *   twice and nothing de-duplicated it.
+ *
+ * Here the client is the record. `snapshot()` is what the client can do right
+ * now, and every request is run once, waited on until the UI settles, and
+ * answered with its result and the snapshot after it.
+ */
+
+interface SettleOptions {
+    /**
+     * The UI counts as settled once nothing has mounted, unmounted or changed an
+     * observation for this long, and no hold is open. Default 250 ms.
+     */
+    quietMs?: number;
+    /** Give up waiting after this long and answer with `settled: false`. Default 5000 ms. */
+    timeoutMs?: number;
+}
+interface SurfaceRuntimeOptions {
+    /** The socket to answer requests on. Can be set or replaced later with `attach`. */
+    socket?: SocketLike | null;
+    /** Wire configuration for the transport the runtime builds on the socket. */
+    transport?: OUITransportConfig;
+    /**
+     * Also announce registrations and observations over the transport, for agent
+     * runtimes that keep a server-side registry. Default true.
+     *
+     * An agent runtime that takes the client's snapshot instead (sent with each
+     * turn, and returned on every result) has no use for them: set false.
+     */
+    announce?: boolean;
+    settle?: SettleOptions;
+    /** How many answered request ids to remember, for de-duplication. Default 500. */
+    dedupeWindow?: number;
+    /**
+     * Decides whether a request that arrived on the socket may run at all. A
+     * refused request is neither run nor answered, and is logged.
+     *
+     * The server should be the only sender of action requests, but a client can
+     * also check that a request is one it expects: for example, only while its
+     * agent has a turn in progress. Requests passed to `execute` directly are
+     * not checked; they come from the application itself.
+     */
+    accept?: (request: OUIActionRequest) => boolean;
+}
+interface MountedSurface {
+    readonly surfaceId: string;
+    /** Record an observation value. A no-op once unmounted. */
+    pushObservation(observationId: string, value: unknown): void;
+    /** Remove this mount. Other mounts of the same surface id are unaffected. */
+    unmount(): void;
+}
+interface SurfaceRuntime {
+    /**
+     * Mount a surface. `getContext` is read when an action runs, so handlers see
+     * the latest state rather than the state at mount time.
+     *
+     * Mounting the same surface id twice is allowed (React StrictMode does it on
+     * every mount); the most recent mount serves its actions.
+     */
+    mount<TContext>(surface: DefinedSurface<TContext>, getContext: () => TContext): MountedSurface;
+    /** Answer requests arriving on this socket (null detaches). */
+    attach(socket: SocketLike | null): void;
+    /** What the client can do right now. */
+    snapshot(): OUISurfaceSnapshot;
+    /**
+     * Run a request once and resolve with its result. A request id seen before
+     * resolves with the first result instead of running again.
+     */
+    execute(request: OUIActionRequest): Promise<OUIActionResult>;
+    /**
+     * Keep the UI unsettled until the returned function is called. For work an
+     * action starts that mounting and unmounting cannot show, such as a route's
+     * code still loading or a page fetching the data it will display.
+     */
+    hold(): () => void;
+    /** Called whenever the snapshot changes. */
+    subscribe(listener: () => void): () => void;
+    /** Stop polling, detach from the socket and forget every mount. */
+    dispose(): void;
+}
+declare function createSurfaceRuntime(options?: SurfaceRuntimeOptions): SurfaceRuntime;
+
+export { type ActionDefinition as A, type DefinedSurface as D, type MountedSurface as M, type OUIBranded as O, type SettleOptions as S, type ActionHandlerResult as a, type ActionPollingConfig as b, type ObservationDefinition as c, type SurfaceDefinition as d, type SurfaceRuntime as e, type SurfaceRuntimeOptions as f, createSurfaceRuntime as g, defineSurface as h };