@xmachines/docs 5.0.2 → 6.0.0

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

@@ -6,7 +6,7 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L30)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L30)
 
 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:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L34)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L34)
 
 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:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/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/v6.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
 
 The state metadata. A `meta.route` field gives the state a route.
 
@@ -64,7 +64,7 @@ generated transition, and that flag defaults to `false`.
 optional on?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L51)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L51)
 
 The event handlers of this state. The function reads them where a child asks for a
 local `play.route` handler, so that the transitions of the user survive the merge.
@@ -77,6 +77,6 @@ local `play.route` handler, so that the transitions of the user survive the merg
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/routing/format-play-route-transitions.ts#L46)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L46)
 
 The nested child states. The function walks them for each further route declaration.

package/api/@xmachines/play-xstate/with-view/functions/withView.md

@@ -6,7 +6,7 @@
 function withView<TMachine>(Base): PlayerConstructor<TMachine, Viewable>;
 ```
 
-Defined in: [packages/play-xstate/src/with-view.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-xstate/src/with-view.ts#L99)
+Defined in: [packages/play-xstate/src/with-view.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-xstate/src/with-view.ts#L99)
 
 Adds the view capability to an actor class.
 

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

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [vite-aliases.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L238)
+Defined in: [vite-aliases.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vite-aliases.ts#L238)
 
 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:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L355)
+Defined in: [vite-aliases.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vite-aliases.ts#L355)
 
 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:308](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L308)
+Defined in: [vite-aliases.ts:308](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vite-aliases.ts#L308)
 
 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:275](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L275)
+Defined in: [vite-aliases.ts:275](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vite-aliases.ts#L275)
 
 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:334](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L334)
+Defined in: [vite-aliases.ts:334](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vite-aliases.ts#L334)
 
 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:335](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vite-aliases.ts#L335) |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:335](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vite-aliases.ts#L335) |

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

@@ -6,7 +6,7 @@
 function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
 ```
 
