@xmachines/docs 1.0.0-beta.10

package/api/@xmachines/play-solid-router/interfaces/RouterBridge.md

@@ -0,0 +1,104 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / RouterBridge
+
+# Interface: RouterBridge
+
+Defined in: packages/play-router/dist/types.d.ts:229
+
+RouterBridge interface for runtime infrastructure adapters
+
+Defines the lifecycle connection between Infrastructure (e.g., TanStack Router) and
+the Actor. Infrastructure "bridges" to the Actor by observing its signals and
+managing its own lifecycle accordingly.
+
+**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by establishing
+a unidirectional observation pattern. Infrastructure connects to observe Actor signals
+(currentRoute, currentView, state) and reflects changes without making state decisions.
+
+## Example
+
+TanStack Router bridge implementation
+
+```typescript
+import type { RouterBridge } from "@xmachines/play-router";
+import { Signal } from "@xmachines/play-signals";
+
+class TanStackRouterBridge implements RouterBridge {
+	private watcher: Signal.Watcher | null = null;
+
+	async connect(): Promise<void> {
+		// Start observing actor.currentRoute signal
+		this.watcher = new Signal.subtle.Watcher(() => {
+			const route = actor.currentRoute.get();
+			if (route) router.navigate(route);
+		});
+		this.watcher.watch(actor.currentRoute);
+	}
+
+	async disconnect(): Promise<void> {
+		// Stop observing, cleanup watchers
+		this.watcher?.unwatch(actor.currentRoute);
+		this.watcher = null;
+	}
+}
+```
+
+## See
+
+[RFC Play v1 - Invariant INV-04](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void | Promise<void>;
+```
+
+Defined in: packages/play-router/dist/types.d.ts:245
+
+Connect the router bridge to the Actor
+
+Called when Infrastructure should begin observing Actor signals and
+synchronizing its state (e.g., browser URL) with Actor state.
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when connection is established, or void for synchronous connection
+
+#### Example
+
+```typescript
+const bridge: RouterBridge = createBridge(actor, router);
+await bridge.connect();
+// Bridge now observing actor.currentRoute signal
+```
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void | Promise<void>;
+```
+
+Defined in: packages/play-router/dist/types.d.ts:260
+
+Disconnect the router bridge from the Actor
+
+Called when Infrastructure should stop observing and clean up resources
+(e.g., signal watchers, event listeners).
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when disconnection is complete, or void for synchronous disconnection
+
+#### Example
+
+```typescript
+await bridge.disconnect();
+// Bridge stopped observing, resources cleaned up
+```

package/api/@xmachines/play-solid-router/type-aliases/RoutableActor.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / RoutableActor
+
+# Type Alias: RoutableActor
+
+```ts
+type RoutableActor = AbstractActor<AnyActorLogic> & Routable & Viewable;
+```
+
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L7)

package/api/@xmachines/play-solid-router/type-aliases/SolidRouterHooks.md

@@ -0,0 +1,51 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / SolidRouterHooks
+
+# Type Alias: SolidRouterHooks
+
+```ts
+type SolidRouterHooks = object;
+```
+
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L8)
+
+## Properties
+
+### location
+
+```ts
+location: object;
+```
+
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L10)
+
+#### pathname
+
+```ts
+pathname: string;
+```
+
+#### search
+
+```ts
+search: string;
+```
+
+---
+
+### navigate
+
+```ts
+navigate: ((path) => void) | ((path, ...args) => unknown);
+```
+
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L9)
+
+---
+
+### params
+
+```ts
+params: Record<string, string | undefined>;
+```
+
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L11)

package/api/@xmachines/play-solid-router-demo/README.md

