@crvouga/atlas 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+export type TransitionConfig = {
+    target: string;
+};
+export type InvokeConfig = {
+    /** The id of another chart in the bundle; composed statically. */
+    src: string;
+    id?: string;
+    /** Where the parent goes when the child reaches a final state (`done.invoke.<id>`). */
+    onDone?: string | TransitionConfig;
+};
+export type StateMeta = {
+    description?: string;
+    snapshot?: string;
+    events?: string[];
+    confidence?: 'confirmed' | 'assumed';
+    source?: string[];
+    checks?: string[];
+    contracts?: {
+        id: string;
+        name: string;
+        source: string;
+        description?: string;
+        steps: {
+            keyword: string;
+            text: string;
+            table?: string[][];
+            docString?: string;
+        }[];
+    }[];
+    deadEnd?: string;
+    /** Legacy composition: the chart that runs inside this state. Prefer `invoke`. */
+    childMachine?: string;
+    /** Legacy composition: child final state → the event the parent receives. Prefer `invoke`. */
+    childFinalEvents?: Record<string, string>;
+    /** On a final state: the event the parent receives when this final is reached. */
+    doneEvent?: string;
+    [key: string]: unknown;
+};
+export type StateConfig = {
+    id?: string;
+    initial?: string;
+    type?: 'parallel' | 'final';
+    meta?: StateMeta;
+    states?: Record<string, StateConfig>;
+    on?: Record<string, TransitionConfig | string>;
+    invoke?: InvokeConfig | InvokeConfig[];
+    [key: string]: unknown;
+};
+export type MachineConfig = StateConfig & {
+    id: string;
+};
+export type Journey = {
+    name: string;
+    description: string;
+    events: string[];
+    endsIn: string[];
+};
+export type Chart = {
+    /** Path relative to the spec directory. */
+    file: string;
+    format: 'scxml' | 'xstate';
+    machine: MachineConfig;
+};
+export type SpecBundle = {
+    directory: string;
+    charts: Chart[];
+    journeys: Journey[];
+    /** The chart the others are composed into: the one no other chart invokes. */
+    root: string;
+};
+export declare const TRANSITION_SEPARATOR = " :: ";
+export declare function transitionId(source: string, event: string): string;
+export declare function splitTransitionId(id: string): {
+    source: string;
+    event: string;
+};
+export declare function targetOf(t: TransitionConfig | string | undefined): string | undefined;
+export type StateEntry = {
+    name: string;
+    node: StateConfig;
+    trail: string[];
+};
+export declare function walkStates(config: StateConfig, trail?: string[]): StateEntry[];
+export declare function invokesOf(node: StateConfig): InvokeConfig[];

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

@@ -0,0 +1,25 @@
+export const TRANSITION_SEPARATOR = ' :: ';
+export function transitionId(source, event) {
+    return `${source}${TRANSITION_SEPARATOR}${event}`;
+}
+export function splitTransitionId(id) {
+    const at = id.indexOf(TRANSITION_SEPARATOR);
+    return { source: id.slice(0, at), event: id.slice(at + TRANSITION_SEPARATOR.length) };
+}
+export function targetOf(t) {
+    if (t === undefined)
+        return undefined;
+    const raw = typeof t === 'string' ? t : t.target;
+    return raw.startsWith('#') ? raw.slice(1) : raw;
+}
+export function walkStates(config, trail = []) {
+    return Object.entries(config.states ?? {}).flatMap(([name, node]) => [
+        { name, node, trail },
+        ...walkStates(node, [...trail, name])
+    ]);
+}
+export function invokesOf(node) {
+    if (!node.invoke)
+        return [];
+    return Array.isArray(node.invoke) ? node.invoke : [node.invoke];
+}

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

