@xmachines/docs 2.1.1 → 3.0.0

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:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L73)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L73)
 
 The minimal structural constraint of a machine config that
 `formatPlayRouteTransitions` accepts.
@@ -32,7 +32,7 @@ original concrete type through the transform. Therefore
 optional context?: unknown;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L74)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L74)
 
 ---
 
@@ -42,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:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L76)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L76)
 
 ---
 
@@ -52,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:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L75)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.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.1.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/v3.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:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
 
 The minimal structural shape of one XState state node, as
 `formatPlayRouteTransitions` reads it during its walk over the machine config.
@@ -29,7 +29,7 @@ signature without a change.
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
 
 The optional explicit state ID, for example `"home"` or `"settings"`. It is the `#id` target of a `play.route` event.
 
@@ -41,7 +41,7 @@ The optional explicit state ID, for example `"home"` or `"settings"`. It is the
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L38)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L38)
 
 The state metadata. A `meta.route` field gives the state a route.
 
@@ -63,6 +63,6 @@ The template of the URL path: the string form, for example
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L47)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L47)
 
 The nested child states. The function walks them for each further route declaration.

package/api/@xmachines/play-xstate/variables/DISPOSE.md

@@ -0,0 +1,34 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / DISPOSE
+
+# Variable: DISPOSE
+
+```ts
+const DISPOSE: DisposeKey;
+```
+
+Defined in: [packages/play/src/disposable.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/disposable.ts#L94)
+
+The key that a release is stored under.
+
+`Symbol.dispose` where the runtime has it, and `Symbol.for("Symbol.dispose")` where it
+does not. This is not a convenience — it is the difference between a `using` that
+releases and one that raises.
+
+A bundler that downlevels `using` for a target below Chrome 134 emits a helper that
+reads `object[Symbol.dispose || Symbol.for("Symbol.dispose")]`. A release stored under
+a bare `[Symbol.dispose]` lands on the string key `"undefined"` in that runtime,
+because the well-known symbol is absent and the computed key takes the value
+`undefined`. The helper then looks up the registered symbol, finds nothing, and throws
+`TypeError: Object is not disposable`. Storing under the same fallback closes the gap.
+
+The type assertion states what the fallback IS. `Symbol.for` returns a plain `symbol`,
+TypeScript declares `Symbol.dispose` as a `unique symbol`, and no expression produces
+a `unique symbol` other than the declaration itself.
+
+This binding resolves ONE time, when the module evaluates. [asCleanup](../../play/functions/asCleanup.md) therefore
+reads `Symbol.dispose` again at each call and stores the release under both keys, so a
+polyfill that installs the well-known symbol after this module evaluates still finds
+the release. A class or an object literal that writes `[DISPOSE]()` has no such second
+chance: it carries the key that existed when it was defined. Install an Explicit
+Resource Management polyfill before the first import of `@xmachines/play`, which is the
+ordinary contract of a polyfill.

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

@@ -31,7 +31,7 @@ In the monorepo, each package refers to it by name:
 | `@xmachines/shared/vite-aliases`            | `config/vite-aliases.ts`            | Vite resolve aliases for all `@xmachines/*` workspace packages                                  |
 | `@xmachines/shared/vitest`                  | `config/vitest.ts`                  | `defineXmVitestConfig` helper for per-package Vitest configs                                    |
 | `@xmachines/shared/vitest-setup`            | `config/vitest.setup.ts`            | Shared Vitest setup — extends matchers with `@testing-library/jest-dom`                         |
-| `@xmachines/shared/vitest-node-setup`       | `config/vitest.node.setup.ts`       | Node.js runtime guard — asserts `Node.js >= 22`                                                 |
+| `@xmachines/shared/vitest-node-setup`       | `config/vitest.node.setup.ts`       | Node.js runtime guard — asserts `Node.js >= 24`                                                 |
 | `@xmachines/shared/vitest-urlpattern-setup` | `config/vitest.urlpattern.setup.ts` | Optional URLPattern polyfill setup for route-matching tests                                     |
 
 ## Usage

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.1.1/packages/shared/config/vite-aliases.ts#L221)
+Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.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:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vite-aliases.ts#L338)
+Defined in: [vite-aliases.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.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

@@ -6,7 +6,7 @@
 function xmOptimizeDeps(include?): DepOptimizationOptions;
 ```
 
-Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vite-aliases.ts#L291)
+Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vite-aliases.ts#L291)
 
 Returns the standard Vite `optimizeDeps` config for browser test projects.
 

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.1.1/packages/shared/config/vite-aliases.ts#L258)
+Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.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:317](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vite-aliases.ts#L317)
+Defined in: [vite-aliases.ts:317](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vite-aliases.ts#L317)
 
 Svelte plugin options that enforce runes mode for workspace sources only.
 
@@ -35,4 +35,4 @@ one and change the other.
 
 | Name                      | Type                                                    | Defined in                                                                                                                  |
 | ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vite-aliases.ts#L318) |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.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.1.1/packages/shared/config/vitest.ts#L167)
+Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.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.1.1/packages/shared/config/vitest.ts#L64)
+Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.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,7 +2,7 @@
 
 # Interface: XmBrowserConfigOptions
 
-Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vitest.ts#L117)
+Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/shared/config/vitest.ts#L117)
 
 Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
 Vitest config overrides.
@@ -11,6 +11,6 @@ Vitest config overrides.
 
 | 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.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.1.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.1.1/packages/shared/config/vitest.ts#L138) |
+| <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/v3.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/v3.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/v3.0.0/packages/shared/config/vitest.ts#L138) |

package/contributing/architecture.md

@@ -586,7 +586,11 @@ Custom `watchRouterChanges()` implementations that bypass `syncActorFromRouter()
 
 **SSR / test injection:** [`WindowLike`](../api/@xmachines/play-router/interfaces/WindowLike.md) and [`LocationLike`](../api/@xmachines/play-router/interfaces/LocationLike.md) structural interfaces in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) allow injecting mock objects in router adapters, enabling testing without a real browser environment.
 
-**Logging:** No structured logging framework. [`PlayerOptions`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md) exposes lifecycle hooks — `onStart`, `onStop`, `onTransition`, `onStateChange`, `onError` — as observability extension points. No `console.*` calls in library source code.
+**Logging:** No structured logging framework. [`PlayerOptions`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md) exposes lifecycle hooks — `onStart`, `onStop`, `onTransition`, `onStateChange`, `onError` — as observability extension points. A renderer writes to `console.error` in ONE case: it contained a failure, and no handler of the host receives that failure. Such a failure is the one result that nobody can debug. Give `onError` to send the failure of a view to your own observability tool instead.
+
+Five paths reach that case. The host gives no `onError` prop. The handler of the host throws, or the producer of the `fallback` throws, or a release of the caller throws — each of those reports the failure of the HOST, which no handler of the host receives. `ActorProvider` of play-vue stops a second report of one error, and `onError` stays silent there on purpose, because the four other renderers see such an error never.
+
+Three other places write to `console.warn`, and each one reports a configuration that the library cannot refuse: `warnOnce` of `@xmachines/play-actor` names a `/context` projection that it cannot derive, one time for each spec; `@xmachines/play-xstate` names the `meta.view.contextProps` field that 1.x removed, one time for each spec; and `@xmachines/play-router` names a `basePath` that a bridge with no mount ignores. A warning is the answer where a throw would stop an application for a fault that it can still run with. No other library source calls `console.*`.
 
 **Authentication:** Not in scope. Enforced via XState guards on `play.route` transitions. The guard evaluates machine `context` (e.g., `isLoggedIn`) before permitting navigation. No library-level auth primitives — the machine defines all access control.
 

package/contributing/configuration.md

@@ -47,21 +47,22 @@ SEMREL_SKIP_STEPS="@semantic-release/git|@semantic-release/gitlab"
 
 **Location:** `/tsconfig.json`
 
-The root TypeScript config is a **build coordinator only** — it compiles nothing itself. It lists every package and example via `references` so that `tsc --build` can determine the correct build order automatically.
+The root TypeScript config is a **build coordinator only** — it compiles nothing itself. It lists every package and example via `references`, and that array is the whole build order: TypeScript does not inherit `references` through `extends`, so a package declares none of its own. `tests/tsconfig-reference-graph.test.ts` fails when the array misses a project or lists a package before something it imports.
 
 ```json
 {
 	"files": [],
 	"references": [
 		// Layer 0 — no internal deps
-		{ "path": "./packages/play-signals" },
-		{ "path": "./packages/play" },
 		{ "path": "./packages/docs" },
+		{ "path": "./packages/play" },
+		{ "path": "./packages/shared" },
 		// Layer 1 — depends on Layer 0
+		{ "path": "./packages/play-signals" },
+		// Layer 2
 		{ "path": "./packages/play-actor" },
-		// Layer 2 — depends on Layer 0 + 1
-		{ "path": "./packages/play-router" },
-		{ "path": "./packages/play-xstate" }
+		// Layer 3
+		{ "path": "./packages/play-router" }
 		// ...etc.
 	]
 }
@@ -80,7 +81,7 @@ All packages extend this base. Key compiler settings:
 
 | Setting                      | Value        | Notes                                                    |
 | ---------------------------- | ------------ | -------------------------------------------------------- |
-| `target`                     | `ESNext`     | Latest ECMAScript output                                 |
+| `target`                     | `ESNext`     | Latest ECMAScript output. See the two passes below       |
 | `module`                     | `NodeNext`   | ESM with `.js` extension imports required                |
 | `moduleResolution`           | `NodeNext`   | Matches `module` setting                                 |
 | `customConditions`           | `["source"]` | Resolves `@xmachines/*` to TypeScript source in dev/test |
@@ -98,6 +99,31 @@ All packages extend this base. Key compiler settings:
 | `isolatedModules`            | `true`       |                                                          |
 | `removeComments`             | `false`      | Preserves JSDoc in output                                |
 
+**Two passes emit, and `emitDeclarationOnly` decides which one ships.** `build` is
+`vite build && tsc --build`, so tsc runs last.
+
+- **Fourteen publishable packages** let tsc emit JavaScript. tsc overwrites the Vite pass,
+  and `compilerOptions.target` above is what governs the published `dist/*.js`.
+- **Five** — play-vue, play-svelte, play-solid, play-solid-router,
+  play-tanstack-solid-router — set `emitDeclarationOnly`, so tsc emits only `.d.ts` and the
+  Vite pass is the published JavaScript. `build.target` governs theirs.
+
+Vite inherits no target from the tsconfig. It reads `compilerOptions.target` for one
+purpose: to pick the `useDefineForClassFields` default that it gives the transform. The
+syntax level of the Vite pass comes from `build.target`, which
+`packages/shared/config/vite.ts` sets — `"esnext"` for a publishable package, and an
+explicit browser list for a demo app.
+
+Leave both stated, and keep both at ESNext for a library. A package that inherits the Vite
+default builds against a browser baseline, which is a second and lower ceiling than the one
+this table declares — and it is the ceiling that ships for those five.
+
+**A demo states an explicit browser list, and not `baseline-widely-available`.** A target
+controls syntax and adds no method. `baseline-widely-available` of Vite 8 names
+`firefox114`, the demos bundle `play-router`, and `play-router` calls `toSorted()`, which
+shipped in Firefox 115. The list in `vite.ts` therefore raises that one entry, so the
+declared floor is the floor the bundle runs on.
+
 **Per-package `tsconfig.json` pattern:**
 
 ```json
@@ -107,16 +133,17 @@ All packages extend this base. Key compiler settings:
 		"composite": true,
 		"rootDir": "./src",
 		"outDir": "./dist"
-	},
-	"references": [{ "path": "../dependency-package" }]
+	}
 }
 ```
 
+A package declares no `references`. Its dependencies live in `package.json`, and the root array orders the build.
+
 **Test tsconfig (`@xmachines/shared/tsconfig-test`):**
 
 **Location:** `packages/shared/config/tsconfig.test.json`
 
-Test builds add `noEmit: true`, `allowImportingTsExtensions: true`, and `vitest/globals` types. Used by `pnpm run test:build` to type-check test files without emitting output.
+Test builds add `noEmit: true`, `allowImportingTsExtensions: true`, and `vitest/globals` types. Used by `pnpm run test:build` to type-check test files without emitting output. That script passes `--force`, so the check covers every project of the solution on every run.
 
 ### Linting — `oxlint.config.ts` (root)
 
@@ -154,6 +181,20 @@ export default defineConfig({
 | `typescript/no-explicit-any` | —             | `error`                              |
 | `typescript/no-unused-vars`  | —             | `error` (ignores `_` prefixed names) |
 | `unicorn/filename-case`      | —             | `off`                                |
+| `unicorn/no-array-sort`      | —             | `error`                              |
+| `no-underscore-dangle`       | —             | `off`                                |
+
+`unicorn/no-array-sort` is an error and not the warning of its category. The workspace
+targets ESNext, and Node 22 — the lowest runtime a published package supports — has
+`toSorted()`, so the method is always available. As a warning the rule kept
+the lint job green while the Code Quality report showed the degradation, and `sort()` stayed
+behind a suppression for a ceiling that had already gone.
+
+`no-underscore-dangle` is off because it contradicts `typescript/no-unused-vars`, which
+declares `^_` as the mark of a binding that exists on purpose and that nothing reads. A
+`using` declaration is the case that makes the contradiction concrete: the scope reads the
+binding through `Symbol.dispose`, the linter sees no read, and the `_` that answers one rule
+trips the other.
 
 **Per-package override pattern:**
 
@@ -344,14 +385,15 @@ The only environment-specific distinction is between **local development** (dev
 
 ## Required vs Optional Settings Summary
 
-| Config                               | Required to Work                      | Optional / Has Default        |
-| ------------------------------------ | ------------------------------------- | ----------------------------- |
-| `SEMREL_SKIP_STEPS`                  | No                                    | Default: `""` (run all steps) |
-| Root `tsconfig.json` `references`    | Yes — must list all packages          | —                             |
-| Per-package `composite: true`        | Yes — required for project references | —                             |
-| `@xmachines/shared/tsconfig` extends | Yes — all packages must extend it     | —                             |
-| `@xmachines/shared/oxlint` extends   | Yes — all packages must extend it     | —                             |
-| `@xmachines/shared/oxfmt` extends    | Yes — all packages must extend it     | —                             |
+| Config                               | Required to Work                        | Optional / Has Default        |
+| ------------------------------------ | --------------------------------------- | ----------------------------- |
+| `SEMREL_SKIP_STEPS`                  | No                                      | Default: `""` (run all steps) |
+| Root `tsconfig.json` `references`    | Yes — the whole build order             | —                             |
+| Per-package `references`             | No — TypeScript drops them on `extends` | —                             |
+| Per-package `composite: true`        | Yes — required for project references   | —                             |
+| `@xmachines/shared/tsconfig` extends | Yes — all packages must extend it       | —                             |
+| `@xmachines/shared/oxlint` extends   | Yes — all packages must extend it       | —                             |
+| `@xmachines/shared/oxfmt` extends    | Yes — all packages must extend it       | —                             |
 
 ---
 

package/contributing/development.md

@@ -20,7 +20,7 @@ This guide covers everything you need to set up a local development environment,
 
 ### Prerequisites
 
-- **Node.js** `>= 22.0.0`
+- **Node.js** `>= 24.0.0` (the suite writes `using`, which needs V8 13.4)
 - **pnpm** via corepack (`corepack enable`; version pinned by the `packageManager` field — the project uses pnpm workspaces)
 - **Git**
 
@@ -125,22 +125,22 @@ packages/<name>/
 
 All commands are run from the **repository root** unless otherwise noted.
 
-| Command                                    | Description                                                           |
-| ------------------------------------------ | --------------------------------------------------------------------- |
-| `pnpm run build`                           | TypeScript composite build — all packages in dependency order         |
-| `pnpm --filter @xmachines/<pkg> run build` | Build a single package (and its deps)                                 |
-| `pnpm run clean`                           | Remove coverage, Vite caches, and all `dist/` directories in packages |
-| `pnpm test`                                | Run all unit/integration tests once                                   |
-| `pnpm run test:watch`                      | Re-run tests on file changes (interactive)                            |
-| `pnpm run test:browser`                    | Run Playwright browser tests                                          |
-| `pnpm run test:coverage`                   | Run tests with V8 coverage reporting                                  |
-| `pnpm run test:browser:coverage`           | Run browser tests with coverage reporting                             |
-| `pnpm run test:build`                      | Type-check test files without running them (`tsconfig.test.json`)     |
-| `pnpm run lint`                            | Lint all packages with oxlint                                         |
-| `pnpm run lint:fix`                        | Auto-fix lint issues                                                  |
-| `pnpm run format`                          | Format all files with oxfmt                                           |
-| `pnpm run format:check`                    | Check formatting (CI mode — no writes)                                |
-| `pnpm run docs`                            | Build packages, generate TypeDoc API docs, then format                |
+| Command                                    | Description                                                               |
+| ------------------------------------------ | ------------------------------------------------------------------------- |
+| `pnpm run build`                           | Incremental build — all packages in dependency order (not a type-check)   |
+| `pnpm --filter @xmachines/<pkg> run build` | Build a single package (and its deps)                                     |
+| `pnpm run clean`                           | Remove coverage, Vite caches, and all `dist/` directories in packages     |
+| `pnpm test`                                | Run all unit/integration tests once                                       |
+| `pnpm run test:watch`                      | Re-run tests on file changes (interactive)                                |
+| `pnpm run test:browser`                    | Run Playwright browser tests                                              |
+| `pnpm run test:coverage`                   | Run tests with V8 coverage reporting                                      |
+| `pnpm run test:browser:coverage`           | Run browser tests with coverage reporting                                 |
+| `pnpm run test:build`                      | Complete type-check of every package and its tests (`tsconfig.test.json`) |
+| `pnpm run lint`                            | Lint all packages with oxlint                                             |
+| `pnpm run lint:fix`                        | Auto-fix lint issues                                                      |
+| `pnpm run format`                          | Format all files with oxfmt                                               |
+| `pnpm run format:check`                    | Check formatting (CI mode — no writes)                                    |
+| `pnpm run docs`                            | Build packages, generate TypeDoc API docs, then format                    |
 
 ---
 
@@ -198,52 +198,72 @@ The monorepo uses **TypeScript project references** for correct build-order mana
 
 Packages are grouped into dependency layers as defined in the root `tsconfig.json`:
 
-| Layer | Packages                                                                                                                                                                                                                                                                  | Depends on         |
-| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
-| 0     | `play-signals`, `play`, `docs`                                                                                                                                                                                                                                            | External libs only |
-| 1     | `play-actor`                                                                                                                                                                                                                                                              | Layer 0            |
-| 2     | `play-router`, `play-dom-router`, `play-sveltekit-router`, `play-xstate`, `play-react`, `play-vue`, `play-solid`, `play-svelte`, `play-dom`, `play-tanstack-react-router`, `play-vue-router`, `play-solid-router`, `play-svelte-spa-router`, `play-tanstack-solid-router` | Layers 0–1         |
-| 3     | `play-react-router`, example demo apps                                                                                                                                                                                                                                    | Layer 2            |
+| Layer | Packages                                                                         | Depends on         |
+| ----- | -------------------------------------------------------------------------------- | ------------------ |
+| 0     | `docs`, `play`, `shared`                                                         | External libs only |
+| 1     | `play-signals`                                                                   | Layer 0            |
+| 2     | `play-actor`                                                                     | Layers 0–1         |
+| 3     | `play-dom`, `play-react`, `play-router`, `play-solid`, `play-svelte`, `play-vue` | Layers 0–2         |
+| 4     | `play-tanstack-router`, `play-xstate`                                            | Layers 0–3         |
+| 5     | `play-actor/examples/shared`                                                     | Layers 0–4         |
+| 6     | renderer demo apps                                                               | Layers 0–5         |
+| 7     | the eight router adapters                                                        | Layers 0–6         |
+| 8     | router demo apps                                                                 | Layers 0–7         |
+
+The layer of an entry is its longest path to a package with no workspace dependency, and `tests/tsconfig-reference-graph.test.ts` computes it from the manifests.
 
 #### Mermaid Diagram
 
 ```mermaid
 flowchart LR
-    subgraph L0["Layer 0 — no internal deps"]
-        play-signals
+    subgraph L0["Layer 0 — no workspace deps"]
         play
+        shared
         docs
     end
 
     subgraph L1["Layer 1"]
+        play-signals
+    end
+
+    subgraph L2["Layer 2"]
         play-actor
     end
 
-    subgraph L2["Layer 2 — view renderers & router adapters"]
-        play-router
-        play-dom-router
-        play-sveltekit-router
-        play-xstate
+    subgraph L3["Layer 3 — view renderers, and the router core"]
+        play-dom
         play-react
-        play-vue
+        play-router
         play-solid
         play-svelte
-        play-dom
-        play-tanstack-react-router
-        play-vue-router
-        play-solid-router
-        play-svelte-spa-router
-        play-tanstack-solid-router
+        play-vue
+    end
+
+    subgraph L4["Layer 4"]
+        play-tanstack-router
+        play-xstate
+    end
+
+    subgraph L5["Layer 5"]
+        actorshared["play-actor/examples/shared"]
+    end
+
+    subgraph L6["Layer 6"]
+        renderdemos["renderer demo apps"]
+    end
+
+    subgraph L7["Layer 7 — the eight router adapters"]
+        adapters["play-dom-router, play-react-router, play-solid-router,
+        play-svelte-spa-router, play-sveltekit-router,
+        play-tanstack-react-router, play-tanstack-solid-router,
+        play-vue-router"]
     end
 
-    subgraph L3["Layer 3 — application layer"]
-        play-react-router
-        examples["example demo apps"]
+    subgraph L8["Layer 8"]
+        routerdemos["router demo apps"]
     end
 
-    L0 --> L1
-    L1 --> L2
-    L2 --> L3
+    L0 --> L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7 --> L8
 ```
 
 ### Adding a New Package
@@ -351,6 +371,8 @@ Active plugins: `typescript`, `unicorn`, `import`. Key rules:
 | `typescript/no-explicit-any` | error                          |
 | `import/no-cycle`            | error                          |
 | `typescript/no-unused-vars`  | error (prefix unused with `_`) |
+| `unicorn/no-array-sort`      | error (use `toSorted()`)       |
+| `no-underscore-dangle`       | off (clashes with `^_` unused) |
 | `correctness` category       | error                          |
 | `suspicious` category        | warn                           |
 
@@ -501,7 +523,7 @@ feat(play-react): add PlayRenderer suspense boundary
 
 3. **Write tests** — new code must meet coverage thresholds (80% lines/functions/statements and 75% branches at the monorepo level; core packages enforce higher per-package thresholds)
 4. **Add JSDoc** — all new public exports require JSDoc with `@param`, `@returns`, and `@see` RFC links
-5. **Never edit `packages/docs/api/`** — API docs are auto-generated; edit source JSDoc and regenerate with `pnpm run docs`
+5. **Never edit `packages/docs/api/`** — API docs are auto-generated; edit source JSDoc and regenerate with `pnpm run docs`. Keep the result out of your branch: the release regenerates and commits it (see [deployment.md](deployment.md)), so a branch that carries its own regeneration churns hundreds of files and conflicts with the next one.
 
 ### Merge Request Checklist