@crvouga/atlas 0.4.0 → 0.5.0

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;

package/dist/playwright/src/media.js

@@ -1,8 +1,19 @@
+/**
+ * @module Playwright screenshots, clips and paced actions
+ *
+ * The media side of the Playwright driver: `UserActions` taps and types like a person (pausing, and drawing a touch
+ * indicator in showcase videos) while logging each action to the step's timeline; `captureScreen` takes a settled,
+ * deterministic screenshot at device resolution plus a WebP thumbnail; `ScreencastRecorder` records an H.264 clip at
+ * device resolution; `ffmpeg` runs the `ffmpeg` binary, which must be on the PATH for thumbnails and clips.
+ *
+ * @see docs/statecharts.md
+ */
 import { spawn } from 'node:child_process';
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { locate } from './signals.js';
 const isLocator = (target) => 'waitFor' in target;
+/** The default pacing of showcase mode: a visible glide and pauses, so a person can follow the clip. */
 export const SHOWCASE_PACING = {
     moveMs: 600,
     pauseBeforeTapMs: 300,
@@ -10,6 +21,7 @@ export const SHOWCASE_PACING = {
     holdAfterMs: 1000,
     holdBeforeMs: 500
 };
+/** No pauses at all; the pacing of fast mode. */
 export const FAST_PACING = {
     moveMs: 0,
     pauseBeforeTapMs: 0,
@@ -17,6 +29,10 @@ export const FAST_PACING = {
     holdAfterMs: 0,
     holdBeforeMs: 0
 };
+/**
+ * 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 const PHONE = {
     viewport: { width: 390, height: 844 },
     deviceScaleFactor: 3,
@@ -66,7 +82,10 @@ const TOUCH_OVERLAY = `(() => {
   };
   if (document.documentElement) install(); else document.addEventListener('DOMContentLoaded', install);
 })();`;
-/** 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 class UserActions {
     page;
     pacing;
@@ -78,6 +97,10 @@ export class UserActions {
         this.timeline = timeline;
         this.showTouches = showTouches;
     }
+    /**
+     * 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 async install(page) {
         await page.addInitScript(TOUCH_OVERLAY);
     }
@@ -91,7 +114,13 @@ export class UserActions {
         }, { fn, args })
             .catch(() => undefined);
     }
-    /** 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.
+     */
     async tap(target, label) {
         const locator = isLocator(target) ? target : locate(this.page, target);
         await locator.waitFor({ state: 'visible', timeout: 15_000 });
@@ -113,6 +142,10 @@ export class UserActions {
             await this.overlay('press', false);
         }
     }
+    /**
+     * 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.
+     */
     async type(target, text, label) {
         const locator = isLocator(target) ? target : locate(this.page, target);
         await this.tap(locator, label);
@@ -120,18 +153,26 @@ export class UserActions {
         await locator.fill('');
         await locator.pressSequentially(text, { delay: this.pacing.typeDelayMs });
     }
+    /** Waits `ms` milliseconds; does nothing when `ms` is zero or less. */
     async hold(ms) {
         if (ms > 0)
             await this.page.waitForTimeout(ms);
     }
+    /** Hides the touch indicator, so a screenshot does not show it. */
     async hideTouches() {
         await this.overlay('visible', false);
     }
+    /** Shows the touch indicator again after `hideTouches`. */
     async showTouchLayer() {
         await this.overlay('visible', true);
     }
 }
-/** 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 async function captureScreen(page, driver, file, mask = []) {
     mkdirSync(path.dirname(file), { recursive: true });
     await page.waitForLoadState('networkidle', { timeout: 5_000 }).catch(() => undefined);
@@ -160,6 +201,10 @@ export async function captureScreen(page, driver, file, mask = []) {
     ]);
     return { png: file, webp };
 }
+/**
+ * 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 function ffmpeg(args) {
     return new Promise((resolve, reject) => {
         const child = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] });
@@ -170,7 +215,7 @@ export function ffmpeg(args) {
     });
 }
 /**
- * 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
@@ -189,6 +234,7 @@ export class ScreencastRecorder {
         this.page = page;
         this.scale = scale;
     }
+    /** Begins capturing frames of the page into `workDirectory`, which is emptied first. Call `stop` to encode them. */
     async start(workDirectory) {
         this.directory = workDirectory;
         rmSync(workDirectory, { recursive: true, force: true });
@@ -220,6 +266,11 @@ export class ScreencastRecorder {
             }
         })();
     }
