@statelyai/sdk 0.34.1 → 0.35.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 -->
 
@@ -223,6 +215,10 @@ 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.
 
+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
 actors. For example, with `producerId: 'demo'`, select `inspector.actor('root')`
@@ -236,9 +232,14 @@ const inspector = createInspector();
 const { inspect } = inspector;
 
 const actor = createActor(machine, { inspect });
+// With XState v6, the inspector shows this actor's graph before start().
 actor.start();
 ```
 
+Before `start()`, the XState v6 actor view has no active-state highlight. The
+first runtime transition updates that same actor view. An initial error is
+shown immediately, even if `start()` produces no transition.
+
 The inspector also accepts read-only `documents`, panel configuration, initial
 `viewMode`, and typed display `settings`. Use `selectActor(sessionId)`,
 `setTheme(theme)`, `setViewMode(mode)`, and `setSettings(settings)` to control the
@@ -307,7 +308,12 @@ replacement; late observations from a displaced actor are ignored.
 
 The resolver's third argument is the parent's resolved id, so recreated child
 actors can use stable paths instead of accumulating runtime session ids. IDs
-must still be unique within one live actor tree.
+must be unique along each parent-child path. Sibling actors may reuse one id
+after its previous owner reaches `done`, `stopped`, or `error`; setting
+`sessionIdReuse: "always"` also permits explicit replacement of an active
+sibling. The displaced actor's later observations are ignored. Inspector
+callback errors emit `on('error', ...)` with code `inspection_failed` and do not
+interrupt the actor system.
 
 To present a stopped request-scoped runtime as waiting for its next resume, map
 its serialized status to a non-terminal value such as `suspended` in
@@ -332,6 +338,9 @@ keep it private. Hosted replay expires after 24
 hours without activity. Only actor checkpoints and observations are replayed;
 export traffic is live-only, and auth/upload/embed-control messages are rejected.
 AI-backed features remain separately authenticated.
+The relay keeps a complete current actor checkpoint while bounding recent
+observation history, so joining after many actor registrations still initializes
+the viewer.
 
 After successful registration, hosted Sky records coarse connection analytics:
 role, normalized browser origin or `unknown`, localhost status, runtime,
@@ -360,8 +369,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
@@ -394,15 +403,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`. 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-B7q2lWj_.mjs";
+import { Gt as UploadResult } from "./protocol-nOWsz3UV.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-DNFk7Xtj.d.mts

@@ -0,0 +1,53 @@
+//#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[];
+  staticValues?: Array<EditorSyncSourceLocation & {
+    value: 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,197 @@
+import { Q as ProjectEmbedMachine, an as EmbedPanelConfig, lt as ProjectWorkspaceConfig } from "./protocol-nOWsz3UV.mjs";
+import { a as MachineSourceLocations, t as EditorCapabilities } from "./editor-sync-types-DNFk7Xtj.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;
+  machineId?: string;
+  sourceLocations?: MachineSourceLocations;
+} | {
+  type: '@statelyai.change';
+  graph: unknown;
+  machineConfig: unknown;
+  machineId?: string;
+  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;
+  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';
+  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;
+  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-DZivqh0u.mjs";
-import { i as StatelyGraph } from "./graph-Ciocekxl.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-B7q2lWj_.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, 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-nOWsz3UV.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-BEfUEyPL.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-DECst76A.mjs";
+import { EDITOR_PROTOCOL_VERSION } from "./editorHostProtocol.mjs";
 
 //#region src/embed.ts
 function isRecord(value) {

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

@@ -1,4 +1,4 @@
-import { t as CodeExpression } from "./index-DZivqh0u.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-Ciocekxl.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 };