@statelyai/sdk 0.34.2 → 0.36.0

package/README.md

@@ -109,22 +109,14 @@ restricted embeds.
 Use `access-unverified` when reopening or signing in, rather than upgrading, is
 the appropriate recovery action.
 
-### Editor hosts
-
-<!-- shared editor host session and protocol from src/editorHostSession.ts and src/editorHostProtocol.ts -->
-
-CLI and editor-extension hosts use `EditorHostSession` from
-`@statelyai/sdk/editor-host` for initialization, saves, source refreshes,
-clipboard requests, and editor protocol negotiation. Use
-`createRemoteEditorSyncBackend` for two-way validation of the versioned Editor
-Sync HTTP contract.
-Remote authentication failures are surfaced as `EditorSyncError` with HTTP
-status and protocol error code metadata so hosts can refresh credentials and
-retry once without depending on response-message text.
-Source write and refresh failures include an `EditorHostDiagnostic` with a
-unique diagnostic ID, phase, and structured details so host logs can be shared
-without exposing source text by default.
-Hosts keep ownership of files, credentials, UI, and transport adapters.
+### Editor host protocol
+
+<!-- shared editor protocol from src/editorHostProtocol.ts and private host implementation from ../editor-sync/src/host.ts -->
+
+`@statelyai/sdk/editor-host-protocol` provides the versioned messages and types
+used by editor hosts. The private `@statelyai/editor-sync` package coordinates
+CLI and VS Code source editing. Application developers use the embed API below
+without a TypeScript compiler or source writeback dependency.
 
 <!-- supported editor export formats from packages/editor/src/formatConfig.ts -->
 
@@ -132,6 +124,7 @@ Key capabilities:
 
 - **Mount or attach** to any container element or existing iframe
 - **Two-way sync** - push machine configs in, get changes and saves back via event callbacks
+- **Draft-aware events** - change callbacks report the visible graph, even when a retained draft has a separate source baseline
 - **Export** to multiple formats: XState v5, XState v6 alpha, XState JSON, Mermaid, Redux, Zustand, ASL, SCXML, and more
 - **Access policies** for read-only, no-export, no-AI, shallow-viewer embeds
 - **Reference documents** supplied as ordered, read-only Markdown, code, or text
@@ -190,6 +183,8 @@ The client namespaces map one-to-one onto the server-owned `/api/v1` contract:
 
 `machines.get(machineId)` preserves the stored `definition` and also exposes a
 public `graph` property when the server can provide a canonical XGraph.
+Pass that record's `updatedAt` as `expectedUpdatedAt` to reject a stale machine
+update atomically.
 
 `baseUrl` defaults to `https://editor.stately.ai`. Do not target
 `stately.ai/registry` directly: Registry URLs are deprecated for clients, and
@@ -223,11 +218,9 @@ Resource operations always require a credential.
 Stream live actor-system state to the hosted Stately inspector. Zero-config
 inspection needs no API key or local relay.
 
-For an app that only needs actor inspection, install
-[`@statelyai/inspector`](../inspector) instead. It provides the same
-`createInspector` API without installing the SDK's source-sync, graph, and Node
-relay dependencies. In the examples below, import from `@statelyai/inspector`
-when using that package.
+Install `@statelyai/sdk` for inspection. Source editing and the TypeScript
+compiler are confined to the private Editor Sync package. The Node relay's `ws`
+peer is optional for other SDK users.
 
 `selectedSessionId` takes the exact session id: `actor.sessionId` for runtime
 actors (or your `resolveSessionId` result), and `${producerId}:${id}` for manual
@@ -379,8 +372,8 @@ WebSocket UTF-8 length limit.
 
 ### CLI and sync
 
