@crvouga/atlas 0.4.0 → 0.6.0

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

@@ -1,5 +1,8 @@
 /**
- * Atlas reads statecharts in two open formats:
+ * @module Statechart spec types
+ *
+ * The data model every other module works on: a chart, a bundle of charts plus journeys, and the
+ * helpers that walk and name states and transitions. Atlas reads statecharts in two open formats:
  *
  * - W3C SCXML (`*.scxml`), the standard for statecharts.
  * - XState v5 machine config (`*.machine.json`, `*.machine.yaml`), the JSON form Stately Studio
@@ -9,24 +12,43 @@
  * walked without running code: states, nesting, parallel regions, final states, event
  * transitions, statically resolvable child charts (`invoke` with a `src` naming another chart),
  * and `meta`. Guards, actions, context, delays and `always` are rejected by the linter.
+ * This module has no I/O and no Node built-ins.
+ *
+ * @see docs/statecharts.md
  */
+/** The object form of a transition. `target` is a state name, optionally prefixed with `#` (a reference by name across the composed product). */
 export type TransitionConfig = {
     target: string;
 };
+/** An `invoke` that runs another chart inside a state. It is never executed: `composeCharts` inlines the child chart statically. */
 export type InvokeConfig = {
     /** The id of another chart in the bundle; composed statically. */
     src: string;
+    /** Names the invocation; the parent hears `done.invoke.<id>` (`<src>` when omitted) when the child ends. */
     id?: string;
     /** Where the parent goes when the child reaches a final state (`done.invoke.<id>`). */
     onDone?: string | TransitionConfig;
 };
