@itmetsam/samurai-framework 0.21.2 → 0.21.4

package/dist/browser/page.js

@@ -1,5 +1,5 @@
 import Locator from "../locator/locator.js";
-import { cssSelector, labelSelector, roleSelector, testIdSelector, textSelector, } from "../locator/selector.js";
+import { attributeSelector, cssSelector, labelSelector, roleSelector, testIdSelector, textSelector, } from "../locator/selector.js";
 import EventEmitter from "node:events";
 import path from "node:path";
 import { projectDir } from "../config/config.js";
@@ -19,27 +19,32 @@ import { DocumentWatcher } from "./document-watcher.js";
 import { PageNavigation } from "./page-navigation.js";
 import { PageNetwork } from "./page-network.js";
 import { PageTransfers } from "./page-transfers.js";
-import { initScriptSource } from "./init-script.js";
+import { InitScripts } from "./init-script.js";
+import { grantPermission } from "./page-permissions.js";
+import { PageLocators } from "./page-locators.js";
 import { sourcesFor, waitForPageEvent, } from "./page-events.js";
 import { PageConfig, } from "./page-settings.js";
 import { applyViewport } from "./viewport.js";
 import { HelperRealm } from "../locator/helper-realm.js";
-import { addPreload } from "../script/preload.js";
 import { BiDiError } from "../transport/bidi-error.js";
 import { callFunction } from "../script/call-function.js";
