@xmachines/docs 2.2.0 → 4.0.0

package/guides/signals.md

@@ -109,6 +109,49 @@ Use [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) i
 
 ---
 
+## The release, and `using`
+
+`watchSignal()` returns a `Cleanup` from [`@xmachines/play`](../api/@xmachines/play/README.md): a
+function, and a `Disposable`. One value therefore serves two forms, and the same holds for
+the mount of `@xmachines/play-dom` and for `history.subscribe()` of
+`@xmachines/play-dom-router`.
+
+Keep the explicit call where the release outlives the scope that made it — a field that a
+teardown reads, an entry in a `Set` of releases:
+
+```typescript
+const stop = watchSignal(actor.currentRoute, render);
+onUnmount(() => stop());
+```
+
+Write `using` where the release belongs to one scope. The scope releases it, an exception
+releases it too, and the code carries no teardown:
+
+```typescript
+{
+	using stop = watchSignal(actor.currentRoute, render);
+	render(actor.currentRoute.get());
+	// stop() runs here, and it runs even when render() throws
+}
+```
+
+A scope releases from the last declaration to the first, so a release that depends on an
+earlier one is safe.
+
+Every release here is synchronous, so `Cleanup` is a `Disposable` and not an
+`AsyncDisposable`. That is the permissive choice: a `Disposable` serves `using` AND
+`await using`, while an `AsyncDisposable` raises a TypeError under a plain `using` and
+forces every holder into an async function. `asCleanup` therefore refuses a release that
+returns a value, and a promise above all — a promise handed to it would go on the floor,
+released and unawaitable.
+
+`using` needs Node 24 or a browser with Explicit Resource Management. The publishable
+packages build at `target: "esnext"` and pass the syntax through untouched, so your bundler
+decides how to emit it. The `Cleanup` VALUE needs neither: a runtime without
+`Symbol.dispose` still calls it as a plain function.
+
+---
+
 ## Why not observables (RxJS) or event emitters?
 
 The XMachines architecture chose TC39 Signals over observable libraries and event emitters for three reasons:

package/guides/state-machines.md

@@ -77,7 +77,7 @@ Key patterns:
 XMachines extends XState's `meta` field on each state node. This is where routing intent and view structure live:
 
 ```typescript
-import { typedSpec } from "@xmachines/play-actor";
+import { typedSpec } from "@xmachines/play-view";
 
 const appMachine = setup({/* ... */}).createMachine({
 	id: "app",
@@ -122,7 +122,7 @@ const appMachine = setup({/* ... */}).createMachine({
 
 `meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `Signal.Computed`) derives this path and emits it. The router bridge reads it and updates the URL.
 
