@statelyai/sdk 0.12.3 → 0.13.0

package/dist/inspect-D9GyHTTW.mjs

@@ -0,0 +1,469 @@
+import { a as createPendingExportManager, i as createEventRegistry, r as createWebSocketTransport } from "./transport-D2Ud05yg.mjs";
+import { INSPECTION_PROTOCOL_VERSION } from "./protocol.mjs";
+
+//#region src/openBrowser.ts
+async function openBrowser(url) {
+	if (typeof process === "undefined" || !process.versions?.node || typeof process.getBuiltinModule !== "function") return;
+	const { spawn } = process.getBuiltinModule("node:child_process");
+	const child = spawn(process.platform === "darwin" ? "open" : process.platform === "win32" ? "powershell.exe" : "xdg-open", process.platform === "win32" ? [
+		"-NoProfile",
+		"-NonInteractive",
+		"-Command",
+		"Start-Process -FilePath $args[0]",
+		"--",
+		url
+	] : [url], {
+		detached: true,
+		stdio: "ignore",
+		windowsHide: true
+	});
+	await new Promise((resolve, reject) => {
+		child.once("spawn", () => {
+			child.unref();
+			resolve();
+		});
+		child.once("error", (error) => reject(error));
+	});
+}
+
+//#endregion
+//#region src/inspect.ts
+const defaultSerializeSnapshot = (snapshot) => ({
+	value: snapshot?.value,
+	status: snapshot?.status
+});
+const defaultExtractMachineConfig = (actor, source) => actor?.logic?.config ?? source?.config ?? null;
+let nextManualId = 0;
+function generateSessionId() {
+	return `manual-${Date.now()}-${nextManualId++}`;
+}
+function createInspectorLaunchUrl(websocketUrl, sessionId) {
+	try {
+		const launchUrl = new URL(websocketUrl);
+		if (launchUrl.protocol === "ws:") launchUrl.protocol = "http:";
+		else if (launchUrl.protocol === "wss:") launchUrl.protocol = "https:";
+		else return null;
+		launchUrl.searchParams.set("session", sessionId);
+		return launchUrl.toString();
+	} catch {
+		return null;
+	}
+}
+function createInspector(options = {}) {
+	const { url = "ws://localhost:4242", autoOpen = true, name, serializeSnapshot = defaultSerializeSnapshot, extractMachineConfig = defaultExtractMachineConfig, selectedActorId, panels, theme, readOnly, depth, capabilities, transport: injectedTransport } = options;
+	const sessionId = options.sessionId ?? generateSessionId();
+	const displayName = name ?? "system:manual";
+	let destroyed = false;
+	let initSent = false;
+	let initialized = false;
+	let pendingTransportReady = false;
+	let didAutoOpen = false;
+	const pendingMessages = [];
+	const events = createEventRegistry();
+	const localListeners = {};
+	const transport = injectedTransport ?? createWebSocketTransport({
+		url,
+		role: "client",
+		sessionId,
+		metadata: { name: displayName }
+	});
+	const ownsTransport = !injectedTransport;
+	const exportManager = createPendingExportManager((message) => send(message));
+	function send(msg) {
+		if (!transport.ready) {
+			pendingMessages.push(msg);
+			return;
+		}
+		transport.send(msg);
+	}
+	function handleTransportReady() {
+		pendingMessages.length = 0;
+		initSent = false;
+		sendInit();
+		if (autoOpen && !didAutoOpen && ownsTransport) {
+			didAutoOpen = true;
+			const launchUrl = createInspectorLaunchUrl(url, sessionId);
+			if (launchUrl) openBrowser(launchUrl).catch((error) => {
+				const failure = {
+					code: "open_failed",
+					message: error instanceof Error ? error.message : "Unable to open the inspector browser"
+				};
+				emitLocal("error", failure);
+				events.emit("error", failure);
+			});
+		}
+	}
+	transport.onReady(() => {
+		if (!initialized) {
+			pendingTransportReady = true;
+			return;
+		}
+		handleTransportReady();
+	});
+	transport.onMessage((msg) => {
+		if (destroyed) return;
+		switch (msg.type) {
+			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 actor events for. */
+	const locallyRegistered = /* @__PURE__ */ new Set();
+	/** v5 emits transition facets separately; accumulate them until snapshot. */
+	const pendingTransitions = /* @__PURE__ */ new Map();
+	function emitRegisterOnce(entry) {
+		if (locallyRegistered.has(entry.actorId)) return;
+		locallyRegistered.add(entry.actorId);
+		emitLocal("actor", entry);
+		emitLocal("register", entry);
+	}
+	function snapshotValue(actorRef) {
+		try {
+			return serializeSnapshot(actorRef.getSnapshot());
+		} catch {
+			return null;
+		}
+	}
+	function toEntry(actorRef, rootActorId, details) {
+		return {
+			actorId: actorRef.sessionId,
+			parentActorId: details?.parentRef?.sessionId ?? actorRef._parent?.sessionId ?? null,
+			rootId: rootActorId,
+			id: details?.id ?? actorRef.id ?? actorRef.sessionId,
+			systemId: actorRef.systemId,
+			snapshot: details?.snapshot ? serializeSnapshot(details.snapshot) : snapshotValue(actorRef),
+			machineConfig: extractMachineConfig(actorRef, details?.source ?? actorRef.src)
+		};
+	}
+	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, rootActorId) {
+		const existing = actors.get(actorRef.sessionId);
+		const entry = existing ?? toEntry(actorRef, rootActorId);
+		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, rootActorId);
+	}
+	const inspectedRoots = /* @__PURE__ */ new Map();
+	function sendInit() {
+		for (const [rootActorId, { actor }] of inspectedRoots) backfillActorTree(actor, rootActorId);
+		send({
+			type: "@statelyai.system.init",
+			protocolVersion: INSPECTION_PROTOCOL_VERSION,
+			mode: "inspecting",
+			actors: Array.from(actors.values()).map(toSystemEntry),
+			selectedActorId: selectedActorId ?? inspectedRoots.keys().next().value ?? sessionId,
+			...theme && { theme },
+			...readOnly !== void 0 && { readOnly },
+			...depth !== void 0 && { depth },
+			...capabilities !== void 0 && { capabilities },
+			...panels?.leftPanels && { leftPanels: panels.leftPanels },
+			...panels?.rightPanels && { rightPanels: panels.rightPanels },
+			...panels?.activePanels && { activePanels: panels.activePanels }
+		});
+		initSent = true;
+	}
+	function handleActor(actorRef, rootActorId, details) {
+		if (actors.has(actorRef.sessionId)) return;
+		const entry = toEntry(actorRef, rootActorId, details);
+		actors.set(entry.actorId, entry);
+		emitRegisterOnce(entry);
+		if (initSent) send({
+			type: "@statelyai.system.actorRegistered",
+			actorId: entry.actorId,
+			parentActorId: entry.parentActorId,
+			id: entry.id,
+			machine: entry.machineConfig,
+			snapshot: entry.snapshot ?? void 0
+		});
+	}
+	function normalizeAction(action) {
+		return {
+			type: action.type,
+			...action.params !== void 0 && { params: action.params }
+		};
+	}
+	function normalizeTakenTransition(transition) {
+		const raw = transition;
+		const json = raw?.toJSON?.();
+		const source = raw?.source ?? json?.source;
+		const targets = raw?.target ?? json?.target ?? [];
+		return {
+			sourceStateId: typeof source === "string" ? source : source?.id ?? null,
+			targetStateIds: targets.map((target) => typeof target === "string" ? target : target.id ?? "").filter(Boolean),
+			...(raw?.eventType ?? json?.eventType) && { eventType: raw?.eventType ?? json?.eventType },
+			...(raw?.reenter ?? json?.reenter) !== void 0 && { reenter: raw?.reenter ?? json?.reenter }
+		};
+	}
+	function normalizeSentEvent(sentEvent) {
+		return {
+			...sentEvent.targetRef?.sessionId && { targetActorId: sentEvent.targetRef.sessionId },
+			targetId: sentEvent.targetId,
+			event: sentEvent.event,
+			...sentEvent.delay !== void 0 && { delay: sentEvent.delay },
+			...sentEvent.id !== void 0 && { id: sentEvent.id }
+		};
+	}
+	function createPendingTransition(actorRef, event = null, sourceRef) {
+		return {
+			previousSnapshot: actors.get(actorRef.sessionId)?.snapshot ?? null,
+			event,
+			sourceActorId: sourceRef?.sessionId ?? null,
+			actions: [],
+			transitions: [],
+			sent: []
+		};
+	}
+	function getPendingTransition(actorRef, event) {
+		const existing = pendingTransitions.get(actorRef.sessionId);
+		if (existing) return existing;
+		const pending = createPendingTransition(actorRef, event);
+		pendingTransitions.set(actorRef.sessionId, pending);
+		return pending;
+	}
+	function handleTransition(actorRef, snapshot, triggeringEvent, rootActorId, transition) {
+		if (!actors.has(actorRef.sessionId)) handleActor(actorRef, rootActorId);
+		const entry = actors.get(actorRef.sessionId);
+		if (!entry) return;
+		const serialized = serializeSnapshot(snapshot);
+		const inspectedTransition = {
+			actorId: entry.actorId,
+			sourceActorId: transition.sourceActorId,
+			previousSnapshot: transition.previousSnapshot,
+			snapshot: serialized,
+			event: triggeringEvent ?? transition.event ?? null,
+			actions: transition.actions,
+			transitions: transition.transitions,
+			sent: transition.sent
+		};
+		entry.snapshot = serialized;
+		pendingTransitions.delete(entry.actorId);
+		if (initSent) send({
+			type: "@statelyai.system.actorSnapshot",
+			actorId: entry.actorId,
+			previousSnapshot: inspectedTransition.previousSnapshot,
+			snapshot: inspectedTransition.snapshot,
+			event: inspectedTransition.event,
+			sourceActorId: inspectedTransition.sourceActorId,
+			actions: inspectedTransition.actions,
+			transitions: inspectedTransition.transitions,
+			sent: inspectedTransition.sent
+		});
+		emitLocal("transition", inspectedTransition);
+		emitLocal("snapshot", entry);
+		const status = snapshot?.status;
+		if (status === "done" || status === "stopped" || status === "error") {
+			actors.delete(entry.actorId);
+			pendingTransitions.delete(entry.actorId);
+			if (initSent) send({
+				type: "@statelyai.system.actorStopped",
+				actorId: entry.actorId
+			});
+			const stopped = { actorId: entry.actorId };
+			emitLocal("stop", stopped);
+			emitLocal("stopped", stopped);
+		}
+	}
+	function inspectActor(actor) {
+		const root = actor;
+		const rootActorId = root.sessionId;
+		const existing = inspectedRoots.get(rootActorId);
+		if (existing) return existing.subscription;
+		const subscription = root.system.inspect((inspectionEvent) => {
+			if (destroyed) return;
+			switch (inspectionEvent.type) {
+				case "@xstate.actor":
+					handleActor(inspectionEvent.actorRef, rootActorId, {
+						parentRef: inspectionEvent.parentRef,
+						id: inspectionEvent.id,
+						source: inspectionEvent.src,
+						snapshot: inspectionEvent.snapshot
+					});
+					break;
+				case "@xstate.event":
+					pendingTransitions.set(inspectionEvent.actorRef.sessionId, createPendingTransition(inspectionEvent.actorRef, inspectionEvent.event, inspectionEvent.sourceRef));
+					break;
+				case "@xstate.action":
+					getPendingTransition(inspectionEvent.actorRef).actions.push(normalizeAction(inspectionEvent.action));
+					break;
+				case "@xstate.microstep":
+					getPendingTransition(inspectionEvent.actorRef, inspectionEvent.event).transitions.push(...(inspectionEvent._transitions ?? []).map(normalizeTakenTransition));
+					break;
+				case "@xstate.snapshot": {
+					const pending = getPendingTransition(inspectionEvent.actorRef, inspectionEvent.event);
+					handleTransition(inspectionEvent.actorRef, inspectionEvent.snapshot, inspectionEvent.event, rootActorId, pending);
+					break;
+				}
+				case "@xstate.transition":
+					if (!inspectionEvent.actions || !inspectionEvent.microsteps || !inspectionEvent.sent) break;
+					handleTransition(inspectionEvent.actorRef, inspectionEvent.snapshot, inspectionEvent.event, rootActorId, {
+						previousSnapshot: actors.get(inspectionEvent.actorRef.sessionId)?.snapshot ?? null,
+						event: inspectionEvent.event,
+						sourceActorId: inspectionEvent.sourceRef?.sessionId ?? null,
+						actions: inspectionEvent.actions.map(normalizeAction),
+						transitions: inspectionEvent.microsteps.map(normalizeTakenTransition),
+						sent: inspectionEvent.sent.map(normalizeSentEvent)
+					});
+					break;
+				default: break;
+			}
+		});
+		inspectedRoots.set(rootActorId, {
+			actor: root,
+			subscription
+		});
+		backfillActorTree(root, rootActorId);
+		if (initSent) sendInit();
+		return { unsubscribe() {
+			subscription.unsubscribe();
+			inspectedRoots.delete(rootActorId);
+		} };
+	}
+	function manualRegister(id, opts) {
+		if (actors.has(id)) return;
+		const entry = {
+			actorId: id,
+			parentActorId: opts?.parent ?? null,
+			rootId: sessionId,
+			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);
+		const previousSnapshot = entry.snapshot;
+		const transition = {
+			actorId,
+			sourceActorId: sourceActorId ?? null,
+			previousSnapshot,
+			snapshot,
+			event: event ?? null,
+			actions: [],
+			transitions: [],
+			sent: []
+		};
+		entry.snapshot = snapshot;
+		if (initSent) send({
+			type: "@statelyai.system.actorSnapshot",
+			actorId,
+			previousSnapshot,
+			snapshot,
+			event: event ?? null,
+			sourceActorId: sourceActorId ?? null,
+			actions: [],
+			transitions: [],
+			sent: []
+		});
+		emitLocal("transition", transition);
+		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
+		});
+		const stopped = { actorId };
+		emitLocal("stop", stopped);
+		emitLocal("stopped", stopped);
+	}
+	initialized = true;
+	if (pendingTransportReady) {
+		pendingTransportReady = false;
+		handleTransportReady();
+	}
+	return {
+		actors,
+		get sessionId() {
+			return sessionId;
+		},
+		inspect: inspectActor,
+		on(event, handler) {
+			if (!localListeners[event]) localListeners[event] = /* @__PURE__ */ new Set();
+			localListeners[event].add(handler);
+			return () => {
+				localListeners[event].delete(handler);
+			};
+		},
+		off(event, handler) {
+			localListeners[event]?.delete(handler);
+		},
+		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;
+			try {
+				for (const { subscription } of inspectedRoots.values()) subscription.unsubscribe();
+			} catch {}
+			if (ownsTransport) transport.destroy();
+			exportManager.clear("Inspector destroyed");
+			events.clear();
+			actors.clear();
+			inspectedRoots.clear();
+			pendingTransitions.clear();
+			pendingMessages.length = 0;
+			for (const set of Object.values(localListeners)) set?.clear();
+		}
+	};
+}
+/** @deprecated Use {@link createInspector}. */
+const createStatelyInspector = createInspector;
+
+//#endregion
+export { createStatelyInspector as n, createInspector as t };

package/dist/inspect.d.mts

@@ -1,3 +1,3 @@
-import { EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap } from "./protocol.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-BmZUcnZB.mjs";
-export { AdoptedActor, CreateInspectorOptions, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, Inspector, InspectorEvents, ManualActorOptions, Transport, createStatelyInspector };
+import { EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InspectionAction, InspectionSentEvent, InspectionTakenTransition } from "./protocol.mjs";
+import { a as InspectorEvents, c as createStatelyInspector, f as Transport, i as Inspector, n as CreateInspectorOptions, o as ManualActorOptions, r as InspectedTransition, s as createInspector, t as AdoptedActor } from "./inspect-BMHheAvx.mjs";
+export { AdoptedActor, CreateInspectorOptions, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InspectedTransition, InspectionAction, InspectionSentEvent, InspectionTakenTransition, Inspector, InspectorEvents, ManualActorOptions, Transport, createInspector, createStatelyInspector };