@@ -0,0 +1,75 @@
+import type { Driver, StateImplementation, Timeline } from '../../core/src/index.js';
+import type { Signal, SignalContext } from '../../core/src/signals.js';
+/**
+ * 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.
+ */
+export type DetoxMatcher = unknown;
+export type DetoxApi = {
+    device: {
+        launchApp(params?: Record<string, unknown>): Promise<void>;
+        openURL?(params: {
+            url: string;
+        }): Promise<void>;
+        terminateApp?(): Promise<void>;
+        takeScreenshot(name: string): Promise<string>;
+    };
+    element(matcher: DetoxMatcher): {
+        tap(): Promise<void>;
+        typeText(text: string): Promise<void>;
+        replaceText?(text: string): Promise<void>;
+    };
+    by: {
+        id(id: string): DetoxMatcher;
+        text(text: string): DetoxMatcher;
+        label(label: string): DetoxMatcher;
+        traits?(traits: string[]): DetoxMatcher & {
+            and?(other: DetoxMatcher): DetoxMatcher;
+        };
+    };
+    waitFor(element: unknown): {
+        toBeVisible(): {
+            withTimeout(ms: number): Promise<void>;
+        };
+    };
+};
+/** Detox's API plus a `SignalContext`, so implementations written against signals run here too. */
+export type DetoxContext = DetoxApi & SignalContext & {
+    timeline: Timeline;
+    /** Tap an element and log it to the step timeline. */
+    tap(matcher: DetoxMatcher, label: string): Promise<void>;
+    type(matcher: DetoxMatcher, text: string, label: string): Promise<void>;
+};
+export type DetoxDriverOptions = {
+    /** Detox's globals; `globalThis` (where Detox puts them) by default. */
+    api?: DetoxApi;
+    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.
+ */
+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.
+ */
+export declare function detoxDriver(options?: DetoxDriverOptions): Driver<DetoxContext>;
+/** A state recognised by Detox matchers: every `all` visible and no `none` visible. */
+export declare function detoxScreen(spec: {
+    all: {
+        matcher: DetoxMatcher;
+        name: string;
+    }[];
+    none?: {
+        matcher: DetoxMatcher;
+        name: string;
+    }[];
+    checks?: {
+        check: string;
+        matcher: DetoxMatcher;
+        name: string;
+    }[];
+}): StateImplementation<DetoxContext>;

package/dist/detox/src/index.js

@@ -0,0 +1,110 @@
+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.
+ */
+export function detoxMatcher(api, signal) {
+    if ('testId' in signal)
+        return api.by.id(signal.testId);
+    if ('css' in signal)
+        throw new Error(`${describeSignal(signal)}: CSS selectors only work in web sessions`);
+    const value = 'label' in signal ? signal.label : 'role' in signal ? signal.name : signal.text;
+    if (value === undefined)
+        throw new Error(`${describeSignal(signal)}: Detox needs a name to find a role`);
+    if (value instanceof RegExp)
+        throw new Error(`${describeSignal(signal)}: Detox matches exact text, not regular expressions`);
+    if ('text' in signal)
+        return api.by.text(value);
+    const byLabel = api.by.label(value);
+    if ('role' in signal && signal.role === 'button' && api.by.traits) {
+        const trait = api.by.traits(['button']);
+        return trait.and ? trait.and(byLabel) : byLabel;
+    }
+    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.
+ */
+export function detoxDriver(options = {}) {
+    const api = () => options.api ?? globalThis;
+    return {
+        name: 'detox',
+        async open({ timeline }) {
+            const d = api();
+            await d.device.launchApp({ newInstance: true, ...(options.launchArgs ? { launchArgs: options.launchArgs } : {}) });
+            const tap = async (matcher, label) => {
+                timeline.add({ kind: 'tap', label });
+                await d.element(matcher).tap();
+            };
+            const type = async (matcher, text, label) => {
+                timeline.add({ kind: 'type', label, text });
+                await d.element(matcher).typeText(text);
+            };
+            const ctx = {
+                ...d,
+                timeline,
+                tap,
+                type,
+                async goto(url) {
+                    if (!d.device.openURL)
+                        throw new Error('This Detox device cannot open URLs');
+                    await d.device.openURL({ url });
+                },
+                isVisible: (signal) => visible(ctx, detoxMatcher(d, signal)),
+                user: {
+                    tap: (signal, label) => tap(detoxMatcher(d, signal), label),
+                    type: (signal, text, label) => type(detoxMatcher(d, signal), text, label)
+                }
+            };
+            return ctx;
+        },
+        async close(ctx) {
+            await ctx.device.terminateApp?.().catch(() => undefined);
+        },
+        async screenshot(ctx, file) {
+            const taken = await ctx.device.takeScreenshot(path.basename(file, '.png'));
+            mkdirSync(path.dirname(file), { recursive: true });
+            copyFileSync(taken, file);
+            return { png: file };
+        }
+    };
+}
+async function visible(ctx, matcher) {
+    try {
+        await ctx.waitFor(ctx.element(matcher)).toBeVisible().withTimeout(0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A state recognised by Detox matchers: every `all` visible and no `none` visible. */
+export function detoxScreen(spec) {
+    return {
+        async recognize(ctx) {
+            const signals = [];
+            for (const s of spec.all)
+                signals.push({ signal: s.name, expected: 'visible', visible: await visible(ctx, s.matcher) });
+            for (const s of spec.none ?? [])
+                signals.push({ signal: s.name, expected: 'hidden', visible: await visible(ctx, s.matcher) });
+            return { matched: signals.every((x) => (x.expected === 'visible' ? x.visible : !x.visible)), signals };
+        },
+        ...(spec.checks
+            ? {
+                async checks(ctx) {
+                    const out = [];
+                    for (const c of spec.checks) {
+                        const ok = await visible(ctx, c.matcher);
+                        out.push({ check: c.check, passed: ok, expected: `${c.name} visible`, actual: ok ? 'visible' : 'not on screen' });
+                    }
+                    return out;
+                }
+            }
+            : {})
+    };
+}

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

@@ -0,0 +1,44 @@
+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';
+import type { Pacing } from './media.js';
+import { UserActions } from './media.js';
+/**
+ * What every Playwright event and recogniser receives for one path attempt. It is a
+ * `SignalContext` too, so implementations written against signals run here unchanged.
+ */
+export type PlaywrightContext = SignalContext & {
+    page: Page;
+    context: BrowserContext;
+    browser: Browser;
+    /** Paced taps and typing, logged to the step's timeline and shown by the touch overlay in videos. */
+    user: UserActions;
+};
+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;
+    launch?: LaunchOptions;
+    /** Override the pacing used in showcase mode. */
+    pacing?: Partial<Pacing>;
+    /** Install Playwright's fake clock before the app loads, so time events can jump it. */
+    clock?: boolean;
+    /** Save a Playwright trace for failed attempts (default true). */
+    traceOnFailure?: boolean;
+    /**
+     * Which attempts record a trace: `retry` (default) traces only the retry of a failed path, which
+     * keeps first attempts fast; `always` traces every attempt so even a first failure has one.
+     */
+    trace?: 'retry' | 'always';
+    /** Called after the page is created and before the implementation's setup. */
+    onPage?: (page: Page) => Promise<void>;
+    /** Browser contexts open at once (one per worker); unlimited when omitted. */
+    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).
+ */
+export declare function playwrightDriver(options?: PlaywrightDriverOptions): Driver<PlaywrightContext>;

package/dist/playwright/src/driver.js

@@ -0,0 +1,82 @@
+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).
+ */
+export function playwrightDriver(options = {}) {
+    let browser = null;
+    const tracedContexts = new WeakSet();
+    const device = options.device ?? PHONE;
+    const scale = device.deviceScaleFactor ?? 1;
+    const showcasePacing = { ...SHOWCASE_PACING, ...options.pacing };
+    const ensureBrowser = async () => {
+        const current = browser ? await browser.catch(() => null) : null;
+        if (current?.isConnected())
+            return current;
+        browser = chromium.launch(options.launch);
+        return browser;
+    };
+    return {
+        name: 'playwright',
+        pacing: { before: showcasePacing.holdBeforeMs, after: showcasePacing.holdAfterMs },
+        concurrency: options.concurrency ?? Number.POSITIVE_INFINITY,
+        async open({ mode, timeline, attempt }) {
+            const b = await ensureBrowser();
+            const context = await b.newContext(device);
+            const tracing = options.traceOnFailure !== false && (options.trace === 'always' || attempt > 1);
+            if (tracing)
+                await context.tracing.start({ screenshots: true, snapshots: true });
+            tracedContexts.add(context);
+            if (!tracing)
+                tracedContexts.delete(context);
+            const page = await context.newPage();
+            const showcase = mode === 'showcase';
+            if (showcase)
+                await UserActions.install(page);
+            if (options.clock)
+                await page.clock.install();
+            await options.onPage?.(page);
+            const baseUrl = typeof options.baseUrl === 'function' ? await options.baseUrl() : options.baseUrl;
+            return {
+                page,
+                context,
+                browser: b,
+                user: new UserActions(page, showcase ? showcasePacing : FAST_PACING, timeline, showcase),
+                goto: async (url) => {
+                    await page.goto(baseUrl ? new URL(url, baseUrl).href : url);
+                },
+                isVisible: (signal) => locate(page, signal).isVisible().catch(() => false)
+            };
+        },
+        async close(ctx, { failed, traceFile }) {
+            let trace;
+            if (tracedContexts.delete(ctx.context)) {
+                if (failed) {
+                    await ctx.context.tracing.stop({ path: traceFile }).catch(() => undefined);
+                    trace = traceFile;
+                }
+                else {
+                    await ctx.context.tracing.stop().catch(() => undefined);
+                }
+            }
+            await ctx.context.close().catch(() => undefined);
+            return trace ? { trace } : undefined;
+        },
+        screenshot: (ctx, file) => captureScreen(ctx.page, ctx.user, file),
+        async record(ctx, workDirectory) {
+            const recorder = new ScreencastRecorder(ctx.page, scale);
+            await recorder.start(workDirectory);
+            return { stop: (output) => recorder.stop(output) };
+        },
+        text: (ctx) => ctx.page.evaluate(() => document.body.innerText),
+        hold: (ctx, ms) => ctx.page.waitForTimeout(ms),
+        async dispose() {
+            const current = browser;
+            browser = null;
+            await current?.then((b) => b.close()).catch(() => undefined);
+        }
+    };
+}

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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,68 @@
+import type { Locator, Page } from 'playwright';
+import type { Timeline } from '../../core/src/index.js';
+import type { Signal } from '../../core/src/signals.js';
+export type Pacing = {
+    moveMs: number;
+    pauseBeforeTapMs: number;
+    typeDelayMs: number;
+    holdAfterMs: number;
+    holdBeforeMs: number;
+};
+export declare const SHOWCASE_PACING: Pacing;
+export declare const FAST_PACING: Pacing;
+export declare const PHONE: {
+    readonly viewport: {
+        readonly width: 390;
+        readonly height: 844;
+    };
+    readonly deviceScaleFactor: 3;
+    readonly isMobile: true;
+    readonly hasTouch: true;
+};
+/** Taps and typing a person would do, paced for showcase videos and logged to the step timeline. */
+export declare class UserActions {
+    readonly page: Page;
+    readonly pacing: Pacing;
+    timeline: Timeline;
+    readonly showTouches: boolean;
+    constructor(page: Page, pacing: Pacing, timeline: Timeline, showTouches: boolean);
+    static install(page: Page): Promise<void>;
+    private overlay;
+    /** Tap a locator or a signal (resolved with `locate`). */
+    tap(target: Locator | Signal, label: string): Promise<void>;
+    type(target: Locator | Signal, text: string, label: string): Promise<void>;
+    hold(ms: number): Promise<void>;
+    hideTouches(): Promise<void>;
+    showTouchLayer(): Promise<void>;
+}
+export type ScreenshotFiles = {
+    png: string;
+    webp?: string;
+};
+/** A settled, deterministic capture at device resolution, with the touch layer hidden. */
+export declare function captureScreen(page: Page, driver: UserActions, file: string, mask?: Locator[]): Promise<ScreenshotFiles>;
+export declare function ffmpeg(args: string[]): Promise<void>;
+/**
+ * Records a clip at the phone's physical resolution (1170×2532). 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
+ * long as it was on screen. The first frame becomes the poster.
+ */
+export declare class ScreencastRecorder {
+    private readonly page;
+    private readonly scale;
+    private session;
+    private frames;
+    private directory;
+    private stoppedAt;
+    private running;
+    private loop;
+    constructor(page: Page, scale?: number);
+    start(workDirectory: string): Promise<void>;
+    stop(output: string): Promise<{
+        video: string;
+        poster: string;
+        durationMs: number;
+    } | null>;
+}