@xmachines/play-solid-router 1.0.0-beta.5 → 1.0.0-beta.51

package/README.md

@@ -1,637 +1,158 @@
-# @xmachines/play-solid-router
-
-**SolidJS Router adapter for XMachines Universal Player Architecture**
-
-SolidJS Router adapter using `RouterBridgeBase` for consistent actor↔router sync.
-
-## Overview
-
-`@xmachines/play-solid-router` provides seamless integration between SolidJS Router and XMachines state machines. Built on Solid's reactive primitives, it enables zero-adaptation signals synchronization.
-
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+<!-- generated-by: gsd-doc-writer -->
 
-- **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):** TC39 watcher lifecycle + Solid reactive owner integration
-
-**Key Benefits:**
-
-- **Bridge-first:** Extends shared `RouterBridgeBase` policy used by other adapters
-- **Automatic tracking:** Uses Solid reactivity for router→actor while base class handles actor→router watcher lifecycle
-- **Fine-grained reactivity:** Updates only affected components
-- **Logic-driven navigation:** Business logic in state machines, not components
-- **Type-safe parameters:** Route params flow through state machine context
+# @xmachines/play-solid-router
 
-**Framework Compatibility:**
+SolidJS Router adapter for the XMachines Universal Player Architecture. Provides bidirectional synchronisation between a `PlayerActor`'s state machine routes and the browser URL via `@solidjs/router`.
 
-- SolidJS 1.8.4+ (signals-native architecture)
-- @solidjs/router 0.13.0+ (modern routing primitives)
-- TC39 Signals polyfill integration
+Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation
 
 ```bash
-npm install @solidjs/router@^0.13.0 solid-js@^1.8.0 @xmachines/play-solid-router @xmachines/play-solid
+npm install @xmachines/play-solid-router
 ```
 
-**Peer dependencies:**
+**Peer dependencies** (must be installed separately):
 
-- `@solidjs/router` ^0.13.0 - SolidJS 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
+```bash
+npm install solid-js @solidjs/router xstate
+```
 
 ## Quick Start
 
