@xmachines/docs 2.1.1 → 2.2.0

package/api/@xmachines/play-xstate/type-aliases/RouteStateNode.md

@@ -6,7 +6,7 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
 
 The minimal structural shape of one XState state node, as
 `formatPlayRouteTransitions` reads it during its walk over the machine config.
@@ -29,7 +29,7 @@ signature without a change.
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L36)
 
 The optional explicit state ID, for example `"home"` or `"settings"`. It is the `#id` target of a `play.route` event.
 
@@ -41,7 +41,7 @@ The optional explicit state ID, for example `"home"` or `"settings"`. It is the
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L38)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L38)
 
 The state metadata. A `meta.route` field gives the state a route.
 
@@ -63,6 +63,6 @@ The template of the URL path: the string form, for example
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-xstate/src/routing/format-play-route-transitions.ts#L47)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L47)
 
 The nested child states. The function walks them for each further route declaration.

package/api/@xmachines/shared/vite-aliases/functions/xmAliases.md

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vite-aliases.ts#L221)
+Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vite-aliases.ts#L221)
 
 Vite resolve.alias entries for all @xmachines/* workspace packages.
 

package/api/@xmachines/shared/vite-aliases/functions/xmCacheDir.md

@@ -6,7 +6,7 @@
 function xmCacheDir(importMetaUrl, name): string;
 ```
 
-Defined in: [vite-aliases.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vite-aliases.ts#L338)
+Defined in: [vite-aliases.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vite-aliases.ts#L338)
 
 Returns the shared Vite `cacheDir` for this workspace package.
 

package/api/@xmachines/shared/vite-aliases/functions/xmOptimizeDeps.md

@@ -6,7 +6,7 @@
 function xmOptimizeDeps(include?): DepOptimizationOptions;
 ```
 
-Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vite-aliases.ts#L291)
+Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vite-aliases.ts#L291)
 
 Returns the standard Vite `optimizeDeps` config for browser test projects.
 

package/api/@xmachines/shared/vite-aliases/functions/xmResolve.md

@@ -6,7 +6,7 @@
 function xmResolve(importMetaUrl, extra?): ResolveOptions & object;
 ```
 
-Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vite-aliases.ts#L258)
+Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vite-aliases.ts#L258)
 
 Full Vite `resolve` config for @xmachines/* workspace packages.
 

package/api/@xmachines/shared/vite-aliases/functions/xmSvelteRunes.md

@@ -6,7 +6,7 @@
 function xmSvelteRunes(): object;
 ```
 
-Defined in: [vite-aliases.ts:317](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vite-aliases.ts#L317)
+Defined in: [vite-aliases.ts:317](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vite-aliases.ts#L317)
 
 Svelte plugin options that enforce runes mode for workspace sources only.
 
@@ -35,4 +35,4 @@ one and change the other.
 
 | Name                      | Type                                                    | Defined in                                                                                                                  |
 | ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vite-aliases.ts#L318) |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vite-aliases.ts#L318) |

package/api/@xmachines/shared/vitest/functions/defineXmBrowserConfig.md

@@ -6,7 +6,7 @@
 function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
 ```
 
-Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vitest.ts#L167)
+Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vitest.ts#L167)
 
 Create a Vitest browser-mode config with XMachines workspace defaults.
 

package/api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
 
-Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vitest.ts#L64)
+Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vitest.ts#L64)
 
 Create a Vitest config with XMachines workspace defaults.
 

package/api/@xmachines/shared/vitest/interfaces/XmBrowserConfigOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: XmBrowserConfigOptions
 
-Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vitest.ts#L117)
+Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vitest.ts#L117)
 
 Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
 Vitest config overrides.
@@ -11,6 +11,6 @@ Vitest config overrides.
 
 | Property                                           | Type                                     | Description                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                      |
 | -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vitest.ts#L125) |
-| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vitest.ts#L132) |
-| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/shared/config/vitest.ts#L138) |
+| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vitest.ts#L125) |
+| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vitest.ts#L132) |
+| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/shared/config/vitest.ts#L138) |

package/contributing/configuration.md

@@ -116,7 +116,7 @@ All packages extend this base. Key compiler settings:
 
 **Location:** `packages/shared/config/tsconfig.test.json`
 
-Test builds add `noEmit: true`, `allowImportingTsExtensions: true`, and `vitest/globals` types. Used by `pnpm run test:build` to type-check test files without emitting output.
+Test builds add `noEmit: true`, `allowImportingTsExtensions: true`, and `vitest/globals` types. Used by `pnpm run test:build` to type-check test files without emitting output. That script passes `--force`, so the check covers every project of the solution on every run.
 
 ### Linting — `oxlint.config.ts` (root)
 

package/contributing/development.md

@@ -125,22 +125,22 @@ packages/<name>/
 
 All commands are run from the **repository root** unless otherwise noted.
 
-| Command                                    | Description                                                           |
-| ------------------------------------------ | --------------------------------------------------------------------- |
-| `pnpm run build`                           | TypeScript composite build — all packages in dependency order         |
-| `pnpm --filter @xmachines/<pkg> run build` | Build a single package (and its deps)                                 |
-| `pnpm run clean`                           | Remove coverage, Vite caches, and all `dist/` directories in packages |
-| `pnpm test`                                | Run all unit/integration tests once                                   |
-| `pnpm run test:watch`                      | Re-run tests on file changes (interactive)                            |
-| `pnpm run test:browser`                    | Run Playwright browser tests                                          |
-| `pnpm run test:coverage`                   | Run tests with V8 coverage reporting                                  |
-| `pnpm run test:browser:coverage`           | Run browser tests with coverage reporting                             |
-| `pnpm run test:build`                      | Type-check test files without running them (`tsconfig.test.json`)     |
-| `pnpm run lint`                            | Lint all packages with oxlint                                         |
-| `pnpm run lint:fix`                        | Auto-fix lint issues                                                  |
-| `pnpm run format`                          | Format all files with oxfmt                                           |
-| `pnpm run format:check`                    | Check formatting (CI mode — no writes)                                |
-| `pnpm run docs`                            | Build packages, generate TypeDoc API docs, then format                |
+| Command                                    | Description                                                               |
+| ------------------------------------------ | ------------------------------------------------------------------------- |
+| `pnpm run build`                           | Incremental build — all packages in dependency order (not a type-check)   |
+| `pnpm --filter @xmachines/<pkg> run build` | Build a single package (and its deps)                                     |
+| `pnpm run clean`                           | Remove coverage, Vite caches, and all `dist/` directories in packages     |
+| `pnpm test`                                | Run all unit/integration tests once                                       |
+| `pnpm run test:watch`                      | Re-run tests on file changes (interactive)                                |
+| `pnpm run test:browser`                    | Run Playwright browser tests                                              |
+| `pnpm run test:coverage`                   | Run tests with V8 coverage reporting                                      |
+| `pnpm run test:browser:coverage`           | Run browser tests with coverage reporting                                 |
+| `pnpm run test:build`                      | Complete type-check of every package and its tests (`tsconfig.test.json`) |
+| `pnpm run lint`                            | Lint all packages with oxlint                                             |
+| `pnpm run lint:fix`                        | Auto-fix lint issues                                                      |
+| `pnpm run format`                          | Format all files with oxfmt                                               |
+| `pnpm run format:check`                    | Check formatting (CI mode — no writes)                                    |
+| `pnpm run docs`                            | Build packages, generate TypeDoc API docs, then format                    |
 
 ---
 

package/contributing/testing.md

@@ -33,7 +33,9 @@ pnpm install --frozen-lockfile
 pnpm test
 ```
 
-Runs `vitest run` across all 30 package-level projects defined in the root `vitest.config.ts`. Uses the `forks` pool (up to 4 workers) with process-level isolation between test files.
+Runs `vitest run` across every project that the root `vitest.config.ts` collects — 36 of them today: one for each package, one for each demo that holds node tests, and `infrastructure` for the repository tests in `tests/`. Uses the `forks` pool (up to 4 workers) with process-level isolation between test files.
+
+The root config finds those projects by glob, so a new package or demo joins the run with no edit. Each test file must belong to **one** project: a package config that reaches into its own `examples/` collects the demo tests that the demo config collects already, and the run then executes them two times, under two different environments. `tests/project-collection-overlap.test.ts` asks Vitest for the whole collection and fails on any file that two projects claim.
 
 ### Watch mode (development)
 
@@ -80,7 +82,9 @@ Individual packages may enforce higher per-package thresholds in their own `vite
 pnpm run test:build
 ```
 
-Runs `tsc --build tsconfig.test.json`. This validates that all test TypeScript files across the monorepo type-check correctly without running the tests themselves. Also compiles `.typecheck.ts` files in `src/` directories.
+Runs `tsc --build tsconfig.test.json --force`. This validates that all test TypeScript files across the monorepo type-check correctly without running the tests themselves. Also compiles `.typecheck.ts` files in `src/` directories.
+
+This is the command that answers "does this tree type-check?". Use it rather than `pnpm run build` for that question. `tsc --build` skips a project whose dependencies have unchanged `.d.ts` files, so an error inside the source of a library that changes no exported declaration can leave every consumer of that library up to date and never be reported — and consumers here compile library **source**, through the `source` export condition. `--force` costs about a second and takes that decision away from tsc; `tests/typecheck-staleness.test.ts` holds it, and the two other properties the complete check rests on, in place: no project of the gate is `composite`, and the CI job starts with no build state on disk. The job gets that second property by DELETING every `*.tsbuildinfo` before it runs the gate. It does not inherit it: most of the caching of the pipeline arrives through the included node component, and no test in this repository can read that component's cache paths, so a claim about them would be prose that nothing verifies.
 
 ### Running tests for a single package
 
@@ -137,6 +141,27 @@ packages/<name>/
 - **`packages/play-react/test/test-utils.ts`** — React-specific test utilities for the `play-react` package.
 - **`packages/play-router/examples/shared/`** and **`packages/play-actor/examples/shared/`** — Shared test fixtures for router and actor integration tests.
 
+### Portable contract suites
+
+Two suites live in `@xmachines/play-router-shared` and every router adapter runs them,
+so a behaviour of `RouterBridgeBase` is asserted one time and covered eight times:
+
+| Suite                      | Import                                                         | What it holds                                           |
+| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------- |
+| `runBridgeContractTests`   | `@xmachines/play-router-shared/test/router-bridge-contract.js` | The bidirectional sync contract, with optional sections |
+| `runBasePathContractTests` | `@xmachines/play-router-shared/test/base-path-contract.js`     | The `basePath` mount contract, and several machines     |
+
+An adapter supplies a harness rather than tests. For the `basePath` contract the
+harness builds ONE router whose write reaches every bridge on it, and the suite mounts
+one machine or two on that router. A browser behaves that way, and two bridges that
+never see each other's writes never contend for the address bar — which is the case the
+suite exists to cover.
+
+Add a new adapter to both suites. A copy of the assertions in the adapter is how the
+coverage drifted apart before: five adapters asserted the four behaviours of a mount,
+two asserted two of them, and the vanilla DOM adapter asserted only that the option
+reached the bridge.
+
 ## Writing New Tests
 
 ### Adding a new package test config
@@ -157,9 +182,11 @@ packages/<name>/
     });
     ```
 
-4. Register the new config in the root `vitest.config.ts` `projects` array.
+4. Keep the `include` inside `test/`, and exclude `examples/`. The demo config of the package owns every test under `examples/`, and the root run joins both configs.
 5. Add the package's `tsconfig.test.json` to `tsconfig.test.json` references in the root.
 
+The root `vitest.config.ts` needs no edit: it collects `packages/*/vitest.config.ts` and `packages/*/examples/*/vitest.config.ts` by glob.
+
 ### Basic test structure
 
 ```typescript
