@statelyai/sdk 0.37.3 → 0.37.4

package/README.md

@@ -464,6 +464,16 @@ from graph data. Source generation is part of the private Editor Sync workflow.
 For pricing and support, contact
 [team@stately.ai](mailto:team@stately.ai).
 
+## Machine JSON schemas
+
+<!-- JSON schema exports from package.json and schemas/ -->
+
+Use `@statelyai/sdk/xstate-v6.schema.json` to validate the `MachineJSON` loader format accepted by XState v6's `createMachineFromConfig`, including `@expr` expressions and `@xstate.*` action objects. It uses JSON Schema draft 2020-12.
+
+This loader format has its own contract: transition `actions` must be arrays, history states require a non-empty fallback `target`, and state `onDone` and root `options` are unsupported. Code-authored `createMachine` configurations and the editor's general `xstate-json` exports can contain fields or shorthand outside this loader format.
+
+`@statelyai/sdk/xstate.schema.json` and `xstate-json.schema.json` continue to describe v5 definitions. The schemas are also available under the `schemas/` export paths.
+
 ## Self-hosting
 
 <!-- self-host configuration from the editor app auth and editor-sync routes -->

package/dist/embed.mjs

@@ -1,5 +1,5 @@
 import "./protocol-M3Zeun3o.mjs";
-import { c as createPendingExportManager, l as settingsWithViewMode, r as createPostMessageTransport, s as createEventRegistry, t as SDK_VERSION, u as toInitMessage } from "./version-Bdi39PxU.mjs";
+import { c as createPendingExportManager, l as settingsWithViewMode, r as createPostMessageTransport, s as createEventRegistry, t as SDK_VERSION, u as toInitMessage } from "./version-BeGmL5w7.mjs";
 import { EDITOR_PROTOCOL_VERSION } from "./editorHostProtocol.mjs";
 
 //#region src/embed.ts

package/dist/index.mjs

@@ -1,10 +1,10 @@
 import { n as StudioApiError, r as createStatelyClient, t as DEFAULT_STATELY_BASE_URL } from "./studio-uGK1kS0n.mjs";
 import { c as createInspectionRoomUrls, d as isEmbedExampleMachine, i as INSPECTION_ROOM_QUERY_PARAM, l as getInspectionRoomId, m as resolveInspectorSettings, n as EMBED_DOCUMENT_LIMITS, o as assertEmbedExamples, p as mergeInspectorSettings, r as INSPECTION_PROTOCOL_VERSION, s as createInspectionActorId, t as EMBED_DOCUMENT_LANGUAGES, u as isEmbedExample } from "./protocol-M3Zeun3o.mjs";
-import { i as createWebSocketTransport, r as createPostMessageTransport } from "./version-Bdi39PxU.mjs";
+import { i as createWebSocketTransport, r as createPostMessageTransport } from "./version-BeGmL5w7.mjs";
 import { EDITOR_PROTOCOL_VERSION } from "./editorHostProtocol.mjs";
 import { createStatelyEmbed } from "./embed.mjs";
 import { createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter } from "./assetStorage.mjs";
-import { n as createStatelyInspector, t as createInspector } from "./inspect-C2F95TDZ.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-CGMew487.mjs";
 import { createAuthorizationHeader, getCredentialToken } from "./auth.mjs";
 import { buildAuthorizeUrl, createPkcePair, discoverAuthorizationServer, discoverProtectedResource, exchangeCodeForToken, refreshToken, registerOAuthClient } from "./oauth.mjs";
 import { StatelyApiError, createStatelyApiClient, createStatelyApiUrl } from "./api.mjs";

package/dist/{inspect-C2F95TDZ.mjs → inspect-CGMew487.mjs}

@@ -1,5 +1,5 @@
 import { c as createInspectionRoomUrls, l as getInspectionRoomId, m as resolveInspectorSettings, p as mergeInspectorSettings, r as INSPECTION_PROTOCOL_VERSION } from "./protocol-M3Zeun3o.mjs";