-<!-- CLI package identity and commands from ../cli/package.json, ../cli/src/cli.ts#COMMANDS, and src/sync.ts#pullSync -->
-<!-- linked-machine read-merge behavior from src/sync.ts#pushLocalMachineLinks and src/sync.ts#pushSync -->
+<!-- CLI package identity and commands from ../cli/package.json, ../cli/src/cli.ts#COMMANDS, and ../editor-sync/src/sync.ts#pullSync -->
+<!-- linked-machine read-merge behavior from ../editor-sync/src/sync.ts#pushLocalMachineLinks and ../editor-sync/src/sync.ts#pushSync -->
 
 The separate [`statelyai`](https://www.npmjs.com/package/statelyai) CLI lists
 local XState machines without authentication and can connect them to Stately
@@ -413,19 +406,12 @@ patches. Comments, imports, helpers, and implementation bodies outside the
 changed machine regions remain intact. `force: true` on `pullSync` allows full
 regeneration when the source cannot be reconciled safely.
 
-### Graph and codegen helpers
+### Graph conversion
 
-<!-- graph conversion and codegen exports from src/graph.ts and src/index.ts -->
+<!-- graph conversion exports from src/graph.ts and src/index.ts -->
 
-Convert between Studio graph data, XState machine configs, and TypeScript
-source with `graphToXStateTS`. `graphToXStateTSResult` also reports code leaves
-that a profile replaced to keep an export syntactically valid;
-`getProfileCodeIssues` inspects them without exporting, and
-`recoverInvalidProfileCode` applies the profile's exact fallback functions to a
-copy. Source-location documents retain authored code instead of applying these
-export-only stubs. Use `graphToXStateFSM` for a flat `createFSM` projection and
-`getXStateFSMCompatibilityIssues` before exporting to report semantics that the
-compact FSM cannot represent. Generate types from JSON Schema.
+`fromStudioMachine` and `toStudioMachine` convert Studio machine records to and
+from graph data. Source generation is part of the private Editor Sync workflow.
 
 ## Support
 

package/dist/assetStorage.d.mts

@@ -1,4 +1,4 @@
-import { Gt as UploadResult } from "./protocol-CCf9j_SZ.mjs";
+import { Gt as UploadResult } from "./protocol-CP3DSl5u.mjs";
 
 //#region src/assetStorage.d.ts
 interface AssetUploadContext {

package/dist/auth.d.mts

@@ -1,2 +1,15 @@
-import { i as getCredentialToken, n as StatelyCredential, r as createAuthorizationHeader, t as StatelyAuthMode } from "./auth-CVFc85uF.mjs";
+//#region src/auth.d.ts
+type StatelyCredential = {
+  type: 'api_key';
+  token: string;
+} | {
+  type: 'oauth';
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+};
+type StatelyAuthMode = 'auto' | 'none' | 'bearer';
+declare function getCredentialToken(credential: StatelyCredential | string | null | undefined): string | undefined;
+declare function createAuthorizationHeader(credential: StatelyCredential | string): string;
+//#endregion
 export { StatelyAuthMode, StatelyCredential, createAuthorizationHeader, getCredentialToken };

package/dist/bin.mjs

@@ -1,7 +1,4 @@
 #!/usr/bin/env node
-import "./protocol-BsBGRISR.mjs";
-import { createNodeInspectionRelay } from "./node-relay.mjs";
-
 //#region src/bin.ts
 function readFlag(name, fallback) {
 	const index = process.argv.indexOf(`--${name}`);
@@ -14,6 +11,7 @@ async function main() {
 		process.exitCode = command ? 1 : 0;
 		return;
 	}
+	const { createNodeInspectionRelay } = await import("./node-relay.mjs");
 	const relay = createNodeInspectionRelay({
 		host: readFlag("host", process.env.STATELY_HOST ?? "127.0.0.1"),
 		port: Number(readFlag("port", process.env.STATELY_PORT ?? "4242")),

package/dist/editor-sync-types-U5uryWOk.d.mts

@@ -0,0 +1,55 @@
+//#region ../api-contract/dist/editor-sync-types.d.mts
+//#region src/editor-sync-types.d.ts
+interface EditorCapabilities {
+  edit?: boolean;
+  export?: boolean;
+  ai?: boolean;
+  simulate?: boolean;
+  inspect?: boolean;
+  maxDepth?: number;
+  panels?: string[];
+  commands?: string[];
+}
+interface EditorSyncSourceRange {
+  startLine: number;
+  startChar: number;
+  endLine: number;
+  endChar: number;
+}
+interface EditorSyncSourceLocation {
+  uri: string;
+  range: EditorSyncSourceRange;
+}
+interface EditorSyncStateSourceLocation extends EditorSyncSourceLocation {
+  path: string[];
+  kind: 'inline' | 'objectReference' | 'createStateConfig';
+  symbol?: string;
+  keyRange?: EditorSyncSourceRange;
+  referenceRange?: EditorSyncSourceRange;
+  keySource?: {
+    kind: 'const' | 'enumMember' | 'computedLiteral';
+    symbol?: string;
+    valueRange?: EditorSyncSourceRange;
+    machineLocal?: boolean;
+  };
+  keyReplacementText?: string;
+}
+interface MachineSourceLocations {
+  version: 1;
+  profile?: 'xstate-v5' | 'xstate-v6-alpha';
+  profileRef?: `@statelyai/xstate@${string}`;
+  root?: EditorSyncSourceLocation;
+  statesObject?: EditorSyncStateSourceLocation;
+  states: EditorSyncStateSourceLocation[];
+  dependencyUris?: string[];
+  staticValues?: Array<EditorSyncSourceLocation & {
+    value: string;
+    definitionUri?: string;
+  }>;
+  transitionFunctions?: Array<EditorSyncSourceLocation & {
+    symbol: string;
+    sourcePaths: string[][];
+  }>;
+}
+//#endregion
+export { MachineSourceLocations as a, EditorSyncStateSourceLocation as i, EditorSyncSourceLocation as n, EditorSyncSourceRange as r, EditorCapabilities as t };

package/dist/editorHostProtocol.d.mts

@@ -0,0 +1,203 @@
+import { Q as ProjectEmbedMachine, an as PresentationMetadataInitializer, lt as ProjectWorkspaceConfig, on as EmbedPanelConfig } from "./protocol-CP3DSl5u.mjs";
+import { a as MachineSourceLocations, t as EditorCapabilities } from "./editor-sync-types-U5uryWOk.mjs";
+
+//#region src/editorHostProtocol.d.ts
+declare const EDITOR_PROTOCOL_VERSION = 1;
+type EditorHostDiagnostic = {
+  id: string;
+  code: string;
+  phase: 'initialize' | 'save' | 'update' | 'export';
+  timestamp: string;
+  details?: Record<string, unknown>;
+};
+type EditorHostExportFormat = 'xstate-v6' | 'xstate' | 'async' | 'xstate-json' | 'xgraph' | 'digraph' | 'd2' | 'mermaid' | 'redux' | 'zustand' | 'asl-json' | 'asl-yaml' | 'scxml';
+interface EditorHostValidationIssue {
+  nodeIds: string[];
+  edgeIds: string[];
+  level: 'info' | 'warning' | 'error';
+  message: string;
+}
+type EditorHostInboundMessage = {
+  type: '@statelyai.ready';
+  version?: string;
+  protocolVersion?: number;
+} | {
+  type: '@statelyai.loaded';
+  graph: unknown;
+  sourceBaselineGraph?: unknown;
+  machineId?: string;
+  sourceLocations?: MachineSourceLocations;
+} | {
+  type: '@statelyai.change';
+  graph: unknown;
+  machineConfig: unknown;
+  machineId?: string; /** The editor has applied a host source refresh, not a visual edit. */
+  source?: 'external';
+  sourceBaselineGraph?: unknown;
+  patches?: unknown[];
+  sourceLocations?: MachineSourceLocations;
+} | {
+  type: '@statelyai.save';
+  requestId?: string;
+  graph: unknown;
+  machineConfig: unknown;
+  machineId?: string;
+  patches?: unknown[];
+  validations?: EditorHostValidationIssue[];
+  sourceLocations?: MachineSourceLocations;
+  sourceUpdateStrategy?: 'preserve' | 'rewrite';
+} | {
+  type: '@statelyai.refresh';
+  machineId?: string;
+} | {
+  type: '@statelyai.retrieved';
+  requestId: string;
+  data: unknown;
+  machineId?: string;
+} | {
+  type: '@statelyai.error';
+  code: string;
+  message: string;
+  machineId?: string;
+  requestId?: string;
+  diagnostic?: EditorHostDiagnostic;
+} | {
+  type: '@statelyai.clipboardRead';
+  requestId: string;
+} | {
+  type: '@statelyai.clipboardWrite';
+  requestId: string;
+  text: string;
+} | {
+  type: '@statelyai.project.machineSelected';
+  machineId: string;
+} | {
+  type: '@statelyai.project.workspaceAction';
+  actionId: string;
+  projectId?: string;
+  machineId?: string;
+  data?: unknown;
+} | {
+  type: '@statelyai.project.workspaceOpenChanged';
+  open: boolean;
+};
+interface EditorHostInitOptions {
+  settings?: Record<string, unknown>;
+  panels?: EmbedPanelConfig[];
+  /** @deprecated Use `panels`. */
+  leftPanels?: string[];
+  /** @deprecated Use `panels`. */
+  rightPanels?: string[];
+  /** @deprecated Use `panels[].initiallyOpen`. */
+  activePanels?: string[];
+  unsavedIndicator?: {
+    enabled?: boolean;
+    mode?: 'structural' | 'all';
+  };
+}
+type EditorHostOutboundMessage = {
+  type: '@statelyai.init';
+  machine: unknown;
+  presentation?: PresentationMetadataInitializer;
+  format?: string;
+  mode?: 'editing' | 'viewing';
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+  readOnlyReason?: 'free-plan' | 'access-unverified';
+  capabilities?: EditorCapabilities;
+  sourceLocations?: MachineSourceLocations;
+  settings?: Record<string, unknown>;
+  panels?: EmbedPanelConfig[]; /** @deprecated Use `panels`. */
+  leftPanels?: string[]; /** @deprecated Use `panels`. */
+  rightPanels?: string[]; /** @deprecated Use `panels[].initiallyOpen`. */
+  activePanels?: string[];
+  unsavedIndicator?: {
+    enabled?: boolean;
+    mode?: 'structural' | 'all';
+  };
+} | {
+  type: '@statelyai.project.init';
+  machines: ProjectEmbedMachine[];
+  chrome?: {
+    header?: boolean;
+  };
+  currentMachineId?: string;
+  mode?: 'editing' | 'viewing';
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+  readOnlyReason?: 'free-plan' | 'access-unverified';
+  capabilities?: EditorCapabilities;
+  projectWorkspace?: ProjectWorkspaceConfig;
+  projectWorkspaceOpen?: boolean;
+  settings?: Record<string, unknown>;
+  panels?: EmbedPanelConfig[];
+  unsavedIndicator?: {
+    enabled?: boolean;
+    mode?: 'structural' | 'all';
+  };
+} | {
+  type: '@statelyai.project.update';
+  machines: ProjectEmbedMachine[];
+  source?: 'external' | 'presentation';
+  updatedMachineId?: string;
+  currentMachineId?: string;
+  projectWorkspace?: ProjectWorkspaceConfig;
+  projectWorkspaceOpen?: boolean;
+} | {
+  type: '@statelyai.project.selectMachine';
+  machineId: string;
+} | {
+  type: '@statelyai.setApiKey';
+  apiKey: string;
+} | {
+  type: '@statelyai.handshake';
+  protocolVersion: number;
+  client?: {
+    name: string;
+    version: string;
+  };
+} | {
+  type: '@statelyai.update';
+  machine: unknown;
+  format?: string;
+  source?: 'presentation';
+  machineId?: string;
+  sourceLocations?: MachineSourceLocations;
+} | {
+  type: '@statelyai.saved';
+  requestId?: string;
+  graph: unknown;
+  machineId?: string;
+} | {
+  type: '@statelyai.retrieve';
+  requestId: string;
+  format: EditorHostExportFormat;
+  machineId?: string;
+} | {
+  type: '@statelyai.toast';
+  message: string;
+  toastType?: 'success' | 'error' | 'info' | 'warning';
+  id?: string;
+  machineId?: string;
+} | {
+  type: '@statelyai.toast.dismiss';
+  id: string;
+  machineId?: string;
+} | {
+  type: '@statelyai.error';
+  code: string;
+  message: string;
+  machineId?: string;
+  requestId?: string;
+  diagnostic?: EditorHostDiagnostic;
+} | {
+  type: '@statelyai.clipboardReadResponse';
+  requestId: string;
+  text: string;
+} | {
+  type: '@statelyai.clipboardWriteResponse';
+  requestId: string;
+  ok: boolean;
+};
+//#endregion
+export { EDITOR_PROTOCOL_VERSION, EditorHostDiagnostic, EditorHostExportFormat, EditorHostInboundMessage, EditorHostInitOptions, EditorHostOutboundMessage, EditorHostValidationIssue };

package/dist/{editorHostProtocol-B2_t3Le7.mjs → editorHostProtocol.mjs}

@@ -2,4 +2,4 @@
 const EDITOR_PROTOCOL_VERSION = 1;
 
 //#endregion
-export { EDITOR_PROTOCOL_VERSION as t };
+export { EDITOR_PROTOCOL_VERSION };

package/dist/embed.d.mts

@@ -1,6 +1,6 @@
-import { i as ProfileManifest } from "./index-A5CMACoO.mjs";
-import { i as StatelyGraph } from "./graph-DVfx7FwN.mjs";
-import { D as ExportCallOptions, F as InitOptions, G as MachineInitOptions, Gt as UploadResult, J as MachineVersionAutoSaveOptions, O as ExportFormat, Q as ProjectEmbedMachine, S as EmbedExtensionsManifest, Yt as ViewerOptions, _ as EmbedDocumentLanguage, an as EmbedPanelConfig, at as ProjectWorkspaceAction, b as EmbedEventName, ct as ProjectWorkspaceCapabilities, d as CommentsConfig, dt as ProjectWorkspaceMachineOrigin, et as ProjectInitOptions, g as EmbedDocument, k as ExportFormatMap, lt as ProjectWorkspaceConfig, m as EditorCapabilities, on as EmbedPanelPosition, ot as ProjectWorkspaceActionIcon, pt as ProjectWorkspaceProject, q as MachineSourceLocations, r as CapabilityDeniedEvent, ut as ProjectWorkspaceMachine, v as EmbedEventHandler, w as EmbedMode, y as EmbedEventMap } from "./protocol-CCf9j_SZ.mjs";
+import { n as ProfileManifest } from "./index-CoxF4Saw.mjs";
+import { i as StatelyGraph } from "./graph-B6xUxqR5.mjs";
+import { D as ExportCallOptions, F as InitOptions, G as MachineInitOptions, Gt as UploadResult, J as MachineVersionAutoSaveOptions, O as ExportFormat, Q as ProjectEmbedMachine, S as EmbedExtensionsManifest, Yt as ViewerOptions, _ as EmbedDocumentLanguage, at as ProjectWorkspaceAction, b as EmbedEventName, ct as ProjectWorkspaceCapabilities, d as CommentsConfig, dt as ProjectWorkspaceMachineOrigin, et as ProjectInitOptions, g as EmbedDocument, k as ExportFormatMap, lt as ProjectWorkspaceConfig, m as EditorCapabilities, on as EmbedPanelConfig, ot as ProjectWorkspaceActionIcon, pt as ProjectWorkspaceProject, q as MachineSourceLocations, r as CapabilityDeniedEvent, sn as EmbedPanelPosition, ut as ProjectWorkspaceMachine, v as EmbedEventHandler, w as EmbedMode, y as EmbedEventMap } from "./protocol-CP3DSl5u.mjs";
 import { AssetUploadAdapter } from "./assetStorage.mjs";
 
 //#region src/embed.d.ts

package/dist/embed.mjs

@@ -1,6 +1,6 @@
 import "./protocol-BsBGRISR.mjs";
-import { c as createPendingExportManager, l as settingsWithViewMode, r as createPostMessageTransport, s as createEventRegistry, t as SDK_VERSION, u as toInitMessage } from "./version-CUFh-PYe.mjs";
-import { t as EDITOR_PROTOCOL_VERSION } from "./editorHostProtocol-B2_t3Le7.mjs";
+import { c as createPendingExportManager, l as settingsWithViewMode, r as createPostMessageTransport, s as createEventRegistry, t as SDK_VERSION, u as toInitMessage } from "./version-DS2izNeF.mjs";
+import { EDITOR_PROTOCOL_VERSION } from "./editorHostProtocol.mjs";
 
 //#region src/embed.ts
 function isRecord(value) {

package/dist/{graph-DVfx7FwN.d.mts → graph-B6xUxqR5.d.mts}

@@ -1,4 +1,4 @@
-import { t as CodeExpression } from "./index-A5CMACoO.mjs";
+import { t as CodeExpression } from "./index-CoxF4Saw.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-DVfx7FwN.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-B6xUxqR5.mjs";
 export { StatelyAction, StatelyActorImplementation, StatelyEdgeData, StatelyGraph, StatelyGraphData, StatelyGuard, StatelyImplementation, StatelyInvoke, StatelyNodeData, StatelyTagImplementation, StudioAction, StudioEdge, StudioEventTypeData, StudioMachine, StudioNode, fromStudioMachine, studioMachineConverter, toStudioMachine };