+    /**
+     * 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.
+     */
     async stop(output) {
         this.stoppedAt = Date.now();
         this.running = false;

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

@@ -1,24 +1,63 @@
+/**
+ * @module Playwright signal helpers
+ *
+ * Maps the driver-neutral `Signal` values (test ID, role, label, text, CSS) to Playwright locators, and builds state
+ * recognisers from them: `recognize` evaluates a UI signature, `checkSignals` verifies quoted spec text is on screen,
+ * and `screen` wraps both into a `StateImplementation` for any context that exposes `page`. Also re-exports the
+ * signal constructors so an implementation imports everything from `@crvouga/atlas/playwright`. Visibility always
+ * means the first visible match.
+ *
+ * @see docs/statecharts.md
+ */
 import type { CheckResult, RecognizerResult, StateImplementation } from '../../core/src/index.js';
 import type { Signal } from '../../core/src/signals.js';
 import type { Locator, Page } from 'playwright';
 export { css, describeSignal, label, role, testId, text, type Signal } from '../../core/src/signals.js';
-/** A signal as a Playwright locator: the first visible match, with Playwright's own role and text rules. */
+/**
+ * Resolves a `Signal` to a Playwright locator for the first visible match, using Playwright's own role, label and
+ * text rules (text matches are substrings unless `exact`).
+ */
 export declare function locate(page: Page, signal: Signal): Locator;
+/**
+ * A state's UI signature: every `all` signal visible, at least one `any` signal visible (when `any` is given), and no
+ * `none` signal visible.
+ */
 export type SignatureSpec = {
     all?: Signal[];
     any?: Signal[];
     none?: Signal[];
 };
-/** Recognise a state from its UI signature: every `all` visible, one `any` visible, no `none`. */
+/**
+ * Recognises a state from its UI signature on `page`: every `all` signal visible, one `any` signal visible (when `any`
+ * is given), no `none` signal visible. Returns `matched` plus one entry per signal with what was expected and whether
+ * it
+ * was visible, which the report shows when the state is not recognised. A signal that cannot be evaluated counts as not
+ * visible.
+ */
 export declare function recognize(page: Page, spec: SignatureSpec): Promise<RecognizerResult>;
-/** Checks that a quoted piece of the spec is on screen; records expected and actual on failure. */
+/**
+ * Checks that each quoted piece of the spec (`check`) is visible on screen; returns one result per check, with
+ * `expected` and `actual` filled in.
+ */
 export declare function checkSignals(page: Page, checks: {
     check: string;
     signal: Signal;
 }[]): Promise<CheckResult[]>;
 /**
- * A state implementation from a UI signature, for a context that exposes `page`. Extra fields
- * (`lookIn`, `settle`, `transient`, `sameAs`, `checks`) pass through.
+ * Builds a state implementation from a UI signature, for a context that exposes `page` (the `PlaywrightContext`). The
+ * state is recognised as `recognize` describes; `checks` become the state's `meta.checks` results. The other fields
+ * (`lookIn`, `settle`, `transient`, `sameAs`) pass through to the `StateImplementation`.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * ```ts
+ * import { role, screen, text } from '@crvouga/atlas/playwright';
+ *
+ * const states = {
+ *   'No todos': screen({ all: [text('Nothing to do yet')], none: [role('listitem')] })
+ * };
+ * ```
  */
 export declare function screen<C extends {
     page: Page;

package/dist/playwright/src/signals.js

@@ -1,6 +1,9 @@
 import { describeSignal } from '../../core/src/signals.js';
 export { css, describeSignal, label, role, testId, text } from '../../core/src/signals.js';
-/** A signal as a Playwright locator: the first visible match, with Playwright's own role and text rules. */
+/**
+ * Resolves a `Signal` to a Playwright locator for the first visible match, using Playwright's own role, label and
+ * text rules (text matches are substrings unless `exact`).
+ */
 export function locate(page, signal) {
     if ('testId' in signal)
         return page.getByTestId(signal.testId).filter({ visible: true }).first();
@@ -15,7 +18,13 @@ export function locate(page, signal) {
     return page.getByText(signal.text, signal.exact ? { exact: true } : {}).filter({ visible: true }).first();
 }
 const isVisible = (page, signal) => locate(page, signal).isVisible().catch(() => false);
-/** Recognise a state from its UI signature: every `all` visible, one `any` visible, no `none`. */
+/**
+ * Recognises a state from its UI signature on `page`: every `all` signal visible, one `any` signal visible (when `any`
+ * is given), no `none` signal visible. Returns `matched` plus one entry per signal with what was expected and whether
+ * it
+ * was visible, which the report shows when the state is not recognised. A signal that cannot be evaluated counts as not
+ * visible.
+ */
 export async function recognize(page, spec) {
     const signals = [];
     for (const s of spec.all ?? [])
@@ -31,7 +40,10 @@ export async function recognize(page, spec) {
         signals.push({ signal: describeSignal(s), expected: 'hidden', visible: await isVisible(page, s) });
     return { matched: signals.every((x) => (x.expected === 'visible' ? x.visible : !x.visible)), signals };
 }
-/** Checks that a quoted piece of the spec is on screen; records expected and actual on failure. */
+/**
+ * Checks that each quoted piece of the spec (`check`) is visible on screen; returns one result per check, with
+ * `expected` and `actual` filled in.
+ */
 export async function checkSignals(page, checks) {
     const results = [];
     for (const { check, signal } of checks) {
@@ -41,8 +53,20 @@ export async function checkSignals(page, checks) {
     return results;
 }
 /**
- * A state implementation from a UI signature, for a context that exposes `page`. Extra fields
- * (`lookIn`, `settle`, `transient`, `sameAs`, `checks`) pass through.
+ * Builds a state implementation from a UI signature, for a context that exposes `page` (the `PlaywrightContext`). The
+ * state is recognised as `recognize` describes; `checks` become the state's `meta.checks` results. The other fields
+ * (`lookIn`, `settle`, `transient`, `sameAs`) pass through to the `StateImplementation`.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * ```ts
+ * import { role, screen, text } from '@crvouga/atlas/playwright';
+ *
+ * const states = {
+ *   'No todos': screen({ all: [text('Nothing to do yet')], none: [role('listitem')] })
+ * };
+ * ```
  */
 export function screen(spec) {
     return {

package/dist/reports/src/attachment-files.d.ts

@@ -0,0 +1,44 @@
+type Loose = Record<string, unknown>;
+/** What {@link readAttachmentFiles} found. */
+export type AttachmentFileResult = {
+    /** A copy of the holder in which every readable `path` attachment became a `data` attachment (and `path` is gone). The input is not mutated. */
+    readonly value: Loose;
+    /** How many files were read. */
+    readonly attached: number;
+    /** The total size of those files, in bytes. */
+    readonly bytes: number;
+    /** One line per attachment that was left out (missing, not allowed, too large, over budget), prefixed with its name. */
+    readonly warnings: readonly string[];
+};
+/** A budget shared by every call of one publish, so many files cannot add up to more than can be held. */
+export type AttachmentBudget = {
+    /** Bytes still available; each file read subtracts its size. A file larger than this is left out, not truncated. */
+    remaining: number;
+};
+/** Options of {@link readAttachmentFiles}. */
+export type ReadOptions = {
+    /** Largest single file, in bytes. Default 512 MiB. */
+    readonly maxBytes?: number;
+    /** Shared total-size budget; mutated as files are read. Omit for no total limit. */
+    readonly budget?: AttachmentBudget;
+    /**
+     * A path the person running the command typed (`--attach`) is theirs to choose. A path inside a *report* is
+     * data from a test run, which is not: it may name only files inside `roots`, never a hidden file, and never a
+     * link that leads out.
+     */
+    readonly trusted?: boolean;
+};
+/**
+ * Reads the files that attachments name (`path`), at every level (the holder, its `steps` and its `attempts`,
+ * recursively), and hands their bytes over as `data` with a `contentType` guessed from the file name when the
+ * attachment gave none.
+ *
+ * A file that is missing, not allowed or too large is left out with a warning: evidence that could not be
+ * found never stops the results from being published. Attachments without a `path` are kept untouched.
+ *
+ * @param holder A check, step, attempt or any object that may have `attachments`, `steps` and `attempts`.
+ * @param roots Folders a relative path is resolved against (in order), and the only folders an untrusted path may name.
+ * @returns The rewritten copy, counts and warnings; never throws for a bad file.
+ */
+export declare function readAttachmentFiles(holder: Loose, roots: readonly string[], options?: ReadOptions): Promise<AttachmentFileResult>;
+export {};