@statelyai/sdk 0.1.0 → 0.2.0

package/README.md

@@ -46,20 +46,20 @@ embed.init({
 
 Creates an embed instance.
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `baseUrl` | `string` | **Required.** Base URL of the Stately app |
-| `apiKey` | `string` | **Required.** Your Stately API key |
-| `origin` | `string` | Custom target origin for postMessage |
-| `onReady` | `() => void` | Called when embed is ready |
-| `onLoaded` | `(graph) => void` | Called when machine is loaded |
-| `onChange` | `(graph, machineConfig) => void` | Called on every change |
-| `onSave` | `(graph, machineConfig) => void` | Called on save |
-| `onError` | `({ code, message }) => void` | Called on error |
+| Option     | Type                             | Description                               |
+| ---------- | -------------------------------- | ----------------------------------------- |
+| `baseUrl`  | `string`                         | **Required.** Base URL of the Stately app |
+| `apiKey`   | `string`                         | **Required.** Your Stately API key        |
+| `origin`   | `string`                         | Custom target origin for postMessage      |
+| `onReady`  | `() => void`                     | Called when embed is ready                |
+| `onLoaded` | `(graph) => void`                | Called when machine is loaded             |
+| `onChange` | `(graph, machineConfig) => void` | Called on every change                    |
+| `onSave`   | `(graph, machineConfig) => void` | Called on save                            |
+| `onError`  | `({ code, message }) => void`    | Called on error                           |
 
 ### Embed methods
 
-#### `mount(container)` / `attach(iframe)`
+#### `embed.mount(container)` / `embed.attach(iframe)`
 
 Mount creates an iframe inside a container element. Attach connects to an existing iframe.
 
@@ -71,7 +71,7 @@ const iframe = embed.mount(document.getElementById('editor')!);
 embed.attach(document.querySelector('iframe')!);
 ```
 
-#### `init(options)`
+#### `embed.init(options)`
 
 Initialize the embed with a machine and display options.
 
@@ -79,8 +79,8 @@ Initialize the embed with a machine and display options.
 embed.init({
   machine: machineConfig,
   format: 'xstate', // optional
-  mode: 'editing',  // 'editing' | 'viewing' | 'simulating'
-  theme: 'dark',    // 'light' | 'dark'
+  mode: 'editing', // 'editing' | 'viewing' | 'simulating'
+  theme: 'dark', // 'light' | 'dark'
   readOnly: false,
   depth: 3,
   panels: {
@@ -91,15 +91,15 @@ embed.init({
 });
 ```
 
-#### `updateMachine(machine, format?)`
+#### `embed.updateMachine(machine, format?)`
 
 Update the displayed machine.
 
-#### `setMode(mode)` / `setTheme(theme)`
+#### `embed.setMode(mode)` / `embed.setTheme(theme)`
 
 Change the embed mode or theme at runtime.
 
-#### `export(format, options?)`
+#### `embed.export(format, options?)`
 
 Export the current machine. Returns a promise.
 
@@ -111,7 +111,7 @@ const mermaid = await embed.export('mermaid');
 
 Supported formats: `xstate`, `json`, `digraph`, `mermaid`, `scxml`
 
-#### `on(event, handler)` / `off(event, handler)`
+#### `embed.on(event, handler)` / `embed.off(event, handler)`
 
 Subscribe/unsubscribe to embed events: `ready`, `loaded`, `change`, `save`, `error`.
 
@@ -121,10 +121,10 @@ embed.on('change', ({ graph, machineConfig }) => {
 });
 ```
 
-#### `toast(message, type?)`
+#### `embed.toast(message, type?)`
 
 Show a toast notification in the embed. Type: `'success' | 'error' | 'info' | 'warning'`
 
-#### `destroy()`
+#### `embed.destroy()`
 
 Tear down the embed. Removes listeners, rejects pending promises, and removes the iframe if it was created via `mount()`.

package/dist/index.d.mts

@@ -1,77 +1,9 @@
+import { a as EmbedEventHandler, c as EmbedMode, d as ExportFormatMap, f as InitOptions, i as createInspector, l as ExportCallOptions, n as InspectOptions, o as EmbedEventMap, p as ProtocolMessage, r as Inspector, s as EmbedEventName, t as CreateInspectorOptions, u as ExportFormat } from "./inspect-Bt5Ohkrp.mjs";
+
 //#region src/embed.d.ts
-interface ExportFormatMap {
-  xstate: {
-    options: {
-      version?: 4 | 5;
-      addTSTypes?: boolean;
-      showIds?: boolean;
-      showDescriptions?: boolean;
-    };
-    result: string;
-  };
-  json: {
-    options: {
-      simplifyArrays?: boolean;
-      version?: 4 | 5;
-    };
-    result: Record<string, unknown>;
-  };
-  digraph: {
-    options: Record<string, never>;
-    result: Record<string, unknown>;
-  };
-  mermaid: {
-    options: Record<string, never>;
-    result: string;
-  };
-  scxml: {
-    options: Record<string, never>;
-    result: string;
-  };
-}
-type ExportFormat = keyof ExportFormatMap;
-type ExportCallOptions<F extends ExportFormat> = ExportFormatMap[F]['options'] & {
-  timeout?: number;
-};
-type EmbedMode = 'editing' | 'viewing' | 'simulating';
-interface InitOptions {
-  machine: unknown;
-  format?: string;
-  mode?: EmbedMode;
-  theme?: 'light' | 'dark';
-  readOnly?: boolean;
-  depth?: number;
-  panels?: {
-    leftPanels?: string[];
-    rightPanels?: string[];
-    activePanels?: string[];
-  };
-}
-interface EmbedEventMap {
-  ready: {
-    version: string;
-  };
-  loaded: {
-    graph: unknown;
-  };
-  change: {
-    graph: unknown;
-    machineConfig: unknown;
-  };
-  save: {
-    graph: unknown;
-    machineConfig: unknown;
-  };
-  error: {
-    code: string;
-    message: string;
-  };
-}
-type EmbedEventName = keyof EmbedEventMap;
-type EmbedEventHandler<K extends EmbedEventName> = (data: EmbedEventMap[K]) => void;
 interface StatelyEmbedOptions {
   baseUrl: string;
-  apiKey: string;
+  apiKey?: string;
   origin?: string;
   onReady?: () => void;
   onLoaded?: (graph: unknown) => void;
@@ -108,4 +40,34 @@ interface StatelyEmbed {
 }
 declare function createStatelyEmbed(options: StatelyEmbedOptions): StatelyEmbed;
 //#endregion
-export { type EmbedEventMap, type EmbedMode, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type InitOptions, type StatelyEmbed, type StatelyEmbedOptions, createStatelyEmbed };
+//#region src/transport.d.ts
+interface Transport {
+  send(msg: ProtocolMessage): void;
+  onMessage(handler: (msg: ProtocolMessage) => void): () => void;
+  destroy(): void;
+  readonly ready: boolean;
+  onReady(handler: () => void): () => void;
+}
+interface PostMessageTransportOptions {
+  iframe: HTMLIFrameElement;
+  targetOrigin: string;
+  /** Filter by source. Defaults to iframe.contentWindow. */
+  source?: Window;
+}
+declare function createPostMessageTransport(options: PostMessageTransportOptions): Transport;
+interface WebSocketTransportOptions {
+  url: string;
+  role: 'client' | 'viz';
+  sessionId: string;
+  metadata?: {
+    name?: string;
+    machineId?: string;
+  };
+  /** Reconnect on disconnect. Default true. */
+  reconnect?: boolean;
+  /** Max reconnect attempts. Default 10. */
+  maxReconnectAttempts?: number;
+}
+declare function createWebSocketTransport(options: WebSocketTransportOptions): Transport;
+//#endregion
+export { type CreateInspectorOptions, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedMode, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type InitOptions, type InspectOptions, type Inspector, type StatelyEmbed, type StatelyEmbedOptions, type Transport, createInspector, createPostMessageTransport, createStatelyEmbed, createWebSocketTransport };

package/dist/index.mjs

@@ -1,94 +1,96 @@
+import { a as createPendingExportManager, i as createEventRegistry, n as createPostMessageTransport, o as toInitMessage, r as createWebSocketTransport, t as createInspector } from "./inspect-C3Rjgn1o.mjs";
+
 //#region src/embed.ts
-const PREFIX = "@statelyai.";
 function createStatelyEmbed(options) {
-	const embedUrl = `${options.baseUrl.replace(/\/+$/, "") + "/embed"}?api_key=${encodeURIComponent(options.apiKey)}`;
+	const base = options.baseUrl.replace(/\/+$/, "") + "/embed";
+	const embedUrl = options.apiKey ? `${base}?api_key=${encodeURIComponent(options.apiKey)}` : base;
 	const targetOrigin = options.origin ?? new URL(embedUrl).origin;
 	let iframe = null;
+	let transport = null;
 	let ownedIframe = false;
-	let ready = false;
 	let destroyed = false;
 	const pendingMessages = [];
-	let pendingExport = null;
-	const jsonResultFormats = new Set(["digraph", "json"]);
-	const listeners = {};
-	function emit(event, data) {
-		const set = listeners[event];
-		if (set) set.forEach((fn) => fn(data));
-	}
+	const events = createEventRegistry();
+	const exportManager = createPendingExportManager((message) => send(message));
 	function send(msg) {
-		if (!ready) {
+		if (!transport?.ready) {
 			pendingMessages.push(msg);
 			return;
 		}
-		iframe?.contentWindow?.postMessage(msg, targetOrigin);
+		transport.send(msg);
 	}
 	function flush() {
+		if (!transport) return;
 		while (pendingMessages.length > 0) {
 			const msg = pendingMessages.shift();
-			iframe?.contentWindow?.postMessage(msg, targetOrigin);
+			transport.send(msg);
 		}
 	}
-	function handleMessage(e) {
+	function handleMessage(data) {
 		if (destroyed) return;
-		if (e.source !== iframe?.contentWindow) return;
-		const data = e.data;
-		if (!data?.type?.startsWith?.(PREFIX)) return;
 		switch (data.type) {
 			case "@statelyai.ready":
-				ready = true;
 				flush();
 				options.onReady?.();
-				emit("ready", { version: data.version });
+				events.emit("ready", { version: data.version });
 				break;
 			case "@statelyai.loaded":
 				options.onLoaded?.(data.graph);
-				emit("loaded", { graph: data.graph });
+				events.emit("loaded", { graph: data.graph });
 				break;
 			case "@statelyai.change":
 				options.onChange?.(data.graph, data.machineConfig);
-				emit("change", {
+				events.emit("change", {
 					graph: data.graph,
 					machineConfig: data.machineConfig
 				});
 				break;
 			case "@statelyai.save":
 				options.onSave?.(data.graph, data.machineConfig);
-				emit("save", {
+				events.emit("save", {
 					graph: data.graph,
 					machineConfig: data.machineConfig
 				});
 				break;
 			case "@statelyai.retrieved":
-				if (pendingExport) {
-					clearTimeout(pendingExport.timer);
-					let result = data.data;
-					if (jsonResultFormats.has(pendingExport.format) && typeof result === "string") result = JSON.parse(result);
-					pendingExport.resolve(result);
-					pendingExport = null;
-				}
+				if (typeof data.requestId === "string") exportManager.resolve(data.requestId, data.data);
 				break;
 			case "@statelyai.error": {
 				const err = {
 					code: data.code,
 					message: data.message
 				};
+				exportManager.reject(new Error(err.message), typeof data.requestId === "string" ? data.requestId : void 0);
 				options.onError?.(err);
-				emit("error", err);
+				events.emit("error", err);
 				break;
 			}
 		}
 	}
-	function startListening() {
-		window.addEventListener("message", handleMessage);
+	function replaceTransport(nextTransport) {
+		transport?.destroy();
+		transport = nextTransport;
+	}
+	function setupTransport(el) {
+		replaceTransport(createPostMessageTransport({
+			iframe: el,
+			targetOrigin
+		}));
+		transport.onMessage(handleMessage);
+		transport.onReady(flush);
 	}
 	return {
 		attach(el) {
 			if (destroyed) return;
+			const currentSrc = el.getAttribute("src");
+			if (currentSrc && currentSrc !== "about:blank" && el.src !== embedUrl) console.warn("Replacing existing iframe src during attach()", {
+				currentSrc,
+				nextSrc: embedUrl
+			});
 			iframe = el;
 			ownedIframe = false;
-			ready = false;
 			el.src = embedUrl;
-			startListening();
+			setupTransport(el);
 		},
 		mount(container) {
 			if (destroyed) throw new Error("Embed is destroyed");
@@ -102,23 +104,11 @@ function createStatelyEmbed(options) {
 			container.appendChild(el);
 			iframe = el;
 			ownedIframe = true;
-			ready = false;
-			startListening();
+			setupTransport(el);
 			return el;
 		},
 		init(opts) {
-			send({
-				type: "@statelyai.init",
-				machine: opts.machine,
-				format: opts.format,
-				mode: opts.mode,
-				theme: opts.theme,
-				readOnly: opts.readOnly,
-				depth: opts.depth,
-				leftPanels: opts.panels?.leftPanels,
-				rightPanels: opts.panels?.rightPanels,
-				activePanels: opts.panels?.activePanels
-			});
+			send(toInitMessage(opts));
 		},
 		updateMachine(machine, format) {
 			send({
@@ -146,49 +136,22 @@ function createStatelyEmbed(options) {
 				toastType
 			});
 		},
-		export(format, options) {
-			const { timeout = 1e4, ...formatOptions } = options ?? {};
-			return new Promise((resolve, reject) => {
-				if (destroyed) {
-					reject(/* @__PURE__ */ new Error("Embed is destroyed"));
-					return;
-				}
-				if (pendingExport) {
-					clearTimeout(pendingExport.timer);
-					pendingExport.reject(/* @__PURE__ */ new Error("Superseded by new export"));
-				}
-				pendingExport = {
-					resolve,
-					reject,
-					timer: setTimeout(() => {
-						pendingExport = null;
-						reject(/* @__PURE__ */ new Error("Export timed out"));
-					}, timeout),
-					format
-				};
-				send({
-					type: "@statelyai.retrieve",
-					format,
-					...Object.keys(formatOptions).length > 0 && { options: formatOptions }
-				});
-			});
+		export(format, callOptions) {
+			return exportManager.start(format, callOptions, "Embed is destroyed", () => destroyed);
 		},
 		on(event, handler) {
-			if (!listeners[event]) listeners[event] = /* @__PURE__ */ new Set();
-			listeners[event].add(handler);
+			events.on(event, handler);
 		},
 		off(event, handler) {
-			listeners[event]?.delete(handler);
+			events.off(event, handler);
 		},
 		destroy() {
 			if (destroyed) return;
 			destroyed = true;
-			window.removeEventListener("message", handleMessage);
-			if (pendingExport) {
-				clearTimeout(pendingExport.timer);
-				pendingExport.reject(/* @__PURE__ */ new Error("Embed destroyed"));
-				pendingExport = null;
-			}
+			transport?.destroy();
+			transport = null;
+			exportManager.clear("Embed destroyed");
+			events.clear();
 			pendingMessages.length = 0;
 			if (ownedIframe && iframe) iframe.remove();
 			iframe = null;
@@ -197,4 +160,4 @@ function createStatelyEmbed(options) {
 }
 
 //#endregion
-export { createStatelyEmbed };
+export { createInspector, createPostMessageTransport, createStatelyEmbed, createWebSocketTransport };

package/dist/inspect-Bt5Ohkrp.d.mts

@@ -0,0 +1,214 @@
+//#region src/protocol.d.ts
+type EmbedMode = 'editing' | 'viewing' | 'simulating' | 'inspecting';
+interface ExportFormatMap {
+  xstate: {
+    options: {
+      version?: 4 | 5;
+      addTSTypes?: boolean;
+      showIds?: boolean;
+      showDescriptions?: boolean;
+    };
+    result: string;
+  };
+  json: {
+    options: {
+      simplifyArrays?: boolean;
+      version?: 4 | 5;
+    };
+    result: Record<string, unknown>;
+  };
+  digraph: {
+    options: Record<string, never>;
+    result: Record<string, unknown>;
+  };
+  mermaid: {
+    options: Record<string, never>;
+    result: string;
+  };
+  scxml: {
+    options: Record<string, never>;
+    result: string;
+  };
+}
+type ExportFormat = keyof ExportFormatMap;
+type ExportCallOptions<F extends ExportFormat> = ExportFormatMap[F]['options'] & {
+  timeout?: number;
+};
+interface EmbedEventMap {
+  ready: {
+    version: string;
+  };
+  loaded: {
+    graph: unknown;
+  };
+  change: {
+    graph: unknown;
+    machineConfig: unknown;
+  };
+  save: {
+    graph: unknown;
+    machineConfig: unknown;
+  };
+  error: {
+    code: string;
+    message: string;
+  };
+  snapshot: {
+    snapshot: unknown;
+    event: unknown | null;
+  };
+}
+type EmbedEventName = keyof EmbedEventMap;
+type EmbedEventHandler<K extends EmbedEventName> = (data: EmbedEventMap[K]) => void;
+interface InitOptions {
+  machine: unknown;
+  format?: string;
+  mode?: EmbedMode;
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+  depth?: number;
+  panels?: {
+    leftPanels?: string[];
+    rightPanels?: string[];
+    activePanels?: string[];
+  };
+}
+interface InitMessage {
+  type: '@statelyai.init';
+  machine: unknown;
+  format?: string;
+  mode?: EmbedMode;
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+  depth?: number;
+  leftPanels?: string[];
+  rightPanels?: string[];
+  activePanels?: string[];
+}
+interface UpdateMessage {
+  type: '@statelyai.update';
+  machine: unknown;
+  format?: string;
+}
+interface SetModeMessage {
+  type: '@statelyai.setMode';
+  mode: EmbedMode;
+}
+interface SetThemeMessage {
+  type: '@statelyai.setTheme';
+  theme: 'light' | 'dark';
+}
+interface RetrieveMessage {
+  type: '@statelyai.retrieve';
+  requestId: string;
+  format: ExportFormat;
+  options?: Record<string, unknown>;
+}
+interface ToastMessage {
+  type: '@statelyai.toast';
+  message: string;
+  toastType?: 'success' | 'error' | 'info' | 'warning';
+}
+interface InspectSnapshotMessage {
+  type: '@statelyai.inspectSnapshot';
+  snapshot: unknown;
+  event: unknown | null;
+}
+/** All messages a client (embed/inspector) can send to the viz. */
+type ClientMessage = InitMessage | UpdateMessage | SetModeMessage | SetThemeMessage | RetrieveMessage | ToastMessage | InspectSnapshotMessage;
+interface ReadyMessage {
+  type: '@statelyai.ready';
+  version: string;
+}
+interface LoadedMessage {
+  type: '@statelyai.loaded';
+  graph: unknown;
+}
+interface ChangeMessage {
+  type: '@statelyai.change';
+  graph: unknown;
+  machineConfig: unknown;
+}
+interface SaveMessage {
+  type: '@statelyai.save';
+  graph: unknown;
+  machineConfig: unknown;
+}
+interface RetrievedMessage {
+  type: '@statelyai.retrieved';
+  requestId: string;
+  data: unknown;
+}
+interface ErrorMessage {
+  type: '@statelyai.error';
+  code: string;
+  message: string;
+  requestId?: string;
+}
+/** All messages the viz can send back to a client. */
+type VizMessage = ReadyMessage | LoadedMessage | ChangeMessage | SaveMessage | RetrievedMessage | ErrorMessage;
+interface RegisterMessage {
+  type: '@statelyai.register';
+  role: 'client' | 'viz';
+  sessionId: string;
+  metadata?: {
+    name?: string;
+    machineId?: string;
+  };
+}
+interface RegisteredMessage {
+  type: '@statelyai.registered';
+  sessionId: string;
+}
+interface RequestOpenMessage {
+  type: '@statelyai.requestOpen';
+  sessionId: string;
+}
+/** All session-management messages for the WS relay. */
+type SessionMessage = RegisterMessage | RegisteredMessage | RequestOpenMessage;
+/** Any valid protocol message. */
+type ProtocolMessage = ClientMessage | VizMessage | SessionMessage;
+//#endregion
+//#region src/inspect.d.ts
+interface CreateInspectorOptions {
+  /** WebSocket URL of the devtools server. Default: 'ws://localhost:4242' */
+  url?: string;
+  /** Auto-open browser to visualizer. Default: true */
+  autoOpen?: boolean;
+  /** Unique session ID. Auto-generated if not provided. */
+  sessionId?: string;
+  /** Display name for this connection in the visualizer. */
+  name?: string;
+}
+interface Inspector {
+  /** Send a machine for inspection (starts visualization). */
+  inspect(options: InspectOptions): void;
+  /** Update the machine currently being inspected. */
+  update(machine: unknown, format?: string): void;
+  /** Change the visualization mode. */
+  setMode(mode: EmbedMode): void;
+  /** Export the current machine in a given format. Returns a promise. */
+  export<F extends ExportFormat>(format: F, options?: ExportCallOptions<F>): Promise<ExportFormatMap[F]['result']>;
+  /** Subscribe to events from the visualizer. */
+  on<K extends EmbedEventName>(event: K, handler: EmbedEventHandler<K>): void;
+  /** Unsubscribe from an event. */
+  off<K extends EmbedEventName>(event: K, handler: EmbedEventHandler<K>): void;
+  /** Send a state snapshot for real-time inspection. */
+  sendSnapshot(snapshot: unknown, event?: unknown): void;
+  /** Clean up the connection. */
+  destroy(): void;
+  /** Session ID for this connection. */
+  readonly sessionId: string;
+}
+interface InspectOptions {
+  machine: unknown;
+  format?: string;
+  mode?: EmbedMode;
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+  depth?: number;
+  panels?: InitOptions['panels'];
+}
+declare function createInspector(options?: CreateInspectorOptions): Inspector;
+//#endregion
+export { EmbedEventHandler as a, EmbedMode as c, ExportFormatMap as d, InitOptions as f, createInspector as i, ExportCallOptions as l, InspectOptions as n, EmbedEventMap as o, ProtocolMessage as p, Inspector as r, EmbedEventName as s, CreateInspectorOptions as t, ExportFormat as u };

package/dist/inspect-C3Rjgn1o.mjs

@@ -0,0 +1,369 @@
+//#region src/clientUtils.ts
+const jsonResultFormats = new Set(["digraph", "json"]);
+function createRequestId() {
+	const cryptoObject = globalThis.crypto;
+	if (cryptoObject?.randomUUID) return cryptoObject.randomUUID();
+	return Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2);
+}
+function createEventRegistry() {
+	const listeners = {};
+	return {
+		emit(event, data) {
+			listeners[event]?.forEach((handler) => handler(data));
+		},
+		on(event, handler) {
+			if (!listeners[event]) listeners[event] = /* @__PURE__ */ new Set();
+			listeners[event].add(handler);
+		},
+		off(event, handler) {
+			listeners[event]?.delete(handler);
+		},
+		clear() {
+			Object.values(listeners).forEach((handlers) => handlers?.clear());
+		}
+	};
+}
+function parseExportedData(format, data) {
+	if (jsonResultFormats.has(format) && typeof data === "string") return JSON.parse(data);
+	return data;
+}
+function createPendingExportManager(sendRetrieve) {
+	const pendingExports = /* @__PURE__ */ new Map();
+	return {
+		start(format, callOptions, destroyedMessage, isDestroyed) {
+			const { timeout = 1e4, ...formatOptions } = callOptions ?? {};
+			return new Promise((resolve, reject) => {
+				if (isDestroyed()) {
+					reject(new Error(destroyedMessage));
+					return;
+				}
+				const requestId = createRequestId();
+				const timer = setTimeout(() => {
+					pendingExports.delete(requestId);
+					reject(/* @__PURE__ */ new Error("Export timed out"));
+				}, timeout);
+				pendingExports.set(requestId, {
+					resolve,
+					reject,
+					timer,
+					format
+				});
+				sendRetrieve({
+					type: "@statelyai.retrieve",
+					requestId,
+					format,
+					...Object.keys(formatOptions).length > 0 && { options: formatOptions }
+				});
+			});
+		},
+		resolve(requestId, data) {
+			const pendingExport = pendingExports.get(requestId);
+			if (!pendingExport) return;
+			pendingExports.delete(requestId);
+			const { resolve, timer, format } = pendingExport;
+			clearTimeout(timer);
+			resolve(parseExportedData(format, data));
+		},
+		reject(error, requestId) {
+			if (requestId) {
+				const pendingExport = pendingExports.get(requestId);
+				if (!pendingExport) return;
+				pendingExports.delete(requestId);
+				clearTimeout(pendingExport.timer);
+				pendingExport.reject(error);
+				return;
+			}
+			pendingExports.forEach((pendingExport, pendingRequestId) => {
+				pendingExports.delete(pendingRequestId);
+				clearTimeout(pendingExport.timer);
+				pendingExport.reject(error);
+			});
+		},
+		clear(message) {
+			this.reject(new Error(message));
+		}
+	};
+}
+function toInitMessage(options) {
+	return {
+		type: "@statelyai.init",
+		machine: options.machine,
+		format: options.format,
+		mode: options.mode,
+		theme: options.theme,
+		readOnly: options.readOnly,
+		depth: options.depth,
+		leftPanels: options.panels?.leftPanels,
+		rightPanels: options.panels?.rightPanels,
+		activePanels: options.panels?.activePanels
+	};
+}
+
+//#endregion
+//#region src/protocol.ts
+const PREFIX = "@statelyai.";
+
+//#endregion
+//#region src/transport.ts
+function createPostMessageTransport(options) {
+	const { iframe, targetOrigin } = options;
+	let destroyed = false;
+	let isReady = false;
+	const readyHandlers = /* @__PURE__ */ new Set();
+	const messageHandlers = /* @__PURE__ */ new Set();
+	function handleMessage(e) {
+		if (destroyed) return;
+		const expectedSource = options.source ?? iframe.contentWindow;
+		if (e.source !== expectedSource) return;
+		if (targetOrigin !== "*" && e.origin !== targetOrigin) return;
+		const data = e.data;
+		if (!data?.type?.startsWith?.(PREFIX)) return;
+		if (data.type === "@statelyai.ready" && !isReady) {
+			isReady = true;
+			readyHandlers.forEach((fn) => fn());
+			readyHandlers.clear();
+		}
+		messageHandlers.forEach((fn) => fn(data));
+	}
+	window.addEventListener("message", handleMessage);
+	return {
+		send(msg) {
+			if (destroyed) return;
+			iframe.contentWindow?.postMessage(msg, targetOrigin);
+		},
+		onMessage(handler) {
+			messageHandlers.add(handler);
+			return () => {
+				messageHandlers.delete(handler);
+			};
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			window.removeEventListener("message", handleMessage);
+			messageHandlers.clear();
+			readyHandlers.clear();
+		},
+		get ready() {
+			return isReady;
+		},
+		onReady(handler) {
+			if (isReady) {
+				handler();
+				return () => {};
+			}
+			readyHandlers.add(handler);
+			return () => {
+				readyHandlers.delete(handler);
+			};
+		}
+	};
+}
+function createWebSocketTransport(options) {
+	const { url, role, sessionId, metadata, reconnect = true, maxReconnectAttempts = 10 } = options;
+	let ws = null;
+	let destroyed = false;
+	let isReady = false;
+	let reconnectAttempts = 0;
+	let reconnectTimer = null;
+	const readyHandlers = /* @__PURE__ */ new Set();
+	const messageHandlers = /* @__PURE__ */ new Set();
+	function connect() {
+		if (destroyed) return;
+		ws = new WebSocket(url);
+		ws.onopen = () => {
+			reconnectAttempts = 0;
+			ws.send(JSON.stringify({
+				type: "@statelyai.register",
+				role,
+				sessionId,
+				...metadata && { metadata }
+			}));
+		};
+		ws.onmessage = (event) => {
+			if (destroyed) return;
+			let raw;
+			try {
+				raw = JSON.parse(event.data);
+			} catch {
+				return;
+			}
+			if (!raw?.type || typeof raw.type !== "string") return;
+			if (!raw.type.startsWith(PREFIX)) return;
+			const data = raw;
+			if (data.type === "@statelyai.registered" && !isReady) {
+				isReady = true;
+				readyHandlers.forEach((fn) => fn());
+				readyHandlers.clear();
+			}
+			messageHandlers.forEach((fn) => fn(data));
+		};
+		ws.onclose = () => {
+			if (destroyed) return;
+			isReady = false;
+			if (reconnect && reconnectAttempts < maxReconnectAttempts) {
+				const delay = Math.min(1e3 * 2 ** reconnectAttempts, 3e4);
+				reconnectAttempts++;
+				reconnectTimer = setTimeout(connect, delay);
+			}
+		};
+		ws.onerror = () => {};
+	}
+	connect();
+	return {
+		send(msg) {
+			if (destroyed || !ws || ws.readyState !== WebSocket.OPEN) return;
+			ws.send(JSON.stringify(msg));
+		},
+		onMessage(handler) {
+			messageHandlers.add(handler);
+			return () => {
+				messageHandlers.delete(handler);
+			};
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			if (reconnectTimer) clearTimeout(reconnectTimer);
+			ws?.close();
+			ws = null;
+			messageHandlers.clear();
+			readyHandlers.clear();
+		},
+		get ready() {
+			return isReady;
+		},
+		onReady(handler) {
+			if (isReady) {
+				handler();
+				return () => {};
+			}
+			readyHandlers.add(handler);
+			return () => {
+				readyHandlers.delete(handler);
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/inspect.ts
+function generateId() {
+	return createRequestId();
+}
+function createInspector(options) {
+	const { url = "ws://localhost:4242", autoOpen = true, sessionId = generateId(), name } = options ?? {};
+	let destroyed = false;
+	const pendingMessages = [];
+	const events = createEventRegistry();
+	const transport = createWebSocketTransport({
+		url,
+		role: "client",
+		sessionId,
+		...name && { metadata: { name } }
+	});
+	const exportManager = createPendingExportManager((message) => send(message));
+	function send(msg) {
+		if (!transport.ready) {
+			pendingMessages.push(msg);
+			return;
+		}
+		transport.send(msg);
+	}
+	function flush() {
+		while (pendingMessages.length > 0) {
+			const msg = pendingMessages.shift();
+			transport.send(msg);
+		}
+	}
+	transport.onReady(() => {
+		flush();
+	});
+	if (autoOpen) transport.onReady(() => {
+		transport.send({
+			type: "@statelyai.requestOpen",
+			sessionId
+		});
+	});
+	transport.onMessage((msg) => {
+		if (destroyed) return;
+		switch (msg.type) {
+			case "@statelyai.ready":
+				events.emit("ready", { version: msg.version });
+				break;
+			case "@statelyai.loaded":
+				events.emit("loaded", { graph: msg.graph });
+				break;
+			case "@statelyai.change":
+				events.emit("change", {
+					graph: msg.graph,
+					machineConfig: msg.machineConfig
+				});
+				break;
+			case "@statelyai.save":
+				events.emit("save", {
+					graph: msg.graph,
+					machineConfig: msg.machineConfig
+				});
+				break;
+			case "@statelyai.retrieved":
+				exportManager.resolve(msg.requestId, msg.data);
+				break;
+			case "@statelyai.error":
+				exportManager.reject(new Error(msg.message), msg.requestId);
+				events.emit("error", {
+					code: msg.code,
+					message: msg.message
+				});
+				break;
+		}
+	});
+	return {
+		get sessionId() {
+			return sessionId;
+		},
+		inspect(opts) {
+			send(toInitMessage(opts));
+		},
+		update(machine, format) {
+			send({
+				type: "@statelyai.update",
+				machine,
+				format
+			});
+		},
+		setMode(mode) {
+			send({
+				type: "@statelyai.setMode",
+				mode
+			});
+		},
+		export(format, callOptions) {
+			return exportManager.start(format, callOptions, "Inspector is destroyed", () => destroyed);
+		},
+		on(event, handler) {
+			events.on(event, handler);
+		},
+		off(event, handler) {
+			events.off(event, handler);
+		},
+		sendSnapshot(snapshot, event) {
+			send({
+				type: "@statelyai.inspectSnapshot",
+				snapshot,
+				event: event ?? null
+			});
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			transport.destroy();
+			exportManager.clear("Inspector destroyed");
+			events.clear();
+			pendingMessages.length = 0;
+		}
+	};
+}
+
+//#endregion
+export { createPendingExportManager as a, createEventRegistry as i, createPostMessageTransport as n, toInitMessage as o, createWebSocketTransport as r, createInspector as t };

package/dist/inspect.d.mts

@@ -0,0 +1,2 @@
+import { a as EmbedEventHandler, c as EmbedMode, d as ExportFormatMap, f as InitOptions, i as createInspector, l as ExportCallOptions, n as InspectOptions, o as EmbedEventMap, r as Inspector, s as EmbedEventName, t as CreateInspectorOptions, u as ExportFormat } from "./inspect-Bt5Ohkrp.mjs";
+export { CreateInspectorOptions, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InitOptions, InspectOptions, Inspector, createInspector };

package/dist/inspect.mjs

@@ -0,0 +1,3 @@
+import { t as createInspector } from "./inspect-C3Rjgn1o.mjs";
+
+export { createInspector };

package/package.json

@@ -1,24 +1,32 @@
 {
   "name": "@statelyai/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
+  "files": [
+    "dist"
+  ],
   "type": "module",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {
     ".": {
-      "import": "./dist/index.mjs",
-      "types": "./dist/index.d.mts"
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./inspect": {
+      "types": "./dist/inspect.d.mts",
+      "import": "./dist/inspect.mjs"
     }
   },
-  "files": [
-    "dist"
-  ],
   "devDependencies": {
+    "jsdom": "^27.4.0",
     "tsdown": "0.21.0-beta.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
   },
   "scripts": {
-    "build": "tsdown"
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }