@statelyai/sdk 0.10.2 → 0.11.0

package/README.md

@@ -85,10 +85,11 @@ Stream live actor-system state to the Stately inspector over WebSockets, with su
 import { createActor } from 'xstate';
 import { createStatelyInspector } from '@statelyai/sdk';
 
-const inspector = createStatelyInspector({
-  actor: createActor(machine),
-  autoOpen: true,
-});
+const actor = createActor(machine);
+const inspector = createStatelyInspector({ autoOpen: true });
+
+inspector.inspect(actor);
+actor.start();
 ```
 
 ### CLI and sync

package/dist/{graphToXStateTS-DOaLOySy.mjs → graphToXStateTS-DV62vO_d.mjs}

@@ -4668,6 +4668,7 @@ function deepSimplify(config) {
 	return config;
 }
 function buildMeta(meta, color) {
+	if (isCodeExpression(meta)) return meta;
 	const result = {};
 	if (meta) {
 		for (const [k, v] of Object.entries(meta)) if (v !== void 0 && v !== null) result[k] = v;
@@ -4675,6 +4676,9 @@ function buildMeta(meta, color) {
 	if (color) result["@statelyai.color"] = color;
 	return Object.keys(result).length > 0 ? result : void 0;
 }
+function isCodeExpression(value) {
+	return Boolean(value && typeof value === "object" && !Array.isArray(value) && value["@type"] === "code" && typeof value.expr === "string");
+}
 /** Format event param — supports { type: string } (new) and plain string (legacy) */
 function formatEventParam(event) {
 	if (event && typeof event === "object" && "type" in event) return formatInlineObject(event);

package/dist/index.d.mts

@@ -3,7 +3,7 @@ import { CommentsConfig, EmbedEventHandler, EmbedEventMap, EmbedEventName, Embed
 import { AssetUploadAdapter, AssetUploadContext, AssetUploadRequest, CreateS3AssetUploadAdapterOptions, CreateSupabaseAssetUploadAdapterOptions, S3UploadTarget, SupabaseStorageClient, createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
 import { AssetConfig, StatelyEmbed, StatelyEmbedOptions, createStatelyEmbed } from "./embed.mjs";
 import { C as EventTypeData, E as JSONSchema7, S as DigraphNodeConfig, T as CodeGenGraph, _ as studioMachineConverter, a as StatelyGraphData, b as DigraphConfig, c as StatelyInvoke, d as StudioAction, f as StudioEdge, g as fromStudioMachine, h as StudioNode, i as StatelyGraph, l as StatelyNodeData, m as StudioMachine, o as StatelyGuard, r as StatelyEdgeData, t as StatelyAction, v as toStudioMachine, w as StateNodeJSONData, x as DigraphEdgeConfig, y as DigraphAction } from "./graph-GeuH-mFK.mjs";
-import { a as ManualActorOptions, c as createPostMessageTransport, i as InspectorEvents, l as createWebSocketTransport, n as CreateInspectorOptions, o as createStatelyInspector, r as Inspector, s as Transport, t as AdoptedActor } from "./inspect-BLlM3qKf.mjs";
+import { a as ManualActorOptions, c as createPostMessageTransport, i as InspectorEvents, l as createWebSocketTransport, n as CreateInspectorOptions, o as createStatelyInspector, r as Inspector, s as Transport, t as AdoptedActor } from "./inspect-CZ8iLJR7.mjs";
 import { ConnectedRepo, CreateMachineFromDefinitionInput, CreateMachineFromTemplateInput, CreateMachineInput, CreateMachineTemplate, CreateProjectInput, EnsureProjectInput, ExtractMachinesResponse, ExtractedMachine, GetMachineOptions, ProjectData, ProjectMachine, ProjectVisibility, RepoType, StudioApiError, StudioClient, StudioClientOptions, StudioMachineRecord, UpdateMachineInput, VerifyApiKeyResponse, XStateVersion, createStatelyClient } from "./studio.mjs";
 import { PlanSyncOptions, PullSyncResult, PushLocalMachineLinksResult, PushSyncOptions, PushSyncProjectOptions, PushSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary } from "./sync.mjs";
 import { ActionLocation, GraphPatch } from "./patchTypes.mjs";

package/dist/index.mjs

@@ -4,7 +4,7 @@ import { createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./
 import { createStatelyInspector } from "./inspect.mjs";
 import { StudioApiError, createStatelyClient } from "./studio.mjs";
 import { StatelyApiError, createStatelyApiClient, createStatelyApiUrl } from "./api.mjs";
-import { S as upsertStatelyPragma, a as graphToMachineConfig, b as findStatelyPragmaAttachments, c as serializeJS, i as jsonSchemaToTSType, n as contextSchemaToTSType, o as RawCode, r as eventsSchemaToTSType, s as raw, t as graphToXStateTS, x as getStatelyPragma } from "./graphToXStateTS-DOaLOySy.mjs";
+import { S as upsertStatelyPragma, a as graphToMachineConfig, b as findStatelyPragmaAttachments, c as serializeJS, i as jsonSchemaToTSType, n as contextSchemaToTSType, o as RawCode, r as eventsSchemaToTSType, s as raw, t as graphToXStateTS, x as getStatelyPragma } from "./graphToXStateTS-DV62vO_d.mjs";
 import { fromStudioMachine, studioMachineConverter, toStudioMachine } from "./graph.mjs";
 
 export { RawCode, StatelyApiError, StudioApiError, contextSchemaToTSType, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, eventsSchemaToTSType, findStatelyPragmaAttachments, fromStudioMachine, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };

package/dist/{inspect-BLlM3qKf.d.mts → inspect-CZ8iLJR7.d.mts}

@@ -120,19 +120,13 @@ interface ManualActorOptions {
   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.
+   * Relay session id. Defaults to a random id. This is the `?session=<id>`
+   * value the viz iframe connects with.
    */
   sessionId?: string;
   /** Display name for this system in the visualizer. */
@@ -148,7 +142,7 @@ interface CreateInspectorOptions {
    * `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. */