-import { a as assertEmbedDocuments, c as createPendingExportManager, i as createWebSocketTransport, n as inspectionRuntime, o as assertEmbedPanels, s as createEventRegistry, t as SDK_VERSION } from "./version-Bdi39PxU.mjs";
+import { a as assertEmbedDocuments, c as createPendingExportManager, i as createWebSocketTransport, n as inspectionRuntime, o as assertEmbedPanels, s as createEventRegistry, t as SDK_VERSION } from "./version-BeGmL5w7.mjs";
 
 //#region src/openBrowser.ts
 async function openBrowser(url) {

package/dist/inspect.mjs

@@ -1,5 +1,5 @@
 import "./protocol-M3Zeun3o.mjs";
-import "./version-Bdi39PxU.mjs";
-import { n as createStatelyInspector, t as createInspector } from "./inspect-C2F95TDZ.mjs";
+import "./version-BeGmL5w7.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-CGMew487.mjs";
 
 export { createInspector, createStatelyInspector };

package/dist/{version-Bdi39PxU.mjs → version-BeGmL5w7.mjs}

@@ -378,7 +378,7 @@ function createWebSocketTransport(options) {
 
 //#endregion
 //#region src/version.ts
-const SDK_VERSION = "0.37.3";
+const SDK_VERSION = "0.37.4";
 function inspectionRuntime() {
 	if (typeof window !== "undefined") return "browser";
 	if (typeof process !== "undefined" && process.versions?.node) return "node";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/sdk",
-  "version": "0.37.3",
+  "version": "0.37.4",
   "license": "MIT",
   "bin": {
     "stately-sdk": "./dist/bin.mjs"
@@ -74,7 +74,9 @@
     "./editor-host-protocol": {
       "types": "./dist/editorHostProtocol.d.mts",
       "import": "./dist/editorHostProtocol.mjs"
-    }
+    },
+    "./xstate-v6.schema.json": "./schemas/xstate-v6.schema.json",
+    "./schemas/xstate-v6.schema.json": "./schemas/xstate-v6.schema.json"
   },
   "dependencies": {
     "@statelyai/graph": "^2.1.0"
@@ -82,19 +84,17 @@
   "devDependencies": {
     "@types/json-schema": "^7.0.15",
     "@types/ws": "^8.18.1",
+    "ajv": "8.20.0",
     "jsdom": "^27.4.0",
     "tsdown": "0.21.0-beta.2",
-    "vitest": "^3.2.4",
-    "xstate-v6": "npm:xstate@6.0.0-alpha.63",
     "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
     "ws": "^8.19.0",
     "xstate": "^5.0.0",
-    "@statelyai/api-contract": "0.5.6",
+    "xstate-v6": "npm:xstate@6.0.0-alpha.63",
+    "@statelyai/api-contract": "0.6.0",
     "@statelyai/graph-tools": "0.9.4"
   },
-  "engines": {
-    "node": ">=22.4"
-  },
   "peerDependencies": {
     "ws": "^8.19.0"
   },
@@ -103,6 +103,9 @@
       "optional": true
     }
   },
+  "engines": {
+    "node": ">=22.4"
+  },
   "scripts": {
     "build": "tsdown",
     "test": "vitest run",

package/schemas/xstate-v6.schema.json

@@ -0,0 +1,674 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "XState v6 machine definition (MachineJSON)",
+  "description": "The JSON-serializable XState machine definition accepted by createMachineFromConfig. Expressions use reserved @ keys: @exprLang on the machine and @expr/@code with optional @lang in value slots.",
+  "$ref": "#/$defs/machine",
+  "$defs": {
+    "jsonSchema": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "eventPayloadSchema": {
+      "allOf": [
+        {
+          "$ref": "#/$defs/jsonSchema"
+        },
+        {
+          "not": {
+            "type": "object",
+            "properties": {
+              "properties": {
+                "type": "object",
+                "required": ["type"]
+              }
+            },
+            "required": ["properties"]
+          }
+        }
+      ]
+    },
+    "expression": {
+      "type": "object",
+      "properties": {
+        "@expr": {
+          "type": "string"
+        },
+        "@lang": {
+          "type": "string"
+        }
+      },
+      "required": ["@expr"],
+      "additionalProperties": false
+    },
+    "code": {
+      "type": "object",
+      "properties": {
+        "@code": {
+          "type": "string"
+        },
+        "@lang": {
+          "type": "string"
+        }
+      },
+      "required": ["@code"],
+      "additionalProperties": false
+    },
+    "resolvable": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/expression"
+        },
+        {
+          "$ref": "#/$defs/code"
+        }
+      ]
+    },
+    "condition": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/resolvable"
+        },
+        {
+          "$ref": "#/$defs/guardObject"
+        }
+      ]
+    },
+    "guardObject": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "params": {}
+      },
+      "required": ["type"],
+      "additionalProperties": false
+    },
+    "actionObject": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true
+    },
+    "action": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/actionObject"
+        },
+        {
+          "$ref": "#/$defs/resolvable"
+        }
+      ]
+    },
+    "actionList": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/action"
+      }
+    },
+    "transitionObject": {
+      "type": "object",
+      "properties": {
+        "target": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "actions": {
+          "$ref": "#/$defs/actionList"
+        },
+        "context": {
+          "type": "object"
+        },
+        "matches": {
+          "type": "object"
+        },
+        "guard": {
+          "$ref": "#/$defs/condition"
+        },
+        "input": {},
+        "description": {
+          "type": "string"
+        },
+        "reenter": {
+          "type": "boolean"
+        },
+        "meta": {
+          "type": "object"
+        }
+      },
+      "additionalProperties": false
+    },
+    "transition": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/transitionObject"
+        },
+        {
+          "$ref": "#/$defs/resolvable"
+        }
+      ]
+    },
+    "transitionOrArray": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/transition"
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/transition"
+          }
+        }
+      ]
+    },
+    "transitionMap": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/transitionOrArray"
+      }
+    },
+    "choiceBranch": {
+      "type": "object",
+      "properties": {
+        "when": {
+          "$ref": "#/$defs/condition"
+        },
+        "target": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "context": {
+          "type": "object"
+        },
+        "input": {},
+        "description": {
+          "type": "string"
+        },
+        "reenter": {
+          "type": "boolean"
+        },
+        "meta": {
+          "type": "object"
+        }
+      },
+      "required": ["target"],
+      "additionalProperties": false
+    },
+    "choice": {
+      "oneOf": [
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/choiceBranch"
+          }
+        },
+        {
+          "$ref": "#/$defs/resolvable"
+        }
+      ]
+    },
+    "invokeObject": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "registryKey": {
+          "type": "string"
+        },
+        "src": {
+          "type": "string"
+        },
+        "input": {},
+        "onDone": {
+          "$ref": "#/$defs/transitionOrArray"
+        },
+        "onError": {
+          "$ref": "#/$defs/transitionOrArray"
+        },
+        "onSnapshot": {
+          "$ref": "#/$defs/transitionOrArray"
+        },
+        "onTimeout": {
+          "$ref": "#/$defs/transitionOrArray"
+        },
+        "timeout": {
+          "$ref": "#/$defs/duration"
+        }
+      },
+      "required": ["src"],
+      "additionalProperties": false
+    },
+    "invoke": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/invokeObject"
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/invokeObject"
+          }
+        }
+      ]
+    },
+    "duration": {
+      "oneOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        },
+        {
+          "$ref": "#/$defs/resolvable"
+        }
+      ]
+    },
+    "initial": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "target": {
+              "type": "string"
+            },
+            "input": {}
+          },
+          "required": ["target"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "actionDefinitions": {
+      "type": "object",
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "$ref": "#/$defs/action"
+          },
+          {
+            "$ref": "#/$defs/actionList"
+          }
+        ]
+      }
+    },
+    "guardDefinitions": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "when": {
+            "$ref": "#/$defs/condition"
+          }
+        },
+        "required": ["when"],
+        "additionalProperties": false
+      }
+    },
+    "delayDefinitions": {
+      "type": "object",
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "duration": {
+                "$ref": "#/$defs/duration"
+              }
+            },
+            "required": ["duration"],
+            "additionalProperties": false
+          }
+        ]
+      }
+    },
+    "schemas": {
+      "type": "object",
+      "properties": {
+        "context": {
+          "$ref": "#/$defs/jsonSchema"
+        },
+        "events": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/eventPayloadSchema"
+          }
+        },
+        "actions": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "params": {
+                "$ref": "#/$defs/jsonSchema"
+              }
+            },
+            "required": ["params"],
+            "additionalProperties": false
+          }
+        },
+        "guards": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "params": {
+                "$ref": "#/$defs/jsonSchema"
+              }
+            },
+            "required": ["params"],
+            "additionalProperties": false
+          }
+        },
+        "actors": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "input": {
+                "$ref": "#/$defs/jsonSchema"
+              },
+              "output": {
+                "$ref": "#/$defs/jsonSchema"
+              },
+              "emitted": {
+                "type": "object",
+                "additionalProperties": {
+                  "$ref": "#/$defs/eventPayloadSchema"
+                }
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "emitted": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/eventPayloadSchema"
+          }
+        },
+        "input": {
+          "$ref": "#/$defs/jsonSchema"
+        },
+        "output": {
+          "$ref": "#/$defs/jsonSchema"
+        },
+        "meta": {
+          "$ref": "#/$defs/jsonSchema"
+        },
+        "tags": {
+          "$ref": "#/$defs/jsonSchema"
+        },
+        "children": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/jsonSchema"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "stateNode": {
+      "type": "object",
+      "properties": {
+        "@exprLang": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "key": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "atomic",
+            "compound",
+            "parallel",
+            "final",
+            "history",
+            "choice"
+          ]
+        },
+        "initial": {
+          "$ref": "#/$defs/initial"
+        },
+        "states": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/stateNode"
+          }
+        },
+        "on": {
+          "$ref": "#/$defs/transitionMap"
+        },
+        "onError": {
+          "$ref": "#/$defs/transitionOrArray"
+        },
+        "after": {
+          "$ref": "#/$defs/transitionMap"
+        },
+        "always": {
+          "$ref": "#/$defs/transitionOrArray"
+        },
+        "choice": {
+          "$ref": "#/$defs/choice"
+        },
+        "route": {
+          "oneOf": [
+            {
+              "type": "object",
+              "properties": {
+                "description": {
+                  "type": "string"
+                },
+                "reenter": {
+                  "type": "boolean"
+                },
+                "meta": {
+                  "type": "object"
+                },
+                "guard": {
+                  "type": "string"
+                },
+                "input": {
+                  "type": "object"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "$ref": "#/$defs/resolvable"
+            }
+          ]
+        },
+        "invoke": {
+          "$ref": "#/$defs/invoke"
+        },
+        "entry": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/actionList"
+            },
+            {
+              "$ref": "#/$defs/action"
+            }
+          ]
+        },
+        "exit": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/actionList"
+            },
+            {
+              "$ref": "#/$defs/action"
+            }
+          ]
+        },
+        "timeout": {
+          "$ref": "#/$defs/duration"
+        },
+        "onTimeout": {
+          "$ref": "#/$defs/transitionOrArray"
+        },
+        "meta": {
+          "type": "object"
+        },
+        "description": {
+          "type": "string"
+        },
+        "history": {
+          "type": "string",
+          "enum": ["shallow", "deep"]
+        },
+        "target": {
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          ]
+        },
+        "output": {},
+        "input": {},
+        "tags": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "context": {
+          "type": "object"
+        },
+        "version": {
+          "type": "string"
+        },
+        "internalEvents": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "schemas": {
+          "$ref": "#/$defs/schemas"
+        },
+        "actions": {
+          "$ref": "#/$defs/actionDefinitions"
+        },
+        "guards": {
+          "$ref": "#/$defs/guardDefinitions"
+        },
+        "actors": {
+          "type": "object"
+        },
+        "delays": {
+          "$ref": "#/$defs/delayDefinitions"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "history"
+              }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "required": ["target"]
+          }
+        },
+        {
+          "if": {
+            "required": ["history"]
+          },
+          "then": {
+            "required": ["target"]
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "machine": {
+      "$ref": "#/$defs/stateNode"
+    }
+  },
+  "$id": "https://stately.ai/schemas/xstate-v6.json",
+  "examples": [
+    {
+      "initial": "idle",
+      "context": {
+        "count": 0
+      },
+      "states": {
+        "idle": {
+          "on": {
+            "INC": {
+              "target": "done",
+              "actions": [
+                {
+                  "type": "@xstate.assign",
+                  "context": {
+                    "count": 1
+                  }
+                }
+              ]
+            }
+          }
+        },
+        "done": {
+          "type": "final"
+        }
+      }
+    }
+  ]
+}