@statelyai/sdk 0.14.2 → 0.16.0

package/dist/{inspect-DWDTNMEc.mjs → inspect-BwVdM4R8.mjs}

@@ -1,5 +1,5 @@
-import { a as createPendingExportManager, i as createEventRegistry, r as createWebSocketTransport } from "./transport-D2Ud05yg.mjs";
-import { INSPECTION_PROTOCOL_VERSION } from "./protocol.mjs";
+import { i as createPendingExportManager, n as createWebSocketTransport, r as createEventRegistry } from "./transport-B_ig9Znn.mjs";
+import { INSPECTION_PROTOCOL_VERSION, createInspectionRoomUrls, getInspectionRoomId } from "./protocol.mjs";
 
 //#region src/openBrowser.ts
 async function openBrowser(url) {
@@ -37,25 +37,23 @@ 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.");
+function generateRoomId() {
+	if (!globalThis.crypto?.randomUUID) throw new Error("createInspector() requires crypto.randomUUID() to generate a secure room capability. Pass roomId explicitly in older runtimes.");
 	return globalThis.crypto.randomUUID();
 }
-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 environmentUrl = typeof process !== "undefined" ? process.env?.STATELY_INSPECT_URL : void 0;
+	const url = options.url ?? environmentUrl ?? "wss://sky.stately.ai";
+	const { inspectorBaseUrl, autoOpen = true, name, serializeSnapshot = defaultSerializeSnapshot, extractMachineConfig = defaultExtractMachineConfig, selectedSessionId: configuredSelectedSessionId, selectedActorId, panels, theme, readOnly, depth, capabilities, transport: injectedTransport } = options;
+	const roomId = options.roomId ?? options.sessionId ?? getInspectionRoomId(url) ?? generateRoomId();
+	const producerId = options.producerId ?? generateRoomId();
+	const roomUrls = injectedTransport ? null : createInspectionRoomUrls({
+		url,
+		roomId,
+		inspectorBaseUrl
+	});
+	const relayUrl = roomUrls?.relayUrl ?? null;
+	const inspectorUrl = roomUrls?.inspectorUrl ?? null;
 	const displayName = name ?? "system:manual";
 	let destroyed = false;
 	let initSent = false;
@@ -63,13 +61,21 @@ function createInspector(options = {}) {
 	let pendingTransportReady = false;
 	let transportWasReady = false;
 	let didAutoOpen = false;
+	let resolveReady;
+	let rejectReady;
+	let readySettled = false;
+	const ready = new Promise((resolve, reject) => {
+		resolveReady = resolve;
+		rejectReady = reject;
+	});
+	ready.catch(() => {});
 	const pendingMessages = [];
 	const events = createEventRegistry();
 	const localListeners = {};
 	const transport = injectedTransport ?? createWebSocketTransport({
-		url,
-		role: "client",
-		sessionId,
+		url: relayUrl,
+		role: "producer",
+		producerId,
 		metadata: { name: displayName }
 	});
 	const ownsTransport = !injectedTransport;
@@ -87,6 +93,8 @@ function createInspector(options = {}) {
 			if (!initSent) sendInit();
 			const queued = pendingMessages.splice(0);
 			for (const message of queued) transport.send(message);
+			readySettled = true;
+			resolveReady();
 		} else {
 			pendingMessages.length = 0;
 			initSent = false;
@@ -94,8 +102,7 @@ function createInspector(options = {}) {
 		}
 		if (autoOpen && !didAutoOpen && ownsTransport) {
 			didAutoOpen = true;
-			const launchUrl = createInspectorLaunchUrl(url, sessionId);
-			if (launchUrl) openBrowser(launchUrl).catch((error) => {
+			if (inspectorUrl) openBrowser(inspectorUrl).catch((error) => {
 				const failure = {
 					code: "open_failed",
 					message: error instanceof Error ? error.message : "Unable to open the inspector browser"
@@ -112,6 +119,15 @@ function createInspector(options = {}) {
 		}
 		handleTransportReady();
 	});
+	transport.onError?.((failure) => {
+		const error = new Error(failure.message);
+		if (!readySettled) {
+			readySettled = true;
+			rejectReady(error);
+		}
+		emitLocal("error", failure);
+		events.emit("error", failure);
+	});
 	transport.onMessage((msg) => {
 		if (destroyed) return;
 		switch (msg.type) {
@@ -120,6 +136,10 @@ function createInspector(options = {}) {
 				break;
 			case "@statelyai.error":
 				exportManager.reject(new Error(msg.message), msg.requestId);
+				if (!readySettled) {
+					readySettled = true;
+					rejectReady(new Error(msg.message));
+				}
 				emitLocal("error", {
 					code: msg.code,
 					message: msg.message
@@ -138,13 +158,14 @@ function createInspector(options = {}) {
 		for (const handler of set) handler(data);
 	}
 	const actors = /* @__PURE__ */ new Map();
+	const manualSessionIds = /* @__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);
+		if (locallyRegistered.has(entry.sessionId)) return;
+		locallyRegistered.add(entry.sessionId);
 		emitLocal("actor", entry);
 		emitLocal("register", entry);
 	}
@@ -164,10 +185,10 @@ function createInspector(options = {}) {
 	}
 	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,
+			sessionId: actorRef.sessionId,
+			actorId: details?.id ?? actorRef.id ?? actorRef.sessionId,
+			parentSessionId: details?.parentRef?.sessionId ?? actorRef._parent?.sessionId ?? null,
+			rootSessionId: rootActorId,
 			systemId: actorRef.systemId,
 			snapshot: details?.snapshot ? serializeSnapshot(details.snapshot) : snapshotValue(actorRef),
 			stopped: stoppedValue(actorRef, details?.snapshot),
@@ -176,9 +197,9 @@ function createInspector(options = {}) {
 	}
 	function toSystemEntry(entry) {
 		return {
+			sessionId: entry.sessionId,
 			actorId: entry.actorId,
-			parentActorId: entry.parentActorId,
-			id: entry.id,
+			parentSessionId: entry.parentSessionId,
 			machine: entry.machineConfig,
 			snapshot: entry.snapshot ?? void 0,
 			...entry.stopped && { stopped: true }
@@ -195,7 +216,7 @@ function createInspector(options = {}) {
 			const snapshot = actorRef.getSnapshot();
 			existing.snapshot = serializeSnapshot(snapshot);
 			existing.stopped ||= isStoppedSnapshot(snapshot);
-		} else actors.set(entry.actorId, entry);
+		} else actors.set(entry.sessionId, entry);
 		emitRegisterOnce(entry);
 		const children = actorRef.getSnapshot()?.children ?? {};
 		for (const child of Object.values(children)) if (child) backfillActorTree(child, rootActorId);
@@ -204,12 +225,14 @@ function createInspector(options = {}) {
 	const observedRootIds = /* @__PURE__ */ new Set();
 	function sendInit() {
 		for (const [rootActorId, { actor }] of inspectedRoots) backfillActorTree(actor, rootActorId);
+		const allEntries = Array.from(actors.values());
+		const selectedSessionId = configuredSelectedSessionId ?? selectedActorId ?? observedRootIds.values().next().value ?? allEntries[0]?.sessionId;
 		send({
 			type: "@statelyai.system.init",
 			protocolVersion: INSPECTION_PROTOCOL_VERSION,
 			mode: "inspecting",
-			actors: Array.from(actors.values()).map(toSystemEntry),
-			selectedActorId: selectedActorId ?? observedRootIds.values().next().value ?? sessionId,
+			actors: allEntries.map(toSystemEntry),
+			...selectedSessionId && { selectedSessionId },
 			...theme && { theme },
 			...readOnly !== void 0 && { readOnly },
 			...depth !== void 0 && { depth },
@@ -223,13 +246,13 @@ function createInspector(options = {}) {
 	function handleActor(actorRef, rootActorId, details) {
 		if (actors.has(actorRef.sessionId)) return;
 		const entry = toEntry(actorRef, rootActorId, details);
-		actors.set(entry.actorId, entry);
+		actors.set(entry.sessionId, entry);
 		emitRegisterOnce(entry);
 		if (initSent) send({
 			type: "@statelyai.system.actorRegistered",
+			sessionId: entry.sessionId,
 			actorId: entry.actorId,
-			parentActorId: entry.parentActorId,
-			id: entry.id,
+			parentSessionId: entry.parentSessionId,
 			machine: entry.machineConfig,
 			snapshot: entry.snapshot ?? void 0
 		});
@@ -254,7 +277,7 @@ function createInspector(options = {}) {
 	}
 	function normalizeSentEvent(sentEvent) {
 		return {
-			...sentEvent.targetRef?.sessionId && { targetActorId: sentEvent.targetRef.sessionId },
+			...sentEvent.targetRef?.sessionId && { targetSessionId: sentEvent.targetRef.sessionId },
 			targetId: sentEvent.targetId,
 			event: sentEvent.event,
 			...sentEvent.delay !== void 0 && { delay: sentEvent.delay },
@@ -265,23 +288,23 @@ function createInspector(options = {}) {
 		return {
 			previousSnapshot: actors.get(actorRef.sessionId)?.snapshot ?? null,
 			event,
-			sourceActorId: sourceRef?.sessionId ?? null,
+			sourceSessionId: sourceRef?.sessionId ?? null,
 			actions: [],
 			transitions: [],
 			sent: []
 		};
 	}
-	function handleEvent(actorId, event, sourceActorId) {
+	function handleEvent(sessionId, event, sourceSessionId) {
 		const inspectedEvent = {
-			actorId,
-			sourceActorId,
+			sessionId,
+			sourceSessionId,
 			event
 		};
 		if (initSent) send({
 			type: "@statelyai.system.actorEvent",
-			actorId,
+			sessionId,
 			event,
-			sourceActorId
+			sourceSessionId
 		});
 		emitLocal("event", inspectedEvent);
 	}
@@ -298,8 +321,8 @@ function createInspector(options = {}) {
 		if (!entry) return;
 		const serialized = serializeSnapshot(snapshot);
 		const inspectedSnapshot = {
-			actorId: entry.actorId,
-			sourceActorId: transition.sourceActorId,
+			sessionId: entry.sessionId,
+			sourceSessionId: transition.sourceSessionId,
 			previousSnapshot: transition.previousSnapshot,
 			snapshot: serialized,
 			event: triggeringEvent ?? transition.event ?? null,
@@ -311,14 +334,14 @@ function createInspector(options = {}) {
 		entry.snapshot = serialized;
 		const stopped = isStoppedSnapshot(snapshot);
 		entry.stopped ||= stopped;
-		pendingTransitions.delete(entry.actorId);
+		pendingTransitions.delete(entry.sessionId);
 		if (initSent) send({
 			type: "@statelyai.system.actorSnapshot",
-			actorId: entry.actorId,
+			sessionId: entry.sessionId,
 			previousSnapshot: inspectedSnapshot.previousSnapshot,
 			snapshot: inspectedSnapshot.snapshot,
 			event: inspectedSnapshot.event,
-			sourceActorId: inspectedSnapshot.sourceActorId,
+			sourceSessionId: inspectedSnapshot.sourceSessionId,
 			actions: inspectedSnapshot.actions,
 			transitions: inspectedSnapshot.transitions,
 			sent: inspectedSnapshot.sent
@@ -326,12 +349,12 @@ function createInspector(options = {}) {
 		emitLocal("snapshot", inspectedSnapshot);
 		emitLocal("transition", inspectedSnapshot);
 		if (stopped && !wasStopped) {
-			pendingTransitions.delete(entry.actorId);
+			pendingTransitions.delete(entry.sessionId);
 			if (initSent) send({
 				type: "@statelyai.system.actorStopped",
-				actorId: entry.actorId
+				sessionId: entry.sessionId
 			});
-			const stopped = { actorId: entry.actorId };
+			const stopped = { sessionId: entry.sessionId };
 			emitLocal("stop", stopped);
 			emitLocal("stopped", stopped);
 		}
@@ -372,7 +395,7 @@ function createInspector(options = {}) {
 				handleTransition(event.actorRef, event.snapshot, event.event, rootActorId, {
 					previousSnapshot: actors.get(event.actorRef.sessionId)?.snapshot ?? null,
 					event: event.event,
-					sourceActorId: event.sourceRef?.sessionId ?? null,
+					sourceSessionId: event.sourceRef?.sessionId ?? null,
 					actions: event.actions.map(normalizeAction),
 					transitions: event.microsteps.map(normalizeTakenTransition),
 					sent: event.sent.map(normalizeSentEvent)
@@ -400,37 +423,44 @@ function createInspector(options = {}) {
 			inspectedRoots.delete(rootActorId);
 		} };
 	}
+	function getManualSessionId(actorId) {
+		return manualSessionIds.get(actorId) ?? `${producerId}:${actorId}`;
+	}
 	function manualRegister(id, opts) {
-		if (actors.has(id)) return;
+		const sessionId = getManualSessionId(id);
+		if (actors.has(sessionId)) return;
+		manualSessionIds.set(id, sessionId);
+		const parentSessionId = opts?.parent ? getManualSessionId(opts.parent) : null;
 		const entry = {
+			sessionId,
 			actorId: id,
-			parentActorId: opts?.parent ?? null,
-			rootId: sessionId,
-			id,
+			parentSessionId,
+			rootSessionId: (parentSessionId && actors.get(parentSessionId)?.rootSessionId) ?? sessionId,
 			systemId: opts?.systemId,
 			snapshot: opts?.snapshot ?? null,
 			stopped: false,
 			machineConfig: opts?.machine ?? null
 		};
-		actors.set(id, entry);
+		actors.set(sessionId, entry);
 		if (!initSent) sendInit();
 		else send({
 			type: "@statelyai.system.actorRegistered",
+			sessionId,
 			actorId: id,
-			parentActorId: entry.parentActorId,
-			id,
+			parentSessionId: entry.parentSessionId,
 			machine: entry.machineConfig,
 			snapshot: entry.snapshot ?? void 0
 		});
 		emitRegisterOnce(entry);
 	}
 	function manualSnapshot(actorId, snapshot, event) {
-		if (!actors.has(actorId)) manualRegister(actorId);
-		const entry = actors.get(actorId);
+		const sessionId = getManualSessionId(actorId);
+		if (!actors.has(sessionId)) manualRegister(actorId);
+		const entry = actors.get(sessionId);
 		const previousSnapshot = entry.snapshot;
 		const inspectedSnapshot = {
-			actorId,
-			sourceActorId: null,
+			sessionId,
+			sourceSessionId: null,
 			previousSnapshot,
 			snapshot,
 			event: event ?? null,
@@ -441,11 +471,11 @@ function createInspector(options = {}) {
 		entry.snapshot = snapshot;
 		if (initSent) send({
 			type: "@statelyai.system.actorSnapshot",
-			actorId,
+			sessionId,
 			previousSnapshot,
 			snapshot,
 			event: event ?? null,
-			sourceActorId: null,
+			sourceSessionId: null,
 			actions: [],
 			transitions: [],
 			sent: []
@@ -455,18 +485,20 @@ function createInspector(options = {}) {
 	}
 	function manualEvent(actorId, event, eventOpts) {
 		const eventObj = typeof event === "string" ? { type: event } : { ...event };
-		if (!actors.has(actorId)) manualRegister(actorId);
-		handleEvent(actorId, eventObj, eventOpts?.source ?? null);
+		const sessionId = getManualSessionId(actorId);
+		if (!actors.has(sessionId)) manualRegister(actorId);
+		handleEvent(sessionId, eventObj, eventOpts?.source ? getManualSessionId(eventOpts.source) : null);
 	}
 	function manualStop(actorId) {
-		const entry = actors.get(actorId);
+		const sessionId = getManualSessionId(actorId);
+		const entry = actors.get(sessionId);
 		if (!entry || entry.stopped) return;
 		entry.stopped = true;
 		if (initSent) send({
 			type: "@statelyai.system.actorStopped",
-			actorId
+			sessionId
 		});
-		const stopped = { actorId };
+		const stopped = { sessionId };
 		emitLocal("stop", stopped);
 		emitLocal("stopped", stopped);
 	}
@@ -477,9 +509,14 @@ function createInspector(options = {}) {
 	}
 	return {
 		actors,
+		roomId,
+		relayUrl,
+		producerId,
 		get sessionId() {
-			return sessionId;
+			return roomId;
 		},
+		inspectorUrl,
+		ready,
 		inspect: handleInspectionEvent,
 		attach: attachActor,
 		on(event, handler) {

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

@@ -1,12 +1,17 @@
 import { EditorCapabilities, EmbedEventMap, ExportCallOptions, ExportFormat, ExportFormatMap, InspectionAction, InspectionSentEvent, InspectionTakenTransition, ProtocolMessage } from "./protocol.mjs";
 
 //#region src/transport.d.ts
+interface TransportFailure {
+  code: string;
+  message: string;
+}
 interface Transport {
   send(msg: ProtocolMessage): void;
   onMessage(handler: (msg: ProtocolMessage) => void): () => void;
   destroy(): void;
   readonly ready: boolean;
   onReady(handler: () => void): () => void;
+  onError?(handler: (failure: TransportFailure) => void): () => void;
 }
 interface PostMessageTransportOptions {
   iframe: HTMLIFrameElement;
@@ -17,51 +22,18 @@ interface PostMessageTransportOptions {
 declare function createPostMessageTransport(options: PostMessageTransportOptions): Transport;
 interface WebSocketTransportOptions {
   url: string;
-  role: 'client' | 'viz';
-  sessionId: string;
+  role: 'producer' | 'viewer';
+  producerId?: string;
   metadata?: {
     name?: string;
     machineId?: string;
   };
   /** Reconnect on disconnect. Default true. */
   reconnect?: boolean;
-  /** Max reconnect attempts. Default 10. */
+  /** Max reconnect attempts after the first connection. Default 10. */
   maxReconnectAttempts?: number;
 }
 declare function createWebSocketTransport(options: WebSocketTransportOptions): Transport;
-interface MultiplexedWebSocketConnectionOptions {
-  url: string;
-  role: 'client' | 'viz';
-  /** First (primary) session to register on connect. */
-  sessionId: string;
-  /** Metadata for the primary session. */
-  metadata?: {
-    name?: string;
-    machineId?: string;
-  };
-  reconnect?: boolean;
-  maxReconnectAttempts?: number;
-}
-interface MultiplexedChannelOptions {
-  /** Session id this channel targets. */
-  sessionId: string;
-  /** Optional metadata for this session. */
-  metadata?: {
-    name?: string;
-    machineId?: string;
-  };
-}
-interface MultiplexedWebSocketConnection {
-  /** Open a channel for a sessionId. Re-opening an existing session returns the same channel. */
-  openChannel(options: MultiplexedChannelOptions): Transport;
-  /** Close the connection and all its channels. */
-  destroy(): void;
-  /** Whether the underlying WebSocket is connected + the primary session is registered. */
-  readonly ready: boolean;
-  /** Primary session id (first registered). */
-  readonly primarySessionId: string;
-}
-declare function createMultiplexedWebSocketConnection(options: MultiplexedWebSocketConnectionOptions): MultiplexedWebSocketConnection;
 //#endregion
 //#region src/inspect.d.ts
 interface MinimalActorRef {
@@ -93,14 +65,14 @@ interface InspectorInspectionEvent {
   readonly actorRef: unknown;
 }
 interface AdoptedActor {
-  /** `actor.sessionId` from xstate. Unique across the system. */
+  /** Globally unique `actor.sessionId` from xstate. */
+  sessionId: string;
+  /** System-local `actor.id`. */
   actorId: string;
   /** Parent actor's sessionId, or `null` for the root. */
-  parentActorId: string | null;
-  /** Root actor's sessionId (equal to `actorId` for the root). */
-  rootId: string;
-  /** `actor.id` — a human-facing local name. */
-  id: string;
+  parentSessionId: string | null;
+  /** Root actor's sessionId. */
+  rootSessionId: string;
   /** `actor.systemId`, if registered under one. */
   systemId: string | undefined;
   /** Latest serialized snapshot streamed for this actor. */
@@ -112,8 +84,8 @@ interface AdoptedActor {
 }
 /** One observed snapshot, independent of the XState inspection version. */
 interface InspectedSnapshot {
-  actorId: string;
-  sourceActorId: string | null;
+  sessionId: string;
+  sourceSessionId: string | null;
   /** Previously observed snapshot, which may not be the immediate predecessor. */
   previousSnapshot: unknown | null;
   snapshot: unknown;
@@ -127,8 +99,8 @@ interface InspectedSnapshot {
 type InspectedTransition = InspectedSnapshot;
 /** One observed event, independent of whether processing produced a snapshot. */
 interface InspectedEvent {
-  actorId: string;
-  sourceActorId: string | null;
+  sessionId: string;
+  sourceSessionId: string | null;
   event: unknown;
 }
 interface InspectorEvents {
@@ -136,7 +108,7 @@ interface InspectorEvents {
   event: InspectedEvent;
   snapshot: InspectedSnapshot;
   stop: {
-    actorId: string;
+    sessionId: string;
   };
   /** @deprecated Use `actor`. */
   register: AdoptedActor;
@@ -144,7 +116,7 @@ interface InspectorEvents {
   transition: InspectedSnapshot;
   /** @deprecated Use `stop`. */
   stopped: {
-    actorId: string;
+    sessionId: string;
   };
   error: EmbedEventMap['error'];
 }
@@ -161,15 +133,27 @@ interface ManualActorOptions {
   systemId?: string;
 }
 interface CreateInspectorOptions {
-  /** WebSocket URL of the devtools server. Default: `'ws://localhost:4242'`. */
+  /**
+   * WebSocket relay base URL. Defaults to `STATELY_INSPECT_URL`, then
+   * `wss://sky.stately.ai`. Passing this option always wins.
+   */
   url?: string;
+  /** Unguessable inspection room capability. Defaults to a random UUID. */
+  roomId?: string;
+  /** Stable identity for this producer connection. Defaults to a random UUID. */
+  producerId?: string;
+  /**
+   * Inspector UI base URL when hosted separately from the WebSocket relay. The
+   * inspector adds `ws` and `r` query parameters. When omitted, the URL
+   * is derived from the relay URL by replacing `ws` with `http`.
+   */
+  inspectorBaseUrl?: string;
   /** Auto-open browser to visualizer. Default: `true`. */
   autoOpen?: boolean;
   /**
-   * Relay session capability. Defaults to a cryptographically random UUID.
-   * This is the `?session=<id>` value the visualizer connects with. Custom
-   * values used with a hosted relay must be unguessable.
+   * Legacy name for the unguessable room capability.
    */
+  /** @deprecated Use {@link roomId}. */
   sessionId?: string;
   /** Display name for this system in the visualizer. */
   name?: string;
@@ -184,7 +168,9 @@ interface CreateInspectorOptions {
    * `actor.logic.config`. Return `null` for non-machine actors.
    */
   extractMachineConfig?: (actor: any, source?: unknown) => unknown;
-  /** Selected actor id to focus on first. Defaults to the first inspected root. */
+  /** Selected actor session id to focus on first. */
+  selectedSessionId?: string;
+  /** @deprecated Use {@link selectedSessionId}. */
   selectedActorId?: string;
   /** Panel layout forwarded into the system init message. */
   panels?: {
@@ -197,17 +183,26 @@ interface CreateInspectorOptions {
   depth?: number;
   capabilities?: EditorCapabilities;
   /**
-   * Advanced: inject a pre-built transport (e.g. a channel from a
-   * multiplexed connection). When provided, `url`/`name` are ignored and the
-   * inspector shares that transport instead of opening its own WebSocket.
+   * Advanced: inject a pre-built transport. When provided, `url`/`name` are
+   * ignored and no WebSocket or browser URL is created.
    */
   transport?: Transport;
 }
 interface Inspector {
-  /** Snapshot of currently-adopted actors keyed by `actorId`. */
+  /** Snapshot of currently-adopted actors keyed by global `sessionId`. */
   readonly actors: ReadonlyMap<string, AdoptedActor>;
-  /** The relay sessionId this inspector registered under. */
+  /** Unguessable inspection room capability. */
+  readonly roomId: string;
+  /** Complete WebSocket URL for this room. */
+  readonly relayUrl: string | null;
+  /** Identity stamped onto this producer's protocol messages. */
+  readonly producerId: string;
+  /** @deprecated Use {@link roomId}. */
   readonly sessionId: string;
+  /** URL that opens the inspector UI for this live session. */
+  readonly inspectorUrl: string | null;
+  /** Resolves after the first relay registration and initial-state flush. */
+  readonly ready: Promise<void>;
   /**
    * XState `inspect` option callback. Pass directly to `createActor` or another
    * host that creates actors internally.
@@ -251,4 +246,4 @@ declare function createInspector(options?: CreateInspectorOptions): Inspector;
 /** @deprecated Use {@link createInspector}. */
 declare const createStatelyInspector: typeof createInspector;
 //#endregion
-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 };
+export { InspectedTransition as a, InspectorInspectionEvent as c, createStatelyInspector as d, Transport as f, createWebSocketTransport as h, InspectedSnapshot as i, ManualActorOptions as l, createPostMessageTransport as m, CreateInspectorOptions as n, Inspector as o, TransportFailure as p, InspectedEvent as r, InspectorEvents as s, AdoptedActor as t, createInspector as u };

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 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";
+import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f 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-CduY_2Fa.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-DWDTNMEc.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-BwVdM4R8.mjs";
 
 export { createInspector, createStatelyInspector };

package/dist/node-relay.d.mts

@@ -0,0 +1,22 @@
+//#region src/node-relay.d.ts
+interface NodeInspectionRelayOptions {
+  host?: string;
+  port?: number;
+  logger?: Pick<Console, 'info'>;
+}
+/** Local/self-hosted Node adapter for the room inspection relay. */
+declare class NodeInspectionRelayServer {
+  private readonly options;
+  private server;
+  private webSocketServer;
+  private readonly rooms;
+  private readonly connections;
+  private readonly sockets;
+  constructor(options?: NodeInspectionRelayOptions);
+  get url(): string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+declare function createNodeInspectionRelay(options?: NodeInspectionRelayOptions): NodeInspectionRelayServer;
+//#endregion
+export { NodeInspectionRelayOptions, NodeInspectionRelayServer, createNodeInspectionRelay };