@statelyai/sdk 0.5.0 → 0.5.1

package/README.md

@@ -69,6 +69,7 @@ The common environment variables are:
 | Variable | Purpose |
 | --- | --- |
 | `AUTH_PROVIDER` | Auth strategy used by the editor host |
+| `EDITOR_SYNC_AUTH_REQUIRED` | Set to `false` to disable API-key checks for editor-sync endpoints only |
 | `STATELY_API_KEY` | Server-side API key for Stately data fetching |
 | `STATELY_API_URL` | Stately API base URL override |
 | `NEXT_PUBLIC_BASE_URL` | Public-facing editor URL |
@@ -354,7 +355,7 @@ const aslYaml = await embed.export('asl-yaml');
 
 <!-- supported export formats from ExportFormatMap in src/protocol.ts -->
 
-Supported formats: `xstate`, `json`, `digraph`, `mermaid`, `rtk`, `zustand`, `asl-json`, `asl-yaml`, `scxml`
+Supported formats: `xstate`, `json`, `xgraph`, `digraph`, `mermaid`, `rtk`, `zustand`, `asl-json`, `asl-yaml`, `scxml`
 
 #### `embed.on(event, handler)` / `embed.off(event, handler)`
 
@@ -507,11 +508,11 @@ Available commands:
 
 Common flags:
 
-- `--api-key` for remote machine resolution
+- `--api-key` for remote machine resolution or editor servers that require auth
 - `--base-url` for self-hosted or non-default Stately deployments
 - `--fail-on-changes` to return a nonzero exit code when a diff is detected
 
-`statelyai open` also supports `--editor-url`, `--host`, `--port`, `--no-open`, and `--debug`. It watches the local file on disk, updates the visual editor after saved source changes, and writes saved visual edits back to source.
+`statelyai open` also supports `--api-key`, `--editor-url`, `--host`, `--port`, `--no-open`, and `--debug`. It watches the local file on disk and sends source snapshots to `/api/editor-sync/*` endpoints, which return the text replacements to apply locally. Pass `--api-key` or set `STATELY_API_KEY` when the editor server requires auth. Self-hosted servers can disable editor-sync API-key checks with `EDITOR_SYNC_AUTH_REQUIRED=false`. The private source reconciliation engine is not bundled into the published CLI.
 
 ## Transport Helpers
 

package/dist/cli.mjs

@@ -1,11 +1,651 @@
 #!/usr/bin/env node
 import { planSync, pullSync } from "./sync.mjs";
+import fs from "node:fs/promises";
+import * as path$1 from "node:path";
 import path from "node:path";
-import fs from "node:fs";
-import { fileURLToPath } from "node:url";
+import fs$1, { watch } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { Args, Command, Flags, flush, handle, run as run$1 } from "@oclif/core";
-import { openEditor } from "@statelyai/editor-sync/cli-host";
+import * as crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import * as http from "node:http";
 