@@ -349,7 +376,7 @@ const actorNotAny: AssertFalse<IsAny<typeof actor>> = false;
 void actorNotAny;
 ```
 
-These files are validated by `pnpm run test:build` (`tsc --build tsconfig.test.json`) — never executed by Vitest.
+These files are validated by `pnpm run test:build` (`tsc --build tsconfig.test.json --force`) — never executed by Vitest.
 
 ### Error testing
 

package/examples/README.md

@@ -17,7 +17,7 @@ Start with the fundamental machine + actor pattern:
 Learn how state machines control navigation:
 
 - **[Routing Patterns](routing-patterns.md)** — `meta.route`, `play.route` events, `always` auth guards, and parameter routes
-- **[Multi-Router Integration](multi-router-integration.md)** — All 8 router adapters: provider pattern vs `connectRouter` pattern
+- **[Multi-Router Integration](multi-router-integration.md)** — All 8 router adapters: provider pattern vs `connectRouter` pattern, and `basePath` for sharing a router with the host
 
 ### Level 3: Full Applications
 

package/examples/multi-router-integration.md

@@ -11,7 +11,9 @@ There are two integration patterns:
 | Pattern                     | Used by                                                                        | Key API                                                       |
 | --------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
 | **Provider pattern**        | React (TanStack, React Router), SolidJS (TanStack, SolidJS Router), Vue Router | `<PlayRouterProvider actor router routeMap renderer={...} />` |
-| **`connectRouter` pattern** | Vanilla DOM, SvelteKit, Svelte SPA Router                                      | `connectRouter({ actor, routeMap })`                          |
+| **`connectRouter` pattern** | Vanilla DOM, SvelteKit, Svelte SPA Router                                      | `connectRouter({ actor, routeMap, ...adapter })`              |
+
+Either pattern can share its router with routes the host owns — see [Sharing a Router with the Host](#sharing-a-router-with-the-host-basepath).
 
 ## Pattern 1: Provider Pattern
 
@@ -348,6 +350,129 @@ export const routeMap = createRouteMap(authMachine);
 export const disconnectRouter = connectRouter({ actor, routeMap });
 ```
 
