xstate 6.0.0-beta.1 → 6.0.0-beta.2

package/docs/serialization.md

@@ -85,7 +85,7 @@ const machine = machineFromJSON(definition, {
 
 The second argument supplies the runtime sources the definition refers to: `actions`, `guards`, `actors`, `delays`, and `evaluators` for code expressions. Invokes keep their string `src` names, so a machine built this way can be cloned with different actors through [`provide()`](setup-and-provide.md), including when restoring its children. Deserialization still requires an implementation for every referenced actor; provide the initial implementations in the second argument, then override them by name.
 
-Actions in JSON are objects. The built-in vocabulary is `{ type: '@xstate.raise', event, id?, delay? }`, `{ type: '@xstate.emit', event }`, `{ type: '@xstate.assign', context }`, `{ type: '@xstate.cancel', id }` and `{ type: '@xstate.log', args }`. Any other `{ type, params }` object is a custom action resolved against the `actions` sources. Guards are `{ type, params? }` references resolved against `guards`. Two guard types are built in: `{ type: '@xstate.not', params: { guard } }` negates another guard reference or expression, and `{ type: '@xstate.stateIn', params: { stateId: '#id' } }` is true while the state node with that `id` is active (the same check as `snapshot.matches('#id')`). Source names, and the names of `actions`, `guards` and `delays` defined in the JSON, may not start with `xstate.` or `@xstate.`; those prefixes are reserved for built-in names. Because the runtime invokes these references itself, a JSON-referenced guard receives the transition arguments object first and the declared `params` second — unlike code-authored machines, where guards are plain functions called by your own transition code.
+Actions in JSON are objects. The built-in vocabulary is `{ type: '@xstate.raise', event, id?, delay? }`, `{ type: '@xstate.emit', event }`, `{ type: '@xstate.assign', context }`, `{ type: '@xstate.cancel', id }` and `{ type: '@xstate.log', args }`. Any other `{ type, params }` object is a custom action resolved against the `actions` sources. Guards are `{ type, params? }` references resolved against `guards`. Two guard types are built in: `{ type: '@xstate.not', params: { guard } }` negates another guard reference or expression, and `{ type: '@xstate.stateIn', params: { stateId: '#id' } }` is true while the state node with that `id` is active (the same check as `snapshot.matches('#id')`). Source names, and the names of `actions`, `guards` and `delays` defined in the JSON, may not start with `xstate.` or `@xstate.`; those prefixes are reserved for built-in names. Because the runtime invokes these references itself, a JSON-referenced guard receives the transition arguments object first and the declared `params` second. This differs from code-authored machines, where guards are plain functions called by your own transition code.
 
 Machines built from JSON round-trip losslessly. The loader copies the definition, and each serialization returns a fresh copy. Mutating either copy does not change the machine.
 

package/docs/setup-and-provide.md

@@ -140,8 +140,8 @@ Validation can be installed, replaced or disabled by a derived setup. Installing
 
 Where a validation failure surfaces depends on which side of the delivery boundary produced the invalid value:
 
-- **Events arriving from outside the actor** — from `actor.send` or from another actor — are rejected at the boundary when their payload fails its schema, or when the event type is undeclared and `unknownEvents` is `'error'`. The event is never delivered: the actor does not transition, does not error, and no API throws. The rejection is reported to the `onRejectedEvent` dead-letter hook on `createActor` options and as a development-mode console warning. In pure `transition(...)` calls, the snapshot is returned unchanged together with a `@xstate.deadLetter` effect carrying the rejection.
-- **Values the actor produces itself** — input, context, output, emitted events and delayed raised events — error the actor when they fail their schema, and pure `transition(...)`/`initialTransition(...)` throw an `ActorValidationError`. These are machine bugs.
+- **Events arriving from outside the actor** (from `actor.send` or from another actor) are rejected at the boundary when their payload fails its schema, or when the event type is undeclared and `unknownEvents` is `'error'`. The event is never delivered: the actor does not transition, does not error, and no API throws. The rejection is reported to the `onRejectedEvent` dead-letter hook on `createActor` options and as a development-mode console warning. In pure `transition(...)` calls, the snapshot is returned unchanged together with a `@xstate.deadLetter` effect carrying the rejection.
+- **Values the actor produces itself** (input, context, output, emitted events and delayed raised events) error the actor when they fail their schema, and pure `transition(...)`/`initialTransition(...)` throw an `ActorValidationError`. These are machine bugs.
 
 ## Sources on the machine
 
@@ -175,7 +175,7 @@ idle: {
 }
 ```
 
-Named actions and guards are plain functions called with only their params — nothing is injected. Pass values from `context` or the event explicitly. Declare param types on the function itself, or with `schemas.actions` and `schemas.guards` so the params are checked before the implementations exist:
+Named actions and guards are plain functions called with only their params. Nothing is injected. Pass values from `context` or the event explicitly. Declare param types on the function itself, or with `schemas.actions` and `schemas.guards` so the params are checked before the implementations exist:
 
 ```ts
 setup({

package/docs/spawn.md

@@ -46,7 +46,7 @@ The name is checked against `actors`; its required input and returned actor refe
 
 Passing the logic value remains convenient: `enq.spawn(actors.upload, options)`. XState recovers its registered name when possible. Inline unregistered logic may run but cannot be durably persisted.
 
-Spawning with an `id` that a live child of the same parent already uses throws: an address names at most one live actor. Stop the existing child first — an id stopped earlier in the same transition is free to reuse, and a child that completed on its own frees its id for the transition handling its completion. Generate ids from something stable, such as a file or participant id.
+Spawning with an `id` that a live child of the same parent already uses throws: an address names at most one live actor. Stop the existing child first. An id stopped earlier in the same transition is free to reuse, and a child that completed on its own frees its id for the transition handling its completion. Generate ids from something stable, such as a file or participant id.
 
 ## Where you can spawn
 

package/docs/system-transitions.md

@@ -67,8 +67,8 @@ actor's macrostep. Microsteps are atomic; system snapshots contain no unfinished
 microstep or continuation state. A UI presenting individual completed
 microsteps within a macrostep needs a separate tracing interface.
 
-Snapshot actor references are data: `{ $actor, incarnation }`, the same shape as `SerializedActorRef`, with a string `incarnation`. Use `$actor`
-as `actorPath`, for example `snapshot.actors[snapshot.root].snapshot.children.worker.$actor`.
+Snapshot actor references are data: `{ '@actor': address, incarnation }`, the same shape as `SerializedActorRef`, with a string `incarnation`. Use `@actor`
+as `actorPath`, for example `snapshot.actors[snapshot.root].snapshot.children.worker["@actor"]`.
 Paths encode IDs; avoid concatenating unescaped IDs. Replacing an actor at the
 same path allocates a fresh incarnation.
 
@@ -101,7 +101,7 @@ Select a pending timer in a simulator with its current occurrence:
 
 ```ts
 const selected = snapshot.timers.find((timer) => timer.dueAt === 6000)!;
-const [next] = systemTransition(systemLogic, snapshot, selected.source.$actor, {
+const [next] = systemTransition(systemLogic, snapshot, selected.source["@actor"], {
   type: 'xstate.timer',
   occurrence: selected.occurrence
 });
@@ -128,7 +128,7 @@ using the source actor's definition and saved input; the host owns the
 external implementation. Its result reenters as a correlated input:
 
 ```ts
-const [resolved] = systemTransition(systemLogic, pendingSnapshot, effect.source.$actor, {
+const [resolved] = systemTransition(systemLogic, pendingSnapshot, effect.source["@actor"], {
   type: 'xstate.system.effect.result',
   effectId: effect.id,
   event: { type: 'xstate.async.resolve', data: result }
@@ -150,8 +150,8 @@ input, outputs, events and effect arguments are JSON-compatible. Actor reference
 state-node references, errors and named mappers use data markers. Errors retain
 name/message. Undefined properties follow ordinary JSON rules. Cycles,
 unregistered functions, live actors, class instances, symbols, bigint and
-nonfinite numbers are rejected. `$actor`, `$stateNode`, `$error` and
-`$systemMapper` marker shapes are reserved. Logic versions must match on replay.
+nonfinite numbers are rejected. `@actor`, `@stateNode`, `@error` and
+`@systemMapper` marker shapes are reserved. Logic versions must match on replay.
 
 Transition functions, guards and mappers must be deterministic and pure.
 Read external values from input/events and virtual time from `system._clock.now()`.

package/docs/tutorial.md

@@ -430,7 +430,7 @@ Nothing about the machine changes. A UI reads snapshots and sends events.
 
 ```html
 <p id="status">stopped</p>
-<p id="title">—</p>
+<p id="title"></p>
 <button id="play">Play</button> <button id="pause">Pause</button>
 <button id="stop">Stop</button> <button id="previous">Previous</button>
 <button id="next">Next</button> <button id="mute">Mute</button>
@@ -475,7 +475,7 @@ Frameworks work the same way, with a hook or store binding instead of manual sub
 
 You built one machine with context, guards, invoked async logic, hierarchy, parallel regions, delayed events, emitted events and a UI. From here:
 
-- [Statecharts](statecharts.md) — nested, parallel and history states
-- [Actors](actors.md) — spawning, communication and actor systems
-- [Frameworks](frameworks.md) — bindings for React, Vue, Svelte and Solid
-- [Testing](testing.md) — testing machines and the actors that run them
+- [Statecharts](statecharts.md): nested, parallel and history states
+- [Actors](actors.md): spawning, communication and actor systems
+- [Frameworks](frameworks.md): bindings for React, Vue, Svelte and Solid
+- [Testing](testing.md): testing machines and the actors that run them

package/docs/typescript.md

@@ -49,6 +49,12 @@ adding explicit type annotations.
 
 For an actor used in one state, `invoke: s.createInvoke({ src, input, onDone })` infers input and completion output from `src`. Keep the helper inline in `s.createMachine(...)` to also infer that state's narrowed context, ancestor context, state input and transition target requirements. The helper works alongside named actor sources. See [typed inline invokes](invoke.md#typed-inline-invokes).
 
+A bare inline `invoke: { src: logic, onDone }` cannot correlate its source with
+the output; with no registered actor sources it has `event.output: unknown`.
+Use `s.createInvoke(...)` or a source registered in `setup({ actors })` when
+reading the output. This is especially important for generated machine code:
+the bare form cannot infer the output type from `src`.
+
 An async function can be used directly as `src`. Declare `schemas.input`, `schemas.output`, and `schemas.error` on the invoke to type the function and its lifecycle handlers together. Without `schemas.output`, `onDone.event.output` infers from the async return value.
 
 Public schema event keys create typed methods on `actor.trigger`; internal
@@ -84,6 +90,9 @@ When `schemas.events` is declared, each key in an `on` map must match a
 declared event type. Matching wildcards (`'*'`, `'user.*'`) and known reserved
 machine descriptors are allowed; misspelled or invented reserved prefixes are rejected. Without `schemas.events`, any key is accepted.
 
+An empty `schemas.events: {}` means the machine has no public events. Final
+state output callbacks still receive the declared context and input types.
+
 ```ts
 on: {
   toggel: { target: 'active' }

package/docs/xstate-v5-to-v6.md

@@ -79,12 +79,12 @@ Beyond simplifying the action/guard surface, v6 introduces a number of features
 
 ## 1. Inline functions replace action creators
 
-This is the largest change. Action creators (`assign`, `raise`, `sendTo`, `emit`, `log`, `cancel`, `enqueueActions`, `spawnChild`, `stopChild`, `forwardTo`, `sendParent`) are **no longer exported**.
+This is the largest change. Action creators (`assign`, `raise`, `sendTo`, `emit`, `log`, `cancel`, `enqueueActions`, `spawnChild`, `stopChild`, `forwardTo`, `sendParent`) are no longer exported.
 
-In v6, every `entry`, `exit`, and transition handler is a **single function** that receives `(args, enq)` where `enq` is a queue of side effects. The function can also **return** an object that the engine applies after it runs:
+In v6, every `entry`, `exit`, and transition handler is a **single function** that receives `(args, enq)` where `enq` is a queue of side effects. The function can also return an object that the engine applies after it runs:
 
 - **Transition handlers** (`on`, `always`, `after`, `onTimeout`, `onDone`, `onError`) - may return a target, a new `context`, `reenter`, or `meta`.
-- **Entry / exit actions** - may return a new `context` (or `children`). They **cannot** return a `target`; entry/exit cannot transition.
+- **Entry / exit actions** - may return a new `context` (or `children`). They cannot return a `target`; entry/exit cannot transition.
 
 Returned `context` values are patches. XState merges a patch into the current context at the top level (`{ ...context, ...patch }`): omitted keys keep their current values, and a nested object in the patch replaces the current value of that key. If a transition targets a state with a narrower `schemas.context`, the patch type requires the keys needed to satisfy that state's context.
 
@@ -241,7 +241,7 @@ An **entry / exit action** may return:
 | `context`  | shallow context patch       |
 | `children` | replacement children record |
 
-Returning nothing (`undefined`) means "no changes". For transition handlers specifically, returning nothing without calling `enq` also means **the event is treated as unhandled at this state** - useful for inline guarding. A handler that calls `enq` is taken even when it returns nothing, so check the condition first:
+Returning nothing (`undefined`) means "no changes". For transition handlers specifically, returning nothing without calling `enq` also means the event is treated as unhandled at this state - useful for inline guarding. A handler that calls `enq` is taken even when it returns nothing, so check the condition first:
 
 ```ts
 // v6 - guard inline by returning undefined
@@ -306,8 +306,8 @@ runs, because the two exit sets no longer overlap.
 ```ts
 // Parallel state `p` with regions `a` and `b`.
 // Event `t`: `a` reenters itself; `b.b1` moves to `b.b2`.
-// v5 after `t`: { a: 'a1', b: 'b1' } — `b` was reset when `p` was exited.
-// v6 after `t`: { a: 'a1', b: 'b2' } — only `a` was exited.
+// v5 after `t`: { a: 'a1', b: 'b1' }: `b` was reset when `p` was exited.
+// v6 after `t`: { a: 'a1', b: 'b2' }: only `a` was exited.
 ```
 
 Reset the sibling regions explicitly if the v5 behavior was intended: target
@@ -737,7 +737,7 @@ const fetchUser = createAsyncLogic({
 });
 ```
 
-`enq.step(key, exec)` records each step's outcome on the snapshot under `effects[key]`, so on rehydration the step is **not re-executed** - the previous result is replayed. This makes async logic durable across restarts.
+`enq.step(key, exec)` records each step's outcome on the snapshot under `effects[key]`, so on rehydration the step is not re-executed - the previous result is replayed. This makes async logic durable across restarts.
 
 When `timeout` elapses, the logic aborts and rejects with `TimeoutError` (also exported):
 
@@ -942,8 +942,8 @@ on: {
 
 ## 12. Internal events
 
-Events declared in `schemas.internalEvents` can be **raised** internally but
-are **rejected** by the public actor protocol. Wildcard patterns are supported.
+Events declared in `schemas.internalEvents` can be raised internally but
+are rejected by the public actor protocol. Wildcard patterns are supported.
 
 ```ts
 const machine = createMachine({
@@ -1014,7 +1014,7 @@ states: {
 
 The function must resolve to a target - returning `undefined` throws "must resolve to a target".
 
-Choice states are entered automatically by routing **into** them. They cannot themselves declare `invoke`, `after`, `on`, or `entry`/`exit` (machine creation rejects these).
+Choice states are entered automatically by routing into them. They cannot themselves declare `invoke`, `after`, `on`, or `entry`/`exit` (machine creation rejects these).
 
 ---
 
@@ -1046,7 +1046,7 @@ State `timeout` and `createAsyncLogic({ timeout })` accept `number` (ms) or `str
 | Seconds           | `'5s'`, `'1.5s'`                                               | integer or decimal + `s` suffix |
 | ISO 8601 duration | `'PT5S'`, `'PT1M30S'`, `'PT2H'`, `'P1D'`, `'P1W'`, `'P1DT12H'` | always starts with `P`          |
 
-Plain `'5m'`, `'1h'`, `'1d'`, `'1w'` (without the `P`/`PT` prefix) are **not** accepted - use the ISO 8601 form for anything beyond seconds and milliseconds.
+Plain `'5m'`, `'1h'`, `'1d'`, `'1w'` (without the `P`/`PT` prefix) are not accepted - use the ISO 8601 form for anything beyond seconds and milliseconds.
 
 `after` delays accept the same duration formats. A string delay is resolved against the machine's named `delays` first; only strings that don't match a named delay are parsed as durations.
 
@@ -1089,7 +1089,7 @@ loop until the process ran out of memory.
 
 <!-- exports removed from and added to packages/core/src/index.ts on the v6 branch (relative to main / v5) -->
 
-These exports have been **removed** from `xstate`:
+These exports have been removed from `xstate`:
 
 - Action creators (entire `actions.ts` module): `assign`, `raise`, `sendTo`, `sendParent`, `forwardTo`, `emit`, `log`, `cancel`, `enqueueActions`, `spawnChild`, `stopChild`, `stop`, plus their `*Action`/`*Params` types
 - Guard combinators and helpers: `and`, `or`, `not`, `stateIn`
@@ -1116,7 +1116,7 @@ These exports have been **removed** from `xstate`:
 
 `SetupReturn`, the type returned by `setup(...)`, is still exported, but its type parameters changed, so a v5 `SetupReturn<TContext, TEvent, ...>` annotation no longer type-checks. Use `typeof yourSetup` to name the type of a specific setup.
 
-These exports have been **added**:
+These exports have been added:
 
 - `setup` (reshaped - see §4) and `createSystem` for typed system registries
 - Setup state contract types: `SetupStateSchema`, `SetupStateSchemas`, `SetupStateType`
@@ -1275,7 +1275,7 @@ on: {
 
 ## 20. Persistence / rehydration
 
-Persisted snapshots round-trip through `JSON.stringify` and rehydrate via `restoreActor(machine, persisted)` from `xstate/persist`. The internal shape changed, so v5 persisted snapshots are **not** binary-compatible with v6 - drain or migrate stored state during your rollout.
+Persisted snapshots round-trip through `JSON.stringify` and rehydrate via `restoreActor(machine, persisted)` from `xstate/persist`. The internal shape changed, so v5 persisted snapshots are not binary-compatible with v6 - drain or migrate stored state during your rollout.
 
 ```ts
 import { restoreActor } from 'xstate/persist';
@@ -1296,7 +1296,7 @@ Child actors, async logic with effects, and listener-resume semantics are all pa
 
 The host serializes the payload. Development builds warn when `context`, `output`, `error`, or state input holds a value that does not survive a JSON round-trip: functions, symbols, `BigInt`, `Map`, `Set`, cycles, `NaN`, and `Infinity`. Persisting a snapshot whose `context` contains a circular reference throws an error that names the actor and the context path. See [Persistence](persistence.md) for the format rules.
 
-Actor refs in persisted `context` are stored as `{ "$actor": "<address>" }`. v5 stored them as `{ "xstate$$type": 1, "id": "<id>" }`; v6 does not read that shape, so convert those entries with [`machineVersions`](persistence.md#migrate-machine-versions) before restoring v5 snapshots.
+Actor refs in persisted `context` are stored as `{ "@actor": "<address>" }`. v5 stored them as `{ "xstate$$type": 1, "id": "<id>" }`; v6 does not read that shape, so convert those entries with [`machineVersions`](persistence.md#migrate-machine-versions) before restoring v5 snapshots.
 
 ### Snapshot versioning
 
@@ -1752,7 +1752,7 @@ A diff that matches a known v6 change is classified with a rule instead of `uncl
 | --- | --- |
 | `anonymous-child-id` | Child or send-target ids that differ only by a generated suffix. |
 | `error-string-shape` | Error strings with the same message after the prefix is removed. |
-| `context-reference` | `context` that is equal after removing actor-reference keys (`$actor`). |
+| `context-reference` | `context` that is equal after removing actor-reference keys (`@actor`). |
 | `done-event-session` | Processed events that are equal after dropping `sessionId`. |
 | `final-state-output` | `output` that is undefined in v5 and set in v6, because v6 uses a top-level final state's `output` when the root has none (see [Machine output](#machine-output)). |
 | `root-send-parent` | `status` and `error` where v5 errored with `Unable to send event to actor '#_parent'` and v6 did not, because v6 makes a send to a missing parent a dead letter (see [Sending to a missing target](#sending-to-a-missing-target)). Later fields of that step, such as `value`, can still differ. |
@@ -1840,7 +1840,7 @@ Code written against a v6 alpha uses names that changed before the beta. The old
 | `xstate.system.cancelEffect`, `xstate.logic.cleanup` effects | `@xstate.cancelEffect`, `@xstate.cleanup`                |
 | `xstate.logic.effect`, `xstate.log` system effects           | `@xstate.effect`, `@xstate.log`                          |
 | suffixed `xstate.done.actor.<id>` etc. descriptors           | category types with `matches` (see [Internal lifecycle events](#internal-lifecycle-events)) |
-| `{ xstate$type: 'actorRef', id, address, src }`              | `{ $actor: address }` (`SerializedActorRef`)             |
+| `{ xstate$type: 'actorRef', id, address, src }`              | `{ '@actor': address }` (`SerializedActorRef`; `$actor` in 6.0.0-beta.1) |
 | persisted timer `startedAt`                                  | `scheduledAt`                                            |
 | `snapshot.timers` record keyed by generated ids (`xstate.after.<delay>.<stateId>`, `xstate.timeout.state.<stateId>`, `xstate.timer.auto.<n>`) | list; built-in timers have no `id`, delayed sends without an `id` carry `seq` |
 | `scheduleTimer(source, id, delay)`, `cancelTimer(source, id)`, `{ type: 'xstate.timer', id }` | `scheduleTimer(source, timer, delay)`, `cancelTimer(source, timer)`, `{ type: 'xstate.timer', ...timer }` (`TimerKey`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xstate",
-  "version": "6.0.0-beta.1",
+  "version": "6.0.0-beta.2",
   "description": "Finite State Machines and Statecharts for the Modern Web.",
   "main": "dist/xstate.cjs.js",
   "bin": {