@crvouga/atlas 0.4.0 → 0.6.0

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

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

package/dist/core/src/signals.js

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

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

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

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 ?? {}))