@itmetsam/samurai-framework 0.21.4 → 0.22.0

package/dist/locator/input-actions.js

@@ -1,47 +1,10 @@
 /** 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";
+// (a touch pointer is a source of its own, with its own id)
+export const POINTER_ID = "samurai-pointer";
+export 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", {
@@ -51,22 +14,6 @@ export async function pause(connector, context, 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) => [

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

@@ -0,0 +1,11 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { KeySourceAction } from "../types/bidi-modules/input.js";
+import { type KeyChord } from "./key-map.js";
+/** Sends `actions` to the page's keyboard; BiDi remembers which keys are down between calls */
+export declare function performKeys(connector: BiDiConnector, context: string, actions: KeySourceAction[]): Promise<void>;
+/** The modifiers down, the key down and up (`delay` ms apart), the modifiers up again in reverse order */
+export declare function chordSteps(chord: KeyChord, delay?: number): KeySourceAction[];
+/** One key press per character (a line break is Enter, a tab is Tab), `delay` ms between characters */
+export declare function textSteps(text: string, delay?: number): KeySourceAction[];
+/** Holds `modifiers` down while `action` runs, and lets go of them afterwards even when it throws */
+export declare function withModifiers<T>(connector: BiDiConnector, context: string, modifiers: readonly string[], action: () => Promise<T>): Promise<T>;

package/dist/locator/key-actions.js

@@ -0,0 +1,52 @@
+import { KEYBOARD_ID } from "./input-actions.js";
+import { NAMED_KEYS } from "./key-map.js";
+/** Sends `actions` to the page's keyboard; BiDi remembers which keys are down between calls */
+export async function performKeys(connector, context, actions) {
+    if (actions.length === 0)
+        return;
+    await connector.send("input.performActions", {
+        context,
+        actions: [{ type: "key", id: KEYBOARD_ID, actions }],
+    });
+}
+const pauseFor = (delay) => delay > 0 ? [{ type: "pause", duration: delay }] : [];
+/** The modifiers down, the key down and up (`delay` ms apart), the modifiers up again in reverse order */
+export function chordSteps(chord, delay = 0) {
+    return [
+        ...chord.modifiers.map((value) => ({ type: "keyDown", value })),
+        { type: "keyDown", value: chord.key },
+        ...pauseFor(delay),
+        { type: "keyUp", value: chord.key },
+        ...[...chord.modifiers]
+            .reverse()
+            .map((value) => ({ type: "keyUp", value })),
+    ];
+}
+/** One key press per character (a line break is Enter, a tab is Tab), `delay` ms between characters */
+export function textSteps(text, delay = 0) {
+    const chars = Array.from(text);
+    return chars.flatMap((char, index) => {
+        const value = char === "\n" || char === "\r"
+            ? NAMED_KEYS.Enter
+            : char === "\t"
+                ? NAMED_KEYS.Tab
+                : char;
+        return [
+            { type: "keyDown", value },
+            { type: "keyUp", value },
+            ...(index < chars.length - 1 ? pauseFor(delay) : []),
+        ];
+    });
+}
+/** Holds `modifiers` down while `action` runs, and lets go of them afterwards even when it throws */
+export async function withModifiers(connector, context, modifiers, action) {
+    if (modifiers.length === 0)
+        return action();
+    await performKeys(connector, context, modifiers.map((value) => ({ type: "keyDown", value })));
+    try {
+        return await action();
+    }
+    finally {
+        await performKeys(connector, context, [...modifiers].reverse().map((value) => ({ type: "keyUp", value })));
+    }
+}

package/dist/locator/key-map.d.ts

@@ -0,0 +1,16 @@
+/** WebDriver code points of the named keys; any other single character is typed as is */
+export declare const NAMED_KEYS: Readonly<Record<string, string>>;
+/** The modifier names `click`, `hover` and key chords accept; `ControlOrMeta` is Meta on macOS and Control elsewhere */
+export type Modifier = "Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift";
+/** One key with the modifiers held while it is pressed, as WebDriver code points or characters */
+export interface KeyChord {
+    modifiers: string[];
+    key: string;
+}
+/** The code points of `modifiers`; `method` names the public method for the error */
+export declare function modifierCodes(modifiers: readonly Modifier[], platform?: string, method?: string): string[];
+/**
+ * Reads a key such as `a`, `Enter` or a chord such as `Control+a`, `Shift+Tab`, `ControlOrMeta+Enter`: modifiers
+ * joined by `+`, then one key (which may be `+` itself: `Control++`). `method` names the public method for errors.
+ */
+export declare function parseKeyChord(spec: string, method: string, platform?: string): KeyChord;

