@xmachines/docs 2.0.0-alpha.1 → 2.0.0

package/guides/inspector.md

@@ -0,0 +1,197 @@
+# Inspecting a Running Actor
+
+A `PlayerActor` is an XState actor, so every XState inspection tool works on it unchanged. This guide covers how to attach an inspector, what the events look like once they arrive, and the two things that are specific to XMachines: the actor _is_ the actor an inspector sees, and the observer is configured on the factory rather than on each instance.
+
+After reading this you will be able to open the [Stately inspector](https://stately.ai/docs/inspector) against a running demo or your own app, inspect an actor that has no browser around it, and wire an inspector that can be turned on after the actor has already started.
+
+- [Quick start](#quick-start) — three lines to a live inspector
+- [Where the observer attaches](#where-the-observer-attaches) — factory-level, creation-time
+- [Reading the events](#reading-the-events) — identity, `rootId`, the construction caveat
+- [Turning the inspector on later](#turning-the-inspector-on-later) — dev-tools toggles and replay
+- [Inspecting without a browser](#inspecting-without-a-browser) — WebSocket transport, Node and SSR
+- [Trying it in the demos](#trying-it-in-the-demos) — the shared demo controller
+- [Production considerations](#production-considerations) — cost and data exposure
+
+---
+
+## Quick start
+
+Install the inspect client alongside your existing XState dependency:
+
+```bash
+pnpm add -D @statelyai/inspect
+```
+
+Create an inspector and hand its `inspect` observer to [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md):
+
+```typescript
+import { createBrowserInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import { appMachine } from "./machine.js";
+
+const { inspect } = createBrowserInspector();
+
+const createPlayer = definePlayer({
+	machine: appMachine,
+	options: { inspect },
+});
+
+const actor = createPlayer();
+actor.start();
+```
+
+`createBrowserInspector()` opens Stately's hosted inspector in a new tab and streams the actor's events to it. From there the machine draws itself, every transition animates, and the context is readable at each step.
+
+That is the whole integration. [`PlayerOptions.inspect`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md) is forwarded verbatim to XState's `createActor`, so anything XState accepts there is accepted here — a function, or an observer object with a `next` method:
+
+```typescript
+// Function form — the common case
+definePlayer({ machine, options: { inspect: (event) => console.log(event.type) } });
+
+// Observer form — also forwarded as-is
+definePlayer({ machine, options: { inspect: { next: (event) => sink.write(event) } } });
+```
+
+---
+
+## Where the observer attaches
+
+Two properties of the attachment point matter in practice.
+
+**It is configured on the factory, not on the instance.** `definePlayer({ machine, options })` returns a factory; `options.inspect` belongs to that configuration, and every actor the factory creates reports to the same observer. The factory's per-call options bag carries `snapshot` for restoring persisted state and nothing else — there is no per-instance `inspect` override. When one factory produces several live actors (multi-user scenarios, SSR, tests), demultiplex the stream by root instead:
+
+```typescript
+const createPlayer = definePlayer({ machine, options: { inspect } });
+
+const alice = createPlayer({ userId: "alice" });
+const bob = createPlayer({ userId: "bob" });
+
+// Events from alice's tree, children included
+const forAlice = (event: InspectionEvent) => event.rootId === alice.sessionId;
+```
+
+**It is the only route that sees construction.** Attaching after the fact with `actor.system.inspect(fn)` works and needs no factory changes, but it only receives events from the moment it subscribes — the `@xstate.actor` registration event has already fired by then, and an inspector that never receives it has no machine to draw. Use `options.inspect` when you want the full history; use `actor.system.inspect(fn)` when you only care about what happens next.
+
+---
+
+## Reading the events
+
+Because a `PlayerActor` _is_ the XState actor rather than a wrapper around a hidden one, the events name it directly:
+
+- `event.actorRef === actor` for the player's own events — recognise a player by identity, no bookkeeping required.
+- `event.rootId === actor.sessionId` for the whole tree, including invoked and spawned children, whose `actorRef` is the child rather than the player.
+
+The event types are XState's: `@xstate.actor` when an actor registers, `@xstate.event` when an event is sent, `@xstate.snapshot` after a transition, `@xstate.action` for executed actions, and `@xstate.microstep` for intermediate steps.
+
+### The construction caveat
+
+`@xstate.actor` fires from _inside_ the actor's constructor. The `actorRef` it carries is a real `PlayerActor`, but a mid-construction one: `state`, `currentRoute`, `currentView` and `initialRoute` do not exist yet, and reading them there throws — XState itself refuses to read a snapshot in that window.
+
+```typescript
+const inspect = (event: InspectionEvent) => {
+	if (event.type === "@xstate.actor") {
+		// ❌ throws — the signals are not assigned yet
+		console.log(event.actorRef.currentRoute.get());
+	}
+	if (event.type === "@xstate.snapshot") {
+		// ✅ construction has returned; signals are live
+		console.log(event.actorRef.getSnapshot().value);
+	}
+};
+```
+
+Capture the reference during construction if you need it, and read the signals from a later event or from outside the observer entirely.
+
+---
+
+## Turning the inspector on later
+
+An inspector that is only created when the user asks for it — a dev-tools toggle, a keyboard shortcut, a debug panel button — cannot be passed to `definePlayer`, which ran at module scope long before the click. Pass a forwarding function instead, so the attachment point is fixed at factory time while the destination stays swappable:
+
+```typescript
+let current: ((event: InspectionEvent) => void) | undefined;
+
+const createPlayer = definePlayer({
+	machine: appMachine,
+	options: { inspect: (event) => current?.(event) },
+});
+
+// Later, from a click handler
+export function enableInspector() {
+	const { inspect } = createBrowserInspector();
+	current = inspect;
+}
+```
+
+This attaches at creation time (so nothing is missed structurally) while forwarding to nothing until the toggle flips.
+
+There is a catch worth knowing before you ship it: events that arrive while `current` is undefined are dropped, so an inspector enabled after startup opens on a machine with no registration event and no history — it has nothing to draw until the next transition. If late opening should show the machine as it stands, buffer the events from creation and replay the buffer when the inspector connects. The demo controller described below does exactly that, and is worth reading as a worked example.
+
+---
+
+## Inspecting without a browser
+
+`createBrowserInspector` is one transport, not the only one. `@statelyai/inspect` also exports `createWebSocketInspector`, which pairs with `createInspectorServer` from `@statelyai/inspect/server` to stream the same events over a socket — the route to an actor with no browser around it at all, such as one running in a Node process or on the server half of an SSR render:
+
+```typescript
+import { createWebSocketInspector } from "@statelyai/inspect";
+
+const { inspect } = createWebSocketInspector({ url: "ws://localhost:8080" });
+
+const createPlayer = definePlayer({ machine: appMachine, options: { inspect } });
+```
+
+Both transports consume the identical `options.inspect` observer, so switching between them touches only the line that creates the inspector. The same is true of an observer you write yourself: a `console.log`, a test spy asserting a transition sequence, or a writer that appends events to a log are all valid `inspect` values, and none of them require the inspect client at all.
+
+---
+
+## Trying it in the demos
+
+Every demo in this repository — all five renderer demos and all eight router demos — wires the inspector the same way, so any of them can be used to see the flow end to end:
+
+```bash
+pnpm --filter @xmachines/play-react-demo run dev
+```
+
+Click **Show Inspector** in the debug panel at the bottom of the page. The inspector opens in its own window with the machine already drawn and the session's history replayed, and it keeps updating as you log in, navigate, and log out.
+
+The demos share one controller, `createDemoInspector()` from `@xmachines/play-actor-shared`, which each demo passes straight through to `definePlayer`:
+
+```typescript
+const inspector = createDemoInspector();
+
+const actor = definePlayer({
+	machine: authMachine,
+	options: { inspect: inspector.inspect },
+})();
+actor.start();
+
+// The debug panel's button
+<button onClick={() => inspector.show()}>Show Inspector</button>;
+```
+
+The controller answers the late-opening problem from the previous section: it buffers serialized events from actor creation, pins the current root's registration so it can never roll out of the bounded buffer, and flushes the buffer when the inspector window completes its handshake. That is a demo trade-off rather than a general recommendation — every transition pays serialization whether or not anyone ever opens the inspector — but it is what makes the button work at any point in a session. See the [shared demo package README](../../play-actor/examples/shared/README.md) for the design in full.
+
+---
+
+## Production considerations
+
+**Cost.** Inspection serializes events. A `console.log` observer is cheap; a browser inspector posting every transition, and any buffering scheme layered on top, is not. Gate the inspector behind a development-only branch, and prefer letting the bundler drop it entirely:
+
+```typescript
+const options = import.meta.env.DEV ? { inspect: createBrowserInspector().inspect } : {};
+
+const createPlayer = definePlayer({ machine: appMachine, options });
+```
+
+**Data exposure.** Inspection events carry the machine's definition and its context — which in a real application may include user identifiers, tokens, or form input. The browser transport posts that data to the inspector's origin over `postMessage`, and the WebSocket transport sends it to whatever server is listening. Treat an inspector connection as a data egress path: keep it out of production builds, and when inspecting a shared environment, know where the events are going.
+
+---
+
+## Related documentation
+
+- **[`PlayerOptions`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md)** — the full options bag, `inspect` included
+- **[`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md)** — the actor an inspector observes
+- **[Understanding the Actor Model](actor-model.md)** — why the actor is the actor, and what that buys
+- **[Getting Started](getting-started.md)** — installing packages and creating your first actor
+- **[Stately inspect docs](https://stately.ai/docs/inspector)** — the inspector itself, its transports and options

package/guides/state-machines.md

@@ -1,6 +1,6 @@
 # Understanding State Machines in XMachines
 
-XMachines uses XState v6 as its state machine engine. This page explains what finite state machines are, how XMachines extends them with routing and view metadata, and why this design eliminates an entire category of bugs common in traditional frontend architecture.
+XMachines uses XState v5 as its state machine engine. This page explains what finite state machines are, how XMachines extends them with routing and view metadata, and why this design eliminates an entire category of bugs common in traditional frontend architecture.
 
 After reading this, you will understand what a machine definition actually encodes — and why state machines are a better unit of business logic than component-level state or ad-hoc if/else trees.
 
@@ -22,21 +22,18 @@ In traditional component-level state (e.g., boolean flags, `useState` combinatio
 
 ---
 
-## How XMachines uses XState v6
+## How XMachines uses XState v5
 
-XMachines wraps XState v6 via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md). You define machines using XState's `setup().createMachine()` API:
+XMachines wraps XState v5 via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md). You define machines using XState's `setup().createMachine()` API:
 
 ```typescript
-import { setup, types } from "xstate";
-import { emptyEventSchema } from "@xmachines/play-xstate";
+import { setup } from "xstate";
 
 const authSetup = setup({
-	schemas: {
-		context: types<{ username: string | null }>(),
-		events: {
-			"auth.login": types<{ username: string }>(),
-			"auth.logout": emptyEventSchema,
-		},
+	types: {
+		context: {} as { username: string | null },
+		events: {} as { type: "auth.login"; username: string } | { type: "auth.logout" },
+		input: {} as undefined,
 	},
 });
 
@@ -47,18 +44,20 @@ const authMachine = authSetup.createMachine({
 	states: {
 		unauthenticated: {
 			on: {
-				"auth.login": ({ event }) => ({
+				"auth.login": {
 					target: "authenticated",
-					context: { username: event.username },
-				}),
+					actions: authSetup.assign({
+						username: ({ event }) => event.username,
+					}),
+				},
 			},
 		},
 		authenticated: {
 			on: {
-				"auth.logout": () => ({
+				"auth.logout": {
 					target: "unauthenticated",
-					context: { username: null },
-				}),
+					actions: authSetup.assign({ username: null }),
+				},
 			},
 		},
 	},
@@ -67,8 +66,8 @@ const authMachine = authSetup.createMachine({
 
 Key patterns:
 
-- **Always use `setup({ schemas })`** before `createMachine`. The `types<T>()` helper declares type-only schemas so TypeScript can check that your events, context fields, and transitions are consistent throughout the machine. The `events` schema is a map from event type to payload shape — the payload excludes the `type` field itself.
-- **Transitions are plain functions** that return `{ target, context }`. Context updates are shallow patches returned from the transition function — there is no separate `assign` action.
+- **Always use `setup({ types })`** before `createMachine`. The type declarations let TypeScript check that your events, context fields, and actions are consistent throughout the machine.
+- **Use `setup.assign()`**, not the bare `assign` from xstate. This keeps the type checker aware of which context fields the action touches.
 - **Event names use lowercase dot-separated namespaces**: `"auth.login"`, `"play.route"`, `"form.submit"`. This convention makes the event log readable and avoids collisions.
 
 ---
@@ -123,7 +122,9 @@ const appMachine = setup({/* ... */}).createMachine({
 
 `meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `Signal.Computed`) derives this path and emits it. The router bridge reads it and updates the URL.
 
-`meta.view` is a [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) — a `@xmachines/json-render-core` spec object describing what to render. Use `typedSpec<TContext>(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to validate `contextProps` entries at compile time. When the machine enters a state, `actor.currentView` is updated with this spec. The renderer reads it and projects it through framework components.
+`meta.view` is a [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) — a `@xmachines/json-render-core` spec object describing what to render. Use `typedSpec(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to type-check the spec literal at the definition site (XState's `meta` is untyped). When the machine enters a state, `actor.currentView` is updated with the derived spec. The renderer reads it and projects it through framework components.
+
+The machine's whole context is available to every view through the **`/context` projection**: the derived spec's `state` carries `context: <machine context>`. Specs read it with ordinary state expressions — `{ $state: "/context/username" }` in props, `visible` conditions, or `repeat.statePath`. The subtree is **read-only**: context changes only through machine events, and a `$bindState`/`setState` write under `/context` throws. URL data lives at its own paths (`/context/params/…`, `/context/query/…`, written into context by `formatPlayRouteTransitions`), so a URL param can never shadow a machine-owned field. When validating specs with tools like `validateSpec`, validate the **derived** view (`actor.currentView.get()`) — its `state` honestly describes the store contents — not the raw `meta.view`. A context change re-emits the view with the same `viewKey`; providers respond by refreshing `/context` in the live store, not by remounting the UI.
 
 **The machine is the single source of truth for both routing and views.** There is no separate route configuration file. There is no switch statement in a component deciding what to render based on the URL. The state machine encodes all of that.
 
@@ -139,8 +140,8 @@ states: {
   home: {
     on: {
       "play.route": [
-        ({ event }) => (event.to === "#login" ? { target: "login" } : undefined),
-        ({ event }) => (event.to === "#dashboard" ? { target: "dashboard" } : undefined),
+        { guard: ({ event }) => event.to === "#login", target: "login" },
+        { guard: ({ event }) => event.to === "#dashboard", target: "dashboard" },
       ],
     },
     meta: { route: "/" },
@@ -149,38 +150,34 @@ states: {
 }
 ```
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) wires this up automatically from the `id` and `meta.route` fields you already have — each routed state gets a native XState v6 `route: {}` config (for `xstate.route` interop and graph tooling), and one root `play.route` forwarder navigates those targets in a single atomic transition, patching `params`/`query` into context:
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) generates these transitions automatically from the `id` and `meta.route` fields you already have:
 
 ```typescript
-import { createRoutedMachine, emptyEventSchema } from "@xmachines/play-xstate";
-
-const appSetup = setup({/* ... */});
-
-const appMachine = createRoutedMachine(appSetup)({
-	id: "app",
-	initial: "home",
-	states: {
-		home: { id: "home", meta: { route: "/" } },
-		login: { id: "login", meta: { route: "/login" } },
-		dashboard: { id: "dashboard", meta: { route: "/dashboard" } },
-	},
-});
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+
+const appMachine = setup({/* ... */}).createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		states: {
+			home: { id: "home", meta: { route: "/" } },
+			login: { id: "login", meta: { route: "/login" } },
+			dashboard: { id: "dashboard", meta: { route: "/dashboard" } },
+		},
+	}),
+);
 ```
 
-`createRoutedMachine` has the same signature as the setup's own `createMachine`, so the config keeps full contextual typing. (The underlying transform, [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md), can also be called directly on a config before `createMachine`.) The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
 
 ```typescript
-schemas: {
-  context: types<{
+types: {
+  context: {} as {
     params: Record<string, string>;
     query:  Record<string, string>;
     // ... other context fields
-  }>(),
-  events: {
-    "play.route": playRouteEventSchema, // exported by @xmachines/play-xstate
-    // ... other event schemas
   },
-  meta: playMetaSchema, // exported by @xmachines/play-xstate — types meta.route / meta.view
+  events: {} as PlayRouteEvent | OtherEvents,
 }
 ```
 
@@ -188,7 +185,7 @@ schemas: {
 
 ## Guards — the actor's authority
 
-Guards are the mechanism by which the actor controls whether a transition occurs. They are pure functions of transition arguments (`{ context, event, ... }`) that return a boolean. Named guards declared in `setup({ guards })` are passed to every transition function via `args.guards`:
+Guards are the mechanism by which the actor controls whether a transition occurs. They are pure functions of `{ context, event }` that return a boolean.
 
 ```typescript
 const authSetup = setup({
@@ -199,22 +196,11 @@ const authSetup = setup({
 });
 ```
 
-A transition function evaluates its guard condition and returns early to reject the transition:
-
-```typescript
-on: {
-	"admin.open": (args) => {
-		if (!args.guards.isAdmin(args)) return;
-		return { target: "adminPanel" };
-	},
-},
-```
-
-When the guard fails, the transition function returns `undefined`, the transition does not occur — the machine stays in its current state and the `play.route` event is discarded. The router bridge then sees that `actor.currentRoute` has not changed and corrects the URL back to the current valid route.
+Guards are evaluated by XState before a transition fires. If the guard returns `false`, the transition does not occur — the machine stays in its current state and the `play.route` event is discarded. The router bridge then sees that `actor.currentRoute` has not changed and corrects the URL back to the current valid route.
 
 This is the **Actor Authority** invariant in practice: the machine decides, infrastructure adjusts.
 
-XMachines provides guard combinators in [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) for composing complex conditions. Each combinator returns a plain predicate — call it inside a transition function with the transition arguments:
+XMachines provides guard combinators in [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) for composing complex conditions:
 
 | Function                                                                                            | What it does                            |
 | --------------------------------------------------------------------------------------------------- | --------------------------------------- |
@@ -229,27 +215,27 @@ XMachines provides guard combinators in [`@xmachines/play-xstate`](../api/@xmach
 
 ## Context — persistent state across transitions
 
-Context is the machine's persistent data store. It survives transitions and is updated by the shallow patches transition functions return:
+Context is the machine's persistent data store. It survives transitions and can be read and updated by actions:
 
 ```typescript
-// Context is defined in setup({ schemas })
-schemas: {
-  context: types<{
+// Context is defined in setup({ types })
+types: {
+  context: {} as {
     isAuthenticated: boolean;
     username: string | null;
     loginAttempts: number;
-  }>(),
+  },
 },
 
-// Transitions update context by returning a patch
-on: {
-  "login.failure": ({ context }) => ({
-    context: { loginAttempts: context.loginAttempts + 1 },
+// Actions mutate context via assign
+actions: {
+  recordLoginFailure: assign({
+    loginAttempts: ({ context }) => context.loginAttempts + 1,
   }),
 },
 ```
 
-Context is accessed in guards, transition functions, and when computing routes or views. It is not directly observable from outside the actor via signals — only the derived signals (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a `Signal.Computed` to the actor that derives from `actor.state`.
+Context is accessed in guards, actions, and when computing routes or views. It is not directly observable from outside the actor via signals — only the derived signals (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a `Signal.Computed` to the actor that derives from `actor.state`.
 
 ---
 
@@ -296,5 +282,5 @@ actor.start();
 - [Getting Started](getting-started.md) — step-by-step walkthrough building your first machine and actor
 - [Routing Patterns](../examples/routing-patterns.md) — worked examples of `meta.route` and guards
 - [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — full API reference for [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), guard combinators
-- [XState documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
+- [XState v5 documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
 - [Play RFC](../rfc/play.md) — complete architectural specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -15,7 +15,7 @@
   "author": "Mikael Karon <mikael@karon.se>",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@gitlab.com/xmachin-es/xmachines-js.git",
+    "url": "git+https://gitlab.com/xmachin-es/xmachines-js.git",
     "directory": "packages/docs"
   },
   "files": [
@@ -28,6 +28,7 @@
     "index.d.ts"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./index.d.ts",
@@ -53,13 +54,15 @@
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
-    "@types/node": "^26.1.1",
-    "@xmachines/shared": "2.0.0-alpha.1",
-    "oxfmt": "^0.58.0",
-    "oxlint": "^1.73.0",
+    "@types/node": "^26.2.0",
+    "oxfmt": "^0.64.0",
+    "oxlint": "^1.79.0",
     "typedoc": "^0.28.19",
     "typedoc-plugin-llms-txt": "^0.1.2",
     "typedoc-plugin-markdown": "^4.11.0",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=22.0.0"
   }
 }

package/rfc/play.md

@@ -11,7 +11,7 @@
 
 This RFC defines the **Universal Player Architecture** and its reference implementation. The architecture establishes a design pattern that strictly separates **Business Logic (The Actor)** from **Infrastructure (The Runtime Adapter and View)**.
 
-The reference implementation provides a modular monorepo that satisfies the architectural constraints of **Runtime Agnosticism** and **Logic-Driven Guarding**. It leverages **Standardized Signals (TC39)** to glue a specific **State Engine (XState v6)** to multiple **Runtime Adapters** (TanStack Router, React Router, Vue Router, SolidJS Router) and **View Layers** (React, Vue, SolidJS, Vanilla DOM — all via JSON-Render), while ensuring that **business logic remains the single source of truth** for navigation, state, and UI structure.
+The reference implementation provides a modular monorepo that satisfies the architectural constraints of **Runtime Agnosticism** and **Logic-Driven Guarding**. It leverages **Standardized Signals (TC39)** to glue a specific **State Engine (XState v5)** to multiple **Runtime Adapters** (TanStack Router, React Router, Vue Router, SolidJS Router) and **View Layers** (React, Vue, SolidJS, Vanilla DOM — all via JSON-Render), while ensuring that **business logic remains the single source of truth** for navigation, state, and UI structure.
 
 ---
 
@@ -153,7 +153,16 @@ export interface Routable {
 
 // Optional capability: View rendering
 export interface PlaySpec extends Spec {
-	contextProps?: string[];
+	// The machine's whole context is projected into the derived view's state
+	// under the read-only /context subtree; specs read it via
+	// { $state: "/context/…" } in props, visible conditions, and
+	// repeat.statePath. /context never accepts writes — machine context
+	// changes only through events.
+	//
+	// Stamped by view derivation from the selected meta entry (never
+	// authored): providers key their store lifecycle on it — changed key
+	// reseeds the store, unchanged key refreshes /context in place.
+	viewKey?: string;
 }
 
 export interface Viewable {
@@ -183,9 +192,9 @@ export abstract class AbstractActor<
 
 #### 5.2.1 `@xmachines/play-xstate`
 
-**Role:** Concrete Logic Adapter (XState v6)
+**Role:** Concrete Logic Adapter (XState v5)
 
-Wraps XState v6 to satisfy the `AbstractActor` contract. Provides the primary API for creating actors from state machine definitions.
+Wraps XState v5 to satisfy the `AbstractActor` contract. Provides the primary API for creating actors from state machine definitions.
 
 **Primary Exports:**
 
@@ -387,13 +396,13 @@ Defines **Logic**. No framework code. No routing library imports.
 import { setup } from "xstate";
 import { definePlayer } from "@xmachines/play-xstate";
 
-export const machine = setup({/* schemas, guards */}).createMachine({
+export const machine = setup({/* types, guards, actions */}).createMachine({
 	initial: "overview",
 	states: {
 		overview: {
 			meta: {
 				route: "/dashboard",
-				view: typedSpec<DashboardCtx>({
+				view: typedSpec({
 					root: "root",
 					elements: {
 						root: {

package/api/@xmachines/play-xstate/functions/createRoutedMachine.md

@@ -1,87 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / createRoutedMachine
-
-# Function: createRoutedMachine()
-
-```ts
-function createRoutedMachine<TSetup>(s): TSetup["createMachine"];
-```
-
-Defined in: [packages/play-xstate/src/routing/create-routed-machine.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/create-routed-machine.ts#L78)
-
-Returns a `createMachine` that routes: identical signature to the setup's
-own `createMachine`, with [formatPlayRouteTransitions](formatPlayRouteTransitions.md) applied to the
-config at runtime.
-
-### Why this exists
-
-`formatPlayRouteTransitions(config)` accepts a loosely-typed config. A config
-authored as a standalone value loses inline transition-function parameter
-inference entirely (implicit-any under strict mode), and even the inline
-`setup().createMachine(formatPlayRouteTransitions({ ... }))` form depends on
-TypeScript threading contextual typing through two generic calls.
-
-This wrapper removes the question: it is typed as the setup's own
-`createMachine`, so the config is contextually typed exactly as if passed to
-`setup().createMachine(...)` directly — transition-function args infer from
-the setup's schemas, sibling targets are validated, and the returned machine
-keeps its full literal state-value typing.
-
-Typing is _identical to native_ — including its current gaps: as of xstate
-6.0.0-alpha.20, `event` and `context` reads in transition args are fully
-typed, while returned context patches are property-typed but still carry a
-loose index signature in the alpha itself. Expect that to tighten upstream
-without changes here.
-
-## Type Parameters
-
-| Type Parameter                                                 |
-| -------------------------------------------------------------- |
-| `TSetup` _extends_ [`SetupLike`](../type-aliases/SetupLike.md) |
-
-## Parameters
-
-| Parameter | Type     | Description                                                  |
-| --------- | -------- | ------------------------------------------------------------ |
-| `s`       | `TSetup` | A `setup(...)` return value (anything with `createMachine`). |
-
-## Returns
-
-`TSetup`\[`"createMachine"`\]
-
-A function with the same signature as `s.createMachine` that
-applies [formatPlayRouteTransitions](formatPlayRouteTransitions.md) before creating the machine.
-
-## Example
-
-```typescript
-import { setup, types } from "xstate";
-import { createRoutedMachine, playMetaSchema, playRouteEventSchema } from "@xmachines/play-xstate";
-
-const authSetup = setup({
-	schemas: {
-		context: types<{ isAuthenticated: boolean }>(),
-		events: { "play.route": playRouteEventSchema },
-		meta: playMetaSchema,
-	},
-});
-
-const machine = createRoutedMachine(authSetup)({
-	initial: "home",
-	context: { isAuthenticated: false },
-	states: {
-		home: { id: "home", meta: { route: "/" } },
-		login: { id: "login", meta: { route: "/login" } },
-	},
-});
-// ({ context }) params in transitions infer from the setup schemas —
-// no explicit annotations needed.
-```
-
-Note: routes are injected at runtime, so the machine's static type does not
-gain an `xstate.route` event for them — `play.route` (declared in the
-setup's event schemas) remains the typed public API; native `xstate.route`
-interop is runtime-only.
-
-## See
-
-[formatPlayRouteTransitions](formatPlayRouteTransitions.md) for the routing transform itself

package/api/@xmachines/play-xstate/type-aliases/PlayRoutePayload.md

@@ -1,30 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayRoutePayload
-
-# Type Alias: PlayRoutePayload
-
-```ts
-type PlayRoutePayload = WithOptional<
-	WithOptional<
-		WithOptional<
-			{
-				to: PlayRouteEvent["to"];
-			},
-			{
-				params: Record<string, string>;
-			}
-		>,
-		{
-			query: Record<string, string>;
-		}
-	>,
-	{
-		match: unknown;
-	}
->;
-```
-
-Defined in: [packages/play-xstate/src/routing/schemas.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/schemas.ts#L62)
-
-The `play.route` event payload as machines receive it: `to` required;
-`params`/`query`/`match` encoded as optional-by-union so they stay omittable
-through XState v6's `Required<>` event inference.