@statelyai/sdk 0.16.2 → 0.18.0

package/README.md

@@ -37,6 +37,10 @@ embed.init({
   format: 'xstate',
   mode: 'editing',
   theme: 'dark',
+  documents: [
+    { path: 'README.md', content: '# How this workflow works' },
+    { path: 'src/machine.ts', content: machineSource },
+  ],
 });
 ```
 
@@ -76,6 +80,7 @@ Key capabilities:
 - **Two-way sync** - push machine configs in, get changes and saves back via event callbacks
 - **Export** to multiple formats: XState v5, XState JSON, Mermaid, Redux, Zustand, ASL, SCXML, and more
 - **Access policies** for read-only, no-export, no-AI, shallow-viewer embeds
+- **Reference documents** supplied as ordered, read-only Markdown, code, or text
 - **Comments** via Liveblocks integration (optional)
 - **Asset uploads** with built-in S3 and Supabase adapters, or bring your own upload handler
 - **Runtime settings** - toggle color mode, grid, snap lines, autolayout, and view mode on the fly
@@ -170,12 +175,24 @@ actor.start();
 If you already have the actor reference, `inspector.attach(actor)` subscribes to
 its system and backfills actors that are already running.
 
+When authored source is available, return it from `extractMachine` so the
+visualizer preserves executable guards, inputs, and outputs instead of only a
+JSON-safe machine structure:
+
+```ts
+const inspector = createInspector({
+  extractMachine: (actor) =>
+    actor.logic === machine ? machineSource : actor.logic?.config,
+});
+```
+
 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.
-`actorId` is system-local; `sessionId` is globally unique.
+`actorId` is system-local and `sessionId` is process-local. A room uses
+`producerId + sessionId` as the global actor identity.
 Observations captured before the first transport registration replay in order
 after the initial actor-tree baseline. Reconnects use the latest checkpoint.
 In Node, the inspector opens in the default browser automatically. The SDK

package/dist/embed.d.mts

@@ -1,5 +1,5 @@
 import { i as StatelyGraph } from "./graph-DuOeLGvh.mjs";
-import { CapabilityDeniedEvent, CommentsConfig, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InitOptions, MachineInitOptions, MachineSourceLocations, ProjectEmbedMachine, UploadResult } from "./protocol.mjs";
+import { CapabilityDeniedEvent, CommentsConfig, EditorCapabilities, EmbedDocument, EmbedDocumentLanguage, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InitOptions, MachineInitOptions, MachineSourceLocations, ProjectEmbedMachine, UploadResult } from "./protocol.mjs";
 import { AssetUploadAdapter } from "./assetStorage.mjs";
 
 //#region src/embed.d.ts
@@ -91,4 +91,4 @@ interface StatelyEmbed {
 }
 declare function createStatelyEmbed(options: StatelyEmbedOptions): StatelyEmbed;
 //#endregion
-export { AssetConfig, type CapabilityDeniedEvent, type CommentsConfig, type EditorCapabilities, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type InitOptions, type MachineInitOptions, type MachineSourceLocations, type ProjectEmbedMachine, StatelyEmbed, StatelyEmbedOptions, type UploadResult, createStatelyEmbed };
+export { AssetConfig, type CapabilityDeniedEvent, type CommentsConfig, type EditorCapabilities, type EmbedDocument, type EmbedDocumentLanguage, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type InitOptions, type MachineInitOptions, type MachineSourceLocations, type ProjectEmbedMachine, StatelyEmbed, StatelyEmbedOptions, type UploadResult, createStatelyEmbed };

package/dist/embed.mjs

@@ -1,4 +1,4 @@
-import { a as toInitMessage, i as createPendingExportManager, r as createEventRegistry, t as createPostMessageTransport } from "./transport-B_ig9Znn.mjs";
+import { a as toInitMessage, i as createPendingExportManager, r as createEventRegistry, t as createPostMessageTransport } from "./transport-CyCrdKyz.mjs";
 
 //#region src/embed.ts
 function buildEmbedUrl(options) {
@@ -10,6 +10,7 @@ function buildEmbedUrl(options) {
 function extractInitOptions(options) {
 	if (options.machines) return {
 		machines: options.machines,
+		documents: options.documents,
 		currentMachineId: options.currentMachineId,
 		mode: options.mode,
 		theme: options.theme,
@@ -22,6 +23,7 @@ function extractInitOptions(options) {
 	};
 	if (options.machine !== void 0) return {
 		machine: options.machine,
+		documents: options.documents,
 		format: options.format,
 		mode: options.mode,
 		theme: options.theme,

package/dist/index.d.mts

@@ -1,11 +1,11 @@
 import { StatelyApiClientOptions, StatelyApiError, StatelyApiUrlOptions, createStatelyApiClient, createStatelyApiUrl } from "./api.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-ag6K2iAS.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-DuOeLGvh.mjs";
-import { CapabilityDeniedCapability, CapabilityDeniedEvent, CommentsConfig, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, InitOptions, InspectionAction, InspectionSentEvent, InspectionTakenTransition, ProjectEmbedMachine, UploadResult, createInspectionRoomUrls, getInspectionRoomId } from "./protocol.mjs";
+import { CapabilityDeniedCapability, CapabilityDeniedEvent, CommentsConfig, EMBED_DOCUMENT_LANGUAGES, EMBED_DOCUMENT_LIMITS, EditorCapabilities, EmbedDocument, EmbedDocumentLanguage, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, InitOptions, InspectionAction, InspectionSentEvent, InspectionTakenTransition, ProjectEmbedMachine, UploadResult, createInspectionActorId, createInspectionRoomUrls, getInspectionRoomId } from "./protocol.mjs";
 import { AssetUploadAdapter, AssetUploadContext, AssetUploadRequest, CreateS3AssetUploadAdapterOptions, CreateSupabaseAssetUploadAdapterOptions, S3UploadTarget, SupabaseStorageClient, createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
 import { i as getCredentialToken, n as StatelyCredential, r as createAuthorizationHeader, t as StatelyAuthMode } from "./auth-2Thaw42j.mjs";
 import { AssetConfig, StatelyEmbed, StatelyEmbedOptions, createStatelyEmbed } from "./embed.mjs";
-import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f as Transport, h as createWebSocketTransport, i as InspectedSnapshot, l as ManualActorOptions, m as createPostMessageTransport, n as CreateInspectorOptions, o as Inspector, p as TransportFailure, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector } from "./inspect-BScvqVcM.mjs";
+import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f as Transport, h as createWebSocketTransport, i as InspectedSnapshot, l as ManualActorOptions, m as createPostMessageTransport, n as CreateInspectorOptions, o as Inspector, p as TransportFailure, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector } from "./inspect-BZFzyeew.mjs";
 import { A as Machine, C as StudioMachineRecord, D as VerifyApiKeyResponse, E as UpdateProjectInput, F as ProjectVisibility, I as VerifyResult, L as XStateVersion, M as Project, N as ProjectMachineSummary, O as createStatelyClient, P as ProjectSummary, R as ResourceErrorCode, S as StudioClientOptions, T as UpdateMachineInput, _ as ProjectMachine, a as CreateMachineTemplate, b as StudioApiErrorOptions, c as EnsureProjectInput, d as ExtractedMachine, f as GetMachineOptions, g as ProjectData, h as LegacyUpdateMachineInput, i as CreateMachineInput, j as MachineVersion, k as ExtractedMachines, l as ExtractMachinesInput, m as LegacyProjectVisibility, n as CreateMachineFromDefinitionInput, o as CreateProjectInput, r as CreateMachineFromTemplateInput, s as DEFAULT_STATELY_BASE_URL, t as ConnectedRepo, u as ExtractMachinesResponse, v as RepoType, w as StudioRequestOptions, x as StudioClient, y as StudioApiError } from "./studio-Bk_u41gu.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, DEFAULT_STATELY_BASE_URL, 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 ExtractMachinesInput, type ExtractMachinesResponse, type ExtractedMachine, type ExtractedMachines, type GetMachineOptions, type GraphPatch, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, 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 LegacyProjectVisibility, type LegacyUpdateMachineInput, type Machine, type MachineConfigOptions, type MachineVersion, type ManualActorOptions, type OAuthAuthorizationServerMetadata, type OAuthClientRegistrationResponse, type OAuthProtectedResourceMetadata, type OAuthTokenResponse, type PkcePair, type PlanSyncOptions, type Project, type ProjectData, type ProjectEmbedMachine, type ProjectMachine, type ProjectMachineSummary, type ProjectSummary, type ProjectVisibility, type PullSyncResult, type PushLocalMachineLinksResult, type PushSyncOptions, type PushSyncProjectOptions, type PushSyncResult, RawCode, type RepoType, type ResolvedSyncInput, type ResourceErrorCode, 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 StudioApiErrorOptions, type StudioClient, type StudioClientOptions, type StudioEdge, type StudioMachine, type StudioMachineRecord, type StudioNode, type StudioRequestOptions, type SupabaseStorageClient, type SyncInputFormat, type SyncPlan, type SyncPlanSummary, type Transport, type TransportFailure, type UpdateMachineInput, type UpdateProjectInput, type UploadResult, type UpsertStatelyPragmaOptions, type VerifyApiKeyResponse, type VerifyResult, type XStateTSOptions, type XStateVersion, buildAuthorizeUrl, contextSchemaToTSType, createAuthorizationHeader, createInspectionRelay, createInspectionRoomUrls, createInspector, createPkcePair, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, discoverAuthorizationServer, discoverProtectedResource, eventsSchemaToTSType, exchangeCodeForToken, findStatelyPragmaAttachments, fromStudioMachine, getCredentialToken, getInspectionRoomId, 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, DEFAULT_STATELY_BASE_URL, type DigraphAction, type DigraphConfig, type DigraphEdgeConfig, type DigraphNodeConfig, EMBED_DOCUMENT_LANGUAGES, EMBED_DOCUMENT_LIMITS, type EditorCapabilities, type EmbedDocument, type EmbedDocumentLanguage, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type EnsureProjectInput, type EventTypeData, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type ExtractMachinesInput, type ExtractMachinesResponse, type ExtractedMachine, type ExtractedMachines, type GetMachineOptions, type GraphPatch, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, 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 LegacyProjectVisibility, type LegacyUpdateMachineInput, type Machine, type MachineConfigOptions, type MachineVersion, type ManualActorOptions, type OAuthAuthorizationServerMetadata, type OAuthClientRegistrationResponse, type OAuthProtectedResourceMetadata, type OAuthTokenResponse, type PkcePair, type PlanSyncOptions, type Project, type ProjectData, type ProjectEmbedMachine, type ProjectMachine, type ProjectMachineSummary, type ProjectSummary, type ProjectVisibility, type PullSyncResult, type PushLocalMachineLinksResult, type PushSyncOptions, type PushSyncProjectOptions, type PushSyncResult, RawCode, type RepoType, type ResolvedSyncInput, type ResourceErrorCode, 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 StudioApiErrorOptions, type StudioClient, type StudioClientOptions, type StudioEdge, type StudioMachine, type StudioMachineRecord, type StudioNode, type StudioRequestOptions, type SupabaseStorageClient, type SyncInputFormat, type SyncPlan, type SyncPlanSummary, type Transport, type TransportFailure, type UpdateMachineInput, type UpdateProjectInput, type UploadResult, type UpsertStatelyPragmaOptions, type VerifyApiKeyResponse, type VerifyResult, type XStateTSOptions, type XStateVersion, buildAuthorizeUrl, contextSchemaToTSType, createAuthorizationHeader, createInspectionActorId, createInspectionRelay, createInspectionRoomUrls, createInspector, createPkcePair, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, discoverAuthorizationServer, discoverProtectedResource, eventsSchemaToTSType, exchangeCodeForToken, findStatelyPragmaAttachments, fromStudioMachine, getCredentialToken, getInspectionRoomId, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, refreshToken, registerOAuthClient, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };

package/dist/index.mjs

@@ -1,8 +1,8 @@
-import { n as createWebSocketTransport, t as createPostMessageTransport } from "./transport-B_ig9Znn.mjs";
-import { INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, createInspectionRoomUrls, getInspectionRoomId } from "./protocol.mjs";
+import { EMBED_DOCUMENT_LANGUAGES, EMBED_DOCUMENT_LIMITS, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, createInspectionActorId, createInspectionRoomUrls, getInspectionRoomId } from "./protocol.mjs";
+import { n as createWebSocketTransport, t as createPostMessageTransport } from "./transport-CyCrdKyz.mjs";
 import { createStatelyEmbed } from "./embed.mjs";
 import { createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
-import { n as createStatelyInspector, t as createInspector } from "./inspect-DxOsKzlq.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-llcqYpZ1.mjs";
 import { n as StudioApiError, r as createStatelyClient, t as DEFAULT_STATELY_BASE_URL } from "./studio-txdyJHD7.mjs";
 import { a as RawCode, c as eventsSchemaToTSType, d as jsonSchemaToTSType, f as raw, l as graphToMachineConfig, n as getStatelyPragma, o as contextSchemaToTSType, p as serializeJS, r as upsertStatelyPragma, t as findStatelyPragmaAttachments, u as graphToXStateTS } from "./statelyPragma-Bm9O4XV6.mjs";
 import { createAuthorizationHeader, getCredentialToken } from "./auth.mjs";
@@ -11,4 +11,4 @@ import { StatelyApiError, createStatelyApiClient, createStatelyApiUrl } from "./
 import { fromStudioMachine, studioMachineConverter, toStudioMachine } from "./graph.mjs";
 import { createInspectionRelay } from "./relay.mjs";
 
-export { DEFAULT_STATELY_BASE_URL, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, RawCode, StatelyApiError, StudioApiError, buildAuthorizeUrl, contextSchemaToTSType, createAuthorizationHeader, createInspectionRelay, createInspectionRoomUrls, createInspector, createPkcePair, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, discoverAuthorizationServer, discoverProtectedResource, eventsSchemaToTSType, exchangeCodeForToken, findStatelyPragmaAttachments, fromStudioMachine, getCredentialToken, getInspectionRoomId, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, refreshToken, registerOAuthClient, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };
+export { DEFAULT_STATELY_BASE_URL, EMBED_DOCUMENT_LANGUAGES, EMBED_DOCUMENT_LIMITS, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, RawCode, StatelyApiError, StudioApiError, buildAuthorizeUrl, contextSchemaToTSType, createAuthorizationHeader, createInspectionActorId, createInspectionRelay, createInspectionRoomUrls, createInspector, createPkcePair, createPostMessageTransport, createS3AssetUploadAdapter, createStatelyApiClient, createStatelyApiUrl, createStatelyClient, createStatelyEmbed, createStatelyInspector, createSupabaseAssetUploadAdapter, createWebSocketTransport, discoverAuthorizationServer, discoverProtectedResource, eventsSchemaToTSType, exchangeCodeForToken, findStatelyPragmaAttachments, fromStudioMachine, getCredentialToken, getInspectionRoomId, getStatelyPragma, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, refreshToken, registerOAuthClient, serializeJS, studioMachineConverter, toStudioMachine, upsertStatelyPragma };

package/dist/{inspect-BScvqVcM.d.mts → inspect-BZFzyeew.d.mts}

@@ -62,7 +62,7 @@ interface InspectorInspectionEvent {
   readonly actorRef: unknown;
 }
 interface AdoptedActor {
-  /** Globally unique `actor.sessionId` from xstate. */
+  /** XState process-local `actor.sessionId`. Pair with inspector.producerId. */
   sessionId: string;
   /** System-local `actor.id`. */
   actorId: string;
@@ -76,7 +76,7 @@ interface AdoptedActor {
   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. */
+  /** Machine source or config sent to the visualizer, or `null` for non-machine actors. */
   machineConfig: unknown;
 }
 /** One observed snapshot, independent of the XState inspection version. */
@@ -161,8 +161,15 @@ interface CreateInspectorOptions {
    */
   serializeSnapshot?: (snapshot: MinimalSnapshot) => unknown;
   /**
-   * Extract the machine config for a given actor. Defaults to reading
-   * `actor.logic.config`. Return `null` for non-machine actors.
+   * Extract the machine sent to the visualizer for a given actor. Return an
+   * XState source string to preserve executable expressions, a machine config
+   * object for structural inspection, or `null` for non-machine actors.
+   * Defaults to reading `actor.logic.config`.
+   */
+  extractMachine?: (actor: any, source?: unknown) => unknown;
+  /**
+   * Extract the machine config for a given actor.
+   * @deprecated Use {@link extractMachine}; it also accepts source strings.
    */
   extractMachineConfig?: (actor: any, source?: unknown) => unknown;
   /** Selected actor session id to focus on first. */
@@ -186,7 +193,7 @@ interface CreateInspectorOptions {
   transport?: Transport;
 }
 interface Inspector {
-  /** Snapshot of currently-adopted actors keyed by global `sessionId`. */
+  /** Snapshot of this producer's actors keyed by XState `sessionId`. */
   readonly actors: ReadonlyMap<string, AdoptedActor>;
   /** Unguessable inspection room capability. */
   readonly roomId: string;

package/dist/{inspect-DxOsKzlq.mjs → inspect-llcqYpZ1.mjs}

@@ -1,5 +1,5 @@
-import { i as createPendingExportManager, n as createWebSocketTransport, r as createEventRegistry } from "./transport-B_ig9Znn.mjs";
 import { INSPECTION_PROTOCOL_VERSION, createInspectionRoomUrls, getInspectionRoomId } from "./protocol.mjs";
+import { i as createPendingExportManager, n as createWebSocketTransport, r as createEventRegistry } from "./transport-CyCrdKyz.mjs";
 
 //#region src/openBrowser.ts
 async function openBrowser(url) {
@@ -28,7 +28,7 @@ async function openBrowser(url) {
 
 //#endregion
 //#region src/version.ts
-const SDK_VERSION = "0.16.2";
+const SDK_VERSION = "0.18.0";
 function inspectionRuntime() {
 	if (typeof window !== "undefined") return "browser";
 	if (typeof process !== "undefined" && process.versions?.node) return "node";
@@ -53,7 +53,8 @@ function generateRoomId() {
 function createInspector(options = {}) {
 	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 { inspectorBaseUrl, autoOpen = true, name, serializeSnapshot = defaultSerializeSnapshot, selectedSessionId: configuredSelectedSessionId, selectedActorId, panels, theme, readOnly, depth, capabilities, transport: injectedTransport } = options;
+	const extractMachine = options.extractMachine ?? options.extractMachineConfig ?? defaultExtractMachineConfig;
 	const roomId = options.roomId ?? options.sessionId ?? getInspectionRoomId(url) ?? generateRoomId();
 	const producerId = options.producerId ?? generateRoomId();
 	const roomUrls = injectedTransport ? null : createInspectionRoomUrls({
@@ -101,6 +102,7 @@ function createInspector(options = {}) {
 		transport.send(msg);
 	}
 	function handleTransportReady() {
+		if (destroyed) return;
 		if (!transportWasReady) {
 			transportWasReady = true;
 			if (!initSent) sendInit();
@@ -125,14 +127,15 @@ function createInspector(options = {}) {
 			});
 		}
 	}
-	transport.onReady(() => {
+	const stopTransportReady = transport.onReady(() => {
 		if (!initialized) {
 			pendingTransportReady = true;
 			return;
 		}
 		handleTransportReady();
 	});
-	transport.onError?.((failure) => {
+	const stopTransportError = transport.onError?.((failure) => {
+		if (destroyed) return;
 		const error = new Error(failure.message);
 		if (!readySettled) {
 			readySettled = true;
@@ -141,7 +144,7 @@ function createInspector(options = {}) {
 		emitLocal("error", failure);
 		events.emit("error", failure);
 	});
-	transport.onMessage((msg) => {
+	const stopTransportMessages = transport.onMessage((msg) => {
 		if (destroyed) return;
 		switch (msg.type) {
 			case "@statelyai.retrieved":
@@ -205,7 +208,7 @@ function createInspector(options = {}) {
 			systemId: actorRef.systemId,
 			snapshot: details?.snapshot ? serializeSnapshot(details.snapshot) : snapshotValue(actorRef),
 			stopped: stoppedValue(actorRef, details?.snapshot),
-			machineConfig: extractMachineConfig(actorRef, details?.source ?? actorRef.src)
+			machineConfig: extractMachine(actorRef, details?.source ?? actorRef.src)
 		};
 	}
 	function toSystemEntry(entry) {
@@ -555,6 +558,9 @@ function createInspector(options = {}) {
 			try {
 				for (const { subscription } of inspectedRoots.values()) subscription.unsubscribe();
 			} catch {}
+			stopTransportReady();
+			stopTransportError?.();
+			stopTransportMessages();
 			if (ownsTransport) transport.destroy();
 			exportManager.clear("Inspector destroyed");
 			events.clear();

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, 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-BScvqVcM.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-BZFzyeew.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,4 @@
-import { n as createStatelyInspector, t as createInspector } from "./inspect-DxOsKzlq.mjs";
+import "./transport-CyCrdKyz.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-llcqYpZ1.mjs";
 
 export { createInspector, createStatelyInspector };

package/dist/protocol.d.mts

@@ -3,6 +3,12 @@ import { i as StatelyGraph } from "./graph-DuOeLGvh.mjs";
 //#region src/protocol.d.ts
 /** Query parameter carrying the unguessable inspection room capability. */
 declare const INSPECTION_ROOM_QUERY_PARAM = "r";
+/**
+ * Create the room-global identity for one producer-local actor session.
+ * XState session ids are process-local; the producer id supplies the missing
+ * cross-process namespace.
+ */
+declare function createInspectionActorId(producerId: string, sessionId: string): string;
 interface InspectionRoomUrls {
   roomId: string;
   relayUrl: string;
@@ -29,6 +35,21 @@ interface ProjectEmbedMachine {
   name?: string;
   machine: unknown;
 }
+declare const EMBED_DOCUMENT_LANGUAGES: readonly ["markdown", "typescript", "javascript", "json", "xml", "mermaid", "text"];
+type EmbedDocumentLanguage = (typeof EMBED_DOCUMENT_LANGUAGES)[number];
+declare const EMBED_DOCUMENT_LIMITS: {
+  readonly maxDocuments: 100;
+  readonly maxDocumentLength: number;
+  readonly maxTotalLength: number;
+};
+/** Read-only text supplied by an embed host for display beside a machine. */
+interface EmbedDocument {
+  /** Relative POSIX path used as the document's stable identity. */
+  path: string;
+  content: string;
+  /** Overrides renderer detection from the path's file extension. */
+  language?: EmbedDocumentLanguage;
+}
 interface ValidationIssue {
   nodeIds: string[];
   edgeIds: string[];
@@ -192,6 +213,8 @@ type EmbedEventName = keyof EmbedEventMap;
 type EmbedEventHandler<K extends EmbedEventName> = (data: EmbedEventMap[K]) => void;
 interface MachineInitOptions {
   machine: unknown;
+  /** Ephemeral, read-only reference documents owned by the embed host. */
+  documents?: EmbedDocument[];
   format?: string;
   mode?: EmbedMode;
   theme?: 'light' | 'dark';
@@ -226,6 +249,8 @@ interface MachineInitOptions {
 }
 interface ProjectInitOptions {
   machines: ProjectEmbedMachine[];
+  /** Ephemeral, read-only reference documents shared across the project. */
+  documents?: EmbedDocument[];
   currentMachineId?: string;
   mode?: EmbedMode;
   theme?: 'light' | 'dark';
@@ -248,6 +273,7 @@ type InitOptions = MachineInitOptions | ProjectInitOptions;
 interface InitMessage {
   type: '@statelyai.init';
   machine: unknown;
+  documents?: EmbedDocument[];
   format?: string;
   mode?: EmbedMode;
   theme?: 'light' | 'dark';
@@ -274,6 +300,7 @@ interface SetApiKeyMessage {
 interface ProjectInitMessage {
   type: '@statelyai.project.init';
   machines: ProjectEmbedMachine[];
+  documents?: EmbedDocument[];
   currentMachineId?: string;
   mode?: EmbedMode;
   theme?: 'light' | 'dark';
@@ -334,11 +361,11 @@ interface InspectSnapshotMessage {
   type: '@statelyai.inspectSnapshot';
   snapshot: unknown;
   event: unknown | null;
-  /** Global actor session id, when this snapshot belongs to an actor. */
+  /** Producer-local actor session id, when this snapshot belongs to an actor. */
   sessionId?: string;
 }
 interface ActorSystemEntry {
-  /** Globally unique xstate `actor.sessionId`. */
+  /** XState process-local `actor.sessionId`; pair with relay `producerId`. */
   sessionId: string;
   /** System-local xstate `actor.id`. */
   actorId: string;
@@ -378,6 +405,7 @@ interface SystemInitMessage {
   actors: ActorSystemEntry[];
   /** Actor session id the viz should focus first. Defaults to the root. */
   selectedSessionId?: string;
+  documents?: EmbedDocument[];
   mode?: EmbedMode;
   theme?: 'light' | 'dark';
   readOnly?: boolean;
@@ -549,4 +577,4 @@ declare const PREFIX = "@statelyai.";
 /** Current WebSocket inspection protocol version. */
 declare const INSPECTION_PROTOCOL_VERSION = 2;
 //#endregion
-export { ActorSystemEntry, CapabilityDeniedCapability, CapabilityDeniedEvent, CapabilityDeniedMessage, ChangeMessage, ClientMessage, CommentsConfig, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ErrorMessage, ExportCallOptions, ExportFormat, ExportFormatMap, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, InitMessage, InitOptions, InspectSnapshotMessage, InspectionAction, InspectionClientMetadata, InspectionRoomUrls, InspectionSentEvent, InspectionTakenTransition, LoadedMessage, MachineInitOptions, MachineSourceLocations, PREFIX, ProjectEmbedMachine, ProjectInitMessage, ProjectInitOptions, ProjectMachineSelectedMessage, ProjectSelectMachineMessage, ProjectUpdateMessage, ProtocolMessage, ReadOnlyReason, ReadyMessage, RegisterMessage, RegisteredMessage, RetrieveMessage, RetrievedMessage, SaveMessage, SessionMessage, SetApiKeyMessage, SetModeMessage, SetSettingsMessage, SetThemeMessage, SourceLocation, SourceRange, StateSourceLocation, SystemActorEventMessage, SystemActorRegisteredMessage, SystemActorSnapshotMessage, SystemActorStoppedMessage, SystemInitMessage, SystemSelectActorMessage, ToastMessage, UpdateMessage, UploadCapabilitiesMessage, UploadFileInfo, UploadRequestMessage, UploadResponseMessage, UploadResult, ValidationIssue, VizMessage, createInspectionRoomUrls, getInspectionRoomId };
+export { ActorSystemEntry, CapabilityDeniedCapability, CapabilityDeniedEvent, CapabilityDeniedMessage, ChangeMessage, ClientMessage, CommentsConfig, EMBED_DOCUMENT_LANGUAGES, EMBED_DOCUMENT_LIMITS, EditorCapabilities, EmbedDocument, EmbedDocumentLanguage, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ErrorMessage, ExportCallOptions, ExportFormat, ExportFormatMap, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, InitMessage, InitOptions, InspectSnapshotMessage, InspectionAction, InspectionClientMetadata, InspectionRoomUrls, InspectionSentEvent, InspectionTakenTransition, LoadedMessage, MachineInitOptions, MachineSourceLocations, PREFIX, ProjectEmbedMachine, ProjectInitMessage, ProjectInitOptions, ProjectMachineSelectedMessage, ProjectSelectMachineMessage, ProjectUpdateMessage, ProtocolMessage, ReadOnlyReason, ReadyMessage, RegisterMessage, RegisteredMessage, RetrieveMessage, RetrievedMessage, SaveMessage, SessionMessage, SetApiKeyMessage, SetModeMessage, SetSettingsMessage, SetThemeMessage, SourceLocation, SourceRange, StateSourceLocation, SystemActorEventMessage, SystemActorRegisteredMessage, SystemActorSnapshotMessage, SystemActorStoppedMessage, SystemInitMessage, SystemSelectActorMessage, ToastMessage, UpdateMessage, UploadCapabilitiesMessage, UploadFileInfo, UploadRequestMessage, UploadResponseMessage, UploadResult, ValidationIssue, VizMessage, createInspectionActorId, createInspectionRoomUrls, getInspectionRoomId };

package/dist/protocol.mjs

@@ -1,6 +1,14 @@
 //#region src/protocol.ts
 /** Query parameter carrying the unguessable inspection room capability. */
 const INSPECTION_ROOM_QUERY_PARAM = "r";
+/**
+* Create the room-global identity for one producer-local actor session.
+* XState session ids are process-local; the producer id supplies the missing
+* cross-process namespace.
+*/
+function createInspectionActorId(producerId, sessionId) {
+	return `${encodeURIComponent(producerId)}:${encodeURIComponent(sessionId)}`;
+}
 /** Resolve the transport and browser URLs required by the inspection protocol. */
 function createInspectionRoomUrls(options) {
 	const relayUrl = new URL(options.url);
@@ -30,9 +38,23 @@ function createInspectionRoomUrls(options) {
 function getInspectionRoomId(value) {
 	return new URL(value).searchParams.get(INSPECTION_ROOM_QUERY_PARAM)?.trim() || null;
 }
+const EMBED_DOCUMENT_LANGUAGES = [
+	"markdown",
+	"typescript",
+	"javascript",
+	"json",
+	"xml",
+	"mermaid",
+	"text"
+];
+const EMBED_DOCUMENT_LIMITS = {
+	maxDocuments: 100,
+	maxDocumentLength: 512 * 1024,
+	maxTotalLength: 2 * 1024 * 1024
+};
 const PREFIX = "@statelyai.";
 /** Current WebSocket inspection protocol version. */
 const INSPECTION_PROTOCOL_VERSION = 2;
 
 //#endregion
-export { INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, PREFIX, createInspectionRoomUrls, getInspectionRoomId };
+export { EMBED_DOCUMENT_LANGUAGES, EMBED_DOCUMENT_LIMITS, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, PREFIX, createInspectionActorId, createInspectionRoomUrls, getInspectionRoomId };

package/dist/{transport-B_ig9Znn.mjs → transport-CyCrdKyz.mjs}

@@ -1,6 +1,27 @@
-import { INSPECTION_PROTOCOL_VERSION, PREFIX } from "./protocol.mjs";
+import { EMBED_DOCUMENT_LANGUAGES, EMBED_DOCUMENT_LIMITS, INSPECTION_PROTOCOL_VERSION, PREFIX } from "./protocol.mjs";
 
 //#region src/clientUtils.ts
+const embedDocumentLanguages = new Set(EMBED_DOCUMENT_LANGUAGES);
+function assertEmbedDocuments(documents) {
+	if (!documents) return;
+	if (documents.length > EMBED_DOCUMENT_LIMITS.maxDocuments) throw new TypeError(`Embed documents are limited to ${EMBED_DOCUMENT_LIMITS.maxDocuments}.`);
+	const seen = /* @__PURE__ */ new Set();
+	let totalLength = 0;
+	for (const document of documents) {
+		const path = document?.path;
+		const content = document?.content;
+		const language = document?.language;
+		const segments = typeof path === "string" ? path.split("/") : [];
+		if (typeof path !== "string" || path.length === 0 || path.startsWith("/") || path.includes("\\") || segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) throw new TypeError("Embed document paths must be non-empty relative POSIX paths.");
+		if (seen.has(path)) throw new TypeError(`Duplicate embed document path: ${path}`);
+		if (typeof content !== "string") throw new TypeError(`Embed document content must be text: ${path}`);
+		if (language !== void 0 && (typeof language !== "string" || !embedDocumentLanguages.has(language))) throw new TypeError(`Unsupported embed document language: ${language}`);
+		if (content.length > EMBED_DOCUMENT_LIMITS.maxDocumentLength) throw new TypeError(`Embed document exceeds the 512 KiB character limit: ${path}`);
+		seen.add(path);
+		totalLength += content.length;
+	}
+	if (totalLength > EMBED_DOCUMENT_LIMITS.maxTotalLength) throw new TypeError("Embed documents exceed the 2 MiB character limit.");
+}
 const jsonResultFormats = new Set([
 	"digraph",
 	"xstate-json",
@@ -91,9 +112,11 @@ function createPendingExportManager(sendRetrieve) {
 	};
 }
 function toInitMessage(options) {
+	assertEmbedDocuments(options.documents);
 	if ("machines" in options) return {
 		type: "@statelyai.project.init",
 		machines: options.machines,
+		documents: options.documents,
 		currentMachineId: options.currentMachineId,
 		mode: options.mode,
 		theme: options.theme,
@@ -109,6 +132,7 @@ function toInitMessage(options) {
 	return {
 		type: "@statelyai.init",
 		machine: options.machine,
+		documents: options.documents,
 		format: options.format,
 		mode: options.mode,
 		theme: options.theme,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/sdk",
-  "version": "0.16.2",
+  "version": "0.18.0",
   "license": "MIT",
   "bin": {
     "stately-sdk": "./dist/bin.mjs"