lynkeus 0.2.0

package/lib/config.d.ts

@@ -0,0 +1,72 @@
+import type { CasesConfig } from './cases/runner.js';
+import type { ScreenGraph } from './knowledge/types.js';
+export declare const lynkeusDir: (root?: string) => string;
+export declare const graphFile: (root?: string) => string;
+export declare const edgesFile: (root?: string) => string;
+export declare const frontierFile: (root?: string) => string;
+export declare const runsDir: (root?: string) => string;
+export declare const loadGraph: (root?: string) => ScreenGraph | null;
+/**
+ * `lynkeus.config.json` in the app's folder: what would otherwise be repeated
+ * as flags or environment on every invocation. Flags win over the
+ * environment, the environment over the file.
+ */
+export type LynkeusConfig = {
+    cases?: CasesConfig;
+    /** The headless entry (default `qa/headless.tsx`). */
+    entry?: string;
+    /** The environment variable the app reads its API base from; the headless entry refuses one that is not local. */
+    apiEnv?: string;
+    /** The driver port the app dials. */
+    port?: number;
+    /** Simulator udid or name. */
+    device?: string;
+    /** Bundle id or application id. */
+    app?: string;
+    /**
+     * The language this app speaks, passed on and never interpreted: `os
+     * language` defaults to it, the headless entry mocks this locale, and an MCP
+     * client is told, so a model reading the screens knows their language.
+     */
+    language?: string;
+    locale?: {
+        languageTag?: string;
+        country?: string;
+    };
+    /** How long to wait for the app to attach, in ms. */
+    attachTimeout?: number;
+    /** The lint baseline `lint` compares against when no file is given. */
+    lintBaseline?: string;
+    /** Regular expressions for the text this app shows when it is broken; `smoke` and `crawl` report a match. */
+    errorCopy?: string[];
+    /** The shape of an untranslated key, and the smallest acceptable touch target in points. */
+    lint?: {
+        i18nKeyPatterns?: string[];
+        minTouchTarget?: number;
+    };
+    /**
+     * Regular expressions for the testIDs of controls whose content changes on
+     * its own (a ticking clock, a countdown). Their text stops counting as a
+     * commit, or `idle` would wait out its whole timeout on every screen that
+     * shows one.
+     */
+    live?: string[];
+    /** Keep React.StrictMode in the headless host. Off by default: its double renders inflate what the host measures. */
+    strictMode?: boolean;
+    /** Regular expressions matched against a control's testID and label. lynkeus ships none: only the app knows which controls are irreversible. */
+    crawl?: {
+        /** Never pressed. */
+        never?: string[];
+        /** Close an overlay the app raises. */
+        close?: string[];
+        /** Go back. Without them the crawl takes a small control in the top-left corner for one. */
+        back?: string[];
+    };
+};
+export declare const configFile: (root?: string) => string;
+/** The app's configuration, under the one `LYNKEUS_CONFIG` names: cases and fixtures often live in a repository of their own. */
+export declare const loadConfig: (root?: string) => LynkeusConfig;
+export declare const portFromEnv: (config?: LynkeusConfig) => number | undefined;
+/** A list of regular expressions from the configuration, as one that matches any of them. */
+export declare const anyOf: (patterns: string[] | undefined) => RegExp | undefined;
+export declare const packageName: (root: string) => string;

