# Planned Design — npm `@next` prerelease lane

Status: **PLANNED / not yet built**

## Current state

`tools/install.sh --next` provides a prerelease integration lane by building the Mosaic CLI and gateway from source at the permanent `next` branch. This is correct for validating integration-branch source, but it is slower than the stable npm lane because it downloads the archive, installs workspace dependencies, builds packages, packs local tarballs, and installs those tarballs globally.

## Medium-term target

Publish every accepted `next` integration build to the npm registry under the `@next` dist-tag, for example:

```text
@mosaicstack/mosaic@0.0.49-next.1
@mosaicstack/mosaic@0.0.49-next.2
```

Then move `tools/install.sh --next` from source-build behavior to a fast npm install:

```bash
npm install -g @mosaicstack/mosaic@next
```

The framework archive should still resolve from the matching `next` source/ref until framework packaging has a registry-backed equivalent.

## Pipeline shape

1. Trigger on successful CI for `next`.
2. Compute the next prerelease version from the upcoming stable version plus a monotonic prerelease counter (`0.0.49-next.N`).
3. Build and pack publishable packages in CI.
4. Publish to the Mosaic Gitea npm registry with dist-tag `next`.
5. Keep `latest` untouched; only main/release promotion can update `latest`.
6. Teach the installer to prefer `@next` for the CLI/gateway prerelease lane once the registry tag is reliable.

## Guardrails

- `@next` is mutable prerelease convenience, not a deployment pin.
- Stable installs continue to use `@latest`.
- Contributor validation remains available through `--dev --ref <branch>`.
- Pipeline must be reproducible and trace every prerelease package back to the source commit on `next`.