@crvouga/atlas 0.4.0 → 0.6.0

package/dist/core/src/run/execute.js

@@ -1,3 +1,16 @@
+/**
+ * @module Path runner and manifest
+ *
+ * Runs planned paths against the product through a driver and turns what happened into a run: a
+ * directory holding `manifest.json`, `junit.xml`, `ctrf.json`, `chart.mmd`, `outcomes.json` and `media/`.
+ * The invariants: the manifest is a pure fold of the plan and the per-path outcomes in plan order (so
+ * worker scheduling, sharding and reruns never change the report); it is rewritten atomically after
+ * every path so a crash keeps what ran; a failed path is retried once, and passing the second time is
+ * `flaky`. This module is the only one that touches the driver and the file system for a run. Its
+ * outputs follow the manifest schema in `packages/schema` (`schemaVersion: 1`).
+ *
+ * @see docs/statecharts.md
+ */
 import { execSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
@@ -25,7 +38,7 @@ function specVersion(bundle) {
 const relative = (root, file) => path.relative(root, file).split(path.sep).join('/');
 const pad = (n) => String(n).padStart(2, '0');
 const sameStates = (a, b) => a.length === b.length && [...a].sort().join('|') === [...b].sort().join('|');
-/** A rough cost of a path before it has ever run: setting it up, then each step. */
+/** A rough cost in milliseconds of a path that has never run (5 s to set up, 2.5 s a step); used to order and shard paths. */
 export const estimateMs = (p) => 5_000 + 2_500 * p.steps.length;
 /**
  * The paths one shard runs: longest first onto the least loaded shard, by the plan alone, so
@@ -73,7 +86,10 @@ function copyMedia(outcome, from, to) {
         cpSync(source, path.join(to, file));
     }
 }
-/** The plan keys and outcomes a run wrote, for merging shards and reusing passed paths. */
+/**
+ * Reads the `outcomes.json` of a run directory: the run id and each finished path's outcome by key.
+ * Returns `null` when the file is missing or unreadable, never throws.
+ */
 export function readOutcomes(runDir) {
     const file = path.join(runDir, 'outcomes.json');
     if (!existsSync(file))
@@ -86,7 +102,11 @@ export function readOutcomes(runDir) {
         return null;
     }
 }
-/** How long each path took in the newest run under `outputRoot` that recorded it, by path key. */
+/**
+ * Milliseconds each path took, by path key, taken from the newest of the last 10 runs under
+ * `outputRoot` that ran it (outcomes reused from elsewhere are ignored). Empty when the directory
+ * does not exist. `runPaths` uses it to start the slowest paths first.
+ */
 export function durationHistory(outputRoot) {
     const history = {};
     if (!existsSync(outputRoot))
@@ -104,7 +124,7 @@ export function durationHistory(outputRoot) {
     }
     return history;
 }
-/** The newest run under `outputRoot` that wrote outcomes. */
+/** The directory of the newest run under `outputRoot` that wrote `outcomes.json` (run ids sort by time), or `null`. */
 export function latestRun(outputRoot) {
     if (!existsSync(outputRoot))
         return null;
@@ -114,8 +134,20 @@ export function latestRun(outputRoot) {
     return runs.length ? path.join(outputRoot, runs.at(-1)) : null;
 }
 /**
- * Fold path outcomes into the run's report, in plan order: the same plan and outcomes always give
- * the same manifest, however many workers ran them, in whatever order they finished.
+ * Folds path outcomes into the run's manifest object, in plan order: the same plan and outcomes
+ * always give the same manifest, however many workers ran them, in whatever order they finished.
+ *
+ * A state or transition is `passed` when a path reached it, `flaky` when only a flaky path did,
+ * `failed` when any failure touched it (a failed check fails its state), else `not-reached`. Reaching a
+ * state also marks its ancestors reached. The whole manifest is scanned for privacy findings, and any
+ * finding sets `privacy.passed` to false. Reads the chart files (for `specVersion`) and runs `git`
+ * in the current directory (for `commit` and `branch`, `null` when that fails). Apart from the
+ * wall-clock fields (`finishedAt`, `updatedAt`, `durationMs`) and those that depend on the working
+ * directory (`commit`, `branch`, `specDirectory`), two folds of the same outcomes are identical.
+ *
+ * @param outcomes finished or in-progress outcomes by path key; a path with none is `queued` or `running`.
+ * @param run.activePaths ids of the paths in flight; they are reported `running` and not counted complete.
+ * @param run.extra extra fields merged into `run` of the manifest (workers, shard, reused, mergedFrom).
  */
 export function buildManifest(context, paths, outcomes, run) {
     const { implementation: impl, graph, scope } = context;
@@ -406,7 +438,11 @@ function writeAtomic(file, text) {
     writeFileSync(temporary, text);
     renameSync(temporary, file);
 }
-/** Write a run's manifest, reports and outcomes; returns the manifest. */
+/**
+ * Writes a run's `junit.xml`, `ctrf.json`, `chart.mmd`, `outcomes.json` and `manifest.json` into
+ * `runDir` (each through a temporary file and a rename, so a reader never sees half a file) and returns
+ * the manifest. `outcomes.json` holds only finished paths, not those in `run.activePaths`.
+ */
 export function writeRun(runDir, context, paths, outcomes, run) {
     const manifest = buildManifest(context, paths, outcomes, run);
     writeAtomic(path.join(runDir, 'junit.xml'), toJUnit(manifest));
@@ -419,9 +455,14 @@ export function writeRun(runDir, context, paths, outcomes, run) {
 }
 const newRunId = (mode) => `${new Date().toISOString().replace(/[:.]/g, '-')}-${mode}`;
 /**
- * Compose the outcomes of several runs of the same plan (the shards of one run, or a rerun of the
- * paths that failed) into one run, folded in plan order. Media are copied in, so the merged run
- * stands on its own. Later runs win when two ran the same path.
+ * Composes the outcomes of several runs of the same plan (the shards of one run, or a rerun and
+ * the run before it) into one new run directory under `options.outputRoot`, folded in plan order. Media are
+ * copied in, so the merged run stands on its own. Later entries of `runDirs` win when two ran the same
+ * path; outcomes whose key is not in `paths` are ignored. The merged run's mode and driver name are
+ * taken from the run manifests unless `options` gives them.
+ *
+ * @returns the new `runDir`, its `manifest`, and `ok` (privacy passed and no path failed).
+ * @throws Error when a run directory has no `outcomes.json`.
  */
 export function mergeRuns(context, paths, runDirs, options) {
     const outcomes = new Map();
@@ -461,12 +502,22 @@ export function mergeRuns(context, paths, runDirs, options) {
     return { runDir, manifest, ok: manifest.privacy.passed && manifest.paths.every((r) => r.status !== 'failed') };
 }
 /**
- * Run planned paths against a system through a driver. Paths start from their seed (or the
- * implementation's `setup`) and run on a pool of workers, longest first, each attempt in its own
- * driver context; every state is recognised from the outside after every step; a failed path is
- * retried once to tell flaky from broken. The manifest is rewritten as each path finishes, from
- * all outcomes so far in plan order, so a crash keeps what ran and the order paths finished in
- * never changes the report.
+ * Runs planned paths against a system through a driver and writes the run to
+ * `<outputRoot>/<timestamp>-<mode>/`. Paths start from their seed (or the implementation's
+ * `setup`) and run on a pool of workers, longest first (by earlier timings, else `estimateMs`),
+ * each attempt in its own driver context; every state is recognised from the outside after every step;
+ * a failed path is retried once to tell flaky from broken. The manifest is rewritten as each path
+ * finishes, from all outcomes so far in plan order, so a crash keeps what ran and the order paths
+ * finished in never changes the report.
+ *
+ * Workers are capped by `driver.concurrency` (1 if the driver gives none) and by the number of paths.
+ * Without `implementation.correlate`, a run on several workers reports business events as "no
+ * signal" rather than guess which attempt they belong to. While it runs it installs
+ * `uncaughtException` and `unhandledRejection` handlers that log and swallow stray errors from
+ * drivers, and removes them when it ends. Passed paths of `options.reuse` are kept instead of re-run.
+ *
+ * @returns the run directory, the final manifest, and `ok` (privacy passed and no path failed).
+ * @see docs/statecharts.md
  */
 export async function runPaths(options) {
     const { driver, implementation: impl, graph, scope } = options;
@@ -840,7 +891,8 @@ export async function runPaths(options) {
         }
     });
     function publish() {
-        writeRun(runDir, options, options.paths, new Map([...outcomes, ...activeOutcomes]), runInfo(false));
+        const snapshot = writeRun(runDir, options, options.paths, new Map([...outcomes, ...activeOutcomes]), runInfo(false));
+        options.onProgress?.(snapshot);
     }
     const history = durationHistory(options.outputRoot);
     const cost = (p) => history[p.key] ?? estimateMs(p);
@@ -848,7 +900,7 @@ export async function runPaths(options) {
     if (reused.size)
         log(`Reusing ${reused.size} passed path(s) from ${path.basename(options.reuse.runDir)}`);
     log(`Running ${queue.length} path(s) on ${workers} worker(s)`);
-    writeRun(runDir, options, options.paths, outcomes, runInfo(false));
+    options.onProgress?.(writeRun(runDir, options, options.paths, outcomes, runInfo(false)));
     // A driver can throw outside any awaited call (a message for a context that just closed); it
     // belongs to one attempt, so it is logged and the run goes on instead of the process dying.
     const stray = (error) => log(`  (ignored an error thrown outside any step: ${(error instanceof Error ? error.message : String(error)).split('\n')[0]})`);
@@ -873,5 +925,6 @@ export async function runPaths(options) {
     await driver.dispose?.();
     await Promise.all(sources.map((s) => s.close?.()));
     const manifest = writeRun(runDir, options, options.paths, outcomes, runInfo(true));
+    options.onProgress?.(manifest);
     return { runDir, manifest, ok: manifest.privacy.passed && manifest.paths.every((r) => r.status !== 'failed') };
 }

package/dist/core/src/run/frames.d.ts

@@ -1,4 +1,5 @@
 import type { Clip } from './types.js';
+/** Options for `recordFrames`. */
 export type FrameRecorderOptions = {
     /** The image format `capture` returns (default png). */
     extension?: 'png' | 'jpg';
@@ -6,10 +7,18 @@ export type FrameRecorderOptions = {
     maxFps?: number;
 };
 /**
- * Record a clip from any driver that can take a screenshot: capture frames back to back while the
- * step runs, then encode them with FFmpeg as H.264 MP4 at their real timing. Drivers without a
- * native screen recorder (Bun WebView, WebDriver) use it; it needs `ffmpeg` on the PATH and
- * returns no clip without it.
+ * Starts recording a clip from any driver that can take a screenshot: capture frames back to back
+ * while the step runs, then encode them with FFmpeg as H.264 MP4 at their real timing. Drivers
+ * without a native screen recorder (Bun WebView, WebDriver) use it; it needs `ffmpeg` on the PATH.
+ *
+ * Capturing starts immediately and continues until `stop` is called. A `capture` that throws or
+ * returns no bytes just skips that frame. The returned `stop(output)` ends capture, writes the MP4 to
+ * `output` and resolves to the clip (`durationMs` is wall-clock time since the call), or to `null`
+ * when no frame was captured or FFmpeg is missing or fails. It writes no poster. Frames and the
+ * FFmpeg frame list are left in `workDirectory`.
+ *
+ * @param capture returns one screenshot as encoded image bytes in `options.extension`'s format.
+ * @param workDirectory where the frames are written; created if missing.
  */
 export declare function recordFrames(capture: () => Promise<Uint8Array>, workDirectory: string, options?: FrameRecorderOptions): Promise<{
     stop(output: string): Promise<Clip | null>;

package/dist/core/src/run/frames.js

@@ -1,11 +1,26 @@
+/**
+ * @module Frame-based clip recorder
+ *
+ * Builds a video clip for drivers that can only take screenshots: frames are captured repeatedly while
+ * a step runs and encoded afterwards with FFmpeg at their real timing. It owns no driver logic; the
+ * caller supplies the capture function. A missing or failing `ffmpeg` produces no clip, never an error.
+ */
 import { spawnSync } from 'node:child_process';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 /**
- * Record a clip from any driver that can take a screenshot: capture frames back to back while the
- * step runs, then encode them with FFmpeg as H.264 MP4 at their real timing. Drivers without a
- * native screen recorder (Bun WebView, WebDriver) use it; it needs `ffmpeg` on the PATH and
- * returns no clip without it.
+ * Starts recording a clip from any driver that can take a screenshot: capture frames back to back
+ * while the step runs, then encode them with FFmpeg as H.264 MP4 at their real timing. Drivers
+ * without a native screen recorder (Bun WebView, WebDriver) use it; it needs `ffmpeg` on the PATH.
+ *
+ * Capturing starts immediately and continues until `stop` is called. A `capture` that throws or
+ * returns no bytes just skips that frame. The returned `stop(output)` ends capture, writes the MP4 to
+ * `output` and resolves to the clip (`durationMs` is wall-clock time since the call), or to `null`
+ * when no frame was captured or FFmpeg is missing or fails. It writes no poster. Frames and the
+ * FFmpeg frame list are left in `workDirectory`.
+ *
+ * @param capture returns one screenshot as encoded image bytes in `options.extension`'s format.
+ * @param workDirectory where the frames are written; created if missing.
  */
 export async function recordFrames(capture, workDirectory, options = {}) {
     mkdirSync(workDirectory, { recursive: true });

package/dist/core/src/run/http.d.ts

@@ -1,23 +1,40 @@
+/**
+ * @module HTTP driver
+ *
+ * A driver (and a bare client) for acting on or observing a system over HTTP, with no browser or
+ * device: a fetch with a base URL, a cookie jar and timeline logging. It is the fastest driver and
+ * runs any number of attempts side by side, each with its own cookie jar. Uses the global `fetch`.
+ */
 import type { Driver, Timeline } from './types.js';
+/** The response of an `HttpClient` call; the body is read in full. */
 export type HttpResponse = {
     status: number;
+    /** True for a 2xx status. A non-2xx status does not throw. */
     ok: boolean;
     headers: Headers;
+    /** The body as text. */
     text: string;
+    /** The body parsed as JSON when the content type is JSON and it parses; `null` otherwise (also for a literal JSON `null`). */
     json: unknown;
 };
+/** Per-call options of an `HttpClient`. */
 export type HttpRequestOptions = {
+    /** A string is sent as is; anything else is sent as JSON with a `content-type: application/json` header. */
     body?: unknown;
+    /** Added to the client's headers for this call and overriding them (and the cookie header) on conflict. */
     headers?: Record<string, string>;
     /** What the timeline says this call was for; `METHOD /path` when omitted. */
     label?: string;
 };
 /** What every event and recogniser receives from an HTTP client: a fetch with a base URL and a cookie jar. */
 export type HttpClient = {
+    /** The URL that request paths are resolved against with `new URL(path, baseUrl)`: a path starting with `/` replaces any path in the base URL. */
     baseUrl: string;
     /** Sent with every request; set an `authorization` header here after signing in. */
     headers: Record<string, string>;
+    /** Cookie name to value, stored from `Set-Cookie` responses and sent back on every request. Only the name and value are kept (no expiry, path or domain handling). */
     cookies: Map<string, string>;
+    /** Sends a request. Rejects on a network error or timeout; resolves for any HTTP status. Each call adds a `system` entry (method, path, status, never bodies) to the timeline. */
     request(method: string, path: string, options?: HttpRequestOptions): Promise<HttpResponse>;
     get(path: string, options?: HttpRequestOptions): Promise<HttpResponse>;
     post(path: string, body?: unknown, options?: HttpRequestOptions): Promise<HttpResponse>;
@@ -25,17 +42,33 @@ export type HttpClient = {
     patch(path: string, body?: unknown, options?: HttpRequestOptions): Promise<HttpResponse>;
     delete(path: string, options?: HttpRequestOptions): Promise<HttpResponse>;
 };
+/** Options for `httpDriver` and `httpClient`. */
 export type HttpDriverOptions = {
+    /** The driver's name and the `source` recorded on timeline entries; `http` when omitted. */
     name?: string;
+    /** Headers sent with every request. */
     headers?: Record<string, string>;
     /** Per request, in milliseconds (default 30 000). */
     timeoutMs?: number;
 };
+/**
+ * Creates an `HttpClient` that logs each call to `timeline`. Use it directly when you need a client
+ * outside a driver; `httpDriver` creates one per path attempt.
+ *
+ * @param baseUrl the URL request paths are resolved against.
+ */
 export declare function httpClient(baseUrl: string, timeline: Timeline, options?: HttpDriverOptions): HttpClient;
 /**
  * The fastest driver: a client of an HTTP API, with no browser or device. Use it for actors that
  * only talk to the system (a partner webhook, an operator API, a back office job) or to drive a
  * whole chart at the API level. Each path attempt gets a fresh cookie jar; every call is logged to
- * the step's timeline (method, path, status; never bodies).
+ * the step's timeline (method, path, status; never bodies). Has no screenshots or clips, and no limit on
+ * concurrent attempts.
+ *
+ * @param baseUrl the API's base URL, or a function returning it (called for each attempt).
+ *
+ * @example
+ * const driver = httpDriver('http://127.0.0.1:4000', { headers: { 'x-test': '1' } });
+ * // events then receive an HttpClient: run: (api) => api.post('/orders', { sku: 'A1' })
  */
 export declare function httpDriver(baseUrl: string | (() => string | Promise<string>), options?: HttpDriverOptions): Driver<HttpClient>;

package/dist/core/src/run/http.js

@@ -8,6 +8,12 @@ function parseBody(text, contentType) {
         return null;
     }
 }
+/**
+ * Creates an `HttpClient` that logs each call to `timeline`. Use it directly when you need a client
+ * outside a driver; `httpDriver` creates one per path attempt.
+ *
+ * @param baseUrl the URL request paths are resolved against.
+ */
 export function httpClient(baseUrl, timeline, options = {}) {
     const source = options.name ?? 'http';
     const client = {
@@ -55,7 +61,14 @@ export function httpClient(baseUrl, timeline, options = {}) {
  * The fastest driver: a client of an HTTP API, with no browser or device. Use it for actors that
  * only talk to the system (a partner webhook, an operator API, a back office job) or to drive a
  * whole chart at the API level. Each path attempt gets a fresh cookie jar; every call is logged to
- * the step's timeline (method, path, status; never bodies).
+ * the step's timeline (method, path, status; never bodies). Has no screenshots or clips, and no limit on
+ * concurrent attempts.
+ *
+ * @param baseUrl the API's base URL, or a function returning it (called for each attempt).
+ *
+ * @example
+ * const driver = httpDriver('http://127.0.0.1:4000', { headers: { 'x-test': '1' } });
+ * // events then receive an HttpClient: run: (api) => api.post('/orders', { sku: 'A1' })
  */
 export function httpDriver(baseUrl, options = {}) {
     return {

package/dist/core/src/run/types.d.ts

@@ -1,29 +1,56 @@
+/**
+ * @module Run types and function driver
+ *
+ * The contracts between a run and the things it drives: `Driver` (owns the system under test for one
+ * path attempt), `Implementation` (how each event is made to happen and each state recognised), `Seed`,
+ * event sources and privacy rules, plus the status vocabulary and `Timeline`. These shapes are what
+ * integrators write against, so they change only by adding optional fields. Also holds
+ * `functionDriver`, the simplest complete driver.
+ *
+ * @see docs/statecharts.md
+ */
 import type { CloudEvent } from '../events/cloudevents.js';
 import type { StateValue } from '../graph.js';
 import type { PlannedPath } from '../plan.js';
+/** `fast` runs without pacing and takes screenshots only; `showcase` paces steps like a person and records a clip of every transition. */
 export type RunMode = 'fast' | 'showcase';
+/** The result of a path, state, transition or journey: `flaky` passed only on the retry; `not-reached` was never run, was blocked, or has no covering path. */
 export type Status = 'passed' | 'failed' | 'flaky' | 'not-reached';
+/** Who or what makes an event happen: a `user` action, a `system` call, the passing of `time`, or a `hand-off` from a child chart (inserted by the planner, usually a no-op). */
 export type EventKind = 'user' | 'system' | 'time' | 'hand-off';
 /** `client` names which client's screen it is in a multi-client run; `also` holds the other clients' screens at the same moment. */
 export type Image = {
+    /** Path to the PNG. A driver returns an absolute path; in a manifest it is relative to the run directory. */
     png: string;
+    /** Path to a WebP thumbnail, when one was made. */
     webp?: string;
     client?: string;
     also?: Image[];
 };
+/** A recorded video of one transition. */
 export type Clip = {
+    /** Path to the MP4 (relative to the run directory in a manifest). */
     video: string;
+    /** Path to a poster image, when one was made. */
     poster?: string;
     durationMs: number;
+    /** The client whose screen was recorded, in a multi-client run. */
     client?: string;
 };
+/** One thing that happened during a step, which becomes a caption on the step's clip. */
 export type TimelineEntry = {
+    /** Milliseconds since the step began (see `Timeline.restart`). */
     atMs: number;
+    /** What kind of thing happened. */
     kind: 'tap' | 'type' | 'system' | 'screen' | 'toast' | 'note' | 'time' | 'notification';
+    /** The caption. */
     label: string;
+    /** For a tap, where it landed (page pixels for the Playwright driver). */
     x?: number;
     y?: number;
+    /** For typing, what was typed; shown in the caption. */
     text?: string;
+    /** For a system call, what it was (never bodies). */
     system?: {
         source?: string;
         endpoint?: string;
@@ -40,26 +67,37 @@ type TimelineState = {
 };
 /**
  * What a step records while it runs: taps, typing, system calls, the screen change. `for(client)`
- * returns a view onto the same timeline that tags every entry with that client.
+ * returns a view onto the same timeline that tags every entry with that client. The runner restarts
+ * it at the start of every step, so entries are relative to the step they belong to.
  */
 export declare class Timeline {
     private readonly state;
+    /** The client this view tags entries with; `undefined` on the root timeline. */
     readonly client: string | undefined;
     constructor(state?: TimelineState, client?: string);
+    /** Every entry added since the last `restart`, in order, shared by all views of the timeline. */
     get entries(): TimelineEntry[];
+    /** Clears the entries and makes now the origin for `atMs`. */
     restart(): void;
+    /** Appends an entry stamped with the time since the origin, and with this view's client when it has one. */
     add(entry: Omit<TimelineEntry, 'atMs'>): void;
+    /** A view of the same timeline that tags what it adds with `client`. */
     for(client: string): Timeline;
 }
+/** What a state recogniser found. */
 export type RecognizerResult = {
+    /** Whether the state is showing. */
     matched: boolean;
+    /** What was looked at, shown to explain a failure. `expected` is `visible` or `hidden`. */
     signals: {
         signal: string;
         expected: 'visible' | 'hidden' | string;
         visible: boolean;
     }[];
 };
+/** The result of one of a state's `meta.checks`; a failed check fails the state. */
 export type CheckResult = {
+    /** The check statement, quoted from the spec. */
     check: string;
     passed: boolean;
     expected?: string;
@@ -87,7 +125,12 @@ export type Focus = {
  * required; media hooks are used when present. `combineDrivers` runs several at once.
  */
 export type Driver<C> = {
+    /** Shown in reports as the driver the run used. */
     name: string;
+    /**
+     * Creates a fresh context for one attempt of one path. `attempt` is 1, or 2 for the retry;
+     * `directory` is a scratch directory for this attempt; the driver should log what it does to `timeline`.
+     */
     open(input: {
         path: PlannedPath;
         attempt: number;
@@ -95,6 +138,10 @@ export type Driver<C> = {
         directory: string;
         timeline: Timeline;
     }): Promise<C>;
+    /**
+     * Releases the context. `traceFile` is where a trace may be written when `failed`; return the path
+     * actually written as `trace` (or one per client as `traces`) to attach it to the report.
+     */
     close(ctx: C, input: {
         failed: boolean;
         traceFile: string;
@@ -124,10 +171,12 @@ export type Driver<C> = {
      * single device is not). Runs use at most this many workers; 1 when omitted.
      */
     concurrency?: number;
+    /** Releases what is shared by all contexts (a browser, a server); called once after the last path. */
     dispose?(): Promise<void>;
 };
 /** How one event is made to happen. Keyed by the event's exact name in the spec. */
 export type EventImplementation<C> = {
+    /** Who makes the event happen; recorded with the event in the manifest. */
     kind: EventKind;
     /** The client that does it, in a multi-client run: its screen is recorded for the clip. */
     client?: string;
@@ -135,12 +184,14 @@ export type EventImplementation<C> = {
     how: string;
     /** Test data the event needs before the path starts (a condition modelled as an event). */
     prepare?(ctx: C, tools: StepTools): Promise<void>;
+    /** Makes the event happen. The runner then waits for the target state to be recognised, so `run` does not need to wait for it; it should throw only when the event cannot be done. */
     run(ctx: C, tools: StepTools): Promise<void>;
     /** Set when the event cannot be triggered reliably yet: the path stops before it. */
     blocked?: string;
 };
 /** How one state is recognised from the outside, and what is checked there. */
 export type StateImplementation<C> = {
+    /** Looks at the system from the outside and says whether the state is showing. Called repeatedly (with growing pauses, until `stepTimeoutMs`) while the runner waits for the state, so it must be cheap and side-effect free. */
     recognize(ctx: C): Promise<RecognizerResult>;
     /** The client whose screen shows it, in a multi-client run: that screen is the screenshot. */
     client?: string;
@@ -152,6 +203,7 @@ export type StateImplementation<C> = {
     lookIn?(ctx: C): Promise<void>;
     /** Within-state actions after the screenshot (dismiss a success message). */
     settle?(ctx: C): Promise<void>;
+    /** Results for the state's `meta.checks`, evaluated once the state is recognised. */
     checks?(ctx: C): Promise<CheckResult[]>;
 };
 /**
@@ -184,8 +236,15 @@ export type Seed<C> = {
     /** Set when the configuration cannot be seeded yet: paths start from another seed. */
     blocked?: string;
 };
+/**
+ * How a driver makes each event of the spec happen and recognises each state: everything the charts
+ * do not say. Events and states are keyed by their exact names in the spec; only leaf states need a
+ * recogniser.
+ */
 export type Implementation<C> = {
+    /** By event name; an event with no entry is reported as blocked. */
     events: Record<string, EventImplementation<C>>;
+    /** By state name; only leaf states need one. */
     states: Record<string, StateImplementation<C>>;
     /**
      * Named seeds: configurations paths can start from. Journeys are cut at every seeded
@@ -207,13 +266,16 @@ export type Implementation<C> = {
 };
 /** Where business events come from: a CloudEvents endpoint, a log, a message queue. */
 export type EventSource = {
+    /** Identifies the source; a name starting with `log:` marks a log file, anything else counts as a CloudEvents source. */
     name: string;
     /** Where "now" is in the source; `collect` returns what arrived after this mark. */
     mark(): unknown;
+    /** Returns what arrived since `mark` (everything when omitted): CloudEvents and/or raw log text. */
     collect(mark?: unknown): Promise<{
         events: CloudEvent[];
         text?: string;
     }>;
+    /** Releases the source; called when the run ends. */
     close?(): Promise<void>;
 };
 /** How a business event named in `meta.events` is recognised in what a source collected. */
@@ -222,6 +284,7 @@ export type EventMatcher = {
 } | {
     pattern: RegExp;
 } | ((events: CloudEvent[], text: string) => boolean);
+/** Rules for what may appear on screen and in a manifest. They extend the defaults (see `DEFAULT_PRIVACY`) except `allowHosts`, which replaces them. */
 export type PrivacyRules = {
     /** Patterns that must never appear on screen or in a manifest. */
     deny?: {
@@ -234,8 +297,18 @@ export type PrivacyRules = {
     allowHosts?: string[];
 };
 /**
- * A driver for anything you can reach from Node: a domain model, an API client, a CLI. `create`
- * returns a fresh context per path attempt; recognisers and events work on it directly.
+ * A driver for anything you can reach from code: a domain model, an API client, a CLI. `create`
+ * returns a fresh context per path attempt; recognisers and events work on it directly. It takes
+ * no screenshots or clips, and any number of attempts can run side by side unless `concurrency` says otherwise.
+ *
+ * @param create builds the context for one attempt; it may be async.
+ * @param options.name the driver's name in reports; `function` when omitted.
+ * @param options.dispose called with the context when the attempt ends.
+ * @param options.concurrency how many contexts may be open at once; unlimited when omitted.
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const driver = functionDriver(() => new TodoModel());
  */
 export declare function functionDriver<C>(create: (input: {
     path: PlannedPath;

package/dist/core/src/run/types.js

@@ -1,31 +1,47 @@
 /**
  * What a step records while it runs: taps, typing, system calls, the screen change. `for(client)`
- * returns a view onto the same timeline that tags every entry with that client.
+ * returns a view onto the same timeline that tags every entry with that client. The runner restarts
+ * it at the start of every step, so entries are relative to the step they belong to.
  */
 export class Timeline {
     state;
+    /** The client this view tags entries with; `undefined` on the root timeline. */
     client;
     constructor(state = { origin: Date.now(), entries: [] }, client) {
         this.state = state;
         this.client = client;
     }
+    /** Every entry added since the last `restart`, in order, shared by all views of the timeline. */
     get entries() {
         return this.state.entries;
     }
+    /** Clears the entries and makes now the origin for `atMs`. */
     restart() {
         this.state.origin = Date.now();
         this.state.entries = [];
     }
+    /** Appends an entry stamped with the time since the origin, and with this view's client when it has one. */
     add(entry) {
         this.state.entries.push({ atMs: Date.now() - this.state.origin, ...(this.client ? { client: this.client } : {}), ...entry });
     }
+    /** A view of the same timeline that tags what it adds with `client`. */
     for(client) {
         return new Timeline(this.state, client);
     }
 }
 /**
- * A driver for anything you can reach from Node: a domain model, an API client, a CLI. `create`
- * returns a fresh context per path attempt; recognisers and events work on it directly.
+ * A driver for anything you can reach from code: a domain model, an API client, a CLI. `create`
+ * returns a fresh context per path attempt; recognisers and events work on it directly. It takes
+ * no screenshots or clips, and any number of attempts can run side by side unless `concurrency` says otherwise.
+ *
+ * @param create builds the context for one attempt; it may be async.
+ * @param options.name the driver's name in reports; `function` when omitted.
+ * @param options.dispose called with the context when the attempt ends.
+ * @param options.concurrency how many contexts may be open at once; unlimited when omitted.
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const driver = functionDriver(() => new TodoModel());
  */
 export function functionDriver(create, options = {}) {
     return {