Statecharts: hierarchical state machines
statecharts.dev
statecharts.dev
I created XState, a JS/TS library for authoring, executing, and visualizing state machines/statecharts: https://github.com/statelyai/xstate
I've been working on it for 10+ years. The main thing I've learned is that statecharts are most valuable when they're treated as executable behavior, not just documentation.
That doesn't mean you need to use them everywhere or model everything with them. They're most useful when you have behavior where the answer to "what happens next?" depends on both the current state & the event. A statechart can act as an oracle for questions like: "Given I'm in this state, when this event happens, what is the next state, and what effects should run?"
I'm close to releasing an alpha of the next major version of XState, focused on better ergonomics, type safety, and composability, as well as a new visualizer/editor.
There's also an open-source basic statechart visualizer here: https://sketch.stately.ai
For the formal/spec side, SCXML is worth reading: https://www.w3.org/TR/scxml
Also worth reading the original paper by David Harel: https://www.weizmann.ac.il/math/harel/sites/math.harel/files...
I used it with lit.js to help with a drawer-like navigation component that reacts to page width and has many props and internal states. I can't even think how horrible it'd have been without XState. Thank you very much!
In a conventional FSM yes but not a statechart. Statecharts support parallel regions within a single state. You’d have 3 regions for your example: one waiting for each person. There would be 4 states total: one to wait on each person, each in its own region, plus the superstate. The superstate would exit when all 3 “waiting for person <x>” sub states exited, independent of their sequence.
I’m with you on Petri nets though, very helpful for modelling concurrent behaviour.
This was a talk I gave at Laracon that was my stab at distilling my thinking about State Machines, State Charts etc.
If this is the first time you're hearing about Statecharts, I highly recommend the book "Constructing the user interface with statecharts" by Ian Horrucks (https://archive.org/details/isbn_9780201342789/mode/2up) which yes, is from 1999, but probably the best introduction for how to actually apply and use Statecharts.
Yes, I stumbled upon statecharts checking out this Godot plugin: https://github.com/derkork/godot-statecharts
I often have my AI code output one just to make sure my logic feels more sound. Along with mermaid charts if I need to toy around or drop into stately for more power.
I've had models produce very reasonable Mermaid diagrams that matched the intended design but not the actual program. It felt helpful until I realized I was reviewing the plan twice and the implementation zero times.
For PRs I'd rather render the diagram from the executable state machine itself — at least then drift in the chart means drift in behavior, and you can't review one without the other.
It'll take some time for those apps/tools to realize the full potential of statecharts, but it's a good start.
Naturally, as the author notes, we are using states in our programs. Three kinds at least
- current program state in the complex space-of-states the program can have - most properties (and vars) are expect to undergo several states, and enumerable denotes a state. - every program traversing a graph for something, essentially runs a state machine of some sort
Indeed a user interface can benefit from having a FSM run it, given interfaces guide the end-user through predefined states from which he navigates into other states (which show/hide a set of widgets and wire them with data).
"inputs" can refer to just current and future inputs --- or it refers to the totality of inputs, including the inputs leading up to "here".
in the latter interpretation the machine is perfectly deterministic. and the "deep history" pointer simply is part of the state machine.
I’m essentially thinking of H’ as a write-ahead-log prefixing any node
What I'm solving for is AI-generated diagrams are usually one-shot: Mermaid/SVG/PNG gets emitted, but there’s no durable diagram state to update, validate, diff, or reuse.
Zindex makes the diagram itself structured state. Agents use a Diagram Scene Protocol (DSP) to patch nodes, edges, groups, relationships, constraints, and revisions; Zindex handles validation, layout, rendering, versioning, and storage.
So for Temporal/DBOS/Restate/Cloudflare Workflows, I’d imagine Zindex sitting beside the durable execution engine: the engine remains the source of truth for execution, while Zindex maintains the persistent, inspectable visual model derived from code or execution history.
ETL State Chart and Hierarchial FSM https://www.etlcpp.com/state_chart.html and https://www.etlcpp.com/hfsm.html
Quantum Leaps https://www.state-machine.com
I've used them primarily in safety-critical systems where complexity, timing and the ability to effectively verify behaviour is obviously important. Being able to separate the decision-making from the actions is a great aid. Having to strip back the decision making to "what do I do next" when I'm in this state and this event occurs is a bit different to how most programs are structured, but really does aid separation and makes it easy to reason about behaviour under different conditions.
state charts (FSM with history pointers)
pushdown automaton (FSM with a stack)
turing machine (FSM with a tape)
the terminology is well established.
Having visual understanding of state is becoming increasingly important for AI generated code you don't nearly understand as well as the human variety.
It seems many still favor store based reactivity state in frontend frameworks.
I contribute to it being the default so why change and because libraries like xstate are far more difficult to learn the syntax and are more verbose. But with AI that's hardly an issue, so I wonder if there is more to it I don't see and we just haven't seen the state chart reach it's peak yet.
But at the same time, frontier models are very good at writing XState.
It feels bad because I know your team was working so hard pre AI to make state machines more accessible and bring such a powerful concept to the world.
I know it didn't pan out exactly, but I really want durable execution state machines that exceed workflows one day.
I keep thinking to myself can I enforce my AI layer to have some deterministic durable state machine running it and I'm not deep enough on them from a creator/author perspective to answer that question like you, but keep us posted on the changes.
A general framework is I think more rarely useful.
Unreal Engine is a popular game engine and it seems to contain dozens of different state machine frameworks.
> A statechart is a state machine where each state in the state machine may define its own subordinate state machines, called substates
> The primary feature of statecharts is that states can be organized in a hierarchy: A statechart is a state machine where each state in the state machine may define its own subordinate state machines, called substates. Those states can again define substates.
Created StateKit for ObjC/Swift some time ago, it’s been production tested in some very large apps: https://github.com/sghiassy/StateKit
Such a cool data structure
More recently, I avoided some early SwiftUI bugs by modeling some of the iOS app interaction using Statecharts, in an ASCII art comment in the code, and implementing that.
https://doc.qt.io/qt-6/qtstatemachine-overview.html
Qt also supports W3's State Chart XML (SCXML)
It has been a great experience so darn it makes processes very resilient against change and very easy to come back to after years.
The library is open source too:
The statemachine itself also forces you to think about which transitions between which states are possible and whst you may need to consider when such a state change happens.
Then I googled for "hierarchical state machines" and found statecharts. These two ideas are somewhat similar so here are my 2cents. Imo more software should use hierarchies of state machines to fight the worst class of bugs with non-determinism.
I blogged[0] a bit about my experience with Finite State Machines, and about the architecture we landed on with XState and Mastra (although since publishing we have swapped to Pipecat).
[0] - https://blog.davemo.com/posts/2026-02-14-deterministic-core-...
i gave it some time, but that's not a good site. it takes forever to explain simple things and never gets to any important and novel idea. i gave up when it turned out that it's just a tree of state machines - for some reason called a 'chart' despite not apparently having any chart-like property.
ugh. it's just a doodling exercise for architecture astronauts. OMG it actually, unironically references UML and has Statechart XML!
flipping the bit on this one
2. I did come across Tinyfsm (https://digint.ch/tinyfsm/). Any thoughts on that?
What's better than graphically designing your HSM, simulating it vs all kinds of scenarios to verify it, and auto generating the code?
> It’s easier to understand a statechart than many other forms of code.
There's a lot of arguable quantifiers here, but when I was started at https://gadget.dev (no longer working there), we started with hierarchical statecharts as a way for users to specify their behaviour (with the ability to customize transitions with code snippets). No matter what we did, users just found it incredibly confusing. This was with a customer based that had decent spread across the "how technical are you" spectrum.
Did we do a poor job of introducing it to the user? Maybe. We were forced to switch everything over to flat code though.
> As complexity grows, statecharts scale well.
I think there's a big asterisk on this one, likely. I had to undo a lot of unfortunate statechart code that was introduced for some of the backend of gadget, and I consider myself a pretty good programmer. Perhaps it's just the difference in paradigm, or the accidental complexity of how we worked with xstate, but I reduced 1000+ lines of very hard to read and extend statechart code to a few hundred lines of imperative code, with some hardcoded states. It was actually easier and faster for me to do this than fix bugs that existed somewhere in there (I tried, and failed).
Every engineer at the company (it's a small company :P) agreed that it was substantially easier to read and understand.
I think this perhaps echoes things said elsewhere here, like dflock's comment on the boundary between "xstate" and "not xstate".
All that being said, I'll restate: I love the idea of statecharts, I just have scars from dealing with them. I think they were perhaps applied in situations where the benefit was low, and the overhead of understanding the bits and bobs of xstate was too high of a cost for any perceivable benefit it may have offered.
> It’s worth noting that you’re already coding state machines, except that they’re hidden in the code.
I will say that this is a great point that may often be overlooked.
When I interview candidates, one problem I enjoy doing (and they do too!) is "let's try building vim" problem. We build out a few basic commands — move left, move right, replace character under cursor — to edit a string of text. The candidates that do the best often see how parsing can be encoded in a state machine and plan with that in mind. They perhaps still just encode it as if/else statements with a state variable, but that still gives the better outcome. Something like this:
0-9
---------
| |
| v hj
|-- (number N) -----> move N spaces
|
| r
------> (read char c) ---> replace N characters with c
These render in GitHub flavoured markdown
Is it clean? Not always, it gets messy. On the other hand it is deterministic and traceable to specifications. Specifications as state machines can be easier understood and shared than raw code or raw prose.
I also think more effort is needed to synthesize a clean set of state machines with hierarchy for a system at scale and I'm sure there are times when that effort is not warranted.
Just don’t use one state chart for everything. Just like any data structure, use multiple of them scoped appropriately
Even when I haven't actually used a state machine, I've modelled problems as state machines just to help me think about the system. Thinking in terms of state can often help traditional software designs.