clearcote 0.47.0 → 0.48.0

package/dist/humanize.js

@@ -4,13 +4,15 @@
 //   dragging, scrolling and typing — dispatched as native trusted input (isTrusted===true,
 //   navigator.webdriver stays false). It works whether you drive the page directly or via
 //   locators:
-//     page level    — page.click / hover / dblclick / type / fill / press / selectOption,
-//                      page.mouse.move / click / wheel and held-button drags (down -> move -> up),
-//                      page.keyboard.type / press
+//     page level    — page.click / hover / dblclick / type / fill / press / selectOption /
+//                      check / uncheck / setChecked,
+//                      page.mouse.move / click / dblclick / wheel and held-button drags
+//                      (down -> move -> up), page.keyboard.type / press
 //     locator level  — locator.click / type / fill / hover / dblclick / press /
-//                      pressSequentially / clear / check / uncheck / tap / selectOption / dragTo
+//                      pressSequentially / clear / check / uncheck / setChecked / tap /
+//                      selectOption / dragTo
 //                      (routed through the humanized page methods; main-frame locators only,
-//                      native fallback)
+//                      STRICT like Playwright, native fallback)
 // `showCursor: true` — injects a red cursor dot that follows the real mousemove events.
 //
 // Mouse moves build an eased, slightly bowed cubic-bezier path SDK-side from the tracked cursor
@@ -19,8 +21,14 @@
 // (slider captchas work) with no separate CDP channel to desync. Typing goes key-by-key through
 // the native keyboard (trusted; shift handled by the engine) with human inter-key timing. No
 // special binary command required.
+//
+// Form input follows sdk/python/clearcote/_humanize.py (the reference); WHAT to press comes from
+// ./forms.ts (shared test vectors with Python and .NET), HOW comes from this file. Every DOM read
+// goes through the isolated world (./isolated.ts) or Playwright's utility-world queries, never
+// page.evaluate / locator.evaluate.
 import { makePersona, planMove, dragDwell, clickHold, keyDwell, clickPoint, planAmbient, gaussFrom, rolloverRate, wheelNotches, platformFromNavigator, WHEEL_NOTCH_PX, } from "./motion.js";