-`meta.view` is a [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) — a `@xmachines/json-render-core` spec object describing what to render. Use `typedSpec(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to type-check the spec literal at the definition site (XState's `meta` is untyped). When the machine enters a state, `actor.currentView` is updated with the derived spec. The renderer reads it and projects it through framework components.
+`meta.view` is a [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) — a `@xmachines/json-render-core` spec object describing what to render. Use `typedSpec(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to type-check the spec literal at the definition site (XState's `meta` is untyped). When the machine enters a state, `actor.currentView` is updated with the derived spec. The renderer reads it and projects it through framework components.
 
 The machine's whole context is available to every view through the **`/context` projection**: the derived spec's `state` carries `context: <machine context>`. Specs read it with ordinary state expressions — `{ $state: "/context/username" }` in props, `visible` conditions, or `repeat.statePath`. The subtree is **read-only**: context changes only through machine events, and a `$bindState`/`setState` write under `/context` throws. URL data lives at its own paths (`/context/params/…`, `/context/query/…`, written into context by `formatPlayRouteTransitions`), so a URL param can never shadow a machine-owned field. When validating specs with tools like `validateSpec`, validate the **derived** view (`actor.currentView.get()`) — its `state` honestly describes the store contents — not the raw `meta.view`. A context change re-emits the view with the same `viewKey`; providers respond by refreshing `/context` in the live store, not by remounting the UI.
 
@@ -130,7 +130,7 @@ The machine's whole context is available to every view through the **`/context`
 
 ---
 
-## [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) — automatic route event wiring
+## [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) — automatic route event wiring
 
 For routing to work, the machine must respond to `play.route` events (sent by router bridges when the user navigates). Writing these transitions by hand is mechanical:
 
@@ -150,10 +150,10 @@ states: {
 }
 ```
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) generates these transitions automatically from the `id` and `meta.route` fields you already have:
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) generates these transitions automatically from the `id` and `meta.route` fields you already have:
 
 ```typescript
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 
 const appMachine = setup({/* ... */}).createMachine(
 	formatPlayRouteTransitions({
@@ -168,7 +168,7 @@ const appMachine = setup({/* ... */}).createMachine(
 );
 ```
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
 
 ```typescript
 types: {
@@ -200,16 +200,15 @@ Guards are evaluated by XState before a transition fires. If the guard returns `
 
 This is the **Actor Authority** invariant in practice: the machine decides, infrastructure adjusts.
 
-XMachines provides guard combinators in [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) for composing complex conditions:
+Compose a condition with the combinators of XState:
 
-| Function                                                                                            | What it does                            |
-| --------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| [`composeGuards(...guards)`](../api/@xmachines/play-xstate/functions/composeGuards.md)              | AND — all guards must pass              |
-| [`composeGuardsOr(...guards)`](../api/@xmachines/play-xstate/functions/composeGuardsOr.md)          | OR — any guard must pass                |
-| [`negateGuard(guard)`](../api/@xmachines/play-xstate/functions/negateGuard.md)                      | NOT — inverts the guard result          |
-| [`hasContext(key)`](../api/@xmachines/play-xstate/functions/hasContext.md)                          | Checks that a context field is non-null |
-| [`contextFieldMatches(key, value)`](../api/@xmachines/play-xstate/functions/contextFieldMatches.md) | Checks a context field against a value  |
-| [`eventMatches(type)`](../api/@xmachines/play-xstate/functions/eventMatches.md)                     | Checks the event type                   |
+| Function        | What it does                |
+| --------------- | --------------------------- |
+| `and([g1, g2])` | AND — every guard must pass |
+| `or([g1, g2])`  | OR — one guard must pass    |
+| `not(g)`        | NOT — it inverts the guard  |
+
+Each combinator resolves a guard NAME against the `guards` of `setup()`, so a name that the map does not hold fails to compile.
 
 ---
 
@@ -259,7 +258,7 @@ actor.start();
 // Actor resumes from where it left off
 ```
 
-[`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
+[`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
 
 ---
 
@@ -281,6 +280,6 @@ actor.start();
 - [Understanding TC39 Signals](signals.md) — how the actor's state is observed by infrastructure
 - [Getting Started](getting-started.md) — step-by-step walkthrough building your first machine and actor
 - [Routing Patterns](../examples/routing-patterns.md) — worked examples of `meta.route` and guards
-- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — full API reference for [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), guard combinators
+- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — full API reference for [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), and the routing utilities
 - [XState v5 documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
 - [Play RFC](../rfc/play.md) — complete architectural specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "2.2.0",
+  "version": "4.0.0",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -45,6 +45,7 @@
   },
   "scripts": {
     "lint": "oxlint .",
+    "lint:security": "node ../../scripts/semgrep-scan.mjs",
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
@@ -53,16 +54,16 @@
     "clean": "rm -rf coverage node_modules/.vite*"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.9.1",
-    "@types/node": "^26.2.0",
-    "oxfmt": "^0.64.0",
-    "oxlint": "^1.79.0",
-    "typedoc": "^0.28.19",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@types/node": "^26.6.2",
+    "oxfmt": "^0.68.0",
+    "oxlint": "^1.83.0",
+    "typedoc": "^0.28.20",
     "typedoc-plugin-llms-txt": "^0.1.2",
-    "typedoc-plugin-markdown": "^4.11.0",
-    "vitest": "^4.1.11"
+    "typedoc-plugin-markdown": "^4.13.0",
+    "vitest": "^5.0.1"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   }
 }

package/rfc/play.md

@@ -136,10 +136,12 @@ Exports the minimal shared contracts that allow the Logic Engine and Infrastruct
 
 **Role:** Abstract Logic Engine
 
-Defines the minimal base class that all logic adapters must implement. By extending the XState `Actor` class, the `AbstractActor` remains fully compatible with the XState ecosystem (inspection, system registration, message passing) while enforcing the Play Architecture's **push–pull signal contract**.
+Defines the minimal base class that all logic adapters must implement. By extending the XState `Actor` class, the `PlayActor` remains fully compatible with the XState ecosystem (inspection, system registration, message passing) while enforcing the Play Architecture's **push–pull signal contract**.
 
 The base class requires only two abstract members: **reactive state** and **typed event dispatch**. Routing and view rendering are opt-in via separate interfaces, allowing actors to compose only the capabilities they need.
 
+**Design Rationale:** The RFC declared an abstract `AbstractActor` CLASS that extended `Actor` of `xstate`, and it declared both capability interfaces in this package. The implementation made the contract an INTERFACE, `PlayActor`, because the class carried no implementation: both of its members were abstract, and its whole effect was to force the inheritance of XState on every consumer of the contract. `@xmachines/play-actor` names `xstate` nowhere now. The implementation also moved each capability interface to the package that holds its shared machinery: `Routable` is in `@xmachines/play-router`, beside the bridge that reads it, and `Viewable` and `PlaySpec` are in `@xmachines/play-view`, beside the view store lifecycle. A consumer who needs no routing and no view therefore installs neither package, and `@xmachines/play-actor` names the capability packages nowhere. The shape of each interface is unchanged.
+
 ```ts
 import { Actor, type AnyActorLogic, type EventObject } from "xstate";
 import type { Signal } from "@xmachines/play-signals";
@@ -170,7 +172,7 @@ export interface Viewable {
 }
 
 // The Base Protocol — minimal contract
-export abstract class AbstractActor<
+export abstract class PlayActor<
 	TLogic extends AnyActorLogic,
 	TEvent extends EventObject = EventObject,
 > extends Actor<TLogic> {
@@ -182,7 +184,7 @@ export abstract class AbstractActor<
 }
 ```
 
-**Design Rationale:** The original design placed `currentRoute`, `currentView`, and `catalog` directly on `AbstractActor`. The implementation extracted these into `Routable` and `Viewable` interfaces because:
+**Design Rationale:** The original design placed `currentRoute`, `currentView`, and `catalog` directly on `PlayActor`. The implementation extracted these into `Routable` and `Viewable` interfaces because:
 
 1. Not all actors need routing (e.g. embedded sub-actors)
 2. Not all actors need view rendering (e.g. background logic actors)
@@ -194,16 +196,16 @@ export abstract class AbstractActor<
 
 **Role:** Concrete Logic Adapter (XState v5)
 
-Wraps XState v5 to satisfy the `AbstractActor` contract. Provides the primary API for creating actors from state machine definitions.
+Wraps XState v5 to satisfy the `PlayActor` contract. Provides the primary API for creating actors from state machine definitions.
 
 **Primary Exports:**
 
 - `definePlayer` — Factory builder: accepts a machine config, returns a factory function that creates `PlayerActor` instances
-- `PlayerActor` — Concrete class extending `AbstractActor` and implementing both `Routable` and `Viewable`
+- `PlayerActor` — Concrete class extending `PlayActor`. It carries state and send alone, and a capability mixin adds the rest
+- `compose`, `withRouting`, `withView` — The composition of the optional capabilities onto `PlayerActor`
 
 **Utility Exports:**
 
-- Guard combinators: `composeGuards`, `composeGuardsOr`, `negateGuard`, `hasContext`, `eventMatches`, `contextFieldMatches`
 - Route derivation: `deriveRoute`, `isAbsoluteRoute`, `buildRouteUrl`, `formatPlayRouteTransitions`
 
 **Responsibilities:**
@@ -228,18 +230,22 @@ const definePlayer = <TMachine extends AnyStateMachine>(
 	return (input?, restore?) => new PlayerActor(machine, options, input, restore?.snapshot);
 };
 
-// PlayerActor composes all capabilities
+// PlayerActor carries the core protocol alone. It extends the actor class of XState
+// directly, and `PlayActor` is a contract that it implements.
 class PlayerActor<TMachine extends AnyStateMachine>
-	extends AbstractActor<AnyActorLogic, EventFromLogic<TMachine>>
-	implements Routable, Viewable
+	extends Actor<AnyActorLogic>
+	implements PlayActor<SnapshotFrom<TMachine>, EventFromLogic<TMachine>>
 {
-	public state: Signal.State<AnyMachineSnapshot>;
-	public currentRoute: Signal.Computed<string | null>;
-	public currentView: Signal.State<PlaySpec | null>;
-	public readonly initialRoute: string | null;
+	public state: Signal.State<SnapshotFrom<TMachine>>;
 }
+
+// A capability arrives through `compose`, and each one brings its own package
+const RoutedPlayer = compose(PlayerActor, withRouting, withView);
+// RoutedPlayer instances hold `currentRoute`, `initialRoute` and `currentView`
 ```
 
+**Design Rationale:** The RFC made `PlayerActor` implement both capabilities directly. The implementation split them into mixins, because a direct implementation made `@xmachines/play-router` and `@xmachines/play-view` hard dependencies of every actor. Both packages are optional peer dependencies now: `definePlayer({ machine })` installs neither, `withRouting` needs `@xmachines/play-router`, and `withView` needs `@xmachines/play-view`.
+
 **Design Rationale:** The original design passed a `catalog` to `definePlayer` and returned `{ create, catalog }`. The implementation decoupled catalogs entirely — component schemas are defined via `@xmachines/json-render-core`'s `defineCatalog` and bound to renderers via `defineRegistry`, not to actors. This means a single actor can be rendered by different component libraries without change.
 
 ### 5.3 Router Layer
@@ -250,6 +256,14 @@ class PlayerActor<TMachine extends AnyStateMachine>
 
 Provides the complete routing infrastructure: route extraction from state machines, bidirectional route mapping, and the abstract `RouterBridgeBase` that all framework-specific router adapters extend.
 
+**Design Rationale:** The RFC put the whole of the routing in one package. The implementation split it at two boundaries, because a consumer paid for both halves and used one:
+
+- `@xmachines/play-router/xstate` holds the machine half — `extractMachineRoutes`, `createRouteMap`, `machineToGraph`, and the queries over a route tree. That half alone needs `xstate` and `@statelyai/graph`.
+- `@xmachines/play-url` holds the URL language — the URLPattern grammar, a base path, and the params of a framework router. It knows no machine and no bridge, and BOTH directions of the routing read it.
+- `@xmachines/play-router` keeps the route map, the match of a location, `RouterBridgeBase`, the provider lifecycle, and the `Routable` capability. It names no state machine.
+
+The export lists below name the original layout. Each package README names what it holds now.
+
 **Protocol Exports:**
 
 - `RouterBridge` — Interface: `{ connect(): void; disconnect(): void }`
@@ -266,7 +280,6 @@ Provides the complete routing infrastructure: route extraction from state machin
 - `extractMachineRoutes` — Build complete route tree from a machine definition
 - `buildRouteTree` — Construct hierarchical tree from flat route info
 - `createRouteMap` / `RouteMap` — Bidirectional path ↔ state ID resolution
-- `BaseRouteMap` / `BaseRouteMapping` — Shared base for adapter-specific route maps
 
 **Validation & Query Exports:**
 
@@ -284,13 +297,13 @@ Provides the complete routing infrastructure: route extraction from state machin
 
 Each adapter extends `RouterBridgeBase` and implements the three abstract methods for its target router. All share the same architectural pattern:
 
-| Package                                 | Router          | Framework |
-| --------------------------------------- | --------------- | --------- |
-| `@xmachines/play-tanstack-react-router` | TanStack Router | React     |
-| `@xmachines/play-tanstack-solid-router` | TanStack Router | SolidJS   |
-| `@xmachines/play-react-router`          | React Router v7 | React     |
-| `@xmachines/play-vue-router`            | Vue Router 4/5  | Vue       |
-| `@xmachines/play-solid-router`          | SolidJS Router  | SolidJS   |
+| Package                                 | Router           | Framework |
+| --------------------------------------- | ---------------- | --------- |
+| `@xmachines/play-tanstack-react-router` | TanStack Router  | React     |
+| `@xmachines/play-tanstack-solid-router` | TanStack Router  | SolidJS   |
+| `@xmachines/play-react-router`          | React Router 7/8 | React     |
+| `@xmachines/play-vue-router`            | Vue Router 4/5   | Vue       |
+| `@xmachines/play-solid-router`          | SolidJS Router   | SolidJS   |
 
 **Runtime Adapter Responsibilities (all adapters):**
 
@@ -431,7 +444,7 @@ import { createDashboard, machine } from "./features/dashboard/player";
 import { catalog } from "./catalog";
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
 import { TanStackReactRouterBridge } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
+import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router/xstate";
 
 // 1. Create the actor
 const actor = createDashboard();