@xmachines/docs 1.0.0-beta.9 → 1.0.0

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

@@ -0,0 +1,38 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmAliases
+
+# Function: xmAliases()
+
+```ts
+function xmAliases(importMetaUrl): Record<string, string>;
+```
+
+Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L221)
+
+Vite resolve.alias entries for all @xmachines/* workspace packages.
+
+Maps every package to its TypeScript source entry so that `pnpm run dev`
+works without a prior `pnpm run build`. Required because `pnpm run clean`
+removes all dist/ directories — including transitive dependencies —
+leaving Vite unable to resolve package.json `exports` that point to dist/.
+
+The map is derived from the workspace layout at config-load time (see
+`buildAliases`), so adding a new package needs no edit here. A few
+special-case subpath aliases are maintained explicitly on top.
+
+Usage in a demo vite.config.ts:
+
+import { xmAliases } from "@xmachines/shared/vite-aliases";
+
+export default defineConfig({
+resolve: { alias: xmAliases(import.meta.url) },
+});
+
+## Parameters
+
+| Parameter       | Type     | Description                                                                                                                    |
+| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `importMetaUrl` | `string` | Pass `import.meta.url` from the calling config file. Used to locate the workspace root (the directory containing `packages/`). |
+
+## Returns
+
+`Record`\<`string`, `string`\>

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

@@ -0,0 +1,27 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmCacheDir
+
+# Function: xmCacheDir()
+
+```ts
+function xmCacheDir(importMetaUrl, name): string;
+```
+
+Defined in: [vite-aliases.ts:330](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L330)
+
+Returns the shared Vite `cacheDir` for this workspace package.
+
+All browser test projects use a single cache under `<workspace-root>/node_modules/.vite/`
+keyed by the project name. This means the dep optimizer runs once per project
+across the whole workspace rather than once per local `node_modules/.vite/` directory,
+and a lockfile change only triggers one rebuild per project — not one per local cache.
+
+## Parameters
+
+| Parameter       | Type     | Description                                          |
+| --------------- | -------- | ---------------------------------------------------- |
+| `importMetaUrl` | `string` | Pass `import.meta.url` from the calling config file. |
+| `name`          | `string` | Unique project name (matches `test.name`).           |
+
+## Returns
+
+`string`

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

@@ -0,0 +1,30 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmOptimizeDeps
+
+# Function: xmOptimizeDeps()
+
+```ts
+function xmOptimizeDeps(extra?): DepOptimizationOptions;
+```
+
+Defined in: [vite-aliases.ts:286](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L286)
+
+Returns the standard Vite `optimizeDeps` config for browser test projects.
+
+Tells Vite's dep optimizer which packages to pre-bundle at startup rather than
+discovering them lazily at runtime. Without this, adding or changing dependencies
+(e.g. a lockfile change) causes Vite to re-optimize mid-run, producing the
+"Re-optimizing dependencies because lockfile has changed" warnings that slow down
+and occasionally destabilise browser test runs.
+
+Pass `extra` to include framework-specific packages (e.g. `["@xmachines/json-render-vue/schema"]`).
+The base set (`@xmachines/json-render-core`) is always included.
+
+## Parameters
+
+| Parameter | Type       | Default value | Description                                                       |
+| --------- | ---------- | ------------- | ----------------------------------------------------------------- |
+| `extra`   | `string`[] | `[]`          | Additional package specifiers to pre-bundle (framework-specific). |
+
+## Returns
+
+`DepOptimizationOptions`

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

@@ -0,0 +1,42 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmResolve
+
+# Function: xmResolve()
+
+```ts
+function xmResolve(importMetaUrl, extra?): ResolveOptions & object;
+```
+
+Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L258)
+
+Full Vite `resolve` config for @xmachines/* workspace packages.
+
+Combines `xmAliases` with `conditions: ["source"]` so Vite resolves every
+`@xmachines/*` package to its TypeScript source via the `"source"` export
+condition — without requiring a prior `pnpm run build`.
+
+`preserveSymlinks` defaults to `false`: under pnpm every dependency is a
+symlink into the content-addressed store, and preserving symlink paths
+prevents Vite from deduplicating packages and from resolving nested
+dependencies of pre-bundled modules (vitest's own browser-mode chunks fail
+to load). Callers can still override it explicitly.
+
+Use this instead of manually setting `resolve.alias: xmAliases(...)`:
+
+```ts
+import { xmResolve } from "@xmachines/shared/vite-aliases";
+
+export default defineConfig({
+	resolve: xmResolve(import.meta.url),
+});
+```
+
+## Parameters
+
+| Parameter       | Type                                     | Description                                          |
+| --------------- | ---------------------------------------- | ---------------------------------------------------- |
+| `importMetaUrl` | `string`                                 | Pass `import.meta.url` from the calling config file. |
+| `extra?`        | `Partial`\<`ResolveOptions` & `object`\> | -                                                    |
+
+## Returns
+
+`ResolveOptions` & `object`

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

@@ -0,0 +1,33 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmSvelteRunes
+
+# Function: xmSvelteRunes()
+
+```ts
+function xmSvelteRunes(): object;
+```
+
+Defined in: [vite-aliases.ts:309](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L309)
+
+Svelte plugin options that enforce runes mode for workspace sources only.
+
+Forcing `compilerOptions.runes` globally also applies to third-party
+`.svelte` files pulled in through Vite dependency optimization — e.g.
+`@testing-library/svelte-core`'s `wrapper-scaffold-legacy.svelte`, which is
+intentionally written in legacy syntax and fails to compile in runes mode.
+Scoping the flag with `dynamicCompileOptions` keeps the strictness for our
+own components while letting node_modules compile in their intended mode.
+
+Usage:
+
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import { xmSvelteRunes } from "@xmachines/shared/vite-aliases";
+
+export default defineConfig({ plugins: [svelte(xmSvelteRunes())] });
+
+## Returns
+
+`object`
+
+| Name                      | Type                                                    | Defined in                                                                                                                  |
+| ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:310](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vite-aliases.ts#L310) |

package/api/@xmachines/shared/vitest/README.md

@@ -0,0 +1,12 @@
+[API](../../../README.md) / [@xmachines/shared](../README.md) / vitest
+
+# vitest
+
+## Interfaces
+
+- [XmBrowserConfigOptions](interfaces/XmBrowserConfigOptions.md)
+
+## Functions
+
+- [defineXmBrowserConfig](functions/defineXmBrowserConfig.md)
+- [defineXmVitestConfig](functions/defineXmVitestConfig.md)

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

@@ -0,0 +1,42 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vitest](../README.md) / defineXmBrowserConfig
+
+# Function: defineXmBrowserConfig()
+
+```ts
+function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
+```
+
+Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vitest.ts#L167)
+
+Create a Vitest browser-mode config with XMachines workspace defaults.
+
+Composes [defineXmVitestConfig](defineXmVitestConfig.md) (so alias resolution, setup-file
+normalization/injection, and the required deep excludes all apply) and
+bakes in the browser boilerplate shared by every browser test project:
+
+- `cacheDir` from `xmCacheDir(importMetaUrl, test.name)` and
+  `resolve` from `xmResolve(importMetaUrl)` (standalone configs only).
+- `optimizeDeps` from `xmOptimizeDeps(options.optimizeDeps)`.
+- `test.include: ["test/browser/**/*.browser.test.ts"]` and
+  `test.exclude: ["**/node_modules/**", "**/dist/**"]` defaults.
+- `test.fileParallelism: false`.
+- Headless Playwright Chromium via `test.browser`.
+
+Everything in `overrides` wins over these defaults: `test.include`,
+`test.exclude`, and `test.setupFiles` replace the defaults when provided,
+and `test.browser` entries (e.g. an `api` port) are merged on top of the
+Playwright defaults. Plugins stay per-package arguments (`plugins: [vue()]`).
+
+## Parameters
+
+| Parameter       | Type                                                                | Description                                                                                                                                          |
+| --------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `importMetaUrl` | `string`                                                            | Pass `import.meta.url` from the calling config file.                                                                                                 |
+| `overrides`     | `UserConfig`                                                        | Package/project-specific Vitest config overrides. `overrides.test.name` is required — it names the project and keys the shared Vite cache directory. |
+| `options`       | [`XmBrowserConfigOptions`](../interfaces/XmBrowserConfigOptions.md) | Browser-specific knobs, see [XmBrowserConfigOptions](../interfaces/XmBrowserConfigOptions.md).                                                       |
+
+## Returns
+
+`UserConfig`
+
+Merged Vitest configuration object.

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

