@specific.dev/spectest 0.64.0 → 0.67.0

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { McpHttpError, McpRpcError, McpAuthDeniedError, type Mcp, type McpOption
 import type { Mcp, McpOptions } from "./mcp.js";
 export type { Locator, GetByRoleOptions, GetByTextOptions, FilterOptions, ClickOptions, BoundingBox, FilePayload, InputFiles, } from "./locator.js";
 import type { Locator } from "./locator.js";
+import { type TextMatchOptions } from "./text-match.js";
 export type { UrlPattern } from "./url-match.js";
 import type { UrlPattern } from "./url-match.js";
 export type { Mobile, MobileApp } from "./mobile.js";
@@ -34,7 +35,8 @@ export type { InterceptHandler, InterceptNext, InterceptedRequest };
  */
 export interface Interception {
     hostname: string;
-    /** The normalised mount path (`"/"` when none was given). */
+    /** The normalised mount path parsed off the target (`"/"` when the
+     *  target was a bare hostname). */
     path: string;
     /** How many requests the interceptor has seen. Provenance-wrapped, so an
      *  `expect(outage.calls)` nests under the intercept step; `.unwrap()` for
@@ -381,12 +383,23 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      * make your **own** backend misbehave for one test: force a 500 from an
      * API route, add latency, fail twice then pass, or just count calls.
      *
+     * `target` is the hostname, optionally with a mount path:
+     * `"app.test"` claims every request to that host, `"app.test/api/sync"`
+     * claims that path and everything below it (like `app.use(path, fn)`).
+     *
+     * `description` is what the environment now **does**, in the present
+     * tense — it is the step's whole title in the timeline and in the CLI's
+     * failure detail, so it is what tells a reader why the page under test
+     * went to its error state. Write the effect, not the act of intercepting
+     * (the step is already labelled INTERCEPT) and not the test's goal:
+     * `"the sync endpoint returns 503"`, not `"intercept sync"`, `"mock the
+     * API"` or `"test error handling"`. The handler's own source is shown
+     * under it, so the description carries the intent, never the mechanism.
+     *
      * Hono/Koa-style middleware: `(req, next)` where `next()` returns the real upstream's
      * response (a proxied service, or a fake). Return a `Response` to answer
      * yourself, `next()` to pass through, or change what `next()` returned.
-     * An optional mount `path` limits it to that path and everything below
-     * (`"/functions/v1/sync"`), like `app.use(path, fn)`. Interceptors run in
-     * registration order.
+     * Interceptors run in registration order.
      *
      * Only traffic that reaches the daemon can be intercepted: the browser,
      * `ctx.fetch`, and any container that calls the hostname — so the service
@@ -400,16 +413,18 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      * `remove()`. Every request it sees is recorded under the intercept step.
      *
      * ```ts
-     * const outage = ctx.intercept("api.test", "/functions/v1/sync", () =>
-     *   new Response("boom", { status: 500 }));
+     * const outage = ctx.intercept(
+     *   "api.test/functions/v1/sync",
+     *   "the sync function returns 500",
+     *   () => new Response("boom", { status: 500 }),
+     * );
      * await page.getByRole("button", { name: "Sync" }).click();
      * await expect(page.getByText("Retry")).toBeVisible();
      * expect(outage.calls).toBe(1);
      * outage.remove();                           // the retry now reaches the real function
      * ```
      */
-    intercept(hostname: string, handler: InterceptHandler): Interception;
-    intercept(hostname: string, path: string, handler: InterceptHandler): Interception;
+    intercept(target: string, description: string, handler: InterceptHandler): Interception;
     /**
      * Mint a leaf certificate from the in-VM root CA and return the PEMs.
      *
@@ -1672,6 +1687,14 @@ interface Matchers {
 export interface Expectation extends Matchers {
     not: Matchers;
 }
+/** Options for the text matchers — playwright's set, same names, same
+ *  meanings. */
+export interface TextMatcherOptions extends TextMatchOptions {
+    timeout?: number;
+    /** Read `innerText` (what the page renders — hidden elements dropped,
+     *  `text-transform` applied) instead of `textContent`. */
+    useInnerText?: boolean;
+}
 /**
  * Auto-retrying web-first assertions for a {@link Locator} — Playwright's
  * `expect(locator)` matchers. Each polls the element until it passes or a
@@ -1687,14 +1710,27 @@ export interface LocatorMatchers {
     toBeHidden(opts?: {
         timeout?: number;
     }): Promise<void>;
-    /** The element's (trimmed) text equals `expected` (or matches a RegExp). */
-    toHaveText(expected: string | RegExp, opts?: {
-        timeout?: number;
-    }): Promise<void>;
-    /** The element's text contains `expected`. */
-    toContainText(expected: string, opts?: {
-        timeout?: number;
-    }): Promise<void>;
+    /**
+     * The element's text equals `expected`, or matches it when it is a RegExp.
+     *
+     * **Whitespace is normalized on both sides**, exactly as playwright does
+     * it: the text is trimmed and every run of whitespace becomes one space.
+     * So a typed space matches the no-break space (U+00A0) that
+     * `Intl.NumberFormat` puts between thousands, and a value wrapped across
+     * two lines in the markup matches the one-line string you wrote.
+     *
+     * Pass an **array** to assert over every element the locator matches, in
+     * order; the counts must then agree.
+     */
+    toHaveText(expected: string | RegExp | Array<string | RegExp>, opts?: TextMatcherOptions): Promise<void>;
+    /**
+     * The element's text contains `expected` — a substring, or a RegExp tested
+     * against the text. Whitespace is normalized as in {@link toHaveText}.
+     *
+     * An **array** asserts that the matched elements contain these texts in
+     * order; unlike `toHaveText` extra elements between them are allowed.
+     */
+    toContainText(expected: string | RegExp | Array<string | RegExp>, opts?: TextMatcherOptions): Promise<void>;
     /** The input's value equals `expected` (or matches a RegExp). */
     toHaveValue(expected: string | RegExp, opts?: {
         timeout?: number;

package/dist/index.js

@@ -39,7 +39,8 @@ export { S3Client } from "./s3.js";
 // own browser. See `mcp.ts`.
 export { McpHttpError, McpRpcError, McpAuthDeniedError, } from "./mcp.js";
 import { isLocator, getLocatorProbe, isBrowserSession, getBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, } from "./locator.js";
-import { formatWaited, locatorFailureMessage } from "./locator-errors.js";
+import { classifyLocatorFailure, formatWaited, locatorFailureMessage, } from "./locator-errors.js";
+import { containsText, containsTextArray, escapeInvisible, matchesText, matchesTextArray, textDifferenceNote, } from "./text-match.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
 import { applyCoverageAdapters, validateCoverage } from "./coverage.js";
 import { resolveExistingProjectPath } from "./project-files.js";
@@ -674,14 +675,33 @@ function buildLocatorMatchers(loc, negated, message) {
         // matches a hidden element fail identically — so the count is read once,
         // at failure time only. `toHaveCount` is left alone: "expected count 2,
         // got 0" already says it, and better.
+        //
+        // Either way the message ends with the near-miss block — what the page
+        // holds that is close to what was asked for (see locator-hints.ts) — so
+        // the author does not have to run again to find out.
+        const nearMiss = async () => {
+            try {
+                return await probe.nearMiss();
+            }
+            catch {
+                return "";
+            }
+        };
         const elementFailure = async (err) => {
-            if (err !== undefined)
-                return locatorFailureMessage(probe.label, err);
+            if (err !== undefined) {
+                const failure = classifyLocatorFailure(probe.label, err);
+                if (!failure)
+                    return undefined;
+                return failure.kind === "no-match"
+                    ? failure.message + (await nearMiss())
+                    : failure.message;
+            }
             if (expectsGone || matcher === "toHaveCount")
                 return undefined;
             try {
                 if ((await probe.count()) === 0) {
-                    return `No element matches ${probe.label} (waited ${formatWaited(budget)})`;
+                    return (`No element matches ${probe.label} (waited ${formatWaited(budget)})` +
+                        (await nearMiss()));
                 }
             }
             catch {
@@ -754,7 +774,22 @@ function buildLocatorMatchers(loc, negated, message) {
         }
     };
     const not = negated ? " not" : "";
-    const matchesText = (v, expected) => expected instanceof RegExp ? expected.test(v) : v === expected;
+    // The element's text, read the way the caller asked for it. `useInnerText`
+    // is playwright's option and means the same here: what the page renders,
+    // rather than every character in the subtree.
+    const readText = async (opts) => opts?.useInnerText
+        ? await probe.innerText(opts.timeout)
+        : ((await probe.textContent(opts?.timeout)) ?? "");
+    const readTexts = async (opts) => opts?.useInnerText ? await probe.allInnerTexts() : await probe.allTextContents();
+    const isArrayExpectation = (v) => Array.isArray(v);
+    /** Expected values render as themselves; a RegExp renders as its source. */
+    const fmtExpected = (v) => v instanceof RegExp
+        ? String(v)
+        : Array.isArray(v)
+            ? `[${v.map(fmtExpected).join(", ")}]`
+            : fmt(v);
+    /** What goes on the assertion event: a RegExp cannot be serialized. */
+    const expectedValue = (v) => (v instanceof RegExp ? String(v) : Array.isArray(v) ? v.map(expectedValue) : v);
     return {
         toBeVisible: (opts) => run("toBeVisible", opts?.timeout, async () => {
             const v = await probe.isVisible();
@@ -765,17 +800,34 @@ function buildLocatorMatchers(loc, negated, message) {
             return { satisfied: !v, actual: v };
         }, () => `expected ${probe.label}${not} to be hidden`),
         toHaveText: (expected, opts) => run("toHaveText", opts?.timeout, async () => {
-            const t = (await probe.textContent(opts?.timeout)) ?? "";
-            return { satisfied: matchesText(t.trim(), expected), actual: t };
-        }, (a) => `expected ${probe.label}${not} to have text ${fmt(expected)}, got ${fmt(a)}`, expected instanceof RegExp ? String(expected) : expected),
+            if (isArrayExpectation(expected)) {
+                const texts = await readTexts(opts);
+                return { satisfied: matchesTextArray(texts, expected, opts), actual: texts };
+            }
+            const t = await readText(opts);
+            return { satisfied: matchesText(t, expected, opts), actual: t };
+        }, (a) => `expected ${probe.label}${not} to have text ${fmtExpected(expected)}, got ${fmt(a)}` +
+            textDifferenceNote(a, expected, "equal"), expectedValue(expected)),
         toContainText: (expected, opts) => run("toContainText", opts?.timeout, async () => {
-            const t = (await probe.textContent(opts?.timeout)) ?? "";
-            return { satisfied: t.includes(expected), actual: t };
-        }, (a) => `expected ${probe.label}${not} to contain text ${fmt(expected)}, got ${fmt(a)}`, expected),
+            if (isArrayExpectation(expected)) {
+                const texts = await readTexts(opts);
+                return { satisfied: containsTextArray(texts, expected, opts), actual: texts };
+            }
+            const t = await readText(opts);
+            return { satisfied: containsText(t, expected, opts), actual: t };
+        }, (a) => `expected ${probe.label}${not} to contain text ${fmtExpected(expected)}, got ${fmt(a)}` +
+            textDifferenceNote(a, expected, "contains"), expectedValue(expected)),
+        // Deliberately NOT whitespace-normalized: an input's value is data the
+        // user typed or the app set, not rendered text, and playwright compares
+        // it exactly for the same reason. When that exactness is what failed,
+        // `textDifferenceNote` says so instead of leaving two identical-looking
+        // strings on screen.
         toHaveValue: (expected, opts) => run("toHaveValue", opts?.timeout, async () => {
             const v = await probe.inputValue(opts?.timeout);
-            return { satisfied: matchesText(v, expected), actual: v };
-        }, (a) => `expected ${probe.label}${not} to have value ${fmt(expected)}, got ${fmt(a)}`, expected instanceof RegExp ? String(expected) : expected),
+            const satisfied = expected instanceof RegExp ? expected.test(v) : v === expected;
+            return { satisfied, actual: v };
+        }, (a) => `expected ${probe.label}${not} to have value ${fmtExpected(expected)}, got ${fmt(a)}` +
+            textDifferenceNote(a, expected, "equal"), expectedValue(expected)),
         toHaveCount: (expected, opts) => run("toHaveCount", opts?.timeout, async () => {
             const c = await probe.count();
             return { satisfied: c === expected, actual: c };
@@ -949,7 +1001,8 @@ function buildCore(actual, tag, negated, message, pendingError) {
     return {
         toBe(expected) {
             const exp = readRaw(expected);
-            run("toBe", Object.is(actual, exp), `expected ${fmt(actual)}${negated ? " not" : ""} to be ${fmt(exp)}`, exp);
+            run("toBe", Object.is(actual, exp), `expected ${fmt(actual)}${negated ? " not" : ""} to be ${fmt(exp)}` +
+                textDifferenceNote(actual, exp, "equal"), exp);
         },
         toEqual(expected) {
             const exp = readRaw(expected);
@@ -960,7 +1013,8 @@ function buildCore(actual, tag, negated, message, pendingError) {
             catch {
                 equal = false;
             }
-            run("toEqual", equal, `expected ${fmt(actual)}${negated ? " not" : ""} to deep-equal ${fmt(exp)}`, exp);
+            run("toEqual", equal, `expected ${fmt(actual)}${negated ? " not" : ""} to deep-equal ${fmt(exp)}` +
+                textDifferenceNote(actual, exp, "equal"), exp);
         },
         toBeTruthy() {
             run("toBeTruthy", !!actual, `expected ${fmt(actual)}${negated ? " not" : ""} to be truthy`);
@@ -997,7 +1051,8 @@ function buildCore(actual, tag, negated, message, pendingError) {
                     }
                 });
             }
-            run("toContain", contained, `expected ${fmt(actual)}${negated ? " not" : ""} to contain ${fmt(exp)}`, exp);
+            run("toContain", contained, `expected ${fmt(actual)}${negated ? " not" : ""} to contain ${fmt(exp)}` +
+                textDifferenceNote(actual, exp, "contains"), exp);
         },
         toMatch(re) {
             run("toMatch", typeof actual === "string" && re.test(actual), `expected ${fmt(actual)}${negated ? " not" : ""} to match ${re}`, String(re));
@@ -1032,8 +1087,12 @@ function buildCore(actual, tag, negated, message, pendingError) {
     };
 }
 function fmt(v) {
+    // A string is escaped down to its invisible characters, so two values that
+    // print the same on screen do not print the same in a failure. Without it a
+    // no-break space and a space are the same three characters wide, and the
+    // message reads "expected "15 000 kr", got "15 000 kr"".
     if (typeof v === "string")
-        return JSON.stringify(v);
+        return escapeInvisible(JSON.stringify(v));
     if (typeof v === "bigint")
         return `${v}n`;
     if (v === undefined)

package/dist/locator-errors.d.ts

@@ -1,21 +1,30 @@
 /** A wait's duration, in the units a reader thinks in: "800ms", "5s", "1.5s". */
 export declare function formatWaited(ms: number): string;
+/** How a locator failed. `no-match` is the only kind worth asking the page
+ *  about (see locator-hints.ts) — for every other kind the element was found
+ *  and near misses would be noise. */
+export type LocatorFailureKind = "no-match" | "state" | "strict";
+export interface LocatorFailure {
+    message: string;
+    kind: LocatorFailureKind;
+}
 /**
- * The sentence to fail with, or `undefined` when `err` is not a locator
- * timeout we understand (in which case the caller must leave it alone).
+ * What to fail with, or `undefined` when `err` is not a locator failure we
+ * understand (in which case the caller must leave it alone).
  *
  * `label` is the locator's human chain label, the same string the timeline
  * step shows.
  */
+export declare function classifyLocatorFailure(label: string, err: unknown): LocatorFailure | undefined;
+/** The sentence alone. See {@link classifyLocatorFailure}. */
 export declare function locatorFailureMessage(label: string, err: unknown): string | undefined;
 /**
- * Replace a locator timeout's message in place and hand the error back, so the
- * caller can `throw` it unchanged in every other respect.
+ * The rewrite above, plus the near-miss block for the one failure that can
+ * carry one — a locator that matched nothing.
  *
- * The error is mutated rather than wrapped: its stack holds the frames of the
- * author's own call, which a fresh Error would lose. The stack string embeds
- * the old message (it is built at construction), so that copy is rewritten
- * too — otherwise the CLI's failure block would print the friendly message and
- * then the timeout wall right under it.
+ * `hints` is only called in that case, so a page query is never made for a
+ * failure it could not explain (a disabled element, a covered one, an
+ * ambiguous match). It is expected to be best-effort itself; anything it
+ * throws leaves the plain sentence standing.
  */
-export declare function rewriteLocatorError(err: unknown, label: string): unknown;
+export declare function rewriteLocatorErrorWithHints(err: unknown, label: string, hints: () => Promise<string>): Promise<unknown>;

package/dist/locator-errors.js

@@ -8,10 +8,15 @@
 // as an infrastructure problem and says nothing about the page.
 //
 // This module turns those into one sentence that names the element and what
-// was wrong with it. Anything it does not recognise (a strict-mode violation,
-// a closed page, an assertion of ours) is passed through untouched — the rule
-// is that a message is only ever replaced when we have something better to
-// say.
+// was wrong with it. A strict-mode violation — the opposite failure, where the
+// locator matched too much — is rewritten too, keeping playwright's own list
+// of matches, which is the useful half of it. Anything else (a closed page, an
+// assertion of ours) is passed through untouched: the rule is that a message is
+// only ever replaced when we have something better to say.
+//
+// `classifyLocatorFailure` also says WHICH failure it was, because only one of
+// them — a locator that matched nothing — can be explained further by asking
+// the page what it holds (see locator-hints.ts).
 //
 // The call log is read from the error's own `log` array (playwright attaches
 // it) and falls back to parsing the message, since only the message survives
@@ -80,38 +85,72 @@ function actionabilityReason(log) {
     }
     return undefined;
 }
+/** Playwright's strict-mode violation: the locator matched more than one
+ *  element and refused to act. It is an ordinary `Error`, not a
+ *  `TimeoutError`, and its message already lists the matches — which is the
+ *  useful half, so it is kept and only the wall of text around it is cut. */
+function parseStrictViolation(err, label) {
+    const e = err;
+    if (!e || typeof e.message !== "string")
+        return undefined;
+    if (!e.message.includes("strict mode violation"))
+        return undefined;
+    const m = /resolved to (\d+) elements/.exec(e.message);
+    if (!m)
+        return undefined;
+    const matches = e.message
+        .split("\n")
+        .filter((l) => /^\s*\d+\)\s/.test(l))
+        .slice(0, 3)
+        .map((l) => `  - ${l.trim().replace(/^\d+\)\s*/, "")}`);
+    const head = `${label} matches ${m[1]} elements, so it is ambiguous` +
+        " — narrow it with .first(), .nth(i), .filter({ hasText }) or a more specific query";
+    return {
+        kind: "strict",
+        message: matches.length ? `${head}:\n${matches.join("\n")}` : head,
+    };
+}
 /**
- * The sentence to fail with, or `undefined` when `err` is not a locator
- * timeout we understand (in which case the caller must leave it alone).
+ * What to fail with, or `undefined` when `err` is not a locator failure we
+ * understand (in which case the caller must leave it alone).
  *
  * `label` is the locator's human chain label, the same string the timeline
  * step shows.
  */
-export function locatorFailureMessage(label, err) {
+export function classifyLocatorFailure(label, err) {
+    const strict = parseStrictViolation(err, label);
+    if (strict)
+        return strict;
     const detail = parseTimeout(err);
     if (!detail)
         return undefined;
     const waited = `(waited ${formatWaited(detail.timeoutMs)})`;
-    if (!resolved(detail.log))
-        return `No element matches ${label} ${waited}`;
+    if (!resolved(detail.log)) {
+        return { kind: "no-match", message: `No element matches ${label} ${waited}` };
+    }
     // It matched, so the failure is about the element's state.
+    const state = (message) => ({ kind: "state", message });
     switch (waitedForState(detail.log)) {
         case "hidden":
-            return `Element ${label} is still visible ${waited}`;
+            return state(`Element ${label} is still visible ${waited}`);
         case "detached":
-            return `Element ${label} is still attached to the page ${waited}`;
+            return state(`Element ${label} is still attached to the page ${waited}`);
         case "visible":
-            return `Element ${label} is not visible ${waited}`;
+            return state(`Element ${label} is not visible ${waited}`);
         default:
             break;
     }
     const reason = actionabilityReason(detail.log);
-    return reason
+    return state(reason
         ? `Element ${label} ${reason} ${waited}`
-        : `Element ${label} never became ready for this action ${waited}`;
+        : `Element ${label} never became ready for this action ${waited}`);
+}
+/** The sentence alone. See {@link classifyLocatorFailure}. */
+export function locatorFailureMessage(label, err) {
+    return classifyLocatorFailure(label, err)?.message;
 }
 /**
- * Replace a locator timeout's message in place and hand the error back, so the
+ * Replace a locator failure's message in place and hand the error back, so the
  * caller can `throw` it unchanged in every other respect.
  *
  * The error is mutated rather than wrapped: its stack holds the frames of the
@@ -120,11 +159,8 @@ export function locatorFailureMessage(label, err) {
  * too — otherwise the CLI's failure block would print the friendly message and
  * then the timeout wall right under it.
  */
-export function rewriteLocatorError(err, label) {
-    const message = locatorFailureMessage(label, err);
-    if (message === undefined)
-        return err;
-    const e = err;
+/** Put `message` on `err`, in the message and in the stack's copy of it. */
+function setErrorMessage(e, message) {
     const old = e.message;
     if (typeof e.stack === "string") {
         for (const [header, replacement] of [
@@ -140,3 +176,27 @@ export function rewriteLocatorError(err, label) {
     e.message = message;
     return e;
 }
+/**
+ * The rewrite above, plus the near-miss block for the one failure that can
+ * carry one — a locator that matched nothing.
+ *
+ * `hints` is only called in that case, so a page query is never made for a
+ * failure it could not explain (a disabled element, a covered one, an
+ * ambiguous match). It is expected to be best-effort itself; anything it
+ * throws leaves the plain sentence standing.
+ */
+export async function rewriteLocatorErrorWithHints(err, label, hints) {
+    const failure = classifyLocatorFailure(label, err);
+    if (!failure)
+        return err;
+    let message = failure.message;
+    if (failure.kind === "no-match") {
+        try {
+            message += await hints();
+        }
+        catch {
+            /* A diagnostic must never replace the failure it explains. */
+        }
+    }
+    return setErrorMessage(err, message);
+}

package/dist/locator-hints.d.ts

@@ -0,0 +1,96 @@
+import type { Page } from "playwright-core";
+/** What the author asked for — the last selecting step of a failed chain. */
+export interface HintTarget {
+    kind: "role" | "text" | "label" | "placeholder" | "altText" | "title" | "testId" | "other";
+    /** The ARIA role, for `kind: "role"`. */
+    role?: string;
+    /** The string the author asked for. Absent for a RegExp query, which we
+     *  make no suggestions from — a near-miss on a pattern is not a near-miss. */
+    query?: string;
+}
+/** One role/name pair from the page's accessibility tree. */
+export interface AriaCandidate {
+    role: string;
+    name: string;
+}
+/** An interactive element whose visible text is not its accessible name. */
+export interface NameMismatch {
+    tag: string;
+    text: string;
+    name: string;
+    /** The attribute the name came from: `aria-label`, `aria-labelledby`, … */
+    from: string;
+}
+/** What the DOM pass brings back. Every list is deduplicated and capped. */
+export interface DomFacts {
+    texts: string[];
+    testIds: string[];
+    placeholders: string[];
+    labels: string[];
+    titles: string[];
+    alts: string[];
+    mismatches: NameMismatch[];
+}
+export declare const EMPTY_DOM_FACTS: DomFacts;
+/** The locator a suggestion proposes, as data — so the ranking stays pure and
+ *  testable and only `nearMissHints` touches a page. */
+export type SuggestedLocator = {
+    m: "getByRole";
+    role: string;
+    name: string;
+} | {
+    m: "getByText";
+    text: string;
+} | {
+    m: "getByLabel";
+    text: string;
+} | {
+    m: "getByPlaceholder";
+    text: string;
+} | {
+    m: "getByAltText";
+    text: string;
+} | {
+    m: "getByTitle";
+    text: string;
+} | {
+    m: "getByTestId";
+    id: string;
+};
+export interface Suggestion {
+    /** What is on the page, in the reader's terms. */
+    fact: string;
+    /** The locator that selects it. */
+    locator: SuggestedLocator;
+    /** Higher is closer. Ranking only; never shown. */
+    score: number;
+}
+/**
+ * How close `candidate` is to what the author asked for, from 0 (unrelated)
+ * to 4 (the same string). Everything at or above `NEAR` is worth showing.
+ */
+export declare function closeness(query: string, candidate: string): number;
+/** Render one verified suggestion as the line the author reads. */
+export declare function suggestionLine(s: Suggestion, matches: number): string;
+/**
+ * Rank what the page holds against what the author asked for. Pure: the
+ * caller collects `aria`/`dom` and verifies the winners.
+ */
+export declare function buildSuggestions(target: HintTarget, aria: AriaCandidate[], dom: DomFacts): Suggestion[];
+/**
+ * Pull `- button "Save"` lines out of an ARIA snapshot.
+ *
+ * The snapshot is YAML, but only its leading token carries what we need, so
+ * this reads it line by line rather than pulling in a parser. A line we do not
+ * recognise is skipped — the worst case is one fewer suggestion.
+ */
+export declare function parseAriaSnapshot(yaml: string): AriaCandidate[];
+/**
+ * The lines to append to a "no element matches" failure — at most
+ * {@link MAX_SUGGESTIONS}, each verified against the live page, and empty
+ * whenever the page holds nothing close.
+ */
+export declare function nearMissHints(page: Page, target: HintTarget): Promise<string[]>;
+/** The block appended under a failure sentence, or `""` when there is
+ *  nothing to add. */
+export declare function formatHints(lines: string[]): string;