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

package/api/@xmachines/play-xstate/type-aliases/RouteStateNode.md

@@ -6,7 +6,7 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-xstate/src/routing/format-play-route-transitions.ts#L13)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/play-xstate/src/routing/format-play-route-transitions.ts#L13)
 
 Minimal structural shape of a single XState state node as read by
 `formatPlayRouteTransitions` when crawling the machine config.
@@ -29,7 +29,7 @@ the index signature.
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
 
 Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` target in `play.route` events.
 
@@ -41,7 +41,7 @@ Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` targ
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-xstate/src/routing/format-play-route-transitions.ts#L17)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/play-xstate/src/routing/format-play-route-transitions.ts#L17)
 
 State metadata — `meta.route` marks the state as routable.
 
@@ -61,6 +61,6 @@ URL path template (e.g. `"/profile/:username"`, `"/settings/:section?"`).
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-xstate/src/routing/format-play-route-transitions.ts#L22)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/play-xstate/src/routing/format-play-route-transitions.ts#L22)
 
 Nested child states, recursively crawled for additional route declarations.

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

@@ -163,10 +163,10 @@ The base `config/tsconfig.json` configures:
 
 ```bash
 # Run tests for this package
-npm test -w packages/shared
+pnpm --filter @xmachines/shared test
 
 # Or from the package directory
-npm test
+pnpm test
 ```
 
 ## License

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

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/shared/config/vite-aliases.ts#L221)
+Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/shared/config/vite-aliases.ts#L221)
 
 Vite resolve.alias entries for all @xmachines/\* workspace packages.
 

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

@@ -6,7 +6,7 @@
 function xmCacheDir(importMetaUrl, name): string;
 ```
 
-Defined in: [vite-aliases.ts:330](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/shared/config/vite-aliases.ts#L330)
+Defined in: [vite-aliases.ts:330](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/shared/config/vite-aliases.ts#L330)
 
 Returns the shared Vite `cacheDir` for this workspace package.
 

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

@@ -6,7 +6,7 @@
 function xmOptimizeDeps(extra?): DepOptimizationOptions;
 ```
 
