@xmachines/docs 1.0.0-beta.56 → 1.0.0-beta.57

package/examples/@xmachines/play-vue-demo/variables/App.md

@@ -6,4 +6,4 @@
 const App: DefineComponent<{}, {}, unknown>;
 ```
 
-Defined in: [packages/play-vue/examples/demo/src/env.d.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-vue/examples/demo/src/env.d.ts#L5)
+Defined in: [packages/play-vue/examples/demo/src/env.d.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/play-vue/examples/demo/src/env.d.ts#L5)

package/examples/@xmachines/play-vue-demo/variables/authCatalog.md

@@ -169,4 +169,4 @@ const authCatalog: Catalog<
 >;
 ```
 
-Defined in: [packages/play-vue/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-vue/examples/demo/src/catalog.ts#L5)
+Defined in: [packages/play-vue/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/play-vue/examples/demo/src/catalog.ts#L5)

package/examples/@xmachines/play-vue-router-demo/README.md

@@ -19,11 +19,11 @@ Vue Router integration demo for the XMachines Play architecture using Vue Compos
 From the repository root:
 
 ```bash
-npm install
-npm run dev -w @xmachines/play-vue-router-demo
+pnpm install
+pnpm --filter @xmachines/play-vue-router-demo run dev
 ```
 
-Then open `http://localhost:3001`.
+Then open `http://localhost:3010`.
 
 ## Step-by-Step Code Flow
 
@@ -114,21 +114,21 @@ Vue Router integration remains passive infrastructure. `RouterBridgeBase` owns s
 
 These commands are defined in `package.json`:
 
-| Command                                                   | Description                      |
-| --------------------------------------------------------- | -------------------------------- |
-| `npm run dev -w @xmachines/play-vue-router-demo`          | Start Vite dev server            |
-| `npm run build -w @xmachines/play-vue-router-demo`        | Build production bundle          |
-| `npm run preview -w @xmachines/play-vue-router-demo`      | Preview built bundle             |
-| `npm run test -w @xmachines/play-vue-router-demo`         | Run Vitest test suite            |
-| `npm run test:browser -w @xmachines/play-vue-router-demo` | Run browser-focused Vitest suite |
+| Command                                                          | Description                                    |
+| ---------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-vue-router-demo run dev`          | Start Vite dev server (http://localhost:3010/) |
+| `pnpm --filter @xmachines/play-vue-router-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-vue-router-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-vue-router-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-vue-router-demo run test:browser` | Run browser-focused Vitest suite               |
 
 ## Verification
 
 Use these checks to validate README claims against the current demo implementation:
 
 ```bash
-npm run test -w @xmachines/play-vue-router-demo
-npm run test:browser -w @xmachines/play-vue-router-demo
+pnpm --filter @xmachines/play-vue-router-demo run test
+pnpm --filter @xmachines/play-vue-router-demo run test:browser
 ```
 
 Expected result: reactivity integration tests and the browser shared-demo suite both pass, confirming login/logout transitions update both view and URL correctly.

package/examples/README.md

@@ -58,16 +58,16 @@ The conceptual examples in this directory are TypeScript snippets. To run them:
 
 ```bash
 # Install dependencies (from the monorepo root)
-npm install @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals xstate
+pnpm add @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals xstate
 
 # Run with tsx
-npx tsx my-example.ts
+pnpm dlx tsx my-example.ts
 ```
 
 To run a complete demo application, use the workspace package name:
 
 ```bash
-npm run dev -w @xmachines/play-dom-router-demo
+pnpm --filter @xmachines/play-dom-router-demo run dev
 ```
 
 ## Key Packages

package/guides/getting-started.md

@@ -20,13 +20,13 @@ Jump to the section that applies to you:
 
 You need the following installed before cloning the repository:
 
-| Requirement | Version              | Notes                                                        |
-| ----------- | -------------------- | ------------------------------------------------------------ |
-| Node.js     | `>= 22.0.0`          | Specified in all `package.json` `engines` fields             |
-| npm         | bundled with Node 22 | The project uses npm workspaces — no separate install needed |
-| Git         | any recent version   | Conventional commit format is enforced by CI                 |
+| Requirement | Version            | Notes                                                                                                                 |
+| ----------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| Node.js     | `>= 22.0.0`        | Specified in all `package.json` `engines` fields                                                                      |
+| pnpm        | via corepack       | Enable with `corepack enable`; the version is pinned by the `packageManager` field. The project uses pnpm workspaces. |
+| Git         | any recent version | Conventional commit format is enforced by CI                                                                          |
 
-No global TypeScript install is needed — it is installed as a dev dependency via `npm ci`.
+No global TypeScript install is needed — it is installed as a dev dependency via `pnpm install --frozen-lockfile`.
 
 > **Node.js version manager tip:** If you manage multiple Node versions with `nvm` or `fnm`, install and activate Node 22 before proceeding.
 
@@ -41,18 +41,19 @@ cd xmachines-js
 
 #### 2. Install dependencies
 
-Always use `npm ci` (not `npm install`) to respect the lockfile exactly:
+Always use `pnpm install --frozen-lockfile` (not `pnpm install`) to respect the lockfile exactly:
 
 ```bash
-npm ci
+corepack enable
+pnpm install --frozen-lockfile
 ```
 
-This installs all workspace dependencies and automatically runs `patch-package` via the `postinstall` hook to apply the patches in `patches/`. The patch output is expected and required — do not skip it.
+This installs the exact versions recorded in the lockfile for all workspace packages.
 
 #### 3. Build all packages
 
 ```bash
-npm run build
+pnpm run build
 ```
 
 The root `tsc --build` command uses TypeScript project references to compile all packages in correct dependency order. Build outputs go to each package's `dist/` directory (gitignored).
@@ -62,7 +63,7 @@ The root `tsc --build` command uses TypeScript project references to compile all
 Verify your setup is working end-to-end:
 
 ```bash
-npm test
+pnpm test
 ```
 
 All tests should pass on a freshly cloned and built repository. If they do, your environment is correctly configured.
@@ -76,7 +77,7 @@ A fully configured dev container is provided at `.devcontainer/`. It uses Docker
 **CLI:**
 
 ```bash
-npm run devcontainer:up
+pnpm run devcontainer:up
 ```
 
 To customize the container, copy the sample env file:
@@ -98,20 +99,12 @@ Available variables:
 
 The test suite relies on TypeScript path aliases that resolve to source files. If aliases are not resolving:
 
-1. Run `npm run build` first — some packages need their `dist/` present even in development.
+1. Run `pnpm run build` first — some packages need their `dist/` present even in development.
 2. Confirm your package's `vitest.config.ts` uses `defineXmVitestConfig` from `@xmachines/shared/vitest`, which automatically configures the `@xmachines/*` path aliases.
 
 #### TypeScript errors about missing types after adding a dependency
 
-Run `npm ci` again to ensure all types are installed. If you added a workspace-local dependency, also add the correct `references` entry in the package's `tsconfig.base.json`.
-
-#### `patch-package` errors during install
-
-The patches in `patches/` are version-specific. If you updated a `@json-render` package, regenerate the patch:
-
-```bash
-npx patch-package <package-name>
-```
+Run `pnpm install --frozen-lockfile` again to ensure all types are installed. If you added a workspace-local dependency, also add the correct `references` entry in the package's `tsconfig.base.json`.
 
 #### Lint errors about import extensions
 
@@ -150,7 +143,7 @@ This section covers installing XMachines packages into your own application and
 ### Prerequisites
 
 - **Node.js** `>= 22.0.0`
-- **npm** `>= 10.0.0`
+- **pnpm** via corepack (`corepack enable`)
 - **TypeScript** `>= 5.7` (strict mode recommended)
 - **XState** `v5` (required peer dependency for [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md))
 
@@ -163,7 +156,7 @@ All packages are ES modules (`"type": "module"`). Use `.js` extensions in all Ty
 Every XMachines application needs these three packages plus XState:
 
 ```bash
-npm install xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
+pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
 ```
 
 | Package                                                               | Role                                                                                                                                                                |
@@ -177,26 +170,26 @@ npm install xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-
 
 ```bash
 # Provider pattern (framework-integrated routers)
-npm install @xmachines/play-tanstack-react-router   # TanStack Router (React)
-npm install @xmachines/play-tanstack-solid-router   # TanStack Router (SolidJS)
-npm install @xmachines/play-react-router            # React Router v7
-npm install @xmachines/play-vue-router              # Vue Router 4.x/5.x
-npm install @xmachines/play-solid-router            # SolidJS Router
+pnpm add @xmachines/play-tanstack-react-router   # TanStack Router (React)
+pnpm add @xmachines/play-tanstack-solid-router   # TanStack Router (SolidJS)
+pnpm add @xmachines/play-react-router            # React Router v7
+pnpm add @xmachines/play-vue-router              # Vue Router 4.x/5.x
+pnpm add @xmachines/play-solid-router            # SolidJS Router
 
 # connectRouter pattern (framework-agnostic)
-npm install @xmachines/play-dom-router              # Vanilla DOM (Browser History API)
-npm install @xmachines/play-sveltekit-router        # SvelteKit
-npm install @xmachines/play-svelte-spa-router       # Svelte SPA Router
+pnpm add @xmachines/play-dom-router              # Vanilla DOM (Browser History API)
+pnpm add @xmachines/play-sveltekit-router        # SvelteKit
+pnpm add @xmachines/play-svelte-spa-router       # Svelte SPA Router
 ```
 
 #### Step 3: Install a view renderer (pick one)
 
 ```bash
-npm install @xmachines/play-react    # React 18/19
-npm install @xmachines/play-vue      # Vue 3
-npm install @xmachines/play-solid    # SolidJS
-npm install @xmachines/play-svelte   # Svelte 5
-npm install @xmachines/play-dom      # Vanilla DOM
+pnpm add @xmachines/play-react    # React 18/19
+pnpm add @xmachines/play-vue      # Vue 3
+pnpm add @xmachines/play-solid    # SolidJS
+pnpm add @xmachines/play-svelte   # Svelte 5
+pnpm add @xmachines/play-dom      # Vanilla DOM
 ```
 
 ---
@@ -701,7 +694,7 @@ node --version
 | [`extractMachineRoutes`](../api/@xmachines/play-router/functions/extractMachineRoutes.md)             | Extracts a `RouteTree` from a state machine — used by framework-integrated router adapters                      |
 | [`createRouteMapFromTree`](../api/@xmachines/play-router/functions/createRouteMapFromTree.md)         | Builds a `RouteMap` from a `RouteTree` for bidirectional state ID ↔ URL lookups                                 |
 | [`connectRouter`](../api/@xmachines/play-dom-router/functions/connectRouter.md)                       | Connects a vanilla DOM router to an actor — returns a disconnect cleanup function                               |
-| [`PlayRouterProvider`](../api/@xmachines/play-tanstack-react-router/functions/PlayRouterProvider.md)  | React component that connects a `PlayerActor` to TanStack React Router                                          |
+| [`PlayRouterProvider`](../api/@xmachines/play-tanstack-react-router/variables/PlayRouterProvider.md)  | React component that connects a `PlayerActor` to TanStack React Router                                          |
 
 ---
 

package/guides/signals.md

@@ -158,8 +158,8 @@ Failing to clean up watchers causes memory leaks and stale callbacks firing afte
 
 ## See also
 
-- [Understanding the Actor Model](concepts-actor-model.md) — why the actor owns all signal writes
-- [Understanding State Machines](concepts-state-machines.md) — how state nodes produce the metadata that signals derive
+- [Understanding the Actor Model](actor-model.md) — why the actor owns all signal writes
+- [Understanding State Machines](state-machines.md) — how state nodes produce the metadata that signals derive
 - [Getting Started](getting-started.md) — hands-on walkthrough using signals to observe an actor
 - [@xmachines/play-signals](../api/@xmachines/play-signals/README.md) — API reference
 - [Play RFC](../rfc/play.md) — architectural specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.56",
+  "version": "1.0.0-beta.57",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -54,7 +54,7 @@
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
     "@types/node": "^25.6.0",
-    "@xmachines/shared": "1.0.0-beta.56",
+    "@xmachines/shared": "1.0.0-beta.57",
     "oxfmt": "^0.47.0",
     "oxlint": "^1.62.0",
     "typedoc": "^0.28.19",