@xmachines/play-tanstack-solid-router 1.0.0-beta.7 → 1.0.0-beta.9

package/README.md

@@ -6,7 +6,7 @@ Signals-native integration with TanStack Solid Router enabling logic-driven navi
 
 ## Overview
 
-`@xmachines/play-tanstack-solid-router` provides seamless integration between TanStack Solid Router and XMachines state machines. Built on Solid's reactive primitives (`createEffect`), it implements the RouterBridge protocol for bidirectional synchronization.
+`@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:
 
@@ -17,26 +17,26 @@ Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md),
 **Key Benefits:**
 
 - **Signals-native:** Zero adaptation layer between Solid signals and TC39 Signals
-- **RouterBridge pattern:** ~220 lines, 2 flags (consistent with Vue/Solid Router adapters)
-- **Automatic tracking:** `createEffect` handles dependency tracking (no manual Watcher)
+- **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.0.0+
+- TanStack Solid Router 1.100.0+
 - SolidJS 1.8.0+
 - TC39 Signals polyfill integration
 
 ## Installation
 
 ```bash
-npm install @tanstack/solid-router@^1.0.0 solid-js@^1.8.0 @xmachines/play-tanstack-solid-router @xmachines/play-solid
+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.0.0 - TanStack Solid Router library
+- `@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
@@ -45,377 +45,212 @@ npm install @tanstack/solid-router@^1.0.0 solid-js@^1.8.0 @xmachines/play-tansta
 
 ## Quick Start
 
-```typescript
-import { createRouter } from '@tanstack/solid-router';
-import { onCleanup } from 'solid-js';
-import { PlayRenderer } from '@xmachines/play-solid';
-import { definePlayer } from '@xmachines/play-xstate';
-import { extractMachineRoutes } from '@xmachines/play-router';
-import { SolidRouterBridge, createRouteMapFromTree } from '@xmachines/play-tanstack-solid-router';
+```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 actor
-  const actor = definePlayer({ machine, catalog })();
-
-  // 2. Create router
-  const router = createRouter({
-    routes: /* ... TanStack route config ... */
-  });
-
-  // 3. Extract routes from machine and create RouteMap
-  const routeTree = extractMachineRoutes(machine);
-  const routeMap = createRouteMapFromTree(routeTree);
-
-  // 4. Create and connect bridge (inside component with Solid ownership context)
-  const bridge = new SolidRouterBridge(router, actor, routeMap);
-  bridge.connect();
-
-  onCleanup(() => bridge.disconnect());
-
-  return (
-    <Router>
-      <PlayRenderer actor={actor} components={components} />
-    </Router>
-  );
+	// 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>
+			)}
+		/>
+	);
 }
 ```
 
-**Important:** The bridge must be created inside a component where Solid hooks (`createEffect`, `onCleanup`) are available. TanStack Solid Router requires Solid's ownership context for reactivity to work correctly.
-
 ## API Reference
 
 ### `SolidRouterBridge`
 
 Router adapter implementing the `RouterBridge` protocol for TanStack Solid Router.
 
-**Constructor:**
+**Type Signature:**
 
 ```typescript
-new SolidRouterBridge(
-  router: Router,
-  actor: AbstractActor<any>,
-  routeMap: RouteMap
-)
+class SolidRouterBridge {
+	constructor(router: Router, actor: AbstractActor<any>, routeMap: RouteMap);
+	dispose(): void;
+}
 ```
 
-**Parameters:**
+**Constructor Parameters:**
 
-- `router`: TanStack Solid Router instance (from `createRouter()`)
-- `actor`: XMachines player actor implementing signal protocol
-- `routeMap`: Bidirectional state ID ↔ path mapping
+- `router` - TanStack Solid Router instance
+- `actor` - XMachines actor instance
+- `routeMap` - Bidirectional state ID ↔ path mapping
 
 **Methods:**
 
