@xmachines/docs 1.0.0-beta.45 → 1.0.0-beta.48

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

@@ -1,676 +1,163 @@
 [API](../../README.md) / @xmachines/play-solid-router
 
-# @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 [Play RFC](../../../rfc/play.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
-  -)
-- — Actor base
-- — Route extraction
-- — TC39 Signals primitives
+```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. Both `location.pathname` and `location.search` are forwarded to the actor on first connect, so users arriving on `/profile?tab=posts` have `query: { tab: "posts" }` in the initial `play.route` event.
-- `disconnect()` - Stop synchronization and cleanup bridge resources.
-- `dispose()` - Alias of `disconnect()`.
-
-`connect()` creates a Solid-owned router watcher, and `disconnect()`/`dispose()` tears it down immediately. Do not rely on owner unmount alone if you need the bridge to stop processing router updates earlier.
-
-**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, using Solid's pre-parsed `useParams()` for path parameter extraction (no URLPattern polyfill required)
-- Prevents circular updates with path tracking and processing flags
-
-### `RouteMap`
-
-Bidirectional mapping between XMachines state IDs and SolidJS Router paths with pattern matching support.
-
-`RouteMap` extends `BaseRouteMap` from, inheriting bucket-indexed
-bidirectional route matching. No routing logic lives in the adapter itself.
-
-```typescript
-interface RouteMapping {
-	readonly stateId: string;
-	readonly path: string;
-}
-
-// 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
-```
-
-`getStateIdByPath` and `getPathByStateId` both return `null` (not `undefined`) for misses.
-
-**Constructor Parameters:**
-
-- `mappings` - Array of `{ stateId, path }` entries:
-    - `stateId` — State machine state ID (e.g., `'#profile'`)
-    - `path` — SolidJS Router path pattern (e.g., `'/profile/:userId'`)
-
-**Methods:**
-
-- `getPathByStateId(stateId)` — Find path pattern from state ID
-- `getStateIdByPath(path)` — Find state ID from path with pattern matching (supports `:param` and `:param?` syntax)
-
-**Pattern Matching:**
-
-Uses bucket-indexed RegExp matching for dynamic routes:
-
-```typescript
-const routeMap = new RouteMap([{ stateId: "#settings", path: "/settings/:section?" }]);
-
-routeMap.getStateIdByPath("/settings"); // '#settings'
-routeMap.getStateIdByPath("/settings/account"); // '#settings'
-routeMap.getStateIdByPath("/settings/privacy"); // '#settings'
-routeMap.getStateIdByPath("/other"); // null
-```
-
-## Examples
-
-### Basic Usage: Simple 2-3 Route Setup
-
-```typescript
-import { Router, Route } from '@solidjs/router';
-import { defineCatalog } from "@json-render/core";
-import { schema } from "@json-render/react/schema";
-import { defineRegistry } from "@xmachines/play-solid";
-import { z } from "zod";
-
-// Catalog and registry
-const appCatalog = defineCatalog(schema, {
-  components: {
-    Home: { props: z.object({}) },
-    About: { props: z.object({}) },
-    Contact: { props: z.object({}) },
-  },
-});
-const registry = defineRegistry(appCatalog, { components: { Home, About, Contact } });
-
-// 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' } }
-    }
-  }
-});
-
-// Component setup
-function App() {
-  const navigate = useNavigate();
-  const location = useLocation();
-  const params = useParams();
-
-  const routeMap = createRouteMap(appMachine);
-
-  const createPlayer = definePlayer({ machine: appMachine, catalog: appCatalog });
-  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 "@json-render/core";
-import { schema } from "@json-render/react/schema";
-import { defineRegistry } from "@xmachines/play-solid";
-import { z } from "zod";
-
-const appCatalog = defineCatalog(schema, {
-  components: {
-    Profile: { props: z.object({ userId: z.string() }) },
-    Settings: { props: z.object({ section: z.string().optional() }) },
-  },
-});
-const registry = defineRegistry(appCatalog, { components: { Profile, Settings } });
-
-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));
-
-// 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: appCatalog });
-  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 "@json-render/core";
-import { schema } from "@json-render/react/schema";
-import { defineRegistry } from "@xmachines/play-solid";
-import { z } from "zod";
-
-const searchCatalog = defineCatalog(schema, {
-  components: {
-    Search: { props: z.object({ query: z.string().optional() }) },
-  },
-});
-const registry = defineRegistry(searchCatalog, { components: { Search } });
-
-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 player = definePlayer({ machine: searchMachine, catalog: searchCatalog });
-
-// 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 "@json-render/core";
-import { schema } from "@json-render/react/schema";
-import { defineRegistry } from "@xmachines/play-solid";
-import { z } from "zod";
-
-const authCatalog = defineCatalog(schema, {
-	components: {
-		Home: { props: z.object({}) },
-		Login: { props: z.object({ title: z.string() }) },
-		Dashboard: { props: z.object({ username: z.string() }) },
-	},
-});
-const registry = defineRegistry(authCatalog, { components: { Home, Login, Dashboard } });
-
-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 player = definePlayer({ machine: authMachine, catalog: authCatalog });
-```
-
-**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.getPathByStateId(stateId)`
-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 },
-	),
-);
-```
+### `createRouteMap(machine)`
 
-### Relationship to Other Packages
+Factory that builds a `RouteMap` directly from an XState machine definition. Re-exported from `@xmachines/play-router`.
 
-**Package Dependencies:**
+```ts
+import { createRouteMap } from "@xmachines/play-solid-router";
 
--)
-
--   - Actor base class with signal protocol
--   - Route extraction and pattern matching
--   - TC39 Signals polyfill for reactivity
-- **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:**
-
-- **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
-
-**Hook context requirement (Pitfall 2):**
+### `RouteMap` / `RouteMapping`
 
-SolidJS hooks (`useNavigate`, `useLocation`, `useParams`) **MUST** be called inside component tree:
+Bidirectional state ID ↔ URL path mapping. Re-exported from `@xmachines/play-router`.
 
-```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.
-
-### Pattern Matching for Dynamic Routes
-
-**Bucket-indexed matching via `BaseRouteMap`:**
+### Types
 
-Routes are grouped by their first path segment into buckets. On each lookup only the
-relevant bucket (plus the wildcard `*` bucket for `:param`-first routes) is scanned —
-typically far fewer than all registered 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`                                                 |
 
-**Supported syntax:**
+## Testing
 
-- `: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)
+Run tests for this package in isolation:
 
-**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
 ```
 
-## Learn More
-
-- [Demo](../../../examples/@xmachines/play-solid-router-demo/README.md)
-- [SolidJS renderer](../play-solid/README.md)
+Coverage thresholds: **80%** lines, functions, branches, and statements.
 
 ## 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