@crvouga/atlas 0.5.0 → 0.6.0

package/docs/report-backends.md

@@ -3,7 +3,7 @@
 > [!NOTE]
 > Atlas has two kinds of backend, and this page is about the first.
 >
-> - **Run sources** (this page): where the viewer finds *statechart runs* (`manifest.json` per run)
+> - **Run sources** (this page): where the client finds *statechart runs* (`manifest.json` per run)
 >   and live snapshots of a run in progress: a directory, HTTP files, or an HTTP API.
 > - **Layer stores**: where *layers of evidence for any kind of spec* are kept, an `ObjectStore`
 >   such as a directory or a bucket. Any number of them are one report. See
@@ -14,7 +14,7 @@
 
 Atlas maps the product's areas, screens, events and journeys from a spec, then overlays evidence
 of what the product did. Specs and reports are independent. Local development, CI, device labs
-and hosted runners can supply reports to the same product atlas simultaneously. The viewer works
+and hosted runners can supply reports to the same product atlas simultaneously. The client works
 before the first report exists.
 
 ## Connect sources
@@ -33,9 +33,9 @@ The default source is the directory passed to `--runs`. Add sources with a JSON
 ```
 
 ```sh
-atlas-visualizer dev --specs ./specs --runs ./atlas-runs --sources ./atlas.sources.json
-atlas-visualizer build --specs ./specs --runs ./atlas-runs --sources ./atlas.sources.json --out ./atlas-site
-atlas-visualizer publish-data --specs ./specs --runs ./atlas-runs --sources ./atlas.sources.json --out ./atlas-data
+atlas client dev --specs ./specs --runs ./atlas-runs --sources ./atlas.sources.json
+atlas client build --specs ./specs --runs ./atlas-runs --sources ./atlas.sources.json --out ./atlas-site
+atlas client publish-data --specs ./specs --runs ./atlas-runs --sources ./atlas.sources.json --out ./atlas-data
 ```
 
 Directory paths resolve against the configuration file. Source ids are unique, stable names
@@ -45,7 +45,7 @@ Credentials must not appear in this file or URLs: descriptors are sent to the br
 included in static output.
 
 Remote services must allow requests
-from the viewer's origin. For private services, use an authenticated same-origin gateway. Atlas
+from the client's origin. For private services, use an authenticated same-origin gateway. Atlas
 does not download private GitHub artifacts or sign object-storage requests itself: expose their
 published data over HTTP or implement a gateway using the contract below.
 
@@ -113,7 +113,7 @@ updates to keep a snapshot steady; manual Refresh still works. Resuming refreshe
 
 ## Identity, failures and publishing
 
-Viewer identities combine source ids and native run ids. Cache keys include the backend location
+Client identities combine source ids and native run ids. Cache keys include the backend location
 and transport. Matching run names cannot mix results or media. Shared links retain the qualified
 identity; old links containing only a run id still resolve to workspace reports.
 
@@ -136,7 +136,7 @@ URLs and never expose the directory paths.
 
 `src/data/adapters/report-backend.ts` defines `ReportBackend`: stable identity and cache key,
 report listing, snapshot loading, media resolution and optional change subscription. The query
-layer consumes this separately from the spec adapter. An embedded viewer can supply a backend
+layer consumes this separately from the spec adapter. An embedded client can supply a backend
 through `ReportSourcesContext`; a new built-in transport can add a factory alongside
 `createReportBackend`. Screens, maps and journeys require no transport-specific code.
 

package/docs/report-contract.md

@@ -6,7 +6,7 @@ unit tests, linters, anything that ends in "this check passed or failed". If thi
 disagree, that is a bug: [file it](reporting-issues.md).
 
 The contract is small on purpose. It is one document (the **layer**), one rule (how layers compose),
-and one interface (the **backend** that stores them). Everything else, the viewer, the gate, the CLI,
+and one interface (the **backend** that stores them). Everything else, the client, the gate, the CLI,
 is built on those three and can be replaced.
 
 - [Concepts](#concepts)
@@ -289,7 +289,7 @@ import { verifyObjectStore } from '@crvouga/atlas/reports/object-store-conforman
 const { ok, failures } = await verifyObjectStore(myS3Store); // writes under a scratch prefix, cleans up
 ```
 
-Several backends are one report: pass them all to `combineBackends`, to the viewer
+Several backends are one report: pass them all to `combineBackends`, to the client
 (`reportsHost`), or to the CLI (`--store` for directories, `--backends <module>` for the rest). A
 backend that cannot be reached is named in the notices and leaves the others usable; asking again
 retries it.
