@xmachines/docs 4.0.0 → 5.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "4.0.0",
+  "version": "5.0.1",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -56,8 +56,8 @@
   "devDependencies": {
     "@testing-library/jest-dom": "^7.0.1",
     "@types/node": "^26.6.2",
-    "oxfmt": "^0.68.0",
-    "oxlint": "^1.83.0",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.0",
     "typedoc": "^0.28.20",
     "typedoc-plugin-llms-txt": "^0.1.2",
     "typedoc-plugin-markdown": "^4.13.0",

package/rfc/play.md

@@ -3,7 +3,7 @@
 **Status:** Living  
 **Version:** 1.1  
 **Scope:** Universal runtime interoperability and reference implementation  
-**Non-goals:** Persistence, transport protocols, alternative state engines, non-signal reactivity
+**Non-goals:** Persistence, transport protocols, alternative state engines, non-atom reactivity
 
 ---
 
@@ -11,7 +11,7 @@
 
 This RFC defines the **Universal Player Architecture** and its reference implementation. The architecture establishes a design pattern that strictly separates **Business Logic (The Actor)** from **Infrastructure (The Runtime Adapter and View)**.
 
-The reference implementation provides a modular monorepo that satisfies the architectural constraints of **Runtime Agnosticism** and **Logic-Driven Guarding**. It leverages **Standardized Signals (TC39)** to glue a specific **State Engine (XState v5)** to multiple **Runtime Adapters** (TanStack Router, React Router, Vue Router, SolidJS Router) and **View Layers** (React, Vue, SolidJS, Vanilla DOM — all via JSON-Render), while ensuring that **business logic remains the single source of truth** for navigation, state, and UI structure.
+The reference implementation provides a modular monorepo that satisfies the architectural constraints of **Runtime Agnosticism** and **Logic-Driven Guarding**. It leverages **atoms** to glue a specific **State Engine (XState v5)** to multiple **Runtime Adapters** (TanStack Router, React Router, Vue Router, SolidJS Router) and **View Layers** (React, Vue, SolidJS, Vanilla DOM — all via JSON-Render), while ensuring that **business logic remains the single source of truth** for navigation, state, and UI structure.
 
 ---
 
@@ -35,7 +35,7 @@ The reference implementation provides a modular monorepo that satisfies the arch
 
 ### 2.2 Communication Medium
 
-- **Signals (TC39 Proposal)**
+- **Atoms (`@xstate/store`)**
     - Used exclusively for Actor ↔ Adapter communication
     - Enables synchronous, glitch-free propagation
 
@@ -43,26 +43,29 @@ The reference implementation provides a modular monorepo that satisfies the arch
 
 ## 3. Invariants
 
-1. **Actor Authority**  
+This document DEFINES the identifier of each invariant. Every other document and every
+source comment cites the identifier from this list, and it invents none of its own.
+
+1. **INV-01 — Actor Authority**  
    The Actor is the final authority on state and route validity.
 
-2. **Strict Separation**  
+2. **INV-02 — Strict Separation**  
    Business logic never depends on runtime APIs or routing libraries.
 
-3. **Signal-Only Reactivity**  
-   All cross-boundary communication uses standardized Signals.
+3. **INV-03 — Atom-Only Reactivity**  
+   All cross-boundary communication uses atoms.
 
-4. **Passive Infrastructure**  
+4. **INV-04 — Passive Infrastructure**  
    Runtime Adapters do not enforce guards, validation, or business rules.
 
-5. **State-Driven Reset**  
+5. **INV-05 — State-Driven Reset**  
    Invalid external navigation is always overwritten by Actor-derived state.
 
 ---
 
 ## 4. Core Mechanisms
 
-### 4.1 Reactive Substrate (Signals)
+### 4.1 Reactive Substrate (Atoms)
 
 - **Push–Pull Model**  
   The Actor pushes state updates; Adapters and Views pull computed values lazily.
@@ -89,7 +92,7 @@ The Actor has zero knowledge of:
 ### 4.3 Infrastructure Layer (Runtime Adapter)
 
 - **Watcher (Output)**  
-  Observes the Actor's _Intended Route_ signal and updates the environment accordingly.
+  Observes the Actor's _Intended Route_ atom and updates the environment accordingly.
 
 - **Reflector (Input)**  
   Listens to environment events (e.g. back/forward navigation) and forwards them as intents to the Actor.
@@ -105,19 +108,35 @@ If an intent is rejected:
 
 ### 5.1 Core Layer
 
-#### 5.1.1 `@xmachines/play-signals`
+#### 5.1.1 `@xmachines/play-atom`
 
 **Role:** Reactive Substrate
 
-Wraps the TC39 Signals (Stage 1) polyfill. By isolating the reactive primitive within this package, the ecosystem is protected from specification churn while providing the ergonomic API surface required by the rest of the architecture.
+Re-exports the atom of `@xstate/store`, whose reactive core adapts the Alien Signals algorithm. By isolating the reactive primitive within this package, the ecosystem is protected from churn in the underlying library while providing the ergonomic API surface required by the rest of the architecture.
 
 **Exports:**
 
-- `Signal` — Re-exported namespace from `signal-polyfill`:
-    - `Signal.State` — Actor output snapshot
-    - `Signal.Computed` — Lazy, pull-based derivation of routes and views
-    - `Signal.subtle.Watcher` — Synchronous observation for Runtime Adapters
-- `watchSignal` — Convenience function: subscribes to a single signal with a one-shot watcher lifecycle and microtask batching; returns a cleanup function
+- `createAtom(value)` — The writable atom. It holds the Actor output snapshot, and the derived view
+- `createAtom(fn)` — The computed atom. It derives a route from the snapshot, and it memoizes the result
+- `createWritableAtom(value)` — The writable atom, with one signature. Use it when the value type is a type parameter: the overload pair of `createAtom` reads an unresolved conditional type as a possible function, and it returns a `ReadonlyAtom`
+- `createAsyncAtom(fn)` — The computed atom of a promise, with a `pending`, `done` and `error` state
+- `watchAtom(atom, onValue)` — Convenience function: subscribes to one atom, coalesces the notifications into one microtask, and returns a cleanup function
+- The types `Atom`, `ReadonlyAtom`, `Readable`, `BaseAtom`, `AnyAtom` and `AtomOptions`
+
+**One instance:** `@xstate/store` is a PEER dependency, and it must resolve to ONE copy. The library holds the active subscriber in a module variable, so two copies track no dependency across a package boundary. `tests/singleton-peers.test.ts` holds this rule true for the workspace.
+
+**Two properties that a reader has to know:**
+
+- A subscription EVALUATES a computed atom, and it does not merely notify. `@xstate/store` builds the subscription on an effect that reads the atom, so a computed atom with a subscriber is eager, and a derivation runs one time for each write of a dependency. A computed atom with NO subscriber stays lazy, and it derives when a reader calls `get()`.
+- The propagation is SYNCHRONOUS, inside the `set` of the atom that changed, and the library exposes no batching. A callback that throws therefore throws inside that `set`, and an observer of two atoms is evaluated between two writes.
+
+**Therefore the Actor writes ONE atom for each transition.** `state` is that atom. `currentRoute` and `currentView` are computed atoms over it, so one write reaches both in one propagation and the engine orders the evaluation. Two writes would flush two times, and an observer of `state` and `currentView` would read the new state beside the old view in between.
+
+**A derivation of the Actor reports through `onError`, keeps its last good value, and throws never.** `currentRoute` and `currentView` both follow this rule. A subscriber makes a computed atom eager, so the derivation runs inside the `set` of `state`, inside the state-engine subscription: a throw that left it would unwind into the event dispatch and break the transition for every other observer. The containment therefore belongs to the derivation, and not to each subscriber — a consumer that writes its own `watchAtom(actor.currentRoute, …)` is protected by the same rule that protects a router bridge.
+
+The rule covers the reactive path. A pure helper such as `deriveCurrentRoute` still throws, because it holds no error channel and no previous value; its callers decide. Construction is the other caller: an unbuildable `initialRoute` fails the construction, which is where a developer wants to see it.
+
+Infrastructure that runs HOST code from a subscription contains that code by the same reasoning: `useAtomEffect` of [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) catches a throw of the host callback and throws it again from a microtask.
 
 #### 5.1.2 `@xmachines/play`
 
@@ -130,26 +149,37 @@ Exports the minimal shared contracts that allow the Logic Engine and Infrastruct
 - `PlayEvent<TPayload>` — Generic intent event dispatched from Infrastructure to Actor. Any object with `{ readonly type: string }` plus optional typed payload fields.
 - `PlayError` — Structured error base with `scope` and `code` fields for consistent error handling across all `@xmachines/*` packages.
 
-> **Note:** Routing contracts (`RouterBridge`, `PlayRouteEvent`) live in `@xmachines/play-router`, not here. This keeps the core protocol package dependency-free.
+> **Note:** Routing contracts (`RouterBridge`, `PlayRouteEvent`) live in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md), not here. This keeps the core protocol package dependency-free.
 
 #### 5.1.3 `@xmachines/play-actor`
 
 **Role:** Abstract Logic Engine
 