+/**
+ * The `meta` of a state: the business-language facts about it that Atlas lints, shows and checks.
+ * Open object: unknown keys are kept and ignored.
+ *
+ * @see docs/statecharts.md
+ */
 export type StateMeta = {
+    /** What is true in this state. Required on every state by default (`requiredMeta` in the config changes that). */
     description?: string;
+    /** What a person sees in this state, in words. */
     snapshot?: string;
+    /** Business events that happen on entering the state, compared with what event sources observed. */
     events?: string[];
+    /** Whether the behaviour is `confirmed` against the product or only `assumed`. */
     confidence?: 'confirmed' | 'assumed';
+    /** Where the behaviour is documented. */
     source?: string[];
+    /** Things to verify on screen, quoted from the spec; the implementation's `checks()` returns their results. */
     checks?: string[];
+    /** Gherkin-style contracts attached to the state. Core does not read them; they are carried through for viewers. */
     contracts?: {
         id: string;
         name: string;
@@ -39,6 +61,7 @@ export type StateMeta = {
             docString?: string;
         }[];
     }[];
+    /** Why a state with no way out is meant to be one. Without it, a state with no outgoing transition is a lint error. */
     deadEnd?: string;
     /** Legacy composition: the chart that runs inside this state. Prefer `invoke`. */
     childMachine?: string;
@@ -48,49 +71,77 @@ export type StateMeta = {
     doneEvent?: string;
     [key: string]: unknown;
 };
+/**
+ * One state of an XState-shaped chart, recursively. Keys not listed here (guards, actions, `after`,
+ * ...) are accepted by the type so the linter can report them; the planner never executes them.
+ */
 export type StateConfig = {
+    /** Set by `composeCharts` to the state's name when absent; used by `#<name>` targets. */
     id?: string;
+    /** The child state entered first. */
     initial?: string;
+    /** `parallel`: all child regions are active together. `final`: the state ends its chart (or hands off to the parent). */
     type?: 'parallel' | 'final';
     meta?: StateMeta;
     states?: Record<string, StateConfig>;
+    /** Event name (exact business wording) to its transition: a target string or `{ target }`. */
     on?: Record<string, TransitionConfig | string>;
+    /** Child chart(s) that run inside this state. */
     invoke?: InvokeConfig | InvokeConfig[];
     [key: string]: unknown;
 };
+/** A whole chart: a state config with a required `id`, which is the name other charts `invoke` it by. */
 export type MachineConfig = StateConfig & {
     id: string;
 };
+/** A curated, named sequence of events, replayed by the linter and run as its own path(s). */
 export type Journey = {
+    /** The key in `journeys.yaml`. */
     name: string;
+    /** Empty string when the file gives none. */
     description: string;
+    /** Event names in order, using the exact spec wording. Hand-off events are never listed; the planner inserts them. */
     events: string[];
+    /** State names that must all be active after the last event. Empty when the file gives none. */
     endsIn: string[];
 };
+/** One loaded chart file. */
 export type Chart = {
     /** Path relative to the spec directory. */
     file: string;
+    /** The notation the file was parsed from. */
     format: 'scxml' | 'xstate';
     machine: MachineConfig;
 };
+/** Everything loaded from a specs directory. */
 export type SpecBundle = {
+    /** The directory the files were read from. */
     directory: string;
+    /** Charts in load order, one per chart id. */
     charts: Chart[];
+    /** Journeys from every journeys file, in file then declaration order. */
     journeys: Journey[];
     /** The chart the others are composed into: the one no other chart invokes. */
     root: string;
 };
+/** The separator inside a transition id (`<source> :: <event>`). The ids are not escaped, so a state name containing it makes `splitTransitionId` ambiguous. */
 export declare const TRANSITION_SEPARATOR = " :: ";
+/** The id of a transition: the source state's name and the event, joined by `TRANSITION_SEPARATOR`. */
 export declare function transitionId(source: string, event: string): string;
+/** Splits a transition id at its first separator into `{ source, event }`; the inverse of `transitionId`. */
 export declare function splitTransitionId(id: string): {
     source: string;
     event: string;
 };
+/** The state name a transition leads to, with any leading `#` removed; `undefined` when there is no transition. */
 export declare function targetOf(t: TransitionConfig | string | undefined): string | undefined;
+/** A state found by `walkStates`: its name, its config, and the names of its ancestors from the outermost down. */
 export type StateEntry = {
     name: string;
     node: StateConfig;
     trail: string[];
 };
+/** Lists every state under `config` depth-first, parents before their children, in declaration order. The root `config` itself is not listed. */
 export declare function walkStates(config: StateConfig, trail?: string[]): StateEntry[];
+/** The `invoke` entries of a state as an array (empty when it has none). */
 export declare function invokesOf(node: StateConfig): InvokeConfig[];

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

@@ -1,23 +1,47 @@
+/**
+ * @module Statechart spec types
+ *
+ * The data model every other module works on: a chart, a bundle of charts plus journeys, and the
+ * helpers that walk and name states and transitions. Atlas reads statecharts in two open formats:
+ *
+ * - W3C SCXML (`*.scxml`), the standard for statecharts.
+ * - XState v5 machine config (`*.machine.json`, `*.machine.yaml`), the JSON form Stately Studio
+ *   imports and exports.
+ *
+ * Both load into the XState config shape below. Atlas executes only the pure subset that can be
+ * walked without running code: states, nesting, parallel regions, final states, event
+ * transitions, statically resolvable child charts (`invoke` with a `src` naming another chart),
+ * and `meta`. Guards, actions, context, delays and `always` are rejected by the linter.
+ * This module has no I/O and no Node built-ins.
+ *
+ * @see docs/statecharts.md
+ */
+/** The separator inside a transition id (`<source> :: <event>`). The ids are not escaped, so a state name containing it makes `splitTransitionId` ambiguous. */
 export const TRANSITION_SEPARATOR = ' :: ';
+/** The id of a transition: the source state's name and the event, joined by `TRANSITION_SEPARATOR`. */
 export function transitionId(source, event) {
     return `${source}${TRANSITION_SEPARATOR}${event}`;
 }
+/** Splits a transition id at its first separator into `{ source, event }`; the inverse of `transitionId`. */
 export function splitTransitionId(id) {
     const at = id.indexOf(TRANSITION_SEPARATOR);
     return { source: id.slice(0, at), event: id.slice(at + TRANSITION_SEPARATOR.length) };
 }
+/** The state name a transition leads to, with any leading `#` removed; `undefined` when there is no transition. */
 export function targetOf(t) {
     if (t === undefined)
         return undefined;
     const raw = typeof t === 'string' ? t : t.target;
     return raw.startsWith('#') ? raw.slice(1) : raw;
 }
+/** Lists every state under `config` depth-first, parents before their children, in declaration order. The root `config` itself is not listed. */
 export function walkStates(config, trail = []) {
     return Object.entries(config.states ?? {}).flatMap(([name, node]) => [
         { name, node, trail },
         ...walkStates(node, [...trail, name])
     ]);
 }
+/** The `invoke` entries of a state as an array (empty when it has none). */
 export function invokesOf(node) {
     if (!node.invoke)
         return [];

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

@@ -1,24 +1,32 @@
 import type { Driver, StateImplementation, Timeline } from '../../core/src/index.js';
 import type { Signal, SignalContext } from '../../core/src/signals.js';
+/** What Detox's `by.*` builders return: an opaque matcher that is only passed back to Detox's `element(...)`. */
+export type DetoxMatcher = unknown;
 /**
  * The parts of Detox's global API the driver uses (`device`, `element`, `by`, `waitFor`), typed
- * structurally so this package needs no Detox install to build.
+ * structurally so this package needs no Detox install to build. Detox's real globals satisfy it.
  */
-export type DetoxMatcher = unknown;
 export type DetoxApi = {
+    /** The device under test; Detox's `device`. */
     device: {
+        /** Launches the app; the driver passes `newInstance: true` and any `launchArgs`. */
         launchApp(params?: Record<string, unknown>): Promise<void>;
+        /** Opens a deep link; when the device lacks it, `goto` throws. */
         openURL?(params: {
             url: string;
         }): Promise<void>;
+        /** Terminates the app; skipped when absent. */
         terminateApp?(): Promise<void>;
+        /** Takes a screenshot and resolves to the path of the file Detox wrote. */
         takeScreenshot(name: string): Promise<string>;
     };
+    /** Detox's `element(matcher)`: the actions the driver performs on an element. */
     element(matcher: DetoxMatcher): {
         tap(): Promise<void>;
         typeText(text: string): Promise<void>;
         replaceText?(text: string): Promise<void>;
     };
+    /** Detox's `by`: matcher builders. `traits` exists on iOS only. */
     by: {
         id(id: string): DetoxMatcher;
         text(text: string): DetoxMatcher;
@@ -27,37 +35,72 @@ export type DetoxApi = {
             and?(other: DetoxMatcher): DetoxMatcher;
         };
     };
+    /** Detox's `waitFor(element)`, used to ask whether an element is visible. */
     waitFor(element: unknown): {
         toBeVisible(): {
             withTimeout(ms: number): Promise<void>;
         };
     };
 };
-/** Detox's API plus a `SignalContext`, so implementations written against signals run here too. */
+/**
+ * What every event and recogniser receives from `detoxDriver`: Detox's API plus a `SignalContext`,
+ * so implementations written against signals run here too. One context is created per path attempt.
+ */
 export type DetoxContext = DetoxApi & SignalContext & {
+    /** The step timeline the actions below write to. */
     timeline: Timeline;
-    /** Tap an element and log it to the step timeline. */
+    /** Tap the element a matcher finds and log it to the step timeline. Rejects with Detox's error if the element is not found. */
     tap(matcher: DetoxMatcher, label: string): Promise<void>;
+    /** Type `text` into the element a matcher finds (Detox `typeText`, which appends) and log it to the step timeline; `label` is the caption. */
     type(matcher: DetoxMatcher, text: string, label: string): Promise<void>;
 };
+/** Options of `detoxDriver`. */
 export type DetoxDriverOptions = {
     /** Detox's globals; `globalThis` (where Detox puts them) by default. */
     api?: DetoxApi;
+    /** Passed to `device.launchApp` as `launchArgs` at the start of every attempt. */
     launchArgs?: Record<string, unknown>;
 };
 /**
- * A signal as a Detox matcher: test IDs are `by.id` (React Native's `testID`), labels `by.label`,
- * text `by.text`, a role with a name `by.label` (with the iOS `button` trait when Detox has it).
- * Detox matches exact strings, so regular expressions and CSS selectors are refused.
+ * Translates a signal into a Detox matcher: test IDs are `by.id` (React Native's `testID`), labels
+ * `by.label`, text `by.text`, a role with a name `by.label` (with the iOS `button` trait when Detox
+ * has it). Detox matches exact strings, so regular expressions and CSS selectors are refused.
+ *
+ * @param api the Detox API whose `by` builds the matcher.
+ * @throws Error for a `css` signal, a regular expression, or a role without a name.
  */
 export declare function detoxMatcher(api: DetoxApi, signal: Signal): DetoxMatcher;
 /**
- * Drive a native app with Detox. Screenshots come from `device.takeScreenshot`. Detox records
- * video per test through its artifacts plugin rather than per call, so this driver does not
- * record clips; enable Detox's `--record-videos` to keep a video of each attempt.
+ * Creates a driver for a native app tested with Detox. Every path attempt relaunches the app
+ * (`device.launchApp({ newInstance: true })`) and terminates it afterwards. Screenshots come from
+ * `device.takeScreenshot`. Detox records video per test through its artifacts plugin rather than per
+ * call, so this driver does not record clips; enable Detox's `--record-videos` to keep a video of
+ * each attempt.
+ *
+ * The Detox globals are read when an attempt opens, so call `runConfig` from inside a Detox test.
+ * Signals are resolved with `detoxMatcher`, so regular expressions and CSS selectors are refused.
+ *
+ * @param options `api` to use instead of the globals, and `launchArgs` for the app.
+ * @returns a driver whose context is a `DetoxContext`.
+ *
+ * @example
+ * const config = defineConfig<DetoxContext>({
+ *   specs: './specs',
+ *   driver: detoxDriver({ launchArgs: { resetData: true } }),
+ *   implementation
+ * });
+ * await runConfig(config, { mode: 'fast' });
  */
 export declare function detoxDriver(options?: DetoxDriverOptions): Driver<DetoxContext>;
-/** A state recognised by Detox matchers: every `all` visible and no `none` visible. */
+/**
+ * Builds a state implementation recognised by Detox matchers: matched when every `all` matcher is
+ * visible and no `none` matcher is. `checks` pair a statement from the state's `meta.checks` with
+ * the matcher that proves it. Each entry's `name` appears in failure reports. Unlike
+ * `screen(...)` from the signals module it takes matchers, not signals, and has no `any`.
+ *
+ * @example
+ * states: { 'No todos': detoxScreen({ all: [{ matcher: by.text('Nothing to do yet'), name: 'empty message' }] }) }
+ */
 export declare function detoxScreen(spec: {
     all: {
         matcher: DetoxMatcher;

package/dist/detox/src/index.js

@@ -1,10 +1,23 @@
+/**
+ * @module Detox driver
+ *
+ * The Atlas driver for native iOS and Android apps tested with Detox (https://wix.github.io/Detox/).
+ * It owns launching and terminating the app, mapping signals to Detox matchers, screenshots, and
+ * logging taps and typing to the step timeline; it does not record video (Detox does that through its
+ * artifacts plugin). It must run inside a Detox test, where Detox's `device`, `element`, `by` and
+ * `waitFor` globals exist, or be given them as `api`. Detox is typed structurally here, so importing
+ * this module needs no Detox install.
+ */
 import { copyFileSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { describeSignal } from '../../core/src/signals.js';
 /**
- * A signal as a Detox matcher: test IDs are `by.id` (React Native's `testID`), labels `by.label`,
- * text `by.text`, a role with a name `by.label` (with the iOS `button` trait when Detox has it).
- * Detox matches exact strings, so regular expressions and CSS selectors are refused.
+ * Translates a signal into a Detox matcher: test IDs are `by.id` (React Native's `testID`), labels
+ * `by.label`, text `by.text`, a role with a name `by.label` (with the iOS `button` trait when Detox
+ * has it). Detox matches exact strings, so regular expressions and CSS selectors are refused.
+ *
+ * @param api the Detox API whose `by` builds the matcher.
+ * @throws Error for a `css` signal, a regular expression, or a role without a name.
  */
 export function detoxMatcher(api, signal) {
     if ('testId' in signal)
@@ -26,9 +39,25 @@ export function detoxMatcher(api, signal) {
     return byLabel;
 }
 /**
- * Drive a native app with Detox. Screenshots come from `device.takeScreenshot`. Detox records
- * video per test through its artifacts plugin rather than per call, so this driver does not
- * record clips; enable Detox's `--record-videos` to keep a video of each attempt.
+ * Creates a driver for a native app tested with Detox. Every path attempt relaunches the app
+ * (`device.launchApp({ newInstance: true })`) and terminates it afterwards. Screenshots come from
+ * `device.takeScreenshot`. Detox records video per test through its artifacts plugin rather than per
+ * call, so this driver does not record clips; enable Detox's `--record-videos` to keep a video of
+ * each attempt.
+ *
+ * The Detox globals are read when an attempt opens, so call `runConfig` from inside a Detox test.
+ * Signals are resolved with `detoxMatcher`, so regular expressions and CSS selectors are refused.
+ *
+ * @param options `api` to use instead of the globals, and `launchArgs` for the app.
+ * @returns a driver whose context is a `DetoxContext`.
+ *
+ * @example
+ * const config = defineConfig<DetoxContext>({
+ *   specs: './specs',
+ *   driver: detoxDriver({ launchArgs: { resetData: true } }),
+ *   implementation
+ * });
+ * await runConfig(config, { mode: 'fast' });
  */
 export function detoxDriver(options = {}) {
     const api = () => options.api ?? globalThis;
@@ -74,6 +103,7 @@ export function detoxDriver(options = {}) {
         }
     };
 }
+/** Whether the matcher's element is visible right now: asks Detox with a zero timeout and counts any failure as not visible. */
 async function visible(ctx, matcher) {
     try {
         await ctx.waitFor(ctx.element(matcher)).toBeVisible().withTimeout(0);
@@ -83,7 +113,15 @@ async function visible(ctx, matcher) {
         return false;
     }
 }
-/** A state recognised by Detox matchers: every `all` visible and no `none` visible. */
+/**
+ * Builds a state implementation recognised by Detox matchers: matched when every `all` matcher is
+ * visible and no `none` matcher is. `checks` pair a statement from the state's `meta.checks` with
+ * the matcher that proves it. Each entry's `name` appears in failure reports. Unlike
+ * `screen(...)` from the signals module it takes matchers, not signals, and has no `any`.
+ *
+ * @example
+ * states: { 'No todos': detoxScreen({ all: [{ matcher: by.text('Nothing to do yet'), name: 'empty message' }] }) }
+ */
 export function detoxScreen(spec) {
     return {
         async recognize(ctx) {

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

@@ -1,3 +1,13 @@
+/**
+ * @module Playwright driver
+ *
+ * `playwrightDriver()` is the core `Driver` that runs a statechart's paths against a web app (or a React Native app
+ * on the web) in Chromium. Each path attempt gets its own browser context and page; the `PlaywrightContext` it passes
+ * to event and state implementations carries the page and paced user actions. Screens are recognised by signals
+ * (`signals.ts`), and screenshots, clips and touch overlay come from `media.ts`.
+ *
+ * @see docs/statecharts.md
+ */
 import type { Driver } from '../../core/src/index.js';
 import type { SignalContext } from '../../core/src/signals.js';
 import type { Browser, BrowserContext, BrowserContextOptions, LaunchOptions, Page } from 'playwright';
@@ -14,11 +24,13 @@ export type PlaywrightContext = SignalContext & {
     /** Paced taps and typing, logged to the step's timeline and shown by the touch overlay in videos. */
     user: UserActions;
 };
+/** Options of `playwrightDriver`; every field is optional. */
 export type PlaywrightDriverOptions = {
     /** Where `goto` paths resolve; the implementation's setup decides where to open. */
     baseUrl?: string | (() => string | Promise<string>);
     /** Browser context options; a 390×844 phone at device scale factor 3 with touch by default. */
     device?: BrowserContextOptions;
+    /** Options for `chromium.launch`. */
     launch?: LaunchOptions;
     /** Override the pacing used in showcase mode. */
     pacing?: Partial<Pacing>;
@@ -37,8 +49,32 @@ export type PlaywrightDriverOptions = {
     concurrency?: number;
 };
 /**
- * Drive a web app (or a React Native app on the web) with Playwright. Screenshots are taken at the
- * device's physical resolution; clips are recorded at that resolution too and encoded with
- * FFmpeg as H.264 MP4 (FFmpeg on the PATH is needed for video and WebP thumbnails).
+ * Drives a web app (or a React Native app on the web) in Chromium with Playwright, for `atlas run`. Pass it in the
+ * config as `driver: () => playwrightDriver(options)`. The browser launches on first use (and again if it was
+ * disconnected) and is shared by every context; each path attempt opens a fresh context from `options.device`
+ * (default `PHONE`). Screenshots are taken at the device's physical resolution; clips are recorded at that
+ * resolution too and encoded with FFmpeg as H.264 MP4. FFmpeg must be on the PATH: each screenshot also writes a
+ * WebP thumbnail with it, so without FFmpeg no screenshot is recorded (the run goes on). A Playwright trace is
+ * kept only for a failed attempt that was traced (see `trace`), and `dispose` closes the browser.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@crvouga/atlas';
+ * import { playwrightDriver, screen, text } from '@crvouga/atlas/playwright';
+ *
+ * export default defineConfig({
+ *   specs: './specs',
+ *   driver: () => playwrightDriver({ clock: true }),
+ *   implementation: {
+ *     async setup({ page }) { await page.goto('http://127.0.0.1:4317'); },
+ *     events: {
+ *       // one entry per event of the spec
+ *     },
+ *     states: { 'No todos': screen({ all: [text('Nothing to do yet')] }) }
+ *   }
+ * });
+ * ```
  */
 export declare function playwrightDriver(options?: PlaywrightDriverOptions): Driver<PlaywrightContext>;

package/dist/playwright/src/driver.js

@@ -2,9 +2,33 @@ import { chromium } from 'playwright';
 import { captureScreen, FAST_PACING, PHONE, ScreencastRecorder, SHOWCASE_PACING, UserActions } from './media.js';
 import { locate } from './signals.js';
 /**
- * Drive a web app (or a React Native app on the web) with Playwright. Screenshots are taken at the
- * device's physical resolution; clips are recorded at that resolution too and encoded with
- * FFmpeg as H.264 MP4 (FFmpeg on the PATH is needed for video and WebP thumbnails).
+ * Drives a web app (or a React Native app on the web) in Chromium with Playwright, for `atlas run`. Pass it in the
+ * config as `driver: () => playwrightDriver(options)`. The browser launches on first use (and again if it was
+ * disconnected) and is shared by every context; each path attempt opens a fresh context from `options.device`
+ * (default `PHONE`). Screenshots are taken at the device's physical resolution; clips are recorded at that
+ * resolution too and encoded with FFmpeg as H.264 MP4. FFmpeg must be on the PATH: each screenshot also writes a
+ * WebP thumbnail with it, so without FFmpeg no screenshot is recorded (the run goes on). A Playwright trace is
+ * kept only for a failed attempt that was traced (see `trace`), and `dispose` closes the browser.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@crvouga/atlas';
+ * import { playwrightDriver, screen, text } from '@crvouga/atlas/playwright';
+ *
+ * export default defineConfig({
+ *   specs: './specs',
+ *   driver: () => playwrightDriver({ clock: true }),
+ *   implementation: {
+ *     async setup({ page }) { await page.goto('http://127.0.0.1:4317'); },
+ *     events: {
+ *       // one entry per event of the spec
+ *     },
+ *     states: { 'No todos': screen({ all: [text('Nothing to do yet')] }) }
+ *   }
+ * });
+ * ```
  */
 export function playwrightDriver(options = {}) {
     let browser = null;

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

@@ -1,3 +1,13 @@
+/**
+ * @module Playwright driver entry point (`@crvouga/atlas/playwright`)
+ *
+ * Re-exports the Playwright driver for statechart runs (`playwrightDriver`), the helpers an implementation uses to
+ * recognise screens and tap or type (`screen`, `recognize`, `locate`, the signal constructors and `UserActions`), and
+ * the media tools (`captureScreen`, `ScreencastRecorder`, `ffmpeg`, `PHONE` and the pacing presets). Needs the
+ * `playwright` package; clips and thumbnails need FFmpeg on the PATH.
+ *
+ * @see docs/statecharts.md
+ */
 export { playwrightDriver, type PlaywrightContext, type PlaywrightDriverOptions } from './driver.js';
 export { captureScreen, ScreencastRecorder, UserActions, PHONE, SHOWCASE_PACING, FAST_PACING, ffmpeg, type Pacing } from './media.js';
 export { recognize, checkSignals, screen, locate, describeSignal, testId, text, role, label, css, type Signal, type SignatureSpec } from './signals.js';

package/dist/playwright/src/index.js

@@ -1,3 +1,13 @@
+/**
+ * @module Playwright driver entry point (`@crvouga/atlas/playwright`)
+ *
+ * Re-exports the Playwright driver for statechart runs (`playwrightDriver`), the helpers an implementation uses to
+ * recognise screens and tap or type (`screen`, `recognize`, `locate`, the signal constructors and `UserActions`), and
+ * the media tools (`captureScreen`, `ScreencastRecorder`, `ffmpeg`, `PHONE` and the pacing presets). Needs the
+ * `playwright` package; clips and thumbnails need FFmpeg on the PATH.
+ *
+ * @see docs/statecharts.md
+ */
 export { playwrightDriver } from './driver.js';
 export { captureScreen, ScreencastRecorder, UserActions, PHONE, SHOWCASE_PACING, FAST_PACING, ffmpeg } from './media.js';
 export { recognize, checkSignals, screen, locate, describeSignal, testId, text, role, label, css } from './signals.js';

package/dist/playwright/src/media.d.ts

@@ -1,6 +1,10 @@
 import type { Locator, Page } from 'playwright';
 import type { Timeline } from '../../core/src/index.js';
 import type { Signal } from '../../core/src/signals.js';
+/**
+ * Pauses, in milliseconds, that make a showcase video readable: how long the touch indicator takes to glide to a tap
+ * target, the pause before the tap, the delay between typed characters, and the holds after and before a step.
+ */
 export type Pacing = {
     moveMs: number;
     pauseBeforeTapMs: number;
@@ -8,8 +12,14 @@ export type Pacing = {
     holdAfterMs: number;
     holdBeforeMs: number;
 };
+/** The default pacing of showcase mode: a visible glide and pauses, so a person can follow the clip. */
 export declare const SHOWCASE_PACING: Pacing;
+/** No pauses at all; the pacing of fast mode. */
 export declare const FAST_PACING: Pacing;
+/**
+ * The default `device` of `playwrightDriver`: a 390 by 844 CSS pixel viewport at device scale factor 3 (screenshots
+ * are 1170 by 2532 pixels), a mobile user agent and touch.
+ */
 export declare const PHONE: {
     readonly viewport: {
         readonly width: 390;
@@ -19,31 +29,61 @@ export declare const PHONE: {
     readonly isMobile: true;
     readonly hasTouch: true;
 };
-/** Taps and typing a person would do, paced for showcase videos and logged to the step timeline. */
+/**
+ * Taps and typing a person would do, paced for showcase videos and logged to the step timeline. Provided to event
+ * implementations as `user` on the `PlaywrightContext`. `showTouches` turns on the touch indicator (showcase mode).
+ */
 export declare class UserActions {
     readonly page: Page;
     readonly pacing: Pacing;
     timeline: Timeline;
     readonly showTouches: boolean;
     constructor(page: Page, pacing: Pacing, timeline: Timeline, showTouches: boolean);
+    /**
+     * Registers the touch indicator overlay to be added to every page load, so it exists before the app's scripts run.
+     * Call it once per page, before navigating.
+     */
     static install(page: Page): Promise<void>;
     private overlay;
-    /** Tap a locator or a signal (resolved with `locate`). */
+    /**
+     * Taps the centre of a locator or a signal (resolved with `locate`). Waits up to 15 s for it to be visible, scrolls
+     * it
+     * into view, logs a `tap` entry labelled `label` to the timeline, then clicks (10 s timeout). In showcase mode the
+     * touch
+     * indicator glides there first. Throws when the target has no position on screen.
+     */
     tap(target: Locator | Signal, label: string): Promise<void>;
+    /**
+     * Taps `target`, clears it, then types `text` one character at a time, `pacing.typeDelayMs` apart. Logs a `tap` and
+     * a `type` entry labelled `label` to the timeline.
+     */
     type(target: Locator | Signal, text: string, label: string): Promise<void>;
+    /** Waits `ms` milliseconds; does nothing when `ms` is zero or less. */
     hold(ms: number): Promise<void>;
+    /** Hides the touch indicator, so a screenshot does not show it. */
     hideTouches(): Promise<void>;
+    /** Shows the touch indicator again after `hideTouches`. */
     showTouchLayer(): Promise<void>;
 }
+/** The files `captureScreen` wrote: the full-size PNG and its WebP thumbnail. */
 export type ScreenshotFiles = {
     png: string;
     webp?: string;
 };
-/** A settled, deterministic capture at device resolution, with the touch layer hidden. */
+/**
+ * Takes a settled, deterministic screenshot at device resolution, with the touch layer hidden: waits for the network to
+ * go quiet (up to 5 s) and for fonts, disables animations and hides the caret. Writes the PNG to `file` (creating its
+ * folder) and a 400 px wide WebP thumbnail beside it with FFmpeg. `mask` lists locators to paint over. Rejects when
+ * FFmpeg is missing or fails.
+ */
 export declare function captureScreen(page: Page, driver: UserActions, file: string, mask?: Locator[]): Promise<ScreenshotFiles>;
+/**
+ * Runs `ffmpeg` with `args` and resolves when it exits with code 0. Rejects with the spawn error when `ffmpeg` is not
+ * on the PATH, or with `ffmpeg <code>: <stderr>` when it fails.
+ */
 export declare function ffmpeg(args: string[]): Promise<void>;
 /**
- * Records a clip at the phone's physical resolution (1170×2532). Chrome's screencast, and
+ * Records a clip of a page at its physical resolution (1170×2532 for the default `PHONE`). Chrome's screencast, and
  * Playwright's built-in video that rides on it, only deliver CSS-pixel frames (390×844) and
  * upscale them, so text goes soft. Instead this loops device-scale JPEG captures (about 20 fps
  * here), keeps each frame's own timestamp, and encodes H.264 at 30 fps, holding each frame for as
@@ -59,7 +99,13 @@ export declare class ScreencastRecorder {
     private running;
     private loop;
     constructor(page: Page, scale?: number);
+    /** Begins capturing frames of the page into `workDirectory`, which is emptied first. Call `stop` to encode them. */
     start(workDirectory: string): Promise<void>;
+    /**
+     * Stops capturing and encodes the frames to the MP4 file `output` (the poster is written beside it, with `.mp4`
+     * replaced by `.poster.webp`), then deletes the work directory. Resolves to `{ video, poster, durationMs }`, or
+     * `null` when no frame was captured.
+     */
     stop(output: string): Promise<{
         video: string;
         poster: string;