@xmachines/docs 2.0.0-alpha.1 → 2.0.0

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:244](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L244)
+Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L225)
 
 Enhanced routing event with parameter and query support
 
@@ -120,10 +120,10 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 ## Properties
 
-| Property                               | Modifier   | Type                           | Defined in                                                                                                                              |
-| -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:249](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L249) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:247](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L247) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L248) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:246](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L246) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:245](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L245) |
+| Property                               | Modifier   | Type                           | Defined in                                                                                                                      |
+| -------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L230) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L228) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L229) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L227) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L226) |

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

@@ -2,12 +2,12 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/create-route-map.ts#L9)
 
 Options for `createRouteMap` and `createRouteMapFromTree`.
 
 ## Properties
 
-| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                                  |
-| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/create-route-map.ts#L20) |
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                          |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/create-route-map.ts#L20) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L51)
+Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L51)
 
 A single state ID ↔ path mapping entry.
 
@@ -21,7 +21,7 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 ## Properties
 
-| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                              |
-| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L55) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L53) |
+| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                      |
+| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L55) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L53) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-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)
+Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L341)
 
 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:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L376)
+Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L357)
 
 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:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L392)
+Defined in: [play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L373)
 
 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/v2.0.0-alpha.1/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/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/v2.0.0-alpha.1/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/packages/play-vue-router/src/play-router-provider.ts#L19)
 
 PlayRouterProvider — Vue convenience wrapper for VueRouterBridge.
 

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

@@ -1,13 +1,10 @@
 [API](../../README.md) / @xmachines/play-xstate
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-xstate
 
-> XState v6 adapter for the XMachines Play Architecture — bind state machines to the actor base with signal-driven reactivity and router integration.
+> XState v5 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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
 
 Part of the [XMachines Play](../../README.md) monorepo.
 
@@ -19,7 +16,7 @@ Part of the [XMachines Play](../../README.md) monorepo.
 pnpm add @xmachines/play-xstate xstate
 ```
 
-`xstate ^6.0.0-alpha.19` is a peer dependency and must be installed alongside this package.
+`xstate ^5.31.0` is a peer dependency and must be installed alongside this package.
 
 ---
 
@@ -27,18 +24,13 @@ pnpm add @xmachines/play-xstate xstate
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, emptyEventSchema, playMetaSchema } from "@xmachines/play-xstate";
+import { definePlayer } from "@xmachines/play-xstate";
 
-// 1. Define your XState v6 machine
-const machine = setup({
-	schemas: {
-		events: { activate: emptyEventSchema },
-		meta: playMetaSchema, // types meta.route / meta.view on state nodes
-	},
-}).createMachine({
+// 1. Define your XState v5 machine
+const machine = setup({}).createMachine({
 	initial: "idle",
 	states: {
-		idle: { meta: { route: "/" }, on: { activate: { target: "active" } } },
+		idle: { meta: { route: "/" } },
 		active: { meta: { route: "/active" } },
 	},
 });
@@ -66,16 +58,16 @@ actor.stop();
 
 ### `definePlayer(config)`
 
-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.
+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.
 
 ```typescript
