Stately

Stately for VS Code opens the Stately visual editor next to your source file so you can inspect and edit supported state models without leaving your workspace.

Features

• Open every machine in a source file as one visual workspace.
• Open every discovered machine in the current worktree as one workspace.
• Edit state machines visually and save changes back to code.
• Refresh the visual editor from saved source changes and external file reloads.
• Sign in with Stately OAuth when the editor host requires authentication.
• Free accounts open read-only root-level views.
• Export extension logs when visual/code sync fails.
• Preserve existing authoring style where possible.

Supported Files

• XState JavaScript and TypeScript
• JSON and JSONC
• YAML
• Amazon States Language
• Redux Toolkit slices
• Zustand stores
• Mermaid state diagrams and flowcharts

Usage

1. Open a supported file in VS Code.
2. Run Stately: Open Visual Editor from the command palette or editor title menu. The workspace sidebar starts collapsed and contains every machine in the file. A machine's Open Visual Editor CodeLens selects that machine in the existing panel.
3. The editor panel opens with neutral loading status while stored credentials are restored. Browser sign-in appears only when authentication is needed; if a stored OAuth credential is rejected, it is refreshed when possible or replaced through browser sign-in.
4. If prompted, complete browser sign-in. The open panel receives the credential and loads the machine automatically.
5. Save changes in VS Code to update the visual editor, or save in the visual editor to update your source file. Clean external file reloads (for example, a CLI save) also refresh an already-open visual editor without another VS Code save.

Loading, authentication, and the editor follow VS Code's light or dark theme, including high contrast variants. The iframe stays hidden until initialization completes or an editor error is available. Changing the VS Code theme updates the open editor without reloading the machine.

Machines linked with an @statelyai id reuse their Studio presentation. Unlinked machines share a presentation-only overlay with the CLI through .statelyai/local.json. It stores canonical coordinates, colors, annotations, and canvas assets without duplicating inferable machine structure. The extension uses Git's repository-local .git/info/exclude mechanism in Git workspaces and resolves nested workspace folders to the same Git-root sidecar as the CLI. File locking preserves concurrent CLI and extension updates; the file stays local until the machine is linked to Studio. Linked presentation saves preserve Studio structure and use an atomic updatedAt guard. Newly discovered states move only when their generated coordinates overlap restored layout.

Description images and function transitions

State descriptions support Markdown images with adjacent paths such as assets/screen.png. Paths resolve relative to the selected machine file. Only images referenced by that machine's descriptions can load. Absolute paths and file: URLs work within that file's workspace (or its folder for standalone files). PNG, JPEG, GIF, WebP, and AVIF files up to 5 MB load within the editor session; saved Markdown keeps its original paths. HTTP(S) images and embedded raster data images also render. The Details panel's rich-text description editor loads images through the same host resolver; editing and blur preserve the authored Markdown paths. Missing or unsupported images show a fallback. Local file loading requires a local VS Code filesystem; remote source hosts are not yet supported.

XState v6 transition functions can declare local values before literal return targets, including helper calls and guarded returns. The chart shows their targets and context expressions while retaining the original declarations for export. Returned target (target or to), context, and input edits preserve the prelude; edit control flow in source. Export filters can omit returned descriptions and metadata. Genuinely dynamic targets remain marked as unresolved.

For imported XState v5/v6 source, including automatically detected TypeScript files, the Context expression editor retains module helpers, imports, and transition parameters for type checking and hover information. Source hosts retain module declarations when preparing the selected machine's parse payload, so the same scope is available when opening files in VS Code. External module types depend on the editor's available declarations; the panel does not use VS Code's complete TypeScript project or tsconfig.

Commands

• Stately: Open Visual Editor
• Stately: Open Visual Editor (Worktree)
• Stately: Sign In
• Stately: Use API Key
• Stately: Sign Out
• Stately: Export Logs

Stately: Sign In and Stately: Sign Out reflect the credential currently stored by the extension. Stately: Use API Key remains available so the credential type can be changed.

Configuration

• statelyai.editorUrl: base URL for the Stately visual editor embed. Defaults to https://editor.stately.ai.
• statelyai.allowUnauthorizedEditorTls: allow self-signed or otherwise untrusted TLS certificates when the extension calls a non-local configured editor host. Defaults to false. Loopback localhost hosts are handled automatically for local development.
• statelyai.roundTripStatelyMetadata: write supported visual @statelyai.* metadata into source during structural edits. Defaults to false, keeping visual changes in local presentation data.
• statelyai.sourceUpdateStrategy: preserve keeps existing formatting and comments with focused edits; rewrite regenerates the selected machine and may change its formatting and comments. Defaults to preserve.
• statelyai.syncBackend: choose where sync conversion runs, local or remote. Defaults to local.
• statelyai.syncMaxFiles: maximum number of workspace source files included in each sync conversion. Defaults to 150.
• statelyai.syncMaxBytes: maximum total source bytes included in each sync conversion. Defaults to 50000000.

License

Stately Editor is proprietary software. It is free to install, with available features determined by your Stately account and plan. See the bundled LICENSE file or the License tab on the Marketplace listing.