@statelyai/sdk 0.13.4 → 0.14.1

package/LICENSE

@@ -1,10 +1,21 @@
-Copyright (c) 2025 Stately Software, Inc.
+MIT License
 
-All rights reserved.
+Copyright (c) 2026 Stately Software, Inc.
 
-This repository and the Stately Viz software are proprietary to Stately
-Software, Inc. No rights are granted to use, copy, modify, distribute, host, or
-sublicense this software except under a separate written agreement with Stately
-Software, Inc.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-For licensing inquiries, contact team@stately.ai.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -115,21 +115,28 @@ Stream live actor-system state to the Stately inspector over WebSockets, with su
 import { createActor } from 'xstate';
 import { createInspector } from '@statelyai/sdk';
 
-const actor = createActor(machine);
 const inspector = createInspector({
   url: 'ws://localhost:4242',
 });
+const { inspect } = inspector;
 
-inspector.inspect(actor);
+const actor = createActor(machine, { inspect });
 actor.start();
 ```
 
-XState v5 and v6 inspection events normalize to actor, transition, and stop
-events before crossing the WebSocket protocol.
+If you already have the actor reference, `inspector.attach(actor)` subscribes to
+its system and backfills actors that are already running.
+
+Stopped actors remain in `inspector.actors` and in reconnect checkpoints, so
+completed request-scoped runs stay available for inspection.
+
+XState v5 and v6 inspection events normalize to independent actor, event,
+snapshot, and stop observations before crossing the WebSocket protocol.
 In Node, the inspector opens in the default browser automatically. The SDK
-generates a cryptographically random session capability; hosted inspectors send
-signed-out users through OAuth and return them to that same live session. The
-Node process does not need a Stately API key.
+generates a cryptographically random session capability; hosted inspectors open
+without requiring login. The session capability controls access to the live
+session. AI-backed features remain separately authenticated. The Node process
+does not need a Stately API key.
 
 ### CLI and sync
 

package/dist/{dist-CHGcvOdQ.mjs → dist-C8jVuuHf.mjs}

@@ -8713,6 +8713,7 @@ const validationIssueCodeSchema = _enum([
 	"empty_parallel",
 	"single_child_compound",
 	"noop_transient_state",
+	"sole_default_choice",
 	"on_done_unreachable",
 	"duplicate_transition",
 	"invalid_delay",

package/dist/index.d.mts

@@ -5,7 +5,7 @@ import { i as getCredentialToken, n as StatelyCredential, r as createAuthorizati
 import { AssetConfig, StatelyEmbed, StatelyEmbedOptions, createStatelyEmbed } from "./embed.mjs";
 import { _ as serializeJS, c as MachineConfigOptions, d as contextSchemaToTSType, f as eventsSchemaToTSType, g as raw, h as jsonSchemaToTSType, i as CodeGenGraph, l as RawCode, m as graphToXStateTS, o as GraphPatch, p as graphToMachineConfig, t as ActionLocation, u as XStateTSOptions } from "./index-DVjNSTuQ.mjs";
 import { C as EventTypeData, S as DigraphNodeConfig, _ 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-R0sbxnZ7.mjs";
-import { a as InspectorEvents, c as createStatelyInspector, d as MultiplexedWebSocketConnectionOptions, f as Transport, h as createWebSocketTransport, i as Inspector, l as MultiplexedChannelOptions, m as createPostMessageTransport, n as CreateInspectorOptions, o as ManualActorOptions, p as createMultiplexedWebSocketConnection, r as InspectedTransition, s as createInspector, t as AdoptedActor, u as MultiplexedWebSocketConnection } from "./inspect-COqtklcn.mjs";
+import { _ as createPostMessageTransport, a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f as MultiplexedChannelOptions, g as createMultiplexedWebSocketConnection, h as Transport, i as InspectedSnapshot, l as ManualActorOptions, m as MultiplexedWebSocketConnectionOptions, n as CreateInspectorOptions, o as Inspector, p as MultiplexedWebSocketConnection, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector, v as createWebSocketTransport } from "./inspect-DQ_7I7eH.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 { OAuthAuthorizationServerMetadata, OAuthClientRegistrationResponse, OAuthProtectedResourceMetadata, OAuthTokenResponse, PkcePair, buildAuthorizeUrl, createPkcePair, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, refreshToken, registerOAuthClient } from "./oauth.mjs";
 import { PlanSyncOptions, PullSyncResult, PushLocalMachineLinksResult, PushSyncOptions, PushSyncProjectOptions, PushSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary } from "./sync.mjs";
@@ -32,4 +32,4 @@ declare function findStatelyPragmaAttachments(sourceText: string, fileName?: str
 declare function getStatelyPragma(sourceText: string, fileName?: string, machineIndex?: number): StatelyPragma | undefined;
 declare function upsertStatelyPragma(sourceText: string, id: string, options?: UpsertStatelyPragmaOptions): string;
 //#endregion
-export { type ActionLocation, type AdoptedActor, type AssetConfig, type AssetUploadAdapter, type AssetUploadContext, type AssetUploadRequest, type CapabilityDeniedCapability, type CapabilityDeniedEvent, type CodeGenGraph, type CommentsConfig, type ConnectedRepo, type CreateInspectionRelayOptions, type CreateInspectorOptions, type CreateMachineFromDefinitionInput, type CreateMachineFromTemplateInput, type CreateMachineInput, type CreateMachineTemplate, type CreateProjectInput, type CreateS3AssetUploadAdapterOptions, type CreateSupabaseAssetUploadAdapterOptions, type DigraphAction, type DigraphConfig, type DigraphEdgeConfig, type DigraphNodeConfig, type EditorCapabilities, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type EnsureProjectInput, type EventTypeData, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type ExtractMachinesResponse, type ExtractedMachine, type GetMachineOptions, type GraphPatch, INSPECTION_PROTOCOL_VERSION, type InitOptions, type InspectedTransition, type InspectionAction, type InspectionRelay, type InspectionRelayEffect, type InspectionRelayPeer, type InspectionRelayRole, type InspectionRelaySnapshot, type InspectionSentEvent, type InspectionTakenTransition, type Inspector, type InspectorEvents, type MachineConfigOptions, type ManualActorOptions, type MultiplexedChannelOptions, type MultiplexedWebSocketConnection, type MultiplexedWebSocketConnectionOptions, type OAuthAuthorizationServerMetadata, type OAuthClientRegistrationResponse, type OAuthProtectedResourceMetadata, type OAuthTokenResponse, type PkcePair, type PlanSyncOptions, type ProjectData, type ProjectEmbedMachine, type ProjectMachine, type ProjectVisibility, type PullSyncResult, type PushLocalMachineLinksResult, type PushSyncOptions, type PushSyncProjectOptions, type PushSyncResult, RawCode, type RepoType, type ResolvedSyncInput, type S3UploadTarget, type StateNodeJSONData, type StatelyAction, type StatelyApiClientOptions, StatelyApiError, type StatelyApiUrlOptions, type StatelyAuthMode, type StatelyCredential, type StatelyEdgeData, type StatelyEmbed, type StatelyEmbedOptions, type StatelyGraph, type StatelyGraphData, type StatelyGuard, type StatelyInvoke, type StatelyNodeData, type StatelyPragma, type StatelyPragmaAttachment, type StudioAction, StudioApiError, type StudioClient, type StudioClientOptions, type StudioEdge, type StudioMachine, type StudioMachineRecord, type StudioNode, type SupabaseStorageClient, type SyncInputFormat, type SyncPlan, type SyncPlanSummary, type Transport, type UpdateMachineInput, type UploadResult, type UpsertStatelyPragmaOptions, type VerifyApiKeyResponse, type XStateTSOptions, type XStateVersion, buildAuthorizeUrl, contextSchemaToTSType, createAuthorizationHeader, createInspectionRelay, createInspector, createMultiplexedWebSocketConnection, createPkcePair, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, discoverAuthorizationServer, discoverProtectedResource, eventsSchemaToTSType, exchangeCodeForToken, findStatelyPragmaAttachments, fromStudioMachine, getCredentialToken, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, refreshToken, registerOAuthClient, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };
+export { type ActionLocation, type AdoptedActor, type AssetConfig, type AssetUploadAdapter, type AssetUploadContext, type AssetUploadRequest, type CapabilityDeniedCapability, type CapabilityDeniedEvent, type CodeGenGraph, type CommentsConfig, type ConnectedRepo, type CreateInspectionRelayOptions, type CreateInspectorOptions, type CreateMachineFromDefinitionInput, type CreateMachineFromTemplateInput, type CreateMachineInput, type CreateMachineTemplate, type CreateProjectInput, type CreateS3AssetUploadAdapterOptions, type CreateSupabaseAssetUploadAdapterOptions, type DigraphAction, type DigraphConfig, type DigraphEdgeConfig, type DigraphNodeConfig, type EditorCapabilities, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type EnsureProjectInput, type EventTypeData, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type ExtractMachinesResponse, type ExtractedMachine, type GetMachineOptions, type GraphPatch, INSPECTION_PROTOCOL_VERSION, type InitOptions, type InspectedEvent, type InspectedSnapshot, type InspectedTransition, type InspectionAction, type InspectionRelay, type InspectionRelayEffect, type InspectionRelayPeer, type InspectionRelayRole, type InspectionRelaySnapshot, type InspectionSentEvent, type InspectionTakenTransition, type Inspector, type InspectorEvents, type InspectorInspectionEvent, type MachineConfigOptions, type ManualActorOptions, type MultiplexedChannelOptions, type MultiplexedWebSocketConnection, type MultiplexedWebSocketConnectionOptions, type OAuthAuthorizationServerMetadata, type OAuthClientRegistrationResponse, type OAuthProtectedResourceMetadata, type OAuthTokenResponse, type PkcePair, type PlanSyncOptions, type ProjectData, type ProjectEmbedMachine, type ProjectMachine, type ProjectVisibility, type PullSyncResult, type PushLocalMachineLinksResult, type PushSyncOptions, type PushSyncProjectOptions, type PushSyncResult, RawCode, type RepoType, type ResolvedSyncInput, type S3UploadTarget, type StateNodeJSONData, type StatelyAction, type StatelyApiClientOptions, StatelyApiError, type StatelyApiUrlOptions, type StatelyAuthMode, type StatelyCredential, type StatelyEdgeData, type StatelyEmbed, type StatelyEmbedOptions, type StatelyGraph, type StatelyGraphData, type StatelyGuard, type StatelyInvoke, type StatelyNodeData, type StatelyPragma, type StatelyPragmaAttachment, type StudioAction, StudioApiError, type StudioClient, type StudioClientOptions, type StudioEdge, type StudioMachine, type StudioMachineRecord, type StudioNode, type SupabaseStorageClient, type SyncInputFormat, type SyncPlan, type SyncPlanSummary, type Transport, type UpdateMachineInput, type UploadResult, type UpsertStatelyPragmaOptions, type VerifyApiKeyResponse, type XStateTSOptions, type XStateVersion, buildAuthorizeUrl, contextSchemaToTSType, createAuthorizationHeader, createInspectionRelay, createInspector, createMultiplexedWebSocketConnection, createPkcePair, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, discoverAuthorizationServer, discoverProtectedResource, eventsSchemaToTSType, exchangeCodeForToken, findStatelyPragmaAttachments, fromStudioMachine, getCredentialToken, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, refreshToken, registerOAuthClient, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };

package/dist/index.mjs

@@ -2,12 +2,12 @@ import { n as createPostMessageTransport, r as createWebSocketTransport, t as cr
 import { INSPECTION_PROTOCOL_VERSION } from "./protocol.mjs";
 import { createStatelyEmbed } from "./embed.mjs";
 import { createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
-import { n as createStatelyInspector, t as createInspector } from "./inspect-pcNCbL7j.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-BcKTFJI1.mjs";
 import { createAuthorizationHeader, getCredentialToken } from "./auth.mjs";
 import { StudioApiError, createStatelyClient } from "./studio.mjs";
 import { buildAuthorizeUrl, createPkcePair, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, refreshToken, registerOAuthClient } from "./oauth.mjs";
 import { StatelyApiError, createStatelyApiClient, createStatelyApiUrl } from "./api.mjs";
-import { a as eventsSchemaToTSType, c as jsonSchemaToTSType, f as findStatelyPragmaAttachments, l as raw, m as upsertStatelyPragma, n as RawCode, o as graphToMachineConfig, p as getStatelyPragma, r as contextSchemaToTSType, s as graphToXStateTS, u as serializeJS } from "./dist-CHGcvOdQ.mjs";
+import { a as eventsSchemaToTSType, c as jsonSchemaToTSType, f as findStatelyPragmaAttachments, l as raw, m as upsertStatelyPragma, n as RawCode, o as graphToMachineConfig, p as getStatelyPragma, r as contextSchemaToTSType, s as graphToXStateTS, u as serializeJS } from "./dist-C8jVuuHf.mjs";
 import { fromStudioMachine, studioMachineConverter, toStudioMachine } from "./graph.mjs";
 import { createInspectionRelay } from "./relay.mjs";
 

package/dist/{inspect-pcNCbL7j.mjs → inspect-BcKTFJI1.mjs}

@@ -33,6 +33,10 @@ const defaultSerializeSnapshot = (snapshot) => ({
 	status: snapshot?.status
 });
 const defaultExtractMachineConfig = (actor, source) => actor?.logic?.config ?? source?.config ?? null;
+function isStoppedSnapshot(snapshot) {
+	const status = snapshot?.status;
+	return status === "done" || status === "stopped" || status === "error";
+}
 function generateSessionId() {
 	if (!globalThis.crypto?.randomUUID) throw new Error("createInspector() requires crypto.randomUUID() to generate a secure session capability. Pass sessionId explicitly in older runtimes.");
 	return globalThis.crypto.randomUUID();
@@ -143,6 +147,13 @@ function createInspector(options = {}) {
 			return null;
 		}
 	}
+	function stoppedValue(actorRef, snapshot) {
+		try {
+			return isStoppedSnapshot(snapshot ?? actorRef.getSnapshot());
+		} catch {
+			return false;
+		}
+	}
 	function toEntry(actorRef, rootActorId, details) {
 		return {
 			actorId: actorRef.sessionId,
@@ -151,6 +162,7 @@ function createInspector(options = {}) {
 			id: details?.id ?? actorRef.id ?? actorRef.sessionId,
 			systemId: actorRef.systemId,
 			snapshot: details?.snapshot ? serializeSnapshot(details.snapshot) : snapshotValue(actorRef),
+			stopped: stoppedValue(actorRef, details?.snapshot),
 			machineConfig: extractMachineConfig(actorRef, details?.source ?? actorRef.src)
 		};
 	}
@@ -160,7 +172,8 @@ function createInspector(options = {}) {
 			parentActorId: entry.parentActorId,
 			id: entry.id,
 			machine: entry.machineConfig,
-			snapshot: entry.snapshot ?? void 0
+			snapshot: entry.snapshot ?? void 0,
+			...entry.stopped && { stopped: true }
 		};
 	}
 	/**
@@ -170,13 +183,17 @@ function createInspector(options = {}) {
 	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);
+		if (existing) {
+			const snapshot = actorRef.getSnapshot();
+			existing.snapshot = serializeSnapshot(snapshot);
+			existing.stopped ||= isStoppedSnapshot(snapshot);
+		} 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();
+	const observedRootIds = /* @__PURE__ */ new Set();
 	function sendInit() {
 		for (const [rootActorId, { actor }] of inspectedRoots) backfillActorTree(actor, rootActorId);
 		send({
@@ -184,7 +201,7 @@ function createInspector(options = {}) {
 			protocolVersion: INSPECTION_PROTOCOL_VERSION,
 			mode: "inspecting",
 			actors: Array.from(actors.values()).map(toSystemEntry),
-			selectedActorId: selectedActorId ?? inspectedRoots.keys().next().value ?? sessionId,
+			selectedActorId: selectedActorId ?? observedRootIds.values().next().value ?? sessionId,
 			...theme && { theme },
 			...readOnly !== void 0 && { readOnly },
 			...depth !== void 0 && { depth },
@@ -246,6 +263,20 @@ function createInspector(options = {}) {
 			sent: []
 		};
 	}
+	function handleEvent(actorId, event, sourceActorId) {
+		const inspectedEvent = {
+			actorId,
+			sourceActorId,
+			event
+		};
+		if (initSent) send({
+			type: "@statelyai.system.actorEvent",
+			actorId,
+			event,
+			sourceActorId
+		});
+		emitLocal("event", inspectedEvent);
+	}
 	function getPendingTransition(actorRef, event) {
 		const existing = pendingTransitions.get(actorRef.sessionId);
 		if (existing) return existing;
@@ -258,7 +289,7 @@ function createInspector(options = {}) {
 		const entry = actors.get(actorRef.sessionId);
 		if (!entry) return;
 		const serialized = serializeSnapshot(snapshot);
-		const inspectedTransition = {
+		const inspectedSnapshot = {
 			actorId: entry.actorId,
 			sourceActorId: transition.sourceActorId,
 			previousSnapshot: transition.previousSnapshot,
@@ -268,24 +299,25 @@ function createInspector(options = {}) {
 			transitions: transition.transitions,
 			sent: transition.sent
 		};
+		const wasStopped = entry.stopped;
 		entry.snapshot = serialized;
+		const stopped = isStoppedSnapshot(snapshot);
+		entry.stopped ||= stopped;
 		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
+			previousSnapshot: inspectedSnapshot.previousSnapshot,
+			snapshot: inspectedSnapshot.snapshot,
+			event: inspectedSnapshot.event,
+			sourceActorId: inspectedSnapshot.sourceActorId,
+			actions: inspectedSnapshot.actions,
+			transitions: inspectedSnapshot.transitions,
+			sent: inspectedSnapshot.sent
 		});
-		emitLocal("transition", inspectedTransition);
-		emitLocal("snapshot", entry);
-		const status = snapshot?.status;
-		if (status === "done" || status === "stopped" || status === "error") {
-			actors.delete(entry.actorId);
+		emitLocal("snapshot", inspectedSnapshot);
+		emitLocal("transition", inspectedSnapshot);
+		if (stopped && !wasStopped) {
 			pendingTransitions.delete(entry.actorId);
 			if (initSent) send({
 				type: "@statelyai.system.actorStopped",
@@ -296,50 +328,59 @@ function createInspector(options = {}) {
 			emitLocal("stopped", stopped);
 		}
 	}
-	function inspectActor(actor) {
+	function handleInspectionEvent(inspectionEvent) {
+		if (destroyed) return;
+		const event = inspectionEvent;
+		const rootActorId = event.rootId;
+		const isNewRoot = !observedRootIds.has(rootActorId);
+		observedRootIds.add(rootActorId);
+		switch (event.type) {
+			case "@xstate.actor":
+				handleActor(event.actorRef, rootActorId, {
+					parentRef: event.parentRef,
+					id: event.id,
+					source: event.src,
+					snapshot: event.snapshot
+				});
+				break;
+			case "@xstate.event":
+				if (!actors.has(event.actorRef.sessionId)) handleActor(event.actorRef, rootActorId);
+				handleEvent(event.actorRef.sessionId, event.event, event.sourceRef?.sessionId ?? null);
+				pendingTransitions.set(event.actorRef.sessionId, createPendingTransition(event.actorRef, event.event, event.sourceRef));
+				break;
+			case "@xstate.action":
+				getPendingTransition(event.actorRef).actions.push(normalizeAction(event.action));
+				break;
+			case "@xstate.microstep":
+				getPendingTransition(event.actorRef, event.event).transitions.push(...(event._transitions ?? []).map(normalizeTakenTransition));
+				break;
+			case "@xstate.snapshot": {
+				const pending = getPendingTransition(event.actorRef, event.event);
+				handleTransition(event.actorRef, event.snapshot, event.event, rootActorId, pending);
+				break;
+			}
+			case "@xstate.transition":
+				if (!event.actions || !event.microsteps || !event.sent) break;
+				handleTransition(event.actorRef, event.snapshot, event.event, rootActorId, {
+					previousSnapshot: actors.get(event.actorRef.sessionId)?.snapshot ?? null,
+					event: event.event,
+					sourceActorId: event.sourceRef?.sessionId ?? null,
+					actions: event.actions.map(normalizeAction),
+					transitions: event.microsteps.map(normalizeTakenTransition),
+					sent: event.sent.map(normalizeSentEvent)
+				});
+				break;
+			default: break;
+		}
+		if (isNewRoot && initSent) sendInit();
+	}
+	function attachActor(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;
-			}
-		});
+		observedRootIds.add(rootActorId);
+		const subscription = root.system.inspect(handleInspectionEvent);
 		inspectedRoots.set(rootActorId, {
 			actor: root,
 			subscription
@@ -360,6 +401,7 @@ function createInspector(options = {}) {
 			id,
 			systemId: opts?.systemId,
 			snapshot: opts?.snapshot ?? null,
+			stopped: false,
 			machineConfig: opts?.machine ?? null
 		};
 		actors.set(id, entry);
@@ -373,13 +415,13 @@ function createInspector(options = {}) {
 		});
 		emitRegisterOnce(entry);
 	}
-	function manualSnapshot(actorId, snapshot, event, sourceActorId) {
+	function manualSnapshot(actorId, snapshot, event) {
 		if (!actors.has(actorId)) manualRegister(actorId);
 		const entry = actors.get(actorId);
 		const previousSnapshot = entry.snapshot;
-		const transition = {
+		const inspectedSnapshot = {
 			actorId,
-			sourceActorId: sourceActorId ?? null,
+			sourceActorId: null,
 			previousSnapshot,
 			snapshot,
 			event: event ?? null,
@@ -394,21 +436,23 @@ function createInspector(options = {}) {
 			previousSnapshot,
 			snapshot,
 			event: event ?? null,
-			sourceActorId: sourceActorId ?? null,
+			sourceActorId: null,
 			actions: [],
 			transitions: [],
 			sent: []
 		});
-		emitLocal("transition", transition);
-		emitLocal("snapshot", entry);
+		emitLocal("snapshot", inspectedSnapshot);
+		emitLocal("transition", inspectedSnapshot);
 	}
 	function manualEvent(actorId, event, eventOpts) {
 		const eventObj = typeof event === "string" ? { type: event } : { ...event };
-		manualSnapshot(actorId, actors.get(actorId)?.snapshot ?? null, eventObj, eventOpts?.source ?? null);
+		if (!actors.has(actorId)) manualRegister(actorId);
+		handleEvent(actorId, eventObj, eventOpts?.source ?? null);
 	}
 	function manualStop(actorId) {
-		if (!actors.has(actorId)) return;
-		actors.delete(actorId);
+		const entry = actors.get(actorId);
+		if (!entry || entry.stopped) return;
+		entry.stopped = true;
 		if (initSent) send({
 			type: "@statelyai.system.actorStopped",
 			actorId
@@ -427,7 +471,8 @@ function createInspector(options = {}) {
 		get sessionId() {
 			return sessionId;
 		},
-		inspect: inspectActor,
+		inspect: handleInspectionEvent,
+		attach: attachActor,
 		on(event, handler) {
 			if (!localListeners[event]) localListeners[event] = /* @__PURE__ */ new Set();
 			localListeners[event].add(handler);
@@ -456,6 +501,7 @@ function createInspector(options = {}) {
 			events.clear();
 			actors.clear();
 			inspectedRoots.clear();
+			observedRootIds.clear();
 			pendingTransitions.clear();
 			pendingMessages.length = 0;
 			for (const set of Object.values(localListeners)) set?.clear();

package/dist/{inspect-COqtklcn.d.mts → inspect-DQ_7I7eH.d.mts}

@@ -75,7 +75,7 @@ interface MinimalActorRef {
   src?: unknown;
   getSnapshot(): MinimalSnapshot;
   system: {
-    inspect: (observer: (event: InspectionEvent) => void) => {
+    inspect: (observer: (event: InspectorInspectionEvent) => void) => {
       unsubscribe: () => void;
     };
   };
@@ -86,63 +86,12 @@ interface MinimalSnapshot {
   context?: unknown;
   children?: Record<string, MinimalActorRef>;
 }
-type InspectionEvent = {
-  type: '@xstate.actor';
-  actorRef: MinimalActorRef;
-  rootId: string;
-  parentRef?: MinimalActorRef;
-  id?: string;
-  src?: unknown;
-  snapshot?: MinimalSnapshot;
-} | {
-  type: '@xstate.snapshot';
-  actorRef: MinimalActorRef;
-  rootId: string;
-  snapshot: MinimalSnapshot;
-  event: unknown;
-} | {
-  type: '@xstate.event';
-  actorRef: MinimalActorRef;
-  rootId: string;
-  sourceRef?: MinimalActorRef;
-  event: unknown;
-} | {
-  type: '@xstate.transition';
-  actorRef: MinimalActorRef;
-  rootId: string;
-  snapshot: MinimalSnapshot;
-  event: unknown;
-  sourceRef?: MinimalActorRef;
-  targetRef?: MinimalActorRef;
-  eventType?: string;
-  microsteps?: unknown[];
-  actions?: Array<{
-    type: string;
-    params: unknown;
-  }>;
-  sent?: Array<{
-    targetRef?: MinimalActorRef;
-    targetId: string;
-    event: unknown;
-    delay?: number;
-    id?: string;
-  }>;
-} | {
-  type: '@xstate.microstep';
-  actorRef: MinimalActorRef;
-  rootId: string;
-  snapshot: MinimalSnapshot;
-  event: unknown;
-  _transitions?: unknown[];
-} | {
-  type: '@xstate.action';
-  actorRef: MinimalActorRef;
-  rootId: string;
-  action: {
-    type: string;
-    params: unknown;
-  };
-};
+/** Cross-version event envelope accepted by {@link Inspector.inspect}. */
+interface InspectorInspectionEvent {
+  readonly type: string;
+  readonly rootId: string;
+  readonly actorRef: unknown;
+}
 interface AdoptedActor {
   /** `actor.sessionId` from xstate. Unique across the system. */
   actorId: string;
@@ -156,30 +105,43 @@ interface AdoptedActor {
   systemId: string | undefined;
   /** Latest serialized snapshot streamed for this actor. */
   snapshot: unknown | null;
+  /** Whether the actor has stopped. Stopped actors remain inspectable. */
+  stopped: boolean;
   /** Machine config sent to the visualizer, or `null` for non-machine actors. */
   machineConfig: unknown;
 }
-/** One normalized transition, independent of the XState inspection version. */
-interface InspectedTransition {
+/** One observed snapshot, independent of the XState inspection version. */
+interface InspectedSnapshot {
   actorId: string;
   sourceActorId: string | null;
+  /** Previously observed snapshot, which may not be the immediate predecessor. */
   previousSnapshot: unknown | null;
   snapshot: unknown;
+  /** Event known to have caused this snapshot, if observed. */
   event: unknown | null;
   actions: InspectionAction[];
   transitions: InspectionTakenTransition[];
   sent: InspectionSentEvent[];
 }
+/** @deprecated Use {@link InspectedSnapshot}. */
+type InspectedTransition = InspectedSnapshot;
+/** One observed event, independent of whether processing produced a snapshot. */
+interface InspectedEvent {
+  actorId: string;
+  sourceActorId: string | null;
+  event: unknown;
+}
 interface InspectorEvents {
   actor: AdoptedActor;
-  transition: InspectedTransition;
+  event: InspectedEvent;
+  snapshot: InspectedSnapshot;
   stop: {
     actorId: string;
   };
   /** @deprecated Use `actor`. */
   register: AdoptedActor;
-  /** @deprecated Use `transition`. */
-  snapshot: AdoptedActor;
+  /** @deprecated Use `snapshot`. */
+  transition: InspectedSnapshot;
   /** @deprecated Use `stop`. */
   stopped: {
     actorId: string;
@@ -246,8 +208,13 @@ 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): {
+  /**
+   * XState `inspect` option callback. Pass directly to `createActor` or another
+   * host that creates actors internally.
+   */
+  readonly inspect: (event: InspectorInspectionEvent) => void;
+  /** Attach an existing xstate actor system and backfill its current actors. */
+  attach(actor: any): {
     unsubscribe(): void;
   };
   /** Subscribe to lifecycle / error events. Returns an unsubscribe function. */
@@ -261,13 +228,13 @@ interface Inspector {
    */
   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.
+   * Push a snapshot update for an actor, optionally with the event known to
+   * have caused it. The actor is auto-registered if needed.
    */
   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.
+   * Log an event targeting an actor immediately, independently of any later
+   * snapshot. The actor is auto-registered if needed.
    */
   event(actorId: string, event: string | {
     type: string;
@@ -275,7 +242,7 @@ interface Inspector {
   }, options?: {
     source?: string;
   }): void;
-  /** Mark an actor as stopped and remove it from the tree. */
+  /** Mark an actor as stopped while retaining it in the tree. */
   stop(actorId: string): void;
   /** Tear down the WebSocket + xstate subscription. */
   destroy(): void;
@@ -284,4 +251,4 @@ declare function createInspector(options?: CreateInspectorOptions): Inspector;
 /** @deprecated Use {@link createInspector}. */
 declare const createStatelyInspector: typeof createInspector;
 //#endregion
-export { InspectorEvents as a, createStatelyInspector as c, MultiplexedWebSocketConnectionOptions as d, Transport as f, createWebSocketTransport as h, Inspector as i, MultiplexedChannelOptions as l, createPostMessageTransport as m, CreateInspectorOptions as n, ManualActorOptions as o, createMultiplexedWebSocketConnection as p, InspectedTransition as r, createInspector as s, AdoptedActor as t, MultiplexedWebSocketConnection as u };
+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 };

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 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-COqtklcn.mjs";
-export { AdoptedActor, CreateInspectorOptions, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InspectedTransition, InspectionAction, InspectionSentEvent, InspectionTakenTransition, Inspector, InspectorEvents, ManualActorOptions, Transport, createInspector, createStatelyInspector };
+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-DQ_7I7eH.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-pcNCbL7j.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-BcKTFJI1.mjs";
 
 export { createInspector, createStatelyInspector };