@itmetsam/samurai-framework 0.21.1 → 0.21.3

package/dist/locator/accessible-name.js

@@ -0,0 +1,128 @@
+import { NAME_FROM_CONTENT_ROLES, ROLE_OF_JS } from "./role-table.js";
+/**
+ * Page-side source that defines, in the scope it is pasted into:
+ *
+ * - `isHidden(el)`: not rendered or hidden from assistive technology: `display: none`, `visibility: hidden` or
+ *   `collapse`, or `aria-hidden="true"` on the element or an ancestor.
+ * - `accessibleName(el)` and `accessibleDescription(el)`: strings, whitespace collapsed and trimmed.
+ * - `roleOf(el)` (from `ROLE_OF_JS`).
+ *
+ * The name follows the accname algorithm in a simplified form, the order being: `aria-labelledby` (hidden content is
+ * read when referenced directly), `aria-label`, the native text alternative (`alt` of img / area / input[type=image],
+ * `value` of button-like inputs, the `<label>`s of a form control, `<legend>`, `<caption>`, `<figcaption>`, svg
+ * `<title>`), the content for roles that take their name from it (and always for what an embedding walks through),
+ * the `title` attribute, and for a text field its `placeholder`. Embedded form controls count by their value, and
+ * `::before` / `::after` text by its CSS content. Hidden descendants are skipped. A reference loop stops at the
+ * element already visited. The description is `aria-describedby`, else `aria-description`, else the `title` when it was not
+ * used as the name.
+ *
+ * It deliberately differs from the browser's own accessibility tree: no CSS `display` quirks for table parts, no
+ * `<summary>` or `<details>` rules, no shadow DOM or slot flattening, no `aria-owns`, and `placeholder` counts as a name
+ * for inputs in both browsers' way (Firefox and Chrome disagree there).
+ */
+export const ACCESSIBLE_NAME_JS = `
+  ${ROLE_OF_JS}
+  const NAME_FROM_CONTENT = ${JSON.stringify(NAME_FROM_CONTENT_ROLES)};
+  const squash = (text) => String(text).replace(/\\s+/g, " ").trim();
+  const hiddenSelf = (n) => {
+    if (n.getAttribute("aria-hidden") === "true") return true;
+    const style = getComputedStyle(n);
+    return style.display === "none" || style.visibility === "hidden" || style.visibility === "collapse";
+  };
+  const isHidden = (el) => {
+    if (hiddenSelf(el)) return true;
+    for (let n = el.parentElement; n; n = n.parentElement) {
+      if (n.getAttribute("aria-hidden") === "true" || getComputedStyle(n).display === "none") return true;
+    }
+    return false;
+  };
+  const byIds = (el, attribute) => (el.getAttribute(attribute) || "").split(/\\s+/)
+    .map((id) => (id ? el.ownerDocument.getElementById(id) : null)).filter(Boolean);
+  const pseudoText = (el, which) => {
+    const content = getComputedStyle(el, which).content;
+    return content && content !== "none" && content !== "normal" && /^["']/.test(content) ? content.slice(1, -1) : "";
+  };
+  const embeddedValue = (el, role) => {
+    if (role === "textbox" || role === "searchbox" || role === "spinbutton" || role === "slider") return el.value ?? el.getAttribute("aria-valuenow") ?? "";
+    if (role === "combobox" || role === "listbox") {
+      const chosen = el.localName === "select" ? Array.from(el.selectedOptions) : [];
+      return chosen.map((option) => option.label || option.textContent).join(" ");
+    }
+    return null;
+  };
+  /** The text of a node and what it embeds. \`seen\` guards reference loops; \`top\` is the node whose name is asked for */
+  const walk = (node, seen, top) => {
+    if (node.nodeType === 3) return node.nodeValue;
+    if (node.nodeType !== 1 || seen.has(node)) return "";
+    if (node !== top && hiddenSelf(node)) return "";
+    if (["script", "style", "noscript", "template"].includes(node.localName)) return "";
+    seen.add(node);
+    const label = node !== top && (node.getAttribute("aria-label") || "").trim();
+    if (label) return label;
+    const role = roleOf(node);
+    if (node !== top) {
+      const value = embeddedValue(node, role);
+      if (value !== null) return value;
+    }
+    let text = pseudoText(node, "::before");
+    for (const child of node.childNodes) {
+      const part = walk(child, seen, top);
+      const block = child.nodeType === 1 && getComputedStyle(child).display !== "inline";
+      text += block ? " " + part + " " : part;
+    }
+    return text + pseudoText(node, "::after");
+  };
+  const fromReferences = (el, attribute, seen) => squash(byIds(el, attribute).map((ref) => {
+    const own = (ref.getAttribute("aria-label") || "").trim();
+    return own || walk(ref, new Set(seen), ref);
+  }).join(" "));
+  const labelText = (el, seen) => squash(Array.from(el.labels || []).map((label) => walk(label, new Set(seen), label)).join(" "));
+  const nativeName = (el, seen) => {
+    const tag = el.localName;
+    const type = (el.getAttribute("type") || "").toLowerCase();
+    const first = (selector) => el.querySelector(":scope > " + selector);
+    if (tag === "img" || tag === "area" || (tag === "input" && type === "image")) {
+      const alt = el.getAttribute("alt");
+      if (alt !== null && squash(alt)) return squash(alt);
+      if (tag === "input") return squash(el.getAttribute("value") || "") || labelText(el, seen);
+      return "";
+    }
+    if (tag === "input" && (type === "button" || type === "submit" || type === "reset")) {
+      const value = squash(el.getAttribute("value") || "");
+      return value || labelText(el, seen) || (type === "submit" ? "Submit" : type === "reset" ? "Reset" : "");
+    }
+    if (tag === "input" || tag === "textarea" || tag === "select" || tag === "meter" || tag === "progress" || tag === "output") return labelText(el, seen);
+    if (tag === "fieldset") { const legend = first("legend"); return legend ? squash(walk(legend, new Set(seen), legend)) : ""; }
+    if (tag === "table") { const caption = first("caption"); return caption ? squash(walk(caption, new Set(seen), caption)) : ""; }
+    if (tag === "figure") { const caption = first("figcaption"); return caption ? squash(walk(caption, new Set(seen), caption)) : ""; }
+    if (tag === "svg") { const title = first("title"); return title ? squash(title.textContent) : ""; }
+    return "";
+  };
+  /** The name and where it came from (\`title\` or \`placeholder\` matter to the description) */
+  const nameSource = (el) => {
+    const seen = new Set([el]);
+    const referenced = fromReferences(el, "aria-labelledby", seen);
+    if (referenced) return { name: referenced, source: "labelledby" };
+    const own = squash(el.getAttribute("aria-label") || "");
+    if (own) return { name: own, source: "label" };
+    const native = nativeName(el, seen);
+    if (native) return { name: native, source: "native" };
+    if (NAME_FROM_CONTENT.includes(roleOf(el)) || el.localName === "label" || el.localName === "legend" || el.localName === "caption") {
+      const content = squash(walk(el, new Set(), el));
+      if (content) return { name: content, source: "content" };
+    }
+    const title = squash(el.getAttribute("title") || "");
+    if (title) return { name: title, source: "title" };
+    const placeholder = squash(el.getAttribute("placeholder") || "");
+    if ((el.localName === "input" || el.localName === "textarea") && placeholder) return { name: placeholder, source: "placeholder" };
+    return { name: "", source: "" };
+  };
+  const accessibleName = (el) => nameSource(el).name;
+  const accessibleDescription = (el) => {
+    const referenced = fromReferences(el, "aria-describedby", new Set([el]));
+    if (referenced) return referenced;
+    const attribute = squash(el.getAttribute("aria-description") || "");
+    if (attribute) return attribute;
+    const title = squash(el.getAttribute("title") || "");
+    return title && nameSource(el).source !== "title" ? title : "";
+  };`;

