@xmachines/docs 1.0.0-beta.53 → 1.0.0-beta.55

package/api/@xmachines/play-tanstack-router/classes/TanStackRouterBridgeBase.md

@@ -0,0 +1,131 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-router](../README.md) / TanStackRouterBridgeBase
+
+# Class: TanStackRouterBridgeBase
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L102)
+
+Shared TanStack Router adapter implementing RouterBridge protocol via RouterBridgeBase
+
+## Remarks
+
+Extends RouterBridgeBase to handle all common lifecycle and sync logic; adds
+the TanStack-specific navigation and subscription methods shared by the React
+and Solid adapters.
+
+Subscribes to router.history (not router.subscribe("onBeforeLoad")) so that
+back/forward browser navigation (popstate events) are also captured. The
+router.subscribe("onBeforeLoad") approach only works when TanStack's
+Transitioner component is mounted (i.e. inside a full <RouterProvider>).
+Since this bridge is used without <RouterProvider>, we must subscribe to
+the underlying history object directly — which is exactly what Transitioner
+does internally: `router.history.subscribe(router.load)`.
+
+Architectural Invariants:
+
+- INV-02 (Passive Infrastructure): Router reflects actor state, never decides
+- Actor validates all navigation via guards before URL changes
+
+The class is concrete — it can be instantiated directly. The framework
+packages re-export or subclass it purely to bind the public adapter name
+(and, for Solid, to add the `dispose()` alias).
+
+## Example
+
+```typescript
+const bridge = new TanStackRouterBridgeBase(router, actor, routeMap);
+bridge.connect();
+return () => bridge.disconnect();
+```
+
+## Extends
+
+- [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md)
+
+## Extended by
+
+- [`TanStackSolidRouterBridge`](../../play-tanstack-solid-router/classes/TanStackSolidRouterBridge.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new TanStackRouterBridgeBase(
+   router,
+   actor,
+   routeMap): TanStackRouterBridgeBase;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L112)
+
+Create a TanStack Router bridge
+
+#### Parameters
+
+| Parameter  | Type                                                                 | Description                                       |
+| ---------- | -------------------------------------------------------------------- | ------------------------------------------------- |
+| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)        | TanStack Router instance (from `createRouter`)    |
+| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | XMachines actor instance                          |
+| `routeMap` | [`TanStackRouteMapLike`](../type-aliases/TanStackRouteMapLike.md)    | Bidirectional mapping between state IDs and paths |
+
+#### Returns
+
+`TanStackRouterBridgeBase`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void;
+```
+
+Defined in: play-router/dist/router-bridge-base.d.ts:120
+
+Connect the router bridge to the Actor.
+
+Sets up the TC39 Signal watcher for actor → router direction and
+starts watching router changes (framework-specific).
+
+Ordering here is part of the bridge contract:
+
+- `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
+- the actor watcher is installed before adapter router subscriptions
+- initial sync then resolves deep-link vs restore using `actor.initialRoute`
+
+Adapters that need custom initial-sync behavior should override
+`getInitialRouterPath()` rather than reordering `connect()` steps.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`connect`](../../play-router/classes/RouterBridgeBase.md#connect)
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void;
+```
+
+Defined in: play-router/dist/router-bridge-base.d.ts:126
+
+Disconnect the router bridge from the Actor.
+
+Stops signal watching and unregisters framework-specific router listener.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/classes/RouterBridgeBase.md#disconnect)

package/api/@xmachines/play-tanstack-router/type-aliases/TanStackRouteMapLike.md

@@ -0,0 +1,57 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-router](../README.md) / TanStackRouteMapLike
+
+# Type Alias: TanStackRouteMapLike
+
+```ts
+type TanStackRouteMapLike = object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L66)
+
+Narrow route-map surface required by `TanStackRouterBridgeBase`.
+`RouteMap` from `@xmachines/play-router` satisfies it (null returns are
+adapted to undefined internally).
+
+`getPathByStateId` may receive the stateId in either `"#stateId"` or bare
+`"stateId"` form — the bridge tries both forms automatically, so custom
+implementations keyed on a single form still resolve.
+
+## Methods
+
+### getPathByStateId()
+
+```ts
+getPathByStateId(id): string | null | undefined;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L68)
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `id`      | `string` |
+
+#### Returns
+
+`string` \| `null` \| `undefined`
+
+---
+
+### getStateIdByPath()
+
+```ts
+getStateIdByPath(path): string | null | undefined;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L67)
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+
+#### Returns
+
+`string` \| `null` \| `undefined`

package/api/@xmachines/play-tanstack-router/type-aliases/TanStackRouterLike.md

