@crvouga/atlas 0.4.0 → 0.5.0

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

@@ -4,7 +4,7 @@ function asTransition(t) {
     return target ? { target: `#${target}` } : undefined;
 }
 /**
- * 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>`;
@@ -13,6 +13,15 @@ function asTransition(t) {
  *
  * 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 function composeCharts(bundle) {
     const byId = new Map(bundle.charts.map((c) => [c.machine.id, c.machine]));

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

@@ -1,4 +1,12 @@
-/** Browser-safe: parsing, SCXML conversion and composition, with no Node built-ins. */
+/**
+ * @module Spec entry point (browser-safe)
+ *
+ * Re-exports the parts of the spec layer that need no Node built-ins: the spec types, chart and
+ * journey parsing, SCXML conversion and static composition. `loadSpecDirectory` (which reads the
+ * file system) is deliberately not here; import it from the package root.
+ *
+ * @see docs/statecharts.md
+ */
 export * from './types.js';
 export { parseChart, parseJourneys } from './parse.js';
 export { scxmlToMachine, machineToScxml, scxmlToken, ATLAS_NS } from './scxml.js';

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

@@ -1,4 +1,12 @@
-/** Browser-safe: parsing, SCXML conversion and composition, with no Node built-ins. */
+/**
+ * @module Spec entry point (browser-safe)
+ *
+ * Re-exports the parts of the spec layer that need no Node built-ins: the spec types, chart and
+ * journey parsing, SCXML conversion and static composition. `loadSpecDirectory` (which reads the
+ * file system) is deliberately not here; import it from the package root.
+ *
+ * @see docs/statecharts.md
+ */
 export * from './types.js';
 export { parseChart, parseJourneys } from './parse.js';
 export { scxmlToMachine, machineToScxml, scxmlToken, ATLAS_NS } from './scxml.js';

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

@@ -3,6 +3,27 @@ import { parseChart, parseJourneys } from './parse.js';
 export { parseChart, parseJourneys };
 /** The ids of the charts a machine composes, by `invoke` or the legacy `meta.childMachine`. */
 export declare function childChartIds(machine: MachineConfig): Set<string>;
+/**
+ * Assembles a bundle from already-parsed charts and journeys, choosing the root chart: the first
+ * chart (in the order given) that no other chart invokes, or the first chart when every chart is
+ * invoked by another (a cycle, which `composeCharts` later rejects).
+ *
+ * @throws Error when `charts` is empty.
+ */
 export declare function bundleOf(directory: string, charts: Chart[], journeys: Journey[]): SpecBundle;
-/** Load every chart and journeys file directly inside `directory`. */
+/**
+ * Loads every chart and journeys file directly inside `directory` into a bundle.
+ *
+ * Chart files are `*.scxml`, `*.machine.json` and `*.machine.yaml`/`.yml`; journeys files are
+ * `journeys.yaml`/`.yml`/`.json`. When two files declare the same chart id the first wins, in the
+ * order SCXML, then YAML, then JSON, then by file name, so the result does not depend on directory
+ * order.
+ *
+ * @throws Error when the directory is missing, a file does not parse, or no chart is found.
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const bundle = loadSpecDirectory('./specs');
+ * bundle.root; // the id of the chart no other chart invokes
+ */
 export declare function loadSpecDirectory(directory: string): SpecBundle;

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

@@ -1,3 +1,12 @@
+/**
+ * @module Spec directory loader
+ *
+ * Reads a specs directory from disk into a `SpecBundle`: every chart file and journeys file directly
+ * inside it (no recursion), and works out the root chart. Node only. Parsing itself lives in `./parse`;
+ * loading throws on the first malformed file rather than skipping it.
+ *
+ * @see docs/statecharts.md
+ */
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parseChart, parseJourneys } from './parse.js';
@@ -16,6 +25,13 @@ export function childChartIds(machine) {
     }
     return ids;
 }
