@reticlehq/server 3.8.2 → 3.10.0

package/dist/features/exhaust/invariants.js

@@ -0,0 +1,188 @@
+/**
+ * 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 { BehaviourFindingKind } from '@reticlehq/core';
+import { describeStep } from './edge-cases.js';
+/** The rule each check holds the app to, in words, for the report. */
+export const Invariant = {
+    UNDO_RESTORES: 'undo or cancel returns the previous page',
+    REPEAT_IS_STABLE: 'a repeated action does not change state again',
+    RELOAD_KEEPS: 'a saved value is still shown after reload',
+    SHOWN_IS_SENT: 'the value shown after a write is the value the write sent',
+    DETERMINISTIC: 'two identical drives give the same result',
+    FAILURE_HANDLED: 'no success over a failed write',
+    NO_FAULT: 'an edge case gets an answer, not an error',
+    RESPONDS: 'a control that is pressed does something',
+};
+const REF = /\s*\(ref=e\d+\)/g;
+/** Focus moves with every action and is not part of what the page shows. */
+const FOCUSED = /\[focused\]|,focused\b|\bfocused,/g;
+const DIGITS = /\d+/g;
+/** How many changed lines a finding quotes. */
+const MAX_QUOTED = 3;
+/** Writes that create something new each time they are sent. PUT and DELETE are idempotent. */
+const CREATES = 'POST ';
+const OK_MIN = 200;
+const OK_MAX = 299;
+function visibleLines(page) {
+    const lines = page.tree
+        .split('\n')
+        .map((line) => line
+        .replace(REF, '')
+        .replace(FOCUSED, '')
+        .replace(/\s*\[\]/g, '')
+        .trimEnd())
+        .filter((line) => line.trim().length > 0);
+    return [`route ${page.route ?? ''}`, ...lines];
+}
+const same = (a, b) => a.length === b.length && a.every((line, i) => line === b[i]);
+/** The two pages show the same thing: refs and focus aside, every line and the route are equal. */
+export const samePage = (a, b) => same(visibleLines(a), visibleLines(b));
+/** The lines one page has and the other does not, quoted for a finding. */
+function difference(before, after) {
+    const gone = before.filter((line) => !after.includes(line)).slice(0, MAX_QUOTED);
+    const added = after.filter((line) => !before.includes(line)).slice(0, MAX_QUOTED);
+    const parts = [
+        ...(gone.length > 0 ? [`missing: ${gone.map((l) => l.trim()).join('; ')}`] : []),
+        ...(added.length > 0 ? [`new: ${added.map((l) => l.trim()).join('; ')}`] : []),
+    ];
+    return parts.length > 0 ? parts.join(' | ') : 'the lines are in a different order';
+}
+function finding(kind, invariant, detail, ctx, extraSteps = []) {
+    const src = ctx.source;
+    return {
+        kind,
+        invariant,
+        detail,
+        sequence: [...ctx.steps.map(describeStep), ...extraSteps],
+        ...(src === undefined ? {} : { source: `${src.file}:${String(src.line)}` }),
+    };
+}
+/**
+ * (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 function checkUndo(input) {
+    const before = visibleLines(input.before);
+    const after = visibleLines(input.after);
+    if (same(before, after)) {
+        return [];
+    }
+    return [
+        finding(BehaviourFindingKind.UNDO_NOT_RESTORED, Invariant.UNDO_RESTORES, `the page after undo is not the page before the action (${difference(before, after)})`, input),
+    ];
+}
+const isOk = (w) => w.status !== undefined && w.status >= OK_MIN && w.status <= OK_MAX;
+/**
+ * (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 function checkRepeat(input) {
+    const before = visibleLines(input.before);
+    const first = visibleLines(input.afterFirst);
+    const second = visibleLines(input.afterSecond);
+    if (same(first, second)) {
+        const firstWrites = input.firstWrites ?? [];
+        const hidden = (input.secondWrites ?? []).find((w) => w.key.startsWith(CREATES) &&
+            isOk(w) &&
+            !firstWrites.some((f) => f.key === w.key && f.response === w.response));
+        if (hidden === undefined) {
+            return [];
+        }
+        return [
+            finding(BehaviourFindingKind.REPEAT_CHANGED_STATE, Invariant.REPEAT_IS_STABLE, `the second press sent ${hidden.key} and the server accepted it with a new answer, but the page shows the same result as after the first press`, input),
+        ];
+    }
+    if (!same(before, first)) {
+        return [];
+    }
+    return [
+        finding(BehaviourFindingKind.REPEAT_CHANGED_STATE, Invariant.REPEAT_IS_STABLE, `the first press changed nothing and the second press changed the page (${difference(first, second)})`, input),
+    ];
+}
+/**
+ * (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 function checkReloadKeeps(input) {
+    const value = input.value.trim();
+    if (0 === value.length ||
+        true === input.appSaidNotSaved ||
+        input.afterReload.tree.includes(value)) {
+        return [];
+    }
+    return [
+        finding(BehaviourFindingKind.LOST_AFTER_RELOAD, Invariant.RELOAD_KEEPS, `the app saved ${JSON.stringify(value)}, and after a reload the page does not show it`, input, ['reload']),
+    ];
+}
+/** Padding, case and digit grouping are presentation, not a different value. */
+function normalized(value) {
+    const text = value.trim().replace(/\s+/g, ' ').toLowerCase();
+    return /^-?[\d,]+(?:\.\d+)?$/.test(text) ? text.replace(/,/g, '') : text;
+}
+/**
+ * (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 function checkShownMatchesSent(input) {
+    if (input.shown === undefined || 0 === input.shown.trim().length) {
+        return [];
+    }
+    if (normalized(input.shown) === normalized(input.sent)) {
+        return [];
+    }
+    return [
+        finding(BehaviourFindingKind.SHOWN_DIFFERS_FROM_SENT, Invariant.SHOWN_IS_SENT, `${input.field} shows ${JSON.stringify(input.shown)}, but the write sent ${JSON.stringify(input.sent)}`, input),
+    ];
+}
+/**
+ * (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 function checkDeterministic(input) {
+    const shape = (page) => visibleLines(page).map((line) => line.replace(DIGITS, '#'));
+    const first = shape(input.first);
+    const second = shape(input.second);
+    if (same(first, second)) {
+        return [];
+    }
+    return [
+        {
+            ...finding(BehaviourFindingKind.INTERMITTENT_RESULT, Invariant.DETERMINISTIC, `two identical drives showed different pages (${difference(first, second)})`, input),
+            intermittent: true,
+        },
+    ];
+}
+/**
+ * (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 function failureFindings(branches, writes) {
+    return branches.unhandled.map((u) => ({
+        kind: BehaviourFindingKind.FAILURE_UNHANDLED,
+        invariant: Invariant.FAILURE_HANDLED,
+        detail: u.detail,
+        sequence: [
+            ...(writes.find((w) => w.key === u.key)?.path ?? []).map(describeStep),
+            `fail ${u.key}`,
+        ],
+    }));
+}

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

@@ -30,6 +30,18 @@ export declare const CoverageLevel: {
     readonly EXECUTED: "executed";
 };
 export type CoverageLevel = (typeof CoverageLevel)[keyof typeof CoverageLevel];
+/** How many missing items a level names before it only counts them. */
+export declare const MAX_MISSING = 50;
+/** A behaviour fault the explorer found. See `invariants.ts`, which produces these. */
+export declare const BehaviourFindingSchema: z.ZodObject<{
+    kind: z.ZodString;
+    invariant: z.ZodString;
+    detail: z.ZodString;
+    sequence: z.ZodArray<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    intermittent: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type BehaviourFinding = z.infer<typeof BehaviourFindingSchema>;
 declare const LedgerSchema: z.ZodObject<{
     routes: z.ZodObject<{
         discovered: z.ZodArray<z.ZodString>;
@@ -48,6 +60,17 @@ declare const LedgerSchema: z.ZodObject<{
         branched: z.ZodArray<z.ZodString>;
         unhandled: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
+    edges: z.ZodDefault<z.ZodObject<{
+        probed: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    findings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        invariant: z.ZodString;
+        detail: z.ZodString;
+        sequence: z.ZodArray<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+        intermittent: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
     code: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
         name: z.ZodString;
         executed: z.ZodBoolean;
@@ -62,6 +85,8 @@ export interface LedgerDelta {
     controls?: Partial<AppLedger['controls']>;
     journeys?: Partial<AppLedger['journeys']>;
     writes?: Partial<AppLedger['writes']>;
+    edges?: Partial<AppLedger['edges']>;
+    findings?: readonly BehaviourFinding[];
     code?: CodeCoverage;
     /** When `code` was taken, so a file edited since reads as not measured rather than as covered. */
     codeTakenAt?: number;
@@ -87,6 +112,49 @@ export declare function coveragePercents(reticleRoot: string): Record<string, nu
 export declare function emptyLedger(): AppLedger;
 export declare function mergeLedger(into: AppLedger, delta: LedgerDelta): AppLedger;
 export declare function levelsOf(ledger: AppLedger): LevelReport[];
+/**
+ * What was never reached, as named items: the holes in the exploration.
+ *
+ * The levels above give a number per level. A number does not say where to go next, and it hides a
+ * level that was never measured behind an empty list. `holesOf` names every gap by kind, says when
+ * a kind was not measured at all, and counts the items past its cap. Nothing is left out in silence.
+ */
+export declare const HoleKind: {
+    /** Routes discovered and never visited. */
+    readonly ROUTES: "routes";
+    /** Controls seen and never driven. */
+    readonly CONTROLS: "controls";
+    /** Controls seen whose edge cases were never driven. */
+    readonly EDGES: "edges";
+    /** Writes seen whose failure path was never driven. */
+    readonly WRITES: "writes";
+    /** App functions loaded and never executed, as `file: function`. */
+    readonly FUNCTIONS: "functions";
+    /** Components the app has and never rendered. */
+    readonly COMPONENTS: "components";
+};
+export type HoleKind = (typeof HoleKind)[keyof typeof HoleKind];
+export interface HoleList {
+    /** False when nothing could measure this kind: an empty list then means "unknown", not "none". */
+    measured: boolean;
+    items: string[];
+    /** How many more items there are than `items` names. */
+    overflow?: number;
+    /** Why the kind is not measured, or what to do to measure it. */
+    note?: string;
+}
+export type HolesReport = Record<HoleKind, HoleList>;
+/** The React adapter's component inventory: every component it knows, and the ones it rendered. */
+export interface ComponentInventory {
+    known: readonly string[];
+    rendered: readonly string[];
+}
+export declare const HoleNote: {
+    readonly CODE: "Not measured: code coverage needs a browser Reticle drives (`reticle drive`, or RETICLE_CDP_URL).";
+    readonly COMPONENTS: "Not measured: no component inventory is available. A component that never rendered still shows in `functions` when code coverage is on.";
+    readonly EDGES: "No edge cases were driven yet. Run `reticle_crawl { exhaustive: true }`; every control listed here is still a hole.";
+};
+export declare function holesOf(ledger: AppLedger, components?: ComponentInventory): HolesReport;
 /** The best percentage each level has reached, raised to today's where today is higher. */
 export declare function raiseBest(ledger: AppLedger): AppLedger;
 /**

package/dist/features/exhaust/ledger.js

@@ -34,13 +34,31 @@ export const CoverageLevel = {
 };
 const LEDGER_VERSION = 1;
 /** How many missing items a level names before it only counts them. */
-const MAX_MISSING = 50;
+export const MAX_MISSING = 50;
 const names = z.array(z.string());
+/** A behaviour fault the explorer found. See `invariants.ts`, which produces these. */
+export const BehaviourFindingSchema = z.object({
+    /** A `BehaviourFindingKind` from core, or the kind of a fault an edge case caused (`console-error`). */
+    kind: z.string(),
+    /** The rule that did not hold, in words. */
+    invariant: z.string(),
+    detail: z.string(),
+    /** The steps that show it, from a fresh page. */
+    sequence: z.array(z.string()),
+    /** `file:line` of the element, when the app gives source attribution. */
+    source: z.string().optional(),
+    /** True when the fault did not occur on every run. */
+    intermittent: z.boolean().optional(),
+});
 const LedgerSchema = z.object({
     routes: z.object({ discovered: names, reached: names }),
     controls: z.object({ seen: names, touched: names, proved: names }),
     journeys: z.object({ completed: names }),
     writes: z.object({ seen: names, branched: names, unhandled: names }),
+    /** Controls whose edge cases (edge inputs, edge interactions) were driven. */
+    edges: z.object({ probed: names }).default({ probed: [] }),
+    /** Behaviour faults, one copy each. Absent in a ledger from before they existed. */
+    findings: z.array(BehaviourFindingSchema).default([]),
     code: z.record(z.string(), z.record(z.string(), z.object({ name: z.string(), executed: z.boolean() }))),
     /** Per file, when its code coverage was last taken. Absent in a ledger from before it existed. */
     codeTaken: z.record(z.string(), z.number()).default({}),
@@ -74,8 +92,9 @@ export function coveragePercents(reticleRoot) {
     }
     const out = {};
     for (const report of levelsOf(parseLedger(text))) {
-        if (report.pct !== undefined)
+        if (report.pct !== undefined) {
             out[report.level] = report.pct;
+        }
     }
     return 0 < Object.keys(out).length ? out : undefined;
 }
@@ -85,12 +104,27 @@ export function emptyLedger() {
         controls: { seen: [], touched: [], proved: [] },
         journeys: { completed: [] },
         writes: { seen: [], branched: [], unhandled: [] },
+        edges: { probed: [] },
+        findings: [],
         code: {},
         codeTaken: {},
         best: {},
     };
 }
 const union = (a, b) => b === undefined ? [...a] : [...new Set([...a, ...b])];
+/** The same fault found again by the same steps is one finding; the first copy is kept. */
+const findingKey = (f) => `${f.kind}\n${f.sequence.join('\n')}`;
+function unionFindings(into, add) {
+    const out = [...into];
+    const keys = new Set(out.map(findingKey));
+    for (const f of add ?? []) {
+        if (!keys.has(findingKey(f))) {
+            keys.add(findingKey(f));
+            out.push(f);
+        }
+    }
+    return out;
+}
 export function mergeLedger(into, delta) {
     const code = { ...into.code };
     const codeTaken = { ...into.codeTaken };
@@ -100,12 +134,15 @@ export function mergeLedger(into, delta) {
             merged[key] = { name: fn.name, executed: fn.executed || true === merged[key]?.executed };
         }
         code[file] = merged;
-        if (delta.codeTakenAt !== undefined)
+        if (delta.codeTakenAt !== undefined) {
             codeTaken[file] = delta.codeTakenAt;
+        }
     }
-    // Reaching a route discovers it; touching or proving a control means it was seen.
+    // Reaching a route discovers it; touching or proving a control means it was seen. Probing a
+    // control's edge cases drove it, so it was touched.
     const reached = union(into.routes.reached, delta.routes?.reached);
-    const touched = union(into.controls.touched, delta.controls?.touched);
+    const probed = union(into.edges.probed, delta.edges?.probed);
+    const touched = union(union(into.controls.touched, delta.controls?.touched), probed);
     const proved = union(into.controls.proved, delta.controls?.proved);
     const branched = union(into.writes.branched, delta.writes?.branched);
     return {
@@ -124,6 +161,8 @@ export function mergeLedger(into, delta) {
             branched,
             unhandled: union(into.writes.unhandled, delta.writes?.unhandled),
         },
+        edges: { probed },
+        findings: unionFindings(into.findings, delta.findings),
         code,
         codeTaken,
         best: { ...into.best },
@@ -166,12 +205,74 @@ export function levelsOf(ledger) {
         executedLevel(ledger.code),
     ];
 }
+/**
+ * What was never reached, as named items: the holes in the exploration.
+ *
+ * The levels above give a number per level. A number does not say where to go next, and it hides a
+ * level that was never measured behind an empty list. `holesOf` names every gap by kind, says when
+ * a kind was not measured at all, and counts the items past its cap. Nothing is left out in silence.
+ */
+export const HoleKind = {
+    /** Routes discovered and never visited. */
+    ROUTES: 'routes',
+    /** Controls seen and never driven. */
+    CONTROLS: 'controls',
+    /** Controls seen whose edge cases were never driven. */
+    EDGES: 'edges',
+    /** Writes seen whose failure path was never driven. */
+    WRITES: 'writes',
+    /** App functions loaded and never executed, as `file: function`. */
+    FUNCTIONS: 'functions',
+    /** Components the app has and never rendered. */
+    COMPONENTS: 'components',
+};
+export const HoleNote = {
+    CODE: 'Not measured: code coverage needs a browser Reticle drives (`reticle drive`, or RETICLE_CDP_URL).',
+    COMPONENTS: 'Not measured: no component inventory is available. A component that never rendered still shows in `functions` when code coverage is on.',
+    EDGES: 'No edge cases were driven yet. Run `reticle_crawl { exhaustive: true }`; every control listed here is still a hole.',
+};
+function named(universe, covered) {
+    const done = new Set(covered);
+    const missing = [...new Set(universe)].filter((item) => !done.has(item));
+    return {
+        measured: true,
+        items: missing.slice(0, MAX_MISSING),
+        ...(missing.length > MAX_MISSING ? { overflow: missing.length - MAX_MISSING } : {}),
+    };
+}
+/** The same named list a coverage level reports, so the two can never disagree. */
+function fromLevel(ledger, level) {
+    const report = levelsOf(ledger).find((l) => l.level === level);
+    return {
+        measured: true,
+        items: report?.missing ?? [],
+        ...(report?.missingOverflow === undefined ? {} : { overflow: report.missingOverflow }),
+    };
+}
+export function holesOf(ledger, components) {
+    const edges = named(ledger.controls.seen, ledger.edges.probed);
+    return {
+        [HoleKind.ROUTES]: fromLevel(ledger, CoverageLevel.REACHED),
+        [HoleKind.CONTROLS]: fromLevel(ledger, CoverageLevel.TOUCHED),
+        [HoleKind.EDGES]: 0 === ledger.edges.probed.length
+            ? { ...edges, measured: false, note: HoleNote.EDGES }
+            : edges,
+        [HoleKind.WRITES]: fromLevel(ledger, CoverageLevel.BRANCHED),
+        [HoleKind.FUNCTIONS]: 0 === Object.keys(ledger.code).length
+            ? { measured: false, items: [], note: HoleNote.CODE }
+            : fromLevel(ledger, CoverageLevel.EXECUTED),
+        [HoleKind.COMPONENTS]: components === undefined
+            ? { measured: false, items: [], note: HoleNote.COMPONENTS }
+            : named(components.known, components.rendered),
+    };
+}
 /** The best percentage each level has reached, raised to today's where today is higher. */
 export function raiseBest(ledger) {
     const best = { ...ledger.best };
     for (const l of levelsOf(ledger)) {
-        if (l.pct !== undefined && l.pct > (best[l.level] ?? -1))
+        if (l.pct !== undefined && l.pct > (best[l.level] ?? -1)) {
             best[l.level] = l.pct;
+        }
     }
     return { ...ledger, best };
 }
@@ -181,9 +282,11 @@ export function raiseBest(ledger) {
  */
 export function acceptCurrent(ledger) {
     const best = {};
-    for (const l of levelsOf(ledger))
-        if (l.pct !== undefined)
+    for (const l of levelsOf(ledger)) {
+        if (l.pct !== undefined) {
             best[l.level] = l.pct;
+        }
+    }
     return { ...ledger, best };
 }
 /** Levels now below the best they ever reached — something new appeared and nothing covered it. */
@@ -191,8 +294,9 @@ export function regressions(ledger) {
     const out = [];
     for (const l of levelsOf(ledger)) {
         const was = ledger.best[l.level];
-        if (l.pct !== undefined && was !== undefined && l.pct < was)
+        if (l.pct !== undefined && was !== undefined && l.pct < was) {
             out.push({ level: l.level, was, now: l.pct });
+        }
     }
     return out;
 }
@@ -207,8 +311,9 @@ function servedAs(code, file) {
 export function unexecutedChanged(code, changed) {
     return changed.filter((file) => {
         const served = servedAs(code, file);
-        if (served === undefined)
+        if (served === undefined) {
             return false;
+        }
         const fns = Object.values(code[served] ?? {});
         return fns.length > 0 && fns.every((fn) => !fn.executed);
     });
@@ -223,8 +328,9 @@ export function staleChanged(ledger, changed, modifiedAt) {
     return changed.filter((file) => {
         const served = servedAs(ledger.code, file);
         const modified = modifiedAt(file);
-        if (served === undefined || modified === undefined)
+        if (served === undefined || modified === undefined) {
             return false;
+        }
         const taken = ledger.codeTaken[served];
         return taken === undefined || modified > taken;
     });
@@ -243,8 +349,9 @@ export class LedgerStore {
             text = await this.#fs.readFile(this.#path);
         }
         catch (error) {
-            if (this.#fs.isNotFound(error))
+            if (this.#fs.isNotFound(error)) {
                 return emptyLedger();
+            }
             throw error;
         }
         return parseLedger(text);
@@ -264,8 +371,9 @@ export class LedgerStore {
         return withFileLock(this.#path, async () => {
             const ledger = await this.load();
             const accepted = regressions(ledger);
-            if (accepted.length > 0)
+            if (accepted.length > 0) {
                 await this.#save(acceptCurrent(ledger));
+            }
             return accepted;
         });
     }

package/dist/features/exhaust/session-fold.d.ts

@@ -29,3 +29,13 @@ export declare function sessionDelta(input: {
 export declare function isConsoleError(e: ReticleEvent): boolean;
 /** Requests that answered at or above `floor`. */
 export declare function failedRequests(events: ReticleEvent[], floor: number): ReticleEvent[];
+/** Any buffer event that proves the app reacted to a click (vs a dead/no-op control). */
+export declare function isActivity(e: ReticleEvent): boolean;
+/**
+ * Controls whose correct behaviour IS to do nothing when clicked.
+ *
+ * Read off the same descriptor the crawler already has, so no extra round trip: `[disabled]` is inert
+ * by definition, an already `[checked]` radio/checkbox is idempotent, and clicking a text field
+ * focuses it rather than changing anything.
+ */
+export declare function legitimatelyInert(desc: string): boolean;

package/dist/features/exhaust/session-fold.js

@@ -14,12 +14,14 @@ const ID_SEGMENT = /^(?:\d+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9
  * refund of order 41 and of order 42 are one endpoint with one failure path to drive, not two.
  */
 export function writeKeyOf(event) {
-    if (EventType.NET_REQUEST !== event.type)
+    if (EventType.NET_REQUEST !== event.type) {
         return undefined;
+    }
     const method = asString(event.data['method'])?.toUpperCase();
     const url = asString(event.data['url']);
-    if (method === undefined || url === undefined || !MUTATING_METHODS.includes(method))
+    if (method === undefined || url === undefined || !MUTATING_METHODS.includes(method)) {
         return undefined;
+    }
     let path;
     try {
         path = new URL(url, 'http://localhost').pathname;
@@ -71,9 +73,50 @@ export function isConsoleError(e) {
 /** Requests that answered at or above `floor`. */
 export function failedRequests(events, floor) {
     return events.filter((e) => {
-        if (e.type !== EventType.NET_REQUEST)
+        if (e.type !== EventType.NET_REQUEST) {
             return false;
+        }
         const status = asNumber(e.data['status']);
         return status !== undefined && status >= floor;
     });
 }
+/** Any buffer event that proves the app reacted to a click (vs a dead/no-op control). */
+export function isActivity(e) {
+    return (e.type === EventType.NET_REQUEST ||
+        e.type === EventType.DOM_ADDED ||
+        e.type === EventType.DOM_REMOVED ||
+        e.type === EventType.DOM_ATTR ||
+        e.type === EventType.DOM_TEXT ||
+        e.type === EventType.ROUTE_CHANGE ||
+        e.type === EventType.SIGNAL ||
+        e.type === EventType.ANIM_START ||
+        e.type === EventType.ANIM_END);
+}
+/**
+ * Controls whose correct behaviour IS to do nothing when clicked.
+ *
+ * Read off the same descriptor the crawler already has, so no extra round trip: `[disabled]` is inert
+ * by definition, an already `[checked]` radio/checkbox is idempotent, and clicking a text field
+ * focuses it rather than changing anything.
+ */
+export function legitimatelyInert(desc) {
+    if (desc.includes('[disabled]')) {
+        return true;
+    }
+    if (desc.includes('[checked]')) {
+        return true;
+    }
+    // Inputs, and the ARIA LIVE-REGION roles.
+    //
+    // `alert`, `status`, `log`, `timer` and `marquee` exist to be READ — a screen reader announces
+    // them and nothing is meant to happen when one is clicked. Clicking twice and seeing nothing is
+    // therefore correct behaviour, and reporting it as `dead-control` accuses a working app.
+    //
+    // Found by driving a real app: the demo reported `dead-control — alert "Invalid email or
+    // password"`, which is a login form correctly telling somebody their password was wrong. That is
+    // the most expensive kind of false positive there is — the strongest claim the crawler makes,
+    // about an app that was working, and on the path a new user meets first.
+    //
+    // `alertdialog` is deliberately NOT here: it is interactive, and a word boundary keeps it out.
+    return /\b(textbox|searchbox|combobox|spinbutton|alert|status|log|timer|marquee)\b/.test(desc);
+}

package/dist/features/exhaust/session-port.d.ts

@@ -7,7 +7,7 @@
  * the successor before it answers — the same wait `navigate { reload }` does.
  */
 import { type CommandResult, type ReticleEvent } from '@reticlehq/core';
-import type { ExplorePort } from './explorer.js';
+import { type ExplorePort } from './explorer.js';
 export interface PortSession {
     readonly id: string;
     readonly url: string;
@@ -17,6 +17,8 @@ export interface PortSession {
     beginAction?(tool: string, args: Record<string, unknown>): unknown;
     finishAction?(): void;
 }
+/** How long a press waits for the requests it started to answer. */
+export declare const PENDING_WAIT_MS = 10000;
 export declare function sessionPort(input: {
     sessions: {
         get(id: string): PortSession | undefined;