@reticlehq/server 3.9.0 → 3.10.0

package/dist/features/crawl/crawl-tools.js

@@ -5,7 +5,7 @@ import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { stepCountSchema, timeoutMsSchema } from '../../surface/tools/args/numeric-bounds.js';
 import { crawl } from './crawl.js';
-import { EXHAUST_DEFAULT_ACTIONS, runExhaustive } from '../exhaust/exhaust-run.js';
+import { runExhaustive } from './crawl-exhaustive.js';
 import { heuristicFillValue } from '../harness/fill-values.js';
 import { secretEnvKey } from '../../language/flows/flows.js';
 import { CRAWL_DEFAULTS } from '@reticlehq/core';
@@ -16,6 +16,24 @@ const nodeSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * from whatever page is on screen, so without the check a page on another origin could name an
  * empty textbox after a secret and have the crawl type it in.
  */
+/**
+ * How the exhaustive crawl breaks a request: the driven browser first, then the leased page the
+ * session runs in. `reticle mcp --headless` drives a lease, and the mock tool already reaches it the
+ * same way. Undefined when neither exists, so the crawl says why its failure paths were skipped.
+ */
+export function exhaustiveMocks(deps, sessionId) {
+    const driven = deps.realInput?.setMocks?.bind(deps.realInput);
+    const pool = deps.pool;
+    if (driven === undefined && pool === undefined) {
+        return undefined;
+    }
+    return async (url, rules) => {
+        if (driven !== undefined && (await driven(url, rules))) {
+            return true;
+        }
+        return true === (await pool?.setMocksLease(sessionId, rules));
+    };
+}
 export function crawlSecret(startUrl, env) {
     const originOf = (url) => {
         try {
@@ -29,14 +47,14 @@ export function crawlSecret(startUrl, env) {
     return (name, pageUrl) => home !== undefined && home === originOf(pageUrl) ? env[secretEnvKey(name)] : undefined;
 }
 /**
- * The autonomous "smart monkey" tool. Builds on reticle_explore (which only LISTS) by
+ * The autonomous "smart monkey" tool. Builds on the interactive snapshot (which only LISTS) by
  * actually clicking each reachable control and classifying the reaction. DESTRUCTIVE by nature —
  * it drives the app — so it's an explicit, bounded tool, never part of a passive read.
  */
 export const CRAWL_TOOLS = [
     {
         name: ReticleTool.CRAWL,
-        description: 'Autonomously click every reachable interactive control (bounded by maxSteps, default 25) and report anomalies WITHOUT a script. Two classes: single-channel faults (console errors, failed requests ≥400, DEAD controls that dispatched but did nothing) and CONTRADICTIONS — two channels disagreeing about the same click, e.g. the UI advanced while its write failed, a success signal fired over a failed request, a write succeeded and nothing changed, the same write fired twice, or the UI moved on over an in-flight request. Contradictions are the false greens a human cannot see, because a human watches one channel (the screen) and it looks correct. DESTRUCTIVE — it really clicks (may navigate/mutate state); use reticle_explore first for a non-destructive list. Returns { interactiveFound, stepsRun, anomalies[{kind,ref,desc,detail}], counts, visited, truncated }.',
+        description: 'Autonomously click every reachable interactive control (bounded by maxSteps, default 25) and report anomalies WITHOUT a script. Two classes: single-channel faults (console errors, failed requests ≥400, DEAD controls that dispatched but did nothing) and CONTRADICTIONS — two channels disagreeing about the same click, e.g. the UI advanced while its write failed, a success signal fired over a failed request, a write succeeded and nothing changed, the same write fired twice, or the UI moved on over an in-flight request. Contradictions are the false greens a human cannot see, because a human watches one channel (the screen) and it looks correct. DESTRUCTIVE — it really clicks (may navigate/mutate state); use reticle_snapshot { mode: "interactive" } first for a non-destructive list. Returns { interactiveFound, stepsRun, anomalies[{kind,ref,desc,detail}], counts, visited, truncated }.',
         inputSchema: {
             maxSteps: stepCountSchema
                 .optional()
@@ -51,7 +69,7 @@ export const CRAWL_TOOLS = [
             exhaustive: z
                 .boolean()
                 .optional()
-                .describe("Walk every state it can tell apart, drive each write's failure path, fold into the coverage ledger."),
+                .describe("Walk every state it can tell apart, drive each write's failure path and edge cases, fold into the coverage ledger."),
             confirmDangerous: z
                 .boolean()
                 .optional()
@@ -91,7 +109,7 @@ export const CRAWL_TOOLS = [
                 .array(z.object({ ref: z.string(), desc: z.string(), reason: z.string() }))
                 .optional()
                 .describe('Controls clicked whose silence could not be judged, e.g. on a background tab. They are NOT reported as dead, and they are not known to work either.'),
-            // Only on `exhaustive` — see features/exhaust/exhaust-run.ts. Loose: it carries the levels.
+            // Only on `exhaustive` — see crawl-exhaustive.ts. Loose: it carries the levels.
             exhaustive: z.record(z.string(), z.unknown()).optional(),
         },
         handler: async (deps, args) => {
@@ -111,11 +129,12 @@ export const CRAWL_TOOLS = [
                 // Starts code-coverage collection, so the drive below is measured. See takeCodeCoverage.
                 await deps.realInput?.takeCodeCoverage?.(session.url);
                 const secret = crawlSecret(session.url, process.env);
+                const mocks = exhaustiveMocks(deps, session.id);
                 return runExhaustive({
                     sessions: deps.sessions,
                     session,
                     startUrl: session.url,
-                    maxActions: maxSteps ?? EXHAUST_DEFAULT_ACTIONS,
+                    ...(maxSteps === undefined ? {} : { maxActions: maxSteps }),
                     settleMs: settleMs ?? CRAWL_DEFAULTS.SETTLE_MS,
                     fillValue: (label, pageUrl) => {
                         const name = /"([^"]*)"/.exec(label)?.[1] ?? label;
@@ -123,11 +142,7 @@ export const CRAWL_TOOLS = [
                     },
                     now: deps.now,
                     sleep: nodeSleep,
-                    ...(deps.realInput?.setMocks === undefined
-                        ? {}
-                        : {
-                            setMocks: (url, rules) => deps.realInput?.setMocks?.(url, rules) ?? Promise.resolve(false),
-                        }),
+                    ...(mocks === undefined ? {} : { setMocks: mocks }),
                     ...(deps.realInput?.takeCodeCoverage === undefined
                         ? {}
                         : {
@@ -142,8 +157,9 @@ export const CRAWL_TOOLS = [
                 ...(initialRoute === undefined ? [] : [initialRoute]),
                 ...routesFromEvents(session.eventsSince(since)),
             ];
-            if (routes.length > 0)
+            if (routes.length > 0) {
                 await projectForRoot(deps, sessionRoot(deps, session.id)).recordRoutes(routes);
+            }
             return report;
         },
     },

package/dist/features/crawl/crawl.d.ts

@@ -1,3 +1,10 @@
+/**
+ * The autonomous "smart monkey": discover every reachable interactive control once, click each
+ * (bounded by `maxSteps`) and classify the reaction into anomalies — console errors, failed
+ * requests, and DEAD controls (dispatched but the app did nothing). Pure orchestration over a
+ * `CrawlSession`, so no browser or Node imports. Single-pass by design, so it always terminates.
+ */
+import { legitimatelyInert } from '../exhaust/session-fold.js';
 import { type CommandResult, type ReticleEvent } from '@reticlehq/core';
 /** The slice of Session the crawler needs — so tests inject a fake without a live browser. */
 export interface CrawlSession {
@@ -94,13 +101,5 @@ export interface CrawlOptions {
     scope?: string;
     confirmDangerous?: 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;
 export declare function crawl(session: CrawlSession, opts: CrawlOptions, sleep: CrawlSleep): Promise<CrawlReport>;
-export {};
+export { legitimatelyInert };

package/dist/features/crawl/crawl.js

@@ -4,8 +4,9 @@
  * requests, and DEAD controls (dispatched but the app did nothing). Pure orchestration over a
  * `CrawlSession`, so no browser or Node imports. Single-pass by design, so it always terminates.
  */
+import { isActivity, legitimatelyInert } from '../exhaust/session-fold.js';
 import { span } from '../../trace.js';
-import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
+import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, DANGEROUS_ACTION_CONFIRM_ARG, ReticleCommand, } from '@reticlehq/core';
 import { crawlEmptyNote } from './crawl-empty.js';
 import { failedRequests, isConsoleError } from '../exhaust/session-fold.js';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
@@ -40,20 +41,12 @@ function revealedControlsNote(count) {
  */
 const ENDS_SESSION = /\b(?:sign ?out|log ?out|sign ?off|log ?off)\b/i;
 const ENDS_SESSION_NOT_PRESSED = 'not pressed: it ends the signed-in session the crawl is driving';
+const NO_ACCESSIBLE_NAME_NOT_PRESSED = 'not pressed: no accessible name, so the destructive-action guard cannot classify it (set confirmDangerous to include it)';
+// A snapshot line carries the accessible name, a value or an own text as a quoted string. A line
+// with no quote has no text at all, for example an icon-only button.
+const HAS_TEXT = /"/;
 /** Why a silent control on a throttled page is not reported as dead. */
 const BACKGROUND_TAB_NOT_JUDGED = 'not judged: the page is throttled (its tab is in the background, or it has not been heard from recently), so a reaction may not show inside the sample window; bring the tab to the front and crawl again';
-/** Any buffer event that proves the app reacted to a click (vs a dead/no-op control). */
-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);
-}
 const SOURCE_FRAME = /^(.*):(\d+):(\d+)$/;
 const COMPONENT_STACK_FIELDS = ['componentStack', 'message'];
 const URL_SOURCE_PROTOCOLS = new Set([
@@ -66,44 +59,54 @@ const URL_SOURCE_PROTOCOLS = new Set([
 /** Turn a browser/dev-server frame URL into the file-shaped pointer the rest of Reticle emits. */
 function sourceFile(raw) {
     let file = raw.trim();
-    if (0 === file.length)
+    if (0 === file.length) {
         return undefined;
+    }
     try {
         const parsed = new URL(file);
-        if (URL_SOURCE_PROTOCOLS.has(parsed.protocol))
+        if (URL_SOURCE_PROTOCOLS.has(parsed.protocol)) {
             file = decodeURIComponent(parsed.pathname);
+        }
     }
     catch {
         // A repo-relative or Windows path is already the more useful form; keep it as-is.
     }
     file = file.replace(/[?#].*$/, '').replace(/\\/g, '/');
     const bundledPrefix = file.lastIndexOf('/./');
-    if (-1 !== bundledPrefix)
+    if (-1 !== bundledPrefix) {
         file = file.slice(bundledPrefix + 3);
-    if (file.startsWith('/@fs/'))
+    }
+    if (file.startsWith('/@fs/')) {
         file = file.slice('/@fs/'.length);
-    if (/^\/[A-Za-z]:\//.test(file))
+    }
+    if (/^\/[A-Za-z]:\//.test(file)) {
         file = file.slice(1);
-    else
+    }
+    else {
         file = file.replace(/^\/+/, '');
-    if (file.startsWith('./'))
+    }
+    if (file.startsWith('./')) {
         file = file.slice(2);
+    }
     return 0 === file.length ? undefined : file;
 }
 /** The location part of a Chrome/React or Firefox stack frame. */
 function frameLocation(line) {
     let frame = line.trim();
-    if (frame.startsWith('at '))
+    if (frame.startsWith('at ')) {
         frame = frame.slice(3).trim();
+    }
     else {
         const firefoxSeparator = frame.lastIndexOf('@');
-        if (-1 === firefoxSeparator)
+        if (-1 === firefoxSeparator) {
             return undefined;
+        }
         frame = frame.slice(firefoxSeparator + 1);
     }
     const opening = frame.lastIndexOf('(');
-    if (-1 !== opening && frame.endsWith(')'))
+    if (-1 !== opening && frame.endsWith(')')) {
         return frame.slice(opening + 1, -1);
+    }
     return frame;
 }
 function isFrameworkSource(file) {
@@ -114,14 +117,17 @@ function isFrameworkSource(file) {
 function sourceFromStack(stack) {
     for (const line of stack.split('\n')) {
         const location = frameLocation(line);
-        if (location === undefined)
+        if (location === undefined) {
             continue;
+        }
         const match = SOURCE_FRAME.exec(location);
-        if (null === match)
+        if (null === match) {
             continue;
+        }
         const [, rawFile, rawLine] = match;
-        if (rawFile === undefined || rawLine === undefined)
+        if (rawFile === undefined || rawLine === undefined) {
             continue;
+        }
         const file = sourceFile(rawFile);
         const lineNumber = Number(rawLine);
         if (file === undefined ||
@@ -140,55 +146,33 @@ function sourceFromConsoleError(event) {
     // observer carries it inside `message`; richer producers can send `componentStack` directly.
     for (const field of COMPONENT_STACK_FIELDS) {
         const componentStack = asString(event.data[field]);
-        if (componentStack === undefined)
+        if (componentStack === undefined) {
             continue;
+        }
         const componentSource = sourceFromStack(componentStack);
-        if (componentSource !== undefined)
+        if (componentSource !== undefined) {
             return componentSource;
+        }
     }
     // The ordinary error stack can also identify a component better than ErrorEvent.filename (for
     // example, a bundle or click-handler frame), so try app frames before the structured fallback.
     const stack = asString(event.data['stack']);
     if (stack !== undefined) {
         const stackSource = sourceFromStack(stack);
-        if (stackSource !== undefined)
+        if (stackSource !== undefined) {
             return stackSource;
+        }
     }
     const directFile = asString(event.data['source']);
     const directLine = asNumber(event.data['line']);
-    if (directFile === undefined || directLine === undefined || directLine <= 0)
+    if (directFile === undefined || directLine === undefined || directLine <= 0) {
         return undefined;
+    }
     const file = sourceFile(directFile);
     return file === undefined || isFrameworkSource(file)
         ? undefined
         : `${file}:${String(directLine)}`;
 }
-/**
- * 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);
-}
 /**
  * How many interactive controls exist now that did not exist when the crawl enumerated.
  *
@@ -202,8 +186,9 @@ async function revealedItems(session, opts, before) {
         mode: 'interactive',
         ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
     });
-    if (!snap.ok)
+    if (!snap.ok) {
         return [];
+    }
     const tree = (snap.result ?? {}).tree ?? '';
     const known = new Set(before.map((i) => (i.ref !== '' ? i.ref : i.desc)));
     return parseInteractive(tree).filter((i) => !known.has(i.ref !== '' ? i.ref : i.desc));
@@ -237,8 +222,9 @@ async function stillSilent(session, item, settleMs, confirm, sleep) {
         });
         await sleep(settleMs);
         // A control that has GONE (the first click removed it) is not a dead control — it did something.
-        if (!again.ok || false === asRecord(again.result)['dispatched'])
+        if (!again.ok || false === asRecord(again.result)['dispatched']) {
             return false;
+        }
         return !session.eventsSince(since).some(isActivity);
     }
     catch {
@@ -277,18 +263,24 @@ export async function crawl(session, opts, sleep) {
         // so one call finished a deletion nobody authorized the second half of.
         const confirm = 0 === round && true === opts.confirmDangerous;
         for (const item of frontier) {
-            if (stepsRun >= maxSteps)
+            if (stepsRun >= maxSteps) {
                 break;
+            }
             // Dedupe by ref (the unique element), not by label — two "Delete"/"Edit" controls share a desc
             // but are different controls; collapsing them by label under-covers list/table UIs.
             const dedupeKey = item.ref !== '' ? item.ref : item.desc;
-            if (seen.has(dedupeKey))
-                continue; // don't re-click the same control
+            if (seen.has(dedupeKey)) {
+                continue;
+            } // don't re-click the same control
             seen.add(dedupeKey);
             if (ENDS_SESSION.test(item.desc)) {
                 notJudged.push({ ref: item.ref, desc: item.desc, reason: ENDS_SESSION_NOT_PRESSED });
                 continue;
             }
+            if (!confirm && !HAS_TEXT.test(item.desc)) {
+                notJudged.push({ ref: item.ref, desc: item.desc, reason: NO_ACCESSIBLE_NAME_NOT_PRESSED });
+                continue;
+            }
             stepsRun += 1;
             visited.push(item.desc);
             const since = session.elapsed();
@@ -321,8 +313,9 @@ export async function crawl(session, opts, sleep) {
                 });
             }
             catch (err) {
-                if (!isSessionReplacedError(err))
+                if (!isSessionReplacedError(err)) {
                     throw err;
+                }
                 navigatedAway = true;
             }
             finally {
@@ -433,11 +426,13 @@ export async function crawl(session, opts, sleep) {
                 }
             }
         }
-        if (coverageCapped || stepsRun >= maxSteps || REVEAL_ROUNDS <= round)
+        if (coverageCapped || stepsRun >= maxSteps || REVEAL_ROUNDS <= round) {
             break;
+        }
         const next = await revealedItems(session, opts, found);
-        if (0 === next.length)
+        if (0 === next.length) {
             break;
+        }
         found.push(...next);
         frontier = next;
     }
@@ -450,7 +445,7 @@ export async function crawl(session, opts, sleep) {
     // one would only muddy it.
     const revealed = coverageCapped ? 0 : (await revealedItems(session, opts, found)).length;
     // Left alone on purpose, so not a step the budget ran out before.
-    const leftAlone = notJudged.filter((n) => ENDS_SESSION_NOT_PRESSED === n.reason).length;
+    const leftAlone = notJudged.filter((n) => ENDS_SESSION_NOT_PRESSED === n.reason || NO_ACCESSIBLE_NAME_NOT_PRESSED === n.reason).length;
     return {
         interactiveFound: found.length,
         stepsRun,
@@ -480,3 +475,4 @@ export async function crawl(session, opts, sleep) {
         })(),
     };
 }
+export { legitimatelyInert };

package/dist/features/exhaust/app-coverage.d.ts

@@ -5,7 +5,7 @@
 import type { ReticleEvent } from '@reticlehq/core';
 import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
 import { type RawScriptCoverage } from './code-coverage.js';
-import { type LevelReport } from './ledger.js';
+import { type BehaviourFinding, type HolesReport, type LevelReport } from './ledger.js';
 export interface AppCoverageReport {
     levels: LevelReport[];
     /** Writes whose failure path was driven and the app claimed success anyway. Findings, not gaps. */
@@ -16,6 +16,10 @@ export interface AppCoverageReport {
         was: number;
         now: number;
     }[];
+    /** Every route, control, edge case, write, function and component never reached, by name. */
+    holes: HolesReport;
+    /** Behaviour faults the explorer found, one copy each. Absent when there are none. */
+    findings?: BehaviourFinding[];
     note?: string;
 }
 export declare function foldAppCoverage(input: {

package/dist/features/exhaust/app-coverage.js

@@ -3,7 +3,7 @@
  * stands, level by level.
  */
 import { emptyCodeCoverage, foldCodeCoverage } from './code-coverage.js';
-import { LedgerStore, levelsOf, regressions } from './ledger.js';
+import { holesOf, LedgerStore, levelsOf, regressions, } from './ledger.js';
 import { sessionDelta } from './session-fold.js';
 const NO_CODE_NOTE = 'The `executed` level is unmeasured here: code coverage needs a browser Reticle drives (`reticle drive`, or RETICLE_CDP_URL), and collection starts at the first coverage request, so drive and ask again. The other levels are real.';
 export async function foldAppCoverage(input) {
@@ -26,6 +26,8 @@ export async function foldAppCoverage(input) {
         levels: levelsOf(ledger),
         unhandledWrites: ledger.writes.unhandled,
         regressed: regressions(ledger),
+        holes: holesOf(ledger),
+        ...(ledger.findings.length > 0 ? { findings: ledger.findings } : {}),
         ...(take === undefined && 0 === Object.keys(ledger.code).length ? { note: NO_CODE_NOTE } : {}),
     };
 }

package/dist/features/exhaust/code-coverage.js

@@ -22,8 +22,9 @@ export function appFileOf(url) {
     catch {
         return undefined;
     }
-    if (NOT_APP.test(path) || !SOURCE_FILE.test(path))
+    if (NOT_APP.test(path) || !SOURCE_FILE.test(path)) {
         return undefined;
+    }
     return path.replace(/^\/+/, '');
 }
 export function emptyCodeCoverage() {
@@ -37,17 +38,20 @@ export function foldCodeCoverage(into, take) {
     const out = { ...into };
     for (const script of take) {
         const file = appFileOf(script.url);
-        if (file === undefined)
+        if (file === undefined) {
             continue;
+        }
         const fns = { ...(out[file] ?? {}) };
         for (const f of script.functions) {
             const first = f.ranges[0];
-            if (first === undefined)
+            if (first === undefined) {
                 continue;
+            }
             // The module's own top-level body is reported as an anonymous function starting at 0. It
             // always runs when the file loads, so counting it would inflate every file by one.
-            if ('' === f.functionName && 0 === first.startOffset)
+            if ('' === f.functionName && 0 === first.startOffset) {
                 continue;
+            }
             const key = `${f.functionName}@${String(first.startOffset)}`;
             const ran = first.count > 0 || true === fns[key]?.executed;
             fns[key] = { name: '' === f.functionName ? '(anonymous)' : f.functionName, executed: ran };

package/dist/features/exhaust/edge-cases.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Edge cases for the explorer to drive: the inputs and the interaction orders where behavioural
+ * bugs live.
+ *
+ * The explorer types one ordinary value into each field and activates each control once, in the
+ * order the page lists them. That proves the happy path and nothing else. A form that accepts
+ * "   " as a name, keeps 11 in a field whose maximum is 10, or creates two orders on a double click
+ * fails on a value or an order nobody tried. This module lists those values and sequences.
+ *
+ * Pure and deterministic: the same field, control and clock give the same list in the same order.
+ * Every list is bounded, and the most telling items come first, so a small budget still tries them.
+ * A sequence says nothing about what a correct result is; `invariants.ts` judges the pages it leaves.
+ */
+import type { Step } from './explorer.js';
+/** What a field takes, as far as its type, input mode, role and name say. */
+export declare const FieldKind: {
+    readonly TEXT: "text";
+    readonly NUMBER: "number";
+    readonly EMAIL: "email";
+    readonly DATE: "date";
+    readonly TIME: "time";
+    readonly URL: "url";
+    readonly TEL: "tel";
+};
+export type FieldKind = (typeof FieldKind)[keyof typeof FieldKind];
+/** Why a value is an edge case. The report shows this beside the value. */
+export declare const EdgeLabel: {
+    readonly EMPTY: "empty";
+    readonly EMPTY_REQUIRED: "empty in a required field";
+    readonly WHITESPACE: "whitespace only";
+    readonly PADDED: "leading and trailing spaces";
+    readonly OVER_MAX_LENGTH: "one character over maxlength";
+    readonly UNDER_MIN_LENGTH: "one character under minlength";
+    readonly LONG_TEXT: "long text, no maxlength set";
+    readonly UNICODE: "emoji and non-Latin script";
+    readonly RTL: "right-to-left text";
+    readonly MARKUP: "markup characters";
+    readonly BREAKS_PATTERN: "does not match the pattern";
+    readonly DUPLICATE: "duplicate of a value the app already holds";
+    readonly ZERO: "zero";
+    readonly NEGATIVE: "negative number";
+    readonly BELOW_MIN: "one below min";
+    readonly ABOVE_MAX: "one above max";
+    readonly VERY_LARGE: "very large number";
+    readonly DECIMAL: "decimal number";
+    readonly WRONG_FORMAT: "wrong format for the field type";
+    readonly PAST_DATE: "date in the past";
+    readonly FUTURE_DATE: "date far in the future";
+    readonly IMPOSSIBLE_DATE: "date that does not exist";
+    readonly MIDNIGHT: "midnight";
+    readonly IMPOSSIBLE_TIME: "time that does not exist";
+};
+export type EdgeLabel = (typeof EdgeLabel)[keyof typeof EdgeLabel];
+/** One field, with what the snapshot or the DOM gives about it. Every attribute is optional. */
+export interface FieldSpec {
+    role: string;
+    name?: string;
+    type?: string;
+    inputMode?: string;
+    value?: string;
+    min?: string;
+    max?: string;
+    maxLength?: number;
+    minLength?: number;
+    pattern?: string;
+    required?: boolean;
+    /** Values the app already holds for this field, such as the rows of a list. */
+    existing?: readonly string[];
+}
+export interface EdgeValue {
+    value: string;
+    label: EdgeLabel;
+}
+/** The default bound. A field gets at most this many values. */
+export declare const MAX_EDGE_VALUES = 16;
+export declare function fieldKindOf(spec: Pick<FieldSpec, 'role' | 'type' | 'inputMode' | 'name'>): FieldKind;
+/**
+ * The edge-case values for a field, most telling first, with no value twice, at most `max`.
+ * `now` is the injected clock: past and future dates are relative to it.
+ */
+export declare function edgeInputs(spec: FieldSpec, opts: {
+    now: () => number;
+    max?: number;
+}): EdgeValue[];
+/** The actions a sequence uses. `click` and `fill` are the explorer's own; the rest are new. */
+export declare const EdgeAction: {
+    readonly CLICK: "click";
+    readonly FILL: "fill";
+    /** The browser's back. */
+    readonly BACK: "back";
+    /** A full reload of the current page. */
+    readonly RELOAD: "reload";
+    /** Wait until the page settles. Two steps with no settle between them run back to back. */
+    readonly SETTLE: "settle";
+};
+export type EdgeAction = (typeof EdgeAction)[keyof typeof EdgeAction];
+export type EdgeStep = Step | {
+    action: typeof EdgeAction.BACK | typeof EdgeAction.RELOAD | typeof EdgeAction.SETTLE;
+};
+export declare const EdgeInteraction: {
+    readonly DOUBLE_ACTIVATION: "double-activation";
+    readonly RAPID_REPEAT: "rapid-repeat";
+    readonly ACT_THEN_BACK: "act-then-back";
+    readonly ACT_THEN_RELOAD: "act-then-reload";
+    readonly SUBMIT_TWICE: "submit-twice";
+    readonly SUBMIT_BEFORE_FILL: "submit-before-fill";
+    readonly OUT_OF_ORDER: "out-of-order";
+};
+export type EdgeInteraction = (typeof EdgeInteraction)[keyof typeof EdgeInteraction];
+export interface EdgeSequence {
+    kind: EdgeInteraction;
+    /** The control the sequence is about. */
+    target: string;
+    steps: EdgeStep[];
+}
+/** How many activations a rapid repeat sends back to back. */
+export declare const RAPID_REPEAT = 5;
+/** The default bound on sequences for one control. */
+export declare const MAX_EDGE_SEQUENCES = 8;
+export declare function looksLikeSubmit(control: string): boolean;
+/** A step in words, for the action sequence on a finding. */
+export declare function describeStep(step: EdgeStep): string;
+/**
+ * The edge sequences for `control`. `order` is the page's controls in document order; `fills` are
+ * the steps that fill the form the control belongs to, when it has one.
+ */
+export declare function edgeInteractions(input: {
+    control: string;
+    order: readonly string[];
+    fills?: readonly Step[];
+}, opts?: {
+    max?: number;
+}): EdgeSequence[];