+/**
+ * Assembles a bundle from already-parsed charts and journeys, choosing the root chart: the first
+ * chart (in the order given) that no other chart invokes, or the first chart when every chart is
+ * invoked by another (a cycle, which `composeCharts` later rejects).
+ *
+ * @throws Error when `charts` is empty.
+ */
 export function bundleOf(directory, charts, journeys) {
     const invoked = new Set(charts.flatMap((c) => [...childChartIds(c.machine)]));
     const roots = charts.filter((c) => !invoked.has(c.machine.id));
@@ -24,7 +40,21 @@ export function bundleOf(directory, charts, journeys) {
         throw new Error(`No statechart found in ${directory}`);
     return { directory, charts, journeys, root };
 }
-/** Load every chart and journeys file directly inside `directory`. */
+/**
+ * Loads every chart and journeys file directly inside `directory` into a bundle.
+ *
+ * Chart files are `*.scxml`, `*.machine.json` and `*.machine.yaml`/`.yml`; journeys files are
+ * `journeys.yaml`/`.yml`/`.json`. When two files declare the same chart id the first wins, in the
+ * order SCXML, then YAML, then JSON, then by file name, so the result does not depend on directory
+ * order.
+ *
+ * @throws Error when the directory is missing, a file does not parse, or no chart is found.
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const bundle = loadSpecDirectory('./specs');
+ * bundle.root; // the id of the chart no other chart invokes
+ */
 export function loadSpecDirectory(directory) {
     if (!existsSync(directory))
         throw new Error(`Spec directory not found: ${directory}`);

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

@@ -1,5 +1,19 @@
 import type { Chart, Journey } from './types.js';
-/** Parse one chart from its text, by file name: SCXML or XState config in JSON or YAML. */
+/**
+ * Parses one chart from its text. The file name picks the format: `.scxml` is SCXML (the machine id
+ * falls back to the file's base name), `.json` is an XState config, anything else is read as YAML.
+ *
+ * @param file the file name, relative to the specs directory; stored as `Chart.file`.
+ * @param text the file contents.
+ * @throws Error when an XState config is not an object with a string `id` and a `states` object, or
+ *   when the text is not valid JSON/YAML/SCXML.
+ */
 export declare function parseChart(file: string, text: string): Chart;
-/** Parse a journeys file: `{ journeys: { <name>: { description, events, endsIn } } }`. */
+/**
+ * Parses a journeys file of the form `{ journeys: { <name>: { description, events, endsIn } } }`
+ * (JSON when the name ends in `.json`, otherwise YAML). Journeys come back in declaration order.
+ * `description` defaults to `''` and `endsIn` to `[]`; events are coerced to strings.
+ *
+ * @throws Error when there is no `journeys` map, or a journey has no `events` list.
+ */
 export declare function parseJourneys(file: string, text: string): Journey[];

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

@@ -1,9 +1,26 @@
+/**
+ * @module Chart and journeys parsers
+ *
+ * Turns the text of one spec file into a `Chart` or a list of `Journey`. Pure functions of their
+ * input (no file access), so they run in a browser too. They check only the shape that later stages
+ * rely on; whether the chart is executable is the linter's job.
+ *
+ * @see docs/statecharts.md
+ */
 import YAML from 'yaml';
 import { scxmlToMachine } from './scxml.js';
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-/** Parse one chart from its text, by file name: SCXML or XState config in JSON or YAML. */
+/**
+ * Parses one chart from its text. The file name picks the format: `.scxml` is SCXML (the machine id
+ * falls back to the file's base name), `.json` is an XState config, anything else is read as YAML.
+ *
+ * @param file the file name, relative to the specs directory; stored as `Chart.file`.
+ * @param text the file contents.
+ * @throws Error when an XState config is not an object with a string `id` and a `states` object, or
+ *   when the text is not valid JSON/YAML/SCXML.
+ */
 export function parseChart(file, text) {
     if (file.endsWith('.scxml')) {
         return { file, format: 'scxml', machine: scxmlToMachine(text, file.replace(/^.*[\\/]/, '').replace(/\.scxml$/, '')) };
@@ -14,7 +31,13 @@ export function parseChart(file, text) {
     }
     return { file, format: 'xstate', machine: value };
 }
-/** Parse a journeys file: `{ journeys: { <name>: { description, events, endsIn } } }`. */
+/**
+ * Parses a journeys file of the form `{ journeys: { <name>: { description, events, endsIn } } }`
+ * (JSON when the name ends in `.json`, otherwise YAML). Journeys come back in declaration order.
+ * `description` defaults to `''` and `endsIn` to `[]`; events are coerced to strings.
+ *
+ * @throws Error when there is no `journeys` map, or a journey has no `events` list.
+ */
 export function parseJourneys(file, text) {
     const value = file.endsWith('.json') ? JSON.parse(text) : YAML.parse(text);
     if (!isRecord(value) || !isRecord(value['journeys']))

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

@@ -1,6 +1,8 @@
 import type { MachineConfig } from './types.js';
 /**
- * W3C SCXML ↔ XState config, for the pure subset Atlas executes.
+ * The XML namespace of Atlas's SCXML extensions (`atlas:name`, `<atlas:meta>`, `atlas:done-event`).
+ *
+ * The SCXML conventions Atlas reads and writes:
  *
  * - `<state>`, `<parallel>`, `<final>`, `initial`, `<transition event target>`.
  * - `<invoke type="scxml" src="other.scxml" id>` composes another chart; a transition on
@@ -11,9 +13,28 @@ import type { MachineConfig } from './types.js';
  *   that are not strings are written as JSON in an element marked `type="json"`.
  */
 export declare const ATLAS_NS = "https://github.com/crvouga/atlas/ns/1";
-/** SCXML ids are XML IDs and event attributes are token lists, so names travel in `atlas:name`. */
+/**
+ * Turns a business name into a valid SCXML id/event token: ASCII lowercase letters, digits and `-`,
+ * starting with a letter or `_` (`s-` is prefixed otherwise). Lossy, so the original name is kept in `atlas:name`.
+ *
+ * @example scxmlToken('Adds a todo') // 'adds-a-todo'
+ */
 export declare function scxmlToken(name: string): string;
-/** Read an SCXML document into an XState machine config. */
+/**
+ * Reads an SCXML document into an XState machine config, restoring business names from `atlas:name`.
+ *
+ * The machine id is the `name` attribute of `<scxml>`, else `fallbackId`. `initial` is the attribute
+ * when given, else the first child state. A state's `initial` defaults to its first child state
+ * (none for `<parallel>`). Transitions without both an event and a target are skipped.
+ *
+ * @param xml the document text.
+ * @param fallbackId the machine id when the document has no `name`.
+ * @throws Error when there is no `<scxml>` root element.
+ */
 export declare function scxmlToMachine(xml: string, fallbackId?: string): MachineConfig;
-/** Write an XState machine config as an SCXML document. */
+/**
+ * Writes a machine config as an SCXML document with Atlas's `atlas:` extensions, so that
+ * `scxmlToMachine(machineToScxml(m))` gives the same chart. Ids are `scxmlToken` forms of the names;
+ * the names are kept in `atlas:name`. Only the pure subset is written: `on`, `invoke`, `meta`, nesting.
+ */
 export declare function machineToScxml(machine: MachineConfig): string;

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

@@ -1,7 +1,20 @@
+/**
+ * @module SCXML reader and writer
+ *
+ * Converts W3C SCXML to and from the XState-shaped `MachineConfig` the rest of Atlas uses, for the
+ * pure subset Atlas executes. Business names travel in an `atlas:name` attribute next to a token id,
+ * and metadata in the `atlas` namespace, so reading what `machineToScxml` wrote gives the same chart
+ * back. Browser-safe (no Node built-ins). Reading is synchronous and keeps its id-to-name table in
+ * module state for the duration of one `scxmlToMachine` call, so do not call it re-entrantly.
+ *
+ * @see docs/statecharts.md
+ */
 import { XMLBuilder, XMLParser } from 'fast-xml-parser';
 import { invokesOf, targetOf } from './types.js';
 /**
- * W3C SCXML ↔ XState config, for the pure subset Atlas executes.
+ * The XML namespace of Atlas's SCXML extensions (`atlas:name`, `<atlas:meta>`, `atlas:done-event`).
+ *
+ * The SCXML conventions Atlas reads and writes:
  *
  * - `<state>`, `<parallel>`, `<final>`, `initial`, `<transition event target>`.
  * - `<invoke type="scxml" src="other.scxml" id>` composes another chart; a transition on
@@ -65,7 +78,12 @@ function readMeta(node) {
     }
     return meta;
 }
-/** SCXML ids are XML IDs and event attributes are token lists, so names travel in `atlas:name`. */
+/**
+ * Turns a business name into a valid SCXML id/event token: ASCII lowercase letters, digits and `-`,
+ * starting with a letter or `_` (`s-` is prefixed otherwise). Lossy, so the original name is kept in `atlas:name`.
+ *
+ * @example scxmlToken('Adds a todo') // 'adds-a-todo'
+ */
 export function scxmlToken(name) {
     const token = name
         .normalize('NFKD')
@@ -148,7 +166,17 @@ function readState(node, invokeIds) {
         state.invoke = invokes.length === 1 ? invokes[0] : invokes;
     return [name, state];
 }
-/** Read an SCXML document into an XState machine config. */
+/**
+ * Reads an SCXML document into an XState machine config, restoring business names from `atlas:name`.
+ *
+ * The machine id is the `name` attribute of `<scxml>`, else `fallbackId`. `initial` is the attribute
+ * when given, else the first child state. A state's `initial` defaults to its first child state
+ * (none for `<parallel>`). Transitions without both an event and a target are skipped.
+ *
+ * @param xml the document text.
+ * @param fallbackId the machine id when the document has no `name`.
+ * @throws Error when there is no `<scxml>` root element.
+ */
 export function scxmlToMachine(xml, fallbackId = 'machine') {
     const doc = parser.parse(xml);
     const root = doc.find((n) => local(tagOf(n)) === 'scxml');
@@ -220,7 +248,11 @@ function stateToXml(name, node) {
         at['atlas:done-event'] = node.meta.doneEvent;
     return { [tag]: kids, ':@': at };
 }
-/** Write an XState machine config as an SCXML document. */
+/**
+ * Writes a machine config as an SCXML document with Atlas's `atlas:` extensions, so that
+ * `scxmlToMachine(machineToScxml(m))` gives the same chart. Ids are `scxmlToken` forms of the names;
+ * the names are kept in `atlas:name`. Only the pure subset is written: `on`, `invoke`, `meta`, nesting.
+ */
 export function machineToScxml(machine) {
     const kids = [...metaToXml(machine.meta)];
     for (const [k, v] of Object.entries(machine.states ?? {}))

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;