@@ -302,7 +302,7 @@ entry whose content has not arrived:
 A layer's checks are the contract. Next to them the store holds the two other things a whole project
 needs, written the same way (content first, catalog entry last, nothing overwritten):
 
-- **Spec sets** (`layers/specs/…`): the specs of one commit, so a viewer needs no checkout. A spec set is
+- **Spec sets** (`layers/specs/…`): the specs of one commit, so a client needs no checkout. A spec set is
   `{ schemaVersion, id, branch, sha, recordedAtMs, freshness?, files: [{ path, digest, fingerprint, kind,
   title, domain, bytes }] }` ([`spec-set.schema.json`](../packages/schema/schemas/spec-set.schema.json)). Its
   id is the digest of the branch, commit and file digests, so one commit's specs are one set however many
@@ -310,7 +310,7 @@ needs, written the same way (content first, catalog entry last, nothing overwrit
   The outline a report is laid over is the **newest set from `main`** (then `master`, then the newest);
   a set from a modified checkout is used only if no committed set exists.
 - **Run bundles** (`layers/runs/<run>/…` and `layers/runs/index/…`): a finished statechart run with its
-  screenshots and clips, for the viewer. Uploaded only when the run's privacy scan passed; the manifest is
+  screenshots and clips, for the client. Uploaded only when the run's privacy scan passed; the manifest is
   written last, then the catalog entry.
 
 The keys of a layer, bottom up:
@@ -376,13 +376,13 @@ and composed with layers; Atlas never rewrites them. `copyStore` and `atlas repo
   the number of checks (plus a few bytes for each layer ever read), not the age of the project, and a refresh
   with nothing new is one request for the newest page of the catalog. Folding is exact in any order because the winner
   rule is a total order; a test proves the incremental report equals combining every layer from scratch.
-  The node sends the viewer only that: one request, only winning rows, with an ETag.
+  The node sends the client only that: one request, only winning rows, with an ETag.
 - Measured on a laptop with a directory backend: 300 layers of 50 checks in about 0.2 s; 1,000 layers
   of 100 checks, each recorded against 1,000 specs (100,000 results), in about 0.9 s. Composing two
   thousand layers of 100 checks (200,000 results) already in memory takes about 0.3 s.
   `performance.test.ts` holds budgets ten times looser, to catch an accidental quadratic step on a
   slow machine.
-- A directory backend lists only the directories a prefix can reach. The viewer polls a small index,
+- A directory backend lists only the directories a prefix can reach. The client polls a small index,
   reads an immutable layer once and caches it forever, and loads recordings only when opened.
 
 ## Other documents of the contract
@@ -394,7 +394,7 @@ and composed with layers; Atlas never rewrites them. `copyStore` and `atlas repo
 | Report status | `report-status.schema.json` | The output of `atlas report status --format json`. |
 | Spec set | `spec-set.schema.json` | The specs of one commit, as published beside the layers. |
 | Run manifest | `manifest.schema.json` | What `atlas run` writes for a statechart run. Publish it as a layer with `--manifest`. |
-| Runs index, sources, change notices | `runs-index`, `report-sources`, `atlas-change` | How the viewer finds runs. See [report backends](report-backends.md). |
+| Runs index, sources, change notices | `runs-index`, `report-sources`, `atlas-change` | How the client finds runs. See [report backends](report-backends.md). |
 | CloudEvents | `cloud-event.schema.json` | Business events a run observed. |
 
 All of them are JSON Schema 2020-12 and ship in the package at `@crvouga/atlas/schemas/<name>.schema.json`.

package/docs/reporting-issues.md

@@ -16,7 +16,7 @@ This guide is written for coding agents. Read it top to bottom once, then use
 
 `<part>` is the part of `@crvouga/atlas` the issue is about: `core` (the main import and the
 `atlas` command), or the import path after the package name: `playwright`, `bun`, `webdriver`,
-`detox`, `vitest`, `schema`, `reports`; `visualizer` for the `atlas-visualizer` command. Use `core`
+`detox`, `vitest`, `schema`, `reports`; `visualizer` for the `atlas client` command. Use `core`
 when you cannot tell.
 
 1. [Search for an existing issue](#1-search-first). Comment on it instead of opening a duplicate.
@@ -43,10 +43,10 @@ File when:
 
 - **bug**: Atlas throws or hangs; lint, plan or a run gives a result the spec does not support;
   a driver taps, types, waits or records differently from what its README says; the manifest or a
-  report does not match its JSON Schema; the visualizer shows something other than what the run
+  report does not match its JSON Schema; the Atlas client shows something other than what the run
   recorded; the package fails to install, import, build or type-check.
 - **feature**: you need something Atlas does not have: a spec construct, a config option, a driver
-  capability, a CLI flag, a field in the manifest, a view in the visualizer, an export format. Check
+  capability, a CLI flag, a field in the manifest, a view in the Atlas client, an export format. Check
   that part's README and `docs/` first.
 
 Do not file when:

package/docs/runners.md

@@ -0,0 +1,69 @@
+# Native test runner reporters
+
+Projects upload results to a shared Atlas node under their own project slug. CodeceptJS, Mocha, Jest and Node's test runner have native reporters; other runners can publish their JUnit or CTRF output with `atlas report publish`. All reporters are entry points of the single `@crvouga/atlas` package.
+
+## Configure the project once
+
+Set these in the test process, locally or in CI:
+
+```sh
+export ATLAS_SERVER_URL=https://atlas.example.com
+export ATLAS_PROJECT=checkout-service
+export ATLAS_PUBLISH_TOKEN=your-publish-token
+export ATLAS_ENVIRONMENT=linux-chromium
+export ATLAS_BRANCH=main
+export ATLAS_SHA=your-commit-sha
+```
+
+The server owns its storage configuration and credentials. Consumers only need the server URL and a publish token. Upload failures fail the test invocation; reporters wait for publication before finishing. Each invocation streams a live run, then publishes final evidence, with stable check IDs relative to the project directory, durations, failures and skipped outcomes. Unknown outcomes, TODOs and skipped tests are `not-run`, never passed. Parallel processes upload independent layers; use distinct producer/environment values for independent suites.
+
+A test file is part of a check's identity, not automatically a specification: link checks to product specifications through the existing report mapping workflow when importing JUnit/CTRF, or publish explicit `specPath` checks through the API.
+
+## CodeceptJS
+
+Use its [Mocha reporter interface](https://codecept.io/reports/):
+
+```sh
+bunx codeceptjs run --reporter @crvouga/atlas/codecept
+```
+
+Streams scenario starts and outcomes, then records durations and scenario steps when supplied by CodeceptJS. Use the standard single-process runner; parallel workers should each publish their own layer. Runner-native screenshot/video attachments can also be imported from CTRF/JUnit; this reporter does not read arbitrary files from runner objects.
+
+## Mocha
+
+```sh
+bunx mocha --reporter @crvouga/atlas/mocha
+```
+
+Or configure `reporter` and `reporterOptions` in Mocha. Options include `url`, `token`, `producer`, `environment`, `branch`, `sha`, `rootDir` and `timeoutMs` (30 seconds by default); explicit options override the environment. Final failures and hook failures are failed checks. Passing retries include a flaky label. Mocha parallel mode is not supported by this reporter's event model; run each shard separately.
+
+## Jest
+
+Keep Jest's console reporter alongside Atlas:
+
+```js
+export default {
+  reporters: ['default', ['@crvouga/atlas/jest', { producer: 'unit' }]],
+};
+```
+
+The reporter streams test-case starts and results from workers and uploads full aggregated evidence after workers finish. File-level exceptions become failed checks even when no test ran. Watch mode resets publication errors on each invocation. It accepts the same options as Mocha.
+
+## Node's test runner
+
+```sh
+node --test --test-reporter=spec --test-reporter-destination=stdout \
+  --test-reporter=@crvouga/atlas/node-test --test-reporter-destination=stdout
+```
+
+Uses the native async event stream, with environment configuration. Reports leaf tests; successful suite containers are excluded, while suite hook failures remain failed checks. Test names include enclosing suites so identical names in different suites keep distinct IDs. Skips and TODOs remain not-run, including TODO failures.
+
+## Other runners and frameworks
+
+Playwright, Vitest, Bun, WebDriver/Appium and Detox already have Atlas statechart adapters. Pytest, JUnit/TestNG, NUnit, xUnit, Go, Rust, Cypress, WebdriverIO, Cucumber and Robot Framework can publish JUnit XML or CTRF JSON through the existing importer. See [integration commands](integrating.md) and the [report contract](report-contract.md). These report importers complement native reporters; they do not require a storage backend in the consumer project.
+
+## Operate the singleton
+
+Run `atlas server` once for the projects the node hosts; point local and CI publishers at that URL and set each project's `ATLAS_PROJECT`. Configure backends using environment variables or open **Settings** in the client (`/admin`). Authentication and listening addresses remain deployment configuration. Settings changes are validated and saved atomically for the next server restart. Environment variables and flags override saved values. A backend change does not migrate historical data: retain the old backend as a read source when switching the upload destination.
+
+Native reporters send a heartbeat every 5 seconds. The server interrupts invocations after 30 seconds of silence, or after the configurable progress-stall timeout. It preserves finished results and never marks missing tests as passed. See [live test runs](server.md#live-test-runs-and-heartbeats).

package/docs/server.md

@@ -1,11 +1,11 @@
 # The Atlas server
 
-One process per project that **takes in results from every environment, keeps them, and shows everyone the
-combined report, live**. It is a Bun API that serves a Vite-built single-page viewer: one host, one port, in
+One node for multiple projects that **takes in results from every environment, keeps them, and shows everyone the
+combined report, live**. It is a Bun API that serves a Vite-built single-page client: one host, one port, in
 development and in production.
 
 ```
-  laptop ──────┐                                        ┌── browsers  (the viewer: reads /api, listens on /api/events)
+  laptop ──────┐                                        ┌── browsers  (the client: reads /api, listens on /api/events)
   CI job ──────┼── PUT /api/store/…  POST /api/checks ─▶│
   device lab ──┘   atlas report publish | stream        │   atlas report status  (the gate: asks /api/status)
                                                         │
@@ -18,8 +18,8 @@ development and in production.
 - **Its default backend is its own filesystem** (`./atlas-data`). That folder is the whole state: back it up,
   mount it on a volume, or put the state in a bucket instead ([backends](#backends)). Several backends are one
   report, as ever.
-- **The report is live.** Every viewer holds one server-sent-events connection; when results arrive the server
-  says so and each viewer reads only what changed ([streaming](#streaming)).
+- **The report is live.** Every client holds one server-sent-events connection; when results arrive the server
+  says so and each client reads only what changed ([streaming](#streaming)).
 - **Layered, never partitioned**, as everywhere in Atlas: the server only stores immutable, content-addressed
   layers and works out the report from them. Replace it, restore it, or run a second one on a copy of the data:
   the same layers give the same report ([the contract](report-contract.md)).
@@ -36,13 +36,13 @@ export ATLAS_TOKEN=$(openssl rand -hex 24)   # admin token; see "Tokens and role
 bunx atlas serve                             # http://127.0.0.1:8080, data in ./atlas-data
 ```
 
-It runs on Bun and on Node 22.18 or later. The first start builds the viewer once into `~/.cache/atlas/site`
+It runs on Bun and on Node 22.18 or later. The first start builds the client once into `~/.cache/atlas/site`
 (or serves `./atlas-site`, or `--site <dir>`); the build is the same for every project, because the server writes
 its own address book into the page (`window.__ATLAS_CONFIG__`).
 
-**Working on Atlas or on the viewer:** `atlas dev` runs the server on a port of its own and the viewer's Vite dev
+**Working on Atlas or on the client:** `atlas dev` runs the server on a port of its own and the client's Vite dev
 server in front of it. Vite proxies `/api` (server-sent events included) to the server, so the browser, the
-uploaders and the viewer all use **one host**, exactly as in production, and a change to the viewer shows at once.
+uploaders and the client all use **one host**, exactly as in production, and a change to the client shows at once.
 
 ```sh
 bunx atlas dev --data .atlas-data            # http://127.0.0.1:5180
@@ -90,7 +90,7 @@ purposes.
 
 A backend is anything that implements `ObjectStore`: a folder, an S3-compatible bucket (`s3://`, `r2://`,
 `gs://`), or **another Atlas server** (`https://…`, with `ATLAS_TOKEN` for it). The server reads every backend
-and shows one report; one that is down is named in the viewer and skipped, and the server recovers by itself.
+and shows one report; one that is down is named in the client and skipped, and the server recovers by itself.
 
 - **Uploads go to one backend**: the `data` folder, or the one named by `write` / `ATLAS_WRITE`. Name a bucket
   to make it the system of record, so the server holds nothing a replacement would lose:
@@ -107,7 +107,7 @@ and shows one report; one that is down is named in the viewer and skipped, and t
 
 | Role | May |
 | --- | --- |
-| `read` | look: the viewer, the report, `/api/status` |
+| `read` | look: the client, the report, `/api/status` |
 | `publish` | also upload layers, specs and runs, and remove the scratch objects `atlas report doctor` writes |
 | `admin` | all server operations |
 
@@ -191,24 +191,26 @@ there (`409`), so nothing half-uploaded is ever shown.
 
 | Event | Data | Meaning |
 | --- | --- | --- |
-| `hello` | `{ version, ready, time }` | Sent first. The report's current version. |
+| `hello` | `{ version, ready, time, heartbeatMs? }` | Sent first. The report's current version. |
 | `report` | `{ version, totalLayers, added: [{ id, producer, environment, branch, sha, recordedAtMs, counts }], addedTotal }` | Layers arrived. Enough to say who sent what, without asking. |
 | `atlas:change` | `{ scope: "specs" \| "runs", files, runIds }` | New specs or runs. |
-| `ping` | `{}` | Every 15 s, so proxies keep the connection and the viewer can tell a quiet server from a dead connection. |
+| `run` | A bounded `LiveRun` snapshot | Start, progress logs, heartbeat, completion, and interruption; no producer credentials. |
+| `projects` | `{}` | Another project was discovered; refresh the project picker. |
+| `ping` | `{}` | Every 15 s, so proxies keep the connection and the client can tell a quiet server from a dead connection. |
 
-Events say *that* something changed; the state is always fetched. A viewer that missed some (a dropped
-connection, a laptop that slept) loses nothing: it reads again when it reconnects, and the viewer also reads on a
+Run events update progress directly in the client cache. Report and specification events trigger coalesced reads of the affected data. Events arriving during a read cause a trailing refresh rather than cancelling that read. A client that missed some (a dropped
+connection, a laptop that slept) loses nothing: it reads again when it reconnects, and the client also reads on a
 slow timer behind the stream. Past `limits.maxStreams` viewers the server answers `503` with `Retry-After` and the
-viewer polls instead; a viewer that stops reading is let go rather than held in memory.
+client polls instead; a client that stops reading is let go rather than held in memory.
 
 ### Reading only what changed
 
 `GET /api/reports/evidence/effective` is the whole report: only the layers that win a check, each with only the
-rows that win, with an ETag. A viewer that holds a version asks `?since=<version>` and is sent **only the layers
+rows that win, with an ETag. A client that holds a version asks `?since=<version>` and is sent **only the layers
 that changed since, and the ids that no longer win anything** (`"delta": true`). Applying that gives exactly the
 report the server would have sent whole (`applyEffectiveDelta`, tested against every earlier version of random
-runs); a version the server does not remember, or an older server, answers with the whole report, which a viewer
-takes as it always did. A result streamed into a 100 000-check report costs a viewer a few kilobytes.
+runs); a version the server does not remember, or an older server, answers with the whole report, which a client
+takes as it always did. A result streamed into a 100 000-check report costs a client a few kilobytes.
 
 ## API reference
 
@@ -250,7 +252,7 @@ laptop with 2 000 layers of 100 checks (200 000 results, 10 000 slots) and with
 | --- | --- | --- |
 | Start: read and fold every layer | 0.4 s | 1.7 s |
 | A refresh with nothing new | 4 ms | 4 ms |
-| Upload one layer → every viewer told | 4 ms | 5 ms |
+| Upload one layer → every client told | 4 ms | 5 ms |
 | `GET effective`, cached / `304` | 1 ms / 0.2 ms | 13 ms / 0.5 ms |
 | `GET status`, cached for the version | 12 ms first | 70 ms first |
 
@@ -264,22 +266,56 @@ What makes it so, none of it at the cost of the contract:
 - **An upload is read once.** A layer's manifest is parsed and verified when it arrives and handed to the report,
   not read again; blob existence is asked 16 at a time.
 - **The newest end of the catalog is all a refresh looks at**, with a full look now and then.
-- **Compressed once.** The viewer's files are brotli-compressed once (gzip for clients that cannot read it), a
-  report version is gzipped once however many viewers fetch it, and events are encoded once for every viewer.
-- **A small viewer.** The graph, the Gherkin parser, the recording player and the finder load when used: the
+- **Compressed once.** The client's files are brotli-compressed once (gzip for clients that cannot read it), a
+  report version is gzipped once however many viewers fetch it, and events are encoded once for every client.
+- **A small client.** The graph, the Gherkin parser, the recording player and the finder load when used: the
   first page is about 250 KB over the wire.
 
 ## Operating it
 
-- **One server per project.** It is a singleton by design: local environments and CI all talk to it, and it tells
-  every viewer at once. Two servers on one backend both work and show the same report, but a viewer hears about
+- **One node for multiple projects.** Local environments and CI select their project slug and talk to the same node, which tells
+  every client at once. Two servers on one backend both work and show the same report, but a client hears about
   an upload only from the server that took it and about the other's at the next refresh, so give a team one.
 - **State is the write backend.** Back up `./atlas-data` (or the bucket). Restoring it, or starting a new server
   on it, shows the same report.
 - **Stopping.** `SIGTERM` stops accepting, lets requests in flight finish, ends the event streams and exits 0.
 - **Logs.** One JSON line per request (method, path, status, ms) to stdout, none for the probes. The first lines
   say what it reads and which backend takes uploads, and warn when there are no tokens.
-- **A backend goes down.** The server keeps serving what it has, names the backend in the viewer and in
+- **A backend goes down.** The server keeps serving what it has, names the backend in the client and in
   `/readyz`, and recovers by itself. The gate fails closed: unknown is not a pass.
 - **Upgrades.** The layer format is a stable, versioned contract; upgrade the server before the clients that
   publish when a release says the format moved.
+
+## Configure from the client
+
+Open **Settings** (`/admin`) and enter an admin token. The token stays in page memory. Read and publish tokens cannot edit settings; the browser sign-in box only grants reading. The API uses `Authorization: Bearer` and refuses cross-origin browser writes.
+
+Use the Storage, Live updates, and Report rules forms to edit saved settings. Advanced includes request limits, logging, a JSON editor, and a read-only view of the active configuration. Save changes and restart Atlas to apply them. Atlas validates the configuration and atomically replaces `atlas.server.json`, preserving authentication and deployment settings. Changes apply at the next restart; environment variables and flags retain precedence. Concurrent edits require reloading the current revision. Data is never moved or removed by changing settings. Keep an old backend as a read source when moving future uploads to a new one. Embedded servers can provide their own settings persistence or manage configuration outside this API.
+
+Native test reporters for CodeceptJS, Mocha, Jest and Node upload directly to this server; see [runner setup](runners.md). Every publisher uses the same server address and only a publish token. Storage credentials belong in the server environment.
+
+## Live test runs and heartbeats
+
+The default native reporters and statechart runner stream tests and steps through `/api/live`, before the invocation finishes. Running tests appear inside their report with an animated status mark and the latest step. Open a test to read its progress log; its previous recorded result stays available separately. The **Running** filter narrows both the spec list and the test rows, and counts update as tests finish or time out. Statechart tests appear inside the chart and screen details. Selecting an archived run leaves live progress out of that historical view. Finished checks immediately enter normal immutable report layers. Operational progress is separate from historical winners, so a previous passed result never implies that the current invocation passed.
+
+Start with `POST /api/live/<uuid>`, send ordered check deltas with `PATCH /api/live/<uuid>`, and renew the producer lease with `POST /api/live/<uuid>/heartbeat` every 5 seconds. Finish with a terminal update. Only the publisher token that registered the invocation can update it. Replayed sequences must have identical content; late writes cannot revive an expired invocation. `createLiveReporter` handles batching, retries, heartbeat timers and the final flush.
+
+The server uses its own receipt clock. By default it interrupts a run after 30 seconds without a heartbeat (`ATLAS_RUN_TIMEOUT_SECONDS`). Heartbeats do not reset progress: after 15 minutes with no changed tests/steps, a separate stall timeout interrupts it (`ATLAS_RUN_STALL_SECONDS`, 0 disables). Both settings are editable in the admin UI. Healthy long tests continue renewing heartbeats; increase or disable the progress timeout for tests that legitimately make no observable progress for longer.
+
+Interrupted runs retain completed results and show why the remaining work stopped. Missing outcomes never become passes. The server persists bounded summaries under `server/live/` in its write backend (an HTTP relay keeps operational leases in its own data folder; the remote server only accepts immutable report objects) and restores outstanding leases as interrupted after a server restart. S3 server credentials need GetObject/PutObject for that prefix; generate the updated `atlas report policy --role both` policy. Producers still receive no backend credentials. Live `run` events carry bounded snapshots directly into test rows, including step logs and interruption reasons. The legacy `atlas:change` announcement remains available for older clients; its optional `liveRunId` identifies lease updates. Reconnecting viewers re-fetch progress, reports, and specifications. With SSE connected, live progress uses a 60-second safety refresh; without SSE it polls every two seconds. Returning to the tab or coming back online also revalidates reports and progress.
+
+In this repository, use `bun atlas` and `bun example:run` in two terminals. Every example Gherkin scenario executes, including sharing and renaming; `@unrecorded` no longer excludes tests.
+
+## Multiple projects on one node
+
+Start the node with `atlas server` (or `bun atlas` in this repository). The server builds or finds the Atlas client and serves it with the API from one process. It never imports a consumer or an example. In this repository the node uses port 5180 and `./atlas-data`; `bun example:run` publishes the Todo app to project `todo-app`.
+
+Set `ATLAS_PROJECT=todo-app` alongside `ATLAS_SERVER_URL` for native reporters and statechart runs. Report CLI commands accept `--project todo-app` (or `ATLAS_PROJECT`) with an HTTP store. Programmatic HTTP stores, live reporters and native reporter options accept `project: 'todo-app'`. Keep the same slug for the invocation's live progress, final results, spec sets and recordings. Slugs use 1–64 lowercase letters, digits or hyphens, starting and ending with a letter or digit.
+
+Every project API is available as `/api/projects/<slug>/…`, for example `/api/projects/todo-app/checks`, `/api/projects/todo-app/events` and `/api/projects/todo-app/reports/evidence/effective`. The unprefixed API accepts optional `?project=todo-app` or `X-Atlas-Project: todo-app`. Conflicting selectors are refused. `GET /api/projects` discovers projects. A successful authenticated upload creates a project; reads of an unknown project return 404.
+
+Projects isolate check identities, specs, run IDs, recordings, lease summaries, event streams and report caches. Identical layer bytes are preserved as uploaded. The node stores each project's objects under `projects/<slug>/` and discovery markers under `server/projects/`. Unqualified requests continue reading the legacy default namespace, advertised as **Default** when it has reports. Existing data is never implicitly moved. For S3, use the combined server policy (`atlas report policy --role both`) with access to both project namespaces and the catalog. An HTTP relay selects the same project on its upstream node and keeps discovery and leases locally.
+
+The project picker sits at the top right; the header also provides spec dropdown breadcrumbs. Project selection lives in the page URL, so links and refreshes preserve it. Switching projects reloads the client, clearing report queries, media and event connections. Custom report-source preferences are keyed by the project's data URL. Project namespaces share the node's authentication roles: they are organizational partitions, not separate tenant authorization policies. Settings and server identity remain node-wide.
+
+Project indexes are opened lazily; at most 64 are active in memory. An index with no active requests or event subscribers is closed after five idle minutes. Event subscribers share the node-wide stream limit. Project discovery lists only small catalog markers, never every report layer.

package/docs/statecharts.md

@@ -5,7 +5,7 @@ paths that cover every transition, run those paths against the real product thro
 browser, a phone, a plain function), and write a manifest of what happened, with screenshots, video
 clips, captions, business events and standard test reports. Each run publishes as a layer
 (`atlas report publish --manifest`), so it combines with every other suite's evidence. This page covers
-running them, from a runnable example to the visualizer.
+running them, from a runnable example to the Atlas client.
 
 ```
 specs/                     atlas lint      the charts are pure, reachable, free of silent dead ends,
@@ -35,7 +35,7 @@ served by a small Node server) specified as two charts:
 - `specs/getting-started.feature` and `specs/working-the-list.feature`, the same stories in Gherkin.
 - `specs/todo.qnt`, the list, its sync, and its actions as a Quint model.
 
-The visualizer lists the features under Gherkin and the model under Quint.
+The Atlas client lists the features under Gherkin and the model under Quint.
 
 It has every kind of event: user events (taps and typing), a **system** event ("Sync fails", which
 the test triggers through a real HTTP endpoint on the example server), a **time** event ("Retry
@@ -65,24 +65,26 @@ visualizer updates when a run finishes.
 
 ```sh
 bun run atlas:run   # example:clients, then example:run: every chart of the example, in showcase mode
-bun run atlas:viz   # the example's specs, chart runs, and layered reports
+bun atlas          # the example's specs, chart runs, and layered reports
 ```
 
-Each config writes its own run and the visualizer shows one run at a time: the latest is the
+Each config writes its own run and the Atlas client shows one run at a time: the latest is the
 single-browser run, and the run across clients is the one before it in the run picker.
 
-`bun run viz:dev` opens the full coffee example with a layered report, without waiting
-for a run. Gherkin, Quint, DMN, Alloy and OpenSLO documents sit beside the charts. The same scenarios
-are filled by separate layers across desktop web, mobile web, iOS and Android, and across versions,
-branches and backends (this machine, shared reports, and a device lab). A layer that repeated one
-scenario leaves the others as the last layer that ran them. One feature is left with no results.
-**Sources** in the header switches any of those off. The chart runs stay on the statechart map.
-
-`bun run atlas:viz` opens the todo example the same way. The Gherkin, Quint, DMN, Alloy and OpenSLO
-tabs already show five layers, so each environment is visible before a run. `example:run` adds one
-desktop web layer for the scenarios and traces it actually ran. That layer replaces only those
-desktop web results. The other environments stay. `ATLAS_REPORTS_MODULE` replaces this example API
-with a host's reports.
+Gherkin, Quint, DMN, Alloy and OpenSLO documents sit beside the charts. Results compose across
+environments, branches and backends within each project. **Sources** switches report sources on or off.
+
+`bun atlas` runs the singleton Atlas server and the client together at `http://localhost:5180`.
+It starts a project-agnostic node with no example data. Select a project using the top-right picker.
+In another terminal run `bun run example:run`: statecharts, Gherkin scenarios and Quint traces stream running checks, completed results and current steps
+to project `todo-app` on that server while testing. Producers renew a heartbeat every 5 seconds; 30 seconds of silence
+marks an invocation interrupted. Final specs and recordings upload when their privacy scan completes.
+Tests show inline running indicators and logs without waiting for the whole suite to finish. Report history
+is retained in `atlas-data/projects/todo-app`; local run artifacts remain in `atlas-runs` and
+`atlas-reports`. To upload a completed run again without rerunning tests,
+use `bun run example:publish`. Set `ATLAS_SERVER_URL` for a different upload destination (and
+`ATLAS_PUBLISH_TOKEN` when it requires one). Restart `bun atlas` when switching from the older
+file-based example client; a busy port is an error so publishers cannot silently target another server.
 
 A showcase run ends with:
 
@@ -92,7 +94,7 @@ Transitions 14/14 passed, 0 failed, 0 not reached
 Manifest: examples/todo/atlas-runs/<run-id>/manifest.json
 ```
 
-`example:run` then runs the Gherkin features in a browser and the Quint model, and publishes that desktop web layer beside the ones already in the report.
+`example:run` then runs the Gherkin features in a browser and the Quint model, and streams every scenario and trace as it runs, including sharing and renaming. The final recordings are uploaded alongside the completed statechart run.
 
 `bun test examples` runs [`model.test.ts`](https://github.com/crvouga/atlas/blob/main/examples/todo/model.test.ts): the same charts and journeys
 against `TodoModel`, a plain class, through `functionDriver` and `describeAtlas`. Only the driver
@@ -517,7 +519,7 @@ atlas report publish --producer statecharts --environment desktop-web \
   --manifest atlas-runs/<run>/manifest.json --specs ./specs --upload-run
 ```
 
-`--upload-run` also sends the run's screenshots and clips to the store (or the server) so the viewer can show them
+`--upload-run` also sends the run's screenshots and clips to the store (or the server) so the client can show them
 (only when the run's privacy scan passed).
 
 ## Config reference
@@ -627,7 +629,7 @@ Runs produce media and manifests that get shared, so Atlas refuses to leak real
 
 ## Visualizer
 
-The [`atlas-visualizer`](../packages/visualizer) command renders the charts from the specs directory and
+The [`atlas client`](../packages/visualizer) command renders the charts from the specs directory and
 overlays runs from the runs directory: screenshots on states, clips on transitions, statuses and
 history. See its README for how to point it at a project.
 
@@ -638,4 +640,4 @@ and completed steps while paths are still running.
 
 Layered reports for any spec appear beside the charts: each Gherkin, Quint, DMN, Alloy and OpenSLO
 document shows the combined result of its checks per environment, with the layer behind each. Point
-the viewer at your stores with `reportsHost` ([integrating Atlas](integrating.md#6-browse-it)).
+the client at your stores with `reportsHost` ([integrating Atlas](integrating.md#6-browse-it)).