@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.50

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

@@ -1,258 +1,283 @@
 [API](../../README.md) / @xmachines/play-tanstack-solid-router
 
+<!-- generated-by: gsd-doc-writer -->
+
 # @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 [Play RFC](../../../rfc/play.md), this package implements:
+Part of the [xmachines-js](../../README.md) monorepo.
 
-- **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:**
+## Overview
 
-- **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
+[`@xmachines/play-tanstack-solid-router`](README.md) connects a Play actor to TanStack Solid Router through `SolidRouterBridge`.
 
-**Framework Compatibility:**
+The bridge extends `RouterBridgeBase` from [`@xmachines/play-router`](../play-router/README.md), keeping adapter behavior consistent across frameworks:
 
-- TanStack Solid Router 1.100.0+
-- SolidJS 1.8.0+
-- TC39 Signals polyfill integration
+- 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).
+- Circular update prevention built into `RouterBridgeBase`.
 
 ## Installation
 
 ```bash
-npm install @tanstack/solid-router@^1.108.0 solid-js@^1.8.0 @xmachines/play-tanstack-solid-router @xmachines/play-solid
+npm install @tanstack/solid-router solid-js
+npm install @xmachines/play-tanstack-solid-router @xmachines/play-router
 ```
 
 **Peer dependencies:**
 
-- `@tanstack/solid-router` ^1.108.0 - TanStack Solid Router library
-- `solid-js` ^1.8.0 - SolidJS runtime
-  -)
--   - Actor base
--   - Route extraction
--   - TC39 Signals polyfill
+- `@tanstack/solid-router` `^1.168.7`
+- `solid-js` `^1.8.0`
+- `xstate` `^5.30.0`
+
+## Current Exports
+
+- `SolidRouterBridge` — primary adapter class
+- `PlayRouterProvider` — Solid component wrapper for bridge lifecycle
+- `PlayRouterProviderProps`, `RoutableActor`, `TanStackRouterInstance` (types)
+- `RouteMap`, `createRouteMap`, `RouteMapping`, `RouteMapOptions` (re-exported from `@xmachines/play-router`)
+- `TanStackRouterLike` (type)
+- `RouterBridge`, `PlayRouteEvent` (types)
+
+## 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`](../play-router/README.md).
+
+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`](../play-router/README.md) for details.
 
 ## 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 { createRouter } from "@tanstack/solid-router";
 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>
-			)}
-		/>
-	);
-}
-```
+import { extractMachineRoutes } from "@xmachines/play-router";
+import { SolidRouterBridge, createRouteMap } from "@xmachines/play-tanstack-solid-router";
 
-## API Reference
-
-### `SolidRouterBridge`
+const routeMap = createRouteMap(machine);
+const router = createRouter({ routeTree: tanstackRouteTree });
 
-Router adapter implementing the `RouterBridge` protocol for TanStack Solid Router.
+const actor = definePlayer({ machine })();
+actor.start();
 
-**Type Signature:**
+const bridge = new SolidRouterBridge(router, actor, routeMap);
+bridge.connect();
 
-```typescript
-class SolidRouterBridge {
-	constructor(router: Router, actor: AbstractActor<any>, routeMap: RouteMap);
-	dispose(): void;
-}
+// later
+bridge.disconnect();
 ```
 
-**Constructor Parameters:**
-
-- `router` - TanStack Solid Router instance
-- `actor` - XMachines actor instance
-- `routeMap` - Bidirectional state ID ↔ path mapping
+### Solid convenience wrapper
 
-**Methods:**
+Use `PlayRouterProvider` when you want bridge lifecycle wiring managed by a component:
 
-- `connect()` - Start bidirectional synchronization. Both pathname and query string from `router.history.location` are forwarded to the actor on first connect.
-- `disconnect()` - Stop synchronization and cleanup bridge resources.
-- `dispose()` - Alias of `disconnect()`.
-
-**Internal Behavior:**
+```tsx
+import { PlayRouterProvider } from "@xmachines/play-tanstack-solid-router";
+import { RouterProvider } from "@tanstack/solid-router";
+
+<PlayRouterProvider
+	actor={actor}
+	router={router}
+	routeMap={routeMap}
+	renderer={(currentActor, currentRouter) => (
+		<RouterProvider router={currentRouter}>{/* your app here */}</RouterProvider>
+	)}
+/>;
+```
 
