@xmachines/docs 5.0.2 → 6.1.0

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
@@ -177,20 +184,30 @@ flowchart TD
     F -->|"URL = machine initial state"| H
 ```
 
-### View Prop Enrichment
+### View derivation
 
 ```mermaid
 flowchart TD
-    A["XState snapshot.getMeta()"]
-    B["resolveViewMeta(meta)\nfinds deepest meta.view with root + elements\n(its record key becomes viewKey)"]
+    A["XState snapshot"]
+    O{"a state node of the machine\ndeclares meta.view.outlets?\n(cached for each machine)"}
+    T["resolveViewTree(root, snapshot.value)\na view with outlets composes its active children;\nany other node keeps its deepest view"]
+    G["composeViews(tree) in play-view\ncached for each tree: elements, authored state, viewParts\nviewKey = the id of the outermost composing state"]
+    B["resolveViewMeta(active branch: the routed region first)\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 the currentView atom)\ncarry previous state reference when the slice is value-unchanged"]
     F["Derived PlaySpec (with viewKey) is the value of the currentView atom"]
 
-    A --> B --> C --> D --> E --> F
+    A --> O
+    O -->|"yes"| T
+    T -->|"an active view composes"| G --> C
+    T -->|"no active view composes:\nthe view that the walk resolved"| C
+    O -->|"no"| B --> C
+    C --> D --> E --> F
 ```
 
+The composition keeps each element of the outer view by reference, except an element that receives a child view. It prefixes each key of a child view with the id of its state. `composeViews` caches the result for each tree of view objects. A context assign therefore emits the same `elements` and `viewParts` references, and the emit gate of `withView` walks no element. When the `viewKey` stays and the `viewParts` value changes, `createViewStoreLifecycle` writes the authored keys that the store does not hold. play-dom then gives the new spec to `setSpec` of the incremental renderer, which keeps each node whose element did not change.
+
 **State atoms on the actor:**
 
 | Atom                 | Type                             | Description                                                                                                                                                                                                      |
@@ -213,7 +230,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";
@@ -238,7 +255,7 @@ Optional capability interface. Exposes `currentView: ReadonlyAtom<PlaySpec | nul
 
 ### [`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md)
 
-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).
+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. An authored `outlets` field composes the views of the active substates into the view of their parent, and the composed spec also carries `viewParts`. 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/index/classes/PlayerActor.md)
 
@@ -254,7 +271,7 @@ The core imports neither capability, so an application that declares no route lo
 
 **The composition order decides nothing.** `PlayerActor` writes ONE atom for each transition — `state` — and every capability that publishes a value DERIVES it with a computed atom over that one. The engine evaluates `currentRoute` and `currentView` from a single write, in topological order, so a router bridge sees a guard redirect and a renderer sees the view of the same snapshot whatever order `compose` applied.
 
-An earlier release wrote `currentView` from an `onSnapshot` override, and the order was load-bearing there: two writes flushed two times, and an observer of `state` and `currentView` read the new state beside the old view in between. `onSnapshot` remains for a capability that must run an EFFECT on a transition, and an override still calls `super.onSnapshot()` first.
+A capability that must run an EFFECT on a transition overrides `onSnapshot`, and the override calls `super.onSnapshot()` first.
 
 ### [`definePlayer(config)`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) → [`PlayerFactory`](../api/@xmachines/play-xstate/index/type-aliases/PlayerFactory.md)
 
@@ -306,7 +323,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 +385,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)
@@ -428,7 +446,7 @@ packages/<name>/
 
 The monorepo uses **TypeScript composite project references** (`"composite": true` per package) for a correct, incremental, dependency-ordered build. The root `tsconfig.json` lists every package in layer order — leaves first, dependents last — and it is the ONLY build order of the workspace. `tsc --build` at the root reads that array and resolves the graph.
 