@@ -0,0 +1,34 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vitest](../README.md) / defineXmVitestConfig
+
+# Function: defineXmVitestConfig()
+
+```ts
+function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
+```
+
+Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vitest.ts#L64)
+
+Create a Vitest config with XMachines workspace defaults.
+
+What this applies automatically:
+
+- `resolve.alias` from `xmAliases(importMetaUrl)` so `@xmachines/*` imports
+  resolve to source in local/dev test runs.
+- `config/vitest.setup.ts` when missing.
+- `config/vitest.node.setup.ts` for non-browser projects when missing.
+
+Setup injection is additive and preserves caller-provided ordering after
+required shared setup files.
+
+## Parameters
+
+| Parameter       | Type         | Description                                          |
+| --------------- | ------------ | ---------------------------------------------------- |
+| `importMetaUrl` | `string`     | Pass `import.meta.url` from the calling config file. |
+| `overrides`     | `UserConfig` | Package/project-specific Vitest config overrides.    |
+
+## Returns
+
+`UserConfig`
+
+Merged Vitest configuration object.

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

@@ -0,0 +1,16 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vitest](../README.md) / XmBrowserConfigOptions
+
+# Interface: XmBrowserConfigOptions
+
+Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/shared/config/vitest.ts#L117)
+
+Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
+Vitest config overrides.
+
+## Properties
+
+| 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/v1.0.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/v1.0.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/v1.0.0/packages/shared/config/vitest.ts#L138) |

