@crvouga/atlas 0.0.0-stage → 0.2.0

package/dist/core/src/signals.js

@@ -0,0 +1,121 @@
+export const testId = (id) => ({ testId: id });
+export const text = (value, options = {}) => ({ text: value, ...options });
+export const role = (r, name, options = {}) => ({ role: r, ...(name ? { name } : {}), ...options });
+export const label = (value) => ({ label: value });
+export const css = (selector) => ({ css: selector });
+export function describeSignal(signal) {
+    if ('testId' in signal)
+        return `test ID "${signal.testId}"`;
+    if ('role' in signal)
+        return `${signal.role}${signal.name ? ` "${String(signal.name)}"` : ''}`;
+    if ('label' in signal)
+        return `label ${String(signal.label)}`;
+    if ('css' in signal)
+        return `selector ${signal.css}`;
+    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.
+ */
+export function signatureScreen(isVisible, describe) {
+    const visible = (ctx, signal) => isVisible(ctx, signal).catch(() => false);
+    const describeSignal = describe;
+    return function screen(spec) {
+        return {
+            async recognize(ctx) {
+                const signals = [];
+                for (const s of spec.all ?? [])
+                    signals.push({ signal: describeSignal(s), expected: 'visible', visible: await visible(ctx, s) });
+                if (spec.any?.length) {
+                    let seen = false;
+                    for (const s of spec.any)
+                        if (await visible(ctx, s))
+                            seen = true;
+                    signals.push({ signal: `one of: ${spec.any.map(describeSignal).join(' | ')}`, expected: 'visible', visible: seen });
+                }
+                for (const s of spec.none ?? [])
+                    signals.push({ signal: describeSignal(s), expected: 'hidden', visible: await visible(ctx, s) });
+                return { matched: signals.every((x) => (x.expected === 'visible' ? x.visible : !x.visible)), signals };
+            },
+            ...(spec.checks
+                ? {
+                    async checks(ctx) {
+                        const results = [];
+                        for (const { check, signal } of spec.checks) {
+                            const seen = await visible(ctx, signal);
+                            results.push({ check, passed: seen, expected: `${describeSignal(signal)} visible`, actual: seen ? 'visible' : 'not on screen' });
+                        }
+                        return results;
+                    }
+                }
+                : {}),
+            ...(spec.transient ? { transient: true } : {}),
+            ...(spec.sameAs ? { sameAs: spec.sameAs } : {}),
+            ...(spec.lookIn ? { lookIn: spec.lookIn } : {}),
+            ...(spec.settle ? { settle: spec.settle } : {})
+        };
+    };
+}
+/** A state recognised from signals on any driver that provides a `SignalContext`. */
+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. */
+export function toWire(signal) {
+    if ('testId' in signal)
+        return { kind: 'testId', id: signal.testId };
+    if ('role' in signal)
+        return { kind: 'role', role: signal.role, name: signal.name ? wire(signal.name, signal.exact) : null };
+    if ('label' in signal)
+        return { kind: 'label', match: wire(signal.label) };
+    if ('css' in signal)
+        return { kind: 'css', selector: signal.css };
+    return { kind: 'text', match: wire(signal.text, signal.exact) };
+}
+/**
+ * A function expression, as source, that finds a wire signal in a DOM: `(signal, scroll,
+ * withElement) => DomProbeResult`, plus the element itself when `withElement` is set (WebDriver
+ * returns it as an element reference). It is plain JavaScript so any driver can run it in a page (Bun WebView's
+ * `evaluate`, WebDriver's Execute Script). Roles follow the HTML-AAM implicit role mapping for the
+ * common elements; names follow aria-label, the associated label, then text content.
+ */
+export const DOM_PROBE = `(signal, scroll, withElement) => {
+  const norm = (s) => String(s || '').replace(/\\s+/g, ' ').trim();
+  const matches = (value, m) => (m.regex !== undefined ? new RegExp(m.regex, m.flags).test(value) : m.exact ? value === m.text : value.toLowerCase().includes(m.text.toLowerCase()));
+  const shown = (el) => {
+    const r = el.getBoundingClientRect();
+    const st = getComputedStyle(el);
+    return r.width > 0 && r.height > 0 && st.visibility !== 'hidden' && st.display !== 'none' && Number(st.opacity) !== 0;
+  };
+  const ROLES = {
+    button: 'button,[role=button],input[type=button],input[type=submit],input[type=reset]',
+    heading: 'h1,h2,h3,h4,h5,h6,[role=heading]',
+    link: 'a[href],[role=link]',
+    textbox: 'input:not([type]),input[type=text],input[type=email],input[type=tel],input[type=url],input[type=search],input[type=password],textarea,[role=textbox]',
+    checkbox: 'input[type=checkbox],[role=checkbox]',
+    radio: 'input[type=radio],[role=radio]',
+    combobox: 'select,[role=combobox]',
+    listitem: 'li,[role=listitem]',
+    list: 'ul,ol,[role=list]',
+    status: 'output,[role=status]',
+    alert: '[role=alert]',
+    dialog: 'dialog,[role=dialog]',
+    img: 'img[alt],[role=img]'
+  };
+  const labelOf = (el) => norm(el.getAttribute('aria-label') || (el.labels && el.labels[0] ? el.labels[0].textContent : ''));
+  const nameOf = (el) => labelOf(el) || norm(el.textContent) || norm(el.getAttribute('alt') || el.getAttribute('title') || el.getAttribute('placeholder') || (el.type === 'submit' || el.type === 'button' ? el.value : ''));
+  const ownText = (el) => Array.from(el.childNodes).some((n) => n.nodeType === 3 && n.textContent.trim());
+  let found = [];
+  if (signal.kind === 'css') found = Array.from(document.querySelectorAll(signal.selector));
+  else if (signal.kind === 'testId') found = Array.from(document.querySelectorAll('[data-testid="' + CSS.escape(signal.id) + '"]'));
+  else if (signal.kind === 'role') found = Array.from(document.querySelectorAll(ROLES[signal.role] || '[role="' + signal.role + '"]')).filter((el) => !signal.name || matches(nameOf(el), signal.name));
+  else if (signal.kind === 'label') found = Array.from(document.querySelectorAll('input,textarea,select,[aria-label]')).filter((el) => matches(labelOf(el), signal.match));
+  else found = Array.from(document.querySelectorAll('body *')).filter((el) => ownText(el) && matches(norm(el.textContent), signal.match));
+  const el = found.find(shown);
+  if (!el) return { visible: false, count: found.length };
+  if (scroll) el.scrollIntoView({ block: 'center', inline: 'center' });
+  const r = el.getBoundingClientRect();
+  const at = { visible: true, count: found.length, x: r.x + r.width / 2, y: r.y + r.height / 2 };
+  return withElement ? Object.assign(at, { element: el }) : at;
+}`;

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

@@ -0,0 +1,28 @@
+import type { MachineConfig, SpecBundle } from './types.js';
+export type HandOff = {
+    finalState: string;
+    event: string;
+    parentState: string;
+    childChart: string;
+};
+export type Composition = {
+    machine: MachineConfig;
+    /** Which chart each state came from. */
+    chartOf: Map<string, string>;
+    /** A child's former final states and the event each hands to its parent. */
+    handOffs: HandOff[];
+    /** The state each child chart is inlined into. */
+    hosts: Map<string, string>;
+};
+/**
+ * Inline 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>`;
+ * - a final state's `meta.doneEvent`, naming the event the parent receives from that final;
+ * - the legacy `meta.childMachine` + `meta.childFinalEvents` on the parent state.
+ *
+ * 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.
+ */
+export declare function composeCharts(bundle: SpecBundle): Composition;

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

@@ -0,0 +1,71 @@
+import { invokesOf, targetOf, walkStates } from './types.js';
+function asTransition(t) {
+    const target = targetOf(t);
+    return target ? { target: `#${target}` } : undefined;
+}
+/**
+ * Inline 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>`;
+ * - a final state's `meta.doneEvent`, naming the event the parent receives from that final;
+ * - the legacy `meta.childMachine` + `meta.childFinalEvents` on the parent state.
+ *
+ * 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.
+ */
+export function composeCharts(bundle) {
+    const byId = new Map(bundle.charts.map((c) => [c.machine.id, c.machine]));
+    const chartOf = new Map();
+    const handOffs = [];
+    const hosts = new Map();
+    const root = byId.get(bundle.root);
+    if (!root)
+        throw new Error(`Root chart "${bundle.root}" is not loaded`);
+    const inline = (name, node, chart, stack) => {
+        chartOf.set(name, chart);
+        const invoke = invokesOf(node)[0] ?? (typeof node.meta?.childMachine === 'string' ? { src: node.meta.childMachine } : undefined);
+        if (invoke) {
+            const child = byId.get(invoke.src);
+            if (!child)
+                throw new Error(`"${name}" invokes chart "${invoke.src}", which is not loaded`);
+            hosts.set(invoke.src, name);
+            if (stack.includes(invoke.src))
+                throw new Error(`Charts invoke each other in a cycle: ${[...stack, invoke.src].join(' → ')}`);
+            const legacy = node.meta?.childFinalEvents ?? {};
+            const doneEvent = `done.invoke.${invoke.id ?? invoke.src}`;
+            const consumed = new Set();
+            const retarget = (states) => Object.fromEntries(Object.entries(states).map(([k, s]) => {
+                if (s.type === 'final') {
+                    const event = legacy[k] ?? (typeof s.meta?.doneEvent === 'string' ? s.meta.doneEvent : doneEvent);
+                    const transition = asTransition(node.on?.[event]) ?? asTransition(invoke.onDone);
+                    if (!transition)
+                        throw new Error(`Child final "${k}" has nowhere to go in "${name}" (no "${event}" or onDone)`);
+                    consumed.add(event);
+                    handOffs.push({ finalState: k, event, parentState: name, childChart: invoke.src });
+                    const { type: _final, ...rest } = s;
+                    chartOf.set(k, invoke.src);
+                    return [k, { ...rest, on: { ...rest.on, [event]: transition } }];
+                }
+                return [k, inline(k, s, invoke.src, [...stack, invoke.src])];
+            }));
+            const states = retarget(child.states ?? {});
+            const { invoke: _invoke, initial: _initial, on: _on, ...withoutInvoke } = node;
+            const on = Object.fromEntries(Object.entries(node.on ?? {}).filter(([event]) => !consumed.has(event)));
+            return { ...withoutInvoke, ...(child.initial === undefined ? {} : { initial: child.initial }), states, ...(Object.keys(on).length ? { on } : {}) };
+        }
+        if (!node.states)
+            return node;
+        return {
+            ...node,
+            states: Object.fromEntries(Object.entries(node.states).map(([k, v]) => [k, inline(k, v, chart, stack)]))
+        };
+    };
+    const states = Object.fromEntries(Object.entries(root.states ?? {}).map(([k, v]) => [k, inline(k, v, root.id, [root.id])]));
+    const machine = JSON.parse(JSON.stringify({ ...root, states }));
+    for (const { name, node } of walkStates(machine)) {
+        if (!node.id)
+            node.id = name;
+    }
+    return { machine, chartOf, handOffs, hosts };
+}

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

@@ -0,0 +1,5 @@
+/** Browser-safe: parsing, SCXML conversion and composition, with no Node built-ins. */
+export * from './types.js';
+export { parseChart, parseJourneys } from './parse.js';
+export { scxmlToMachine, machineToScxml, scxmlToken, ATLAS_NS } from './scxml.js';
+export { composeCharts, type Composition, type HandOff } from './compose.js';

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

@@ -0,0 +1,5 @@
+/** Browser-safe: parsing, SCXML conversion and composition, with no Node built-ins. */
+export * from './types.js';
+export { parseChart, parseJourneys } from './parse.js';
+export { scxmlToMachine, machineToScxml, scxmlToken, ATLAS_NS } from './scxml.js';
+export { composeCharts } from './compose.js';

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

@@ -0,0 +1,8 @@
+import type { Chart, Journey, MachineConfig, SpecBundle } from './types.js';
+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>;
+export declare function bundleOf(directory: string, charts: Chart[], journeys: Journey[]): SpecBundle;
+/** Load every chart and journeys file directly inside `directory`. */
+export declare function loadSpecDirectory(directory: string): SpecBundle;

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

@@ -0,0 +1,46 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseChart, parseJourneys } from './parse.js';
+import { invokesOf, walkStates } from './types.js';
+export { parseChart, parseJourneys };
+const CHART_FILE = /(\.scxml|(^|\.)machine\.(ya?ml|json))$/;
+const JOURNEY_FILE = /^journeys\.(ya?ml|json)$/;
+/** The ids of the charts a machine composes, by `invoke` or the legacy `meta.childMachine`. */
+export function childChartIds(machine) {
+    const ids = new Set();
+    for (const { node } of walkStates(machine)) {
+        for (const invoke of invokesOf(node))
+            ids.add(invoke.src);
+        if (typeof node.meta?.childMachine === 'string')
+            ids.add(node.meta.childMachine);
+    }
+    return ids;
+}
+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));
+    const root = roots[0]?.machine.id ?? charts[0]?.machine.id;
+    if (!root)
+        throw new Error(`No statechart found in ${directory}`);
+    return { directory, charts, journeys, root };
+}
+/** Load every chart and journeys file directly inside `directory`. */
+export function loadSpecDirectory(directory) {
+    if (!existsSync(directory))
+        throw new Error(`Spec directory not found: ${directory}`);
+    const files = readdirSync(directory).sort();
+    const rank = (f) => (f.endsWith('.scxml') ? 0 : /\.ya?ml$/.test(f) ? 1 : 2);
+    const parsed = files
+        .filter((f) => CHART_FILE.test(f))
+        .sort((a, b) => rank(a) - rank(b) || a.localeCompare(b))
+        .map((f) => parseChart(f, readFileSync(path.join(directory, f), 'utf8')));
+    const byId = new Map();
+    for (const chart of parsed)
+        if (!byId.has(chart.machine.id))
+            byId.set(chart.machine.id, chart);
+    const charts = [...byId.values()];
+    const journeys = files
+        .filter((f) => JOURNEY_FILE.test(f))
+        .flatMap((f) => parseJourneys(f, readFileSync(path.join(directory, f), 'utf8')));
+    return bundleOf(directory, charts, journeys);
+}

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