package/lib/config.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson } from './files.js';
+export const lynkeusDir = (root = process.cwd()) => path.join(root, '.lynkeus');
+export const graphFile = (root) => path.join(lynkeusDir(root), 'graph.json');
+export const edgesFile = (root) => path.join(lynkeusDir(root), 'edges.jsonl');
+export const frontierFile = (root) => path.join(lynkeusDir(root), 'frontier.jsonl');
+export const runsDir = (root) => path.join(lynkeusDir(root), 'runs');
+export const loadGraph = (root) => {
+    const file = graphFile(root);
+    return fs.existsSync(file) ? readJson(file) : null;
+};
+export const configFile = (root) => path.join(root ?? process.cwd(), 'lynkeus.config.json');
+const readConfig = (file) => {
+    if (!fs.existsSync(file))
+        return {};
+    try {
+        const config = readJson(file);
+        // Paths under `cases` are relative to the file that declares them.
+        if (config.cases)
+            config.cases.base = path.dirname(path.resolve(file));
+        return config;
+    }
+    catch (error) {
+        throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+/** The app's configuration, under the one `LYNKEUS_CONFIG` names: cases and fixtures often live in a repository of their own. */
+export const loadConfig = (root) => {
+    const own = readConfig(configFile(root));
+    const extra = process.env.LYNKEUS_CONFIG ? readConfig(path.resolve(process.env.LYNKEUS_CONFIG)) : {};
+    return { ...own, ...extra };
+};
+export const portFromEnv = (config = {}) => (process.env.LYNKEUS_PORT ? Number(process.env.LYNKEUS_PORT) : config.port);
+/** A list of regular expressions from the configuration, as one that matches any of them. */
+export const anyOf = (patterns) => (patterns?.length ? new RegExp(patterns.join('|'), 'i') : undefined);
+export const packageName = (root) => {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name ?? path.basename(root);
+    }
+    catch {
+        return path.basename(root);
+    }
+};

package/lib/device/devices.d.ts

@@ -0,0 +1,11 @@
+export type Platform = 'ios' | 'android';
+export type DeviceInfo = {
+    id: string;
+    name: string;
+    platform: Platform;
+    type: 'simulator' | 'emulator' | 'physical';
+    connected: boolean;
+};
+export declare const bootedSimulators: () => Promise<DeviceInfo[]>;
+export declare const HEADLESS_HOST: DeviceInfo;
+export declare const pickAgentDevice: (wanted?: string) => Promise<DeviceInfo>;

package/lib/device/devices.js

@@ -0,0 +1,33 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+export const bootedSimulators = async () => {
+    // No Xcode (Linux, CI) means no simulators, not a crash: the app may be hosted headless.
+    let stdout;
+    try {
+        ({ stdout } = await run('xcrun', ['simctl', 'list', 'devices', 'booted', '-j']));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const parsed = JSON.parse(stdout);
+    return Object.values(parsed.devices)
+        .flat()
+        .filter((d) => d.state === 'Booted')
+        .map((d) => ({ id: d.udid, name: d.name, platform: 'ios', type: 'simulator', connected: true }));
+};
+export const HEADLESS_HOST = { id: 'headless', name: 'headless host', platform: 'ios', type: 'simulator', connected: true };
+export const pickAgentDevice = async (wanted) => {
+    const devices = await bootedSimulators();
+    const id = wanted ?? process.env.LYNKEUS_DEVICE;
+    const device = id ? devices.find((d) => d.id === id || d.name.includes(id)) : devices[0];
+    if (!device) {
+        // A headless host dials the driver itself: nothing to boot or attach to.
+        if (!id && devices.length === 0)
+            return HEADLESS_HOST;
+        throw new Error(id ? `No booted simulator matching "${id}".` : 'No booted simulator. Boot one first.');
+    }
+    return device;
+};

package/lib/device/driver.d.ts

@@ -0,0 +1,53 @@
+/**
+ * An app running the agent. The screen is the React tree the app hands over and
+ * touches are synthesized inside its process, so an action costs milliseconds;
+ * only launching, screenshots and the status bar go through simctl or adb.
+ */
+import { AgentServer } from 'lynkeus-client';
+import type { CoreMethods, Screen, TraceEvent } from 'lynkeus-protocol';
+import type { DeviceInfo } from './devices.js';
+export declare class Device {
+    #private;
+    info: DeviceInfo;
+    readonly server: AgentServer;
+    constructor(info: DeviceInfo, options?: {
+        server?: AgentServer;
+        appId?: string | null;
+        resolving?: Promise<DeviceInfo>;
+    });
+    /** The device as the OS knows it: reading the screen needs none of it; launching, screenshots and OS commands do. */
+    resolved(): Promise<DeviceInfo>;
+    get appId(): string | null;
+    stop(): Promise<void>;
+    launchApp(appId: string, options?: {
+        fresh?: boolean;
+    }): Promise<void>;
+    openUrl(url: string): Promise<void>;
+    /** Pins the clock, battery and radios so a pixel baseline survives the calendar. */
+    freezeChrome(): Promise<void>;
+    screenshot(destination: string): Promise<void>;
+    screen(): Promise<Screen>;
+    press(params: CoreMethods['press']['params']): Promise<CoreMethods['press']['result']>;
+    type(params: CoreMethods['type']['params']): Promise<CoreMethods['type']['result']>;
+    swipe(params: CoreMethods['swipe']['params']): Promise<CoreMethods['swipe']['result']>;
+    back(): Promise<CoreMethods['back']['result']>;
+    navigate(name: string, params?: object): Promise<void>;
+    waitFor(params: CoreMethods['waitFor']['params']): Promise<CoreMethods['waitFor']['result']>;
+    idle(params?: CoreMethods['idle']['params']): Promise<CoreMethods['idle']['result']>;
+    requests(since?: number): Promise<CoreMethods['requests']['result']>;
+    trace(since?: number): Promise<CoreMethods['trace']['result']>;
+    /** A command the app registered with `qa.register`. */
+    command<T = unknown>(name: string, params?: unknown): Promise<T>;
+}
+export declare const describeTrace: (events: TraceEvent[]) => string;
+type DescribeOptions = {
+    limit?: number;
+    /** Also what the platform is not presenting: behind a layer, out of the accessibility tree. */
+    all?: boolean;
+    /** Each element's centre, in points. */
+    frames?: boolean;
+    /** The commit count and the read's cost in the header. */
+    verbose?: boolean;
+};
+export declare const describeScreen: (screen: Screen, options?: DescribeOptions) => string;
+export {};

package/lib/device/driver.js

@@ -0,0 +1,169 @@
+/**
+ * An app running the agent. The screen is the React tree the app hands over and
+ * touches are synthesized inside its process, so an action costs milliseconds;
+ * only launching, screenshots and the status bar go through simctl or adb.
+ */
+import { AgentServer } from 'lynkeus-client';
+import { portFromEnv } from '../config.js';
+import { withoutHost } from '../knowledge/problems.js';
+import { lifecycleFor } from './platform.js';
+export class Device {
+    info;
+    server;
+    #lifecycle;
+    #appId;
+    #resolving;
+    constructor(info, options = {}) {
+        this.info = info;
+        this.#resolving = options.resolving;
+        // The app serves commands only to a driver that presents its token; without one, anything on the loopback could drive a dev build.
+        this.server = options.server ?? new AgentServer({ token: process.env.LYNKEUS_TOKEN, port: portFromEnv() });
+        this.#lifecycle = lifecycleFor(info.platform);
+        this.#appId = options.appId ?? null;
+    }
+    /** The device as the OS knows it: reading the screen needs none of it; launching, screenshots and OS commands do. */
+    async resolved() {
+        if (this.#resolving) {
+            this.info = await this.#resolving;
+            this.#resolving = undefined;
+        }
+        return this.info;
+    }
+    get appId() {
+        return this.#appId;
+    }
+    async stop() {
+        await this.server.close();
+    }
+    async launchApp(appId, options = {}) {
+        this.#appId = appId;
+        await this.server.listen();
+        await this.#lifecycle.launchApp((await this.resolved()).id, appId, options.fresh ?? true);
+        await this.server.waitForApp();
+    }
+    async openUrl(url) {
+        await this.server.call('deepLink', { url });
+    }
+    /** Pins the clock, battery and radios so a pixel baseline survives the calendar. */
+    async freezeChrome() {
+        await this.#lifecycle.freezeChrome((await this.resolved()).id);
+    }
+    async screenshot(destination) {
+        await this.#lifecycle.screenshot((await this.resolved()).id, destination);
+    }
+    screen() {
+        return this.server.call('screen');
+    }
+    press(params) {
+        return this.server.call('press', params);
+    }
+    type(params) {
+        return this.server.call('type', params);
+    }
+    swipe(params) {
+        return this.server.call('swipe', params);
+    }
+    back() {
+        return this.server.call('back');
+    }
+    async navigate(name, params) {
+        await this.server.call('navigate', { name, params });
+    }
+    // The agent's own timeout governs; the transport waits a little longer so it hears the agent's answer.
+    waitFor(params) {
+        return this.server.call('waitFor', params, (params.timeoutMs ?? 5000) + 2000);
+    }
+    idle(params) {
+        return this.server.call('idle', params, (params?.timeoutMs ?? 3000) + 2000);
+    }
+    requests(since) {
+        return this.server.call('requests', { since });
+    }
+    trace(since) {
+        return this.server.call('trace', { since });
+    }
+    /** A command the app registered with `qa.register`. */
+    command(name, params) {
+        return this.server.call(name, params);
+    }
+}
+const quote = (value) => JSON.stringify(value);
+export const describeTrace = (events) => {
+    if (events.length === 0)
+        return '(no events)';
+    const t0 = events[0].t;
+    const rel = (t) => `+${String(t - t0).padStart(6)}ms`;
+    return events
+        .map((e) => {
+        if (e.kind === 'route')
+            return `${rel(e.t)}  route    ${e.route ?? '?'}  (${e.path.join(' > ')})`;
+        if (e.kind === 'request')
+            return `${rel(e.t)}  request  ${String(e.status ?? '…').padStart(3)} ${e.method.padEnd(5)} ${withoutHost(e.url)}${e.error ? `  (${e.error})` : ''}`;
+        if (e.kind === 'stall')
+            return `${rel(e.t)}  stall    render loop broken: ${e.renders} updates${e.component ? ` to ${e.component}` : ''} in ${e.windowMs}ms`;
+        if (e.kind === 'touch')
+            return `${rel(e.t)}  touch    ${e.testId ? `#${e.testId}` : e.text ? JSON.stringify(e.text) : `${e.x},${e.y}`}  on ${e.route ?? '?'}`;
+        if (e.kind === 'crash')
+            return `${rel(e.t)}  crash    ${e.message}`;
+        if (e.kind === 'event')
+            return `${rel(e.t)}  event    ${e.name}${e.props ? ` ${JSON.stringify(e.props)}` : ''}`;
+        if (e.kind === 'store')
+            return `${rel(e.t)}  store    ${e.store}: ${Object.entries(e.changed)
+                .map(([k, v]) => `${k} ${JSON.stringify(v.from)}→${JSON.stringify(v.to)}`)
+                .join(', ')}`;
+        return `${rel(e.t)}  command  ${e.method} ${e.ms}ms${e.error ? `  ✗ ${e.error}` : ''}`;
+    })
+        .join('\n');
+};
+export const describeScreen = (screen, options = {}) => {
+    const { limit = 80, all = false, frames = false, verbose = false } = options;
+    const layer = screen.presenting ? ` +${screen.presenting.modal ? 'modal' : 'overlay'}${screen.presenting.testId ? `#${screen.presenting.testId}` : ''}` : '';
+    // Plain views are layout; one that names itself (a testID, a label) is content.
+    const named = screen.elements.filter((e) => e.kind !== 'view' || e.accessibilityLabel !== undefined || e.testId !== undefined);
+    // What sits inside a button is the button: its icon is not something else to read or press.
+    const insideButton = (e) => {
+        for (let p = e.parent; p !== undefined; p = screen.elements[p]?.parent)
+            if (screen.elements[p]?.kind === 'button')
+                return true;
+        return false;
+    };
+    // An inert control is still read, even though it cannot be touched.
+    const listed = all ? named : named.filter((e) => (!e.hidden || e.hidden === 'inert') && !(e.kind === 'view' && insideButton(e)));
+    const counts = new Map();
+    if (!all)
+        for (const e of named)
+            if (e.hidden && e.hidden !== 'inert')
+                counts.set(e.hidden, (counts.get(e.hidden) ?? 0) + 1);
+    const hiddenTotal = [...counts.values()].reduce((sum, n) => sum + n, 0);
+    const hiddenNote = hiddenTotal ? ` · ${hiddenTotal} hidden: ${[...counts].map(([reason, n]) => `${n} ${reason}`).join(', ')}` : '';
+    const stats = verbose ? ` commit=${screen.commit}${screen.busy ? ' busy' : ''} ${screen.costMs}ms` : screen.busy ? ' busy' : '';
+    // The path says which navigators hold the route; alone, it only repeats it.
+    const trail = screen.path.join(' > ');
+    const header = `${screen.route ?? '?'}${trail === screen.route ? '' : ` (${trail})`}${layer}${stats}${hiddenNote}`;
+    // An index is how to point at what has no name of its own, or shares it: a control
+    // with a testID nothing else carries is pointed at by that.
+    const nameOf = (e) => (e.testId ? `#${e.testId}` : (e.text ?? e.accessibilityLabel));
+    const uses = new Map();
+    for (const e of listed) {
+        const name = nameOf(e);
+        if (name !== undefined)
+            uses.set(name, (uses.get(name) ?? 0) + 1);
+    }
+    const lines = listed.slice(0, limit).map((e) => {
+        const id = e.testId ? ` #${e.testId}` : '';
+        const name = nameOf(e);
+        const index = name !== undefined && uses.get(name) === 1 ? '' : `${e.i} `;
+        // A label that only repeats the testID says nothing new.
+        const label = (e.text ?? e.accessibilityLabel) === e.testId ? undefined : (e.text ?? e.accessibilityLabel);
+        const value = e.kind === 'input'
+            ? ` value=${quote(e.value ?? '')}${e.placeholder ? ` placeholder=${quote(e.placeholder)}` : ''}${e.focused ? ' *focused' : ''}`
+            : e.value !== undefined
+                ? ` value=${quote(e.value)}` // a QR's encoded string, say
+                : '';
+        const state = `${e.enabled ? '' : ' !disabled'}${e.covered ? ' ~covered' : ''}${e.hidden ? ` ~${e.hidden}` : ''}`;
+        const at = frames ? ` @${Math.round(e.frame.x + e.frame.w / 2)},${Math.round(e.frame.y + e.frame.h / 2)}` : '';
+        return `${index}${e.kind}${id}${label ? ` ${quote(label)}` : ''}${value}${state}${at}`;
+    });
+    const rest = listed.length - lines.length;
+    return [header, ...lines, rest > 0 ? `… ${rest} more` : ''].filter(Boolean).join('\n');
+};

package/lib/device/platform.d.ts

@@ -0,0 +1,7 @@
+import type { Platform } from './devices.js';
+export type PlatformLifecycle = {
+    launchApp(deviceId: string, appId: string, fresh: boolean): Promise<void>;
+    screenshot(deviceId: string, destination: string): Promise<void>;
+    freezeChrome(deviceId: string): Promise<void>;
+};
+export declare const lifecycleFor: (platform: Platform) => PlatformLifecycle;

package/lib/device/platform.js

@@ -0,0 +1,59 @@
+import { execFile } from 'node:child_process';
+import { writeFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+const ios = {
+    async launchApp(deviceId, appId, fresh) {
+        const args = ['simctl', 'launch'];
+        if (fresh)
+            args.push('--terminate-running-process');
+        await run('xcrun', [...args, deviceId, appId]);
+    },
+    async screenshot(deviceId, destination) {
+        await run('xcrun', ['simctl', 'io', deviceId, 'screenshot', destination]);
+    },
+    async freezeChrome(deviceId) {
+        await run('xcrun', [
+            'simctl',
+            'status_bar',
+            deviceId,
+            'override',
+            '--time',
+            '9:41',
+            '--batteryState',
+            'charged',
+            '--batteryLevel',
+            '100',
+            '--cellularMode',
+            'active',
+            '--cellularBars',
+            '4',
+            '--wifiMode',
+            'active',
+            '--wifiBars',
+            '3',
+        ]);
+    },
+};
+const adb = (deviceId, args) => run('adb', ['-s', deviceId, ...args]);
+const android = {
+    async launchApp(deviceId, appId, fresh) {
+        if (fresh)
+            await adb(deviceId, ['shell', 'am', 'force-stop', appId]);
+        await adb(deviceId, ['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1']);
+    },
+    async screenshot(deviceId, destination) {
+        const { stdout } = await run('adb', ['-s', deviceId, 'exec-out', 'screencap', '-p'], { encoding: 'buffer', maxBuffer: 64 * 1024 * 1024 });
+        await writeFile(destination, stdout);
+    },
+    async freezeChrome(deviceId) {
+        await adb(deviceId, ['shell', 'settings', 'put', 'global', 'sysui_demo_allowed', '1']);
+        const demo = (args) => adb(deviceId, ['shell', 'am', 'broadcast', '-a', 'com.android.systemui.demo', ...args]);
+        await demo(['-e', 'command', 'enter']);
+        await demo(['-e', 'command', 'clock', '-e', 'hhmm', '0941']);
+        await demo(['-e', 'command', 'battery', '-e', 'level', '100', '-e', 'plugged', 'false']);
+        await demo(['-e', 'command', 'network', '-e', 'wifi', 'show', '-e', 'level', '4']);
+        await demo(['-e', 'command', 'notifications', '-e', 'visible', 'false']);
+    },
+};
+export const lifecycleFor = (platform) => (platform === 'ios' ? ios : android);

package/lib/files.d.ts

@@ -0,0 +1,7 @@
+export declare const readJson: <T>(file: string) => T;
+export declare const writeJson: (file: string, value: unknown) => void;
+export declare const readJsonl: <T>(file: string) => T[];
+export declare const appendJsonl: (file: string, row: unknown) => void;
+export declare const writeJsonl: (file: string, rows: unknown[]) => void;
+export declare const today: () => string;
+export declare const stamp: () => string;

package/lib/files.js

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
+export const writeJson = (file, value) => {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+};
+export const readJsonl = (file) => {
+    if (!fs.existsSync(file))
+        return [];
+    return fs
+        .readFileSync(file, 'utf8')
+        .split('\n')
+        .filter((line) => line.trim())
+        .map((line) => JSON.parse(line));
+};
+export const appendJsonl = (file, row) => {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(row)}\n`);
+};
+// Through a temporary file and a rename, so a reader never sees half a file.
+export const writeJsonl = (file, rows) => {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, rows.map((row) => `${JSON.stringify(row)}\n`).join(''));
+    fs.renameSync(tmp, file);
+};
+export const today = () => new Date().toISOString().slice(0, 10);
+export const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');

package/lib/flow/artifacts.d.ts

@@ -0,0 +1,19 @@
+import type { Element, Screen } from 'lynkeus-protocol';
+export declare const runDir: (root: string, flowName: string) => string;
+export declare const stepFile: (dir: string, index: number, extension: string) => string;
+export type ScreenDiff = {
+    route: {
+        before?: string;
+        after?: string;
+        changed: boolean;
+    };
+    added: Element[];
+    removed: Element[];
+    changedText: {
+        before: Element;
+        after: Element;
+    }[];
+};
+/** Structural difference between two screens: no geometry, so layout jitter is not a change. */
+export declare const diffScreens: (before: Screen, after: Screen) => ScreenDiff;
+export declare const describeDiff: (diff: ScreenDiff) => string;

package/lib/flow/artifacts.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { stamp } from '../files.js';
+export const runDir = (root, flowName) => {
+    const slug = flowName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+    const dir = path.join(root, slug, stamp());
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+};
+export const stepFile = (dir, index, extension) => path.join(dir, `step-${String(index).padStart(2, '0')}.${extension}`);
+const key = (e) => `${e.kind}|${e.testId ?? ''}|${e.text ?? e.accessibilityLabel ?? ''}`;
+/** Structural difference between two screens: no geometry, so layout jitter is not a change. */
+export const diffScreens = (before, after) => {
+    const beforeByKey = new Map(before.elements.map((e) => [key(e), e]));
+    const afterByKey = new Map(after.elements.map((e) => [key(e), e]));
+    const added = after.elements.filter((e) => !beforeByKey.has(key(e)));
+    const removed = before.elements.filter((e) => !afterByKey.has(key(e)));
+    // Same identity (testId) but different text: a value or a label changed.
+    const changedText = [];
+    const removedById = new Map(removed.filter((e) => e.testId).map((e) => [e.testId, e]));
+    for (const e of added) {
+        const previous = e.testId ? removedById.get(e.testId) : undefined;
+        if (previous)
+            changedText.push({ before: previous, after: e });
+    }
+    const paired = new Set(changedText.flatMap((c) => [c.before, c.after]));
+    return {
+        route: { before: before.route, after: after.route, changed: before.route !== after.route },
+        added: added.filter((e) => !paired.has(e)),
+        removed: removed.filter((e) => !paired.has(e)),
+        changedText,
+    };
+};
+const label = (e) => `${e.kind} ${e.testId ? `#${e.testId}` : ''} ${e.text ? JSON.stringify(e.text.slice(0, 60)) : ''}`.trim();
+export const describeDiff = (diff) => {
+    const lines = [];
+    if (diff.route.changed)
+        lines.push(`route ${diff.route.before ?? '?'} → ${diff.route.after ?? '?'}`);
+    for (const c of diff.changedText)
+        lines.push(`~ ${label(c.before)} → ${JSON.stringify(c.after.text ?? '')}`);
+    for (const e of diff.added)
+        lines.push(`+ ${label(e)}`);
+    for (const e of diff.removed)
+        lines.push(`- ${label(e)}`);
+    return lines.length ? lines.join('\n') : '(no structural change)';
+};

package/lib/flow/runner.d.ts

@@ -0,0 +1,13 @@
+import type { Device } from '../device/driver.js';
+import type { Flow, FlowReport, StepReport } from './types.js';
+export type RunFlowOptions = {
+    device: Device;
+    vars?: Record<string, unknown>;
+    /** Where to leave each step's screen, and screenshot when asked; nothing is kept without one. */
+    artifactsRoot?: string;
+    screenshots?: boolean;
+    /** Drain the app's `events` after every step and keep them with the run; it empties the app's buffer. */
+    events?: boolean;
+    onStep?: (report: StepReport, index: number) => void;
+};
+export declare const runFlow: (flow: Flow, options: RunFlowOptions) => Promise<FlowReport>;