Transitions & Pathfinding
How the engine navigates between states to reach a goal
What Is a Transition?
A transition is a connection between states that describes how to move from one to another. If states are the nodes of the model graph, transitions are the edges. Each transition specifies the actions to perform — typing, clicking, waiting — and which states become active or inactive once it completes.
Key Concept: You Name a Destination, Not a Route
You do not script the full sequence of screens to traverse. Instead you declare a target state and let the engine find a path of transitions from the current state to that target — re-planning if the application is not where it was expected.
Pathfinding
Because the model is a graph, reaching a goal is a search problem. Given the currently active state(s) and a set of target state(s), the engine computes an ordered sequence of transitions that connects them.
Shortest-Path Search
The engine treats transitions as weighted edges and searches for a low-cost route from the current state to the target, much like a shortest-path algorithm over a map.
Multi-Target Pathfinding
A goal can be several states at once — e.g. open the search panel and the properties panel and the debug view. The engine finds a single path that reaches all of the requested targets, not just one.
Re-Planning on Drift
After each step the engine verifies the state it actually reached. If reality diverged from the plan, it searches for a new path from where it really is rather than blindly continuing.
Multi-State Activation
A single transition can change more than one state at a time. This mirrors how real interfaces behave — opening a workspace might bring up a toolbar, a sidebar, and a content area together.
A transition can specify:
- States to activate — one or more states that become active together when the transition completes
- States to exit — states that should deactivate, such as a splash screen being replaced
- States that stay visible — for overlays and dialogs that appear without dismissing the screen beneath them
Phased Execution & Rollback
Transitions execute in ordered phases. Splitting execution this way allows the engine to validate before acting and to roll back cleanly if a phase fails, leaving the model in a known state rather than a half-applied one.
- VALIDATE— confirm the transition can run from the current state
- OUTGOING— perform the actions that leave the source state
- ACTIVATE— mark the destination state(s) active
- INCOMING— run any verification or setup for the new state
- EXIT— deactivate states that should no longer be active
If a phase fails, the engine rolls back, preserving the prior state instead of leaving a partial transition applied.
Note: Multi-target pathfinding, multi-state activation, and phased execution come from the open-source MultiState library. For the step-by-step of authoring transitions in the builder, see State Transitions.