@@ -0,0 +1,5 @@
+import type { Chart, Journey } from './types.js';
+/** Parse one chart from its text, by file name: SCXML or XState config in JSON or YAML. */
+export declare function parseChart(file: string, text: string): Chart;
+/** Parse a journeys file: `{ journeys: { <name>: { description, events, endsIn } } }`. */
+export declare function parseJourneys(file: string, text: string): Journey[];

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

@@ -0,0 +1,32 @@
+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. */
+export function parseChart(file, text) {
+    if (file.endsWith('.scxml')) {
+        return { file, format: 'scxml', machine: scxmlToMachine(text, file.replace(/^.*[\\/]/, '').replace(/\.scxml$/, '')) };
+    }
+    const value = file.endsWith('.json') ? JSON.parse(text) : YAML.parse(text);
+    if (!isRecord(value) || typeof value['id'] !== 'string' || !isRecord(value['states'])) {
+        throw new Error(`${file} is not an XState machine config with an id and states`);
+    }
+    return { file, format: 'xstate', machine: value };
+}
+/** Parse a journeys file: `{ journeys: { <name>: { description, events, endsIn } } }`. */
+export function parseJourneys(file, text) {
+    const value = file.endsWith('.json') ? JSON.parse(text) : YAML.parse(text);
+    if (!isRecord(value) || !isRecord(value['journeys']))
+        throw new Error(`${file} has no journeys map`);
+    return Object.entries(value['journeys']).map(([name, raw]) => {
+        if (!isRecord(raw) || !Array.isArray(raw['events']))
+            throw new Error(`${file}: journey "${name}" needs an events list`);
+        return {
+            name,
+            description: typeof raw['description'] === 'string' ? raw['description'] : '',
+            events: raw['events'].map(String),
+            endsIn: Array.isArray(raw['endsIn']) ? raw['endsIn'].map(String) : []
+        };
+    });
+}

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