+## Sharing a Router with the Host (`basePath`)
+
+Both patterns give the machine the complete URL space of its router by default. Pass a `basePath` and the machine owns a prefix only — the host keeps every other route in the same router.
+
+The shape that motivates this is a URL such as `/:machineId/play/dashboard`. The host resolves `:machineId` — a TanStack loader, a `useParams()` call, a SvelteKit `load` function — and owns that prefix. The `meta.route` tree of the machine owns everything below it.
+
+### Under the Provider Pattern
+
+`basePath` and `basePathParams` are **reactive props**. They need no stable reference, unlike `actor`, `router`, and `routeMap`, and a change moves the live bridge instead of rebuilding it:
+
+```tsx
+function PlayRoute() {
+	const { machineId } = useLoaderData({ from: "/$machineId/play/$" });
+
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap} // unchanged — the route map stays machine-relative
+			basePath="/:machineId/play"
+			basePathParams={{ machineId }} // the loader resolved this already
+			renderer={(currentActor) => <Shell actor={currentActor} registry={registry} />}
+		/>
+	);
+}
+
+// The "/dashboard" of the machine is now the URL "/abc123/play/dashboard".
+// The "/"          of the machine is now the URL "/abc123/play".
+```
+
+### Under `connectRouter`
+
+`basePath` and `basePathParams` join the options that the adapter needs already. The
+vanilla DOM adapter needs `router`, as it does in the example above:
+
+```typescript
+const disconnect = connectRouter({
+	actor,
+	router, // required: @xmachines/play-dom-router reads its history
+	routeMap, // unchanged — the route map stays machine-relative
+	basePath: "/:machineId/play",
+	basePathParams: { machineId }, // the loader resolved this already
+});
+```
+
+The Svelte adapters take the same two prefix options. They need no `router`:
+`@xmachines/play-svelte-spa-router` reads an optional `window`, and
+`@xmachines/play-sveltekit-router` reads an optional `location`.
+
+### What the Prefix Changes
+
+A location **outside** the prefix belongs to the host. The bridge sends no `play.route` event there, it runs no corrective navigation there, and it writes no route of its actor there. That silence is what lets the two halves share one router: without it, the unknown-path correction would drag the user off every page the host owns, and so would any route change of the actor that no URL event caused — an `after` timer, an async guard that settles, a restore of a snapshot. The bridge remembers such a move and writes it when the location comes back under the prefix, so the machine keeps its place.
+
+| Location of the router | `basePath = "/abc123/play"`                           |
+| ---------------------- | ----------------------------------------------------- |
+| `/abc123/play`         | the `/` of the machine → `play.route`                 |
+| `/abc123/play/about`   | the `/about` of the machine → `play.route`            |
+| `/abc123/play/nope`    | unknown inside the mount → the URL follows the actor  |
+| `/account/billing`     | a route of the host → the bridge does nothing         |
+| `/abc123/playground`   | another segment → the host's, the bridge does nothing |
+
+The prefix resolves in advance, because the bridge writes a real browser URL. It rejects every shape that resolves to one concrete path never — a `*` wildcard, a `:param?`, a `$param` (the TanStack spelling; write `:param`), a query string, and a hash. A base path is a _pathname_, so a URL scheme is rejected too: write `/admin`, not `https://app.example.com/admin`. Every segment that a browser rewrites is rejected on the same rule, the resolved value of a `:param` included — a dot segment, a backslash, whitespace, and a character that a URL percent-encodes, such as the `é` of `/café` — because each one makes the prefix that comes back differ from the prefix that went out, and the machine would go silent with no error. An unresolved `:param` throws `MissingBasePathParamError` at construction, rather than falling back to "no prefix yet": a bridge with no prefix would claim the complete router and start correcting the URLs of the host.
+
+**The machine stays authoritative over its own params (INV-01).** `event.params` carries what the pattern of the machine declares and nothing else. The params of the prefix belong to the host, so they travel in no `play.route` event, and a host param that shares a name with one of the machine can shadow it never. Read the resolved mount from the bridge instead, where it cannot go stale:
+
+```typescript
+bridge.basePath; // "/abc123/play"
+bridge.basePathParams; // { machineId: "abc123" }
+```
+
+A machine that needs the identity of its host takes it through the actor `input`, where that identity decides **which** machine runs.
+
+### Several Machines Alive at Once
+
+Several machines can be alive together, each mounted at its own prefix, all sharing one router. Every bridge hears every location change, and a location under another machine's prefix is foreign in exactly the way a route of the host is — so a `play.route` reaches the machine that owns the URL and no other, and a correction of an unknown path happens only inside the prefix that owns it.
+
+**Each bridge can stay connected, as long as each one has its own prefix.** A bridge outside its mount keeps the silence in _both_ directions: it sends no `play.route`, it corrects no URL, and it writes no route of its actor. The machine that the location belongs to is therefore the only one that writes, and an actor that nobody is looking at cannot take the URL from the one on screen. A route that the hidden machine moved to is not lost either: the bridge remembers it, and it writes it when the host navigates back under its prefix.
+
+**Two bridges contend when neither prefix separates their halves of the URL.** That is the case for two bridges with no prefix, for two with the same prefix, and also for two whose prefixes NEST: a mount at `/a` and a mount at `/a/b` both claim `/a/b/x`, because `/a` is a prefix of it. Give sibling prefixes — `/a/one` and `/a/two` — and no location belongs to two machines. Mount the provider for the machine the host is showing, and let the others keep their state with no bridge attached.
+
+### Loading and Unloading Routes
+
+`setBasePath()` moves **where** an actor is mounted, and never **which** actor is mounted. The actor, the route map, and its LRU cache all stay:
+
+```typescript
+// The host moved this actor from one region of its URL space to another.
+bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
+```
+
+The call also brings the location in step. Nothing else moves the address bar, so a move to a prefix that the URL is not under writes the new mount and keeps the route of the actor: `/eu/abc123/play/about` becomes `/us/abc123/play/about`. A location that already lies under the new prefix drives the actor instead, exactly as it does on `connect()`.
+
+An actor never changes identity, so a segment of the prefix that _identifies_ the actor never moves through this method. A new identity is a new **actor**, and a new actor takes a new bridge, because `connect()` permits one bridge for each actor. The segments that move here are the ones that _locate_: a region, a locale, a tenant, a workspace slug.
+
+For a host router that declares real route objects, ask for the list — and drop it again when the machine unloads:
+
+```typescript
+import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router";
+
+const tree = extractMachineRoutes(authMachine);
+
+// Concrete, for a route that the host adds after a loader resolved the mount
+getRouteMappings(tree, { basePath: "/:machineId/play", basePathParams: { machineId } });
+// [{ stateId: "home", path: "/abc123/play" },
+//  { stateId: "profile", path: "/abc123/play/profile/:userId" }, ...]
+
+// The pattern, for a static route declaration of the host
+getRouteMappings(tree, { basePath: "/:machineId/play" });
+// [{ stateId: "home", path: "/:machineId/play" }, ...]
+```
+
+> **Polyfill note.** Under a mount, `@xmachines/play-vue-router` and `@xmachines/play-solid-router` resolve each param from the stripped path with `URLPattern`, and not from the pre-parsed params of their framework: under a prefix the framework matched a route of the **host**, so those params describe the route of the machine never — and a collision of names carries the value of the host. Both adapters therefore need a `URLPattern` polyfill on an older runtime when they are mounted. With no prefix, both keep the parse of their framework whenever it reports at least one
+> param the pattern declares, and every required one. A pattern whose params are ALL
+> optional and a framework that reports none — `/settings/:section?` under a catch-all of
+> the host — is settled by the PATH: `/settings` is the bare form of that pattern, so
+> every optional segment is absent and the params are `{}`. A path that DOES carry a
+> value, such as `/settings/security`, still reaches the extraction, because only the
+> extraction reads that value.
+>
+> These branches decide the CALLS of a navigation, and not whether the application needs
+> the polyfill. `RouteMap` compiles each parameterized route in its constructor and
+> throws there without `URLPattern`, so one `:param` in the route map makes the polyfill
+> a startup requirement on an older runtime.
+
 ## Adapter Summary
 
 | Package                                 | Framework             | Pattern         | Key Import                                                                |

