@xmachines/play-solid-router 1.0.0-beta.1

package/README.md

@@ -0,0 +1,637 @@
+# @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:
+
+- **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
+
+**Framework Compatibility:**
+
+- SolidJS 1.8.4+ (signals-native architecture)
+- @solidjs/router 0.13.0+ (modern routing primitives)
+- TC39 Signals polyfill integration
+
+## Installation
+
+```bash
+npm install @solidjs/router@^0.13.0 solid-js@^1.8.0 @xmachines/play-solid-router @xmachines/play-solid
+```
+
+**Peer dependencies:**
+
+- `@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
+
+## 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>
+  );
+}
+```
+
+## API Reference
+
+### `SolidRouterBridge`
+
+Router adapter implementing the `RouterBridge` protocol for SolidJS Router.
+
+**Type Signature:**
+
+```typescript
+class SolidRouterBridge {
+	constructor(
+		navigate: ReturnType<typeof useNavigate>,
+		location: ReturnType<typeof useLocation>,
+		params: ReturnType<typeof useParams>,
+		actor: AbstractActor<any>,
+		routeMap: RouteMap,
+	);
+	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>
+  );
+}
+```
+
+**Usage in component:**
+
+```tsx
+function ProfileButton(props: { userId: string }) {
+	return (
+		<button
+			onClick={() =>
+				props.actor.send({
+					type: "play.route",
+					to: "#profile",
+					params: { userId: props.userId },
+				})
+			}
+		>
+			View Profile
+		</button>
+	);
+}
+```
+
+### 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' },
+      },
+    }
+  }
+};
+
+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>
+  );
+}
+```
+
+**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:**
+
+- 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
+
+### Cleanup: Proper Disposal on Component Unmount
+
+```tsx
+import { onCleanup } from "solid-js";
+import { SolidRouterBridge } 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);
+
+	// CRITICAL: Cleanup effects
+	onCleanup(() => {
+		bridge.dispose();
+	});
+
+	return <Router>...</Router>;
+}
+```
+
+**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
+
+**Package Dependencies:**
+
+- `@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()`
+
+**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)     │    │                  │
+└─────────────┘    └──────────────────┘
+```
+
+### 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):**
+
+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, ...);
+
+// ✅ 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>;
+}
+```
+
+**Why:** Solid's reactivity system requires reactive ownership context. Hooks create tracked scopes that exist only within component lifecycle.
+
+### Pattern Matching for Dynamic Routes
+
+**URLPattern API integration:**
+
+```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:**
+
+- `: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?" },
+]);
+
+routeMap.getStateIdByPath("/profile/123"); // '#profile'
+routeMap.getStateIdByPath("/settings"); // '#settings'
+routeMap.getStateIdByPath("/settings/privacy"); // '#settings'
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,25 @@
+/**
+ * Create RouteMap helper for SolidJS Router adapter
+ *
+ * Simplifies demo code by hiding route extraction complexity.
+ * Internally calls extractMachineRoutes() and getRoutableRoutes(),
+ * then constructs RouteMap with proper state ID ↔ path mappings.
+ */
+import type { AnyStateMachine } from "xstate";
+import { RouteMap } from "./route-map.js";
+/**
+ * Create a RouteMap from an XState machine
+ *
+ * @param machine - XState machine with route: {} config on states
+ * @returns RouteMap for bidirectional state ID ↔ path resolution
+ *
+ * @example
+ * ```typescript
+ * import { createRouteMap } from '@xmachines/play-solid-router';
+ * import { authMachine } from './machine.js';
+ *
+ * const routeMap = createRouteMap(authMachine);
+ * ```
+ */
+export declare function createRouteMap(machine: AnyStateMachine): RouteMap;
+//# sourceMappingURL=create-route-map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-route-map.d.ts","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAcjE"}

package/dist/create-route-map.js

@@ -0,0 +1,36 @@
+/**
+ * Create RouteMap helper for SolidJS Router adapter
+ *
+ * Simplifies demo code by hiding route extraction complexity.
+ * Internally calls extractMachineRoutes() and getRoutableRoutes(),
+ * then constructs RouteMap with proper state ID ↔ path mappings.
+ */
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
+import { RouteMap } from "./route-map.js";
+/**
+ * Create a RouteMap from an XState machine
+ *
+ * @param machine - XState machine with route: {} config on states
+ * @returns RouteMap for bidirectional state ID ↔ path resolution
+ *
+ * @example
+ * ```typescript
+ * import { createRouteMap } from '@xmachines/play-solid-router';
+ * import { authMachine } from './machine.js';
+ *
+ * const routeMap = createRouteMap(authMachine);
+ * ```
+ */
+export function createRouteMap(machine) {
+    // Extract route tree from machine
+    const routeTree = extractMachineRoutes(machine);
+    // Get only routable nodes (states with route: {} config)
+    const routes = getRoutableRoutes(routeTree);
+    // Map to RouteMapping format expected by RouteMap constructor
+    const mappings = routes.map((node) => ({
+        stateId: node.stateId,
+        path: node.fullPath,
+    }));
+    return new RouteMap(mappings);
+}
+//# sourceMappingURL=create-route-map.js.map

package/dist/create-route-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-route-map.js","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,OAAwB;IACtD,kCAAkC;IAClC,MAAM,SAAS,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAEhD,yDAAyD;IACzD,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAE5C,8DAA8D;IAC9D,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtC,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI,EAAE,IAAI,CAAC,QAAQ;KACnB,CAAC,CAAC,CAAC;IAEJ,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @xmachines/play-solid-router
+ *
+ * SolidJS Router adapter for XMachines Universal Player Architecture
+ */
+export { SolidRouterBridge } from "./solid-router-bridge.js";
+export { PlayRouterProvider } from "./play-router-provider.js";
+export type { PlayRouterProviderProps, RoutableActor, SolidRouterHooks, } from "./play-router-provider.js";
+export { RouteMap } from "./route-map.js";
+export { createRouteMap } from "./create-route-map.js";
+export type { RouteMapping, PlayRouteEvent, RouterBridge, AbstractActor } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EACX,uBAAuB,EACvB,aAAa,EACb,gBAAgB,GAChB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @xmachines/play-solid-router
+ *
+ * SolidJS Router adapter for XMachines Universal Player Architecture
+ */
+export { SolidRouterBridge } from "./solid-router-bridge.js";
+export { PlayRouterProvider } from "./play-router-provider.js";
+export { RouteMap } from "./route-map.js";
+export { createRouteMap } from "./create-route-map.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAM/D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/play-router-provider.d.ts

@@ -0,0 +1,21 @@
+import { type JSX } from "solid-js";
+import type { AbstractActor, Routable, Viewable } from "@xmachines/play-actor";
+import type { AnyActorLogic } from "xstate";
+import type { RouteMap } from "./route-map.js";
+export type RoutableActor = AbstractActor<AnyActorLogic> & Routable & Viewable;
+export type SolidRouterHooks = {
+    navigate: ((path: string) => void) | ((path: string, ...args: unknown[]) => unknown);
+    location: {
+        pathname: string;
+        search: string;
+    };
+    params: Record<string, string | undefined>;
+};
+export interface PlayRouterProviderProps {
+    actor: RoutableActor;
+    routeMap: RouteMap;
+    router: SolidRouterHooks;
+    renderer: (actor: RoutableActor, router: SolidRouterHooks) => JSX.Element;
+}
+export declare function PlayRouterProvider(props: PlayRouterProviderProps): any;
+//# sourceMappingURL=play-router-provider.d.ts.map

package/dist/play-router-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"play-router-provider.d.ts","sourceRoot":"","sources":["../src/play-router-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAC/E,MAAM,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAC;IACrF,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC3C,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACvC,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,KAAK,GAAG,CAAC,OAAO,CAAC;CAC1E;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,OAehE"}

package/dist/play-router-provider.jsx

@@ -0,0 +1,11 @@
+import { onCleanup } from "solid-js";
+import { SolidRouterBridge } from "./solid-router-bridge.js";
+export function PlayRouterProvider(props) {
+    const bridge = new SolidRouterBridge(props.router.navigate, props.router.location, props.router.params, props.actor, props.routeMap);
+    bridge.connect();
+    onCleanup(() => {
+        bridge.disconnect();
+    });
+    return <>{props.renderer(props.actor, props.router)}</>;
+}
+//# sourceMappingURL=play-router-provider.jsx.map

package/dist/play-router-provider.jsx.map

@@ -0,0 +1 @@
+{"version":3,"file":"play-router-provider.jsx","sourceRoot":"","sources":["../src/play-router-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAY,MAAM,UAAU,CAAC;AAG/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAiB7D,MAAM,UAAU,kBAAkB,CAAC,KAA8B;IAChE,MAAM,MAAM,GAAG,IAAI,iBAAiB,CACnC,KAAK,CAAC,MAAM,CAAC,QAAQ,EACrB,KAAK,CAAC,MAAM,CAAC,QAAQ,EACrB,KAAK,CAAC,MAAM,CAAC,MAAM,EACnB,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,QAAQ,CACd,CAAC;IACF,MAAM,CAAC,OAAO,EAAE,CAAC;IAEjB,SAAS,CAAC,GAAG,EAAE;QACd,MAAM,CAAC,UAAU,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC;AACzD,CAAC"}

package/dist/route-map.d.ts

@@ -0,0 +1,75 @@
+/**
+ * RouteMap for bidirectional state ID ↔ path mapping
+ *
+ * Provides efficient lookup between XMachines state IDs and SolidJS Router paths.
+ * Supports pattern matching for dynamic routes with parameters.
+ */
+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 undefined if not found
+     *
+     * @example
+     * ```typescript
+     * routeMap.getPath('#profile'); // '/profile/:userId'
+     * ```
+     */
+    getPath(stateId: string): string | undefined;
+    /**
+     * 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 undefined if no match found
+     *
+     * @example
+     * ```typescript
+     * routeMap.getStateIdByPath('/profile/123');  // '#profile'
+     * routeMap.getStateIdByPath('/settings');      // '#settings'
+     * routeMap.getStateIdByPath('/settings/account'); // '#settings'
+     * ```
+     */
+    getStateIdByPath(path: string): string | undefined;
+    /**
+     * 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;
+}
+//# sourceMappingURL=route-map.d.ts.map

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

@@ -0,0 +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,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5C;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAmBlD;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,cAAc;CAetB"}

package/dist/route-map.js

@@ -0,0 +1,107 @@
+/**
+ * RouteMap for bidirectional state ID ↔ path mapping
+ *
+ * Provides efficient lookup between XMachines state IDs and SolidJS Router paths.
+ * Supports pattern matching for dynamic routes with parameters.
+ */
+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 undefined if not found
+     *
+     * @example
+     * ```typescript
+     * routeMap.getPath('#profile'); // '/profile/:userId'
+     * ```
+     */
+    getPath(stateId) {
+        return this.stateToPath.get(stateId);
+    }
+    /**
+     * 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 undefined 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 undefined;
+    }
+    /**
+     * 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);
+    }
+}
+//# sourceMappingURL=route-map.js.map

package/dist/route-map.js.map

@@ -0,0 +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,OAAO,CAAC,OAAe;QACtB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACtC,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,CAAC,CAAC;QACxC,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,SAAS,CAAC;IAClB,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"}

package/dist/solid-router-bridge.d.ts

@@ -0,0 +1,90 @@
+/**
+ * SolidJS Router bridge implementing RouterBridge protocol via RouterBridgeBase
+ *
+ * Extends RouterBridgeBase to handle all common lifecycle and sync logic.
+ * Uses Solid's native reactive primitives (createEffect) for router→actor direction.
+ *
+ * **IMPORTANT:** `connect()` MUST be called inside a Solid reactive owner (component
+ * or createRoot). The createEffect() in watchRouterChanges() relies on Solid's
+ * reactive system for automatic cleanup.
+ *
+ * @example
+ * ```tsx
+ * import { useNavigate, useLocation, useParams } from '@solidjs/router';
+ * import { onCleanup } from 'solid-js';
+ * import { SolidRouterBridge, RouteMap } from '@xmachines/play-solid-router';
+ *
+ * function App() {
+ *   const navigate = useNavigate();
+ *   const location = useLocation();
+ *   const params = useParams();
+ *
+ *   const routeMap = new RouteMap([...]);
+ *   const bridge = new SolidRouterBridge(navigate, location, params, actor, routeMap);
+ *
+ *   // connect() MUST be called inside a Solid reactive owner
+ *   bridge.connect();
+ *   onCleanup(() => bridge.disconnect());
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+import { RouterBridgeBase } from "@xmachines/play-router";
+import type { AbstractActor, Routable } from "@xmachines/play-actor";
+import type { AnyActorLogic } from "xstate";
+import type { RouteMap } from "./route-map.js";
+/**
+ * SolidJS Router integration bridge extending RouterBridgeBase
+ *
+ * Implements RouterBridge protocol for SolidJS Router using Solid's reactive
+ * primitives. The actor→router direction uses TC39 Signal watcher (from base class).
+ * The router→actor direction uses Solid's createEffect for native reactivity.
+ */
+export declare class SolidRouterBridge extends RouterBridgeBase {
+    private readonly solidNavigate;
+    private readonly location;
+    /**
+     * Create a SolidJS Router bridge
+     *
+     * **CRITICAL:** `connect()` must be called inside a Solid component where hooks are available.
+     *
+     * @param solidNavigate - Result of useNavigate() hook
+     * @param location - Result of useLocation() hook
+     * @param _params - Result of useParams() hook
+     * @param actor - XMachines actor instance
+     * @param routeMap - Bidirectional state ID ↔ path mapping
+     */
+    constructor(solidNavigate: ((path: string) => void) | ((path: string, ...args: unknown[]) => unknown), location: {
+        pathname: string;
+        search: string;
+    }, _params: Record<string, string | undefined>, actor: AbstractActor<AnyActorLogic> & Routable, routeMap: RouteMap);
+    /**
+     * Navigate SolidJS Router to the given path.
+     */
+    protected navigateRouter(path: string): void;
+    /**
+     * Subscribe to SolidJS Router location changes using createEffect.
+     *
+     * MUST be called inside a Solid reactive owner (component/createRoot).
+     * Solid auto-cleans createEffect subscriptions on component unmount.
+     */
+    protected watchRouterChanges(): void;
+    /**
+     * Stop watching SolidJS Router changes.
+     *
+     * Solid auto-cleans createEffect subscriptions when component unmounts.
+     * This sets the processing flag to prevent pending operations.
+     */
+    protected unwatchRouterChanges(): void;
+    /**
+     * Dispose the bridge (alias for disconnect).
+     *
+     * @example
+     * ```tsx
+     * onCleanup(() => bridge.dispose());
+     * ```
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=solid-router-bridge.d.ts.map

package/dist/solid-router-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solid-router-bridge.d.ts","sourceRoot":"","sources":["../src/solid-router-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,gBAAgB;IAarD,OAAO,CAAC,QAAQ,CAAC,aAAa;IAG9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAf1B;;;;;;;;;;OAUG;gBAEe,aAAa,EAC3B,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GACxB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,EACjC,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC/D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC3C,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE,QAAQ;IAQnB;;OAEG;IACH,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5C;;;;;OAKG;IACH,SAAS,CAAC,kBAAkB,IAAI,IAAI;IAcpC;;;;;OAKG;IACH,SAAS,CAAC,oBAAoB,IAAI,IAAI;IAMtC;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;CAGf"}

package/dist/solid-router-bridge.js

@@ -0,0 +1,107 @@
+/**
+ * SolidJS Router bridge implementing RouterBridge protocol via RouterBridgeBase
+ *
+ * Extends RouterBridgeBase to handle all common lifecycle and sync logic.
+ * Uses Solid's native reactive primitives (createEffect) for router→actor direction.
+ *
+ * **IMPORTANT:** `connect()` MUST be called inside a Solid reactive owner (component
+ * or createRoot). The createEffect() in watchRouterChanges() relies on Solid's
+ * reactive system for automatic cleanup.
+ *
+ * @example
+ * ```tsx
+ * import { useNavigate, useLocation, useParams } from '@solidjs/router';
+ * import { onCleanup } from 'solid-js';
+ * import { SolidRouterBridge, RouteMap } from '@xmachines/play-solid-router';
+ *
+ * function App() {
+ *   const navigate = useNavigate();
+ *   const location = useLocation();
+ *   const params = useParams();
+ *
+ *   const routeMap = new RouteMap([...]);
+ *   const bridge = new SolidRouterBridge(navigate, location, params, actor, routeMap);
+ *
+ *   // connect() MUST be called inside a Solid reactive owner
+ *   bridge.connect();
+ *   onCleanup(() => bridge.disconnect());
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+import { createEffect, on } from "solid-js";
+import { RouterBridgeBase } from "@xmachines/play-router";
+/**
+ * SolidJS Router integration bridge extending RouterBridgeBase
+ *
+ * Implements RouterBridge protocol for SolidJS Router using Solid's reactive
+ * primitives. The actor→router direction uses TC39 Signal watcher (from base class).
+ * The router→actor direction uses Solid's createEffect for native reactivity.
+ */
+export class SolidRouterBridge extends RouterBridgeBase {
+    solidNavigate;
+    location;
+    /**
+     * Create a SolidJS Router bridge
+     *
+     * **CRITICAL:** `connect()` must be called inside a Solid component where hooks are available.
+     *
+     * @param solidNavigate - Result of useNavigate() hook
+     * @param location - Result of useLocation() hook
+     * @param _params - Result of useParams() hook
+     * @param actor - XMachines actor instance
+     * @param routeMap - Bidirectional state ID ↔ path mapping
+     */
+    constructor(solidNavigate, location, _params, actor, routeMap) {
+        super(actor, {
+            getStateIdByPath: (path) => routeMap.getStateIdByPath(path),
+            getPathByStateId: (id) => routeMap.getPath(id),
+        });
+        this.solidNavigate = solidNavigate;
+        this.location = location;
+    }
+    /**
+     * Navigate SolidJS Router to the given path.
+     */
+    navigateRouter(path) {
+        this.solidNavigate(path);
+    }
+    /**
+     * Subscribe to SolidJS Router location changes using createEffect.
+     *
+     * MUST be called inside a Solid reactive owner (component/createRoot).
+     * Solid auto-cleans createEffect subscriptions on component unmount.
+     */
+    watchRouterChanges() {
+        // MUST be called inside Solid reactive owner (component or createRoot)
+        // createEffect in watchRouterChanges() relies on Solid's reactive system
+        createEffect(on(() => this.location.pathname, (pathname) => {
+            const search = this.location.search ?? "";
+            this.syncActorFromRouter(pathname, search);
+        }));
+    }
+    /**
+     * Stop watching SolidJS Router changes.
+     *
+     * Solid auto-cleans createEffect subscriptions when component unmounts.
+     * This sets the processing flag to prevent pending operations.
+     */
+    unwatchRouterChanges() {
+        // Solid auto-cleans createEffect on component unmount
+        // Set flag to prevent any pending operations
+        this.isProcessingNavigation = true;
+    }
+    /**
+     * Dispose the bridge (alias for disconnect).
+     *
+     * @example
+     * ```tsx
+     * onCleanup(() => bridge.dispose());
+     * ```
+     */
+    dispose() {
+        this.disconnect();
+    }
+}
+//# sourceMappingURL=solid-router-bridge.js.map

package/dist/solid-router-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solid-router-bridge.js","sourceRoot":"","sources":["../src/solid-router-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK1D;;;;;;GAMG;AACH,MAAM,OAAO,iBAAkB,SAAQ,gBAAgB;IAapC;IAGA;IAflB;;;;;;;;;;OAUG;IACH,YACkB,aAEiC,EACjC,QAA8C,EAC/D,OAA2C,EAC3C,KAA8C,EAC9C,QAAkB;QAElB,KAAK,CAAC,KAAK,EAAE;YACZ,gBAAgB,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC;YACnE,gBAAgB,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;SACtD,CAAC,CAAC;QAXc,kBAAa,GAAb,aAAa,CAEoB;QACjC,aAAQ,GAAR,QAAQ,CAAsC;IAShE,CAAC;IAED;;OAEG;IACO,cAAc,CAAC,IAAY;QACpC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;;;;OAKG;IACO,kBAAkB;QAC3B,uEAAuE;QACvE,yEAAyE;QACzE,YAAY,CACX,EAAE,CACD,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAC5B,CAAC,QAAgB,EAAE,EAAE;YACpB,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC;YAC1C,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC5C,CAAC,CACD,CACD,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACO,oBAAoB;QAC7B,sDAAsD;QACtD,6CAA6C;QAC7C,IAAI,CAAC,sBAAsB,GAAG,IAAI,CAAC;IACpC,CAAC;IAED;;;;;;;OAOG;IACH,OAAO;QACN,IAAI,CAAC,UAAU,EAAE,CAAC;IACnB,CAAC;CACD"}

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Type definitions for @xmachines/play-solid-router
+ */
+/**
+ * Mapping between state ID and URL path for SolidJS Router
+ */
+export interface RouteMapping {
+    /**
+     * XMachines state ID with # prefix
+     * @example '#home', '#profile'
+     */
+    readonly stateId: string;
+    /**
+     * SolidJS Router path pattern
+     * @example '/', '/profile/:userId', '/settings/:section?'
+     */
+    readonly path: string;
+}
+export type { PlayRouteEvent, RouterBridge } from "@xmachines/play-router";
+export type { AbstractActor } from "@xmachines/play-actor";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAGD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3E,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for @xmachines/play-solid-router
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@xmachines/play-solid-router",
+  "version": "1.0.0-beta.1",
+  "description": "SolidJS Router adapter for XMachines Universal Player Architecture",
+  "license": "MIT",
+  "author": "XMachines Contributors",
+  "repository": {
+    "type": "git",
+    "url": "git@gitlab.com:xmachin-es/xmachines-js.git",
+    "directory": "packages/play-solid-router"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@xmachines/play": "1.0.0-beta.1",
+    "@xmachines/play-actor": "1.0.0-beta.1",
+    "@xmachines/play-router": "1.0.0-beta.1",
+    "@xmachines/play-signals": "1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@solidjs/router": "^0.15.4",
+    "@solidjs/testing-library": "^0.8.0",
+    "solid-js": "^1.8.0"
+  },
+  "peerDependencies": {
+    "@solidjs/router": "^0.15.4",
+    "solid-js": "^1.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}