@xmachines/docs 3.0.0 → 4.0.0

package/api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
 
-Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vitest.ts#L64)
+Defined in: [vitest.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vitest.ts#L65)
 
 Create a Vitest config with XMachines workspace defaults.
 
@@ -16,6 +16,7 @@ What this applies automatically:
   resolve to source in local/dev test runs.
 - `config/vitest.setup.ts` when missing.
 - `config/vitest.node.setup.ts` for non-browser projects when missing.
+- `pool: "vmThreads"` for jsdom projects that declare no pool.
 
 Setup injection is additive and preserves caller-provided ordering after
 required shared setup files.

package/api/@xmachines/shared/vitest/interfaces/XmBrowserConfigOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: XmBrowserConfigOptions
 
-Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vitest.ts#L117)
+Defined in: [vitest.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vitest.ts#L159)
 
 Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
 Vitest config overrides.
@@ -11,6 +11,6 @@ Vitest config overrides.
 
 | Property                                           | Type                                     | Description                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                      |
 | -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vitest.ts#L125) |
-| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vitest.ts#L132) |
-| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vitest.ts#L138) |
+| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vitest.ts#L167) |
+| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vitest.ts#L174) |
+| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/shared/config/vitest.ts#L180) |

package/api/README.md

@@ -18,6 +18,8 @@
 - [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md)
 - [@xmachines/play-tanstack-router](@xmachines/play-tanstack-router/README.md)
 - [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md)
+- [@xmachines/play-url](@xmachines/play-url/README.md)
+- [@xmachines/play-view](@xmachines/play-view/README.md)
 - [@xmachines/play-vue](@xmachines/play-vue/README.md)
 - [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md)
 - [@xmachines/play-xstate](@xmachines/play-xstate/README.md)

package/api/llms.txt

@@ -9,9 +9,9 @@
 ## Start Here
 
 - Defining players from machines: start with [@xmachines/play-xstate](@xmachines/play-xstate/README.md).
-- Understanding actor contracts: read [@xmachines/play-actor](@xmachines/play-actor/README.md) for [Viewable](@xmachines/play-actor/interfaces/Viewable.md) and [Routable](@xmachines/play-actor/interfaces/Routable.md).
-- [Viewable](@xmachines/play-actor/interfaces/Viewable.md) is the rendering contract: actors expose `currentView` plus a component catalog so rendering packages can resolve UI without owning application state.
-- [Routable](@xmachines/play-actor/interfaces/Routable.md) is the routing contract: actors expose `currentRoute` plus route-oriented event handling, while adapters translate browser or router changes into actor events.
+- Understanding actor contracts: read [@xmachines/play-actor](@xmachines/play-actor/README.md) for [Viewable](@xmachines/play-view/index/interfaces/Viewable.md) and [Routable](@xmachines/play-router/index/interfaces/Routable.md).
+- [Viewable](@xmachines/play-view/index/interfaces/Viewable.md) is the rendering contract: actors expose `currentView` plus a component catalog so rendering packages can resolve UI without owning application state.
+- [Routable](@xmachines/play-router/index/interfaces/Routable.md) is the routing contract: actors expose `currentRoute` plus route-oriented event handling, while adapters translate browser or router changes into actor events.
 - Rendering actor-driven UI: use [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), [@xmachines/play-svelte](@xmachines/play-svelte/README.md), or [@xmachines/play-vue](@xmachines/play-vue/README.md).
 - Synchronizing URLs with actor state: use [@xmachines/play-router](@xmachines/play-router/README.md) plus a framework-specific router adapter.
 
@@ -19,12 +19,14 @@
 
 - `Core runtime`: [@xmachines/play](@xmachines/play/README.md), [@xmachines/play-actor](@xmachines/play-actor/README.md), [@xmachines/play-signals](@xmachines/play-signals/README.md), [@xmachines/play-router](@xmachines/play-router/README.md), and [@xmachines/play-xstate](@xmachines/play-xstate/README.md). Catalog and component registry are provided by `@xmachines/json-render-core` and the framework rendering packages.
 - `Rendering`: [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), [@xmachines/play-svelte](@xmachines/play-svelte/README.md), and [@xmachines/play-vue](@xmachines/play-vue/README.md).
-- `Router adapters`: [@xmachines/play-react-router](@xmachines/play-react-router/README.md), [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md), [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md), [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md), [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md), [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md), and [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md), all built on top of [Routable](@xmachines/play-actor/interfaces/Routable.md) actors and shared route metadata.
+- `Router adapters`: [@xmachines/play-react-router](@xmachines/play-react-router/README.md), [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md), [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md), [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md), [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md), [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md), and [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md), all built on top of [Routable](@xmachines/play-router/index/interfaces/Routable.md) actors and shared route metadata.
 - `Shared tooling`: [@xmachines/shared](@xmachines/shared/README.md) for shared config and workspace-level support files.
 
 ## API
 - [@xmachines/play](@xmachines/play/README.md): Core Play types and runtime contracts
-- [@xmachines/play-actor](@xmachines/play-actor/README.md): Abstract actor base class plus Routable and Viewable capabilities
+- [@xmachines/play-actor](@xmachines/play-actor/README.md): The actor contract: state and send. It names no state machine library, and each capability interface lives with its own package
+- [@xmachines/play-url](@xmachines/play-url/README.md): The URL language: the URLPattern grammar, a base path, and the params of a framework router
+- [@xmachines/play-view](@xmachines/play-view/README.md): The shared view half of every renderer: Viewable, PlaySpec, and the view store lifecycle
 - [@xmachines/play-dom](@xmachines/play-dom/README.md): Vanilla DOM renderer for Viewable actors
 - [@xmachines/play-dom-router](@xmachines/play-dom-router/README.md): Vanilla DOM browser history, router, and actor↔URL synchronization
 - [@xmachines/play-signals](@xmachines/play-signals/README.md): Signal primitives used by Play actors and adapters
@@ -48,19 +50,22 @@
 
 - Prefer the core packages before the demo apps; demos are intentionally excluded from this file.
 - For implementation questions, usually read in this order: [@xmachines/play-actor](@xmachines/play-actor/README.md) -> [@xmachines/play-xstate](@xmachines/play-xstate/README.md) -> [@xmachines/play-router](@xmachines/play-router/README.md) -> framework renderer/adapter.
-- [Routable](@xmachines/play-actor/interfaces/Routable.md) is the key abstraction for URL synchronization: router adapters observe and update actor route state but do not own navigation policy.
+- [Routable](@xmachines/play-router/index/interfaces/Routable.md) is the key abstraction for URL synchronization: router adapters observe and update actor route state but do not own navigation policy.
 - Router adapter packages are passive infrastructure; business logic stays in the actor and machine layers.
-- Rendering packages consume the [Viewable](@xmachines/play-actor/interfaces/Viewable.md) contract and component catalogs rather than owning application state.
+- Rendering packages consume the [Viewable](@xmachines/play-view/index/interfaces/Viewable.md) contract and component catalogs rather than owning application state.
 
 ## Quick Reference
 
 ```javascript
-import { definePlayer } from '@xmachines/play-xstate';
-import { createRouteMapFromTree, extractMachineRoutes, extractRouteParams } from '@xmachines/play-router';
+import { definePlayer, compose, PlayerActor } from '@xmachines/play-xstate';
+import { withRouting } from '@xmachines/play-xstate/routing';
+import { withView } from '@xmachines/play-xstate/view';
+import { createRouteMapFromTree, extractRouteParams } from '@xmachines/play-router';
+import { extractMachineRoutes } from '@xmachines/play-router/xstate';
 import { defineRegistry } from '@xmachines/json-render-react';
 import { PlayRenderer } from '@xmachines/play-react';
 
-const createPlayer = definePlayer({ machine });
+const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting, withView) });
 const actor = createPlayer();
 actor.start();
 

package/contributing/architecture.md

@@ -27,12 +27,17 @@ graph TD
     end
 
     subgraph Layer1["Layer 1 — Abstract Actor Base"]
-        actor["@xmachines/play-actor\n(AbstractActor, Routable, Viewable, PlaySpec)"]
+        actor["@xmachines/play-actor\n(PlayActor)"]
+    end
+
+    subgraph Layer2v["Layer 2 — The View Half"]
+        view["@xmachines/play-view\n(Viewable, PlaySpec, the view store lifecycle)"]
     end
 
     subgraph Layer2["Layer 2 — Concrete Implementations"]
-        xstate["@xmachines/play-xstate\n(PlayerActor, definePlayer, guards, routing)"]
-        router["@xmachines/play-router\n(RouterBridgeBase, RouteMap, extractMachineRoutes)"]
+        xstate["@xmachines/play-xstate\n(PlayerActor, definePlayer, routing)"]
+        router["@xmachines/play-router\n(RouterBridgeBase, RouteMap, Routable)"]
+        routerxstate["@xmachines/play-router/xstate\n(extractMachineRoutes, createRouteMap)"]
 
         subgraph Views["View Renderers"]
             react["@xmachines/play-react"]
@@ -73,18 +78,22 @@ graph TD
 | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- |
 | [`@xmachines/play`](../api/@xmachines/play/README.md)                                             | Core protocol types and error base class                | `packages/play/src/index.ts`                                        |
 | [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md)                             | TC39 Signal polyfill isolation wrapper                  | `packages/play-signals/src/index.ts`                                |
-| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `AbstractActor` base class + capability interfaces      | `packages/play-actor/src/abstract-actor.ts`                         |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `PlayActor`, and nothing else                           | `packages/play-actor/src/play-actor.ts`                             |
+| [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)                                   | `Viewable`, `PlaySpec`, the shared view half            | `packages/play-view/src/view-types.ts`                              |
 | [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | XState v5 adapter: `definePlayer`, `PlayerActor`        | `packages/play-xstate/src/player-actor.ts`                          |
-| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | Route extraction, `RouteMap`, `RouterBridgeBase`        | `packages/play-router/src/router-bridge-base.ts`                    |
+| [`@xmachines/play-url`](../api/@xmachines/play-url/README.md)                                     | The URLPattern grammar, a base path, framework params   | `packages/play-url/src/pattern-grammar.ts`                          |
+| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | `RouteMap`, `RouterBridgeBase`, the provider lifecycle  | `packages/play-router/src/router-bridge-base.ts`                    |
+| [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md)                        | Route extraction from an XState machine                 | `packages/play-router/src/xstate/extract-routes.ts`                 |
 | [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)                                 | React renderer: `ActorProvider`, `PlayRenderer`         | `packages/play-react/src/ActorProvider.tsx`                         |
 | [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)                                     | Vue 3 renderer: `ActorProvider.vue`, `PlayRenderer.vue` | `packages/play-vue/src/ActorProvider.vue`                           |
 | [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)                                 | SolidJS renderer                                        | `packages/play-solid/src/ActorProvider.tsx`                         |
 | [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md)                               | Svelte 5 renderer                                       | `packages/play-svelte/src/ActorProvider.svelte`                     |
 | [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)                                     | Vanilla DOM renderer                                    | `packages/play-dom/src/create-play-ui.ts`                           |
+| [`@xmachines/play-tanstack-router`](../api/@xmachines/play-tanstack-router/README.md)             | The framework-free TanStack bridge base                 | `packages/play-tanstack-router/src/tanstack-router-bridge-base.ts`  |
 | [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | TanStack React Router bridge                            | `packages/play-tanstack-react-router/src/tanstack-router-bridge.ts` |
 | [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | TanStack SolidJS Router bridge                          | `packages/play-tanstack-solid-router/src/solid-router-bridge.ts`    |
 | [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | Vue Router 4/5 bridge                                   | `packages/play-vue-router/src/vue-router-bridge.ts`                 |
-| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router v7 bridge                                  | `packages/play-react-router/src/react-router-bridge.ts`             |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router 7/8 bridge                                 | `packages/play-react-router/src/react-router-bridge.ts`             |
 | [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | SolidJS Router bridge                                   | `packages/play-solid-router/src/solid-router-bridge.ts`             |
 | [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | Vanilla DOM hash/history router bridge                  | `packages/play-dom-router/src/dom-router-bridge.ts`                 |
 | [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | SvelteKit router bridge                                 | `packages/play-sveltekit-router/src/sveltekit-router-bridge.ts`     |
@@ -186,7 +195,7 @@ flowchart TD
 
 ## Key Abstractions
 
-### [`PlayEvent<TPayload>`](../api/@xmachines/play/type-aliases/PlayEvent.md)
+### [`PlayEvent<TPayload>`](../api/@xmachines/play/index/type-aliases/PlayEvent.md)
 
 The minimal event contract for Actor communication: any object with a `readonly type: string` property. `TPayload` extends `Record<string, unknown>` for additional fields. Framework-agnostic; used directly by XState, router adapters, and domain logic. Part of [`@xmachines/play`](../api/@xmachines/play/README.md).
 
@@ -196,12 +205,12 @@ import type { PlayEvent } from "@xmachines/play";
 type LoginEvent = PlayEvent<{ userId: string; timestamp: number }>;
 ```
 
-### [`PlayError`](../api/@xmachines/play/classes/PlayError.md)
+### [`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md)
 
 Base class for all `@xmachines/*` typed runtime errors. Carries `scope` (throwing class/module) and `code` (stable machine-readable identifier, e.g. `"PLAY_ROUTER_SYNC_FAILED"`). Subclassed per package, exported from each package's `./errors` subpath. Never match on `.message` — always match on `.code` or the subclass.
 
 ```typescript
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
 import { RouterSyncError } from "@xmachines/play-router/errors";
 
 if (err instanceof RouterSyncError) {
@@ -209,27 +218,37 @@ if (err instanceof RouterSyncError) {
 }
 ```
 
-### [`AbstractActor<TLogic, TEvent>`](../api/@xmachines/play-actor/classes/AbstractActor.md)
+### [`PlayActor<TSnapshot, TEvent>`](../api/@xmachines/play-actor/interfaces/PlayActor.md)
 
-Abstract base class extending XState `Actor`. Declares `public abstract state: Signal.State<unknown>` and `public abstract override send(event: TEvent): void`. Maintains XState ecosystem compatibility (devtools, inspection) while enforcing the signal protocol. Concrete implementations extend this (e.g. [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md)).
+The actor contract, as an INTERFACE. It asks for two members: a reactive `state: Signal.State<TSnapshot>`, and a typed `send(event: TEvent): void`. It names no state machine library, so a consumer of the contract installs `xstate` never. An implementation satisfies it (e.g. [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)).
 
-### [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md)
+### [`Routable`](../api/@xmachines/play-router/index/interfaces/Routable.md)
 
-Optional capability interface. Exposes `currentRoute: Signal.Computed<string | null>` (derived URL path) and `readonly initialRoute: string | null` (machine's initial route, fixed at definition time). Router bridges consume this interface directly — they never depend on the concrete [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md).
+Optional capability interface. Exposes `currentRoute: Signal.Computed<string | null>` (derived URL path) and `readonly initialRoute: string | null` (machine's initial route, fixed at definition time). Router bridges consume this interface directly — they never depend on the concrete [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md).
 
-### [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md)
+### [`Viewable`](../api/@xmachines/play-view/index/interfaces/Viewable.md)
 
 Optional capability interface. Exposes `currentView: Signal.State<PlaySpec | null>`. View renderers (`PlayRenderer`) consume this contract to resolve the current view description into UI without coupling to the framework or actor implementation.
 
-### [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)
+### [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md)
 
 Extends `@xmachines/json-render-core` `Spec`. `deriveCurrentView` projects the machine's whole context into the derived spec's `state` under the read-only `/context` subtree, and stamps a `viewKey` from the selected meta entry so providers can reseed vs refresh their store. Specs read context through the ordinary `{ $state: "/context/…" }` grammar; element props are never enriched. `typedSpec()` type-checks the spec literal at the definition site (XState's `meta` is untyped).
 
-### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
+### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)
+
+Concrete XState v5 actor. It extends XState's own `Actor` directly, and it implements [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md). It receives the machine in its constructor, so an instance IS the actor rather than a wrapper around one. Bridges its own subscription to TC39 Signals. Exposes: `state`, `send()`, `start()`, `stop()`, `can()`.
+
+[`Routable`](../api/@xmachines/play-router/index/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-view/index/interfaces/Viewable.md) are OPTIONAL capabilities, and the class implements neither. Each one is a mixin behind its own entry point — `@xmachines/play-xstate/routing` and `@xmachines/play-xstate/view` — and `compose` builds the class that an application needs:
+
+```typescript
+definePlayer({ machine, actor: compose(PlayerActor, withRouting, withView) });
+```
+
+The core imports neither capability, so an application that declares no route loads no routing code, and one that renders no view loads no view code and installs no json-render.
 
-Concrete XState v5 actor implementing the full signal protocol. Extends [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) — and so XState's own `Actor`, receiving the machine in its constructor, so an instance IS the actor rather than a wrapper around one; implements both [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md). Bridges its own subscription to TC39 Signals. Exposes: `state`, `currentRoute`, `currentView`, `initialRoute`, `send()`, `start()`, `stop()`, `can()`, `dispose()`.
+**The composition order is the derivation order.** `PlayerActor` owns ONE subscription and calls a protected `onSnapshot` hook after `state` holds the new snapshot. A capability overrides that hook and calls `super.onSnapshot()` first, so `compose(PlayerActor, withRouting, withView)` derives the route before the view. That order is load-bearing: a router bridge must see a guard redirect synchronously, and the view of a state reads the route that the same transition produced.
 
-### [`definePlayer(config)`](../api/@xmachines/play-xstate/functions/definePlayer.md) → [`PlayerFactory`](../api/@xmachines/play-xstate/type-aliases/PlayerFactory.md)
+### [`definePlayer(config)`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) → [`PlayerFactory`](../api/@xmachines/play-xstate/index/type-aliases/PlayerFactory.md)
 
 Factory creator. Each call constructs one `PlayerActor`, which is itself the XState actor and derives its own `initialRoute` from its pre-start snapshot. Restoring a snapshot is the exception: the default initial route can only come from XState's pure `initialTransition` helper, whose inert actor scope constructs a throwaway actor and evaluates the initial transition twice. Returns `(input?, restore?) => PlayerActor<TMachine>`.
 
@@ -241,7 +260,7 @@ const actor = createPlayer(); // or createPlayer(input) or createPlayer(undefine
 actor.start();
 ```
 
-### [`RouterBridgeBase`](../api/@xmachines/play-router/classes/RouterBridgeBase.md)
+### [`RouterBridgeBase`](../api/@xmachines/play-router/index/classes/RouterBridgeBase.md)
 
 Abstract base class capturing all common router bridge logic. Template Method pattern — subclasses implement exactly three abstract methods: `navigateRouter(path)`, `watchRouterChanges()`, `unwatchRouterChanges()`. Manages `isConnected`, `lastSyncedPath` (echo suppression), `isProcessingNavigation` (re-entrant guard redirect prevention), and `routeWatcher` lifecycle. Enforces one-bridge-per-actor via a module-level `WeakMap`.
 
@@ -259,11 +278,11 @@ class MyRouterBridge extends RouterBridgeBase {
 }
 ```
 
-### [`RouteMap`](../api/@xmachines/play-router/classes/RouteMap.md) / [`createRouteMap`](../api/@xmachines/play-router/functions/createRouteMap.md)
+### [`RouteMap`](../api/@xmachines/play-router/index/classes/RouteMap.md) / [`createRouteMap`](../api/@xmachines/play-router/xstate/functions/createRouteMap.md)
 
-Bidirectional `stateId ↔ URL path` lookup. [`createRouteMap(machine)`](../api/@xmachines/play-router/functions/createRouteMap.md) → [`RouteMap`](../api/@xmachines/play-router/classes/RouteMap.md). [`createRouteMapFromTree(routeTree)`](../api/@xmachines/play-router/functions/createRouteMapFromTree.md) takes the output of [`extractMachineRoutes(machine)`](../api/@xmachines/play-router/functions/extractMachineRoutes.md) directly. Internally uses `URLPattern` for parameterized route matching (e.g. `/profile/:userId`).
+Bidirectional `stateId ↔ URL path` lookup. [`createRouteMap(machine)`](../api/@xmachines/play-router/xstate/functions/createRouteMap.md) of `@xmachines/play-router/xstate` → [`RouteMap`](../api/@xmachines/play-router/index/classes/RouteMap.md). [`createRouteMapFromTree(routeTree)`](../api/@xmachines/play-router/index/functions/createRouteMapFromTree.md) of `@xmachines/play-router` takes the output of [`extractMachineRoutes(machine)`](../api/@xmachines/play-router/xstate/functions/extractMachineRoutes.md) directly. Both drop the synthetic root node of the tree, so neither map answers a state ID that the machine does not hold. The match of a parameterized route, for example `/profile/:userId`, uses `URLPattern` of [`@xmachines/play-url`](../api/@xmachines/play-url/README.md).
 
-### [`PlayRouteEvent`](../api/@xmachines/play-router/interfaces/PlayRouteEvent.md)
+### [`PlayRouteEvent`](../api/@xmachines/play-router/index/interfaces/PlayRouteEvent.md)
 
 Unified routing event sent by router adapters to the Actor.
 
@@ -281,7 +300,7 @@ interface PlayRouteEvent {
 
 Subscribe to a single TC39 signal with microtask batching and memory-safe cleanup. Uses a one-shot `Signal.subtle.Watcher` lifecycle — re-arms after each notification. `disposed` flag guards post-cleanup callbacks; `needsEnqueue` deduplicates rapid synchronous signal changes. Returns a `() => void` cleanup function.
 
-### [`formatPlayRouteTransitions(machineConfig)`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md)
+### [`formatPlayRouteTransitions(machineConfig)`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md)
 
 Crawls machine state configs looking for states with `meta.route` and auto-generates `play.route` transition handlers at the root machine level. Each generated transition targets the matching state, guards on `event.to === "#stateId"`, and assigns `event.params` and `event.query` to context. Returns the same config type `T` — directly usable by `setup().createMachine()`.
 
@@ -306,11 +325,11 @@ All five view renderer packages follow an identical structural pattern:
 | [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md) | Svelte 5 runes (`$effect`) via `actor-context.svelte.ts`                                                                                                                                                                                          |
 | [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)       | Manual DOM updates via [`createPlayUI`](../api/@xmachines/play-dom/functions/createPlayUI.md) / [`createRenderer`](../api/@xmachines/play-dom/functions/createRenderer.md) / [`PlayRenderer`](../api/@xmachines/play-dom/classes/PlayRenderer.md) |
 
-Per-view component state is managed by `@xstate/store`: a fresh store atom is created per [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) transition (uncontrolled mode), or an external `store` prop is passed via `ActorProvider`/`PlayUIProvider` (controlled mode).
+Per-view component state is managed by `@xstate/store`: a fresh store atom is created per [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md) transition (uncontrolled mode), or an external `store` prop is passed via `ActorProvider`/`PlayUIProvider` (controlled mode).
 
 ## Router Adapter Pattern
 
-All eight router adapter packages follow the Template Method pattern via [`RouterBridgeBase`](../api/@xmachines/play-router/classes/RouterBridgeBase.md). Each adapter implements exactly three abstract methods:
+All eight router adapter packages follow the Template Method pattern via [`RouterBridgeBase`](../api/@xmachines/play-router/index/classes/RouterBridgeBase.md). Each adapter implements exactly three abstract methods:
 
 ```typescript
 // How to tell the framework router to change URL
@@ -344,22 +363,22 @@ packages/
 ├── play/                       # Layer 0: Core protocol: PlayEvent, PlayError, assertNonNullable
 ├── play-signals/               # Layer 0: TC39 Signal polyfill wrapper — all signal imports go here
 │   └── src/                    # Re-exports signal-polyfill; watchSignal utility
-├── play-actor/                 # Layer 1: AbstractActor base + Routable, Viewable, PlaySpec interfaces
+├── play-actor/                 # Layer 1: the PlayActor contract — state and send, and nothing else
+├── play-url/                   # Layer 1: the URL language — the URLPattern grammar, a base path, framework params
+├── play-view/                  # Layer 2: Viewable, PlaySpec, the view store lifecycle, the context projection
 │
 ├── play-xstate/                # Layer 2: Concrete XState v5 actor: definePlayer, PlayerActor
 │   └── src/
 │       ├── player-actor.ts              # PlayerActor — concrete actor
 │       ├── define-player.ts             # definePlayer factory
-│       ├── guards/                      # composeGuards, composeGuardsOr, negateGuard, hasContext...
 │       ├── routing/                     # deriveRoute, buildRouteUrl, formatPlayRouteTransitions
 │       └── view/                        # deriveCurrentView (meta.view → PlaySpec)
 │
 ├── play-router/                # Layer 2: Route extraction, bidirectional mapping, bridge base
 │   └── src/
 │       ├── router-bridge-base.ts        # RouterBridgeBase (Template Method for all adapters)
-│       ├── extract-routes.ts            # extractMachineRoutes → RouteTree
 │       ├── base-route-map.ts            # RouteMap (bidirectional stateId ↔ path)
-│       ├── create-route-map.ts          # createRouteMap factory (URLPattern-based)
+│       ├── xstate/                      # the machine half — extractMachineRoutes, createRouteMap
 │       ├── router-sync.ts               # buildPlayRouteEvent, extractRouteParams, sanitizePathname
 │       └── types.ts                     # PlayRouteEvent, RouterBridge, RouteTree, WindowLike...
 │
@@ -371,7 +390,7 @@ packages/
 │
 ├── play-tanstack-react-router/ # Router adapter: TanStack Router (React)
 ├── play-tanstack-solid-router/ # Router adapter: TanStack Router (SolidJS)
-├── play-react-router/          # Router adapter: React Router v7
+├── play-react-router/          # Router adapter: React Router 7/8
 ├── play-vue-router/            # Router adapter: Vue Router 4/5
 ├── play-solid-router/          # Router adapter: SolidJS Router
 ├── play-svelte-spa-router/     # Router adapter: Svelte SPA Router
@@ -409,28 +428,39 @@ flowchart LR
     end
     subgraph L1["Layer 1 — depends on L0"]
         pa[play-actor]
+        pu[play-url]
     end
-    subgraph L2["Layer 2 — depends on L0 + L1"]
+    subgraph L2["Layer 2 — the view half"]
+        pvw[play-view]
+    end
+    subgraph L3r["Layer 3 — the routers, which read NO view package"]
         pr[play-router]
         pdr[play-dom-router]
         psk[play-sveltekit-router]
-        px[play-xstate]
-        prea[play-react]
-        pv[play-vue]
-        pso[play-solid]
-        psv[play-svelte]
-        pdo[play-dom]
         ptsr[play-tanstack-react-router]
         pvr[play-vue-router]
         psor[play-solid-router]
         pssr[play-svelte-spa-router]
         ptss[play-tanstack-solid-router]
     end
-    subgraph L3["Layer 3 — examples / play-react-router"]
+    subgraph L3v["Layer 3 — the renderers and the xstate adapter, which read L2"]
+        px[play-xstate]
+        prea[play-react]
+        pvue[play-vue]
+        pso[play-solid]
+        psv[play-svelte]
+        pdo[play-dom]
+    end
+    subgraph L4["Layer 4 — examples / play-react-router"]
         ex["play-react-router\nplay-*/examples/demo"]
     end
 
-    L0 --> L1 --> L2 --> L3
+    L0 --> L1
+    L1 --> L2
+    L1 --> L3r
+    L2 --> L3v
+    L3r --> L4
+    L3v --> L4
 ```
 
 With `declarationMap: true` in the base tsconfig (from `@xmachines/shared/tsconfig`), IDE "Go to Definition" jumps to TypeScript source files rather than compiled `.d.ts` files, and refactoring works correctly across package boundaries without requiring a build step.
@@ -440,14 +470,16 @@ With `declarationMap: true` in the base tsconfig (from `@xmachines/shared/tsconf
 | Layer                                           | May import from                                     | Must not import from             |
 | ----------------------------------------------- | --------------------------------------------------- | -------------------------------- |
 | Protocol (`play`, `play-signals`, `play-actor`) | External libs only                                  | Any other `@xmachines/*` package |
+| View half (`play-view`)                         | Protocol layer, `@xmachines/json-render-core`       | Router adapters, framework code  |
 | Actor logic (`play-xstate`)                     | Protocol layer                                      | View renderers, router adapters  |
-| Router infrastructure (`play-router`)           | Protocol layer, `@statelyai/graph`                  | View renderers                   |
+| URL language (`play-url`)                       | Protocol layer, `urlpattern-polyfill`               | Any other `@xmachines/*` package |
+| Router infrastructure (`play-router`)           | Protocol layer, `play-url`, `@statelyai/graph`      | View renderers                   |
 | Router adapters (`play-*-router`)               | `play-router`, protocol layer, framework router lib | Other view renderers             |
 | View renderers (`play-*`)                       | Protocol layer, `@xmachines/json-render-*`          | Router adapters                  |
 
 ## Error Handling
 
-All `@xmachines/*` errors extend [`PlayError`](../api/@xmachines/play/classes/PlayError.md) and carry two stable fields:
+All `@xmachines/*` errors extend [`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md) and carry two stable fields:
 
 - `scope` — the class or module that threw (e.g. `"RouterBridgeBase"`)
 - `code` — a stable machine-readable identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`)
@@ -456,48 +488,44 @@ All `@xmachines/*` errors extend [`PlayError`](../api/@xmachines/play/classes/Pl
 
 ```mermaid
 flowchart TD
-    PE["PlayError\n@xmachines/play"]
+    PE["PlayError\n@xmachines/play/errors"]
     PE --> NNE["NonNullableError\nPLAY_NON_NULLABLE"]
     PE --> RSE["RouterSyncError\nPLAY_ROUTER_SYNC_FAILED"]
-    PE --> UPE["URLPatternUnavailableError\nPLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE"]
     PE --> DBE["DuplicateBridgeError\nPLAY_ROUTER_DUPLICATE_BRIDGE"]
     PE --> IEE["InvalidEventError\nPLAY_XSTATE_INVALID_EVENT"]
     PE --> IME["InvalidMachineError\nPLAY_XSTATE_INVALID_MACHINE"]
     PE --> MRP["MissingRouteParamError\nPLAY_XSTATE_ROUTE_PARAM_MISSING"]
     PE --> MSI["MissingStateIdError\nPLAY_XSTATE_MISSING_STATE_ID"]
-    PE --> MQC["MissingQueryContextError\nPLAY_XSTATE_MISSING_QUERY_CONTEXT\n(deprecated — never thrown)"]
     PE --> IRE["InvalidRouteMetadataError\nPLAY_XSTATE_INVALID_ROUTE_METADATA"]
     PE --> ATN["ActorThrewNonErrorError\nPLAY_XSTATE_NON_ERROR_THROWN"]
-    PE --> EGA["EmptyGuardArrayError\nPLAY_XSTATE_EMPTY_GUARD_ARRAY"]
 ```
 
 Package-specific errors are exported from `./errors` subpath imports:
 
 ```typescript
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
 import { RouterSyncError } from "@xmachines/play-router/errors";
 import { InvalidEventError } from "@xmachines/play-xstate/errors";
 ```
 
 **Error behavior by case:**
 
-| Error                        | Package       | Behavior                                                                                   |
-| ---------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
-| `MissingRouteParamError`     | `play-xstate` | Transient — `currentRoute` returns `null`; does not throw                                  |
-| `MissingQueryContextError`   | `play-xstate` | Deprecated — never thrown; exported only so existing `instanceof` handlers keep compiling  |
-| `ActorThrewNonErrorError`    | `play-xstate` | Constructed for `onError` when the machine throws a non-`Error`; original value on `cause` |
-| `EmptyGuardArrayError`       | `play-xstate` | Structural programmer error — `composeGuards`/`composeGuardsOr` called with `[]`           |
-| `RouterSyncError`            | `play-router` | Wraps router sync failures                                                                 |
-| `DuplicateBridgeError`       | `play-router` | Two bridges registered for the same actor                                                  |
-| `URLPatternUnavailableError` | `play-router` | URLPattern API missing — load `urlpattern-polyfill`                                        |
-| View errors                  | `play-xstate` | Caught in `validateAndCacheView()`; forwarded to `onError` hook; last valid view retained  |
+| Error                     | Package       | Behavior                                                                                   |
+| ------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
+| `MissingRouteParamError`  | `play-xstate` | Transient — `currentRoute` returns `null`; does not throw                                  |
+| `ActorThrewNonErrorError` | `play-xstate` | Constructed for `onError` when the machine throws a non-`Error`; original value on `cause` |
+| `RouterSyncError`         | `play-router` | Wraps router sync failures                                                                 |
+| `DuplicateBridgeError`    | `play-router` | Two bridges registered for the same actor                                                  |
+| View errors               | `play-xstate` | Caught in `validateAndCacheView()`; forwarded to `onError` hook; last valid view retained  |
 
 ## Application Bootstrap (React example)
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions, withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 import { createRouteMapFromTree, PlayRouterProvider } from "@xmachines/play-tanstack-react-router";
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
 
@@ -530,8 +558,8 @@ const machine = setup({}).createMachine(machineConfig);
 const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMapFromTree(routeTree);
 
-// 3. Create player factory and start actor
-const createPlayer = definePlayer({ machine });
+// 3. Create player factory and start actor — the providers need BOTH capabilities
+const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting, withView) });
 const actor = createPlayer();
 actor.start();
 
@@ -574,23 +602,23 @@ const currentUser = useActorSelector(actor, (s) => s.context.currentUser);
 
 ### Calling `navigateRouter` inside `watchRouterChanges`
 
-Calling `navigateRouter()` before updating `lastSyncedPath` inside the `watchRouterChanges` callback causes an echo loop. The router navigation fires the watcher again, which sends a duplicate `play.route` event. Always update `lastSyncedPath` before calling `navigateRouter()` — see [`RouterBridgeBase`](../api/@xmachines/play-router/classes/RouterBridgeBase.md) source at `packages/play-router/src/router-bridge-base.ts`.
+Calling `navigateRouter()` before updating `lastSyncedPath` inside the `watchRouterChanges` callback causes an echo loop. The router navigation fires the watcher again, which sends a duplicate `play.route` event. Always update `lastSyncedPath` before calling `navigateRouter()` — see [`RouterBridgeBase`](../api/@xmachines/play-router/index/classes/RouterBridgeBase.md) source at `packages/play-router/src/router-bridge-base.ts`.
 
 ### Skipping `sanitizePathname` in custom bridge implementations
 
-Custom `watchRouterChanges()` implementations that bypass `syncActorFromRouter()` and process pathnames directly skip the length/content guards that protect the route-map lookup from malformed or oversized paths. Always call [`sanitizePathname(path)`](../api/@xmachines/play-router/functions/sanitizePathname.md) before processing.
+Custom `watchRouterChanges()` implementations that bypass `syncActorFromRouter()` and process pathnames directly skip the length/content guards that protect the route-map lookup from malformed or oversized paths. Always call [`sanitizePathname(path)`](../api/@xmachines/play-router/index/functions/sanitizePathname.md) before processing.
 
 ## Cross-Cutting Concerns
 
-**Circular update prevention:** `lastSyncedPath` in [`RouterBridgeBase`](../api/@xmachines/play-router/classes/RouterBridgeBase.md) provides echo suppression for the actor→router direction; `isProcessingNavigation` flag guards against re-entrant guard-redirect loops in `syncActorFromRouter`. `needsEnqueue` in [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md) deduplicates rapid synchronous signal changes via microtask batching.
+**Circular update prevention:** `lastSyncedPath` in [`RouterBridgeBase`](../api/@xmachines/play-router/index/classes/RouterBridgeBase.md) provides echo suppression for the actor→router direction; `isProcessingNavigation` flag guards against re-entrant guard-redirect loops in `syncActorFromRouter`. `needsEnqueue` in [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md) deduplicates rapid synchronous signal changes via microtask batching.
 
-**SSR / test injection:** [`WindowLike`](../api/@xmachines/play-router/interfaces/WindowLike.md) and [`LocationLike`](../api/@xmachines/play-router/interfaces/LocationLike.md) structural interfaces in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) allow injecting mock objects in router adapters, enabling testing without a real browser environment.
+**SSR / test injection:** [`WindowLike`](../api/@xmachines/play-router/index/interfaces/WindowLike.md) and [`LocationLike`](../api/@xmachines/play-router/index/interfaces/LocationLike.md) structural interfaces in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) allow injecting mock objects in router adapters, enabling testing without a real browser environment.
 
-**Logging:** No structured logging framework. [`PlayerOptions`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md) exposes lifecycle hooks — `onStart`, `onStop`, `onTransition`, `onStateChange`, `onError` — as observability extension points. A renderer writes to `console.error` in ONE case: it contained a failure, and no handler of the host receives that failure. Such a failure is the one result that nobody can debug. Give `onError` to send the failure of a view to your own observability tool instead.
+**Logging:** No structured logging framework. [`PlayerOptions`](../api/@xmachines/play-xstate/index/interfaces/PlayerOptions.md) exposes lifecycle hooks — `onStart`, `onStop`, `onTransition`, `onStateChange`, `onError` — as observability extension points. A renderer writes to `console.error` in ONE case: it contained a failure, and no handler of the host receives that failure. Such a failure is the one result that nobody can debug. Give `onError` to send the failure of a view to your own observability tool instead.
 
 Five paths reach that case. The host gives no `onError` prop. The handler of the host throws, or the producer of the `fallback` throws, or a release of the caller throws — each of those reports the failure of the HOST, which no handler of the host receives. `ActorProvider` of play-vue stops a second report of one error, and `onError` stays silent there on purpose, because the four other renderers see such an error never.
 
-Three other places write to `console.warn`, and each one reports a configuration that the library cannot refuse: `warnOnce` of `@xmachines/play-actor` names a `/context` projection that it cannot derive, one time for each spec; `@xmachines/play-xstate` names the `meta.view.contextProps` field that 1.x removed, one time for each spec; and `@xmachines/play-router` names a `basePath` that a bridge with no mount ignores. A warning is the answer where a throw would stop an application for a fault that it can still run with. No other library source calls `console.*`.
+Three other places write to `console.warn`, and each one reports a configuration that the library cannot refuse: `warnOnce` of `@xmachines/play-view` names a `/context` projection that it cannot derive, one time for each spec; `@xmachines/play-xstate` names the `meta.view.contextProps` field that 1.x removed, one time for each spec; and `@xmachines/play-router` names a `basePath` that a bridge with no mount ignores. A warning is the answer where a throw would stop an application for a fault that it can still run with. No other library source calls `console.*`.
 
 **Authentication:** Not in scope. Enforced via XState guards on `play.route` transitions. The guard evaluates machine `context` (e.g., `isLoggedIn`) before permitting navigation. No library-level auth primitives — the machine defines all access control.