+//#region src/cliHost.ts
+const DEFAULT_SYNC_MAX_FILES = 150;
+const DEFAULT_SYNC_MAX_BYTES = 2e6;
+const supportedDocumentPattern = /\.(?:c|m)?(?:jsx?|tsx?)$|\.jsonc?$|\.ya?ml$|\.mmd$|\.mermaid$/i;
+var WebSocketClient = class {
+	buffer = Buffer.alloc(0);
+	listeners = /* @__PURE__ */ new Set();
+	constructor(socket) {
+		this.socket = socket;
+		socket.on("data", (chunk) => {
+			const nextChunk = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+			this.buffer = Buffer.concat([this.buffer, nextChunk]);
+			this.readFrames();
+		});
+	}
+	onMessage(listener) {
+		this.listeners.add(listener);
+	}
+	send(message) {
+		this.socket.write(encodeWebSocketFrame(JSON.stringify(message)));
+	}
+	close() {
+		this.socket.end();
+	}
+	readFrames() {
+		while (this.buffer.length >= 2) {
+			const first = this.buffer[0];
+			const second = this.buffer[1];
+			const opcode = first & 15;
+			const masked = (second & 128) !== 0;
+			let length = second & 127;
+			let offset = 2;
+			if (length === 126) {
+				if (this.buffer.length < offset + 2) return;
+				length = this.buffer.readUInt16BE(offset);
+				offset += 2;
+			} else if (length === 127) {
+				if (this.buffer.length < offset + 8) return;
+				const bigLength = this.buffer.readBigUInt64BE(offset);
+				if (bigLength > BigInt(Number.MAX_SAFE_INTEGER)) {
+					this.socket.destroy(/* @__PURE__ */ new Error("WebSocket frame is too large."));
+					return;
+				}
+				length = Number(bigLength);
+				offset += 8;
+			}
+			const maskLength = masked ? 4 : 0;
+			if (this.buffer.length < offset + maskLength + length) return;
+			const mask = masked ? this.buffer.subarray(offset, offset + 4) : void 0;
+			offset += maskLength;
+			const payload = Buffer.from(this.buffer.subarray(offset, offset + length));
+			this.buffer = this.buffer.subarray(offset + length);
+			if (mask) for (let index = 0; index < payload.length; index++) payload[index] = payload[index] ^ mask[index % 4];
+			if (opcode === 8) {
+				this.close();
+				return;
+			}
+			if (opcode === 9) {
+				this.socket.write(encodeWebSocketFrame(payload, 10));
+				continue;
+			}
+			if (opcode !== 1) continue;
+			const message = JSON.parse(payload.toString("utf8"));
+			for (const listener of this.listeners) listener(message);
+		}
+	}
+};
+var RemoteEditorSession = class {
+	currentGraph;
+	lastPersistedGraph;
+	currentSourceLocations;
+	currentFormat;
+	ready = false;
+	pendingMessages = [];
+	pendingRetrievals = /* @__PURE__ */ new Map();
+	retrieveRequestCount = 0;
+	watchedSourceUris = /* @__PURE__ */ new Set();
+	selfEditCount = 0;
+	watcher;
+	constructor(options, sendMessage) {
+		this.options = options;
+		this.sendMessage = sendMessage;
+		this.watcher = watchWorkspace(this.options.rootDir, (uri) => {
+			this.handleSavedDocument(uri);
+		});
+	}
+	dispose() {
+		for (const pending of this.pendingRetrievals.values()) pending.reject(/* @__PURE__ */ new Error("Editor session disposed before export completed."));
+		this.pendingRetrievals.clear();
+		this.watcher?.dispose();
+	}
+	async receiveMessage(msg) {
+		this.log("recv", msg.type, msg);
+		switch (msg.type) {
+			case "@statelyai.ready":
+				await this.initializeEditor();
+				break;
+			case "@statelyai.loaded":
+				this.currentGraph = msg.graph;
+				this.lastPersistedGraph = msg.graph;
+				this.currentSourceLocations = msg.sourceLocations ?? this.currentSourceLocations;
+				this.updateSourceLocations(this.currentSourceLocations);
+				break;
+			case "@statelyai.change":
+				this.currentGraph = msg.graph;
+				this.currentSourceLocations = msg.sourceLocations ?? this.currentSourceLocations;
+				this.updateSourceLocations(this.currentSourceLocations);
+				break;
+			case "@statelyai.save":
+				await this.saveFromEditor(msg);
+				break;
+			case "@statelyai.retrieved":
+				this.resolveRetrievedSource(msg);
+				break;
+			case "@statelyai.clipboardRead":
+				this.postMessage({
+					type: "@statelyai.clipboardReadResponse",
+					requestId: msg.requestId,
+					text: ""
+				});
+				break;
+			case "@statelyai.error":
+				this.handleErrorMessage(msg);
+				break;
+		}
+	}
+	async initializeEditor() {
+		this.ready = true;
+		try {
+			const update = await this.parseRootDocument();
+			this.currentFormat = update.format;
+			this.currentSourceLocations = update.sourceLocations;
+			this.updateSourceLocations(update.sourceLocations);
+			this.postMessage({
+				type: "@statelyai.init",
+				machine: update.machine,
+				format: update.format,
+				sourceLocations: update.sourceLocations,
+				mode: "editing",
+				theme: "light",
+				unsavedIndicator: { enabled: true },
+				leftPanels: [],
+				rightPanels: [],
+				activePanels: []
+			});
+		} catch (error) {
+			this.showError(formatError(error, "Failed to initialize the visual editor."));
+			return;
+		}
+		for (const pending of this.pendingMessages) this.sendMessage(pending);
+		this.pendingMessages = [];
+	}
+	async handleSavedDocument(uri) {
+		if (uri !== this.options.rootUri && !this.watchedSourceUris.has(uri)) return;
+		if (this.selfEditCount > 0) return;
+		try {
+			const update = await this.parseRootDocument();
+			this.currentFormat = update.format;
+			this.currentSourceLocations = update.sourceLocations;
+			this.updateSourceLocations(update.sourceLocations);
+			this.postMessage({
+				type: "@statelyai.update",
+				machine: update.machine,
+				format: update.format,
+				sourceLocations: update.sourceLocations
+			});
+		} catch (error) {
+			this.showError(formatError(error, "Failed to read the saved document."));
+		}
+	}
+	async saveFromEditor(msg) {
+		const validationErrors = getValidationErrors(msg.validations);
+		if (validationErrors.length > 0) {
+			const message = formatValidationErrorMessage(validationErrors);
+			this.postMessage({
+				type: "@statelyai.toast",
+				message,
+				toastType: "error"
+			});
+			this.showError(message);
+			return;
+		}
+		this.currentSourceLocations = msg.sourceLocations ?? this.currentSourceLocations;
+		this.updateSourceLocations(this.currentSourceLocations);
+		try {
+			const serialized = await this.getSerializedPayloadForCurrentFormat();
+			const documents = await collectSourceDocuments({
+				rootFileName: this.options.fileName,
+				rootDir: this.options.rootDir,
+				extraUris: sourceLocationUris(this.currentSourceLocations)
+			});
+			const response = await this.postSync("/api/editor-sync/apply", {
+				rootUri: this.options.rootUri,
+				rootFileName: this.options.fileName,
+				rootDir: this.options.rootDir,
+				documents,
+				machineConfig: msg.machineConfig,
+				patches: msg.patches,
+				prevGraph: this.lastPersistedGraph ?? this.currentGraph,
+				nextGraph: msg.graph,
+				sourceLocations: this.currentSourceLocations,
+				serialized
+			});
+			if (response.replacements.length === 0) {
+				const message = "Unable to apply Viz changes to the source file automatically.";
+				this.postMessage({
+					type: "@statelyai.toast",
+					message,
+					toastType: "error"
+				});
+				this.showError(message);
+				return;
+			}
+			await this.runWithSelfEdit(async () => {
+				await applyFileReplacements(response.replacements, this.options.rootUri);
+			});
+			this.currentGraph = msg.graph;
+			this.lastPersistedGraph = msg.graph;
+		} catch (error) {
+			const message = formatError(error, "Failed to apply Viz changes.");
+			this.postMessage({
+				type: "@statelyai.toast",
+				message,
+				toastType: "error"
+			});
+			this.showError(message);
+		}
+	}
+	async parseRootDocument() {
+		const documents = await collectSourceDocuments({
+			rootFileName: this.options.fileName,
+			rootDir: this.options.rootDir,
+			extraUris: sourceLocationUris(this.currentSourceLocations)
+		});
+		return this.postSync("/api/editor-sync/parse", {
+			rootUri: this.options.rootUri,
+			rootFileName: this.options.fileName,
+			rootDir: this.options.rootDir,
+			documents
+		});
+	}
+	async postSync(pathname, body) {
+		const url = new URL(pathname, normalizedBaseUrl(this.options.editorUrl));
+		const headers = { "Content-Type": "application/json" };
+		if (this.options.apiKey) headers.Authorization = `Bearer ${this.options.apiKey}`;
+		const response = await fetch(url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body)
+		});
+		const data = await response.json().catch(() => null);
+		if (!response.ok) {
+			const message = data && typeof data === "object" && "error" in data && typeof data.error === "string" ? data.error : `HTTP ${response.status}`;
+			throw new Error(message);
+		}
+		return data;
+	}
+	async getSerializedPayloadForCurrentFormat() {
+		const format = this.currentFormat;
+		if (!format || format === "xstate") return;
+		try {
+			const serialized = await this.requestSerialized(format);
+			return { [format]: serialized };
+		} catch {
+			return;
+		}
+	}
+	requestSerialized(format) {
+		const requestId = `retrieve-${++this.retrieveRequestCount}`;
+		return new Promise((resolve, reject) => {
+			this.pendingRetrievals.set(requestId, {
+				resolve,
+				reject
+			});
+			this.postMessage({
+				type: "@statelyai.retrieve",
+				requestId,
+				format
+			});
+		});
+	}
+	resolveRetrievedSource(msg) {
+		const pending = this.pendingRetrievals.get(msg.requestId);
+		if (!pending) return;
+		this.pendingRetrievals.delete(msg.requestId);
+		const serialized = typeof msg.data === "string" ? msg.data : JSON.stringify(msg.data, null, 2);
+		pending.resolve(serialized);
+	}
+	handleErrorMessage(msg) {
+		if (msg.requestId) {
+			const pending = this.pendingRetrievals.get(msg.requestId);
+			if (pending) {
+				this.pendingRetrievals.delete(msg.requestId);
+				pending.reject(new Error(msg.message));
+				return;
+			}
+		}
+		this.showError(msg.message);
+	}
+	updateSourceLocations(sourceLocations) {
+		this.watchedSourceUris.clear();
+		for (const location of sourceLocations?.states ?? []) if (location.uri !== this.options.rootUri) this.watchedSourceUris.add(location.uri);
+	}
+	async runWithSelfEdit(operation) {
+		this.selfEditCount++;
+		try {
+			return await operation();
+		} finally {
+			this.selfEditCount--;
+		}
+	}
+	postMessage(msg) {
+		this.log("send", msg.type, msg);
+		if (!this.ready) {
+			this.pendingMessages.push(msg);
+			return;
+		}
+		this.sendMessage(msg);
+	}
+	showError(message) {
+		console.error(`Stately Editor: ${message}`);
+	}
+	log(direction, type, payload) {
+		if (this.options.debug) console.error(`[${direction}] ${type}`, payload ?? "");
+	}
+};
+async function openEditor(options) {
+	const fileName = path$1.resolve(options.fileName);
+	await fs.access(fileName);
+	const rootUri = fileNameToUri(fileName);
+	const rootDir = path$1.dirname(fileName);
+	let activeClient;
+	let session;
+	const server = http.createServer((request, response) => {
+		if (new URL(request.url ?? "/", `http://${request.headers.host}`).pathname !== "/") {
+			response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+			response.end("Not found");
+			return;
+		}
+		response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+		response.end(getCliWebviewContent({
+			editorUrl: options.editorUrl,
+			apiKey: options.apiKey
+		}));
+	});
+	server.on("upgrade", (request, socket) => {
+		if (request.url !== "/ws") {
+			socket.end("HTTP/1.1 404 Not Found\r\n\r\n");
+			return;
+		}
+		const key = request.headers["sec-websocket-key"];
+		if (typeof key !== "string") {
+			socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+			return;
+		}
+		const accept = crypto.createHash("sha1").update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`).digest("base64");
+		socket.write([
+			"HTTP/1.1 101 Switching Protocols",
+			"Upgrade: websocket",
+			"Connection: Upgrade",
+			`Sec-WebSocket-Accept: ${accept}`,
+			"\r\n"
+		].join("\r\n"));
+		activeClient?.close();
+		session?.dispose();
+		activeClient = new WebSocketClient(socket);
+		session = new RemoteEditorSession({
+			...options,
+			fileName,
+			rootUri,
+			rootDir
+		}, (message) => activeClient?.send(message));
+		activeClient.onMessage((message) => {
+			session?.receiveMessage(message);
+		});
+	});
+	await listen(server, options.port, options.host);
+	const address = server.address();
+	const port = typeof address === "object" && address ? address.port : options.port;
+	const editorPageUrl = `http://${options.host}:${port}`;
+	console.log(`Stately visual editor: ${editorPageUrl}`);
+	console.log(`Editing ${fileName}`);
+	if (options.shouldOpen) openBrowser(editorPageUrl);
+	const shutdown = () => {
+		session?.dispose();
+		activeClient?.close();
+		server.close();
+	};
+	process.once("SIGINT", () => {
+		shutdown();
+		process.exit(0);
+	});
+	process.once("SIGTERM", () => {
+		shutdown();
+		process.exit(0);
+	});
+}
+async function collectSourceDocuments(options) {
+	const files = new Set([options.rootFileName]);
+	const maxFiles = Number.parseInt(process.env.STATELY_SYNC_MAX_FILES ?? "", 10) || DEFAULT_SYNC_MAX_FILES;
+	const maxBytes = Number.parseInt(process.env.STATELY_SYNC_MAX_BYTES ?? "", 10) || DEFAULT_SYNC_MAX_BYTES;
+	for (const uri of options.extraUris ?? []) files.add(sourceUriToFileName(uri));
+	await collectDirectoryFiles(options.rootDir, files, maxFiles);
+	const documents = [];
+	let totalBytes = 0;
+	for (const fileName of files) {
+		if (!isSupportedDocument(fileName)) continue;
+		const text = await fs.readFile(fileName, "utf8").catch(() => null);
+		if (text === null) continue;
+		totalBytes += Buffer.byteLength(text);
+		if (totalBytes > maxBytes) throw new Error(`Source payload exceeds ${maxBytes} bytes.`);
+		documents.push({
+			uri: fileNameToUri(fileName),
+			fileName,
+			text
+		});
+	}
+	return documents;
+}
+async function collectDirectoryFiles(rootDir, files, maxFiles) {
+	const queue = [rootDir];
+	while (queue.length > 0 && files.size < maxFiles) {
+		const dir = queue.shift();
+		const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+		for (const entry of entries) {
+			if (files.size >= maxFiles) break;
+			if (entry.name.startsWith(".") || shouldSkipDirectory(entry.name)) continue;
+			const fileName = path$1.join(dir, entry.name);
+			if (entry.isDirectory()) queue.push(fileName);
+			else if (entry.isFile() && isSupportedDocument(fileName)) files.add(fileName);
+		}
+	}
+}
+function shouldSkipDirectory(name) {
+	return [
+		"node_modules",
+		"dist",
+		"out",
+		"build",
+		"coverage",
+		".git"
+	].includes(name);
+}
+function isSupportedDocument(fileName) {
+	return supportedDocumentPattern.test(fileName);
+}
+async function applyFileReplacements(replacements, defaultUri) {
+	const replacementsByUri = /* @__PURE__ */ new Map();
+	for (const replacement of replacements) {
+		const uri = replacement.uri ?? defaultUri;
+		const existing = replacementsByUri.get(uri) ?? [];
+		existing.push(replacement);
+		replacementsByUri.set(uri, existing);
+	}
+	for (const [uri, uriReplacements] of replacementsByUri) {
+		const fileName = sourceUriToFileName(uri);
+		const nextText = applyReplacementsToText(await fs.readFile(fileName, "utf8"), uriReplacements);
+		await fs.writeFile(fileName, nextText, "utf8");
+	}
+}
+function applyReplacementsToText(text, replacements) {
+	let updated = text;
+	const sorted = [...replacements].sort(compareReplacementRangesDescending);
+	for (const replacement of sorted) {
+		const lineStarts = getLineStarts(updated);
+		const start = offsetAt(lineStarts, replacement.range.startLine, replacement.range.startChar);
+		const end = offsetAt(lineStarts, replacement.range.endLine, replacement.range.endChar);
+		updated = `${updated.slice(0, start)}${replacement.newText}${updated.slice(end)}`;
+	}
+	return updated;
+}
+function watchWorkspace(rootDir, listener) {
+	let watcher;
+	const timers = /* @__PURE__ */ new Map();
+	const queue = (fileName) => {
+		const existing = timers.get(fileName);
+		if (existing) clearTimeout(existing);
+		timers.set(fileName, setTimeout(() => {
+			timers.delete(fileName);
+			listener(fileNameToUri(fileName));
+		}, 75));
+	};
+	try {
+		watcher = watch(rootDir, { recursive: true }, (_event, fileName) => {
+			if (fileName) queue(path$1.join(rootDir, fileName.toString()));
+		});
+	} catch {
+		watcher = watch(rootDir, (_event, fileName) => {
+			if (fileName) queue(path$1.join(rootDir, fileName.toString()));
+		});
+	}
+	return { dispose() {
+		watcher?.close();
+		for (const timer of timers.values()) clearTimeout(timer);
+		timers.clear();
+	} };
+}
+function getCliWebviewContent(options) {
+	const baseUrl = normalizedBaseUrl(options.editorUrl);
+	const url = new URL(`${baseUrl}/embed`);
+	if (options.apiKey) url.searchParams.set("api_key", options.apiKey);
+	return `<!DOCTYPE html>
+<html lang="en" style="height:100%;margin:0">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <style>
+    body { margin: 0; padding: 0; height: 100vh; overflow: hidden; }
+    iframe { border: 0; width: 100%; height: 100%; display: block; }
+  </style>
+</head>
+<body>
+  <iframe
+    id="stately-editor"
+    src="${escapeAttribute(url.toString())}"
+    allow="clipboard-read; clipboard-write"
+  ></iframe>
+  <script>
+    const iframe = document.getElementById('stately-editor');
+    const socket = new WebSocket(
+      (location.protocol === 'https:' ? 'wss:' : 'ws:') + '//' + location.host + '/ws'
+    );
+    const pending = [];
+
+    function sendToCli(message) {
+      if (socket.readyState === WebSocket.OPEN) {
+        socket.send(JSON.stringify(message));
+        return;
+      }
+      pending.push(message);
+    }
+
+    socket.addEventListener('open', () => {
+      while (pending.length > 0) {
+        socket.send(JSON.stringify(pending.shift()));
+      }
+    });
+
+    socket.addEventListener('message', (event) => {
+      iframe.contentWindow?.postMessage(JSON.parse(event.data), '*');
+    });
+
+    window.addEventListener('message', (event) => {
+      if (!event.data?.type?.startsWith?.('@statelyai.')) {
+        return;
+      }
+      sendToCli(event.data);
+    });
+  <\/script>
+</body>
+</html>`;
+}
+function encodeWebSocketFrame(payload, opcode = 1) {
+	const data = typeof payload === "string" ? Buffer.from(payload) : payload;
+	const headerLength = data.length < 126 ? 2 : data.length <= 65535 ? 4 : 10;
+	const frame = Buffer.alloc(headerLength + data.length);
+	frame[0] = 128 | opcode;
+	if (data.length < 126) {
+		frame[1] = data.length;
+		data.copy(frame, 2);
+	} else if (data.length <= 65535) {
+		frame[1] = 126;
+		frame.writeUInt16BE(data.length, 2);
+		data.copy(frame, 4);
+	} else {
+		frame[1] = 127;
+		frame.writeBigUInt64BE(BigInt(data.length), 2);
+		data.copy(frame, 10);
+	}
+	return frame;
+}
+function listen(server, port, host) {
+	return new Promise((resolve) => {
+		server.listen(port, host, resolve);
+	});
+}
+function openBrowser(url) {
+	spawn(process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open", process.platform === "win32" ? [
+		"/c",
+		"start",
+		"",
+		url
+	] : [url], {
+		detached: true,
+		stdio: "ignore"
+	}).unref();
+}
+function getValidationErrors(validations) {
+	return (validations ?? []).filter((validation) => validation.level === "error");
+}
+function formatValidationErrorMessage(errors) {
+	const [firstError] = errors;
+	if (!firstError) return "Cannot save Viz changes because the graph has validation errors.";
+	if (errors.length === 1) return `Cannot save Viz changes: ${firstError.message}`;
+	return `Cannot save Viz changes: ${errors.length} validation errors. First: ${firstError.message}`;
+}
+function sourceLocationUris(sourceLocations) {
+	return [
+		...sourceLocations?.root ? [sourceLocations.root.uri] : [],
+		...(sourceLocations?.states ?? []).map((state) => state.uri),
+		...(sourceLocations?.staticValues ?? []).map((value) => value.uri)
+	];
+}
+function fileNameToUri(fileName) {
+	return pathToFileURL(path$1.resolve(fileName)).toString();
+}
+function sourceUriToFileName(uriOrPath) {
+	if (uriOrPath.startsWith("file://")) return fileURLToPath(uriOrPath);
+	if (/^[a-z][a-z\d+.-]*:/i.test(uriOrPath)) throw new Error(`Unsupported non-file URI: ${uriOrPath}`);
+	return path$1.resolve(uriOrPath);
+}
+function getLineStarts(text) {
+	const lineStarts = [0];
+	for (let index = 0; index < text.length; index += 1) if (text.charCodeAt(index) === 10) lineStarts.push(index + 1);
+	return lineStarts;
+}
+function offsetAt(lineStarts, line, character) {
+	const lineStart = lineStarts[line];
+	if (lineStart === void 0) return lineStarts[lineStarts.length - 1] + character;
+	return lineStart + character;
+}
+function compareReplacementRangesDescending(left, right) {
+	if (left.range.startLine !== right.range.startLine) return right.range.startLine - left.range.startLine;
+	return right.range.startChar - left.range.startChar;
+}
+function normalizedBaseUrl(value) {
+	return value.replace(/\/+$/, "");
+}
+function formatError(error, fallback) {
+	return error instanceof Error ? error.message : fallback;
+}
+function escapeAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+//#endregion
 //#region src/cli.ts
 function loadLocalEnv() {
 	if (typeof process.loadEnvFile !== "function") return;
@@ -136,7 +776,7 @@ var OpenCommand = class OpenCommand extends Command {
 	}) };
 	static flags = {
 		help: Flags.help({ char: "h" }),
-		"api-key": Flags.string({ description: "Stately API key used by the embedded editor" }),
+		"api-key": Flags.string({ description: "Stately API key used when the editor server requires auth" }),
 		"editor-url": Flags.string({ description: "Base URL for the Stately editor embed" }),
 		host: Flags.string({
 			description: "Local server host",
@@ -190,7 +830,7 @@ function isDirectExecution() {
 	if (!entryPath) return false;
 	const modulePath = fileURLToPath(import.meta.url);
 	try {
-		return fs.realpathSync(entryPath) === fs.realpathSync(modulePath);
+		return fs$1.realpathSync(entryPath) === fs$1.realpathSync(modulePath);
 	} catch {
 		return path.resolve(entryPath) === modulePath;
 	}

package/dist/embed.d.mts

@@ -1,4 +1,4 @@
-import { a as EmbedMode, c as ExportFormatMap, f as UploadResult, i as EmbedEventName, l as InitOptions, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat, t as CommentsConfig, u as MachineSourceLocations } from "./protocol-B1cNV7QB.mjs";
+import { a as EmbedMode, c as ExportFormatMap, f as UploadResult, i as EmbedEventName, l as InitOptions, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat, t as CommentsConfig, u as MachineSourceLocations } from "./protocol-BPuwbNCz.mjs";
 
 //#region src/embed.d.ts
 interface AssetConfig {

package/dist/embed.mjs

@@ -1,4 +1,4 @@
-import { a as toInitMessage, i as createPendingExportManager, r as createEventRegistry, t as createPostMessageTransport } from "./transport-lomH7b0v.mjs";
+import { a as toInitMessage, i as createPendingExportManager, r as createEventRegistry, t as createPostMessageTransport } from "./transport-DoCHBLTu.mjs";
 
 //#region src/embed.ts
 function buildEmbedUrl(options) {

package/dist/{graphToXStateTS-BSUj97r0.mjs → graphToXStateTS-CtecEESq.mjs}

@@ -5,6 +5,7 @@
 * - Single-quoted strings
 * - Omits undefined values
 * - Supports RawCode for verbatim expressions
+* - Supports inline expression directives for verbatim expressions
 */
 const VALID_IDENT = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 var RawCode = class {
@@ -17,6 +18,7 @@ function raw(code) {
 }
 function serializeJS(value, indent = 0, step = 2) {
 	if (value instanceof RawCode) return value.code;
+	if (isInlineExpressionDirective(value)) return value.expr;
 	if (value === void 0) return "undefined";
 	if (value === null) return "null";
 	if (typeof value === "string") return `'${escapeString(value)}'`;
@@ -45,10 +47,18 @@ function serializeObject(obj, indent, step) {
 	return `{\n${entries.map(([key, val]) => {
 		const k = VALID_IDENT.test(key) ? key : `'${escapeString(key)}'`;
 		const serialized = serializeJS(val, inner, step);
-		if (val instanceof RawCode && serialized.includes("\n")) return `${pad}${k}: ${indentRawCode(serialized, inner)}`;
+		if (isRawExpression(val) && serialized.includes("\n")) return `${pad}${k}: ${indentRawCode(serialized, inner)}`;
 		return `${pad}${k}: ${serialized}`;
 	}).join(",\n")},\n${closePad}}`;
 }
+function isRawExpression(value) {
+	return value instanceof RawCode || isInlineExpressionDirective(value);
+}
+function isInlineExpressionDirective(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const directive = value;
+	return directive["@type"] === "code" && typeof directive.expr === "string";
+}
 function indentRawCode(code, indent) {
 	const lines = code.split("\n");
 	if (lines.length <= 1) return code;
@@ -250,7 +260,8 @@ function graphToMachineConfig(graph, options = {}) {
 			...node.data.invokes?.length ? { invoke: node.data.invokes.map((inv) => ({
 				src: inv.src,
 				id: inv.id,
-				...inv.input ? { input: inv.input } : void 0
+				...inv.input ? { input: inv.input } : void 0,
+				...inv.output ? { output: inv.output } : void 0
 			})) } : void 0,
 			...tags?.length ? { tags: tags.map(tagToString) } : void 0,
 			...showDescriptions && node.data.description ? { description: node.data.description } : void 0,

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 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-BfezxFKJ.mjs";
 import { a as ProjectMachine, c as StudioClientOptions, i as ProjectData, l as VerifyApiKeyResponse, n as ExtractedMachine, o as StudioApiError, r as GetMachineOptions, s as StudioClient, t as ExtractMachinesResponse, u as createStatelyClient } from "./studio-D2uQhrvX.mjs";
 import { PlanSyncOptions, PullSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary } from "./sync.mjs";
-import { a as EmbedMode, c as ExportFormatMap, f as UploadResult, i as EmbedEventName, l as InitOptions, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat, t as CommentsConfig } from "./protocol-B1cNV7QB.mjs";
+import { a as EmbedMode, c as ExportFormatMap, f as UploadResult, i as EmbedEventName, l as InitOptions, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat, t as CommentsConfig } from "./protocol-BPuwbNCz.mjs";
 import { AssetConfig, StatelyEmbed, StatelyEmbedOptions, createStatelyEmbed } from "./embed.mjs";
-import { a as ManualActorOptions, c as createPostMessageTransport, i as InspectorEvents, l as createWebSocketTransport, n as CreateInspectorOptions, o as createStatelyInspector, r as Inspector, s as Transport, t as AdoptedActor } from "./inspect-WUC2inmJ.mjs";
+import { a as ManualActorOptions, c as createPostMessageTransport, i as InspectorEvents, l as createWebSocketTransport, n as CreateInspectorOptions, o as createStatelyInspector, r as Inspector, s as Transport, t as AdoptedActor } from "./inspect-ttRIjoCu.mjs";
 import { ActionLocation, GraphPatch } from "./patchTypes.mjs";
 import { JSONSchema7 } from "json-schema";
 import { UnknownMachineConfig } from "xstate";
@@ -18,10 +18,23 @@ interface CodeGenGuard {
   code?: string;
   params?: Record<string, unknown>;
 }
+/**
+ * Serialized inline expression directive.
+ *
+ * Code generation treats this object as JavaScript/TypeScript source, not as a
+ * machine config object. It is used for fields such as invoke `input` and
+ * `output` where XState accepts mapper expressions.
+ */
+interface CodeExpression {
+  '@type': 'code';
+  lang: 'js' | 'ts';
+  expr: string;
+}
 interface CodeGenInvoke {
   src: string;
   id: string;
-  input?: unknown;
+  input?: Record<string, unknown> | CodeExpression;
+  output?: Record<string, unknown> | CodeExpression;
 }
 interface CodeGenNodeData {
   nodeId?: string | null;
@@ -126,6 +139,7 @@ declare function graphToXStateTS(graph: CodeGenGraph, options?: XStateTSOptions)
  * - Single-quoted strings
  * - Omits undefined values
  * - Supports RawCode for verbatim expressions
+ * - Supports inline expression directives for verbatim expressions
  */
 declare class RawCode {
   code: string;

package/dist/index.mjs

@@ -1,8 +1,8 @@
-import { n as createWebSocketTransport, t as createPostMessageTransport } from "./transport-lomH7b0v.mjs";
+import { n as createWebSocketTransport, t as createPostMessageTransport } from "./transport-DoCHBLTu.mjs";
 import { createStatelyEmbed } from "./embed.mjs";
 import { createStatelyInspector } from "./inspect.mjs";
 import { StudioApiError, createStatelyClient } from "./studio.mjs";
 import { fromStudioMachine, studioMachineConverter, toStudioMachine } from "./graph.mjs";
-import { a as graphToMachineConfig, c as serializeJS, i as jsonSchemaToTSType, n as contextSchemaToTSType, o as RawCode, r as eventsSchemaToTSType, s as raw, t as graphToXStateTS } from "./graphToXStateTS-BSUj97r0.mjs";
+import { a as graphToMachineConfig, c as serializeJS, i as jsonSchemaToTSType, n as contextSchemaToTSType, o as RawCode, r as eventsSchemaToTSType, s as raw, t as graphToXStateTS } from "./graphToXStateTS-CtecEESq.mjs";
 
 export { RawCode, StudioApiError, contextSchemaToTSType, createPostMessageTransport, createStatelyClient, createStatelyEmbed, createStatelyInspector, createWebSocketTransport, eventsSchemaToTSType, fromStudioMachine, graphToMachineConfig, graphToXStateTS, jsonSchemaToTSType, raw, serializeJS, studioMachineConverter, toStudioMachine };

package/dist/{inspect-WUC2inmJ.d.mts → inspect-ttRIjoCu.d.mts}

@@ -1,4 +1,4 @@
-import { c as ExportFormatMap, d as ProtocolMessage, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat } from "./protocol-B1cNV7QB.mjs";
+import { c as ExportFormatMap, d as ProtocolMessage, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat } from "./protocol-BPuwbNCz.mjs";
 
 //#region src/transport.d.ts
 interface Transport {

package/dist/inspect.d.mts

@@ -1,3 +1,3 @@
-import { a as EmbedMode, c as ExportFormatMap, i as EmbedEventName, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat } from "./protocol-B1cNV7QB.mjs";
-import { a as ManualActorOptions, i as InspectorEvents, n as CreateInspectorOptions, o as createStatelyInspector, r as Inspector, s as Transport, t as AdoptedActor } from "./inspect-WUC2inmJ.mjs";
+import { a as EmbedMode, c as ExportFormatMap, i as EmbedEventName, n as EmbedEventHandler, o as ExportCallOptions, r as EmbedEventMap, s as ExportFormat } from "./protocol-BPuwbNCz.mjs";
+import { a as ManualActorOptions, i as InspectorEvents, n as CreateInspectorOptions, o as createStatelyInspector, r as Inspector, s as Transport, t as AdoptedActor } from "./inspect-ttRIjoCu.mjs";
 export { AdoptedActor, CreateInspectorOptions, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, Inspector, InspectorEvents, ManualActorOptions, Transport, createStatelyInspector };

package/dist/inspect.mjs

@@ -1,4 +1,4 @@
-import { i as createPendingExportManager, n as createWebSocketTransport, r as createEventRegistry } from "./transport-lomH7b0v.mjs";
+import { i as createPendingExportManager, n as createWebSocketTransport, r as createEventRegistry } from "./transport-DoCHBLTu.mjs";
 
 //#region src/inspect.ts
 const defaultSerializeSnapshot = (snapshot) => ({

package/dist/patchTypes.d.mts

@@ -8,6 +8,7 @@ type ActionLocation = {
   edgeId: string;
   group: 'transition';
 };
+type ImplementationSourceType = 'action' | 'guard' | 'actor' | 'delay';
 type GraphPatch = {
   op: 'createNode';
   description?: string;
@@ -163,6 +164,29 @@ type GraphPatch = {
   description?: string;
   nodeId: string;
   invokeId: string;
+} | {
+  op: 'createImplementation';
+  description?: string;
+  sourceType: ImplementationSourceType;
+  implementation: {
+    id: string;
+    name?: string;
+    code?: string;
+  };
+} | {
+  op: 'updateImplementation';
+  description?: string;
+  sourceType: ImplementationSourceType;
+  implementationId: string;
+  data: {
+    name?: string;
+    code?: string;
+  };
+} | {
+  op: 'deleteImplementation';
+  description?: string;
+  sourceType: ImplementationSourceType;
+  implementationId: string;
 } | {
   op: 'setGuard';
   description?: string;
@@ -222,4 +246,4 @@ type GraphPatch = {
   };
 };
 //#endregion
-export { ActionLocation, CanvasColor, EditorStateType, GraphPatch };
+export { ActionLocation, CanvasColor, EditorStateType, GraphPatch, ImplementationSourceType };

package/dist/{protocol-B1cNV7QB.d.mts → protocol-BPuwbNCz.d.mts}

@@ -62,6 +62,10 @@ interface ExportFormatMap {
     };
     result: Record<string, unknown>;
   };
+  xgraph: {
+    options: object;
+    result: Record<string, unknown>;
+  };
   digraph: {
     options: object;
     result: Record<string, unknown>;

package/dist/sync.mjs

@@ -1,6 +1,6 @@
 import { createStatelyClient } from "./studio.mjs";
 import { fromStudioMachine, toStudioMachine } from "./graph.mjs";
-import { t as graphToXStateTS } from "./graphToXStateTS-BSUj97r0.mjs";
+import { t as graphToXStateTS } from "./graphToXStateTS-CtecEESq.mjs";
 import { getDiff, isEmptyDiff } from "@statelyai/graph";
 import fs from "node:fs/promises";
 import path from "node:path";

package/dist/{transport-lomH7b0v.mjs → transport-DoCHBLTu.mjs}

@@ -1,5 +1,9 @@
 //#region src/clientUtils.ts
-const jsonResultFormats = new Set(["digraph", "json"]);
+const jsonResultFormats = new Set([
+	"digraph",
+	"json",
+	"xgraph"
+]);
 function createRequestId() {
 	const cryptoObject = globalThis.crypto;
 	if (cryptoObject?.randomUUID) return cryptoObject.randomUUID();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/sdk",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "license": "MIT",
   "files": [
     "dist"
@@ -63,8 +63,7 @@
     "@types/json-schema": "^7.0.15",
     "jsdom": "^27.4.0",
     "tsdown": "0.21.0-beta.2",
-    "vitest": "^3.2.4",
-    "@statelyai/editor-sync": "0.0.0"
+    "vitest": "^3.2.4"
   },
   "scripts": {
     "build": "tsdown",