@xmachines/docs 1.0.0-beta.9 → 2.0.0-alpha.1

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / buildRouteUrl
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / buildRouteUrl
 
 # Function: buildRouteUrl()
 
@@ -6,38 +6,49 @@
 function buildRouteUrl(routeTemplate, context?): string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/build-url.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/build-url.ts#L28)
+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 full URL from route template and context
+Build a full URL from a route template and the actor's context.
 
-Per CONTEXT.md:
+Substitutes `:param` and `:param?` placeholders from `context.params`,
+then appends query params and hash fragments.
 
-- "currentRoute derivation: Full URL generation including query params, hash, base path"
-- "Parameters: String template syntax — /user/:id"
-- "Inheritance: relative paths inherit parent route"
-
-Per RESEARCH.md Pattern 3: Replace :param with context values
+All parameter values must be in `context.params`. Flat context fields are not
+inspected — this is intentional so misspelled placeholders produce a compile-time
+error rather than silently resolving to `undefined`.
 
 ## Parameters
 
-| Parameter       | Type                                            | Description                                |
-| --------------- | ----------------------------------------------- | ------------------------------------------ |
-| `routeTemplate` | `string`                                        | Route path with :param placeholders        |
-| `context`       | [`RouteContext`](../interfaces/RouteContext.md) | Route context with parameters, query, hash |
+| Parameter       | Type                                            | Description                                                                                                                                                                                                                                                                                                         |
+| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `routeTemplate` | `string`                                        | Route path template, e.g. `"/profile/:userId"` or `"/settings/:section?"`.                                                                                                                                                                                                                                          |
+| `context`       | [`RouteContext`](../interfaces/RouteContext.md) | Actor context object. Route parameters must be in `context.params`; flat context fields are not inspected. **Must include a `query` field** (use `query: {}` when no query parameters are needed). Omitting `query` when `params` is present throws `MissingQueryContextError` to prevent silent query-string loss. |
 
 ## Returns
 
 `string`
 
-Full URL string
+The fully resolved URL string.
+
+## Throws
+
+When a **required** `:param` placeholder has no
+matching value in context. Optional parameters (`:param?`) are silently omitted
+when missing. Import the class from `@xmachines/play-xstate/errors`.
+
+## Throws
+
+When the context has a `params` field but no
+`query` field. This indicates a routing-aware machine context that was not set up
+to receive query parameters, which would silently drop query params from
+`play.route` events. Import the class from `@xmachines/play-xstate/errors`.
 
 ## Example
 
 ```typescript
-const url = buildRouteUrl("/user/:id", {
-	id: "123",
-	query: { tab: "profile" },
-	hash: "section-1",
-});
-// Result: '/user/123?tab=profile#section-1'
+buildRouteUrl("/user/:id", { params: { id: "123" }, query: { tab: "profile" }, hash: "top" });
+// → "/user/123?tab=profile#top"
+
+buildRouteUrl("/settings/:section?", { params: {}, query: {} });
+// → "/settings"  (optional param omitted, no query string)
 ```

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuards
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuards
 
 # Function: composeGuards()
 
@@ -6,36 +6,38 @@
 function composeGuards<TContext, TEvent>(guards): ComposedGuard;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/compose.ts#L72)