-Defined in: [vitest.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vitest.ts#L209)
+Defined in: [vitest.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vitest.ts#L209)
 
 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:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vitest.ts#L65)
+Defined in: [vitest.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vitest.ts#L65)
 
 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:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vitest.ts#L159)
+Defined in: [vitest.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vitest.ts#L159)
 
 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:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vitest.ts#L167) |
-| <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:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vitest.ts#L174) |
-| <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:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/shared/config/vitest.ts#L180) |
+| <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:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vitest.ts#L167) |
+| <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:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vitest.ts#L174) |
+| <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:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/shared/config/vitest.ts#L180) |

package/api/README.md

@@ -2,6 +2,7 @@
 
 ## Packages
 
+- [@xmachines/core](@xmachines/core/README.md)
 - [@xmachines/play](@xmachines/play/README.md)
 - [@xmachines/play-actor](@xmachines/play-actor/README.md)
 - [@xmachines/play-atom](@xmachines/play-atom/README.md)

package/api/llms.txt

@@ -46,6 +46,7 @@
 - [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md): SvelteKit router adapter for actor-driven navigation
 - [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md): Svelte SPA router adapter for actor-driven navigation
 - [@xmachines/shared](@xmachines/shared/README.md): Shared TypeScript, oxlint, and formatting configuration
+- [@xmachines/core](@xmachines/core/README.md): BaseError, the release protocol (asDisposable), a key-value cache, and helpers for values and errors
 
 ## Notes For LLMs
 

package/contributing/architecture.md

@@ -20,21 +20,25 @@ XMachines JS is the JavaScript/TypeScript reference implementation of the **Univ
 
 ```mermaid
 graph TD
-    subgraph Layer0["Layer 0 — Protocol / Primitives"]
+    subgraph Foundation["Foundation"]
+        core["@xmachines/core\n(BaseError, asDisposable, cache)"]
+        shared["@xmachines/shared\n(tsconfig, oxlint, oxfmt)"]
+    end
+
+    subgraph Protocol["Protocol / Primitives"]
         play["@xmachines/play\n(PlayEvent, PlayError)"]
         atoms["@xmachines/play-atom\n(atoms, watchAtom)"]
-        shared["@xmachines/shared\n(tsconfig, oxlint, oxfmt)"]
     end
 
-    subgraph Layer1["Layer 1 — Abstract Actor Base"]
+    subgraph ActorBase["Abstract Actor Base"]
         actor["@xmachines/play-actor\n(PlayActor)"]
     end
 
-    subgraph Layer2v["Layer 2 — The View Half"]
+    subgraph ViewHalf["The View Half"]
         view["@xmachines/play-view\n(Viewable, PlaySpec, the view store lifecycle)"]
     end
 
-    subgraph Layer2["Layer 2 — Concrete Implementations"]
+    subgraph Concrete["Concrete Implementations"]
         xstate["@xmachines/play-xstate\n(PlayerActor, definePlayer, routing)"]
         router["@xmachines/play-router\n(RouterBridgeBase, RouteMap, Routable)"]
         routerxstate["@xmachines/play-router/xstate\n(extractMachineRoutes, createRouteMap)"]
@@ -59,7 +63,7 @@ graph TD
         end
     end
 
-    play --> actor
+    core --> play
     atoms --> actor
     actor --> xstate
     actor --> router
@@ -72,6 +76,8 @@ graph TD
     xstate -.->|"play.route events"| router
 ```
 
+The diagram groups the packages by role. The build order is a separate view: each package sits one layer above its deepest workspace dependency, and [Build Layers](development.md#build-layers) lists them.
+
 ## Component Responsibilities
 
 | Package                                                                                           | Responsibility                                          | Key File                                                            |
@@ -100,6 +106,7 @@ graph TD
 | [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | SvelteKit router bridge                                 | `packages/play-sveltekit-router/src/sveltekit-router-bridge.ts`     |
 | [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | Svelte SPA Router bridge                                | `packages/play-svelte-spa-router/src/svelte-spa-router-bridge.ts`   |
 | [`@xmachines/shared`](../api/@xmachines/shared/README.md)                                         | Shared configs: tsconfig, oxlint, oxfmt, vitest         | `packages/shared/config/`                                           |
+| [`@xmachines/core`](../api/@xmachines/core/README.md)                                             | `BaseError`, the release protocol, a cache, helpers     | `packages/core/src/`                                                |
 | `@xmachines/docs`                                                                                 | API docs and RFC documentation                          | `packages/docs/`                                                    |
 
 ## Data Flow
@@ -213,7 +220,7 @@ type LoginEvent = PlayEvent<{ userId: string; timestamp: number }>;
 
 ### [`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md)
 
-Base class for all `@xmachines/*` typed runtime errors. Carries `scope` (throwing class/module) and `code` (stable machine-readable identifier, e.g. `"PLAY_ROUTER_SYNC_FAILED"`). Subclassed per package, exported from each package's `./errors` subpath. Never match on `.message` — always match on `.code` or the subclass.
+Base class for the typed runtime errors of every Play package. It extends [`BaseError`](../api/@xmachines/core/errors/classes/BaseError.md) of [`@xmachines/core/errors`](../api/@xmachines/core/README.md). Carries `scope` (throwing class/module) and `code` (stable machine-readable identifier, e.g. `"PLAY_ROUTER_SYNC_FAILED"`). Subclassed per package, exported from each package's `./errors` subpath. Never match on `.message` — always match on `.code` or the subclass.
 
 ```typescript
 import { PlayError } from "@xmachines/play/errors";
@@ -306,7 +313,7 @@ interface PlayRouteEvent {
 
 ### [`watchAtom(atom, callback)`](../api/@xmachines/play-atom/functions/watchAtom.md)
 
-Subscribe to a single atom with microtask coalescing and memory-safe cleanup. It builds one `subscribe` for the life of the watch, so no code arms anything again. The `disposed` flag guards post-cleanup callbacks, and the `scheduled` guard deduplicates rapid synchronous atom changes. Returns a `Cleanup` function.
+Subscribe to a single atom with microtask coalescing and memory-safe cleanup. It builds one `subscribe` for the life of the watch, so no code arms anything again. The `disposed` flag guards post-cleanup callbacks, and the `scheduled` guard deduplicates rapid synchronous atom changes. Returns a plain release function.
 
 ### [`formatPlayRouteTransitions(machineConfig)`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md)
 
@@ -368,22 +375,23 @@ Each adapter also exports a framework-integrated provider component (e.g. `PlayR
 ```
 packages/
 ├── shared/                     # Zero-dependency shared configs (tsconfig, oxlint, oxfmt, vitest)
-├── play/                       # Layer 0: Core protocol: PlayEvent, PlayError, assertNonNullable
-├── play-atom/                  # Layer 1: the atom primitives — all atom imports go here
+├── core/                       # Layer 0: BaseError, the release protocol, the cache, helpers; no module state
+├── play/                       # Layer 1: Core protocol: PlayEvent, PlayError, assertNonNullable
+├── play-atom/                  # Layer 0: the atom primitives — all atom imports go here
 │   └── src/                    # Declares the atom contract, binds the engine; watchAtom utility
-├── play-actor/                 # Layer 2: the PlayActor contract — state and send, and nothing else
+├── play-actor/                 # Layer 1: the PlayActor contract — state and send, and nothing else
 ├── play-pattern/               # Layer 1: the route pattern language — one parse, and the path it builds back
 ├── play-url/                   # Layer 2: the URL layer — the URLPattern API, a base path, framework params
-├── play-view/                  # Layer 3: Viewable, PlaySpec, the view store lifecycle, the context projection
+├── play-view/                  # Layer 2: Viewable, PlaySpec, the view store lifecycle, the context projection
 │
-├── play-xstate/                # Layer 5: Concrete XState v5 actor: definePlayer, PlayerActor
+├── play-xstate/                # Layer 4: Concrete XState v5 actor: definePlayer, PlayerActor
 │   └── src/
 │       ├── player-actor.ts              # PlayerActor — concrete actor
 │       ├── define-player.ts             # definePlayer factory
 │       ├── routing/                     # deriveRoute, buildRouteUrl, formatPlayRouteTransitions
 │       └── view/                        # deriveCurrentView (meta.view → PlaySpec)
 │
-├── play-router/                # Layer 4: Route extraction, bidirectional mapping, bridge base
+├── play-router/                # Layer 3: Route extraction, bidirectional mapping, bridge base
 │   └── src/
 │       ├── router-bridge-base.ts        # RouterBridgeBase (Template Method for all adapters)
 │       ├── base-route-map.ts            # RouteMap (bidirectional stateId ↔ path)
@@ -439,14 +447,15 @@ With `declarationMap: true` in the base tsconfig (from [`@xmachines/shared/tscon
 
 **Dependency rules:**
 
-The **protocol layer** is `play`, `play-atom` and `play-actor`. The three form a chain — `play-atom` reads `play`, and `play-actor` reads `play-atom` — and none of them reads a package below.
+The **protocol layer** is `play`, `play-atom` and `play-actor`. `play` reads `core` alone, for the base of `PlayError`. `play-atom` reads no workspace package. `play-actor` reads `play-atom`, and no other package of the workspace.
 
 | Layer                                 | May import from                                         | Must not import from             |
 | ------------------------------------- | ------------------------------------------------------- | -------------------------------- |
-| Protocol (`play`)                     | External libs only                                      | Any other `@xmachines/*` package |
-| Protocol (`play-atom`)                | `play`, `@xstate/store`                                 | Any other `@xmachines/*` package |
-| Protocol (`play-actor`)               | `play`, `play-atom`                                     | Any other `@xmachines/*` package |
-| Pattern language (`play-pattern`)     | External libs only                                      | Any other `@xmachines/*` package |
+| Core (`core`)                         | No package                                              | Any `@xmachines/*` package       |
+| Protocol (`play`)                     | `core`                                                  | Any other `@xmachines/*` package |
+| Protocol (`play-atom`)                | `@xstate/store`                                         | Any other `@xmachines/*` package |
+| Protocol (`play-actor`)               | `play-atom`                                             | Any other `@xmachines/*` package |
+| Pattern language (`play-pattern`)     | `core`                                                  | Any other `@xmachines/*` package |
 | URL layer (`play-url`)                | Protocol layer, `play-pattern`, `urlpattern-polyfill`   | Any other `@xmachines/*` package |
 | View half (`play-view`)               | Protocol layer, `@xmachines/json-render-core`           | Router adapters, framework code  |
 | Actor logic (`play-xstate`)           | Protocol layer, `play-pattern`, `xstate`                | View renderers, router adapters  |
@@ -454,20 +463,26 @@ The **protocol layer** is `play`, `play-atom` and `play-actor`. The three form a
 | Router adapters (`play-*-router`)     | `play-router`, protocol layer, framework router lib     | View renderers                   |
 | View renderers (`play-*`)             | Protocol layer, `play-view`, `@xmachines/json-render-*` | Router adapters                  |
 
+Every layer above the protocol layer may also import [`@xmachines/core`](../api/@xmachines/core/README.md), and `play` imports it for `BaseError`. It is a peer, and not a dependency: `err instanceof BaseError` answers `false` for an error of a second copy, so an install must hold one copy. See [the packages that must exist one time](development.md#the-packages-that-must-exist-one-time).
+
 `play-view` and `play-router` are OPTIONAL peer dependencies of `play-xstate`, because the two capability subpaths carry them: [`@xmachines/play-xstate/view`](../api/@xmachines/play-xstate/README.md) names the first and [`@xmachines/play-xstate/routing`](../api/@xmachines/play-xstate/README.md) names the second. The core entry point imports neither.
 
 ## Error Handling
 
-All `@xmachines/*` errors extend [`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md) and carry two stable fields:
+All `@xmachines/*` errors extend [`BaseError`](../api/@xmachines/core/errors/classes/BaseError.md) of [`@xmachines/core/errors`](../api/@xmachines/core/README.md), and carry two stable fields:
 
 - `scope` — the class or module that threw (e.g. `"RouterBridgeBase"`)
 - `code` — a stable machine-readable identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`)
 
+Every error of a Play package extends [`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md), which extends `BaseError`. A package below the Play protocol extends `BaseError` directly: [`@xmachines/core`](../api/@xmachines/core/README.md) throws `DisposeConflictError` when `asDisposable` receives a named release that the scope would never run.
+
 **Error hierarchy:**
 
 ```mermaid
 flowchart TD
-    PE["PlayError\n@xmachines/play/errors"]
+    BE["BaseError\n@xmachines/core/errors"]
+    BE --> DCE["DisposeConflictError\nCORE_DISPOSE_CONFLICT"]
+    BE --> PE["PlayError\n@xmachines/play/errors"]
     PE --> NNE["NonNullableError\nPLAY_NON_NULLABLE"]
     PE --> RSE["RouterSyncError\nPLAY_ROUTER_SYNC_FAILED"]
     PE --> DBE["DuplicateBridgeError\nPLAY_ROUTER_DUPLICATE_BRIDGE"]

package/contributing/configuration.md

@@ -54,13 +54,15 @@ The root TypeScript config is a **build coordinator only** — it compiles nothi
 	"files": [],
 	"references": [
 		// Layer 0 — no internal deps
+		{ "path": "./packages/core" },
 		{ "path": "./packages/docs" },
-		{ "path": "./packages/play" },
+		{ "path": "./packages/play-atom" },
 		{ "path": "./packages/shared" },
 		// Layer 1 — depends on Layer 0
-		{ "path": "./packages/play-atom" },
-		// Layer 2
+		{ "path": "./packages/play" },
 		{ "path": "./packages/play-actor" },
+		// Layer 2
+		{ "path": "./packages/play-view" },
 		// Layer 3
 		{ "path": "./packages/play-router" }
 		// ...etc.

package/contributing/development.md

@@ -82,6 +82,7 @@ The repository is organized as a **pnpm workspaces** monorepo with all packages
 ```
 packages/
 ├── shared/                      # Shared configs (tsconfig, oxlint, oxfmt, vitest)
+├── core/                        # BaseError, the release protocol, the cache, small helpers
 ├── play/                        # Core protocol (PlayEvent, PlayError)
 ├── play-atom/                   # The atom primitives over @xstate/store
 ├── play-pattern/                # The route pattern language: one parse, and the path it builds back
@@ -188,17 +189,17 @@ React 18 and vue-router 4 are supported by intent — nothing known depends on 1
 
 ### The packages that must exist one time
 
-[`@xmachines/play`](../api/@xmachines/play/README.md) and [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) are a peer of every package that reads them, and a dependency of none.
+[`@xmachines/core`](../api/@xmachines/core/README.md), [`@xmachines/play`](../api/@xmachines/play/README.md) and [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) are a peer of every package that reads them, and a dependency of none.
 
 [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) re-exports the atom of `@xstate/store`, and that library holds the active subscriber in a variable of its own module. Two copies build two graphs. A computed atom of the first copy and a subscription of the second copy therefore never meet: the subscriber stays silent, and no error reports the fault. Every propagation of state in this architecture goes through an atom, so the second copy stops the reactivity of a whole application.
 
-[`@xmachines/play`](../api/@xmachines/play/README.md) holds `PlayError`, and the documentation sends a consumer to `err instanceof PlayError`. That check answers `false` for an error of the second copy.
+[`@xmachines/play`](../api/@xmachines/play/README.md) holds `PlayError`, and the documentation sends a consumer to `err instanceof PlayError`. That check answers `false` for an error of the second copy. [`@xmachines/core`](../api/@xmachines/core/README.md) holds `BaseError`, the base of `PlayError`, and `err instanceof BaseError` fails in the same way.
 
 A dependency invites that second copy. `scripts/lib/workspace-deps.mjs` pins a `workspace:*` range to an EXACT version, so two packages of two releases name two versions, and an installer resolves both. A peer moves the choice to the consumer, who brings one copy. The `@xmachines/json-render-*` packages carry the same rule for the same reason.
 
-Each of the two needs a `devDependency` beside the peer, because the workspace installs no peer. Without that entry a package resolves the specifier through the hoisting of another package, and it compiles until that other package stops declaring it.
+Each of the three needs a `devDependency` beside the peer, because the workspace installs no peer. Without that entry a package resolves the specifier through the hoisting of another package, and it compiles until that other package stops declaring it.
 
-`tests/singleton-peers.test.ts` holds the three rules true: no dependency, a dev entry beside each peer, and a peer for each one that `src/` imports. A package that reads one of the two in its TESTS alone needs the dev entry alone — [`@xmachines/play-tanstack-router`](../api/@xmachines/play-tanstack-router/README.md) is that case.
+`tests/singleton-peers.test.ts` holds the three rules true: no dependency, a dev entry beside each peer, and a peer for each one that `src/` imports. A package that reads one of the three in its TESTS alone needs the dev entry alone — [`@xmachines/play-tanstack-router`](../api/@xmachines/play-tanstack-router/README.md) is that case.
 
 The rule reads in both directions. A peer that the `src/` directory never imports is a peer that a consumer installs for nothing, and four router adapters carried one. A package declares the peer when it reads the package, and a `devDependency` alone when its tests read it.
 
@@ -221,16 +222,15 @@ Packages are grouped into dependency layers as defined in the root `tsconfig.jso
 
 | Layer | Packages                                                                         | Depends on         |
 | ----- | -------------------------------------------------------------------------------- | ------------------ |
-| 0     | `docs`, `play`, `shared`                                                         | External libs only |
-| 1     | `play-atom`, `play-pattern`                                                      | Layer 0            |
-| 2     | `play-actor`, `play-url`                                                         | Layers 0–1         |
-| 3     | `play-view`                                                                      | Layers 0–2         |
-| 4     | `play-dom`, `play-react`, `play-router`, `play-solid`, `play-svelte`, `play-vue` | Layers 0–3         |
-| 5     | `play-tanstack-router`, `play-xstate`                                            | Layers 0–4         |
-| 6     | `play-actor/examples/shared`                                                     | Layers 0–5         |
-| 7     | renderer demo apps                                                               | Layers 0–6         |
-| 8     | the eight router adapters                                                        | Layers 0–7         |
-| 9     | router demo apps                                                                 | Layers 0–8         |
+| 0     | `core`, `docs`, `play-atom`, `shared`                                            | External libs only |
+| 1     | `play`, `play-actor`, `play-pattern`                                             | Layer 0            |
+| 2     | `play-url`, `play-view`                                                          | 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.
 
@@ -239,26 +239,24 @@ The layer of an entry is its longest path to a package with no workspace depende
 ```mermaid
 flowchart LR
     subgraph L0["Layer 0 — no workspace deps"]
-        play
+        core
+        play-atom
         shared
         docs
     end
 
     subgraph L1["Layer 1"]
-        play-atom
+        play
+        play-actor
         play-pattern
     end
 
     subgraph L2["Layer 2"]
-        play-actor
         play-url
-    end
-
-    subgraph L3["Layer 3"]
         play-view
     end
 
-    subgraph L4["Layer 4 — view renderers, and the router core"]
+    subgraph L3["Layer 3 — view renderers, and the router core"]
         play-dom
         play-react
         play-router
@@ -267,31 +265,31 @@ flowchart LR
         play-vue
     end
 
-    subgraph L5["Layer 5"]
+    subgraph L4["Layer 4"]
         play-tanstack-router
         play-xstate
     end
 
-    subgraph L6["Layer 6"]
+    subgraph L5["Layer 5"]
         actorshared["play-actor/examples/shared"]
     end
 
-    subgraph L7["Layer 7"]
+    subgraph L6["Layer 6"]
         renderdemos["renderer demo apps"]
     end
 
-    subgraph L8["Layer 8 — the eight router adapters"]
+    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 L9["Layer 9"]
+    subgraph L8["Layer 8"]
         routerdemos["router demo apps"]
     end
 
-    L0 --> L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7 --> L8 --> L9
+    L0 --> L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7 --> L8
 ```
 
 ### Adding a New Package

package/contributing/migrating-to-play-atom.md

@@ -57,6 +57,7 @@ pnpm add @xmachines/play-atom @xstate/store
 | `{ equals }`                               | `{ compare }`                                                   |
 | `SignalOptions<T>` / `ComputedOptions<T>`  | `AtomOptions<T>`                                                |
 | `watchSignal(signal, onValue)`             | `watchAtom(atom, onValue)`                                      |
+| `Cleanup` (type)                           | `() => void` — the codemod reports it, and rewrites it not      |
 | `useSignalEffect(cb, deps)` (`play-react`) | `useAtomEffect(sources, cb, deps)`                              |
 | `Signal.subtle.Watcher`                    | `atom.subscribe(fn)`, or `watchAtom`                            |
 | `Signal.subtle.untrack(fn)`                | — no equivalent. See below                                      |

package/examples/@xmachines/play-dom-demo/functions/createAuthActionHandlers.md

@@ -6,7 +6,7 @@
 function createAuthActionHandlers(actor): object;
 ```
 
-Defined in: [packages/play-actor/examples/shared/src/actions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-actor/examples/shared/src/actions.ts#L48)
+Defined in: [packages/play-actor/examples/shared/src/actions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L48)
 
 Build the demo action handler map for one actor.
 
@@ -25,11 +25,11 @@ framework's `defineRegistry` accepts; spread the result into its `actions`.
 
 | Name             | Type                                                    | Defined in                                                                                                                                                               |
 | ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `addTask()`      | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-actor/examples/shared/src/actions.ts#L65) |
-| `completeTask()` | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-actor/examples/shared/src/actions.ts#L72) |
-| `login()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-actor/examples/shared/src/actions.ts#L50) |
-| `logout()`       | () => `Promise`\<`void`\>                               | [packages/play-actor/examples/shared/src/actions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-actor/examples/shared/src/actions.ts#L54) |
-| `removeTask()`   | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-actor/examples/shared/src/actions.ts#L81) |
-| `resetForm()`    | (`params`, `setState`) => `Promise`\<`void`\>           | [packages/play-actor/examples/shared/src/actions.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-actor/examples/shared/src/actions.ts#L99) |
-| `route()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-actor/examples/shared/src/actions.ts#L55) |
-| `submitForm()`   | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-actor/examples/shared/src/actions.ts#L92) |
+| `addTask()`      | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L65) |
+| `completeTask()` | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L72) |
+| `login()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L50) |
+| `logout()`       | () => `Promise`\<`void`\>                               | [packages/play-actor/examples/shared/src/actions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L54) |
+| `removeTask()`   | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L81) |
+| `resetForm()`    | (`params`, `setState`) => `Promise`\<`void`\>           | [packages/play-actor/examples/shared/src/actions.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L99) |
+| `route()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L55) |
+| `submitForm()`   | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L92) |

package/examples/@xmachines/play-dom-demo/functions/createConfirmDialog.md

@@ -6,7 +6,7 @@
 function createConfirmDialog(confirm): Promise<boolean>;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/ConfirmDialog.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/ConfirmDialog.ts#L12)
+Defined in: [packages/play-dom/examples/demo/src/components/ConfirmDialog.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/ConfirmDialog.ts#L12)
 
 ConfirmDialog — the DOM demo's onConfirm implementation.
 

package/examples/@xmachines/play-dom-demo/functions/createNavBar.md

@@ -6,7 +6,7 @@
 function createNavBar(actor, container): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
 
 NavBar — App-shell navigation factory. Mounts a reactive nav into
 `container`, observes actor.state via watchAtom, and updates button

package/examples/@xmachines/play-dom-demo/functions/initShell.md

@@ -6,7 +6,7 @@
 function initShell(actor, appElement, inspector): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Shell.ts#L18)
+Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Shell.ts#L18)
 
 Shell — DOM shell layout factory. Renders demo chrome (header + main +
 debug panel), mounts NavBar, connects DOM renderer, and wires DebugPanel.

package/examples/@xmachines/play-dom-demo/type-aliases/AuthCatalog.md

@@ -6,4 +6,4 @@
 type AuthCatalog = typeof authCatalog;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/catalog.ts#L6)
+Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/catalog.ts#L6)

package/examples/@xmachines/play-dom-demo/variables/About.md

@@ -6,7 +6,7 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/About.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/About.ts#L8)
 
 About — Public information page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'About'>). Renders static content from props.

package/examples/@xmachines/play-dom-demo/variables/Button.md

@@ -6,7 +6,7 @@
 const Button: ComponentFn<AuthCatalog, "Button">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Button.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Button.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/Button.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Button.ts#L8)
 
 Button — emits `press`; the spec's `on.press` binding decides what happens
 (a host action sending a machine event, or a built-in like setState).

package/examples/@xmachines/play-dom-demo/variables/Contact.md

@@ -6,7 +6,7 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
 
 Contact — Public contact page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Contact'>). Renders static content from props.