@statelyai/sdk 0.4.1 → 0.5.1

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-BPuwbNCz.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-ttRIjoCu.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-DoCHBLTu.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();
 		}
 	};
 }

package/dist/patchTypes.d.mts

@@ -0,0 +1,249 @@
+//#region src/patchTypes.d.ts
+type EditorStateType = 'normal' | 'parallel' | 'history' | 'final' | null;
+type CanvasColor = 'green' | 'red' | 'purple' | 'blue' | 'orange' | 'yellow' | 'pink' | 'teal';
+type ActionLocation = {
+  nodeId: string;
+  group: 'entry' | 'exit';
+} | {
+  edgeId: string;
+  group: 'transition';
+};
+type ImplementationSourceType = 'action' | 'guard' | 'actor' | 'delay';
+type GraphPatch = {
+  op: 'createNode';
+  description?: string;
+  id?: string;
+  parentId: string;
+  key: string;
+  type?: EditorStateType;
+  x?: number;
+  y?: number;
+} | {
+  op: 'updateNode';
+  description?: string;
+  nodeId: string;
+  data: {
+    key?: string;
+    type?: EditorStateType;
+    description?: string;
+    initialId?: string | null;
+  };
+} | {
+  op: 'deleteNode';
+  description?: string;
+  nodeId: string;
+} | {
+  op: 'createEdge';
+  description?: string;
+  id?: string;
+  sourceId: string;
+  targetId: string;
+  eventType: string;
+  transitionType?: 'normal' | 'targetless' | 'reenter';
+} | {
+  op: 'updateEdge';
+  description?: string;
+  edgeId: string;
+  data: {
+    sourceId?: string;
+    targetId?: string;
+    eventType?: string;
+    transitionType?: 'normal' | 'targetless' | 'reenter';
+    description?: string | null;
+  };
+} | {
+  op: 'deleteEdge';
+  description?: string;
+  edgeId: string;
+} | {
+  op: 'createState';
+  description?: string;
+  id?: string;
+  parentId: string;
+  key: string;
+  type?: EditorStateType;
+  x?: number;
+  y?: number;
+  color?: CanvasColor | null;
+  initial?: boolean;
+} | {
+  op: 'updateState';
+  description?: string;
+  stateId: string;
+  key?: string;
+  type?: EditorStateType;
+  stateDescription?: string;
+  initialId?: string | null;
+  color?: CanvasColor | null;
+  meta?: Record<string, unknown> | null;
+  history?: 'shallow' | 'deep' | null;
+} | {
+  op: 'deleteState';
+  description?: string;
+  stateId: string;
+} | {
+  op: 'createTransition';
+  description?: string;
+  id?: string;
+  sourceId: string;
+  targetId: string;
+  eventType: string;
+  transitionType?: 'normal' | 'targetless' | 'reenter';
+  guard?: {
+    type: string;
+    code?: string;
+    params?: Record<string, unknown>;
+  };
+  color?: CanvasColor | null;
+  transitionDescription?: string | null;
+} | {
+  op: 'updateTransition';
+  description?: string;
+  transitionId: string;
+  sourceId?: string;
+  targetId?: string;
+  eventType?: string;
+  transitionType?: 'normal' | 'targetless' | 'reenter';
+  transitionDescription?: string | null;
+  color?: CanvasColor | null;
+  meta?: Record<string, unknown> | null;
+} | {
+  op: 'deleteTransition';
+  description?: string;
+  transitionId: string;
+} | {
+  op: 'createAction';
+  description?: string;
+  location: ActionLocation;
+  action: {
+    id?: string;
+    type: string;
+    params?: Record<string, unknown>;
+    code?: string;
+  };
+  index?: number;
+} | {
+  op: 'updateAction';
+  description?: string;
+  location: ActionLocation;
+  actionId: string;
+  data: {
+    type?: string;
+    params?: Record<string, unknown>;
+    code?: string;
+  };
+} | {
+  op: 'deleteAction';
+  description?: string;
+  location: ActionLocation;
+  actionId: string;
+} | {
+  op: 'createInvoke';
+  description?: string;
+  nodeId: string;
+  invoke: {
+    id?: string;
+    src: string;
+    code?: string;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+  };
+} | {
+  op: 'updateInvoke';
+  description?: string;
+  nodeId: string;
+  invokeId: string;
+  data: {
+    src?: string;
+    code?: string;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+  };
+} | {
+  op: 'deleteInvoke';
+  description?: string;
+  nodeId: string;
+  invokeId: string;
+} | {
+  op: 'createImplementation';
+  description?: string;
+  sourceType: ImplementationSourceType;
+  implementation: {
+    id: string;
+    name?: string;
+    code?: string;
+  };
+} | {
+  op: 'updateImplementation';
+  description?: string;
+  sourceType: ImplementationSourceType;
+  implementationId: string;
+  data: {
+    name?: string;
+    code?: string;
+  };
+} | {
+  op: 'deleteImplementation';
+  description?: string;
+  sourceType: ImplementationSourceType;
+  implementationId: string;
+} | {
+  op: 'setGuard';
+  description?: string;
+  edgeId: string;
+  guard: {
+    type: string;
+    code?: string;
+    params?: Record<string, unknown>;
+  };
+} | {
+  op: 'deleteGuard';
+  description?: string;
+  edgeId: string;
+} | {
+  op: 'createTag';
+  description?: string;
+  nodeId: string;
+  tag: {
+    name: string;
+  };
+} | {
+  op: 'deleteTag';
+  description?: string;
+  nodeId: string;
+  tagName: string;
+} | {
+  op: 'createAnnotation';
+  description?: string;
+  id?: string;
+  parentId: string | null;
+  content: string;
+  x?: number;
+  y?: number;
+} | {
+  op: 'updateAnnotation';
+  description?: string;
+  annotationId: string;
+  data: {
+    content?: string;
+  };
+} | {
+  op: 'deleteAnnotation';
+  description?: string;
+  annotationId: string;
+} | {
+  op: 'setContext';
+  description?: string;
+  context: Record<string, unknown>;
+} | {
+  op: 'updateSchemas';
+  description?: string;
+  schemas: {
+    context?: Record<string, unknown> | null;
+    events?: Record<string, unknown> | null;
+    input?: unknown | null;
+    output?: unknown | null;
+  };
+};
+//#endregion
+export { ActionLocation, CanvasColor, EditorStateType, GraphPatch, ImplementationSourceType };

package/dist/patchTypes.mjs

@@ -0,0 +1 @@
+export {  };