+Defined in: [packages/play-xstate/src/guards/compose.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/compose.ts#L130)
 
-Compose guards with AND logic using XState's and() helper
+Compose guards with AND logic.
 
 Combines multiple guard predicates using AND semantics—all guards must pass for
-the composition to succeed. Uses XState's built-in `and()` helper to ensure proper
-type inference and machine serialization.
+the composition to succeed. Evaluation is short-circuiting, left to right.
 
 **Architectural Context:** Supports **Actor Authority (INV-01)** by enabling
 declarative guard composition in state machine transitions. Guards enforce business
 logic rules that determine whether navigation or actions are valid.
 
+**XState v6:** the composed value is a plain predicate. Call it inside a
+transition function and return early to block the transition:
+
 ## Type Parameters
 
-| Type Parameter | Default type | Description                |
-| -------------- | ------------ | -------------------------- |
-| `TContext`     | `any`        | State machine context type |
-| `TEvent`       | `any`        | Event type                 |
+| Type Parameter | Default type | Description                                                                                                            |
+| -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `TContext`     | `any`        | State machine context type (defaults to `any` so the documented inline-predicate examples compile without annotations) |
+| `TEvent`       | `any`        | Event type                                                                                                             |
 
 ## Parameters
 
-| Parameter | Type                                                                  | Description                                                  |
-| --------- | --------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names (string references) |
+| Parameter | Type                                                                  | Description                                                                                                          |
+| --------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names (string references resolved against `args.guards` from `setup({ guards })`) |
 
 ## Returns
 
 [`ComposedGuard`](../type-aliases/ComposedGuard.md)
 
-XState and() guard composition
+Predicate returning `true` only when every guard passes
 
 ## Throws
 
@@ -49,6 +51,8 @@ AND composition with named guards
 import { setup } from "xstate";
 import { composeGuards } from "@xmachines/play-xstate";
 
+const canAccessAdmin = composeGuards(["isLoggedIn", "hasPermission"]);
+
 const machine = setup({
 	guards: {
 		isLoggedIn: ({ context }) => !!context.userId,
@@ -56,10 +60,9 @@ const machine = setup({
 	},
 }).createMachine({
 	on: {
-		accessAdmin: {
-			// Both guards must pass
-			guard: composeGuards(["isLoggedIn", "hasPermission"]),
-			target: "adminPanel",
+		accessAdmin: (args) => {
+			if (!canAccessAdmin(args)) return;
+			return { target: "adminPanel" };
 		},
 	},
 });
@@ -70,7 +73,10 @@ AND composition with inline predicates
 ```typescript
 import { composeGuards } from "@xmachines/play-xstate";
 
-guard: composeGuards([({ context }) => context.age >= 18, ({ context }) => context.verified]);
+const isEligible = composeGuards([
+	({ context }) => context.age >= 18,
+	({ context }) => context.verified,
+]);
 ```
 
 ## See

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuardsOr
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuardsOr
 
 # Function: composeGuardsOr()
 
@@ -6,32 +6,31 @@
 function composeGuardsOr<TContext, TEvent>(guards): ComposedGuard;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/compose.ts#L138)
+Defined in: [packages/play-xstate/src/guards/compose.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/compose.ts#L189)
 
-Compose guards with OR logic using XState's or() helper
+Compose guards with OR logic.
 
 Combines multiple guard predicates using OR semantics—at least one guard must pass
-for the composition to succeed. Uses XState's built-in `or()` helper for proper
-type inference.
+for the composition to succeed. Evaluation is short-circuiting, left to right.
 
 ## Type Parameters
 
-| Type Parameter | Default type | Description                |
-| -------------- | ------------ | -------------------------- |
-| `TContext`     | `any`        | State machine context type |
-| `TEvent`       | `any`        | Event type                 |
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `TContext`     | `any`        |
+| `TEvent`       | `any`        |
 
 ## Parameters
 
-| Parameter | Type                                                                  | Description                              |
-| --------- | --------------------------------------------------------------------- | ---------------------------------------- |
-| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names |
+| Parameter | Type                                                                  | Description                                                                                                          |
+| --------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names (string references resolved against `args.guards` from `setup({ guards })`) |
 
 ## Returns
 
 [`ComposedGuard`](../type-aliases/ComposedGuard.md)
 
-XState or() guard composition
+Predicate returning `true` when any guard passes
 
 ## Throws
 
@@ -45,6 +44,8 @@ OR composition with named guards
 import { setup } from "xstate";
 import { composeGuardsOr } from "@xmachines/play-xstate";
 
+const canDelete = composeGuardsOr(["isOwner", "isAdmin"]);
+
 const machine = setup({
 	guards: {
 		isOwner: ({ context }) => context.role === "owner",
@@ -52,10 +53,9 @@ const machine = setup({
 	},
 }).createMachine({
 	on: {
-		deleteResource: {
-			// Either guard can pass
-			guard: composeGuardsOr(["isOwner", "isAdmin"]),
-			actions: "delete",
+		deleteResource: (args, enq) => {
+			if (!canDelete(args)) return;
+			enq(() => deleteIt());
 		},
 	},
 });

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

@@ -0,0 +1,38 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / contextFieldMatches
+
+# Function: contextFieldMatches()
+
+```ts
+function contextFieldMatches<TContext>(fieldPath, expectedValue): Guard<TContext, PlayEvent>;
+```
+
+Defined in: [packages/play-xstate/src/guards/helpers.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/helpers.ts#L71)
+
+Check if a context field matches an expected value.
+
+- Accepts an explicit dot-separated field path (e.g. `"user.role"`)
+- Uses strict equality for primitives, deep structural equality for objects
+- Object comparison is key-order-insensitive: `{a:1,b:2}` equals `{b:2,a:1}`
+- Supports Date, RegExp, class instances, nested objects and arrays via `dequal/lite`
+- Does NOT use substring matching — `"a"` will not match `"active"`
+
+For XState state-node matching, use the built-in `in:` guard syntax instead.
+
+## Type Parameters
+
+| Type Parameter | Default type                    |
+| -------------- | ------------------------------- |
+| `TContext`     | `Record`\<`string`, `unknown`\> |
+
+## Parameters
+
+| Parameter       | Type      | Description                                                          |
+| --------------- | --------- | -------------------------------------------------------------------- |
+| `fieldPath`     | `string`  | Dot-separated path to context property (e.g., "status", "user.role") |
+| `expectedValue` | `unknown` | Value to compare against (string, object, Date, etc.)                |
+
+## Returns
+
+[`Guard`](../type-aliases/Guard.md)\<`TContext`, [`PlayEvent`](../../play/type-aliases/PlayEvent.md)\>
+
+Guard predicate checking if context field matches

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

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

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

@@ -1,36 +1,31 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / definePlayer
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / definePlayer
 
 # Function: definePlayer()
 
 ```ts
-function definePlayer<TMachine, TCatalog>(config): PlayerFactory<TMachine>;
+function definePlayer<TMachine>(config): PlayerFactory<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/define-player.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/define-player.ts#L111)
+Defined in: [packages/play-xstate/src/define-player.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/define-player.ts#L61)
 
-Create a player factory from XState machine and catalog
+Create a player factory from an XState machine
 
-Factory pattern that accepts an XState v5 machine and optional UI catalog,
+Factory pattern that accepts an XState v6 machine,
 returning a function that creates [PlayerActor](../classes/PlayerActor.md) instances. This enables
 creating multiple actor instances from a single configuration, useful for
 testing, multi-instance scenarios, or server-side rendering.
 
-**Architectural Context:** Implements **Strict Separation (INV-02)** by accepting
-the machine definition (pure business logic) separately from the catalog (UI vocabulary).
-The machine references component names in `meta.view` without importing React/framework code.
-
 ## Type Parameters
 
-| Type Parameter                         | Default type                    | Description                        |
-| -------------------------------------- | ------------------------------- | ---------------------------------- |
-| `TMachine` _extends_ `AnyStateMachine` | -                               | XState v5 state machine type       |
-| `TCatalog`                             | `Record`\<`string`, `unknown`\> | Optional UI component catalog type |
+| Type Parameter                                                                                 | Description                  |
+| ---------------------------------------------------------------------------------------------- | ---------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v6 state machine type |
 
 ## Parameters
 
-| Parameter | Type                                                                      | Description                 |
-| --------- | ------------------------------------------------------------------------- | --------------------------- |
-| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`, `TCatalog`\> | Player configuration object |
+| Parameter | Type                                                          | Description                 |
+| --------- | ------------------------------------------------------------- | --------------------------- |
+| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`\> | Player configuration object |
 
 ## Returns
 
@@ -40,7 +35,7 @@ Factory function that creates actor instances with optional input context
 
 ## Examples
 
-Basic player factory without catalog
+Basic player factory
 
 ```typescript
 import { setup } from "xstate";
@@ -59,54 +54,10 @@ const actor = createPlayer();
 actor.start();
 ```
 
-Player factory with catalog and parameter-aware routing
-
-```typescript
-import { setup } from "xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { definePlayer } from "@xmachines/play-xstate";
-import { z } from "zod";
-
-const catalog = defineCatalog({
-	HomePage: z.object({}),
-	ProfilePage: z.object({ userId: z.string() }),
-});
-
-const machine = setup({
-	types: {
-		context: {} as { userId: string },
-		events: {} as { type: "play.route"; to: string; params?: Record<string, string> },
-	},
-}).createMachine({
-	initial: "home",
-	context: { userId: "" },
-	states: {
-		home: {
-			route: {},
-			meta: {
-				route: "/",
-				view: { component: "HomePage" },
-			},
-		},
-		profile: {
-			route: {},
-			meta: {
-				route: "/profile/:userId",
-				view: { component: "ProfilePage", userId: (ctx) => ctx.userId },
-			},
-		},
-	},
-});
-
-const createPlayer = definePlayer({ machine, catalog });
-const actor = createPlayer({ userId: "user123" });
-actor.start();
-```
-
 Multiple actor instances from single factory
 
 ```typescript
-const createPlayer = definePlayer({ machine, catalog });
+const createPlayer = definePlayer({ machine });
 
 // Create actors for different users
 const alice = createPlayer({ userId: "alice" });
@@ -121,7 +72,7 @@ console.log(alice.state.get() !== bob.state.get());
 
 ## See
 
-- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+- [Play RFC](../../../../rfc/play.md)
 - [PlayerActor](../classes/PlayerActor.md) for the concrete actor implementation
 - [PlayerConfig](../interfaces/PlayerConfig.md) for configuration options
 - [PlayerFactory](../type-aliases/PlayerFactory.md) for factory function signature

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / deriveRoute
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / deriveRoute
 
 # Function: deriveRoute()
 
@@ -6,7 +6,7 @@
 function deriveRoute(stateMeta): string | null;
 ```
 
-Defined in: [packages/play-xstate/src/routing/derive-route.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/derive-route.ts#L90)
+Defined in: [packages/play-xstate/src/routing/derive-route.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/derive-route.ts#L91)
 
 Derive route from XState state metadata
 
@@ -94,7 +94,7 @@ console.log(route); // "/dashboard"
 
 ## See
 
-- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+- [Play RFC](../../../../rfc/play.md)
 - [buildRouteUrl](buildRouteUrl.md) for URL construction with parameter substitution
 - [isAbsoluteRoute](isAbsoluteRoute.md) for checking path absoluteness
 

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / eventMatches
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / eventMatches
 
 # Function: eventMatches()
 
@@ -6,7 +6,7 @@
 function eventMatches<TEvent>(eventType): Guard<unknown, TEvent>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/helpers.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/helpers.ts#L49)
+Defined in: [packages/play-xstate/src/guards/helpers.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/helpers.ts#L50)
 
 Check if event type matches expected type
 

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / formatPlayRouteTransitions
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / formatPlayRouteTransitions
 
 # Function: formatPlayRouteTransitions()
 
@@ -6,14 +6,20 @@
 function formatPlayRouteTransitions<T>(machineConfig): T;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L65)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:146](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L146)
 
-Formats play.route transitions from declarative route configs
+Formats play.route routing from declarative route configs.
 
-Crawls machine states looking for states with meta.route and generates
-transitions that handle `play.route` events by matching event.to to state IDs.
+Crawls machine states looking for states with `meta.route` and wires them to
+XState v6's **native routing machinery**:
 
-Inspired by XState's internal formatRouteTransitions (stateUtils.ts line 391).
+- every routed state gets a native `route: {}` config (unless it already
+  declares its own `route`), making it targetable via the built-in
+  `{ type: "xstate.route", to: "#id" }` event (Stately tooling interop and
+  statically-known graph edges), and
+- one root-level `play.route` forwarder performs the navigation for those
+  targets as ONE atomic transition: target + re-entry + a shallow
+  `params`/`query` context patch.
 
 ## Type Parameters
 
@@ -31,7 +37,7 @@ Inspired by XState's internal formatRouteTransitions (stateUtils.ts line 391).
 
 `T`
 
-The same machine config with auto-generated `play.route` handlers merged in, preserving the original type `T`.
+The machine config with native `route` configs and the `play.route` forwarder merged in, preserving the original type `T`.
 
 ## Example
 
@@ -47,8 +53,36 @@ const machineConfig = {
 const machine = createMachine(formatPlayRouteTransitions(machineConfig));
 ```
 
-This automatically generates play.route handlers at the root level that:
-
-- Match event.to against state IDs (e.g., event.to === "#home")
-- Target the appropriate state
-- Assign routeParams and queryParams from the event to context
+Because the injected `route` configs are static (object form), the machine's
+route transitions keep **statically-known targets** — `toDirectedGraph()` /
+`machineToGraph()` edges point at the actual routed states, so graph
+reachability queries work. (Function-form transition candidates would have
+dynamic targets, opaque to static analysis.)
+
+The `play.route` public API and its v5 semantics are preserved:
+
+- `send({ type: "play.route", to: "#home", params, query })` navigates and
+  patches `context.params`/`context.query` in the SAME transition — exit
+  actions of the departing state observe the OLD params, entry actions of
+  the target observe the NEW ones, `always` transitions never see a
+  half-navigated intermediate state, and entry/exit actions receive the
+  original `play.route` event;
+- user-defined `play.route` transitions (e.g. a hand-written 404 fallback)
+  are preserved AFTER the forwarder: for unknown targets the forwarder
+  returns `undefined`, so evaluation falls through to them;
+- `params`/`query` are only patched when the forwarder navigates — unknown
+  and blocked targets leave context untouched.
+
+When a state declares its OWN `route` config (which wins over the injected
+default), the forwarder re-raises the event as `xstate.route` instead of
+navigating, so the user's resolver decides — including blocking. The
+forwarder does NOT patch `params`/`query` for such targets (a blocking
+resolver would otherwise leave context describing a route that was never
+entered); the user's function-form resolver owns any context patch, and
+that navigation microstep runs under the `xstate.route` event.
+
+Native `xstate.route` events also work directly (Stately ecosystem tooling),
+but bypass the forwarder — no `params`/`query` context patch is applied, so
+stale values from earlier `play.route` events linger in context (and a
+router bridge deriving the URL from context would interpolate those stale
+params).

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / hasContext
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / hasContext
 
 # Function: hasContext()
 
@@ -6,7 +6,7 @@
 function hasContext<TContext>(path): Guard<TContext, PlayEvent>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/helpers.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/helpers.ts#L23)
+Defined in: [packages/play-xstate/src/guards/helpers.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/helpers.ts#L24)
 
 Check if context has a truthy value at path
 

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / isAbsoluteRoute
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / isAbsoluteRoute
 
 # Function: isAbsoluteRoute()
 
@@ -6,7 +6,7 @@
 function isAbsoluteRoute(path): boolean;
 ```
 
-Defined in: [packages/play-xstate/src/routing/derive-route.ts:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/derive-route.ts#L150)
+Defined in: [packages/play-xstate/src/routing/derive-route.ts:160](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/derive-route.ts#L160)
 
 Check if route path is absolute