-- `connect(): void` - Start bidirectional synchronization (actor ↔ router)
-- `disconnect(): void` - Stop synchronization and cleanup subscriptions
+- `connect()` - Start bidirectional synchronization.
+- `disconnect()` - Stop synchronization and cleanup bridge resources.
+- `dispose()` - Alias of `disconnect()`.
 
-**Important:** Must be created inside component where Solid hooks (`createEffect`, `onCleanup`) are available. Creating outside ownership context will cause reactivity to fail.
+**Internal Behavior:**
 
-### `RouteMap`
+- 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
 
-Bidirectional mapping between XMachines state IDs and URL paths with pattern matching support.
+### `PlayTanStackRouterProvider`
 
-**Constructor:**
+A Solid component that automatically sets up, connects, and tears down the `SolidRouterBridge` using Solid's lifecycle.
 
-```typescript
-new RouteMap(routes: RouteMapping[])
+```tsx
+interface PlayTanStackRouterProviderProps {
+	actor: AbstractActor<any>;
+	router: Router;
+	routeMap: RouteMap;
+	renderer: (actor: AbstractActor<any>, router: Router) => JSX.Element;
+}
 ```
 
-**Interface:**
+**Props:**
 
-```typescript
-interface RouteMapping {
-	stateId: string; // XMachines state ID (e.g., '#home', '#profile')
-	path: string; // URL path pattern (e.g., '/', '/profile/:userId')
-}
-```
+- `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
 
-**Methods:**
+**Behavior:**
 
-- `getStateIdByPath(path: string): string | null` - Lookup state ID by path (with URLPattern matching)
-- `getPathByStateId(stateId: string): string | null` - Lookup path by state ID
+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`
 
-### `createRouteMapFromTree()`
+### `createRouteMap()`
 
-Helper to create RouteMap from RouteTree extracted from state machine.
+Helper to build a `RouteMap` instance directly from an XState machine.
 
 **Signature:**
 
 ```typescript
-function createRouteMapFromTree(routeTree: RouteTree): RouteMap;
+function createRouteMap(machine: AnyStateMachine): RouteMap;
 ```
 
 **Usage:**
 
 ```typescript
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { createRouteMapFromTree } from "@xmachines/play-tanstack-solid-router";
+import { createRouteMap } from "@xmachines/play-tanstack-solid-router";
 
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
+const routeMap = createRouteMap(machine);
 ```
 
-This helper traverses the route tree and creates RouteMapping entries for all routable states.
-
 ## Usage Patterns
 
-### Creating RouteMap from Machine
-
-**Recommended:** Extract routes from state machine automatically:
-
-```typescript
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { createRouteMapFromTree } from "@xmachines/play-tanstack-solid-router";
-
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
-```
-
-**Manual:** Define routes explicitly:
-
-```typescript
-const routeMap = new RouteMap([
-	{ stateId: "#home", path: "/" },
-	{ stateId: "#profile", path: "/profile/:userId" },
-]);
-```
-
 ### Dynamic Routes with Parameters
 
-**Path parameters:**
+TanStack Router and URLPattern (used internally) support dynamic route matching syntax:
 
 ```typescript
-const routeMap = new RouteMap([
-	{ stateId: "#home", path: "/" },
-	{ stateId: "#settings", path: "/settings/:section?" }, // Optional param
-	{ stateId: "#profile", path: "/profile/:userId" }, // Required param
-]);
-```
-
-**Pattern matching examples:**
+// Machine configuration
+const machineConfig = {
+	states: {
+		profile: {
+			meta: {
+				route: "/profile/:userId",
+				view: { component: "Profile" },
+			},
+		},
+	},
+};
 
-```typescript
+// Route mapping will natively support URLPattern parameters
 routeMap.getStateIdByPath("/profile/123"); // → '#profile'
-routeMap.getStateIdByPath("/settings"); // → '#settings'
-routeMap.getStateIdByPath("/settings/privacy"); // → '#settings'
 ```
 
-### Cleanup on Component Unmount
+### Protected Routes and Guards
 
-**Always cleanup when component unmounts:**
+With XMachines, auth guards are handled entirely inside the state machine, preventing flashes of unauthorized content.
 
 ```typescript