-- Uses `RouterBridgeBase` TC39 watcher lifecycle for actor→router synchronization
-- Updates TanStack Router via `router.navigate({ to: path })` when actor state changes
-- Uses `router.history.subscribe` to watch history navigation events (covers PUSH, POP, BACK, FORWARD — works without `<RouterProvider>` mounted)
-- Sends `play.route` events to actor when user navigates
+## API
 
-### `PlayTanStackRouterProvider`
+### `SolidRouterBridge`
 
-A Solid component that automatically sets up, connects, and tears down the `SolidRouterBridge` using Solid's lifecycle.
+Primary adapter class extending `RouterBridgeBase`.
 
-```tsx
-interface PlayTanStackRouterProviderProps {
-	actor: AbstractActor<any>;
-	router: Router;
-	routeMap: RouteMap;
-	renderer: (actor: AbstractActor<any>, router: Router) => JSX.Element;
+```ts
+class SolidRouterBridge {
+	constructor(
+		router: TanStackRouterLike,
+		actor: AbstractActor<AnyActorLogic> & Routable,
+		routeMap: RouteMap,
+	);
+	connect(): void;
+	disconnect(): void;
+	dispose(): void; // alias for disconnect()
 }
 ```
 
-**Props:**
+**Behavior:**
 
-- `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
+- `connect()` — subscribes to `router.history`, performs initial deep-link sync from `router.history.location`, and starts watching `actor.currentRoute` for state-driven navigation.
+- `disconnect()` — unsubscribes from history and stops all sync.
+- Navigates via `router.navigate({ to: path })`.
+- Subscribes via `router.history.subscribe` — covers PUSH, POP, BACK, FORWARD, REPLACE, and GO, and works without `<RouterProvider>` mounted.
 
-**Behavior:**
+### `PlayRouterProvider`
 
-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`
+Solid component that instantiates, connects, and cleans up a `SolidRouterBridge` automatically.
 
-### `createRouteMap()`
+```ts
+interface PlayRouterProviderProps<TActor extends RoutableActor = RoutableActor> {
+	/** The actor to sync with TanStack Solid Router. */
+	actor: TActor;
+	/** The TanStack Router instance returned by `createRouter`. */
+	router: TanStackRouterInstance;
+	/** Bidirectional route map for state ID ↔ URL path lookups. */
+	routeMap: RouteMap;
+	/** Renderer callback receives the same concrete actor type that was passed in. */
+	renderer: (actor: TActor, router: TanStackRouterInstance) => JSX.Element;
+}
+```
 
-Helper to build a `RouteMap` instance directly from an XState machine.
+The bridge is created synchronously at component evaluation time (Solid's execution model) and torn down via `onCleanup` when the component is disposed.
 
-**Signature:**
+### `RouteMap` and `createRouteMap`
 
-```typescript
-function createRouteMap(machine: AnyStateMachine): RouteMap;
-```
+Map state IDs to URL paths and resolve URLs back to state IDs.
 
-**Usage:**
+```ts
+const routeMap = new RouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
 
-```typescript
-import { createRouteMap } from "@xmachines/play-tanstack-solid-router";
+routeMap.getStateIdByPath("/profile/123"); // "profile"
+routeMap.getPathByStateId("home"); // "/"
+routeMap.getStateIdByPath("/unknown"); // null
 
+// Or build from a machine directly:
+import { createRouteMap } from "@xmachines/play-tanstack-solid-router";
 const routeMap = createRouteMap(machine);
 ```
 
