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

package/guides/signals.md

@@ -27,7 +27,7 @@ This model is sometimes called _glitch-free reactivity_: intermediate invalid st
 
 ## The three Signal primitives
 
-XMachines uses three primitives from the [TC39 Signals proposal](https://github.com/tc39/proposal-signals), accessed via `@xmachines/play-signals`:
+XMachines uses three primitives from the [TC39 Signals proposal](https://github.com/tc39/proposal-signals), accessed via [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md):
 
 ### `Signal.State` — writable values
 
@@ -78,13 +78,13 @@ actor.currentRoute.get(); // initial read required to arm the watcher
 
 Watcher notifications are **one-shot**: if you do not call `watch()` again after draining pending signals, you will miss subsequent changes.
 
-Router bridges and renderers use `Signal.subtle.Watcher` internally. For most application code, the `watchSignal()` helper covers the common case.
+Router bridges and renderers use `Signal.subtle.Watcher` internally. For most application code, the [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) helper covers the common case.
 
 ---
 
-## `watchSignal()` — the safe helper
+## [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) — the safe helper
 
-`@xmachines/play-signals` exports `watchSignal(signal, onValue)` as a lifecycle-safe wrapper around the raw watcher pattern. It returns a cleanup function:
+[`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) exports [`watchSignal(signal, onValue)`](../api/@xmachines/play-signals/functions/watchSignal.md) as a lifecycle-safe wrapper around the raw watcher pattern. It returns a cleanup function:
 
 ```typescript
 import { watchSignal } from "@xmachines/play-signals";
@@ -97,15 +97,15 @@ const stop = watchSignal(actor.currentRoute, (route) => {
 stop();
 ```
 
-`watchSignal()` handles three subtle correctness concerns for you:
+[`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) handles three subtle correctness concerns for you:
 
-| Concern                | What happens without it                            | How `watchSignal` handles it                                           |
-| ---------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- |
-| **Use-after-free**     | Callback fires after component unmounts            | `disposed` flag checked before invoking callback                       |
-| **Coalescing**         | Rapid synchronous changes cause multiple callbacks | `needsEnqueue` guard — only one microtask queued per synchronous burst |
-| **Idempotent cleanup** | Calling the cleanup twice throws                   | Safe to call multiple times                                            |
+| Concern                | What happens without it                            | How [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md) handles it |
+| ---------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| **Use-after-free**     | Callback fires after component unmounts            | `disposed` flag checked before invoking callback                                        |
+| **Coalescing**         | Rapid synchronous changes cause multiple callbacks | `needsEnqueue` guard — only one microtask queued per synchronous burst                  |
+| **Idempotent cleanup** | Calling the cleanup twice throws                   | Safe to call multiple times                                                             |
 
-Use `watchSignal()` in framework adapters and application code. Use the raw `Signal.subtle.Watcher` only when building infrastructure that needs to watch multiple signals independently.
+Use [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) in framework adapters and application code. Use the raw `Signal.subtle.Watcher` only when building infrastructure that needs to watch multiple signals independently.
 
 ---
 
@@ -113,7 +113,7 @@ Use `watchSignal()` in framework adapters and application code. Use the raw `Sig
 
 The XMachines architecture chose TC39 Signals over observable libraries and event emitters for three reasons:
 
-**1. Standardization.** Signals are a Stage 1 TC39 proposal. They are not tied to any library, bundler, or framework. Isolating the polyfill behind `@xmachines/play-signals` means the entire ecosystem can migrate to native signals when the proposal lands, with a single package update.
+**1. Standardization.** Signals are a Stage 1 TC39 proposal. They are not tied to any library, bundler, or framework. Isolating the polyfill behind [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) means the entire ecosystem can migrate to native signals when the proposal lands, with a single package update.
 
 **2. Synchronous atomic propagation.** RxJS streams are asynchronous by default. Event emitters fire immediately but serially — a listener registered halfway through a sequence can see inconsistent state. Signals propagate atomically: all computeds update before any watcher fires.
 
@@ -139,7 +139,7 @@ The Play RFC defines five invariants that govern how signals are used:
 
 Signals do not clean themselves up when they go out of scope. Every watcher you create must be explicitly disposed when the consuming component or adapter unmounts.
 
-- Framework lifecycle hooks (`useEffect` cleanup in React, `onUnmounted` in Vue, `onCleanup` in Solid) must call `unwatch()` or the cleanup returned by `watchSignal()`.
+- Framework lifecycle hooks (`useEffect` cleanup in React, `onUnmounted` in Vue, `onCleanup` in Solid) must call `unwatch()` or the cleanup returned by [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md).
 - Router bridge `disconnect()` methods must unwatch all signal subscriptions.
 - If you use the raw `Signal.subtle.Watcher` API, pair every `watch()` call with `unwatch()` in teardown.
 
@@ -149,12 +149,12 @@ Failing to clean up watchers causes memory leaks and stale callbacks firing afte
 
 ## Summary
 
-| Primitive               | Role in XMachines                              | Who uses it                        |
-| ----------------------- | ---------------------------------------------- | ---------------------------------- |
-| `Signal.State`          | Actor output: writable snapshot and view state | Actor writes; infrastructure reads |
-| `Signal.Computed`       | Lazy derivations: routes, view specs           | Actor defines; adapters read       |
-| `Signal.subtle.Watcher` | Low-level reactive observation                 | Framework adapters, router bridges |
-| `watchSignal()`         | Lifecycle-safe single-signal subscription      | Application code, adapter code     |
+| Primitive                                                                  | Role in XMachines                              | Who uses it                        |
+| -------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------- |
+| `Signal.State`                                                             | Actor output: writable snapshot and view state | Actor writes; infrastructure reads |
+| `Signal.Computed`                                                          | Lazy derivations: routes, view specs           | Actor defines; adapters read       |
+| `Signal.subtle.Watcher`                                                    | Low-level reactive observation                 | Framework adapters, router bridges |
+| [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) | Lifecycle-safe single-signal subscription      | Application code, adapter code     |
 
 ## See also
 

package/guides/state-machines.md

@@ -24,7 +24,7 @@ In traditional component-level state (e.g., boolean flags, `useState` combinatio
 
 ## How XMachines uses XState v5
 
-XMachines wraps XState v5 via `@xmachines/play-xstate`. You define machines using XState's `setup().createMachine()` API:
+XMachines wraps XState v5 via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md). You define machines using XState's `setup().createMachine()` API:
 
 ```typescript
 import { setup } from "xstate";
@@ -124,13 +124,13 @@ const appMachine = setup({
 
 `meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `Signal.Computed`) derives this path and emits it. The router bridge reads it and updates the URL.
 
-`meta.view` is a `PlaySpec` — a `@json-render/core` spec object describing what to render. Use `typedSpec<TContext>(...)` from `@xmachines/play-actor` to validate `contextProps` entries at compile time. When the machine enters a state, `actor.currentView` is updated with this spec. The renderer reads it and projects it through framework components.
+`meta.view` is a [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) — a `@json-render/core` spec object describing what to render. Use `typedSpec<TContext>(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to validate `contextProps` entries at compile time. When the machine enters a state, `actor.currentView` is updated with this spec. The renderer reads it and projects it through framework components.
 
 **The machine is the single source of truth for both routing and views.** There is no separate route configuration file. There is no switch statement in a component deciding what to render based on the URL. The state machine encodes all of that.
 
 ---
 
-## `formatPlayRouteTransitions` — automatic route event wiring
+## [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) — automatic route event wiring
 
 For routing to work, the machine must respond to `play.route` events (sent by router bridges when the user navigates). Writing these transitions by hand is mechanical:
 
@@ -150,7 +150,7 @@ states: {
 }
 ```
 
-`formatPlayRouteTransitions` from `@xmachines/play-xstate` generates these transitions automatically from the `id` and `meta.route` fields you already have:
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) generates these transitions automatically from the `id` and `meta.route` fields you already have:
 
 ```typescript
 import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
@@ -170,7 +170,7 @@ const appMachine = setup({
 );
 ```
 
-`formatPlayRouteTransitions` inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
 
 ```typescript
 types: {
@@ -202,16 +202,16 @@ Guards are evaluated by XState before a transition fires. If the guard returns `
 
 This is the **Actor Authority** invariant in practice: the machine decides, infrastructure adjusts.
 
-XMachines provides guard combinators in `@xmachines/play-xstate` for composing complex conditions:
+XMachines provides guard combinators in [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) for composing complex conditions:
 
-| Function                          | What it does                            |
-| --------------------------------- | --------------------------------------- |
-| `composeGuards(...guards)`        | AND — all guards must pass              |
-| `composeGuardsOr(...guards)`      | OR — any guard must pass                |
-| `negateGuard(guard)`              | NOT — inverts the guard result          |
-| `hasContext(key)`                 | Checks that a context field is non-null |
-| `contextFieldMatches(key, value)` | Checks a context field against a value  |
-| `eventMatches(type)`              | Checks the event type                   |
+| Function                                                                                            | What it does                            |
+| --------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| [`composeGuards(...guards)`](../api/@xmachines/play-xstate/functions/composeGuards.md)              | AND — all guards must pass              |
+| [`composeGuardsOr(...guards)`](../api/@xmachines/play-xstate/functions/composeGuardsOr.md)          | OR — any guard must pass                |
+| [`negateGuard(guard)`](../api/@xmachines/play-xstate/functions/negateGuard.md)                      | NOT — inverts the guard result          |
+| [`hasContext(key)`](../api/@xmachines/play-xstate/functions/hasContext.md)                          | Checks that a context field is non-null |
+| [`contextFieldMatches(key, value)`](../api/@xmachines/play-xstate/functions/contextFieldMatches.md) | Checks a context field against a value  |
+| [`eventMatches(type)`](../api/@xmachines/play-xstate/functions/eventMatches.md)                     | Checks the event type                   |
 
 ---
 
@@ -261,7 +261,7 @@ actor.start();
 // Actor resumes from where it left off
 ```
 
-`definePlayer` accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
+[`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
 
 ---
 
@@ -283,6 +283,6 @@ actor.start();
 - [Understanding TC39 Signals](signals.md) — how the actor's state is observed by infrastructure
 - [Getting Started](getting-started.md) — step-by-step walkthrough building your first machine and actor
 - [Routing Patterns](../examples/routing-patterns.md) — worked examples of `meta.route` and guards
-- [@xmachines/play-xstate README](../api/@xmachines/play-xstate/README.md) — full API reference for `definePlayer`, `PlayerActor`, guard combinators
+- [@xmachines/play-xstate README](../api/@xmachines/play-xstate/README.md) — full API reference for [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), guard combinators
 - [XState v5 documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
 - [Play RFC](../rfc/play.md) — complete architectural specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.46",
+  "version": "1.0.0-beta.50",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -20,6 +20,7 @@
   },
   "files": [
     "api",
+    "contributing",
     "examples",
     "guides",
     "rfc",
@@ -33,6 +34,7 @@
       "import": "./index.js"
     },
     "./api/*": "./api/*",
+    "./contributing/*": "./contributing/*",
     "./examples/*": "./examples/*",
     "./guides/*": "./guides/*",
     "./rfc/*": "./rfc/*"
@@ -49,12 +51,12 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@xmachines/shared": "1.0.0-beta.46",
-    "oxfmt": "^0.45.0",
-    "oxlint": "^1.60.0",
+    "@xmachines/shared": "1.0.0-beta.50",
+    "oxfmt": "^0.47.0",
+    "oxlint": "^1.62.0",
     "typedoc": "^0.28.19",
     "typedoc-plugin-llms-txt": "^0.1.2",
     "typedoc-plugin-markdown": "^4.11.0",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.5"
   }
 }

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