@xmachines/docs 1.0.0-beta.51 → 1.0.0-beta.53

package/guides/architecture.md

@@ -1,500 +0,0 @@
-<!-- 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)._