@statelyai/sdk 0.4.0 → 0.5.0

package/dist/patchTypes.d.mts

@@ -0,0 +1,225 @@
+//#region src/patchTypes.d.ts
+type EditorStateType = 'normal' | 'parallel' | 'history' | 'final' | null;
+type CanvasColor = 'green' | 'red' | 'purple' | 'blue' | 'orange' | 'yellow' | 'pink' | 'teal';
+type ActionLocation = {
+  nodeId: string;
+  group: 'entry' | 'exit';
+} | {
+  edgeId: string;
+  group: 'transition';
+};
+type GraphPatch = {
+  op: 'createNode';
+  description?: string;
+  id?: string;
+  parentId: string;
+  key: string;
+  type?: EditorStateType;
+  x?: number;
+  y?: number;
+} | {
+  op: 'updateNode';
+  description?: string;
+  nodeId: string;
+  data: {
+    key?: string;
+    type?: EditorStateType;
+    description?: string;
+    initialId?: string | null;
+  };
+} | {
+  op: 'deleteNode';
+  description?: string;
+  nodeId: string;
+} | {
+  op: 'createEdge';
+  description?: string;
+  id?: string;
+  sourceId: string;
+  targetId: string;
+  eventType: string;
+  transitionType?: 'normal' | 'targetless' | 'reenter';
+} | {
+  op: 'updateEdge';
+  description?: string;
+  edgeId: string;
+  data: {
+    sourceId?: string;
+    targetId?: string;
+    eventType?: string;
+    transitionType?: 'normal' | 'targetless' | 'reenter';
+    description?: string | null;
+  };
+} | {
+  op: 'deleteEdge';
+  description?: string;
+  edgeId: string;
+} | {
+  op: 'createState';
+  description?: string;
+  id?: string;
+  parentId: string;
+  key: string;
+  type?: EditorStateType;
+  x?: number;
+  y?: number;
+  color?: CanvasColor | null;
+  initial?: boolean;
+} | {
+  op: 'updateState';
+  description?: string;
+  stateId: string;
+  key?: string;
+  type?: EditorStateType;
+  stateDescription?: string;
+  initialId?: string | null;
+  color?: CanvasColor | null;
+  meta?: Record<string, unknown> | null;
+  history?: 'shallow' | 'deep' | null;
+} | {
+  op: 'deleteState';
+  description?: string;
+  stateId: string;
+} | {
+  op: 'createTransition';
+  description?: string;
+  id?: string;
+  sourceId: string;
+  targetId: string;
+  eventType: string;
+  transitionType?: 'normal' | 'targetless' | 'reenter';
+  guard?: {
+    type: string;
+    code?: string;
+    params?: Record<string, unknown>;
+  };
+  color?: CanvasColor | null;
+  transitionDescription?: string | null;
+} | {
+  op: 'updateTransition';
+  description?: string;
+  transitionId: string;
+  sourceId?: string;
+  targetId?: string;
+  eventType?: string;
+  transitionType?: 'normal' | 'targetless' | 'reenter';
+  transitionDescription?: string | null;
+  color?: CanvasColor | null;
+  meta?: Record<string, unknown> | null;
+} | {
+  op: 'deleteTransition';
+  description?: string;
+  transitionId: string;
+} | {
+  op: 'createAction';
+  description?: string;
+  location: ActionLocation;
+  action: {
+    id?: string;
+    type: string;
+    params?: Record<string, unknown>;
+    code?: string;
+  };
+  index?: number;
+} | {
+  op: 'updateAction';
+  description?: string;
+  location: ActionLocation;
+  actionId: string;
+  data: {
+    type?: string;
+    params?: Record<string, unknown>;
+    code?: string;
+  };
+} | {
+  op: 'deleteAction';
+  description?: string;
+  location: ActionLocation;
+  actionId: string;
+} | {
+  op: 'createInvoke';
+  description?: string;
+  nodeId: string;
+  invoke: {
+    id?: string;
+    src: string;
+    code?: string;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+  };
+} | {
+  op: 'updateInvoke';
+  description?: string;
+  nodeId: string;
+  invokeId: string;
+  data: {
+    src?: string;
+    code?: string;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+  };
+} | {
+  op: 'deleteInvoke';
+  description?: string;
+  nodeId: string;
+  invokeId: string;
+} | {
+  op: 'setGuard';
+  description?: string;
+  edgeId: string;
+  guard: {
+    type: string;
+    code?: string;
+    params?: Record<string, unknown>;
+  };
+} | {
+  op: 'deleteGuard';
+  description?: string;
+  edgeId: string;
+} | {
+  op: 'createTag';
+  description?: string;
+  nodeId: string;
+  tag: {
+    name: string;
+  };
+} | {
+  op: 'deleteTag';
+  description?: string;
+  nodeId: string;
+  tagName: string;
+} | {
+  op: 'createAnnotation';
+  description?: string;
+  id?: string;
+  parentId: string | null;
+  content: string;
+  x?: number;
+  y?: number;
+} | {
+  op: 'updateAnnotation';
+  description?: string;
+  annotationId: string;
+  data: {
+    content?: string;
+  };
+} | {
+  op: 'deleteAnnotation';
+  description?: string;
+  annotationId: string;
+} | {
+  op: 'setContext';
+  description?: string;
+  context: Record<string, unknown>;
+} | {
+  op: 'updateSchemas';
+  description?: string;
+  schemas: {
+    context?: Record<string, unknown> | null;
+    events?: Record<string, unknown> | null;
+    input?: unknown | null;
+    output?: unknown | null;
+  };
+};
+//#endregion
+export { ActionLocation, CanvasColor, EditorStateType, GraphPatch };