+`getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
+
 ## Usage Patterns
 
 ### Dynamic Routes with Parameters
 
-TanStack Router and URLPattern (used internally) support dynamic route matching syntax:
+```ts
+const routeMap = new RouteMap([
+	{ stateId: "post", path: "/users/:userId/posts/:postId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
+
+// Params are extracted and forwarded in the play.route event:
+// { type: "play.route", to: "#post", params: { userId: "123", postId: "456" }, query: {} }
+```
+
+### Protected Routes and Guards
+
+Auth guards live entirely inside the state machine, preventing flashes of unauthorized content:
 
-```typescript
-// Machine configuration
+```ts
 const machineConfig = {
 	states: {
-		profile: {
-			meta: {
-				route: "/profile/:userId",
-				view: { component: "Profile" },
+		dashboard: {
+			meta: { route: "/dashboard" },
+			always: {
+				guard: ({ context }) => !context.isAuthenticated,
+				target: "login",
 			},
 		},
 	},
 };
-
-// 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`:
+When a user navigates to `/dashboard` while unauthenticated:
 
-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`
+1. TanStack Router updates location.
+2. Bridge intercepts and sends `play.route` to the actor.
+3. Actor evaluates the guard — denies transition, moves to `login` instead.
+4. Bridge observes new actor route (`/login`).
+5. Bridge calls `router.navigate({ to: "/login" })`.
 
-## Circular Update Prevention
+### Full App Example
 
-The `RouterBridgeBase` architecture prevents infinite loops between router and actor using two mechanisms:
+```tsx
+import { createRouter, RouterProvider, createRootRoute, createRoute } from "@tanstack/solid-router";
+import { onCleanup } from "solid-js";
+import { PlayRouterProvider, createRouteMap } from "@xmachines/play-tanstack-solid-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
+
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer();
+actor.start();
+
+const routeMap = createRouteMap(authMachine);
+const routeTree = extractMachineRoutes(authMachine);
+const routes = getRoutableRoutes(routeTree);
+
+const rootRoute = createRootRoute({
+	component: () => {
+		onCleanup(() => actor.stop());
+		return (
+			<PlayRouterProvider
+				actor={actor}
+				router={router}
+				routeMap={routeMap}
+				renderer={(currentActor, currentRouter) => (
+					/* your shell/renderer here */
+					<div />
+				)}
+			/>
+		);
+	},
+});
 
-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.
+const tanstackRoutes = routes.map((route) =>
+	createRoute({
+		getParentRoute: () => rootRoute,
+		path: route.fullPath.replace(/:(\w+)/g, "$$$1"),
+		component: () => null,
+	}),
+);
 
-## Comparison with @solidjs/router Adapter
+export const router = createRouter({ routeTree: rootRoute.addChildren(tanstackRoutes) });
 
-| 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.history.subscribe` callback |
+export default function App() {
+	return <RouterProvider router={router} />;
+}
+```
 
 ## Architecture
 
-This package implements standard Play invariants:
+Bridge-first data flow:
 
-### INV-01: Actor Authority
+1. `RouterBridgeBase.connect()` performs initial actor/router synchronization — both pathname and query string from `router.history.location` are forwarded to the actor on first connect.
+2. Actor route updates (`actor.currentRoute` signal) call TanStack navigation (`router.navigate({ to })`).
+3. TanStack history updates are subscribed and translated to `play.route` events sent to the actor.
+4. Actor guards accept or reject transitions; infrastructure reflects resulting state.
 
-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.
+This keeps routing infrastructure passive while preserving business-logic control in the state machine.
 
-### INV-02: Passive Infrastructure
+## Testing
 
-Infrastructure reflects actor state. The router observes `actor.currentRoute` and updates the browser URL, never storing independent business state.
+Run tests for this package in isolation:
 
-### 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.
+```bash
+npm test -w packages/play-tanstack-solid-router
+```
 
-## URLPattern Support
+Or from the package directory:
 
-This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for robust route pattern matching via.
+```bash
+npm test
+```
 
-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`](../play-router/README.md) for details.
+Coverage thresholds: lines 80%, functions 80%, branches 70%, statements 80%.
 
 ## 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
+- [@xmachines/play-router](../play-router/README.md) — core router primitives and `RouterBridgeBase`
+- [@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md) — TanStack Router (React) equivalent
+- [@xmachines/play-solid](../play-solid/README.md) — SolidJS renderer
+- [@xmachines/play-solid-router](../play-solid-router/README.md) — native `@solidjs/router` adapter
+- [@xmachines/play-xstate](../play-xstate/README.md) — XState v5 player factory
 
 ## Learn More
 
@@ -261,10 +286,7 @@ URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+,
 
 ## 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>.
+MIT — see [LICENSE](LICENSE).
 
 ## Classes
 

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L100)
+Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/base-route-map.ts#L100)
 
 Shared bidirectional route map base class.
 
@@ -50,7 +50,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L125)
+Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -78,7 +78,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -109,7 +109,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L174)
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.