@@ -0,0 +1,127 @@
+[Documentation](../../README.md) / @xmachines/play-solid-router-demo
+
+# Solid Router Demo
+
+Solid + `@solidjs/router` demonstration of the Play architecture using provider-based router integration.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with Solid Router
+- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Canonical TC39 Signals lifecycle integration with Solid's fine-grained reactivity
+- Non-browser invariant tests plus browser E2E coverage
+
+## Running the Demo
+
+From this directory (`packages/play-solid-router/examples/demo`):
+
+```bash
+npm install
+npm run dev
+```
+
+Open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.tsx` bootstraps the demo and mounts the `<App />` component.
+2. `src/App.tsx` wires actor lifecycle, shared machine/catalog imports, and router integration.
+3. A `routeMap` is created by extracting routes from the shared `authMachine`.
+4. `PlayRouterProvider` forwards navigation intent from `@solidjs/router` to the actor, and reflects actor-approved routes back to the URL.
+5. `Shell` (inside `src/App.tsx`) renders actor-projected views (`PlayRenderer`) and provides the shared UI shell.
+6. `test/library-pattern.test.ts` and `test/browser/` verify invariants and runtime routing behavior.
+
+```tsx
+// src/main.tsx (shape)
+render(() => <App />, document.getElementById("root")!);
+```
+
+```tsx
+// src/App.tsx (shape)
+const createPlayer = definePlayer({ machine: authMachine, catalog });
+const actor = createPlayer();
+actor.start();
+
+const routeMap = createRouteMap(authMachine);
+
+<PlayRouterProvider
+	actor={actor}
+	routeMap={routeMap}
+	router={{ navigate, location, params }}
+	renderer={(currentActor, currentRouter) => (
+		<Shell actor={currentActor} router={currentRouter} />
+	)}
+/>;
+```
+
+```tsx
+// src/components/Nav.tsx (shape)
+<button onClick={() => actor.send({ type: "auth.logout" })}>Logout</button>
+```
+
+## Key Files
+
+- `src/App.tsx` - Integration entry point wiring actor, provider, renderer, and shared machine/catalog imports.
+- `src/main.tsx` - Vite bootstrap for the Solid app.
+- `src/components/` - Demo views and controls that send events to the actor.
+- `test/library-pattern.test.ts` - Node/Vitest invariant checks for architecture boundaries.
+- `test/browser/startup.browser.test.ts` - Browser startup and mount coverage.
+- `test/browser/auth-flow.browser.test.ts` - Browser auth and routing behavior coverage.
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** When a user navigates to a protected route, the Solid Router updates the URL. The `PlayRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g., is the user logged in?) and transitions to the appropriate state.
+2. **Passive Infrastructure:** Solid components hold no business state. They observe `actor.currentView` to know what to render, and `actor.currentRoute` to reflect the active path.
+3. **Signal-Only Reactivity:** Instead of React-like re-renders, Solid uses `createEffect` internally within the `RouterBridge` to react precisely when signals update.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and update Solid-local render triggers
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit and lifecycle-bound: Solid teardown uses `onCleanup`, and provider/bridge teardown must call `disconnect`/`unwatch` paths rather than relying on GC-only cleanup. This is crucial to prevent memory leaks during component unmounting.
+
+## Adapter Boundaries
+
+Solid Router integration remains passive infrastructure. `RouterBridgeBase` stays the shared policy point; the Solid adapter only implements framework port behavior (calling `navigate()` and tracking `location.pathname`).
+
+## Available Scripts
+
+```bash
+npm run dev           # Start Vite dev server (default: http://localhost:5173)
+npm run build         # Build production assets
+npm run preview       # Preview production build locally
+npm run test          # Run unit/integration tests via Vitest
+npm run test:browser  # Run browser-mode tests via vitest.browser.config.ts
+```
+
+## Verification
+
+Use these checks from this directory:
+
+```bash
+npm run test
+npm run test:browser
+```
+
+Manual sanity check:
+
+1. Start the app with `npm run dev`.
+2. Open `http://localhost:5173`.
+3. Confirm login/logout transitions update both view and URL, and that accessing protected routes while logged out redirects properly.
+
+## Learn More
+
+- [Solid Router package README](../play-solid-router/README.md)
+- [TanStack Solid Router demo README](../play-tanstack-solid-router-demo/README.md)
+- [TanStack React Router demo README](../play-tanstack-react-router-demo/README.md)

package/api/@xmachines/play-tanstack-react-router/README.md

