@statelyai/sdk 0.4.1 → 0.5.0

package/dist/inspect-WUC2inmJ.d.mts

@@ -0,0 +1,206 @@
+import { c as ExportFormatMap, d as ProtocolMessage, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat } from "./protocol-B1cNV7QB.mjs";
+
+//#region src/transport.d.ts
+interface Transport {
+  send(msg: ProtocolMessage): void;
+  onMessage(handler: (msg: ProtocolMessage) => void): () => void;
+  destroy(): void;
+  readonly ready: boolean;
+  onReady(handler: () => void): () => void;
+}
+interface PostMessageTransportOptions {
+  iframe: HTMLIFrameElement;
+  targetOrigin: string;
+  /** Filter by source. Defaults to iframe.contentWindow. */
+  source?: Window;
+}
+declare function createPostMessageTransport(options: PostMessageTransportOptions): Transport;
+interface WebSocketTransportOptions {
+  url: string;
+  role: 'client' | 'viz';
+  sessionId: string;
+  metadata?: {
+    name?: string;
+    machineId?: string;
+  };
+  /** Reconnect on disconnect. Default true. */
+  reconnect?: boolean;
+  /** Max reconnect attempts. Default 10. */
+  maxReconnectAttempts?: number;
+}
+declare function createWebSocketTransport(options: WebSocketTransportOptions): Transport;
+//#endregion
+//#region src/inspect.d.ts
+interface MinimalActorRef {
+  id: string;
+  sessionId: string;
+  systemId?: string;
+  _parent?: MinimalActorRef;
+  logic?: {
+    config?: unknown;
+  };
+  getSnapshot(): MinimalSnapshot;
+  system: {
+    inspect: (observer: (event: InspectionEvent) => void) => {
+      unsubscribe: () => void;
+    };
+  };
+}
+interface MinimalSnapshot {
+  value: unknown;
+  status: unknown;
+  context?: unknown;
+  children?: Record<string, MinimalActorRef>;
+}
+type InspectionEvent = {
+  type: '@xstate.actor';
+  actorRef: MinimalActorRef;
+  rootId: string;
+} | {
+  type: '@xstate.snapshot';
+  actorRef: MinimalActorRef;
+  rootId: string;
+  snapshot: MinimalSnapshot;
+  event: unknown;
+} | {
+  type: '@xstate.event';
+  actorRef: MinimalActorRef;
+  rootId: string;
+  sourceRef?: MinimalActorRef;
+  event: unknown;
+} | {
+  type: '@xstate.microstep';
+  actorRef: MinimalActorRef;
+  rootId: string;
+  snapshot: MinimalSnapshot;
+  event: unknown;
+} | {
+  type: '@xstate.action';
+  actorRef: MinimalActorRef;
+  rootId: string;
+  action: {
+    type: string;
+    params: unknown;
+  };
+};
+interface AdoptedActor {
+  /** `actor.sessionId` from xstate. Unique across the system. */
+  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;
+  /** `actor.systemId`, if registered under one. */
+  systemId: string | undefined;
+  /** Latest serialized snapshot streamed for this actor. */
+  snapshot: unknown | null;
+  /** Machine config sent to the visualizer, or `null` for non-machine actors. */
+  machineConfig: unknown;
+}
+interface InspectorEvents {
+  register: AdoptedActor;
+  snapshot: AdoptedActor;
+  stopped: {
+    actorId: string;
+  };
+  error: EmbedEventMap['error'];
+}
+type EventName = keyof InspectorEvents;
+type Handler<E extends EventName> = (data: InspectorEvents[E]) => void;
+interface ManualActorOptions {
+  /** Initial snapshot. */
+  snapshot?: unknown;
+  /** Machine config for the visualizer. Without this, the actor shows as a generic node. */
+  machine?: unknown;
+  /** Parent actor id (for hierarchy). */
+  parent?: string;
+  /** System-level id (optional alias). */
+  systemId?: string;
+}
+interface CreateInspectorOptions {
+  /**
+   * Root xstate actor to adopt. The inspector walks its `system`.
+   * Omit this for manual-only mode where you call `.actor()` / `.snapshot()`.
+   */
+  actor?: any;
+  /** WebSocket URL of the devtools server. Default: `'ws://localhost:4242'`. */
+  url?: string;
+  /** Auto-open browser to visualizer. Default: `true`. */
+  autoOpen?: boolean;
+  /**
+   * Relay session id. Defaults to the root actor's `sessionId` (auto mode)
+   * or a random id (manual mode). This is the `?session=<id>` value the viz
+   * iframe connects with.
+   */
+  sessionId?: string;
+  /** Display name for this system in the visualizer. */
+  name?: string;
+  /**
+   * Serialize a snapshot for the wire. Defaults to `{value, status}` —
+   * dropping context entirely because xstate contexts routinely contain
+   * spawned actor refs which are not JSON-safe.
+   */
+  serializeSnapshot?: (snapshot: MinimalSnapshot) => unknown;
+  /**
+   * Extract the machine config for a given actor. Defaults to reading
+   * `actor.logic.config`. Return `null` for non-machine actors.
+   */
+  extractMachineConfig?: (actor: any) => unknown;
+  /** Selected actor id to focus on first. Defaults to the root actor. */
+  selectedActorId?: string;
+  /** Panel layout forwarded into the system init message. */
+  panels?: {
+    leftPanels?: string[];
+    rightPanels?: string[];
+    activePanels?: string[];
+  };
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+  depth?: number;
+  /**
+   * 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.
+   */
+  transport?: Transport;
+}
+interface Inspector {
+  /** Snapshot of currently-adopted actors keyed by `actorId`. */
+  readonly actors: ReadonlyMap<string, AdoptedActor>;
+  /** The relay sessionId this inspector registered under. */
+  readonly sessionId: string;
+  /** Subscribe to lifecycle / error events. Returns an unsubscribe function. */
+  on<E extends EventName>(event: E, handler: Handler<E>): () => void;
+  off<E extends EventName>(event: E, handler: Handler<E>): void;
+  /** Export the currently-viewed machine in a given format. */
+  export<F extends ExportFormat>(format: F, options?: ExportCallOptions<F>): Promise<ExportFormatMap[F]['result']>;
+  /**
+   * Register a manual actor. In auto mode this adds an actor alongside the
+   * xstate-discovered ones; in manual mode it's the only way to add actors.
+   */
+  actor(id: string, options?: ManualActorOptions): void;
+  /**
+   * Push a snapshot update for an actor. The actor is auto-registered if
+   * it hasn't been `.actor()`'d yet.
+   */
+  snapshot(actorId: string, snapshot: unknown, event?: unknown): void;
+  /**
+   * Log an event targeting an actor. Sends a snapshot message with the
+   * actor's current snapshot + the new event so it appears in the event log.
+   */
+  event(actorId: string, event: string | {
+    type: string;
+    [key: string]: unknown;
+  }, options?: {
+    source?: string;
+  }): void;
+  /** Mark an actor as stopped and remove it from the tree. */
+  stop(actorId: string): void;
+  /** Tear down the WebSocket + xstate subscription. */
+  destroy(): void;
+}
+declare function createStatelyInspector(options: CreateInspectorOptions): Inspector;
+//#endregion
+export { ManualActorOptions as a, createPostMessageTransport as c, InspectorEvents as i, createWebSocketTransport as l, CreateInspectorOptions as n, createStatelyInspector as o, Inspector as r, Transport as s, AdoptedActor as t };

