clearcote 0.48.0 → 0.49.0

package/dist/humanize.js

@@ -26,9 +26,11 @@
 // ./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 { errors as pwErrors } from "playwright-core";
 import { makePersona, planMove, dragDwell, clickHold, keyDwell, clickPoint, planAmbient, gaussFrom, rolloverRate, wheelNotches, platformFromNavigator, WHEEL_NOTCH_PX, } from "./motion.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";
+import { keepInView, trimTo, walk } from "./pacing.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, roundHalfEven, worldFor, } from "./isolated.js";
+import { DEFAULT_TYPO_RATE, NEARBY_LETTERS, classifyField, datetimeEqual, enginePathOk, fitMaxlength, formattedEqual, maskKept, matchOption, normalizeClickOptions, numericEqual, planDatetime, planSelect, planTypo, prePressMs, 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 = `(() => {
@@ -55,22 +57,24 @@ const ROLL_KEYS = new Set("abcdefghijklmnopqrstuvwxyz0123456789 ,.;'/-=");
 /** The persona platform when the page cannot say: the SDK's default persona follows the host. */
 const hostWheelPlatform = () => process.platform === "win32" ? "windows" : process.platform === "darwin" ? "macos" : "linux";
 // The engine's pointer-path command. r34 renamed Browser.humanizedClick to Browser.dispatchPointerPath:
-// the old name was listed in /json/protocol for anyone who asked, and "humanizedClick" is known
-// vocabulary, so the method list alone said what the build was for. r33 and older only know the old
+// "humanizedClick" is known vocabulary. The served /json/protocol still lists the old name (measured on
+// r38, SC 210); r40 keeps the new one out of it. r33 and older only know the old
 // name, so the new one goes first and the old one is the fallback for a method-not-found only.
 /** @internal exported for tests */
 export const POINTER_PATH = "Browser.dispatchPointerPath";
 /** @internal exported for tests */
 export const POINTER_PATH_LEGACY = "Browser.humanizedClick";
-// Which name each browser answered to, so only its first call can pay for a miss.
+// Which name each browser answered to, so only its first call can pay for a miss. NO_ENGINE_PATH: the
+// engine knew neither name -- remembered too, so a new page of that browser does not probe both again.
 const engineMethodNames = new WeakMap();
+const NO_ENGINE_PATH = "";
 // A CDP method-not-found: the engine predates the name. A raw CDP client sees code -32601;
 // Playwright's CDPSession keeps only the message ("Protocol error (X): 'X' wasn't found").
 const isMethodNotFound = (e) => e?.code === -32601 || /-32601|wasn't found|method not found/i.test(String(e?.message ?? e));
 /** @internal exported for tests. Send `method`, or `legacy` when the engine predates the rename, and
- * remember per `cacheKey` (a Browser, or the context when there is none) which one answered. Any
- * error other than method-not-found propagates as-is: retrying a real failure under the old name
- * would only replay it. */
+ * remember per `cacheKey` (a Browser, or the context when there is none) which one answered -- or that
+ * neither did, after which every call fails at once without a round trip. Any error other than
+ * method-not-found propagates as-is: retrying a real failure under the old name would only replay it. */
 export async function sendEngineCommand(session, cacheKey, method, legacy, params) {
     let names = engineMethodNames.get(cacheKey);
     if (!names) {
@@ -78,6 +82,8 @@ export async function sendEngineCommand(session, cacheKey, method, legacy, param
         engineMethodNames.set(cacheKey, names);
     }
     const known = names.get(method);
+    if (known === NO_ENGINE_PATH)
+        throw Object.assign(new Error(`'${method}' wasn't found`), { code: -32601 });
     if (known)
         return session.send(known, params);
     try {
@@ -89,10 +95,42 @@ export async function sendEngineCommand(session, cacheKey, method, legacy, param
         if (!isMethodNotFound(e))
             throw e;
     }
-    const r = await session.send(legacy, params);
+    let r;
+    try {
+        r = await session.send(legacy, params);
+    }
+    catch (e) {
+        if (isMethodNotFound(e))
+            names.set(method, NO_ENGINE_PATH);
+        throw e;
+    }
     names.set(method, legacy);
     return r;
 }
+/** @internal exported for tests. Did this browser's engine already say it has no pointer-path command? */
+export function engineHasNoPointerPath(cacheKey) {
+    return !!cacheKey && engineMethodNames.get(cacheKey)?.get(POINTER_PATH) === NO_ENGINE_PATH;
+}
+/** @internal exported for tests. The page's default action timeout (setDefaultTimeout, else the
+ * context's, else Playwright's 30 s). */
+export function defaultTimeoutMs(page) {
+    try {
+        const t = page?._timeoutSettings?.timeout({});
+        if (typeof t === "number" && Number.isFinite(t))
+            return t;
+    }
+    catch { /* not this Playwright's shape */ }
+    return 30_000;
+}
+/** @internal exported for tests. A Playwright TimeoutError for a trial whose checks never passed,
+ * worded like Playwright's. */
+export function trialTimeoutError(selector, ms, why) {
+    const msg = `Timeout ${Math.round(ms)}ms exceeded.\nCall log:\n  - waiting for locator('${selector}')\n  - ${why}`;
+    const E = pwErrors?.TimeoutError;
+    if (typeof E === "function")
+        return Object.assign(new E(msg), { [SDK_PW_ERROR]: true });
+    return Object.assign(new Error(msg), { name: "TimeoutError", [SDK_PW_ERROR]: true });
+}
 // The characters a US-layout keyboard (Playwright's, and the engine's keyboard.getLayoutMap())
 // types with Shift held: capitals and the shifted symbols.
 const SHIFTED_SYMBOLS = new Set('~!@#$%^&*()_+{}|:"<>?');
@@ -125,6 +163,52 @@ export function typoRate() {
 export function isTimeout(err) {
     return err?.name === "TimeoutError";
 }
+// Playwright words every error after the API the caller used: "page.click: Timeout 800ms exceeded.",
+// "locator.check: Error: Not a checkbox or radio button". A humanized call rejected with the error of
+// whatever Playwright call it made inside (locator.waitFor, locator.isChecked; verifier B, SC 210) --
+// the same class, but a message a caller matching on it would not recognise. Pre-existing in 0.48.0.
+const API_PREFIX = /^[A-Za-z_]+\.[A-Za-z_]+: /;
+/** Marks an error the SDK raises in Playwright's place (a trial that never passed, a checkbox that would
+ * not change): it gets the caller's API prefix too. */
+const SDK_PW_ERROR = Symbol.for("clearcote.playwrightError");
+/** @internal exported for tests. `err` worded as Playwright words an error of `api` ("page.click",
+ * "locator.setChecked"): the inner call's "locator.waitFor: " prefix replaced (or, for an error the SDK
+ * raised in Playwright's place, added), in the message and the stack's first line. The object, and so
+ * its class, is kept. Anything else is returned as it is. */
+export function asApiError(err, api) {
+    const e = err;
+    if (!(e instanceof Error) || typeof e.message !== "string")
+        return err;
+    const m = API_PREFIX.exec(e.message);
+    if (!m && !err[SDK_PW_ERROR] && e.name !== "TimeoutError")
+        return err;
+    const msg = api + ": " + (m ? e.message.slice(m[0].length) : e.message);
+    if (msg === e.message)
+        return err;
+    const old = e.message;
+    try {
+        e.message = msg;
+        if (typeof e.stack === "string")
+            e.stack = e.stack.replace(old, msg);
+    }
+    catch { /* a frozen error keeps its words */ }
+    return err;
+}
+/** @internal `fn`, with every Playwright error it rejects with worded as `api`'s (asApiError). */
+export function apiErrors(api, fn) {
+    return async (...a) => {
+        try {
+            return await fn(...a);
+        }
+        catch (e) {
+            throw asApiError(e, api);
+        }
+    };
+}
+/** @internal An Error the SDK raises where Playwright would, worded by the caller's API (apiErrors). */
+export function sdkPlaywrightError(message) {
+    return Object.assign(new Error(message), { [SDK_PW_ERROR]: true });
+}
 /** 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"; }
@@ -144,6 +228,22 @@ export function createInputLock() {
     };
 }
 /** Wrap a single page's input methods + (optionally) inject the cursor overlay. */
+/** Which clicks the engine pointer path (Browser.dispatchPointerPath) may walk, from
+ * CLEARCOTE_HUMANIZE_ENGINE_CLICKS: "off" (also 0/false/no) never; "all" (also "selector") coordinate
+ * clicks AND targeted page.click(selector) / locator.click() clicks; anything else (the default)
+ * coordinate clicks only, as before.
+ *
+ * Targeted clicks stay on the SDK planner by default (SC 210 lane S, measured on r38): the engine
+ * presses 9 ms after its last move (the planner's press waits 40-130 ms), and it walks from its own last
+ * position, which an SDK glide does not update. Same values as Python `_engine_clicks_mode`. */
+export function engineClicksMode() {
+    const v = (process.env.CLEARCOTE_HUMANIZE_ENGINE_CLICKS || "").trim().toLowerCase();
+    if (["0", "off", "false", "no", "none"].includes(v))
+        return "off";
+    if (["all", "selector", "selectors"].includes(v))
+        return "all";
+    return "coords";
+}
 export async function attachHumanize(browser, page, opts) {
     // IDEMPOTENCY GUARD — do not remove.
     //
@@ -193,22 +293,37 @@ export async function attachHumanize(browser, page, opts) {
     // Walk a planned trajectory (motion.ts) with native (trusted) mouse.move + off-protocol sleeps.
     // Native input carries the button state, so a button pressed via mouse.down() stays held across
     // the whole path — the same code powers a free move AND a held-button drag.
+    //
+    // Paced against a WALL CLOCK (pacing.ts): each sample goes out at its planned time and late ones
+    // are skipped (never the last, and no skip hops more than 40 px, or 20 px once nothing has been
+    // dispatched for 40 ms: MAX_JUMP_PX / IDLE_HOP_PX). "Move, then sleep the planned gap" added the
+    // ~27 ms mouse.move round trip to every 6-8 ms sample: a 1.05 s planned glide took 3.5-5.4 s on
+    // PRO r38 (SC 209), ambient motion 5.7x as long.
     const dispatch = async (steps) => {
-        for (const s of steps) {
+        const vp = await viewBounds();
+        await walk(vp ? keepInView(steps, vp.width, vp.height) : steps, async (x, y) => { await nativeMove(x, y); st.placed = true; });
+    };
+    // The viewport a planned path is kept inside (keepInView: the planner's overshoot arcs left the window
+    // near its edges, verifier B), read in the isolated world at most every 2 s; null when it cannot be read.
+    let vb = null;
+    const viewBounds = async () => {
+        const now = Date.now();
+        if (vb === null || now - vb.t > 2000) {
+            let vp = null;
             try {
-                await nativeMove(s.x, s.y);
+                const wh = await worldFor(page).evaluate(ISO_VIEWPORT);
+                if (wh && wh[0] && wh[1])
+                    vp = { width: Number(wh[0]), height: Number(wh[1]) };
             }
-            catch {
-                break;
-            }
-            st.placed = true;
-            await sleep(s.sleepMs);
+            catch { /* detached / navigating / no CDP: no clamp */ }
+            vb = { t: now, vp };
         }
+        return vb.vp;
     };
     // Move to (x, y) as a minimum-jerk sum-of-submovements path (primary ballistic + corrective homing)
     // with colored sub-pixel noise and Fitts-scaled duration. `settle` adds a seating jiggle (drag).
     const glide = async (x, y, o = {}) => {
-        await dispatch(planMove(st, { x, y }, persona, { settle: o.settle, targetW: o.targetW }));
+        await dispatch(planMove(st, { x, y }, persona, { settle: o.settle, targetW: o.targetW, held: o.held }));
         st.x = x;
         st.y = y;
     };
@@ -217,11 +332,23 @@ export async function attachHumanize(browser, page, opts) {
     // recorded human paths for PRO, engine bezier for free, tiered by the engine license gate).
     // Held-button DRAGS stay native; falls back to the SDK bezier if the method is unavailable
     // (older engine / no browser session).
-    const eng = { session: null, key: null, tid: null, ok: true };
+    const eng = { session: null, key: null, tid: null, ok: true, at: null };
+    // The engine walks from ITS OWN last position on this page, not from where an SDK glide left the
+    // pointer. Measured on r38 (SC 210): an engine click at (300,300), an SDK glide to (800,550), then
+    // mouse.click(400,200) through the engine -- its first sample was at (300,300), a 559 px teleport
+    // from where the pointer was. So the engine walks only while nothing else has moved the pointer
+    // since its own last walk (before its first walk: while nothing has moved it at all).
+    const engineInSync = () => (eng.at === null ? !st.placed : st.x === eng.at.x && st.y === eng.at.y);
     const engineGlide = async (x, y, noClick) => {
-        if (!eng.ok)
+        if (!eng.ok || !engineInSync())
             return false;
         try {
+            // This browser's engine already said it has neither command: no sessions, no probe.
+            const ctx0 = page.context();
+            if (engineHasNoPointerPath((ctx0.browser ? ctx0.browser() : null) ?? ctx0)) {
+                eng.ok = false;
+                return false;
+            }
             if (eng.session === null) {
                 const ctx = page.context();
                 const tsession = await ctx.newCDPSession(page);
@@ -234,13 +361,17 @@ export async function attachHumanize(browser, page, opts) {
             const dx = x - st.x, dy = y - st.y;
             const dist = Math.sqrt(dx * dx + dy * dy);
             const dur = Math.min(1.10, Math.max(0.28, 0.30 + dist / 1700)) * (0.85 + 0.30 * Math.random());
+            const tSend = Date.now();
             await sendEngineCommand(eng.session, eng.key, POINTER_PATH, POINTER_PATH_LEGACY, { targetId: eng.tid, x, y, duration: dur, noClick });
             // The engine walks the trajectory in the BROWSER process and answers this command before it
             // has finished. Without waiting, a following mouse.down() fires at the cursor's STALE
             // position — measured: a move to (110,58) then a press landed at (981,629), on <body>
             // instead of the target, so every move-then-press sequence (drag, press-and-hold,
             // drag-and-drop) acted on the wrong element.
-            await sleep(dur * 1000);
+            // r38 answers only after the walk AND the click (send returned 772 ms after a 600 ms walk, 2 ms
+            // after the release, SC 210): wait only for what is left of `dur`, so an engine that answers
+            // late does not add a second, idle `dur` after every click.
+            await sleep(Math.max(0, dur * 1000 - (Date.now() - tSend)));
             try {
                 await nativeMove(x, y);
             }
@@ -248,6 +379,7 @@ export async function attachHumanize(browser, page, opts) {
             st.x = x;
             st.y = y;
             st.placed = true;
+            eng.at = { x, y };
             return true;
         }
         catch {
@@ -283,7 +415,9 @@ export async function attachHumanize(browser, page, opts) {
     // an action needs one but names no coordinates.
     const ambient = async (ms) => {
         try {
-            const steps = planAmbient(st, await viewport(), persona, ms);
+            // planAmbient overruns its budget (whole excursions, rests drawn at 0.9-1.4x a frame): cut the
+            // plan at a slow sample near ms so ambientMotion(ms) lasts about ms.
+            const steps = trimTo(planAmbient(st, await viewport(), persona, ms), ms);
             await dispatch(steps);
             if (steps.length) {
                 st.x = steps[steps.length - 1].x;
@@ -328,7 +462,9 @@ export async function attachHumanize(browser, page, opts) {
     // mouse.click keeps engine routing: it performs move+click entirely engine-side, where nothing
     // races the trajectory. glide() is still fully humanized (minimum-jerk, colored noise, Fitts).
     mouse.move = async (x, y) => {
-        await glide(x, y);
+        // A move while the button is held is a DRAG leg: planDrag keeps it on the line between grab and
+        // drop (an aimed reach's arc took a slider handle 47 px off a 40 px track, SC 209).
+        await glide(x, y, { held: st.held });
     };
     // down/up are wrapped to TRACK the held state mouse.move needs, and — critically — to make the
     // press position DETERMINISTIC. The engine answers its pointer path before the trajectory has
@@ -336,6 +472,29 @@ export async function attachHumanize(browser, page, opts) {
     // enough: measured on Node, a move to (110,58) was still mid-flight at (416,504) when the press
     // fired, landing on <body>. Re-issuing a native move to the tracked target immediately before
     // the press pins the cursor to where the caller asked, whatever the trajectory is doing.
+    // The pause between the pointer coming to rest and the button going down (forms.prePressMs: 40-250
+    // ms, right-skewed, centred per identity). Measured on r38 before it: the focus click before typing
+    // pressed ~4 ms after the last pointermove, a drag grab ~21 ms.
+    const prePress = async () => { await sleep(prePressMs(persona.seed)); };
+    // What is left of a button hold once mouse.down() has returned: the hold runs from when the press was
+    // SENT. mouse.down() returns only after the page handled the press, and a <select> opens its popup
+    // inside that, so a hold slept afterwards reached the page ~30-80 ms longer than planned.
+    const holdRest = (holdMs, t0) => Math.max(0, holdMs - (Date.now() - t0));
+    // Press and release the left button where the last glide left the pointer, after the pre-press
+    // pause. Native down/up, so nothing moves: Playwright's mouse.click(x, y) sends one more mouseMoved
+    // first, and THAT was the last pointermove the page saw, ~4 ms before the press.
+    const pressHere = async (x, y, holdMs) => {
+        const hold = holdMs ?? clickHold(persona);
+        await prePress();
+        const t0 = Date.now();
+        await nativeDown();
+        try {
+            await sleep(holdRest(hold, t0));
+        }
+        finally {
+            await nativeUp();
+        } // never leave the button down
+    };
     mouse.down = async (...a) => {
         // DELIBERATELY NO PLACEMENT WHEN THE POINTER HAS NEVER MOVED.
         //
@@ -354,6 +513,9 @@ export async function attachHumanize(browser, page, opts) {
                 await nativeMove(st.x, st.y);
             }
             catch { /* best effort: keep the press on target */ }
+            // The hand has arrived; it confirms the target before the button goes down. The pin is itself
+            // a pointermove, so the pause comes after it. A down() with no move before it stays instant.
+            await prePress();
         }
         st.held = true;
         try {
@@ -375,12 +537,12 @@ export async function attachHumanize(browser, page, opts) {
     // 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))
+        if (enginePathOk(o) && engineClicksMode() !== "off" && await engineGlide(x, y, false))
             return;
         await glide(x, y);
         try {
             if (o.modifiers.length && !(nativeKbDown && nativeKbUp)) {
-                await sleep(rand(40, 130)); // brief dwell before pressing, like a human
+                await prePress(); // the hand confirms the target before it presses
                 // 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;
@@ -499,6 +661,8 @@ export async function attachHumanize(browser, page, opts) {
     const keyboard = page.keyboard;
     const nativeKbType = keyboard.type.bind(keyboard);
     const nativeKbPress = keyboard.press.bind(keyboard);
+    // A bulk fill's paste (Input.insertText).
+    const nativeKbInsert = typeof keyboard.insertText === "function" ? keyboard.insertText.bind(keyboard) : undefined;
     // A page-like keyboard without down/up still gets every other humanization; it just types
     // capitals without the Shift key, as before.
     const nativeKbDown = typeof keyboard.down === "function" ? keyboard.down.bind(keyboard) : undefined;
@@ -527,8 +691,8 @@ export async function attachHumanize(browser, page, opts) {
     };
     // 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
+    // persona's, and modifiers held around the whole press with a lead before it (80-360 ms: 40-110 ms
+    // per modifier plus the 40-250 ms pre-press pause) and a 20-80 ms lag after, as fingers do. Native
     // down/up, so nothing moves.
     const pressAt = async (o) => {
         const held = [];
@@ -538,13 +702,14 @@ export async function attachHumanize(browser, page, opts) {
                 held.push(m);
                 await sleep(rand(40, 110));
             }
-            await sleep(rand(40, 130)); // brief dwell before pressing, like a human
+            await prePress(); // the hand confirms the target before it presses
             const n = o.clickCount;
             for (let i = 1; i <= n; i++) {
                 const hold = o.delay ?? clickHold(persona);
+                const t0 = Date.now();
                 await nativeDown({ button: o.button, clickCount: i });
                 try {
-                    await sleep(hold);
+                    await sleep(holdRest(hold, t0));
                 }
                 finally {
                     await nativeUp({ button: o.button, clickCount: i }); // never leave the button down
@@ -862,18 +1027,24 @@ export async function attachHumanize(browser, page, opts) {
         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) => {
+    // cannot be told here (CDP is unavailable). A point inside a child frame is answered by the <iframe>
+    // element that holds it (IsolatedWorld.nodeAt).
+    // `sel`: a plain-CSS selector for the element, when the caller has one: whether the hit is THAT
+    // element (ISO_HIT_IN_BOX), not just one that fills the box.
+    const hitInBox = async (box, x, y, sel = null) => {
         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 });
+        const b = { x: box.x, y: box.y, width: box.width, height: box.height };
+        if (sel)
+            b.sel = sel;
+        const res = await w.callOnNode(nid, ISO_HIT_IN_BOX, b);
         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;
+    const hitOk = async (box, sel = null) => (await hitInBox(box, box.x + box.width / 2, box.y + box.height / 2, sel)) === 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 --
@@ -894,7 +1065,7 @@ export async function attachHumanize(browser, page, opts) {
             return null;
         }
         let box = rectBox(r);
-        if (box && !((await inView(box)) && (await hitOk(box)))) {
+        if (box && !((await inView(box)) && (await hitOk(box, selector)))) {
             // 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 }));
@@ -938,12 +1109,12 @@ export async function attachHumanize(browser, page, opts) {
         if (css)
             return css;
         let box = await loc.boundingBox();
-        if (box && !((await inView(box)) && (await hitOk(box)))) {
+        if (box && !((await inView(box)) && (await hitOk(box, selector)))) {
             // 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)))
+            if (moved && (await inView(moved)) && (await hitOk(moved, selector)))
                 return moved;
             await loc.scrollIntoViewIfNeeded({ timeout });
             box = await loc.boundingBox();
@@ -1002,10 +1173,10 @@ export async function attachHumanize(browser, page, opts) {
         else if (info.disabled) {
             return false;
         }
-        const pt = at ? { x: at[0], y: at[1] } : clickPoint(box, st, persona); // 2D gaussian toward the centre
+        const p0 = at ? { x: at[0], y: at[1] } : clickPoint(box, st, persona); // 2D gaussian toward the centre
+        const pt = { x: roundHalfEven(p0.x), y: roundHalfEven(p0.y) }; // the pixel the hit test answered for
         await glide(pt.x, pt.y);
-        await sleep(rand(40, 130));
-        await nativeClick(pt.x, pt.y, { delay: clickHold(persona) });
+        await pressHere(pt.x, pt.y);
         return true;
     };
     // Ctrl+A (Cmd+A on a Mac engine) the way a hand does it: the modifier goes down a moment before the
@@ -1083,16 +1254,30 @@ export async function attachHumanize(browser, page, opts) {
         // 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));
+    page.type = apiErrors("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");
+        // What the field can hold: a maxlength keeps the first N characters (what Playwright's insertText
+        // leaves too), and a person types only those -- the field stops taking keys.
+        let want = value;
+        let limit = [null, null, null];
+        if (!isCe) {
+            limit = info
+                ? [info.maxlength, info.tag, info.type]
+                : [await loc.getAttribute("maxlength"),
+                    (await loc.locator("xpath=self::textarea").count()) ? "textarea" : "input", (await loc.getAttribute("type")) || ""];
+            want = fitMaxlength(value, ...limit);
+        }
+        // Bulk values (over 200 characters) are still inserted at once -- typing thousands of keys would
+        // crawl -- but the way a person pastes: glide to the field, click into it, then insert.
+        const bulk = Array.from(want).length > 200; // what the field holds: a 300-character value cut to 5 is typed
+        if (bulk && !nativeKbInsert)
+            return false;
         if (!(await focusClick(box, box ? provenPoint(box, info) : null, loc, selector)))
             return false;
         await sleep(rand(40, 120));
@@ -1106,11 +1291,20 @@ export async function attachHumanize(browser, page, opts) {
                 return null;
             }
         };
+        const put = async (text, typos = true) => {
+            if (bulk) {
+                await sleep(rand(120, 320)); // the paste shortcut, after the click
+                await nativeKbInsert(text);
+            }
+            else {
+                await humanTypeText(text, info, typos);
+            }
+        };
         if (isCe) {
             const cur = info ? info.value : null;
             if (cur)
                 await clearFocused();
-            await humanTypeText(value, info);
+            await put(want);
             return true; // contenteditable: Playwright's fill sets text the same way; no value to read
         }
         const cur = await read();
@@ -1118,18 +1312,22 @@ export async function attachHumanize(browser, page, opts) {
             return false;
         if (cur)
             await clearFocused(read); // a person does not select-all an empty field
-        await humanTypeText(value, info);
+        await put(want);
         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
+        // exact; a mask that only re-punctuated what was typed (a phone format); or one that re-punctuated it
+        // and then stopped taking keys (MM/YY on maxlength 5): no wipe and retype (maskKept)
+        if (got === want || formattedEqual(got, want) || maskKept(got, want, ...limit))
+            return true;
+        if (bulk)
+            return false; // an inserted value that did not land: Playwright's fill, not a second paste
         // 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);
+        await put(want, false);
         got = await read();
-        return got !== null && (got === value || formattedEqual(got, value));
+        return got !== null && (got === want || formattedEqual(got, want) || maskKept(got, want, ...limit));
     };
     // 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
@@ -1162,7 +1360,7 @@ export async function attachHumanize(browser, page, opts) {
             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));
+            await prePress();
             const { grabMs, releaseMs } = dragDwell(persona);
             await nativeDown();
             st.held = true;
@@ -1178,8 +1376,7 @@ export async function attachHumanize(browser, page, opts) {
         }
         else {
             await glide(tx, ty, { targetW: 16 });
-            await sleep(rand(40, 130));
-            await nativeClick(tx, ty, { delay: clickHold(persona) });
+            await pressHere(tx, ty);
         }
         for (let round = 0; round < 3; round++) {
             const v = await now();
@@ -1232,17 +1429,15 @@ export async function attachHumanize(browser, page, opts) {
             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 pressHere(px, py);
         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));
-                }
+                // The same typing model as text (persona dwell, gaussian gaps, thinking pauses, rollover): the
+                // old flat 60-150 ms gap had a CV of 0.24 and no rollover. A segment moves on by itself after
+                // its last digit and keys go down in order, so a rolled-over digit still lands in the right
+                // field (checked on r38, all five types). No typos: a slip in a date is a wrong date.
+                await humanTypeText(a[1], null, false);
             }
             else {
                 await key(a[1], a.length > 2 ? a[2] : 1, [70, 170]);
@@ -1292,13 +1487,13 @@ export async function attachHumanize(browser, page, opts) {
         // raises, as before humanize), and anything the humane route could not prove it did right.
         return nativePageFill(selector, value, options);
     };
-    page.fill = (selector, value, options = {}) => locked(() => hfill(selector, value, options));
-    page.dblclick = (selector, options = {}) => locked(() => {
+    page.fill = apiErrors("page.fill", (selector, value, options = {}) => locked(() => hfill(selector, value, options)));
+    page.dblclick = apiErrors("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 {
             // Click into text fields only: a press on a button or a link that is not focused yet is
@@ -1316,7 +1511,7 @@ export async function attachHumanize(browser, page, opts) {
         }
         return nativePagePress(selector, key, options);
     };
-    page.press = (selector, key, options = {}) => locked(() => hpress(selector, key, options));
+    page.press = apiErrors("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
@@ -1465,8 +1660,7 @@ export async function attachHumanize(browser, page, opts) {
                 await pressAt(normalizeClickOptions({ modifiers: ["ControlOrMeta"] }));
             }
             else {
-                await sleep(rand(40, 130));
-                await nativeClick(px, py, { delay: clickHold(persona) });
+                await pressHere(px, py);
             }
             await sleep(rand(150, 350));
         }
@@ -1537,35 +1731,39 @@ export async function attachHumanize(browser, page, opts) {
             }
             return nativePageSelect(selector, values, options);
         };
-        page.selectOption = (selector, values, options = {}) => locked(() => hselect(selector, values, options));
+        page.selectOption = apiErrors("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
+    // the state is read (a non-checkbox raises, as in Playwright) and, when a click would be needed, its
+    // checks run here (trial) -- not Playwright's trial, which moves the pointer and presses. 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 (opts.trial) {
+            if ((await loc.isChecked({ timeout: opts.timeout })) === checked)
+                return;
+            return trial(selector, opts, false);
+        }
         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");
+        throw sdkPlaywrightError("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));
+            page[name] = apiErrors("page." + name, (selector, options = {}) => locked(() => setChecked(orig, selector, want, options)));
         }
     }
     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));
+        page.setChecked = apiErrors("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
@@ -1574,35 +1772,61 @@ export async function attachHumanize(browser, page, opts) {
     // 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) => {
+    // fading out). A point inside a child frame is answered by the <iframe> element that holds it
+    // (IsolatedWorld.nodeAt), so no Playwright trial runs for it either. false when covered; null when
+    // the hit test cannot run (no CDP): the caller goes native.
+    const reachesPoint = async (box, x, y, sel = null) => {
         const deadline = Date.now() + COVER_CHECK_MS;
-        let hit = await hitInBox(box, x, y);
+        let hit = await hitInBox(box, x, y, sel);
         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;
+            hit = await hitInBox(box, x, y, sel);
+        }
+        return hit;
+    };
+    // The viewport point of Playwright's `position` (relative to the PADDING box: the border widths are added).
+    const positionPoint = async (box, pos) => {
+        const info = await describe(box, null);
+        const bl = info ? info.bl || 0 : 0, bt = info ? info.bt || 0 : 0;
+        return { x: box.x + bl + pos.x, y: box.y + bt + pos.y };
+    };
+    // `trial: true`, answered by the SDK: Playwright's actionability checks -- visible, enabled (not for
+    // hover), stable, and the click point receives the press (the browser's own hit test, read in the
+    // isolated world) -- retried until the caller's timeout (or the page default), then a Playwright
+    // TimeoutError. NO pointer move and NO press: Playwright's own trial moves the real pointer onto the
+    // target and dispatches pointerdown/pointerup/click that page listeners registered before its blocker
+    // see (SC 209: 6/6). The point checked is Playwright's: `position`, else the centre. Scrolling the
+    // element into view is part of the checks, as in Playwright. With `force` only the element must exist.
+    const trial = async (selector, options, noClick) => {
+        const opts = options ?? {};
+        const o = normalizeClickOptions(opts);
+        const ms = typeof opts.timeout === "number" ? opts.timeout : defaultTimeoutMs(page);
+        const end = ms > 0 ? Date.now() + ms : null;
+        const left = () => (end === null ? 0 : Math.max(1, Math.round(end - Date.now())));
+        const loc = page.locator(selector).first();
+        if (o.force) {
+            await loc.waitFor({ state: "attached", timeout: left() });
+            return;
         }
-        catch {
-            return false;
+        for (;;) {
+            let why = "element is not visible";
+            const box = await boxOf(loc, left(), false, selector); // waits for visible; throws Playwright's timeout
+            if (box) {
+                if (!noClick && !(await loc.isEnabled())) {
+                    why = "element is not enabled";
+                }
+                else {
+                    const { x, y } = o.position ? await positionPoint(box, o.position)
+                        : { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+                    await sleep(50); // stable: 50 ms on, the element still fills `box` (ISO_HIT_IN_BOX)
+                    if ((await hitInBox(box, x, y, selector)) !== false)
+                        return; // null: the hit test cannot run -- nothing to add
+                    why = `element is not stable, or another element would receive the pointer at (${Math.round(x)}, ${Math.round(y)})`;
+                }
+            }
+            if (end !== null && Date.now() >= end)
+                throw trialTimeoutError(selector, ms, why);
+            await sleep(end === null ? 100 : Math.max(0, Math.min(100, end - Date.now())));
         }
     };
     // The humanized form of page.click / dblclick / hover (and the click inside check/uncheck and the
@@ -1610,12 +1834,13 @@ export async function attachHumanize(browser, page, opts) {
     //
     // 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.
+    // (and, as in Playwright, every wait); `trial` performs NO action: its checks run here (trial), with
+    // no pointer move and no press. The caller's `timeout` is passed through unchanged. No Playwright
+    // trial runs before a humanized press either (reachesPoint).
     const targetedClick = async (orig, selector, options, noClick, nativeOpts) => {
         const opts = options ?? {};
         const o = normalizeClickOptions(opts);
+        let aim = null; // where Playwright's own click lands, once the box is known (native)
         const native = async () => {
             if (!orig)
                 throw new Error("humanized click could not run");
@@ -1624,12 +1849,19 @@ export async function attachHumanize(browser, page, 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.
+                // false afterwards made the next wheel anchor believe the pointer was still unplaced -- and the
+                // engine path walked again from its own stale point (engineInSync; verifier A #6). The next
+                // SDK glide starts where Playwright pressed: `position`, else the centre of the box.
                 st.placed = true;
+                eng.at = null;
+                if (aim) {
+                    st.x = aim.x;
+                    st.y = aim.y;
+                }
             }
         };
         if (o.trial)
-            return native();
+            return trial(selector, opts, noClick);
         try {
             const timeout = opts.timeout; // undefined: the page's default, as Playwright would use
             const loc = page.locator(selector).first();
@@ -1638,29 +1870,38 @@ export async function attachHumanize(browser, page, opts) {
             const box = await boxOf(loc, timeout, o.force, selector);
             if (!box)
                 throw new NativeSignal();
+            aim = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
             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;
+                ({ x, y } = await positionPoint(box, o.position));
+                aim = { x, y };
             }
             else {
                 ({ x, y } = clickPoint(box, st, persona));
             }
+            // Whole pixels: the hit test below answers for the pixel DOM.getNodeForLocation rounds to, so the
+            // press goes to that pixel too. A press at 971.6 next to a badge ending at 972 was proven at 972 and
+            // landed on the badge, reported as a success (verifier B, SC 210).
+            x = roundHalfEven(x);
+            y = roundHalfEven(y);
             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);
-                if (!(await reachesPoint(orig, selector, box, x, y)))
+                if (!(await reachesPoint(box, x, y, selector)))
                     throw new NativeSignal();
             }
             if (o.modifiers.length && !(nativeKbDown && nativeKbUp))
                 throw new NativeSignal();
+            if (!noClick && !o.force && orig && engineClicksMode() === "all" && enginePathOk(o) && await engineGlide(x, y, false)) {
+                // Opt-in (CLEARCOTE_HUMANIZE_ENGINE_CLICKS=all): the engine walks the approach and clicks the
+                // point the hit test above proved; plain left single clicks only, and only while the engine
+                // knows where the pointer is (engineInSync). Otherwise: the planner.
+                return;
+            }
             if (noClick && o.modifiers.length) {
                 // hover with modifiers: Playwright holds them across the move
                 const held = [];
@@ -1695,8 +1936,10 @@ export async function attachHumanize(browser, page, opts) {
         // outside the try, so a native call that raises is not run a second time by the handler
         return native();
     };
-    page.click = (selector, options = {}) => locked(() => targetedClick(nativePageClick, selector, options, false, null));
-    page.hover = (selector, options = {}) => locked(() => targetedClick(nativePageHover, selector, options, true, null));
+    page.click = apiErrors("page.click", (selector, options = {}) => locked(() => targetedClick(nativePageClick, selector, options, false, null)));
+    page.hover = apiErrors("page.hover", (selector, options = {}) => locked(() => targetedClick(nativePageHover, selector, options, true, null)));
+    // Locator.dragTo({ trial: true }) answers its checks here too (see the Locator patch).
+    page._clearcoteTrial = (selector, options, noClick) => locked(() => trial(selector, options, noClick));
     // Marker the Locator-class patch keys off: humanize is active for THIS page.
     page._clearcoteHumanized = true;
     patchLocatorClass(page.locator("html"));
@@ -1817,66 +2060,102 @@ function patchLocatorClass(sample) {
             return [true, await fn()];
         return [false, undefined];
     };
-    proto.fill = async function (value, kw = {}) {
+    // Every routed method words its errors as Playwright words the Locator method (asApiError): through
+    // page.*, an error read "page.click: ..." or "locator.waitFor: ...".
+    const apiMethod = (api, fn) => async function (...a) {
+        try {
+            return await fn.apply(this, a);
+        }
+        catch (e) {
+            throw asApiError(e, api);
+        }
+    };
+    // Playwright's tap rejects at once in a context without hasTouch ("The page does not support tap");
+    // routed as a click it clicked instead (SC 210 error parity). A context it cannot read is routed.
+    const noTouch = (self) => {
+        try {
+            return self.page().context()._options.hasTouch !== true;
+        }
+        catch {
+            return false;
+        }
+    };
+    proto.fill = apiMethod("locator.fill", async function (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 = {}) {
+    });
+    proto.click = apiMethod("locator.click", async function (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 = {}) {
+    });
+    proto.type = apiMethod("locator.type", async function (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 = {}) {
+    });
+    proto.dblclick = apiMethod("locator.dblclick", async function (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 = {}) {
+    });
+    proto.hover = apiMethod("locator.hover", async function (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 = {}) {
+    });
+    proto.press = apiMethod("locator.press", async function (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 = {}) {
+    });
+    proto.pressSequentially = apiMethod("locator.pressSequentially", async function (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 = {}) {
+    });
+    proto.clear = apiMethod("locator.clear", async function (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 = {}) {
+    });
+    proto.tap = apiMethod("locator.tap", async function (kw = {}) {
+        if (noTouch(this))
+            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 = {}) {
+    });
+    proto.check = apiMethod("locator.check", async function (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 = {}) {
+    });
+    proto.uncheck = apiMethod("locator.uncheck", async function (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 = {}) {
+        proto.setChecked = apiMethod("locator.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 = {}) {
+        proto.selectOption = apiMethod("locator.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)) {
+    proto.dragTo = apiMethod("locator.dragTo", async function (target, kw = {}) {
+        if (kw?.trial && on(this) && on(target) && await strict(this) && await strict(target)) {
+            // Playwright's drag trial moves the pointer onto the source and presses there (SC 209); the SDK
+            // runs the checks of both ends instead: visible, stable, receives the pointer.
+            const t = this.page()._clearcoteTrial;
+            if (typeof t === "function") {
+                for (const [loc, pos] of [[this, kw.sourcePosition], [target, kw.targetPosition]]) {
+                    const o = pickOptions(kw, ["force", "timeout"]);
+                    if (pos)
+                        o.position = pos;
+                    await t(sel(loc), o, true);
+                }
+                return;
+            }
+        }
+        if (on(this) && !kw?.trial) {
             try {
                 const pg = this.page();
                 const sb = await this.boundingBox();
@@ -1889,9 +2168,8 @@ function patchLocatorClass(sample) {
                     const persona = pg._clearcotePersona;
                     const { grabMs, releaseMs } = persona ? dragDwell(persona) : { grabMs: rand(130, 360), releaseMs: rand(90, 230) };
                     await pg.mouse.move(sx, sy);
-                    await sleep(rand(100, 200));
                     await pg.mouse.down();
-                    await sleep(grabMs); // grab hesitation (native -> button held across glide)
+                    await sleep(grabMs); // pre-press pause inside down(); then the grab hesitation
                     const heldGlide = pg._clearcoteHeldGlide; // humanized held-button drag + seating jiggle (settle)
                     if (heldGlide)
                         await heldGlide(tx, ty);
@@ -1905,7 +2183,7 @@ function patchLocatorClass(sample) {
             catch { /* fall back */ }
         }
         return oDragTo.call(this, target, kw);
-    };
+    });
 }
 /** Install humanize/showCursor on a browser: wraps newPage/newContext so every page is covered. */
 export function installHumanize(browser, opts) {