package/dist/locator/key-map.js

@@ -0,0 +1,76 @@
+/** WebDriver code points of the named keys; any other single character is typed as is */
+export const NAMED_KEYS = {
+    Backspace: "",
+    Tab: "",
+    Enter: "",
+    Escape: "",
+    Space: " ",
+    ArrowLeft: "",
+    ArrowUp: "",
+    ArrowRight: "",
+    ArrowDown: "",
+    Delete: "",
+    Home: "",
+    End: "",
+    PageUp: "",
+    PageDown: "",
+    Insert: "",
+    ...Object.fromEntries(Array.from({ length: 12 }, (_, i) => [
+        `F${i + 1}`,
+        String.fromCharCode(0xe031 + i),
+    ])),
+};
+const MODIFIER_KEYS = {
+    Control: "",
+    Shift: "",
+    Alt: "",
+    Meta: "",
+};
+/** The code points of `modifiers`; `method` names the public method for the error */
+export function modifierCodes(modifiers, platform = process.platform, method = "click") {
+    return modifiers.map((name) => {
+        if (name === "ControlOrMeta") {
+            return platform === "darwin"
+                ? MODIFIER_KEYS.Meta
+                : MODIFIER_KEYS.Control;
+        }
+        const code = MODIFIER_KEYS[name];
+        if (code === undefined) {
+            throw new Error(`${method}(): unknown modifier "${name}"`);
+        }
+        return code;
+    });
+}
+function keyCode(name, method) {
+    const code = NAMED_KEYS[name] ??
+        MODIFIER_KEYS[name] ??
+        (/^Key[A-Za-z]$/.test(name) ? name.slice(3).toLowerCase() : undefined) ??
+        (/^Digit\d$/.test(name) ? name.slice(5) : undefined) ??
+        (Array.from(name).length === 1 ? name : undefined);
+    if (code === undefined) {
+        throw new Error(`${method}(): unknown key "${name}". Use a named key such as Enter, Tab or ArrowDown, a single character, or a chord like Control+a`);
+    }
+    return code;
+}
+/**
+ * Reads a key such as `a`, `Enter` or a chord such as `Control+a`, `Shift+Tab`, `ControlOrMeta+Enter`: modifiers
+ * joined by `+`, then one key (which may be `+` itself: `Control++`). `method` names the public method for errors.
+ */
+export function parseKeyChord(spec, method, platform = process.platform) {
+    if (spec === "+")
+        return { modifiers: [], key: "+" };
+    const parts = spec.split("+");
+    // "Control++" splits into a trailing empty pair: the last key is the plus sign
+    const key = spec.endsWith("++") ? "+" : parts[parts.length - 1];
+    const names = parts.slice(0, spec.endsWith("++") ? -2 : -1);
+    const modifiers = names.map((name) => {
+        if (!(name in MODIFIER_KEYS) && name !== "ControlOrMeta") {
+            throw new Error(`${method}(): "${name}" is not a modifier. A chord is modifiers followed by one key, like Control+a`);
+        }
+        return name;
+    });
+    return {
+        modifiers: modifierCodes(modifiers, platform, method),
+        key: keyCode(key, method),
+    };
+}

package/dist/locator/locator.d.ts

@@ -6,6 +6,8 @@ import type { ElementScreenshotOptions } from "../browser/screenshot.js";
 import type { FileInput } from "../browser/generated-files.js";
 import { type ActionOptions } from "./actionability.js";
 import { type CheckOptions } from "./check-actions.js";
+import { type DragOptions } from "./drag-actions.js";
+import { type ClickOptions, type PointerOptions } from "./pointer-element-actions.js";
 import { type BoundingBox } from "./element-reads.js";
 import type { WaitForState } from "./element-state.js";
 import type { HelperInstaller } from "./helper-realm.js";