package/dist/inspect.d.mts

@@ -1,49 +1,3 @@
-import { a as EmbedMode, c as ExportFormatMap, i as EmbedEventName, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat } from "./protocol-CZVFCSg3.mjs";
-
-//#region src/inspect.d.ts
-interface CreateInspectorOptions {
-  /** WebSocket URL of the devtools server. Default: 'ws://localhost:4242' */
-  url?: string;
-  /** Auto-open browser to visualizer. Default: true */
-  autoOpen?: boolean;
-  /** Unique session ID. Auto-generated if not provided. */
-  sessionId?: string;
-  /** Display name for this connection in the visualizer. */
-  name?: string;
-}
-interface Inspector {
-  /** Send a machine for inspection (starts visualization). */
-  inspect(options: InspectOptions): void;
-  /** Update the machine currently being inspected. */
-  update(machine: unknown, format?: string): void;
-  /** Change the visualization mode. */
-  setMode(mode: EmbedMode): void;
-  /** Export the current machine in a given format. Returns a promise. */
-  export<F extends ExportFormat>(format: F, options?: ExportCallOptions<F>): Promise<ExportFormatMap[F]['result']>;
-  /** Subscribe to events from the visualizer. */
-  on<K extends EmbedEventName>(event: K, handler: EmbedEventHandler<K>): void;
-  /** Unsubscribe from an event. */
-  off<K extends EmbedEventName>(event: K, handler: EmbedEventHandler<K>): void;
-  /** Send a state snapshot for real-time inspection. */
-  sendSnapshot(snapshot: unknown, event?: unknown): void;
-  /** Clean up the connection. */
-  destroy(): void;
-  /** Session ID for this connection. */
-  readonly sessionId: string;
-}
-interface InspectOptions {
-  machine: unknown;
-  format?: string;
-  mode?: EmbedMode;
-  theme?: 'light' | 'dark';
-  readOnly?: boolean;
-  depth?: number;
-  panels?: {
-    leftPanels?: string[];
-    rightPanels?: string[];
-    activePanels?: string[];
-  };
-}
-declare function createStatelyInspector(options?: CreateInspectorOptions): Inspector;
-//#endregion
-export { CreateInspectorOptions, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type ExportCallOptions, type ExportFormat, type ExportFormatMap, InspectOptions, Inspector, createStatelyInspector };
+import { a as EmbedMode, c as ExportFormatMap, i as EmbedEventName, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat } from "./protocol-B1cNV7QB.mjs";
+import { a as ManualActorOptions, i as InspectorEvents, n as CreateInspectorOptions, o as createStatelyInspector, r as Inspector, s as Transport, t as AdoptedActor } from "./inspect-WUC2inmJ.mjs";
+export { AdoptedActor, CreateInspectorOptions, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, Inspector, InspectorEvents, ManualActorOptions, Transport, createStatelyInspector };

