@xmachines/docs 7.0.0 → 7.2.0

package/contributing/deployment.md

@@ -8,11 +8,11 @@ This document describes how `@xmachines/xmachines-js` packages are built, versio
 
 All `@xmachines/*` packages are published to the **public npm registry** (`registry.npmjs.org`). Every package uses `"publishConfig": { "access": "public" }` so scoped packages are accessible without an npm org subscription. See the [Published Packages](#published-packages) table for the full list.
 
-| Target          | Config File                                        | Purpose                                                |
-| --------------- | -------------------------------------------------- | ------------------------------------------------------ |
-| npm registry    | `scripts/publish-release.mjs`, on the tag pipeline | Publish all public packages                            |
-| GitLab Releases | `scripts/publish-release.mjs`, on the tag pipeline | Attach tarball artifacts to the GitLab release tag     |
-| GitLab CI       | `.gitlab-ci.yml`                                   | Trigger builds, tests, and releases on push / MR / tag |
+| Target          | Config File                                       | Purpose                                                |
+| --------------- | ------------------------------------------------- | ------------------------------------------------------ |
+| npm registry    | `publish-release`, on the tag pipeline of a train | Publish the public packages of the train               |
+| GitLab Releases | `publish-release`, on the tag pipeline of a train | Attach tarball artifacts to the GitLab release tag     |
+| GitLab CI       | `.gitlab-ci.yml`                                  | Trigger builds, tests, and releases on push / MR / tag |
 
 The root `package.json` is marked `"private": true` and is **never published** to npm.
 
@@ -20,32 +20,38 @@ The root `package.json` is marked `"private": true` and is **never published** t
 
 ## Published Packages
 
-The following packages are published on every release (derived from the workspace scan in `release.config.mjs` — every non-private package that is not a demo):
-
-| Package                                                                                           | Directory                             |
-| ------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| [`@xmachines/shared`](../api/@xmachines/shared/README.md)                                         | `packages/shared`                     |
-| [`@xmachines/play`](../api/@xmachines/play/README.md)                                             | `packages/play`                       |
-| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `packages/play-actor`                 |
-| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)                                   | `packages/play-atom`                  |
-| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | `packages/play-router`                |
-| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)                                     | `packages/play-dom`                   |
-| [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | `packages/play-dom-router`            |
-| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)                                 | `packages/play-react`                 |
-| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | `packages/play-react-router`          |
-| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)                                 | `packages/play-solid`                 |
-| [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | `packages/play-solid-router`          |
-| [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md)                               | `packages/play-svelte`                |
-| [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | `packages/play-sveltekit-router`      |
-| [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | `packages/play-svelte-spa-router`     |
-| [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | `packages/play-tanstack-react-router` |
-| [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | `packages/play-tanstack-solid-router` |
-| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)                                     | `packages/play-vue`                   |
-| [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | `packages/play-vue-router`            |
-| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | `packages/play-xstate`                |
-| [`@xmachines/docs`](../README.md)                                                                 | `packages/docs`                       |
-
-**Example demo packages** (under `packages/*/examples/demo`) are **not published** to npm (`"npmPublish": false`) but are still packed into release tarballs and attached as GitLab release assets for testing.
+The release is in **trains**, each released on its own: `core`, `play` and `docs`. A train publishes every package under its paths that is not private, at the version of the train's release (`release.config.mjs`, `trains`):
+
+| Package                                                                                           | Directory                             | Train  |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------- | ------ |
+| [`@xmachines/core`](../api/@xmachines/core/README.md)                                             | `packages/core`                       | `core` |
+| [`@xmachines/play`](../api/@xmachines/play/README.md)                                             | `packages/play`                       | `play` |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `packages/play-actor`                 | `play` |
+| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)                                   | `packages/play-atom`                  | `play` |
+| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)                                     | `packages/play-dom`                   | `play` |
+| [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | `packages/play-dom-router`            | `play` |
+| [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md)                             | `packages/play-pattern`               | `play` |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)                                 | `packages/play-react`                 | `play` |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | `packages/play-react-router`          | `play` |
+| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | `packages/play-router`                | `play` |
+| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)                                 | `packages/play-solid`                 | `play` |
+| [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | `packages/play-solid-router`          | `play` |
+| [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md)                               | `packages/play-svelte`                | `play` |
+| [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | `packages/play-svelte-spa-router`     | `play` |
+| [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | `packages/play-sveltekit-router`      | `play` |
+| [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | `packages/play-tanstack-react-router` | `play` |
+| [`@xmachines/play-tanstack-router`](../api/@xmachines/play-tanstack-router/README.md)             | `packages/play-tanstack-router`       | `play` |
+| [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | `packages/play-tanstack-solid-router` | `play` |
+| [`@xmachines/play-url`](../api/@xmachines/play-url/README.md)                                     | `packages/play-url`                   | `play` |
+| [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)                                   | `packages/play-view`                  | `play` |
+| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)                                     | `packages/play-vue`                   | `play` |
+| [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | `packages/play-vue-router`            | `play` |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | `packages/play-xstate`                | `play` |
+| [`@xmachines/docs`](../README.md)                                                                 | `packages/docs`                       | `docs` |
+
+Every package of `packages/play-*` that is not private is on the `play` train. [`@xmachines/shared`](../api/@xmachines/shared/README.md) is private: it holds the configs every package is built with, and no train publishes it.
+
+**Example demo packages** (under `packages/*/examples/*`, every one but the `shared` packages) are private and **not published** to npm, but the `play` train packs them beside its packages and attaches them to its GitLab release as assets for testing. It also packs the shared package of the demos, `packages/play-actor/examples/shared`, because each demo depends on it and no registry holds it.
 
 Each published package includes only the directories listed in its `files` field: `dist`, `README.md`, and `LICENSE` (or equivalent for packages without a compilation step).
 
@@ -57,13 +63,14 @@ Each published package includes only the directories listed in its `files` field
 
 Pipeline runs are triggered by `.gitlab-ci.yml` under the following conditions:
 
-| Trigger                                          | Pipeline runs                                      |
-| ------------------------------------------------ | -------------------------------------------------- |
-| Push to `main` / `rc` / `beta` / `alpha` / `pre` | Full pipeline; the release job waits to be started |
-| Merge request                                    | Full pipeline, no release job                      |
-| Web / API / trigger / parent pipeline            | Full pipeline                                      |
+| Trigger                                                   | Pipeline runs                                      |
+| --------------------------------------------------------- | -------------------------------------------------- |
+| Push to `main` / `next` / `rc` / `beta` / `alpha` / `pre` | Full pipeline; the release jobs wait to be started |
+| Merge request                                             | Full pipeline, no release job                      |
+| Web / API / trigger / parent pipeline                     | Full pipeline                                      |
+| A release tag, `<train>-v<version>`                       | `publish-release` alone, which publishes the train |
 
-No rule admits a tag pipeline, so pushing a tag runs nothing.
+No rule admits another tag, so pushing one runs nothing.
 
 The pipeline includes two reusable CI components, both pinned in `.gitlab-ci.yml` — which is the version to trust, rather than a number repeated here:
 
@@ -112,42 +119,30 @@ To run the same check on your machine, run `pnpm run docs` and then `pnpm run te
 
 ### Release Job Detail
 
-The `semantic-release` CI job is configured with:
-
-```yaml
-semantic-release:
-    id_tokens:
-        NPM_ID_TOKEN:
-            aud: "npm:registry.npmjs.org"
-    artifacts:
-        when: always
-        expire_in: 1 week
-        paths:
-            - dist/releases/*.tgz
-```
+The `semantic-release` job is the job of the `to-be-continuous/semantic-release` component, with its own rules: manual on every release branch, and a `resource_group` that runs one release at a time. One click releases every train: the job runs semantic-release once for each train that the pipeline's input `release-trains` names, all three by default, in the order of the trains of `release.config.mjs`: `core`, then `play`, then `docs`, whatever order they were ticked in. A train with no commit that releases it releases nothing, and the next one runs. A run that fails stops the job; retry it, and each train it released already has nothing left to release. To release some trains alone, tick them in the multi-select `release-trains` of **Run pipeline**, or set `RELEASE_TRAINS` as you start the job, as `docs`: the input is the default of the global variable `RELEASE_TRAINS`, which a CI/CD variable overrides, as a to-be-continuous component maps its inputs. A name of no train fails the job.
+
+The component turns `release.config.mjs` into `.releaserc.json`, of `RELEASE_TRAIN=docs`, whose run names every plugin of the others' runs too, and installs semantic-release and each plugin that the config names, globally. The config is therefore literals: it imports no plugin, and holds no top-level await. The job then removes `.releaserc.json`, so each run reads `release.config.mjs` of its own train.
 
-The job uses a GitLab OIDC id token (`NPM_ID_TOKEN`) scoped to `npm:registry.npmjs.org` rather than a static `NPM_TOKEN`.
+The job releases from the tip of its branch: a release of an earlier pipeline may have pushed a release commit since, and semantic-release releases nothing of a branch behind its remote. The job checks the tip out when every commit past its pipeline's commit is a release commit, and fails otherwise, as a branch that moved on needs the pipeline of its tip. Each run of a train then starts at the release commit of the run before it.
 
 The `semantic-release` command is called with `--no-ci` to allow it to run inside CI without triggering its own CI-environment mode.
 
 ### Release Smoke Test Job
 
-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):
+The `release-pack-smoke` job runs automatically on `main` and in a merge train, and manually on a merge request:
 
 ```bash
 pnpm run build
-node scripts/release-pack-smoke.mjs
+semantic-release-trains-smoke
 ```
 
-`scripts/release-pack-smoke.mjs`:
+`semantic-release-trains-smoke`, of `@wtf/semantic-release-trains-publish`, reads the trains of `release.config.mjs` and:
 
-1. Asks `scripts/lib/release-packages.mjs` which packages a release publishes. `publish-release.mjs` and `release.config.mjs` ask the same module, so the three cannot disagree.
-2. For each publishable package: runs `npm pack --json` in the package directory.
-3. Creates a temporary directory, runs `npm init -y`, and installs the local tarball with `--ignore-scripts`.
-4. Asserts the install succeeds — any missing files, broken exports, or pack-time errors surface here.
-5. Cleans up temp directories and tarballs after each check.
+1. Packs every package of every train, and each private package of its `pack` globs, as the release packs it: each `workspace:` range resolved, the `source` export condition stripped. The globs name the demos, and the shared package of the demos, which each demo depends on and which no registry holds.
+2. Checks each tarball: every entry of its `files` present, no `source` condition left, and no file a `forbid` glob names, as a typecheck build.
+3. Installs each tarball in a temporary project, with every other package that it packed in place of the registry's, and imports each of its exports.
 
-This smoke test runs **before** the actual publish so packaging problems are caught in CI rather than on npm.
+The publish plugin runs the same check on the tag, of the tarballs it is about to publish, before the first publish.
 
 ---
 
@@ -155,117 +150,111 @@ This smoke test runs **before** the actual publish so packaging problems are cau
 
 ### Branch Model
 
-Releases are driven by commit history on the release branches:
+Releases are driven by the commit history of each train on the release branches:
 
-| Branch  | Channel          | Tag format       | Behaviour                     |
-| ------- | ---------------- | ---------------- | ----------------------------- |
-| `main`  | stable (default) | `v1.2.3`         | Full production release       |
-| `rc`    | `rc`             | `v1.2.3-rc.N`    | Release candidate pre-release |
-| `beta`  | `beta`           | `v1.2.3-beta.N`  | Beta pre-release              |
-| `alpha` | `alpha`          | `v1.2.3-alpha.N` | Alpha pre-release             |
-| `pre`   | `pre`            | `v1.2.3-pre.N`   | Pre-release                   |
+| Branch  | Channel          | Tag format (of `play`) | Behaviour                     |
+| ------- | ---------------- | ---------------------- | ----------------------------- |
+| `main`  | stable (default) | `play-v1.2.3`          | Full production release       |
+| `next`  | `next`           | `play-v1.2.3-next.N`   | The line on XState 6          |
+| `rc`    | `rc`             | `play-v1.2.3-rc.N`     | Release candidate pre-release |
+| `beta`  | `beta`           | `play-v1.2.3-beta.N`   | Beta pre-release              |
+| `alpha` | `alpha`          | `play-v1.2.3-alpha.N`  | Alpha pre-release             |
+| `pre`   | `pre`            | `play-v1.2.3-pre.N`    | Pre-release                   |
 
 The channel becomes the npm dist-tag verbatim, which is why none of them contains a slash: npm reads a slash in a version selector as a GitHub shorthand, so such a tag cannot be installed.
 
-Tag format is `v${version}` (e.g., `v1.0.0-beta.46`).
+The tag format of a train is `<train>-v${version}`. Every train continued from 7.0.0, the last release of one version for everything: `core-v7.0.0`, `play-v7.0.0` and `docs-v7.0.0` name its commit.
 
-### Prepare Phase
+#### `next` after a release of `main`
 
-Before any package is published, semantic-release runs a sequence of `@semantic-release/exec` prepare steps defined in `release.config.mjs`:
+`main` stays on XState 5 and merges into `next`. **After each release on `main`, merge `main` into `next`**, by a merge request from `main` to `next`, kept unsquashed, that keeps `main` (its source branch is never deleted).
 
-```bash
-corepack enable
-pnpm install --frozen-lockfile
-node scripts/set-workspace-versions.mjs ${nextRelease.version}
-pnpm run build
-pnpm --filter @xmachines/docs run typedoc --gitRevision v${nextRelease.version}
-pnpm --filter @xmachines/docs run format
-git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md
-```
+A prerelease of `next` builds on the last release of its train that `next` reaches: from `play-v7.0.0`, a breaking change on `next` releases `play` `8.0.0-next.1`, then `8.0.0-next.2`, and so on. That claims 8.0.0 for the line of XState 6. When `main` takes that major first, by a breaking release of the same train, `play` 8.0.0 is something else, and `next` would go on with `8.0.0-next.N`, which sorts below 8.0.0 and does not hold it. The merge of `main` corrects it: `play-v8.0.0` is then reachable from `next`, the breaking change of `next` is not in it, and the next prerelease is `9.0.0-next.1`. A user of `@next` sees the major move from 8 to 9, as semver allows. The same holds for `core` and `docs`, each by its own version.
 
-Step by step:
+### Which Commits Release a Train
 
-1. **Enable corepack** — activates the pinned pnpm version.
-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 `vite build && tsc --build` to produce compiled `dist/` output — JavaScript then declarations — in all packages.
-5. **Generate API docs** — runs TypeDoc to regenerate `packages/docs/api/` and `packages/docs/examples/@xmachines/` at the release git revision. TypeDoc also rewrites the demo lists of `packages/docs/examples/README.md`.
-6. **Format docs** — runs `oxfmt` on the docs package to ensure consistent formatting.
-7. **Stage the generated docs** — `git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md`. The git plugin stages what `git ls-files -m -o` reports, and that never reports a DELETION. A page that TypeDoc removed, because an export was renamed or deleted, therefore stayed in git forever while the docs tarball packed from the working tree was correct. `git add -A` stages the removals, and the git plugin commits the index.
+A commit counts for a train when it changes a file under the train's paths, or one of its `shared` files. A breaking change of `core` therefore makes a major release of `core` alone.
 
-### Publish Phase
+- `core`: `packages/core`.
+- `play`: `packages/play` and `packages/play-*`, the demos too.
+- `docs`: `packages/docs`, and every file of `core` and of `play`: the reference documents them, so a release of either is a release of `docs`. Release `docs` last.
 
-semantic-release publishes nothing. It stops at the tag, and `scripts/publish-release.mjs` publishes from a pipeline that runs ON that tag:
+The files every package is built with count for every train: the root `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `tsconfig.json`, `vite.config.ts`, and `packages/shared`.
 
-```bash
-node scripts/publish-release.mjs
-```
+Release the trains in order: `core`, then `play`, then `docs`. `play` depends on `core`, and `dependencies: "fail"` of the config fails a run of `play` while `core` has commits that would release and are not released: its publish would pin `core`'s last release, without what those commits changed. The job runs them in that order; one of the input `play` alone fails so. `docs` depends on both by the `dependsOn` of its train, as its package depends on neither, and fails so too: its reference would show their old version badges until its next release.
 
-The tag pipeline is what makes the provenance attestation meaningful. npm records the commit of the pipeline in the attestation. On a tag pipeline that commit IS the commit that the tag names, and it is the commit whose manifests declare this version. A publish from the branch pipeline attests the PARENT of the release commit instead: a revision that the tag does not name, and whose manifests still carry the previous version.
+### Branch Phase
 
-The script pins the internal dependencies, strips the `source` export condition, packs every workspace package into `dist/releases/`, publishes each publishable tarball with `--provenance` under the dist-tag of the version, and verifies that every one reached the registry. It then creates the GitLab release with the tarballs attached, and it restores the working tree.
+The job of a train runs these plugins, in this order:
 
-The script is idempotent. It skips every package that the registry already serves at this version, so one retry of the job finishes a run that died partway — which is how the publish of 1.1.0 recovered from a credential that expired mid-run. Nothing to untag, nothing to force-push.
+1. **The analyzer and the notes generator**, each wrapped by an entry of `@wtf/semantic-release-trains` (`wrap`), which gives it the train's commits alone. Each entry of the trains plugin also checks the trains: no file on two of them, and the trains the train depends on released. `type!:` is a breaking change, by `parserOpts` at the root of the config.
+2. **`@semantic-release/changelog`** writes the train's changelog, the `CHANGELOG.md` of its first path: `packages/core/CHANGELOG.md`, `packages/play/CHANGELOG.md`, `packages/docs/CHANGELOG.md`. The root `CHANGELOG.md` holds the history up to 7.0.0.
+3. **`@wtf/semantic-release-replace`** writes the version into the badge of each README of the train, by the `badge` template at the root of the config: a RegExp of the badge of shields.io, its version written as `shields` escapes it. `tests/readme-badges.test.ts` holds the template to every badge of the READMEs.
+4. **Of `docs` alone**, the reference: `corepack enable`, `pnpm install --frozen-lockfile`, `pnpm run build`, TypeDoc at the revision `docs-v${nextRelease.version}`, and `oxfmt` of the docs package, each a `@semantic-release/exec` step. Then an entry of `@wtf/semantic-release-trains` of `generated: true` stages the trees TypeDoc writes, deletions too: the git plugin stages what `git ls-files -m -o` reports, which never reports a deletion, so a page of an export that was renamed or removed would stay in git for ever.
+5. **`@semantic-release/git`** commits the changelog, the READMEs of the train, and of `docs` the reference (`packages/docs/api/**`, `packages/docs/examples/@xmachines/**` and the demo lists of `packages/docs/examples/README.md`), as:
 
-### Post-Release Phase
+    ```
+    chore(release): <train> <version>
+    ```
 
-This phase runs on the branch, BEFORE the tag pipeline publishes.
+    The release notes are NOT interpolated into the message. `@semantic-release/git` runs `git commit -m <message>`, and the notes of a long release overflow the argument limit of the OS. The notes land in the changelog, which the same commit carries.
 
-1. **`@semantic-release/git`** commits updated files back to the repository:
-    - `CHANGELOG.md`
-    - `package.json`, `pnpm-lock.yaml` and `pnpm-workspace.yaml` (root)
-    - The `package.json` of every scanned package, and the `README.md` of every one — the release stamps the version badge of a README at the same moment as the manifest
-    - `packages/docs/api/**` (generated API documentation)
-    - `packages/docs/examples/@xmachines/**` (generated demo documentation)
-    - `packages/docs/examples/README.md` (TypeDoc rewrites its demo lists)
+    The message carries no `[skip ci]`. The release commit needs no pipeline of its own, but the TAG that points at it does: that pipeline is where the publish happens. A `workflow:` rule skips the branch pipeline of the commit instead.
 
-    The manifest list and the README list both come from the workspace scan, and not from a glob written by hand, so a package that a new `pnpm-workspace` pattern adds cannot be published while its manifest stays behind in git. A test asserts that every scanned package appears in both lists.
+6. semantic-release pushes the tag `<train>-v<version>`. It publishes nothing.
 
-    Commit message format:
+### Publish Phase
 
-    ```
-    chore(release): <version>
-    ```
+The tag's pipeline builds the tagged commit, and its `publish-release` job runs `semantic-release-trains-tag`, of `@wtf/semantic-release-trains`. It runs semantic-release's own config, plugins and branches for the tag, with its version and its channel, and the plugins of the tag's run of `release.config.mjs`:
 
-    The release notes are NOT interpolated into the message. `@semantic-release/git` runs `git commit -m <message>`, and the notes of the first stable release aggregate about 1600 commits — an `-m` value of several megabytes overflows the argument limit of the OS. The notes land in `CHANGELOG.md`, which the same commit carries.
+1. **The notes generator**, on the train, writes the notes again of the same commits.
+2. **`@wtf/semantic-release-trains-publish`** packs each package of the train into `dist/releases/`, the demos too, with each `workspace:` range resolved (a package of the same train to the release's version, one of another train to that train's last release) and the `source` export condition stripped; runs the smoke test of the tarballs; and publishes each package that is not private, in the order of their dependencies, under the dist-tag of the channel, with provenance. `NPM_DIST_TAG` overrides the dist-tag for a one-off.
+3. **`@semantic-release/gitlab`** creates the GitLab release of the tag, its notes those of the release, its assets every tarball of `dist/releases/` — after the publish succeeded, so a release entry never advertises a tarball that npm refused.
 
-    The message carries no `[skip ci]`. The release commit needs no pipeline of its own, but the TAG that points at it does: that pipeline is where the publish happens.
+The tag pipeline is what makes the provenance attestation meaningful. npm records the commit of the pipeline in the attestation. On a tag pipeline that commit IS the commit that the tag names. A publish from the branch pipeline attests the PARENT of the release commit instead: a revision that the tag does not name.
 
-2. **The git plugin pushes the commit and the tag.** semantic-release stops there. The GitLab release entry, with every `dist/releases/*.tgz` attached, is created later by `scripts/publish-release.mjs` on the tag pipeline — after the publish succeeded, so a release entry never advertises a tarball that npm refused.
+The job is idempotent. It skips every package that the registry already serves at this version, so one retry of the job finishes a run that died partway. Nothing to untag, nothing to force-push. A version below the one its dist-tag points at publishes nothing, so a retry of an older release's job moves no dist-tag back.
 
 ---
 
-## Version Synchronisation
+## Versions
 
-All packages in the monorepo share a **single version** at all times. This is enforced during release by `scripts/set-workspace-versions.mjs`, which:
+No version is written into git. Every `package.json` holds `0.0.0-development`, and each `@xmachines/*` dependency of the workspace is `workspace:*` within a train, `workspace:^` across trains. The tag is the version of a train, and the publish writes it into the manifests it packs, each `workspace:*` resolved to an exact version, so a package always depends on the exact version of a sibling of its train that was released with it. A dependency on a package of another train resolves to the range of that train's last release, by its tags, as `^7.0.0`: an exact pin would hold back each release of that train alone, a peer of it failing the install of the new version, and a dependency of it installing a second copy.
 
-- Sets `version` in every workspace `package.json` (including the root) to the new release version.
-- Rewrites `dependencies`, `devDependencies`, `peerDependencies`, and `optionalDependencies` ranges for any `@xmachines/*` workspace package to the exact new version (no `^` or `~` prefix — a strict pinned version is written).
+Why the versions stay out of git:
 
-This means packages always depend on the exact same version of sibling packages that was released together.
+- **`main` merges into `next`.** With versions in git, `main` holds 7.x and `next` holds 8.0.0-next.N in the same `package.json` files, and each merge of `main` conflicts in the version of every package that either line released since the last merge.
+- **The trains stay apart.** The release commit of a train touches its changelog and its READMEs alone: no two trains write the same file, and the release commit of one train never counts as a change of another.
+- **One source of truth.** The tag and npm hold the version, and nothing in git has to agree with them, so no release can stop between writing versions and tagging.
+
+What it costs:
+
+- A checkout says `0.0.0-development`: a package built from git, or packed by hand, carries no real version. Only the publish of the tag's pipeline writes one. No source reads its own version from its `package.json`; keep it so.
+- The README badges carry the version, by the release commit of the train, and the manifests do not.
+- `npm version`, and any tool that bumps a `package.json`, has nothing to do here.
 
 ---
 
 ## Credentials and Protected Variables
 
-| Variable                    | Source                                  | Purpose                                                                                                        |
-| --------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `NPM_ID_TOKEN`              | GitLab CI OIDC (auto-generated per job) | Authenticates `semantic-release` to npm registry via OIDC token exchange                                       |
-| `GL_TOKEN` / `GITLAB_TOKEN` | GitLab CI group variable (unprotected)  | Authenticates the git push back of semantic-release, and the GitLab release that `publish-release.mjs` creates |
-| `CI_JOB_TOKEN`              | GitLab CI built-in                      | Used by the `to-be-continuous` components for GitLab API calls                                                 |
+| Variable                    | Source                                  | Purpose                                                                                                    |
+| --------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `NPM_ID_TOKEN`              | GitLab CI OIDC (auto-generated per job) | Authenticates the publish of `publish-release` to npm registry via OIDC token exchange                     |
+| `GL_TOKEN` / `GITLAB_TOKEN` | GitLab CI group variable (protected)    | Authenticates the git push back of semantic-release, and the GitLab release that `publish-release` creates |
+| `CI_JOB_TOKEN`              | GitLab CI built-in                      | Used by the `to-be-continuous` components for GitLab API calls                                             |
 
 **No static npm token is committed to the repository.** The `NPM_ID_TOKEN` is a short-lived OIDC token generated for each CI job with audience `npm:registry.npmjs.org`.
 
 To publish packages, a maintainer must:
 
-1. Have push access to a release-eligible branch (`main`, `rc`, `beta`, `alpha`, `pre`). Only `main` is protected; see the branch model above for what changes if `GITLAB_TOKEN` is ever made a protected variable.
+1. Have push access to a release-eligible branch (`main`, `next`, `rc`, `beta`, `alpha`, `pre`). `GITLAB_TOKEN` is a protected variable, so each of these branches is protected, and a new release branch must be too. The tags of the trains (`core-v*`, `play-v*`, `docs-v*`) are protected, so the tag's pipeline gets the token for the GitLab release.
 2. Ensure the GitLab project CI/CD variables include the required tokens.
 
 ---
 
 ## Artifacts
 
-Release tarballs are stored as GitLab CI artifacts for **1 week** after each pipeline:
+Release tarballs are stored as artifacts of the `publish-release` job, with no expiry:
 
 ```
 dist/releases/*.tgz
@@ -273,7 +262,7 @@ dist/releases/*.tgz
 
 The same tarballs are attached to the GitLab Release entry as permanent downloadable assets. Tarballs are **not committed** to git (the `dist/` directory is gitignored).
 
-The post-release git commit **commits** the generated documentation (`packages/docs/api/` and `packages/docs/examples/@xmachines/`) to git. The same commit holds the demo lists that TypeDoc writes into the hand-written `packages/docs/examples/README.md`. It also holds `CHANGELOG.md`, which `@semantic-release/changelog` writes.
+The release commit of `docs` **commits** the generated documentation (`packages/docs/api/` and `packages/docs/examples/@xmachines/`) to git, with the demo lists that TypeDoc writes into the hand-written `packages/docs/examples/README.md`. The release commit of each train holds its changelog and its stamped READMEs.
 
 ---
 
@@ -295,7 +284,7 @@ There is no automated rollback mechanism. To revert a release:
     npm unpublish @xmachines/play@<bad-version>
     ```
 
-3. **Patch release** — push a `fix:` commit to `main` (or the relevant branch) to trigger a patch version release via semantic-release. This is the preferred long-term approach for production issues.
+3. **Patch release** — push a `fix:` commit to `main` (or the relevant branch) and release its train, a patch release by semantic-release. This is the preferred long-term approach for production issues.
 
 4. **GitLab Release** — delete or edit the GitLab Release entry via the GitLab UI or API to remove broken tarballs. This does not affect what is on npm.
 
@@ -368,50 +357,31 @@ Then, for EACH package:
 
 ## Recovering a Failed Release
 
-If the job dies partway (e.g. one package's trusted publisher isn't set up), some packages are published, the git tag is created, and the rest are missing. To finish the release:
-
-1. **Delete the release tag.** semantic-release creates the tag _before_ publishing, so a re-run while it exists is a no-op ([semantic-release#3178](https://github.com/semantic-release/semantic-release/issues/3178)):
-    ```bash
-    glab api --method DELETE "projects/xmachin-es%2Fxmachines-js/repository/tags/vX.Y.Z"
-    ```
-2. **Re-run the `semantic-release` job.**
-
-The config detects a staged-but-untagged version (a recovery re-run) and automatically demotes any package already on npm at that version to pack-only — re-packing it for the release assets but **not** re-publishing it — so the re-run publishes only what's missing, with no manual input. `SEMREL_SKIP_STEPS` (a regex matched against release step IDs) remains available as a manual override to force-skip specific steps.
+**A publish that failed** (e.g. one package's trusted publisher isn't set up) has pushed the tag, published some packages and left the rest missing. Fix the cause, then retry the `publish-release` job of the tag: every package npm already has is skipped, and the GitLab release is created once every package is published.
 
-> First fix the underlying cause before re-running — e.g. configure the missing trusted publisher — otherwise the same packages fail again.
+**A branch job that failed** before `@semantic-release/git` pushed the release commit is retried as it is. One that failed after, as of the push of the tag, cannot be: the retry runs behind the release commit, where semantic-release releases nothing. Push the missing tag by hand, at the release commit, with semantic-release's note of its channel (`refs/notes/semantic-release-<tag>`, `{"channels":[<channel>]}`, `null` of `main`'s) added to the tag's commit; its pipeline publishes it.
 
 ---
 
 ## Local Release Dry-Run (Manual)
 
-To preview what semantic-release would do without publishing:
+To preview what the release of a train would do, without a tag and without a publish:
 
 ```bash
-# Install dependencies first
-pnpm install --frozen-lockfile
-
-# Run semantic-release in dry-run mode
-pnpm exec semantic-release --dry-run --no-ci
+npm install --global semantic-release@25 @semantic-release/changelog @semantic-release/exec \
+  @semantic-release/git @semantic-release/gitlab @wtf/semantic-release-trains \
+  @wtf/semantic-release-replace @wtf/semantic-release-trains-publish
+RELEASE_TRAIN=play semantic-release --dry-run --no-ci
 ```
 
-To test package packaging locally (the same check run by `release-pack-smoke` in CI):
+To test the packaging locally (the same check run by `release-pack-smoke` in CI):
 
 ```bash
 pnpm run build
-node scripts/release-pack-smoke.mjs
-```
-
-This packs every publishable package, installs each tarball in a temporary project, and verifies the install succeeds.
-
-To manually version and pack a single package for local inspection:
-
-```bash
-# From the repo root
-pnpm --filter @xmachines/play run build
-pnpm --filter @xmachines/play pack
+semantic-release-trains-smoke
 ```
 
-**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. [Bootstrapping a New Package](#bootstrapping-a-new-package) is the ONE exception, and it publishes a version that holds no code.
+**Do not run `npm publish` manually.** All publishing must go through the release in CI to keep the changelogs, git tags, and npm versions in sync. [Bootstrapping a New Package](#bootstrapping-a-new-package) is the ONE exception, and it publishes a version that holds no code.
 
 ---
 
@@ -422,6 +392,6 @@ The project does not include application runtime monitoring (no Sentry, Datadog,
 Post-release health checks:
 
 - **npm package availability** — verify new versions appear on `https://www.npmjs.com/package/@xmachines/<pkg>` after the pipeline completes.
-- **GitLab pipeline status** — monitor the `semantic-release` job in the GitLab CI UI for the release commit.
+- **GitLab pipeline status** — monitor the `semantic-release` job of the train, then the `publish-release` job of its tag.
 - **GitLab Releases page** — confirm the release tag and tarball assets appear at `https://gitlab.com/xmachin-es/xmachines-js/-/releases`.
-- **`packages/docs/api/` commit** — confirm the post-release git commit updated API docs on the target branch.
+- **`packages/docs/api/` commit** — confirm the release commit of `docs` updated the API docs on the target branch.

package/contributing/development.md

@@ -199,7 +199,7 @@ React 18 and vue-router 4 are supported by intent — nothing known depends on 1
 
 [`@xmachines/play`](../api/@xmachines/play/README.md) holds `PlayError`, and the documentation sends a consumer to `err instanceof PlayError`. That check answers `false` for an error of the second copy. [`@xmachines/core`](../api/@xmachines/core/README.md) holds `BaseError`, the base of `PlayError`, and `err instanceof BaseError` fails in the same way.
 
-A dependency invites that second copy. `scripts/lib/workspace-deps.mjs` pins a `workspace:*` range to an EXACT version, so two packages of two releases name two versions, and an installer resolves both. A peer moves the choice to the consumer, who brings one copy. The `@xmachines/json-render-*` packages carry the same rule for the same reason.
+A dependency invites that second copy. The publish resolves a `workspace:*` range to an EXACT version, so two packages of two releases name two versions, and an installer resolves both. A peer moves the choice to the consumer, who brings one copy. The `@xmachines/json-render-*` packages carry the same rule for the same reason.
 
 Each of the three needs a `devDependency` beside the peer, because the workspace installs no peer. Without that entry a package resolves the specifier through the hoisting of another package, and it compiles until that other package stops declaring it.
 
@@ -542,7 +542,7 @@ Release branches are managed by the project maintainers:
 | `alpha` | Pre-release alpha channel |
 | `pre`   | Pre-release channel       |
 
-**Do not** manually version packages or create release branches — semantic-release owns the version, and a release is cut by starting its manual CI job.
+**Do not** manually version packages or create release branches — semantic-release owns the version of each train (`core`, `play`, `docs`), and a release is cut by starting the manual CI job of the train.
 
 ---
 
@@ -576,13 +576,13 @@ This project uses **Conventional Commits** — changelogs and version bumps are
 Breaking changes: append `!` after the type (`feat!:`) AND write a `BREAKING CHANGE:`
 footer. The two do different work, and neither one replaces the other:
 
-- The `!` decides the BUMP. `release.config.mjs` gives both semantic-release plugins a
-  `breakingHeaderPattern`, because the angular preset reads `!` not at all: without that
+- The `!` decides the BUMP. `release.config.mjs` gives every semantic-release plugin a
+  `breakingHeaderPattern`, at the root of the config, because the angular preset reads `!` not at all: without that
   pattern, `feat!: …` parses with no type, and a release made of nothing but such commits
   is no release.
 - The footer writes the NOTE. The changelog lists a breaking change from the footer alone,
   so a `!` commit with no footer bumps the major and tells a reader nothing about what
-  broke. Seven commits shipped that way once, and none of them appears in `CHANGELOG.md`.
+  broke. Seven commits shipped that way once, and none of them appears in the changelog.
 
 Write the footer as one paragraph that names the old form and the new one:
 

package/contributing/testing.md

@@ -84,7 +84,7 @@ The two scripts set `XM_TEST_TARGET=dist`, and the config helpers of [`@xmachine
 - **A specifier.** The alias map drops each published package. [`@xmachines/play-xstate/routing`](../api/@xmachines/play-xstate/README.md) then resolves through the `exports` map of the package to `dist/with-routing.js`. The `source` condition is not set either, so the resolution is the one that a consumer gets.
 - **A path into `src/`.** A test imports the module under test by path, as `../src/define-player.js`, and that import reaches no exports map. The `xmBuildOutput` plugin moves it to `dist/define-player.js`, which is the file that the package entry imports. The test and the package then share ONE module, and a `vi.mock` of the `src/` path replaces the module of the build. The build keeps the module structure, so each source file has one counterpart.
 
-The private packages — the demos and the `examples/shared` fixtures — reach no consumer, and the build does not compile them for one. Both runs read their source, and that source imports the packages from `dist/`.
+The private packages — the demos and the `examples/shared` fixtures — are never published. Both runs read their source, and that source imports the packages from `dist/`. The release packs the demos as assets, with the shared package of the demos. The build therefore compiles each packed package whose exports map names `dist/`, from its `vite.lib.config.ts`: the shared package of the demos, and the DOM, React and Solid galleries, which the router demos import.
 
 The plugin fails an import when the build output holds no counterpart. The import then names both files. A fallback to the source would hide the defect that the dist run exists to find. The plugin also fails the run when anything loads a `src/` file of a published package by another route.
 
@@ -587,18 +587,20 @@ Tests run in GitLab CI using the `to-be-continuous/node` pipeline component (ver
 
 ```bash
 pnpm run test:dist --coverage           # test:dist
-pnpm run test:browser:dist --coverage   # test:browser:dist, on the Playwright image
+pnpm run test:browser:dist --coverage --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL   # test:browser:dist, on the Playwright image
 pnpm run test:docs:examples             # test:docs:examples
 ```
 
 CI runs the suites on the build output alone. `test:dist` and `test:browser:dist` take `dist/` from `node-build` through `needs:`, so they test the build that the pipeline produced. They block: a failure is a defect of the tarball that a consumer installs, and it holds the release, because `semantic-release` runs in a later stage. `test:docs:examples` reads the source, so it waits for no build.
 
+`test:browser:dist` runs in four shards of a parallel job. One process that runs every browser project holds a Vite server for each one, and the job ran out of memory. Each shard runs a quarter of the test files. To run one shard locally, give `--shard=1/4` to `pnpm run test:browser:dist`.
+
 The jobs pass no reporter flag. `vitest.config.ts` and `vitest.browser.config.ts` own the reporters, the JUnit file and the coverage directory, and they read `COVERAGE_REPORTS_DIR` — which the dist jobs set to `reports/`. A new package therefore needs no CI change. `test:docs:examples` shares the root config with `test:dist`, so it names its own JUnit file on the command line.
 
 **Artifacts:**
 
 - `test:dist`: JUnit at `reports/test-results.xml`, and Cobertura at `reports/cobertura-coverage.xml`. GitLab reads the coverage percentage from the `All files` line.
-- `test:browser:dist`: JUnit at `reports/browser-results.xml`, and its own Cobertura report. GitLab merges the two Cobertura reports.
+- `test:browser:dist`: in each shard, JUnit at `reports/browser-results.xml`, and its own Cobertura report. GitLab merges the Cobertura reports.
 - `test:docs:examples`: JUnit at `reports/docs-examples.xml`.
 
 Coverage and test results are always uploaded (`when: always`) so failures are visible even when the job itself fails.