@crvouga/atlas 0.4.0 → 0.6.0

package/dist/bun/src/driver.d.ts

@@ -37,6 +37,7 @@ export type WebViewContext = SignalContext & {
         press(key: string, label?: string): Promise<void>;
     };
 };
+/** Options of `bunWebViewDriver`; every field is optional. */
 export type BunWebViewDriverOptions = {
     /** Where `goto` paths resolve; the implementation's setup decides where to open. */
     baseUrl?: string | (() => string | Promise<string>);
@@ -47,7 +48,10 @@ export type BunWebViewDriverOptions = {
     backend?: 'webkit' | 'chrome';
     /** How long a tap waits for its target to show, in milliseconds (default 10 000). */
     actionTimeoutMs?: number;
-    /** Showcase pacing, in milliseconds. */
+    /**
+     * Showcase pacing, in milliseconds: the hold before each event runs and after its state shows (default 400 and
+     * 900).
+     */
     pacing?: {
         before: number;
         after: number;
@@ -56,12 +60,42 @@ export type BunWebViewDriverOptions = {
     concurrency?: number;
 };
 /**
- * Drive a web app in Bun's built-in headless browser: the system WebKit on macOS (nothing to
- * install), Chrome over CDP elsewhere. A view starts in milliseconds and screenshots take about
- * ten, so it is the quickest way to run a chart against a real page. Clips are encoded from
- * screenshots with FFmpeg. Needs the Bun runtime; there is no fake clock, so time events use the
- * app's own controls.
+ * Drives a web app in Bun's built-in headless browser for `atlas run`: the system WebKit on macOS (nothing to
+ * install), Chrome over CDP elsewhere. A view starts in milliseconds and screenshots take about ten, so it is the
+ * quickest way to run a chart against a real page. Each path attempt gets its own view, closed afterwards. Screenshots
+ * are PNG files without a thumbnail. Clips are encoded from screenshots with FFmpeg (no clip is recorded without it).
+ * `user.tap` and `user.type` wait up to `actionTimeoutMs` for the target signal to show, then click its centre; a
+ * target that never shows fails the step with "<signal> is not on screen". Needs the Bun runtime (run
+ * `bun --bun atlas run`), and throws on open without it. There is no fake clock, so time events use the app's own
+ * controls.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@crvouga/atlas';
+ * import { bunWebViewDriver, screen, text } from '@crvouga/atlas/bun';
+ *
+ * export default defineConfig({
+ *   specs: './specs',
+ *   driver: () => bunWebViewDriver({ baseUrl: 'http://127.0.0.1:4317' }),
+ *   implementation: {
+ *     async setup(ctx) { await ctx.goto('/'); },
+ *     events: {
+ *       // one entry per event of the spec
+ *     },
+ *     states: { 'No todos': screen({ all: [text('Nothing to do yet')] }) }
+ *   }
+ * });
+ * ```
  */
 export declare function bunWebViewDriver(options?: BunWebViewDriverOptions): Driver<WebViewContext>;
-/** A state recognised from its signals in the page: every `all` visible and no `none` visible. */
+/**
+ * Builds a state implementation for a `WebViewContext` from its signals in the page: every `all` signal visible, one
+ * `any` signal visible (when given), no `none` signal visible. It is core's `signatureScreen` over `ctx.isVisible`, so
+ * it takes the same spec as `screen` from `@crvouga/atlas/signals` (`checks`, `transient`, `sameAs`, `lookIn`,
+ * `settle` included).
+ *
+ * @see docs/statecharts.md
+ */
 export declare const screen: (spec: import('../../core/src/signals.js').ScreenSpec<WebViewContext, Signal>) => import('../../core/src/index.js').StateImplementation<WebViewContext>;

package/dist/bun/src/driver.js

@@ -1,3 +1,14 @@
+/**
+ * @module Bun WebView driver
+ *
+ * `bunWebViewDriver()` is the core `Driver` that runs a statechart's paths in Bun's built-in headless browser
+ * (`Bun.WebView`), the quickest way to run a chart against a real page. It provides a `WebViewContext` whose
+ * `user.tap` and `user.type` act on `Signal`s, found by the shared in-page DOM probe from core, so an implementation
+ * written against `SignalContext` runs here and on the other web drivers unchanged. `Bun.WebView` is typed
+ * structurally (`BunWebView`), so this package builds without Bun's types; at run time the Bun runtime is required.
+ *
+ * @see docs/statecharts.md
+ */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { recordFrames } from '../../core/src/index.js';
@@ -51,11 +62,34 @@ function contextFor(view, baseUrl, timeline, options) {
     return ctx;
 }
 /**
- * Drive a web app in Bun's built-in headless browser: the system WebKit on macOS (nothing to
- * install), Chrome over CDP elsewhere. A view starts in milliseconds and screenshots take about
- * ten, so it is the quickest way to run a chart against a real page. Clips are encoded from
- * screenshots with FFmpeg. Needs the Bun runtime; there is no fake clock, so time events use the
- * app's own controls.
+ * Drives a web app in Bun's built-in headless browser for `atlas run`: the system WebKit on macOS (nothing to
+ * install), Chrome over CDP elsewhere. A view starts in milliseconds and screenshots take about ten, so it is the
+ * quickest way to run a chart against a real page. Each path attempt gets its own view, closed afterwards. Screenshots
+ * are PNG files without a thumbnail. Clips are encoded from screenshots with FFmpeg (no clip is recorded without it).
+ * `user.tap` and `user.type` wait up to `actionTimeoutMs` for the target signal to show, then click its centre; a
+ * target that never shows fails the step with "<signal> is not on screen". Needs the Bun runtime (run
+ * `bun --bun atlas run`), and throws on open without it. There is no fake clock, so time events use the app's own
+ * controls.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@crvouga/atlas';
+ * import { bunWebViewDriver, screen, text } from '@crvouga/atlas/bun';
+ *
+ * export default defineConfig({
+ *   specs: './specs',
+ *   driver: () => bunWebViewDriver({ baseUrl: 'http://127.0.0.1:4317' }),
+ *   implementation: {
+ *     async setup(ctx) { await ctx.goto('/'); },
+ *     events: {
+ *       // one entry per event of the spec
+ *     },
+ *     states: { 'No todos': screen({ all: [text('Nothing to do yet')] }) }
+ *   }
+ * });
+ * ```
  */
 export function bunWebViewDriver(options = {}) {
     const width = options.width ?? 390;
@@ -86,5 +120,12 @@ export function bunWebViewDriver(options = {}) {
         hold: (_ctx, ms) => new Promise((r) => setTimeout(r, ms))
     };
 }
-/** A state recognised from its signals in the page: every `all` visible and no `none` visible. */
+/**
+ * Builds a state implementation for a `WebViewContext` from its signals in the page: every `all` signal visible, one
+ * `any` signal visible (when given), no `none` signal visible. It is core's `signatureScreen` over `ctx.isVisible`, so
+ * it takes the same spec as `screen` from `@crvouga/atlas/signals` (`checks`, `transient`, `sameAs`, `lookIn`,
+ * `settle` included).
+ *
+ * @see docs/statecharts.md
+ */
 export const screen = signatureScreen((ctx, signal) => ctx.isVisible(signal), describeSignal);

package/dist/bun/src/index.d.ts

@@ -1,2 +1,10 @@
+/**
+ * @module Bun WebView driver entry point (`@crvouga/atlas/bun`)
+ *
+ * Re-exports the Bun WebView driver for statechart runs (`bunWebViewDriver`), its context and option types, `screen`
+ * for recognising states from signals, and the signal constructors. Needs the Bun runtime.
+ *
+ * @see docs/statecharts.md
+ */
 export { bunWebViewDriver, screen, type BunWebView, type BunWebViewDriverOptions, type WebViewContext } from './driver.js';
 export { css, label, role, testId, text, describeSignal, type Signal } from '../../core/src/signals.js';

package/dist/bun/src/index.js

@@ -1,2 +1,10 @@
+/**
+ * @module Bun WebView driver entry point (`@crvouga/atlas/bun`)
+ *
+ * Re-exports the Bun WebView driver for statechart runs (`bunWebViewDriver`), its context and option types, `screen`
+ * for recognising states from signals, and the signal constructors. Needs the Bun runtime.
+ *
+ * @see docs/statecharts.md
+ */
 export { bunWebViewDriver, screen } from './driver.js';
 export { css, label, role, testId, text, describeSignal } from '../../core/src/signals.js';

package/dist/core/src/cli.d.ts

@@ -1 +1,14 @@
-export declare function main(argv?: string[]): Promise<0 | 1 | 2>;
+/**
+ * @module The `atlas` command
+ *
+ * Dispatches `atlas <command>`: the statechart commands (`lint`, `plan`, `run`, `merge`, `export`) and, loaded on demand so
+ * they cost nothing otherwise, `serve`, `dev`, `init` and `report`. Statechart configuration is `atlas.config.ts` (see
+ * `defineConfig`). A command that is wrong prints a message and exits 2; a plan, lint or run that finds problems exits 1.
+ *
+ * @see docs/statecharts.md
+ * @see docs/reference/cli.md
+ */
+/** The text `atlas --help` prints: every command, and the flags of the statechart commands. */
+export declare const USAGE = "atlas \u2014 executable statecharts\n\n  atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]\n  atlas plan   [--config atlas.config.ts] [--state <name>]\n  atlas run    [--config atlas.config.ts] [--mode fast|showcase] [--workers n] [--state <name>]\n               [--seed <name>]... [--paths id,id] [--shard i/n] [--rerun-failed | --reuse <run-dir>]\n               [--no-retry] [--output <dir>]\n  atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...\n  atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]\n  atlas server [--data <dir>] [--port 8080] [--store <url>]...   one Atlas node: API, projects and client\n  atlas client build [--no-data] [--out <dir>]                    build the project-agnostic Atlas client\n  atlas dev    [--port 5180]                                     develop the Atlas server and client on one host\n  atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)\n  atlas report publish|stream|status|merge|doctor|policy \u2026       layered evidence for any kind of spec (atlas report --help)\n\n  --workers       path attempts that run at once (default: one per CPU, capped by the driver)\n  --seed          only paths that start from this seed (\"start\" for paths setup starts); repeatable\n  --shard 2/4     run the second quarter of the plan; merge the shards' runs afterwards\n  --rerun-failed  keep the newest run's passed paths and run only the rest\n";
+/** Runs `atlas` with `argv` (default: the process arguments) and returns the exit code. Throws for a command that is wrong, which the `atlas` binary reports as a message and exit code 2. */
+export declare function main(argv?: string[]): Promise<number>;

package/dist/core/src/cli.js

@@ -1,3 +1,13 @@
+/**
+ * @module The `atlas` command
+ *
+ * Dispatches `atlas <command>`: the statechart commands (`lint`, `plan`, `run`, `merge`, `export`) and, loaded on demand so
+ * they cost nothing otherwise, `serve`, `dev`, `init` and `report`. Statechart configuration is `atlas.config.ts` (see
+ * `defineConfig`). A command that is wrong prints a message and exits 2; a plan, lint or run that finds problems exits 1.
+ *
+ * @see docs/statecharts.md
+ * @see docs/reference/cli.md
+ */
 import { writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -8,7 +18,8 @@ import { toMarkdown } from './report/markdown.js';
 import { composeCharts } from './spec/compose.js';
 import { loadSpecDirectory } from './spec/load.js';
 import { machineToScxml } from './spec/scxml.js';
-const USAGE = `atlas — executable statecharts
+/** The text `atlas --help` prints: every command, and the flags of the statechart commands. */
+export const USAGE = `atlas — executable statecharts
 
   atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]
   atlas plan   [--config atlas.config.ts] [--state <name>]
@@ -17,6 +28,11 @@ const USAGE = `atlas — executable statecharts
                [--no-retry] [--output <dir>]
   atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...
   atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]
+  atlas server [--data <dir>] [--port 8080] [--store <url>]...   one Atlas node: API, projects and client
+  atlas client build [--no-data] [--out <dir>]                    build the project-agnostic Atlas client
+  atlas dev    [--port 5180]                                     develop the Atlas server and client on one host
+  atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)
+  atlas report publish|stream|status|merge|doctor|policy …       layered evidence for any kind of spec (atlas report --help)
 
   --workers       path attempts that run at once (default: one per CPU, capped by the driver)
   --seed          only paths that start from this seed ("start" for paths setup starts); repeatable
@@ -69,8 +85,26 @@ async function loadConfig(file) {
         throw new Error(`${file} has no default export (use defineConfig)`);
     return { config: mod.default, base: path.dirname(absolute) };
 }
+/** Runs `atlas` with `argv` (default: the process arguments) and returns the exit code. Throws for a command that is wrong, which the `atlas` binary reports as a message and exit code 2. */
 export async function main(argv = process.argv.slice(2)) {
     const [command] = argv;
+    // Loaded on demand: lint, plan and run do not pay for the reports.
+    if (command === 'serve' || command === 'server') {
+        const { serveMain } = await import('../../server/src/main.js');
+        return serveMain(argv.slice(1), { out: text => process.stdout.write(text) });
+    }
+    if (command === 'client') {
+        const { clientMain } = await import('../../server/src/site.js');
+        return clientMain(argv.slice(1));
+    }
+    if (command === 'dev') {
+        const { devMain } = await import('../../server/src/dev.js');
+        return devMain(argv.slice(1), { out: text => process.stdout.write(text) });
+    }
+    if (command === 'init')
+        return (await import('../../reports/src/init.js')).initMain(argv.slice(1), { out: text => process.stdout.write(text) });
+    if (command === 'report')
+        return (await import('../../reports/src/report-cli.js')).runReportCommand(argv.slice(1));
     const configFile = flag(argv, 'config') ?? 'atlas.config.ts';
     const specs = flag(argv, 'specs');
     const output = flag(argv, 'output');

package/dist/core/src/config.d.ts

@@ -1,13 +1,21 @@
+import { type LiveReporterOptions } from '../../reports/src/live-reporter.js';
 import type { StateValue } from './graph.js';
 import type { Shard } from './run/execute.js';
 import type { Driver, EventMatcher, EventSource, Implementation, PrivacyRules, RunMode } from './run/types.js';
+/**
+ * Everything a project says about running its specs. `C` is the type of the driver's context
+ * (a Playwright `Page`, a model, ...), which events and states receive.
+ */
 export type AtlasConfig<C = unknown> = {
     /** The directory holding the charts (`*.scxml`, `*.machine.{json,yaml}`) and `journeys.yaml`. */
     specs: string;
+    /** Live reporting endpoint. Defaults to ATLAS_SERVER_URL when set; false disables streaming. */
+    reporting?: LiveReporterOptions | false;
     /** The chart to run; the root chart when omitted. */
     chart?: string;
     /** Where generated paths start (an XState state value); the initial state when omitted. */
     start?: StateValue;
+    /** A phrase describing `start` in reports; `The start of the chart` when omitted. */
     startLabel?: string;
     /** Only these events enter the chart from outside it. */
     entryEvents?: string[];
@@ -17,27 +25,61 @@ export type AtlasConfig<C = unknown> = {
     workers?: number;
     /** Runs once before any path: prepare what every seed relies on (reference data, config). */
     beforeRun?: () => Promise<void> | void;
+    /** The driver, or a function that creates it (called once per run, after `beforeRun`). */
     driver: Driver<C> | (() => Driver<C> | Promise<Driver<C>>);
+    /** How to make each event happen and recognise each state. */
     implementation: Implementation<C>;
     /** Where runs are written; `atlas-runs` beside the config when omitted. */
     output?: string;
+    /** Creates the business event sources for a run (called once per run; the run closes them). */
     eventSources?: () => EventSource[] | Promise<EventSource[]>;
+    /** How each business event name from `meta.events` is recognised; by default a CloudEvent whose `type` equals the name. */
     eventMatchers?: Record<string, EventMatcher>;
+    /** Extra privacy rules on top of the defaults. */
     privacy?: PrivacyRules;
     /** URLs the run will reach; checked against `privacy.allowHosts` (loopback by default). */
     targets?: string[];
+    /** Recorded in the manifest as the run's environment (`run.environment`), beside the driver name. */
     environment?: Record<string, unknown>;
+    /** How long to wait for a state to be recognised after an event, in milliseconds; 45 000 when omitted. */
     stepTimeoutMs?: number;
     /** Meta fields every state must carry (default: description). */
     requiredMeta?: string[];
 };
+/**
+ * Declares an Atlas config with types, returning it unchanged. Put it as the default export of
+ * `atlas.config.ts`; the CLI loads the file with `tsx` and defaults to `atlas.config.ts` in the
+ * current directory.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * export default defineConfig({
+ *   specs: './specs',
+ *   driver: () => functionDriver(() => new TodoModel()),
+ *   implementation: {
+ *     events: { 'Adds a todo': { kind: 'user', how: 'Calls add().', run: async (model) => model.add('x') } },
+ *     states: { 'No todos': { recognize: async (model) => ({ matched: model.count === 0, signals: [] }) } }
+ *   }
+ * });
+ */
 export declare function defineConfig<C>(config: AtlasConfig<C>): AtlasConfig<C>;
-/** Narrow what a config runs from the command line. */
+/** Overrides of a config that the command line can give. */
 export type PrepareOptions = {
     /** Scope the run to this state instead of the config's. */
     state?: string;
 };
-/** Load, lint and plan a config without running anything. */
+/**
+ * Loads, lints and plans a config without running anything (what `atlas lint` and `atlas plan` do).
+ *
+ * @param baseDirectory what a relative `config.specs` resolves against.
+ * @returns the loaded `bundle`; `lint` (findings, composition and graph, including `implemented`
+ *   findings for what the implementation lacks); the run's `scope`; the `plan` (paths, journeys, seeds,
+ *   `unreachable`); and the resolved `specs` directory.
+ * @throws Error when the specs cannot be loaded or composed, when a seed's `shows` is not active where
+ *   it starts, or when a seed's `for` names an event no state handles. Lint findings are returned,
+ *   not thrown.
+ */
 export declare function prepare<C>(config: AtlasConfig<C>, baseDirectory?: string, options?: PrepareOptions): {
     bundle: import('./index.js').SpecBundle;
     lint: {
@@ -82,22 +124,43 @@ export declare function prepare<C>(config: AtlasConfig<C>, baseDirectory?: strin
     };
     specs: string;
 };
+/** The options of `atlas run` that `runConfig` accepts; each overrides the config's own setting. */
 export type RunCommandOptions = PrepareOptions & {
+    /** `fast` when omitted. */
     mode?: RunMode;
+    /** Override live reporting. Defaults to config.reporting or ATLAS_SERVER_URL. */
+    reporting?: LiveReporterOptions | false;
     /** Only these paths, by id. */
     paths?: string[];
     /** Only paths that start from these seeds ("start" for paths that `setup` starts). */
     seeds?: string[];
+    /** Whether a failed path runs again to tell flaky from broken; true unless `false`. */
     retry?: boolean;
+    /** Where the run is written; the config's `output`, else `atlas-runs`. */
     output?: string;
+    /** Path attempts at once; the config's `workers`, else one per CPU, always capped by the driver. */
     workers?: number;
     /** Run one shard of the plan; `atlas merge` composes the shards. */
     shard?: Shard;
     /** Keep the passed paths of this run (or the newest run, with "latest") and run the rest. */
     reuse?: string;
+    /** Receives progress lines; stdout when omitted. */
     log?: (line: string) => void;
 };
-/** Run a config end to end and write its manifest and reports. */
+/**
+ * Runs a config end to end and writes the run (manifest, reports, media) under its output
+ * directory, like `atlas run`.
+ *
+ * Refuses to start (throws) when the spec has any structural lint finding (everything but missing
+ * implementations, which just block paths) or when a `targets` URL is not on the privacy allow-list.
+ * Then it calls `beforeRun`, creates the driver and runs the planned paths (filtered by
+ * `options.paths`/`seeds`/`shard`, reusing earlier passes when `options.reuse` is set).
+ *
+ * @returns what `runPaths` returns: the run directory, the manifest and `ok` (false if any path
+ *   failed or the privacy scan found something).
+ * @throws Error also when `reuse` names a run with no outcomes or there is no earlier run for `latest`.
+ * @see docs/statecharts.md
+ */
 export declare function runConfig<C>(config: AtlasConfig<C>, options?: RunCommandOptions, baseDirectory?: string): Promise<{
     runDir: string;
     manifest: {
@@ -202,6 +265,7 @@ export declare function runConfig<C>(config: AtlasConfig<C>, options?: RunComman
             key: string;
             name: string;
             kind: import('./plan.js').PlannedPath["kind"];
+            progress?: "queued" | "running" | "complete";
             status: import('./index.js').Status;
             attempts: {
                 status: "passed" | "failed";
@@ -285,7 +349,15 @@ export declare function runConfig<C>(config: AtlasConfig<C>, options?: RunComman
     };
     ok: boolean;
 }>;
-/** Compose runs of a config (its shards, or a rerun and the run before it) into one run. */
+/**
+ * Composes runs of a config (its shards, or a rerun and the run before it) into one new run
+ * under the output directory, like `atlas merge`. The plan is recomputed from the config, so the runs
+ * must come from the same specs, implementation and seeds.
+ *
+ * @param runDirs the run directories to compose; later ones win when two ran the same path.
+ * @returns what `mergeRuns` returns: the new run directory, its manifest and `ok`.
+ * @throws Error when a run directory has no `outcomes.json`.
+ */
 export declare function mergeConfigRuns<C>(config: AtlasConfig<C>, runDirs: string[], options?: PrepareOptions & {
     output?: string;
 }, baseDirectory?: string): {
@@ -392,6 +464,7 @@ export declare function mergeConfigRuns<C>(config: AtlasConfig<C>, runDirs: stri
             key: string;
             name: string;
             kind: import('./plan.js').PlannedPath["kind"];
+            progress?: "queued" | "running" | "complete";
             status: import('./index.js').Status;
             attempts: {
                 status: "passed" | "failed";

package/dist/core/src/config.js

@@ -1,14 +1,57 @@
+/**
+ * @module Config and programmatic API
+ *
+ * The user-facing entry point: `defineConfig` types a project's `atlas.config.ts`, and `prepare`,
+ * `runConfig` and `mergeConfigRuns` are the programmatic equivalents of `atlas lint`/`plan`, `atlas
+ * run` and `atlas merge`. They wire the pieces together (load specs, lint, scope, plan, run) and add
+ * no behaviour of their own beyond validating the config against the spec. Relative paths in a config
+ * resolve against the `baseDirectory` argument (the config file's directory when called by the CLI).
+ *
+ * @see docs/statecharts.md
+ */
 import { availableParallelism } from 'node:os';
 import path from 'node:path';
+import { createLiveReporter } from '../../reports/src/live-reporter.js';
+import { httpStore } from '../../reports/src/http-store.js';
+import { publishChecks } from '../../reports/src/publish-checks.js';
+import { publishRunBundle } from '../../reports/src/run-bundle.js';
+import { checksFromManifest } from '../../reports/src/ingest.js';
 import { lintBundle } from './lint.js';
 import { chartScope, planChart } from './plan.js';
 import { assertAllowedTarget, mergePrivacy } from './privacy.js';
 import { latestRun, mergeRuns, readOutcomes, runPaths, shardPaths } from './run/execute.js';
 import { loadSpecDirectory } from './spec/load.js';
+/**
+ * Declares an Atlas config with types, returning it unchanged. Put it as the default export of
+ * `atlas.config.ts`; the CLI loads the file with `tsx` and defaults to `atlas.config.ts` in the
+ * current directory.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * export default defineConfig({
+ *   specs: './specs',
+ *   driver: () => functionDriver(() => new TodoModel()),
+ *   implementation: {
+ *     events: { 'Adds a todo': { kind: 'user', how: 'Calls add().', run: async (model) => model.add('x') } },
+ *     states: { 'No todos': { recognize: async (model) => ({ matched: model.count === 0, signals: [] }) } }
+ *   }
+ * });
+ */
 export function defineConfig(config) {
     return config;
 }
-/** Load, lint and plan a config without running anything. */
+/**
+ * Loads, lints and plans a config without running anything (what `atlas lint` and `atlas plan` do).
+ *
+ * @param baseDirectory what a relative `config.specs` resolves against.
+ * @returns the loaded `bundle`; `lint` (findings, composition and graph, including `implemented`
+ *   findings for what the implementation lacks); the run's `scope`; the `plan` (paths, journeys, seeds,
+ *   `unreachable`); and the resolved `specs` directory.
+ * @throws Error when the specs cannot be loaded or composed, when a seed's `shows` is not active where
+ *   it starts, or when a seed's `for` names an event no state handles. Lint findings are returned,
+ *   not thrown.
+ */
 export function prepare(config, baseDirectory = process.cwd(), options = {}) {
     const specs = path.resolve(baseDirectory, config.specs);
     const bundle = loadSpecDirectory(specs);
@@ -60,7 +103,20 @@ const contextOf = (config, prepared) => ({
     ...(config.privacy ? { privacy: config.privacy } : {}),
     ...(config.environment ? { environment: config.environment } : {})
 });
-/** Run a config end to end and write its manifest and reports. */
+/**
+ * Runs a config end to end and writes the run (manifest, reports, media) under its output
+ * directory, like `atlas run`.
+ *
+ * Refuses to start (throws) when the spec has any structural lint finding (everything but missing
+ * implementations, which just block paths) or when a `targets` URL is not on the privacy allow-list.
+ * Then it calls `beforeRun`, creates the driver and runs the planned paths (filtered by
+ * `options.paths`/`seeds`/`shard`, reusing earlier passes when `options.reuse` is set).
+ *
+ * @returns what `runPaths` returns: the run directory, the manifest and `ok` (false if any path
+ *   failed or the privacy scan found something).
+ * @throws Error also when `reuse` names a run with no outcomes or there is no earlier run for `latest`.
+ * @see docs/statecharts.md
+ */
 export async function runConfig(config, options = {}, baseDirectory = process.cwd()) {
     const prepared = prepare(config, baseDirectory, options);
     const structural = prepared.lint.findings.filter((f) => f.rule !== 'implemented');
@@ -78,22 +134,59 @@ export async function runConfig(config, options = {}, baseDirectory = process.cw
     const reused = reuseDir ? readOutcomes(reuseDir) : null;
     if (options.reuse && !reused)
         throw new Error(`There is no earlier run to reuse${reuseDir ? ` at ${reuseDir}` : ''}`);
-    return runPaths({
-        ...contextOf(config, prepared),
-        paths,
-        driver,
-        mode: options.mode ?? 'fast',
-        outputRoot,
-        ...(options.retry === undefined ? {} : { retry: options.retry }),
-        ...(config.stepTimeoutMs === undefined ? {} : { stepTimeoutMs: config.stepTimeoutMs }),
-        eventSources: config.eventSources ? await config.eventSources() : [],
-        workers: options.workers ?? config.workers ?? availableParallelism(),
-        ...(options.shard ? { shard: options.shard } : {}),
-        ...(reused && reuseDir ? { reuse: { runDir: reuseDir, outcomes: reused.outcomes } } : {}),
-        ...(options.log ? { log: options.log } : {})
-    });
+    const requestedReporting = options.reporting ?? config.reporting ?? (process.env.ATLAS_SERVER_URL ? { url: process.env.ATLAS_SERVER_URL, token: process.env.ATLAS_PUBLISH_TOKEN ?? process.env.ATLAS_TOKEN } : undefined);
+    const reporting = requestedReporting ? { ...requestedReporting, project: requestedReporting.project ?? process.env.ATLAS_PROJECT, token: requestedReporting.token ?? process.env.ATLAS_PUBLISH_TOKEN ?? process.env.ATLAS_TOKEN } : undefined;
+    let live;
+    const onProgress = reporting ? (manifest) => {
+        if (!manifest.privacy.passed)
+            return;
+        live ??= createLiveReporter({ producer: process.env.ATLAS_PRODUCER ?? 'atlas-statecharts', title: `${prepared.scope.chart} · ${options.mode ?? 'fast'}`,
+            plannedChecks: paths.length, environment: process.env.ATLAS_ENVIRONMENT ?? 'desktop-web', branch: manifest.run.branch ?? undefined, sha: manifest.run.commit ?? undefined }, reporting);
+        const ingested = checksFromManifest(manifest);
+        ingested.checks.forEach((check, index) => {
+            if (manifest.paths[index]?.progress === 'queued' && !manifest.run.finishedAt)
+                return;
+            live.check({ ...check, steps: check.steps?.slice(-20).map(step => ({ name: step.name, status: step.status })) });
+        });
+    } : undefined;
+    try {
+        const outcome = await runPaths({
+            ...contextOf(config, prepared),
+            paths,
+            driver,
+            mode: options.mode ?? 'fast',
+            outputRoot,
+            ...(options.retry === undefined ? {} : { retry: options.retry }),
+            ...(config.stepTimeoutMs === undefined ? {} : { stepTimeoutMs: config.stepTimeoutMs }),
+            eventSources: config.eventSources ? await config.eventSources() : [],
+            workers: options.workers ?? config.workers ?? availableParallelism(),
+            ...(options.shard ? { shard: options.shard } : {}),
+            ...(reused && reuseDir ? { reuse: { runDir: reuseDir, outcomes: reused.outcomes } } : {}),
+            ...(options.log ? { log: options.log } : {}), ...(onProgress ? { onProgress } : {})
+        });
+        await live?.finish(outcome.manifest.privacy.passed ? 'completed' : 'interrupted', outcome.manifest.privacy.passed ? undefined : 'Run failed its privacy scan; unsafe progress was withheld.');
+        if (reporting && outcome.manifest.privacy.passed) {
+            const store = httpStore({ url: reporting.url, project: reporting.project, token: reporting.token });
+            await publishChecks(store, { producer: process.env.ATLAS_PRODUCER ?? 'atlas-statecharts', environment: process.env.ATLAS_ENVIRONMENT ?? 'desktop-web',
+                branch: outcome.manifest.run.branch, sha: outcome.manifest.run.commit, recordedAtMs: Math.max(Date.now(), (live?.finishedAtMs ?? 0) + 1), checks: checksFromManifest(outcome.manifest).checks.map(check => ({ ...check, measurements: [...check.measurements] })) });
+            await publishRunBundle(store, outcome.runDir);
+        }
+        return outcome;
+    }
+    catch (error) {
+        await live?.finish('interrupted', 'The producer exited before completing the run.').catch(() => { });
+        throw error;
+    }
 }
-/** Compose runs of a config (its shards, or a rerun and the run before it) into one run. */
+/**
+ * Composes runs of a config (its shards, or a rerun and the run before it) into one new run
+ * under the output directory, like `atlas merge`. The plan is recomputed from the config, so the runs
+ * must come from the same specs, implementation and seeds.
+ *
+ * @param runDirs the run directories to compose; later ones win when two ran the same path.
+ * @returns what `mergeRuns` returns: the new run directory, its manifest and `ok`.
+ * @throws Error when a run directory has no `outcomes.json`.
+ */
 export function mergeConfigRuns(config, runDirs, options = {}, baseDirectory = process.cwd()) {
     const prepared = prepare(config, baseDirectory, options);
     return mergeRuns(contextOf(config, prepared), prepared.plan.paths, runDirs.map((d) => path.resolve(d)), { outputRoot: path.resolve(baseDirectory, options.output ?? config.output ?? 'atlas-runs') });