-Defined in: [vite-aliases.ts:286](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/shared/config/vite-aliases.ts#L286)
+Defined in: [vite-aliases.ts:286](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/shared/config/vite-aliases.ts#L286)
 
 Returns the standard Vite `optimizeDeps` config for browser test projects.
 
@@ -16,8 +16,8 @@ discovering them lazily at runtime. Without this, adding or changing dependencie
 "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. `["@json-render/vue/schema"]`).
-The base set (`@json-render/core`) is always included.
+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
 

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

@@ -6,13 +6,13 @@
 function xmResolve(importMetaUrl, extra?): ResolveOptions & object;
 ```
 
-Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/shared/config/vite-aliases.ts#L258)
+Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/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 `npm run build`.
+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

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

@@ -6,7 +6,7 @@
 function xmSvelteRunes(): object;
 ```
 
-Defined in: [vite-aliases.ts:309](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/shared/config/vite-aliases.ts#L309)
+Defined in: [vite-aliases.ts:309](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/shared/config/vite-aliases.ts#L309)
 
 Svelte plugin options that enforce runes mode for workspace sources only.
 
@@ -30,4 +30,4 @@ export default defineConfig({ plugins: [svelte(xmSvelteRunes())] });
 
 | Name                      | Type                                                    | Defined in                                                                                                                          |
 | ------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:310](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/shared/config/vite-aliases.ts#L310) |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:310](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/shared/config/vite-aliases.ts#L310) |

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

@@ -6,7 +6,7 @@
 function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
 ```
 
-Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/shared/config/vitest.ts#L167)
+Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/shared/config/vitest.ts#L167)
 
 Create a Vitest browser-mode config with XMachines workspace defaults.
 

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

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
 
-Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/shared/config/vitest.ts#L64)
+Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/shared/config/vitest.ts#L64)
 
 Create a Vitest config with XMachines workspace defaults.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: XmBrowserConfigOptions
 
-Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/shared/config/vitest.ts#L117)
+Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.57/packages/shared/config/vitest.ts#L117)
 
 Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
 Vitest config overrides.
@@ -11,6 +11,6 @@ Vitest config overrides.
 
 | 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-beta.55/packages/shared/config/vitest.ts#L125) |
-| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@json-render/vue", "@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-beta.55/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-beta.55/packages/shared/config/vitest.ts#L138) |
+| <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-beta.57/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-beta.57/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-beta.57/packages/shared/config/vitest.ts#L138) |

package/api/llms.txt

@@ -17,7 +17,7 @@
 
 ## 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 `@json-render/core` and the framework rendering packages.
+- `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.
@@ -57,7 +57,7 @@
 ```javascript
 import { definePlayer } from '@xmachines/play-xstate';
 import { createRouteMapFromTree, extractMachineRoutes, extractRouteParams } from '@xmachines/play-router';
-import { defineRegistry } from '@json-render/react';
+import { defineRegistry } from '@xmachines/json-render-react';
 import { PlayRenderer } from '@xmachines/play-react';
 
 const createPlayer = definePlayer({ machine });

package/contributing/architecture.md

@@ -107,7 +107,7 @@ flowchart TD
     E["validateAndCacheView(snapshot)\nactor.currentView Signal.State updated"]
     F["Framework signal watcher fires\nmicrotask"]
     G["ActorProvider reads actor.currentView.get()"]
-    H["PlayRenderer renders via @json-render/* Renderer"]
+    H["PlayRenderer renders via @xmachines/json-render-* Renderer"]
 
     A --> B --> C --> D --> E --> F --> G --> H
 ```
@@ -225,7 +225,7 @@ Optional capability interface. Exposes `currentView: Signal.State<PlaySpec | nul
 
 ### [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)
 
-Extends `@json-render/core` `Spec` with `readonly contextProps?: readonly string[]` — an explicit allowlist of machine context fields that `deriveCurrentView` merges into element props. Only fields named here are ever exposed to components. `typedSpec<TContext>()` provides compile-time validation of `contextProps` entries against the machine's context type.
+Extends `@xmachines/json-render-core` `Spec` with `readonly contextProps?: readonly string[]` — an explicit allowlist of machine context fields that `deriveCurrentView` merges into element props. Only fields named here are ever exposed to components. `typedSpec<TContext>()` provides compile-time validation of `contextProps` entries against the machine's context type.
 
 ### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
 
@@ -291,12 +291,12 @@ Crawls machine state configs looking for states with `meta.route` and auto-gener
 
 All five view renderer packages follow an identical structural pattern:
 
-| Component        | Role                                                                                   |
-| ---------------- | -------------------------------------------------------------------------------------- |
-| `ActorProvider`  | Subscribes to `actor.currentView` signal; owns signal lifecycle; provides view context |
-| `PlayUIProvider` | Convenience wrapper combining `ActorProvider` + framework's `JSONUIProvider`           |
-| `PlayRenderer`   | Zero-prop leaf component; reads from context; delegates to `@json-render/*` `Renderer` |
-| `useActor()`     | Hook/composable for accessing the raw actor in consuming components                    |
+| Component        | Role                                                                                             |
+| ---------------- | ------------------------------------------------------------------------------------------------ |
+| `ActorProvider`  | Subscribes to `actor.currentView` signal; owns signal lifecycle; provides view context           |
+| `PlayUIProvider` | Convenience wrapper combining `ActorProvider` + framework's `JSONUIProvider`                     |
+| `PlayRenderer`   | Zero-prop leaf component; reads from context; delegates to `@xmachines/json-render-*` `Renderer` |
+| `useActor()`     | Hook/composable for accessing the raw actor in consuming components                              |
 
 **Framework-specific signal bridging:**
 
@@ -445,7 +445,7 @@ With `declarationMap: true` in the base tsconfig (from `@xmachines/shared/tsconf
 | Actor logic (`play-xstate`)                     | Protocol layer                                      | View renderers, router adapters  |
 | Router infrastructure (`play-router`)           | Protocol layer, `@statelyai/graph`                  | View renderers                   |
 | Router adapters (`play-*-router`)               | `play-router`, protocol layer, framework router lib | Other view renderers             |
-| View renderers (`play-*`)                       | Protocol layer, `@json-render/*`                    | Router adapters                  |
+| View renderers (`play-*`)                       | Protocol layer, `@xmachines/json-render-*`          | Router adapters                  |
 
 ## Error Handling
 

package/contributing/configuration.md

@@ -118,13 +118,13 @@ All packages extend this base. Key compiler settings:
 
 **Location:** `packages/shared/config/tsconfig.test.json`
 
-Test builds add `noEmit: true`, `allowImportingTsExtensions: true`, and `vitest/globals` types. Used by `npm run test:build` to type-check test files without emitting output.
+Test builds add `noEmit: true`, `allowImportingTsExtensions: true`, and `vitest/globals` types. Used by `pnpm run test:build` to type-check test files without emitting output.
 
 ### Linting — `oxlint.config.ts` (root)
 
 **Location:** `/oxlint.config.ts`
 **Tool:** [oxlint](https://oxc.rs/docs/guide/usage/linter) `^1.62.0`
-**Run:** `npm run lint` / `npm run lint:fix`
+**Run:** `pnpm run lint` / `pnpm run lint:fix`
 
 The root config extends the shared base (`@xmachines/shared/oxlint`) and adds workspace-level ignore patterns:
 
@@ -175,7 +175,7 @@ export default defineConfig({
 
 **Location:** `/oxfmt.config.ts`
 **Tool:** [oxfmt](https://oxc.rs/docs/guide/usage/formatter) `^0.47.0`
-**Run:** `npm run format` / `npm run format:check`
+**Run:** `pnpm run format` / `pnpm run format:check`
 
 The root config extends the shared base and adds workspace-level ignore patterns:
 
@@ -232,7 +232,7 @@ export default defineConfig({
 
 **Location:** `/vitest.config.ts`
 **Tool:** [Vitest](https://vitest.dev/) `^4.1.5`
-**Run:** `npm test` / `npm run test:coverage`
+**Run:** `pnpm test` / `pnpm run test:coverage`
 
 Root Vitest config is a **workspace coordinator** that lists all per-package configs under `test.projects`. It sets conservative monorepo-wide defaults:
 
@@ -258,7 +258,7 @@ Root Vitest config is a **workspace coordinator** that lists all per-package con
 Coverage provider: `v8`. Individual packages may declare higher per-package thresholds in their own `vitest.config.ts`.
 
 **Browser test config:** `/vitest.browser.config.ts`
-Run with `npm run test:browser`. Uses Playwright Chromium via Vitest browser mode. `testTimeout` is `20000` ms; `maxWorkers` is `2` (default; demo integration projects override with `pool: "threads"` + `maxWorkers: 2`).
+Run with `pnpm run test:browser`. Uses Playwright Chromium via Vitest browser mode. `testTimeout` is `20000` ms; `maxWorkers` is `2` (default; demo integration projects override with `pool: "threads"` + `maxWorkers: 2`).
 
 ### Per-Package Vitest Config — `@xmachines/shared/vitest`
 
@@ -292,7 +292,7 @@ export default defineXmVitestConfig(import.meta.url, {
 
 Provides two helpers used in all `vitest.config.ts` and `vite.config.ts` files:
 
-- **`xmAliases(import.meta.url)`** — returns a `Record<string, string>` mapping every `@xmachines/*` package to its TypeScript source entry. Enables tests and dev servers to run without a prior `npm run build`.
+- **`xmAliases(import.meta.url)`** — returns a `Record<string, string>` mapping every `@xmachines/*` package to its TypeScript source entry. Enables tests and dev servers to run without a prior `pnpm run build`.
 - **`xmResolve(import.meta.url)`** — returns a full Vite `resolve` config with `xmAliases` plus `preserveSymlinks: true` and `conditions: ["source"]`.
 - **`xmCacheDir(import.meta.url, name)`** — returns a shared Vite cache path under `node_modules/.vite/<name>` to prevent redundant dep optimizer runs across projects.
 - **`xmOptimizeDeps(extra?)`** — returns a standard `optimizeDeps.include` list; pass framework-specific extras to pre-bundle them at startup.
@@ -320,12 +320,12 @@ Defines the release branches and plugin chain used by the GitLab CI semantic-rel
 2. `@semantic-release/release-notes-generator` — builds release notes
 3. `@semantic-release/changelog` — writes `CHANGELOG.md`
 4. `@semantic-release/exec` steps (in order):
-    - `install` — `npm ci`
-    - `apply-patches` — `npm run apply-patches`
+    - `corepack` — `corepack enable`
+    - `install` — `pnpm install --frozen-lockfile`
     - `set-workspace-versions` — updates all `package.json` files to the new version
-    - `build` — `npm run build`
-    - `typedoc` — `npm run typedoc -w @xmachines/docs`
-    - `format-docs` — `npm run format -w @xmachines/docs`
+    - `build` — `pnpm run build`
+    - `typedoc` — `pnpm --filter @xmachines/docs run typedoc`
+    - `format-docs` — `pnpm --filter @xmachines/docs run format`
 5. `@semantic-release/npm` — one entry per published package (20 packages) + pack-only for demo apps
 6. `@semantic-release/git` — commits `CHANGELOG.md`, updated `package.json` files, and generated API docs
 7. `@semantic-release/gitlab` — creates a GitLab release with tarball assets
@@ -365,4 +365,4 @@ When adding a new package, update these configuration files:
 4. **`/vitest.browser.config.ts`** (if the package has browser tests) — add the browser config path to `test.projects`.
 5. **`/release.config.mjs`** — add an entry to `NPM_PACKAGES` array with the package's `pkgRoot`.
 
-See [AGENTS.md](../../../AGENTS.md) for the full new-package checklist.
+See [AGENTS.md](https://gitlab.com/xmachin-es/xmachines-js/-/blob/main/AGENTS.md) for the full new-package checklist.

package/contributing/deployment.md

@@ -73,8 +73,8 @@ The pipeline includes two reusable CI components:
 The `node-build` job runs with:
 
 ```bash
-npm run build           # tsc --build (TypeScript composite build)
-npm test:coverage       # vitest run --coverage (with JUnit + Cobertura reporters)
+pnpm run build           # tsc --build (TypeScript composite build)
+pnpm run test:coverage   # vitest run --coverage (with JUnit + Cobertura reporters)
 ```
 
 Coverage is extracted from the `node-build` job via the regex:
@@ -110,7 +110,7 @@ The `semantic-release` command is called with `--no-ci` to allow it to run insid
 The `release-pack-smoke` job is defined in `.gitlab-ci.yml` and runs on the same trigger rules as other CI jobs (automatically on `main` pushes and tags, manually on MRs):
 
 ```bash
-npm run build
+pnpm run build
 node scripts/release-pack-smoke.mjs
 ```
 
@@ -156,7 +156,7 @@ pnpm --filter @xmachines/docs run format
 Step by step:
 
 1. **Enable corepack** — activates the pinned pnpm version.
-2. **Install** — `pnpm install --frozen-lockfile` installs dependencies and applies the `patches/` (pnpm `patchedDependencies`) during install, so no separate apply-patches step is needed.
+2. **Install** — `pnpm install --frozen-lockfile` installs the exact dependency versions recorded in the lockfile.
 3. **Sync versions** — `scripts/set-workspace-versions.mjs` sets the same release version across every `package.json` in the workspace (root + all packages), including cross-package workspace dependency ranges.
 4. **Build** — runs `tsc --build` to produce compiled `dist/` output in all packages.
 5. **Generate API docs** — runs TypeDoc to regenerate `packages/docs/api/` at the release git revision.
@@ -275,16 +275,16 @@ To preview what semantic-release would do without publishing:
 
 ```bash
 # Install dependencies first
-npm ci
+pnpm install --frozen-lockfile
 
 # Run semantic-release in dry-run mode
-npx semantic-release --dry-run --no-ci
+pnpm exec semantic-release --dry-run --no-ci
 ```
 
 To test package packaging locally (the same check run by `release-pack-smoke` in CI):
 
 ```bash
-npm run build
+pnpm run build
 node scripts/release-pack-smoke.mjs
 ```
 
@@ -294,8 +294,8 @@ To manually version and pack a single package for local inspection:
 
 ```bash
 # From the repo root
-npm run build -w packages/play
-npm pack --workspaces --workspace=packages/play
+pnpm --filter @xmachines/play run build
+pnpm --filter @xmachines/play pack
 ```
 
 **Do not run `npm publish` manually.** All publishing must go through semantic-release in CI to keep `CHANGELOG.md`, git tags, and npm versions in sync.

package/contributing/development.md

@@ -21,25 +21,25 @@ This guide covers everything you need to set up a local development environment,
 ### Prerequisites
 
 - **Node.js** `>= 22.0.0`
-- **npm** (bundled with Node.js — the project uses npm workspaces)
+- **pnpm** via corepack (`corepack enable`; version pinned by the `packageManager` field — the project uses pnpm workspaces)
 - **Git**
 
-No global tool installs are required beyond Node.js. All build, lint, and format tooling is installed locally via `npm ci`.
+No global tool installs are required beyond Node.js. All build, lint, and format tooling is installed locally via `pnpm install --frozen-lockfile`.
 
 ### Clone and Install
 
 ```bash
 git clone git@gitlab.com:xmachin-es/xmachines-js.git
 cd xmachines-js
-npm ci
+pnpm install --frozen-lockfile
 ```
 
-> **Use `npm ci`, not `npm install`.** `npm ci` installs exact locked versions and triggers the `postinstall` hook that runs `patch-package` to apply any repository patches.
+> **Use `pnpm install --frozen-lockfile` (not `pnpm install`)** — it installs the exact versions from the lockfile.
 
 ### Build
 
 ```bash
-npm run build
+pnpm run build
 ```
 
 The root-level `tsc --build` command uses TypeScript project references to build all packages in the correct dependency order automatically. You never need to sequence builds manually.
@@ -47,7 +47,7 @@ The root-level `tsc --build` command uses TypeScript project references to build
 To build a single package (and its upstream dependencies):
 
 ```bash
-npm run build -w @xmachines/<package-name>
+pnpm --filter @xmachines/<package-name> run build
 ```
 
 ### Dev Container (Optional)
@@ -55,7 +55,7 @@ npm run build -w @xmachines/<package-name>
 A fully configured dev container is provided at `.devcontainer/`. It includes Docker-outside-of-Docker, Claude Code, and OpenCode.
 
 ```bash
-npm run devcontainer:up
+pnpm run devcontainer:up
 ```
 
 Or open the repository in VS Code and choose **Reopen in Container** when prompted.
@@ -63,9 +63,9 @@ Or open the repository in VS Code and choose **Reopen in Container** when prompt
 ### Verify Your Setup
 
 ```bash
-npm test              # Run the full test suite
-npm run lint          # Check for lint errors
-npm run format:check  # Check formatting without modifying files
+pnpm test              # Run the full test suite
+pnpm run lint          # Check for lint errors
+pnpm run format:check  # Check formatting without modifying files
 ```
 
 All three should pass without errors on a freshly cloned repository.
@@ -74,7 +74,7 @@ All three should pass without errors on a freshly cloned repository.
 
 ## Monorepo Structure
 
-The repository is organized as an **npm workspaces** monorepo with all packages under `packages/`:
+The repository is organized as a **pnpm workspaces** monorepo with all packages under `packages/`:
 
 ```
 packages/
@@ -123,23 +123,23 @@ packages/<name>/
 
 All commands are run from the **repository root** unless otherwise noted.
 
-| Command                             | Description                                                           |
-| ----------------------------------- | --------------------------------------------------------------------- |
-| `npm run build`                     | TypeScript composite build — all packages in dependency order         |
-| `npm run build -w @xmachines/<pkg>` | Build a single package (and its deps)                                 |
-| `npm run clean`                     | Remove coverage, Vite caches, and all `dist/` directories in packages |
-| `npm test`                          | Run all unit/integration tests once                                   |
-| `npm run test:watch`                | Re-run tests on file changes (interactive)                            |
-| `npm run test:browser`              | Run Playwright browser tests                                          |
-| `npm run test:coverage`             | Run tests with V8 coverage reporting                                  |
-| `npm run coverage:report`           | Run tests and write an HTML coverage report                           |
-| `npm run coverage:summary`          | Run tests and write a JSON summary report                             |
-| `npm run test:build`                | Type-check test files without running them (`tsconfig.test.json`)     |
-| `npm run lint`                      | Lint all packages with oxlint                                         |
-| `npm run lint:fix`                  | Auto-fix lint issues                                                  |
-| `npm run format`                    | Format all files with oxfmt                                           |
-| `npm run format:check`              | Check formatting (CI mode — no writes)                                |
-| `npm run docs`                      | Build packages, generate TypeDoc API docs, then format                |
+| Command                                    | Description                                                           |
+| ------------------------------------------ | --------------------------------------------------------------------- |
+| `pnpm run build`                           | TypeScript composite build — all packages in dependency order         |
+| `pnpm --filter @xmachines/<pkg> run build` | Build a single package (and its deps)                                 |
+| `pnpm run clean`                           | Remove coverage, Vite caches, and all `dist/` directories in packages |
+| `pnpm test`                                | Run all unit/integration tests once                                   |
+| `pnpm run test:watch`                      | Re-run tests on file changes (interactive)                            |
+| `pnpm run test:browser`                    | Run Playwright browser tests                                          |
+| `pnpm run test:coverage`                   | Run tests with V8 coverage reporting                                  |
+| `pnpm run coverage:report`                 | Run tests and write an HTML coverage report                           |
+| `pnpm run coverage:summary`                | Run tests and write a JSON summary report                             |
+| `pnpm run test:build`                      | Type-check test files without running them (`tsconfig.test.json`)     |
+| `pnpm run lint`                            | Lint all packages with oxlint                                         |
+| `pnpm run lint:fix`                        | Auto-fix lint issues                                                  |
+| `pnpm run format`                          | Format all files with oxfmt                                           |
+| `pnpm run format:check`                    | Check formatting (CI mode — no writes)                                |
+| `pnpm run docs`                            | Build packages, generate TypeDoc API docs, then format                |
 
 ---
 
@@ -280,8 +280,8 @@ All style rules are **mandatory** — CI enforces them on every merge request.
 oxfmt (Biome-based) is configured via `oxfmt.config.ts` at the root (extends `@xmachines/shared/oxfmt`).
 
 ```bash
-npm run format          # Format all files
-npm run format:check    # Check without writing (CI mode)
+pnpm run format          # Format all files
+pnpm run format:check    # Check without writing (CI mode)
 ```
 
 Key settings (from `packages/shared/config/oxfmt.config.ts`):
@@ -300,8 +300,8 @@ Key settings (from `packages/shared/config/oxfmt.config.ts`):
 oxlint is configured via `oxlint.config.ts` at the root (extends `@xmachines/shared/oxlint`).
 
 ```bash
-npm run lint        # Lint all packages
-npm run lint:fix    # Auto-fix lint issues
+pnpm run lint        # Lint all packages
+pnpm run lint:fix    # Auto-fix lint issues
 ```
 
 Active plugins: `typescript`, `unicorn`, `import`. Key rules:
@@ -425,23 +425,23 @@ feat(play-react): add PlayRenderer suspense boundary
 2. **Run the full check suite** from the repo root:
 
     ```bash
-    npm run build
-    npm test
-    npm run lint
-    npm run format:check
+    pnpm run build
+    pnpm test
+    pnpm run lint
+    pnpm run format:check
     ```
 
 3. **Write tests** — new code must meet coverage thresholds (80% lines/functions/statements and 75% branches at the monorepo level; core packages enforce higher per-package thresholds)
 4. **Add JSDoc** — all new public exports require JSDoc with `@param`, `@returns`, and `@see` RFC links
-5. **Never edit `packages/docs/api/`** — API docs are auto-generated; edit source JSDoc and regenerate with `npm run docs`
+5. **Never edit `packages/docs/api/`** — API docs are auto-generated; edit source JSDoc and regenerate with `pnpm run docs`
 
 ### Merge Request Checklist
 
 - [ ] Branch is up to date with `main`
-- [ ] All tests pass (`npm test`)
-- [ ] Lint passes (`npm run lint`)
-- [ ] Formatting is correct (`npm run format:check`)
-- [ ] Build succeeds (`npm run build`)
+- [ ] All tests pass (`pnpm test`)
+- [ ] Lint passes (`pnpm run lint`)
+- [ ] Formatting is correct (`pnpm run format:check`)
+- [ ] Build succeeds (`pnpm run build`)
 - [ ] New code has tests at or above coverage thresholds
 - [ ] All new public exports have JSDoc
 - [ ] Conventional commit format used on all commits
@@ -453,10 +453,10 @@ The GitLab CI pipeline runs automatically on merge requests, pushes to `main`, a
 
 | Job                | Command                               | Artifacts                              |
 | ------------------ | ------------------------------------- | -------------------------------------- |
-| Build              | `npm run build`                       | —                                      |
+| Build              | `pnpm run build`                      | —                                      |
 | Test with coverage | `vitest run --coverage`               | JUnit XML, Cobertura coverage report   |
 | Lint               | `oxlint .`                            | —                                      |
-| Audit              | `npm audit --audit-level=high`        | —                                      |
+| Audit              | `pnpm audit --audit-level=high`       | —                                      |
 | Semantic release   | (automated on `main`/`beta`/`pre/rc`) | CHANGELOG, npm publish, GitLab release |
 
 ---