@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.48

package/guides/README.md

@@ -7,14 +7,14 @@ Entry points for the current XMachines Play architecture.
 ## Start Here
 
 - **[Installation](installation.md)** — Core packages, framework-specific additions, TypeScript config, ESM setup
-- **[Getting Started](getting-started.md)** — `setup().createMachine()` → `definePlayer()` → `actor.start()` → TC39 Signals
+- **[Getting Started](getting-started.md)** — `setup().createMachine()` → [`definePlayer()`](../api/@xmachines/play-xstate/functions/definePlayer.md) → `actor.start()` → TC39 Signals
 
 ## Concepts
 
 Background reading that explains the _why_ behind XMachines design decisions. Read these when you want to understand the architecture, not just use the API.
 
 - **[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, scattered guards, and component-level routing logic
-- **[Understanding the Actor Model](actor-model.md)** — The actor/infrastructure split, what `AbstractActor` enforces, why the machine has zero framework imports, and how the reset invariant works
+- **[Understanding the Actor Model](actor-model.md)** — The actor/infrastructure split, what [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) enforces, why the machine has zero framework imports, and how the reset invariant works
 - **[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 five architectural invariants they enforce
 
 ## Examples
@@ -25,8 +25,8 @@ Background reading that explains the _why_ behind XMachines design decisions. Re
 
 Framework-specific adapter documentation:
 
-- **[@xmachines/play-router](../api/@xmachines/play-router/README.md)** — Route extraction, route maps, and `RouterBridgeBase`
-- **[@xmachines/play-tanstack-react-router](../api/@xmachines/play-tanstack-react-router/README.md)** — TanStack React adapter (`PlayRouterProvider`, `createRouteMapFromTree`)
+- **[@xmachines/play-router](../api/@xmachines/play-router/README.md)** — Route extraction, route maps, and [`RouterBridgeBase`](../api/@xmachines/play-router/classes/RouterBridgeBase.md)
+- **[@xmachines/play-tanstack-react-router](../api/@xmachines/play-tanstack-react-router/README.md)** — TanStack React adapter (`PlayRouterProvider`, [`createRouteMapFromTree`](../api/@xmachines/play-router/functions/createRouteMapFromTree.md))
 - **[@xmachines/play-react-router](../api/@xmachines/play-react-router/README.md)** — React Router v7 data-router adapter
 - **[@xmachines/play-tanstack-solid-router](../api/@xmachines/play-tanstack-solid-router/README.md)** — TanStack Solid adapter
 - **[@xmachines/play-solid-router](../api/@xmachines/play-solid-router/README.md)** — SolidJS Router adapter
@@ -39,12 +39,12 @@ Framework-specific adapter documentation:
 
 View layer documentation by framework:
 
-- **[@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md)** — `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor`
-- **[@xmachines/play-react](../api/@xmachines/play-react/README.md)** — React rendering from actor-driven view state (`PlayRenderer`, `defineRegistry`)
+- **[@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md)** — [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
+- **[@xmachines/play-react](../api/@xmachines/play-react/README.md)** — React rendering from actor-driven view state (`PlayRenderer`, [`defineRegistry`](../api/@xmachines/play-dom/functions/defineRegistry.md))
 - **[@xmachines/play-vue](../api/@xmachines/play-vue/README.md)** — Vue rendering from actor-driven view state
 - **[@xmachines/play-solid](../api/@xmachines/play-solid/README.md)** — SolidJS rendering from actor-driven view state
 - **[@xmachines/play-svelte](../api/@xmachines/play-svelte/README.md)** — Svelte 5 rendering from actor-driven view state
-- **[@xmachines/play-dom](../api/@xmachines/play-dom/README.md)** — Vanilla DOM rendering (`connectRenderer`, `defineRegistry`)
+- **[@xmachines/play-dom](../api/@xmachines/play-dom/README.md)** — Vanilla DOM rendering ([`connectRenderer`](../api/@xmachines/play-dom/functions/connectRenderer.md), [`defineRegistry`](../api/@xmachines/play-dom/functions/defineRegistry.md))
 
 ## API Reference
 

package/guides/actor-model.md

@@ -33,20 +33,20 @@ Infrastructure → actor: only via actor.send({ type: "..." })
 
 ## What the actor owns
 
-An actor in XMachines is a `PlayerActor` — a concrete class that extends XState's `Actor` class via `AbstractActor`. It implements three reactive properties:
+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:
 
-| 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` 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`.                                                                             |
+| `actor.currentView`  | `Signal.State<PlaySpec \| null>`  | Updated on each transition. Holds the [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) that drives renderers. |
 
 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`) are part of the actor's state graph, not thrown into the environment.
+- **Error states** — structured errors ([`PlayError`](../api/@xmachines/play/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,17 @@ This is why the invariant is called **State-Driven Reset** in the Play RFC.
 
 ---
 
-## `AbstractActor` — the enforced contract
+## [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) — the enforced contract
 
-`AbstractActor` (from `@xmachines/play-actor`) is the abstract base class that all actor implementations must extend. It extends XState's `Actor`, which means:
+[`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:
 
 - XState's inspection API works (`@xstate/inspect`)
 - XState DevTools attach to actors normally
 - The full XState ecosystem (testing utilities, visualization) is compatible
 
-`AbstractActor` 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.
+[`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.
 
-The two optional capability interfaces — `Routable` and `Viewable` — are deliberately separate:
+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:
 
 - 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).
@@ -118,13 +118,13 @@ class PlayerActor extends AbstractActor<SomeMachine> implements Routable, Viewab
 }
 ```
 
-In practice you never write `PlayerActor` yourself — `definePlayer` from `@xmachines/play-xstate` creates one from your machine definition.
+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.
 
 ---
 
-## `definePlayer` — the factory builder
+## [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) — the factory builder
 
-`definePlayer({ machine })` is the primary entry point for creating actors:
+[`definePlayer({ machine })`](../api/@xmachines/play-xstate/functions/definePlayer.md) is the primary entry point for creating actors:
 
 ```typescript
 import { definePlayer } from "@xmachines/play-xstate";
@@ -137,7 +137,7 @@ const actor = createPlayer();
 actor.start();
 ```
 
-`definePlayer` 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/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):
 
@@ -152,7 +152,7 @@ const actor = createPlayer(undefined, { snapshot }); // restored from snapshot
 
 The machine definition — the `setup().createMachine(...)` call — is pure TypeScript with zero runtime dependencies on browsers, routers, or UI frameworks. This is not a convention; it is enforced by the dependency graph.
 
-`@xmachines/play-xstate` depends on `xstate` and `@xmachines/play-signals`. It does not depend on React, Vue, any router library, or any browser API. Your machine file inherits those same boundaries.
+[`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) depends on `xstate` and [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md). It does not depend on React, Vue, any router library, or any browser API. Your machine file inherits those same boundaries.
 
 This has concrete practical benefits:
 
@@ -175,6 +175,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 README](../api/@xmachines/play-actor/README.md) — API reference for `AbstractActor`
-- [@xmachines/play-xstate README](../api/@xmachines/play-xstate/README.md) — API reference for `definePlayer` and `PlayerActor`
+- [@xmachines/play-actor README](../api/@xmachines/play-actor/README.md) — API reference for [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md)
+- [@xmachines/play-xstate README](../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)
 - [Play RFC](../rfc/play.md) — complete architectural specification

package/guides/architecture.md

@@ -0,0 +1,500 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Architecture
+
+## System Overview
+
+XMachines JS is the JavaScript/TypeScript reference implementation of the **Universal Player Architecture** (Play RFC). It is a monorepo of modular packages that strictly separates **business logic (the Actor)** from **infrastructure (router adapters and view renderers)**. An XState v5 state machine is the single source of truth; it owns all state, guards, and route validity. Infrastructure is passive: it observes TC39 Signals emitted by the Actor and proposes state changes via typed events. The Actor's guards make every navigation and transition decision. Communication across the boundary is exclusively through TC39 Signals — never subscriptions, callbacks, or direct state mutation. Five architectural invariants (documented in [`rfc/play.md`](../rfc/play.md)) enforce this contract across the entire package graph.
+
+**Architectural invariants:**
+
+| ID     | Name                   | Rule                                                              |
+| ------ | ---------------------- | ----------------------------------------------------------------- |
+| INV-01 | Actor Authority        | Infrastructure proposes intents; Actor decides via guards         |
+| INV-02 | Strict Separation      | No direct dependencies between Actor and Infrastructure layers    |
+| INV-03 | Passive Infrastructure | Infrastructure observes Actor signals, never controls state       |
+| INV-04 | Signal-Only Reactivity | All state changes flow through TC39 Signals                       |
+| INV-05 | State-Driven Reset     | Invalid external navigation is overwritten by Actor-derived state |
+
+---
+
+## Component Diagram
+
+```mermaid
+graph TD
+    subgraph Layer0["Layer 0 — Protocol / Primitives"]
+        play["@xmachines/play<br/>(PlayEvent, PlayError)"]
+        signals["@xmachines/play-signals<br/>(TC39 Signal, watchSignal)"]
+        shared["@xmachines/shared<br/>(tsconfig, oxlint, oxfmt)"]
+    end
+
+    subgraph Layer1["Layer 1 — Abstract Actor Base"]
+        actor["@xmachines/play-actor<br/>(AbstractActor, Routable, Viewable, PlaySpec)"]
+    end
+
+    subgraph Layer2["Layer 2 — Concrete Implementations"]
+        xstate["@xmachines/play-xstate<br/>(PlayerActor, definePlayer, guards, routing)"]
+        router["@xmachines/play-router<br/>(RouterBridgeBase, RouteMap, extractMachineRoutes)"]
+
+        subgraph Views["View Renderers"]
+            react["@xmachines/play-react"]
+            vue["@xmachines/play-vue"]
+            solid["@xmachines/play-solid"]
+            svelte["@xmachines/play-svelte"]
+            dom["@xmachines/play-dom"]
+        end
+
+        subgraph RouterAdapters["Router Adapters"]
+            tsr["@xmachines/play-tanstack-react-router"]
+            rr["@xmachines/play-react-router"]
+            vr["@xmachines/play-vue-router"]
+            sr["@xmachines/play-solid-router"]
+            tss["@xmachines/play-tanstack-solid-router"]
+            sk["@xmachines/play-sveltekit-router"]
+            ssr["@xmachines/play-svelte-spa-router"]
+            dr["@xmachines/play-dom-router"]
+        end
+    end
+
+    play --> actor
+    signals --> actor
+    actor --> xstate
+    actor --> router
+    actor --> Views
+    signals --> xstate
+    signals --> router
+    play --> xstate
+    play --> router
+    router --> RouterAdapters
+    xstate -.->|"play.route events"| router
+```
+
+---
+
+## Data Flow
+
+### Actor State Change → UI Render
+
+```mermaid
+flowchart TD
+    A["XState machine transition"]
+    B["PlayerActor._xstateActor.subscribe(snapshot)"]
+    C["StateSignalManager.scheduleUpdate(snapshot)\nactor.state Signal.State updated — synchronous"]
+    D["actor.currentRoute Signal.Computed recomputes\nderives URL from meta.route + context.params"]
+    E["_validateAndCacheView(snapshot)\nactor.currentView Signal.State updated"]
+    F["Framework signal watcher fires\nmicrotask"]
+    G["ActorProvider reads actor.currentView.get()"]
+    H["PlayRenderer renders via @json-render/* Renderer"]
+
+    A --> B --> C --> D --> E --> F --> G --> H
+```
+
+### User Navigation (Browser URL → Actor)
+
+```mermaid
+flowchart TD
+    A["Browser popstate / router navigation event"]
+    B["Router adapter watchRouterChanges() handler fires"]
+    C["RouterBridgeBase.syncActorFromRouter(pathname, search)"]
+    D["sanitizePathname(pathname)\nlength/content guard"]
+    E["buildPlayRouteEvent(path, routeMap)\nresolves stateId from URL via URLPattern"]
+    F["actor.send({ type: 'play.route', to: '#stateId', params, query })"]
+    G["XState machine guard evaluates transition"]
+    H["machine transitions → signals update\n→ URL bar updated"]
+    I["guard blocks → machine stays\n→ router re-syncs to actor's current route"]
+
+    A --> B --> C --> D --> E --> F --> G
+    G -->|valid| H
+    G -->|invalid| I
+```
+
+### Actor State Change → Router URL Sync
+
+```mermaid
+flowchart TD
+    A["actor.currentRoute Signal.Computed changes"]
+    B["RouterBridgeBase routeWatcher\nTC39 Signal.subtle.Watcher fires"]
+    C["watchSignal microtask queued\nneedsEnqueue dedup guard"]
+    D["syncRouterFromActor(route) called"]
+    E["lastSyncedPath set\necho suppression — prevents circular callback"]
+    F["navigateRouter(path)\ncalls framework router's navigate API"]
+    G["Router updates URL bar"]
+
+    A --> B --> C --> D --> E --> F --> G
+```
+
+### Initial Connection (deep-link vs. restore detection)
+
+```mermaid
+flowchart TD
+    A["bridge.connect()"]
+    B["routeWatcher armed on actor.currentRoute"]
+    C["watchRouterChanges() subscribed"]
+    D["getInitialRouterPath() reads current browser URL"]
+    E["resolves sanitized URL path → stateId via routeMap"]
+    F{"Compare stateId vs actor.initialRoute"}
+    G["syncActorFromRouter()\nrouter wins — deep-link"]
+    H["navigateRouter()\nactor wins — restore"]
+
+    A --> B --> C --> D --> E --> F
+    F -->|"URL ≠ machine initial state"| G
+    F -->|"URL = machine initial state"| H
+```
+
+### View Prop Enrichment
+
+```mermaid
+flowchart TD
+    A["XState snapshot.getMeta()"]
+    B["resolveViewMeta(meta)\nfinds first meta.view with root + elements"]
+    C["Extract context.params\nURL path params set by formatPlayRouteTransitions assign"]
+    D["Extract contextProps allowlist\nexplicit opt-in from PlaySpec.contextProps"]
+    E["mergeRouteParamsIntoProps()\npriority: spec prop > URL param > contextProps value"]
+    F["Enriched PlaySpec set on currentView signal"]
+
+    A --> B --> C --> D --> E --> F
+```
+
+---
+
+## Key Abstractions
+
+### [`PlayEvent<TPayload>`](../api/@xmachines/play/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).
+
+```typescript
+import type { PlayEvent } from "@xmachines/play";
+
+type LoginEvent = PlayEvent<{ userId: string; timestamp: number }>;
+```
+
+### [`PlayError`](../api/@xmachines/play/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 { RouterSyncError } from "@xmachines/play-router/errors";
+
+if (err instanceof RouterSyncError) {
+	/* err.scope, err.code, err.cause */
+}
+```
+
+### [`AbstractActor<TLogic, TEvent>`](../api/@xmachines/play-actor/classes/AbstractActor.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)).
+
+### [`Routable`](../api/@xmachines/play-actor/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).
+
+### [`Viewable`](../api/@xmachines/play-actor/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)
+
+Extends `@json-render/core` `Spec` with `readonly contextProps?: readonly string[]` — an explicit allowlist of machine context fields that `deriveCurrentView` merges into element props. Only fields named here are ever exposed to components. `typedSpec<TContext>()` provides compile-time validation of `contextProps` entries against the machine's context type.
+
+### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
+
+Concrete XState v5 actor implementing the full signal protocol. Extends [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md); implements both [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md). Wraps an internal `xstate.Actor` and bridges its subscription to TC39 Signals via `StateSignalManager`. Exposes: `state`, `currentRoute`, `currentView`, `initialRoute`, `send()`, `start()`, `stop()`, `can()`, `dispose()`.
+
+### [`definePlayer(config)`](../api/@xmachines/play-xstate/functions/definePlayer.md)
+
+Factory creator. Pre-computes `initialRoute` once from the machine's initial state (zero extra actor instantiation per factory call). Returns [`PlayerFactory<TMachine>`](../api/@xmachines/play-xstate/type-aliases/PlayerFactory.md): `(input?, restore?) => PlayerActor<TMachine>`.
+
+```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+const createPlayer = definePlayer({ machine, options });
+const actor = createPlayer(); // or createPlayer(input) or createPlayer(undefined, { snapshot })
+actor.start();
+```
+
+### [`RouterBridgeBase`](../api/@xmachines/play-router/classes/RouterBridgeBase.md)
+
+Abstract base class capturing 100% of the shared 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`.
+
+### [`RouteMap`](../api/@xmachines/play-router/classes/RouteMap.md) / [`createRouteMap`](../api/@xmachines/play-router/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`).
+
+### [`PlayRouteEvent`](../api/@xmachines/play-router/interfaces/PlayRouteEvent.md)
+
+Unified routing event sent by router adapters to the Actor.
+
+```typescript
+interface PlayRouteEvent {
+	readonly type: "play.route";
+	readonly to: string; // e.g. "#home", "#profile"
+	readonly params?: Record<string, string>; // URL path params, e.g. { userId: "123" }
+	readonly query?: Record<string, string>; // Query string params
+	readonly match?: unknown; // URLPatternResult (optional, for debugging)
+}
+```
+
+### [`watchSignal(signal, callback)`](../api/@xmachines/play-signals/functions/watchSignal.md)
+
+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)
+
+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()`.
+
+---
+
+## Directory Structure Rationale
+
+```
+/workspace/
+├── packages/                  # All npm workspace packages
+│   ├── shared/                # Shared tooling configs (tsconfig, oxlint, oxfmt, vitest setup)
+│   │   └── config/            # Not a runtime package — devDependency only
+│   │
+│   ├── play/                  # Layer 0: Protocol contracts
+│   │   └── src/               # PlayEvent, PlayError, NonNullableError, assertNonNullable
+│   │
+│   ├── play-signals/          # Layer 0: TC39 Signals isolation layer
+│   │   └── src/               # Re-exports signal-polyfill; watchSignal utility
+│   │
+│   ├── play-actor/            # Layer 1: Abstract actor + capability interfaces
+│   │   └── src/               # AbstractActor, Routable, Viewable, PlaySpec, typedSpec
+│   │
+│   ├── play-xstate/           # Layer 2: XState v5 adapter
+│   │   └── src/
+│   │       ├── player-actor.ts          # PlayerActor — concrete actor
+│   │       ├── define-player.ts         # definePlayer factory
+│   │       ├── guards/                  # composeGuards, composeGuardsOr, negateGuard, hasContext...
+│   │       ├── routing/                 # deriveRoute, buildRouteUrl, formatPlayRouteTransitions
+│   │       └── signals/                 # StateSignalManager (XState → TC39 Signal bridge)
+│   │
+│   ├── 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)
+│   │       ├── router-sync.ts           # buildPlayRouteEvent, extractRouteParams, sanitizePathname
+│   │       └── types.ts                 # PlayRouteEvent, RouterBridge, RouteTree, WindowLike...
+│   │
+│   ├── play-react/            # Layer 2: React view renderer
+│   ├── play-vue/              # Layer 2: Vue 3 view renderer
+│   ├── play-solid/            # Layer 2: SolidJS view renderer
+│   ├── play-svelte/           # Layer 2: Svelte 5 view renderer
+│   ├── play-dom/              # Layer 2: Vanilla DOM renderer
+│   │
+│   ├── play-tanstack-react-router/    # Router adapter: TanStack Router (React)
+│   ├── play-react-router/             # Router adapter: React Router v7
+│   ├── play-vue-router/               # Router adapter: Vue Router
+│   ├── play-solid-router/             # Router adapter: SolidJS Router
+│   ├── play-tanstack-solid-router/    # Router adapter: TanStack Router (SolidJS)
+│   ├── play-sveltekit-router/         # Router adapter: SvelteKit
+│   ├── play-svelte-spa-router/        # Router adapter: Svelte SPA Router
+│   ├── play-dom-router/               # Router adapter: Vanilla DOM (History API)
+│   │
+│   └── docs/                  # @xmachines/docs — API docs + RFCs
+│       └── rfc/               # Living RFC documents (play.md, streams.md, etc.)
+│
+├── tsconfig.json              # Root TypeScript project reference coordinator
+│                              # Lists all packages in build-order (leaves first)
+│                              # Does not compile anything itself
+└── package.json               # npm workspaces root
+```
+
+---
+
+## TypeScript Build Graph
+
+The monorepo uses **TypeScript project references** (`"composite": true` per package) for a correct, incremental, dependency-ordered build. The root `tsconfig.json` lists all packages in layer order — leaves first, dependents last. `tsc --build` at the root resolves the full dependency graph automatically.
+
+**Build layer order (as declared in `tsconfig.json`):**
+
+```mermaid
+flowchart LR
+    subgraph L0["Layer 0 — no internal deps"]
+        ps[play-signals]
+        p[play]
+        d[docs]
+    end
+    subgraph L1["Layer 1 — depends on L0"]
+        pa[play-actor]
+    end
+    subgraph L2["Layer 2 — depends on L0 + L1"]
+        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 / demos"]
+        ex[play-react-router\nplay-*/examples/demo]
+    end
+
+    L0 --> L1 --> L2 --> L3
+```
+
+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.
+
+---
+
+## View Renderer Pattern
+
+All five view renderer packages follow an identical structural pattern:
+
+| Component        | Role                                                                                   |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| `ActorProvider`  | Subscribes to `actor.currentView` signal; owns signal lifecycle; provides view context |
+| `PlayUIProvider` | Convenience wrapper combining `ActorProvider` + framework's `JSONUIProvider`           |
+| `PlayRenderer`   | Zero-prop leaf component; reads from context; delegates to `@json-render/*` `Renderer` |
+| `useActor()`     | Hook/composable for accessing the raw actor in consuming components                    |
+
+**Framework-specific signal bridging:**
+
+| Package                                                             | Signal → Render mechanism                                                                                                                                                    |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)   | `useSignalEffect` → `useReducer` force-update                                                                                                                                |
+| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)       | Vue reactivity bridge via `watchEffect` equivalent                                                                                                                           |
+| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)   | SolidJS native reactive integration                                                                                                                                          |
+| [`@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 [`connectRenderer`](../api/@xmachines/play-dom/functions/connectRenderer.md) / [`createPlayUI`](../api/@xmachines/play-dom/functions/createPlayUI.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).
+
+---
+
+## 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:
+
+```typescript
+// How to tell the framework router to change URL
+protected abstract navigateRouter(path: string): void;
+
+// How to subscribe to router location change events
+protected abstract watchRouterChanges(): void;
+
+// How to unsubscribe from router location change events
+protected abstract unwatchRouterChanges(): void;
+```
+
+| Package                                                                                           | Bridge class                           |
+| ------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | `TanStackReactRouterBridge`            |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | `ReactRouterBridge`                    |
+| [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | `VueRouterBridge`                      |
+| [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | `SolidRouterBridge`                    |
+| [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | `SolidRouterBridge` (TanStack variant) |
+| [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | `SvelteKitRouterBridge`                |
+| [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | `SvelteSpaRouterBridge`                |
+| [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | `DomRouterBridge`                      |
+
+Each adapter also exports a framework-integrated provider component (e.g. `PlayRouterProvider`) and a `createRouteMapFrom*` factory appropriate for its router's route definition format.
+
+---
+
+## Error Handling
+
+All `@xmachines/*` errors extend [`PlayError`](../api/@xmachines/play/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"`)
+
+**Error hierarchy:**
+
+```mermaid
+flowchart TD
+    PE["PlayError\n@xmachines/play"]
+    PE --> NNE["NonNullableError\nPLAY_NON_NULLABLE"]
+    PE --> RSE["RouterSyncError\nPLAY_ROUTER_SYNC_FAILED"]
+    PE --> UPE["URLPatternUnavailableError\nPLAY_URL_PATTERN_UNAVAILABLE"]
+    PE --> DBE["DuplicateBridgeError\nPLAY_DUPLICATE_BRIDGE"]
+    PE --> IEE["InvalidEventError\nPLAY_INVALID_EVENT"]
+    PE --> IME["InvalidMachineError\nPLAY_INVALID_MACHINE"]
+    PE --> MRP["MissingRouteParamError\nPLAY_MISSING_ROUTE_PARAM"]
+    PE --> MSI["MissingStateIdError\nPLAY_MISSING_STATE_ID"]
+```
+
+Package-specific errors are exported from `./errors` subpath imports:
+
+```typescript
+import { PlayError } from "@xmachines/play";
+import { RouterSyncError } from "@xmachines/play-router/errors";
+import { InvalidEventError } from "@xmachines/play-xstate/errors";
+```
+
+---
+
+## 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.
+
+**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.
+
+**Logging:** None built-in. [`PlayerOptions`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md) exposes lifecycle hooks — `onStart`, `onStop`, `onTransition`, `onStateChange`, `onError` — as observability extension points.
+
+**Authentication:** Not in scope. Authentication is enforced by XState machine guards. Infrastructure proposes navigation via `play.route` events; guards decide whether the transition is allowed from the current state.
+
+**TC39 Signal isolation:** All signal imports go through [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md), which re-exports the `signal-polyfill` reference implementation. This isolates the codebase from Stage-1 API churn — a polyfill version upgrade or API change requires editing only one package.
+
+---
+
+## Application Bootstrap (typical React example)
+
+```typescript
+import { setup } from "xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { extractMachineRoutes } from "@xmachines/play-router";
+import { createRouteMapFromTree, PlayRouterProvider } from "@xmachines/play-tanstack-react-router";
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
+
+// 1. Define machine — meta.route declares virtual routes; meta.view declares UI specs
+const machineConfig = formatPlayRouteTransitions({
+  id: "app",
+  initial: "home",
+  context: { params: {}, query: {} },
+  states: {
+    home: { id: "home", meta: { route: "/", view: { root: "home", elements: { home: { type: "HomePage", props: {}, children: [] } } } } },
+    profile: { id: "profile", meta: { route: "/profile/:userId", view: { root: "profile", elements: { profile: { type: "ProfilePage", props: { userId: undefined }, children: [] } } } } },
+  },
+});
+
+const machine = setup({}).createMachine(machineConfig);
+
+// 2. Build route map from machine definition (done once at startup)
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree);
+
+// 3. Create player factory and start actor
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
+
+// 4. Define component registry for json-render
+const registryResult = defineRegistry({ /* components */ });
+
+// 5. Render — framework providers wire actor → router → view
+function App() {
+  return (
+    <PlayRouterProvider actor={actor} router={router} routeMap={routeMap}>
+      <PlayUIProvider actor={actor} registryResult={registryResult}>
+        <PlayRenderer />
+      </PlayUIProvider>
+    </PlayRouterProvider>
+  );
+}
+```
+
+---
+
+_For the living RFC specification, see [`rfc/play.md`](../rfc/play.md)._