@xmachines/docs 1.0.0 → 2.0.0-alpha.1

package/api/@xmachines/play-vue-router/interfaces/RouterBridge.md

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L341)
+Defined in: [play-router/src/types.ts:360](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L360)
 
 RouterBridge interface for runtime infrastructure adapters
 
@@ -54,7 +54,7 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L357)
+Defined in: [play-router/src/types.ts:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L376)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L373)
+Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L392)
 
 Disconnect the router bridge from the Actor
 

package/api/@xmachines/play-vue-router/type-aliases/RoutableActor.md

@@ -6,7 +6,7 @@
 type RoutableActor = PlayActor;
 ```
 
-Defined in: [play-vue-router/src/play-router-provider.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-vue-router/src/play-router-provider.ts#L10)
+Defined in: [play-vue-router/src/play-router-provider.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-vue-router/src/play-router-provider.ts#L10)
 
 ## Deprecated
 

package/api/@xmachines/play-vue-router/variables/PlayRouterProvider.md

@@ -64,7 +64,7 @@ const PlayRouterProvider: DefineComponent<
 >;
 ```
 
-Defined in: [play-vue-router/src/play-router-provider.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-vue-router/src/play-router-provider.ts#L19)
+Defined in: [play-vue-router/src/play-router-provider.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-vue-router/src/play-router-provider.ts#L19)
 
 PlayRouterProvider — Vue convenience wrapper for VueRouterBridge.
 

package/api/@xmachines/play-xstate/README.md

@@ -4,7 +4,7 @@
 
 # @xmachines/play-xstate
 
-> XState v5 adapter for the XMachines Play Architecture — bind state machines to the actor base with signal-driven reactivity and router integration.
+> XState v6 adapter for the XMachines Play Architecture — bind state machines to the actor base with signal-driven reactivity and router integration.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Version](https://img.shields.io/badge/version-1.0.0--beta.51-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
@@ -19,7 +19,7 @@ Part of the [XMachines Play](../../README.md) monorepo.
 pnpm add @xmachines/play-xstate xstate
 ```
 
-`xstate ^5.31.0` is a peer dependency and must be installed alongside this package.
+`xstate ^6.0.0-alpha.19` is a peer dependency and must be installed alongside this package.
 
 ---
 
@@ -27,13 +27,18 @@ pnpm add @xmachines/play-xstate xstate
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
+import { definePlayer, emptyEventSchema, playMetaSchema } from "@xmachines/play-xstate";
 
-// 1. Define your XState v5 machine
-const machine = setup({}).createMachine({
+// 1. Define your XState v6 machine
+const machine = setup({
+	schemas: {
+		events: { activate: emptyEventSchema },
+		meta: playMetaSchema, // types meta.route / meta.view on state nodes
+	},
+}).createMachine({
 	initial: "idle",
 	states: {
-		idle: { meta: { route: "/" } },
+		idle: { meta: { route: "/" }, on: { activate: { target: "active" } } },
 		active: { meta: { route: "/active" } },
 	},
 });
@@ -61,16 +66,16 @@ actor.stop();
 
 ### `definePlayer(config)`
 
-Creates a `PlayerFactory` from an XState v5 machine. The factory pattern enables multiple independent actor instances from a single configuration — useful for multi-user scenarios, SSR, or testing.
+Creates a `PlayerFactory` from an XState v6 machine. The factory pattern enables multiple independent actor instances from a single configuration — useful for multi-user scenarios, SSR, or testing.
 
 ```typescript
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 import { definePlayer } from "@xmachines/play-xstate";
 
 const machine = setup({
-	types: {
-		context: {} as { userId: string },
-		input: {} as { userId: string },
+	schemas: {
+		context: types<{ userId: string }>(),
+		input: types<{ userId: string }>(),
 	},
 }).createMachine({
 	context: ({ input }) => ({ userId: input.userId }),
@@ -119,7 +124,7 @@ console.log(restored.currentRoute.get()); // same route as when saved
 
 ### `PlayerActor<TMachine>`
 
-Concrete actor class that wraps an XState v5 actor and exposes TC39 Signal-based reactive signals. Implements both `Routable` and `Viewable` interfaces from `@xmachines/play-actor`.
+Concrete actor class that wraps an XState v6 actor and exposes TC39 Signal-based reactive signals. Implements both `Routable` and `Viewable` interfaces from `@xmachines/play-actor`.
 
 #### Signals
 
@@ -160,7 +165,7 @@ actor.start();
 
 ### Guard utilities
 
-Composable guard helpers that wrap XState's built-in `and()`, `or()`, and `not()` for use in machine `setup({ guards })` definitions.
+Composable guard helpers that combine predicates with AND, OR, and NOT logic. Each helper returns a plain predicate — call it inside a transition function with the transition arguments and return early to block the transition. String guard names are resolved against the named guards declared in `setup({ guards })`.
 
 ```typescript
 import { setup } from "xstate";
@@ -173,20 +178,24 @@ import {
 	contextFieldMatches, // guard: context field equals a value
 } from "@xmachines/play-xstate";
 
+const canAccessAdmin = composeGuards(["isLoggedIn", "hasAdminRole"]);
+const isAuthenticated = negateGuard("isGuest");
+
 const machine = setup({
 	guards: {
 		isLoggedIn: ({ context }) => !!context.userId,
 		hasAdminRole: ({ context }) => context.role === "admin",
+		isGuest: ({ context }) => !context.userId,
 	},
 }).createMachine({
 	on: {
-		accessAdmin: {
-			guard: composeGuards(["isLoggedIn", "hasAdminRole"]),
-			target: "adminPanel",
+		accessAdmin: (args) => {
+			if (!canAccessAdmin(args)) return;
+			return { target: "adminPanel" };
 		},
-		accessDashboard: {
-			guard: negateGuard("isGuest"),
-			target: "dashboard",
+		accessDashboard: (args) => {
+			if (!isAuthenticated(args)) return;
+			return { target: "dashboard" };
 		},
 	},
 	// ...
@@ -199,13 +208,42 @@ const machine = setup({
 
 Helper functions for declarative route configuration in XState machines.
 
+#### `createRoutedMachine(setup)`
+
+The recommended entry point: returns a `createMachine` with the same signature as the setup's own — full contextual typing for the config — that wires routing up at runtime.
+
+```typescript
+import { setup } from "xstate";
+import { createRoutedMachine } from "@xmachines/play-xstate";
+
+const appSetup = setup({/* schemas, guards, ... */});
+
+const machine = createRoutedMachine(appSetup)({
+	id: "app",
+	states: {
+		home: {
+			id: "home",
+			meta: { route: "/home" },
+		},
+		profile: {
+			id: "profile",
+			meta: { route: "/users/:userId" },
+		},
+	},
+});
+```
+
 #### `formatPlayRouteTransitions(machineConfig)`
 
-Crawls machine states with `meta.route` and auto-generates `play.route` event handlers at the root level — eliminating boilerplate routing transitions.
+The underlying transform. Crawls machine states with `meta.route` and wires them to XState v6's native routing: each routed state gets a native `route: {}` config (targetable via the built-in `xstate.route` event and visible to graph tooling), and one root `play.route` forwarder navigates those targets in a single atomic transition — patching `params`/`query` into context — while re-raising `xstate.route` only for states that declare their own `route` config. Unknown targets fall through to user-defined `play.route` fallbacks (e.g. a 404 route); one `play.route` send is one atomic transition, so exit actions see the old `params` and entry actions the new ones.
 
 ```typescript
 import { setup } from "xstate";
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import {
+	formatPlayRouteTransitions,
+	playMetaSchema,
+	playRouteEventSchema,
+} from "@xmachines/play-xstate";
 
 const config = formatPlayRouteTransitions({
 	id: "app",
@@ -221,17 +259,30 @@ const config = formatPlayRouteTransitions({
 	},
 });
 
-// config now includes auto-generated play.route handlers:
-// on: { "play.route": [ { target: ".home", guard: e => e.to === "#home" }, ... ] }
-const machine = setup({}).createMachine(config);
+// config now carries native route configs plus the play.route forwarder:
+// states: { home: { ..., route: {} }, profile: { ..., route: {} } }
+// on: { "play.route": [forwarder, ...userFallbacks] }
+// The forwarder navigates injected-route targets directly (atomically);
+// xstate.route is raised only for states declaring their own route config.
+const machine = setup({
+	schemas: {
+		events: { "play.route": playRouteEventSchema },
+		meta: playMetaSchema,
+	},
+}).createMachine(config);
 ```
 
+Because the injected `route` configs are static, route transitions keep statically-known targets — `machineToGraph()` sees real edges to every routed state, so reachability queries work.
+
 > **Note:** Every state with `meta.route` must also have an explicit `id` field; omitting it throws `MissingStateIdError` at machine-definition time.
 
 #### Other routing exports
 
 | Export                             | Description                                                               |
 | ---------------------------------- | ------------------------------------------------------------------------- |
+| `playMetaSchema`                   | Shared `schemas.meta` declaration for `meta.route` / `meta.view` metadata |
+| `playRouteEventSchema`             | Shared `schemas.events` entry for the `play.route` event payload          |
+| `emptyEventSchema`                 | Shared `schemas.events` entry for events that carry no payload            |
 | `deriveRoute(meta)`                | Extract the route template string from a state's metadata object          |
 | `isAbsoluteRoute(route)`           | Returns `true` if the route string is an absolute URL path                |
 | `buildRouteUrl(template, context)` | Substitute `:param` placeholders in a route template using context values |
@@ -272,6 +323,8 @@ import {
 	InvalidEventError, // actor.send() called with null/undefined/non-object
 	InvalidRouteMetadataError, // meta.route is neither a string nor { path: string }
 	EmptyGuardArrayError, // composeGuards/composeGuardsOr called with empty array
+	UnresolvableGuardNameError, // string guard name could not be resolved at call time
+	InvalidGuardEntryError, // guard entry was neither a predicate nor a name (e.g. undefined)
 } from "@xmachines/play-xstate/errors";
 ```
 
@@ -297,7 +350,7 @@ Tests use [Vitest](https://vitest.dev/) and live in `packages/play-xstate/test/`
 
 MIT — see [LICENSE](LICENSE) for details.
 
-@xmachines/play-xstate - XState v5 adapter for Play Architecture
+@xmachines/play-xstate - XState v6 adapter for Play Architecture
 
 Provides definePlayer() API for binding XState state machines to the
 actor base with signal lifecycle and DevTools integration.
@@ -324,9 +377,18 @@ reactivity.
 - [Guard](type-aliases/Guard.md)
 - [GuardArray](type-aliases/GuardArray.md)
 - [PlayerFactory](type-aliases/PlayerFactory.md)
+- [PlayRoutePayload](type-aliases/PlayRoutePayload.md)
 - [RouteMachineConfig](type-aliases/RouteMachineConfig.md)
 - [RouteMetadata](type-aliases/RouteMetadata.md)
 - [RouteStateNode](type-aliases/RouteStateNode.md)
+- [SetupLike](type-aliases/SetupLike.md)
+- [WithOptional](type-aliases/WithOptional.md)
+
+## Variables
+
+- [emptyEventSchema](variables/emptyEventSchema.md)
+- [playMetaSchema](variables/playMetaSchema.md)
+- [playRouteEventSchema](variables/playRouteEventSchema.md)
 
 ## Functions
 
@@ -334,6 +396,7 @@ reactivity.
 - [composeGuards](functions/composeGuards.md)
 - [composeGuardsOr](functions/composeGuardsOr.md)
 - [contextFieldMatches](functions/contextFieldMatches.md)
+- [createRoutedMachine](functions/createRoutedMachine.md)
 - [definePlayer](functions/definePlayer.md)
 - [deriveRoute](functions/deriveRoute.md)
 - [eventMatches](functions/eventMatches.md)

package/api/@xmachines/play-xstate/classes/PlayerActor.md

@@ -2,11 +2,11 @@
 
 # Class: PlayerActor\<TMachine\>
 
-Defined in: [packages/play-xstate/src/player-actor.ts:362](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L362)
+Defined in: [packages/play-xstate/src/player-actor.ts:362](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L362)
 
 Concrete XState actor implementing Play Architecture signal protocol
 
-Extends [@xmachines/play-actor!AbstractActor](../../play-actor/classes/AbstractActor.md) to provide XState v5 integration
+Extends [@xmachines/play-actor!AbstractActor](../../play-actor/classes/AbstractActor.md) to provide XState v6 integration
 while maintaining ecosystem compatibility (XState inspection, devtools). This actor
 wraps an internal XState actor and exposes TC39 Signal-based reactive state for
 Infrastructure observation.
@@ -89,7 +89,7 @@ cached and updated at state entry, not computed on every read.
 
 | Type Parameter                                                                                 | Description                  |
 | ---------------------------------------------------------------------------------------------- | ---------------------------- |
-| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine type |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v6 state machine type |
 
 ## Implements
 
@@ -108,7 +108,7 @@ new PlayerActor<TMachine>(
 restoredSnapshot?): PlayerActor<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:454](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L454)
+Defined in: [packages/play-xstate/src/player-actor.ts:459](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L459)
 
 #### Parameters
 
@@ -129,22 +129,23 @@ Defined in: [packages/play-xstate/src/player-actor.ts:454](https://gitlab.com/xm
 
 ## Properties
 
-| Property                                          | Modifier   | Type                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Overrides                                                                                                                        | Inherited from                                                                                                                           | Defined in                                                                                                                                             |
-| ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-_parent"></a> `_parent?`          | `public`   | [`AnyActorRef`](https://www.jsdocs.io/package/xstate#AnyActorRef)                                                                   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`_parent`](../../play-actor/classes/AbstractActor.md#property-_parent)     | -                                                                                                                                                      |
-| <a id="property-clock"></a> `clock`               | `public`   | [`Clock`](https://www.jsdocs.io/package/xstate#Clock)                                                                               | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`clock`](../../play-actor/classes/AbstractActor.md#property-clock)         | -                                                                                                                                                      |
-| <a id="property-currentroute"></a> `currentRoute` | `public`   | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | A TC39 `Signal.Computed` that derives the current URL path from the active machine state's `meta.route` template and the actor's context. Returns `null` when the current state has no `meta.route`, or when the route template cannot be fully resolved (e.g. a required parameter is absent from context). **Throws** When a required `:param` placeholder in the route template has no matching value in the actor's context. Import the class from `@xmachines/play-xstate/errors`. **Example** `// Returns "/profile/alice" when context.userId === "alice" const route = actor.currentRoute.get();`                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:408](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L408) |
-| <a id="property-currentview"></a> `currentView`   | `public`   | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | Reactive signal containing the current view spec derived from the active state's `meta.view` metadata. Emits a **fresh object reference** whenever the rendered view actually changes — a different state's view, or a param/context change that alters the resolved spec (including `reenter: true` re-entries with new params). Snapshots that do not change the rendered view (e.g. context-only assigns) keep the previous reference so downstream providers do not remount the UI on every event. The emitted `PlaySpec` has its element `props` enriched with `context.params` before emission — URL path parameters (e.g. `:section?`) flow into component props automatically. See `mergeRouteParamsIntoProps` for the merge priority rules. Returns `null` when the current state has no `meta.view` metadata. **Example** `const view = actor.currentView.get(); if (view) { console.log(view.root); // e.g. "root" console.log(view.elements); // @xmachines/json-render-core Spec elements }` | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:452](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L452) |
-| <a id="property-id"></a> `id`                     | `public`   | `string`                                                                                                                            | The unique identifier for this actor relative to its parent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`id`](../../play-actor/classes/AbstractActor.md#property-id)               | -                                                                                                                                                      |
-| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route derived from the machine's initial state — fixed at construction, never changes even when the actor is restored from a snapshot. Router bridges compare this against the browser URL to distinguish a deep-link (non-initial URL → router wins) from a restore (initial URL + actor at a different restored route → actor wins). Derived statically from the machine definition via `deriveInitialRoute` (XState's pure `initialTransition` helper): the initial state chain and its `meta.route` templates are fixed at machine definition time, while `:param` substitution uses the machine's real initial context for this actor's `input`. No extra actor is ever created, and a restored snapshot never influences the value — it is always the machine's **default** initial route.                                                                                                                                                                                                      | -                                                                                                                                | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:425](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L425) |
-| <a id="property-logic"></a> `logic`               | `public`   | [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`logic`](../../play-actor/classes/AbstractActor.md#property-logic)         | -                                                                                                                                                      |
-| <a id="property-options"></a> `options`           | `public`   | `Readonly`\<[`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\>\>                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`options`](../../play-actor/classes/AbstractActor.md#property-options)     | -                                                                                                                                                      |
-| <a id="property-ref"></a> `ref`                   | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<`any`, `any`, `any`\>                                                  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`ref`](../../play-actor/classes/AbstractActor.md#property-ref)             | -                                                                                                                                                      |
-| <a id="property-sessionid"></a> `sessionId`       | `public`   | `string`                                                                                                                            | The globally unique process ID for this invocation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`sessionId`](../../play-actor/classes/AbstractActor.md#property-sessionid) | -                                                                                                                                                      |
-| <a id="property-src"></a> `src`                   | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`src`](../../play-actor/classes/AbstractActor.md#property-src)             | -                                                                                                                                                      |
-| <a id="property-state"></a> `state`               | `public`   | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`ReturnType`\<`TMachine`\[`"transition"`\]\>\>                    | Reactive snapshot of current actor state. Infrastructure observes this signal to react to state changes without directly coupling to the actor's internal state machine implementation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`state`](../../play-actor/classes/AbstractActor.md#property-state) | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L373) |
-| <a id="property-system"></a> `system`             | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                             | The system to which this actor belongs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`system`](../../play-actor/classes/AbstractActor.md#property-system)       | -                                                                                                                                                      |
-| <a id="property-systemid"></a> `systemId`         | `public`   | `string` \| `undefined`                                                                                                             | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`systemId`](../../play-actor/classes/AbstractActor.md#property-systemid)   | -                                                                                                                                                      |
+| Property                                          | Modifier   | Type                                                                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Overrides                                                                                                                        | Inherited from                                                                                                                               | Defined in                                                                                                                                                     |
+| ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-_parent"></a> `_parent?`          | `public`   | `AnyActor`                                                                                                                                            | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`_parent`](../../play-actor/classes/AbstractActor.md#property-_parent)         | -                                                                                                                                                              |
+| <a id="property-clock"></a> `clock`               | `public`   | [`Clock`](https://www.jsdocs.io/package/xstate#Clock)                                                                                                 | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`clock`](../../play-actor/classes/AbstractActor.md#property-clock)             | -                                                                                                                                                              |
+| <a id="property-currentroute"></a> `currentRoute` | `public`   | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                                          | A TC39 `Signal.Computed` that derives the current URL path from the active machine state's `meta.route` template and the actor's context. Returns `null` when the current state has no `meta.route`, or when the route template cannot be fully resolved (e.g. a required parameter is absent from context). **Throws** When a required `:param` placeholder in the route template has no matching value in the actor's context. Import the class from `@xmachines/play-xstate/errors`. **Example** `// Returns "/profile/alice" when context.userId === "alice" const route = actor.currentRoute.get();`                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                                | -                                                                                                                                            | [packages/play-xstate/src/player-actor.ts:413](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L413) |
+| <a id="property-currentview"></a> `currentView`   | `public`   | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\>                   | Reactive signal containing the current view spec derived from the active state's `meta.view` metadata. Emits a **fresh object reference** whenever the rendered view actually changes — a different state's view, or a param/context change that alters the resolved spec (including `reenter: true` re-entries with new params). Snapshots that do not change the rendered view (e.g. context-only assigns) keep the previous reference so downstream providers do not remount the UI on every event. The emitted `PlaySpec` has its element `props` enriched with `context.params` before emission — URL path parameters (e.g. `:section?`) flow into component props automatically. See `mergeRouteParamsIntoProps` for the merge priority rules. Returns `null` when the current state has no `meta.view` metadata. **Example** `const view = actor.currentView.get(); if (view) { console.log(view.root); // e.g. "root" console.log(view.elements); // @xmachines/json-render-core Spec elements }` | -                                                                                                                                | -                                                                                                                                            | [packages/play-xstate/src/player-actor.ts:457](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L457) |
+| <a id="property-id"></a> `id`                     | `public`   | `string`                                                                                                                                              | The unique identifier for this actor relative to its parent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`id`](../../play-actor/classes/AbstractActor.md#property-id)                   | -                                                                                                                                                              |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                                    | The route derived from the machine's initial state — fixed at construction, never changes even when the actor is restored from a snapshot. Router bridges compare this against the browser URL to distinguish a deep-link (non-initial URL → router wins) from a restore (initial URL + actor at a different restored route → actor wins). Derived statically from the machine definition via `deriveInitialRoute` (XState's pure `initialTransition` helper): the initial state chain and its `meta.route` templates are fixed at machine definition time, while `:param` substitution uses the machine's real initial context for this actor's `input`. No extra actor is ever created, and a restored snapshot never influences the value — it is always the machine's **default** initial route.                                                                                                                                                                                                      | -                                                                                                                                | -                                                                                                                                            | [packages/play-xstate/src/player-actor.ts:430](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L430) |
+| <a id="property-logic"></a> `logic`               | `public`   | [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                 | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`logic`](../../play-actor/classes/AbstractActor.md#property-logic)             | -                                                                                                                                                              |
+| <a id="property-options"></a> `options`           | `public`   | `Readonly`\<[`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\>\>                                                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`options`](../../play-actor/classes/AbstractActor.md#property-options)         | -                                                                                                                                                              |
+| <a id="property-ref"></a> `ref`                   | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<`any`, `any`, [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject), `any`\> | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`ref`](../../play-actor/classes/AbstractActor.md#property-ref)                 | -                                                                                                                                                              |
+| <a id="property-registrykey"></a> `registryKey`   | `public`   | `string` \| `undefined`                                                                                                                               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`registryKey`](../../play-actor/classes/AbstractActor.md#property-registrykey) | -                                                                                                                                                              |
+| <a id="property-sessionid"></a> `sessionId`       | `public`   | `string`                                                                                                                                              | The globally unique process ID for this invocation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`sessionId`](../../play-actor/classes/AbstractActor.md#property-sessionid)     | -                                                                                                                                                              |
+| <a id="property-src"></a> `src`                   | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`src`](../../play-actor/classes/AbstractActor.md#property-src)                 | -                                                                                                                                                              |
+| <a id="property-state"></a> `state`               | `public`   | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\>\> | Reactive snapshot of current actor state. Infrastructure observes this signal to react to state changes without directly coupling to the actor's internal state machine implementation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`state`](../../play-actor/classes/AbstractActor.md#property-state) | -                                                                                                                                            | [packages/play-xstate/src/player-actor.ts:375](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L375) |
+| <a id="property-system"></a> `system`             | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                               | The system to which this actor belongs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`system`](../../play-actor/classes/AbstractActor.md#property-system)           | -                                                                                                                                                              |
+| <a id="property-trigger"></a> `trigger`           | `public`   | `ActorTrigger`\<`SendableEventFromLogic`\<`TLogic`\>\>                                                                                                | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`trigger`](../../play-actor/classes/AbstractActor.md#property-trigger)         | -                                                                                                                                                              |
 
 ## Methods
 
@@ -172,7 +173,7 @@ Defined in: `xstate`
 can(event): boolean;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:386](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L386)
+Defined in: [packages/play-xstate/src/player-actor.ts:388](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L388)
 
 Returns whether the actor's current state can accept the given event.
 
@@ -203,7 +204,7 @@ if (actor.can({ type: "auth.logout" })) { ... }
 dispose(): void;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:727](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L727)
+Defined in: [packages/play-xstate/src/player-actor.ts:731](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L731)
 
 Convenience dispose method for cleanup
 
@@ -221,7 +222,7 @@ Per CONTEXT.md: "Both .dispose() convenience method and manual machine.stop()"
 getPersistedSnapshot(): Snapshot<unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:685](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L685)
+Defined in: [packages/play-xstate/src/player-actor.ts:689](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L689)
 
 Get the persisted snapshot of the wrapped XState actor.
 
@@ -244,7 +245,7 @@ Suitable for serialization and later restoration via the factory's
 getSnapshot(): SnapshotFrom<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:609](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L609)
+Defined in: [packages/play-xstate/src/player-actor.ts:613](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L613)
 
 Get current snapshot
 
@@ -264,15 +265,15 @@ Get current snapshot
 on<TType>(type, handler): Subscription;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:670](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L670)
+Defined in: [packages/play-xstate/src/player-actor.ts:674](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L674)
 
 Listen for events emitted by the wrapped XState actor via the `emit` action.
 
 #### Type Parameters
 
-| Type Parameter          |
-| ----------------------- |
-| `TType` _extends_ `any` |
+| Type Parameter             |
+| -------------------------- |
+| `TType` _extends_ `string` |
 
 #### Parameters
 
@@ -330,7 +331,7 @@ Defined in: `xstate`
 send(event): void;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:586](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L586)
+Defined in: [packages/play-xstate/src/player-actor.ts:590](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L590)
 
 Send an event to the underlying XState actor.
 
@@ -374,7 +375,7 @@ actor.send({ type: "play.route", to: "#home" });
 start(): this;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:541](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L541)
+Defined in: [packages/play-xstate/src/player-actor.ts:545](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L545)
 
 Start the actor
 
@@ -396,7 +397,7 @@ Per RESEARCH.md Pitfall 1: Always call start() after creation
 stop(): this;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:555](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L555)
+Defined in: [packages/play-xstate/src/player-actor.ts:559](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L559)
 
 Stop the actor and cleanup
 
@@ -418,7 +419,7 @@ Stop the actor and cleanup
 subscribe(observer): Subscription;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:631](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L631)
+Defined in: [packages/play-xstate/src/player-actor.ts:635](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L635)
 
 Subscribe to snapshot updates from the wrapped XState actor.
 
@@ -449,7 +450,7 @@ subscribe(
    completeListener?): Subscription;
 ```
 
-Defined in: [packages/play-xstate/src/player-actor.ts:642](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/player-actor.ts#L642)
+Defined in: [packages/play-xstate/src/player-actor.ts:646](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/player-actor.ts#L646)
 
 Subscribe to snapshot updates from the wrapped XState actor.
 

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

@@ -6,7 +6,7 @@
 function buildRouteUrl(routeTemplate, context?): string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/build-url.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/build-url.ts#L40)
+Defined in: [packages/play-xstate/src/routing/build-url.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/build-url.ts#L40)
 
 Build a full URL from a route template and the actor's context.