package/examples/routing-patterns.md

@@ -289,7 +289,7 @@ function App() {
 
 ## Next Steps
 
-- **[Multi-Router Integration](./multi-router-integration.md)** — All 8 router adapters and the two integration patterns
+- **[Multi-Router Integration](./multi-router-integration.md)** — All 8 router adapters, the two integration patterns, and `basePath`
 - **[Examples Index](./README.md)** — Complete catalog of runnable demos
 
 ## Learn More

package/guides/inspector.md

@@ -170,7 +170,7 @@ actor.start();
 <button onClick={() => inspector.show()}>Show Inspector</button>;
 ```
 
-The controller answers the late-opening problem from the previous section: it buffers serialized events from actor creation, pins the current root's registration so it can never roll out of the bounded buffer, and flushes the buffer when the inspector window completes its handshake. That is a demo trade-off rather than a general recommendation — every transition pays serialization whether or not anyone ever opens the inspector — but it is what makes the button work at any point in a session. The shared package's own README, at `packages/play-actor/examples/shared/README.md` in this repository, documents the design in full.
+The controller answers the late-opening problem from the previous section: it buffers serialized events from actor creation, pins the registration of every live root so it can never roll out of the bounded buffer, and flushes those buffers when the inspector window completes its handshake. Several machines can be alive together — one for each document a host has open — and the handshake replays each of them. That is a demo trade-off rather than a general recommendation — every transition pays serialization whether or not anyone ever opens the inspector — but it is what makes the button work at any point in a session. The shared package's own README, at `packages/play-actor/examples/shared/README.md` in this repository, documents the design in full.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",

package/api/@xmachines/play-react-router/interfaces/PlayRouterProviderBaseProps.md

@@ -1,32 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-react-router](../README.md) / PlayRouterProviderBaseProps
-
-# Interface: PlayRouterProviderBaseProps\<TRouter, TActor\>
-
-Defined in: [play-react-router/src/create-play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L34)
-
-The props that every React `PlayRouterProvider` of the factory shares.
-
-An adapter package re-exports a concrete alias, with `TRouter` bound to the type of
-its router instance. For example, `PlayRouterProviderProps<TActor>` in
-`@xmachines/play-react-router` binds `TRouter` to the return type of
-`createBrowserRouter`.
-
-## Extended by
-
-- [`PlayRouterProviderProps`](PlayRouterProviderProps.md)
-
-## Type Parameters
-
-| Type Parameter                                 | Default type                |
-| ---------------------------------------------- | --------------------------- |
-| `TRouter`                                      | -                           |
-| `TActor` _extends_ [`PlayActor`](PlayActor.md) | [`PlayActor`](PlayActor.md) |
-
-## Properties
-
-| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Defined in                                                                                                                                                                              |
-| ----------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to keep in step with the router. It must be a stable reference: give the same actor instance on every render. An actor in the JSX, or a new actor on each render, makes the bridge disconnect and connect again each time.                                                                                                                                                                                                                                                         | [play-react-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L40) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                     | [play-react-router/src/create-play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L57) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | The route map of both directions, for the lookup between a state ID and a URL path. **It must be a stable reference.** The provider builds the bridge again on each change of the identity of `routeMap`. A value in the JSX, for example `createRouteMapFromTree(routeTree)`, makes a new object on every render, and the bridge therefore connects again on every render. Hold the value with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [play-react-router/src/create-play-router-provider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L55) |
-| <a id="property-router"></a> `router`     | `TRouter`                            | The router instance that the bridge keeps in step with the actor. It must be a stable reference.                                                                                                                                                                                                                                                                                                                                                                                             | [play-react-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L42) |

package/api/@xmachines/play-solid-router/interfaces/PlayRouterProviderBaseProps.md

@@ -1,30 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-solid-router](../README.md) / PlayRouterProviderBaseProps
-
-# Interface: PlayRouterProviderBaseProps\<TRouter, TActor\>
-
-Defined in: [packages/play-solid-router/src/create-play-router-provider.tsx:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/create-play-router-provider.tsx#L36)
-
-The props that every Solid `PlayRouterProvider` of the factory shares.
-
-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`.
-
-## Extended by
-
-- [`PlayRouterProviderProps`](PlayRouterProviderProps.md)
-
-## Type Parameters
-
-| Type Parameter                                 | Default type                |
-| ---------------------------------------------- | --------------------------- |
-| `TRouter`                                      | -                           |
-| `TActor` _extends_ [`PlayActor`](PlayActor.md) | [`PlayActor`](PlayActor.md) |
-
-## Properties
-
-| Property                                  | Type                                 | Description                                                                         | Defined in                                                                                                                                                                                       |
-| ----------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to keep in step with the router.                                          | [packages/play-solid-router/src/create-play-router-provider.tsx:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/create-play-router-provider.tsx#L38) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `any`         | The renderer callback receives the same concrete actor type as the prop.            | [packages/play-solid-router/src/create-play-router-provider.tsx:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/create-play-router-provider.tsx#L44) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | The route map of both directions, for the lookup between a state ID and a URL path. | [packages/play-solid-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/create-play-router-provider.tsx#L42) |
-| <a id="property-router"></a> `router`     | `TRouter`                            | The router that the bridge keeps in step with the actor.                            | [packages/play-solid-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/create-play-router-provider.tsx#L40) |

package/api/@xmachines/play-tanstack-react-router/interfaces/PlayRouterProviderBaseProps.md

@@ -1,32 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / PlayRouterProviderBaseProps
-
-# Interface: PlayRouterProviderBaseProps\<TRouter, TActor\>
-
-Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L46)
-
-The props that every React `PlayRouterProvider` of the factory shares.
-
-An adapter package re-exports a concrete alias, with `TRouter` bound to the type of
-its router instance. For example, `PlayRouterProviderProps<TActor>` in
-`@xmachines/play-tanstack-react-router` binds `TRouter` to the type of the TanStack
-Router instance.
-
-## Extended by
-
-- [`PlayRouterProviderProps`](PlayRouterProviderProps.md)
-
-## Type Parameters
-
-| Type Parameter                                 | Default type                |
-| ---------------------------------------------- | --------------------------- |
-| `TRouter`                                      | -                           |
-| `TActor` _extends_ [`PlayActor`](PlayActor.md) | [`PlayActor`](PlayActor.md) |
-
-## Properties
-
-| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Defined in                                                                                                                                                                                                |
-| ----------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to keep in step with the router. It must be a stable reference: give the same actor instance on every render. An actor in the JSX, or a new actor on each render, makes the bridge disconnect and connect again each time.                                                                                                                                                                                                                                                         | [play-tanstack-react-router/src/create-play-router-provider.tsx:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L52) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                     | [play-tanstack-react-router/src/create-play-router-provider.tsx:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L69) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | The route map of both directions, for the lookup between a state ID and a URL path. **It must be a stable reference.** The provider builds the bridge again on each change of the identity of `routeMap`. A value in the JSX, for example `createRouteMapFromTree(routeTree)`, makes a new object on every render, and the bridge therefore connects again on every render. Hold the value with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [play-tanstack-react-router/src/create-play-router-provider.tsx:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L67) |
-| <a id="property-router"></a> `router`     | `TRouter`                            | The router instance that the bridge keeps in step with the actor. It must be a stable reference.                                                                                                                                                                                                                                                                                                                                                                                             | [play-tanstack-react-router/src/create-play-router-provider.tsx:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L54) |

package/api/@xmachines/play-tanstack-solid-router/interfaces/PlayRouterProviderBaseProps.md

@@ -1,31 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-tanstack-solid-router](../README.md) / PlayRouterProviderBaseProps
-
-# Interface: PlayRouterProviderBaseProps\<TRouter, TActor\>
-
-Defined in: [play-tanstack-solid-router/src/create-play-router-provider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-solid-router/src/create-play-router-provider.tsx#L45)
-
-The props that every Solid `PlayRouterProvider` of the factory shares.
-
-An adapter package re-exports a concrete alias, with `TRouter` bound to the type of
-its router. For example, `TanStackRouterInstance` in
-`@xmachines/play-tanstack-solid-router`.
-
-## Extended by
-
-- [`PlayRouterProviderProps`](PlayRouterProviderProps.md)
-
-## Type Parameters
-
-| Type Parameter                                 | Default type                |
-| ---------------------------------------------- | --------------------------- |
-| `TRouter`                                      | -                           |
-| `TActor` _extends_ [`PlayActor`](PlayActor.md) | [`PlayActor`](PlayActor.md) |
-
-## Properties
-
-| Property                                  | Type                                 | Description                                                                         | Defined in                                                                                                                                                                                                |
-| ----------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to keep in step with the router.                                          | [play-tanstack-solid-router/src/create-play-router-provider.tsx:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-solid-router/src/create-play-router-provider.tsx#L47) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `any`         | The renderer callback receives the same concrete actor type as the prop.            | [play-tanstack-solid-router/src/create-play-router-provider.tsx:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-solid-router/src/create-play-router-provider.tsx#L53) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | The route map of both directions, for the lookup between a state ID and a URL path. | [play-tanstack-solid-router/src/create-play-router-provider.tsx:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-solid-router/src/create-play-router-provider.tsx#L51) |
-| <a id="property-router"></a> `router`     | `TRouter`                            | The router that the bridge keeps in step with the actor.                            | [play-tanstack-solid-router/src/create-play-router-provider.tsx:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-solid-router/src/create-play-router-provider.tsx#L49) |