@@ -0,0 +1,100 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-router](../README.md) / TanStackRouterLike
+
+# Type Alias: TanStackRouterLike
+
+```ts
+type TanStackRouterLike = object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L36)
+
+Structural (type-only) interface for the TanStack Router surface used by
+`TanStackRouterBridgeBase`. Both `@tanstack/react-router` and
+`@tanstack/solid-router` instances satisfy it.
+
+## Properties
+
+### history
+
+```ts
+history: object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L44)
+
+#### location
+
+```ts
+location: object;
+```
+
+Current location — populated from `window.location` when `createRouter()` runs,
+before `router.load()`. Always available in the browser.
+`router.state.location` is only populated after `router.load()` and may be stale.
+
+##### location.pathname
+
+```ts
+pathname: string;
+```
+
+##### location.search?
+
+```ts
+optional search?: string;
+```
+
+#### subscribe()
+
+```ts
+subscribe(handler): () => void;
+```
+
+##### Parameters
+
+| Parameter | Type                |
+| --------- | ------------------- |
+| `handler` | (`event`) => `void` |
+
+##### Returns
+
+() => `void`
+
+## Methods
+
+### load()?
+
+```ts
+optional load(): void | Promise<void>;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L43)
+
+Re-runs TanStack route matching and loaders for the current location.
+Optional: the bridge calls it (fire-and-forget) after every navigation so
+matching/loaders stay in sync even without a mounted `<RouterProvider>`.
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+---
+
+### navigate()
+
+```ts
+navigate(args): void;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L37)
+
+#### Parameters
+
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `args`    | \{ `to`: `string`; \} |
+| `args.to` | `string`              |
+
+#### Returns
+
+`void`

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

@@ -302,6 +302,7 @@ MIT — see [LICENSE](LICENSE).
 
 - [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [PlayRouterProviderBaseProps](interfaces/PlayRouterProviderBaseProps.md)
 - [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
@@ -309,11 +310,16 @@ MIT — see [LICENSE](LICENSE).
 
 ## Type Aliases
 
+- [PlayRouterBridgeConstructor](type-aliases/PlayRouterBridgeConstructor.md)
 - [~~RoutableActor~~](type-aliases/RoutableActor.md)
 - [TanStackRouterInstance](type-aliases/TanStackRouterInstance.md)
 - [TanStackRouterLike](type-aliases/TanStackRouterLike.md)
 
+## Variables
+
+- [PlayRouterProvider](variables/PlayRouterProvider.md)
+
 ## Functions
 
+- [createPlayRouterProvider](functions/createPlayRouterProvider.md)
 - [createRouteMap](functions/createRouteMap.md)
-- [PlayRouterProvider](functions/PlayRouterProvider.md)

package/api/@xmachines/play-tanstack-solid-router/classes/RouteMap.md

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/base-route-map.ts#L100)
+Defined in: [play-router/src/base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/base-route-map.ts#L101)
 
 Shared bidirectional route map base class.
 
@@ -17,10 +17,17 @@ own and inherit the full public API from here.
 - Results are cached after the first match in an LRU cache (default 500 entries,
   configurable via the `cacheSize` constructor option)
 
-**Pattern syntax** (`:param` / `:param?`):
+**Pattern syntax** (`:param` / `:param?` / `*`):
 
 - `:param` — required segment, matches exactly one non-`/` segment
 - `:param?` — optional segment, matches zero or one non-`/` segment
+- `*` — wildcard, matches any number of segments (URLPattern semantics)
+
+**StateId forms:** stateIds may be registered and looked up in either
+`"#stateId"` or `"stateId"` form — `RouteMap` canonicalizes internally.
+`getStateIdByPath` returns the stateId exactly as registered;
+`getPathByStateId` accepts both forms. Registering the same stateId in both
+forms refers to one entry (the later registration wins for reverse lookup).
 
 ## Example
 
@@ -50,7 +57,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/base-route-map.ts#L125)
+Defined in: [play-router/src/base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/base-route-map.ts#L127)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -78,10 +85,14 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [play-router/src/base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/base-route-map.ts#L218)
 
 Look up the path pattern registered for a state ID.
 
+Accepts the stateId in either `"#stateId"` or `"stateId"` form regardless of
+which form was used at registration — lookups are canonicalized internally,
+so consumers never need to try both forms.
+
 #### Parameters
 
 | Parameter | Type     | Description                                               |
@@ -98,6 +109,7 @@ The registered path pattern, or `null` if the state ID is unknown
 
 ```typescript
 map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("#profile"); // "/profile/:userId" (same entry)
 map.getPathByStateId("missing"); // null
 ```
 
@@ -109,7 +121,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/base-route-map.ts#L174)
+Defined in: [play-router/src/base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/base-route-map.ts#L178)
 
 Resolve a URL path to its mapped state ID.