-Defines the minimal base class that all logic adapters must implement. By extending the XState `Actor` class, the `PlayActor` remains fully compatible with the XState ecosystem (inspection, system registration, message passing) while enforcing the Play Architecture's **push–pull signal contract**.
+Defines the minimal base class that all logic adapters must implement. By extending the XState `Actor` class, the `PlayActor` remains fully compatible with the XState ecosystem (inspection, system registration, message passing) while enforcing the Play Architecture's **push–pull atom contract**.
 
 The base class requires only two abstract members: **reactive state** and **typed event dispatch**. Routing and view rendering are opt-in via separate interfaces, allowing actors to compose only the capabilities they need.
 
-**Design Rationale:** The RFC declared an abstract `AbstractActor` CLASS that extended `Actor` of `xstate`, and it declared both capability interfaces in this package. The implementation made the contract an INTERFACE, `PlayActor`, because the class carried no implementation: both of its members were abstract, and its whole effect was to force the inheritance of XState on every consumer of the contract. `@xmachines/play-actor` names `xstate` nowhere now. The implementation also moved each capability interface to the package that holds its shared machinery: `Routable` is in `@xmachines/play-router`, beside the bridge that reads it, and `Viewable` and `PlaySpec` are in `@xmachines/play-view`, beside the view store lifecycle. A consumer who needs no routing and no view therefore installs neither package, and `@xmachines/play-actor` names the capability packages nowhere. The shape of each interface is unchanged.
+**Design Rationale:** The RFC declared an abstract `AbstractActor` CLASS that extended `Actor` of `xstate`, and it declared both capability interfaces in this package. The implementation made the contract an INTERFACE, `PlayActor`, because the class carried no implementation: both of its members were abstract, and its whole effect was to force the inheritance of XState on every consumer of the contract. [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) names `xstate` nowhere now. The implementation also moved each capability interface to the package that holds its shared machinery: `Routable` is in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md), beside the bridge that reads it, and `Viewable` and `PlaySpec` are in [`@xmachines/play-view`](../api/@xmachines/play-view/README.md), beside the view store lifecycle. A consumer who needs no routing and no view therefore installs neither package, and [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) names the capability packages nowhere. The shape of each interface is unchanged.
 
 ```ts
 import { Actor, type AnyActorLogic, type EventObject } from "xstate";
-import type { Signal } from "@xmachines/play-signals";
+import type {
+	AnyAtom,
+	Atom,
+	AtomOptions,
+	BaseAtom,
+	Readable,
+	ReadonlyAtom,
+	createAsyncAtom,
+	createAtom,
+	createWritableAtom,
+	watchAtom,
+} from "@xmachines/play-atom";
 import type { Spec } from "@xmachines/json-render-core";
 
 // Optional capability: Routing
 export interface Routable {
-	readonly currentRoute: Signal.Computed<string | null>;
+	readonly currentRoute: ReadonlyAtom<string | null>;
 	readonly initialRoute: string | null;
 }
 
@@ -168,7 +198,7 @@ export interface PlaySpec extends Spec {
 }
 
 export interface Viewable {
-	readonly currentView: Signal.State<PlaySpec | null>;
+	readonly currentView: ReadonlyAtom<PlaySpec | null>;
 }
 
 // The Base Protocol — minimal contract
@@ -177,7 +207,7 @@ export abstract class PlayActor<
 	TEvent extends EventObject = EventObject,
 > extends Actor<TLogic> {
 	// Reactive Output (Snapshot)
-	public abstract state: Signal.State<unknown>;
+	public abstract state: Atom<unknown>;
 
 	// Input Channel (typed for specific event shapes)
 	public abstract override send(event: TEvent): void;
@@ -211,7 +241,7 @@ Wraps XState v5 to satisfy the `PlayActor` contract. Provides the primary API fo
 **Responsibilities:**
 
 - Derive `currentRoute` and `currentView` from active state node metadata
-- Manage signal lifecycle (create on start, dispose on stop)
+- Manage atom lifecycle (create on start, dispose on stop)
 - Support snapshot restore for resumable sessions
 - Provide XState DevTools compatibility
 
@@ -236,7 +266,7 @@ class PlayerActor<TMachine extends AnyStateMachine>
 	extends Actor<AnyActorLogic>
 	implements PlayActor<SnapshotFrom<TMachine>, EventFromLogic<TMachine>>
 {
-	public state: Signal.State<SnapshotFrom<TMachine>>;
+	public state: Atom<SnapshotFrom<TMachine>>;
 }
 
 // A capability arrives through `compose`, and each one brings its own package
@@ -244,7 +274,7 @@ const RoutedPlayer = compose(PlayerActor, withRouting, withView);
 // RoutedPlayer instances hold `currentRoute`, `initialRoute` and `currentView`
 ```
 
