@xmachines/docs 1.0.0-beta.25 → 1.0.0-beta.27

package/guides/installation.md

@@ -1,175 +1,157 @@
+<!-- generated-by: gsd-doc-writer -->
+
 # Installation
 
-This guide covers installing XMachines packages in your project across different package managers and environments.
+Install XMachines packages for your platform.
 
 ## Prerequisites
 
-Before installing XMachines, ensure you have:
-
 - **Node.js 22+** (or compatible runtime)
-- **Package manager**: npm, pnpm, or yarn
-- **TypeScript** (optional but recommended for full type safety)
-
-## Installing XMachines
-
-Choose your preferred package manager:
+- **TypeScript 5.7+** with `strict: true` and `"type": "module"` in `package.json`
+- A package manager: npm, pnpm, or yarn
 
-### npm
+XMachines packages are **ESM-only** — no CommonJS builds. All packages use `"type": "module"`.
 
-```bash
-npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
-```
+## Core Packages
 
-### pnpm
+The minimum installation for defining machines and actors:
 
 ```bash
-pnpm add @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
+npm install @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals xstate
 ```
 
-### yarn
+| Package                   | Role                                                        |
+| ------------------------- | ----------------------------------------------------------- |
+| `xstate`                  | XState v5 peer dependency — `setup`, `assign`, etc.         |
+| `@xmachines/play-xstate`  | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
+| `@xmachines/play-actor`   | `AbstractActor`, `typedSpec` — actor base class             |
+| `@xmachines/play-signals` | TC39 Signals polyfill, `watchSignal`                        |
 
-```bash
-yarn add @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
-```
+### Minimal working example
 
-## Package Selection Guide
-
-XMachines is a modular system of packages. Choose the packages based on your needs:
-
-### Core Packages (Required)
-
-**@xmachines/play**
-
-- Foundation package with core protocols and contracts
-- Required by all other packages
-
-**@xmachines/play-actor**
-
-- Abstract actor base class extending XState Actor
-- Required for instantiating state machines
+```typescript
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
 
-**@xmachines/play-signals**
+const machine = setup({
+	types: {
+		context: {} as { count: number },
+		events: {} as { type: "increment" },
+		input: {} as undefined,
+	},
+}).createMachine({
+	id: "counter",
+	initial: "idle",
+	context: { count: 0 },
+	states: {
+		idle: {},
+	},
+});
 
-- TC39 Signals polyfill for reactive updates
-- Required for reactive state observation
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
 
-**@xmachines/play-xstate**
+console.log("✓ XMachines installed successfully");
+console.log("Current state:", actor.getSnapshot().value);
 
-- XState v5 logic adapter with catalog binding
-- Required for state machine definitions
+actor.stop();
+```
 
-**Minimal installation:**
+Run with:
 
 ```bash
-npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
+npx tsx my-script.ts
 ```
 
-### UI and Routing (Optional)
-
-**@json-render/core** (external)
-
-- Component catalog and schema definition with Zod validation
-- Install if: Building declarative UI structures from state
-
-**@xmachines/play-router**
+## Framework-Specific Additions
 
-- Route tree protocol and machine crawler
-- Install if: Implementing logic-driven routing
-
-**@xmachines/play-tanstack-react-router**
-
-- TanStack Router adapter with signal observation
-- Install if: Using TanStack Router for navigation (React)
-
-**@xmachines/play-react**
-
-- React view renderer with JSON-Render
-- Install if: Building React applications
-
-> **Other frameworks:** Vue (`@xmachines/play-vue`, `@xmachines/play-vue-router`), SolidJS (`@xmachines/play-solid`, `@xmachines/play-solid-router`, `@xmachines/play-tanstack-solid-router`), and Vanilla DOM (`@xmachines/play-dom`) adapters are also available.
-
-### Complete Installation
-
-For full-featured development with React and routing:
+### Vanilla DOM
 
 ```bash
-npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals @xmachines/play-router @xmachines/play-tanstack-react-router @xmachines/play-react @json-render/core @json-render/react
+npm install @xmachines/play-dom @xmachines/play-dom-router @xmachines/play-router @json-render/core
 ```
 
