@xmachines/docs 2.0.0-alpha.1 → 2.0.0

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

@@ -1,16 +1,14 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / GuardArray
 
-# Type Alias: GuardArray\<TContext, TEvent\>
+# ~~Type Alias: GuardArray\<TContext, TEvent\>~~
 
 ```ts
 type GuardArray<TContext, TEvent> = (Guard<TContext, TEvent> | string)[];
 ```
 
-Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/types.ts#L23)
+Defined in: [packages/play-xstate/src/guards/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/guards/types.ts#L22)
 
-Array of guard predicates or guard names
-
-Per CONTEXT.md: Array means AND - all guards must pass
+Array of guard predicates or guard names — an array means AND: all must pass.
 
 ## Type Parameters
 
@@ -18,3 +16,7 @@ Per CONTEXT.md: Array means AND - all guards must pass
 | -------------- | --------------------------------------------------- |
 | `TContext`     | `Record`\<`string`, `unknown`\>                     |
 | `TEvent`       | [`PlayEvent`](../../play/type-aliases/PlayEvent.md) |
+
+## Deprecated
+
+The guard utilities will be removed in the next major.

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

@@ -3,28 +3,24 @@
 # Type Alias: PlayerFactory\<TMachine\>
 
 ```ts
-type PlayerFactory<TMachine> = (input?, options?) => PlayerActor<TMachine>;
+type PlayerFactory<TMachine> =
+	undefined extends InputFrom<TMachine>
+		? (input?, options?) => PlayerActor<TMachine>
+		: (input, options?) => PlayerActor<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/types.ts#L57)
+Defined in: [packages/play-xstate/src/types.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/types.ts#L131)
 
-Factory function returned by definePlayer()
+Factory function returned by definePlayer() — each call creates an
+independent actor instance from the same configuration.
 
-Per CONTEXT.md: Factory supports creating multiple actor instances
+Input requiredness mirrors XState's `createActor`: a machine whose input
+cannot be `undefined` makes the factory's first argument required, so
+forgetting it is a compile error instead of an actor that starts in an
+error status with a `null` initial route.
 
 ## Type Parameters
 
 | Type Parameter                                                                                 |
 | ---------------------------------------------------------------------------------------------- |
 | `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
-
-## Parameters
-
-| Parameter  | Type                                                                                      |
-| ---------- | ----------------------------------------------------------------------------------------- |
-| `input?`   | [`InputFrom`](https://www.jsdocs.io/package/xstate#InputFrom)\<`TMachine`\>               |
-| `options?` | [`PlayerFactoryResumeOptions`](../interfaces/PlayerFactoryResumeOptions.md)\<`TMachine`\> |
-
-## Returns
-
-[`PlayerActor`](../classes/PlayerActor.md)\<`TMachine`\>

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

@@ -6,7 +6,7 @@
 type RouteMachineConfig = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L76)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L70)
 
 Minimal structural constraint for machine configs accepted by
 `formatPlayRouteTransitions`.
@@ -15,15 +15,8 @@ This is intentionally loose so the function accepts both the bare `createMachine
 config object and the stricter `setup().createMachine` config without requiring
 any type casts at the call site. The generic `T extends RouteMachineConfig`
 parameter on `formatPlayRouteTransitions` preserves the original concrete type
-of the RETURN value, so it remains directly usable by `setup().createMachine()`.
-
-Known limitation: a config authored as a STANDALONE value
-(`const config = formatPlayRouteTransitions({...})`) is typed against this
-loose shape only, so inline transition functions lose parameter inference
-(implicit-any under strict mode). Written inline inside a
-`setup().createMachine(formatPlayRouteTransitions({...}))` call, contextual
-typing still flows. [createRoutedMachine](../functions/createRoutedMachine.md) is the recommended entry
-point either way — it keeps the setup's exact `createMachine` signature.
+through the transform, so the return value remains directly usable by
+`setup().createMachine()`.
 
 ## Indexable
 
@@ -39,7 +32,7 @@ point either way — it keeps the setup's exact `createMachine` signature.
 optional context?: unknown;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L77)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L71)
 
 ---
 
@@ -49,7 +42,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:7
 optional on?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L79)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L73)
 
 ---
 
@@ -59,4 +52,4 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:7
 optional states?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L78)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L72)

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

@@ -6,4 +6,4 @@
 type RouteMetadata = string | RouteObject;
 ```
 