package/api/README.md

@@ -4,22 +4,21 @@
 
 - [@xmachines/play](@xmachines/play/README.md)
 - [@xmachines/play-actor](@xmachines/play-actor/README.md)
-- [@xmachines/play-catalog](@xmachines/play-catalog/README.md)
+- [@xmachines/play-dom](@xmachines/play-dom/README.md)
+- [@xmachines/play-dom-router](@xmachines/play-dom-router/README.md)
 - [@xmachines/play-react](@xmachines/play-react/README.md)
 - [@xmachines/play-react-router](@xmachines/play-react-router/README.md)
-- [@xmachines/play-react-router-demo](@xmachines/play-react-router-demo/README.md)
 - [@xmachines/play-router](@xmachines/play-router/README.md)
-- [@xmachines/play-router-demo](@xmachines/play-router-demo/README.md)
 - [@xmachines/play-signals](@xmachines/play-signals/README.md)
 - [@xmachines/play-solid](@xmachines/play-solid/README.md)
 - [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md)
-- [@xmachines/play-solid-router-demo](@xmachines/play-solid-router-demo/README.md)
+- [@xmachines/play-svelte](@xmachines/play-svelte/README.md)
+- [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md)
+- [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md)
 - [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md)
-- [@xmachines/play-tanstack-react-router-demo](@xmachines/play-tanstack-react-router-demo/README.md)
+- [@xmachines/play-tanstack-router](@xmachines/play-tanstack-router/README.md)
 - [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md)
-- [@xmachines/play-tanstack-solid-router-demo](@xmachines/play-tanstack-solid-router-demo/README.md)
 - [@xmachines/play-vue](@xmachines/play-vue/README.md)
 - [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md)
-- [@xmachines/play-vue-router-demo](@xmachines/play-vue-router-demo/README.md)
 - [@xmachines/play-xstate](@xmachines/play-xstate/README.md)
 - [@xmachines/shared](@xmachines/shared/README.md)

package/api/llms.txt

@@ -1,26 +1,75 @@
-# 
+# XMachines JavaScript/TypeScript API Docs
 