-**See also:** [API Reference](../api/README.md) for detailed descriptions of each package.
-
-## Environment-Specific Setup
+| Package                      | Role                                                                      |
+| ---------------------------- | ------------------------------------------------------------------------- |
+| `@xmachines/play-dom`        | `connectRenderer`, `defineRegistry`                                       |
+| `@xmachines/play-dom-router` | `connectRouter`, `createBrowserHistory`, `createRouter`, `createRouteMap` |
+| `@xmachines/play-router`     | `extractMachineRoutes`, `getRoutableRoutes`                               |
+| `@json-render/core`          | Catalog and schema definitions (`defineCatalog`)                          |
 
-### Browser (Vite, Webpack, or other bundlers)
+### React
 
-No special configuration needed. ESM imports work out of the box:
-
-```typescript
-import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
-import { Signal } from "@xmachines/play-signals";
+```bash
+npm install @xmachines/play-react @xmachines/play-router @json-render/core @json-render/react
 ```
 
-Most modern bundlers (Vite, Webpack 5+, Rollup) handle ESM packages automatically.
-
-### Node.js
-
-XMachines uses ESM (ECMAScript Modules) exclusively. Ensure your project is configured for ESM:
+With routing:
 
-**Option 1: Set `"type": "module"` in package.json**
+```bash
+# TanStack React Router
+npm install @xmachines/play-tanstack-react-router @tanstack/react-router
 
-```json
-{
-	"type": "module",
-	"dependencies": {
-		"@xmachines/play": "^1.0.0"
-	}
-}
+# React Router v7
+npm install @xmachines/play-react-router react-router
 ```
 
-**Option 2: Use `.mjs` file extensions**
+| Package                                 | Role                                                             |
+| --------------------------------------- | ---------------------------------------------------------------- |
+| `@xmachines/play-react`                 | `PlayRenderer`, `defineRegistry`                                 |
+| `@xmachines/play-tanstack-react-router` | `PlayRouterProvider`, `createRouteMapFromTree`                   |
+| `@xmachines/play-react-router`          | `PlayRouterProvider`, `createRouteMapFromTree` (React Router v7) |
 
-Alternatively, name your files with `.mjs` extension:
+### Vue 3
 
 ```bash
-node my-app.mjs
+npm install @xmachines/play-vue @xmachines/play-vue-router @xmachines/play-router @json-render/core vue-router
 ```
 
-**Import example:**
+| Package                      | Role                                   |
+| ---------------------------- | -------------------------------------- |
+| `@xmachines/play-vue`        | `PlayRenderer`, `defineRegistry`       |
+| `@xmachines/play-vue-router` | `PlayRouterProvider`, `createRouteMap` |
 
-```typescript
-import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
+### SolidJS
 
-const machine = setup({}).createMachine({
-	id: "example",
-	initial: "idle",
-	states: {
-		idle: { on: { START: "running" } },
-		running: { on: { STOP: "idle" } },
-	},
-});
+```bash
+npm install @xmachines/play-solid @xmachines/play-router @json-render/core
 
-const createExample = definePlayer({ machine });
-const actor = createExample();
-actor.start();
+# With router:
+npm install @xmachines/play-solid-router @solidjs/router
+# or TanStack:
+npm install @xmachines/play-tanstack-solid-router @tanstack/solid-router
 ```
 
-### Deno
+| Package                                 | Role                                                    |
+| --------------------------------------- | ------------------------------------------------------- |
+| `@xmachines/play-solid`                 | `PlayRenderer`, `defineRegistry`                        |
+| `@xmachines/play-solid-router`          | `PlayRouterProvider`, `createRouteMap` (SolidJS Router) |
+| `@xmachines/play-tanstack-solid-router` | `PlayRouterProvider`, `createRouteMap` (TanStack Solid) |
 
-XMachines works with Deno via npm specifiers:
+### Svelte 5
 
-```typescript
-import { setup } from "npm:xstate";
-import { definePlayer } from "npm:@xmachines/play-xstate";
-import { Signal } from "npm:@xmachines/play-signals";
+```bash
+npm install @xmachines/play-svelte @xmachines/play-router @json-render/core
+
+# With SvelteKit routing:
+npm install @xmachines/play-sveltekit-router
+
+# With svelte-spa-router (hash routing):
+npm install @xmachines/play-svelte-spa-router
 ```
 
-### TypeScript
+| Package                             | Role                                                  |
+| ----------------------------------- | ----------------------------------------------------- |
+| `@xmachines/play-svelte`            | `PlayRenderer`, `defineRegistry`                      |
+| `@xmachines/play-sveltekit-router`  | `connectRouter`, `createRouteMap` (SvelteKit)         |
+| `@xmachines/play-svelte-spa-router` | `connectRouter`, `createRouteMap` (svelte-spa-router) |
 
