@reticlehq/server 3.9.0 → 3.10.0

package/dist/features/exhaust/explorer.d.ts

@@ -13,27 +13,55 @@
  * - Controls that differ only by a number — the rows of a table — are one control. It is covered
  *   once, which is what keeps a 500-row page from eating the whole budget.
  * - Text fields on a state are filled before its buttons are tried, so a submit is driven with
- *   input rather than dismissed as dead because it refused an empty form.
+ *   input rather than dismissed as dead because it refused an empty form. Each field gets its own
+ *   value (`fillValue` is told the field's position), so two fields a build swaps do not read alike.
+ * - `paths` keeps every click it tried, also a click that kept the same state (a count went up).
+ *   A caller that reads the page after each path needs those clicks too.
  *
  * ponytail: breadth-first with a flat action budget, and every edge replays its path from a fresh
  * load. That is O(states × path length), correct and slow; add prefix sharing if it proves too slow.
  * A control that needs a choice (select, combobox) is not driven — it needs a value model.
  */
 import { type ReticleEvent } from '@reticlehq/core';
+/** What one action gives back. */
+export interface ActResult {
+    ok: boolean;
+    /** The events this action caused. */
+    events: readonly ReticleEvent[];
+    /** The element's source, when the app gives source attribution. */
+    source?: {
+        file: string;
+        line: number;
+    };
+}
+/** A page as the explorer reads it: the snapshot tree and the route. */
+export interface PageRead {
+    tree: string;
+    route?: string;
+}
+/** The attributes `fieldAttrs` reads: what a field takes, for its edge-case values. */
+export declare const FIELD_ATTRS: readonly ["type", "min", "max", "maxlength", "minlength", "pattern", "required", "inputmode"];
 /** What the explorer needs from a driven page. The tool layer adapts a session to it. */
 export interface ExplorePort {
     /** Load the start page fresh. False when it did not come back. */
     reset(): Promise<boolean>;
     /** The interactive tree and route of the page now. */
-    look(): Promise<{
-        tree: string;
-        route?: string;
-    }>;
-    /** Act on a control; the events are the ones this action caused. */
-    act(ref: string, action: 'click' | 'fill', value?: string): Promise<{
-        ok: boolean;
-        events: readonly ReticleEvent[];
-    }>;
+    look(): Promise<PageRead>;
+    /**
+     * Act on a control. `settle: false` returns as soon as the action is sent, so the next action
+     * runs back to back with it; its late events then arrive with the next action's.
+     */
+    act(ref: string, action: 'click' | 'fill', value?: string, opts?: {
+        settle?: boolean;
+    }): Promise<ActResult>;
+    /** The whole page, text included. Absent when the port reads only the interactive tree. */
+    lookFull?: () => Promise<PageRead>;
+    /** Go back to the page before the last action. False when it did not come back. */
+    back?: () => Promise<boolean>;
+    /** Reload the page now. False when it did not come back. */
+    reload?: () => Promise<boolean>;
+    /** The `FIELD_ATTRS` the field `control` (a control key) carries, for its edge-case values. */
+    fieldAttrs?: (control: string) => Promise<Record<string, string> | undefined>;
     /** Install network mocks ([] clears). Absent, or false, when no driven browser can. */
     mock?: (rules: {
         urlContains: string;
@@ -57,6 +85,33 @@ export interface ExploredWrite {
     beforeState: string;
     /** The state the app reached when this write SUCCEEDED — what a failure must not look like. */
     successState: string;
+    /**
+     * True when the write answered an error or never completed while exploring. `successState` is
+     * then where a failure lands, not a success, and nothing can be judged by landing there.
+     */
+    failed?: boolean;
+}
+/** One explored state, as the edge-case drive needs it. */
+export interface ExploredSurface {
+    /** How to reach the state from a fresh start page, before its fields are filled. */
+    path: Step[];
+    /** What the explorer typed into the state's empty fields, in page order. */
+    fills: Step[];
+    /** Every text field on the state, in page order: the empty ones and the pre-filled ones. */
+    fields: string[];
+    /** Each field's `FIELD_ATTRS`, by control key. */
+    attrs: Record<string, Record<string, string>>;
+    /** The controls the explorer clicked on this state, in page order. */
+    order: string[];
+    /** The controls whose click sent a request. */
+    requests: string[];
+    /** The controls whose click sent a write. */
+    writes: string[];
+    /**
+     * The controls whose click showed no activity at all: no request, no DOM change, no route change,
+     * no signal. One sample; the edge drive presses each again before it calls one dead.
+     */
+    inert: string[];
 }
 export interface ExploreReport {
     states: number;
@@ -80,19 +135,29 @@ export interface ExploreReport {
     /** States whose recorded path no longer replays — the app is not deterministic from its start. */
     unreachable: number;
     budgetExhausted: boolean;
+    /** Every click tried, as its path from a fresh start page, in the order the explorer tried them. */
+    paths: Step[][];
+    /** Every explored state, with its fields, controls and the controls that sent a request. */
+    surfaces: ExploredSurface[];
+}
+export interface ExploreOptions {
+    maxActions: number;
+    /** What to type into an empty field: its label, and its position among the fields on the state. */
+    fillValue: (label: string, index: number) => string;
+    /** Called after each click, before the page is read, so behaviour driven by a timer can show. */
+    wait?: () => Promise<void>;
 }
 interface Control {
     ref: string;
     key: string;
     /** The field already holds a value — pre-filled credentials, a default. Typing over it breaks it. */
     holdsValue: boolean;
+    /** The snapshot line, with the states (`[disabled]`) the key leaves out. */
+    desc: string;
 }
 export declare function controlsOf(tree: string): Control[];
 export declare function stateKey(route: string | undefined, controls: readonly Control[]): string;
-export declare function explore(port: ExplorePort, opts: {
-    maxActions: number;
-    fillValue: (label: string) => string;
-}): Promise<ExploreReport>;
+export declare function explore(port: ExplorePort, opts: ExploreOptions): Promise<ExploreReport>;
 /**
  * A fresh start page, then the path. False when a step's control is gone or refused. Every state
  * is reached this way, which is what makes returning to one a replay rather than a hope.
@@ -100,4 +165,12 @@ export declare function explore(port: ExplorePort, opts: {
 export declare function replayPath(port: ExplorePort, path: readonly Step[], act: (ref: string, action: 'click' | 'fill', value?: string) => Promise<{
     ok: boolean;
 }>, spent: () => boolean): Promise<boolean>;
+/**
+ * One action that sent the same write two or more times, whatever the server answered. A second
+ * copy sent after the server refused the credentials of the first is the client's retry, not a
+ * duplicate: the first did no work.
+ */
+export declare function noteDuplicateWrites(events: readonly ReticleEvent[], control: string, anomalies: ExploreReport['anomalies']): void;
+/** The faults in an action's events: page errors, requests at or above `floor`, contradictions. */
+export declare function noteAnomalies(events: readonly ReticleEvent[], control: string, anomalies: ExploreReport['anomalies'], floor?: number): void;
 export {};

package/dist/features/exhaust/explorer.js

@@ -13,20 +13,36 @@
  * - Controls that differ only by a number — the rows of a table — are one control. It is covered
  *   once, which is what keeps a 500-row page from eating the whole budget.
  * - Text fields on a state are filled before its buttons are tried, so a submit is driven with
- *   input rather than dismissed as dead because it refused an empty form.
+ *   input rather than dismissed as dead because it refused an empty form. Each field gets its own
+ *   value (`fillValue` is told the field's position), so two fields a build swaps do not read alike.
+ * - `paths` keeps every click it tried, also a click that kept the same state (a count went up).
+ *   A caller that reads the page after each path needs those clicks too.
  *
  * ponytail: breadth-first with a flat action budget, and every edge replays its path from a fresh
  * load. That is O(states × path length), correct and slow; add prefix sharing if it proves too slow.
  * A control that needs a choice (select, combobox) is not driven — it needs a value model.
  */
-import { asNumber, asString, isAbsenceDerived, isAdvisory, parseInteractive, } from '@reticlehq/core';
+import { EventType, asNumber, asString, isAbsenceDerived, isAdvisory, parseInteractive, } from '@reticlehq/core';
 import { findContradictions } from '@reticlehq/engine/disagreement/contradictions.js';
-import { controlKey, failedRequests, isConsoleError, writeKeyOf } from './session-fold.js';
+import { controlKey, failedRequests, isActivity, isConsoleError, legitimatelyInert, writeKeyOf, } from './session-fold.js';
+/** The attributes `fieldAttrs` reads: what a field takes, for its edge-case values. */
+export const FIELD_ATTRS = [
+    'type',
+    'min',
+    'max',
+    'maxlength',
+    'minlength',
+    'pattern',
+    'required',
+    'inputmode',
+];
 /** Roles that take typed input. */
 const TYPED = /^(?:textbox|searchbox|spinbutton)\b/;
 /** Roles that need a value model this explorer does not have, and are left alone. */
 const CHOOSER = /^(?:combobox|listbox|option|slider)\b/;
 const FAILED_STATUS = 400;
+/** The lowest status of an answer that is not an error. 0 is a request that never completed. */
+const OK_MIN = 200;
 /** A route without its query: `?__reticle_opened=1` and friends are not a different page. */
 const pathOf = (route) => route?.split('?')[0];
 export function controlsOf(tree) {
@@ -36,6 +52,7 @@ export function controlsOf(tree) {
         ref: item.ref,
         key: controlKey(item.desc),
         holdsValue: /\[value="[^"]+"/.test(item.desc),
+        desc: item.desc,
     }));
 }
 export function stateKey(route, controls) {
@@ -52,6 +69,8 @@ export async function explore(port, opts) {
     const explored = new Set();
     const queued = new Set();
     const queue = [{ path: [] }];
+    const paths = [];
+    const surfaces = [];
     const spent = () => actions >= opts.maxActions;
     const act = async (ref, action, value) => {
         actions += 1;
@@ -60,32 +79,47 @@ export async function explore(port, opts) {
     const goTo = (path) => replayPath(port, path, act, spent);
     while (queue.length > 0 && !spent()) {
         const node = queue.shift();
-        if (node === undefined)
+        if (node === undefined) {
             break;
+        }
         if (!(await goTo(node.path))) {
-            if (!spent())
+            if (!spent()) {
                 unreachable += 1;
+            }
             continue;
         }
         const here = await port.look();
         const controls = controlsOf(here.tree);
         const key = stateKey(here.route, controls);
-        if (explored.has(key))
+        if (explored.has(key)) {
             continue;
+        }
         explored.add(key);
         const where = pathOf(here.route);
-        if (where !== undefined)
+        if (where !== undefined) {
             routes.add(where);
-        for (const c of controls)
+        }
+        for (const c of controls) {
             seen.add(c.key);
+        }
         // Only EMPTY fields. The first drive of the fixture typed placeholders over the login form's
         // correct pre-filled credentials, got a 401, and never left the first page.
+        const fields = [...new Set(controls.filter((c) => TYPED.test(c.key)).map((c) => c.key))];
         const typed = controls.filter((c) => TYPED.test(c.key) && !c.holdsValue);
-        const fills = typed.map((c) => ({
+        const fills = typed.map((c, index) => ({
             key: c.key,
             action: 'fill',
-            value: opts.fillValue(c.key),
+            value: opts.fillValue(c.key, index),
         }));
+        const attrs = {};
+        // Every field, the pre-filled ones too: the explorer leaves a pre-filled field alone, but its
+        // edge values are still worth typing. A login form whose fields came filled got none.
+        for (const field of fields) {
+            const read = await port.fieldAttrs?.(field);
+            if (read !== undefined) {
+                attrs[field] = read;
+            }
+        }
         // Fills first, then the targets: valid input can reveal the button that moves on (a Continue,
         // a Submit), and a list drawn before the fill would never contain it.
         const fillHere = async () => {
@@ -100,31 +134,69 @@ export async function explore(port, opts) {
             return 0 < fills.length ? controlsOf((await port.look()).tree) : before;
         };
         const ready = await fillHere();
-        for (const c of ready)
+        for (const c of ready) {
             seen.add(c.key);
+        }
         // Every control of THIS state, once. Not filtered by what other states touched: a "Save" on
         // another screen is another control, and skipping it left reachable writes undriven.
         const untried = [
             ...new Set(ready.filter((c) => !TYPED.test(c.key) && !CHOOSER.test(c.key)).map((c) => c.key)),
         ];
-        for (const [index, target] of untried.entries()) {
-            if (spent())
+        const surface = {
+            path: node.path,
+            fills,
+            fields,
+            attrs,
+            order: untried,
+            requests: [],
+            writes: [],
+            inert: [],
+        };
+        surfaces.push(surface);
+        // Controls no state has tried yet go first. Every page of an app repeats its nav, and trying the
+        // nav first on every state spent the budget before a page's own controls were pressed. Each
+        // control of the state is still tried; only the order changes.
+        const tryOrder = [
+            ...untried.filter((c) => !touched.has(c)),
+            ...untried.filter((c) => touched.has(c)),
+        ];
+        for (const [index, target] of tryOrder.entries()) {
+            if (spent()) {
                 break;
+            }
             // The first control is tried on the page already loaded and filled; every other one starts
             // over from the recorded path, because the one before it may have changed or left this state.
-            if (index > 0 && !(await goTo(node.path)))
+            if (index > 0 && !(await goTo(node.path))) {
                 break;
+            }
             const current = 0 === index ? ready : await fillHere();
             const control = current.find((c) => c.key === target);
-            if (control === undefined || spent())
+            if (control === undefined || spent()) {
                 continue;
+            }
             const result = await act(control.ref, 'click');
             touched.add(target);
             const path = [...node.path, ...fills, { key: target, action: 'click' }];
+            paths.push(path);
+            await opts.wait?.();
             const after = await port.look();
             const next = stateKey(after.route, controlsOf(after.tree));
             noteWrites(result.events, path, key, next, writes);
+            if (result.events.some((e) => EventType.NET_REQUEST === e.type)) {
+                surface.requests.push(target);
+            }
+            if (result.events.some((e) => writeKeyOf(e) !== undefined)) {
+                surface.writes.push(target);
+            }
             noteAnomalies(result.events, target, anomalies);
+            noteDuplicateWrites(result.events, target, anomalies);
+            if (result.ok &&
+                next === key &&
+                pathOf(after.route) === where &&
+                !result.events.some(isActivity) &&
+                !legitimatelyInert(control.desc)) {
+                surface.inert.push(target);
+            }
             if (!explored.has(next) && !queued.has(next)) {
                 queued.add(next);
                 queue.push({ path, key: next });
@@ -142,6 +214,8 @@ export async function explore(port, opts) {
         frontier: queue.filter((n) => n.key === undefined || !explored.has(n.key)).length,
         unreachable,
         budgetExhausted: spent(),
+        paths,
+        surfaces,
     };
 }
 /**
@@ -149,47 +223,107 @@ export async function explore(port, opts) {
  * is reached this way, which is what makes returning to one a replay rather than a hope.
  */
 export async function replayPath(port, path, act, spent) {
-    if (!(await port.reset()))
+    if (!(await port.reset())) {
         return false;
+    }
     for (const step of path) {
-        if (spent())
+        if (spent()) {
             return false;
+        }
         const target = controlsOf((await port.look()).tree).find((c) => c.key === step.key);
-        if (target === undefined)
+        if (target === undefined) {
             return false;
-        if (!(await act(target.ref, step.action, step.value)).ok)
+        }
+        if (!(await act(target.ref, step.action, step.value)).ok) {
             return false;
+        }
     }
     return true;
 }
 function noteWrites(events, path, beforeState, successState, writes) {
     for (const event of events) {
         const key = writeKeyOf(event);
-        if (key === undefined || writes.has(key))
+        if (key === undefined || writes.has(key)) {
             continue;
+        }
         const [method = '', urlPath = ''] = key.split(' ');
         const url = event.data['url'];
         const concrete = 'string' === typeof url ? new URL(url, 'http://localhost').pathname : urlPath;
-        writes.set(key, { key, method, urlPath: concrete, path, beforeState, successState });
+        const status = asNumber(event.data['status']);
+        const failed = status === undefined || status < OK_MIN || status >= FAILED_STATUS;
+        writes.set(key, {
+            key,
+            method,
+            urlPath: concrete,
+            path,
+            beforeState,
+            successState,
+            ...(failed ? { failed } : {}),
+        });
+    }
+}
+/** HTTP answers that refuse the credentials. A client sends the write again after one by design. */
+const AUTH_REFUSED = new Set([401, 403]);
+const DUPLICATE_REQUEST = 'duplicate-request';
+/**
+ * One action that sent the same write two or more times, whatever the server answered. A second
+ * copy sent after the server refused the credentials of the first is the client's retry, not a
+ * duplicate: the first did no work.
+ */
+export function noteDuplicateWrites(events, control, anomalies) {
+    // Each request once, by its id: a write still in flight has only its `net.pending` here, and one
+    // that answered has both. A slow write sent twice is still two sends.
+    const sent = new Map();
+    const retried = new Set();
+    for (const [index, e] of events.entries()) {
+        const key = sentWriteKeyOf(e);
+        if (key === undefined) {
+            continue;
+        }
+        if (AUTH_REFUSED.has(asNumber(e.data['status']) ?? 0)) {
+            retried.add(key);
+        }
+        const id = asString(e.data['id']) ?? `#${String(index)}`;
+        sent.set(key, (sent.get(key) ?? new Set()).add(id));
+    }
+    for (const [key, ids] of sent) {
+        if (ids.size > 1 && !retried.has(key)) {
+            anomalies.push({
+                kind: DUPLICATE_REQUEST,
+                control,
+                detail: `one press sent ${key} ${String(ids.size)} times`,
+            });
+        }
     }
 }
-function noteAnomalies(events, control, anomalies) {
+/** The write a request or a request still in flight sends, as `writeKeyOf` spells it. */
+function sentWriteKeyOf(e) {
+    if (EventType.NET_PENDING === e.type) {
+        return writeKeyOf({ ...e, type: EventType.NET_REQUEST });
+    }
+    return writeKeyOf(e);
+}
+/** The faults in an action's events: page errors, requests at or above `floor`, contradictions. */
+export function noteAnomalies(events, control, anomalies, floor = FAILED_STATUS) {
     const list = [...events];
-    for (const e of list.filter(isConsoleError))
+    for (const e of list.filter(isConsoleError)) {
         anomalies.push({
             kind: 'console-error',
             control,
             detail: asString(e.data['message']) ?? e.type,
         });
-    for (const e of failedRequests(list, FAILED_STATUS))
+    }
+    for (const e of failedRequests(list, floor)) {
         anomalies.push({
             kind: 'failed-request',
             control,
             detail: `${asString(e.data['method']) ?? ''} ${asString(e.data['url']) ?? ''} → ${String(asNumber(e.data['status']) ?? '')}`,
         });
+    }
     for (const c of findContradictions(list, { actionSince: 0 })) {
-        if (isAdvisory(c.kind) || isAbsenceDerived(c.kind))
+        if (isAdvisory(c.kind) || isAbsenceDerived(c.kind)) {
             continue;
+        }
         anomalies.push({ kind: c.kind, control, detail: `${c.claim}, but ${c.counter}` });
     }
 }

package/dist/features/exhaust/failure-branches.d.ts

@@ -25,6 +25,11 @@ export interface FailureBranches {
      * by hand, or to give the app a visible outcome.
      */
     indistinguishable: string[];
+    /**
+     * Writes that answered an error while exploring too, so there is no success to compare with. Not a
+     * finding. A login with its API down lands on its error message both times.
+     */
+    notSucceeded: string[];
     /** Why nothing was driven, when nothing could be. */
     skipped?: string;
 }

package/dist/features/exhaust/failure-branches.js

@@ -24,10 +24,16 @@ function aborted(e, key) {
         (0 === asNumber(e.data['status']) || e.data['error'] !== undefined));
 }
 export async function driveFailureBranches(port, writes, opts) {
-    const out = { branched: [], unhandled: [], indistinguishable: [] };
+    const out = {
+        branched: [],
+        unhandled: [],
+        indistinguishable: [],
+        notSucceeded: [],
+    };
     const mock = port.mock;
-    if (mock === undefined)
+    if (mock === undefined) {
         return { ...out, ...(0 < writes.length ? { skipped: NO_MOCKS } : {}) };
+    }
     let actions = 0;
     const spent = () => actions >= opts.maxActions;
     const act = (ref, action, value) => {
@@ -35,28 +41,34 @@ export async function driveFailureBranches(port, writes, opts) {
         return port.act(ref, action, value);
     };
     for (const write of writes) {
-        if (spent())
+        if (spent()) {
             break;
+        }
         const last = write.path.at(-1);
-        if (last === undefined)
+        if (last === undefined) {
             continue;
+        }
         try {
             // Everything up to the step that fires the write, THEN the break. Installed before the replay,
             // the abort also broke any setup step sending the same request, and the replay died short of
             // the action it existed to reach.
-            if (!(await replayPath(port, write.path.slice(0, -1), act, spent)))
+            if (!(await replayPath(port, write.path.slice(0, -1), act, spent))) {
                 continue;
-            if (!(await mock([{ urlContains: write.urlPath, method: write.method, abort: true }])))
+            }
+            if (!(await mock([{ urlContains: write.urlPath, method: write.method, abort: true }]))) {
                 return { ...out, skipped: NO_MOCKS };
+            }
             const control = controlsOf((await port.look()).tree).find((c) => c.key === last.key);
-            if (control === undefined)
+            if (control === undefined) {
                 continue;
+            }
             const result = await act(control.ref, last.action, last.value);
             // Driven means the write was SENT and did not complete. An action that never dispatched, or a
             // request the rule did not match, drove nothing — and judging where the app landed after a
             // write that succeeded would accuse it of claiming success over a failure that never happened.
-            if (!result.ok || !result.events.some((e) => aborted(e, write.key)))
+            if (!result.ok || !result.events.some((e) => aborted(e, write.key))) {
                 continue;
+            }
             out.branched.push(write.key);
             const after = await port.look();
             const reached = stateKey(after.route, controlsOf(after.tree));
@@ -68,21 +80,27 @@ export async function driveFailureBranches(port, writes, opts) {
                 actionSince: 0,
                 expectedFailures: [{ method: write.method, urlContains: write.urlPath }],
             }).find((c) => !isAdvisory(c.kind) && !isAbsenceDerived(c.kind));
-            if (contradiction !== undefined)
+            if (contradiction !== undefined) {
                 out.unhandled.push({
                     key: write.key,
                     detail: `${contradiction.claim}, but ${contradiction.counter}`,
                 });
+            }
             // Landing where success lands only ACCUSES when success visibly moved the app. A write whose
             // success shows nothing looks identical failing, and the first version of this called that
             // "claimed success" — found by driving the fixture, whose add-item panel claims nothing at all.
-            else if (write.successState === write.beforeState)
+            else if (true === write.failed) {
+                out.notSucceeded.push(write.key);
+            }
+            else if (write.successState === write.beforeState) {
                 out.indistinguishable.push(write.key);
-            else if (reached === write.successState)
+            }
+            else if (reached === write.successState) {
                 out.unhandled.push({
                     key: write.key,
                     detail: `with ${write.key} failing, the app arrived exactly where it goes when the write succeeds (${after.route ?? 'same page'}) — it claimed success over a failure`,
                 });
+            }
         }
         finally {
             await mock([]);

package/dist/features/exhaust/invariants.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Behaviour checks that need no reference answer.
+ *
+ * A test needs someone to write down what the app should do. These do not: each one compares the app
+ * with itself — the page before an action with the page after its undo, the first press with the
+ * second, the value sent with the value shown, one run with an identical run. Each is a pure
+ * function over observations the explorer already takes, and each returns findings with the steps
+ * that show the fault and, when the app gives it, the source line of the element.
+ *
+ * A check that cannot decide returns nothing. A false finding costs more than a missed one, so every
+ * check below names the case it lets pass on purpose.
+ */
+import { type EdgeStep } from './edge-cases.js';
+import type { ExploredWrite } from './explorer.js';
+import type { FailureBranches } from './failure-branches.js';
+import type { BehaviourFinding } from './ledger.js';
+/** The rule each check holds the app to, in words, for the report. */
+export declare const Invariant: {
+    readonly UNDO_RESTORES: "undo or cancel returns the previous page";
+    readonly REPEAT_IS_STABLE: "a repeated action does not change state again";
+    readonly RELOAD_KEEPS: "a saved value is still shown after reload";
+    readonly SHOWN_IS_SENT: "the value shown after a write is the value the write sent";
+    readonly DETERMINISTIC: "two identical drives give the same result";
+    readonly FAILURE_HANDLED: "no success over a failed write";
+    readonly NO_FAULT: "an edge case gets an answer, not an error";
+    readonly RESPONDS: "a control that is pressed does something";
+};
+export type Invariant = (typeof Invariant)[keyof typeof Invariant];
+/** A page as the explorer looks at it: the route and the interactive snapshot tree. */
+export interface PageObservation {
+    route?: string;
+    tree: string;
+}
+/** A write an action sent, with the server's answer. */
+export interface WriteObservation {
+    /** `METHOD /path`, as `writeKeyOf` spells it. */
+    key: string;
+    status?: number;
+    /** The response body, as text. */
+    response?: string;
+}
+/** What every check takes besides its observations. */
+interface Context {
+    steps: readonly EdgeStep[];
+    /** The element's source. Read it from an action result with `sourceOf` (surface/tools). */
+    source?: {
+        file: string;
+        line: number;
+    };
+}
+/** The two pages show the same thing: refs and focus aside, every line and the route are equal. */
+export declare const samePage: (a: PageObservation, b: PageObservation) => boolean;
+/**
+ * (a) After an action and its undo or cancel, the page shows what it showed before the action.
+ * `after` is the page after the undo. Refs and focus are ignored; every other line counts.
+ */
+export declare function checkUndo(input: {
+    before: PageObservation;
+    after: PageObservation;
+} & Context): BehaviourFinding[];
+/**
+ * (b) An action pressed twice. Two faults:
+ * - the page after the second press is the page after the first, but the second press sent a POST
+ *   the server accepted and answered differently: it created a second thing the screen hides;
+ * - the first press changed nothing on the page and the second changed it.
+ * Lets pass: a toggle or a counter (each press shows its own change), and a POST the server answers
+ * the same way twice (an upsert).
+ */
+export declare function checkRepeat(input: {
+    before: PageObservation;
+    afterFirst: PageObservation;
+    afterSecond: PageObservation;
+    firstWrites?: readonly WriteObservation[];
+    secondWrites?: readonly WriteObservation[];
+} & Context): BehaviourFinding[];
+/**
+ * (c) A value the app said it saved is still shown after a reload. Lets pass: an empty value (there
+ * is nothing to look for), and an app that said the value was not saved.
+ */
+export declare function checkReloadKeeps(input: {
+    value: string;
+    afterReload: PageObservation;
+    appSaidNotSaved?: boolean;
+} & Context): BehaviourFinding[];
+/**
+ * (d) The value a field shows after a write is the value the write request sent for it. Lets pass:
+ * a field that shows nothing (it was cleared or closed), and differences of padding, case and digit
+ * grouping.
+ */
+export declare function checkShownMatchesSent(input: {
+    field: string;
+    sent: string;
+    shown: string | undefined;
+} & Context): BehaviourFinding[];
+/**
+ * (e) Two identical drives from a fresh page show the same page. A difference is reported as
+ * intermittent: one run does not say which result is the fault.
+ *
+ * ponytail: every digit is masked before the compare, so a clock, an id or a relative time does not
+ * read as a different result. The ceiling: two runs that differ only in a number ("3 items" against
+ * "4 items") pass. Mask only time-like and id-like tokens if that proves too loose.
+ */
+export declare function checkDeterministic(input: {
+    first: PageObservation;
+    second: PageObservation;
+} & Context): BehaviourFinding[];
+/**
+ * (f) No success over a failed write. The judgement is `driveFailureBranches`'s own; this only gives
+ * each unhandled write the steps that fire it, so it reads like every other finding.
+ */
+export declare function failureFindings(branches: FailureBranches, writes: readonly ExploredWrite[]): BehaviourFinding[];
+export {};