-**Design Rationale:** The RFC made `PlayerActor` implement both capabilities directly. The implementation split them into mixins, because a direct implementation made `@xmachines/play-router` and `@xmachines/play-view` hard dependencies of every actor. Both packages are optional peer dependencies now: `definePlayer({ machine })` installs neither, `withRouting` needs `@xmachines/play-router`, and `withView` needs `@xmachines/play-view`.
+**Design Rationale:** The RFC made `PlayerActor` implement both capabilities directly. The implementation split them into mixins, because a direct implementation made [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) and [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) hard dependencies of every actor. Both packages are optional peer dependencies now: `definePlayer({ machine })` installs neither, `withRouting` needs [`@xmachines/play-router`](../api/@xmachines/play-router/README.md), and `withView` needs [`@xmachines/play-view`](../api/@xmachines/play-view/README.md).
 
 **Design Rationale:** The original design passed a `catalog` to `definePlayer` and returned `{ create, catalog }`. The implementation decoupled catalogs entirely — component schemas are defined via `@xmachines/json-render-core`'s `defineCatalog` and bound to renderers via `defineRegistry`, not to actors. This means a single actor can be rendered by different component libraries without change.
 
@@ -258,9 +288,10 @@ Provides the complete routing infrastructure: route extraction from state machin
 
 **Design Rationale:** The RFC put the whole of the routing in one package. The implementation split it at two boundaries, because a consumer paid for both halves and used one:
 