@@ -45,6 +47,8 @@ export default class Locator {
     get selector(): string;
     /** Steps that keep the fallbacks: each fallback gets the same step, so "inside A or B" stays meaningful */
     private child;
+    /** A locator on the same page and helpers, with the given parts replaced */
+    private copy;
     /**
      * A locator that tries this one first and, whenever it matches nothing, each of `fallbacks` in order;
      * the first one with a match wins. For steps with several ways to find the same element (a test id,
@@ -130,8 +134,30 @@ export default class Locator {
      */
     private resolveOne;
     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>;
+    /**
+     * Waits until the element is attached, visible, stable, enabled and not covered, then clicks it with real pointer
+     * input: its centre, or `position` (pixels from its top left corner). `button`, `clickCount`, `delay` (ms between press
+     * and release) and `modifiers` (keys held down) are as in Playwright
+     */
+    click(options?: ClickOptions): Promise<void>;
+    /** `click` with `clickCount: 2` */
+    dblclick(options?: ClickOptions): Promise<void>;
+    /** Waits until the element is attached, visible, stable and not covered, then moves the mouse onto it (`:hover`, `mouseover`, tooltips) */
+    hover(options?: PointerOptions): Promise<void>;
+    /** Waits like `click`, then touches the element with a touch pointer: `touchstart`, `touchend`, then the mouse events a tap ends in */
+    tap(options?: PointerOptions): Promise<void>;
+    /** Drags this element onto `target` with real pointer input; `sourcePosition`, `targetPosition` and `steps` shape the gesture. Firefox needs synthetic drop events, see the wiki */
+    dragTo(target: Locator, options?: DragOptions): Promise<void>;
+    /** Waits until the element is attached, then fires a synthetic event (`click`, `keydown`, ...; the class follows the type) at it, bubbling and composed */
+    dispatchEvent(type: string, eventInit?: Record<string, unknown>, options?: ActionOptions): Promise<void>;
+    /** Waits until the element is attached, then removes focus from it */
+    blur(options?: ActionOptions): Promise<void>;
+    /** Empties an input, textarea or editable element, as `fill("")` does */
+    clear(options?: ActionOptions): Promise<void>;
+    /** Focuses the element and types `text` into it one key press at a time, `delay` ms apart */
+    pressSequentially(text: string, options?: ActionOptions & {
+        delay?: number;
+    }): Promise<void>;
     /**
      * Checks a checkbox, radio or `role=checkbox|radio|switch` element; does nothing when it is already checked.
      * Waits like `click`, but a hidden input counts as reachable through its `<label>`, which is what gets clicked.
@@ -250,12 +276,16 @@ export default class Locator {
     wait(duration?: number): Promise<void>;
     /**
      * Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input.
-     * Named keys are `Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `Space`, `Home`, `End`, `PageUp`, `PageDown` and the arrows;
-     * any other key must be a single character.
+     * Named keys are `Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `Space`, `Insert`, `Home`, `End`, `PageUp`, `PageDown`,
+     * `F1` to `F12` and the arrows; any other key must be a single character. A chord holds modifiers (`Control`, `Shift`,
+     * `Alt`, `Meta`, `ControlOrMeta`) while the last key is pressed.
      * @example
      *  await page.getByLabel("New todo").press("Enter");
+     *  await page.getByLabel("Name").press("Control+a");
      */
-    press(key: string, options?: ActionOptions): Promise<void>;
+    press(key: string, options?: ActionOptions & {
+        delay?: number;
+    }): Promise<void>;
     /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
     fill(value: string, options?: ActionOptions & {
         output?: string;

package/dist/locator/locator.js

@@ -3,7 +3,10 @@ import { waitForActionable, waitForState, } from "./actionability.js";
 import { setChecked } from "./check-actions.js";
 import { ChainResolver } from "./chain-resolver.js";
 import { callInPage, noElementError, requireElement, } from "./element-access.js";
-import { clickElement, fillElement, focusElement, pressOnElement, screenshotElement, } from "./element-actions.js";
+import { clearElement, fillElement, focusElement, pressOnElement, pressSequentially, screenshotElement, } from "./element-actions.js";
+import { dragElement } from "./drag-actions.js";
+import { blurElement, dispatchEventOn } from "./event-actions.js";
+import { clickElement, hoverElement, tapElement, } from "./pointer-element-actions.js";
 import { readAccessibleDescription, readAccessibleName, readAllInnerTexts, readAllTextContents, readAttribute, readBoundingBox, readBoundingClientRect, readClassAttribute, readCssValue, readEnabledState, readInnerHTML, readInnerText, readInputValue, readIsChecked, readIsEditable, readIsEnabled, readIsVisible, readTextContent, } from "./element-reads.js";
 import { evaluateOnAll, evaluateOnElement } from "./evaluate.js";
 import { dropFiles, setInputFiles } from "./file-actions.js";
@@ -65,7 +68,14 @@ export default class Locator {
     }
     /** Steps that keep the fallbacks: each fallback gets the same step, so "inside A or B" stays meaningful */
     child(step) {
-        return new Locator([...this.chain, step], this.biDiConnector, this.contextId, this.helpers, this.alternatives.map((alt) => alt.child(step)), this.strictness);
+        return this.copy({
+            chain: [...this.chain, step],
+            alternatives: this.alternatives.map((alt) => alt.child(step)),
+        });
+    }
+    /** A locator on the same page and helpers, with the given parts replaced */
+    copy(parts = {}) {
+        return new Locator(parts.chain ?? this.chain, this.biDiConnector, this.contextId, this.helpers, parts.alternatives ?? this.alternatives, parts.strictness ?? this.strictness);
     }
     /**
      * A locator that tries this one first and, whenever it matches nothing, each of `fallbacks` in order;
@@ -76,7 +86,7 @@ export default class Locator {
      *  page.getByTestId("save").withFallbacks(page.getByRole("button", { name: "Save" }), page.getByText("Save"));
      */
     withFallbacks(...fallbacks) {
-        return new Locator(this.chain, this.biDiConnector, this.contextId, this.helpers, [...this.alternatives, ...fallbacks], this.strictness);
+        return this.copy({ alternatives: [...this.alternatives, ...fallbacks] });
     }
     /**
      * This locator, strict or not whatever the page and the config say: a strict locator makes actions and reads
@@ -86,7 +96,7 @@ export default class Locator {
      *  await page.locator("li").strict().click(); // throws when there is more than one li
      */
     strict(enabled = true) {
-        return new Locator(this.chain, this.biDiConnector, this.contextId, this.helpers, this.alternatives, () => Promise.resolve(enabled));
+        return this.copy({ strictness: () => Promise.resolve(enabled) });
     }
     /**
      * Which locator found elements the last time this one searched: index 0 is the primary, 1 the first
@@ -162,13 +172,16 @@ export default class Locator {
         if (other.contextId !== this.contextId) {
             throw new TypeError(`${kind}(): the locators belong to different pages`);
         }
-        return new Locator([
-            {
-                kind,
-                left: this.chainFor(`${kind}()`, "an operand"),
-                right: other.chainFor(`${kind}()`, "an operand"),
-            },
-        ], this.biDiConnector, this.contextId, this.helpers, [], this.strictness);
+        return this.copy({
+            chain: [
+                {
+                    kind,
+                    left: this.chainFor(`${kind}()`, "an operand"),
+                    right: other.chainFor(`${kind}()`, "an operand"),
+                },
+            ],
+            alternatives: [],
+        });
     }
     /** The chain of a locator used inside another (`has`); a locator with fallbacks cannot be */
     chainFor(method, role) {
@@ -196,7 +209,10 @@ export default class Locator {
         const only = this.chain.length === 1 ? this.chain[0] : undefined;
         return Array.from({ length: count }, (_, index) => only?.kind === "xpath"
             ? // A positional xpath keeps working without a second search for the whole chain
-                new Locator(`(${describeSelector(only, false)})[${index + 1}]`, this.biDiConnector, this.contextId, this.helpers, [], this.strictness)
+                this.copy({
+                    chain: `(${describeSelector(only, false)})[${index + 1}]`,
+                    alternatives: [],
+                })
             : this.child({ kind: "nth", index }));
     }
     /**
@@ -232,7 +248,7 @@ export default class Locator {
         return undefined;
     }
     withoutFallbacks() {
-        return new Locator(this.chain, this.biDiConnector, this.contextId, this.helpers, [], this.strictness);
+        return this.copy({ alternatives: [] });
     }
     /**
      * The element the locator matches first. With a `method` name and strict selectors on, several matches
@@ -252,10 +268,46 @@ export default class Locator {
     waitForActionable(action, checks, probe, options) {
         return waitForActionable(this.actionability, action, checks, probe, options);
     }
-    /** Waits until the element is attached, visible, stable, enabled and not covered, then clicks its centre with real pointer input */
+    /**
+     * Waits until the element is attached, visible, stable, enabled and not covered, then clicks it with real pointer
+     * input: its centre, or `position` (pixels from its top left corner). `button`, `clickCount`, `delay` (ms between press
+     * and release) and `modifiers` (keys held down) are as in Playwright
+     */
     async click(options) {
         await clickElement(this.access, options);
     }
+    /** `click` with `clickCount: 2` */
+    async dblclick(options) {
+        await clickElement(this.access, { ...options, clickCount: 2 }, "dblclick");
+    }
+    /** Waits until the element is attached, visible, stable and not covered, then moves the mouse onto it (`:hover`, `mouseover`, tooltips) */
+    async hover(options) {
+        await hoverElement(this.access, options);
+    }
+    /** Waits like `click`, then touches the element with a touch pointer: `touchstart`, `touchend`, then the mouse events a tap ends in */
+    async tap(options) {
+        await tapElement(this.access, options);
+    }
+    /** Drags this element onto `target` with real pointer input; `sourcePosition`, `targetPosition` and `steps` shape the gesture. Firefox needs synthetic drop events, see the wiki */
+    async dragTo(target, options) {
+        await dragElement(this.access, target.access, options);
+    }
+    /** Waits until the element is attached, then fires a synthetic event (`click`, `keydown`, ...; the class follows the type) at it, bubbling and composed */
+    async dispatchEvent(type, eventInit, options) {
+        await dispatchEventOn(this.access, type, eventInit, options);
+    }
+    /** Waits until the element is attached, then removes focus from it */
+    async blur(options) {
+        await blurElement(this.access, options);
+    }
+    /** Empties an input, textarea or editable element, as `fill("")` does */
+    async clear(options) {
+        await clearElement(this.access, options);
+    }
+    /** Focuses the element and types `text` into it one key press at a time, `delay` ms apart */
+    async pressSequentially(text, options) {
+        await pressSequentially(this.access, text, options);
+    }
     /**
      * Checks a checkbox, radio or `role=checkbox|radio|switch` element; does nothing when it is already checked.
      * Waits like `click`, but a hidden input counts as reachable through its `<label>`, which is what gets clicked.
@@ -431,10 +483,12 @@ export default class Locator {
     }
     /**
      * Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input.
-     * Named keys are `Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `Space`, `Home`, `End`, `PageUp`, `PageDown` and the arrows;
-     * any other key must be a single character.
+     * Named keys are `Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `Space`, `Insert`, `Home`, `End`, `PageUp`, `PageDown`,
+     * `F1` to `F12` and the arrows; any other key must be a single character. A chord holds modifiers (`Control`, `Shift`,
+     * `Alt`, `Meta`, `ControlOrMeta`) while the last key is pressed.
      * @example
      *  await page.getByLabel("New todo").press("Enter");
+     *  await page.getByLabel("Name").press("Control+a");
      */
     async press(key, options) {
         await pressOnElement(this.access, key, options);

package/dist/locator/page-scripts.d.ts

@@ -11,6 +11,8 @@ export declare const DROP_INPUT = "() => {\n  const input = document.createEleme
 export declare const DROP_EVENTS = "(el, types) => {\n  const input = globalThis[Symbol.for(\"samurai.drop\")];\n  delete globalThis[Symbol.for(\"samurai.drop\")];\n  const data = new DataTransfer();\n  Array.from(input.files).forEach((file, i) => {\n    data.items.add(types[i] ? new File([file], file.name, { type: types[i], lastModified: file.lastModified }) : file);\n  });\n  const box = el.getBoundingClientRect();\n  const at = { clientX: box.left + box.width / 2, clientY: box.top + box.height / 2 };\n  for (const type of [\"dragenter\", \"dragover\", \"drop\"]) {\n    el.dispatchEvent(new DragEvent(type, Object.assign({ bubbles: true, cancelable: true, composed: true, dataTransfer: data }, at)));\n  }\n}";
 export declare const SCREENSHOT_CHECKS: readonly CheckName[];
 export declare const CLICK_CHECKS: readonly CheckName[];
+/** `hover`: the pointer only moves, so the element need not be enabled */
+export declare const HOVER_CHECKS: readonly CheckName[];
 /** `selectOption`: a select is not clicked, so it need not be stable or uncovered */
 export declare const SELECT_CHECKS: readonly CheckName[];
 export declare const FILL_CHECKS: readonly CheckName[];

package/dist/locator/page-scripts.js

@@ -39,6 +39,13 @@ export const CLICK_CHECKS = [
     "enabled",
     "hit target",
 ];
+/** `hover`: the pointer only moves, so the element need not be enabled */
+export const HOVER_CHECKS = [
+    "attached",
+    "visible",
+    "stable",
+    "hit target",
+];
 /** `selectOption`: a select is not clicked, so it need not be stable or uncovered */
 export const SELECT_CHECKS = [
     "attached",

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

@@ -0,0 +1,44 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { PointerButton, PointerSourceAction } from "../types/bidi-modules/input.js";
+export interface Point {
+    x: number;
+    y: number;
+}
+type Rect = Point & {
+    width: number;
+    height: number;
+};
+export type MouseButton = "left" | "middle" | "right";
+/** What a click does beyond a plain left click */
+export interface PointerClickOptions {
+    button?: MouseButton;
+    /** Presses in a row: 2 is a double click (default 1) */
+    clickCount?: number;
+    /** Milliseconds between a press and its release (default 0) */
+    delay?: number;
+}
+/** The BiDi number of a mouse button; `method` names the public method for the error */
+export declare function buttonCode(button: MouseButton | undefined, method: string): PointerButton;
+/** The viewport point `position` (from the rect's top left corner) names; the centre without one */
+export declare function pointInRect(rect: Rect, position?: Point): Point;
+/** `steps` pointer moves in a straight line from `from` to `to`, the last one on `to` */
+export declare function moveSteps(from: Point, to: Point, steps?: number): PointerSourceAction[];
+/** Sends `actions` to the page's mouse, or to its touch pointer; BiDi remembers the position and the pressed buttons */
+export declare function performPointer(connector: BiDiConnector, context: string, actions: PointerSourceAction[], touch?: boolean): Promise<void>;
+/** Checks a click's `button` and `clickCount` before anything is sent; answers the button's BiDi number */
+export declare function checkClick({ button, clickCount }: PointerClickOptions, method: string): PointerButton;
+/** Press and release `clickCount` times at `point`, `delay` ms between each press and release */
+export declare function clickSteps(point: Point, { button, clickCount, delay }?: PointerClickOptions, method?: string): PointerSourceAction[];
+/** Clicks `point` (viewport pixels) with real pointer input */
+export declare function pointerClick(connector: BiDiConnector, context: string, point: Point, options?: PointerClickOptions, method?: string): Promise<void>;
+/** Clicks the centre of `rect` (viewport pixels) with real pointer input */
+export declare function clickRect(connector: BiDiConnector, context: string, rect: Rect): Promise<void>;
+/** Moves the mouse to `point` (viewport pixels) */
+export declare function pointerMoveTo(connector: BiDiConnector, context: string, point: Point): Promise<void>;
+/** Touches and lifts a finger at `point` (viewport pixels) */
+export declare function pointerTap(connector: BiDiConnector, context: string, point: Point): Promise<void>;
+/** Presses on `from`, moves to `to` in `steps` moves and releases there */
+export declare function pointerDrag(connector: BiDiConnector, context: string, from: Point, to: Point, steps: number): Promise<void>;
+/** Turns the mouse wheel at `point` by `deltaX` and `deltaY` pixels */
+export declare function wheelScroll(connector: BiDiConnector, context: string, point: Point, deltaX: number, deltaY: number): Promise<void>;
+export {};

package/dist/locator/pointer-actions.js

@@ -0,0 +1,117 @@
+import { POINTER_ID } from "./input-actions.js";
+const TOUCH_ID = "samurai-touch";
+const WHEEL_ID = "samurai-wheel";
+const BUTTONS = {
+    left: 0,
+    middle: 1,
+    right: 2,
+};
+/** The BiDi number of a mouse button; `method` names the public method for the error */
+export function buttonCode(button = "left", method) {
+    const code = BUTTONS[button];
+    if (code === undefined) {
+        throw new Error(`${method}(): unknown button "${button}". Use left, middle or right`);
+    }
+    return code;
+}
+/** The viewport point `position` (from the rect's top left corner) names; the centre without one */
+export function pointInRect(rect, position) {
+    return position
+        ? { x: rect.x + position.x, y: rect.y + position.y }
+        : { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+}
+/** `steps` pointer moves in a straight line from `from` to `to`, the last one on `to` */
+export function moveSteps(from, to, steps = 1) {
+    const count = Math.max(1, Math.floor(steps));
+    return Array.from({ length: count }, (_, index) => ({
+        type: "pointerMove",
+        x: from.x + ((to.x - from.x) * (index + 1)) / count,
+        y: from.y + ((to.y - from.y) * (index + 1)) / count,
+    }));
+}
+/** Sends `actions` to the page's mouse, or to its touch pointer; BiDi remembers the position and the pressed buttons */
+export async function performPointer(connector, context, actions, touch = false) {
+    await connector.send("input.performActions", {
+        context,
+        actions: [
+            {
+                type: "pointer",
+                id: touch ? TOUCH_ID : POINTER_ID,
+                parameters: { pointerType: touch ? "touch" : "mouse" },
+                actions,
+            },
+        ],
+    });
+}
+const pauseFor = (delay) => delay > 0 ? [{ type: "pause", duration: delay }] : [];
+/** Checks a click's `button` and `clickCount` before anything is sent; answers the button's BiDi number */
+export function checkClick({ button, clickCount = 1 }, method) {
+    const code = buttonCode(button, method);
+    if (!Number.isInteger(clickCount) || clickCount < 1) {
+        throw new Error(`${method}(): clickCount must be a whole number, 1 or more`);
+    }
+    return code;
+}
+/** Press and release `clickCount` times at `point`, `delay` ms between each press and release */
+export function clickSteps(point, { button, clickCount = 1, delay = 0 } = {}, method = "click") {
+    const code = checkClick({ button, clickCount }, method);
+    return [
+        { type: "pointerMove", x: point.x, y: point.y },
+        ...Array.from({ length: clickCount }, () => [
+            { type: "pointerDown", button: code },
+            ...pauseFor(delay),
+            { type: "pointerUp", button: code },
+        ]).flat(),
+    ];
+}
+/** Clicks `point` (viewport pixels) with real pointer input */
+export async function pointerClick(connector, context, point, options, method = "click") {
+    await performPointer(connector, context, clickSteps(point, options, method));
+}
+/** Clicks the centre of `rect` (viewport pixels) with real pointer input */
+export async function clickRect(connector, context, rect) {
+    await pointerClick(connector, context, pointInRect(rect));
+}
+/** Moves the mouse to `point` (viewport pixels) */
+export async function pointerMoveTo(connector, context, point) {
+    await performPointer(connector, context, moveSteps(point, point));
+}
+/** Touches and lifts a finger at `point` (viewport pixels) */
+export async function pointerTap(connector, context, point) {
+    await performPointer(connector, context, [
+        { type: "pointerMove", x: point.x, y: point.y },
+        { type: "pointerDown", button: 0 },
+        { type: "pointerUp", button: 0 },
+    ], true);
+}
+/** Presses on `from`, moves to `to` in `steps` moves and releases there */
+export async function pointerDrag(connector, context, from, to, steps) {
+    await performPointer(connector, context, [
+        { type: "pointerMove", x: from.x, y: from.y },
+        { type: "pointerDown", button: 0 },
+        ...moveSteps(from, to, steps),
+        { type: "pointerUp", button: 0 },
+    ]);
+}
+/** Turns the mouse wheel at `point` by `deltaX` and `deltaY` pixels */
+export async function wheelScroll(connector, context, point, deltaX, deltaY) {
+    await connector.send("input.performActions", {
+        context,
+        actions: [
+            {
+                type: "wheel",
+                id: WHEEL_ID,
+                actions: [
+                    {
+                        type: "scroll",
+                        x: Math.round(point.x),
+                        y: Math.round(point.y),
+                        deltaX: Math.round(deltaX),
+                        deltaY: Math.round(deltaY),
+                        origin: "viewport",
+                    },
+                ],
+            },
+        ],
+    });
+}