@xmachines/play-solid-router 2.0.0-alpha.1 → 2.1.0

package/README.md

@@ -1,10 +1,8 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-solid-router
 
-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 Router adapter for the XMachines Universal Player Architecture. It keeps the state machine routes of a `PlayerActor` and the browser URL in step, in both directions, through `@solidjs/router`.
 
-Part of the [xmachines-js monorepo](../../README.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-solid-router)
 
 ## Installation
 
@@ -12,7 +10,7 @@ Part of the [xmachines-js monorepo](../../README.md).
 pnpm add @xmachines/play-solid-router
 ```
 
-**Peer dependencies** (must be installed separately):
+**Peer dependencies.** Install them separately:
 
 ```bash
 pnpm add solid-js @solidjs/router xstate
@@ -20,7 +18,7 @@ pnpm add solid-js @solidjs/router xstate
 
 - `solid-js` `^1.8.0`
 - `@solidjs/router` `^0.16.1`
-- `xstate` `^6.0.0-alpha.19`
+- `xstate` `^5.31.0`
 
 ## Quick Start
 
@@ -36,6 +34,10 @@ actor.start();
 
 const routeMap = createRouteMap(myMachine);
 
+// Minimal app shell stub — a real app renders PlayUIProvider + PlayRenderer from
+// @xmachines/play-solid here (see the workspace-only @xmachines/play-solid-demo Shell)
+const MyApp = (props: { actor: typeof actor }) => <main />;
+
 const Layout: ParentComponent = () => {
 	const navigate = useNavigate();
 	const location = useLocation();
@@ -62,7 +64,7 @@ export default function App() {
 
 ### `PlayRouterProvider`
 
-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.
+This SolidJS component connects a `PlayerActor` to Solid Router. It creates and connects a `SolidRouterBridge` on mount. It disconnects the bridge with `onCleanup` on unmount.
 
 ```tsx
 interface PlayRouterProviderProps<TActor extends PlayActor> {
@@ -83,14 +85,17 @@ interface PlayRouterProviderProps<TActor extends PlayActor> {
 
 ### `SolidRouterBridge`
 
-Low-level class for manual integration. Extends `RouterBridgeBase` from `@xmachines/play-router` and uses Solid's `createEffect` for reactive router→actor sync.
+The low-level class for a manual integration. It extends `RouterBridgeBase` from `@xmachines/play-router`. It uses the Solid `createEffect` to send each router change to the actor.
 
-> **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()`.
+> **Important:** call `connect()` inside a Solid reactive owner: a component, or `createRoot`. The bridge does not clean up by itself. Call `disconnect()` or `dispose()` yourself, usually in `onCleanup()`.
 
 ```tsx
-import { useNavigate, useLocation, useParams, onCleanup } from "@solidjs/router";
+import { useNavigate, useLocation, useParams } from "@solidjs/router";
+import { onCleanup } from "solid-js";
 import { SolidRouterBridge, RouteMap } from "@xmachines/play-solid-router";
 
+// actor: your started player (see the Quick Start above)
+
 function App() {
 	const navigate = useNavigate();
 	const location = useLocation();
@@ -111,7 +116,7 @@ function App() {
 
 ### `createRouteMap(machine)`
 
-Factory that builds a `RouteMap` directly from an XState machine definition. Re-exported from `@xmachines/play-router`.
+This factory builds a `RouteMap` directly from an XState machine definition. It comes from `@xmachines/play-router`.
 
 ```ts
 import { createRouteMap } from "@xmachines/play-solid-router";
@@ -121,7 +126,7 @@ const routeMap = createRouteMap(myMachine);
 
 ### `RouteMap` / `RouteMapping`
 
-Bidirectional state ID ↔ URL path mapping. Re-exported from `@xmachines/play-router`.
+The bidirectional map between the state IDs and the URL paths. It comes from `@xmachines/play-router`.
 
 ```ts
 import { RouteMap } from "@xmachines/play-solid-router";
@@ -135,44 +140,44 @@ const routeMap = new RouteMap([
 
 ### Types
 
-| Export                    | Description                                                                                                                                                                                             |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PlayActor`               | `AbstractActor & Routable & Viewable` — canonical actor shape from `@xmachines/play-router`. Required by `PlayRouterProvider`, which renders the current view spec in addition to synchronizing routes. |
-| `RoutableActor`           | Deprecated alias for `PlayActor`. Use `PlayActor` from `@xmachines/play-router` in new code.                                                                                                            |
-| `AbstractActor`           | Re-exported from `@xmachines/play-actor` for convenience when typing renderer callbacks.                                                                                                                |
-| `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`                                                                                                                                                            |
-| `RouteMapOptions`         | Options bag for `RouteMap` construction. Re-exported from `@xmachines/play-router`.                                                                                                                     |
+| Export                    | Description                                                                                                                                                                                                    |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PlayActor`               | `AbstractActor & Routable & Viewable` — the canonical actor shape from `@xmachines/play-router`. `PlayRouterProvider` requires it, because it renders the current view spec and also keeps the routes in step. |
+| `RoutableActor`           | Deprecated alias for `PlayActor`. Use `PlayActor` from `@xmachines/play-router` in new code.                                                                                                                   |
+| `AbstractActor`           | It comes from `@xmachines/play-actor`. Use it for the type of a renderer callback.                                                                                                                             |
+| `SolidRouterHooks`        | Shape of the `router` prop: `{ navigate, location, params }`                                                                                                                                                   |
+| `PlayRouterProviderProps` | Full props interface for `PlayRouterProvider`                                                                                                                                                                  |
+| `PlayRouteEvent`          | The event type that the bridge sends to the actor on a URL change (`play.route`)                                                                                                                               |
+| `RouterBridge`            | The interface that `SolidRouterBridge` implements                                                                                                                                                              |
+| `RouteMapOptions`         | The options object for the `RouteMap` constructor. It comes from `@xmachines/play-router`.                                                                                                                     |
 
 ## Usage Patterns
 
 ### Protected Routes and Guards
 
-Auth guards live entirely inside the state machine, preventing flashes of unauthorized content:
+The auth guards are inside the state machine only. Unauthorized content therefore never appears, not even for a moment:
 
 ```ts
 const machineConfig = {
 	states: {
 		dashboard: {
 			meta: { route: "/dashboard" },
-			always: ({ context }) => {
-				if (context.isAuthenticated) return;
-				return { target: "login" };
+			always: {
+				guard: ({ context }) => !context.isAuthenticated,
+				target: "login",
 			},
 		},
 	},
 };
 ```
 
-When a user navigates to `/dashboard` while unauthenticated:
+A user navigates to `/dashboard`, and the user is not authenticated:
 
 1. Solid Router updates the URL.
-2. Bridge intercepts and sends `play.route` to the actor.
-3. Actor evaluates the guard — denies transition, moves to `login` instead.
-4. Bridge observes new actor route (`/login`) via TC39 Signal.
-5. Bridge calls `navigate("/login")`.
+2. The bridge receives the change and sends `play.route` to the actor.
+3. The actor evaluates the guard. The guard refuses the transition, and the actor moves to `login`.
+4. The bridge reads the new actor route (`/login`) from the TC39 Signal.
+5. The bridge calls `navigate("/login")`.
 
 ### Dynamic Routes with Parameters
 
@@ -186,7 +191,7 @@ const routeMap = new RouteMap([
 // { type: "play.route", to: "#post", params: { userId: "123", postId: "456" }, query: {} }
 ```
 
-Path parameters are extracted from Solid's reactive `useParams()` proxy — no URLPattern polyfill is needed for parameterized routes.
+The bridge reads the path parameters from the reactive `useParams()` proxy of Solid. A parameterized route therefore does not need the URLPattern polyfill.
 
 ## Testing
 
@@ -200,7 +205,7 @@ pnpm --filter @xmachines/play-solid-router test
 pnpm test
 ```
 
-**Browser tests** (`test/browser/**/*.browser.test.ts`) run against real Chromium via Playwright, covering async sequencing that jsdom cannot faithfully reproduce:
+**Browser tests** (`test/browser/**/*.browser.test.ts`) run in real Chromium through Playwright. They cover the asynchronous sequences that jsdom cannot reproduce:
 
 ```bash
 pnpm exec vitest --config vitest.browser.config.ts --project play-solid-router-browser
@@ -213,7 +218,7 @@ Coverage thresholds: **80%** lines, functions, branches, and statements.
 - [@xmachines/play-router](../play-router/README.md) — core router primitives and `RouterBridgeBase`
 - [@xmachines/play-tanstack-solid-router](../play-tanstack-solid-router/README.md) — TanStack Solid Router adapter
 - [@xmachines/play-solid](../play-solid/README.md) — SolidJS view renderer
-- [@xmachines/play-xstate](../play-xstate/README.md) — XState v6 player factory
+- [@xmachines/play-xstate](../play-xstate/README.md) — XState v5 player factory
 
 ## Learn More
 

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

@@ -1,57 +1,58 @@
 /**
- * createPlayRouterProvider — factory for Solid `PlayRouterProvider` components
+ * createPlayRouterProvider — the factory of a Solid `PlayRouterProvider` component
  *
- * Captures the provider component shape used by this package's
- * `PlayRouterProvider` — create a bridge synchronously at component evaluation
- * time, `connect()` it, and `disconnect()` in `onCleanup` — so that Solid
- * bridges with the standard `(router, actor, routeMap)` constructor can be
- * wrapped in a provider with a single call. Only the bridge class (and
- * therefore the `router` prop type) differs between providers created by this
- * factory.
+ * The factory holds the shape of the provider component of this package: it creates a
+ * bridge synchronously, during the evaluation of the component, it calls `connect()`,
+ * and it calls `disconnect()` in `onCleanup`. One call therefore wraps each Solid
+ * bridge with the standard `(router, actor, routeMap)` constructor in a provider. The
+ * bridge class, and therefore the type of the `router` prop, is the one difference
+ * between two providers of this factory.
  *
  * @packageDocumentation
  */
 import { type JSX } from "solid-js";
 import type { PlayActor, RouteMap, RouterBridge } from "@xmachines/play-router";
 /**
- * Constructor shape a bridge class must satisfy to be used with
+ * The constructor shape that a bridge class must satisfy for
  * `createPlayRouterProvider`: `(router, actor, routeMap) → RouterBridge`.
  *
- * Bridges with a different constructor shape (e.g. `SolidRouterBridge`, which
- * takes the hook results as separate arguments) are adapted with a thin
- * subclass that repackages the `router` prop.
+ * A bridge with another constructor shape, for example `SolidRouterBridge`, which
+ * takes each hook result as a separate argument, receives a thin subclass. That
+ * subclass packs the `router` prop again.
  */
 export type PlayRouterBridgeConstructor<TRouter> = new (router: TRouter, actor: PlayActor, routeMap: RouteMap) => RouterBridge;
 /**
- * Props shared by every factory-created Solid `PlayRouterProvider`.
+ * The props that every Solid `PlayRouterProvider` of the factory shares.
  *
- * Adapter packages re-export a concrete alias with `TRouter` bound to their
- * router type (e.g. `SolidRouterHooks` in `@xmachines/play-solid-router`).
+ * An adapter package re-exports a concrete alias, with `TRouter` bound to the type of
+ * its router. For example, `SolidRouterHooks` in `@xmachines/play-solid-router`.
  */
 export interface PlayRouterProviderBaseProps<TRouter, TActor extends PlayActor = PlayActor> {
-    /** The actor to sync with the router. */
+    /** The actor to keep in step with the router. */
     actor: TActor;
-    /** The router the bridge synchronizes with. */
+    /** The router that the bridge keeps in step with the actor. */
     router: TRouter;
-    /** Bidirectional route map for state ID ↔ URL path lookups. */
+    /** The route map of both directions, for the lookup between a state ID and a URL path. */
     routeMap: RouteMap;
-    /** Renderer callback receives the same concrete actor type that was passed in. */
+    /** The renderer callback receives the same concrete actor type as the prop. */
     renderer: (actor: TActor, router: TRouter) => JSX.Element;
 }
 /**
- * Create a Solid `PlayRouterProvider` component bound to a specific bridge class.
+ * Creates a Solid `PlayRouterProvider` component of one bridge class.
  *
- * The returned component connects a `PlayerActor` to the framework router,
- * keeping actor state and browser URL in sync bidirectionally.
+ * The component of the return value connects a `PlayerActor` to the framework
+ * router. It keeps the actor state and the browser URL in step, in both directions.
  *
- * The bridge is created synchronously at component evaluation time (Solid's
- * execution model) and torn down via `onCleanup` when the component is disposed.
- * Unlike React, prop stability is not a concern — Solid's `props` accessor is
- * already reactive and the bridge is created once per component instance.
+ * The component creates the bridge synchronously, during its own evaluation, because
+ * this is the execution model of Solid. It disconnects the bridge in `onCleanup`,
+ * when Solid disposes of the component. React is different: the stability of a prop
+ * is no concern here, because the `props` accessor of Solid is reactive already, and
+ * the component creates the bridge one time for each of its instances.
  *
- * @param BridgeCtor - Bridge class constructed as `new BridgeCtor(router, actor, routeMap)`.
- * @returns A `PlayRouterProvider` component, generic over the actor type so the
- *   `renderer` callback receives the same concrete actor type that was passed in.
+ * @param BridgeCtor - The bridge class. The provider builds it as `new BridgeCtor(router, actor, routeMap)`.
+ * @returns A `PlayRouterProvider` component. It is generic over the actor type.
+ *   Therefore the `renderer` callback receives the same concrete actor type as the
+ *   prop.
  *
  * @example
  * ```tsx

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

@@ -1 +1 @@
-{"version":3,"file":"create-play-router-provider.d.ts","sourceRoot":"","sources":["../src/create-play-router-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAa,KAAK,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEhF;;;;;;;GAOG;AACH,MAAM,MAAM,2BAA2B,CAAC,OAAO,IAAI,KAClD,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,QAAQ,KACd,YAAY,CAAC;AAElB;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B,CAAC,OAAO,EAAE,MAAM,SAAS,SAAS,GAAG,SAAS;IACzF,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,MAAM,EAAE,OAAO,CAAC;IAChB,+DAA+D;IAC/D,QAAQ,EAAE,QAAQ,CAAC;IACnB,kFAAkF;IAClF,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,GAAG,CAAC,OAAO,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAC/C,UAAU,EAAE,2BAA2B,CAAC,OAAO,CAAC,IAEb,MAAM,SAAS,SAAS,EAC1D,OAAO,2BAA2B,CAAC,OAAO,EAAE,MAAM,CAAC,SAWpD"}
+{"version":3,"file":"create-play-router-provider.d.ts","sourceRoot":"","sources":["../src/create-play-router-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAa,KAAK,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEhF;;;;;;;GAOG;AACH,MAAM,MAAM,2BAA2B,CAAC,OAAO,IAAI,KAClD,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,QAAQ,KACd,YAAY,CAAC;AAElB;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B,CAAC,OAAO,EAAE,MAAM,SAAS,SAAS,GAAG,SAAS;IACzF,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;IAChB,0FAA0F;IAC1F,QAAQ,EAAE,QAAQ,CAAC;IACnB,+EAA+E;IAC/E,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,GAAG,CAAC,OAAO,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAC/C,UAAU,EAAE,2BAA2B,CAAC,OAAO,CAAC,IAEb,MAAM,SAAS,SAAS,EAC1D,OAAO,2BAA2B,CAAC,OAAO,EAAE,MAAM,CAAC,SAWpD"}

package/dist/create-play-router-provider.js

@@ -0,0 +1,51 @@
+import { onCleanup } from "solid-js";
+import { memo } from "solid-js/web";
+//#region packages/play-solid-router/src/create-play-router-provider.tsx
+/**
+* createPlayRouterProvider — the factory of a Solid `PlayRouterProvider` component
+*
+* The factory holds the shape of the provider component of this package: it creates a
+* bridge synchronously, during the evaluation of the component, it calls `connect()`,
+* and it calls `disconnect()` in `onCleanup`. One call therefore wraps each Solid
+* bridge with the standard `(router, actor, routeMap)` constructor in a provider. The
+* bridge class, and therefore the type of the `router` prop, is the one difference
+* between two providers of this factory.
+*
+* @packageDocumentation
+*/
+/**
+* Creates a Solid `PlayRouterProvider` component of one bridge class.
+*
+* The component of the return value connects a `PlayerActor` to the framework
+* router. It keeps the actor state and the browser URL in step, in both directions.
+*
+* The component creates the bridge synchronously, during its own evaluation, because
+* this is the execution model of Solid. It disconnects the bridge in `onCleanup`,
+* when Solid disposes of the component. React is different: the stability of a prop
+* is no concern here, because the `props` accessor of Solid is reactive already, and
+* the component creates the bridge one time for each of its instances.
+*
+* @param BridgeCtor - The bridge class. The provider builds it as `new BridgeCtor(router, actor, routeMap)`.
+* @returns A `PlayRouterProvider` component. It is generic over the actor type.
+*   Therefore the `renderer` callback receives the same concrete actor type as the
+*   prop.
+*
+* @example
+* ```tsx
+* export const PlayRouterProvider = createPlayRouterProvider(MySolidRouterBridge);
+* ```
+*/
+function createPlayRouterProvider(BridgeCtor) {
+	return function PlayRouterProvider(props) {
+		const bridge = new BridgeCtor(props.router, props.actor, props.routeMap);
+		bridge.connect();
+		onCleanup(() => {
+			bridge.disconnect();
+		});
+		return memo(() => props.renderer(props.actor, props.router));
+	};
+}
+//#endregion
+export { createPlayRouterProvider };
+
+//# sourceMappingURL=create-play-router-provider.js.map

package/dist/create-play-router-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-play-router-provider.js","names":["onCleanup","JSX","PlayActor","RouteMap","RouterBridge","PlayRouterBridgeConstructor","router","TRouter","actor","routeMap","PlayRouterProviderBaseProps","TActor","renderer","Element","createPlayRouterProvider","BridgeCtor","PlayRouterProvider","props","bridge","connect","disconnect","_$memo"],"sources":["../src/create-play-router-provider.tsx"],"sourcesContent":["/**\n * createPlayRouterProvider — the factory of a Solid `PlayRouterProvider` component\n *\n * The factory holds the shape of the provider component of this package: it creates a\n * bridge synchronously, during the evaluation of the component, it calls `connect()`,\n * and it calls `disconnect()` in `onCleanup`. One call therefore wraps each Solid\n * bridge with the standard `(router, actor, routeMap)` constructor in a provider. The\n * bridge class, and therefore the type of the `router` prop, is the one difference\n * between two providers of this factory.\n *\n * @packageDocumentation\n */\nimport { onCleanup, type JSX } from \"solid-js\";\nimport type { PlayActor, RouteMap, RouterBridge } from \"@xmachines/play-router\";\n\n/**\n * The constructor shape that a bridge class must satisfy for\n * `createPlayRouterProvider`: `(router, actor, routeMap) → RouterBridge`.\n *\n * A bridge with another constructor shape, for example `SolidRouterBridge`, which\n * takes each hook result as a separate argument, receives a thin subclass. That\n * subclass packs the `router` prop again.\n */\nexport type PlayRouterBridgeConstructor<TRouter> = new (\n\trouter: TRouter,\n\tactor: PlayActor,\n\trouteMap: RouteMap,\n) => RouterBridge;\n\n/**\n * The props that every Solid `PlayRouterProvider` of the factory shares.\n *\n * An adapter package re-exports a concrete alias, with `TRouter` bound to the type of\n * its router. For example, `SolidRouterHooks` in `@xmachines/play-solid-router`.\n */\nexport interface PlayRouterProviderBaseProps<TRouter, TActor extends PlayActor = PlayActor> {\n\t/** The actor to keep in step with the router. */\n\tactor: TActor;\n\t/** The router that the bridge keeps in step with the actor. */\n\trouter: TRouter;\n\t/** The route map of both directions, for the lookup between a state ID and a URL path. */\n\trouteMap: RouteMap;\n\t/** The renderer callback receives the same concrete actor type as the prop. */\n\trenderer: (actor: TActor, router: TRouter) => JSX.Element;\n}\n\n/**\n * Creates a Solid `PlayRouterProvider` component of one bridge class.\n *\n * The component of the return value connects a `PlayerActor` to the framework\n * router. It keeps the actor state and the browser URL in step, in both directions.\n *\n * The component creates the bridge synchronously, during its own evaluation, because\n * this is the execution model of Solid. It disconnects the bridge in `onCleanup`,\n * when Solid disposes of the component. React is different: the stability of a prop\n * is no concern here, because the `props` accessor of Solid is reactive already, and\n * the component creates the bridge one time for each of its instances.\n *\n * @param BridgeCtor - The bridge class. The provider builds it as `new BridgeCtor(router, actor, routeMap)`.\n * @returns A `PlayRouterProvider` component. It is generic over the actor type.\n *   Therefore the `renderer` callback receives the same concrete actor type as the\n *   prop.\n *\n * @example\n * ```tsx\n * export const PlayRouterProvider = createPlayRouterProvider(MySolidRouterBridge);\n * ```\n */\nexport function createPlayRouterProvider<TRouter>(\n\tBridgeCtor: PlayRouterBridgeConstructor<TRouter>,\n) {\n\treturn function PlayRouterProvider<TActor extends PlayActor>(\n\t\tprops: PlayRouterProviderBaseProps<TRouter, TActor>,\n\t) {\n\t\tconst bridge = new BridgeCtor(props.router, props.actor, props.routeMap);\n\t\tvoid bridge.connect();\n\n\t\tonCleanup(() => {\n\t\t\tvoid bridge.disconnect();\n\t\t});\n\n\t\treturn <>{props.renderer(props.actor, props.router)}</>;\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoEA,SAAgBc,yBACfC,YACC;CACD,OAAO,SAASC,mBACfC,OACC;EACD,MAAMC,SAAS,IAAIH,WAAWE,MAAMX,QAAQW,MAAMT,OAAOS,MAAMR,QAAQ;EACvE,OAAYU,QAAQ;EAEpBnB,gBAAgB;GACf,OAAYoB,WAAW;EACxB,CAAC;EAED,OAAAC,WAAUJ,MAAML,SAASK,MAAMT,OAAOS,MAAMX,MAAM,CAAC;CACpD;AACD"}

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 /**
  * @xmachines/play-solid-router
  *
- * SolidJS Router adapter for XMachines Universal Player Architecture
+ * SolidJS Router adapter for the XMachines Universal Player Architecture
  */
 export { SolidRouterBridge } from "./solid-router-bridge.js";
 export { PlayRouterProvider } from "./play-router-provider.js";
-export type { PlayRouterProviderProps, PlayActor, RoutableActor, // @deprecated — use PlayActor from @xmachines/play-router
+export type { PlayRouterProviderProps, PlayActor, RoutableActor, // @deprecated — use PlayActor of @xmachines/play-router
 SolidRouterHooks, } from "./play-router-provider.js";
 export { createPlayRouterProvider } from "./create-play-router-provider.js";
 export type { PlayRouterProviderBaseProps, PlayRouterBridgeConstructor, } from "./create-play-router-provider.js";

package/dist/index.d.ts.map

@@ -1 +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,SAAS,EACT,aAAa,EAAE,0DAA0D;AACzE,gBAAgB,GAChB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,YAAY,EACX,2BAA2B,EAC3B,2BAA2B,GAC3B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACN,QAAQ,EACR,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,GACpB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}
+{"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,SAAS,EACT,aAAa,EAAE,wDAAwD;AACvE,gBAAgB,GAChB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,YAAY,EACX,2BAA2B,EAC3B,2BAA2B,GAC3B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACN,QAAQ,EACR,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,GACpB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,10 +1,5 @@
-/**
- * @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 { createPlayRouterProvider } from "./create-play-router-provider.js";
-export { RouteMap, createRouteMap, } from "@xmachines/play-router";
-//# sourceMappingURL=index.js.map
+import { SolidRouterBridge } from "./solid-router-bridge.js";
+import { createPlayRouterProvider } from "./create-play-router-provider.js";
+import { PlayRouterProvider } from "./play-router-provider.js";
+import { RouteMap, createRouteMap } from "@xmachines/play-router";
+export { PlayRouterProvider, RouteMap, SolidRouterBridge, createPlayRouterProvider, createRouteMap };

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

@@ -1,19 +1,19 @@
 /**
- * PlayRouterProvider — Solid convenience wrapper for SolidRouterBridge
+ * PlayRouterProvider — the Solid wrapper of SolidRouterBridge
  *
- * Created via the shared `createPlayRouterProvider` factory: the bridge is
- * created synchronously at component evaluation time and disconnected via
- * `onCleanup` when the component is disposed.
+ * The shared `createPlayRouterProvider` factory makes this component: it creates the
+ * bridge synchronously, during the evaluation of the component, and it disconnects the
+ * bridge in `onCleanup`, when Solid disposes of the component.
  */
 import type { Navigator, Location, Params } from "@solidjs/router";
 import type { PlayActor } from "@xmachines/play-router";
 import { type PlayRouterProviderBaseProps } from "./create-play-router-provider.js";
 export type { PlayActor };
-/** @deprecated Use `PlayActor` from `@xmachines/play-router`. Will be removed in the next major version. */
+/** @deprecated Use `PlayActor` from `@xmachines/play-router`. The next major version removes this alias. */
 export type RoutableActor = PlayActor;
 /**
- * The three Solid Router hook results that `PlayRouterProvider` and `SolidRouterBridge`
- * require. Pass these directly from your component's hook calls:
+ * The three results of the Solid Router hooks that `PlayRouterProvider` and
+ * `SolidRouterBridge` need. Give them directly from the hook calls of your component:
  *
  * ```tsx
  * const navigate = useNavigate();   // → SolidRouterHooks.navigate
@@ -21,11 +21,11 @@ export type RoutableActor = PlayActor;
  * const params   = useParams();     // → SolidRouterHooks.params
  * ```
  *
- * - `navigate` — used to push URL changes when the actor's `currentRoute` changes.
- * - `location` — `pathname` and `search` are read at `connect()` time for deep-link sync.
- *   Subsequent pathname changes drive router→actor sync via `createEffect`.
- * - `params` — Solid's pre-parsed path parameters for the current route segment. Used
- *   directly in `extractParams()` to avoid re-parsing with URLPattern.
+ * - `navigate` — the bridge pushes each URL change with it, when the `currentRoute` of the actor changes.
+ * - `location` — the bridge reads `pathname` and `search` at the moment of `connect()`, for a deep link.
+ *   Each later change of the pathname then goes to the actor, through `createEffect`.
+ * - `params` — the path parameters of the current route segment, which Solid parsed already. The bridge
+ *   uses them directly in `extractParams()`, and it parses them not again with URLPattern.
  */
 export type SolidRouterHooks = {
     navigate: Navigator;
@@ -33,24 +33,25 @@ export type SolidRouterHooks = {
     params: Params;
 };
 /**
- * Props for the Solid Router `PlayRouterProvider`.
+ * The props of the `PlayRouterProvider` of Solid Router.
  *
- * `router` bundles the three Solid Router hook results that drive bidirectional
- * sync. Obtain these from `useNavigate()`, `useLocation()`, and `useParams()`
- * in the parent component (they must be called inside a router context).
+ * `router` holds the three results of the Solid Router hooks that drive the work in
+ * both directions. Take them from `useNavigate()`, from `useLocation()`, and from
+ * `useParams()` in the parent component. Call each hook inside a router context.
  */
 export interface PlayRouterProviderProps<TActor extends PlayActor = PlayActor> extends PlayRouterProviderBaseProps<SolidRouterHooks, TActor> {
 }
 /**
- * Connects a `PlayerActor` to Solid Router, keeping actor state and browser URL
- * in sync bidirectionally.
+ * Connects a `PlayerActor` to Solid Router. It keeps the actor state and the browser
+ * URL in step, in both directions.
  *
- * The bridge is created synchronously at component evaluation time (Solid's
- * execution model) and torn down via `onCleanup` when the component is disposed.
- * Unlike React, prop stability is not a concern — Solid's `props` accessor is
- * already reactive and the bridge is created once per component instance.
+ * The component creates the bridge synchronously, during its own evaluation, because
+ * this is the execution model of Solid. It disconnects the bridge in `onCleanup`,
+ * when Solid disposes of the component. React is different: the stability of a prop
+ * is no concern here, because the `props` accessor of Solid is reactive already, and
+ * the component creates the bridge one time for each of its instances.
  *
- * The `router` prop must be obtained from Solid Router hooks in the parent component:
+ * Take the `router` prop from the Solid Router hooks in the parent component:
  *
  * ```tsx
  * function AppShell() {

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

@@ -1 +1 @@
-{"version":3,"file":"play-router-provider.d.ts","sourceRoot":"","sources":["../src/play-router-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAEN,KAAK,2BAA2B,EAChC,MAAM,kCAAkC,CAAC;AAE1C,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,4GAA4G;AAC5G,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB,CACvC,MAAM,SAAS,SAAS,GAAG,SAAS,CACnC,SAAQ,2BAA2B,CAAC,gBAAgB,EAAE,MAAM,CAAC;CAAG;AAYlE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,kBAAkB,iGAAmD,CAAC"}
+{"version":3,"file":"play-router-provider.d.ts","sourceRoot":"","sources":["../src/play-router-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAEN,KAAK,2BAA2B,EAChC,MAAM,kCAAkC,CAAC;AAE1C,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,4GAA4G;AAC5G,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB,CACvC,MAAM,SAAS,SAAS,GAAG,SAAS,CACnC,SAAQ,2BAA2B,CAAC,gBAAgB,EAAE,MAAM,CAAC;CAAG;AAalE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,kBAAkB,iGAAmD,CAAC"}

package/dist/play-router-provider.js

@@ -0,0 +1,47 @@
+import { SolidRouterBridge } from "./solid-router-bridge.js";
+import { createPlayRouterProvider } from "./create-play-router-provider.js";
+//#region packages/play-solid-router/src/play-router-provider.tsx
+/**
+* The adapter binds the constructor of `SolidRouterBridge`, which takes the hook
+* results, to the `(router, actor, routeMap)` shape of
+* `createPlayRouterProvider`.
+*/
+var SolidHooksRouterBridge = class extends SolidRouterBridge {
+	constructor(router, actor, routeMap) {
+		super(router.navigate, router.location, router.params, actor, routeMap);
+	}
+};
+/**
+* Connects a `PlayerActor` to Solid Router. It keeps the actor state and the browser
+* URL in step, in both directions.
+*
+* The component creates the bridge synchronously, during its own evaluation, because
+* this is the execution model of Solid. It disconnects the bridge in `onCleanup`,
+* when Solid disposes of the component. React is different: the stability of a prop
+* is no concern here, because the `props` accessor of Solid is reactive already, and
+* the component creates the bridge one time for each of its instances.
+*
+* Take the `router` prop from the Solid Router hooks in the parent component:
+*
+* ```tsx
+* function AppShell() {
+*   const navigate = useNavigate();
+*   const location = useLocation();
+*   const params   = useParams();
+*
+*   return (
+*     <PlayRouterProvider
+*       actor={actor}
+*       routeMap={routeMap}
+*       router={{ navigate, location, params }}
+*       renderer={(a) => <PlayRenderer actor={a} registry={registry} />}
+*     />
+*   );
+* }
+* ```
+*/
+var PlayRouterProvider = createPlayRouterProvider(SolidHooksRouterBridge);
+//#endregion
+export { PlayRouterProvider };
+
+//# sourceMappingURL=play-router-provider.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"play-router-provider.js","names":["Navigator","Location","Params","PlayActor","RouteMap","SolidRouterBridge","createPlayRouterProvider","PlayRouterProviderBaseProps","RoutableActor","SolidRouterHooks","navigate","location","params","PlayRouterProviderProps","TActor","SolidHooksRouterBridge","constructor","router","actor","routeMap","PlayRouterProvider"],"sources":["../src/play-router-provider.tsx"],"sourcesContent":["/**\n * PlayRouterProvider — the Solid wrapper of SolidRouterBridge\n *\n * The shared `createPlayRouterProvider` factory makes this component: it creates the\n * bridge synchronously, during the evaluation of the component, and it disconnects the\n * bridge in `onCleanup`, when Solid disposes of the component.\n */\nimport type { Navigator, Location, Params } from \"@solidjs/router\";\nimport type { PlayActor, RouteMap } from \"@xmachines/play-router\";\nimport { SolidRouterBridge } from \"./solid-router-bridge.js\";\nimport {\n\tcreatePlayRouterProvider,\n\ttype PlayRouterProviderBaseProps,\n} from \"./create-play-router-provider.js\";\n\nexport type { PlayActor };\n\n/** @deprecated Use `PlayActor` from `@xmachines/play-router`. The next major version removes this alias. */\nexport type RoutableActor = PlayActor;\n\n/**\n * The three results of the Solid Router hooks that `PlayRouterProvider` and\n * `SolidRouterBridge` need. Give them directly from the hook calls of your component:\n *\n * ```tsx\n * const navigate = useNavigate();   // → SolidRouterHooks.navigate\n * const location = useLocation();   // → SolidRouterHooks.location\n * const params   = useParams();     // → SolidRouterHooks.params\n * ```\n *\n * - `navigate` — the bridge pushes each URL change with it, when the `currentRoute` of the actor changes.\n * - `location` — the bridge reads `pathname` and `search` at the moment of `connect()`, for a deep link.\n *   Each later change of the pathname then goes to the actor, through `createEffect`.\n * - `params` — the path parameters of the current route segment, which Solid parsed already. The bridge\n *   uses them directly in `extractParams()`, and it parses them not again with URLPattern.\n */\nexport type SolidRouterHooks = {\n\tnavigate: Navigator;\n\tlocation: Location;\n\tparams: Params;\n};\n\n/**\n * The props of the `PlayRouterProvider` of Solid Router.\n *\n * `router` holds the three results of the Solid Router hooks that drive the work in\n * both directions. Take them from `useNavigate()`, from `useLocation()`, and from\n * `useParams()` in the parent component. Call each hook inside a router context.\n */\nexport interface PlayRouterProviderProps<\n\tTActor extends PlayActor = PlayActor,\n> extends PlayRouterProviderBaseProps<SolidRouterHooks, TActor> {}\n\n/**\n * The adapter binds the constructor of `SolidRouterBridge`, which takes the hook\n * results, to the `(router, actor, routeMap)` shape of\n * `createPlayRouterProvider`.\n */\nclass SolidHooksRouterBridge extends SolidRouterBridge {\n\tconstructor(router: SolidRouterHooks, actor: PlayActor, routeMap: RouteMap) {\n\t\tsuper(router.navigate, router.location, router.params, actor, routeMap);\n\t}\n}\n\n/**\n * Connects a `PlayerActor` to Solid Router. It keeps the actor state and the browser\n * URL in step, in both directions.\n *\n * The component creates the bridge synchronously, during its own evaluation, because\n * this is the execution model of Solid. It disconnects the bridge in `onCleanup`,\n * when Solid disposes of the component. React is different: the stability of a prop\n * is no concern here, because the `props` accessor of Solid is reactive already, and\n * the component creates the bridge one time for each of its instances.\n *\n * Take the `router` prop from the Solid Router hooks in the parent component:\n *\n * ```tsx\n * function AppShell() {\n *   const navigate = useNavigate();\n *   const location = useLocation();\n *   const params   = useParams();\n *\n *   return (\n *     <PlayRouterProvider\n *       actor={actor}\n *       routeMap={routeMap}\n *       router={{ navigate, location, params }}\n *       renderer={(a) => <PlayRenderer actor={a} registry={registry} />}\n *     />\n *   );\n * }\n * ```\n */\nexport const PlayRouterProvider = createPlayRouterProvider(SolidHooksRouterBridge);\n"],"mappings":";;;;;;;;AA0DA,IAAMe,yBAAN,cAAqCV,kBAAkB;CACtDW,YAAYC,QAA0BC,OAAkBC,UAAoB;EAC3E,MAAMF,OAAOP,UAAUO,OAAON,UAAUM,OAAOL,QAAQM,OAAOC,QAAQ;CACvE;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,IAAaC,qBAAqBd,yBAAyBS,sBAAsB"}