@@ -0,0 +1,226 @@
+[Documentation](../../README.md) / @xmachines/play-tanstack-react-router
+
+# @xmachines/play-tanstack-react-router
+
+**TanStack React Router adapter for XMachines Play using the RouterBridge pattern.**
+
+## Overview
+
+`@xmachines/play-tanstack-react-router` connects a Play actor to TanStack Router through `TanStackReactRouterBridge`.
+
+The bridge extends `RouterBridgeBase` from `@xmachines/play-router`, so adapter behavior stays consistent across frameworks:
+
+- Actor route signal (`actor.currentRoute`) drives router navigation.
+- Router history events send `play.route` intents back to the actor.
+- Guarded state transitions remain actor-owned (Actor Authority).
+
+## Installation
+
+```bash
+npm install @tanstack/react-router react
+npm install @xmachines/play-tanstack-react-router @xmachines/play-router @xmachines/play-react
+```
+
+## Current Exports
+
+- `TanStackReactRouterBridge`
+- `RouteMap`, `createRouteMapFromTree`, `RouteMapping` (type)
+- `extractParams`, `extractQueryParams`
+- `PlayRouterProvider` + `PlayRouterProviderProps`
+- re-exports: `extractMachineRoutes`, `createRouteMap`, `RouterBridge`, `PlayRouteEvent`
+
+Peer dependencies:
+
+- `@tanstack/react-router` `^1.166.7`
+- `react` `^18 || ^19`
+- `xstate` `^5.0.0`
+
+## URLPattern Support
+
+This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching via `@xmachines/play-router`.
+
+URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+, Firefox 117+, Safari 16.4+). On older environments, load a polyfill **before** importing this package — see [`@xmachines/play-router` installation](../play-router/README.md) for details.
+
+## Quick Start
+
+```tsx
+import { createRouter } from "@tanstack/react-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { extractMachineRoutes } from "@xmachines/play-router";
+import {
+	TanStackReactRouterBridge,
+	createRouteMapFromTree,
+} from "@xmachines/play-tanstack-react-router";
+
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree);
+
+const router = createRouter({ routeTree: tanstackRouteTree });
+
+const actor = definePlayer({ machine, catalog })();
+actor.start();
+
+const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
+bridge.connect();
+
+// later
+bridge.disconnect();
+```
+
+### React convenience wrapper
+
+Use `PlayRouterProvider` when you want bridge lifecycle wiring in a component:
+
+```tsx
+import { PlayRenderer } from "@xmachines/play-react";
+
+<PlayRouterProvider
+	actor={actor}
+	router={router}
+	routeMap={routeMap}
+	renderer={(currentActor, currentRouter) => (
+		<PlayRenderer actor={currentActor} components={components} />
+	)}
+/>;
+```
+
+## API
+
+### `TanStackReactRouterBridge`
+
+Primary adapter class.
+
+```ts
+class TanStackReactRouterBridge implements RouterBridge {
+	constructor(
+		router: TanStackRouterLike,
+		actor: AbstractActor<AnyActorLogic> & Routable,
+		routeMap: RouteMap,
+	);
+	connect(): void;
+	disconnect(): void;
+}
+```
+
+### `RouteMap` and `createRouteMapFromTree`
+
+Map state IDs to URL paths and resolve URLs back to state IDs.
+
+`RouteMap` extends `BaseRouteMap` from `@xmachines/play-router`, inheriting bucket-indexed
+bidirectional route matching. No routing logic lives in the adapter itself.
+
+```ts
+// RouteMap is a thin subclass of BaseRouteMap — no extra methods
+class RouteMap extends BaseRouteMap {}
+
+// Inherited API:
+routeMap.getStateIdByPath(path: string): string | null
+routeMap.getPathByStateId(stateId: string): string | null
+
+// Factory from a machine route tree:
+function createRouteMapFromTree(routeTree: RouteTree): RouteMap
+```
+
+`getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
+
+```ts
+const routeMap = new RouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
+
+routeMap.getStateIdByPath("/profile/123"); // "profile"
+routeMap.getPathByStateId("home"); // "/"
+routeMap.getStateIdByPath("/unknown"); // null
+```
+
+### `PlayRouterProvider`
+
+React wrapper around `TanStackReactRouterBridge`.
+
+```ts
+interface PlayRouterProviderProps {
+	actor: AbstractActor<AnyActorLogic> & Routable & Viewable;
+	router: TanStackRouterLike;
+	routeMap: RouteMap;
+	renderer: (
+		actor: AbstractActor<AnyActorLogic> & Routable & Viewable,
+		router: TanStackRouterLike,
+	) => ReactNode;
+}
+```
+
+### Utilities and re-exports
+
+- `extractParams`, `extractQueryParams`
+- `extractMachineRoutes`, `createRouteMap` (re-exported from `@xmachines/play-router`)
+- `RouterBridge`, `PlayRouteEvent` types
+
+## Examples
+
+- Multi-router integration guide: `docs/examples/multi-router-integration.md`
+- Routing patterns guide: `docs/examples/routing-patterns.md`
+
+## Architecture
+
+Bridge-first flow:
+
+1. `RouterBridgeBase.connect()` performs initial actor/router synchronization.
+2. Actor route updates call TanStack navigation (`router.navigate({ to })`).
+3. TanStack history updates are subscribed and translated to `play.route` events.
+4. Actor guards accept or reject transitions; infrastructure reflects resulting state.
+
+This keeps routing infrastructure passive while preserving business-logic control.
+
+## Historical Note
+
+`SignalSyncedHistory` and `createPlayRouter` are legacy migration-era APIs and are not part of the current quick-start path. Use `TanStackReactRouterBridge` + `RouteMap` for new integrations.
+
+## Related Packages
+
+- [@xmachines/play-router](../play-router/README.md)
+- [@xmachines/play-xstate](../play-xstate/README.md)
+- [@xmachines/play-react](../play-react/README.md)
+
+## License
+
+Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT>.
+
+@xmachines/play-tanstack-react-router
+
+TanStack Router adapter for XMachines Play architecture.
+Synchronizes browser URL with actor state through passive infrastructure.
+
+## Classes
+
+- [RouteMap](classes/RouteMap.md)
+- [TanStackReactRouterBridge](classes/TanStackReactRouterBridge.md)
+
+## Interfaces
+
+- [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
+- [RouteMapping](interfaces/RouteMapping.md)
+- [RouteNavigateEvent](interfaces/RouteNavigateEvent.md)
+- [RouterBridge](interfaces/RouterBridge.md)
+
+## Type Aliases
+
+- [TanStackRouterInstance](type-aliases/TanStackRouterInstance.md)
+- [TanStackRouterLike](type-aliases/TanStackRouterLike.md)
+
+## Variables
+
+- [extractMachineRoutes](variables/extractMachineRoutes.md)
+
+## Functions
+
+- [createRouteMap](functions/createRouteMap.md)
+- [createRouteMapFromTree](functions/createRouteMapFromTree.md)
+- [extractParams](functions/extractParams.md)
+- [extractQueryParams](functions/extractQueryParams.md)
+- [PlayRouterProvider](functions/PlayRouterProvider.md)

package/api/@xmachines/play-tanstack-react-router/classes/RouteMap.md

@@ -0,0 +1,137 @@
+[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouteMap
+
+# Class: RouteMap
+
+Defined in: [play-tanstack-react-router/src/route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/route-map.ts#L54)
+
+Bidirectional route mapper for TanStack React Router.
+
+Extends [BaseRouteMap](../../play-router/classes/BaseRouteMap.md) — all matching logic lives there.
+This class exists to provide a TanStack React Router-specific type name and to
+allow future adapter-specific extensions without breaking the shared base.
+
+**Inherited API:**
+
+- `getStateIdByPath(path): string | null` — path → state ID
+- `getPathByStateId(stateId): string | null` — state ID → path pattern
+
+## Example
+
+```typescript
+const routeMap = new RouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
+
+routeMap.getStateIdByPath("/profile/123"); // "profile"
+routeMap.getPathByStateId("home"); // "/"
+```
+
+## Extends
+
+- [`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new RouteMap(mappings): RouteMap;
+```
+
+Defined in: play-router/dist/base-route-map.d.ts:81
+
+Build a route map from an array of state ID ↔ path mappings.
+
+Static paths (no `:param`) are indexed in an O(1) `Map`.
+Parameterized paths are compiled to `RegExp` and grouped into first-segment
+buckets for efficient candidate selection.
+
+#### Parameters
+
+| Parameter  | Type                                                                     | Description                                                                                                       |
+| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `mappings` | [`BaseRouteMapping`](../../play-router/interfaces/BaseRouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path. |
+
+#### Returns
+
+`RouteMap`
+
+#### Inherited from
+
+[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`constructor`](../../play-router/classes/BaseRouteMap.md#constructor)
+
+## Methods
+
+### getPathByStateId()
+
+```ts
+getPathByStateId(stateId): string | null;
+```
+
+Defined in: play-router/dist/base-route-map.d.ts:111
+
+Look up the path pattern registered for a state ID.
+
+#### Parameters
+
+| Parameter | Type     | Description                                               |
+| --------- | -------- | --------------------------------------------------------- |
+| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The registered path pattern, or `null` if the state ID is unknown
+
+#### Example
+
+```typescript
+map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("missing"); // null
+```
+
+#### Inherited from
+
+[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getPathByStateId`](../../play-router/classes/BaseRouteMap.md#getpathbystateid)
+
+---
+
+### getStateIdByPath()
+
+```ts
+getStateIdByPath(path): string | null;
+```
+
+Defined in: play-router/dist/base-route-map.d.ts:98
+
+Resolve a URL path to its mapped state ID.
+
+Strips query strings and hash fragments before matching. Tries an O(1) exact
+lookup first, then falls back to bucket-indexed pattern matching. Results are
+cached after the first pattern match.
+
+#### Parameters
+
+| Parameter | Type     | Description                                                                    |
+| --------- | -------- | ------------------------------------------------------------------------------ |
+| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The mapped state ID, or `null` if no route matches
+
+#### Example
+
+```typescript
+map.getStateIdByPath("/profile/123"); // "profile"
+map.getStateIdByPath("/unknown"); // null
+```
+
+#### Inherited from
+
+[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getStateIdByPath`](../../play-router/classes/BaseRouteMap.md#getstateidbypath)