-> Documentation for XMachines
+> Stream-first, deterministic state machine runtime, rendering, and router adapter packages for JavaScript and TypeScript.
+
+- Core actor, routing, rendering, and catalog packages
+- Framework adapters for React, Solid, Vue, and router integrations
+- Generated API reference tuned for package discovery and implementation guidance
+
+## Start Here
+
+- Defining players from machines: start with [@xmachines/play-xstate](@xmachines/play-xstate/README.md).
+- Understanding actor contracts: read [@xmachines/play-actor](@xmachines/play-actor/README.md) for [Viewable](@xmachines/play-actor/interfaces/Viewable.md) and [Routable](@xmachines/play-actor/interfaces/Routable.md).
+- [Viewable](@xmachines/play-actor/interfaces/Viewable.md) is the rendering contract: actors expose `currentView` plus a component catalog so rendering packages can resolve UI without owning application state.
+- [Routable](@xmachines/play-actor/interfaces/Routable.md) is the routing contract: actors expose `currentRoute` plus route-oriented event handling, while adapters translate browser or router changes into actor events.
+- Rendering actor-driven UI: use [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), [@xmachines/play-svelte](@xmachines/play-svelte/README.md), or [@xmachines/play-vue](@xmachines/play-vue/README.md).
+- Synchronizing URLs with actor state: use [@xmachines/play-router](@xmachines/play-router/README.md) plus a framework-specific router adapter.
+
+## Package Roles
+
+- `Core runtime`: [@xmachines/play](@xmachines/play/README.md), [@xmachines/play-actor](@xmachines/play-actor/README.md), [@xmachines/play-signals](@xmachines/play-signals/README.md), [@xmachines/play-router](@xmachines/play-router/README.md), and [@xmachines/play-xstate](@xmachines/play-xstate/README.md). Catalog and component registry are provided by `@xmachines/json-render-core` and the framework rendering packages.
+- `Rendering`: [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), [@xmachines/play-svelte](@xmachines/play-svelte/README.md), and [@xmachines/play-vue](@xmachines/play-vue/README.md).
+- `Router adapters`: [@xmachines/play-react-router](@xmachines/play-react-router/README.md), [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md), [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md), [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md), [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md), [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md), and [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md), all built on top of [Routable](@xmachines/play-actor/interfaces/Routable.md) actors and shared route metadata.
+- `Shared tooling`: [@xmachines/shared](@xmachines/shared/README.md) for shared config and workspace-level support files.
 
 ## API