-Defined in: [packages/play-xstate/src/routing/types.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/types.ts#L6)
+Defined in: [packages/play-xstate/src/routing/types.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/types.ts#L6)

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

@@ -6,7 +6,7 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L14)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
 
 Minimal structural shape of a single XState state node as read by
 `formatPlayRouteTransitions` when crawling the machine config.
@@ -29,7 +29,7 @@ the index signature.
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L16)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L34)
 
 Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` target in `play.route` events.
 
@@ -41,7 +41,7 @@ Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` targ
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L18)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
 
 State metadata — `meta.route` marks the state as routable.
 
@@ -56,24 +56,12 @@ form (`{ path, title }`), matching [RouteMetadata](RouteMetadata.md).
 
 ---
 
-### route?
-
-```ts
-optional route?: unknown;
-```
-
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L26)
-
-XState v6 native route config; injected as `{}` when absent.
-
----
-
 ### states?
 
 ```ts
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L28)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L44)
 
 Nested child states, recursively crawled for additional route declarations.

package/api/@xmachines/shared/README.md

@@ -1,11 +1,11 @@
 [API](../../README.md) / @xmachines/shared
 
-<!-- generated-by: gsd-doc-writer -->
-
 # `@xmachines/shared`
 
 Shared configurations for XMachines packages — TypeScript, linting, formatting, and Vitest setup used across the monorepo.
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation

package/api/@xmachines/shared/vite-aliases/functions/xmAliases.md

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vite-aliases.ts#L221)
+Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L221)
 
 Vite resolve.alias entries for all @xmachines/* workspace packages.
 

package/api/@xmachines/shared/vite-aliases/functions/xmCacheDir.md

@@ -6,7 +6,7 @@
 function xmCacheDir(importMetaUrl, name): string;
 ```
 
