# plusthree for XState users plusthree runs XState v6 statecharts in Rust. If you know XState, you already know the semantics: states, transitions, guards, `after`, `invoke`, history, `onDone`, `onError`. Those work the way XState v6 defines them, and a conformance harness checks that against XState itself. What changes is the shape of the API. Rust has types, no garbage collector and no event loop of its own, so plusthree makes four choices that XState does not: 1. **Patches instead of `assign`.** Context changes are values a transition returns, not mutations. 2. **Effects as data.** Actions don't run inside the machine. A step returns a list of effects, and your code executes them. 3. **The host fires timers.** The kernel has no clock. It tells you when to start and cancel timers, and you tell it when one is due. 4. **Typed events.** Events are a Rust enum, matched by pattern. This guide walks through each, then the patterns an application needs, and ends with the places where plusthree deliberately differs from XState. The runnable examples in [`crates/plusthree/examples`](../crates/plusthree/examples) show everything here in full; each one asserts what it demonstrates. ## Vocabulary | XState | plusthree | | --- | --- | | `setup({ types }).createMachine({...})` | `plusthree::machine! { Name { context: C, events: E, .. } ... }` | | `machineFromJSON(json)` | `Machine::::from_json(&json, ®istry)` (feature `json`) | | machine | `Machine`, built once: `Name::machine()` | | `createActor(machine).start()` | `machine.initial(input, &mut fx)` returns a `Snapshot` | | `actor.send(event)` | `machine.step(&mut snapshot, event, &mut fx)` | | `getNextSnapshot` / `transition` | `machine.transition(&snapshot, event)` | | `snapshot.matches('a.b')` | `snapshot.matches(name::states::a::B)`, a typed handle | | `snapshot.can(event)` | `machine.can(&snapshot, &event)` | | `snapshot.value` | `snapshot.value(machine.def())` | | `assign({ count: ... })` | `Transition::stay().patch(\|p\| p.count(...))` | | `raise`, `sendTo`, `emit`, `log`, `cancel` | `enq.raise`, `enq.send_to`, `enq.emit`, `enq.log`, `enq.cancel` | | custom action `({ context }) => ...` | `enq.action(Fx::Something)`, executed by the host | | `guard: ({ context, event }) => ...` | `guard: \|a\| ...` with `a.context`, `a.event` | | `after: { 1000: 'b' }` | `after: { 1s => b }` | | `delays: { wait: ({ context }) => ... }` | `delays: { wait: \|a\| Duration::... }` | | `isUnhandled` | `Outcome::Unhandled` | | `createActor` with children, `system` | `plusthree::system::System`, or `plusthree::runtime` on tokio | ## Typed events Events are an enum with `#[derive(Event)]`. A variant's name is its event name, as XState sees it in JSON, inspection and wildcards: ```rust #[derive(Event, Clone, Debug)] enum Ev { Inc, // "Inc" Add { n: u32 }, // "Add" #[event(rename = "user.login")] Login { name: String }, // "user.login", matched by "user.*" } ``` `#[event(rename_all = "SCREAMING_SNAKE_CASE")]` renames every variant. In `machine!`, a key in `on` is a pattern. Its bindings are references into the event, in scope in the transition's guard and handlers. A pattern that doesn't cover the whole variant also guards the transition: ```rust on: { Ev::Add { n } => |a, _| Transition::stay().patch(|p| p.count(a.context.count + n)), Ev::Set(0) => idle, // only Set(0) Ev::Set(n) => |_, _| Transition::stay().patch(|p| p.count(*n)), Ev::Inc | Ev::Reset => counting, "user.*" => |a, enq| { /* any user.* event; a.event is the envelope */ }, } ``` Events must be `Clone`: the kernel clones them for `can`, delayed raises and inspection. Put large or non-`Clone` payloads, such as a fetched message body, behind an `Arc`: ```rust enum Ev { Fetched { seq: u32, body: Arc<[u8]> }, ... } ``` Handlers see built-in events (`xstate.after`, `xstate.done.actor`, `xstate.error.execution`, ...) through `a.event`, an `Envelope`: `Envelope::Event(ev)` is a user event, and the other variants are the built-ins. `a.event.event()` returns the user event when there is one. ## Patches instead of `assign` XState computes `assign` during the microstep, against the context from before it, and merges the results after the exit actions, in document order. plusthree does the same with a value: a transition returns a *patch*, the fields it changes. `#[derive(Context)]` on ```rust #[derive(Context, Clone, Default)] struct Ctx { count: u32, query: String } ``` generates `CtxPatch { count: Option, query: Option }` with a setter per field. You use it in three places: ```rust // A transition function: stay and patch. Ev::Inc => |a, _| Transition::stay().patch(|p| p.count(a.context.count + 1)), // A transition to another state, with a patch. Ev::Reset => |_, _| Transition::to(counter::states::IDLE).patch(|p| p.count(0)), // An action (entry, exit, or a transition object's `actions`) returns // `Option`. Inside `machine!` handlers, `Patch` names it. entry: |a, _| Some(Patch::default().count(0).query(String::new())), ``` A shared action written outside `machine!` names the machine: `Patch` (in the prelude), as in `fn reset(a: &Args, enq: &mut Enq) -> Option>`, built with `Patch::::default()`. Use it in the machine as `entry: self::reset`. Patches are data, which is what makes rollback after an error cheap (the kernel applies the inverse patch) and lets tests compare them. **What belongs in context.** Every patch moves values into the context, and cloning a snapshot clones the context. Keep in context the small facts the chart decides on: counters, ids, the current query, flags, a sequence number. Keep big or shared data outside, in your own structs next to the snapshot (a mailbox's messages, a cache, a connection), or share it with an `Arc`. The chart can hold an id or an `Arc` and the host looks up the rest. ## Effects as data In XState an action is a function that runs inside `actor.send`. In plusthree, the handler *enqueues* an effect and returns: ```rust #[derive(Debug)] enum Fx { FetchFolder { account: String }, Notify(String) } entry: |a, enq| enq.action(Fx::FetchFolder { account: a.context.account.clone() }), ``` `step` writes everything the macrostep wants done into an `Effects` buffer, in XState's order: exit actions, then transition actions, then entry actions, then the starts of new children. Each `initial`, `step` and `fire` clears the buffer first, so effects you ignore don't pile up. Your host drains it: ```rust m.step(&mut snap, event, &mut fx); for effect in fx.drain() { match effect { Effect::Action(Fx::FetchFolder { account }) => imap.fetch(account), Effect::Action(Fx::Notify(text)) => ui.toast(text), // Timers: see "The host fires timers" below. Effect::Schedule(timer) => timers.start(timer.key, timer.delay), Effect::Cancel(key) => timers.cancel(&key), _ => {} } } ``` Other effects are `Emit` (`enq.emit`), `Log` (`enq.log`), `Spawn`, `Start`, `Stop` and `SendTo` (children and messages, carried out by an actor system), and `DeadLetter` (a send to a target that doesn't exist). Reuse one `Effects` buffer for a machine instance: it also holds the kernel's scratch space, so a steady-state step allocates nothing. Besides `enq.action`, handlers can `enq.raise(ev)` (an internal event, processed in the same macrostep), `enq.raise_after(ev, delay, Some(id))` and `enq.cancel(id)`, `enq.emit(..)`, `enq.log(..)`, `enq.send_to(target, ev)`, `enq.spawn(child, options)` and `enq.stop(id)`. ## Async I/O The pattern for any request: the chart enqueues the request as an effect, the host runs it however it likes, and the answer comes back as an event. ```rust searching: { entry: |a, enq| { let seq = a.context.seq + 1; enq.action(Fx::Search { seq, query: a.context.query.clone() }); Some(Patch::default().seq(seq)) }, on: { // Only the answer to the request in flight counts. Ev::Results { seq, hits } => { target: idle, guard: |a| *seq == a.context.seq, .. }, Ev::Failed { seq } => { target: retrying, guard: |a| *seq == a.context.seq, .. }, }, }, ``` The sequence number makes a late answer to an older request harmless. The host can run the request on a thread, a tokio task, or a test double; the chart doesn't know. The [`mail_search`](../crates/plusthree/examples/mail_search.rs) example does this end to end. `invoke` is the other way, and it is XState's: a state invokes a child, and `on_done`/`on_error` handle its typed output or error. A child is an *actor*, so it needs something to run it: [`plusthree::system`](#actors) or the tokio runtime. If you run machines yourself inside your app's own state, use effects and events. If you want XState's actor model (children that outlive a request, per-entity actors, `sendTo` between them), use invoke and spawn with the system. ## The host fires timers The kernel has no clock. When a state with `after` is entered (or a handler calls `enq.raise_after`), the step returns `Effect::Schedule(timer)` with a `timer.key` and a `timer.delay`, and records the timer in the snapshot. When the state is exited first, the step returns `Effect::Cancel(key)`. When the delay has passed, you call: ```rust m.fire(&mut snap, &key, &mut fx); ``` The host keeps its own timer handle for each pending timer: a tokio `AbortHandle`, a GUI toolkit's timeout id, or a deadline. `plusthree::host::Driven` does the bookkeeping. It holds the machine, the snapshot, the effects buffer and the pending timers with your handle `H` for each. `step` runs an event, `fire` a due timer and `stop` stops the machine on teardown; each takes your `host::Scheduler`, which starts a timer (`schedule(delay, token) -> H`, whose callback hands `token` to `fire`) and stops one (`cancel(H)`). The timer effects never reach you: they become calls to your scheduler. Your other effects stay in `effects()`, in order, until the next call. Starting and stopping usually need the same context, such as a GUI toolkit's or a transaction's, so implement `Scheduler` on it, or on a thin wrapper around a borrow of it, and pass `&mut ctx`: ```rust use plusthree::host::{Driven, Scheduler, TimerToken}; impl Scheduler for Ui { fn schedule(&mut self, delay: Duration, token: TimerToken) -> TimeoutId { self.timeout(delay, move |app| app.mail_timer(token)) // calls back with `token` } fn cancel(&mut self, id: TimeoutId) { self.cancel_timeout(id); } } // Driven<'static, Mail, TimeoutId> let mut mail = Driven::start(Mail::machine(), input, &mut ui)?; mail.step(event, &mut ui); for effect in mail.effects_mut().drain() { /* your actions, as above */ } // When the host's timer callback runs with `token`: mail.fire(token, &mut ui); // On teardown: stops the machine and every timer still running. mail.stop(&mut ui); ``` When the two need nothing in common, `host::schedule_with(schedule, cancel)` makes a scheduler of two closures, typed from its signature. With tokio, `schedule` spawns a task that sleeps and sends the token on a channel, and returns its `AbortHandle`; `cancel` aborts it: ```rust let timers = || schedule_with( |delay, token| { let tx = tx.clone(); tokio::spawn(async move { sleep(delay).await; let _ = tx.send(token); }).abort_handle() }, |handle| handle.abort(), ); mail.step(event, timers()); ``` With a simulated clock the handle is the deadline, `schedule_with(move |delay, _| now + delay, |_| {})`: `timers()` lists each pending timer's token and handle, so the clock fires the earliest due one. Two stock schedulers cover the rest. `host::NoTimers` is for a machine that starts no timer, or for `Driven::start` before your scheduler exists when the initial states have none; it panics if a timer starts. For tests, `host::Recorder` records each timer started and stopped, with handles counting up from 1, lists the ones running, and delivers one with `recorder.fire(&mut driven, token)` (or `recorder.fired(token)` after calling `driven.fire` yourself). `recorder.take()` returns the starts and stops since the last call, in order, to check what one step did. The netting covers what one macrostep can produce. A state re-entered with `reenter: true` yields `Cancel(k)` then `Schedule(k)`: the old handle is stopped and a new timer started with the full delay. A state entered and left again in the same macrostep, as by `always`, yields `Schedule(k)` then `Cancel(k)`: nothing is started. Each start carries a fresh `TimerToken`, and your timer callback reports the token, not the key. On an event loop, a timer's callback can already be queued when a step cancels or re-arms its key. That callback carries the old token, so `fire` returns `None`, runs nothing and leaves the effects empty, and the new timer is not fired early. `Driven` is built on `plusthree::host::Timers`, the map from each pending timer to your handle, which you can use directly if you keep the snapshot yourself: after each `step` or `fire`, `timers.apply(&mut fx, &mut ops)` takes the timer effects out of the buffer and nets them into `TimerOp::Arm { delay, token, .. }` and `TimerOp::Disarm(handle)`; give each new handle to `timers.armed(token, handle)`, and when a callback runs pass its token to `timers.fired(token)`, which returns the key for `m.fire` or `None` for a stale callback. A host that starts its timers later than it steps, say after a transaction commits, calls `armed` when the handle exists, in any order: when a step has cancelled or re-armed the key in the meantime, `armed` returns the handle for you to stop. Scheduling a key that is already pending replaces it. In tests, a simulated clock makes timers instant and deterministic; the [`traffic_light`](../crates/plusthree/examples/traffic_light.rs) example has a complete host loop with `Driven`, using each deadline as the handle. Delays can be fixed (`after: { 500ms => b }`, with `ms`, `s`, `min`, `h`) or named functions of the snapshot, evaluated when the timer is scheduled: ```rust delays: { debounce: |a| a.context.debounce, // from context backoff: |a| Duration::from_millis(250 << a.context.failures.min(4)), }, states: { typing: { after: { debounce => searching } }, retrying: { after: { backoff => searching } }, } ``` **Debounce.** Re-arm a timer on every keystroke by re-entering its state. `reenter: true` exits and enters the state even when it is already active, which cancels the old timer and schedules a new one: ```rust on: { Ev::Key { query } => { target: .typing, reenter: true, actions: |_, _| Some(Patch::default().query(query.clone())), }, }, ``` **Back-off.** Count failures in context and let a delay function read the count, as above; a guard on the failure count decides when to give up. **Persisting timers.** Because the snapshot lists its pending timers, persisting a machine persists its timers. `plusthree-json` asks for each timer's deadline on your clock when persisting and returns each timer's remaining delay when restoring, so a restored timer fires when it would have (DEVIATIONS.md D19). Use the same clock for both, such as time since the Unix epoch. Wrap the restored snapshot in `Driven::new(machine, snapshot)` and call `restore(restored.timers, scheduler)`, which starts each timer with its remaining delay (and stops whatever was pending before). When your handle is a deadline, `|k| driven.timers().handle(k).copied()` is the deadline function persisting asks for. ## Guards and transition functions A guard is a function of the snapshot and event; `guard: self::is_valid` names a function. A guard closure sees the bindings of its `on` pattern (`Ev::Swipe { distance } => { target: armed, guard: |a| *distance > 40 }`). A named function gets `a.event`, the `Envelope`; `a.event.event()` returns the typed event when it is one: ```rust fn far_enough(a: &Args) -> bool { matches!(a.event.event(), Some(Ev::Swipe { distance }) if *distance > 40) } ``` A list of candidates is tried in order, and the first enabled one wins, as with XState's guarded transition arrays: ```rust Ev::Send => [ { target: sending, guard: self::is_valid }, { actions: |_, enq| enq.action(Fx::Warn("add a recipient")) }, ], ``` A transition function decides everything at run time. It returns a `Transition`, `Option`, `()`, or any of those in a `Result`. `()` counts as `None`. Returning `None` or `()` without enqueuing anything declines the event, and the search continues with the parent state, as in XState; if it enqueued something, it takes a targetless transition. To take the event without enqueuing anything, or to change the context, return `Transition::stay()` (with `.patch(..)` for the context). It runs exactly once per selection (DEVIATIONS.md D2), so side effects through `enq` are safe. ### Handling an event only in some substates Declining is how a statechart says "only here". A reader re-asks for its thread on every redraw, but should start settling only when it is idle. Put that handler on `idle` and let it decline everything else; the parent handles what is left, here a switch to another thread: ```rust open: { initial: idle, on: { // Reached only when no active child took the event. Ev::Show { thread, .. } => |a, _| (a.context.thread != *thread) .then(|| Transition::to(reader::states::open::IDLE).reenter(true)), }, states: { idle: { on: { Ev::Show { thread, want } => |a, _| (a.context.thread == *thread && *want) .then(|| Transition::to(reader::states::open::SETTLING)), }, }, settling: { after: { 250ms => fetching } }, fetching: {}, }, }, ``` While `settling` or `fetching`, a repeated `Show` for the same thread is unhandled, so the settle timer is not restarted. When a decision needs the whole picture in one place, a function can also ask which states are active with `a.matches(reader::states::open::IDLE)`, as `Snapshot::matches` does for a snapshot. ## Errors A handler fails by returning `Err`. The machine's error type is the header's `error:` key: ```rust plusthree::machine! { Mailbox { context: Ctx, events: Ev, effects: Fx, error: MailError } ... Ev::Received(raw) => |a, enq| { let msg = parse(raw)?; Ok(Transition::stay().patch(|p| p.received(a.context.received + 1))) }, ``` As in XState, an error aborts the whole macrostep: its patches and effects are discarded. If an active state declares `on_error`, the macrostep reruns from the snapshot before the event with `xstate.error.execution` (`Envelope::ErrorExecution`), and `on_error` handles it. Otherwise the step returns `Outcome::Errored`, `snapshot.status()` is `Status::Error`, and `snapshot.error()` holds the error. An errored machine cancels its timers and stops its children. A handler that always fails needs its return type spelled out, because Rust cannot tell which `Result` it returns: ```rust Ev::Corrupt => |_, _| -> Result<(), MailError> { Err(MailError::Storage) }, ``` Panics are not caught (DEVIATIONS.md D3). See the [`errors`](../crates/plusthree/examples/errors.rs) example. ## Parallel states and history These work as in XState. A history state returns to what an overlay was opened over: ```rust window: { initial: main, on: { Ev::Settings => settings }, states: { main: { type: parallel, states: { view: { .. }, sync: { .. } } }, back: { type: history, history: deep, target: main }, }, }, settings: { on: { Ev::Close => window.back } }, ``` ## Actors Children are declared as an enum with `#[derive(Children)]`, one variant per kind of child, whose fields are its input. The derive generates enums for the children's typed outputs, so `on_done` matches on them: ```rust #[derive(Children, Clone, Debug)] #[children(message = Msg)] // what this machine sends to other actors enum Jobs { #[child(output = u32)] Fetch(String), } syncing: { invoke: { src: |a| Jobs::Fetch(a.context.account.clone()), id: "fetch", on_done: { JobsOutput::Fetch(n) => { target: idle, actions: .. } }, on_error: idle, timeout: { 30s => idle }, }, }, ``` Spawn from a handler with `enq.spawn(Kids::Account(name), SpawnOptions::new().id(name))`, and address children with `enq.send_to(Target::Child(id), ev)` or the parent with `Target::Parent`. The kernel only describes children (`Effect::Spawn`, `Start`, `Stop`, `SendTo`). `plusthree::system::System` runs a whole tree: machines, async jobs (`AsyncActor`, XState's `fromPromise`) and callbacks, with one FIFO message queue and timers in system time. Like the kernel, it is a pure reducer: the host sends events, advances time, settles async jobs and drains `Notice`s. `plusthree::runtime` (feature `runtime`) drives one on tokio with real time and real futures. An actor system speaks one set of value types, its `Universe`. A JSON machine needs no glue: `plusthree::json::json_actor(machine, input, spawn)` runs it as an actor of `JsonUniverse`, where every value is a `serde_json::Value` as in XState, and `spawn` creates the logic of each child it invokes or spawns: ```rust use plusthree::json::{json_actor, JsonUniverse}; let root = json_actor(Arc::new(machine), None, |child| match child.src.as_str() { "fetch" => Box::new(AsyncActor::new(plan_for(child), async_snapshot)), src => panic!("no actor named {src}"), }); let mut sys = System::new("mail", root, Duration::ZERO)?; ``` A typed machine joins a system through a `Bridge` that converts its events, outputs and effects, and creates the actors of the children it spawns. For 0.1 you write that bridge yourself; the [`actor_system`](../crates/plusthree/examples/actor_system.rs) and [`tokio_runtime`](../crates/plusthree/examples/tokio_runtime.rs) examples share one in [`support/accounts.rs`](../crates/plusthree/examples/support/accounts.rs), with one actor per mail account. ## Watching machines in the Stately Inspector With feature `inspect`, machines show up live in the [Stately Inspector](https://stately.ai/docs/inspector), as an XState app inspected with `@statelyai/sdk`'s `createInspector` does: the actors, the events they process, and each machine's diagram with its active states and the transitions just taken highlighted. `Inspector::serve(addr)` starts a local inspection relay on a background thread; open `inspector.url()` in Chrome. The viewer is Stately's hosted page; it connects back to the relay on your machine, so no account is needed and inspection data stays local. The URL carries a random room id that the relay checks. Chrome may ask whether `sky.stately.ai` may reach your local network: allow it. ### Machines your host steps A host that owns its snapshots shows each machine with `inspector.actor(id, machine, &snap)`, and steps it through the `ActorHandle` it returns. `Report::step` and `Report::fire` step the machine and report the macrostep in one call: the event's name, the snapshot, the transitions taken (highlighted in the diagram) and the actions. ```rust,ignore use plusthree::inspect::{Inspector, Report}; let inspector = Inspector::serve("127.0.0.1:4242")?; println!("{}", inspector.url()); // An account has no machine of its own: a group, with its machines in it. let account = inspector.group("work"); let mut sync = account.child("sync", Sync::machine(), &snap); let mut draft = account.child("draft", Compose::machine(), &draft_snap); sync.step(m, &mut snap, event, &mut fx); // shows the event's name sync.fire(m, &mut snap, &key, &mut fx); // shows `xstate.timer` ``` Where inspection is optional, keep an `Option`: the same `step` and `fire` calls work on it, and with `None` they are the machine's plain `step` and `fire`. `Option` is also an `Observer`, so `m.step_with(.., &mut self.actor)` covers both cases for a host that steps the machine itself and calls `handle.stepped(event, &snap)` after. A machine run by `host::Driven` takes the handle as its observer instead, and reports every `step`, `fire` and `stop` itself: ```rust,ignore use plusthree::host::Driven; // Start with the observer type it keeps, so the kernel is compiled once // for this machine; the handle needs the snapshot, so it starts as `None`. let mut sync: Driven<_, _, Option> = Driven::start_with(Sync::machine(), (), &mut ui, None)?; *sync.observer_mut() = inspector.as_ref().map(|i| i.actor("sync", Sync::machine(), sync.snapshot())); sync.step(event, &mut ui); // shows the event's name if let Some(a) = sync.observer() { a.move_to(&account); } sync.stop(&mut ui); // shows `xstate.stop` ``` By default the viewer gets only what cannot leak: event names, the state, built-in actions (timers, raises, sends, children, logs, emits) by their v6 types, and the machine's own effects as `effect`. Of the context it gets only the fields you mark `#[context(show)]`: ```rust,ignore #[derive(Context, Clone, Default)] pub struct SyncCtx { #[context(show)] unread: u32, // a count, as is #[context(show)] retry_in: Duration, // in milliseconds #[context(show)] phase: Phase, // a #[derive(VariantName)] enum, by variant #[context(show_with = Option::is_some)] token: Option, // whether there is one, not the token subjects: Vec, // not marked: never shown } ``` Flags, numbers, durations, text, `Option`s of those and `#[derive(VariantName)]` enums can be shown; marking a field of another type is a compile error that suggests `show_with`. To name the machine's own effects by their variants, never their data, derive `VariantName` for the effect enum and call `name_effects` with the machine, which ties the naming to the machine's effect type at compile time: ```rust,ignore #[derive(Debug, VariantName)] pub enum SyncFx { Notify { subject: String } } // shows as `Notify` let mut sync = account.child("sync", Sync::machine(), &snap).name_effects(Sync::machine()); ``` For anything else, build the JSON yourself. `show_context` replaces the marked fields, and `show_effects` makes each effect a name or a `{"type", "params"}` object; it panics if its closure takes another type than the machine's effects: ```rust,ignore let mut sync = account .child("sync", Sync::machine(), &snap) .show_context(&snap, |c: &SyncCtx| json!({ "unread": c.unread })) .show_effects(|e: &SyncFx| match e { SyncFx::Notify { .. } => json!({ "type": "notify", "params": { "n": 1 } }), }); // One event with a payload: a string is the event type, an object the // whole event. sync.step_showing(m, &mut snap, event, &mut fx, |e| json!({ "type": e.name(), "folder": "inbox" })); ``` For a `Driven` machine, which steps without a per-call closure, set the event's JSON once per actor with `show_events(|e: &SyncEv| ..)`; like `show_effects`, it panics if its closure takes another type than the machine's events. `id` is the label the viewer shows. `child` nests actors under an actor or a group, and the viewer groups siblings running the same machine (`account, 2 actors`). Dropping a handle or group shows it as stopped, and registering its id again in the same place then replaces it, as when a draft starts again; while it runs, both show. Register a machine when it starts, even before you know where it belongs, and move it there later with `move_to`: into a group, under another handle, or back to the top level with the inspector itself. It keeps its history and children; open viewers redraw it under its new parent. ```rust,ignore // The session signs in before its account exists. let session = inspector.actor("jmap", Jmap::machine(), &snap); // ... later, once the account is known: session.move_to(&account); ``` The [`inspect_host`](../crates/plusthree/examples/inspect_host.rs) example runs two accounts this way, with `host::Driven`. ### Actor systems For a `System`, pass the inspector every notice and register the machines under the names their actors are created with: ```rust,ignore inspector .machine("mail", Mail::machine()) // the root, by its actor id .machine("Account", Account::machine()); // children, by their `src` let ins = inspector.clone(); let (handle, driver) = Driver::new(clock, make_system, move |n| { ins.notice(&n); // ... the host's own handling ... }); ``` A host that drains a `System` itself calls `inspector.notice(&n)` in its drain loop. `machine` exports the machine's MachineJSON for the diagram; pass a JSON-loaded machine as the `JsonMachine` itself, which keeps its action parameters. The universe says how its values look as JSON by implementing `Inspect`: events as `{"type": ..}` objects, and snapshots as v6's `{"status", "value", "context"?}`. `JsonUniverse` already implements it. A typed bridge can publish JSON snapshots with `plusthree::json::snapshot_json(machine, snapshot)`; see the [`inspect`](../crates/plusthree/examples/inspect.rs) example, which runs the mail actors this way. ## JSON and persistence With feature `json`, `Machine::::from_json(&value, ®istry)` loads MachineJSON as XState's `machineToJSON` and Stately Studio produce it. JSON cannot hold code, so the actions, guards, delays and actors it names are bound from a `Registry`; a missing name is a load error at its JSON path. `registry.effect("name")` turns an action into an `Effect::Action(CustomAction)` for the host. Built-in actions (`@xstate.assign`, `@xstate.raise`, ...) run natively. Embedded code (`@code`, `@expr`) is rejected. The other way, `machine.to_json()` (trait `plusthree::json::ToJson`) exports any machine, typed or loaded from JSON, as MachineJSON that XState's `machineFromJSON`, Stately Studio, the visualizer and the Stately Inspector accept: `serde_json::to_string(&Light::machine().to_json())`. Functions become names, so a diagram shows `guard: is_unlocked`. A `machine!` handler written as a path (`guard: self::is_unlocked`) and a function passed to the builder by name keep their function's name; a closure is named after where it sits, such as `door.closed.on.Lock[0].actions`. A transition function shows up as a transition without a target whose one action is its name, since only running it decides where it goes. Design ยง7 lists the rest. `machine.persist(&snapshot, deadline)` writes XState's persisted snapshot format, and `machine.restore(&persisted, now)` reads it back. See [`json_persist`](../crates/plusthree/examples/json_persist.rs). ## Where plusthree differs from XState plusthree follows XState v6 except where XState leaks a JavaScript artifact or has a bug. [DEVIATIONS.md](../DEVIATIONS.md) lists every difference with its reason and the test that checks it. The ones you are most likely to notice: - An infinite eventless loop is cut off after 10,000 microsteps and raises an execution error (D1). - A transition function runs exactly once per selection (D2). - Document order is the written order, also for integer-like JSON keys (D6), and parallel regions always take events in document order (D15). - Final states schedule no timers (D5), and an unrecovered error cancels every pending timer and stops every child (D16). - Actors exchange messages through one FIFO queue, each macrostep running to completion first, as in XState's `systemTransition` (D18). - Restored timers keep their deadlines under any clock (D19). - An error in the initial macrostep is never recovered (D20). ## Gotchas - `machine!` defines types and a module, so invoke it at module level, not inside a function. - On the root, a transition targets children with a leading dot (`on: { Ev::Fault => .broken }`); the macro says so if you forget. - Every state reference is checked at compile time: an unknown target, `initial` or delay name is a compile error on the offending token. - Built-in event names (`"xstate.done.actor.fetch"`) are keys in `on` for one child's events; `out @ "xstate.done.actor.fetch"` binds its typed output.