package/dist/inspect.mjs

@@ -1,20 +1,33 @@
-import { a as createRequestId, i as createPendingExportManager, n as createWebSocketTransport, o as toInitMessage, r as createEventRegistry } from "./transport-C1fRAuv-.mjs";
+import { i as createPendingExportManager, n as createWebSocketTransport, r as createEventRegistry } from "./transport-lomH7b0v.mjs";
 
 //#region src/inspect.ts
-function generateId() {
-	return createRequestId();
+const defaultSerializeSnapshot = (snapshot) => ({
+	value: snapshot?.value,
+	status: snapshot?.status
+});
+const defaultExtractMachineConfig = (actor) => actor?.logic?.config ?? null;
+let nextManualId = 0;
+function generateSessionId() {
+	return `manual-${Date.now()}-${nextManualId++}`;
 }
 function createStatelyInspector(options) {
-	const { url = "ws://localhost:4242", autoOpen = true, sessionId = generateId(), name } = options ?? {};
+	const { url = "ws://localhost:4242", autoOpen = true, actor: rootActor, name, serializeSnapshot = defaultSerializeSnapshot, extractMachineConfig = defaultExtractMachineConfig, selectedActorId, panels, theme, readOnly, depth, transport: injectedTransport } = options;
+	const root = rootActor ? rootActor : null;
+	const rootActorId = root?.sessionId ?? generateSessionId();
+	const sessionId = options.sessionId ?? rootActorId;
+	const displayName = name ?? (root ? `system:${root.id}` : "system:manual");
 	let destroyed = false;
+	let initSent = false;
 	const pendingMessages = [];
 	const events = createEventRegistry();
-	const transport = createWebSocketTransport({
+	const localListeners = {};
+	const transport = injectedTransport ?? createWebSocketTransport({
 		url,
 		role: "client",
 		sessionId,
-		...name && { metadata: { name } }
+		metadata: { name: displayName }
 	});
+	const ownsTransport = !injectedTransport;
 	const exportManager = createPendingExportManager((message) => send(message));
 	function send(msg) {
 		if (!transport.ready) {
@@ -23,17 +36,11 @@ function createStatelyInspector(options) {
 		}
 		transport.send(msg);
 	}
-	function flush() {
-		while (pendingMessages.length > 0) {
-			const msg = pendingMessages.shift();
-			transport.send(msg);
-		}
-	}
 	transport.onReady(() => {
-		flush();
-	});
-	if (autoOpen) transport.onReady(() => {
-		transport.send({
+		pendingMessages.length = 0;
+		initSent = false;
+		sendInit();
+		if (autoOpen) transport.send({
 			type: "@statelyai.requestOpen",
 			sessionId
 		});
@@ -41,79 +48,239 @@ function createStatelyInspector(options) {
 	transport.onMessage((msg) => {
 		if (destroyed) return;
 		switch (msg.type) {
-			case "@statelyai.ready":
-				events.emit("ready", { version: msg.version });
-				break;
-			case "@statelyai.loaded":
-				events.emit("loaded", { graph: msg.graph });
-				break;
-			case "@statelyai.change":
-				events.emit("change", {
-					graph: msg.graph,
-					machineConfig: msg.machineConfig
-				});
-				break;
-			case "@statelyai.save":
-				events.emit("save", {
-					graph: msg.graph,
-					machineConfig: msg.machineConfig
-				});
-				break;
 			case "@statelyai.retrieved":
 				exportManager.resolve(msg.requestId, msg.data);
 				break;
 			case "@statelyai.error":
 				exportManager.reject(new Error(msg.message), msg.requestId);
+				emitLocal("error", {
+					code: msg.code,
+					message: msg.message
+				});
 				events.emit("error", {
 					code: msg.code,
 					message: msg.message
 				});
 				break;
+			default: break;
 		}
 	});
+	function emitLocal(event, data) {
+		const set = localListeners[event];
+		if (!set) return;
+		for (const handler of set) handler(data);
+	}
+	const actors = /* @__PURE__ */ new Map();
+	/** Tracks which actors we've already emitted local 'register' events for. */
+	const locallyRegistered = /* @__PURE__ */ new Set();
+	/**
+	* Maps target actorId → source actorId for the most recent `@xstate.event`.
+	* Read + cleared by `handleSnapshot` so the source info propagates into the
+	* `actorSnapshot` message. xstate emits `@xstate.event` immediately before
+	* `@xstate.snapshot` for the same actor.
+	*/
+	const pendingEventSource = /* @__PURE__ */ new Map();
+	function emitRegisterOnce(entry) {
+		if (locallyRegistered.has(entry.actorId)) return;
+		locallyRegistered.add(entry.actorId);
+		emitLocal("register", entry);
+	}
+	function snapshotValue(actorRef) {
+		try {
+			return serializeSnapshot(actorRef.getSnapshot());
+		} catch {
+			return null;
+		}
+	}
+	function toEntry(actorRef) {
+		return {
+			actorId: actorRef.sessionId,
+			parentActorId: actorRef._parent?.sessionId ?? null,
+			rootId: rootActorId,
+			id: actorRef.id,
+			systemId: actorRef.systemId,
+			snapshot: snapshotValue(actorRef),
+			machineConfig: extractMachineConfig(actorRef)
+		};
+	}
+	function toSystemEntry(entry) {
+		return {
+			actorId: entry.actorId,
+			parentActorId: entry.parentActorId,
+			id: entry.id,
+			machine: entry.machineConfig,
+			snapshot: entry.snapshot ?? void 0
+		};
+	}
+	/**
+	* Walk the actor tree and populate the local `actors` map. Idempotent —
+	* existing entries stay in place but have their snapshot refreshed.
+	*/
+	function backfillActorTree(actorRef) {
+		const existing = actors.get(actorRef.sessionId);
+		const entry = existing ?? toEntry(actorRef);
+		if (existing) existing.snapshot = snapshotValue(actorRef);
+		else actors.set(entry.actorId, entry);
+		emitRegisterOnce(entry);
+		const children = actorRef.getSnapshot()?.children ?? {};
+		for (const child of Object.values(children)) if (child) backfillActorTree(child);
+	}
+	function sendInit() {
+		if (root) backfillActorTree(root);
+		send({
+			type: "@statelyai.system.init",
+			mode: "inspecting",
+			actors: Array.from(actors.values()).map(toSystemEntry),
+			selectedActorId: selectedActorId ?? rootActorId,
+			...theme && { theme },
+			...readOnly !== void 0 && { readOnly },
+			...depth !== void 0 && { depth },
+			...panels?.leftPanels && { leftPanels: panels.leftPanels },
+			...panels?.rightPanels && { rightPanels: panels.rightPanels },
+			...panels?.activePanels && { activePanels: panels.activePanels }
+		});
+		initSent = true;
+	}
+	function handleActor(actorRef) {
+		if (actors.has(actorRef.sessionId)) return;
+		const entry = toEntry(actorRef);
+		actors.set(entry.actorId, entry);
+		if (!initSent) return;
+		send({
+			type: "@statelyai.system.actorRegistered",
+			actorId: entry.actorId,
+			parentActorId: entry.parentActorId,
+			id: entry.id,
+			machine: entry.machineConfig,
+			snapshot: entry.snapshot ?? void 0
+		});
+		emitRegisterOnce(entry);
+	}
+	function handleSnapshot(actorRef, snapshot, triggeringEvent) {
+		if (!actors.has(actorRef.sessionId)) handleActor(actorRef);
+		const entry = actors.get(actorRef.sessionId);
+		if (!entry) return;
+		const serialized = serializeSnapshot(snapshot);
+		entry.snapshot = serialized;
+		const sourceActorId = pendingEventSource.get(entry.actorId) ?? null;
+		pendingEventSource.delete(entry.actorId);
+		if (initSent) send({
+			type: "@statelyai.system.actorSnapshot",
+			actorId: entry.actorId,
+			snapshot: serialized,
+			event: triggeringEvent ?? null,
+			...sourceActorId ? { sourceActorId } : {}
+		});
+		emitLocal("snapshot", entry);
+		const status = snapshot?.status;
+		if (status === "done" || status === "stopped" || status === "error") {
+			actors.delete(entry.actorId);
+			pendingEventSource.delete(entry.actorId);
+			if (initSent) send({
+				type: "@statelyai.system.actorStopped",
+				actorId: entry.actorId
+			});
+			emitLocal("stopped", { actorId: entry.actorId });
+		}
+	}
+	if (root) backfillActorTree(root);
+	const subscription = root ? root.system.inspect((inspectionEvent) => {
+		if (destroyed) return;
+		switch (inspectionEvent.type) {
+			case "@xstate.actor":
+				handleActor(inspectionEvent.actorRef);
+				break;
+			case "@xstate.event":
+				if (inspectionEvent.sourceRef) pendingEventSource.set(inspectionEvent.actorRef.sessionId, inspectionEvent.sourceRef.sessionId);
+				break;
+			case "@xstate.snapshot":
+				handleSnapshot(inspectionEvent.actorRef, inspectionEvent.snapshot, inspectionEvent.event);
+				break;
+			default: break;
+		}
+	}) : null;
+	function manualRegister(id, opts) {
+		if (actors.has(id)) return;
+		const entry = {
+			actorId: id,
+			parentActorId: opts?.parent ?? null,
+			rootId: rootActorId,
+			id,
+			systemId: opts?.systemId,
+			snapshot: opts?.snapshot ?? null,
+			machineConfig: opts?.machine ?? null
+		};
+		actors.set(id, entry);
+		if (initSent) send({
+			type: "@statelyai.system.actorRegistered",
+			actorId: id,
+			parentActorId: entry.parentActorId,
+			id,
+			machine: entry.machineConfig,
+			snapshot: entry.snapshot ?? void 0
+		});
+		emitRegisterOnce(entry);
+	}
+	function manualSnapshot(actorId, snapshot, event, sourceActorId) {
+		if (!actors.has(actorId)) manualRegister(actorId);
+		const entry = actors.get(actorId);
+		entry.snapshot = snapshot;
+		if (initSent) send({
+			type: "@statelyai.system.actorSnapshot",
+			actorId,
+			snapshot,
+			event: event ?? null,
+			...sourceActorId ? { sourceActorId } : {}
+		});
+		emitLocal("snapshot", entry);
+	}
+	function manualEvent(actorId, event, eventOpts) {
+		const eventObj = typeof event === "string" ? { type: event } : { ...event };
+		manualSnapshot(actorId, actors.get(actorId)?.snapshot ?? null, eventObj, eventOpts?.source ?? null);
+	}
+	function manualStop(actorId) {
+		if (!actors.has(actorId)) return;
+		actors.delete(actorId);
+		if (initSent) send({
+			type: "@statelyai.system.actorStopped",
+			actorId
+		});
+		emitLocal("stopped", { actorId });
+	}
 	return {
+		actors,
 		get sessionId() {
 			return sessionId;
 		},
-		inspect(opts) {
-			send(toInitMessage(opts));
-		},
-		update(machine, format) {
-			send({
-				type: "@statelyai.update",
-				machine,
-				format
-			});
-		},
-		setMode(mode) {
-			send({
-				type: "@statelyai.setMode",
-				mode
-			});
-		},
-		export(format, callOptions) {
-			return exportManager.start(format, callOptions, "Inspector is destroyed", () => destroyed);
-		},
 		on(event, handler) {
-			events.on(event, handler);
+			if (!localListeners[event]) localListeners[event] = /* @__PURE__ */ new Set();
+			localListeners[event].add(handler);
+			return () => {
+				localListeners[event].delete(handler);
+			};
 		},
 		off(event, handler) {
-			events.off(event, handler);
+			localListeners[event]?.delete(handler);
 		},
-		sendSnapshot(snapshot, event) {
-			send({
-				type: "@statelyai.inspectSnapshot",
-				snapshot,
-				event: event ?? null
-			});
+		export(format, callOptions) {
+			return exportManager.start(format, callOptions, "Inspector is destroyed", () => destroyed);
 		},
+		actor: manualRegister,
+		snapshot: manualSnapshot,
+		event: manualEvent,
+		stop: manualStop,
 		destroy() {
 			if (destroyed) return;
 			destroyed = true;
-			transport.destroy();
+			try {
+				subscription?.unsubscribe();
+			} catch {}
+			if (ownsTransport) transport.destroy();
 			exportManager.clear("Inspector destroyed");
 			events.clear();
+			actors.clear();
 			pendingMessages.length = 0;
+			for (const set of Object.values(localListeners)) set?.clear();
 		}
 	};
 }