package/dist/locator/action-timeout-error.js

@@ -1,4 +1,8 @@
-const SYMBOLS = { pass: "✓", fail: "✗", pending: "—" };
+const SYMBOLS = {
+    pass: "✓",
+    fail: "✗",
+    pending: "—",
+};
 function formatMessage({ action, selector, timeout, reason, checks, coveredBy, state, }) {
     switch (reason) {
         case "unreadable":

package/dist/locator/actionability.d.ts

@@ -12,7 +12,8 @@ export interface ActionOptions {
 }
 /** What the actionability waits need of a locator: finding its element, calling into the page, naming itself */
 export interface ActionabilityContext {
-    resolveOne(): Promise<ElementHandle | null>;
+    /** `method` names the public method that asks; with it, a strict locator throws when several elements match */
+    resolveOne(method?: string): Promise<ElementHandle | null>;
     call<T>(fn: string, args: unknown[], sandbox?: string): Promise<T>;
     /** The locator's description for error messages */
     readonly selector: string;
@@ -20,7 +21,7 @@ export interface ActionabilityContext {
     readonly helpers: HelperInstaller | undefined;
 }
 /** Reads the element's actionability state: one search, one probe */
-export declare function probeState(ctx: ActionabilityContext, options: ProbeOptions): Promise<ElementState>;
+export declare function probeState(ctx: ActionabilityContext, options: ProbeOptions, method: string): Promise<ElementState>;
 /**
  * Probes until every required check passes and returns that state.
  * Throws ActionTimeoutError describing the last probe on timeout.

package/dist/locator/actionability.js

@@ -8,8 +8,8 @@ import { allPass, DETACHED_STATE, evaluateChecks, parseElementState, PROBE_ELEME
 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();
+export async function probeState(ctx, options, method) {
+    const el = await ctx.resolveOne(method);
     if (!el)
         return DETACHED_STATE;
     try {
@@ -53,7 +53,7 @@ export async function waitForActionable(ctx, action, checks, probe, options) {
             : checks;
     let lastChecks;
     try {
-        return await waitUntil(() => probeState(ctx, probe), (current, previous) => {
+        return await waitUntil(() => probeState(ctx, probe, action), (current, previous) => {
             lastChecks = evaluateChecks(required, current, previous);
             return allPass(lastChecks);
         }, { timeout });
@@ -88,7 +88,7 @@ export async function waitForState(ctx, { state = "visible", timeout }) {
         hidden: (current) => !current.attached || !current.visible,
     };
     try {
-        await waitUntil(() => probeState(ctx, { scroll: false, hitTest: false }), reached[state], { timeout: resolved });
+        await waitUntil(() => probeState(ctx, { scroll: false, hitTest: false }, "waitFor"), reached[state], { timeout: resolved });
     }
     catch (err) {
         if (!(err instanceof WaitTimeoutError))

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

@@ -0,0 +1,13 @@
+/**
+ * Function declaration run in the page as `(starts, value, match, ignoreCase, attribute)`; returns the
+ * elements whose `placeholder`, `alt` or `title` attribute matches. BiDi has no such locator, so the
+ * framework does it.
+ *
+ * - Searches the descendants of every start node (the whole document when there are none).
+ * - The attribute text is whitespace collapsed and trimmed; `full` needs equality, `partial` a substring,
+ *   a RegExp is tested as written (see `MATCHING_JS`).
+ * - Results are unique and in document order.
+ *
+ * A string, so the transpiler cannot inject helpers that do not exist in the page.
+ */
+export declare const ATTRIBUTE_LOCATE = "(starts, value, match, ignoreCase, attribute) => {\n  \n  const collapse = (text) => String(text).replace(/\\s+/g, \" \").trim();\n  const normalise = (text) => {\n    const collapsed = collapse(text);\n    return ignoreCase ? collapsed.toLowerCase() : collapsed;\n  };\n  const pattern = typeof value === \"string\" ? null : new RegExp(value.source, value.flags.replace(/[gy]/g, \"\"));\n  const wanted = pattern ? \"\" : normalise(value);\n  const textMatches = (text) => {\n    if (pattern) return pattern.test(collapse(text));\n    const normal = normalise(text);\n    return match === \"full\" ? normal === wanted : normal.includes(wanted);\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(\"[\" + attribute + \"]\")) {\n      if (seen.has(el)) continue;\n      seen.add(el);\n      if (textMatches(el.getAttribute(attribute))) matches.push(el);\n    }\n  }\n  return matches.sort((a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1));\n}";

package/dist/locator/attribute-locator.js

@@ -0,0 +1,27 @@
+import { DOCUMENT_ORDER_JS, MATCHING_JS, ROOTS_JS } from "./page-search.js";
+/**
+ * Function declaration run in the page as `(starts, value, match, ignoreCase, attribute)`; returns the
+ * elements whose `placeholder`, `alt` or `title` attribute matches. BiDi has no such locator, so the
+ * framework does it.
+ *
+ * - Searches the descendants of every start node (the whole document when there are none).
+ * - The attribute text is whitespace collapsed and trimmed; `full` needs equality, `partial` a substring,
+ *   a RegExp is tested as written (see `MATCHING_JS`).
+ * - Results are unique and in document order.
+ *
+ * A string, so the transpiler cannot inject helpers that do not exist in the page.
+ */
+export const ATTRIBUTE_LOCATE = `(starts, value, match, ignoreCase, attribute) => {
+  ${MATCHING_JS}
+  ${ROOTS_JS}
+  const seen = new Set();
+  const matches = [];
+  for (const root of roots) {
+    for (const el of root.querySelectorAll("[" + attribute + "]")) {
+      if (seen.has(el)) continue;
+      seen.add(el);
+      if (textMatches(el.getAttribute(attribute))) matches.push(el);
+    }
+  }
+  return matches.sort(${DOCUMENT_ORDER_JS});
+}`;

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

@@ -11,10 +11,19 @@ export declare class ChainResolver {
     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[]>;
+    /**
+     * In document order; `max` limits the final result. Nothing is cached: the first match can change between polls.
+     * `start` makes the chain relative to those elements: its first step searches inside them, like a later step.
+     */
+    resolveChain(chain: readonly Selector[], max?: number, start?: readonly ElementHandle[]): Promise<ElementHandle[]>;
+    /**
+     * `and` keeps what both chains match; `or` what either matches, in document order. Both chains search from
+     * scratch (or inside `from`, when the whole chain is relative). An `or` needs no more than `max` of each
+     */
+    private combine;
+    private inDocumentOrder;
     private locateStep;
     private locateNatively;
-    /** Runs a page-side search `(starts, value, match, ignoreCase) => elements` */
+    /** Runs a page-side search `(starts, ...args) => elements` */
     private locateInPage;
 }

package/dist/locator/chain-resolver.js

@@ -2,10 +2,12 @@ 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 { intersect, union } from "./combine-step.js";
+import { applyFilter } from "./filter-step.js";
+import { SORT_IN_DOCUMENT_ORDER } from "./page-search.js";
 import { InvalidSelectorError } from "./selector-errors.js";
+import { pageSearch, textSearch } from "./page-step.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) {
@@ -14,6 +16,19 @@ function unsupportedTypes(connector) {
         unsupportedByConnector.set(connector, (types = new Set()));
     return types;
 }
+/**
+ * How many matches step `index` has to find: `max` for the last step; for a step an `nth` follows, only
+ * as many as that index needs, when one start node (or none) makes the search order the document's
+ */
+function stepLimit(chain, index, from, max) {
+    if (index === chain.length - 1)
+        return max;
+    const next = chain[index + 1];
+    const single = (from?.length ?? 0) <= 1;
+    return next.kind === "nth" && next.index >= 0 && single
+        ? next.index + 1
+        : undefined;
+}
 /** 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) {
@@ -21,17 +36,50 @@ export class ChainResolver {
         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) {
+    /**
+     * In document order; `max` limits the final result. Nothing is cached: the first match can change between polls.
+     * `start` makes the chain relative to those elements: its first step searches inside them, like a later step.
+     */
+    async resolveChain(chain, max, start) {
         let nodes;
         for (const [index, selector] of chain.entries()) {
+            const from = nodes ?? start;
             if (selector.kind === "nth") {
-                const picked = nodes?.[selector.index];
+                const picked = nodes?.[selector.index < 0 ? nodes.length + selector.index : selector.index];
                 nodes = picked ? [picked] : [];
             }
+            else if (selector.kind === "and" || selector.kind === "or") {
+                try {
+                    nodes = await this.combine(selector, from, stepLimit(chain, index, from, max));
+                }
+                catch (err) {
+                    if (isDocumentSwap(err))
+                        return [];
+                    throw err;
+                }
+            }
+            else if (selector.kind === "filter") {
+                try {
+                    nodes = from
+                        ? await applyFilter(from, selector, {
+                            call: this.call,
+                            findInside: (inner, element) => this.resolveChain(inner, 1, [element]),
+                        })
+                        : [];
+                }
+                catch (err) {
+                    if (isDocumentSwap(err))
+                        return [];
+                    throw err;
+                }
+            }
             else {
                 try {
-                    nodes = await this.locateStep(selector, index > 0, nodes, index === chain.length - 1 ? max : undefined);
+                    nodes = await this.locateStep(selector, from !== undefined, from, stepLimit(chain, index, from, max));
+                    // Results per start node are not in document order, which an index into them needs
+                    if (chain[index + 1]?.kind === "nth" && (from?.length ?? 0) > 1) {
+                        nodes = await this.inDocumentOrder(nodes);
+                    }
                 }
                 catch (err) {
                     // The page is swapping documents: nothing matches right now, and the waits that poll try again
@@ -45,12 +93,36 @@ export class ChainResolver {
         }
         return nodes ?? [];
     }
+    /**
+     * `and` keeps what both chains match; `or` what either matches, in document order. Both chains search from
+     * scratch (or inside `from`, when the whole chain is relative). An `or` needs no more than `max` of each
+     */
+    async combine({ kind, left, right }, from, max) {
+        const limit = kind === "or" ? max : undefined;
+        const first = await this.resolveChain(left, limit, from);
+        const second = await this.resolveChain(right, limit, from);
+        if (kind === "and") {
+            const both = intersect(first, second);
+            return max === undefined ? both : both.slice(0, max);
+        }
+        if (first.length === 0 || second.length === 0) {
+            return (first.length === 0 ? second : first).slice(0, max);
+        }
+        const ordered = await this.inDocumentOrder(union(first, second));
+        return max === undefined ? ordered : ordered.slice(0, max);
+    }
+    async inDocumentOrder(nodes) {
+        if (nodes.length < 2)
+            return nodes;
+        return this.call(SORT_IN_DOCUMENT_ORDER, [nodes]);
+    }
     async locateStep(selector, scoped, startNodes, max) {
-        if (selector.kind === "label")
-            return this.locateInPage(LABEL_LOCATE, selector, startNodes, max);
+        const inPage = pageSearch(selector);
+        if (inPage)
+            return this.locateInPage(inPage, startNodes, max);
         if (selector.kind === "text" &&
             unsupportedTypes(this.connector).has("innerText")) {
-            return this.locateInPage(TEXT_LOCATE, selector, startNodes, max);
+            return this.locateInPage(textSearch(selector), startNodes, max);
         }
         try {
             return await this.locateNatively(selector, scoped, startNodes, max);
@@ -63,7 +135,7 @@ export class ChainResolver {
                 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);
+                    return this.locateInPage(textSearch(selector), startNodes, max);
                 }
                 throw new UnsupportedOperationError(`${describeSelector(selector, scoped)}: this kind of locator is not supported by the browser (${err.message})`);
             }
@@ -89,13 +161,11 @@ export class ChainResolver {
         }
         return [...found.values()];
     }
-    /** Runs a page-side search `(starts, value, match, ignoreCase) => elements` */
-    async locateInPage(fn, selector, startNodes, max) {
+    /** Runs a page-side search `(starts, ...args) => elements` */
+    async locateInPage({ fn, args }, startNodes, max) {
         const found = await this.call(fn, [
             startNodes ?? [],
-            selector.value,
-            selector.match,
-            selector.ignoreCase,
+            ...args,
         ]);
         return max === undefined ? found : found.slice(0, max);
     }

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

@@ -0,0 +1,15 @@
+import type { ActionOptions } from "./actionability.js";
+import { type ElementAccess } from "./element-access.js";
+export interface CheckOptions extends ActionOptions {
+    /** Wait for the element to be actionable, but do not click (and so do not change anything) */
+    trial?: boolean;
+}
+/** Which of the three public methods asked, for the messages */
+type CheckMethod = "check" | "uncheck" | "setChecked";
+/**
+ * Brings a checkbox, radio or `role=checkbox|radio|switch` element to `checked`. Already there: nothing is clicked.
+ * Otherwise waits until the control (or one of its labels, for a hidden input) can be clicked, clicks it with real
+ * pointer input and verifies the state changed.
+ */
+export declare function setChecked(access: ElementAccess, method: CheckMethod, checked: boolean, options?: CheckOptions): Promise<void>;
+export {};

package/dist/locator/check-actions.js

@@ -0,0 +1,44 @@
+import { callOnExistingElement } from "./element-access.js";
+import { clickRect } from "./input-actions.js";
+import { ATTACHED_ONLY, CLICK_CHECKS } from "./page-scripts.js";
+/** Body run in the page as `(el) => { ... }`: what kind of control the element is, and whether it is checked */
+const CONTROL_INFO_BODY = `
+  const type = (el.getAttribute("type") || "").toLowerCase();
+  const role = (el.getAttribute("role") || "").trim().split(/\\s+/)[0].toLowerCase();
+  let kind = null;
+  if (el.tagName === "INPUT" && (type === "checkbox" || type === "radio")) kind = type;
+  else if (role === "checkbox" || role === "switch" || role === "menuitemcheckbox") kind = "checkbox";
+  else if (role === "radio" || role === "menuitemradio") kind = "radio";
+  const native = el.tagName === "INPUT" && (type === "checkbox" || type === "radio");
+  return { kind, checked: native ? el.checked : el.getAttribute("aria-checked") === "true" };`;
+function readControl(access, method) {
+    return callOnExistingElement(access, CONTROL_INFO_BODY, method);
+}
+/**
+ * Brings a checkbox, radio or `role=checkbox|radio|switch` element to `checked`. Already there: nothing is clicked.
+ * Otherwise waits until the control (or one of its labels, for a hidden input) can be clicked, clicks it with real
+ * pointer input and verifies the state changed.
+ */
+export async function setChecked(access, method, checked, options) {
+    const { trial, ...action } = options ?? {};
+    await access.waitForActionable(method, ATTACHED_ONLY, { scroll: false, hitTest: false }, action);
+    const before = await readControl(access, method);
+    if (before.kind === null) {
+        throw new Error(`${method}(): element is not a checkbox, radio, or role=checkbox/radio/switch`);
+    }
+    if (before.checked === checked)
+        return;
+    if (before.kind === "radio" && !checked) {
+        throw new Error(`${method}(): a radio button cannot be unchecked`);
+    }
+    const state = await access.waitForActionable(method, 
+    // The same checks as a click; the probe's `control` mode decides what counts as the target
+    CLICK_CHECKS, { scroll: true, hitTest: true, control: true }, action);
+    if (trial)
+        return;
+    // "attached" is always required, so the box is present
+    await clickRect(access.connector, access.contextId, state.box);
+    if ((await readControl(access, method)).checked !== checked) {
+        throw new Error(`${method}(): clicking the ${before.kind} did not change its state`);
+    }
+}

package/dist/locator/combine-step.d.ts

@@ -0,0 +1,5 @@
+import type { ElementHandle } from "../script/element-handle.js";
+/** The elements in both lists, in the order of the first */
+export declare function intersect(left: readonly ElementHandle[], right: readonly ElementHandle[]): ElementHandle[];
+/** Both lists joined, each element once (the same node has the same `sharedId` in every search) */
+export declare function union(left: readonly ElementHandle[], right: readonly ElementHandle[]): ElementHandle[];

package/dist/locator/combine-step.js

@@ -0,0 +1,15 @@
+/** The elements in both lists, in the order of the first */
+export function intersect(left, right) {
+    const wanted = new Set(right.map(({ sharedId }) => sharedId));
+    return left.filter(({ sharedId }) => wanted.has(sharedId));
+}
+/** Both lists joined, each element once (the same node has the same `sharedId` in every search) */
+export function union(left, right) {
+    const seen = new Set();
+    return [...left, ...right].filter(({ sharedId }) => {
+        if (seen.has(sharedId))
+            return false;
+        seen.add(sharedId);
+        return true;
+    });
+}

package/dist/locator/control-probe.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Page-side branch of the actionability probe for checkboxes, radios and switches (`ProbeOptions.control`).
+ * These are often hidden on purpose: a native input at `opacity: 0` (or 1px, or `display: none`) with a styled
+ * `<label>` on top. A user clicks the label, so the probe accepts the input itself or any of its labels as the
+ * click target: the first one that is shown and reached by a click at its centre. The reported `box` is that
+ * target's, so the click lands where a user's would. Other actions keep the stricter probe.
+ *
+ * Runs inside `PROBE_ELEMENT` with `el` and `options` in scope; a string for the same reason it is (no helpers).
+ */
+export declare const CONTROL_PROBE_BRANCH = "\n  if (options.control) {\n    const labels = Array.from(el.labels || []);\n    const shown = (node) => {\n      const r = node.getBoundingClientRect();\n      const s = getComputedStyle(node);\n      return r.width > 0 && r.height > 0 && s.display !== \"none\" && s.visibility !== \"hidden\";\n    };\n    const candidates = [el, ...labels].filter(shown);\n    const reaches = (node, top) => node === top || node.contains(top) ||\n      (node === el && labels.some((label) => label === top || label.contains(top)));\n    const bringIntoView = (node) => {\n      const r = node.getBoundingClientRect();\n      const inside = r.top >= 0 && r.left >= 0 && r.bottom <= window.innerHeight && r.right <= window.innerWidth;\n      if (options.scroll && !inside) node.scrollIntoView({ block: \"center\", inline: \"center\" });\n    };\n    let chosen = candidates[0] || el;\n    let hitTarget = null;\n    if (options.hitTest) {\n      for (const node of candidates) {\n        bringIntoView(node);\n        const r = node.getBoundingClientRect();\n        const top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);\n        const hit = !top ? \"nothing\" : reaches(node, top) ? \"self\"\n          : top.tagName.toLowerCase() + (top.id ? \"#\" + top.id : \"\") +\n            Array.from(top.classList, (name) => \".\" + name).join(\"\");\n        if (node === candidates[0]) hitTarget = hit;\n        if (hit === \"self\") { chosen = node; hitTarget = \"self\"; break; }\n      }\n    } else if (candidates.length) {\n      bringIntoView(chosen);\n    }\n    const box = chosen.getBoundingClientRect();\n    return {\n      attached: true, visible: candidates.length > 0,\n      enabled: !el.matches(\":disabled\") && el.getAttribute(\"aria-disabled\") !== \"true\",\n      editable: false,\n      box: { x: box.left, y: box.top, width: box.width, height: box.height },\n      hitTarget,\n    };\n  }";

package/dist/locator/control-probe.js

@@ -0,0 +1,50 @@
+/**
+ * Page-side branch of the actionability probe for checkboxes, radios and switches (`ProbeOptions.control`).
+ * These are often hidden on purpose: a native input at `opacity: 0` (or 1px, or `display: none`) with a styled
+ * `<label>` on top. A user clicks the label, so the probe accepts the input itself or any of its labels as the
+ * click target: the first one that is shown and reached by a click at its centre. The reported `box` is that
+ * target's, so the click lands where a user's would. Other actions keep the stricter probe.
+ *
+ * Runs inside `PROBE_ELEMENT` with `el` and `options` in scope; a string for the same reason it is (no helpers).
+ */
+export const CONTROL_PROBE_BRANCH = `
+  if (options.control) {
+    const labels = Array.from(el.labels || []);
+    const shown = (node) => {
+      const r = node.getBoundingClientRect();
+      const s = getComputedStyle(node);
+      return r.width > 0 && r.height > 0 && s.display !== "none" && s.visibility !== "hidden";
+    };
+    const candidates = [el, ...labels].filter(shown);
+    const reaches = (node, top) => node === top || node.contains(top) ||
+      (node === el && labels.some((label) => label === top || label.contains(top)));
+    const bringIntoView = (node) => {
+      const r = node.getBoundingClientRect();
+      const inside = r.top >= 0 && r.left >= 0 && r.bottom <= window.innerHeight && r.right <= window.innerWidth;
+      if (options.scroll && !inside) node.scrollIntoView({ block: "center", inline: "center" });
+    };
+    let chosen = candidates[0] || el;
+    let hitTarget = null;
+    if (options.hitTest) {
+      for (const node of candidates) {
+        bringIntoView(node);
+        const r = node.getBoundingClientRect();
+        const top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+        const hit = !top ? "nothing" : reaches(node, top) ? "self"
+          : top.tagName.toLowerCase() + (top.id ? "#" + top.id : "") +
+            Array.from(top.classList, (name) => "." + name).join("");
+        if (node === candidates[0]) hitTarget = hit;
+        if (hit === "self") { chosen = node; hitTarget = "self"; break; }
+      }
+    } else if (candidates.length) {
+      bringIntoView(chosen);
+    }
+    const box = chosen.getBoundingClientRect();
+    return {
+      attached: true, visible: candidates.length > 0,
+      enabled: !el.matches(":disabled") && el.getAttribute("aria-disabled") !== "true",
+      editable: false,
+      box: { x: box.left, y: box.top, width: box.width, height: box.height },
+      hitTarget,
+    };
+  }`;

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

@@ -0,0 +1,24 @@
+import type { ElementHandle } from "../script/element-handle.js";
+import type { Arg } from "../script/serialize.js";
+import type { ElementContext } from "./file-actions.js";
+/** What reads and actions need of a locator: its page, its description, and finding its element */
+export interface ElementAccess extends ElementContext {
+    /**
+     * The element the locator matches first. With a `method` name and strict selectors on, several matches
+     * throw instead (`method` is the public method that asked, for the message)
+     */
+    resolveOne(method?: string): Promise<ElementHandle | null>;
+}
+/** Calls `fn` in the page; a throwing function becomes a "Failed to locate element" error */
+export declare function callInPage<T>(access: Pick<ElementAccess, "connector" | "contextId" | "selector">, fn: string, args: Arg[], sandbox?: string): Promise<T>;
+/**
+ * Calls a function on the first matching element: `body` sees it as `el`, followed by `params`.
+ * Answers `whenMissing` when nothing matches, or the element disappeared meanwhile.
+ */
+export declare function callOnElement<T>(access: ElementAccess, whenMissing: T, body: string, params?: string[], args?: Arg[], method?: string): Promise<T>;
+/** Like `callOnElement`, for operations that cannot go on without the element */
+export declare function callOnExistingElement<T>(access: ElementAccess, body: string, method?: string): Promise<T>;
+/** The error for an operation that needs an element when none matches */
+export declare function noElementError(selector: string): Error;
+/** The element the locator matches now; throws when none does */
+export declare function requireElement(access: ElementAccess): Promise<ElementHandle>;

package/dist/locator/element-access.js

@@ -0,0 +1,53 @@
+import { BiDiError } from "../transport/bidi-error.js";
+import { callFunction, ScriptError } from "../script/call-function.js";
+/** Calls `fn` in the page; a throwing function becomes a "Failed to locate element" error */
+export async function callInPage(access, fn, args, sandbox) {
+    try {
+        return await callFunction(access.connector, access.contextId, fn, args, {
+            awaitPromise: false,
+            ...(sandbox !== undefined && { sandbox }),
+        });
+    }
+    catch (err) {
+        if (err instanceof ScriptError) {
+            throw new Error(`Failed to locate element ${access.selector}. Details: ${err.text}`);
+        }
+        throw err;
+    }
+}
+/**
+ * Calls a function on the first matching element: `body` sees it as `el`, followed by `params`.
+ * Answers `whenMissing` when nothing matches, or the element disappeared meanwhile.
+ */
+export async function callOnElement(access, whenMissing, body, params = [], args = [], method) {
+    const el = await access.resolveOne(method);
+    if (!el)
+        return whenMissing;
+    try {
+        return await access.call(`(el${params.map((param) => `, ${param}`).join("")}) => { ${body} }`, [el, ...args]);
+    }
+    catch (err) {
+        if (err instanceof BiDiError && err.code === "no such node")
+            return whenMissing;
+        throw err;
+    }
+}
+/** Like `callOnElement`, for operations that cannot go on without the element */
+export async function callOnExistingElement(access, body, method) {
+    const missing = Symbol("missing");
+    const result = await callOnElement(access, missing, body, [], [], method);
+    if (result === missing)
+        throw noElementError(access.selector);
+    return result;
+}
+/** The error for an operation that needs an element when none matches */
+export function noElementError(selector) {
+    return new Error(`Failed to locate element ${selector}. Details: no element matches`);
+}
+/** The element the locator matches now; throws when none does */
+export async function requireElement(access) {
+    const el = await access.resolveOne();
+    if (!el)
+        throw noElementError(access.selector);
+    return el;
+}