-- `@xmachines/play-router/xstate` holds the machine half — `extractMachineRoutes`, `createRouteMap`, `machineToGraph`, and the queries over a route tree. That half alone needs `xstate` and `@statelyai/graph`.
-- `@xmachines/play-url` holds the URL language — the URLPattern grammar, a base path, and the params of a framework router. It knows no machine and no bridge, and BOTH directions of the routing read it.
-- `@xmachines/play-router` keeps the route map, the match of a location, `RouterBridgeBase`, the provider lifecycle, and the `Routable` capability. It names no state machine.
+- [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) holds the machine half — `extractMachineRoutes`, `createRouteMap`, `machineToGraph`, and the queries over a route tree. That half alone needs `xstate` and `@statelyai/graph`.
+- [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md) holds the pattern LANGUAGE — one parse of the URLPattern pathname grammar, and the path that `buildPath` writes back from it. A parse is string work, so the package carries no URLPattern API and no polyfill. BOTH directions of the routing read it: the match of [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) reads the parse, and the routing capability of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) reads the same parse to build a URL, so that package installs no matching machinery.
+- [`@xmachines/play-url`](../api/@xmachines/play-url/README.md) holds the URL LAYER — the URLPattern API with its polyfill, a base path, a location splitter, and the params of a framework router. It reads [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md) for the language and re-exports it whole. It knows no machine and no bridge.
+- [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) keeps the route map, the match of a location, `RouterBridgeBase`, the provider lifecycle, and the `Routable` capability. It names no state machine.
 
 The export lists below name the original layout. Each package README names what it holds now.
 
