Vertepnyk

The puppeteer's workbench

A vertepnyk (вертепник) is the puppeteer who builds the vertep box and runs the show. If a Vertep chart is the stage, with the slots its puppets move along, Vertepnyk is the bench where you cut the slots and try the play.

It reads and writes the same files Vertep runs: *.scxml and *.vt.yaml. The text is the source of truth. Every edit on the canvas becomes a minimal patch to the file, so comments and formatting survive and a git diff shows only what you changed. Layout is stored inline, in a layout namespace Vertep reserves for formatting, so moving a box never changes what the chart does.

Validation and simulation run on Vertep's interpreter, compiled to WebAssembly. The designer never computes a transition itself, so what you see in the simulator is what production runs.

What it does

• Draw and edit atomic, compound, parallel, final and history states and their transitions; the datamodel and executable content go in an inspector beside the canvas.
• Validate as you type, with located diagnostics from Vertep and the chart's version IRI, the hash that names its behaviour.
• Simulate: send events with payloads, watch the active configuration and the context, and step forward, step back, travel through the run or fork it.
• Export the canvas as SVG.
• Work offline: nothing is sent over the network.

VS Code

Install Vertepnyk from the VS Code Marketplace, or:

code --install-extension pavlyshyn.vertepnyk-vscode

Cursor, VSCodium and other VS Code builds install it from Open VSX, and the .vsix is in the release. Right-click a chart and choose Open With… › Vertepnyk Designer, or set vertepnyk.defaultEditor to designer.

Obsidian

The listing in Obsidian's community directory is pending. Until then, download vertepnyk-obsidian-0.1.0.zip and unpack it into your vault's .obsidian/plugins/ folder, so the files sit in .obsidian/plugins/vertepnyk/. Then enable Vertepnyk under Settings › Community plugins. The plugin is self-contained, desktop-only, and tested in Obsidian 1.14.

Desktop app

For macOS (Apple silicon and Intel): Vertepnyk-0.1.0-universal.dmg. The app is not notarized by Apple yet, so the first time, open it with right-click › Open, or allow it under System Settings › Privacy & Security. A .zip of the same app and checksums are in the release. Windows and Linux builds come from source for now.

From source

git clone https://github.com/Volland/vertepnyk
cd vertepnyk
pnpm install
pnpm build
pnpm dev                                        # the web shell in a browser
pnpm --filter vertepnyk-vscode run package      # the VS Code extension
pnpm --filter vertepnyk-electron run dist       # the desktop app for this OS

Building needs Node.js 22 and pnpm. Until @vertep/web is on npm, the workspace links Vertep's JavaScript packages from a sibling checkout; the repository's README explains how.