@statelyai/sdk 0.20.3 → 0.22.0

package/README.md

@@ -37,6 +37,7 @@ embed.init({
   format: 'xstate',
   mode: 'editing',
   theme: 'dark',
+  settings: { canvas: { viewMode: 'list' } },
   documents: [
     { path: 'README.md', content: '# How this workflow works' },
     { path: 'src/machine.ts', content: machineSource },
@@ -44,6 +45,16 @@ embed.init({
 });
 ```
 
+Use `viewMode: 'list'` on `createStatelyEmbed` to add `?view=list` to the
+iframe URL, or subscribe to `viewModeChanged` when the user switches views.
+
+Custom profiles and formats can be supplied when the embed is created. Their
+serializable manifests are sent to the iframe; detector, importer, exporter,
+and validator implementations remain in the host and are called asynchronously.
+RPC methods and payloads are validated before host code runs, and malformed
+graphs returned by custom importers are rejected.
+Use `defaultProfile` and `defaultFormat` to choose the initial custom pair.
+
 Restrict an embed by passing a resolved access policy:
 
 <!-- restricted MachineInitOptions from src/protocol.ts -->

package/dist/{editorHostSession-CCTwvUOB.mjs → editorHostSession-HRuIaZ2G.mjs}

@@ -1,5 +1,5 @@
-import { t as EDITOR_PROTOCOL_VERSION } from "./editorHostProtocol-D_h4y3rX.mjs";
-import { c as object, f as unknown, i as custom, l as record, n as array, o as literal, r as boolean, s as number, t as _enum, u as string } from "./schemas-b9wG-zYl.mjs";
+import { c as object, f as unknown, i as custom, l as record, n as array, o as literal, r as boolean, s as number, t as _enum, u as string } from "./openapi-BTDjYWXd.mjs";
+import { t as EDITOR_PROTOCOL_VERSION } from "./editorHostProtocol-Bko7wge8.mjs";
 
 //#region ../api-contract/dist/editor-sync.mjs
 const EDITOR_SYNC_PROTOCOL_VERSION = 1;

package/dist/editorHostSession.mjs

@@ -1,4 +1,5 @@
-import { t as EDITOR_PROTOCOL_VERSION } from "./editorHostProtocol-D_h4y3rX.mjs";
-import { n as createRemoteEditorSyncBackend, r as fetchEditorSyncAccess, t as EditorHostSession } from "./editorHostSession-CCTwvUOB.mjs";
+import "./openapi-BTDjYWXd.mjs";
+import { t as EDITOR_PROTOCOL_VERSION } from "./editorHostProtocol-Bko7wge8.mjs";
+import { n as createRemoteEditorSyncBackend, r as fetchEditorSyncAccess, t as EditorHostSession } from "./editorHostSession-HRuIaZ2G.mjs";
 
 export { EDITOR_PROTOCOL_VERSION, EditorHostSession, createRemoteEditorSyncBackend, fetchEditorSyncAccess };

package/dist/embed.d.mts

@@ -1,5 +1,6 @@
-import { i as StatelyGraph } from "./graph-yDK-MM3G.mjs";
-import { CapabilityDeniedEvent, CommentsConfig, EditorCapabilities, EmbedDocument, EmbedDocumentLanguage, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InitOptions, MachineInitOptions, MachineSourceLocations, ProjectEmbedMachine, UploadResult } from "./protocol.mjs";
+import { i as ProfileManifest } from "./index-Bakx1tkW.mjs";
+import { i as StatelyGraph } from "./graph-DYjfFztq.mjs";
+import { CapabilityDeniedEvent, CommentsConfig, EditorCapabilities, EmbedDocument, EmbedDocumentLanguage, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedExtensionsManifest, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InitOptions, MachineInitOptions, MachineSourceLocations, ProjectEmbedMachine, UploadResult } from "./protocol.mjs";
 import { AssetUploadAdapter } from "./assetStorage.mjs";
 
 //#region src/embed.d.ts
@@ -29,9 +30,50 @@ interface AssetConfig {
    */
   maxFileSize?: number;
 }
+type EmbedEntity = {
+  data?: Record<string, unknown>;
+};
+type EmbedGraph = EmbedEntity & {
+  nodes?: EmbedEntity[];
+  edges?: EmbedEntity[];
+};
+type EmbedFormatContext = {
+  profile: EmbedProfileDefinition;
+  resolveGraphData(graph: EmbedGraph): Record<string, unknown>;
+  resolveNodeData(node: EmbedEntity): Record<string, unknown>;
+  resolveEdgeData(edge: EmbedEntity): Record<string, unknown>;
+};
+type EmbedProfileDefinition = Omit<ProfileManifest, 'validation'> & {
+  validation?: Array<{
+    name: string;
+    description: string;
+    validate?(context: {
+      graph: EmbedGraph;
+      profile: ProfileManifest;
+      revision?: number;
+      resolveGraphData(graph: EmbedGraph): Record<string, unknown>;
+      resolveNodeData(node: EmbedEntity): Record<string, unknown>;
+      resolveEdgeData(edge: EmbedEntity): Record<string, unknown>;
+    }): unknown | Promise<unknown>;
+  }>;
+};
+type EmbedFormatDefinition = {
+  id: string;
+  name: string;
+  file?: {
+    extension?: string;
+    mediaType?: string;
+  };
+  editorLanguage?: string;
+  detect?(source: string): boolean | number | Promise<boolean | number>;
+  import?(source: string, context: EmbedFormatContext): unknown | Promise<unknown>;
+  export?(graph: EmbedGraph, context: EmbedFormatContext): unknown | Promise<unknown>;
+};
 interface StatelyEmbedOptions extends Partial<MachineInitOptions> {
   baseUrl: string;
   apiKey?: string;
+  /** Initial canvas view. Also reflected in the iframe URL as `?view=`. */
+  viewMode?: 'graph' | 'list';
   origin?: string;
   /**
    * Optional iframe to attach to immediately. Equivalent to calling
@@ -49,10 +91,15 @@ interface StatelyEmbedOptions extends Partial<MachineInitOptions> {
   commentsByMachineId?: Record<string, CommentsConfig>;
   /** Asset upload configuration. If omitted, files are stored as base64 data URLs. */
   assets?: AssetConfig;
+  profiles?: readonly EmbedProfileDefinition[];
+  formats?: readonly EmbedFormatDefinition[];
+  defaultProfile?: string;
+  defaultFormat?: string;
   onReady?: () => void;
   onLoaded?: (graph: StatelyGraph) => void;
   onChange?: (graph: StatelyGraph, machineConfig: unknown) => void;
   onSave?: (graph: StatelyGraph, machineConfig: unknown) => void;
+  onViewModeChanged?: (viewMode: 'graph' | 'list') => void;
   onError?: (error: {
     code: string;
     message: string;
@@ -91,4 +138,4 @@ interface StatelyEmbed {
 }
 declare function createStatelyEmbed(options: StatelyEmbedOptions): StatelyEmbed;
 //#endregion
-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 };
+export { AssetConfig, type CapabilityDeniedEvent, type CommentsConfig, type EditorCapabilities, type EmbedDocument, type EmbedDocumentLanguage, EmbedEntity, type EmbedEventHandler, type EmbedEventMap, type EmbedEventName, type EmbedExtensionsManifest, EmbedFormatContext, EmbedFormatDefinition, EmbedGraph, type EmbedMode, EmbedProfileDefinition, type ExportCallOptions, type ExportFormat, type ExportFormatMap, type InitOptions, type MachineInitOptions, type MachineSourceLocations, type ProjectEmbedMachine, StatelyEmbed, StatelyEmbedOptions, type UploadResult, createStatelyEmbed };

package/dist/embed.mjs

@@ -1,13 +1,74 @@
-import { a as createEventRegistry, o as createPendingExportManager, r as createPostMessageTransport, s as toInitMessage, t as SDK_VERSION } from "./version-DoNMw8g6.mjs";
-import { t as EDITOR_PROTOCOL_VERSION } from "./editorHostProtocol-D_h4y3rX.mjs";
+import { a as createEventRegistry, o as createPendingExportManager, r as createPostMessageTransport, s as toInitMessage, t as SDK_VERSION } from "./version-3cKMfysA.mjs";
+import { t as EDITOR_PROTOCOL_VERSION } from "./editorHostProtocol-Bko7wge8.mjs";
 
 //#region src/embed.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isEmbedEntity(value) {
+	return isRecord(value) && isRecord(value.data);
+}
+function isEmbedGraph(value) {
+	return isRecord(value) && isRecord(value.data) && Array.isArray(value.nodes) && value.nodes.every(isEmbedEntity) && Array.isArray(value.edges) && value.edges.every(isEmbedEntity);
+}
+function assertExtensionCall(value) {
+	if (!isRecord(value)) throw new Error("Invalid extension request.");
+	if (typeof value.requestId !== "string" || typeof value.extensionId !== "string" || ![
+		"detect",
+		"import",
+		"export",
+		"validate"
+	].includes(String(value.method)) || !isRecord(value.payload)) throw new Error("Invalid extension request.");
+	const payload = value.payload;
+	if ((value.method === "detect" || value.method === "import") && typeof payload.source !== "string") throw new Error("Invalid extension source payload.");
+	if ((value.method === "import" || value.method === "export") && typeof payload.profileId !== "string") throw new Error("Invalid extension profile payload.");
+	if ((value.method === "export" || value.method === "validate") && !isEmbedGraph(payload.graph)) throw new Error("Invalid extension graph payload.");
+	if (value.method === "validate" && payload.revision !== void 0 && typeof payload.revision !== "number") throw new Error("Invalid extension revision payload.");
+}
 function buildEmbedUrl(options) {
 	const base = options.baseUrl.replace(/\/+$/, "") + "/embed";
 	const url = new URL(base);
 	if (options.apiKey) url.searchParams.set("api_key", options.apiKey);
+	if (options.viewMode) url.searchParams.set("view", options.viewMode);
 	return url.toString();
 }
+function serializeExtensions(options) {
+	if (!options.profiles?.length && !options.formats?.length) return options.extensions;
+	return {
+		profiles: (options.profiles ?? []).map((profile) => ({
+			profile: profile.profile,
+			name: profile.name,
+			description: profile.description,
+			namespace: profile.namespace,
+			extends: profile.extends,
+			formats: profile.formats,
+			defaultFormat: profile.defaultFormat,
+			graph: profile.graph,
+			authoring: profile.authoring,
+			operations: profile.operations,
+			restrictFormatsToListed: profile.restrictFormatsToListed,
+			features: profile.features,
+			implementations: profile.implementations,
+			rules: profile.rules,
+			editorDefaults: profile.editorDefaults,
+			validation: profile.validation?.map(({ name, description }) => ({
+				name,
+				description
+			}))
+		})),
+		formats: (options.formats ?? []).map((format) => ({
+			id: format.id,
+			name: format.name,
+			file: format.file,
+			editorLanguage: format.editorLanguage,
+			detect: !!format.detect,
+			import: !!format.import,
+			export: !!format.export
+		})),
+		defaultProfile: options.defaultProfile,
+		defaultFormat: options.defaultFormat
+	};
+}
 function extractInitOptions(options) {
 	if (options.machines) return {
 		machines: options.machines,
@@ -20,12 +81,14 @@ function extractInitOptions(options) {
 		capabilities: options.capabilities,
 		panels: options.panels,
 		commentsByMachineId: options.commentsByMachineId,
+		settings: options.settings,
 		unsavedIndicator: options.unsavedIndicator
 	};
 	if (options.machine !== void 0) return {
 		machine: options.machine,
 		documents: options.documents,
 		format: options.format,
+		extensions: serializeExtensions(options),
 		mode: options.mode,
 		theme: options.theme,
 		readOnly: options.readOnly,
@@ -35,13 +98,14 @@ function extractInitOptions(options) {
 		panels: options.panels,
 		comments: options.comments,
 		sourceLocations: options.sourceLocations,
+		settings: options.settings,
 		unsavedIndicator: options.unsavedIndicator
 	};
 	return null;
 }
 function createStatelyEmbed(options) {
 	const embedUrl = buildEmbedUrl(options);
-	const targetOrigin = options.origin ?? "*";
+	const targetOrigin = options.origin ?? new URL(embedUrl).origin;
 	let iframe = null;
 	let transport = null;
 	let ownedIframe = false;
@@ -49,6 +113,9 @@ function createStatelyEmbed(options) {
 	let editorProtocolCompatible;
 	const pendingMessages = [];
 	const events = createEventRegistry();
+	const profiles = new Map((options.profiles ?? []).map((profile) => [profile.profile, profile]));
+	const formats = new Map((options.formats ?? []).map((format) => [format.id, format]));
+	const bundledExtensions = serializeExtensions(options);
 	const exportManager = createPendingExportManager((message) => send(message));
 	const assetUploadAdapter = options.assets?.adapter;
 	const uploadAsset = options.assets?.onUploadRequest ? (file, context) => options.assets.onUploadRequest(file, context) : assetUploadAdapter ? (file, context) => assetUploadAdapter.upload({
@@ -72,9 +139,73 @@ function createStatelyEmbed(options) {
 			transport.send(msg);
 		}
 	}
+	function formatContext(profile) {
+		const namespace = profile.namespace ?? /^(@[^/]+)\//.exec(profile.profile)?.[1];
+		if (!namespace) throw new Error(`Profile ${profile.profile} has no namespace.`);
+		const resolve = (data) => Object.fromEntries(Object.entries(data).filter(([key]) => key.startsWith(`${namespace}.`)).map(([key, value]) => [key.slice(namespace.length + 1), value]));
+		return {
+			profile,
+			resolveGraphData: (graph) => resolve(graph.data ?? {}),
+			resolveNodeData: (node) => resolve(node.data ?? {}),
+			resolveEdgeData: (edge) => resolve(edge.data ?? {})
+		};
+	}
+	async function handleExtensionCall(input) {
+		const requestId = isRecord(input) && typeof input.requestId === "string" ? input.requestId : void 0;
+		try {
+			assertExtensionCall(input);
+			const call = input;
+			const payload = call.payload;
+			let result;
+			if (call.method === "validate") {
+				const profile = profiles.get(call.extensionId);
+				if (!profile) throw new Error(`Unknown profile ${call.extensionId}.`);
+				const context = formatContext(profile);
+				result = (await Promise.all((profile.validation ?? []).filter((validator) => validator.validate).map((validator) => validator.validate({
+					graph: payload.graph,
+					revision: typeof payload.revision === "number" ? payload.revision : void 0,
+					...context
+				})))).flat();
+			} else {
+				const format = formats.get(call.extensionId);
+				if (!format) throw new Error(`Unknown format ${call.extensionId}.`);
+				if (call.method === "detect") {
+					if (!format.detect) throw new Error("Format has no detector.");
+					result = await format.detect(String(payload.source ?? ""));
+				} else {
+					const profile = profiles.get(String(payload.profileId ?? ""));
+					if (!profile) throw new Error(`Unknown profile ${payload.profileId}.`);
+					const context = formatContext(profile);
+					if (call.method === "import") {
+						if (!format.import) throw new Error("Format has no importer.");
+						result = await format.import(payload.source, context);
+						if (!isEmbedGraph(result)) throw new Error("Format importer returned an invalid graph.");
+					} else {
+						if (!format.export) throw new Error("Format has no exporter.");
+						result = await format.export(payload.graph, context);
+					}
+				}
+			}
+			send({
+				type: "@statelyai.extension.result",
+				requestId: call.requestId,
+				result
+			});
+		} catch (error) {
+			if (!requestId) return;
+			send({
+				type: "@statelyai.extension.result",
+				requestId,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
 	function handleMessage(data) {
 		if (destroyed) return;
 		switch (data.type) {
+			case "@statelyai.extension.call":
+				handleExtensionCall(data);
+				break;
 			case "@statelyai.ready": {
 				const ready = data;
 				if (ready.protocolVersion !== void 0) {
@@ -147,6 +278,15 @@ function createStatelyEmbed(options) {
 			case "@statelyai.project.machineSelected":
 				events.emit("machineSelected", { machineId: String(data.machineId) });
 				break;
+			case "@statelyai.viewModeChanged": {
+				const viewMode = data;
+				options.onViewModeChanged?.(viewMode.viewMode);
+				events.emit("viewModeChanged", {
+					viewMode: viewMode.viewMode,
+					machineId: viewMode.machineId
+				});
+				break;
+			}
 			case "@statelyai.retrieved": {
 				const retrieved = data;
 				exportManager.resolve(retrieved.requestId, retrieved.data);
@@ -257,7 +397,10 @@ function createStatelyEmbed(options) {
 			return el;
 		},
 		init(opts) {
-			send(toInitMessage(opts));
+			send(toInitMessage("machine" in opts ? {
+				...opts,
+				extensions: opts.extensions ?? bundledExtensions
+			} : opts));
 		},
 		updateMachine(machine, format, sourceLocations) {
 			send({

package/dist/{graph-yDK-MM3G.d.mts → graph-DYjfFztq.d.mts}

@@ -1,4 +1,4 @@
-import { r as CodeExpression } from "./index-BAkQThnl.mjs";
+import { t as CodeExpression } from "./index-Bakx1tkW.mjs";
 import * as _statelyai_graph0 from "@statelyai/graph";
 import { Graph } from "@statelyai/graph";
 

package/dist/graph.d.mts

@@ -1,2 +1,2 @@
-import { _ as studioMachineConverter, a as StatelyGraphData, c as StatelyInvoke, d as StudioAction, f as StudioEdge, g as fromStudioMachine, h as StudioNode, i as StatelyGraph, l as StatelyNodeData, m as StudioMachine, n as StatelyActorImplementation, o as StatelyGuard, p as StudioEventTypeData, r as StatelyEdgeData, s as StatelyImplementation, t as StatelyAction, u as StatelyTagImplementation, v as toStudioMachine } from "./graph-yDK-MM3G.mjs";
+import { _ as studioMachineConverter, a as StatelyGraphData, c as StatelyInvoke, d as StudioAction, f as StudioEdge, g as fromStudioMachine, h as StudioNode, i as StatelyGraph, l as StatelyNodeData, m as StudioMachine, n as StatelyActorImplementation, o as StatelyGuard, p as StudioEventTypeData, r as StatelyEdgeData, s as StatelyImplementation, t as StatelyAction, u as StatelyTagImplementation, v as toStudioMachine } from "./graph-DYjfFztq.mjs";
 export { StatelyAction, StatelyActorImplementation, StatelyEdgeData, StatelyGraph, StatelyGraphData, StatelyGuard, StatelyImplementation, StatelyInvoke, StatelyNodeData, StatelyTagImplementation, StudioAction, StudioEdge, StudioEventTypeData, StudioMachine, StudioNode, fromStudioMachine, studioMachineConverter, toStudioMachine };