+  /** Selected actor id to focus on first. Defaults to the first inspected root. */
   selectedActorId?: string;
   /** Panel layout forwarded into the system init message. */
   panels?: {
@@ -171,6 +165,10 @@ interface Inspector {
   readonly actors: ReadonlyMap<string, AdoptedActor>;
   /** The relay sessionId this inspector registered under. */
   readonly sessionId: string;
+  /** Adopt an xstate actor system. Existing actors are backfilled immediately. */
+  inspect(actor: any): {
+    unsubscribe(): void;
+  };
   /** 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;
@@ -201,6 +199,6 @@ interface Inspector {
   /** Tear down the WebSocket + xstate subscription. */
   destroy(): void;
 }
-declare function createStatelyInspector(options: CreateInspectorOptions): Inspector;
+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,3 +1,3 @@
 import { 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-BLlM3qKf.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-CZ8iLJR7.mjs";
 export { AdoptedActor, CreateInspectorOptions, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, Inspector, InspectorEvents, ManualActorOptions, Transport, createStatelyInspector };

package/dist/inspect.mjs

@@ -10,12 +10,10 @@ let nextManualId = 0;
 function generateSessionId() {
 	return `manual-${Date.now()}-${nextManualId++}`;
 }
-function createStatelyInspector(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");
+function createStatelyInspector(options = {}) {
+	const { url = "ws://localhost:4242", autoOpen = true, name, serializeSnapshot = defaultSerializeSnapshot, extractMachineConfig = defaultExtractMachineConfig, selectedActorId, panels, theme, readOnly, depth, transport: injectedTransport } = options;
+	const sessionId = options.sessionId ?? generateSessionId();
+	const displayName = name ?? "system:manual";
 	let destroyed = false;
 	let initSent = false;
 	const pendingMessages = [];
@@ -92,7 +90,7 @@ function createStatelyInspector(options) {
 			return null;
 		}
 	}
-	function toEntry(actorRef) {
+	function toEntry(actorRef, rootActorId) {
 		return {
 			actorId: actorRef.sessionId,
 			parentActorId: actorRef._parent?.sessionId ?? null,
@@ -116,22 +114,23 @@ function createStatelyInspector(options) {
 	* Walk the actor tree and populate the local `actors` map. Idempotent —
 	* existing entries stay in place but have their snapshot refreshed.
 	*/
-	function backfillActorTree(actorRef) {
+	function backfillActorTree(actorRef, rootActorId) {
 		const existing = actors.get(actorRef.sessionId);
-		const entry = existing ?? toEntry(actorRef);
+		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);
+		for (const child of Object.values(children)) if (child) backfillActorTree(child, rootActorId);
 	}
+	const inspectedRoots = /* @__PURE__ */ new Map();
 	function sendInit() {
-		if (root) backfillActorTree(root);
+		for (const [rootActorId, { actor }] of inspectedRoots) backfillActorTree(actor, rootActorId);
 		send({
 			type: "@statelyai.system.init",
 			mode: "inspecting",
 			actors: Array.from(actors.values()).map(toSystemEntry),
-			selectedActorId: selectedActorId ?? rootActorId,
+			selectedActorId: selectedActorId ?? inspectedRoots.keys().next().value ?? sessionId,
 			...theme && { theme },
 			...readOnly !== void 0 && { readOnly },
 			...depth !== void 0 && { depth },
@@ -141,9 +140,9 @@ function createStatelyInspector(options) {
 		});
 		initSent = true;
 	}
-	function handleActor(actorRef) {
+	function handleActor(actorRef, rootActorId) {
 		if (actors.has(actorRef.sessionId)) return;
-		const entry = toEntry(actorRef);
+		const entry = toEntry(actorRef, rootActorId);
 		actors.set(entry.actorId, entry);
 		if (!initSent) return;
 		send({
@@ -156,8 +155,8 @@ function createStatelyInspector(options) {
 		});
 		emitRegisterOnce(entry);
 	}
-	function handleSnapshot(actorRef, snapshot, triggeringEvent) {
-		if (!actors.has(actorRef.sessionId)) handleActor(actorRef);
+	function handleSnapshot(actorRef, snapshot, triggeringEvent, rootActorId) {
+		if (!actors.has(actorRef.sessionId)) handleActor(actorRef, rootActorId);
 		const entry = actors.get(actorRef.sessionId);
 		if (!entry) return;
 		const serialized = serializeSnapshot(snapshot);
@@ -183,28 +182,43 @@ function createStatelyInspector(options) {
 			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 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);
+					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, rootActorId);
+					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: rootActorId,
+			rootId: sessionId,
 			id,
 			systemId: opts?.systemId,
 			snapshot: opts?.snapshot ?? null,
@@ -252,6 +266,7 @@ function createStatelyInspector(options) {
 		get sessionId() {
 			return sessionId;
 		},
+		inspect: inspectActor,
 		on(event, handler) {
 			if (!localListeners[event]) localListeners[event] = /* @__PURE__ */ new Set();
 			localListeners[event].add(handler);
@@ -273,12 +288,13 @@ function createStatelyInspector(options) {
 			if (destroyed) return;
 			destroyed = true;
 			try {
-				subscription?.unsubscribe();
+				for (const { subscription } of inspectedRoots.values()) subscription.unsubscribe();
 			} catch {}
 			if (ownsTransport) transport.destroy();
 			exportManager.clear("Inspector destroyed");
 			events.clear();
 			actors.clear();
+			inspectedRoots.clear();
 			pendingMessages.length = 0;
 			for (const set of Object.values(localListeners)) set?.clear();
 		}

package/dist/sync.mjs

@@ -1,5 +1,5 @@
 import { createStatelyClient } from "./studio.mjs";
-import { S as upsertStatelyPragma, _ as string, b as findStatelyPragmaAttachments, d as boolean, f as discriminatedUnion, g as record, h as object, l as _enum, m as number, p as literal, t as graphToXStateTS, u as array, v as union, x as getStatelyPragma, y as unknown } from "./graphToXStateTS-DOaLOySy.mjs";
+import { S as upsertStatelyPragma, _ as string, b as findStatelyPragmaAttachments, d as boolean, f as discriminatedUnion, g as record, h as object, l as _enum, m as number, p as literal, t as graphToXStateTS, u as array, v as union, x as getStatelyPragma, y as unknown } from "./graphToXStateTS-DV62vO_d.mjs";
 import { fromStudioMachine, toStudioMachine } from "./graph.mjs";
 import * as ts$1 from "typescript";
 import ts from "typescript";
@@ -839,6 +839,7 @@ function deepSimplify(config) {
 	return config;
 }
 function buildMeta(meta, color) {
+	if (isCodeExpression(meta)) return meta;
 	const result = {};
 	if (meta) {
 		for (const [k, v] of Object.entries(meta)) if (v !== void 0 && v !== null) result[k] = v;
@@ -846,6 +847,9 @@ function buildMeta(meta, color) {
 	if (color) result["@statelyai.color"] = color;
 	return Object.keys(result).length > 0 ? result : void 0;
 }
+function isCodeExpression(value) {
+	return Boolean(value && typeof value === "object" && !Array.isArray(value) && value["@type"] === "code" && typeof value.expr === "string");
+}
 /** Format event param — supports { type: string } (new) and plain string (legacy) */
 function formatEventParam(event) {
 	if (event && typeof event === "object" && "type" in event) return formatInlineObject(event);
@@ -1003,7 +1007,7 @@ function actionCodeExpression(expr, source) {
 		}]
 	};
 }
-function inlineCodeExpression(expr) {
+function inlineCodeExpression$1(expr) {
 	return {
 		"@type": "code",
 		lang: "ts",
@@ -1021,7 +1025,7 @@ function serializeGuard(guard, asTypeRef) {
 		type: guard.type,
 		params: guard.params
 	} : { type: guard.type };
-	return guard.code ? inlineCodeExpression(guard.code) : guard;
+	return guard.code ? inlineCodeExpression$1(guard.code) : guard;
 }
 /**
 * Converts a built-in xstate ActionItem to a code expression directive,
@@ -1034,7 +1038,7 @@ function serializeActionItem(action) {
 		const builtInAction = XSTATE_BUILT_IN_ACTIONS[type];
 		return actionCodeExpression(emitBuiltInAction(type, params), builtInAction);
 	}
-	if (exprCode) return inlineCodeExpression(exprCode);
+	if (exprCode) return inlineCodeExpression$1(exprCode);
 	if (!params || Object.keys(params).length === 0) return { type };
 	return {
 		type,
@@ -1633,6 +1637,10 @@ function propertyContext(parent, key) {
 		v6: parent.v6,
 		actionValue: true
 	};
+	if (key === "meta") return {
+		v6: parent.v6,
+		metaValue: true
+	};
 	if (parent.transitionValue && key === "to") return {
 		v6: parent.v6,
 		transitionValue: true
@@ -1943,6 +1951,13 @@ function inlineAction(fn) {
 		}
 	};
 }
+function inlineCodeExpression(expr) {
+	return {
+		"@type": "code",
+		lang: "ts",
+		expr
+	};
+}
 function normalizeFunctionAction(fn, bindings) {
 	if (ts.isArrowFunction(fn) && !ts.isBlock(fn.body)) return inlineAction(fn);
 	if (!fn.body || !ts.isBlock(fn.body)) return inlineAction(fn);
@@ -2003,7 +2018,7 @@ function expressionToValue(expression, bindings, context = {}, depth = 0) {
 	if (ts.isIdentifier(node)) {
 		if (node.text === "undefined") return void 0;
 		const binding = bindings.get(node.text);
-		return binding ? expressionToValue(binding, bindings, context, depth + 1) : node.text;
+		return binding ? expressionToValue(binding, bindings, context, depth + 1) : context.metaValue ? inlineCodeExpression(node.getText()) : node.text;
 	}
 	if (ts.isObjectLiteralExpression(node)) return objectLiteralToValue(node, bindings, context, depth);
 	if (ts.isArrayLiteralExpression(node)) {
@@ -2011,17 +2026,19 @@ function expressionToValue(expression, bindings, context = {}, depth = 0) {
 		return context.actionValue ? values.flat() : values;
 	}
 	if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+		if (context.metaValue) return inlineCodeExpression(node.getText());
 		if (context.v6 && context.transitionValue) return normalizeFunctionTransition(node, bindings, depth);
 		if (context.v6 && context.actionValue) return normalizeFunctionAction(node, bindings);
 		return node.getText();
 	}
 	if (ts.isCallExpression(node)) {
+		if (context.metaValue) return inlineCodeExpression(node.getText());
 		if (context.actionValue) return inlineAction(node);
 		const callee = node.expression.getText();
 		const type = callee.includes(".") ? callee.split(".").pop() : callee;
 		return { type: type === "assign" ? "xstate.assign" : type };
 	}
-	return node.getText();
+	return context.metaValue ? inlineCodeExpression(node.getText()) : node.getText();
 }
 function collectBindings$1(file) {
 	const bindings = /* @__PURE__ */ new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/sdk",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "license": "MIT",
   "files": [
     "dist",