@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.48

package/guides/installation.md

@@ -1,257 +0,0 @@
-<!-- generated-by: gsd-doc-writer -->
-
-# Installation
-
-Install XMachines packages for your platform.
-
-## Prerequisites
-
-- **Node.js 22+** (or compatible runtime)
-- **TypeScript 5.7+** with `strict: true` and `"type": "module"` in `package.json`
-- A package manager: npm, pnpm, or yarn
-
-XMachines packages are **ESM-only** — no CommonJS builds. All packages use `"type": "module"`.
-
-## Core Packages
-
-The minimum installation for defining machines and actors:
-
-```bash
-npm install @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals xstate
-```
-
-| 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`                        |
-
-### Minimal working example
-
-```typescript
-import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
-
-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: {},
-	},
-});
-
-const createPlayer = definePlayer({ machine });
-const actor = createPlayer();
-actor.start();
-
-console.log("✓ XMachines installed successfully");
-console.log("Current state:", actor.getSnapshot().value);
-
-actor.stop();
-```
-
-Run with:
-
-```bash
-npx tsx my-script.ts
-```
-
-## Framework-Specific Additions
-
-### Vanilla DOM
-
-```bash
-npm install @xmachines/play-dom @xmachines/play-dom-router @xmachines/play-router @json-render/core
-```
-
-| Package                      | Role                                                                             |
-| ---------------------------- | -------------------------------------------------------------------------------- |
-| `@xmachines/play-dom`        | `createRenderer`, `connectRenderer`, `defineRegistry`, `ComponentFn`, `ActionFn` |
-| `@xmachines/play-dom-router` | `connectRouter`, `createBrowserHistory`, `createRouter`, `createRouteMap`        |
-| `@xmachines/play-router`     | `extractMachineRoutes`, `getRoutableRoutes`, `formatPlayRouteTransitions`        |
-| `@json-render/core`          | Catalog and schema definitions (`defineCatalog`)                                 |
-
-### React
-
-```bash
-npm install @xmachines/play-react @xmachines/play-router @json-render/core @json-render/react
-```
-
-With routing:
-
-```bash
-# TanStack React Router
-npm install @xmachines/play-tanstack-react-router @tanstack/react-router
-
-# React Router v7
-npm install @xmachines/play-react-router react-router
-```
-
-| Package                                 | Role                                                             |
-| --------------------------------------- | ---------------------------------------------------------------- |
-| `@xmachines/play-react`                 | `PlayRenderer`, `defineRegistry`                                 |
-| `@xmachines/play-tanstack-react-router` | `PlayRouterProvider`, `createRouteMapFromTree`                   |
-| `@xmachines/play-react-router`          | `PlayRouterProvider`, `createRouteMapFromTree` (React Router v7) |
-
-### Vue 3
-
-```bash
-npm install @xmachines/play-vue @xmachines/play-vue-router @xmachines/play-router @json-render/core vue-router
-```
-
-| Package                      | Role                                   |
-| ---------------------------- | -------------------------------------- |
-| `@xmachines/play-vue`        | `PlayRenderer`, `defineRegistry`       |
-| `@xmachines/play-vue-router` | `PlayRouterProvider`, `createRouteMap` |
-
-### SolidJS
-
-```bash
-npm install @xmachines/play-solid @xmachines/play-router @json-render/core
-
-# With router:
-npm install @xmachines/play-solid-router @solidjs/router
-# or TanStack:
-npm install @xmachines/play-tanstack-solid-router @tanstack/solid-router
-```
-
-| Package                                 | Role                                                    |
-| --------------------------------------- | ------------------------------------------------------- |
-| `@xmachines/play-solid`                 | `PlayRenderer`, `defineRegistry`                        |
-| `@xmachines/play-solid-router`          | `PlayRouterProvider`, `createRouteMap` (SolidJS Router) |
-| `@xmachines/play-tanstack-solid-router` | `PlayRouterProvider`, `createRouteMap` (TanStack Solid) |
-
-### Svelte 5
-
-```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
-```
-
-| Package                             | Role                                                  |
-| ----------------------------------- | ----------------------------------------------------- |
-| `@xmachines/play-svelte`            | `PlayRenderer`, `defineRegistry`                      |
-| `@xmachines/play-sveltekit-router`  | `connectRouter`, `createRouteMap` (SvelteKit)         |
-| `@xmachines/play-svelte-spa-router` | `connectRouter`, `createRouteMap` (svelte-spa-router) |
-
-## TypeScript Configuration
-
-All XMachines packages require TypeScript strict mode and ESM module resolution.
-
-**Recommended `tsconfig.json`:**
-
-```json
-{
-	"compilerOptions": {
-		"target": "ESNext",
-		"module": "ESNext",
-		"moduleResolution": "bundler",
-		"strict": true,
-		"esModuleInterop": true,
-		"skipLibCheck": false,
-		"resolveJsonModule": true
-	}
-}
-```
-
-For Node.js projects (without a bundler), use `"moduleResolution": "node16"` or `"nodenext"`.
-
-**ESM import extensions:** Always use `.js` extensions in TypeScript import paths, even when importing `.ts` source files:
-
-```typescript
-// ✅ Correct
-import { authMachine } from "./auth-machine.js";
-
-// ❌ Wrong — will fail at runtime
-import { authMachine } from "./auth-machine";
-```
-
-**`package.json` for your project:**
-
-```json
-{
-	"type": "module",
-	"dependencies": {
-		"@xmachines/play-xstate": "latest",
-		"@xmachines/play-actor": "latest",
-		"@xmachines/play-signals": "latest",
-		"xstate": "latest"
-	}
-}
-```
-
-## ESM Setup for Node.js
-
-XMachines uses ESM exclusively. For Node.js:
-
-```json
-{
-	"type": "module"
-}
-```
-
-Or use `.mjs` file extensions. Dynamic imports work in CommonJS contexts:
-
-```javascript
-const { definePlayer } = await import("@xmachines/play-xstate");
-```
-
-## Deno
-
-XMachines works with Deno via npm specifiers:
-
-```typescript
-import { setup } from "npm:xstate";
-import { definePlayer } from "npm:@xmachines/play-xstate";
-```
-
-## Troubleshooting
-
-### `Cannot find module '@xmachines/play-xstate'`
-
-```bash
-# Verify installation
-npm list @xmachines/play-xstate
-
-# Reinstall
-npm install
-```
-
-### `SyntaxError: Cannot use import statement outside a module`
-
-Add `"type": "module"` to your `package.json`, or rename files to `.mjs`.
-
-### `Could not find a declaration file for module`
-
-Types are built-in — no separate `@types/` package needed. Check:
-
-- `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
-
-### Type incompatibilities between packages
-
-Install all XMachines packages with matching major versions:
-
-```bash
-npm install @xmachines/play-xstate@latest @xmachines/play-actor@latest @xmachines/play-signals@latest
-```
-
-## Next Steps
-
-- **[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