@reticlehq/server 3.9.0 → 3.10.1

package/dist/features/compare/action-plan.js

@@ -0,0 +1,543 @@
+/**
+ * The action plan `reticle compare` drives on each build. Pure: it reads trees and returns steps.
+ *
+ * The plan is made on the reference, breadth first, with no model and no settings:
+ * - the start page, and a wait on the start page;
+ * - the start page with each value of each url parameter the app's scripts read
+ *   (`?scenario=deferred`), up to `MAX_URL_ROOTS`. Each is a start page of its own, with its own
+ *   wait, and opening it does not count toward the depth;
+ * - every single action on every control: click each button, tab, checkbox and option; fill each
+ *   text field with two values chosen by the shape of its value, one edge value of that shape, and
+ *   the values the app's scripts compare the field's name with (`value-dictionary.ts`); select each
+ *   option of a combobox;
+ * - a click on each distinct visible text that has no control role (`- text`, `- generic`), up to
+ *   `MAX_TEXT_PROBES`. A text probe stays in the plan only when it changes the screen on the
+ *   reference: much of the web is a clickable element with no role;
+ * - a press of each common key (`DEFAULT_KEYS`) and of each key the app's scripts compare a key
+ *   event with or name in a shortcut, up to `MAX_KEYS`, each on the start page. A key goes to the
+ *   first element of the page and bubbles to the document. Escape again after each sequence that
+ *   made controls appear: what opened must close;
+ * - each request the app makes fails (`FaultKind`), up to `MAX_FAULT_REQUESTS` requests. A request
+ *   the start page makes on load fails three ways before the page loads. A request an action made
+ *   fails two ways (server, network), and the action's sequence is done again under the fault.
+ *   Files the page is built from are not requests the app makes;
+ * - each click again, followed by a wait, so behaviour on a timer can show. Also each path of two or
+ *   more steps that reached a new screen, followed by a wait. The wait stays in the plan only when
+ *   the reference showed delayed activity there: a call still pending, a page that kept changing
+ *   while it settled, or a change during the wait;
+ * - each single action again under each option of each combobox (a mode, a variant);
+ * - after each sequence, one level deeper into the controls its last action made appear (a menu, a
+ *   dialog): controls that were not on the page before that action;
+ * - on a page with two or more fields: fill every field with its own value, then press each button,
+ *   also a button that is disabled until the fields are filled. When such a press brings new
+ *   fields (the next step of a form, a dialog), fill those and press again, past the depth limit
+ *   up to `MAX_CHAIN` steps. A form step and its own buttons (new with its fields, or disabled
+ *   until they are filled) are planned first, so the cap does not starve them.
+ *   Only this shows a build that takes the start time for the end time.
+ *
+ * The plan explores screens, not paths. Many paths reach one screen, and each path costs a load on
+ * every build. A path of two or more steps that ends on a screen already reached is kept for at most
+ * `MAX_PATHS_PER_SCREEN` paths, and nothing is planned after it. A single action is always kept.
+ *
+ * A control is targeted by its test id when it has one, else by its role and name. Controls with the
+ * same target are numbered in page order, so "fill every field" fills eight fields, not one field
+ * eight times. Every sequence starts from a fresh load of the start page.
+ */
+import { magicValues } from './outside/value-dictionary.js';
+import { structureLines } from './visible-content.js';
+/**
+ * How a request fails. A failed answer is an input too: the error state, the retry button and the
+ * empty list exist only when a request fails.
+ */
+export const FaultKind = {
+    /** The server failed. */
+    SERVER: '500',
+    /** The network failed. */
+    ABORT: 'abort',
+    /** The server answered with nothing. */
+    EMPTY: 'empty',
+};
+export const ControlKind = { CLICK: 'click', FILL: 'fill', SELECT: 'select' };
+/** The most sequences in one plan. Each costs one fresh load on every build. */
+export const MAX_SEQUENCES = 220;
+/** A sequence this long is not probed for controls that appeared. */
+const MAX_DEPTH = 3;
+/**
+ * A form chain goes on past `MAX_DEPTH` up to this many steps: fill every field, press a button, and
+ * when the press brought new fields, fill those and press again. A wizard's later steps and a
+ * dialog's submit sit there.
+ */
+export const MAX_CHAIN = 8;
+/**
+ * The most text probes in one plan. Much of the web is a clickable element with no role (an
+ * accordion header, a table row), so visible text is clicked too.
+ */
+export const MAX_TEXT_PROBES = 40;
+/** The most start pages opened by a url parameter value, in one plan. */
+export const MAX_URL_ROOTS = 12;
+/** The most values of one url parameter opened as start pages. */
+export const MAX_VALUES_PER_PARAM = 8;
+/**
+ * The most paths of two or more steps kept to one screen. A path to a screen already reached is not
+ * explored further. A single action is always kept: it is a check on the candidate even when it
+ * changes nothing on the reference.
+ */
+export const MAX_PATHS_PER_SCREEN = 2;
+/**
+ * The keys a person presses on any page: close, confirm, move focus, move in a list. Each is a check
+ * also where it changes nothing on the reference: a build that answers to the wrong key shows it.
+ */
+export const DEFAULT_KEYS = [
+    'Escape',
+    'Enter',
+    'Tab',
+    'ArrowDown',
+    'ArrowUp',
+    'ArrowLeft',
+    'ArrowRight',
+    'Home',
+    'End',
+];
+const ESCAPE = 'Escape';
+/** The most keys pressed on the start page, common keys first. */
+export const MAX_KEYS = 24;
+/** The most requests made to fail, in the order the plan first sees them. */
+export const MAX_FAULT_REQUESTS = 8;
+/** A request made on load fails before the page starts, in each of the three ways. */
+const LOAD_FAULTS = [FaultKind.SERVER, FaultKind.ABORT, FaultKind.EMPTY];
+/** A request an action made fails under that action, as a server or a network failure. */
+const ACTION_FAULTS = [FaultKind.SERVER, FaultKind.ABORT];
+/** A request in an effect line (`effect-lines.ts`): `net: GET /api/items 200`. */
+const NET_LINE = /^net: ([A-Z]+) (\S+)/;
+const QUERY_START = '?';
+/** A file the page is built from: not a request the app makes. */
+const STATIC_PATH = /\.(m?js|jsx|tsx?|css|map|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|otf|html?)$|^\/(@|node_modules\/|src\/|assets\/)|^\/?$/;
+/** The wait after a click: a slideshow advances, a countdown ends, a delivery settles. */
+export const WAIT_AFTER_CLICK_MS = 4000;
+const MS_PER_S = 1000;
+const CONTROL_LINE = /^(\s*)- (button|checkbox|switch|radio|combobox|textbox|spinbutton|menuitem|menuitemcheckbox|tab|option|slider)\b(?: "([^"]*)")?(.*)$/;
+const TESTID = /\[testid=([^\]]+)\]/;
+const REF = /\(ref=(e\d+)\)/;
+const VALUE = /\[value="([^"]*)"\]/;
+const DISABLED = /\[(?:[a-z]+,)*disabled(?:,[a-z]+)*\]/;
+/** Visible text with no control role. */
+const TEXT_LINE = /^\s*- (?:text|generic) "([^"]{1,80})"/;
+const TEXT_ROLE = 'text';
+const COMBOBOX = 'combobox';
+const OPTION = 'option';
+const FIELD_ROLES = new Set(['textbox', 'spinbutton']);
+const TIME = /^\d{1,2}:\d{2}$/;
+const DATE = /^\d{4}-\d{2}-\d{2}|^\d{1,2}\/\d{1,2}\/\d{4}$/;
+const NUMBER = /^-?\d+(\.\d+)?$/;
+/** Long text with markup characters and a non-ASCII mark: a build that breaks only on such input. */
+export const EDGE_TEXT = `${'W'.repeat(120)} <b>&amp;</b> "q" ✓`;
+/** Two ordinary values of a shape, then one edge value: the last minute, a leap day, a negative. */
+const TIME_VALUES = ['09:15', '17:45', '23:59'];
+const DATE_VALUES = ['2024-02-03', '2024-11-28', '2024-02-29'];
+const NUMBER_VALUES = ['0', '7', '-1'];
+const TEXT_VALUES = ['', 'Reticle 42', EDGE_TEXT];
+const FIELD_TEXT = 'Reticle';
+const HOURS_PER_DAY = 24;
+/** The identity of a target, without its number. */
+function identityOf(t) {
+    if (t.text !== undefined) {
+        return `${TEXT_ROLE} "${t.text}"`;
+    }
+    return t.testid === undefined ? `${t.role ?? ''} "${t.name ?? ''}"` : `[testid=${t.testid}]`;
+}
+/** The identity of a target, with its number. */
+export const targetKey = (t) => `${identityOf(t)}#${String(t.nth)}`;
+/** The target as a person reads it: `button "Save"`, `[testid=save]`, `button "Open" #2`. */
+export const targetLabel = (t) => 0 === t.nth ? identityOf(t) : `${identityOf(t)} #${String(t.nth + 1)}`;
+/** The controls of a tree, numbered by page order. Options are kept on their combobox. */
+export function planControls(tree) {
+    const out = [];
+    const seen = new Map();
+    let combo;
+    for (const line of tree.split('\n')) {
+        const m = CONTROL_LINE.exec(line);
+        if (null === m) {
+            continue;
+        }
+        const indent = (m[1] ?? '').length;
+        const role = m[2] ?? '';
+        const name = m[3] ?? '';
+        const rest = m[4] ?? '';
+        if (OPTION === role && combo !== undefined && indent > combo.indent) {
+            combo.control.options.push(name);
+            continue;
+        }
+        combo = undefined;
+        if (OPTION === role) {
+            continue;
+        }
+        const testid = TESTID.exec(rest)?.[1];
+        const base = testid === undefined ? { role, name } : { testid };
+        const identity = identityOf({ ...base, nth: 0 });
+        const nth = seen.get(identity) ?? 0;
+        seen.set(identity, nth + 1);
+        const ref = REF.exec(rest)?.[1];
+        let kind = ControlKind.CLICK;
+        if (COMBOBOX === role) {
+            kind = ControlKind.SELECT;
+        }
+        else if (FIELD_ROLES.has(role)) {
+            kind = ControlKind.FILL;
+        }
+        const control = {
+            kind,
+            target: { ...base, nth },
+            ...(ref === undefined ? {} : { ref }),
+            value: VALUE.exec(rest)?.[1] ?? '',
+            options: [],
+            disabled: DISABLED.test(rest),
+        };
+        out.push(control);
+        if (ControlKind.SELECT === kind) {
+            combo = { indent, control };
+        }
+    }
+    return out;
+}
+/**
+ * A click on each distinct visible text that has no control role, in page order, up to
+ * `MAX_TEXT_PROBES`. `dropped` counts the texts past the cap.
+ */
+export function textProbes(tree) {
+    const texts = new Set();
+    for (const line of tree.split('\n')) {
+        const text = TEXT_LINE.exec(line)?.[1];
+        if (text !== undefined) {
+            texts.add(text);
+        }
+    }
+    const steps = [...texts]
+        .slice(0, MAX_TEXT_PROBES)
+        .map((text) => ({ action: ControlKind.CLICK, target: { text, nth: 0 } }));
+    return { steps, dropped: Math.max(0, texts.size - MAX_TEXT_PROBES) };
+}
+/** The ref of the first element of the page, where a key press goes. */
+export const firstRef = (tree) => REF.exec(tree)?.[1];
+/** The ref of `target` on this tree, or undefined when the tree has no such control. */
+export function refFor(tree, target) {
+    const key = targetKey(target);
+    return planControls(tree).find((c) => targetKey(c.target) === key)?.ref;
+}
+/**
+ * Values for a field, by the shape of its value: two that differ from it and from each other, so a
+ * build that mixes up two fields shows a difference, and one edge value of that shape.
+ */
+export function valuesFor(value) {
+    if (TIME.test(value)) {
+        return TIME_VALUES;
+    }
+    if (DATE.test(value)) {
+        return DATE_VALUES;
+    }
+    if (NUMBER.test(value)) {
+        return NUMBER_VALUES;
+    }
+    return TEXT_VALUES;
+}
+const EMPTY_DICTIONARY = new Map();
+/** The name the app's scripts would compare a field with: its accessible name, else its test id. */
+const fieldName = (c) => c.target.name ?? c.target.testid ?? '';
+/** The single actions on one control. None on a disabled control. */
+export function actionsOf(control, dictionary = EMPTY_DICTIONARY) {
+    if (control.disabled) {
+        return [];
+    }
+    const { target } = control;
+    if (ControlKind.SELECT === control.kind) {
+        return control.options.map((value) => ({ action: ControlKind.SELECT, target, value }));
+    }
+    if (ControlKind.FILL === control.kind) {
+        const values = new Set([
+            ...valuesFor(control.value),
+            ...magicValues(dictionary, fieldName(control)),
+        ]);
+        return [...values].map((value) => ({ action: ControlKind.FILL, target, value }));
+    }
+    return [{ action: ControlKind.CLICK, target }];
+}
+/**
+ * Field `index`'s own value in "fill every field": the first value the app compares it with, else an
+ * ordinary value of its shape, where a time moves by one hour for each field.
+ */
+function ownValue(field, index, dictionary) {
+    const magic = magicValues(dictionary, fieldName(field))[0];
+    if (magic !== undefined) {
+        return magic;
+    }
+    const value = valuesFor(field.value)[index % 2] ?? '';
+    if ('' === value) {
+        return `${FIELD_TEXT} ${String(index + 1)}`;
+    }
+    const time = /^(\d{1,2}):(\d{2})$/.exec(value);
+    if (null === time) {
+        return value;
+    }
+    const hour = (Number(time[1]) + index) % HOURS_PER_DAY;
+    return `${String(hour).padStart(2, '0')}:${time[2] ?? ''}`;
+}
+export function stepLabel(step) {
+    switch (step.action) {
+        case 'wait':
+            return `wait ${String(step.ms / MS_PER_S)} s`;
+        case 'goto':
+            return `open "${step.query}"`;
+        case 'press':
+            return `press ${step.key}`;
+        case 'fault':
+            return `fail ${step.method} ${step.path} (${step.fault})`;
+        case 'fillall':
+            return `fill every field (${step.fields.map((f) => `${targetLabel(f.target)}="${f.value}"`).join(', ')})`;
+        case 'fill':
+            return `fill ${targetLabel(step.target)} with "${step.value}"`;
+        case 'select':
+            return `select "${step.value}" in ${targetLabel(step.target)}`;
+        case 'click':
+            return `click ${targetLabel(step.target)}`;
+    }
+}
+/** One key for one sequence, the same on every build. */
+export const sequenceKey = (seq) => JSON.stringify(seq);
+const targetOf = (step) => 'target' in step ? targetKey(step.target) : undefined;
+const endsInWait = (seq) => 'wait' === seq.at(-1)?.action;
+/** The screen a tree shows, as one string: two trees with the same screen give the same string. */
+const screenOf = (tree) => structureLines(tree).join('\n');
+export const NOTHING_DROPPED = {
+    sequences: 0,
+    textProbes: 0,
+    urlRoots: 0,
+    sameScreenPaths: 0,
+    keys: 0,
+    faultRequests: 0,
+};
+/** The requests the app made, from effect lines, without the files the page is built from. */
+export function requestsIn(lines) {
+    const out = [];
+    for (const line of lines) {
+        const m = NET_LINE.exec(line);
+        const path = (m?.[2] ?? '').split(QUERY_START)[0] ?? '';
+        if (null !== m && !STATIC_PATH.test(path)) {
+            out.push({ method: m[1] ?? '', path });
+        }
+    }
+    return out;
+}
+/**
+ * A start page for each value of each url parameter, up to `MAX_VALUES_PER_PARAM` for one
+ * parameter and `MAX_URL_ROOTS` in all. `dropped` counts the values past the caps.
+ */
+export function urlRoots(params) {
+    const all = [];
+    let dropped = 0;
+    for (const [param, values] of params) {
+        dropped += Math.max(0, values.length - MAX_VALUES_PER_PARAM);
+        for (const value of values.slice(0, MAX_VALUES_PER_PARAM)) {
+            all.push({
+                action: 'goto',
+                query: `?${encodeURIComponent(param)}=${encodeURIComponent(value)}`,
+            });
+        }
+    }
+    dropped += Math.max(0, all.length - MAX_URL_ROOTS);
+    return { steps: all.slice(0, MAX_URL_ROOTS), dropped };
+}
+const keyStep = (key) => ({ action: 'press', key });
+/**
+ * A press of each common key, then of each key the app listens for, up to `MAX_KEYS`. `dropped`
+ * counts the keys past the cap.
+ */
+export function keyPresses(appKeys) {
+    const all = [...new Set([...DEFAULT_KEYS, ...appKeys])];
+    return {
+        steps: all.slice(0, MAX_KEYS).map(keyStep),
+        dropped: Math.max(0, all.length - MAX_KEYS),
+    };
+}
+/**
+ * The steps that count toward `MAX_DEPTH`. Opening a start page by its url and making a request
+ * fail do not: they set up the page the actions start on.
+ */
+const depthOf = (seq) => seq.filter((s) => 'goto' !== s.action && 'fault' !== s.action).length;
+/**
+ * Make the plan on the reference. `probe` drives one sequence from a fresh load, or answers
+ * undefined when a step could not be done.
+ */
+export async function buildPlan(startTree, probe, hints = {}) {
+    const dictionary = hints.dictionary ?? EMPTY_DICTIONARY;
+    const start = planControls(startTree);
+    const startScreen = screenOf(startTree);
+    const probes = textProbes(startTree);
+    const roots = urlRoots(hints.urlParams ?? new Map());
+    const keys = keyPresses(hints.keys ?? []);
+    /** Requests made to fail, and requests past `MAX_FAULT_REQUESTS`, as "METHOD path". */
+    const faulted = new Set();
+    const overFaultCap = new Set();
+    const faultsFor = (lines, kinds) => requestsIn(lines).flatMap(({ method, path }) => {
+        const id = `${method} ${path}`;
+        if (faulted.has(id)) {
+            return [];
+        }
+        if (faulted.size >= MAX_FAULT_REQUESTS) {
+            overFaultCap.add(id);
+            return [];
+        }
+        faulted.add(id);
+        return kinds.map((fault) => ({ action: 'fault', method, path, fault }));
+    });
+    /** A text probe stays in the plan only when it changes the screen on the reference. */
+    const probeKeys = new Set(probes.steps.map((s) => sequenceKey([s])));
+    const keysOf = (tree) => new Set(planControls(tree).map((c) => targetKey(c.target)));
+    /** The controls on the page after each probed sequence, to tell what its next action added. */
+    const before = new Map([[sequenceKey([]), keysOf(startTree)]]);
+    const steps = (c) => actionsOf(c, dictionary);
+    const singles = start.flatMap(steps);
+    const modes = start.filter((c) => ControlKind.SELECT === c.kind).flatMap(steps);
+    const wait = { action: 'wait', ms: WAIT_AFTER_CLICK_MS };
+    const queue = [
+        [wait],
+        ...roots.steps.map((r) => [r]),
+        ...roots.steps.map((r) => [r, wait]),
+        ...faultsFor(hints.loadEffects ?? [], LOAD_FAULTS).map((f) => [f]),
+        ...singles.map((s) => [s]),
+        ...probes.steps.map((s) => [s]),
+        ...keys.steps.map((s) => [s]),
+        ...singles.filter((s) => ControlKind.CLICK === s.action).map((s) => [s, wait]),
+        ...modes.flatMap((m) => singles.filter((s) => targetOf(s) !== targetOf(m)).map((s) => [m, s])),
+    ];
+    const plan = [[]];
+    const seen = new Set([sequenceKey([])]);
+    /** How many probed sequences reached each screen. */
+    const screens = new Map([[startScreen, 1]]);
+    let sameScreenPaths = 0;
+    /** Sequences that end in a press after "fill every field": they may go on past `MAX_DEPTH`. */
+    const chains = new Set();
+    while (queue.length > 0 && plan.length < MAX_SEQUENCES) {
+        const seq = queue.shift() ?? [];
+        const key = sequenceKey(seq);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        const depth = depthOf(seq);
+        const deeper = depth < MAX_DEPTH || (chains.has(key) && depth < MAX_CHAIN) || endsInWait(seq);
+        // A wait is probed before it is planned: it stays only where the reference showed activity.
+        const probed = deeper ? await probe(seq) : undefined;
+        // A request this sequence made can fail: replay the sequence with that request failing.
+        if (probed !== undefined && 'fault' !== seq[0]?.action) {
+            for (const fault of faultsFor(probed.effects ?? [], ACTION_FAULTS)) {
+                queue.push([fault, ...seq]);
+            }
+        }
+        if (endsInWait(seq) && true !== probed?.active) {
+            continue;
+        }
+        if (probeKeys.has(key) && (probed === undefined || screenOf(probed.tree) === startScreen)) {
+            continue;
+        }
+        // Explore screens, not paths: many paths reach one screen, and each costs a load on every build.
+        // A wait is a check of time on its path, so it is kept whatever screen it ends on.
+        if (probed !== undefined && !endsInWait(seq)) {
+            const screen = screenOf(probed.tree);
+            const visits = screens.get(screen) ?? 0;
+            screens.set(screen, visits + 1);
+            if (visits > 0 && seq.length > 1) {
+                if (visits >= MAX_PATHS_PER_SCREEN) {
+                    sameScreenPaths += 1;
+                }
+                else {
+                    plan.push(seq);
+                }
+                continue;
+            }
+        }
+        plan.push(seq);
+        if (probed === undefined || (depth >= MAX_DEPTH && !chains.has(key))) {
+            continue;
+        }
+        before.set(key, keysOf(probed.tree));
+        // A new screen reached by two or more steps can change by itself: a toast goes, a countdown
+        // ends. The wait is probed like any wait, and it stays only where the screen did not hold still.
+        if (seq.length > 1 && !endsInWait(seq)) {
+            queue.push([...seq, wait]);
+        }
+        // The page before the last action: the nearest shorter sequence that was probed. A
+        // "fill every field" step on its own is not probed, and it adds no control anyway. After a
+        // start page opened by its url, every control is new.
+        let parent = 'goto' === seq.at(-1)?.action ? new Set() : undefined;
+        for (let n = seq.length - 1; n >= 0 && parent === undefined; n -= 1) {
+            parent = before.get(sequenceKey(seq.slice(0, n)));
+        }
+        const all = planControls(probed.tree);
+        const now = all.filter((c) => !c.disabled);
+        const fields = now.filter((c) => ControlKind.FILL === c.kind);
+        const filled = seq.some((s) => 'fillall' === s.action);
+        const firstForm = fields.length >= 2 && !filled;
+        // The press after a "fill every field" brought fields that were not there before it.
+        const nextForm = fields.length >= 1 &&
+            filled &&
+            ControlKind.CLICK === seq.at(-1)?.action &&
+            fields.some((f) => parent?.has(targetKey(f.target)) !== true);
+        // A form step adds two steps: the fill and the press.
+        if ((firstForm || nextForm) && depth + 2 <= MAX_CHAIN) {
+            const fillall = {
+                action: 'fillall',
+                fields: fields.map((f, i) => ({ target: f.target, value: ownValue(f, i, dictionary) })),
+            };
+            // Also a disabled button: a submit is often disabled until the fields are filled.
+            const buttons = all.filter((c) => ControlKind.CLICK === c.kind);
+            const pressOf = (b) => [
+                ...seq,
+                fillall,
+                { action: ControlKind.CLICK, target: b.target },
+            ];
+            for (const b of buttons) {
+                chains.add(sequenceKey(pressOf(b)));
+            }
+            // The form's own buttons: new with its fields, or disabled until they are filled.
+            const own = (b) => b.disabled || parent?.has(targetKey(b.target)) !== true;
+            // The form step and its own buttons go first, so the cap does not starve them. A button that
+            // was already there (a nav bar, the page's other controls) is pressed after the rest.
+            queue.unshift([...seq, fillall], ...buttons.filter(own).map(pressOf));
+            queue.push(...buttons.filter((b) => !own(b)).map(pressOf));
+        }
+        const appeared = now.filter((c) => parent?.has(targetKey(c.target)) !== true);
+        for (const control of appeared) {
+            for (const step of steps(control)) {
+                queue.push([...seq, step]);
+            }
+        }
+        // What opened (a dialog, a menu) must close on Escape.
+        if (appeared.length > 0 && 'press' !== seq.at(-1)?.action) {
+            queue.push([...seq, keyStep(ESCAPE)]);
+        }
+    }
+    const untried = new Set(queue.map(sequenceKey).filter((k) => !seen.has(k)));
+    return {
+        sequences: plan,
+        dropped: {
+            sequences: untried.size,
+            textProbes: probes.dropped,
+            urlRoots: roots.dropped,
+            sameScreenPaths,
+            keys: keys.dropped,
+            faultRequests: overFaultCap.size,
+        },
+    };
+}
+/**
+ * The sequences to drive: those that are not the start of another planned sequence. The page is
+ * read after every step of a run, so a run also reads each planned sequence it starts with.
+ */
+export function longestRuns(plan) {
+    const starts = new Set();
+    for (const seq of plan) {
+        for (let i = 0; i < seq.length; i += 1) {
+            starts.add(sequenceKey(seq.slice(0, i)));
+        }
+    }
+    return plan.filter((seq) => !starts.has(sequenceKey(seq)));
+}