@@ -268,7 +299,7 @@ The export lists below name the original layout. Each package README names what
 
 - `RouterBridge` — Interface: `{ connect(): void; disconnect(): void }`
 - `PlayRouteEvent` — Routing event: `{ type: 'play.route'; to: string; params?; query?; match? }`
-- `RouterBridgeBase` — Abstract base class that encapsulates common bridge logic (signal watching, route synchronization, param/query extraction). Subclasses implement only three methods:
+- `RouterBridgeBase` — Abstract base class that encapsulates common bridge logic (atom watching, route synchronization, param/query extraction). Subclasses implement only three methods:
     - `navigateRouter(path)` — Push a path into the framework router
     - `watchRouterChanges()` — Subscribe to framework router navigation events
     - `unwatchRouterChanges()` — Unsubscribe from framework router events
@@ -297,41 +328,41 @@ The export lists below name the original layout. Each package README names what
 
 Each adapter extends `RouterBridgeBase` and implements the three abstract methods for its target router. All share the same architectural pattern:
 
-| Package                                 | Router           | Framework |
-| --------------------------------------- | ---------------- | --------- |
-| `@xmachines/play-tanstack-react-router` | TanStack Router  | React     |
-| `@xmachines/play-tanstack-solid-router` | TanStack Router  | SolidJS   |
-| `@xmachines/play-react-router`          | React Router 7/8 | React     |
-| `@xmachines/play-vue-router`            | Vue Router 4/5   | Vue       |
-| `@xmachines/play-solid-router`          | SolidJS Router   | SolidJS   |
+| Package                                                                                           | Router           | Framework |
+| ------------------------------------------------------------------------------------------------- | ---------------- | --------- |
+| [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | TanStack Router  | React     |
+| [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | TanStack Router  | SolidJS   |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router 7/8 | React     |
+| [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | Vue Router 4/5   | Vue       |
+| [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | SolidJS Router   | SolidJS   |
 
 **Runtime Adapter Responsibilities (all adapters):**
 
 - **Input (Reflector):** Listen to router navigation events, extract params/query, send `PlayRouteEvent` to Actor
-- **Output (Watcher):** Observe Actor's `currentRoute` signal, call `navigateRouter()` when it changes
+- **Output (Watcher):** Observe Actor's `currentRoute` atom, call `navigateRouter()` when it changes
 - **Reset:** If Actor rejects a navigation (guard failure), the adapter overwrites the URL bar to match Actor state
 
 ### 5.4 View Layer
 
 #### 5.4.1 View Renderers
 
-Each view renderer provides a `PlayRenderer` component that passively observes the actor's `currentView` signal and projects the JSON spec into framework-native components via `@json-render`.
+Each view renderer provides a `PlayRenderer` component that passively observes the actor's `currentView` atom and projects the JSON spec into framework-native components via `@json-render`.
 
-| Package                 | Framework   | JSON-Render Backend            |
-| ----------------------- | ----------- | ------------------------------ |
-| `@xmachines/play-react` | React       | `@xmachines/json-render-react` |
-| `@xmachines/play-vue`   | Vue 3       | `@xmachines/json-render-vue`   |
-| `@xmachines/play-solid` | SolidJS     | `@xmachines/json-render-solid` |
-| `@xmachines/play-dom`   | Vanilla DOM | `@xmachines/json-render-core`  |
+| Package                                                           | Framework   | JSON-Render Backend            |
+| ----------------------------------------------------------------- | ----------- | ------------------------------ |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) | React       | `@xmachines/json-render-react` |
+| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)     | Vue 3       | `@xmachines/json-render-vue`   |
+| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md) | SolidJS     | `@xmachines/json-render-solid` |
+| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)     | Vanilla DOM | `@xmachines/json-render-core`  |
 
 **Shared Architecture (all renderers):**
 
-1. Subscribe to `actor.currentView` signal
+1. Subscribe to `actor.currentView` atom
 2. Resolve a `StateStore` (external or auto-created per view transition via `@xstate/store`)
 3. Wire `actions` prop to `actor.send()` via `ActionProvider`
 4. Render `spec` through the framework's `Renderer` with a `registry` (defined via `defineRegistry`)
 