-```typescript
-import { Router, Route, useNavigate, useLocation, useParams } from '@solidjs/router';
-import { onCleanup } from 'solid-js';
-import { SolidRouterBridge, createRouteMap } from '@xmachines/play-solid-router';
-import { definePlayer } from '@xmachines/play-xstate';
-
-function App() {
-  // 1. Get SolidJS Router hooks (MUST be inside component)
-  const navigate = useNavigate();
-  const location = useLocation();
-  const params = useParams();
-
-  // 2. Create route mapping from machine routes
-  const routeMap = createRouteMap(authMachine);
-
-  // 3. Create player with state machine
-  const createPlayer = definePlayer({
-    machine: authMachine,
-    catalog: componentCatalog
-  });
-  const actor = createPlayer();
-  actor.start();
-
-  // 4. Create bridge to sync actor and router
-  const bridge = new SolidRouterBridge(
-    navigate,
-    location,
-    params,
-    actor,
-    routeMap
-  );
-
-  // 5. Start synchronization
-  bridge.connect();
-
-  // 6. Cleanup on component disposal
-  onCleanup(() => {
-    bridge.disconnect();
-  });
-
-  return (
-    <Router>
-      <Route path="/" component={HomeView} />
-      <Route path="/profile/:userId" component={ProfileView} />
-      <Route path="/settings/:section?" component={SettingsView} />
-    </Router>
-  );
-}
-```
+```tsx
+import { Router, Route, useNavigate, useLocation, useParams } from "@solidjs/router";
+import { onCleanup, type ParentComponent } from "solid-js";
+import { PlayRouterProvider, createRouteMap } from "@xmachines/play-solid-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { myMachine } from "./machine.js";
 
-## API Reference
+const actor = definePlayer({ machine: myMachine })();
+actor.start();
 
-### `SolidRouterBridge`
+const routeMap = createRouteMap(myMachine);
 
-Router adapter implementing the `RouterBridge` protocol for SolidJS Router.
+const Layout: ParentComponent = () => {
+	const navigate = useNavigate();
+	const location = useLocation();
+	const params = useParams();
 
-**Type Signature:**
+	onCleanup(() => actor.stop());
 
-```typescript
-class SolidRouterBridge {
-	constructor(
-		navigate: ReturnType<typeof useNavigate>,
-		location: ReturnType<typeof useLocation>,
-		params: ReturnType<typeof useParams>,
-		actor: AbstractActor<any>,
-		routeMap: RouteMap,
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			routeMap={routeMap}
+			router={{ navigate, location, params }}
+			renderer={(a) => <MyApp actor={a} />}
+		/>
 	);
-	dispose(): void;
-}
-```
-
-**Constructor Parameters:**
-
-- `navigate` - Function from `useNavigate()` hook (signals-aware navigation)
-- `location` - Object from `useLocation()` hook (reactive pathname, search, hash)
-- `params` - Object from `useParams()` hook (reactive route parameters)
-- `actor` - XMachines actor instance (from `definePlayer().actor`)
-- `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 SolidJS Router via `navigate(path)` when actor state changes
-- Uses `createEffect(on(...))` to watch `location.pathname` signal
-- Sends `play.route` events to actor when user navigates
-- Prevents circular updates with path tracking and processing flags
-
-### `RouteMap`
-
-Bidirectional mapping between XMachines state IDs and SolidJS Router paths with pattern matching support.
-
-**Type Signature:**
-
-```typescript
-interface RouteMapping {
-	stateId: string;
-	path: string;
-}
-
-class RouteMap {
-	constructor(mappings: RouteMapping[]);
-	getPath(stateId: string, params?: Record<string, string>): string | undefined;
-	getStateIdByPath(path: string): string | undefined;
-}
-```
-
-**Constructor Parameters:**
-
-- `mappings` - Array of mapping objects with:
-    - `stateId` - State machine state ID (e.g., `'#profile'`)
-    - `path` - SolidJS Router path pattern (e.g., `'/profile/:userId'`)
-
-**Methods:**
-
-- `getPath(stateId, params?)` - Find path from state ID, optionally substitute params
-- `getStateIdByPath(path)` - Find state ID from path with pattern matching (supports `:param` and `:param?` syntax)
-
-**Pattern Matching:**
-
-Uses URLPattern API for robust dynamic route matching:
-
-```typescript
-const routeMap = new RouteMap([{ stateId: "#settings", path: "/settings/:section?" }]);
-
-routeMap.getStateIdByPath("/settings"); // '#settings'
-routeMap.getStateIdByPath("/settings/account"); // '#settings'
-routeMap.getStateIdByPath("/settings/privacy"); // '#settings'
-```
-
-## Examples
-
-### Basic Usage: Simple 2-3 Route Setup
-
-```typescript
-import { Router, Route } from '@solidjs/router';
-import { createSignal } from 'solid-js';
-import { defineCatalog } from '@xmachines/play-catalog';
-
-// State machine with 3 states
-const appMachine = setup({
-  types: {
-    events: {} as PlayRouteEvent
-  }
-}).createMachine({
-  id: 'app',
-  initial: 'home',
-  states: {
-    home: {
-      meta: { route: '/', view: { component: 'Home' } }
-    },
-    about: {
-      meta: { route: '/about', view: { component: 'About' } }
-    },
-    contact: {
-      meta: { route: '/contact', view: { component: 'Contact' } }
-    }
-  }
-});
-
-const catalog = defineCatalog({
-  Home,
-  About,
-  Contact,
-});
-
-// Component setup
-function App() {
-  const navigate = useNavigate();
-  const location = useLocation();
-  const params = useParams();
-
-  const routeMap = createRouteMap(appMachine);
-
-  const createPlayer = definePlayer({ machine: appMachine, catalog });
-  const actor = createPlayer();
-  actor.start();
-  const bridge = new SolidRouterBridge(navigate, location, params, actor, routeMap);
-
-  onCleanup(() => bridge.dispose());
-
-  return (
-    <Router>
-      <Route path="/" component={Home} />
-      <Route path="/about" component={About} />
-      <Route path="/contact" component={Contact} />
-    </Router>
-  );
-}
-```
-
-### Parameter Handling: Dynamic Routes with `:param` Syntax
-
-```typescript
-// State machine with parameter routes
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-
-const machineConfig = {
-  id: 'app',
-  context: {},
-  states: {
-    profile: {
-      meta: {
-        route: '/profile/:userId',
-        view: { component: 'Profile' },
-      },
-    },
-    settings: {
-      meta: {
-        route: '/settings/:section?',
-        view: { component: 'Settings' },
-      },
-    }
-  }
 };
 
-const appMachine = setup({
-  types: {
-    context: {} as { userId?: string; section?: string },
-    events: {} as PlayRouteEvent
-  }
-}).createMachine(formatPlayRouteTransitions(machineConfig));
-
-const catalog = defineCatalog({
-  Profile,
-  Settings,
-});
-
-// Router with dynamic routes
-function App() {
-  const navigate = useNavigate();
-  const location = useLocation();
-  const params = useParams();
-
-  const routeMap = createRouteMap(appMachine);
-
-  const createPlayer = definePlayer({ machine: appMachine, catalog });
-  const actor = createPlayer();
-  actor.start();
-  const bridge = new SolidRouterBridge(navigate, location, params, actor, routeMap);
-
-  onCleanup(() => bridge.dispose());
-
-  return (
-    <Router>
-      <Route path="/profile/:userId" component={Profile} />
-      <Route path="/settings/:section?" component={Settings} />
-    </Router>
-  );
+export default function App() {
+	return <Router root={Layout}>{/* one <Route> per routable state */}</Router>;
 }
 ```
 