-- [@xmachines/play](@xmachines/play/README.md): @xmachines/play module
-- [@xmachines/play-actor](@xmachines/play-actor/README.md): @xmachines/play-actor module
-- [@xmachines/play-catalog](@xmachines/play-catalog/README.md): @xmachines/play-catalog module
-- [@xmachines/play-react](@xmachines/play-react/README.md): @xmachines/play-react module
-- [@xmachines/play-react-router](@xmachines/play-react-router/README.md): @xmachines/play-react-router module
-- [@xmachines/play-react-router-demo](@xmachines/play-react-router-demo/README.md): @xmachines/play-react-router-demo module
-- [@xmachines/play-router](@xmachines/play-router/README.md): @xmachines/play-router module
-- [@xmachines/play-router-demo](@xmachines/play-router-demo/README.md): @xmachines/play-router-demo module
-- [@xmachines/play-signals](@xmachines/play-signals/README.md): @xmachines/play-signals module
-- [@xmachines/play-solid](@xmachines/play-solid/README.md): @xmachines/play-solid module
-- [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md): @xmachines/play-solid-router module
-- [@xmachines/play-solid-router-demo](@xmachines/play-solid-router-demo/README.md): @xmachines/play-solid-router-demo module
-- [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md): @xmachines/play-tanstack-react-router module
-- [@xmachines/play-tanstack-react-router-demo](@xmachines/play-tanstack-react-router-demo/README.md): @xmachines/play-tanstack-react-router-demo module
-- [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md): @xmachines/play-tanstack-solid-router module
-- [@xmachines/play-tanstack-solid-router-demo](@xmachines/play-tanstack-solid-router-demo/README.md): @xmachines/play-tanstack-solid-router-demo module
-- [@xmachines/play-vue](@xmachines/play-vue/README.md): @xmachines/play-vue module
-- [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md): @xmachines/play-vue-router module
-- [@xmachines/play-vue-router-demo](@xmachines/play-vue-router-demo/README.md): @xmachines/play-vue-router-demo module
-- [@xmachines/play-xstate](@xmachines/play-xstate/README.md): @xmachines/play-xstate module
-- [@xmachines/shared](@xmachines/shared/README.md): @xmachines/shared module
+- [@xmachines/play](@xmachines/play/README.md): Core Play types and runtime contracts
+- [@xmachines/play-actor](@xmachines/play-actor/README.md): Abstract actor base class plus Routable and Viewable capabilities
+- [@xmachines/play-dom](@xmachines/play-dom/README.md): Vanilla DOM renderer for Viewable actors
+- [@xmachines/play-dom-router](@xmachines/play-dom-router/README.md): Vanilla DOM browser history, router, and actor↔URL synchronization
+- [@xmachines/play-signals](@xmachines/play-signals/README.md): Signal primitives used by Play actors and adapters
+- [@xmachines/play-router](@xmachines/play-router/README.md): Route extraction, route maps, and shared routing infrastructure
+- [@xmachines/play-tanstack-router](@xmachines/play-tanstack-router/README.md): Shared framework-agnostic TanStack Router bridge base
+- [@xmachines/play-xstate](@xmachines/play-xstate/README.md): XState-backed player and actor integration
+- [@xmachines/play-react](@xmachines/play-react/README.md): React renderer for Viewable actors
+- [@xmachines/play-solid](@xmachines/play-solid/README.md): Solid renderer for Viewable actors
+- [@xmachines/play-vue](@xmachines/play-vue/README.md): Vue renderer for Viewable actors
+- [@xmachines/play-svelte](@xmachines/play-svelte/README.md): Svelte renderer for Viewable actors
+- [@xmachines/play-react-router](@xmachines/play-react-router/README.md): React Router bridge and provider for actor-driven navigation
+- [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md): TanStack React Router bridge and provider
+- [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md): Solid Router bridge and provider
+- [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md): TanStack Solid Router bridge and provider
+- [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md): Vue Router bridge and provider
+- [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md): SvelteKit router adapter for actor-driven navigation
+- [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md): Svelte SPA router adapter for actor-driven navigation
+- [@xmachines/shared](@xmachines/shared/README.md): Shared TypeScript, oxlint, and formatting configuration
+
+## Notes For LLMs
+
+- Prefer the core packages before the demo apps; demos are intentionally excluded from this file.
+- For implementation questions, usually read in this order: [@xmachines/play-actor](@xmachines/play-actor/README.md) -> [@xmachines/play-xstate](@xmachines/play-xstate/README.md) -> [@xmachines/play-router](@xmachines/play-router/README.md) -> framework renderer/adapter.
+- [Routable](@xmachines/play-actor/interfaces/Routable.md) is the key abstraction for URL synchronization: router adapters observe and update actor route state but do not own navigation policy.
+- Router adapter packages are passive infrastructure; business logic stays in the actor and machine layers.
+- Rendering packages consume the [Viewable](@xmachines/play-actor/interfaces/Viewable.md) contract and component catalogs rather than owning application state.
+
+## Quick Reference
+
+```javascript
+import { definePlayer } from '@xmachines/play-xstate';
+import { createRouteMapFromTree, extractMachineRoutes, extractRouteParams } from '@xmachines/play-router';
+import { defineRegistry } from '@xmachines/json-render-react';
+import { PlayRenderer } from '@xmachines/play-react';
+
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
+
+const currentView = actor.currentView.get();
+const currentRoute = actor.currentRoute.get();
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree);
+const stateId = routeMap.getStateIdByPath(currentRoute ?? '/');
+
+const { registry } = defineRegistry(catalog, { components, actions });
+<PlayRenderer actor={actor} registry={registry} actions={{ login: 'auth.login' }} />
+```

package/contributing/README.md

@@ -0,0 +1,10 @@
+# XMachines Development
+
+Reference documentation for contributors and maintainers of the `@xmachines/xmachines-js` monorepo.
+
+## Contents
+
+- **[Development](development.md)** — Monorepo setup, build system, adding packages, code conventions
+- **[Configuration](configuration.md)** — TypeScript, linting, formatting, Vitest, CI/CD, and release configuration
+- **[Testing](testing.md)** — Vitest setup, node vs browser modes, test patterns, coverage requirements
+- **[Deployment](deployment.md)** — npm publishing, semantic-release process, GitLab CI pipeline