-**`@xmachines/play-react` exports (representative):**
+**[`@xmachines/play-react`](../api/@xmachines/play-react/README.md) exports (representative):**
 
 ```ts
 // Batteries-included composite — standard entry point
@@ -340,7 +371,7 @@ Each view renderer provides a `PlayRenderer` component that passively observes t
 export { PlayUIProvider } from "./PlayUIProvider";
 export type { PlayUIProviderProps } from "./PlayUIProvider";
 
-// Escape-hatch primitive — owns actor lifecycle, signal bridge, ViewContext
+// Escape-hatch primitive — owns actor lifecycle, atom bridge, ViewContext
 // Props: actor, registryResult, store?, fallback?, onError?, onRenderError?, children (required)
 export { ActorProvider } from "./ActorProvider";
 export type { ActorProviderProps } from "./ActorProvider";
@@ -353,7 +384,7 @@ export const PlayRenderer: React.FC = () => {
 
 // Hooks
 export { usePlayView } from "./ActorProvider"; // returns ViewContextValue | null
-export { useSignalEffect } from "./useSignalEffect";
+export { useAtomEffect } from "./useAtomEffect";
 export { useActor } from "./useActor";
 
 // Error handling
@@ -371,7 +402,7 @@ export {
 } from "@xmachines/json-render-react";
 ```
 
-**Design Rationale:** `PlayRenderer` is now a **zero-prop leaf component** — it reads view context from the enclosing `ActorProvider` via `usePlayView()`. All mount-time concerns (actor bridging, signal subscription, store lifecycle, `onRenderError` injection) are centralised in `ActorProvider`. `PlayUIProvider` is the batteries-included composite that wraps `ActorProvider` + `JSONUIProvider` with a handler bridge. This mirrors the provider/renderer split in `@xmachines/json-render-*` and makes the separation of concerns explicit.
+**Design Rationale:** `PlayRenderer` is now a **zero-prop leaf component** — it reads view context from the enclosing `ActorProvider` via `usePlayView()`. All mount-time concerns (actor bridging, atom subscription, store lifecycle, `onRenderError` injection) are centralised in `ActorProvider`. `PlayUIProvider` is the batteries-included composite that wraps `ActorProvider` + `JSONUIProvider` with a handler bridge. This mirrors the provider/renderer split in `@xmachines/json-render-*` and makes the separation of concerns explicit.
 
 ### 5.5 Schema Layer (External)
 

package/api/@xmachines/play-react/functions/useSignalEffect.md