@@ -0,0 +1,19 @@
+import type { MachineConfig } from './types.js';
+/**
+ * W3C SCXML ↔ XState config, for the pure subset Atlas executes.
+ *
+ * - `<state>`, `<parallel>`, `<final>`, `initial`, `<transition event target>`.
+ * - `<invoke type="scxml" src="other.scxml" id>` composes another chart; a transition on
+ *   `done.invoke.<id>` (or `done.invoke`) becomes the invoke's `onDone`.
+ * - Business metadata lives in a foreign namespace, as SCXML allows:
+ *   `<atlas:meta><atlas:description>…</atlas:description><atlas:event>…</atlas:event></atlas:meta>`.
+ *   A final state's `atlas:done-event` attribute names the event its parent receives. Meta values
+ *   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`. */
+export declare function scxmlToken(name: string): string;
+/** Read an SCXML document into an XState machine config. */
+export declare function scxmlToMachine(xml: string, fallbackId?: string): MachineConfig;
+/** Write an XState machine config as an SCXML document. */
+export declare function machineToScxml(machine: MachineConfig): string;

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

@@ -0,0 +1,239 @@
+import { XMLBuilder, XMLParser } from 'fast-xml-parser';
+import { invokesOf, targetOf } from './types.js';
+/**
+ * W3C SCXML ↔ XState config, for the pure subset Atlas executes.
+ *
+ * - `<state>`, `<parallel>`, `<final>`, `initial`, `<transition event target>`.
+ * - `<invoke type="scxml" src="other.scxml" id>` composes another chart; a transition on
+ *   `done.invoke.<id>` (or `done.invoke`) becomes the invoke's `onDone`.
+ * - Business metadata lives in a foreign namespace, as SCXML allows:
+ *   `<atlas:meta><atlas:description>…</atlas:description><atlas:event>…</atlas:event></atlas:meta>`.
+ *   A final state's `atlas:done-event` attribute names the event its parent receives. Meta values
+ *   that are not strings are written as JSON in an element marked `type="json"`.
+ */
+export const ATLAS_NS = 'https://github.com/crvouga/atlas/ns/1';
+const SCXML_NS = 'http://www.w3.org/2005/07/scxml';
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '',
+    preserveOrder: true,
+    trimValues: true
+});
+function tagOf(node) {
+    return Object.keys(node).find((k) => k !== ':@') ?? '';
+}
+function local(tag) {
+    return tag.includes(':') ? tag.slice(tag.indexOf(':') + 1) : tag;
+}
+function children(node) {
+    const value = node[tagOf(node)];
+    return Array.isArray(value) ? value : [];
+}
+function text(node) {
+    return children(node)
+        .map((c) => (typeof c['#text'] === 'string' || typeof c['#text'] === 'number' ? String(c['#text']) : text(c)))
+        .join('')
+        .trim();
+}
+function attrs(node) {
+    return node[':@'] ?? {};
+}
+const META_LISTS = new Set(['event', 'source', 'check', 'hint']);
+const META_LIST_KEYS = { event: 'events', source: 'source', check: 'checks', hint: 'hints' };
+function readMeta(node) {
+    const meta = {};
+    for (const child of children(node)) {
+        const key = local(tagOf(child));
+        if (META_LISTS.has(key)) {
+            const listKey = META_LIST_KEYS[key];
+            meta[listKey] = [...(meta[listKey] ?? []), text(child)];
+        }
+        else if (key === 'deadEnd' || key === 'dead-end') {
+            meta.deadEnd = text(child);
+        }
+        else if (attrs(child)['type'] === 'json') {
+            try {
+                meta[key] = JSON.parse(text(child));
+            }
+            catch {
+                meta[key] = text(child);
+            }
+        }
+        else {
+            meta[key] = text(child);
+        }
+    }
+    return meta;
+}
+/** SCXML ids are XML IDs and event attributes are token lists, so names travel in `atlas:name`. */
+export function scxmlToken(name) {
+    const token = name
+        .normalize('NFKD')
+        .replace(/[^A-Za-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+    return /^[a-z_]/.test(token) ? token : `s-${token}`;
+}
+function collectNames(nodes, names) {
+    for (const node of nodes) {
+        const tag = local(tagOf(node));
+        if (tag === 'state' || tag === 'parallel' || tag === 'final') {
+            const a = attrs(node);
+            if (a['id'])
+                names.set(a['id'], a['atlas:name'] ?? a['id']);
+        }
+        collectNames(children(node), names);
+    }
+}
+let currentNames = new Map();
+const nameOf = (id) => currentNames.get(id) ?? id;
+function readState(node, invokeIds) {
+    const tag = local(tagOf(node));
+    const a = attrs(node);
+    const name = nameOf(a['id'] ?? '');
+    const state = { id: name };
+    if (tag === 'parallel')
+        state.type = 'parallel';
+    if (tag === 'final')
+        state.type = 'final';
+    const states = {};
+    const invokes = [];
+    for (const child of children(node)) {
+        if (local(tagOf(child)) !== 'invoke')
+            continue;
+        const ca = attrs(child);
+        const src = (ca['src'] ?? '').replace(/\.scxml$/, '').replace(/^.*\//, '');
+        const invoke = { src: ca['atlas:name'] ?? src, ...(ca['id'] ? { id: ca['id'] } : {}) };
+        invokes.push(invoke);
+        if (ca['id'])
+            invokeIds.set(ca['id'], invoke);
+    }
+    for (const child of children(node)) {
+        const childTag = local(tagOf(child));
+        const ca = attrs(child);
+        if (childTag === 'state' || childTag === 'parallel' || childTag === 'final') {
+            const [k, v] = readState(child, invokeIds);
+            states[k] = v;
+        }
+        else if (childTag === 'transition') {
+            const event = ca['atlas:name'] ?? ca['event'];
+            if (!event || !ca['target'])
+                continue;
+            const target = nameOf(ca['target']);
+            const raw = ca['atlas:name'] ? '' : event;
+            if (raw === 'done.invoke' || raw.startsWith('done.invoke.')) {
+                const id = raw.slice('done.invoke.'.length);
+                const invoke = invokes.find((i) => !id || i.id === id) ?? invokeIds.get(id);
+                if (invoke) {
+                    invoke.onDone = { target: `#${target}` };
+                    continue;
+                }
+            }
+            state.on = { ...state.on, [event]: { target: `#${target}` } };
+        }
+        else if (childTag === 'meta' || tagOf(child).startsWith('atlas:')) {
+            state.meta = { ...state.meta, ...readMeta(child) };
+        }
+    }
+    const doneEvent = a['atlas:done-event'];
+    if (doneEvent)
+        state.meta = { ...state.meta, doneEvent };
+    if (a['initial'])
+        state.initial = nameOf(a['initial']);
+    else if (Object.keys(states).length && tag !== 'parallel')
+        state.initial = Object.keys(states)[0];
+    if (Object.keys(states).length)
+        state.states = states;
+    if (invokes.length)
+        state.invoke = invokes.length === 1 ? invokes[0] : invokes;
+    return [name, state];
+}
+/** Read an SCXML document into an XState machine config. */
+export function scxmlToMachine(xml, fallbackId = 'machine') {
+    const doc = parser.parse(xml);
+    const root = doc.find((n) => local(tagOf(n)) === 'scxml');
+    if (!root)
+        throw new Error('Not an SCXML document: no <scxml> root element');
+    const a = attrs(root);
+    currentNames = new Map();
+    collectNames(children(root), currentNames);
+    const invokeIds = new Map();
+    const machine = { id: a['name'] ?? fallbackId };
+    const states = {};
+    for (const child of children(root)) {
+        const tag = local(tagOf(child));
+        if (tag === 'state' || tag === 'parallel' || tag === 'final') {
+            const [k, v] = readState(child, invokeIds);
+            states[k] = v;
+        }
+        else if (tag === 'meta' || tagOf(child).startsWith('atlas:')) {
+            machine.meta = { ...machine.meta, ...readMeta(child) };
+        }
+    }
+    const initial = a['initial'] ? nameOf(a['initial']) : Object.keys(states)[0];
+    if (initial !== undefined)
+        machine.initial = initial;
+    for (const [name, state] of Object.entries(states))
+        state.id = name;
+    machine.states = states;
+    return machine;
+}
+function metaToXml(meta) {
+    if (!meta)
+        return [];
+    const items = [];
+    for (const [key, value] of Object.entries(meta)) {
+        if (key === 'doneEvent' || value === undefined)
+            continue;
+        const listTag = Object.entries(META_LIST_KEYS).find(([, k]) => k === key)?.[0];
+        if (listTag && Array.isArray(value)) {
+            for (const v of value)
+                items.push({ [`atlas:${listTag}`]: [{ '#text': String(v) }] });
+        }
+        else if (typeof value === 'string') {
+            items.push({ [`atlas:${key}`]: [{ '#text': value }] });
+        }
+        else {
+            items.push({ [`atlas:${key}`]: [{ '#text': JSON.stringify(value) }], ':@': { type: 'json' } });
+        }
+    }
+    return items.length ? [{ 'atlas:meta': items }] : [];
+}
+function stateToXml(name, node) {
+    const tag = node.type === 'parallel' ? 'parallel' : node.type === 'final' ? 'final' : 'state';
+    const kids = [...metaToXml(node.meta)];
+    for (const [event, t] of Object.entries(node.on ?? {})) {
+        kids.push({ transition: [], ':@': { event: scxmlToken(event), target: scxmlToken(targetOf(t)), 'atlas:name': event } });
+    }
+    for (const [i, invoke] of invokesOf(node).entries()) {
+        const id = scxmlToken(invoke.id ?? `${name} invoke ${i}`);
+        kids.push({ invoke: [], ':@': { type: 'scxml', src: `${scxmlToken(invoke.src)}.scxml`, id, 'atlas:name': invoke.src } });
+        if (invoke.onDone)
+            kids.push({ transition: [], ':@': { event: `done.invoke.${id}`, target: scxmlToken(targetOf(invoke.onDone)) } });
+    }
+    for (const [k, v] of Object.entries(node.states ?? {}))
+        kids.push(stateToXml(k, v));
+    const at = { id: scxmlToken(name), 'atlas:name': name };
+    if (node.initial && node.type !== 'parallel')
+        at['initial'] = scxmlToken(node.initial);
+    if (typeof node.meta?.doneEvent === 'string')
+        at['atlas:done-event'] = node.meta.doneEvent;
+    return { [tag]: kids, ':@': at };
+}
+/** Write an XState machine config as an SCXML document. */
+export function machineToScxml(machine) {
+    const kids = [...metaToXml(machine.meta)];
+    for (const [k, v] of Object.entries(machine.states ?? {}))
+        kids.push(stateToXml(k, v));
+    const at = {
+        xmlns: SCXML_NS,
+        'xmlns:atlas': ATLAS_NS,
+        version: '1.0',
+        name: machine.id,
+        datamodel: 'null'
+    };
+    if (machine.initial)
+        at['initial'] = scxmlToken(machine.initial);
+    const builder = new XMLBuilder({ ignoreAttributes: false, attributeNamePrefix: '', preserveOrder: true, format: true, suppressEmptyNode: true });
+    return `<?xml version="1.0" encoding="UTF-8"?>\n${String(builder.build([{ scxml: kids, ':@': at }])).trim()}\n`;
+}