-Defined in: [vite-aliases.ts:330](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vite-aliases.ts#L330)
+Defined in: [vite-aliases.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L338)
 
 Returns the shared Vite `cacheDir` for this workspace package.
 

package/api/@xmachines/shared/vite-aliases/functions/xmOptimizeDeps.md

@@ -3,10 +3,10 @@
 # Function: xmOptimizeDeps()
 
 ```ts
-function xmOptimizeDeps(extra?): DepOptimizationOptions;
+function xmOptimizeDeps(include?): DepOptimizationOptions;
 ```
 
-Defined in: [vite-aliases.ts:286](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vite-aliases.ts#L286)
+Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L291)
 
 Returns the standard Vite `optimizeDeps` config for browser test projects.
 
@@ -16,14 +16,19 @@ discovering them lazily at runtime. Without this, adding or changing dependencie
 "Re-optimizing dependencies because lockfile has changed" warnings that slow down
 and occasionally destabilise browser test runs.
 
-Pass `extra` to include framework-specific packages (e.g. `["@xmachines/json-render-vue/schema"]`).
-The base set (`@xmachines/json-render-core`) is always included.
+Every entry has to be a dependency the calling package declares. pnpm gives each
+package its own `node_modules`, so a specifier the project does not declare cannot
+be resolved from its root — and the optimizer only warns: `Failed to resolve
+dependency: <name>, present in client 'optimizeDeps.include'` on stderr, with the
+run carrying on. That reads as a failure inside a passing job, and it hides the
+same message when it is real. So nothing is pre-bundled by default: pass the
+packages this project actually depends on.
 
 ## Parameters
 
-| Parameter | Type       | Default value | Description                                                       |
-| --------- | ---------- | ------------- | ----------------------------------------------------------------- |
-| `extra`   | `string`[] | `[]`          | Additional package specifiers to pre-bundle (framework-specific). |
+| Parameter | Type       | Default value | Description                                                    |
+| --------- | ---------- | ------------- | -------------------------------------------------------------- |
+| `include` | `string`[] | `[]`          | Package specifiers to pre-bundle, each declared by the caller. |
 
 ## Returns
 

package/api/@xmachines/shared/vite-aliases/functions/xmResolve.md

@@ -6,7 +6,7 @@
 function xmResolve(importMetaUrl, extra?): ResolveOptions & object;
 ```
 
-Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vite-aliases.ts#L258)
+Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L258)
 
 Full Vite `resolve` config for @xmachines/* workspace packages.
 

package/api/@xmachines/shared/vite-aliases/functions/xmSvelteRunes.md

@@ -6,7 +6,7 @@
 function xmSvelteRunes(): object;
 ```
 
-Defined in: [vite-aliases.ts:309](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vite-aliases.ts#L309)
+Defined in: [vite-aliases.ts:317](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L317)
 
 Svelte plugin options that enforce runes mode for workspace sources only.
 
@@ -24,10 +24,15 @@ import { xmSvelteRunes } from "@xmachines/shared/vite-aliases";
 
 export default defineConfig({ plugins: [svelte(xmSvelteRunes())] });
 
+`packages/play-svelte/svelte.config.js` states the same policy a second
+time, because that file is published and this package is not — see
+`tests/svelte-runes-policy.test.ts`, which holds the two together. Change
+one and change the other.
+
 ## Returns
 
 `object`
 
-| Name                      | Type                                                    | Defined in                                                                                                                          |
-| ------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:310](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vite-aliases.ts#L310) |
+| Name                      | Type                                                    | Defined in                                                                                                                  |
+| ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L318) |

package/api/@xmachines/shared/vitest/functions/defineXmBrowserConfig.md

@@ -6,7 +6,7 @@
 function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
 ```
 
-Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vitest.ts#L167)
+Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vitest.ts#L167)
 
 Create a Vitest browser-mode config with XMachines workspace defaults.
 

package/api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
 
-Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vitest.ts#L64)
+Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vitest.ts#L64)
 
 Create a Vitest config with XMachines workspace defaults.
 

package/api/@xmachines/shared/vitest/interfaces/XmBrowserConfigOptions.md

@@ -2,15 +2,15 @@
 
 # Interface: XmBrowserConfigOptions
 
-Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vitest.ts#L117)
+Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vitest.ts#L117)
 
 Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
 Vitest config overrides.
 
 ## Properties
 
-| Property                                           | Type                                     | Description                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                              |
-| -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vitest.ts#L125) |
-| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vitest.ts#L132) |
-| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/shared/config/vitest.ts#L138) |
+| Property                                           | Type                                     | Description                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                      |
+| -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vitest.ts#L125) |
+| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vitest.ts#L132) |
+| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vitest.ts#L138) |

package/contributing/architecture.md

@@ -1,12 +1,10 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Architecture
 
 XMachines Play implements the **Universal Player Architecture** — a layered, actor-authority design where XState machines are the single source of truth for routing, navigation, and view selection. Infrastructure (routers, renderers) is strictly passive: it observes actor signals and reflects them, never enforcing guards or making decisions.
 
 ## System Overview
 
-XMachines JS is the JavaScript/TypeScript reference implementation of the **Universal Player Architecture** ([Play RFC](../rfc/play.md)). It is a monorepo of modular packages that strictly separates **business logic (the Actor)** from **infrastructure (router adapters and view renderers)**. An XState v6 state machine is the single source of truth; it owns all state, guards, and route validity. Infrastructure is passive: it observes TC39 Signals emitted by the Actor and proposes state changes via typed events. The Actor's guards make every navigation and transition decision. Communication across the boundary is exclusively through TC39 Signals — never subscriptions, callbacks, or direct state mutation. Five architectural invariants (documented in the [Play RFC](../rfc/play.md)) enforce this contract across the entire package graph.
+XMachines JS is the JavaScript/TypeScript reference implementation of the **Universal Player Architecture** ([Play RFC](../rfc/play.md)). It is a monorepo of modular packages that strictly separates **business logic (the Actor)** from **infrastructure (router adapters and view renderers)**. An XState v5 state machine is the single source of truth; it owns all state, guards, and route validity. Infrastructure is passive: it observes TC39 Signals emitted by the Actor and proposes state changes via typed events. The Actor's guards make every navigation and transition decision. Communication across the boundary is exclusively through TC39 Signals — never subscriptions, callbacks, or direct state mutation. Five architectural invariants (documented in the [Play RFC](../rfc/play.md)) enforce this contract across the entire package graph.
 
 ## Architectural Invariants
 
@@ -76,7 +74,7 @@ graph TD
 | [`@xmachines/play`](../api/@xmachines/play/README.md)                                             | Core protocol types and error base class                | `packages/play/src/index.ts`                                        |
 | [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md)                             | TC39 Signal polyfill isolation wrapper                  | `packages/play-signals/src/index.ts`                                |
 | [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `AbstractActor` base class + capability interfaces      | `packages/play-actor/src/abstract-actor.ts`                         |
-| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | XState v6 adapter: `definePlayer`, `PlayerActor`        | `packages/play-xstate/src/player-actor.ts`                          |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | XState v5 adapter: `definePlayer`, `PlayerActor`        | `packages/play-xstate/src/player-actor.ts`                          |
 | [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | Route extraction, `RouteMap`, `RouterBridgeBase`        | `packages/play-router/src/router-bridge-base.ts`                    |
 | [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)                                 | React renderer: `ActorProvider`, `PlayRenderer`         | `packages/play-react/src/ActorProvider.tsx`                         |
 | [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)                                     | Vue 3 renderer: `ActorProvider.vue`, `PlayRenderer.vue` | `packages/play-vue/src/ActorProvider.vue`                           |
@@ -101,8 +99,8 @@ graph TD
 ```mermaid
 flowchart TD
     A["XState machine transition"]
-    B["PlayerActor xstateActor.subscribe(snapshot)"]
-    C["StateSignalManager.scheduleUpdate(snapshot)\nactor.state Signal.State updated — synchronous"]
+    B["PlayerActor observes its own transitions"]
+    C["actor.state Signal.State updated — synchronous, no batching"]
     D["actor.currentRoute Signal.Computed recomputes\nderives URL from meta.route + context.params"]
     E["validateAndCacheView(snapshot)\nactor.currentView Signal.State updated"]
     F["Framework signal watcher fires\nmicrotask"]
@@ -169,11 +167,11 @@ flowchart TD
 ```mermaid
 flowchart TD
     A["XState snapshot.getMeta()"]
-    B["resolveViewMeta(meta)\nfinds first meta.view with root + elements"]
-    C["Extract context.params\nURL path params patched into context by formatPlayRouteTransitions"]
-    D["Extract contextProps allowlist\nexplicit opt-in from PlaySpec.contextProps"]
-    E["mergeRouteParamsIntoProps()\npriority: spec prop > URL param > contextProps value"]
-    F["Enriched PlaySpec set on currentView signal"]
+    B["resolveViewMeta(meta)\nfinds deepest meta.view with root + elements\n(its record key becomes viewKey)"]
+    C["snapshot.context\nprojected wholesale as the /context slice"]
+    D["composePlayState(spec.state, slice)\nstate: { ...authored, context: slice }"]
+    E["reuseComposedState (in validateAndCacheView)\ncarry previous state reference when the slice is value-unchanged"]
+    F["Derived PlaySpec (with viewKey) set on currentView signal"]
 
     A --> B --> C --> D --> E --> F
 ```
@@ -225,15 +223,15 @@ Optional capability interface. Exposes `currentView: Signal.State<PlaySpec | nul
 
 ### [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)
 
-Extends `@xmachines/json-render-core` `Spec` with `readonly contextProps?: readonly string[]` — an explicit allowlist of machine context fields that `deriveCurrentView` merges into element props. Only fields named here are ever exposed to components. `typedSpec<TContext>()` provides compile-time validation of `contextProps` entries against the machine's context type.
+Extends `@xmachines/json-render-core` `Spec`. `deriveCurrentView` projects the machine's whole context into the derived spec's `state` under the read-only `/context` subtree, and stamps a `viewKey` from the selected meta entry so providers can reseed vs refresh their store. Specs read context through the ordinary `{ $state: "/context/…" }` grammar; element props are never enriched. `typedSpec()` type-checks the spec literal at the definition site (XState's `meta` is untyped).
 
 ### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
 
-Concrete XState v6 actor implementing the full signal protocol. Extends [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md); implements both [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md). Wraps an internal `xstate.Actor` and bridges its subscription to TC39 Signals via `StateSignalManager`. Exposes: `state`, `currentRoute`, `currentView`, `initialRoute`, `send()`, `start()`, `stop()`, `can()`, `dispose()`.
+Concrete XState v5 actor implementing the full signal protocol. Extends [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) — and so XState's own `Actor`, receiving the machine in its constructor, so an instance IS the actor rather than a wrapper around one; implements both [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md). Bridges its own subscription to TC39 Signals. Exposes: `state`, `currentRoute`, `currentView`, `initialRoute`, `send()`, `start()`, `stop()`, `can()`, `dispose()`.
 
 ### [`definePlayer(config)`](../api/@xmachines/play-xstate/functions/definePlayer.md) → [`PlayerFactory`](../api/@xmachines/play-xstate/type-aliases/PlayerFactory.md)
 
-Factory creator. Pre-computes `initialRoute` once from the machine's initial state (zero extra actor instantiation per factory call). Returns `(input?, restore?) => PlayerActor<TMachine>`.
+Factory creator. Each call constructs one `PlayerActor`, which is itself the XState actor and derives its own `initialRoute` from its pre-start snapshot. Restoring a snapshot is the exception: the default initial route can only come from XState's pure `initialTransition` helper, whose inert actor scope constructs a throwaway actor and evaluates the initial transition twice. Returns `(input?, restore?) => PlayerActor<TMachine>`.
 
 ```typescript
 import { definePlayer } from "@xmachines/play-xstate";
@@ -285,7 +283,7 @@ Subscribe to a single TC39 signal with microtask batching and memory-safe cleanu
 
 ### [`formatPlayRouteTransitions(machineConfig)`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md)
 
-Crawls machine state configs looking for states with `meta.route` and wires them to XState v6's native routing: each routed state receives a static `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 one atomic transition — patching `event.params` and `event.query` into context — while re-raising `xstate.route` only for states that declare their own `route` config (unknown targets fall through to user-defined fallbacks). Returns the same config type `T` — directly usable by `setup().createMachine()`. `createRoutedMachine(setup)` wraps this with the setup's own `createMachine` signature so config typing stays fully inferred.
+Crawls machine state configs looking for states with `meta.route` and auto-generates `play.route` transition handlers at the root machine level. Each generated transition targets the matching state, guards on `event.to === "#stateId"`, and assigns `event.params` and `event.query` to context. Returns the same config type `T` — directly usable by `setup().createMachine()`.
 
 ## View Renderer Pattern
 
@@ -348,13 +346,13 @@ packages/
 │   └── src/                    # Re-exports signal-polyfill; watchSignal utility
 ├── play-actor/                 # Layer 1: AbstractActor base + Routable, Viewable, PlaySpec interfaces
 │
-├── play-xstate/                # Layer 2: Concrete XState v6 actor: definePlayer, PlayerActor
+├── play-xstate/                # Layer 2: Concrete XState v5 actor: definePlayer, PlayerActor
 │   └── src/
 │       ├── player-actor.ts              # PlayerActor — concrete actor
 │       ├── define-player.ts             # definePlayer factory
 │       ├── guards/                      # composeGuards, composeGuardsOr, negateGuard, hasContext...
 │       ├── routing/                     # deriveRoute, buildRouteUrl, formatPlayRouteTransitions
-│       └── signals/                     # StateSignalManager (XState → TC39 Signal bridge)
+│       └── view/                        # deriveCurrentView (meta.view → PlaySpec)
 │
 ├── play-router/                # Layer 2: Route extraction, bidirectional mapping, bridge base
 │   └── src/
@@ -467,11 +465,10 @@ flowchart TD
     PE --> IME["InvalidMachineError\nPLAY_XSTATE_INVALID_MACHINE"]
     PE --> MRP["MissingRouteParamError\nPLAY_XSTATE_ROUTE_PARAM_MISSING"]
     PE --> MSI["MissingStateIdError\nPLAY_XSTATE_MISSING_STATE_ID"]
-    PE --> MQC["MissingQueryContextError\nPLAY_XSTATE_MISSING_QUERY_CONTEXT"]
+    PE --> MQC["MissingQueryContextError\nPLAY_XSTATE_MISSING_QUERY_CONTEXT\n(deprecated — never thrown)"]
     PE --> IRE["InvalidRouteMetadataError\nPLAY_XSTATE_INVALID_ROUTE_METADATA"]
+    PE --> ATN["ActorThrewNonErrorError\nPLAY_XSTATE_NON_ERROR_THROWN"]
     PE --> EGA["EmptyGuardArrayError\nPLAY_XSTATE_EMPTY_GUARD_ARRAY"]
-    PE --> UGN["UnresolvableGuardNameError\nPLAY_XSTATE_UNRESOLVABLE_GUARD_NAME"]
-    PE --> IGE["InvalidGuardEntryError\nPLAY_XSTATE_INVALID_GUARD_ENTRY"]
 ```
 
 Package-specific errors are exported from `./errors` subpath imports:
@@ -484,14 +481,16 @@ import { InvalidEventError } from "@xmachines/play-xstate/errors";
 
 **Error behavior by case:**
 
-| Error                        | Package       | Behavior                                                                                  |
-| ---------------------------- | ------------- | ----------------------------------------------------------------------------------------- |
-| `MissingRouteParamError`     | `play-xstate` | Transient — `currentRoute` returns `null`; does not throw                                 |
-| `MissingQueryContextError`   | `play-xstate` | Structural programmer error — always re-throws                                            |
-| `RouterSyncError`            | `play-router` | Wraps router sync failures                                                                |
-| `DuplicateBridgeError`       | `play-router` | Two bridges registered for the same actor                                                 |
-| `URLPatternUnavailableError` | `play-router` | URLPattern API missing — load `urlpattern-polyfill`                                       |
-| View errors                  | `play-xstate` | Caught in `validateAndCacheView()`; forwarded to `onError` hook; last valid view retained |
+| Error                        | Package       | Behavior                                                                                   |
+| ---------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
+| `MissingRouteParamError`     | `play-xstate` | Transient — `currentRoute` returns `null`; does not throw                                  |
+| `MissingQueryContextError`   | `play-xstate` | Deprecated — never thrown; exported only so existing `instanceof` handlers keep compiling  |
+| `ActorThrewNonErrorError`    | `play-xstate` | Constructed for `onError` when the machine throws a non-`Error`; original value on `cause` |
+| `EmptyGuardArrayError`       | `play-xstate` | Structural programmer error — `composeGuards`/`composeGuardsOr` called with `[]`           |
+| `RouterSyncError`            | `play-router` | Wraps router sync failures                                                                 |
+| `DuplicateBridgeError`       | `play-router` | Two bridges registered for the same actor                                                  |
+| `URLPatternUnavailableError` | `play-router` | URLPattern API missing — load `urlpattern-polyfill`                                        |
+| View errors                  | `play-xstate` | Caught in `validateAndCacheView()`; forwarded to `onError` hook; last valid view retained  |
 
 ## Application Bootstrap (React example)
 

package/contributing/configuration.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Configuration
 
 This document describes every configuration file, environment variable, and per-package override used by the `xmachines-js` monorepo.
@@ -133,7 +131,6 @@ The root config extends the shared base (`@xmachines/shared/oxlint`) and adds wo
 export default defineConfig({
 	extends: [sharedConfig],
 	ignorePatterns: [
-		".planning",
 		".opencode",
 		"node_modules",
 		"dist",
@@ -185,7 +182,6 @@ export default defineConfig({
 	...sharedConfig,
 	ignorePatterns: [
 		...(sharedConfig.ignorePatterns ?? []),
-		".planning",
 		".opencode",
 		".agents",
 		".githuman",
@@ -295,7 +291,7 @@ Provides two helpers used in all `vitest.config.ts` and `vite.config.ts` files:
 - **`xmAliases(import.meta.url)`** — returns a `Record<string, string>` mapping every `@xmachines/*` package to its TypeScript source entry. Enables tests and dev servers to run without a prior `pnpm run build`.
 - **`xmResolve(import.meta.url)`** — returns a full Vite `resolve` config with `xmAliases` plus `preserveSymlinks: true` and `conditions: ["source"]`.
 - **`xmCacheDir(import.meta.url, name)`** — returns a shared Vite cache path under `node_modules/.vite/<name>` to prevent redundant dep optimizer runs across projects.
-- **`xmOptimizeDeps(extra?)`** — returns a standard `optimizeDeps.include` list; pass framework-specific extras to pre-bundle them at startup.
+- **`xmOptimizeDeps(include?)`** — returns an `optimizeDeps.include` list holding exactly the specifiers passed in. Nothing is pre-bundled by default, and every entry has to be a package the calling project declares: pnpm gives each package its own `node_modules`, so Vite cannot resolve an undeclared specifier — it warns on stderr and carries on, which reads as a failure in a passing job.
 
 ### Release — `release.config.mjs`
 
@@ -306,11 +302,15 @@ Defines the release branches and plugin chain used by the GitLab CI semantic-rel
 
 **Release branches:**
 
-| Branch   | Channel   | Pre-release |
-| -------- | --------- | ----------- |
-| `main`   | (default) | No          |
-| `pre/rc` | `pre/rc`  | `rc`        |
-| `beta`   | `beta`    | `true`      |
+| Branch  | Channel   | Pre-release |
+| ------- | --------- | ----------- |
+| `main`  | (default) | No          |
+| `rc`    | `rc`      | `rc`        |
+| `beta`  | `beta`    | `true`      |
+| `alpha` | `alpha`   | `alpha`     |
+| `pre`   | `pre`     | `pre`       |
+
+Only `main` is a protected branch today. That works because `GITLAB_TOKEN` — which the release needs, since `CI_JOB_TOKEN` can push neither the release commit nor the tag — is an _unprotected_ group variable and so reaches every one of these refs. If it is ever made protected, each of these branches has to be protected too, or the release fails in verify-conditions with `EGITNOPERMISSION` rather than at the registry.
 
 **Tag format:** `v${version}`