@@ -1,77 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-react](../README.md) / useSignalEffect
-
-# Function: useSignalEffect()
-
-```ts
-function useSignalEffect(callback, deps?): void;
-```
-
-Defined in: [packages/play-react/src/useSignalEffect.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/useSignalEffect.ts#L81)
-
-The React hook that subscribes to the signal changes and runs an effect callback
-
-The hook puts the callback in a Signal.Computed, which tracks each signal that
-the callback reads. It then gives the watcher lifecycle to `watchSignal` from
-`@xmachines/play-signals`. That function does the microtask batching, the new arm
-of the watcher, and the disposal. It is the one canonical implementation, and
-every framework renderer uses it.
-
-Architecture:
-
-- The hook puts the callback in a Signal.Computed for the dependency tracking
-- watchSignal owns the Signal.subtle.Watcher lifecycle (Phase 29, memory safety)
-- The microtask batching groups rapid signal updates
-- The callback triggers each new render with its own setState (see the remarks)
-- The hook cleans up on unmount, so that nothing stays in memory
-
-Invariant: Signal-Only Reactivity. The hook watches each signal that the callback reads.
-Invariant: Passive Infrastructure. React observes the signals, and it does not control them.
-
-## Parameters
-
-| Parameter  | Type                           | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ---------- | ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `callback` | () => `void` \| (() => `void`) | `undefined`   | The effect function that reads the signals. It can return a cleanup function.                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `deps`     | `DependencyList`               | `[]`          | The optional dependency list, as in useEffect. On a change of one dependency, the hook removes the watcher and the Computed, then makes them again and tracks the signals from the start. The default is `[]`, which subscribes one time for each mount. Give this list when the identity of the object whose signals you read can change during the life of the component, for example an `actor` prop. Without the list, the watcher tracks the signals of the OLD object for ever. |
-
-## Returns
-
-`void`
-
-## Example
-
-```typescript
-const MyComponent = ({ actor }) => {
-  const [view, setView] = useState(null);
-
-  // Subscribe to the actor.currentView signal, and subscribe again on a new actor
-  useSignalEffect(() => {
-    const currentView = actor.currentView.get();
-    setView(currentView);
-  }, [actor]);
-
-  return <div>{view?.root}</div>;
-};
-```
-
-## Remarks
-
-**CRITICAL:** read each signal unconditionally, with no `if` statement. A
-conditional read breaks the dependency tracking.
-
-**Performance:** the microtask batching (queueMicrotask, inside watchSignal)
-stops a flood of React renders when several signals update in rapid sequence.
-
-**Re-rendering:** the hook itself does NOT force a React render on a signal
-change. The callback triggers each new render, because it calls setState with the
-new signal value, as in the example above. The setState bailout of React can
-therefore skip a render when the derived value is the same. An unconditional
-force-update here caused one wasted render for each notification before, also
-when the setState of the callback made the bailout. If you must render again on
-every notification, and you read the signals during the render, copy the signal
-value into the React state inside the callback.
-
-**Implementation note:** the hook puts the callback in a Signal.Computed, because
-Signal.subtle.Watcher cannot track an arbitrary function call. The Computed does
-the dependency tracking. watchSignal evaluates the Computed, which runs the
-callback, on each change of a tracked signal.

package/api/@xmachines/play-router/index/functions/getPatternParamNames.md

@@ -1,29 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / getPatternParamNames
-
-# Function: getPatternParamNames()
-
-```ts
-function getPatternParamNames(pattern): string[];
-```
-
-Defined in: [packages/play-url/src/framework-params.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L26)
-
-Reads the names of every `:param` of a route pattern of the route map.
-
-The names come from the parse of `pattern-grammar.ts`, which reads the WHOLE grammar:
-a `{…}` group and a `(\d+)` constraint both hide a name from an expression that looks
-for `:name` alone. An ANONYMOUS param — `*` and a bare `(\d+)` — carries no name, and
-the list therefore holds none.
-
-## Parameters
-
-| Parameter | Type     | Description                                      |
-| --------- | -------- | ------------------------------------------------ |
-| `pattern` | `string` | A route pattern, for example `/profile/:userId`. |
-
-## Returns
-
-`string`[]
-
-The names, in the order that the pattern declares them. A fresh array, because
-`parsePattern` caches the parse that it reads.

package/api/@xmachines/play-router/index/functions/getRequiredPatternParamNames.md

@@ -1,39 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / getRequiredPatternParamNames
-
-# Function: getRequiredPatternParamNames()
-
-```ts
-function getRequiredPatternParamNames(pattern): string[];
-```
-
-Defined in: [packages/play-url/src/framework-params.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L52)
-
-The names of every param the pattern REQUIRES, so an optional one is left out.
-
-A param is optional when its own modifier is `?` or `*`, and when EVERY group above it
-carries one of the two. `?` alone was the test before, and it read `/files/:path*` and
-`/books{/:id}?` as required patterns: a path that fills neither then counted as a gap,
-the pick was discarded, and a correct parse from Vue Router or SolidJS Router went with
-it. That is the same class of defect as the all-optional bug of !133, for the modifiers
-that the fix did not cover.
-
-An optional segment that did not match has no value, and a framework reports none. That
-is a complete answer and not a partial one, so a MIXED pattern such as
-`/profile/:userId/:tab?` keeps the parse of the framework when only `:tab` is absent.
-
-A pattern whose params are ALL optional reports nothing at all, which reads the same as
-"the framework matched another route", so [pickOwnParams](pickOwnParams.md) falls back for it.
-[resolveFrameworkParams](resolveFrameworkParams.md) settles that case from the PATH instead.
-
-## Parameters
-
-| Parameter | Type     | Description                                            |
-| --------- | -------- | ------------------------------------------------------ |
-| `pattern` | `string` | A route pattern, for example `/profile/:userId/:tab?`. |
-
-## Returns
-
-`string`[]
-
-The required names, in the order that the pattern declares them. A fresh
-array, because `parsePattern` caches the parse that it reads.