@itmetsam/samurai-framework 0.9.0 → 0.12.0

package/dist/locator/actionability.js

@@ -0,0 +1,104 @@
+import { BiDiError } from "../transport/bidi-error.js";
+import { ScriptError } from "../script/call-function.js";
+import { resolveTimeout } from "../config/timeouts.js";
+import { waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
+import { ActionTimeoutError } from "./action-timeout-error.js";
+import { isDocumentSwap } from "./document-swap.js";
+import { allPass, DETACHED_STATE, evaluateChecks, parseElementState, PROBE_ELEMENT, } from "./element-state.js";
+import { CALL_PROBE, HELPER_SANDBOX, HELPERS_MISSING, } from "./helper-realm.js";
+import { ATTACHED_ONLY } from "./page-scripts.js";
+/** Reads the element's actionability state: one search, one probe */
+export async function probeState(ctx, options) {
+    const el = await ctx.resolveOne();
+    if (!el)
+        return DETACHED_STATE;
+    try {
+        return parseElementState(await callProbe(ctx, el, options));
+    }
+    catch (err) {
+        // The document changed between the search and the probe
+        if ((err instanceof BiDiError && err.code === "no such node") ||
+            isDocumentSwap(err))
+            return DETACHED_STATE;
+        throw err;
+    }
+}
+async function callProbe(ctx, el, options) {
+    const args = [el, { ...options }];
+    if (!ctx.helpers)
+        return ctx.call(PROBE_ELEMENT, args);
+    await ctx.helpers.ensureInstalled();
+    let result = await ctx.call(CALL_PROBE, args, HELPER_SANDBOX);
+    if (result === HELPERS_MISSING) {
+        // A document got past the registration (e.g. created while it was being set up): install again once
+        await ctx.helpers.reinstall();
+        result = await ctx.call(CALL_PROBE, args, HELPER_SANDBOX);
+        if (result === HELPERS_MISSING) {
+            throw new ScriptError("the samurai helpers are missing in the page after reinstalling", "probeElement");
+        }
+    }
+    return result;
+}
+/**
+ * Probes until every required check passes and returns that state.
+ * Throws ActionTimeoutError describing the last probe on timeout.
+ */
+export async function waitForActionable(ctx, action, checks, probe, options) {
+    const timeout = await resolveTimeout(options?.timeout);
+    // Stability compares two probes; with timeout 0 there is only one
+    const required = options?.force
+        ? ATTACHED_ONLY
+        : timeout === 0
+            ? checks.filter((check) => check !== "stable")
+            : checks;
+    let lastChecks;
+    try {
+        return await waitUntil(() => probeState(ctx, probe), (current, previous) => {
+            lastChecks = evaluateChecks(required, current, previous);
+            return allPass(lastChecks);
+        }, { timeout });
+    }
+    catch (err) {
+        if (!(err instanceof WaitTimeoutError))
+            throw err;
+        const last = err.last;
+        throw new ActionTimeoutError({
+            action,
+            selector: ctx.selector,
+            timeout,
+            reason: !last
+                ? "unreadable"
+                : last.attached
+                    ? "not-actionable"
+                    : "not-attached",
+            checks: lastChecks,
+            coveredBy: lastChecks?.["hit target"] === "fail"
+                ? (last?.hitTarget ?? undefined)
+                : undefined,
+        });
+    }
+}
+/** Waits until the element reaches `state` (default "visible"); does not scroll */
+export async function waitForState(ctx, { state = "visible", timeout }) {
+    const resolved = await resolveTimeout(timeout);
+    const reached = {
+        attached: (current) => current.attached,
+        detached: (current) => !current.attached,
+        visible: (current) => current.attached && current.visible,
+        hidden: (current) => !current.attached || !current.visible,
+    };
+    try {
+        await waitUntil(() => probeState(ctx, { scroll: false, hitTest: false }), reached[state], { timeout: resolved });
+    }
+    catch (err) {
+        if (!(err instanceof WaitTimeoutError))
+            throw err;
+        throw new ActionTimeoutError({
+            action: "waitFor",
+            selector: ctx.selector,
+            timeout: resolved,
+            reason: err.last === undefined ? "unreadable" : "wrong-state",
+            state,
+        });
+    }
+}

package/dist/locator/chain-resolver.d.ts

@@ -0,0 +1,20 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
+import { ElementHandle } from "../script/element-handle.js";
+import type { Arg } from "../script/serialize.js";
+import { type Selector } from "./selector.js";
+/** Calls `fn` in the page; the locator turns a throwing function into a "Failed to locate element" error */
+export type CallInPage = <T>(fn: string, args: Arg[], sandbox?: string) => Promise<T>;
+/** Finds the elements a chain of selector steps matches: every step searches inside the previous step's matches */
+export declare class ChainResolver {
+    private readonly connector;
+    private readonly contextId;
+    private readonly call;
+    constructor(connector: BiDiConnector, contextId: BrowsingContext, call: CallInPage);
+    /** In document order; `max` limits the final result. Nothing is cached: the first match can change between polls */
+    resolveChain(chain: readonly Selector[], max?: number): Promise<ElementHandle[]>;
+    private locateStep;
+    private locateNatively;
+    /** Runs a page-side search `(starts, value, match, ignoreCase) => elements` */
+    private locateInPage;
+}

package/dist/locator/chain-resolver.js

@@ -0,0 +1,102 @@
+import { BiDiError } from "../transport/bidi-error.js";
+import { UnsupportedOperationError } from "../transport/unsupported.js";
+import { ElementHandle } from "../script/element-handle.js";
+import { isDocumentSwap } from "./document-swap.js";
+import { LABEL_LOCATE } from "./label-locator.js";
+import { InvalidSelectorError } from "./selector-errors.js";
+import { describeSelector, toBiDiLocator } from "./selector.js";
+import { TEXT_LOCATE } from "./text-locator.js";
+/** Locator types a connection's browser rejected, so they are not tried again on every poll */
+const unsupportedByConnector = new WeakMap();
+function unsupportedTypes(connector) {
+    let types = unsupportedByConnector.get(connector);
+    if (!types)
+        unsupportedByConnector.set(connector, (types = new Set()));
+    return types;
+}
+/** Finds the elements a chain of selector steps matches: every step searches inside the previous step's matches */
+export class ChainResolver {
+    constructor(connector, contextId, call) {
+        this.connector = connector;
+        this.contextId = contextId;
+        this.call = call;
+    }
+    /** In document order; `max` limits the final result. Nothing is cached: the first match can change between polls */
+    async resolveChain(chain, max) {
+        let nodes;
+        for (const [index, selector] of chain.entries()) {
+            if (selector.kind === "nth") {
+                const picked = nodes?.[selector.index];
+                nodes = picked ? [picked] : [];
+            }
+            else {
+                try {
+                    nodes = await this.locateStep(selector, index > 0, nodes, index === chain.length - 1 ? max : undefined);
+                }
+                catch (err) {
+                    // The page is swapping documents: nothing matches right now, and the waits that poll try again
+                    if (isDocumentSwap(err))
+                        return [];
+                    throw err;
+                }
+            }
+            if (nodes.length === 0)
+                return [];
+        }
+        return nodes ?? [];
+    }
+    async locateStep(selector, scoped, startNodes, max) {
+        if (selector.kind === "label")
+            return this.locateInPage(LABEL_LOCATE, selector, startNodes, max);
+        if (selector.kind === "text" &&
+            unsupportedTypes(this.connector).has("innerText")) {
+            return this.locateInPage(TEXT_LOCATE, selector, startNodes, max);
+        }
+        try {
+            return await this.locateNatively(selector, scoped, startNodes, max);
+        }
+        catch (err) {
+            if (err instanceof BiDiError && err.code === "invalid selector") {
+                throw new InvalidSelectorError(describeSelector(selector, scoped), err.message);
+            }
+            if (err instanceof BiDiError && err.code === "unsupported operation") {
+                if (selector.kind === "text") {
+                    // The browser has no innerText locator (Firefox): remember that and search in the page instead
+                    unsupportedTypes(this.connector).add("innerText");
+                    return this.locateInPage(TEXT_LOCATE, selector, startNodes, max);
+                }
+                throw new UnsupportedOperationError(`${describeSelector(selector, scoped)}: this kind of locator is not supported by the browser (${err.message})`);
+            }
+            throw err;
+        }
+    }
+    async locateNatively(selector, scoped, startNodes, max) {
+        const { nodes } = await this.connector.send("browsingContext.locateNodes", {
+            context: this.contextId,
+            locator: toBiDiLocator(selector, scoped),
+            ...(max !== undefined && { maxNodeCount: max }),
+            // Only the references are needed; skip serializing the matched subtrees
+            serializationOptions: { maxDomDepth: 0 },
+            ...(startNodes && {
+                startNodes: startNodes.map(({ sharedId }) => ({ sharedId })),
+            }),
+        });
+        const found = new Map();
+        for (const node of nodes) {
+            if (node.sharedId !== undefined && !found.has(node.sharedId)) {
+                found.set(node.sharedId, new ElementHandle(node.sharedId));
+            }
+        }
+        return [...found.values()];
+    }
+    /** Runs a page-side search `(starts, value, match, ignoreCase) => elements` */
+    async locateInPage(fn, selector, startNodes, max) {
+        const found = await this.call(fn, [
+            startNodes ?? [],
+            selector.value,
+            selector.match,
+            selector.ignoreCase,
+        ]);
+        return max === undefined ? found : found.slice(0, max);
+    }
+}

package/dist/locator/document-swap.d.ts

@@ -0,0 +1 @@
+export declare function isDocumentSwap(err: unknown): boolean;

package/dist/locator/document-swap.js

@@ -0,0 +1,11 @@
+import { BiDiError } from "../transport/bidi-error.js";
+/**
+ * Chrome answers a command sent while the page swaps documents with an unknown error that says the context
+ * is gone for the moment; the same call a moment later works.
+ */
+const DOCUMENT_SWAP = /Cannot find context with specified id|execution contexts? (was |were )?(cleared|destroyed)/i;
+export function isDocumentSwap(err) {
+    return (err instanceof BiDiError &&
+        err.code === "unknown error" &&
+        DOCUMENT_SWAP.test(err.message));
+}

package/dist/locator/element-state.d.ts

@@ -1,4 +1,4 @@
-export interface ElementBox {
+interface ElementBox {
     x: number;
     y: number;
     width: number;
@@ -39,6 +39,8 @@ export declare const DETACHED_STATE: ElementState;
 export declare const PROBE_ELEMENT: string;
 /** Checks the probe result is a complete state; throws on anything else */
 export declare function parseElementState(value: unknown): ElementState;
+export declare function describeType(value: unknown): string;
 /** Evaluates the required checks in order; after the first failure the rest are pending */
 export declare function evaluateChecks(required: readonly CheckName[], current: ElementState, previous: ElementState | undefined): CheckResults;
 export declare function allPass(results: CheckResults): boolean;
+export {};

package/dist/locator/element-state.js

@@ -1,4 +1,12 @@
-const TEXT_INPUT_TYPES = ["text", "search", "email", "url", "tel", "password", "number"];
+const TEXT_INPUT_TYPES = [
+    "text",
+    "search",
+    "email",
+    "url",
+    "tel",
+    "password",
+    "number",
+];
 /** State of an element that is not in the document (never matched, or gone) */
 export const DETACHED_STATE = {
     attached: false,
@@ -16,7 +24,7 @@ export const DETACHED_STATE = {
  */
 export const PROBE_ELEMENT = `(el, options) => {
   if (!el || !el.isConnected) {
-    return { attached: false, visible: false, enabled: false, editable: false, box: null, hitTarget: null };
+    return ${JSON.stringify(DETACHED_STATE)};
   }
   if (options.scroll) {
     const before = el.getBoundingClientRect();
@@ -62,7 +70,7 @@ export function parseElementState(value) {
     }
     return state;
 }
-function describeType(value) {
+export function describeType(value) {
     return value === null ? "null" : typeof value;
 }
 function sameBox(a, b) {

package/dist/locator/file-actions.d.ts

@@ -0,0 +1,35 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
+import type { ElementHandle } from "../script/element-handle.js";
+import type { Arg } from "../script/serialize.js";
+import { type FileInput } from "../browser/generated-files.js";
+import type { CheckName, ProbeOptions } from "./element-state.js";
+import type { ActionOptions } from "./actionability.js";
+/** What the file actions need of a locator */
+export interface ElementContext {
+    readonly connector: BiDiConnector;
+    readonly contextId: BrowsingContext;
+    /** The locator's description for error messages */
+    readonly selector: string;
+    call<T>(fn: string, args: Arg[], sandbox?: string): Promise<T>;
+    waitForActionable(action: string, checks: readonly CheckName[], probe: ProbeOptions, options: ActionOptions | undefined): Promise<unknown>;
+    /** The element the locator matches now; throws when none does */
+    requireElement(): Promise<ElementHandle>;
+    /** The error for an operation that needs an element when none matches */
+    noElementError(): Error;
+}
+/**
+ * Sets the files of an `<input type=file>`; `[]` clears it. Waits for the input to be attached and enabled;
+ * it need not be visible, file inputs are often hidden behind a label.
+ */
+export declare function setInputFiles(ctx: ElementContext, files: FileInput | FileInput[], options?: {
+    timeout?: number;
+}): Promise<void>;
+/**
+ * Drops files on the element, as dragging them from the desktop does: `dragenter`, `dragover` and `drop`
+ * with a `DataTransfer` holding the files. The events are synthetic (`isTrusted` is false).
+ * Waits for the element to be attached and visible.
+ */
+export declare function dropFiles(ctx: ElementContext, files: FileInput | FileInput[], options?: {
+    timeout?: number;
+}): Promise<void>;

package/dist/locator/file-actions.js

@@ -0,0 +1,55 @@
+import { BiDiError } from "../transport/bidi-error.js";
+import { isGeneratedFile, resolveFileInputs, } from "../browser/generated-files.js";
+import { DROP_CHECKS, DROP_EVENTS, DROP_INPUT, DROP_SANDBOX, FILE_INPUT_CHECKS, FILE_INPUT_INFO, } from "./page-scripts.js";
+/**
+ * Sets the files of an `<input type=file>`; `[]` clears it. Waits for the input to be attached and enabled;
+ * it need not be visible, file inputs are often hidden behind a label.
+ */
+export async function setInputFiles(ctx, files, options) {
+    const paths = await resolveFileInputs(files, "setInputFiles");
+    await ctx.waitForActionable("setInputFiles", FILE_INPUT_CHECKS, { scroll: false, hitTest: false }, options);
+    const el = await ctx.requireElement();
+    let info;
+    try {
+        info = await ctx.call(FILE_INPUT_INFO, [el]);
+    }
+    catch (err) {
+        if (err instanceof BiDiError && err.code === "no such node")
+            throw ctx.noElementError();
+        throw err;
+    }
+    if (info.tag !== "input" || info.type !== "file") {
+        const found = info.tag === "input"
+            ? `<input type="${info.type || "text"}">`
+            : `<${info.tag}>`;
+        throw new Error(`setInputFiles(): ${ctx.selector} is not an <input type=file> (found ${found})`);
+    }
+    if (paths.length > 1 && !info.multiple) {
+        throw new Error(`setInputFiles(): ${ctx.selector} does not accept multiple files`);
+    }
+    await ctx.connector.send("input.setFiles", {
+        context: ctx.contextId,
+        element: { sharedId: el.sharedId },
+        files: paths,
+    });
+}
+/**
+ * Drops files on the element, as dragging them from the desktop does: `dragenter`, `dragover` and `drop`
+ * with a `DataTransfer` holding the files. The events are synthetic (`isTrusted` is false).
+ * Waits for the element to be attached and visible.
+ */
+export async function dropFiles(ctx, files, options) {
+    const list = Array.isArray(files) ? files : [files];
+    const paths = await resolveFileInputs(list, "dropFiles");
+    const types = list.map((file) => isGeneratedFile(file) ? (file.type ?? "") : "");
+    await ctx.waitForActionable("dropFiles", DROP_CHECKS, { scroll: true, hitTest: false }, options);
+    const el = await ctx.requireElement();
+    // A file input of our own, made in a sandbox and never attached: the page doesn't see it
+    const input = await ctx.call(DROP_INPUT, [], DROP_SANDBOX);
+    await ctx.connector.send("input.setFiles", {
+        context: ctx.contextId,
+        element: { sharedId: input.sharedId },
+        files: paths,
+    });
+    await ctx.call(DROP_EVENTS, [el, types], DROP_SANDBOX);
+}

package/dist/{script/helpers.js → locator/helper-realm.js}

@@ -1,5 +1,5 @@
-import { PROBE_ELEMENT } from "../locator/element-state.js";
-import { addPreload, runInLoadedContexts } from "./preload.js";
+import { addPreload, runInLoadedContexts, } from "../script/preload.js";
+import { PROBE_ELEMENT } from "./element-state.js";
 /** Sandbox realm holding the framework's helpers: same DOM as the page, separate JS globals */
 export const HELPER_SANDBOX = "samurai";
 /** What `CALL_PROBE` answers with when the helpers are not installed in the document */

package/dist/locator/input-actions.d.ts

@@ -0,0 +1,18 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/** How long `wait()` pauses when no duration is given (ms) */
+export declare const DEFAULT_PAUSE_MS = 300;
+/** WebDriver code points of the named keys `press()` accepts; any other single character is typed as is */
+export declare const NAMED_KEYS: Readonly<Record<string, string>>;
+/** Clicks the centre of `rect` (viewport pixels) with real pointer input */
+export declare function clickRect(connector: BiDiConnector, context: string, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): Promise<void>;
+/** Pauses the input queue for `duration` ms */
+export declare function pause(connector: BiDiConnector, context: string, duration: number): Promise<void>;
+/** Presses and releases one key, given as its WebDriver code point or a character */
+export declare function pressKey(connector: BiDiConnector, context: string, code: string): Promise<void>;
+/** Types `text` one character at a time (each pressed and released) */
+export declare function typeText(connector: BiDiConnector, context: string, text: string): Promise<void>;

package/dist/locator/input-actions.js

@@ -0,0 +1,80 @@
+/** How long `wait()` pauses when no duration is given (ms) */
+export const DEFAULT_PAUSE_MS = 300;
+// Input source ids: BiDi keeps the pointer position and pressed keys per id, so each kind of input reuses one
+const POINTER_ID = "samurai-pointer";
+const KEYBOARD_ID = "samurai-keyboard";
+const PAUSE_ID = "samurai-sleep";
+/** WebDriver code points of the named keys `press()` accepts; any other single character is typed as is */
+export const NAMED_KEYS = {
+    Backspace: "\uE003",
+    Tab: "\uE004",
+    Enter: "\uE007",
+    Escape: "\uE00C",
+    Space: " ",
+    ArrowLeft: "\uE012",
+    ArrowUp: "\uE013",
+    ArrowRight: "\uE014",
+    ArrowDown: "\uE015",
+    Delete: "\uE017",
+    Home: "\uE011",
+    End: "\uE010",
+    PageUp: "\uE00E",
+    PageDown: "\uE00F",
+};
+/** Clicks the centre of `rect` (viewport pixels) with real pointer input */
+export async function clickRect(connector, context, rect) {
+    await connector.send("input.performActions", {
+        context,
+        actions: [
+            {
+                type: "pointer",
+                id: POINTER_ID,
+                actions: [
+                    {
+                        type: "pointerMove",
+                        x: rect.x + rect.width / 2,
+                        y: rect.y + rect.height / 2,
+                    },
+                    { type: "pointerDown", button: 0 },
+                    { type: "pointerUp", button: 0 },
+                ],
+            },
+        ],
+    });
+}
+/** Pauses the input queue for `duration` ms */
+export async function pause(connector, context, duration) {
+    await connector.send("input.performActions", {
+        context,
+        actions: [
+            { type: "none", id: PAUSE_ID, actions: [{ type: "pause", duration }] },
+        ],
+    });
+}
+/** Presses and releases one key, given as its WebDriver code point or a character */
+export async function pressKey(connector, context, code) {
+    await connector.send("input.performActions", {
+        context,
+        actions: [
+            {
+                type: "key",
+                id: KEYBOARD_ID,
+                actions: [
+                    { type: "keyDown", value: code },
+                    { type: "keyUp", value: code },
+                ],
+            },
+        ],
+    });
+}
+/** Types `text` one character at a time (each pressed and released) */
+export async function typeText(connector, context, text) {
+    const actions = Array.from(text).flatMap((char) => [
+        { type: "keyDown", value: char },
+        { type: "keyUp", value: char },
+    ]);
+    await connector.send("input.performActions", {
+        context,
+        actions: [{ type: "key", id: KEYBOARD_ID, actions }],
+    });
+}

package/dist/locator/label-locator.d.ts

@@ -10,4 +10,4 @@
  *
  * A string, so the transpiler cannot inject helpers that do not exist in the page.
  */
-export declare const LABEL_LOCATE = "(starts, value, match, ignoreCase) => {\n  const normalise = (text) => {\n    const collapsed = String(text).replace(/\\s+/g, \" \").trim();\n    return ignoreCase ? collapsed.toLowerCase() : collapsed;\n  };\n  const wanted = normalise(value);\n  const textOf = (node) => node.innerText ?? node.textContent ?? \"\";\n  const labelsOf = (el) => {\n    const texts = [];\n    if (el.labels) for (const label of el.labels) texts.push(textOf(label));\n    const by = el.getAttribute(\"aria-labelledby\");\n    if (by) {\n      for (const id of by.split(/\\s+/)) {\n        const named = id && document.getElementById(id);\n        if (named) texts.push(textOf(named));\n      }\n    }\n    const own = el.getAttribute(\"aria-label\");\n    if (own) texts.push(own);\n    return texts;\n  };\n  const roots = starts.length > 0 ? starts : [document];\n  const seen = new Set();\n  const matches = [];\n  for (const root of roots) {\n    for (const el of root.querySelectorAll(\"*\")) {\n      if (seen.has(el)) continue;\n      seen.add(el);\n      const found = labelsOf(el).some((text) => {\n        const normal = normalise(text);\n        return match === \"full\" ? normal === wanted : normal.includes(wanted);\n      });\n      if (found) matches.push(el);\n    }\n  }\n  return matches.sort((a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1));\n}";
+export declare const LABEL_LOCATE = "(starts, value, match, ignoreCase) => {\n  \n  const normalise = (text) => {\n    const collapsed = String(text).replace(/\\s+/g, \" \").trim();\n    return ignoreCase ? collapsed.toLowerCase() : collapsed;\n  };\n  const wanted = normalise(value);\n  const textMatches = (text) => {\n    const normal = normalise(text);\n    return match === \"full\" ? normal === wanted : normal.includes(wanted);\n  };\n  const textOf = (node) => node.innerText ?? node.textContent ?? \"\";\n  const labelsOf = (el) => {\n    const texts = [];\n    if (el.labels) for (const label of el.labels) texts.push(textOf(label));\n    const by = el.getAttribute(\"aria-labelledby\");\n    if (by) {\n      for (const id of by.split(/\\s+/)) {\n        const named = id && document.getElementById(id);\n        if (named) texts.push(textOf(named));\n      }\n    }\n    const own = el.getAttribute(\"aria-label\");\n    if (own) texts.push(own);\n    return texts;\n  };\n  const roots = starts.length > 0 ? starts : [document];\n  const seen = new Set();\n  const matches = [];\n  for (const root of roots) {\n    for (const el of root.querySelectorAll(\"*\")) {\n      if (seen.has(el)) continue;\n      seen.add(el);\n      if (labelsOf(el).some(textMatches)) matches.push(el);\n    }\n  }\n  return matches.sort((a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1));\n}";

package/dist/locator/label-locator.js

@@ -1,3 +1,4 @@
+import { DOCUMENT_ORDER_JS, MATCHING_JS, ROOTS_JS } from "./page-search.js";
 /**
  * Function declaration run in the page as `(starts, value, match, ignoreCase)`; returns the elements
  * named by a label whose text matches. BiDi has no label locator, so the framework does it.
@@ -11,11 +12,7 @@
  * A string, so the transpiler cannot inject helpers that do not exist in the page.
  */
 export const LABEL_LOCATE = `(starts, value, match, ignoreCase) => {
-  const normalise = (text) => {
-    const collapsed = String(text).replace(/\\s+/g, " ").trim();
-    return ignoreCase ? collapsed.toLowerCase() : collapsed;
-  };
-  const wanted = normalise(value);
+  ${MATCHING_JS}
   const textOf = (node) => node.innerText ?? node.textContent ?? "";
   const labelsOf = (el) => {
     const texts = [];
@@ -31,19 +28,15 @@ export const LABEL_LOCATE = `(starts, value, match, ignoreCase) => {
     if (own) texts.push(own);
     return texts;
   };
-  const roots = starts.length > 0 ? starts : [document];
+  ${ROOTS_JS}
   const seen = new Set();
   const matches = [];
   for (const root of roots) {
     for (const el of root.querySelectorAll("*")) {
       if (seen.has(el)) continue;
       seen.add(el);
-      const found = labelsOf(el).some((text) => {
-        const normal = normalise(text);
-        return match === "full" ? normal === wanted : normal.includes(wanted);
-      });
-      if (found) matches.push(el);
+      if (labelsOf(el).some(textMatches)) matches.push(el);
     }
   }
-  return matches.sort((a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1));
+  return matches.sort(${DOCUMENT_ORDER_JS});
 }`;

package/dist/locator/locator.d.ts

@@ -1,23 +1,13 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
 import type { BrowsingContext, ElementRectangle } from "../types/bidi-modules/browsing-context.js";
-import { type HelperInstaller } from "../script/helpers.js";
 import { ElementHandle } from "../script/element-handle.js";
 import { type ElementScreenshotOptions } from "../browser/screenshot.js";
-import { type FileInput } from "../browser/generated-files.js";
+import type { FileInput } from "../browser/generated-files.js";
+import { type ActionOptions } from "./actionability.js";
 import { type WaitForState } from "./element-state.js";
+import type { HelperInstaller } from "./helper-realm.js";
 import { type Selector, type TextOptions } from "./selector.js";
-export type { WaitForState } from "./element-state.js";
-export { InvalidSelectorError, UnsupportedOperationError, } from "./selector-errors.js";
-export type { TextOptions } from "./selector.js";
-export interface ActionOptions {
-    /**
-     * Time (ms) to wait for the element to become actionable. Defaults to config `expect.timeout`, then 5000.
-     * 0 checks once without waiting; the stability check is skipped because it needs two probes
-     */
-    timeout?: number;
-    /** Skip every actionability check except "attached" */
-    force?: boolean;
-}
+export type { ActionOptions } from "./actionability.js";
 export default class Locator {
     private biDiConnector;
     private contextId;
@@ -25,6 +15,11 @@ export default class Locator {
     private helpers;
     private alternatives;
     private matched;
+    private resolver;
+    /** What the actionability waits use of this locator */
+    private actionability;
+    /** What the file actions use of this locator */
+    private elementContext;
     /**
      * `selector` is an xpath, or a chain of selector steps that each search inside the previous step's matches.
      * `helpers` is the page's helper realm. With it the actionability probe is installed once per
@@ -81,14 +76,7 @@ export default class Locator {
     /** The primary or the first fallback that currently matches, without its own fallbacks */
     private firstMatching;
     private withoutFallbacks;
-    private resolveChain;
     private resolveOne;
-    private locateStep;
-    private locateNatively;
-    /** Text search done in the page, for browsers without BiDi's innerText locator */
-    private locateByText;
-    /** Runs a page-side search `(starts, value, match, ignoreCase) => elements` */
-    private locateInPage;
     /** Calls `fn` in the page; a throwing function becomes a "Failed to locate element" error */
     private call;
     /**
@@ -98,24 +86,14 @@ export default class Locator {
     private callOnElement;
     /** Like `callOnElement`, for operations that cannot go on without the element */
     private callOnExistingElement;
-    /** Reads the element's actionability state: one search, one probe */
+    /** The error for an operation that needs an element when none matches */
+    private noElementError;
+    /** The element the locator matches now; throws when none does */
+    private requireElement;
     private probeState;
-    private callProbe;
-    /**
-     * Probes until every required check passes and returns that state.
-     * Throws ActionTimeoutError describing the last probe on timeout.
-     */
     private waitForActionable;
     /** Waits until the element is attached, visible, stable, enabled and not covered, then clicks its centre with real pointer input */
     click(options?: ActionOptions): Promise<void>;
-    /** Simulate a click event on the center off a page element.
-     * This is mostly used internally to focus input elements when using the `fill()` method
-     * @example
-     *  const container = page.locator("div[@id=['clickable-element']");
-     *  const rect = await container.getBoundingClientRect();
-     *  await container.clickRect(rect);
-     */
-    clickRect(rect: Pick<ElementRectangle, "x" | "y" | "width" | "height">): Promise<void>;
     /**
      * Sets the files of an `<input type=file>`; `[]` clears it. Paths are relative to the project folder (absolute
      * ones are used as they are); `generatedFile(…)` writes a file of a given size when the step runs.
@@ -150,13 +128,12 @@ export default class Locator {
     /** Waits until the element is attached, then focuses it */
     focus(options?: ActionOptions): Promise<void>;
     /** Waits until the element reaches `state` (default "visible"); does not scroll */
-    waitFor({ state, timeout, }?: {
+    waitFor(options?: {
         state?: WaitForState;
         timeout?: number;
     }): Promise<void>;
     /** Returns the browser's getBoundingClientRect result for the given element */
     getBoundingClientRect(): Promise<ElementRectangle>;
-    private stringOrNull;
     /** Whether the element exists, has a non-empty box and is not hidden by CSS */
     isVisible(): Promise<boolean>;
     /** Trimmed text content, or null when the element is missing */