-function MyApp() {
-  const bridge = new SolidRouterBridge(router, actor, routeMap);
-  bridge.connect();
-
-  onCleanup(() => {
-    bridge.disconnect();  // Stop synchronization
-    actor.stop();          // Stop actor if needed
-  });
-
-  return <Router>...</Router>;
+// Machine side
+dashboard: {
+  meta: { route: "/dashboard", view: { component: "Dashboard" } },
+  always: {
+    guard: ({ context }) => !context.isAuthenticated,
+    target: "login"
+  }
 }
 ```
 
-## Circular Update Prevention
+When a user navigates to `/dashboard`:
 
-SolidRouterBridge uses a **2-flag pattern** to prevent infinite loops:
-
-1. **lastSyncedPath** - Skips redundant updates when path unchanged
-2. **isProcessingNavigation** - Prevents actor → router → actor loops
-
-**How it works:**
-
-```typescript
-// Actor state change → Router navigation
-private syncRouterFromActor(route: string | null): void {
-  if (this.isProcessingNavigation) return;  // Skip if processing router event
-  if (route === this.lastSyncedPath) return; // Skip if path unchanged
-
-  this.lastSyncedPath = route || '/';
-  this.router.navigate({ to: this.lastSyncedPath });
-}
+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`
 
-// Router navigation → Actor event
-private syncActorFromRouter(location: RouterLocation): void {
-  this.isProcessingNavigation = true;  // Set flag
-
-  // Send event to actor...
+## Circular Update Prevention
 
-  queueMicrotask(() => {
-    this.isProcessingNavigation = false;  // Clear flag in microtask
-  });
-}
-```
+The `RouterBridgeBase` architecture prevents infinite loops between router and actor using two mechanisms:
 
-**Microtask timing:** The `isProcessingNavigation` flag is cleared in a microtask (via `queueMicrotask()`) to ensure the actor has processed the event before allowing router-initiated syncs again.
+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   | @tanstack/solid-router       |
-| -------------- | ----------------- | ---------------------------- |
-| **Router API** | router.push()     | router.navigate({ to })      |
-| **Location**   | router.location   | router.state.location        |
-| **Guards**     | router.beforeEach | No guards (use createEffect) |
-| **Reactivity** | createEffect      | createEffect                 |
-
-**Key Differences:**
-
-- **TanStack Solid Router:** Uses `router.navigate({ to })` API (object-based navigation)
-- **SolidJS Router:** Uses `navigate(path)` function (string-based navigation)
-- **TanStack:** Router instance contains state, no separate hooks needed
-- **SolidJS:** Requires hooks (`useNavigate`, `useLocation`) for navigation primitives
-
-## Limitations
-
-### Solid Ownership Context Required
-
-The bridge must be created inside a component where Solid hooks are available:
-
-```typescript
-// ✅ CORRECT: Inside component
-function App() {
-	const bridge = new SolidRouterBridge(router, actor, routeMap);
-	bridge.connect();
-	onCleanup(() => bridge.disconnect());
-}
-
-// ❌ WRONG: Outside component (no ownership context)
-const bridge = new SolidRouterBridge(router, actor, routeMap);
-bridge.connect(); // Will fail - no owner for createEffect
-```
-
-**Error message:**
-
-```
-Error: createEffect can only be used within a component
-```
-
-### Router Creation
-
-Router must be created with TanStack's `createRouter()`:
-
-```typescript
-import { createRouter } from "@tanstack/solid-router";
-
-const router = createRouter({
-	routes: [
-		/* route config */
-	],
-});
-```
-
-### Pattern Matching Requirements
-
-Route patterns with parameters require URLPattern support:
-
-- **Modern browsers:** Safari 17.4+, Chrome 95+, Firefox 106+
-- **Node.js:** Requires `urlpattern-polyfill` for tests
-
-**Polyfill setup:**
-
-```typescript
-// Top of app entry point
-if (!globalThis.URLPattern) {
-	await import("urlpattern-polyfill");
-}
-```
+| 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
 
-SolidRouterBridge follows XMachines Play architectural invariants:
+This package implements standard Play invariants:
 
 ### INV-01: Actor Authority
 
-**Principle:** State machine has final authority over all transitions.
-
-**Implementation:** Router navigation triggers actor events, but actor guards decide validity:
-
-```typescript
-// Router navigation → Actor event
-syncActorFromRouter(location: RouterLocation): void {
-  const stateId = this.routeMap.getStateIdByPath(location.pathname);
-  this.actor.send({
-    type: 'play.route',
-    to: stateId,
-    params: extractParams(location)
-  });
-  // Actor guards validate - if rejected, URL reverts to actor's current route
-}
-```
+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
 
-**Principle:** Infrastructure reflects actor state, never decides navigation.
-
-**Implementation:** Router observes `actor.currentRoute` signal and updates URL:
-
-```typescript
-// Actor state change → Router navigation
-const actorEffect = createEffect(
-	on(
-		() => this.actor.currentRoute.get(),
-		(route) => this.syncRouterFromActor(route),
-	),
-);
-```
-
-### INV-05: Signal-Only Reactivity
-
-**Principle:** All reactivity through signals, never callbacks or promises.
-
-**Implementation:** Solid's `createEffect` watches actor signals automatically:
-
-```typescript
-// Automatic dependency tracking
-createEffect(
-	on(
-		() => this.actor.currentRoute.get(), // Signal read
-		(route) => {
-			// Effect runs when signal changes
-		},
-	),
-);
-```
-
-## Browser Support
-
-This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching.
-
-**Native Support:**
-
-- Safari 17.4+ (Sept 2024)
-- Chrome 95+ (Oct 2021)
-- Firefox 106+ (Oct 2022)
-- **Baseline 2025** status (newly available)
-
-**Polyfill Required:**
-
-- Node.js (all versions) - required for tests
-- Safari < 17.4
-- Older browsers
+Infrastructure reflects actor state. The router observes `actor.currentRoute` and updates the browser URL, never storing independent business state.
 
-**Polyfill Installation:**
+### Cleanup Contract
 
-```bash
-npm install urlpattern-polyfill
-```
+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.
 
-**Usage:**
+## URLPattern Support
 
-```typescript
-// Top of your app entry point (e.g., main.tsx)
-if (!globalThis.URLPattern) {
-	await import("urlpattern-polyfill");
-}
-```
+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`.
 
-**Bundle Size:** ~4KB gzipped (zero impact if URLPattern is native)
+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#installation) for details.
 
-## Examples
+## Related Packages
 
-See `examples/demo/` for the maintained integration example and tests.
+- **[@xmachines/play-solid](../play-solid)** - SolidJS renderer
+- **[@xmachines/play-router](../play-router)** - Core router primitives
+- **[@xmachines/play-solid-router](../play-solid-router)** - Native SolidJS Router equivalent
 
 ## License
 

package/dist/route-map.d.ts

@@ -1,75 +1,27 @@
 /**
- * RouteMap for bidirectional state ID ↔ path mapping
+ * Bidirectional route mapper for TanStack Solid Router.
  *
- * Provides efficient lookup between XMachines state IDs and TanStack Router paths.
- * Supports pattern matching for dynamic routes with parameters.
+ * Extends {@link BaseRouteMap} from `@xmachines/play-router` — all matching logic
+ * lives there. This class exists to provide a TanStack Solid 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
+ *
+ * @extends BaseRouteMap
+ *
+ * @example
+ * ```typescript
+ * import { createRouteMap } from "@xmachines/play-tanstack-solid-router";
+ *
+ * const routeMap = createRouteMap(machine);
+ *
+ * routeMap.getStateIdByPath("/profile/123");  // "#profile"
+ * routeMap.getPathByStateId("#settings");     // "/settings/:section?"
+ * ```
  */
-import type { RouteMapping } from "./types.js";
-export declare class RouteMap {
-    private stateToPath;
-    private pathToState;
-    /**
-     * Create a RouteMap with bidirectional mappings
-     *
-     * @param mappings - Array of state ID to path mappings
-     *
-     * @example
-     * ```typescript
-     * const routeMap = new RouteMap([
-     *   { stateId: '#home', path: '/' },
-     *   { stateId: '#profile', path: '/profile/:userId' },
-     *   { stateId: '#settings', path: '/settings/:section?' }
-     * ]);
-     * ```
-     */
-    constructor(mappings: RouteMapping[]);
-    /**
-     * Get path pattern for a state ID
-     *
-     * @param stateId - XMachines state ID (e.g., '#profile')
-     * @returns Path pattern or null if not found
-     *
-     * @example
-     * ```typescript
-     * routeMap.getPathByStateId('#profile'); // '/profile/:userId'
-     * ```
-     */
-    getPathByStateId(stateId: string): string | null;
-    /**
-     * Get state ID for a path, with pattern matching support
-     *
-     * Performs exact match first, then fuzzy pattern matching for dynamic routes.
-     * Supports both required (:param) and optional (:param?) parameters.
-     *
-     * @param path - Actual URL path (e.g., '/profile/123')
-     * @returns State ID or null if no match found
-     *
-     * @example
-     * ```typescript
-     * routeMap.getStateIdByPath('/profile/123');  // '#profile'
-     * routeMap.getStateIdByPath('/settings');      // '#settings'
-     * routeMap.getStateIdByPath('/settings/account'); // '#settings'
-     * ```
-     */
-    getStateIdByPath(path: string): string | null;
-    /**
-     * Check if a path matches a pattern
-     *
-     * Supports:
-     * - Required parameters: :param
-     * - Optional parameters: :param?
-     *
-     * @param path - Actual URL path
-     * @param pattern - Route pattern with :param syntax
-     * @returns true if path matches pattern
-     *
-     * @example
-     * ```typescript
-     * matchesPattern('/profile/123', '/profile/:userId');  // true
-     * matchesPattern('/settings', '/settings/:section?');  // true
-     * matchesPattern('/settings/account', '/settings/:section?'); // true
-     * ```
-     */
-    private matchesPattern;
+import { BaseRouteMap } from "@xmachines/play-router";
+export declare class RouteMap extends BaseRouteMap {
 }
 //# sourceMappingURL=route-map.d.ts.map

package/dist/route-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-map.d.ts","sourceRoot":"","sources":["../src/route-map.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,qBAAa,QAAQ;IACpB,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,WAAW,CAA6B;IAEhD;;;;;;;;;;;;;OAaG;gBACS,QAAQ,EAAE,YAAY,EAAE;IAOpC;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIhD;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAmB7C;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,cAAc;CAetB"}
+{"version":3,"file":"route-map.d.ts","sourceRoot":"","sources":["../src/route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,qBAAa,QAAS,SAAQ,YAAY;CAAG"}

package/dist/route-map.js

@@ -1,107 +1,27 @@
 /**
- * RouteMap for bidirectional state ID ↔ path mapping
+ * Bidirectional route mapper for TanStack Solid Router.
  *
- * Provides efficient lookup between XMachines state IDs and TanStack Router paths.
- * Supports pattern matching for dynamic routes with parameters.
+ * Extends {@link BaseRouteMap} from `@xmachines/play-router` — all matching logic
+ * lives there. This class exists to provide a TanStack Solid 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
+ *
+ * @extends BaseRouteMap
+ *
+ * @example
+ * ```typescript
+ * import { createRouteMap } from "@xmachines/play-tanstack-solid-router";
+ *
+ * const routeMap = createRouteMap(machine);
+ *
+ * routeMap.getStateIdByPath("/profile/123");  // "#profile"
+ * routeMap.getPathByStateId("#settings");     // "/settings/:section?"
+ * ```
  */
-export class RouteMap {
-    stateToPath = new Map();
-    pathToState = new Map();
-    /**
-     * Create a RouteMap with bidirectional mappings
-     *
-     * @param mappings - Array of state ID to path mappings
-     *
-     * @example
-     * ```typescript
-     * const routeMap = new RouteMap([
-     *   { stateId: '#home', path: '/' },
-     *   { stateId: '#profile', path: '/profile/:userId' },
-     *   { stateId: '#settings', path: '/settings/:section?' }
-     * ]);
-     * ```
-     */
-    constructor(mappings) {
-        mappings.forEach(({ stateId, path }) => {
-            this.stateToPath.set(stateId, path);
-            this.pathToState.set(path, stateId);
-        });
-    }
-    /**
-     * Get path pattern for a state ID
-     *
-     * @param stateId - XMachines state ID (e.g., '#profile')
-     * @returns Path pattern or null if not found
-     *
-     * @example
-     * ```typescript
-     * routeMap.getPathByStateId('#profile'); // '/profile/:userId'
-     * ```
-     */
-    getPathByStateId(stateId) {
-        return this.stateToPath.get(stateId) ?? null;
-    }
-    /**
-     * Get state ID for a path, with pattern matching support
-     *
-     * Performs exact match first, then fuzzy pattern matching for dynamic routes.
-     * Supports both required (:param) and optional (:param?) parameters.
-     *
-     * @param path - Actual URL path (e.g., '/profile/123')
-     * @returns State ID or null if no match found
-     *
-     * @example
-     * ```typescript
-     * routeMap.getStateIdByPath('/profile/123');  // '#profile'
-     * routeMap.getStateIdByPath('/settings');      // '#settings'
-     * routeMap.getStateIdByPath('/settings/account'); // '#settings'
-     * ```
-     */
-    getStateIdByPath(path) {
-        // Strip query string and hash fragment for matching
-        const cleanPath = path.split("?")[0].split("#")[0];
-        // Direct lookup first (exact match)
-        if (this.pathToState.has(cleanPath)) {
-            return this.pathToState.get(cleanPath);
-        }
-        // Fuzzy match for dynamic routes
-        for (const [pattern, stateId] of this.pathToState) {
-            if (this.matchesPattern(cleanPath, pattern)) {
-                return stateId;
-            }
-        }
-        return null;
-    }
-    /**
-     * Check if a path matches a pattern
-     *
-     * Supports:
-     * - Required parameters: :param
-     * - Optional parameters: :param?
-     *
-     * @param path - Actual URL path
-     * @param pattern - Route pattern with :param syntax
-     * @returns true if path matches pattern
-     *
-     * @example
-     * ```typescript
-     * matchesPattern('/profile/123', '/profile/:userId');  // true
-     * matchesPattern('/settings', '/settings/:section?');  // true
-     * matchesPattern('/settings/account', '/settings/:section?'); // true
-     * ```
-     */
-    matchesPattern(path, pattern) {
-        // Convert route pattern to regex
-        // Process replacements in correct order: optional params first, then required
-        let regexPattern = pattern
-            // Replace /:param? with optional segment (matches both /value and nothing)
-            .replace(/\/:(\w+)\?/g, "(?:/([^/]+))?")
-            // Replace /:param with required segment
-            .replace(/\/:(\w+)/g, "/([^/]+)");
-        // Add anchors for exact match
-        regexPattern = "^" + regexPattern + "$";
-        const regex = new RegExp(regexPattern);
-        return regex.test(path);
-    }
+import { BaseRouteMap } from "@xmachines/play-router";
+export class RouteMap extends BaseRouteMap {
 }
 //# sourceMappingURL=route-map.js.map

package/dist/route-map.js.map

@@ -1 +1 @@
-{"version":3,"file":"route-map.js","sourceRoot":"","sources":["../src/route-map.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,OAAO,QAAQ;IACZ,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEhD;;;;;;;;;;;;;OAaG;IACH,YAAY,QAAwB;QACnC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE;YACtC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACpC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,OAAe;QAC/B,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;IAC9C,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAY;QAC5B,oDAAoD;QACpD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAEnD,oCAAoC;QACpC,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC;QACzC,CAAC;QAED,iCAAiC;QACjC,KAAK,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACnD,IAAI,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC;gBAC7C,OAAO,OAAO,CAAC;YAChB,CAAC;QACF,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACK,cAAc,CAAC,IAAY,EAAE,OAAe;QACnD,iCAAiC;QACjC,8EAA8E;QAC9E,IAAI,YAAY,GAAG,OAAO;YACzB,2EAA2E;aAC1E,OAAO,CAAC,aAAa,EAAE,eAAe,CAAC;YACxC,wCAAwC;aACvC,OAAO,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;QAEnC,8BAA8B;QAC9B,YAAY,GAAG,GAAG,GAAG,YAAY,GAAG,GAAG,CAAC;QAExC,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,YAAY,CAAC,CAAC;QACvC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;CACD"}
+{"version":3,"file":"route-map.js","sourceRoot":"","sources":["../src/route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,MAAM,OAAO,QAAS,SAAQ,YAAY;CAAG"}

package/dist/types.d.ts

@@ -3,8 +3,21 @@
  */
 export type { RouterBridge, PlayRouteEvent } from "@xmachines/play-router";
 export type { AbstractActor } from "@xmachines/play-actor";
+/**
+ * A single state ID ↔ path mapping entry for the TanStack Solid Router adapter.
+ *
+ * Structurally compatible with `BaseRouteMapping` from `@xmachines/play-router`.
+ * Fields are `readonly` — entries are immutable once passed to `RouteMap`.
+ *
+ * @example
+ * ```typescript
+ * const mapping: RouteMapping = { stateId: "#profile", path: "/profile/:userId" };
+ * ```
+ */
 export interface RouteMapping {
-    stateId: string;
-    path: string;
+    /** XMachines state ID (e.g., `"#home"`, `"#profile"`) */
+    readonly stateId: string;
+    /** TanStack Router path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) */
+    readonly path: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC3E,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACb"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC3E,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gGAAgG;IAChG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-tanstack-solid-router",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.9",
   "description": "TanStack Solid Router adapter for XMachines Universal Player Architecture",
   "license": "MIT",
   "author": "XMachines Contributors",
@@ -28,27 +28,29 @@
   },
   "scripts": {
     "build": "tsc --build",
-    "test": "vitest run",
+    "test": "vitest",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist *.tsbuildinfo",
+    "clean": "rm -rf dist *.tsbuildinfo node_modules/.vite node_modules/.vite-temp",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@xmachines/play": "1.0.0-beta.7",
-    "@xmachines/play-actor": "1.0.0-beta.7",
-    "@xmachines/play-router": "1.0.0-beta.7",
-    "@xmachines/play-signals": "1.0.0-beta.7"
+    "@xmachines/play": "1.0.0-beta.9",
+    "@xmachines/play-actor": "1.0.0-beta.9",
+    "@xmachines/play-router": "1.0.0-beta.9",
+    "@xmachines/play-signals": "1.0.0-beta.9"
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8.10",
     "@tanstack/solid-router": "^1.167.5",
-    "@xmachines/shared": "1.0.0-beta.7",
+    "@xmachines/shared": "1.0.0-beta.9",
     "solid-js": "^1.9.11",
-    "vite-plugin-solid": "^2.11.11"
+    "vite-plugin-solid": "^2.11.11",
+    "vitest": "^4.1.0",
+    "xstate": "^5.28.0"
   },
   "peerDependencies": {
-    "@tanstack/solid-router": "^1.166.7",
+    "@tanstack/solid-router": "^1.108.0",
     "solid-js": "^1.8.0"
   }
 }