package/dist/features/compare/behaviour-compare.d.ts

@@ -0,0 +1,24 @@
+import { type BehaviourComparison } from './behaviour-diff.js';
+import type { CompareTimings } from './behaviour-report.js';
+import { type PageDriver } from './build-readings.js';
+/** A new browser tab on one build. */
+export interface OpenedPage extends PageDriver {
+    close(): Promise<void>;
+}
+export interface CompareInput {
+    reference: string;
+    candidate: string;
+    base?: string;
+    /** Open a new tab on `url`. Throws when the tab cannot be opened. */
+    open(url: string): Promise<OpenedPage>;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    /** Fetch a file the way a browser does. Undefined when it could not be fetched. */
+    fetchText: (url: string) => Promise<string | undefined>;
+    /** Read the app's declared state sources, after each sequence on every build. */
+    readState?: () => Promise<string[]>;
+}
+export declare function runCompare(input: CompareInput): Promise<{
+    result: BehaviourComparison;
+    timings?: CompareTimings;
+}>;

package/dist/features/compare/behaviour-compare.js

@@ -0,0 +1,85 @@
+/**
+ * `reticle compare`: drive two running builds of one app the same way, and report each difference
+ * in what a person sees. The recipe has no settings:
+ *
+ * 1. Read the values the reference's scripts compare fields and url parameters with
+ *    (`value-dictionary.ts`), then make the action plan on the reference (`action-plan.ts`).
+ * 2. Drive the plan on the reference, the candidate, the base when given, and the reference again,
+ *    in that order, each in a new browser tab (`build-readings.ts`). The two reference runs are on
+ *    each side of the candidate, so a line that changes with time is seen as noise.
+ *    With declared state sources, the app's stored data is read after each sequence too
+ *    (`outside/state-sources.ts`), so a change to a record that no page shows is a difference.
+ * 3. Compare (`behaviour-diff.ts`).
+ *
+ * A lost browser session makes the run invalid, never a difference.
+ */
+import { NOTHING_DROPPED, buildPlan, sequenceKey } from './action-plan.js';
+import { harvestScripts } from './outside/value-dictionary.js';
+import { compareBehaviour, invalidComparison } from './behaviour-diff.js';
+import { DriverLostError, probeSequence, readBuild, settledRead, } from './build-readings.js';
+/** The event cursor before a tab's first event. */
+const FIRST_EVENT = 0;
+const MS_PER_TENTH = 100;
+const TENTHS = 10;
+const LOST_SESSION = 'The browser session was lost, so this run proves nothing. Run it again:';
+async function withPage(input, url, use) {
+    const page = await input.open(url);
+    try {
+        return await use(page);
+    }
+    finally {
+        await page.close();
+    }
+}
+/** Make the plan on the reference. A start page that does not load gives the start page only. */
+async function planOn(input, page) {
+    if (!(await page.open())) {
+        return { sequences: [[]], dropped: NOTHING_DROPPED };
+    }
+    const hints = await harvestScripts(input.reference, input.fetchText);
+    const start = (await settledRead(page, input.sleep)).tree;
+    // The tab is new, so everything from its first event on is the start page's load.
+    const loadEffects = await page.effects(FIRST_EVENT);
+    return buildPlan(start, (seq) => probeSequence(page, seq, input.sleep), {
+        ...hints,
+        loadEffects,
+    });
+}
+export async function runCompare(input) {
+    const timed = async (work) => {
+        const start = input.now();
+        const value = await work();
+        return [value, Math.round((input.now() - start) / MS_PER_TENTH) / TENTHS];
+    };
+    let sequences = 0;
+    try {
+        const [{ sequences: plan, dropped }, planS] = await timed(() => withPage(input, input.reference, (page) => planOn(input, page)));
+        sequences = plan.length;
+        const drive = (url) => timed(() => withPage(input, url, (page) => readBuild(page, plan, input.sleep, input.readState)));
+        const [reference, referenceS] = await drive(input.reference);
+        const [candidate, candidateS] = await drive(input.candidate);
+        const based = input.base === undefined ? undefined : await drive(input.base);
+        const [again, againS] = await drive(input.reference);
+        const result = compareBehaviour({
+            order: plan.map(sequenceKey),
+            reference,
+            again,
+            candidate,
+            ...(based === undefined ? {} : { base: based[0] }),
+        });
+        const timings = {
+            plan: planS,
+            reference: referenceS,
+            candidate: candidateS,
+            ...(based === undefined ? {} : { base: based[1] }),
+            again: againS,
+        };
+        return { result: { ...result, planDropped: dropped }, timings };
+    }
+    catch (error) {
+        if (error instanceof DriverLostError) {
+            return { result: invalidComparison(`${LOST_SESSION} ${error.message}`, sequences) };
+        }
+        throw error;
+    }
+}