@xmachines/docs 1.0.0-beta.10

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

@@ -0,0 +1,285 @@
+[Documentation](../../README.md) / @xmachines/play-tanstack-solid-router
+
+# @xmachines/play-tanstack-solid-router
+
+**TanStack Solid Router adapter for XMachines Universal Player Architecture**
+
+Signals-native integration with TanStack Solid Router enabling logic-driven navigation through Solid.js reactivity.
+
+## Overview
+
+`@xmachines/play-tanstack-solid-router` provides seamless integration between TanStack Solid Router and XMachines state machines. Built on Solid's reactive primitives, it implements the `RouterBridgeBase` pattern for bidirectional synchronization while remaining framework-swappable.
+
+Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+
+- **Actor Authority (INV-01):** State machine controls navigation, router reflects decisions
+- **Passive Infrastructure (INV-04):** Router observes `actor.currentRoute` signal
+- **Signal-Only Reactivity (INV-05):** `createEffect` synchronizes URL with actor state
+
+**Key Benefits:**
+
+- **Signals-native:** Zero adaptation layer between Solid signals and TC39 Signals
+- **Bridge-first:** Extends shared `RouterBridgeBase` policy used by other adapters
+- **Automatic tracking:** `createEffect` handles dependency tracking (no manual Watcher setup needed for the bridge)
+- **Logic-driven navigation:** Business logic in state machines, not components
+- **Type-safe parameters:** Route params flow through state machine context
+
+**Framework Compatibility:**
+
+- TanStack Solid Router 1.100.0+
+- SolidJS 1.8.0+
+- TC39 Signals polyfill integration
+
+## Installation
+
+```bash
+npm install @tanstack/solid-router@^1.108.0 solid-js@^1.8.0 @xmachines/play-tanstack-solid-router @xmachines/play-solid
+```
+
+**Peer dependencies:**
+
+- `@tanstack/solid-router` ^1.108.0 - TanStack Solid Router library
+- `solid-js` ^1.8.0 - SolidJS runtime
+- `@xmachines/play-solid` - Solid renderer (`PlayRenderer`)
+- `@xmachines/play-actor` - Actor base
+- `@xmachines/play-router` - Route extraction
+- `@xmachines/play-signals` - TC39 Signals polyfill
+
+## Quick Start
+
+```tsx
+import { Router, createRouter } from "@tanstack/solid-router";
+import { PlayTanStackRouterProvider, createRouteMap } from "@xmachines/play-tanstack-solid-router";
+import { PlayRenderer } from "@xmachines/play-solid";
+import { definePlayer } from "@xmachines/play-xstate";
+import { routeTree as routerRouteTree } from "./routeTree.gen"; // from TanStack
+
+function App() {
+	// 1. Create player with state machine
+	const createPlayer = definePlayer({
+		machine: authMachine,
+		catalog: componentCatalog,
+	});
+	const actor = createPlayer();
+	actor.start();
+
+	// 2. Create TanStack router instance
+	const router = createRouter({ routeTree: routerRouteTree });
+
+	// 3. Create route mapping from machine routes
+	const routeMap = createRouteMap(authMachine);
+
+	return (
+		// 4. Wrap with provider to sync actor and router
+		<PlayTanStackRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor, currentRouter) => (
+				<Router router={currentRouter}>
+					<PlayRenderer actor={currentActor} components={components} />
+				</Router>
+			)}
+		/>
+	);
+}
+```
+
+## API Reference
+
+### `SolidRouterBridge`
+
+Router adapter implementing the `RouterBridge` protocol for TanStack Solid Router.
+
+**Type Signature:**
+
+```typescript
+class SolidRouterBridge {
+	constructor(router: Router, actor: AbstractActor<any>, routeMap: RouteMap);
+	dispose(): void;
+}
+```
+
+**Constructor Parameters:**
+
+- `router` - TanStack Solid Router instance
+- `actor` - XMachines actor instance
+- `routeMap` - Bidirectional state ID ↔ path mapping
+
+**Methods:**
+
+- `connect()` - Start bidirectional synchronization.
+- `disconnect()` - Stop synchronization and cleanup bridge resources.
+- `dispose()` - Alias of `disconnect()`.
+
+**Internal Behavior:**
+
+- Uses `RouterBridgeBase` TC39 watcher lifecycle for actor→router synchronization
+- Updates TanStack Router via `router.navigate({ to: path })` when actor state changes
+- Uses `router.subscribe` to watch history navigation events
+- Sends `play.route` events to actor when user navigates
+
+### `PlayTanStackRouterProvider`
+
+A Solid component that automatically sets up, connects, and tears down the `SolidRouterBridge` using Solid's lifecycle.
+
+```tsx
+interface PlayTanStackRouterProviderProps {
+	actor: AbstractActor<any>;
+	router: Router;
+	routeMap: RouteMap;
+	renderer: (actor: AbstractActor<any>, router: Router) => JSX.Element;
+}
+```
+
+**Props:**
+
+- `actor` - The XMachines player actor
+- `router` - The TanStack Solid Router instance
+- `routeMap` - Mapping between paths and state IDs
+- `renderer` - A render prop function that receives the active actor and router
+
+**Behavior:**
+
+1. Instantiates `SolidRouterBridge` on mount
+2. Calls `bridge.connect()`
+3. Renders the content returned by the `renderer` function
+4. Calls `bridge.disconnect()` when the component unmounts via `onCleanup`
+
+### `createRouteMap()`
+
+Helper to build a `RouteMap` instance directly from an XState machine.
+
+**Signature:**
+
+```typescript
+function createRouteMap(machine: AnyStateMachine): RouteMap;
+```
+
+**Usage:**
+
+```typescript
+import { createRouteMap } from "@xmachines/play-tanstack-solid-router";
+
+const routeMap = createRouteMap(machine);
+```
+
+## Usage Patterns
+
+### Dynamic Routes with Parameters
+
+TanStack Router and URLPattern (used internally) support dynamic route matching syntax:
+
+```typescript
+// Machine configuration
+const machineConfig = {
+	states: {
+		profile: {
+			meta: {
+				route: "/profile/:userId",
+				view: { component: "Profile" },
+			},
+		},
+	},
+};
+
+// Route mapping will natively support URLPattern parameters
+routeMap.getStateIdByPath("/profile/123"); // → '#profile'
+```
+
+### Protected Routes and Guards
+
+With XMachines, auth guards are handled entirely inside the state machine, preventing flashes of unauthorized content.
+
+```typescript
+// Machine side
+dashboard: {
+  meta: { route: "/dashboard", view: { component: "Dashboard" } },
+  always: {
+    guard: ({ context }) => !context.isAuthenticated,
+    target: "login"
+  }
+}
+```
+
+When a user navigates to `/dashboard`:
+
+1. TanStack Router updates location
+2. Bridge intercepts and sends `play.route`
+3. Actor evaluates guard -> denies target, transitions to `login` instead
+4. Bridge observes new actor state (`/login`)
+5. Bridge tells TanStack Router to redirect to `/login`
+
+## Circular Update Prevention
+
+The `RouterBridgeBase` architecture prevents infinite loops between router and actor using two mechanisms:
+
+1. **`lastSyncedPath` tracking:** Stores the last synchronized path to prevent redundant navigations back to the identical location.
+2. **`isProcessingNavigation` flag:** Set during a router event, preventing the router from immediately reacting to the actor's synchronous state update.
+
+## Comparison with @solidjs/router Adapter
+
+| Aspect            | @solidjs/router Adapter          | @tanstack/solid-router Adapter  |
+| ----------------- | -------------------------------- | ------------------------------- |
+| **Router API**    | `navigate(path)`                 | `router.navigate({ to })`       |
+| **Setup Context** | Must be _inside_ Router context  | Can wrap Router instance        |
+| **State Source**  | Uses Solid hooks (`useLocation`) | Subscribes to `router` directly |
+| **Reacting**      | `createEffect` on location       | `router.subscribe` callback     |
+
+## Architecture
+
+This package implements standard Play invariants:
+
+### INV-01: Actor Authority
+
+State machine has final authority over all transitions. TanStack Router navigation triggers actor events (`play.route`), but the actor's guards and transitions ultimately dictate if the view changes.
+
+### INV-02: Passive Infrastructure
+
+Infrastructure reflects actor state. The router observes `actor.currentRoute` and updates the browser URL, never storing independent business state.
+
+### Cleanup Contract
+
+The bridge implements an explicit `dispose()`/`disconnect()` method. `PlayTanStackRouterProvider` wires this automatically to Solid's `onCleanup` hook to prevent memory leaks and duplicate bridge subscriptions in hot-reloading scenarios.
+
+## URLPattern Support
+
+This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for robust 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.
+
+## Related Packages
+
+- **[@xmachines/play-solid](../play-solid/README.md)** - SolidJS renderer
+- **[@xmachines/play-router](../play-router/README.md)** - Core router primitives
+- **[@xmachines/play-solid-router](../play-solid-router/README.md)** - Native SolidJS Router equivalent
+
+## 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>.
+
+## Classes
+
+- [RouteMap](classes/RouteMap.md)
+- [SolidRouterBridge](classes/SolidRouterBridge.md)
+
+## Interfaces
+
+- [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
+- [RouteMapping](interfaces/RouteMapping.md)
+- [RouterBridge](interfaces/RouterBridge.md)
+
+## Type Aliases
+
+- [RoutableActor](type-aliases/RoutableActor.md)
+- [TanStackRouterInstance](type-aliases/TanStackRouterInstance.md)
+- [TanStackRouterLike](type-aliases/TanStackRouterLike.md)
+
+## Functions
+
+- [createRouteMap](functions/createRouteMap.md)
+- [PlayRouterProvider](functions/PlayRouterProvider.md)

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

@@ -0,0 +1,150 @@
+[Documentation](../../../README.md) / [@xmachines/play-tanstack-solid-router](../README.md) / RouteMap
+
+# Class: RouteMap
+
+Defined in: [play-tanstack-solid-router/src/route-map.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-solid-router/src/route-map.ts#L26)
+
+Shared bidirectional route map base class.
+
+All framework adapter `RouteMap` classes extend this — they add no logic of their
+own and inherit the full public API from here.
+
+**Lookup strategy:**
+
+- Static paths (no `:param`) → O(1) `Map` lookup
+- Dynamic paths → O(k) bucket-indexed scan using `RegExp`, where `k` is the number
+  of routes sharing the same first path segment
+- Results are cached after the first match
+
+**Pattern syntax** (`:param` / `:param?`):
+
+- `:param` — required segment, matches exactly one non-`/` segment
+- `:param?` — optional segment, matches zero or one non-`/` segment
+
+## Example
+
+```typescript
+import { BaseRouteMap } from "@xmachines/play-router";
+
+const map = new BaseRouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
+
+map.getStateIdByPath("/"); // "home"
+map.getStateIdByPath("/profile/123"); // "profile"
+map.getStateIdByPath("/settings"); // "settings"
+map.getStateIdByPath("/unknown"); // null
+
+map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("missing"); // null
+```
+
+## 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)