+import { readContent } from "./page-content.js";
+import { evaluateInPage } from "./page-evaluate.js";
 export default class Page {
     /** `settings` override what `samurai.config.ts` says; without them the config is read when needed */
     constructor(biDiConnector, contextId, settings) {
         this.lazyTree = new Lazy();
-        this.initScripts = new Set();
+        this.initScripts = new InitScripts();
         this.pageEvents = new EventEmitter();
         this.lazyLogs = new Lazy();
         this.errorsAllowed = false;
         this.isClosed = false;
+        this.knownViewport = null;
         this.biDiConnector = biDiConnector;
         this.id = contextId;
         this.pageConfig = new PageConfig(settings);
         this.helperRealm = new HelperRealm(biDiConnector, contextId);
+        this.locators = new PageLocators(biDiConnector, contextId, this.helperRealm, this.pageConfig, () => this.assertOpen());
         this.documents = new DocumentWatcher(biDiConnector, contextId);
         this.net = new PageNetwork(biDiConnector, contextId, {
             config: this.pageConfig,
@@ -70,33 +75,57 @@ export default class Page {
     tree() {
         return this.lazyTree.get(() => ContextTree.create(this.biDiConnector));
     }
-    /** Locates an element on the page and returns an interactable object */
-    locator(xpath) {
-        return this.locate(xpath);
+    /**
+     * Locates elements on the page. An xpath (`//x`, `/html/body`, `(//x)[2]`, `./x`, `xpath=…`, or an older
+     * relative one such as `a[@id='x']`) or a css selector (`input[name='x']`, `a, button`, `css=…`).
+     * `options` filter the matches, as `locator.filter()` does
+     */
+    locator(selector, options) {
+        const found = this.locators.locate(selector);
+        return options === undefined ? found : found.filter(options);
     }
-    locate(selector) {
-        this.assertOpen();
-        return new Locator(selector, this.biDiConnector, this.id, this.helperRealm);
+    /**
+     * Makes this page's locators strict (or not): an action or read on a locator matching several elements then
+     * throws `name(): strict mode violation, N elements match ...` instead of using the first. `undefined` goes back
+     * to config `use.strictSelectors` (off unless set). Applies to locators made afterwards and to earlier ones that have not
+     * run an action or read yet: a locator keeps the answer it got at its first one
+     */
+    setStrictSelectors(enabled) {
+        this.locators.setStrictSelectors(enabled);
     }
     /** Locates elements with a CSS selector */
     getByCss(css) {
-        return this.locate([cssSelector(css)]);
+        return this.locators.locate([cssSelector(css)]);
     }
-    /** Locates elements by their text: an exact match unless `match: "partial"` */
+    /** Locates elements by their text: an exact match unless `match: "partial"` or `exact: false`; a RegExp is tested as written (see `TextOptions`) */
     getByText(text, options) {
-        return this.locate([textSelector(text, options)]);
+        return this.locators.locate([textSelector(text, options)]);
     }
-    /** Locates form controls by their label text: an exact match unless `match: "partial"` */
+    /** Locates form controls by their label text: an exact match unless `match: "partial"` or `exact: false`; a RegExp is tested as written */
     getByLabel(text, options) {
-        return this.locate([labelSelector(text, options)]);
+        return this.locators.locate([labelSelector(text, options)]);
+    }
+    /** Locates elements by their `placeholder` (see `TextOptions` for `exact` and RegExp) */
+    getByPlaceholder(text, options) {
+        return this.locators.locate([
+            attributeSelector("placeholder", text, options),
+        ]);
+    }
+    /** Locates elements by their `alt` text (images, areas, image inputs) */
+    getByAltText(text, options) {
+        return this.locators.locate([attributeSelector("alt", text, options)]);
+    }
+    /** Locates elements by their `title` attribute */
+    getByTitle(text, options) {
+        return this.locators.locate([attributeSelector("title", text, options)]);
     }
     /** Locates elements by their `data-testid` attribute */
     getByTestId(testId) {
-        return this.locate([testIdSelector(testId)]);
+        return this.locators.locate([testIdSelector(testId)]);
     }
-    /** Locates elements by ARIA role and, optionally, accessible name */
+    /** Locates elements by ARIA role and, optionally, accessible name and state (see `RoleOptions`) */
     getByRole(role, options) {
-        return this.locate([roleSelector(role, options)]);
+        return this.locators.locate([roleSelector(role, options)]);
     }
     /**
      * Runs `script` before any page script in every document this page loads from now on, and once in
@@ -109,21 +138,7 @@ export default class Page {
      */
     async addInitScript(script, arg) {
         this.assertOpen();
-        const source = initScriptSource(script, arg);
-        const handle = await addPreload(this.biDiConnector, {
-            source,
-            contexts: [this.id],
-            onRunError: "log",
-        });
-        const tracked = {
-            id: handle.id,
-            dispose: async () => {
-                this.initScripts.delete(tracked);
-                await handle.dispose();
-            },
-        };
-        this.initScripts.add(tracked);
-        return tracked;
+        return this.initScripts.add(this.biDiConnector, this.id, script, arg);
     }
     /**
      * Starts recording what a person does in the page as steps (see `Recorder`). The page must be driven by
@@ -137,7 +152,7 @@ export default class Page {
     }
     /** Removes everything the page registered in the browser: init scripts, framework helpers and event subscriptions */
     async dispose() {
-        const scripts = [...this.initScripts];
+        const scripts = this.initScripts.all();
         const results = await Promise.allSettled([
             ...scripts.map((handle) => handle.dispose()),
             this.helperRealm.dispose(),
@@ -209,11 +224,49 @@ export default class Page {
         this.assertOpen();
         return callFunction(this.biDiConnector, this.id, "() => location.href", [], { awaitPromise: false });
     }
+    /**
+     * Waits until the URL matches `url` (a string equals it, or with `*` / `**` is a glob; a RegExp is tested on it;
+     * a function gets it as a `URL`), then until the page reached `waitUntil` (default "load"). Also sees `pushState`.
+     * @example
+     *  await page.getByRole("button", { name: "Sign in" }).click();
+     *  await page.waitForURL("**\/dashboard");
+     */
+    waitForURL(url, options) {
+        return this.nav.waitForURL(url, options);
+    }
+    /** The markup of the document now, doctype included */
+    async content() {
+        this.assertOpen();
+        return readContent(this.biDiConnector, this.id);
+    }
+    /**
+     * Replaces the document with `html` and waits for `waitUntil` (default "load"). Scripts and styles in it run and apply;
+     * the page keeps its URL and origin (it is not a `data:` page).
+     * @example
+     *  await page.setContent("<button>Go</button><script>document.title = 'x'</script>");
+     */
+    async setContent(html, options) {
+        return this.nav.setContent(html, options);
+    }
     /** The title of the document now */
     async title() {
         this.assertOpen();
         return callFunction(this.biDiConnector, this.id, "() => document.title", [], { awaitPromise: false });
     }
+    /**
+     * Runs `fn` in the page, with `arg` as its only argument, and returns the result (a promise is awaited). `fn` is a function,
+     * the source of one (`"async () => ..."`), or any other string, which is an expression (`"document.title"`; it takes no argument).
+     * Values come back as plain JavaScript: Date, Map, Set, RegExp, BigInt, NaN, undefined, nested objects and arrays;
+     * an element as an `ElementHandle`; what cannot be copied (a function, window, error, promise) as a `RemoteObject` with its `type`.
+     * The page's own error message is kept (`ScriptError`). A function written under tsx must not contain named inner functions
+     * (the transpiler adds a `__name` helper the page lacks); a string always works.
+     * @example
+     *  const count = await page.evaluate((min) => document.querySelectorAll("li").length > min, 3);
+     */
+    async evaluate(fn, arg) {
+        this.assertOpen();
+        return evaluateInPage(this.biDiConnector, this.id, fn, arg);
+    }
     /**
      * Sets the size of the viewport (and, optionally, the device pixel ratio); `null` puts the browser's own size back.
      * @example
@@ -222,6 +275,21 @@ export default class Page {
     async setViewport(viewport) {
         this.assertOpen();
         await applyViewport(this.biDiConnector, this.id, viewport);
+        this.knownViewport = viewport && {
+            width: viewport.width,
+            height: viewport.height,
+        };
+    }
+    /** Playwright's name for `setViewport` */
+    setViewportSize(size) {
+        return this.setViewport(size);
+    }
+    /**
+     * The size this page was last given (`setViewport`, `setViewportSize`, or the default from config `use.viewport` when the
+     * browser opened it), read at once; null before one is known, after `setViewport(null)` and when config turns the viewport off.
+     */
+    viewportSize() {
+        return this.knownViewport && { ...this.knownViewport };
     }
     /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
     async applyDefaultViewport() {
@@ -302,17 +370,7 @@ export default class Page {
      */
     async grantPermission(name, options = {}) {
         this.assertOpen();
-        const origin = options.origin ?? new URL(await this.url()).origin;
-        // about:blank and data: pages have no origin to grant to
-        if (origin === "null")
-            throw new Error("grantPermission(): needs a page on a web origin, or an explicit origin option");
-        const context = this.browserContext;
-        await this.biDiConnector.send("permissions.setPermission", {
-            descriptor: { name },
-            state: "granted",
-            origin,
-            ...(context && !context.isDefault && { userContext: context.id }),
-        });
+        await grantPermission(this.biDiConnector, () => this.url(), () => this.browserContext, name, options);
     }
     /** True once `close()` has run */
     get closed() {

package/dist/config/variables.js

@@ -18,7 +18,8 @@ export function isPassthroughKey(target, key) {
 export function createEnvFixture(environment, variables) {
     return new Proxy(Object.freeze({ ...variables }), {
         get(target, key, receiver) {
-            if (isPassthroughKey(target, key) || Object.prototype.hasOwnProperty.call(target, key))
+            if (isPassthroughKey(target, key) ||
+                Object.prototype.hasOwnProperty.call(target, key))
                 return Reflect.get(target, key, receiver);
             throw new UnknownVariableError(String(key), environment);
         },

package/dist/locator/accessible-name.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare const ACCESSIBLE_NAME_JS: string;

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;
 }