@crvouga/atlas 0.3.0 → 0.5.0

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 {

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

@@ -1,3 +1,14 @@
+/**
+ * @module UI signals
+ *
+ * A driver-neutral vocabulary for saying what is on screen (`testId`, `role`, `label`, `text`, `css`),
+ * and `screen(...)`, which builds a state recogniser from signals. Every UI driver (Playwright, Bun
+ * WebView, WebDriver, Detox) resolves the same signals against its own UI tree, so an implementation
+ * written with them runs on any of them. Also holds the wire form and the in-page probe used by drivers
+ * that evaluate JavaScript in a page. This module is browser-safe and has no driver dependencies.
+ *
+ * @see docs/statecharts.md
+ */
 import type { StateImplementation } from './run/types.js';
 /**
  * A UI signal: something visible (or not) that proves where the app is. Test IDs first, then
@@ -19,35 +30,56 @@ export type Signal = {
 } | {
     css: string;
 };
+/** A signal for the element with this test ID (`data-testid` on the web, the accessibility identifier on native). */
 export declare const testId: (id: string) => Signal;
+/** A signal for visible text: a string matches as a case-insensitive substring unless `exact`, a RegExp is tested as is. */
 export declare const text: (value: string | RegExp, options?: {
     exact?: boolean;
 }) => Signal;
+/** A signal for an element with an accessibility role (`button`, `heading`, ...), optionally filtered by its accessible name (same matching as `text`). */
 export declare const role: (r: string, name?: string | RegExp, options?: {
     exact?: boolean;
 }) => Signal;
+/** A signal for a form control by its label text. */
 export declare const label: (value: string | RegExp) => Signal;
+/** A signal for a CSS selector. Web only: the WebDriver and Detox drivers throw for it in native sessions, so prefer the other signals. */
 export declare const css: (selector: string) => Signal;
+/** Describes a signal in words for recogniser output and failure messages, e.g. `button "Add"`. */
 export declare function describeSignal(signal: Signal): string;
+/** What a screen looks like, as signals. */
 export type SignatureSpec<S = Signal> = {
+    /** Every one must be visible. */
     all?: S[];
+    /** At least one must be visible (ignored when empty). */
     any?: S[];
+    /** None may be visible. */
     none?: S[];
 };
+/** A `SignatureSpec` plus the optional parts of a `StateImplementation`, which are passed through. */
 export type ScreenSpec<C, S = Signal> = SignatureSpec<S> & {
+    /** Each `check` is a statement from the state's `meta.checks`; it passes when its `signal` is visible. */
     checks?: {
         check: string;
         signal: S;
     }[];
+    /** See `StateImplementation.transient`. */
     transient?: boolean;
+    /** See `StateImplementation.sameAs`. */
     sameAs?: string;
+    /** See `StateImplementation.lookIn`. */
     lookIn?: (ctx: C) => Promise<void>;
+    /** See `StateImplementation.settle`. */
     settle?: (ctx: C) => Promise<void>;
 };
 /**
- * Build `screen()` for a driver from one question: is this signal visible right now? A state is
- * recognised when every `all` is visible, one `any` is visible and no `none` is. Drivers with
- * their own locators (WebDriver's) pass their signal type and how to describe it.
+ * Builds a `screen()` function for a driver from one question: is this signal visible right now?
+ * A state is recognised when every `all` is visible, one `any` is visible and no `none` is; the result
+ * lists every signal looked at with whether it was visible, for failure reports. An `isVisible` that
+ * rejects counts as not visible. Drivers with their own locators (WebDriver's) pass their signal type
+ * and how to describe it.
+ *
+ * @param isVisible answers whether one signal is visible in the context.
+ * @param describe names a signal in words.
  */
 export declare function signatureScreen<C, S = Signal>(isVisible: (ctx: C, signal: S) => Promise<boolean>, describe: (signal: S) => string): (spec: ScreenSpec<C, S>) => StateImplementation<C>;
 /**
@@ -58,14 +90,25 @@ export declare function signatureScreen<C, S = Signal>(isVisible: (ctx: C, signa
 export type SignalContext = {
     /** Open a URL (a path resolves against the driver's base URL; a deep link in a native app). */
     goto(url: string): Promise<void>;
+    /** Whether the signal is visible now. */
     isVisible(signal: Signal): Promise<boolean>;
+    /** Actions a person does. Drivers log each to the step's timeline, which becomes the clip's captions. */
     user: {
+        /** Taps or clicks the target; `label` is the caption shown for it. */
         tap(target: Signal, label: string): Promise<void>;
+        /** Types `text` into the target; `label` is the caption shown for it. */
         type(target: Signal, text: string, label: string): Promise<void>;
     };
 };
-/** A state recognised from signals on any driver that provides a `SignalContext`. */
+/**
+ * Builds a state implementation that is recognised from signals on any driver that provides a
+ * `SignalContext`.
+ *
+ * @example
+ * states: { 'No todos': screen({ all: [text('Nothing to do yet')], none: [role('listitem')] }) }
+ */
 export declare const screen: (spec: ScreenSpec<SignalContext, Signal>) => StateImplementation<SignalContext>;
