@statelyai/sdk 0.9.1 → 0.10.0

package/README.md

@@ -21,6 +21,6 @@ The broader in-progress package documentation draft is kept in:
 Published schemas:
 
 - `@statelyai/sdk/statelyai.schema.json`
-- `@statelyai/sdk/xstate-json.schema.json`
+- `@statelyai/sdk/xstate.schema.json`
 
-The CLI-facing `statelyai.json` schema now uses top-level `include` / `exclude` globs for local file discovery.
+The CLI-facing `statelyai.json` schema now uses top-level `include` / `exclude` globs for local file discovery, plus `newMachineDir` for pulling remote-only project machines into new local files.

package/dist/protocol.d.mts

@@ -1,5 +1,5 @@
 //#region src/protocol.d.ts
-type EmbedMode = 'editing' | 'viewing' | 'simulating' | 'inspecting';
+type EmbedMode = "editing" | "viewing" | "simulating" | "inspecting";
 interface CommentsConfig {
   roomId: string;
   userId?: string | null;
@@ -15,7 +15,7 @@ interface ProjectEmbedMachine {
 interface ValidationIssue {
   nodeIds: string[];
   edgeIds: string[];
-  level: 'info' | 'warning' | 'error';
+  level: "info" | "warning" | "error";
   message: string;
 }
 interface SourceRange {
@@ -30,12 +30,12 @@ interface SourceLocation {
 }
 interface StateSourceLocation extends SourceLocation {
   path: string[];
-  kind: 'inline' | 'objectReference' | 'createStateConfig';
+  kind: "inline" | "objectReference" | "createStateConfig";
   symbol?: string;
   keyRange?: SourceRange;
   referenceRange?: SourceRange;
   keySource?: {
-    kind: 'const' | 'enumMember' | 'computedLiteral';
+    kind: "const" | "enumMember" | "computedLiteral";
     symbol?: string;
     valueRange?: SourceRange;
     machineLocal?: boolean;
@@ -60,7 +60,11 @@ interface ExportFormatMap {
     };
     result: string;
   };
-  'xstate-json': {
+  async: {
+    options: object;
+    result: string;
+  };
+  "xstate-json": {
     options: {
       version?: 4 | 5;
     };
@@ -86,11 +90,11 @@ interface ExportFormatMap {
     options: object;
     result: string;
   };
-  'asl-json': {
+  "asl-json": {
     options: object;
     result: string;
   };
-  'asl-yaml': {
+  "asl-yaml": {
     options: object;
     result: string;
   };
@@ -100,7 +104,7 @@ interface ExportFormatMap {
   };
 }
 type ExportFormat = keyof ExportFormatMap;
-type ExportCallOptions<F extends ExportFormat> = ExportFormatMap[F]['options'] & {
+type ExportCallOptions<F extends ExportFormat> = ExportFormatMap[F]["options"] & {
   timeout?: number;
 };
 interface EmbedEventMap {
@@ -145,7 +149,7 @@ interface MachineInitOptions {
   machine: unknown;
   format?: string;
   mode?: EmbedMode;
-  theme?: 'light' | 'dark';
+  theme?: "light" | "dark";
   readOnly?: boolean;
   depth?: number;
   panels?: {
@@ -169,14 +173,14 @@ interface MachineInitOptions {
    */
   unsavedIndicator?: {
     enabled?: boolean;
-    mode?: 'structural' | 'all';
+    mode?: "structural" | "all";
   };
 }
 interface ProjectInitOptions {
   machines: ProjectEmbedMachine[];
   currentMachineId?: string;
   mode?: EmbedMode;
-  theme?: 'light' | 'dark';
+  theme?: "light" | "dark";
   readOnly?: boolean;
   depth?: number;
   panels?: {
@@ -187,16 +191,16 @@ interface ProjectInitOptions {
   commentsByMachineId?: Record<string, CommentsConfig>;
   unsavedIndicator?: {
     enabled?: boolean;
-    mode?: 'structural' | 'all';
+    mode?: "structural" | "all";
   };
 }
 type InitOptions = MachineInitOptions | ProjectInitOptions;
 interface InitMessage {
-  type: '@statelyai.init';
+  type: "@statelyai.init";
   machine: unknown;
   format?: string;
   mode?: EmbedMode;
-  theme?: 'light' | 'dark';
+  theme?: "light" | "dark";
   readOnly?: boolean;
   depth?: number;
   leftPanels?: string[];
@@ -207,17 +211,17 @@ interface InitMessage {
   /** Mirror of `InitOptions.unsavedIndicator`. */
   unsavedIndicator?: {
     enabled?: boolean;
-    mode?: 'structural' | 'all';
+    mode?: "structural" | "all";
   };
   /** Optional session id override (multiplexed clients only). */
   sessionId?: string;
 }
 interface ProjectInitMessage {
-  type: '@statelyai.project.init';
+  type: "@statelyai.project.init";
   machines: ProjectEmbedMachine[];
   currentMachineId?: string;
   mode?: EmbedMode;
-  theme?: 'light' | 'dark';
+  theme?: "light" | "dark";
   readOnly?: boolean;
   depth?: number;
   leftPanels?: string[];
@@ -226,51 +230,51 @@ interface ProjectInitMessage {
   commentsByMachineId?: Record<string, CommentsConfig>;
   unsavedIndicator?: {
     enabled?: boolean;
-    mode?: 'structural' | 'all';
+    mode?: "structural" | "all";
   };
   sessionId?: string;
 }
 interface ProjectUpdateMessage {
-  type: '@statelyai.project.update';
+  type: "@statelyai.project.update";
   machines: ProjectEmbedMachine[];
   currentMachineId?: string;
   commentsByMachineId?: Record<string, CommentsConfig>;
 }
 interface ProjectSelectMachineMessage {
-  type: '@statelyai.project.selectMachine';
+  type: "@statelyai.project.selectMachine";
   machineId: string;
 }
 interface UpdateMessage {
-  type: '@statelyai.update';
+  type: "@statelyai.update";
   machine: unknown;
   format?: string;
   sourceLocations?: MachineSourceLocations;
 }
 interface SetModeMessage {
-  type: '@statelyai.setMode';
+  type: "@statelyai.setMode";
   mode: EmbedMode;
 }
 interface SetThemeMessage {
-  type: '@statelyai.setTheme';
-  theme: 'light' | 'dark';
+  type: "@statelyai.setTheme";
+  theme: "light" | "dark";
 }
 interface SetSettingsMessage {
-  type: '@statelyai.setSettings';
+  type: "@statelyai.setSettings";
   settings: Record<string, unknown>;
 }
 interface RetrieveMessage {
-  type: '@statelyai.retrieve';
+  type: "@statelyai.retrieve";
   requestId: string;
   format: ExportFormat;
   options?: Record<string, unknown>;
 }
 interface ToastMessage {
-  type: '@statelyai.toast';
+  type: "@statelyai.toast";
   message: string;
-  toastType?: 'success' | 'error' | 'info' | 'warning';
+  toastType?: "success" | "error" | "info" | "warning";
 }
 interface InspectSnapshotMessage {
-  type: '@statelyai.inspectSnapshot';
+  type: "@statelyai.inspectSnapshot";
   snapshot: unknown;
   event: unknown | null;
   /**
@@ -293,13 +297,13 @@ interface ActorSystemEntry {
   snapshot?: unknown;
 }
 interface SystemInitMessage {
-  type: '@statelyai.system.init';
+  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';
+  theme?: "light" | "dark";
   readOnly?: boolean;
   depth?: number;
   leftPanels?: string[];
@@ -309,7 +313,7 @@ interface SystemInitMessage {
 }
 /** A new actor joined the system after init. */
 interface SystemActorRegisteredMessage {
-  type: '@statelyai.system.actorRegistered';
+  type: "@statelyai.system.actorRegistered";
   actorId: string;
   parentActorId: string | null;
   id: string;
@@ -318,7 +322,7 @@ interface SystemActorRegisteredMessage {
 }
 /** An actor's snapshot updated. */
 interface SystemActorSnapshotMessage {
-  type: '@statelyai.system.actorSnapshot';
+  type: "@statelyai.system.actorSnapshot";
   actorId: string;
   snapshot: unknown;
   event?: unknown | null;
@@ -327,21 +331,21 @@ interface SystemActorSnapshotMessage {
 }
 /** An actor reached a final state / was stopped. */
 interface SystemActorStoppedMessage {
-  type: '@statelyai.system.actorStopped';
+  type: "@statelyai.system.actorStopped";
   actorId: string;
 }
 interface ReadyMessage {
-  type: '@statelyai.ready';
+  type: "@statelyai.ready";
   version: string;
 }
 interface LoadedMessage {
-  type: '@statelyai.loaded';
+  type: "@statelyai.loaded";
   graph: unknown;
   machineId?: string;
   sourceLocations?: MachineSourceLocations;
 }
 interface ChangeMessage {
-  type: '@statelyai.change';
+  type: "@statelyai.change";
   graph: unknown;
   machineConfig: unknown;
   machineId?: string;
@@ -349,7 +353,7 @@ interface ChangeMessage {
   sourceLocations?: MachineSourceLocations;
 }
 interface SaveMessage {
-  type: '@statelyai.save';
+  type: "@statelyai.save";
   graph: unknown;
   machineConfig: unknown;
   machineId?: string;
@@ -358,16 +362,16 @@ interface SaveMessage {
   sourceLocations?: MachineSourceLocations;
 }
 interface ProjectMachineSelectedMessage {
-  type: '@statelyai.project.machineSelected';
+  type: "@statelyai.project.machineSelected";
   machineId: string;
 }
 interface RetrievedMessage {
-  type: '@statelyai.retrieved';
+  type: "@statelyai.retrieved";
   requestId: string;
   data: unknown;
 }
 interface ErrorMessage {
-  type: '@statelyai.error';
+  type: "@statelyai.error";
   code: string;
   message: string;
   requestId?: string;
@@ -394,21 +398,21 @@ interface UploadResult {
 }
 /** Viz requests the parent to upload a file. */
 interface UploadRequestMessage {
-  type: '@statelyai.uploadRequest';
+  type: "@statelyai.uploadRequest";
   requestId: string;
   file: UploadFileInfo;
   stateNodeId: string;
 }
 /** Parent tells the viz the upload capabilities on init. */
 interface UploadCapabilitiesMessage {
-  type: '@statelyai.uploadCapabilities';
+  type: "@statelyai.uploadCapabilities";
   enabled: boolean;
   accept?: string[];
   maxFileSize?: number;
 }
 /** Parent sends the upload result back to the viz. */
 interface UploadResponseMessage {
-  type: '@statelyai.uploadResponse';
+  type: "@statelyai.uploadResponse";
   requestId: string;
   result: UploadResult;
 }
@@ -417,8 +421,8 @@ type ClientMessage = InitMessage | ProjectInitMessage | ProjectUpdateMessage | P
 /** All messages the viz can send back to a client. */
 type VizMessage = ReadyMessage | LoadedMessage | ChangeMessage | SaveMessage | ProjectMachineSelectedMessage | RetrievedMessage | ErrorMessage | UploadRequestMessage;
 interface RegisterMessage {
-  type: '@statelyai.register';
-  role: 'client' | 'viz';
+  type: "@statelyai.register";
+  role: "client" | "viz";
   sessionId: string;
   metadata?: {
     name?: string;
@@ -426,11 +430,11 @@ interface RegisterMessage {
   };
 }
 interface RegisteredMessage {
-  type: '@statelyai.registered';
+  type: "@statelyai.registered";
   sessionId: string;
 }
 interface RequestOpenMessage {
-  type: '@statelyai.requestOpen';
+  type: "@statelyai.requestOpen";
   sessionId: string;
 }
 /**
@@ -445,7 +449,7 @@ interface RequestOpenMessage {
  *      the root to target a specific session (falls back to primary).
  */
 interface AddSessionMessage {
-  type: '@statelyai.addSession';
+  type: "@statelyai.addSession";
   sessionId: string;
   metadata?: {
     name?: string;
@@ -454,7 +458,7 @@ interface AddSessionMessage {
 }
 /** Relay → client: acknowledgement that a session was added. */
 interface SessionAddedMessage {
-  type: '@statelyai.sessionAdded';
+  type: "@statelyai.sessionAdded";
   sessionId: string;
 }
 /** All session-management messages for the WS relay. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/sdk",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "license": "MIT",
   "files": [
     "dist",
@@ -52,8 +52,10 @@
     },
     "./statelyai.schema.json": "./schemas/statelyai.schema.json",
     "./schemas/statelyai.schema.json": "./schemas/statelyai.schema.json",
-    "./xstate-json.schema.json": "./schemas/xstate-json.schema.json",
-    "./schemas/xstate-json.schema.json": "./schemas/xstate-json.schema.json"
+    "./xstate.schema.json": "./schemas/xstate.schema.json",
+    "./schemas/xstate.schema.json": "./schemas/xstate.schema.json",
+    "./xstate-json.schema.json": "./schemas/xstate.schema.json",
+    "./schemas/xstate-json.schema.json": "./schemas/xstate.schema.json"
   },
   "dependencies": {
     "@statelyai/graph": "^0.9.0",

package/schemas/statelyai.schema.json

@@ -46,6 +46,11 @@
       "items": {
         "$ref": "#/$defs/globPattern"
       }
+    },
+    "newMachineDir": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Directory, relative to statelyai.json, where statelyai pull should create new local files for remote-only project machines."
     }
   },
   "$defs": {
@@ -63,7 +68,8 @@
       "studioUrl": "https://stately.ai",
       "defaultXStateVersion": 5,
       "include": ["src/**/*.ts", "src/**/*.tsx"],
-      "exclude": ["**/*.test.ts", "**/*.spec.ts"]
+      "exclude": ["**/*.test.ts", "**/*.spec.ts"],
+      "newMachineDir": "src/machines"
     }
   ]
 }

package/schemas/{xstate-json.schema.json → xstate.schema.json}

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://stately.ai/schemas/xstate-json.json",
+  "$id": "https://stately.ai/schemas/xstate.json",
   "title": "XState JSON machine config",
   "description": "Strict JSON subset of an XState machine config that can be passed to createMachine(config). Shorthand string forms are normalized to object and array forms.",
   "$ref": "#/$defs/machineConfig",