-**Usage in component:**
+## API Summary
 
-```tsx
-function ProfileButton(props: { userId: string }) {
-	return (
-		<button
-			onClick={() =>
-				props.actor.send({
-					type: "play.route",
-					to: "#profile",
-					params: { userId: props.userId },
-				})
-			}
-		>
-			View Profile
-		</button>
-	);
-}
-```
+### `PlayRouterProvider`
 
-### Query Parameters: Search/Filters via Query Strings
-
-```typescript
-// State machine with query param handling
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-
-const machineConfig = {
-  context: { query: '', filters: {} },
-  states: {
-    search: {
-      meta: {
-        route: '/search',
-        view: { component: 'Search' },
-      },
-    }
-  }
-};
+A SolidJS component that wires a `PlayerActor` to Solid Router. It creates and connects a `SolidRouterBridge` on mount and disconnects it via `onCleanup` on unmount.
 
-const searchMachine = setup({
-  types: {
-    context: {} as { query: string; filters: Record<string, string> },
-    events: {} as PlayRouteEvent
-  }
-}).createMachine(formatPlayRouteTransitions(machineConfig));
-
-const catalog = defineCatalog({
-  Search,
-});
-
-const player = definePlayer({ machine: searchMachine, catalog });
-
-// Component sends query params
-function SearchBar(props) {
-  const [searchTerm, setSearchTerm] = createSignal('');
-
-  function handleSearch() {
-    props.actor.send({
-      type: 'play.route',
-      to: '#search',
-      query: { q: searchTerm(), tag: 'typescript' }
-    });
-  }
-
-  return (
-    <div>
-      <input
-        value={searchTerm()}
-        onInput={(e) => setSearchTerm(e.target.value)}
-      />
-      <button onClick={handleSearch}>Search</button>
-    </div>
-  );
+```tsx
+interface PlayRouterProviderProps<TActor extends RoutableActor> {
+	/** The actor to sync with Solid Router. */
+	actor: TActor;
+	/** Bidirectional route map for state ID ↔ URL path lookups. */
+	routeMap: RouteMap;
+	/**
+	 * The three Solid Router hook results that drive bidirectional sync.
+	 * Must be obtained via useNavigate(), useLocation(), and useParams()
+	 * inside a router context.
+	 */
+	router: SolidRouterHooks;
+	/** Render callback — receives the concrete actor type and router hooks. */
+	renderer: (actor: TActor, router: SolidRouterHooks) => JSX.Element;
 }
 ```
 
-**SolidJS Router automatically reflects query params in URL:**
-
-- `/search?q=xmachines&tag=typescript`
-
-### Protected Routes: Authentication Guards
-
-```typescript
-// State machine with auth guards
-import { defineCatalog } from "@xmachines/play-catalog";
-
-const authMachine = setup({
-	types: {
-		context: {} as { isAuthenticated: boolean },
-		events: {} as PlayRouteEvent | { type: "login" } | { type: "logout" },
-	},
-}).createMachine({
-	context: { isAuthenticated: false },
-	initial: "home",
-	states: {
-		home: {
-			meta: { route: "/", view: { component: "Home" } },
-		},
-		login: {
-			meta: { route: "/login", view: { component: "Login" } },
-			on: {
-				login: {
-					target: "dashboard",
-					actions: assign({ isAuthenticated: true }),
-				},
-			},
-		},
-		dashboard: {
-			meta: { route: "/dashboard", view: { component: "Dashboard" } },
-			always: {
-				guard: ({ context }) => !context.isAuthenticated,
-				target: "login",
-			},
-		},
-	},
-});
-
-const catalog = defineCatalog({
-	Home,
-	Login,
-	Dashboard,
-});
-
-const player = definePlayer({ machine: authMachine, catalog });
-```
-
-**Guard behavior:**
+### `SolidRouterBridge`
 
-- User navigates to `/dashboard`
-- Bridge sends `play.route` event to actor
-- Actor's `always` guard checks `isAuthenticated`
-- If `false`, actor transitions to `login` state
-- Bridge detects state change via `createEffect`, redirects to `/login`
-- Actor Authority principle enforced
+Low-level class for manual integration. Extends `RouterBridgeBase` from `@xmachines/play-router` and uses Solid's `createEffect` for reactive router→actor sync.
 
-### Cleanup: Proper Disposal on Component Unmount
+> **Important:** `connect()` must be called inside a Solid reactive owner (component or `createRoot`). Cleanup is not automatic — call `disconnect()` (or `dispose()`) explicitly, typically in `onCleanup()`.
 
 ```tsx