-import { setup, types } from "xstate";
+import { setup } from "xstate";
 import { definePlayer } from "@xmachines/play-xstate";
 
 const machine = setup({
-	schemas: {
-		context: types<{ userId: string }>(),
-		input: types<{ userId: string }>(),
+	types: {
+		context: {} as { userId: string },
+		input: {} as { userId: string },
 	},
 }).createMachine({
 	context: ({ input }) => ({ userId: input.userId }),
@@ -91,6 +83,7 @@ const createPlayer = definePlayer({
 		onTransition: (actor, prev, next) => console.log("transitioned"),
 		onStateChange: (actor, state) => console.log("state changed"),
 		onError: (actor, err) => console.error(err),
+		inspect: (event) => console.log(event.type), // handed to XState's actor constructor — enables @statelyai/inspect
 	},
 });
 
@@ -101,17 +94,27 @@ const bob = createPlayer({ userId: "bob" });
 
 #### `PlayerFactory` signature
 
+`input` requiredness mirrors XState's `createActor`: a machine whose input type
+cannot be `undefined` makes the factory's first argument required, so forgetting
+it is a compile error instead of an actor stuck in an error status.
+
 ```typescript
-type PlayerFactory<TMachine> = (
-	input?: InputFrom<TMachine>,
-	options?: PlayerFactoryResumeOptions<TMachine>,
-) => PlayerActor<TMachine>;
+type PlayerFactory<TMachine> =
+	undefined extends InputFrom<TMachine>
+		? (
+				input?: InputFrom<TMachine>,
+				options?: PlayerFactoryResumeOptions<TMachine>,
+			) => PlayerActor<TMachine>
+		: (
+				input: InputFrom<TMachine>,
+				options?: PlayerFactoryResumeOptions<TMachine>,
+			) => PlayerActor<TMachine>;
 ```
 
 #### Restoring from a snapshot
 
 ```typescript
-const snapshot = actor.getSnapshot();
+const snapshot = actor.getPersistedSnapshot();
 actor.stop();
 
 // Restore to the exact saved state
@@ -120,11 +123,15 @@ restored.start();
 console.log(restored.currentRoute.get()); // same route as when saved
 ```
 
+> **Note:** Persist with `getPersistedSnapshot()`, not `getSnapshot()` — it is
+> the form `createActor` accepts, and the only one that round-trips machines
+> with invoked or spawned children.
+
 ---
 
 ### `PlayerActor<TMachine>`
 
-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`.
+Concrete actor class: an XState v5 actor that also exposes TC39 Signal-based reactive signals. Implements both `Routable` and `Viewable` interfaces from `@xmachines/play-actor`.
 
 #### Signals
 
@@ -165,7 +172,11 @@ actor.start();
 
 ### Guard utilities
 
-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 })`.
+> **Deprecated:** the guard helpers wrap XState's own `and()` / `or()` / `not()`
+> combinators without composing with `setup()`-typed guard slots. Use XState's
+> combinators directly; this module will be removed in the next major.
+
+Composable guard helpers that wrap XState's built-in `and()`, `or()`, and `not()` for use in machine `setup({ guards })` definitions.
 
 ```typescript
 import { setup } from "xstate";
@@ -178,24 +189,20 @@ 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: (args) => {
-			if (!canAccessAdmin(args)) return;
-			return { target: "adminPanel" };
+		accessAdmin: {
+			guard: composeGuards(["isLoggedIn", "hasAdminRole"]),
+			target: "adminPanel",
 		},
-		accessDashboard: (args) => {
-			if (!isAuthenticated(args)) return;
-			return { target: "dashboard" };
+		accessDashboard: {
+			guard: negateGuard("isGuest"),
+			target: "dashboard",
 		},
 	},
 	// ...
@@ -208,42 +215,13 @@ 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)`
 
-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.
+Crawls machine states with `meta.route` and auto-generates `play.route` event handlers at the root level — eliminating boilerplate routing transitions.
 
 ```typescript
 import { setup } from "xstate";
-import {
-	formatPlayRouteTransitions,
-	playMetaSchema,
-	playRouteEventSchema,
-} from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
 
 const config = formatPlayRouteTransitions({
 	id: "app",
@@ -259,47 +237,69 @@ const config = formatPlayRouteTransitions({
 	},
 });
 
-// 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);
+// config now includes auto-generated play.route handlers:
+// on: { "play.route": [ { target: ".home", guard: e => e.to === "#home" }, ... ] }
+const machine = setup({}).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 |
 
 ---
 
+## Inspection
+
+`options.inspect` is forwarded verbatim to XState's `createActor`, so every XState
+inspection tool — [`@statelyai/inspect`](https://stately.ai/docs/inspector)
+included — works against a `PlayerActor` unchanged:
+
+```typescript
+import { createBrowserInspector } from "@statelyai/inspect";
+
+const { inspect } = createBrowserInspector();
+const createPlayer = definePlayer({ machine, options: { inspect } });
+```
+
+Three things are worth knowing:
+
+- **It is a factory option, not a per-instance one.** Every actor a factory creates
+  reports to the same observer. Demultiplex by root: `event.rootId === actor.sessionId`
+  covers an actor's whole tree, children included.
+- **It is the only route that sees construction.** `actor.system.inspect(fn)` attaches
+  later and only sees events from that point on — including missing the `@xstate.actor`
+  registration an inspector needs in order to draw the machine at all.
+- **A `PlayerActor` is the actor.** Its own events carry `actorRef === playerActor`, so a
+  player can be recognised by identity. The one caveat: `@xstate.actor` fires from inside
+  the constructor, where `state`, `currentRoute`, `currentView` and `initialRoute` do not
+  exist yet — reading them there throws.
+
+For an inspector created after the factory (a dev-tools toggle, say), pass a forwarding
+function: `inspect: (event) => currentInspector?.(event)`.
+
+See the [inspector guide](../../../guides/inspector.md) for the full walkthrough —
+late attachment with replay, browser-free WebSocket inspection, and production
+considerations.
+
+---
+
 ## Exported Types
 
 ```typescript
 import type {
 	PlayerConfig, // definePlayer() config argument shape
-	PlayerOptions, // Lifecycle hooks (onStart, onStop, onTransition, onStateChange, onError)
+	PlayerOptions, // Lifecycle hooks (onStart, onStop, onTransition, onStateChange, onError) + inspect
 	PlayerFactory, // Factory function returned by definePlayer()
 	PlayerFactoryResumeOptions, // { snapshot? } for restoring actor state
-	Guard, // Single XState guard predicate
-	GuardArray, // Array of guards for compose helpers
-	ComposedGuard, // Return type of composeGuards / composeGuardsOr / negateGuard
+	Guard, // deprecated with the guard utilities — removed in the next major
+	GuardArray, // deprecated with the guard utilities — removed in the next major
+	ComposedGuard, // deprecated with the guard utilities — removed in the next major
 	RouteMachineConfig, // Minimal machine config accepted by formatPlayRouteTransitions
 	RouteStateNode, // Single state node shape used during route crawling
 	RouteContext, // Context shape expected by buildRouteUrl ({ params?, query?, basePath?, hash? })
@@ -317,14 +317,13 @@ Error classes are exported from the `@xmachines/play-xstate/errors` sub-path to
 ```typescript
 import {
 	MissingRouteParamError, // Required :param absent from context when resolving currentRoute
-	MissingQueryContextError, // context.params present but context.query missing
+	MissingQueryContextError, // deprecated: no longer thrown
 	MissingStateIdError, // meta.route declared without a state id field
 	InvalidMachineError, // PlayerActor constructed with a non-object machine
 	InvalidEventError, // actor.send() called with null/undefined/non-object
+	ActorThrewNonErrorError, // actor failed with a thrown value that is not an Error
 	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";
 ```
 
@@ -350,7 +349,7 @@ Tests use [Vitest](https://vitest.dev/) and live in `packages/play-xstate/test/`
 
 MIT — see [LICENSE](LICENSE) for details.
 
-@xmachines/play-xstate - XState v6 adapter for Play Architecture
+@xmachines/play-xstate - XState v5 adapter for Play Architecture
 
 Provides definePlayer() API for binding XState state machines to the
 actor base with signal lifecycle and DevTools integration.
@@ -373,34 +372,24 @@ reactivity.
 
 ## Type Aliases
 
-- [ComposedGuard](type-aliases/ComposedGuard.md)
-- [Guard](type-aliases/Guard.md)
-- [GuardArray](type-aliases/GuardArray.md)
+- [~~ComposedGuard~~](type-aliases/ComposedGuard.md)
+- [~~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
 
 - [buildRouteUrl](functions/buildRouteUrl.md)
-- [composeGuards](functions/composeGuards.md)
-- [composeGuardsOr](functions/composeGuardsOr.md)
-- [contextFieldMatches](functions/contextFieldMatches.md)
-- [createRoutedMachine](functions/createRoutedMachine.md)
+- [~~composeGuards~~](functions/composeGuards.md)
+- [~~composeGuardsOr~~](functions/composeGuardsOr.md)
+- [~~contextFieldMatches~~](functions/contextFieldMatches.md)
 - [definePlayer](functions/definePlayer.md)
 - [deriveRoute](functions/deriveRoute.md)
-- [eventMatches](functions/eventMatches.md)
+- [~~eventMatches~~](functions/eventMatches.md)
 - [formatPlayRouteTransitions](functions/formatPlayRouteTransitions.md)
-- [hasContext](functions/hasContext.md)
+- [~~hasContext~~](functions/hasContext.md)
 - [isAbsoluteRoute](functions/isAbsoluteRoute.md)
-- [negateGuard](functions/negateGuard.md)
+- [~~negateGuard~~](functions/negateGuard.md)