package/dist/patchTypes.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/protocol-B1cNV7QB.d.mts

@@ -0,0 +1,397 @@
+//#region src/protocol.d.ts
+type EmbedMode = 'editing' | 'viewing' | 'simulating' | 'inspecting';
+interface CommentsConfig {
+  roomId: string;
+  userId?: string | null;
+  publicApiKey?: string;
+  authEndpoint?: string;
+  baseUrl?: string;
+}
+interface ValidationIssue {
+  nodeIds: string[];
+  edgeIds: string[];
+  level: 'info' | 'warning' | 'error';
+  message: string;
+}
+interface SourceRange {
+  startLine: number;
+  startChar: number;
+  endLine: number;
+  endChar: number;
+}
+interface SourceLocation {
+  uri: string;
+  range: SourceRange;
+}
+interface StateSourceLocation extends SourceLocation {
+  path: string[];
+  kind: 'inline' | 'objectReference' | 'createStateConfig';
+  symbol?: string;
+  keyRange?: SourceRange;
+  referenceRange?: SourceRange;
+  keySource?: {
+    kind: 'const' | 'enumMember' | 'computedLiteral';
+    symbol?: string;
+    valueRange?: SourceRange;
+    machineLocal?: boolean;
+  };
+  keyReplacementText?: string;
+}
+interface MachineSourceLocations {
+  version: 1;
+  root?: SourceLocation;
+  states: StateSourceLocation[];
+  staticValues?: Array<SourceLocation & {
+    value: string;
+  }>;
+}
+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: object;
+    result: Record<string, unknown>;
+  };
+  mermaid: {
+    options: object;
+    result: string;
+  };
+  rtk: {
+    options: object;
+    result: string;
+  };
+  zustand: {
+    options: object;
+    result: string;
+  };
+  'asl-json': {
+    options: object;
+    result: string;
+  };
+  'asl-yaml': {
+    options: object;
+    result: string;
+  };
+  scxml: {
+    options: object;
+    result: string;
+  };
+}
+type ExportFormat = keyof ExportFormatMap;
+type ExportCallOptions<F extends ExportFormat> = ExportFormatMap[F]['options'] & {
+  timeout?: number;
+};
+interface EmbedEventMap {
+  ready: {
+    version: string;
+  };
+  loaded: {
+    graph: unknown;
+    sourceLocations?: MachineSourceLocations;
+  };
+  change: {
+    graph: unknown;
+    machineConfig: unknown;
+    patches?: unknown[];
+    sourceLocations?: MachineSourceLocations;
+  };
+  save: {
+    graph: unknown;
+    machineConfig: unknown;
+    patches?: unknown[];
+    validations?: ValidationIssue[];
+    sourceLocations?: MachineSourceLocations;
+  };
+  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[];
+  };
+  comments?: CommentsConfig;
+  sourceLocations?: MachineSourceLocations;
+  /**
+   * Show a persistent "Save to apply" pill in the embed whenever Viz has
+   * local edits that have not yet been saved. Intended for contexts like
+   * editor extensions where Viz edits don't reach the source until the user
+   * saves.
+   *
+   * - `enabled` — whether to show the pill at all. Defaults to `false`.
+   * - `mode` — `'structural'` (default) only triggers on graph-structural
+   *   changes (state/transition/action/invoke/schema edits). Pure visual
+   *   changes like drag-to-position, color, and autolayout are ignored.
+   *   `'all'` triggers on any graph change.
+   */
+  unsavedIndicator?: {
+    enabled?: boolean;
+    mode?: 'structural' | 'all';
+  };
+}
+interface InitMessage {
+  type: '@statelyai.init';
+  machine: unknown;
+  format?: string;
+  mode?: EmbedMode;
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+  depth?: number;
+  leftPanels?: string[];
+  rightPanels?: string[];
+  activePanels?: string[];
+  comments?: CommentsConfig;
+  sourceLocations?: MachineSourceLocations;
+  /** Mirror of `InitOptions.unsavedIndicator`. */
+  unsavedIndicator?: {
+    enabled?: boolean;
+    mode?: 'structural' | 'all';
+  };
+  /** Optional session id override (multiplexed clients only). */
+  sessionId?: string;
+}
+interface UpdateMessage {
+  type: '@statelyai.update';
+  machine: unknown;
+  format?: string;
+  sourceLocations?: MachineSourceLocations;
+}
+interface SetModeMessage {
+  type: '@statelyai.setMode';
+  mode: EmbedMode;
+}
+interface SetThemeMessage {
+  type: '@statelyai.setTheme';
+  theme: 'light' | 'dark';
+}
+interface SetSettingsMessage {
+  type: '@statelyai.setSettings';
+  settings: Record<string, unknown>;
+}
+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;
+  /**
+   * Optional session id override. Used by multiplexed clients that share one
+   * WebSocket across many actor sessions. When omitted, the relay routes
+   * to the connection's primary sessionId.
+   */
+  sessionId?: string;
+}
+interface ActorSystemEntry {
+  /** The xstate `actor.sessionId` — unique within the system. */
+  actorId: string;
+  /** Parent actor's sessionId, or `null` for the root. */
+  parentActorId: string | null;
+  /** Human-facing id (`actor.id`). */
+  id: string;
+  /** Machine configuration used to render the state chart. */
+  machine: unknown;
+  /** Optional current snapshot (`{value, status, ...}`). */
+  snapshot?: unknown;
+}
+interface SystemInitMessage {
+  type: '@statelyai.system.init';
+  /** All known actors at the moment the system is first streamed. */
+  actors: ActorSystemEntry[];
+  /** Actor id the viz should focus first. Defaults to the root. */
+  selectedActorId?: string;
+  mode?: EmbedMode;
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+  depth?: number;
+  leftPanels?: string[];
+  rightPanels?: string[];
+  activePanels?: string[];
+  comments?: CommentsConfig;
+}
+/** A new actor joined the system after init. */
+interface SystemActorRegisteredMessage {
+  type: '@statelyai.system.actorRegistered';
+  actorId: string;
+  parentActorId: string | null;
+  id: string;
+  machine: unknown;
+  snapshot?: unknown;
+}
+/** An actor's snapshot updated. */
+interface SystemActorSnapshotMessage {
+  type: '@statelyai.system.actorSnapshot';
+  actorId: string;
+  snapshot: unknown;
+  event?: unknown | null;
+  /** The actorId of the actor that sent the triggering event, if known. */
+  sourceActorId?: string | null;
+}
+/** An actor reached a final state / was stopped. */
+interface SystemActorStoppedMessage {
+  type: '@statelyai.system.actorStopped';
+  actorId: string;
+}
+interface ReadyMessage {
+  type: '@statelyai.ready';
+  version: string;
+}
+interface LoadedMessage {
+  type: '@statelyai.loaded';
+  graph: unknown;
+  sourceLocations?: MachineSourceLocations;
+}
+interface ChangeMessage {
+  type: '@statelyai.change';
+  graph: unknown;
+  machineConfig: unknown;
+  patches?: unknown[];
+  sourceLocations?: MachineSourceLocations;
+}
+interface SaveMessage {
+  type: '@statelyai.save';
+  graph: unknown;
+  machineConfig: unknown;
+  patches?: unknown[];
+  validations?: ValidationIssue[];
+  sourceLocations?: MachineSourceLocations;
+}
+interface RetrievedMessage {
+  type: '@statelyai.retrieved';
+  requestId: string;
+  data: unknown;
+}
+interface ErrorMessage {
+  type: '@statelyai.error';
+  code: string;
+  message: string;
+  requestId?: string;
+}
+/** File metadata sent from viz to SDK when a file needs uploading. */
+interface UploadFileInfo {
+  /** Original filename (e.g. "screenshot.png") */
+  name: string;
+  /** MIME type (e.g. "image/png") */
+  mimeType: string;
+  /** File size in bytes */
+  size: number;
+  /** File content as base64-encoded string */
+  data: string;
+}
+/** The result the consumer returns after uploading. */
+interface UploadResult {
+  /** The publicly accessible URL of the uploaded file */
+  url: string;
+  /** Optional display name (defaults to original filename) */
+  name?: string;
+  /** Optional metadata stored on the asset */
+  metadata?: Record<string, unknown>;
+}
+/** Viz requests the parent to upload a file. */
+interface UploadRequestMessage {
+  type: '@statelyai.uploadRequest';
+  requestId: string;
+  file: UploadFileInfo;
+  stateNodeId: string;
+}
+/** Parent tells the viz the upload capabilities on init. */
+interface UploadCapabilitiesMessage {
+  type: '@statelyai.uploadCapabilities';
+  enabled: boolean;
+  accept?: string[];
+  maxFileSize?: number;
+}
+/** Parent sends the upload result back to the viz. */
+interface UploadResponseMessage {
+  type: '@statelyai.uploadResponse';
+  requestId: string;
+  result: UploadResult;
+}
+/** All messages a client (embed/inspector) can send to the viz. */
+type ClientMessage = InitMessage | UpdateMessage | SetModeMessage | SetThemeMessage | SetSettingsMessage | RetrieveMessage | ToastMessage | InspectSnapshotMessage | SystemInitMessage | SystemActorRegisteredMessage | SystemActorSnapshotMessage | SystemActorStoppedMessage | UploadCapabilitiesMessage | UploadResponseMessage | ErrorMessage;
+/** All messages the viz can send back to a client. */
+type VizMessage = ReadyMessage | LoadedMessage | ChangeMessage | SaveMessage | RetrievedMessage | ErrorMessage | UploadRequestMessage;
+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;
+}
+/**
+ * Client → relay: add another sessionId to an existing connection. Used by
+ * multiplexed clients that want one WebSocket to serve many actor sessions.
+ * Order of operations for a multiplexed client:
+ *
+ *   1. Connect WebSocket
+ *   2. Send `@statelyai.register { sessionId: primary }`
+ *   3. Send `@statelyai.addSession { sessionId }` for each additional session
+ *   4. Send regular messages; each can include an explicit `sessionId` at
+ *      the root to target a specific session (falls back to primary).
+ */
+interface AddSessionMessage {
+  type: '@statelyai.addSession';
+  sessionId: string;
+  metadata?: {
+    name?: string;
+    machineId?: string;
+  };
+}
+/** Relay → client: acknowledgement that a session was added. */
+interface SessionAddedMessage {
+  type: '@statelyai.sessionAdded';
+  sessionId: string;
+}
+/** All session-management messages for the WS relay. */
+type SessionMessage = RegisterMessage | RegisteredMessage | RequestOpenMessage | AddSessionMessage | SessionAddedMessage;
+/** Any valid protocol message. */
+type ProtocolMessage = ClientMessage | VizMessage | SessionMessage;
+//#endregion
+export { EmbedMode as a, ExportFormatMap as c, ProtocolMessage as d, UploadResult as f, EmbedEventName as i, InitOptions as l, EmbedEventHandler as n, ExportCallOptions as o, EmbedEventMap as r, ExportFormat as s, CommentsConfig as t, MachineSourceLocations as u };

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-C6HQUrBB.mjs";
+import { t as graphToXStateTS } from "./graphToXStateTS-BSUj97r0.mjs";
 import { getDiff, isEmptyDiff } from "@statelyai/graph";
 import fs from "node:fs/promises";
 import path from "node:path";

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