-import { onCleanup } from "solid-js";
-import { SolidRouterBridge } from "@xmachines/play-solid-router";
+import { useNavigate, useLocation, useParams, onCleanup } from "@solidjs/router";
+import { SolidRouterBridge, RouteMap } from "@xmachines/play-solid-router";
 
 function App() {
 	const navigate = useNavigate();
 	const location = useLocation();
 	const params = useParams();
-	const actor = useContext(ActorContext);
-	const routeMap = useContext(RouteMapContext);
 
-	const bridge = new SolidRouterBridge(navigate, location, params, actor, routeMap);
+	const routeMap = new RouteMap([
+		{ stateId: "#home", path: "/" },
+		{ stateId: "#profile", path: "/profile/:userId" },
+	]);
 
-	// CRITICAL: Cleanup effects
-	onCleanup(() => {
-		bridge.dispose();
-	});
+	const bridge = new SolidRouterBridge(navigate, location, params, actor, routeMap);
+	bridge.connect();
+	onCleanup(() => bridge.disconnect());
 
-	return <Router>...</Router>;
+	return <div>...</div>;
 }
 ```
 
-**Why cleanup matters:**
-
-- `createEffect` subscriptions continue after disposal (memory leak)
-- Multiple bridge instances send duplicate events
-- Tests fail with "Cannot send to stopped actor" errors
-- Solid's fine-grained reactivity tracks disposed components
-
-## Architecture
-
-### Bidirectional Sync (Actor ↔ Router)
-
-**Actor → Router (Signal-driven via createEffect):**
-
-1. Actor transitions to new state with `meta.route`
-2. `actor.currentRoute` signal updates
-3. `createEffect(on(...))` fires with new route value
-4. Bridge extracts state ID from signal
-5. Bridge looks up path via `routeMap.getPath(stateId, params)`
-6. Bridge calls `navigate(path)`
-7. SolidJS Router updates URL and renders component
-
-**Router → Actor (Location tracking via createEffect):**
-
-1. User clicks link or browser back button
-2. `location.pathname` signal updates
-3. `createEffect(on(...))` fires with new pathname
-4. Bridge looks up state ID via `routeMap.getStateIdByPath(pathname)`
-5. Bridge extracts params from `useParams()` reactive object
-6. Bridge sends `play.route` event to actor
-7. Actor validates navigation (guards, transitions)
-8. If accepted: Actor transitions, signal updates, URL stays
-9. If rejected: Actor redirects, bridge corrects URL via `navigate()`
-
-### Circular Update Prevention
-
-**Multi-layer guards prevent infinite loops:**
-
-1. **`lastSyncedPath` tracking:** Stores last synchronized path, skips if unchanged
-2. **`isProcessingNavigation` flag:** Set during navigation processing, prevents concurrent syncs
-3. **Effect timing:** Solid's batched updates and `defer: true` option prevent rapid cycles
-
-**Signals-native pattern:**
-
-```typescript
-// Actor → Router
-createEffect(
-	on(
-		() => this.actor.currentRoute.get(),
-		(route) => {
-			if (!route || route === this.lastSyncedPath || this.isProcessingNavigation) {
-				return;
-			}
-			this.lastSyncedPath = route;
-			this.navigate(route);
-		},
-		{ defer: true },
-	),
-);
-
-// Router → Actor
-createEffect(
-	on(
-		() => this.location.pathname,
-		(pathname) => {
-			if (pathname === this.lastSyncedPath || this.isProcessingNavigation) {
-				return;
-			}
-			this.isProcessingNavigation = true;
-			this.actor.send({ type: "play.route", to: stateId, params });
-			this.isProcessingNavigation = false;
-		},
-		{ defer: true },
-	),
-);
-```
-
-### Relationship to Other Packages
+### `createRouteMap(machine)`
 
-**Package Dependencies:**
+Factory that builds a `RouteMap` directly from an XState machine definition. Re-exported from `@xmachines/play-router`.
 
-- `@xmachines/play` - Protocol interfaces (`PlayRouteEvent`, `RouterBridge`)
-- `@xmachines/play-actor` - Actor base class with signal protocol
-- `@xmachines/play-router` - Route extraction and pattern matching
-- `@xmachines/play-signals` - TC39 Signals polyfill for reactivity
-- `@xmachines/play-xstate` - XState integration via `definePlayer()`
+```ts
+import { createRouteMap } from "@xmachines/play-solid-router";
 
