@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/contributing/architecture.md

@@ -0,0 +1,601 @@
+# Architecture
+
+XMachines Play implements the **Universal Player Architecture** — a layered, actor-authority design where XState machines are the single source of truth for routing, navigation, and view selection. Infrastructure (routers, renderers) is strictly passive: it observes actor signals and reflects them, never enforcing guards or making decisions.
+
+## System Overview
+
+XMachines JS is the JavaScript/TypeScript reference implementation of the **Universal Player Architecture** ([Play RFC](../rfc/play.md)). 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 the [Play RFC](../rfc/play.md)) enforce this contract across the entire package graph.
+
+## Architectural Invariants
+
+| ID     | Name                       | Rule                                                                                                                                     |
+| ------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| INV-01 | **Actor Authority**        | Infrastructure proposes intents via `play.route` events; Actor decides via XState guards                                                 |
+| INV-02 | **Strict Separation**      | No direct dependencies between Actor and Infrastructure layers. `play-xstate` never imports UI frameworks or routing libraries           |
+| INV-03 | **Passive Infrastructure** | Infrastructure observes Actor signals, never controls state                                                                              |
+| INV-04 | **Signal-Only Reactivity** | All Actor→Infrastructure state changes flow through TC39 Signals (`Signal.State`, `Signal.Computed`). No subscriptions or event emitters |
+| 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\n(PlayEvent, PlayError)"]
+        signals["@xmachines/play-signals\n(TC39 Signal, watchSignal)"]
+        shared["@xmachines/shared\n(tsconfig, oxlint, oxfmt)"]
+    end
+
+    subgraph Layer1["Layer 1 — Abstract Actor Base"]
+        actor["@xmachines/play-actor\n(AbstractActor, Routable, Viewable, PlaySpec)"]
+    end
+
+    subgraph Layer2["Layer 2 — Concrete Implementations"]
+        xstate["@xmachines/play-xstate\n(PlayerActor, definePlayer, guards, routing)"]
+        router["@xmachines/play-router\n(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
+```
+
+## Component Responsibilities
+
+| Package                                                                                           | Responsibility                                          | Key File                                                            |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- |
+| [`@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-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-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-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-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`     |
+| [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | Svelte SPA Router bridge                                | `packages/play-svelte-spa-router/src/svelte-spa-router-bridge.ts`   |
+| `@xmachines/shared`                                                                               | Shared configs: tsconfig, oxlint, oxfmt, vitest         | `packages/shared/config/`                                           |
+| `@xmachines/docs`                                                                                 | API docs and RFC documentation                          | `packages/docs/`                                                    |
+
+## Data Flow
+
+### Actor State Change → UI Render
+
+```mermaid
+flowchart TD
+    A["XState machine transition"]
+    B["PlayerActor observes its own transitions"]
+    C["actor.state Signal.State updated — synchronous, no batching"]
+    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 @xmachines/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
+```
+
+**State signals on the actor:**
+
+| Signal               | Type                               | Description                                                                                      |
+| -------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `actor.state`        | `Signal.State<AnyMachineSnapshot>` | XState snapshot; updated synchronously on active states only                                     |
+| `actor.currentRoute` | `Signal.Computed<string \| null>`  | Derived from `meta.route` + `context.params`; `null` when unroutable                             |
+| `actor.currentView`  | `Signal.State<PlaySpec \| null>`   | Set explicitly per-transition (not computed) to ensure watcher notifications on self-transitions |
+
+## 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 `@xmachines/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) — 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()`.
+
+### [`definePlayer(config)`](../api/@xmachines/play-xstate/functions/definePlayer.md) → [`PlayerFactory`](../api/@xmachines/play-xstate/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>`.
+
+```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 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`.
+
+```typescript
+class MyRouterBridge extends RouterBridgeBase {
+	protected navigateRouter(path: string): void {
+		/* push URL */
+	}
+	protected watchRouterChanges(): void {
+		/* subscribe to router */
+	}
+	protected unwatchRouterChanges(): void {
+		/* unsubscribe */
+	}
+}
+```
+
+### [`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()`.
+
+## 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 `@xmachines/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 [`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).
+
+## 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) | `TanStackSolidRouterBridge` |
+| [`@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.
+
+## Directory Structure
+
+```
+packages/
+├── shared/                     # Zero-dependency shared configs (tsconfig, oxlint, oxfmt, vitest)
+├── 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-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)
+│       ├── router-sync.ts               # buildPlayRouteEvent, extractRouteParams, sanitizePathname
+│       └── types.ts                     # PlayRouteEvent, RouterBridge, RouteTree, WindowLike...
+│
+├── play-react/                 # View renderer: React (ActorProvider, PlayRenderer)
+├── play-vue/                   # View renderer: Vue 3
+├── play-solid/                 # View renderer: SolidJS
+├── play-svelte/                # View renderer: Svelte 5
+├── play-dom/                   # View renderer: Vanilla DOM
+│
+├── 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-vue-router/            # Router adapter: Vue Router 4/5
+├── play-solid-router/          # Router adapter: SolidJS Router
+├── play-svelte-spa-router/     # Router adapter: Svelte SPA Router
+├── play-sveltekit-router/      # Router adapter: SvelteKit
+├── play-dom-router/            # Router adapter: Vanilla DOM (History API)
+│
+└── docs/                       # @xmachines/docs — API docs (auto-generated) + RFC specifications
+    └── rfc/                    # Living RFC documents (play.md, streams.md, etc.)
+```
+
+Each package follows the same internal structure:
+
+```
+packages/<name>/
+├── src/
+│   ├── index.ts        # Single public barrel — only file consumers import
+│   └── *.ts / *.tsx    # Implementation files (kebab-case)
+├── test/               # Test files (*.spec.ts, *.test.ts)
+├── dist/               # Build output (gitignored)
+├── examples/           # Runnable demo apps (present in some packages)
+├── package.json        # "type": "module"; exports only via "./dist/index.js"
+└── tsconfig.json       # Extends @xmachines/shared/tsconfig; composite: true
+```
+
+## TypeScript Build Graph
+
+The monorepo uses **TypeScript composite 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.
+
+```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 / play-react-router"]
+        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.
+
+**Dependency rules:**
+
+| Layer                                           | May import from                                     | Must not import from             |
+| ----------------------------------------------- | --------------------------------------------------- | -------------------------------- |
+| Protocol (`play`, `play-signals`, `play-actor`) | External libs only                                  | Any other `@xmachines/*` package |
+| Actor logic (`play-xstate`)                     | Protocol layer                                      | View renderers, router adapters  |
+| Router infrastructure (`play-router`)           | Protocol layer, `@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:
+
+- `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_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 { 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  |
+
+## Application Bootstrap (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>
+  );
+}
+```
+
+## Anti-Patterns
+
+### Importing `signal-polyfill` directly
+
+```typescript
+// ❌ Wrong — bypasses the TC39 Signal isolation layer
+import { Signal } from "signal-polyfill";
+
+// ✅ Correct — all signal imports go through play-signals
+import { Signal } from "@xmachines/play-signals";
+```
+
+### Using framework state for business logic
+
+```typescript
+// ❌ Wrong — violates INV-04 (Signal-Only Reactivity) and INV-02 (Passive Infrastructure)
+const [currentUser, setCurrentUser] = useState(null);
+
+// ✅ Correct — observe the actor signal directly
+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`.
+
+### 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.
+
+## 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:** No structured logging framework. [`PlayerOptions`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md) exposes lifecycle hooks — `onStart`, `onStop`, `onTransition`, `onStateChange`, `onError` — as observability extension points. No `console.*` calls in library source code.
+
+**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.
+
+**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.
+
+**Global state:** An `activeBridges` WeakMap at module level in `packages/play-router/src/router-bridge-base.ts` prevents duplicate bridges per actor. This is the only module-level mutable state in the library.
+
+**Threading:** Single-threaded event loop. No worker threads. XState actor subscription callbacks fire synchronously in `send()`. Signal updates are synchronous to ensure router bridges see guard redirects immediately.
+
+---
+
+_See [Play RFC](../rfc/play.md) for the authoritative protocol specification._