-**The layer table and the diagram live in [development.md](development.md#build-layers).** They stood here too, and the copy drifted: it kept the numbers of an earlier release, so a reader who added a package placed it in the wrong block of the root array. One home for the question, as for the `references` arrays that the root file replaced.
+**The layer table and the diagram live in [development.md](development.md#build-layers).**
 
 Two facts about the graph belong to this document, because they are architecture and not build order:
 
@@ -439,14 +457,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 +473,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"]
@@ -599,7 +624,7 @@ Custom `watchRouterChanges()` implementations that bypass `syncActorFromRouter()
 
 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-view`](../api/@xmachines/play-view/README.md) names a `/context` projection that it cannot derive, one time for each spec; [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) names the `meta.view.contextProps` field that 1.x removed, one time for each spec; and [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) 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.*`.
+Three other places write to `console.warn`, and each one reports a configuration that the library cannot refuse: `warnOnce` of [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) names a `/context` projection that it cannot derive, one time for each spec; [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) names a `meta.view.contextProps` field, which the view does not read, one time for each spec; and [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) 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

@@ -6,12 +6,20 @@ This document describes every configuration file, environment variable, and per-
 
 ## Environment Variables
 
-The monorepo itself has no application runtime that reads environment variables. The only variables are for the **dev container** tooling and the **CI/CD release pipeline**.
+The monorepo itself has no application runtime that reads environment variables. The only variables are for the **dev container** tooling, the **test runs**, and the **CI/CD release pipeline**.
 
 ### Dev Container Variables
 
 The dev container currently defines no workspace-specific environment variables; `.devcontainer/.env` (loaded via `env_file` in `.devcontainer/compose.yaml`) is available for local overrides if a future tool needs one. Copy `.devcontainer/.env.sample` to `.devcontainer/.env` to get started.
 
+### Test Run Variable
+
+| Variable         | Required | Default  | Description                                                                                                                                                      |
+| ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `XM_TEST_TARGET` | Optional | `source` | The code that a test run loads for each published package: `source` (the `src/` tree) or `dist` (the build output). Any other value stops the run with an error. |
+
+**Defined in:** the `test:dist` and `test:browser:dist` scripts of the root `package.json`. **Read by:** `xmTestTarget` of [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md), which every config helper of that package calls. Do not set it by hand: run `pnpm run test:dist`. See [testing.md](testing.md#tests-on-the-build-output).
+
 ### CI / Release Pipeline Variable
 
 | Variable            | Required | Default                      | Description                                                                                                                                                                         |
@@ -54,13 +62,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.
@@ -327,7 +337,7 @@ stays.
 
 **Location:** `/vitest.config.ts`
 **Tool:** [Vitest](https://vitest.dev/) `^4.1.5`
-**Run:** `pnpm test` / `pnpm run test:coverage`
+**Run:** `pnpm test` / `pnpm run test:coverage` / `pnpm run test:dist`
 
 Root Vitest config is a **workspace coordinator** that lists all per-package configs under `test.projects`. It sets conservative monorepo-wide defaults:
 
@@ -352,8 +362,10 @@ Root Vitest config is a **workspace coordinator** that lists all per-package con
 
 Coverage provider: `v8`. Individual packages may declare higher per-package thresholds in their own `vitest.config.ts`.
 
+The JUnit file is `test-results.xml`. The dist run (`XM_TEST_TARGET=dist`) writes `test-results-dist.xml`, and it prefixes each class name with `dist:`, so the two runs stay apart in the merge request widget.
+
 **Browser test config:** `/vitest.browser.config.ts`
-Run with `pnpm run test:browser`. Uses Playwright Chromium via Vitest browser mode. `testTimeout` is `20000` ms; `maxWorkers` is `2` (default; demo integration projects override with `pool: "threads"` + `maxWorkers: 2`).
+Run with `pnpm run test:browser`, or with `pnpm run test:browser:dist` against the build output. Uses Playwright Chromium via Vitest browser mode. `testTimeout` is `20000` ms; `maxWorkers` is `2` (default; demo integration projects override with `pool: "threads"` + `maxWorkers: 2`).
 
 ### Per-Package Vitest Config — `@xmachines/shared/vitest`
 
@@ -363,6 +375,8 @@ Run with `pnpm run test:browser`. Uses Playwright Chromium via Vitest browser mo
 Packages use `defineXmVitestConfig(import.meta.url, overrides)` to create their config. It automatically injects:
 
 - `resolve.alias` via `xmAliases()` so `@xmachines/*` imports resolve to TypeScript source without a prior build.
+- In the dist run, the `xmBuildOutput` plugin. The alias map then holds no published package, so each `@xmachines/*` import resolves through its `exports` map to `dist/`. The plugin moves each `src/` file that a test imports by path to its counterpart in `dist/`.
+- `test.provide.xmTestTarget`, which a test reads with `inject("xmTestTarget")`.
 - `vitest.node.setup.ts` for non-browser projects (if not already present).
 - `vitest.setup.ts` for all projects (if not already present).
 
@@ -385,10 +399,12 @@ export default defineXmVitestConfig(import.meta.url, {
 **Location:** `packages/shared/config/vite-aliases.ts`
 **Exported as:** [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md)
 
-Provides two helpers used in all `vitest.config.ts` and `vite.config.ts` files:
+Provides the helpers used in all `vitest.config.ts` and `vite.config.ts` files:
 
-- **`xmAliases(import.meta.url)`** — returns a `Record<string, string>` mapping every `@xmachines/*` package to its TypeScript source entry. Enables tests and dev servers to run without a prior `pnpm run build`.
-- **`xmResolve(import.meta.url)`** — returns a full Vite `resolve` config with `xmAliases` plus `preserveSymlinks: true` and `conditions: ["source"]`.
+- **`xmAliases(import.meta.url)`** — returns a `Record<string, string>` mapping every `@xmachines/*` package to its TypeScript source entry. Enables tests and dev servers to run without a prior `pnpm run build`. In the dist run, the map holds no entry for a published package except `<name>/src`.
+- **`xmResolve(import.meta.url)`** — returns a full Vite `resolve` config with `xmAliases` plus `preserveSymlinks: false`. It sets no `conditions`: the aliases do the work that the `source` condition does for TypeScript.
+- **`xmTestTarget()`** — reads `XM_TEST_TARGET`, and returns `source` or `dist`.
+- **`xmBuildOutput(import.meta.url)`** — the Vite plugin of the dist run. It moves each `src/` file of a published package to its counterpart in `dist/`, and it fails the import when the build output holds no such file. It also fails the run when anything loads a `src/` file of a published package.
 - **`xmCacheDir(import.meta.url, name)`** — returns a shared Vite cache path under `node_modules/.vite/<name>` to prevent redundant dep optimizer runs across projects.
 - **`xmOptimizeDeps(include?)`** — returns an `optimizeDeps.include` list holding exactly the specifiers passed in. Nothing is pre-bundled by default, and every entry has to be a package the calling project declares: pnpm gives each package its own `node_modules`, so Vite cannot resolve an undeclared specifier — it warns on stderr and carries on, which reads as a failure in a passing job.
 
@@ -434,6 +450,25 @@ Any step above can be skipped with the `SEMREL_SKIP_STEPS` CI variable, which th
 
 ---
 
+### Dependency Updates — `renovate.json5`
+
+**Location:** `/renovate.json5`
+**Tool:** [Renovate](https://docs.renovatebot.com/), from the `xmachin-es/renovate` project
+
+Renovate updates the npm dependencies of every package of the workspace, the demos under `packages/*/examples/*` too. It also updates the to-be-continuous components that `.gitlab-ci.yml` includes. The bot runs one time each week. For each new version, it opens a merge request, and the pipeline of that merge request tests the new version. The Dependency Dashboard issue lists every update that Renovate knows.
+
+The rules of the file:
+
+- **Three days of cooldown.** The renovate component waits 3 days for a new version, which also covers the cooldown of one day in pnpm 11. The `@xmachines/*` packages have no cooldown, as in `pnpm-workspace.yaml`.
+- **One merge request for json-render.** The `@xmachines/json-render-*` packages move together. The merge request moves every range, the `peerDependencies` too, as a `feat(deps):` commit. Renovate proposes the prereleases of the fork (`0.22.0-xm.1`), which it skips by default. Update the ranges that the README files name on the branch of that merge request.
+- **No new major for an audit floor.** An override with a major in its key, for example `brace-expansion@2`, gets no update to the next major.
+- **Approval for a patched package.** `pnpm-workspace.yaml` patches `@testing-library/jest-dom` and `@vitest/mocker` at one version. An update of these packages, or of vitest, needs a new patch. Approve it in the Dependency Dashboard, then move the patch on its branch.
+- **Commit types.** A component update is a `ci:` commit, so semantic-release makes no release from it. An npm update is a `fix(deps):` commit for a `dependencies` entry, and a `chore(deps):` commit for any other type.
+
+A new version of a component can rename an input and not say so. A pipeline that fails with no job is then an error in the inputs. Compare the inputs in `.gitlab-ci.yml` with the `spec` of the new version before you merge.
+
+---
+
 ## Per-Environment Overrides
 
 This monorepo has no application-level config with per-environment overrides (no `.env.development` / `.env.production` files). All configuration is tool-level (TypeScript, linter, formatter, test runner) and is environment-agnostic.

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
@@ -134,9 +135,11 @@ All commands are run from the **repository root** unless otherwise noted.
 | `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 test`                                | Run all unit/integration tests once, on the source                        |
+| `pnpm run test:dist`                       | Run the same tests on the build output (run `pnpm run build` first)       |
 | `pnpm run test:watch`                      | Re-run tests on file changes (interactive)                                |
 | `pnpm run test:browser`                    | Run Playwright browser tests                                              |
+| `pnpm run test:browser:dist`               | Run Playwright browser tests on the build output                          |
 | `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`) |
@@ -188,17 +191,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 +224,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 +241,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 +267,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                                      |
@@ -204,6 +205,6 @@ this.state = createWritableAtom(this.getSnapshot());
 
 ## See also
 
-- [Understanding Atoms](../guides/atoms.md) — the concepts, and the invariants
+- [Atoms](../guides/atoms.md) — the concepts, and the invariants
 - [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) — the API reference
 - [Play RFC](../rfc/play.md) — section 5.1.1 defines the reactive substrate

package/contributing/testing.md

@@ -8,7 +8,7 @@ The monorepo uses **[Vitest](https://vitest.dev/) `^5.0.1`** as its test framewo
 
 All packages extend the shared Vitest configuration helper `defineXmVitestConfig` (from [`@xmachines/shared/vitest`](../api/@xmachines/shared/README.md)) which automatically applies:
 
-- `@xmachines/*` source aliases so imports resolve to source during test runs
+- `@xmachines/*` source aliases so imports resolve to source during test runs — or, in the dist run, to the build output (see [Tests on the build output](#tests-on-the-build-output))
 - [`@xmachines/shared/vitest-setup`](../api/@xmachines/shared/README.md) — extends Vitest matchers with `@testing-library/jest-dom`
 - [`@xmachines/shared/vitest-node-setup`](../api/@xmachines/shared/README.md) — enforces Node.js ≥ 24 on non-browser projects
 
@@ -77,6 +77,33 @@ pnpm run test:browser
 
 Runs `vitest run --config vitest.browser.config.ts`. Launches all browser-mode projects using headless Chromium via Playwright. Includes both package-level browser unit tests and full demo-app integration flows. The browser global setup (`vitest.browser.global-setup.ts`) raises `process.setMaxListeners` to 32 before workers spawn to prevent false-positive `MaxListenersExceededWarning` with multiple parallel browser projects.
 
+### Tests on the build output
+
+```bash
+pnpm run build
+pnpm run test:dist           # the node suites
+pnpm run test:browser:dist   # the browser suites
+```
+
+`pnpm test` runs every suite on the SOURCE of each package. It needs no build, and it cannot see a defect of the build. `pnpm run test:dist` runs the same test files on the BUILD OUTPUT, as a consumer installs it. The 6.0.0 release shows why both runs are necessary. [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md) and [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md) shipped compiled for server-side rendering, and neither rendered in a browser. Every source suite was green. The node dist run fails 14 test files on that output, and the browser dist run fails the Vue suites.
+
+The two scripts set `XM_TEST_TARGET=dist`, and the config helpers of [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md) read it. No package config holds a copy of the dist setup. The variable changes two things:
+
+- **A specifier.** The alias map drops each published package. [`@xmachines/play-xstate/routing`](../api/@xmachines/play-xstate/README.md) then resolves through the `exports` map of the package to `dist/with-routing.js`. The `source` condition is not set either, so the resolution is the one that a consumer gets.
+- **A path into `src/`.** A test imports the module under test by path, as `../src/define-player.js`, and that import reaches no exports map. The `xmBuildOutput` plugin moves it to `dist/define-player.js`, which is the file that the package entry imports. The test and the package then share ONE module, and a `vi.mock` of the `src/` path replaces the module of the build. The build keeps the module structure, so each source file has one counterpart.
+
+The private packages — the demos and the `examples/shared` fixtures — reach no consumer, and the build does not compile them for one. Both runs read their source, and that source imports the packages from `dist/`.
+
+The plugin fails an import when the build output holds no counterpart. The import then names both files. A fallback to the source would hide the defect that the dist run exists to find. The plugin also fails the run when anything loads a `src/` file of a published package by another route.
+
+**Keep one file set.** Both runs collect the same files. A test that cannot run on the build output imports an internal module that the package does not ship. Import that module through the public entry of the package. If that is not possible, exclude the test from the dist run in its project config, and write the reason beside the exclusion. No test is excluded today.
+
+**The proof.** `packages/play-xstate/test/test-target.test.ts` (node) and `packages/play-dom/test/browser/test-target.browser.test.ts` (browser) run in both runs. Each reads the target with `inject("xmTestTarget")`, and it asserts which file each kind of import loads. `import.meta.resolve` cannot answer that question, because it asks the resolver of Node. A stack trace cannot answer it either, because Vite applies the source maps of `dist/` and names `src/` in both runs.
+
+Run `pnpm run build` first. The dist run reads whatever `dist/` holds, and it does not build. A change to `src/` reaches the dist run only through a new build.
+
+Coverage stays on the source run. The build output carries none of the lines that the gate measures.
+
 ### With coverage
 
 ```bash
@@ -400,12 +427,12 @@ stop(); // Always clean up
 For type-only assertions, use `@ts-expect-error` in `.spec.ts` files:
 
 ```typescript
-const bad: PlaySpec = typedSpec({
+const bad: ViewMeta = typedSpec({
 	root: "root",
 	elements: {},
-	// @ts-expect-error "stat" is not a PlaySpec field — typedSpec flags it on an
+	// @ts-expect-error "stat" is not a ViewMeta field — typedSpec flags it on an
 	// inline literal (excess-property checking does not reach aliased or spread
-	// objects; use `satisfies PlaySpec` at the literal for those)
+	// objects; use `satisfies ViewMeta` at the literal for those)
 	stat: {},
 });
 // At runtime the object exists; only the compile-time error is being tested
@@ -536,6 +563,8 @@ pnpm run test:coverage
 
 The job passes no reporter flag. `vitest.config.ts` owns the reporters, the JUnit file and the coverage directory, and it reads `COVERAGE_REPORTS_DIR` — which the `test` job sets to `reports/`. A new package therefore needs no CI change.
 
+**Tests on the build output:** `test:dist` runs `pnpm run test:dist`, and `test:browser:dist` runs `pnpm run test:browser:dist` on the Playwright image. Both take `dist/` from `node-build` through `needs:`, so they test the build that the pipeline produced. They follow the rules of `test`, and they block: a failure is a defect of the tarball that a consumer installs, and it holds the release, because `semantic-release` runs in a later stage. They write `reports/test-results-dist.xml` and `reports/browser-results-dist.xml`, and each test case carries a `dist:` class name, so the widget of the merge request keeps them apart from the source runs. Neither job collects coverage.
+
 **Artifacts:** The `test` job publishes:
 
 - JUnit XML report at `reports/test-results.xml` (surfaced in GitLab's test results panel)

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.1.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.1.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.1.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.1.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.1.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.1.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.1.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.1.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.1.0/packages/play-actor/examples/shared/src/actions.ts#L92) |