-XMachines is written in TypeScript and includes built-in type definitions. No separate `@types` package is needed.
+## TypeScript Configuration
 
-**Recommended tsconfig.json settings:**
+All XMachines packages require TypeScript strict mode and ESM module resolution.
+
+**Recommended `tsconfig.json`:**
 
 ```json
 {
@@ -185,133 +167,91 @@ XMachines is written in TypeScript and includes built-in type definitions. No se
 }
 ```
 
-**Key settings:**
-
-- **`moduleResolution: "bundler"`** (recommended) or `"node16"` for Node.js projects
-- **`strict: true`** enables full type checking
-- **`target: "ESNext"`** leverages modern JavaScript features
+For Node.js projects (without a bundler), use `"moduleResolution": "node16"` or `"nodenext"`.
 
-**Type inference:**
-
-XMachines provides full type inference from machine definition through to components:
+**ESM import extensions:** Always use `.js` extensions in TypeScript import paths, even when importing `.ts` source files:
 
 ```typescript
-import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
-
-const machine = setup({}).createMachine({
-	id: "typed",
-	initial: "idle",
-	context: { count: 0 },
-	states: {
-		idle: { on: { START: "running" } },
-		running: { on: { STOP: "idle" } },
-	},
-});
+// ✅ Correct
+import { authMachine } from "./auth-machine.js";
 
-const createTyped = definePlayer({ machine });
-const actor = createTyped();
-// Actor signals provide reactive type-safe state access
+// ❌ Wrong — will fail at runtime
+import { authMachine } from "./auth-machine";
 ```
 
-## Verifying Installation
+**`package.json` for your project:**
 
-Test your installation with this simple script:
-
-**test.ts** (or test.js with `"type": "module"`):
-
-```typescript
-import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
-
-const machine = setup({}).createMachine({
-	id: "test",
-	initial: "ready",
-	states: {
-		ready: {},
-	},
-});
-
-const createTest = definePlayer({ machine });
-const actor = createTest();
-actor.start();
-
-console.log("✓ XMachines installed successfully");
-console.log("Current state:", actor.getSnapshot().value);
+```json
+{
+	"type": "module",
+	"dependencies": {
+		"@xmachines/play-xstate": "latest",
+		"@xmachines/play-actor": "latest",
+		"@xmachines/play-signals": "latest",
+		"xstate": "latest"
+	}
+}
 ```
 
-**Run the test:**
-
-```bash
-# TypeScript (requires tsx or ts-node)
-npx tsx test.ts
+## ESM Setup for Node.js
 
-# Or compile first
-npx tsc test.ts && node test.js
+XMachines uses ESM exclusively. For Node.js:
 
-# JavaScript (with "type": "module")
-node test.js
+```json
+{
+	"type": "module"
+}
 ```
 
-**Expected output:**
+Or use `.mjs` file extensions. Dynamic imports work in CommonJS contexts:
 
-```
-✓ XMachines installed successfully
-Current state: ready
+```javascript
+const { definePlayer } = await import("@xmachines/play-xstate");
 ```
 
-## Troubleshooting
-
-### Module Not Found
+## Deno
 
-**Error:** `Cannot find module '@xmachines/play-xstate'`
-
-**Solutions:**
+XMachines works with Deno via npm specifiers:
 
-- Verify package is installed: `npm list @xmachines/play-xstate`
-- Re-install dependencies: `npm install`
-- Check `node_modules/@xmachines/` directory exists
+```typescript
+import { setup } from "npm:xstate";
+import { definePlayer } from "npm:@xmachines/play-xstate";
+```
 
-### ESM Import Errors
+## Troubleshooting
 
-**Error:** `SyntaxError: Cannot use import statement outside a module`
+### `Cannot find module '@xmachines/play-xstate'`
 
-**Solutions:**
+```bash
+# Verify installation
+npm list @xmachines/play-xstate
 
