@statelyai/sdk 0.15.0 → 0.16.0

package/dist/{inspect-DenVP7IE.d.mts → inspect-CduY_2Fa.d.mts}

@@ -1,12 +1,17 @@
 import { EditorCapabilities, EmbedEventMap, ExportCallOptions, ExportFormat, ExportFormatMap, InspectionAction, InspectionSentEvent, InspectionTakenTransition, ProtocolMessage } from "./protocol.mjs";
 
 //#region src/transport.d.ts
+interface TransportFailure {
+  code: string;
+  message: string;
+}
 interface Transport {
   send(msg: ProtocolMessage): void;
   onMessage(handler: (msg: ProtocolMessage) => void): () => void;
   destroy(): void;
   readonly ready: boolean;
   onReady(handler: () => void): () => void;
+  onError?(handler: (failure: TransportFailure) => void): () => void;
 }
 interface PostMessageTransportOptions {
   iframe: HTMLIFrameElement;
@@ -17,51 +22,18 @@ interface PostMessageTransportOptions {
 declare function createPostMessageTransport(options: PostMessageTransportOptions): Transport;
 interface WebSocketTransportOptions {
   url: string;
-  role: 'client' | 'viz';
-  sessionId: string;
+  role: 'producer' | 'viewer';
+  producerId?: string;
   metadata?: {
     name?: string;
     machineId?: string;
   };
   /** Reconnect on disconnect. Default true. */
   reconnect?: boolean;
-  /** Max reconnect attempts. Default 10. */
+  /** Max reconnect attempts after the first connection. Default 10. */
   maxReconnectAttempts?: number;
 }
 declare function createWebSocketTransport(options: WebSocketTransportOptions): Transport;
-interface MultiplexedWebSocketConnectionOptions {
-  url: string;
-  role: 'client' | 'viz';
-  /** First (primary) session to register on connect. */
-  sessionId: string;
-  /** Metadata for the primary session. */
-  metadata?: {
-    name?: string;
-    machineId?: string;
-  };
-  reconnect?: boolean;
-  maxReconnectAttempts?: number;
-}
-interface MultiplexedChannelOptions {
-  /** Session id this channel targets. */
-  sessionId: string;
-  /** Optional metadata for this session. */
-  metadata?: {
-    name?: string;
-    machineId?: string;
-  };
-}
-interface MultiplexedWebSocketConnection {
-  /** Open a channel for a sessionId. Re-opening an existing session returns the same channel. */
-  openChannel(options: MultiplexedChannelOptions): Transport;
-  /** Close the connection and all its channels. */
-  destroy(): void;
-  /** Whether the underlying WebSocket is connected + the primary session is registered. */
-  readonly ready: boolean;
-  /** Primary session id (first registered). */
-  readonly primarySessionId: string;
-}
-declare function createMultiplexedWebSocketConnection(options: MultiplexedWebSocketConnectionOptions): MultiplexedWebSocketConnection;
 //#endregion
 //#region src/inspect.d.ts
 interface MinimalActorRef {
@@ -93,14 +65,14 @@ interface InspectorInspectionEvent {
   readonly actorRef: unknown;
 }
 interface AdoptedActor {
-  /** `actor.sessionId` from xstate. Unique across the system. */
+  /** Globally unique `actor.sessionId` from xstate. */
+  sessionId: string;
+  /** System-local `actor.id`. */
   actorId: string;
   /** Parent actor's sessionId, or `null` for the root. */
-  parentActorId: string | null;
-  /** Root actor's sessionId (equal to `actorId` for the root). */
-  rootId: string;
-  /** `actor.id` — a human-facing local name. */
-  id: string;
+  parentSessionId: string | null;
+  /** Root actor's sessionId. */
+  rootSessionId: string;
   /** `actor.systemId`, if registered under one. */
   systemId: string | undefined;
   /** Latest serialized snapshot streamed for this actor. */
@@ -112,8 +84,8 @@ interface AdoptedActor {
 }
 /** One observed snapshot, independent of the XState inspection version. */
 interface InspectedSnapshot {
-  actorId: string;
-  sourceActorId: string | null;
+  sessionId: string;
+  sourceSessionId: string | null;
   /** Previously observed snapshot, which may not be the immediate predecessor. */
   previousSnapshot: unknown | null;
   snapshot: unknown;
@@ -127,8 +99,8 @@ interface InspectedSnapshot {
 type InspectedTransition = InspectedSnapshot;
 /** One observed event, independent of whether processing produced a snapshot. */
 interface InspectedEvent {
-  actorId: string;
-  sourceActorId: string | null;
+  sessionId: string;
+  sourceSessionId: string | null;
   event: unknown;
 }
 interface InspectorEvents {
@@ -136,7 +108,7 @@ interface InspectorEvents {
   event: InspectedEvent;
   snapshot: InspectedSnapshot;
   stop: {
-    actorId: string;
+    sessionId: string;
   };
   /** @deprecated Use `actor`. */
   register: AdoptedActor;
@@ -144,7 +116,7 @@ interface InspectorEvents {
   transition: InspectedSnapshot;
   /** @deprecated Use `stop`. */
   stopped: {
-    actorId: string;
+    sessionId: string;
   };
   error: EmbedEventMap['error'];
 }
@@ -161,15 +133,27 @@ interface ManualActorOptions {
   systemId?: string;
 }
 interface CreateInspectorOptions {
-  /** WebSocket URL of the devtools server. Default: `'ws://localhost:4242'`. */
+  /**
+   * WebSocket relay base URL. Defaults to `STATELY_INSPECT_URL`, then
+   * `wss://sky.stately.ai`. Passing this option always wins.
+   */
   url?: string;
+  /** Unguessable inspection room capability. Defaults to a random UUID. */
+  roomId?: string;
+  /** Stable identity for this producer connection. Defaults to a random UUID. */
+  producerId?: string;
+  /**
+   * Inspector UI base URL when hosted separately from the WebSocket relay. The
+   * inspector adds `ws` and `r` query parameters. When omitted, the URL
+   * is derived from the relay URL by replacing `ws` with `http`.
+   */
+  inspectorBaseUrl?: string;
   /** Auto-open browser to visualizer. Default: `true`. */
   autoOpen?: boolean;
   /**
-   * Relay session capability. Defaults to a cryptographically random UUID.
-   * This is the `?session=<id>` value the visualizer connects with. Custom
-   * values used with a hosted relay must be unguessable.
+   * Legacy name for the unguessable room capability.
    */
+  /** @deprecated Use {@link roomId}. */
   sessionId?: string;
   /** Display name for this system in the visualizer. */
   name?: string;
@@ -184,7 +168,9 @@ interface CreateInspectorOptions {
    * `actor.logic.config`. Return `null` for non-machine actors.
    */
   extractMachineConfig?: (actor: any, source?: unknown) => unknown;
-  /** Selected actor id to focus on first. Defaults to the first inspected root. */
+  /** Selected actor session id to focus on first. */
+  selectedSessionId?: string;
+  /** @deprecated Use {@link selectedSessionId}. */
   selectedActorId?: string;
   /** Panel layout forwarded into the system init message. */
   panels?: {
@@ -197,17 +183,26 @@ interface CreateInspectorOptions {
   depth?: number;
   capabilities?: EditorCapabilities;
   /**
-   * Advanced: inject a pre-built transport (e.g. a channel from a
-   * multiplexed connection). When provided, `url`/`name` are ignored and the
-   * inspector shares that transport instead of opening its own WebSocket.
+   * Advanced: inject a pre-built transport. When provided, `url`/`name` are
+   * ignored and no WebSocket or browser URL is created.
    */
   transport?: Transport;
 }
 interface Inspector {
-  /** Snapshot of currently-adopted actors keyed by `actorId`. */
+  /** Snapshot of currently-adopted actors keyed by global `sessionId`. */
   readonly actors: ReadonlyMap<string, AdoptedActor>;
-  /** The relay sessionId this inspector registered under. */
+  /** Unguessable inspection room capability. */
+  readonly roomId: string;
+  /** Complete WebSocket URL for this room. */
+  readonly relayUrl: string | null;
+  /** Identity stamped onto this producer's protocol messages. */
+  readonly producerId: string;
+  /** @deprecated Use {@link roomId}. */
   readonly sessionId: string;
+  /** URL that opens the inspector UI for this live session. */
+  readonly inspectorUrl: string | null;
+  /** Resolves after the first relay registration and initial-state flush. */
+  readonly ready: Promise<void>;
   /**
    * XState `inspect` option callback. Pass directly to `createActor` or another
    * host that creates actors internally.
@@ -251,4 +246,4 @@ declare function createInspector(options?: CreateInspectorOptions): Inspector;
 /** @deprecated Use {@link createInspector}. */
 declare const createStatelyInspector: typeof createInspector;
 //#endregion
-export { createPostMessageTransport as _, InspectedTransition as a, InspectorInspectionEvent as c, createStatelyInspector as d, MultiplexedChannelOptions as f, createMultiplexedWebSocketConnection as g, Transport as h, InspectedSnapshot as i, ManualActorOptions as l, MultiplexedWebSocketConnectionOptions as m, CreateInspectorOptions as n, Inspector as o, MultiplexedWebSocketConnection as p, InspectedEvent as r, InspectorEvents as s, AdoptedActor as t, createInspector as u, createWebSocketTransport as v };
+export { InspectedTransition as a, InspectorInspectionEvent as c, createStatelyInspector as d, Transport as f, createWebSocketTransport as h, InspectedSnapshot as i, ManualActorOptions as l, createPostMessageTransport as m, CreateInspectorOptions as n, Inspector as o, TransportFailure as p, InspectedEvent as r, InspectorEvents as s, AdoptedActor as t, createInspector as u };

package/dist/inspect.d.mts

@@ -1,3 +1,3 @@
 import { EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InspectionAction, InspectionSentEvent, InspectionTakenTransition } from "./protocol.mjs";
-import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, h as Transport, i as InspectedSnapshot, l as ManualActorOptions, n as CreateInspectorOptions, o as Inspector, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector } from "./inspect-DenVP7IE.mjs";
+import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f as Transport, i as InspectedSnapshot, l as ManualActorOptions, n as CreateInspectorOptions, o as Inspector, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector } from "./inspect-CduY_2Fa.mjs";
 export { AdoptedActor, CreateInspectorOptions, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InspectedEvent, InspectedSnapshot, InspectedTransition, InspectionAction, InspectionSentEvent, InspectionTakenTransition, Inspector, InspectorEvents, InspectorInspectionEvent, ManualActorOptions, Transport, createInspector, createStatelyInspector };

package/dist/inspect.mjs

@@ -1,3 +1,3 @@
-import { n as createStatelyInspector, t as createInspector } from "./inspect-DWDTNMEc.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-BwVdM4R8.mjs";
 
 export { createInspector, createStatelyInspector };

package/dist/node-relay.d.mts

@@ -0,0 +1,22 @@
+//#region src/node-relay.d.ts
+interface NodeInspectionRelayOptions {
+  host?: string;
+  port?: number;
+  logger?: Pick<Console, 'info'>;
+}
+/** Local/self-hosted Node adapter for the room inspection relay. */
+declare class NodeInspectionRelayServer {
+  private readonly options;
+  private server;
+  private webSocketServer;
+  private readonly rooms;
+  private readonly connections;
+  private readonly sockets;
+  constructor(options?: NodeInspectionRelayOptions);
+  get url(): string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+declare function createNodeInspectionRelay(options?: NodeInspectionRelayOptions): NodeInspectionRelayServer;
+//#endregion
+export { NodeInspectionRelayOptions, NodeInspectionRelayServer, createNodeInspectionRelay };

package/dist/node-relay.mjs

@@ -0,0 +1,84 @@
+import { getInspectionRoomId } from "./protocol.mjs";
+import { createInspectionRelay } from "./relay.mjs";
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { WebSocket, WebSocketServer } from "ws";
+
+//#region src/node-relay.ts
+/** Local/self-hosted Node adapter for the room inspection relay. */
+var NodeInspectionRelayServer = class {
+	server = null;
+	webSocketServer = null;
+	rooms = /* @__PURE__ */ new Map();
+	connections = /* @__PURE__ */ new Map();
+	sockets = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.options = options;
+	}
+	get url() {
+		if (!this.server) throw new Error("Inspection relay is not running.");
+		const address = this.server.address();
+		if (!address || typeof address === "string") throw new Error("Inspection relay address is unavailable.");
+		return `ws://${this.options.host ?? "127.0.0.1"}:${address.port}`;
+	}
+	async start() {
+		if (this.server) return;
+		this.server = createServer();
+		this.webSocketServer = new WebSocketServer({ server: this.server });
+		this.webSocketServer.on("connection", (socket, request) => {
+			const roomId = getInspectionRoomId(new URL(request.url ?? "/", this.url));
+			if (!roomId) {
+				socket.close(1008, "Missing ?r=<roomId>");
+				return;
+			}
+			const relay = this.rooms.get(roomId) ?? createInspectionRelay();
+			this.rooms.set(roomId, relay);
+			const peerId = randomUUID();
+			this.connections.set(socket, {
+				peerId,
+				relay
+			});
+			this.sockets.set(peerId, socket);
+			socket.on("message", (raw) => {
+				for (const effect of relay.receive(peerId, raw.toString())) {
+					const target = this.sockets.get(effect.peerId);
+					if (target?.readyState === WebSocket.OPEN) target.send(JSON.stringify(effect.message));
+				}
+			});
+			socket.on("close", () => {
+				relay.disconnect(peerId);
+				this.connections.delete(socket);
+				this.sockets.delete(peerId);
+			});
+		});
+		await new Promise((resolve, reject) => {
+			this.server.once("error", reject);
+			this.server.listen(this.options.port ?? 4242, this.options.host ?? "127.0.0.1", () => {
+				this.server.off("error", reject);
+				resolve();
+			});
+		});
+		this.options.logger?.info(`Inspection relay listening on ${this.url}`);
+	}
+	async stop() {
+		for (const socket of this.connections.keys()) socket.close();
+		this.connections.clear();
+		this.sockets.clear();
+		for (const relay of this.rooms.values()) relay.clear();
+		this.rooms.clear();
+		if (this.webSocketServer) {
+			await new Promise((resolve) => this.webSocketServer.close(() => resolve()));
+			this.webSocketServer = null;
+		}
+		if (this.server) {
+			await new Promise((resolve, reject) => this.server.close((error) => error ? reject(error) : resolve()));
+			this.server = null;
+		}
+	}
+};
+function createNodeInspectionRelay(options) {
+	return new NodeInspectionRelayServer(options);
+}
+
+//#endregion
+export { NodeInspectionRelayServer, createNodeInspectionRelay };