-**Architecture Layers:**
-
-```
-┌─────────────────────────────────────┐
-│  Solid Components (View Layer)     │
-│  - Props include actor reference    │
-│  - Sends play.route events          │
-└─────────────────────────────────────┘
-              ↕
-┌─────────────────────────────────────┐
-│  SolidRouterBridge (Adapter)        │
-│  - createEffect(actor.currentRoute) │
-│  - createEffect(location.pathname)  │
-└─────────────────────────────────────┘
-       ↕                    ↕
-┌─────────────┐    ┌──────────────────┐
-│ SolidJS     │    │ XMachines Actor  │
-│ Router      │    │ (Business Logic) │
-│ (Infra)     │    │                  │
-└─────────────┘    └──────────────────┘
+const routeMap = createRouteMap(myMachine);
 ```
 
-### Signals Integration (SolidJS-Specific)
-
-**Why signals-native matters:**
+### `RouteMap` / `RouteMapping`
 
-- **Zero adaptation:** Solid signals and TC39 Signals share reactive primitives
-- **Automatic tracking:** `createEffect(on(...))` tracks dependencies without manual Watcher setup
-- **Fine-grained updates:** Only affected components re-render (not full tree)
-- **Batched updates:** Solid batches multiple signal changes in single render cycle
+Bidirectional state ID ↔ URL path mapping. Re-exported from `@xmachines/play-router`.
 