-import { COVER_CHECK_MS, ISO_IS_FOCUSED, ISO_PLATFORM, ISO_SELECT_PLAN, ISO_SELECTED_INDEX, ISO_VIEWPORT, worldFor } from "./isolated.js";
+import { COVER_CHECK_MS, COVER_RETRY_MS, ISO_ACTIVE_FIELD, ISO_ACTIVE_VALUE, ISO_CSS_BOX, ISO_DESCRIBE, ISO_FORM_CONTROL, ISO_HIT_IN_BOX, ISO_LISTBOX_ROW, ISO_PLATFORM, ISO_SCROLL_BY, ISO_VIEWPORT, worldFor, } from "./isolated.js";
+import { DEFAULT_TYPO_RATE, NEARBY_LETTERS, classifyField, datetimeEqual, enginePathOk, formattedEqual, matchOption, normalizeClickOptions, numericEqual, planDatetime, planSelect, planTypo, pyFloat, rangeAttrs, rangeFraction, rangeNudge, rangePoint, rangeSanitize, rangeValueOk, segmentNodesFromTree, typoEligible, typosAllowed, } from "./forms.js";
 /** Overlay: a red dot that follows real mousemove events. Idempotent IIFE so it works both as
  * an addInitScript source string AND when passed to page.evaluate. */
 export const CURSOR_OVERLAY = `(() => {
@@ -95,23 +103,46 @@ const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
 // for placing a point in a plausible spread instead of on an exact landmark.
 const gauss = () => gaussFrom(Math.random);
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-// Compact keyboard-adjacency map for realistic fat-finger typos.
-const NEARBY = {
-    a: "sqwz", b: "vghn", c: "xdfv", d: "sfecx", e: "wrsdf", f: "dgrtcv",
-    g: "fhtyb", h: "gjybn", i: "ujko", j: "hkunm", k: "jloi", l: "kop",
-    m: "njk", n: "bhjm", o: "iklp", p: "ol", q: "wa", r: "edft",
-    s: "awedxz", t: "rfgy", u: "yhji", v: "cfgb", w: "qase", x: "zsdc",
-    y: "tghu", z: "asx",
-};
-function nearbyKey(ch) {
-    const lo = ch.toLowerCase();
-    const n = NEARBY[lo];
-    if (!n)
-        return ch;
-    const w = n[Math.floor(Math.random() * n.length)];
-    return ch === ch.toUpperCase() && ch !== ch.toLowerCase() ? w.toUpperCase() : w;
+// The letter-adjacency map now lives in ./forms.ts (shared with Python and .NET); kept under the old
+// name for anything that imported it from here.
+/** @internal */
+export const NEARBY = NEARBY_LETTERS;
+/** @internal exported for tests. Per-character fat-finger rate. CLEARCOTE_HUMANIZE_TYPO_RATE
+ * overrides it (0 disables typos; the test suites raise it to exercise the correction paths). Read at
+ * call time, like Python's typo_rate(). */
+export function typoRate() {
+    const v = process.env.CLEARCOTE_HUMANIZE_TYPO_RATE;
+    if (v === undefined || v === "")
+        return DEFAULT_TYPO_RATE;
+    const f = pyFloat(v);
+    if (f === null || Number.isNaN(f))
+        return DEFAULT_TYPO_RATE;
+    return Math.min(1.0, Math.max(0.0, f));
+}
+/** @internal exported for tests. A Playwright timeout: the element never became actionable. Falling
+ * back to the native call after one would wait the FULL timeout again (a missing element took 2-3x
+ * `timeout` to fail), so timeouts propagate instead. */
+export function isTimeout(err) {
+    return err?.name === "TimeoutError";
+}
+/** Internal: the humane route cannot apply here; run the native Playwright call instead. */
+class NativeSignal extends Error {
+    constructor() { super("clearcote humanize: native route"); this.name = "NativeSignal"; }
+}
+/** @internal exported for tests. A per-page lock: each wrapped public entry point (page.click / fill
+ * / type / press / selectOption / check / uncheck / setChecked / dblclick / hover, mouse.click /
+ * dblclick, keyboard.type / press) runs one at a time. Without it a `Promise.all` of two fills on one
+ * page interleaved their clicks and keys and left each field with part of the other's text: a page has
+ * one pointer and one keyboard focus. Internal steps call internal helpers, never a locked entry point,
+ * so nothing waits on itself. A failed call releases the lock like a successful one. */
+export function createInputLock() {
+    let tail = Promise.resolve();
+    return (fn) => {
+        const run = tail.then(() => fn());
+        tail = run.then(() => undefined, () => undefined);
+        return run;
+    };
 }
-const SELECT_ALL = "Control+a"; // Clearcote ships a Windows binary; Control is correct.
 /** Wrap a single page's input methods + (optionally) inject the cursor overlay. */
 export async function attachHumanize(browser, page, opts) {
     // IDEMPOTENCY GUARD — do not remove.
@@ -144,6 +175,8 @@ export async function attachHumanize(browser, page, opts) {
     // seeds. Stored on the page so the module-level Locator.dragTo patch can reach it too.
     const persona = makePersona(opts.seed);
     page._clearcotePersona = persona;
+    // One input action at a time on this page (see createInputLock).
+    const locked = createInputLock();
     // Tracked cursor position so each move continues from where the last one ended.
     // `held` tracks whether a mouse button is currently down — see mouse.move below.
     // `placed` records whether the engine's cursor has actually been moved yet. A page starts with the
@@ -337,17 +370,33 @@ export async function attachHumanize(browser, page, opts) {
     finally {
         st.held = false;
     } };
-    mouse.click = async (x, y) => {
-        if (await engineGlide(x, y, false))
+    // The engine path performs ONE plain left click. Anything else -- right/middle button, a double
+    // click, a caller-chosen hold -- glides SDK-side and presses as asked (pressAt); the old wrapper
+    // dropped those options and always left-clicked once.
+    const hclick = async (x, y, options = {}) => {
+        const o = normalizeClickOptions(options);
+        if (enginePathOk(o) && await engineGlide(x, y, false))
             return;
         await glide(x, y);
-        await sleep(rand(40, 130)); // brief dwell before pressing, like a human
-        // delay = the mousedown→mouseup HOLD (human ~60–150 ms); without it Playwright releases in ~2 ms.
         try {
-            await nativeClick(x, y, { delay: clickHold(persona) });
+            if (o.modifiers.length && !(nativeKbDown && nativeKbUp)) {
+                await sleep(rand(40, 130)); // brief dwell before pressing, like a human
+                // delay = the mousedown→mouseup HOLD (human ~60–150 ms); without it Playwright releases in ~2 ms.
+                await nativeClick(x, y, { delay: o.delay ?? clickHold(persona), button: o.button, clickCount: o.clickCount });
+                return;
+            }
+            await pressAt(o);
         }
         catch { /* best-effort */ }
     };
+    mouse.click = (x, y, options = {}) => locked(() => hclick(x, y, options));
+    // Stock dblclick teleported and pressed for ~0 ms: route it through the humanized click.
+    if (typeof mouse.dblclick === "function") {
+        mouse.dblclick = (x, y, options = {}) => {
+            const { click_count: _cc, ...rest } = options ?? {};
+            return locked(() => hclick(x, y, { ...rest, clickCount: 2 }));
+        };
+    }
     // Opt-in ambient / pre-challenge cursor activity: idle drift + a few non-goal moves so a behavioral
     // collector sees non-zero pointer entropy BEFORE the first goal action (the biggest reason a
     // challenge/slider is shown to headless automation). `await page.ambientMotion(ms)`.
@@ -468,6 +517,136 @@ export async function attachHumanize(browser, page, opts) {
             catch { /* best-effort */ }
         }
     };
+    // Press `k` (n times) with the persona's hold on every press and a human gap between repeats.
+    const key = async (k, n = 1, gap = [60, 150]) => {
+        for (let j = 0; j < n; j++) {
+            await nativeKbPress(k, { delay: keyDwell(persona) });
+            if (j < n - 1)
+                await sleep(rand(gap[0], gap[1]));
+        }
+    };
+    // Press at the point the last glide ended, the way the options ask: the button, the click count (a
+    // double click is two presses with a human gap, not one event), the caller's hold (`delay`) or the
+    // persona's, and modifiers held around the whole press with a lead before it (80-240 ms: 40-110 ms
+    // per modifier plus the 40-130 ms pre-press dwell) and a 20-80 ms lag after, as fingers do. Native
+    // down/up, so nothing moves.
+    const pressAt = async (o) => {
+        const held = [];
+        try {
+            for (const m of o.modifiers) {
+                await nativeKbDown(m);
+                held.push(m);
+                await sleep(rand(40, 110));
+            }
+            await sleep(rand(40, 130)); // brief dwell before pressing, like a human
+            const n = o.clickCount;
+            for (let i = 1; i <= n; i++) {
+                const hold = o.delay ?? clickHold(persona);
+                await nativeDown({ button: o.button, clickCount: i });
+                try {
+                    await sleep(hold);
+                }
+                finally {
+                    await nativeUp({ button: o.button, clickCount: i }); // never leave the button down
+                }
+                if (i < n)
+                    await sleep(rand(70, 170)); // the gap inside a double click
+            }
+        }
+        finally {
+            for (const m of held.reverse()) {
+                await sleep(rand(20, 80));
+                try {
+                    await nativeKbUp(m);
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    };
+    // The focused field's current value, read in the isolated world (null if unknown).
+    const activeValue = async () => {
+        try {
+            const v = await worldFor(page).evaluate(ISO_ACTIVE_VALUE);
+            return typeof v === "string" ? v : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // Node's inter-key flight (the cadence humanTypeText uses between characters).
+    const flightMs = () => rand(45, 150);
+    const backspaces = async (n) => {
+        for (let k = 0; k < n; k++) {
+            await nativeKbPress("Backspace", { delay: keyDwell(persona) });
+            if (k < n - 1)
+                await sleep(rand(70, 150));
+        }
+    };
+    // How many characters arrived since `before` (null = cannot tell).
+    const landed = (before, now) => before === null || now === null ? null : Array.from(now).length - Array.from(before).length;
+    // Make the planned slip at chars[i] and correct it. Returns true when it already typed chars[i]
+    // itself (the doubled-key case), so the caller must not type it again.
+    //
+    // Only what actually LANDED is deleted: an input mask or a maxlength can swallow the wrong key, and
+    // a Backspace pressed for a key that never arrived deletes a real character (the
+    // letter-typo-in-a-numeric-mask failure). Measured before and after the slip, in the isolated world,
+    // one read each -- typos are ~2 % of keys, so this costs nearly nothing.
+    const doTypo = async (chars, i, tp) => {
+        const before = await activeValue();
+        if (tp.kind === "sub") {
+            await emitKey(tp.wrong);
+            let got = landed(before, await activeValue());
+            if (got !== null && got <= 0)
+                return false; // swallowed: nothing to correct
+            let typed = 1;
+            for (const c of chars.slice(i + 1, i + 1 + tp.late)) { // late notice: a key or two more
+                await sleep(flightMs());
+                await emitKey(c);
+                typed++;
+            }
+            await sleep(rand(140, 340)); // noticing
+            got = landed(before, await activeValue());
+            await backspaces(got === null ? typed : Math.max(0, Math.min(typed, got)));
+            await sleep(rand(80, 200));
+            return false;
+        }
+        if (tp.kind === "double") {
+            await emitKey(chars[i]);
+            await sleep(rand(45, 95)); // the bounce comes fast
+            await emitKey(chars[i]);
+            const got = landed(before, await activeValue());
+            await sleep(rand(140, 340));
+            const extra = got === null ? 1 : Math.max(0, got - 1);
+            if (extra) {
+                await backspaces(extra);
+                await sleep(rand(80, 200));
+            }
+            return true;
+        }
+        if (tp.kind === "swap") {
+            await emitKey(chars[i + 1]);
+            await sleep(flightMs());
+            await emitKey(chars[i]);
+            const got = landed(before, await activeValue());
+            await sleep(rand(140, 340));
+            await backspaces(got === null ? 2 : Math.max(0, Math.min(2, got)));
+            await sleep(rand(80, 200));
+            return false;
+        }
+        return false;
+    };
+    // What the typo gate needs about the field keys go to: the caller's description, else the focused
+    // element read in the isolated world.
+    const typingField = async (field) => {
+        if (field !== null && field !== undefined)
+            return field;
+        try {
+            return (await worldFor(page).evaluate(ISO_ACTIVE_FIELD)) ?? null;
+        }
+        catch {
+            return null;
+        }
+    };
     // Type text key-by-key with human timing. Each char goes through the native keyboard (trusted),
     // so this stays isTrusted===true.
     //
@@ -479,11 +658,16 @@ export async function attachHumanize(browser, page, opts) {
     // Fast pairs ROLL OVER: the next key goes down before the previous one comes up. One press() per
     // character never overlaps (0 of 32 keydowns, measured on r32/r33), a keystroke-dynamics tell;
     // real typists overlap many fast pairs. The share is the persona's rolloverRate, stable per seed.
+    //
+    // Fat-finger typos are planned by forms.planTypo and never happen where a slip is a failure rather
+    // than a slip (passwords, e-mail, numbers, phone numbers, URLs, one-time codes).
     const rollRate = rolloverRate(persona);
-    const humanTypeText = async (text) => {
+    const humanTypeText = async (text, field, typos = true) => {
         const chars = Array.from(text);
         const n = chars.length;
         let shift = false;
+        const rate = typos ? typoRate() : 0;
+        const allow = rate > 0 && typosAllowed(await typingField(field));
         try {
             for (let i = 0; i < n; i++) {
                 let ch = chars[i];
@@ -493,17 +677,18 @@ export async function attachHumanize(browser, page, opts) {
                     shift = true;
                     await sleep(rand(35, 120));
                 }
-                // occasional fat-finger on unshifted alnum chars, then notice + correct
+                // occasional fat-finger on unshifted letters and digits, then notice + correct
                 let typo = false;
-                if (!need && /[a-z0-9]/.test(ch) && Math.random() < 0.02) {
-                    typo = true;
-                    try {
-                        await emitKey(nearbyKey(ch));
-                        await sleep(rand(120, 300));
-                        await nativeKbPress("Backspace", { delay: keyDwell(persona) });
-                        await sleep(rand(80, 200));
+                let consumed = false;
+                if (allow && !need && !shift && typoEligible(ch)) {
+                    const tp = planTypo(chars, i, Math.random, rate);
+                    if (tp !== null) {
+                        typo = true;
+                        try {
+                            consumed = await doTypo(chars, i, tp);
+                        }
+                        catch { /* typo path best-effort */ }
                     }
-                    catch { /* typo path best-effort */ }
                 }
                 // Rollover of ch and the next char: unshifted single-key pairs only, never a key with itself,
                 // never after a typo. keyboard.down inserts the character exactly as press does, so the typed
@@ -541,7 +726,7 @@ export async function attachHumanize(browser, page, opts) {
                         ch = nx; // nx is typed; the cadence below runs as if after it
                     }
                 }
-                if (!rolled) {
+                if (!rolled && !consumed) {
                     try {
                         await emitKey(ch);
                     }
@@ -558,7 +743,7 @@ export async function attachHumanize(browser, page, opts) {
                     if (Math.random() < 0.06)
                         await sleep(rand(180, 450)); // brief thinking pause
                     else
-                        await sleep(rand(45, 150));
+                        await sleep(flightMs());
                     if (/\s/.test(ch))
                         await sleep(rand(20, 100)); // slight extra pause at word boundaries
                 }
@@ -590,7 +775,7 @@ export async function attachHumanize(browser, page, opts) {
         kbWarmed = true;
         await ambient(rand(280, 620));
     };
-    keyboard.type = async (text) => { await keyboardWarmup(); await humanTypeText(text); };
+    keyboard.type = (text) => locked(async () => { await keyboardWarmup(); await humanTypeText(text); });
     // keyboard.press with the persona's hold, unless the caller specified their own.
     //
     // WHY THIS EXISTS. keyboard.type was humanised from the start and keyboard.press was not, which
@@ -601,261 +786,993 @@ export async function attachHumanize(browser, page, opts) {
     // session sees the press path — so one un-humanised call undid the whole keyboard persona.
     //
     // The caller's own `delay` wins: press(key, {delay}) is the documented way to hold a key for a
-    // specific time, and silently overriding it would break that. Only the DEFAULT changes.
-    keyboard.press = async (key, options = {}) => {
+    // specific time, and silently overriding it would break that. Only the DEFAULT changes -- and
+    // `delay: 0` IS Playwright's default ("no hold"), so it, like any non-positive value, gets the
+    // persona's hold too (a 0 ms key hold is the tell this wrapper exists to remove).
+    keyboard.press = (key, options = {}) => locked(async () => {
         await keyboardWarmup();
-        const opts = options && typeof options === "object" ? options : {};
-        if (opts.delay === undefined)
+        const opts = { ...(options && typeof options === "object" ? options : {}) };
+        if (!(typeof opts.delay === "number" && opts.delay > 0))
             opts.delay = keyDwell(persona);
         return nativeKbPress(key, opts);
-    };
+    });
     // ------------------------------------------------------- page-level targeted helpers
-    // Read in an isolated world (./isolated.ts): the page never sees the lookup.
-    const isFocused = async (selector) => Boolean(await worldFor(page).evaluate(ISO_IS_FOCUSED, selector));
-    const pointFor = async (selector, timeout) => {
-        const loc = page.locator(selector).first();
-        await loc.waitFor({ state: "visible", timeout });
-        await loc.scrollIntoViewIfNeeded({ timeout });
-        if (!(await loc.isEnabled()))
+    // Points tried when resolving a control through the browser's hit test: a floating label or an icon
+    // often sits over a field's CENTRE, so the edges get a chance too.
+    const probePoints = [[0.5, 0.5], [0.82, 0.5], [0.18, 0.5], [0.5, 0.8], [0.5, 0.2]];
+    // The control filling `box` (Playwright's resolved box for a locator), read in the isolated world
+    // through the browser's own hit test: works for every Playwright selector (getByRole, getByLabel,
+    // `>> nth=`, .filter()) where document.querySelector threw and dropped the call to stock input. The
+    // element found must fill the SAME box, or it is not the one the locator means; null when no probe
+    // point proves that. `probe` records the point that proved it.
+    const describe = async (box, want = ISO_FORM_CONTROL) => {
+        if (!box || box.width <= 0 || box.height <= 0)
             return null;
-        let box = await loc.boundingBox();
-        if (!box)
+        const w = worldFor(page);
+        const scroll = await w.scroll(); // once: the hit test wants document coordinates
+        for (const [fx, fy] of probePoints) {
+            const nid = await w.nodeAt(box.x + box.width * fx, box.y + box.height * fy, scroll);
+            if (nid === undefined)
+                continue;
+            const info = await w.callOnNode(nid, ISO_DESCRIBE, { want });
+            if (!info || !info.rect)
+                continue;
+            const [rx, ry, rw, rh] = info.rect;
+            if (Math.abs(rx - box.x) <= 1.5 && Math.abs(ry - box.y) <= 1.5
+                && Math.abs(rw - box.width) <= 1.5 && Math.abs(rh - box.height) <= 1.5) {
+                info.node = nid;
+                // The point that PROVED the control: when the centre is covered (a floating label), this is
+                // where a click actually reaches it.
+                info.probe = [fx, fy];
+                return info;
+            }
+        }
+        return null;
+    };
+    // A click point the hit test proved reaches the control, when its centre did not; null when the
+    // centre itself was fine (then the persona's own point is used, as for any click).
+    const provenPoint = (box, info) => {
+        if (!info || !info.probe || (info.probe[0] === 0.5 && info.probe[1] === 0.5))
+            return null;
+        const [fx, fy] = info.probe;
+        const x = box.x + box.width * fx + gauss() * 1.5;
+        const y = box.y + box.height * fy + gauss() * 1.0;
+        return [clamp(x, box.x + 1, box.x + box.width - 1), clamp(y, box.y + 1, box.y + box.height - 1)];
+    };
+    // Describe the SAME element again, from the node the first hit test found: no new Playwright handle
+    // (see boxOf), so nothing the page can see. null if it is gone.
+    const redescribe = async (info, want = ISO_FORM_CONTROL) => {
+        if (info.node === undefined)
+            return null;
+        const again = await worldFor(page).callOnNode(info.node, ISO_DESCRIBE, { want });
+        if (!again)
             return null;
-        await sleep(50); // stability: a box that's still moving = an animation in flight
-        const box2 = await loc.boundingBox();
-        if (!box2 || Math.abs(box2.x - box.x) > 1 || Math.abs(box2.y - box.y) > 1)
+        again.node = info.node;
+        again.probe = info.probe ?? [0.5, 0.5];
+        return again;
+    };
+    const inView = async (box) => {
+        const vp = await viewport();
+        return box.x >= 0 && box.y >= 0 && box.x + box.width <= vp.width && box.y + box.height <= vp.height;
+    };
+    const rectBox = (r) => {
+        if (!r || !Array.isArray(r.rect))
+            return null;
+        const [x, y, width, height] = r.rect;
+        return width > 0 && height > 0 ? { x, y, width, height } : null;
+    };
+    // Does a press at viewport (x, y) reach the element filling `box`? true / false, or null when it
+    // cannot be told here: the point lies in a child frame, or CDP is unavailable.
+    const hitInBox = async (box, x, y) => {
+        const w = worldFor(page);
+        const nid = await w.nodeAt(x, y);
+        if (nid === undefined)
+            return null;
+        const res = await w.callOnNode(nid, ISO_HIT_IN_BOX, { x: box.x, y: box.y, width: box.width, height: box.height });
+        return res === undefined || res === null ? null : Boolean(res);
+    };
+    // Does the element filling `box` own its centre -- not clipped by a scrolling container, not
+    // covered? The browser's own hit test, read in the isolated world.
+    const hitOk = async (box) => (await hitInBox(box, box.x + box.width / 2, box.y + box.height / 2)) === true;
+    // The box of a plain-CSS selector's first match, read (and scrolled into view) in the isolated
+    // world: not even the one boundingBox() handle, and its textContent preview, is made. Used only
+    // when Playwright counts exactly the elements the browser's own querySelectorAll finds --
+    // Playwright's CSS also pierces open shadow roots, so equal counts mean the same elements in the same
+    // order. null otherwise (getByRole, text=, `>>` chains, :has-text()...: then Playwright's boundingBox).
+    const cssBox = async (selector) => {
+        if (typeof selector !== "string" || !selector)
+            return null;
+        const w = worldFor(page);
+        const r = await w.evaluate(ISO_CSS_BOX, { sel: selector, scroll: false });
+        if (!r || !r.n)
+            return null;
+        try {
+            if ((await page.locator(selector).count()) !== r.n)
+                return null;
+        }
+        catch {
             return null;
-        box = box2;
-        return clickPoint(box, st, persona); // 2D gaussian toward center, nudged to the approach side
+        }
+        let box = rectBox(r);
+        if (box && !((await inView(box)) && (await hitOk(box)))) {
+            // scrollIntoViewIfNeeded also scrolls a scrolling container that clips it, and does nothing
+            // when it already shows (then the cover is an overlay: the click's own check)
+            box = rectBox(await w.evaluate(ISO_CSS_BOX, { sel: selector, scroll: true }));
+        }
+        return box;
+    };
+    // Scroll the WINDOW so `box` sits centred where it was off-screen, the way Playwright's scroll
+    // centres it, and return where the box is now (moved by exactly the scrolled distance) -- or null.
+    // Needs no handle: the box is already known.
+    const scrollWindowTo = async (box) => {
+        const vp = await viewport();
+        if (box.width > vp.width || box.height > vp.height)
+            return null;
+        const cx = box.x + box.width / 2, cy = box.y + box.height / 2;
+        const dx = box.x < 0 || box.x + box.width > vp.width ? cx - vp.width / 2 : 0;
+        const dy = box.y < 0 || box.y + box.height > vp.height ? cy - vp.height / 2 : 0;
+        const moved = await worldFor(page).evaluate(ISO_SCROLL_BY, [dx, dy]);
+        if (!Array.isArray(moved) || moved.length !== 2)
+            return null;
+        return { x: box.x - Number(moved[0]), y: box.y - Number(moved[1]), width: box.width, height: box.height };
+    };
+    // Wait the way Playwright would, with the CALLER's timeout (undefined = the page default; a
+    // hard-coded 30 s used to override setDefaultTimeout both ways), and return the box, in view. With
+    // `force` Playwright skips actionability, so nothing is waited for: a hidden target goes native at
+    // once instead of timing out where the native call would have acted.
+    //
+    // Each Playwright call that resolves the element to a handle (waitFor, scrollIntoViewIfNeeded,
+    // boundingBox) makes a MAIN-world handle whose preview reads the element's textContent where the
+    // page can see it: verifier B counted 4 such reads per humanized click and 7 per textarea fill. So
+    // each is made only when needed: the wait only for an element not visible yet (isVisible runs in
+    // Playwright's utility world), the scroll only for a box not already inside the viewport, and a
+    // plain-CSS `selector` needs no handle at all (cssBox). What remains, for other selectors, is the
+    // one boundingBox.
+    const boxOf = async (loc, timeout, force = false, selector = null) => {
+        if (!(await loc.isVisible())) {
+            if (force)
+                throw new NativeSignal();
+            await loc.waitFor({ state: "visible", timeout });
+        }
+        const css = await cssBox(selector);
+        if (css)
+            return css;
+        let box = await loc.boundingBox();
+        if (box && !((await inView(box)) && (await hitOk(box)))) {
+            // Off-screen: scroll the window to it and prove it shows there (hit test), with no new handle.
+            // Clipped by a scrolling container, covered, or the window scroll did not bring it out:
+            // Playwright's scroll, which also scrolls containers, and a fresh box.
+            const moved = !(await inView(box)) ? await scrollWindowTo(box) : null;
+            if (moved && (await inView(moved)) && (await hitOk(moved)))
+                return moved;
+            await loc.scrollIntoViewIfNeeded({ timeout });
+            box = await loc.boundingBox();
+        }
+        return box;
     };
-    const focusClick = async (selector, timeout) => {
-        const pt = await pointFor(selector, timeout);
-        if (!pt)
+    // Does `loc` hold the keyboard focus? Asked through Playwright's utility-world selector engine
+    // (`:focus`), so it works for every element and every locator and the page sees nothing. The
+    // isolated hit test only knew form controls, so a focused BUTTON read as unfocused and got clicked
+    // before a press -- two activations.
+    const focused = async (loc) => {
+        try {
+            return (await loc.and(page.locator(":focus")).count()) > 0;
+        }
+        catch {
             return false;
+        }
+    };
+    const isFocused = (selector) => focused(page.locator(selector).first());
+    // {box, info} when `loc` is a visible text-entry control a person would click into before typing,
+    // else null. Anything else -- a button, a link, a hidden helper textarea, a slider -- is left to
+    // Playwright, which focuses it without a click (a click on a button activates it; on a slider it
+    // moves it).
+    const textEntry = async (loc, timeout, selector = null) => {
+        if (!(await loc.isVisible()))
+            return null;
+        const box = await boxOf(loc, timeout, false, selector);
+        const info = await describe(box);
+        if (box && info && classifyField(info.tag, info.type, info.ce) === "text")
+            return { box, info };
+        return null;
+    };
+    // Click into the control filling `box` (resolved, visible and in view). `at`: the point the hit test
+    // proved when the centre is covered (a floating label); else the persona's point. Stability is
+    // checked in the isolated world -- the control must still fill the same box 50 ms later (an
+    // animation in flight goes native) -- not by a second boundingBox(), which the page could see (see
+    // boxOf).
+    //
+    // A control no probe point reaches -- a label or an icon covers all of it -- is clicked anyway, where
+    // a person clicks (a floating label passes the focus on), and the caller checks that the caret
+    // arrived. Its stability then comes from a fresh box: the isolated CSS read, else boundingBox().
+    // Requiring the hit test there sent a fully labelled field to Playwright's insertText (found by the
+    // .NET port).
+    const focusClick = async (box, at = null, loc = null, selector = null) => {
+        if (!box)
+            return false;
+        await sleep(50);
+        const info = await describe(box);
+        if (!info) {
+            let again = selector ? await cssBox(selector) : null;
+            if (!again && loc)
+                again = await loc.boundingBox();
+            if (!again || Math.abs(again.x - box.x) > 1 || Math.abs(again.y - box.y) > 1)
+                return false;
+        }
+        else if (info.disabled) {
+            return false;
+        }
+        const pt = at ? { x: at[0], y: at[1] } : clickPoint(box, st, persona); // 2D gaussian toward the centre
         await glide(pt.x, pt.y);
         await sleep(rand(40, 130));
         await nativeClick(pt.x, pt.y, { delay: clickHold(persona) });
         return true;
     };
+    // Ctrl+A (Cmd+A on a Mac engine) the way a hand does it: the modifier goes down a moment before the
+    // A, the A is held, the modifier comes up just after. Sent as one Playwright chord the modifier and
+    // the A went down within ~1 ms of each other. ControlOrMeta lets Playwright pick the chord the
+    // ENGINE's editing honours: a Meta+A sent to a Linux engine for a macOS persona selects nothing.
+    const selectAll = async () => {
+        if (!nativeKbDown || !nativeKbUp) {
+            await key("ControlOrMeta+a");
+            return;
+        }
+        await nativeKbDown("ControlOrMeta");
+        try {
+            await sleep(rand(40, 110));
+            await nativeKbPress("a", { delay: keyDwell(persona) });
+            await sleep(rand(20, 80));
+        }
+        finally {
+            await nativeKbUp("ControlOrMeta");
+        }
+    };
+    // Select all, then Backspace -- each key HELD like a finger holds it. The old clear sent Control+a
+    // and Backspace with ~0 ms holds, which is exactly what a key-dwell check flags. If the field is
+    // still not empty (`read` -- the field's value -- says so), it is emptied from the end, one
+    // Backspace per character.
+    const clearFocused = async (read = activeValue) => {
+        await selectAll();
+        await sleep(rand(60, 160));
+        await key("Backspace");
+        await sleep(rand(60, 160));
+        const left = await read();
+        if (left) {
+            const len = Array.from(left).length;
+            if (len > 64)
+                throw new Error("field would not clear");
+            await key("End");
+            await sleep(rand(80, 180));
+            await key("Backspace", len, [55, 120]);
+            await sleep(rand(60, 160));
+            if (await read())
+                throw new Error("field would not clear");
+        }
+    };
     const nativePageType = page.type ? page.type.bind(page) : null;
     const nativePageFill = page.fill.bind(page);
     const nativePagePress = page.press.bind(page);
     const nativePageDblclick = page.dblclick.bind(page);
-    const nativePageSelect = page.selectOption ? page.selectOption.bind(page) : null;
-    page.type = async (selector, text, options = {}) => {
+    const nativePageClick = page.click.bind(page);
+    const nativePageHover = page.hover.bind(page);
+    const nativePageSelect = typeof page.selectOption === "function" ? page.selectOption.bind(page) : null;
+    const nativeType = (selector, text, options) => nativePageType ? nativePageType(selector, text, options) : nativePageFill(selector, text, options);
+    // Make `selector` the focus the way a person does (a click), unless it already is. Only text-entry
+    // controls are clicked; for anything else, and when the click did not actually put the caret there
+    // (an overlay took it), the caller goes native.
+    const clickInto = async (selector, timeout) => {
+        const loc = page.locator(selector).first();
+        if (await focused(loc))
+            return;
+        const te = await textEntry(loc, timeout, selector);
+        if (!te || !(await focusClick(te.box, provenPoint(te.box, te.info), loc, selector)) || !(await focused(loc))) {
+            throw new NativeSignal();
+        }
+        await sleep(rand(40, 120));
+    };
+    const htype = async (selector, text, options) => {
         try {
-            const timeout = options.timeout ?? 30000;
-            if (!(await isFocused(selector))) {
-                if (!(await focusClick(selector, timeout))) {
-                    return nativePageType ? nativePageType(selector, text, options) : nativePageFill(selector, text, options);
+            await clickInto(selector, options?.timeout);
+            await humanTypeText(text);
+            return;
+        }
+        catch (e) {
+            if (isTimeout(e))
+                throw e;
+        }
+        // outside the try: a native call that raises must raise ONCE, not be retried by the handler
+        return nativeType(selector, text, options);
+    };
+    page.type = (selector, text, options = {}) => locked(() => htype(selector, text, options));
+    // Type `value` into a text control and PROVE it landed. The value is read through Playwright's
+    // utility world (`inputValue`): it sees the control the locator means, wherever focus is, and the page
+    // cannot observe it. A field whose value cannot be read, or a click that did not put the caret in it
+    // (an overlay took it), is left to Playwright -- "could not check" is never treated as success.
+    const fillText = async (loc, box, value, info, selector = null) => {
+        if (Array.from(value).length > 200)
+            return false; // bulk values: keep fill fast/atomic
+        const isCe = Boolean(info && info.ce)
+            || (info === null && ((await loc.getAttribute("contenteditable")) || "false") !== "false");
+        if (!(await focusClick(box, box ? provenPoint(box, info) : null, loc, selector)))
+            return false;
+        await sleep(rand(40, 120));
+        if (!(await focused(loc)))
+            return false;
+        const read = async () => {
+            try {
+                return await loc.inputValue({ timeout: COVER_RETRY_MS });
+            }
+            catch {
+                return null;
+            }
+        };
+        if (isCe) {
+            const cur = info ? info.value : null;
+            if (cur)
+                await clearFocused();
+            await humanTypeText(value, info);
+            return true; // contenteditable: Playwright's fill sets text the same way; no value to read
+        }
+        const cur = await read();
+        if (cur === null)
+            return false;
+        if (cur)
+            await clearFocused(read); // a person does not select-all an empty field
+        await humanTypeText(value, info);
+        let got = await read();
+        if (got === null)
+            return false;
+        if (got === value || formattedEqual(got, value))
+            return true; // exact, or a mask that only re-punctuated it
+        // Wrong value (an autocompleter interfered, a key was lost): one clean retry without slips, then
+        // give the field to Playwright -- a correct value beats pretty input.
+        await clearFocused(read);
+        await humanTypeText(value, info, false);
+        got = await read();
+        return got !== null && (got === value || formattedEqual(got, value));
+    };
+    // A range input: drag the thumb (or click the track) to the value, then arrow-nudge to it exactly.
+    // Typing digits into a slider -- what fill() did before -- changes nothing, and the click before it
+    // left the thumb wherever it landed, with no error.
+    const fillRange = async (loc, box, info0, value) => {
+        const info = info0 ?? {
+            min: await loc.getAttribute("min"), max: await loc.getAttribute("max"),
+            step: await loc.getAttribute("step"), value: await loc.inputValue(), dir: "ltr", wm: "",
+        };
+        // Off the step, out of range, not a number: Playwright raises "Malformed value" for these, so does
+        // this route (by leaving them to it) -- never a silently snapped or clamped value.
+        if (!rangeValueOk(value, info.min, info.max, info.step))
+            return false;
+        if ((info.wm || "").startsWith("vertical"))
+            return false;
+        const rtl = info.dir === "rtl";
+        const [lo, hi, step] = rangeAttrs(info.min, info.max, info.step);
+        const target = rangeSanitize(value, info.min, info.max, info.step);
+        const now = async () => {
+            const f = pyFloat(await loc.inputValue());
+            return f === null || Number.isNaN(f) ? null : f;
+        };
+        const cur = await now();
+        if (cur !== null && numericEqual(cur, target))
+            return true;
+        let [tx, ty] = rangePoint(box, rangeFraction(target, lo, hi), rtl);
+        ty += gauss() * box.height * 0.08;
+        if (cur !== null && Math.random() < 0.65) {
+            // Grab the thumb where it is and slide it: what most hands do with a slider.
+            let [cx, cy] = rangePoint(box, rangeFraction(cur, lo, hi), rtl);
+            cy += gauss() * box.height * 0.08;
+            await glide(cx, cy, { targetW: 16 });
+            await sleep(rand(60, 160));
+            const { grabMs, releaseMs } = dragDwell(persona);
+            await nativeDown();
+            st.held = true;
+            try {
+                await sleep(grabMs);
+                await glide(tx, ty, { settle: true });
+                await sleep(releaseMs);
+            }
+            finally {
+                await nativeUp();
+                st.held = false;
+            }
+        }
+        else {
+            await glide(tx, ty, { targetW: 16 });
+            await sleep(rand(40, 130));
+            await nativeClick(tx, ty, { delay: clickHold(persona) });
+        }
+        for (let round = 0; round < 3; round++) {
+            const v = await now();
+            if (v === null)
+                return false;
+            if (numericEqual(v, target))
+                return true;
+            let [k, n] = rangeNudge(v, target, step);
+            if (k === null || n <= 0 || n > 40)
+                break;
+            if (rtl)
+                k = k === "ArrowRight" ? "ArrowLeft" : "ArrowRight";
+            await sleep(rand(150, 350));
+            await key(k, n);
+        }
+        const v = await now();
+        return v !== null && numericEqual(v, target);
+    };
+    // A native date / time / month / week / datetime-local editor: click into its first field and type
+    // each field in the order the editor itself shows them (read from its UA shadow tree over CDP --
+    // the order follows the browser, not the persona, so it is never assumed).
+    const fillDatetime = async (loc, box, info, value) => {
+        if (!info || !info.node)
+            return false;
+        const kind = info.type;
+        const w = worldFor(page);
+        const tree = await w.send("DOM.describeNode", { backendNodeId: info.node, depth: -1, pierce: true });
+        if (!tree || !tree.node)
+            return false;
+        const segs = segmentNodesFromTree(tree.node);
+        const plan = planDatetime(kind, segs.map(([s]) => s), value, info.value);
+        if (!plan || plan.length === 0 || segs.length === 0)
+            return false;
+        let px = null, py = 0, fw = 12.0;
+        const bm = segs[0][1] ? await w.send("DOM.getBoxModel", { backendNodeId: segs[0][1] }) : undefined;
+        if (bm && bm.model) {
+            const c = bm.model.content;
+            const xs = [c[0], c[2], c[4], c[6]], ys = [c[1], c[3], c[5], c[7]];
+            const x0 = Math.min(...xs), y0 = Math.min(...ys), x1 = Math.max(...xs), y1 = Math.max(...ys);
+            // trust the field box only when it lies inside the input's own box
+            if (box.x - 1 <= x0 && x0 < x1 && x1 <= box.x + box.width + 1
+                && box.y - 1 <= y0 && y0 < y1 && y1 <= box.y + box.height + 1) {
+                px = rand(x0 + (x1 - x0) * 0.25, x0 + (x1 - x0) * 0.75);
+                py = (y0 + y1) / 2 + gauss() * Math.max(0.5, (y1 - y0) * 0.1);
+                fw = Math.max(6.0, x1 - x0);
+            }
+        }
+        if (px === null) {
+            px = box.x + Math.min(14.0, box.width * 0.12);
+            py = box.y + box.height / 2;
+        }
+        await glide(px, py, { targetW: fw });
+        await sleep(rand(40, 130));
+        await nativeClick(px, py, { delay: clickHold(persona) });
+        await sleep(rand(150, 350));
+        for (const a of plan) {
+            if (a[0] === "type") {
+                const digits = Array.from(a[1]);
+                for (let j = 0; j < digits.length; j++) {
+                    await nativeKbPress(digits[j], { delay: keyDwell(persona) });
+                    if (j < digits.length - 1)
+                        await sleep(Math.max(30, 110 + gauss() * 40));
                 }
-                await sleep(rand(40, 120));
             }
-            await humanTypeText(text);
+            else {
+                await key(a[1], a.length > 2 ? a[2] : 1, [70, 170]);
+            }
+            await sleep(rand(60, 220)); // between fields: the eye checks what it typed
         }
-        catch {
-            return nativePageType ? nativePageType(selector, text, options) : nativePageFill(selector, text, options);
+        return datetimeEqual(kind, await loc.inputValue(), value);
+    };
+    // Classify through Playwright's utility-world queries when the hit test could not prove the element
+    // (it is covered, or inside a frame): attributes only, nothing the page can see.
+    const classifyFallback = async (loc) => {
+        for (const tag of ["textarea", "select"]) {
+            if (await loc.locator(`xpath=self::${tag}`).count())
+                return classifyField(tag);
         }
+        if (await loc.locator("xpath=self::input").count())
+            return classifyField("input", await loc.getAttribute("type"));
+        const ce = await loc.getAttribute("contenteditable");
+        return classifyField("div", null, ce !== null && ce.toLowerCase() !== "false");
     };
-    page.fill = async (selector, value, options = {}) => {
+    // fill() classifies the field: text-like is typed (cleared first only when non-empty, then
+    // verified), a range is dragged/clicked and nudged, a date-like editor is typed segment by segment.
+    // color, unfillable types and anything the humane route cannot prove it did right go to Playwright.
+    const hfill = async (selector, value, options) => {
         try {
-            const timeout = options.timeout ?? 30000;
-            if (value.length > 200)
-                return nativePageFill(selector, value, options); // bulk -> atomic
-            if (!(await focusClick(selector, timeout)))
-                return nativePageFill(selector, value, options);
-            await sleep(rand(40, 120));
-            try {
-                await nativeKbPress(SELECT_ALL);
-                await sleep(rand(30, 80));
-                await nativeKbPress("Backspace");
-                await sleep(rand(40, 120));
+            if (typeof value === "string") {
+                const timeout = options?.timeout; // undefined: the page's default, as Playwright would use
+                const loc = page.locator(selector).first();
+                const box = await boxOf(loc, timeout, Boolean(options?.force), selector);
+                const info = await describe(box);
+                const kind = info ? classifyField(info.tag, info.type, info.ce) : await classifyFallback(loc);
+                if (!(info && (info.disabled || info.readonly))) {
+                    if (kind === "text" && await fillText(loc, box, value, info, selector))
+                        return;
+                    if (kind === "range" && box && await fillRange(loc, box, info, value))
+                        return;
+                    if (kind === "datetime" && box && await fillDatetime(loc, box, info, value))
+                        return;
+                }
             }
-            catch { /* clear best-effort */ }
-            await humanTypeText(value);
         }
-        catch {
-            return nativePageFill(selector, value, options);
+        catch (e) {
+            if (isTimeout(e))
+                throw e;
         }
+        // Native: color (Playwright sets it -- the OS dialog is no route), unfillable types (Playwright
+        // raises, as before humanize), and anything the humane route could not prove it did right.
+        return nativePageFill(selector, value, options);
     };
-    page.dblclick = async (selector, options = {}) => {
+    page.fill = (selector, value, options = {}) => locked(() => hfill(selector, value, options));
+    page.dblclick = (selector, options = {}) => locked(() => {
+        const o = { ...(options ?? {}) };
+        if (o.clickCount === undefined)
+            o.clickCount = 2;
+        return targetedClick(nativePageDblclick, selector, o, false, options ?? {});
+    });
+    const hpress = async (selector, key, options) => {
         try {
-            const timeout = options.timeout ?? 30000;
-            const pt = await pointFor(selector, timeout);
-            if (!pt)
-                return nativePageDblclick(selector, options);
-            await glide(pt.x, pt.y);
-            await sleep(rand(40, 130));
-            await nativeClick(pt.x, pt.y, { clickCount: 2, delay: rand(40, 90) });
+            // Click into text fields only: a press on a button or a link that is not focused yet is
+            // Playwright's (it focuses without activating); clicking it first activated it twice.
+            await clickInto(selector, options?.timeout);
+            // The persona's hold unless the caller set a real one, for the same reason keyboard.press above
+            // carries one: this is the path locator.press() delegates to.
+            const d = options?.delay;
+            await nativeKbPress(key, { delay: typeof d === "number" && d > 0 ? d : keyDwell(persona) });
+            return;
         }
-        catch {
-            return nativePageDblclick(selector, options);
+        catch (e) {
+            if (isTimeout(e))
+                throw e;
         }
+        return nativePagePress(selector, key, options);
     };
-    page.press = async (selector, key, options = {}) => {
+    page.press = (selector, key, options = {}) => locked(() => hpress(selector, key, options));
+    // ------------------------------------------------------------------------- selectOption
+    // Open the drop-down with a click, move its highlight with the planned keys, commit with Enter: one
+    // trusted input+change, the sequence a mouse-and-keyboard user produces. While the popup is open its
+    // keys never reach the page (measured on r37: value unchanged until Enter). The opening click is the
+    // full humanized click -- including the covered-point check -- at the point the hit test proved when
+    // the centre is covered (`at`, a Playwright `position`), so a floating label over the select's centre
+    // cannot swallow it and leave the letters to change a closed select one per key.
+    const openAndPick = async (selector, plan, at) => {
+        await targetedClick(nativePageClick, selector, at ? { position: at } : {}, false, null);
+        await sleep(rand(220, 480)); // the list opens; the eye finds the option
+        for (const ch of plan.keys) {
+            await nativeKbPress(ch, { delay: keyDwell(persona) });
+            await sleep(Math.max(40, 100 + gauss() * 35)); // well inside type-ahead's 1 s window
+        }
+        const n = plan.arrows;
+        if (n) {
+            await sleep(rand(120, 300));
+            await arrowRun(n > 0 ? "ArrowDown" : "ArrowUp", Math.abs(n));
+        }
+        await sleep(rand(150, 400));
+        await key("Enter");
+        await sleep(rand(80, 160));
+    };
+    // `n` presses of an arrow key in an OPEN drop-down. A long run is HELD, the way a person crosses a
+    // long list: one press, the keyboard's repeat delay, then auto-repeat at its rate -- Playwright sends
+    // a key that is already down again as an autoRepeat keydown. Pressed one by one at a human ~180 ms
+    // each, 370 rows took 68 s (verifier B). The open popup takes these keys, so the page sees none of
+    // them, only how long the pick took.
+    const arrowRun = async (k, n) => {
+        if (n < 8 || !nativeKbDown || !nativeKbUp) {
+            await key(k, n);
+            return;
+        }
+        await nativeKbDown(k);
         try {
-            const timeout = options.timeout ?? 30000;
-            if (!(await isFocused(selector))) {
-                if (!(await focusClick(selector, timeout)))
-                    return nativePagePress(selector, key, options);
-                await sleep(rand(40, 120));
+            await sleep(rand(380, 560)); // the repeat delay
+            const gap = rand(28, 36); // ~30 repeats a second
+            for (let j = 0; j < n - 1; j++) {
+                await sleep(gap);
+                await nativeKbDown(k);
             }
-            // The persona's hold, for the same reason keyboard.press above carries one: this is the
-            // path locator.press() delegates to, so without it every locator.press in a script emitted
-            // a zero-length keypress while the typed text around it looked human.
-            await nativeKbPress(key, { delay: keyDwell(persona) });
         }
-        catch {
-            return nativePagePress(selector, key, options);
+        finally {
+            await sleep(rand(20, 60));
+            await nativeKbUp(k); // never leave the key down
         }
     };
-    // page.selectOption was the last input method humanize did not touch, so a script that used it —
-    // rather than locator.selectOption, which has been patched for a while — went straight to
-    // Playwright's implementation: assign the value, dispatch input+change from page script. That is
-    // measurably scored: it fails 'interaction-select-change-trust' on clearcotelabs.com/audit,
-    // because no user gesture can produce a change event with isTrusted false.
-    //
-    // The move is a HOVER, not a click: clicking a <select> opens the native popup, and the popup
-    // swallows the arrow keys the trusted path steps the selection with. A person's pointer is on the
-    // dropdown they are choosing from either way.
+    const listboxRow = async (info, i) => {
+        if (info.node === undefined)
+            return null;
+        return (await worldFor(page).callOnNode(info.node, ISO_LISTBOX_ROW, { i })) ?? null;
+    };
+    // The list box's state once its scroll has come to rest. A wheel notch scrolls the box SMOOTHLY over
+    // a few frames, and a read taken mid-animation shows the row where it was, not where it is going:
+    // the old loop then wheeled the wrong way and oscillated (verifier B: scrollTop 120 -> 240 -> 323 ->
+    // 203 -> 83 -> 0, twice, with the row in view at 120, then a native, untrusted fallback). Two equal
+    // reads 50 ms apart = at rest.
+    const settledRow = async (info, i) => {
+        let prev = await listboxRow(info, i);
+        for (let k = 0; k < 30; k++) {
+            await sleep(50);
+            const cur = await listboxRow(info, i);
+            if (!cur || !prev)
+                return cur;
+            if (Math.abs(cur.st - prev.st) < 0.5 && Math.abs(cur.row[1] - prev.row[1]) < 0.5)
+                return cur;
+            prev = cur;
+        }
+        return prev;
+    };
+    // The visible vertical span [top, bottom] of the row, or null when too little of it shows. A row cut
+    // off by the box edge is still a target a person clicks when most of it shows.
+    const rowSpan = (s) => {
+        const [, y, w, h] = s.row;
+        if (w <= 0 || h <= 0)
+            return null;
+        const top = Math.max(y, s.top), bottom = Math.min(y + h, s.bottom);
+        return bottom - top >= Math.min(h, Math.max(6, h * 0.6)) ? [top, bottom] : null;
+    };
+    // Wheel the list box until row `i` shows: the pointer goes over the box once, then as many notches
+    // as the distance needs -- one at first, to learn how far a notch scrolls this box -- each burst read
+    // only once the scroll has settled. {top, bottom, s}, or null when it cannot be brought into view
+    // (the wheel does not move the box, or it is at its end).
+    const scrollRowIntoView = async (info, i) => {
+        let s = await settledRow(info, i);
+        if (!s)
+            return null;
+        let span = rowSpan(s), per = null, over = false, notches = 0;
+        while (span === null && notches < 60) {
+            const [, y, , h] = s.row;
+            const room = s.bottom - s.top;
+            const margin = rand(2, Math.max(3, Math.min(12, (room - h) * 0.4)));
+            const need = y + h > s.bottom ? (y + h) - s.bottom + margin : y - s.top - margin;
+            if ((need > 0 && s.st >= s.max - 0.5) || (need < 0 && s.st <= 0.5))
+                return null;
+            if (!over) {
+                const [bx, , bw] = s.box;
+                await glide(bx + bw * rand(0.3, 0.7), s.top + room * rand(0.3, 0.7), { targetW: Math.max(20, room) });
+                await sleep(rand(80, 200));
+                over = true;
+            }
+            const n = !per ? 1
+                : Math.max(1, Math.min(8, Math.floor(Math.abs(need) / per) + (Math.abs(need) % per > per * 0.25 ? 1 : 0)));
+            const notch = await wheelNotchPx();
+            for (let j = 0; j < n; j++) {
+                await nativeWheel(0, need > 0 ? notch : -notch);
+                notches++;
+                if (j < n - 1)
+                    await sleep(rand(30, 70));
+            }
+            const before = s.st;
+            const next = await settledRow(info, i);
+            if (!next)
+                return null;
+            s = next;
+            const moved = Math.abs(s.st - before);
+            if (moved < 0.5)
+                return null; // the wheel did not scroll the box
+            per = moved / n;
+            span = rowSpan(s);
+        }
+        return span ? { top: span[0], bottom: span[1], s } : null;
+    };
+    // A list box (multiple or size > 1): click the rows -- the first plainly (which also drops any other
+    // selection), the rest with Ctrl/Cmd held, scrolling the box with the wheel to bring a row into view
+    // the way a person does.
+    const selectListbox = async (info, idx) => {
+        const want = [...idx].sort((a, b) => a - b);
+        const opts = info.options ?? [];
+        const selectedNow = opts.map((o, i) => (o.selected ? i : -1)).filter((i) => i >= 0);
+        if (want.length === selectedNow.length && want.every((i, k) => i === selectedNow[k])) {
+            return want.map((i) => opts[i].value);
+        }
+        for (let k = 0; k < want.length; k++) {
+            const got = await scrollRowIntoView(info, want[k]);
+            if (!got)
+                return null;
+            const { top, bottom, s } = got;
+            const r = s.row;
+            const px = rand(r[0] + r[2] * 0.12, r[0] + Math.min(r[2] * 0.6, 140));
+            let py = (top + bottom) / 2 + gauss() * Math.max(0.5, (bottom - top) * 0.12);
+            py = Math.min(Math.max(py, top + 1), bottom - 1);
+            await glide(px, py, { targetW: bottom - top });
+            if (k && nativeKbDown && nativeKbUp) {
+                // ControlOrMeta: Playwright sends the add-to-selection key the ENGINE honours
+                await pressAt(normalizeClickOptions({ modifiers: ["ControlOrMeta"] }));
+            }
+            else {
+                await sleep(rand(40, 130));
+                await nativeClick(px, py, { delay: clickHold(persona) });
+            }
+            await sleep(rand(150, 350));
+        }
+        const final = await listboxRow(info, want[0]);
+        if (!final)
+            return null;
+        const got = final.sel.map((v, i) => (v ? i : -1)).filter((i) => i >= 0);
+        return got.length === want.length && got.every((i, k) => i === want[k]) ? want.map((i) => opts[i].value) : null;
+    };
+    // Pick options the way a person does (see openAndPick / selectListbox). Resolves to the selected
+    // values like Playwright, or null when the humane route cannot apply or cannot be shown to have
+    // worked -- the caller then runs stock selectOption.
+    const selectHumanized = async (selector, values, options) => {
+        const wants = selectWants(values);
+        if (!wants)
+            return null;
+        const loc = page.locator(selector).first();
+        const box = await boxOf(loc, options?.timeout, Boolean(options?.force), selector);
+        const info = await describe(box, "select");
+        if (!box || !info || info.tag !== "select" || info.disabled)
+            return null;
+        const opts = info.options ?? [];
+        const idx = [];
+        for (const w of wants) {
+            const i = wantIndex(opts, w);
+            if (i < 0 || opts[i].disabled)
+                return null; // not there (yet) or disabled: Playwright waits / reports it
+            if (!idx.includes(i))
+                idx.push(i);
+        }
+        if (info.multiple || (info.size ?? 0) > 1) {
+            return selectListbox(info, info.multiple ? idx : [Math.min(...idx)]);
+        }
+        const t = Math.min(...idx); // Playwright: the FIRST option (document order) matching any wanted one
+        if (info.selectedIndex === t)
+            return [opts[t].value];
+        const labels = opts.map((o) => (o.disabled ? null : (o.label || "")));
+        const plan = planSelect(labels, info.selectedIndex ?? -1, t);
+        if (plan === null)
+            return null;
+        const pt = provenPoint(box, info);
+        const at = pt ? { x: pt[0] - box.x - (info.bl || 0), y: pt[1] - box.y - (info.bt || 0) } : null;
+        await openAndPick(selector, plan, at);
+        if ((await loc.inputValue()) === opts[t].value)
+            return [opts[t].value];
+        // One correction from wherever the highlight landed (arrows only), then give up to native.
+        const again = await redescribe(info, "select");
+        if (!again)
+            return null;
+        const fix = planSelect(labels, again.selectedIndex ?? -1, t, 0);
+        if (fix === null)
+            return null;
+        await openAndPick(selector, fix, at);
+        return (await loc.inputValue()) === opts[t].value ? [opts[t].value] : null;
+    };
+    // page.selectOption, humanized: no more script-assigned value with an untrusted change event
+    // (which fails 'interaction-select-change-trust' on clearcotelabs.com/audit).
     if (nativePageSelect) {
-        page.selectOption = async (selector, values, options = {}) => {
-            const timeout = options.timeout ?? 30000;
+        const hselect = async (selector, values, options) => {
             try {
-                const pt = await pointFor(selector, timeout);
-                if (pt) {
-                    await glide(pt.x, pt.y);
-                    await sleep(rand(50, 150));
-                }
+                const res = await selectHumanized(selector, values, options ?? {});
+                if (res !== null)
+                    return res;
             }
-            catch { /* the pre-move is best-effort; a trusted selection still beats a native one */ }
-            try {
-                const got = await trustedSelect(page, selector, values, timeout);
-                if (got)
-                    return got;
+            catch (e) {
+                if (isTimeout(e))
+                    throw e;
             }
-            catch { /* fall back */ }
             return nativePageSelect(selector, values, options);
         };
+        page.selectOption = (selector, values, options = {}) => locked(() => hselect(selector, values, options));
+    }
+    // ------------------------------------------------------------------ check / uncheck / setChecked
+    // A humanized click when the state must change, then the state verified. `trial` performs no action:
+    // Playwright's own trial runs. Errors propagate as Playwright's own (not a checkbox, timed out): the
+    // click owns its native fallback, so nothing here may click a second time -- and when one click did
+    // not change the state (a page that cancels it), this raises like Playwright's check instead of
+    // clicking again.
+    const setChecked = async (orig, selector, checked, options) => {
+        const opts = options ?? {};
+        if (opts.trial)
+            return orig(selector, opts);
+        const loc = page.locator(selector).first();
+        if ((await loc.isChecked({ timeout: opts.timeout })) === checked)
+            return;
+        await targetedClick(nativePageClick, selector, { ...opts }, false, null);
+        if ((await loc.isChecked()) === checked)
+            return;
+        throw new Error("Clicking the checkbox did not change its state");
+    };
+    for (const [name, want] of [["check", true], ["uncheck", false]]) {
+        if (typeof page[name] === "function") {
+            const orig = page[name].bind(page);
+            page[name] = (selector, options = {}) => locked(() => setChecked(orig, selector, want, options));
+        }
     }
-    const wrapTargeted = (name, noClick) => {
-        const orig = page[name].bind(page);
-        page[name] = async (selector, options = {}) => {
-            // Actionability pre-flight before a TRUSTED humanized click: visible+enabled+stable+
-            // not-covered, else fall back to the native click (which has its own waits) — only improves.
+    if (typeof page.setChecked === "function") {
+        const origSc = page.setChecked.bind(page);
+        page.setChecked = (selector, checked, options = {}) => locked(() => setChecked((s, o) => origSc(s, checked, o), selector, Boolean(checked), options));
+    }
+    // ------------------------------------------------------------------------- click / hover
+    // The covered-point check, through the browser's own hit test read in the isolated world: nothing is
+    // dispatched and the pointer does not move. It replaced a Playwright TRIAL action, which moves the
+    // REAL pointer onto the element and back and performs a press with its events blocked: verifier B
+    // saw, before every humanized click since 0.46.0, a mousemove inside the target, a 450-500 px jump
+    // back, then the glide, and a pointerdown/pointerup/click (left, even for a right click) that window
+    // capture listeners could see. A covered point is looked at again for COVER_CHECK_MS (an overlay
+    // fading out).
+    const reachesPoint = async (orig, selector, box, x, y) => {
+        const deadline = Date.now() + COVER_CHECK_MS;
+        let hit = await hitInBox(box, x, y);
+        while (hit === false && Date.now() < deadline) {
+            await sleep(80);
+            hit = await hitInBox(box, x, y);
+        }
+        if (hit !== null)
+            return hit;
+        // Only Playwright's trial can look inside a child frame. It moves the pointer: the cost of a point
+        // the isolated world cannot see, never of an ordinary click.
+        const at = { x: x - box.x, y: y - box.y };
+        try {
+            await orig(selector, { trial: true, timeout: COVER_CHECK_MS, position: at });
+            return true;
+        }
+        catch (e) {
+            if (!isTimeout(e) || String(e?.message ?? e).includes("intercepts pointer events"))
+                return false;
+        }
+        try {
+            // Not covered, just not "stable" yet: on the first page of a fresh headless browser Playwright's
+            // animation-frame wait can outlast the first look. One longer look.
+            await orig(selector, { trial: true, timeout: COVER_RETRY_MS, position: at });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    // The humanized form of page.click / dblclick / hover (and the click inside check/uncheck and the
+    // drop-down opener).
+    //
+    // Every Playwright option is honoured: `button`, `clickCount`, `delay` (the hold) and `modifiers`
+    // shape the press; `position` replaces the persona's point; `force` skips the covered-point check
+    // (and, as in Playwright, every wait); `trial` performs NO action (it runs Playwright's own trial, as
+    // documented). The caller's `timeout` is passed through unchanged. No Playwright trial runs before a
+    // humanized press (reachesPoint): only a point inside a child frame still needs one.
+    const targetedClick = async (orig, selector, options, noClick, nativeOpts) => {
+        const opts = options ?? {};
+        const o = normalizeClickOptions(opts);
+        const native = async () => {
+            if (!orig)
+                throw new Error("humanized click could not run");
             try {
-                const timeout = options.timeout ?? 30000;
-                const loc = page.locator(selector).first();
-                await loc.waitFor({ state: "visible", timeout });
-                await loc.scrollIntoViewIfNeeded({ timeout });
-                if (!(await loc.isEnabled()))
-                    return orig(selector, options);
-                let box = await loc.boundingBox();
-                if (!box)
-                    return orig(selector, options);
+                return await orig(selector, nativeOpts ?? opts);
+            }
+            finally {
+                // Native click/hover genuinely move the browser pointer to the element. Leaving `placed`
+                // false afterwards made the next wheel anchor believe the pointer was still unplaced.
+                st.placed = true;
+            }
+        };
+        if (o.trial)
+            return native();
+        try {
+            const timeout = opts.timeout; // undefined: the page's default, as Playwright would use
+            const loc = page.locator(selector).first();
+            // Playwright skips actionability with force: no wait then -- a target it would click hidden goes
+            // native at once instead of timing out first.
+            const box = await boxOf(loc, timeout, o.force, selector);
+            if (!box)
+                throw new NativeSignal();
+            if (!o.force && !(await loc.isEnabled()))
+                throw new NativeSignal();
+            let x, y;
+            if (o.position) {
+                // Playwright's position is relative to the PADDING box: add the border widths.
+                const info = await describe(box, null);
+                const bl = info ? info.bl || 0 : 0, bt = info ? info.bt || 0 : 0;
+                x = box.x + bl + o.position.x;
+                y = box.y + bt + o.position.y;
+            }
+            else {
+                ({ x, y } = clickPoint(box, st, persona));
+            }
+            if (!o.force && orig) {
+                // Stability, then covered-by: 50 ms on, the element must still fill `box` (an animation in
+                // flight does not) and own the click point -- no trusted press at a point some overlay owns.
+                // Either failing goes native: Playwright waits for it.
                 await sleep(50);
-                const box2 = await loc.boundingBox();
-                if (!box2 || Math.abs(box2.x - box.x) > 1 || Math.abs(box2.y - box.y) > 1) {
-                    return orig(selector, options);
-                }
-                box = box2;
-                const cp = clickPoint(box, st, persona);
-                const x = cp.x, y = cp.y;
-                // covered-by: don't fire a trusted click at a point some overlay owns. A TRIAL action runs
-                // Playwright's own hit test at exactly this point, in its utility world, and dispatches
-                // nothing; the old page.evaluate(elementFromPoint) ran in the page's world, where a hooked
-                // prototype saw it. A covered point times out fast -> the native path waits for it.
+                if (!(await reachesPoint(orig, selector, box, x, y)))
+                    throw new NativeSignal();
+            }
+            if (o.modifiers.length && !(nativeKbDown && nativeKbUp))
+                throw new NativeSignal();
+            if (noClick && o.modifiers.length) {
+                // hover with modifiers: Playwright holds them across the move
+                const held = [];
                 try {
-                    await orig(selector, { trial: true, timeout: COVER_CHECK_MS, position: { x: x - box.x, y: y - box.y } });
-                }
-                catch {
-                    return orig(selector, options); // covered -> let PW wait for it on top
+                    for (const m of o.modifiers) {
+                        await nativeKbDown(m);
+                        held.push(m);
+                        await sleep(rand(40, 110));
+                    }
+                    await glide(x, y);
                 }
-                await glide(x, y);
-                if (!noClick) {
-                    await sleep(rand(40, 130));
-                    await nativeClick(x, y, { delay: clickHold(persona) });
+                finally {
+                    for (const m of held.reverse()) {
+                        await sleep(rand(20, 80));
+                        try {
+                            await nativeKbUp(m);
+                        }
+                        catch { /* one failed keyup must not strand the others */ }
+                    }
                 }
                 return;
             }
-            catch {
-                return orig(selector, options);
-            }
-        };
+            await glide(x, y);
+            if (!noClick)
+                await pressAt(o);
+            return;
+        }
+        catch (e) {
+            if (isTimeout(e))
+                throw e;
+        }
+        // outside the try, so a native call that raises is not run a second time by the handler
+        return native();
     };
-    wrapTargeted("click", false);
-    wrapTargeted("hover", true);
+    page.click = (selector, options = {}) => locked(() => targetedClick(nativePageClick, selector, options, false, null));
+    page.hover = (selector, options = {}) => locked(() => targetedClick(nativePageHover, selector, options, true, null));
     // Marker the Locator-class patch keys off: humanize is active for THIS page.
     page._clearcoteHumanized = true;
     patchLocatorClass(page.locator("html"));
 }
-/** Choose a <select> option with the keyboard, so the ENGINE fires the events. Returns Playwright's
- * `[value]` result once the selection is VERIFIED, or null when the keyboard route cannot be shown
- * to have worked and the caller should fall back to native.
- *
- * Playwright's selectOption assigns the value and dispatches input+change from script. Those arrive
- * with isTrusted false, which is the single most reliable dropdown tell there is — the engine cannot
- * produce an untrusted change, so a page reading the flag knows the selection was not made by a
- * person. A <select> that has focus and is CLOSED steps on ArrowUp/ArrowDown and the browser emits
- * input then change itself, trusted, exactly as it does for a mouse. The fix is not to forge better
- * events, it is to stop forging them.
- *
- * Returns null whenever that cannot be guaranteed: a multi- or disabled select, an option that
- * cannot be resolved, an ElementHandle target, or a platform where arrows open the popup instead of
- * stepping (macOS). selectedIndex is verified afterwards rather than assumed — a silently wrong
- * selection is worse than an untrusted one. */
-async function trustedSelect(page, selector, values, timeout) {
-    try {
-        const one = (v) => (Array.isArray(v) && v.length === 1 ? v[0] : v);
-        const v = one(values);
-        let by = null, want = null;
-        if (v && typeof v === "object" && !v.constructor?.name?.includes("ElementHandle")) {
-            if (v.index != null) {
-                by = "index";
-                want = v.index;
-            }
-            else if (v.label != null) {
-                by = "label";
-                want = v.label;
-            }
-            else if (v.value != null) {
-                by = "value";
-                want = v.value;
-            }
-        }
-        else if (typeof v === "string") {
-            by = "value";
-            want = v;
+/** @internal exported for tests. Playwright's selectOption values -> the wanted options, or null when
+ * the humane route does not apply (nothing asked, an ElementHandle, an option object naming more than
+ * one field): the caller then runs stock selectOption. */
+export function selectWants(values) {
+    if (values === null || values === undefined)
+        return null;
+    const list = Array.isArray(values) ? values : [values];
+    const out = [];
+    for (const x of list) {
+        if (typeof x === "string") {
+            out.push({ kind: "value", v: x });
+            continue;
         }
-        if (by === null)
+        if (!x || typeof x !== "object")
             return null;
-        // Read in an isolated world (./isolated.ts): the page never sees the option lookup.
-        const plan = await worldFor(page).evaluate(ISO_SELECT_PLAN, { sel: selector, by, want });
-        if (!plan)
+        if (typeof x.asElement === "function" || /Handle/.test(x.constructor?.name ?? ""))
             return null;
-        if (plan.to === plan.from)
-            return [plan.ret]; // already selected; forge nothing
-        await page.focus(selector, { timeout });
-        await sleep(rand(60, 160));
-        const step = plan.to > plan.from ? "ArrowDown" : "ArrowUp";
-        for (let i = 0; i < Math.abs(plan.to - plan.from); i++) {
-            // page.keyboard.press — humanized by attachHumanize, so the hold comes with it.
-            await page.keyboard.press(step);
-            await sleep(rand(45, 120));
-        }
-        const got = await worldFor(page).evaluate(ISO_SELECTED_INDEX, selector);
-        if (got === plan.to)
-            return [plan.ret];
+        const keys = ["value", "label", "index"].filter((k) => x[k] !== undefined && x[k] !== null);
+        if (keys.length !== 1)
+            return null;
+        if (keys[0] === "index") {
+            if (typeof x.index !== "number" || !Number.isInteger(x.index))
+                return null;
+            out.push({ kind: "index", v: x.index });
+        }
+        else if (keys[0] === "label") {
+            out.push({ kind: "label", v: String(x.label) });
+        }
+        else {
+            out.push({ kind: "valueOnly", v: String(x.value) });
+        }
+    }
+    return out.length ? out : null;
+}
+/** @internal exported for tests. The option index a want resolves to, Playwright's way, or -1. */
+export function wantIndex(opts, w) {
+    switch (w.kind) {
+        case "value": return matchOption(opts, { value: w.v });
+        case "label": return matchOption(opts, { label: w.v });
+        case "index": return matchOption(opts, { index: w.v });
+        case "valueOnly": return opts.findIndex((o) => o.value === w.v);
     }
-    catch { /* fall back */ }
-    return null;
 }
 // --------------------------------------------------------------------------- locator patch
 let locatorPatched = false;
+// The options each page-level humanized method understands. Everything the caller passed that a page
+// method accepts travels with it: the old fwd sent ONLY `timeout`, which turned
+// click({button: "right"}) into a left click and click({trial: true}) into a real one.
+const CLICK_OPTS = ["button", "clickCount", "delay", "force", "modifiers", "noWaitAfter", "position", "timeout", "trial"];
+const HOVER_OPTS = ["force", "modifiers", "noWaitAfter", "position", "timeout", "trial"];
+const DBL_OPTS = ["button", "delay", "force", "modifiers", "noWaitAfter", "position", "timeout", "trial"];
+const FILL_OPTS = ["force", "noWaitAfter", "timeout"];
+const TYPE_OPTS = ["timeout"];
+const PRESS_OPTS = ["delay", "noWaitAfter", "timeout"];
+const SELECT_OPTS = ["force", "noWaitAfter", "timeout"];
+const CHECK_OPTS = ["force", "noWaitAfter", "position", "timeout", "trial"];
+/** @internal exported for tests: the subset of `kw` named in `names` (null/undefined dropped). */
+export function pickOptions(kw, names) {
+    const out = {};
+    if (kw && typeof kw === "object")
+        for (const k of names)
+            if (kw[k] !== undefined && kw[k] !== null)
+                out[k] = kw[k];
+    return out;
+}
 /** Patch the Locator prototype once so locator.* interactions route through the humanized page.*
  * methods. Each is a no-op unless the locator's page has humanize active AND the locator targets
- * the main frame; anything else (frame locators, exotic selectors, errors) falls through to the
- * original Playwright behaviour. Composes if another library already patched the prototype. */
+ * the main frame; anything else (frame locators, another page) uses the original Playwright method.
+ * Locator actions stay STRICT: more than one match goes to the native method, which raises
+ * Playwright's own strict-mode error. Once routed, errors propagate as they are (the page method
+ * already ran its own native fallback, so nothing is retried). Composes if another library already
+ * patched the prototype. */
 function patchLocatorClass(sample) {
     if (locatorPatched)
         return;
@@ -863,134 +1780,101 @@ function patchLocatorClass(sample) {
     const proto = Object.getPrototypeOf(sample);
     if (!proto)
         return;
-    const oFill = proto.fill, oClick = proto.click, oType = proto.type, oDbl = proto.dblclick, oHover = proto.hover, oPress = proto.press, oPressSeq = proto.pressSequentially, oClear = proto.clear, oTap = proto.tap, oCheck = proto.check, oUncheck = proto.uncheck, oDragTo = proto.dragTo, oSelectOption = proto.selectOption;
+    const oFill = proto.fill, oClick = proto.click, oType = proto.type, oDbl = proto.dblclick, oHover = proto.hover, oPress = proto.press, oPressSeq = proto.pressSequentially, oClear = proto.clear, oTap = proto.tap, oCheck = proto.check, oUncheck = proto.uncheck, oDragTo = proto.dragTo, oSelectOption = proto.selectOption, oSetChecked = proto.setChecked;
+    // Main-frame locators only: a FrameLocator's child keeps the MAIN frame as its _frame and enters the
+    // iframe through its selector, so the selector is what tells. Routed through page.fill, its
+    // prefilled field was never cleared ("old" + "new" = "oldnew"); frame locators stay native.
     const on = (self) => {
         const pg = self.page();
         if (!pg || !pg._clearcoteHumanized)
             return false;
         try {
+            if (String(self._selector ?? "").includes("internal:control=enter-frame"))
+                return false;
             return self._frame === pg.mainFrame();
         }
         catch {
             return false;
         }
     };
+    // Locator actions are STRICT in Playwright: more than one match is an error. The page-level methods
+    // they route through take the first match, so check the count here and let the native call raise
+    // its own strict-mode error when it is not at most one.
+    const strict = async (self) => {
+        try {
+            return (await self.count()) <= 1;
+        }
+        catch {
+            return false;
+        }
+    };
     const sel = (self) => self._selector;
-    const fwd = (kw) => (kw && kw.timeout != null ? { timeout: kw.timeout } : {});
+    // Once routed, every error propagates: the page-level wrappers own the native fallback, so retrying
+    // the original locator method here ran the action a second (or third) time -- a checkbox whose click
+    // is cancelled was clicked three times.
+    const route = async (self, fn) => {
+        if (on(self) && await strict(self))
+            return [true, await fn()];
+        return [false, undefined];
+    };
     proto.fill = async function (value, kw = {}) {
-        if (on(this)) {
-            try {
-                return await this.page().fill(sel(this), value, fwd(kw));
-            }
-            catch { /* fall back */ }
-        }
-        return oFill.call(this, value, kw);
+        const [done, r] = await route(this, () => this.page().fill(sel(this), value, pickOptions(kw, FILL_OPTS)));
+        return done ? r : oFill.call(this, value, kw);
     };
     proto.click = async function (kw = {}) {
-        if (on(this)) {
-            try {
-                return await this.page().click(sel(this), fwd(kw));
-            }
-            catch { /* fall back */ }
-        }
-        return oClick.call(this, kw);
+        const [done, r] = await route(this, () => this.page().click(sel(this), pickOptions(kw, CLICK_OPTS)));
+        return done ? r : oClick.call(this, kw);
     };
     proto.type = async function (text, kw = {}) {
-        if (on(this)) {
-            try {
-                return await this.page().type(sel(this), text, fwd(kw));
-            }
-            catch { /* fall back */ }
-        }
-        return oType.call(this, text, kw);
+        const [done, r] = await route(this, () => this.page().type(sel(this), text, pickOptions(kw, TYPE_OPTS)));
+        return done ? r : oType.call(this, text, kw);
     };
     proto.dblclick = async function (kw = {}) {
-        if (on(this)) {
-            try {
-                return await this.page().dblclick(sel(this), fwd(kw));
-            }
-            catch { /* fall back */ }
-        }
-        return oDbl.call(this, kw);
+        const [done, r] = await route(this, () => this.page().dblclick(sel(this), pickOptions(kw, DBL_OPTS)));
+        return done ? r : oDbl.call(this, kw);
     };
     proto.hover = async function (kw = {}) {
-        if (on(this)) {
-            try {
-                return await this.page().hover(sel(this), fwd(kw));
-            }
-            catch { /* fall back */ }
-        }
-        return oHover.call(this, kw);
+        const [done, r] = await route(this, () => this.page().hover(sel(this), pickOptions(kw, HOVER_OPTS)));
+        return done ? r : oHover.call(this, kw);
     };
     proto.press = async function (key, kw = {}) {
-        if (on(this)) {
-            try {
-                return await this.page().press(sel(this), key, fwd(kw));
-            }
-            catch { /* fall back */ }
-        }
-        return oPress.call(this, key, kw);
+        const [done, r] = await route(this, () => this.page().press(sel(this), key, pickOptions(kw, PRESS_OPTS)));
+        return done ? r : oPress.call(this, key, kw);
     };
     proto.pressSequentially = async function (text, kw = {}) {
-        if (on(this)) {
-            try {
-                return await this.page().type(sel(this), text, fwd(kw));
-            }
-            catch { /* fall back */ }
-        }
-        return oPressSeq.call(this, text, kw);
+        const [done, r] = await route(this, () => this.page().type(sel(this), text, pickOptions(kw, TYPE_OPTS)));
+        return done ? r : oPressSeq.call(this, text, kw);
     };
     proto.clear = async function (kw = {}) {
-        if (on(this)) {
-            try {
-                return await this.page().fill(sel(this), "", fwd(kw));
-            }
-            catch { /* fall back */ }
-        }
-        return oClear.call(this, kw);
+        const [done, r] = await route(this, () => this.page().fill(sel(this), "", pickOptions(kw, FILL_OPTS)));
+        return done ? r : oClear.call(this, kw);
     };
     proto.tap = async function (kw = {}) {
-        if (on(this)) {
-            try {
-                return await this.page().click(sel(this), fwd(kw));
-            }
-            catch { /* fall back */ }
-        }
-        return oTap.call(this, kw);
+        const [done, r] = await route(this, () => this.page().click(sel(this), pickOptions(kw, HOVER_OPTS)));
+        return done ? r : oTap.call(this, kw);
     };
     proto.check = async function (kw = {}) {
-        if (on(this)) {
-            try {
-                if (!(await this.isChecked()))
-                    return await this.page().click(sel(this), fwd(kw));
-                return;
-            }
-            catch { /* fall back */ }
-        }
-        return oCheck.call(this, kw);
+        const [done, r] = await route(this, () => this.page().check(sel(this), pickOptions(kw, CHECK_OPTS)));
+        return done ? r : oCheck.call(this, kw);
     };
     proto.uncheck = async function (kw = {}) {
-        if (on(this)) {
-            try {
-                if (await this.isChecked())
-                    return await this.page().click(sel(this), fwd(kw));
-                return;
-            }
-            catch { /* fall back */ }
-        }
-        return oUncheck.call(this, kw);
-    };
-    proto.selectOption = async function (values, kw = {}) {
-        // Routed through the page method (which glides to the control first) rather than calling
-        // trustedSelect straight, so a locator selection gets the same pre-move as a locator click.
-        if (on(this)) {
-            try {
-                return await this.page().selectOption(sel(this), values, fwd(kw));
-            }
-            catch { /* fall back */ }
-        }
-        return oSelectOption.call(this, values, kw);
+        const [done, r] = await route(this, () => this.page().uncheck(sel(this), pickOptions(kw, CHECK_OPTS)));
+        return done ? r : oUncheck.call(this, kw);
     };
+    if (typeof oSetChecked === "function") {
+        proto.setChecked = async function (checked, kw = {}) {
+            const [done, r] = await route(this, () => this.page().setChecked(sel(this), checked, pickOptions(kw, CHECK_OPTS)));
+            return done ? r : oSetChecked.call(this, checked, kw);
+        };
+    }
+    // Delegate to the humanized page.selectOption, like every other method here: one implementation
+    // behind the page method is what stops the two entry points drifting apart.
+    if (typeof oSelectOption === "function") {
+        proto.selectOption = async function (values, kw = {}) {
+            const [done, r] = await route(this, () => this.page().selectOption(sel(this), values, pickOptions(kw, SELECT_OPTS)));
+            return done ? r : oSelectOption.call(this, values, kw);
+        };
+    }
     proto.dragTo = async function (target, kw = {}) {
         if (on(this)) {
             try {