-- Add `"type": "module"` to package.json
-- Or rename files to `.mjs` extension
-- Or use dynamic import: `const { definePlayer } = await import('@xmachines/play-xstate')`
+# Reinstall
+npm install
+```
 
-### Type Errors
+### `SyntaxError: Cannot use import statement outside a module`
 
-**Error:** `Could not find a declaration file for module '@xmachines/play-xstate'`
+Add `"type": "module"` to your `package.json`, or rename files to `.mjs`.
 
-**Solutions:**
+### `Could not find a declaration file for module`
 
-- Types are built-in; no `@types` package needed
-- Check TypeScript version (4.5+ required)
-- Verify `moduleResolution` in tsconfig.json is set correctly
-- Try `npm install` again to ensure types are properly linked
+Types are built-in — no separate `@types/` package needed. Check:
 
-### Version Mismatches
+- `moduleResolution` in `tsconfig.json` is set to `"bundler"`, `"node16"`, or `"nodenext"`
+- TypeScript version is 5.7+
+- Run `npm install` again to ensure dist files are present
 
-**Error:** Type incompatibilities between packages
+### Type incompatibilities between packages
 
-**Solution:**
 Install all XMachines packages with matching major versions:
 
 ```bash
-npm install @xmachines/play@latest @xmachines/play-xstate@latest @xmachines/play-actor@latest @xmachines/play-signals@latest
+npm install @xmachines/play-xstate@latest @xmachines/play-actor@latest @xmachines/play-signals@latest
 ```
 
 ## Next Steps
 
-Now that XMachines is installed, you're ready to build your first state machine:
-
-- **[Getting Started →](getting-started.md)** - Build your first state machine
-- **[API Reference](../api/README.md)** - Deep dive into each package
-- **[Examples](../examples/README.md)** - See XMachines in action
-
----
-
-**Need help?** Check the [API Reference](../api/README.md) for detailed information.
+- **[Getting Started →](getting-started.md)** — Build your first machine and actor
+- **[Examples](../examples/README.md)** — Routing patterns, form validation, multi-router demos
+- **[API Reference](../api/README.md)** — Generated API docs for all packages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.25",
+  "version": "1.0.0-beta.27",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -48,7 +48,7 @@
     "typedoc": "typedoc"
   },
   "devDependencies": {
-    "@xmachines/shared": "1.0.0-beta.25",
+    "@xmachines/shared": "1.0.0-beta.27",
     "oxfmt": "^0.43.0",
     "oxlint": "^1.57.0",
     "typedoc": "^0.28.18",

package/api/@xmachines/play-tanstack-react-router/functions/extractParams.md

@@ -1,38 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / extractParams
-
-# Function: extractParams()
-
-```ts
-function extractParams(pathname, pattern): Record<string, string>;
-```
-
-Defined in: [play-tanstack-react-router/src/extract-params.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/extract-params.ts#L29)
-
-Extract route parameters from URL path based on route pattern using URLPattern API
-
-## Parameters
-
-| Parameter  | Type     | Description                                          |
-| ---------- | -------- | ---------------------------------------------------- |
-| `pathname` | `string` | Actual URL path (e.g., "/profile/123")               |
-| `pattern`  | `string` | Route pattern with params (e.g., "/profile/:userId") |
-
-## Returns
-
-`Record`\<`string`, `string`\>
-
-Object with extracted parameters
-
-## Example
-
-```typescript
-extractParams("/profile/123", "/profile/:userId");
-// Returns: { userId: "123" }
-
-extractParams("/api/123", "/api/:id(\\d+)");
-// Returns: { id: "123" }
-// Validates numeric constraint via URLPattern
-
-extractParams("/docs/intro", "/docs/*");
-// Returns: { "0": "intro" }
-```

package/api/@xmachines/play-tanstack-react-router/functions/extractQueryParams.md

@@ -1,33 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / extractQueryParams
-
-# Function: extractQueryParams()
-
-```ts
-function extractQueryParams(search): Record<string, string>;
-```
-
-Defined in: [play-tanstack-react-router/src/extract-params.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/extract-params.ts#L68)
-
-Extract query parameters from search string
-
-## Parameters
-
-| Parameter | Type     | Description                                                                      |
-| --------- | -------- | -------------------------------------------------------------------------------- |
-| `search`  | `string` | Query string with or without leading ? (e.g., "?tab=settings" or "tab=settings") |
-
-## Returns
-
-`Record`\<`string`, `string`\>
-
-Object mapping query parameter names to values
-
-## Example
-
-```typescript
-extractQueryParams("?tab=settings&theme=dark");
-// Returns: { tab: "settings", theme: "dark" }
-
-extractQueryParams("q=hello%20world");
-// Returns: { q: "hello world" } (auto-decoded)
-```