@@ -96,7 +96,9 @@ function toInitMessage(options) {
 		leftPanels: options.panels?.leftPanels,
 		rightPanels: options.panels?.rightPanels,
 		activePanels: options.panels?.activePanels,
-		comments: options.comments
+		comments: options.comments,
+		sourceLocations: options.sourceLocations,
+		unsavedIndicator: options.unsavedIndicator
 	};
 }
 
@@ -114,9 +116,11 @@ function createPostMessageTransport(options) {
 	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;
+		if (targetOrigin !== "*") {
+			const expectedSource = options.source ?? iframe.contentWindow;
+			if (e.source !== expectedSource) return;
+			if (e.origin !== targetOrigin) return;
+		}
 		const data = e.data;
 		if (!data?.type?.startsWith?.(PREFIX)) return;
 		if (data.type === "@statelyai.ready" && !isReady) {
@@ -192,10 +196,10 @@ function createWebSocketTransport(options) {
 			if (!raw?.type || typeof raw.type !== "string") return;
 			if (!raw.type.startsWith(PREFIX)) return;
 			const data = raw;
-			if (data.type === "@statelyai.registered" && !isReady) {
+			if (data.type === "@statelyai.registered") {
+				const wasReady = isReady;
 				isReady = true;
-				readyHandlers.forEach((fn) => fn());
-				readyHandlers.clear();
+				if (!wasReady) readyHandlers.forEach((fn) => fn());
 			}
 			messageHandlers.forEach((fn) => fn(data));
 		};
@@ -232,14 +236,11 @@ function createWebSocketTransport(options) {
 			readyHandlers.clear();
 		},
 		get ready() {
-			return isReady;
+			return isReady && !!ws && ws.readyState === WebSocket.OPEN;
 		},
 		onReady(handler) {
-			if (isReady) {
-				handler();
-				return () => {};
-			}
 			readyHandlers.add(handler);
+			if (isReady) handler();
 			return () => {
 				readyHandlers.delete(handler);
 			};
@@ -248,4 +249,4 @@ function createWebSocketTransport(options) {
 }
 
 //#endregion
-export { createRequestId as a, createPendingExportManager as i, createWebSocketTransport as n, toInitMessage as o, createEventRegistry as r, createPostMessageTransport as t };
+export { toInitMessage as a, createPendingExportManager as i, createWebSocketTransport as n, createEventRegistry as r, createPostMessageTransport as t };