@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/types.ts#L135)
 
-Factory function returned by definePlayer()
+The factory function that definePlayer() returns. Each call makes an independent
+actor instance from the same configuration.
 
-Per CONTEXT.md: Factory supports creating multiple actor instances
+The `input` argument follows the rule of `createActor` in XState. If the input of
+a machine cannot be `undefined`, the first argument of the factory is necessary.
+An absent input is then a compile error, and not 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,24 +6,17 @@
 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:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L73)
 
-Minimal structural constraint for machine configs accepted by
-`formatPlayRouteTransitions`.
+The minimal structural constraint of a machine config that
+`formatPlayRouteTransitions` accepts.
 
-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.
+The constraint is loose on purpose. The function therefore accepts the bare config
+object of `createMachine` and also the stricter config of
+`setup().createMachine`, and the call site needs no type cast. The generic
+parameter `T extends RouteMachineConfig` of `formatPlayRouteTransitions` keeps the
+original concrete type through the transform. Therefore
+`setup().createMachine()` accepts the return value directly.
 
 ## 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:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L74)
 
 ---
 
@@ -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:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L76)
 
 ---
 
@@ -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:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L75)

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.1.0/packages/play-xstate/src/routing/types.ts#L6)

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

@@ -6,14 +6,14 @@
 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.1.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.
+The minimal structural shape of one XState state node, as
+`formatPlayRouteTransitions` reads it during its walk over the machine config.
 
-Only the fields the function actually inspects are typed here; all other
-state-node fields (e.g. `on`, `entry`, `after`) pass through unmodified via
-the index signature.
+This type holds only the fields that the function reads. Every other field of a
+state node, such as `on`, `entry`, and `after`, passes through the index
+signature without a change.
 
 ## Indexable
 
@@ -29,9 +29,9 @@ 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:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
 
-Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` target in `play.route` events.
+The optional explicit state ID, for example `"home"` or `"settings"`. It is the `#id` target of a `play.route` event.
 
 ---
 
@@ -41,9 +41,9 @@ 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:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L38)
 
-State metadata — `meta.route` marks the state as routable.
+The state metadata. A `meta.route` field gives the state a route.
 
 #### route?
 
@@ -51,20 +51,9 @@ State metadata — `meta.route` marks the state as routable.
 optional route?: RouteMetadata;
 ```
 
-URL path template — string form (e.g. `"/profile/:username"`) or object
-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.
+The template of the URL path: the string form, for example
+`"/profile/:username"`, or the object form (`{ path, title }`). Both match
+[RouteMetadata](RouteMetadata.md).
 
 ---
 
@@ -74,6 +63,6 @@ XState v6 native route config; injected as `{}` when absent.
 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:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L47)
 
-Nested child states, recursively crawled for additional route declarations.
+The nested child states. The function walks them for each further route declaration.

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

@@ -1,18 +1,16 @@
 [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.
+Shared configurations for the XMachines packages: TypeScript, linting, formatting, and the Vitest setup that the monorepo uses.
 
-Part of the [xmachines-js monorepo](../../README.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Installation
 
-This package is an internal monorepo dependency. It is **not intended for installation by external consumers**.
+This package is an internal dependency of the monorepo. **An external user must not install it.**
 
-Within the monorepo it is referenced by package name:
+In the monorepo, each package refers to it by name:
 
 ```json
 {
@@ -76,7 +74,7 @@ The shared config enables the `typescript`, `unicorn`, and `import` plugins with
 - `correctness` rules as errors
 - `suspicious` and `perf` rules as warnings
 - `import/no-cycle` and `typescript/no-explicit-any` as errors
-- `typescript/no-unused-vars` as an error (ignoring `_`-prefixed names)
+- `typescript/no-unused-vars` as an error (it ignores a name with a `_` prefix)
 
 ### Formatting (`oxfmt`)
 
@@ -87,11 +85,11 @@ import sharedConfig from "@xmachines/shared/oxfmt";
 export default sharedConfig;
 ```
 
-Key formatting rules: 4-space tab width using actual tabs, 100-character print width, double quotes, trailing commas, final newline. JSON/YAML files use 2-space indentation.
+The main formatting rules are a tab width of 4 with real tab characters, a print width of 100 characters, double quotes, a trailing comma, and a final newline. A JSON file and a YAML file use an indentation of 2 spaces.
 
 ### Vitest Configuration
 
-Use `defineXmVitestConfig` for per-package Vitest configs. It automatically injects shared setup files and wires `@xmachines/*` source aliases:
+Use `defineXmVitestConfig` for the Vitest config of a package. It adds the shared setup files and the `@xmachines/*` source aliases:
 
 ```typescript
 // vitest.config.ts
@@ -107,7 +105,7 @@ export default defineXmVitestConfig(import.meta.url, {
 **What `defineXmVitestConfig` applies automatically:**
 
 - `resolve.alias` from `xmAliases(import.meta.url)` — resolves `@xmachines/*` to TypeScript source
-- `config/vitest.node.setup.ts` — Node.js runtime guard (skipped in browser mode)
+- `config/vitest.node.setup.ts` — the Node.js runtime guard (the browser mode skips it)
 - `config/vitest.setup.ts` — `@testing-library/jest-dom` matcher extensions
 
 For packages that test URL routing, add the URLPattern polyfill setup:
@@ -123,7 +121,7 @@ export default defineXmVitestConfig(import.meta.url, {
 
 ### Vite Aliases
 
-For Vite-based demo or app packages, resolve all `@xmachines/*` packages to TypeScript source (no prior build required):
+In a Vite demo package or app package, resolve every `@xmachines/*` package to its TypeScript source. A build first is not necessary:
 
 ```typescript
 // vite.config.ts
@@ -135,9 +133,9 @@ export default defineConfig({
 });
 ```
 
-Use `xmAliases` for alias-only setup, or `xmResolve` for the full resolve config including `conditions: ["source"]` and `preserveSymlinks: true`.
+Use `xmAliases` for the aliases alone. Use `xmResolve` for a resolve config that adds `preserveSymlinks` (`false` by default) and your other resolve options to the aliases. For example, give `conditions` yourself if you need it.
 
-For browser test projects, use `xmOptimizeDeps` to pre-bundle packages and avoid mid-run optimizer restarts, and `xmCacheDir` to share a single Vite dep cache across the workspace:
+In a browser test project, use `xmOptimizeDeps` to bundle the packages in advance. The optimizer then does not restart during a run. Use `xmCacheDir` to share one Vite dependency cache across the workspace:
 
 ```typescript
 import { xmResolve, xmOptimizeDeps, xmCacheDir } from "@xmachines/shared/vite-aliases";
@@ -157,7 +155,7 @@ The base `config/tsconfig.json` configures:
 - **Strict mode:** full strict, `noUnusedLocals`, `noUnusedParameters`, `exactOptionalPropertyTypes`, `noImplicitReturns`, `noImplicitOverride`
 - **Emit:** `declaration`, `declarationMap`, `sourceMap` enabled
 - **Interop:** `verbatimModuleSyntax`, `isolatedModules`
-- **Custom condition:** `"source"` — used by `xmAliases` to resolve packages to TypeScript source in dev/test
+- **Custom condition:** `"source"` — `xmAliases` uses it to resolve a package to its TypeScript source in development and in a test
 
 ## Testing
 

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.1.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.1.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.1.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.1.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.1.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.1.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.1.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.1.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.1.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.1.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.1.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.1.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)