-**Hook context requirement (Pitfall 2):**
-
-SolidJS hooks (`useNavigate`, `useLocation`, `useParams`) **MUST** be called inside component tree:
-
-```tsx
-// ❌ WRONG: Bridge created outside component
-const navigate = useNavigate(); // ERROR: No reactive context
-const bridge = new SolidRouterBridge(navigate, ...);
+```ts
+import { RouteMap } from "@xmachines/play-solid-router";
 
-// ✅ CORRECT: Bridge created inside component
-function App() {
-  const navigate = useNavigate();
-  const location = useLocation();
-  const params = useParams();
-  const bridge = new SolidRouterBridge(navigate, location, params, actor, routeMap);
-  onCleanup(() => bridge.dispose());
-  return <Router>...</Router>;
-}
+const routeMap = new RouteMap([
+	{ stateId: "#home", path: "/" },
+	{ stateId: "#profile", path: "/profile/:userId" },
+	{ stateId: "#settings", path: "/settings/:section?" },
+]);
 ```
 
-**Why:** Solid's reactivity system requires reactive ownership context. Hooks create tracked scopes that exist only within component lifecycle.
+### Types
 
-### Pattern Matching for Dynamic Routes
+| Export                    | Description                                                                                  |
+| ------------------------- | -------------------------------------------------------------------------------------------- |
+| `RoutableActor`           | Minimum actor shape accepted by `PlayRouterProvider` (`AbstractActor & Routable & Viewable`) |
+| `SolidRouterHooks`        | Shape of the `router` prop: `{ navigate, location, params }`                                 |
+| `PlayRouterProviderProps` | Full props interface for `PlayRouterProvider`                                                |
+| `PlayRouteEvent`          | Event type sent to the actor on URL change (`play.route`)                                    |
+| `RouterBridge`            | Interface implemented by `SolidRouterBridge`                                                 |
 
-**URLPattern API integration:**
+## Testing
 
-```typescript
-private matchesPattern(path: string, pattern: string): boolean {
-  // Use URLPattern for robust matching
-  const urlPattern = new URLPattern({ pathname: pattern });
-  return urlPattern.test({ pathname: path });
-}
-```
-
-**Supported syntax:**
+Run tests for this package in isolation:
 
-- `:param` - Required parameter (e.g., `/profile/:userId` matches `/profile/123`)
-- `:param?` - Optional parameter (e.g., `/settings/:section?` matches `/settings` and `/settings/account`)
-- Wildcards via `*` (future enhancement)
-
-**Example:**
-
-```typescript
-const routeMap = new RouteMap([
-	{ stateId: "#profile", path: "/profile/:userId" },
-	{ stateId: "#settings", path: "/settings/:section?" },
-]);
+```bash
+# From the monorepo root
+npm test -w packages/play-solid-router
 
-routeMap.getStateIdByPath("/profile/123"); // '#profile'
-routeMap.getStateIdByPath("/settings"); // '#settings'
-routeMap.getStateIdByPath("/settings/privacy"); // '#settings'
+# Or from this package directory
+npm test
 ```
 
+Coverage thresholds: **80%** lines, functions, branches, and statements.
+
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE).