@xmachines/docs 3.0.0 → 4.0.0

package/examples/form-validation.md

@@ -15,7 +15,8 @@ This example mirrors the `authMachine` login pattern: a form state with a local
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 
 // Context shape
 interface LoginContext {
@@ -304,5 +305,5 @@ window.addEventListener("beforeunload", () => {
 
 - **[Basic State Machine](basic-state-machine.md)** — Foundational concepts without a view layer
 - **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth guards
-- **[`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)** — Spec type governing `meta.view`, `$bindState`, and `$state`
+- **[`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md)** — Spec type governing `meta.view`, `$bindState`, and `$state`
 - **[`@xmachines/play-router`](../api/@xmachines/play-router/README.md)** — Route extraction and tree building

package/examples/multi-router-integration.md

@@ -25,12 +25,13 @@ Used by framework adapters that have a React/Solid/Vue provider context. The `Pl
 import { useEffect, useMemo } from "react";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 import { defineRegistry } from "@xmachines/play-react";
 import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 
 const { registry } = defineRegistry(authCatalog, {
   components: { /* ...your components */ },
@@ -66,15 +67,16 @@ export function App() {
 }
 ```
 
-### React + React Router v7 (`@xmachines/play-react-router`)
+### React + React Router 7/8 (`@xmachines/play-react-router`)
 
 ```typescript
 import { createBrowserRouter, RouterProvider } from "react-router";
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-react-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 
 function createAppRuntime() {
   const actor = createPlayer();
@@ -116,11 +118,13 @@ export default function App() {
 ```typescript
 import { Router, Route } from "@solidjs/router";
 import { onCleanup } from "solid-js";
-import { PlayRouterProvider, createRouteMap } from "@xmachines/play-solid-router";
-import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { PlayRouterProvider } from "@xmachines/play-solid-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 const actor = createPlayer();
 actor.start();
 
@@ -164,11 +168,13 @@ export default function App() {
 ```typescript
 import { createRouter, createRootRoute, createRoute, RouterProvider } from "@tanstack/solid-router";
 import { onCleanup } from "solid-js";
-import { PlayRouterProvider, createRouteMap } from "@xmachines/play-tanstack-solid-router";
-import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { PlayRouterProvider } from "@xmachines/play-tanstack-solid-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
 const actor = createPlayer();
 actor.start();
 
@@ -222,7 +228,8 @@ export default function App() {
 <script setup lang="ts">
 	import { h, inject } from "vue";
 	import { createRouter, createWebHistory } from "vue-router";
-	import { PlayRouterProvider, createRouteMap } from "@xmachines/play-vue-router";
+	import { PlayRouterProvider } from "@xmachines/play-vue-router";
+	import { createRouteMap } from "@xmachines/play-router/xstate";
 	import { defineRegistry } from "@xmachines/play-vue";
 	import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
 
@@ -258,18 +265,20 @@ Used by vanilla DOM and Svelte adapters. Call `connectRouter` directly after cre
 ### Vanilla DOM (`@xmachines/play-dom-router`)
 
 ```typescript
-import {
-	createBrowserHistory,
-	createRouter,
-	connectRouter,
-	createRouteMap,
-} from "@xmachines/play-dom-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
 import { createPlayUI, defineRegistry } from "@xmachines/play-dom";
 import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
 
-const createPlayer = definePlayer({ machine: authMachine });
+// The router needs `withRouting`, and the renderer below needs `withView`.
+const createPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -306,10 +315,15 @@ window.addEventListener("beforeunload", () => {
 // lib/router.ts
 import { defineRegistry } from "@xmachines/play-svelte";
 import { authCatalog, authMachine } from "@xmachines/play-actor-shared";
-import { definePlayer } from "@xmachines/play-xstate";
-import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
-
-const createDemoPlayer = definePlayer({ machine: authMachine });
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import { connectRouter } from "@xmachines/play-sveltekit-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+const createDemoPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 
 const { registry } = defineRegistry(authCatalog, {
 	components: {/* ...your Svelte components */},
@@ -337,11 +351,17 @@ export const disconnectRouter = connectRouter({ actor, routeMap });
 
 ```typescript
 // lib/router.ts — identical pattern to SvelteKit, different import
-import { connectRouter, createRouteMap } from "@xmachines/play-svelte-spa-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { connectRouter } from "@xmachines/play-svelte-spa-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
 import { authMachine } from "@xmachines/play-actor-shared";
 
-const createDemoPlayer = definePlayer({ machine: authMachine });
+const createDemoPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 
 export const actor = createDemoPlayer();
 actor.start();
@@ -446,7 +466,7 @@ An actor never changes identity, so a segment of the prefix that _identifies_ th
 For a host router that declares real route objects, ask for the list — and drop it again when the machine unloads:
 
 ```typescript
-import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router";
+import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router/xstate";
 
 const tree = extractMachineRoutes(authMachine);
 
@@ -460,7 +480,7 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 // [{ stateId: "home", path: "/:machineId/play" }, ...]
 ```
 
-> **Polyfill note.** Under a mount, `@xmachines/play-vue-router` and `@xmachines/play-solid-router` resolve each param from the stripped path with `URLPattern`, and not from the pre-parsed params of their framework: under a prefix the framework matched a route of the **host**, so those params describe the route of the machine never — and a collision of names carries the value of the host. Both adapters therefore need a `URLPattern` polyfill on an older runtime when they are mounted. With no prefix, both keep the parse of their framework whenever it reports at least one
+> **Param note.** Under a mount, `@xmachines/play-vue-router` and `@xmachines/play-solid-router` resolve each param from the stripped path with `URLPattern`, and not from the pre-parsed params of their framework: under a prefix the framework matched a route of the **host**, so those params describe the route of the machine never — and a collision of names carries the value of the host. With no prefix, both keep the parse of their framework whenever it reports at least one
 > param the pattern declares, and every required one. A pattern whose params are ALL
 > optional and a framework that reports none — `/settings/:section?` under a catch-all of
 > the host — is settled by the PATH: `/settings` is the bare form of that pattern, so
@@ -468,17 +488,19 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 > value, such as `/settings/security`, still reaches the extraction, because only the
 > extraction reads that value.
 >
-> These branches decide the CALLS of a navigation, and not whether the application needs
-> the polyfill. `RouteMap` compiles each parameterized route in its constructor and
-> throws there without `URLPattern`, so one `:param` in the route map makes the polyfill
-> a startup requirement on an older runtime.
+> These branches decide the CALLS of a navigation, and never the availability of the API.
+> `@xmachines/play-router` carries `urlpattern-polyfill` as an ordinary dependency and it
+> uses the native `URLPattern` when the runtime has one, so you install no polyfill and
+> you load none. A BAD pattern is a question of the route map: `RouteMap` compiles each
+> parameterized route in its constructor and throws an `InvalidRoutePatternError` there.
+> The [routing guide](../guides/routing.md) states the pattern language.
 
 ## Adapter Summary
 
 | Package                                 | Framework             | Pattern         | Key Import                                                                |
 | --------------------------------------- | --------------------- | --------------- | ------------------------------------------------------------------------- |
 | `@xmachines/play-dom-router`            | Vanilla DOM           | `connectRouter` | `connectRouter`, `createRouteMap`, `createBrowserHistory`, `createRouter` |
-| `@xmachines/play-react-router`          | React Router v7       | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
+| `@xmachines/play-react-router`          | React Router 7/8      | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
 | `@xmachines/play-tanstack-react-router` | TanStack React Router | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
 | `@xmachines/play-solid-router`          | SolidJS Router        | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
 | `@xmachines/play-tanstack-solid-router` | TanStack Solid Router | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |

package/examples/routing-patterns.md

@@ -64,7 +64,8 @@ Instead of hand-writing `play.route` event handlers for every routable state, wr
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 import type { PlayRouteEvent } from "@xmachines/play-router";
 
 interface AuthContext {
@@ -108,14 +109,16 @@ const authMachine = authSetup.createMachine(
 ```typescript
 on: {
   "play.route": [
-    { target: ".home",    guard: ({ event }) => event.to === "#home",    reenter: true, actions: assign({ params, query }) },
-    { target: ".about",   guard: ({ event }) => event.to === "#about",   reenter: true, actions: assign({ params, query }) },
-    { target: ".login",   guard: ({ event }) => event.to === "#login",   reenter: true, actions: assign({ params, query }) },
-    { target: ".profile", guard: ({ event }) => event.to === "#profile", reenter: true, actions: assign({ params, query }) },
+    { target: ".home",    guard: ({ event }) => event.to === "#home",    reenter: false, actions: assign({ params, query }) },
+    { target: ".about",   guard: ({ event }) => event.to === "#about",   reenter: false, actions: assign({ params, query }) },
+    { target: ".login",   guard: ({ event }) => event.to === "#login",   reenter: false, actions: assign({ params, query }) },
+    { target: ".profile", guard: ({ event }) => event.to === "#profile", reenter: false, actions: assign({ params, query }) },
   ],
 }
 ```
 
+`reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/about", reenter: true } }` for a state that must re-enter its own domain.
+
 ### `play.route` Events — Navigation
 
 To navigate, send a `play.route` event with `to: "#stateId"`:
@@ -204,7 +207,10 @@ const authMachine = authSetup.createMachine(
 ## Complete Actor Usage
 
 ```typescript
-const createPlayer = definePlayer({ machine: authMachine });
+const createPlayer = definePlayer({
+	machine: authMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -237,13 +243,8 @@ actor.stop();
 To sync the browser URL with `actor.currentRoute`, use `@xmachines/play-dom-router`:
 
 ```typescript
-import {
-	createBrowserHistory,
-	createRouter,
-	connectRouter,
-	createRouteMap,
-} from "@xmachines/play-dom-router";
-
+import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 // createRouteMap extracts meta.route declarations from the machine
 const routeMap = createRouteMap(authMachine);
 
@@ -268,7 +269,7 @@ For React, use `@xmachines/play-react-router` or `@xmachines/play-tanstack-react
 
 ```tsx
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 
 const routeTree = extractMachineRoutes(authMachine);
 const routeMap = createRouteMapFromTree(routeTree);

package/examples/traffic-light.md

@@ -17,7 +17,9 @@ Applicable patterns:
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
 // 1. Typed setup
 const trafficSetup = setup({
@@ -70,7 +72,10 @@ const trafficMachine = trafficSetup.createMachine(
 );
 
 // 3. Player factory
-const createPlayer = definePlayer({ machine: trafficMachine });
+const createPlayer = definePlayer({
+	machine: trafficMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 
 // 4. Create and start actor
 const actor = createPlayer();
@@ -105,9 +110,9 @@ actor.stop();
 // Auto-generated by formatPlayRouteTransitions — you don't write this manually:
 on: {
   "play.route": [
-    { target: ".red",    guard: ({ event }) => event.to === "#red",    reenter: true, actions: assign({ params, query }) },
-    { target: ".green",  guard: ({ event }) => event.to === "#green",  reenter: true, actions: assign({ params, query }) },
-    { target: ".yellow", guard: ({ event }) => event.to === "#yellow", reenter: true, actions: assign({ params, query }) },
+    { target: ".red",    guard: ({ event }) => event.to === "#red",    reenter: false, actions: assign({ params, query }) },
+    { target: ".green",  guard: ({ event }) => event.to === "#green",  reenter: false, actions: assign({ params, query }) },
+    { target: ".yellow", guard: ({ event }) => event.to === "#yellow", reenter: false, actions: assign({ params, query }) },
   ],
 }
 ```
@@ -116,6 +121,7 @@ on: {
 
 - Every routable state must have both `id` (the `#id` navigation target) and `meta.route` (the URL template).
 - The machine's context must include `params` and `query` fields (both `Record<string, string>`), because `formatPlayRouteTransitions` assigns them on every `play.route` transition.
+- `reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/red", reenter: true } }` for a state that must re-enter its own domain.
 
 ## `actor.currentRoute` Signal
 

package/guides/README.md

@@ -12,6 +12,7 @@ Background reading that explains the _why_ behind XMachines design decisions.
 
 - **[Understanding State Machines](state-machines.md)** — What finite state machines are, how `meta.route` and `meta.view` extend them, and why they replace boolean flags and component-level routing logic
 - **[Understanding the Actor Model](actor-model.md)** — The actor/infrastructure split, why the machine has zero framework imports, and how the reset invariant works
+- **[Understanding Routing](routing.md)** — The URLPattern grammar that a `meta.route` path declares, the prefix rule that decides every optional route, and the three invariants that every router adapter follows
 - **[Understanding TC39 Signals](signals.md)** — The three signal primitives (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`), why XMachines uses them instead of observables, and the architectural invariants they enforce
 
 ## Tooling

package/guides/actor-model.md

@@ -19,7 +19,7 @@ The boundary between them is enforced by the signal protocol: the actor exposes
 ```
 Actor (business logic)
   │
-  │  emits signals: state, currentRoute, currentView
+  │  emits signals: state, and currentRoute / currentView from its capabilities
   ▼
 Infrastructure (runtime adapters)
   ├── Router Bridge — reflects currentRoute into the URL bar
@@ -33,20 +33,20 @@ Infrastructure → actor: only via actor.send({ type: "..." })
 
 ## What the actor owns
 
-An actor in XMachines is a [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) — a concrete class that extends XState's `Actor` class via [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md). It implements three reactive properties:
+An actor in XMachines is a [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) — a concrete class that extends XState's `Actor` class via [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md). It implements three reactive properties:
 
-| Property             | Type                              | What it is                                                                                                                     |
-| -------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `actor.state`        | `Signal.State<Snapshot>`          | Updated on every XState transition. The full machine snapshot.                                                                 |
-| `actor.currentRoute` | `Signal.Computed<string \| null>` | Derived from the active state node's `meta.route`.                                                                             |
-| `actor.currentView`  | `Signal.State<PlaySpec \| null>`  | Updated on each transition. Holds the [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) that drives renderers. |
+| Property             | Type                              | What it is                                                                                                                                                     |
+| -------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actor.state`        | `Signal.State<Snapshot>`          | Updated on every XState transition. The full machine snapshot.                                                                                                 |
+| `actor.currentRoute` | `Signal.Computed<string \| null>` | Derived from the active state node's `meta.route`. Needs the routing capability.                                                                               |
+| `actor.currentView`  | `Signal.State<PlaySpec \| null>`  | Updated on each transition. Holds the [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) that drives renderers. Needs the view capability. |
 
 All three are set by the actor, never by infrastructure. Infrastructure reads them via signals.
 
 The actor also owns:
 
 - **Guards** — it decides whether a transition is valid. If a router sends a `play.route` event for a path the actor's guards reject, the actor does not transition. It then emits its current valid route back through `currentRoute`, and the router bridge overwrites the URL to match.
-- **Error states** — structured errors ([`PlayError`](../api/@xmachines/play/classes/PlayError.md)) are part of the actor's state graph, not thrown into the environment.
+- **Error states** — structured errors ([`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md)) are part of the actor's state graph, not thrown into the environment.
 - **Initial route** — `actor.initialRoute` is the route the actor starts in. Router adapters use this for initial navigation, not the browser's current URL.
 
 ---
@@ -87,17 +87,19 @@ This is why the invariant is called **State-Driven Reset** in the Play RFC.
 
 ---
 
-## [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) — the enforced contract
+## [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) — the enforced contract
 
-[`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) (from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)) is the abstract base class that all actor implementations must extend. It extends XState's `Actor`, which means:
+[`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) (from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)) is the contract that all actor implementations satisfy. It is an INTERFACE, and it names no state machine library.
+
+An adapter extends the actor class of its own engine. [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) extends `Actor` of XState, which means:
 
 - XState's inspection API works ([`@statelyai/inspect`](https://stately.ai/docs/inspector) — see [Inspecting a Running Actor](inspector.md))
 - XState DevTools attach to actors normally
 - The full XState ecosystem (testing utilities, visualization) is compatible
 
-[`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) adds one abstract requirement: a reactive `state` property of type `Signal.State<unknown>`. This is the single point where XState's pull-based snapshot API is bridged to TC39's push-based signal system.
+[`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) asks for two members: a reactive `state` property of type `Signal.State<TSnapshot>`, and a typed `send`. `state` is the single point where the pull-based snapshot API of an engine is bridged to the push-based signal system of TC39.
 
-The two optional capability interfaces — [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md) — are deliberately separate:
+The two optional capability interfaces — [`Routable`](../api/@xmachines/play-router/index/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-view/index/interfaces/Viewable.md) — are deliberately separate:
 
 - Not every actor needs routing (e.g., a background data-sync actor).
 - Not every actor drives a view (e.g., a sub-actor composed inside a parent).
@@ -105,26 +107,33 @@ The two optional capability interfaces — [`Routable`](../api/@xmachines/play-a
 An actor implements only the capabilities it actually uses:
 
 ```typescript
-// Minimal actor: just reactive state
-class MinimalActor extends AbstractActor<SomeLogic> {
-	state = new Signal.State(this.getSnapshot());
+// Minimal actor: the contract alone, which is reactive state and send
+class MinimalActor implements PlayActor<SomeSnapshot, SomeEvent> {
+	readonly state = new Signal.State<SomeSnapshot>(initial);
+	send(event: SomeEvent): void {
+		/* dispatch */
+	}
 }
 
-// Full actor: state + routing + view
-class PlayerActor extends AbstractActor<SomeMachine> implements Routable, Viewable {
-	state = new Signal.State(this.getSnapshot());
-	currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
-	currentView = new Signal.State<PlaySpec | null>(null);
+// Full actor: the contract, the routing and the view. It extends the actor class of
+// its own engine, and `PlayActor` stays out of the inheritance.
+class PlayerActor
+	extends Actor<SomeMachine>
+	implements PlayActor<SomeSnapshot, SomeEvent>, Routable, Viewable
+{
+	readonly state = new Signal.State(this.getSnapshot());
+	readonly currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+	readonly currentView = new Signal.State<PlaySpec | null>(null);
 }
 ```
 
-In practice you never write [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) yourself — [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) creates one from your machine definition.
+In practice you never write [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) yourself — [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) creates one from your machine definition.
 
 ---
 
-## [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) — the factory builder
+## [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) — the factory builder
 
-[`definePlayer({ machine })`](../api/@xmachines/play-xstate/functions/definePlayer.md) is the primary entry point for creating actors:
+[`definePlayer({ machine })`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) is the primary entry point for creating actors:
 
 ```typescript
 import { definePlayer } from "@xmachines/play-xstate";
@@ -137,7 +146,7 @@ const actor = createPlayer();
 actor.start();
 ```
 
-[`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) returns a **factory function**, not an actor. This is intentional: it lets you create multiple independent instances (e.g., one per test, one per user session) without re-processing the machine definition each time.
+[`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) returns a **factory function**, not an actor. This is intentional: it lets you create multiple independent instances (e.g., one per test, one per user session) without re-processing the machine definition each time.
 
 The factory accepts optional `input` (initial context overrides) and a `restore` snapshot (for resumable sessions):
 
@@ -175,6 +184,6 @@ The Play RFC captures the actor/infrastructure split in a single statement:
 - [Understanding TC39 Signals](signals.md) — how the actor communicates with infrastructure
 - [Understanding State Machines](state-machines.md) — how the machine definition drives actor behavior
 - [Getting Started](getting-started.md) — hands-on walkthrough creating and starting an actor
-- [@xmachines/play-actor](../api/@xmachines/play-actor/README.md) — API reference for [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md)
-- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — API reference for [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) and [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
+- [@xmachines/play-actor](../api/@xmachines/play-actor/README.md) — API reference for [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md)
+- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — API reference for [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) and [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)
 - [Play RFC](../rfc/play.md) — complete architectural specification