+/** A string or regular expression as JSON. */
 type WireMatch = {
     text: string;
     exact: boolean;
@@ -73,6 +116,7 @@ type WireMatch = {
     regex: string;
     flags: string;
 };
+/** A `Signal` as plain JSON, the form sent to the in-page `DOM_PROBE`. */
 export type WireSignal = {
     kind: 'css';
     selector: string;
@@ -90,7 +134,7 @@ export type WireSignal = {
     kind: 'text';
     match: WireMatch;
 };
-/** A signal as JSON, for a probe that runs inside the page. */
+/** Converts a signal to its JSON form for a probe that runs inside the page. */
 export declare function toWire(signal: Signal): WireSignal;
 /** Where a probe found a signal: whether it is visible, and the centre of the first visible match in CSS pixels. */
 export type DomProbeResult = {

package/dist/core/src/signals.js

@@ -1,8 +1,14 @@
+/** A signal for the element with this test ID (`data-testid` on the web, the accessibility identifier on native). */
 export const testId = (id) => ({ testId: id });
+/** A signal for visible text: a string matches as a case-insensitive substring unless `exact`, a RegExp is tested as is. */
 export const text = (value, options = {}) => ({ text: value, ...options });
+/** A signal for an element with an accessibility role (`button`, `heading`, ...), optionally filtered by its accessible name (same matching as `text`). */
 export const role = (r, name, options = {}) => ({ role: r, ...(name ? { name } : {}), ...options });
+/** A signal for a form control by its label text. */
 export const label = (value) => ({ label: value });
+/** A signal for a CSS selector. Web only: the WebDriver and Detox drivers throw for it in native sessions, so prefer the other signals. */
 export const css = (selector) => ({ css: selector });
+/** Describes a signal in words for recogniser output and failure messages, e.g. `button "Add"`. */
 export function describeSignal(signal) {
     if ('testId' in signal)
         return `test ID "${signal.testId}"`;
@@ -15,9 +21,14 @@ export function describeSignal(signal) {
     return `text ${String(signal.text)}`;
 }
 /**
- * Build `screen()` for a driver from one question: is this signal visible right now? A state is
- * recognised when every `all` is visible, one `any` is visible and no `none` is. Drivers with
- * their own locators (WebDriver's) pass their signal type and how to describe it.
+ * Builds a `screen()` function for a driver from one question: is this signal visible right now?
+ * A state is recognised when every `all` is visible, one `any` is visible and no `none` is; the result
+ * lists every signal looked at with whether it was visible, for failure reports. An `isVisible` that
+ * rejects counts as not visible. Drivers with their own locators (WebDriver's) pass their signal type
+ * and how to describe it.
+ *
+ * @param isVisible answers whether one signal is visible in the context.
+ * @param describe names a signal in words.
  */
 export function signatureScreen(isVisible, describe) {
     const visible = (ctx, signal) => isVisible(ctx, signal).catch(() => false);
@@ -58,10 +69,16 @@ export function signatureScreen(isVisible, describe) {
         };
     };
 }
-/** A state recognised from signals on any driver that provides a `SignalContext`. */
+/**
+ * Builds a state implementation that is recognised from signals on any driver that provides a
+ * `SignalContext`.
+ *
+ * @example
+ * states: { 'No todos': screen({ all: [text('Nothing to do yet')], none: [role('listitem')] }) }
+ */
 export const screen = signatureScreen((ctx, signal) => ctx.isVisible(signal), describeSignal);
 const wire = (value, exact = false) => typeof value === 'string' ? { text: value, exact } : { regex: value.source, flags: value.flags };
-/** A signal as JSON, for a probe that runs inside the page. */
+/** Converts a signal to its JSON form for a probe that runs inside the page. */
 export function toWire(signal) {
     if ('testId' in signal)
         return { kind: 'testId', id: signal.testId };

package/dist/core/src/spec/compose.d.ts

@@ -1,11 +1,24 @@
+/**
+ * @module Static chart composition
+ *
+ * Flattens a bundle of charts into one machine by inlining each child chart into the state that
+ * invokes it, so a plain graph traversal sees the whole product. Pure and deterministic; the input
+ * bundle is not modified. State names are global across the composed product (nothing is renamed or
+ * namespaced), which is why they must be unique across charts.
+ *
+ * @see docs/statecharts.md
+ */
 import type { MachineConfig, SpecBundle } from './types.js';
+/** A child chart's final state and the event it passes to the parent, which the planner and replay insert automatically. */
 export type HandOff = {
     finalState: string;
     event: string;
     parentState: string;
     childChart: string;
 };
+/** The result of composing a bundle. */
 export type Composition = {
+    /** The single flattened machine (a deep copy; the bundle is untouched). */
     machine: MachineConfig;
     /** Which chart each state came from. */
     chartOf: Map<string, string>;
@@ -15,7 +28,7 @@ export type Composition = {
     hosts: Map<string, string>;
 };
 /**
- * Inline every child chart where its parent invokes it, so XState's graph traversal (which cannot
+ * Inlines every child chart where its parent invokes it, so XState's graph traversal (which cannot
  * enter an invoked actor) walks straight through. Supports:
  *
  * - XState `invoke: { src, id, onDone }` and SCXML `<invoke>` + `done.invoke.<id>`;
@@ -24,5 +37,14 @@ export type Composition = {
  *
  * A child's final states stay as states (they keep their screenshots and checks) but stop being
  * final: each takes the parent's transition for its hand-off event.
+ *
+ * Every state without an `id` gets its own name as `id`. A child's `initial` replaces the host
+ * state's `initial`, and the host's transitions that consumed a hand-off event are removed from it.
+ *
+ * @throws Error when the root chart is not loaded, an invoked chart is not loaded, charts invoke
+ *   each other in a cycle, or a child's final state has no matching transition (or `onDone`) in the parent.
+ *
+ * @example
+ * const { machine, handOffs } = composeCharts(loadSpecDirectory('./specs'));
  */
 export declare function composeCharts(bundle: SpecBundle): Composition;