screenci 0.0.4 → 0.0.5

package/dist/src/instrument.js

@@ -0,0 +1,910 @@
+import { logger } from './logger.js';
+import { isInsideAutoZoom, getZoomDuration, getPostZoomInOutDelay, getLastZoomLocation, setLastZoomLocation, } from './autoZoom.js';
+let activeClickRecorder = null;
+export function setActiveClickRecorder(recorder) {
+    activeClickRecorder = recorder;
+}
+/**
+ * Evaluate a polynomial easing function at normalized time t ∈ [0, 1].
+ * Returns the eased progress value (0–1).
+ */
+function evaluateEasingAtT(t, easing) {
+    if (t <= 0)
+        return 0;
+    if (t >= 1)
+        return 1;
+    switch (easing) {
+        case 'linear':
+            return t;
+        case 'ease-in':
+            return t * t * t;
+        case 'ease-out':
+            return 1 - (1 - t) * (1 - t) * (1 - t);
+        case 'ease-in-out':
+            return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+        case 'ease-in-strong':
+            return t * t * t * t;
+        case 'ease-out-strong':
+            return 1 - (1 - t) * (1 - t) * (1 - t) * (1 - t);
+        case 'ease-in-out-strong':
+            return t < 0.5 ? 8 * t * t * t * t : 1 - Math.pow(-2 * t + 2, 4) / 2;
+        default: {
+            const _ = easing;
+            throw new Error(`Unknown easing: ${_}`);
+        }
+    }
+}
+/** Tracked cursor position per page, updated after each animated move. */
+const mousePositions = new WeakMap();
+/** Tracks cursor visibility per page (true = visible). Defaults to true. */
+const mouseVisibilities = new WeakMap();
+/** Stores the original (un-instrumented) mouse.move per page so internal
+ *  cursor animations don't emit addInput recorder events. */
+const originalMouseMoves = new WeakMap();
+const instrumented = new WeakSet();
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const CLICK_DURATION_MS = 200;
+const LOCATOR_RETURN_METHODS = [
+    'locator',
+    'getByAltText',
+    'getByLabel',
+    'getByPlaceholder',
+    'getByRole',
+    'getByTestId',
+    'getByText',
+    'getByTitle',
+];
+const LOCATOR_ONLY_SYNC_RETURN_METHODS = [
+    'and',
+    'describe',
+    'filter',
+    'first',
+    'last',
+    'nth',
+    'or',
+];
+const FRAME_LOCATOR_LOCATOR_RETURN_METHODS = [
+    'locator',
+    'getByAltText',
+    'getByLabel',
+    'getByPlaceholder',
+    'getByRole',
+    'getByTestId',
+    'getByText',
+    'getByTitle',
+    'owner',
+];
+const FRAME_LOCATOR_SELF_RETURN_METHODS = [
+    'frameLocator',
+    'first',
+    'last',
+    'nth',
+];
+// Per-page storage for the most recently captured DOM click event data.
+// Reset to null before each instrumented click; set by the exposeFunction callback.
+const pendingClickData = new WeakMap();
+export function scrollIntoViewAsync(locator, options = {}) {
+    const { behavior = 'smooth', block = 'center', timeout = 5000, postScrollTimeout = 500, } = options;
+    return locator.evaluate((element, opts) => new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(fallback);
+            setTimeout(resolve, opts.postScrollTimeout);
+        };
+        const fallback = setTimeout(finish, opts.timeout);
+        // scrollend fires once the smooth-scroll animation completes (Chrome 114+).
+        // It captures scroll on any ancestor element via the capture phase.
+        window.addEventListener('scrollend', finish, {
+            capture: true,
+            once: true,
+        });
+        element.scrollIntoView({ behavior: opts.behavior, block: opts.block });
+        // If the element is already in the target position no scroll occurs and
+        // scrollend never fires. Detect this: if no scroll event appears within
+        // two animation frames the element was already in place.
+        let didScroll = false;
+        window.addEventListener('scroll', () => {
+            didScroll = true;
+        }, {
+            capture: true,
+            passive: true,
+            once: true,
+        });
+        requestAnimationFrame(() => requestAnimationFrame(() => {
+            if (!didScroll)
+                finish();
+        }));
+    }), { behavior, block, timeout, postScrollTimeout });
+}
+/**
+ * Scrolls the locator into view only if it is at least partially outside the
+ * viewport, then returns the (possibly updated) bounding box as an ElementRect.
+ * Returns undefined if the bounding box cannot be determined.
+ */
+async function scrollIntoViewIfNeeded(locator) {
+    const page = locator.page();
+    const bb = await locator.boundingBox();
+    if (!bb)
+        return undefined;
+    const viewportSize = page.viewportSize();
+    if (viewportSize) {
+        const isFullyInViewport = bb.x >= 0 &&
+            bb.y >= 0 &&
+            bb.x + bb.width <= viewportSize.width &&
+            bb.y + bb.height <= viewportSize.height;
+        if (!isFullyInViewport) {
+            await scrollIntoViewAsync(locator);
+            const newBb = await locator.boundingBox();
+            if (newBb)
+                return {
+                    x: newBb.x,
+                    y: newBb.y,
+                    width: newBb.width,
+                    height: newBb.height,
+                };
+        }
+    }
+    else {
+        logger.warn('[screenci] Unable to determine viewport size; skipping auto-scroll check.');
+    }
+    return { x: bb.x, y: bb.y, width: bb.width, height: bb.height };
+}
+const CURSOR_STEP_MS = 1000 / 60;
+/**
+ * Physically moves the mouse from its current tracked position to (targetX,
+ * targetY) over `duration` ms using `easing`, then returns a MouseMoveEvent
+ * whose startMs is `eventStartMs` (which may predate this call, e.g. when a
+ * scroll consumed part of moveDuration).  When duration ≤ 0 the cursor is
+ * snapped directly to the target with a single move call.
+ * Always updates the internal mousePositions tracker.
+ */
+async function animateMouseMove(page, mouseMoveInternal, targetX, targetY, duration, easing, eventStartMs, elementRect) {
+    if (duration > 0) {
+        const startPos = mousePositions.get(page) ?? { x: 0, y: 0 };
+        const steps = Math.max(1, Math.floor(duration / CURSOR_STEP_MS));
+        const stepMs = duration / steps;
+        for (let i = 0; i <= steps; i++) {
+            const t = i / steps;
+            const easedT = evaluateEasingAtT(t, easing);
+            const x = startPos.x + easedT * (targetX - startPos.x);
+            const y = startPos.y + easedT * (targetY - startPos.y);
+            await mouseMoveInternal(x, y);
+            if (i < steps) {
+                await new Promise((resolve) => setTimeout(resolve, stepMs));
+            }
+        }
+    }
+    else {
+        await mouseMoveInternal(targetX, targetY);
+    }
+    mousePositions.set(page, { x: targetX, y: targetY });
+    return {
+        type: 'mouseMove',
+        startMs: eventStartMs,
+        endMs: Date.now(),
+        x: targetX,
+        y: targetY,
+        easing,
+        ...(elementRect !== undefined ? { elementRect } : {}),
+    };
+}
+/**
+ * Performs all click mechanics (scroll-check, zoom handling, cursor animation,
+ * click, post-click move) and returns the collected timing/position data.
+ * Returns null if coordinates could not be determined (no DOM event and no
+ * locator bounding box).
+ */
+async function performClickActions(locator, doClick, clickOptions, position, moveDuration = 1000, beforeClickPause = CLICK_DURATION_MS / 2, moveEasing = 'ease-in-out', postClickPause = CLICK_DURATION_MS / 2, postClickMove) {
+    const page = locator.page();
+    pendingClickData.set(page, null);
+    const halfClickDuration = CLICK_DURATION_MS / 2;
+    const mouseMoveInternal = originalMouseMoves.get(page) ?? page.mouse.move.bind(page.mouse);
+    // Capture before any setLastZoomLocation call changes the state.
+    const isFirstAutoZoomEvent = isInsideAutoZoom() && getLastZoomLocation() === null;
+    const moveStartTime = Date.now();
+    const locatorRect = await scrollIntoViewIfNeeded(locator);
+    const scrollElapsedMs = Date.now() - moveStartTime;
+    if (!locatorRect) {
+        logger.warn('[screenci] Unable to get locator bounding box; skipping auto-scroll check.');
+    }
+    const innerEvents = [];
+    // If inside autoZoom: optionally await zoom duration for camera pan then
+    // update the zoom location tracker.
+    if (isInsideAutoZoom() && locatorRect) {
+        const targetX = position
+            ? locatorRect.x + position.x
+            : locatorRect.x + locatorRect.width / 2;
+        const targetY = position
+            ? locatorRect.y + position.y
+            : locatorRect.y + locatorRect.height / 2;
+        const lastLoc = getLastZoomLocation();
+        if (lastLoc !== null) {
+            const zoomDur = getZoomDuration() ?? 0;
+            if (zoomDur > 0) {
+                await sleep(zoomDur);
+            }
+        }
+        setLastZoomLocation({
+            x: targetX,
+            y: targetY,
+            elementRect: locatorRect,
+            eventType: 'click',
+        });
+    }
+    const targetPos = position
+        ? position
+        : locatorRect
+            ? {
+                x: locatorRect.width / 2,
+                y: locatorRect.height / 2,
+            }
+            : undefined;
+    // No physical mouse movement happens during the scroll.  moveStartTime is
+    // captured before the scroll so the recorded event spans scroll-start →
+    // animation-end, making the cursor appear to move during the scroll in the
+    // video.  After the scroll, the remaining duration drives the physical easing
+    // animation via the shared helper.
+    if (targetPos && locatorRect) {
+        const targetX = locatorRect.x + targetPos.x;
+        const targetY = locatorRect.y + targetPos.y;
+        const effectiveDuration = Math.max(0, moveDuration - scrollElapsedMs);
+        innerEvents.push(await animateMouseMove(page, mouseMoveInternal, targetX, targetY, effectiveDuration, moveEasing, moveStartTime, locatorRect));
+    }
+    else {
+        const remainingMs = Math.max(0, moveDuration - scrollElapsedMs);
+        if (remainingMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, remainingMs));
+        }
+    }
+    const effectiveBeforeClickPause = isFirstAutoZoomEvent
+        ? Math.max(beforeClickPause, getPostZoomInOutDelay() ?? 0)
+        : beforeClickPause;
+    await new Promise((resolve) => setTimeout(resolve, effectiveBeforeClickPause));
+    await new Promise((resolve) => setTimeout(resolve, halfClickDuration));
+    // Note click can take some time, but better to show it before than after
+    const clickTime = Date.now();
+    const mouseDownStart = clickTime - halfClickDuration;
+    innerEvents.push({
+        type: 'mouseDown',
+        startMs: mouseDownStart,
+        endMs: clickTime,
+        easing: 'ease-in-out',
+    });
+    await doClick({
+        ...clickOptions,
+        ...(targetPos ? { position: targetPos } : {}),
+    });
+    const domClickData = pendingClickData.get(page);
+    const mouseUpEnd = Date.now() + halfClickDuration;
+    innerEvents.push({
+        type: 'mouseUp',
+        startMs: clickTime,
+        endMs: mouseUpEnd,
+        easing: 'ease-in-out',
+    });
+    await new Promise((resolve) => setTimeout(resolve, halfClickDuration));
+    await new Promise((resolve) => setTimeout(resolve, postClickPause));
+    // Animate mouse cursor in the specified direction after the click completes,
+    // capturing start/end times and final position for the recorded event.
+    if (postClickMove !== undefined) {
+        const currentPos = mousePositions.get(page) ?? { x: 0, y: 0 };
+        let targetX;
+        let targetY;
+        if ('direction' in postClickMove) {
+            if (locatorRect === undefined) {
+                logger.warn('[screenci] postClickMove with direction requires a locator rect; skipping mouse move.');
+            }
+            else {
+                const padding = postClickMove.padding ?? 0;
+                switch (postClickMove.direction) {
+                    case 'up':
+                        targetX = currentPos.x;
+                        targetY = locatorRect.y - padding;
+                        break;
+                    case 'down':
+                        targetX = currentPos.x;
+                        targetY = locatorRect.y + locatorRect.height + padding;
+                        break;
+                    case 'left':
+                        targetX = locatorRect.x - padding;
+                        targetY = currentPos.y;
+                        break;
+                    case 'right':
+                        targetX = locatorRect.x + locatorRect.width + padding;
+                        targetY = currentPos.y;
+                        break;
+                    default: {
+                        const _ = postClickMove.direction;
+                        throw new Error(`Unknown postClickMove direction: ${_}`);
+                    }
+                }
+            }
+        }
+        else {
+            targetX = currentPos.x + postClickMove.x;
+            targetY = currentPos.y + postClickMove.y;
+        }
+        if (targetX !== undefined && targetY !== undefined) {
+            const easing = postClickMove.easing ?? 'ease-in-out';
+            const { duration } = postClickMove;
+            const steps = Math.max(1, Math.floor(duration / CURSOR_STEP_MS));
+            const stepMs = duration / steps;
+            const postClickMoveStartMs = Date.now();
+            const startPos = { ...currentPos };
+            for (let i = 0; i <= steps; i++) {
+                const t = i / steps;
+                const easedT = evaluateEasingAtT(t, easing);
+                const x = startPos.x + easedT * (targetX - startPos.x);
+                const y = startPos.y + easedT * (targetY - startPos.y);
+                await mouseMoveInternal(x, y);
+                if (i < steps) {
+                    await new Promise((resolve) => setTimeout(resolve, stepMs));
+                }
+            }
+            innerEvents.push({
+                type: 'mouseMove',
+                startMs: postClickMoveStartMs,
+                endMs: Date.now(),
+                x: targetX,
+                y: targetY,
+                easing,
+                zoomFollow: false,
+            });
+            mousePositions.set(page, { x: targetX, y: targetY });
+        }
+    }
+    let elementRect;
+    if (locatorRect) {
+        elementRect = locatorRect;
+    }
+    else if (domClickData) {
+        console.warn('[screenci] using DOM click data as fallback for elementRect');
+        elementRect = domClickData.targetRect;
+    }
+    if (elementRect) {
+        return {
+            elementRect,
+            innerEvents,
+        };
+    }
+    else {
+        logger.warn('[screenci] Failed to capture click coordinates from both DOM event and locator bounding box.');
+        return null;
+    }
+}
+async function performSimpleAction(locator, doAction, options, subType, clickOpt) {
+    let innerEvents = [];
+    let elementRect;
+    if (clickOpt !== undefined) {
+        const { moveDuration, beforeClickPause, moveEasing, postClickPause, postClickMove, position, } = clickOpt;
+        const clickActionResult = await performClickActions(locator, doAction, {}, position, moveDuration, beforeClickPause, moveEasing, postClickPause, postClickMove);
+        innerEvents = clickActionResult?.innerEvents ?? [];
+        elementRect = clickActionResult?.elementRect;
+    }
+    else {
+        const isFirstAutoZoomEvent = isInsideAutoZoom() && getLastZoomLocation() === null;
+        const locatorRect = await scrollIntoViewIfNeeded(locator);
+        if (isInsideAutoZoom() && locatorRect) {
+            const targetX = locatorRect.x + locatorRect.width / 2;
+            const targetY = locatorRect.y + locatorRect.height / 2;
+            const lastLoc = getLastZoomLocation();
+            if (lastLoc !== null) {
+                const zoomDur = getZoomDuration() ?? 0;
+                if (zoomDur > 0) {
+                    await sleep(zoomDur);
+                }
+            }
+            setLastZoomLocation({
+                x: targetX,
+                y: targetY,
+                elementRect: locatorRect,
+                eventType: 'fill',
+            });
+        }
+        if (isFirstAutoZoomEvent) {
+            const postDelay = getPostZoomInOutDelay() ?? 0;
+            if (postDelay > 0)
+                await sleep(postDelay);
+        }
+        const targetPosition = locatorRect
+            ? {
+                x: locatorRect.width / 2,
+                y: locatorRect.height / 2,
+            }
+            : undefined;
+        const startTime = Date.now();
+        await doAction({
+            ...options,
+            ...(targetPosition ? { position: targetPosition } : {}),
+        });
+        const endTime = Date.now();
+        const midTime = (startTime + endTime) / 2;
+        innerEvents.push({
+            type: 'mouseDown',
+            startMs: startTime,
+            endMs: midTime,
+        });
+        innerEvents.push({
+            type: 'mouseUp',
+            startMs: midTime,
+            endMs: endTime,
+        });
+        elementRect = locatorRect;
+    }
+    if (activeClickRecorder && innerEvents.length > 0) {
+        activeClickRecorder.addInput(subType, elementRect, innerEvents);
+    }
+}
+async function recordedClick(locator, doClick, clickOptions, position, moveDuration = 1000, beforeClickPause = CLICK_DURATION_MS / 2, moveEasing = 'ease-in-out', postClickPause = CLICK_DURATION_MS / 2, postClickMove) {
+    const result = await performClickActions(locator, doClick, clickOptions, position, moveDuration, beforeClickPause, moveEasing, postClickPause, postClickMove);
+    if (activeClickRecorder && result) {
+        activeClickRecorder.addInput('click', result.elementRect, result.innerEvents);
+    }
+}
+function instrumentLocatorMethods(obj) {
+    for (const method of LOCATOR_RETURN_METHODS) {
+        const original = obj[method].bind(obj);
+        obj[method] = (...args) => instrumentLocator(original(...args));
+    }
+}
+export function instrumentFrameLocator(frameLocator) {
+    if (instrumented.has(frameLocator))
+        return frameLocator;
+    instrumented.add(frameLocator);
+    for (const method of FRAME_LOCATOR_LOCATOR_RETURN_METHODS) {
+        const original = frameLocator[method].bind(frameLocator);
+        frameLocator[method] = (...args) => instrumentLocator(original(...args));
+    }
+    for (const method of FRAME_LOCATOR_SELF_RETURN_METHODS) {
+        const original = frameLocator[method].bind(frameLocator);
+        frameLocator[method] =
+            (...args) => instrumentFrameLocator(original(...args));
+    }
+    return frameLocator;
+}
+export function instrumentLocator(locator) {
+    if (instrumented.has(locator))
+        return locator;
+    instrumented.add(locator);
+    const originalClick = locator.click.bind(locator);
+    locator.click = async (options) => {
+        const { moveDuration, beforeClickPause, moveEasing, postClickPause, postClickMove, position, steps: _steps, ...clickOptions } = options ?? {};
+        return recordedClick(locator, (options) => originalClick(options), clickOptions, position, moveDuration, beforeClickPause, moveEasing, postClickPause, postClickMove);
+    };
+    const originalPressSequentially = locator.pressSequentially.bind(locator);
+    locator.pressSequentially = async (text, options) => {
+        const innerEvents = [];
+        let elementRect;
+        if (options?.click !== undefined) {
+            // Click before fill: performClickActions handles scrolling and bounding box.
+            const clickOpt = options.click;
+            const { moveDuration, beforeClickPause, moveEasing, postClickPause, postClickMove, position, ...clickOptions } = clickOpt;
+            const clickActionResult = await performClickActions(locator, (options) => originalClick(options), clickOptions, position, moveDuration, beforeClickPause, moveEasing, postClickPause, postClickMove);
+            innerEvents.push(...(clickActionResult?.innerEvents ?? []));
+            elementRect = clickActionResult?.elementRect;
+        }
+        else {
+            const isFirstAutoZoomEvent = isInsideAutoZoom() && getLastZoomLocation() === null;
+            const locatorRect = await scrollIntoViewIfNeeded(locator);
+            // If inside autoZoom: await zoom duration for camera pan, then update zoom tracker
+            if (isInsideAutoZoom() && locatorRect) {
+                const targetX = locatorRect.x + locatorRect.width / 2;
+                const targetY = locatorRect.y + locatorRect.height / 2;
+                const lastLoc = getLastZoomLocation();
+                if (lastLoc !== null) {
+                    const zoomDur = getZoomDuration() ?? 0;
+                    if (zoomDur > 0) {
+                        await sleep(zoomDur);
+                    }
+                }
+                setLastZoomLocation({
+                    x: targetX,
+                    y: targetY,
+                    elementRect: locatorRect,
+                    eventType: 'fill',
+                });
+            }
+            if (isFirstAutoZoomEvent) {
+                const postDelay = getPostZoomInOutDelay() ?? 0;
+                if (postDelay > 0)
+                    await sleep(postDelay);
+            }
+            elementRect = locatorRect;
+        }
+        // Hide cursor while typing (will be shown again on next mouse move)
+        const page = locator.page();
+        const shouldHideMouse = options?.hideMouse === true;
+        if (shouldHideMouse) {
+            const cursorVisible = mouseVisibilities.get(page) ?? true;
+            if (cursorVisible) {
+                mouseVisibilities.set(page, false);
+                const hideMs = Date.now();
+                innerEvents.push({
+                    type: 'mouseHide',
+                    startMs: hideMs,
+                    endMs: hideMs,
+                });
+            }
+        }
+        // Strip the click and hideMouse options before forwarding to the original Playwright method
+        const { click: _click, hideMouse: _hideMouse, ...pressOptions } = options ?? {};
+        const typingStart = Date.now();
+        await originalPressSequentially(text, pressOptions);
+        const typingEnd = Date.now();
+        if (activeClickRecorder) {
+            // addInput requires at least one inner event; use typing start/end as a
+            // fallback span when no other inner events (click, mouseHide) were collected.
+            const eventsToRecord = innerEvents.length > 0
+                ? innerEvents
+                : [
+                    { type: 'mouseDown', startMs: typingStart, endMs: typingStart },
+                    { type: 'mouseUp', startMs: typingStart, endMs: typingEnd },
+                ];
+            activeClickRecorder.addInput('pressSequentially', elementRect, eventsToRecord);
+        }
+    };
+    locator.fill = async (value, options) => {
+        const duration = options?.duration ?? 1000;
+        const delay = value.length > 0 ? duration / value.length : 0;
+        const pressOptions = { delay };
+        if (options?.timeout !== undefined)
+            pressOptions.timeout = options.timeout;
+        if (options?.click !== undefined)
+            pressOptions.click = options.click;
+        if (options?.hideMouse !== undefined)
+            pressOptions.hideMouse = options.hideMouse;
+        return locator.pressSequentially(value, pressOptions);
+    };
+    const originalTap = locator.tap.bind(locator);
+    locator.tap = async (options) => {
+        const clickOpt = options?.click;
+        const { click: _click, ...tapOpts } = options ?? {};
+        return performSimpleAction(locator, (options) => originalTap(options), tapOpts, 'tap', clickOpt);
+    };
+    const originalCheck = locator.check.bind(locator);
+    locator.check = async (options) => {
+        const clickOpt = options?.click;
+        const { click: _click, position, ...checkOpts } = options ?? {};
+        const effectiveClickOpt = clickOpt !== undefined && position !== undefined
+            ? { ...clickOpt, position }
+            : clickOpt;
+        return performSimpleAction(locator, (options) => originalCheck(options), checkOpts, 'check', effectiveClickOpt);
+    };
+    const originalUncheck = locator.uncheck.bind(locator);
+    locator.uncheck = async (options) => {
+        const clickOpt = options?.click;
+        const { click: _click, position, ...uncheckOpts } = options ?? {};
+        const effectiveClickOpt = clickOpt !== undefined && position !== undefined
+            ? { ...clickOpt, position }
+            : clickOpt;
+        return performSimpleAction(locator, (options) => originalUncheck(options), uncheckOpts, 'uncheck', effectiveClickOpt);
+    };
+    locator.setChecked = async (checked, options) => {
+        if (checked) {
+            return locator.check(options);
+        }
+        else {
+            return locator.uncheck(options);
+        }
+    };
+    const originalSelectOption = locator.selectOption.bind(locator);
+    locator.selectOption = async (values, options) => {
+        const clickOpt = options?.click;
+        const { click: _click, ...selectOpts } = options ?? {};
+        let result = [];
+        await performSimpleAction(locator, (options) => originalSelectOption(values, options).then((res) => {
+            result = res;
+        }), selectOpts, 'select', clickOpt);
+        return result;
+    };
+    const originalHover = locator.hover.bind(locator);
+    locator.hover = async (options) => {
+        const { moveDuration = 1000, easing: moveEasing = 'ease-in-out', hoverDuration = 1000, position, ...hoverOptions } = options ?? {};
+        const page = locator.page();
+        const mouseMoveInternal = originalMouseMoves.get(page) ?? page.mouse.move.bind(page.mouse);
+        const moveStartTime = Date.now();
+        const locatorRect = await scrollIntoViewIfNeeded(locator);
+        const scrollElapsedMs = Date.now() - moveStartTime;
+        const innerEvents = [];
+        const targetPos = position ??
+            (locatorRect
+                ? { x: locatorRect.width / 2, y: locatorRect.height / 2 }
+                : undefined);
+        if (targetPos && locatorRect) {
+            const targetX = locatorRect.x + targetPos.x;
+            const targetY = locatorRect.y + targetPos.y;
+            const effectiveDuration = Math.max(0, moveDuration - scrollElapsedMs);
+            innerEvents.push(await animateMouseMove(page, mouseMoveInternal, targetX, targetY, effectiveDuration, moveEasing, moveStartTime, locatorRect));
+        }
+        const waitStartMs = Date.now();
+        await originalHover({
+            ...hoverOptions,
+            ...(targetPos ? { position: targetPos } : {}),
+        });
+        if (hoverDuration > 0) {
+            await sleep(hoverDuration);
+        }
+        const waitEndMs = Date.now();
+        innerEvents.push({
+            type: 'mouseWait',
+            startMs: waitStartMs,
+            endMs: waitEndMs,
+        });
+        if (activeClickRecorder && innerEvents.length > 0) {
+            activeClickRecorder.addInput('hover', locatorRect, innerEvents);
+        }
+    };
+    const originalSelectText = locator.selectText.bind(locator);
+    locator.selectText = async (options) => {
+        const { moveDuration = 1000, easing: moveEasing = 'ease-in-out', beforeClickPause = CLICK_DURATION_MS / 2, selectDuration = 600, ...selectOpts } = options ?? {};
+        const page = locator.page();
+        const mouseMoveInternal = originalMouseMoves.get(page) ?? page.mouse.move.bind(page.mouse);
+        const moveStartTime = Date.now();
+        const locatorRect = await scrollIntoViewIfNeeded(locator);
+        const scrollElapsedMs = Date.now() - moveStartTime;
+        const innerEvents = [];
+        const targetPos = locatorRect
+            ? { x: locatorRect.width / 2, y: locatorRect.height / 2 }
+            : undefined;
+        if (targetPos && locatorRect) {
+            const targetX = locatorRect.x + targetPos.x;
+            const targetY = locatorRect.y + targetPos.y;
+            const effectiveDuration = Math.max(0, moveDuration - scrollElapsedMs);
+            innerEvents.push(await animateMouseMove(page, mouseMoveInternal, targetX, targetY, effectiveDuration, moveEasing, moveStartTime, locatorRect));
+        }
+        await sleep(beforeClickPause);
+        await originalSelectText(selectOpts);
+        // Backtrack triple-click events from the moment originalSelectText resolves.
+        // Clamp start so events don't precede the prior animation (produces a visible
+        // pre-click pause in the recording, which is acceptable).
+        // All timestamps use a single base + integer * segmentMs to avoid FP drift.
+        const selectEndMs = Date.now();
+        const lastEventEndMs = innerEvents.at(-1)?.endMs ?? 0;
+        const tripleClickStartMs = Math.max(lastEventEndMs, selectEndMs - selectDuration);
+        const segmentMs = selectDuration / 6;
+        for (let i = 0; i < 3; i++) {
+            const seg = i * 2;
+            innerEvents.push({
+                type: 'mouseDown',
+                startMs: tripleClickStartMs + seg * segmentMs,
+                endMs: tripleClickStartMs + (seg + 1) * segmentMs,
+                easing: 'ease-in-out',
+            });
+            innerEvents.push({
+                type: 'mouseUp',
+                startMs: tripleClickStartMs + (seg + 1) * segmentMs,
+                endMs: tripleClickStartMs + (seg + 2) * segmentMs,
+                easing: 'ease-in-out',
+            });
+        }
+        if (activeClickRecorder && innerEvents.length > 0) {
+            activeClickRecorder.addInput('selectText', locatorRect, innerEvents);
+        }
+    };
+    locator.dragTo = async (target, options) => {
+        const { moveDuration = 1000, moveEasing = 'ease-in-out', preDragPause = CLICK_DURATION_MS / 2, dragDuration = 1000, dragEasing = 'ease-in-out', sourcePosition, targetPosition, ...dragOpts } = options ?? {};
+        const page = locator.page();
+        const mouseMoveInternal = originalMouseMoves.get(page) ?? page.mouse.move.bind(page.mouse);
+        const moveStartTime = Date.now();
+        const sourceRect = await scrollIntoViewIfNeeded(locator);
+        const scrollElapsedMs = Date.now() - moveStartTime;
+        const targetBb = await target.boundingBox();
+        const targetRect = targetBb
+            ? {
+                x: targetBb.x,
+                y: targetBb.y,
+                width: targetBb.width,
+                height: targetBb.height,
+            }
+            : undefined;
+        const innerEvents = [];
+        const sourcePos = sourcePosition ??
+            (sourceRect
+                ? { x: sourceRect.width / 2, y: sourceRect.height / 2 }
+                : undefined);
+        const targetPos = targetPosition ??
+            (targetRect
+                ? { x: targetRect.width / 2, y: targetRect.height / 2 }
+                : undefined);
+        // 1. Animate cursor to source
+        if (sourcePos && sourceRect) {
+            const toX = sourceRect.x + sourcePos.x;
+            const toY = sourceRect.y + sourcePos.y;
+            const effectiveDuration = Math.max(0, moveDuration - scrollElapsedMs);
+            innerEvents.push(await animateMouseMove(page, mouseMoveInternal, toX, toY, effectiveDuration, moveEasing, moveStartTime, sourceRect));
+        }
+        // 2. preDragPause + mouseDown
+        await sleep(preDragPause);
+        const mouseDownStart = Date.now();
+        await page.mouse.down();
+        await sleep(CLICK_DURATION_MS / 2);
+        innerEvents.push({
+            type: 'mouseDown',
+            startMs: mouseDownStart,
+            endMs: Date.now(),
+            easing: 'ease-in-out',
+        });
+        // 3. Drag: animate cursor from source to target
+        const dragStartTime = Date.now();
+        if (targetPos && targetRect) {
+            const toX = targetRect.x + targetPos.x;
+            const toY = targetRect.y + targetPos.y;
+            innerEvents.push(await animateMouseMove(page, mouseMoveInternal, toX, toY, dragDuration, dragEasing, dragStartTime, targetRect));
+        }
+        // 4. mouseUp at target
+        const mouseUpStart = Date.now();
+        await page.mouse.up();
+        await sleep(CLICK_DURATION_MS / 2);
+        innerEvents.push({
+            type: 'mouseUp',
+            startMs: mouseUpStart,
+            endMs: Date.now(),
+            easing: 'ease-in-out',
+        });
+        if (activeClickRecorder && innerEvents.length > 0) {
+            activeClickRecorder.addInput('dragTo', sourceRect, innerEvents);
+        }
+    };
+    const originalPage = locator.page.bind(locator);
+    locator.page = () => originalPage();
+    instrumentLocatorMethods(locator);
+    for (const method of LOCATOR_ONLY_SYNC_RETURN_METHODS) {
+        const original = locator[method].bind(locator);
+        locator[method] = (...args) => instrumentLocator(original(...args));
+    }
+    const originalAll = locator.all.bind(locator);
+    locator.all = async () => {
+        const locators = await originalAll();
+        return locators.map(instrumentLocator);
+    };
+    const originalContentFrame = locator.contentFrame.bind(locator);
+    locator.contentFrame =
+        () => instrumentFrameLocator(originalContentFrame());
+    const originalLocatorFrameLocator = locator.frameLocator.bind(locator);
+    locator.frameLocator = (...args) => instrumentFrameLocator(originalLocatorFrameLocator(...args));
+    return locator;
+}
+export async function instrumentPage(page) {
+    if (instrumented.has(page))
+        return page;
+    instrumented.add(page);
+    // Expose a Node.js function to the browser that captures DOM click event data.
+    // Called synchronously from the click handler before any navigation can occur.
+    await page.exposeFunction('__screenciOnClick', (data) => {
+        pendingClickData.set(page, data);
+    });
+    // Inject a capture listener on every page load (including after navigation).
+    await page.addInitScript(() => {
+        document.addEventListener('click', (e) => {
+            const target = e.target;
+            const r = target.getBoundingClientRect();
+            window.__screenciOnClick({
+                x: e.clientX,
+                y: e.clientY,
+                targetRect: { x: r.x, y: r.y, width: r.width, height: r.height },
+            });
+        }, { capture: true });
+    });
+    instrumentLocatorMethods(page);
+    const originalPageFrameLocator = page.frameLocator.bind(page);
+    page.frameLocator = (...args) => instrumentFrameLocator(originalPageFrameLocator(...args));
+    // Delegate page.click to the instrumented locator so all click recording
+    // flows through the same path.
+    page.click = async (selector, options) => {
+        return page.locator(selector).click(options);
+    };
+    // Instrument page.mouse to record mouse moves and visibility toggles.
+    const originalMouse = page.mouse;
+    const originalMove = originalMouse.move.bind(originalMouse);
+    originalMouseMoves.set(page, originalMove);
+    originalMouse.move = async (x, y, options) => {
+        const duration = options?.duration ?? 0;
+        const easing = options?.easing ?? 'ease-in-out';
+        const startMs = Date.now();
+        if (duration > 0) {
+            const startPos = mousePositions.get(page) ?? { x: 0, y: 0 };
+            const steps = Math.max(1, Math.floor(duration / CURSOR_STEP_MS));
+            const stepMs = duration / steps;
+            for (let i = 0; i <= steps; i++) {
+                const t = i / steps;
+                const easedT = evaluateEasingAtT(t, easing);
+                const cx = startPos.x + easedT * (x - startPos.x);
+                const cy = startPos.y + easedT * (y - startPos.y);
+                await originalMove(cx, cy);
+                if (i < steps) {
+                    await new Promise((resolve) => setTimeout(resolve, stepMs));
+                }
+            }
+        }
+        else {
+            await originalMove(x, y);
+        }
+        mousePositions.set(page, { x, y });
+        const endMs = Date.now();
+        if (activeClickRecorder) {
+            // Auto-show cursor when moving after a typing auto-hide
+            if (!(mouseVisibilities.get(page) ?? true)) {
+                mouseVisibilities.set(page, true);
+                const showMs = startMs;
+                const showEvent = {
+                    type: 'mouseShow',
+                    startMs: showMs,
+                    endMs: showMs,
+                };
+                activeClickRecorder.addInput('mouseShow', undefined, [showEvent]);
+            }
+            const moveEvent = {
+                type: 'mouseMove',
+                startMs,
+                endMs,
+                x,
+                y,
+                ...(duration > 0 ? { easing } : {}),
+            };
+            activeClickRecorder.addInput('mouseMove', undefined, [moveEvent]);
+        }
+    };
+    mouseVisibilities.set(page, true);
+    originalMouse.show = () => {
+        if (!(mouseVisibilities.get(page) ?? true)) {
+            mouseVisibilities.set(page, true);
+            if (activeClickRecorder) {
+                const timeMs = Date.now();
+                const showEvent = {
+                    type: 'mouseShow',
+                    startMs: timeMs,
+                    endMs: timeMs,
+                };
+                activeClickRecorder.addInput('mouseShow', undefined, [showEvent]);
+            }
+        }
+    };
+    originalMouse.hide = () => {
+        if (mouseVisibilities.get(page) ?? true) {
+            mouseVisibilities.set(page, false);
+            if (activeClickRecorder) {
+                const timeMs = Date.now();
+                const hideEvent = {
+                    type: 'mouseHide',
+                    startMs: timeMs,
+                    endMs: timeMs,
+                };
+                activeClickRecorder.addInput('mouseHide', undefined, [hideEvent]);
+            }
+        }
+    };
+    page.on('popup', (popup) => {
+        void instrumentPage(popup);
+    });
+    return page;
+}
+export function instrumentContext(context) {
+    if (instrumented.has(context))
+        return context;
+    instrumented.add(context);
+    const originalNewPage = context.newPage.bind(context);
+    context.newPage = async (...args) => {
+        return instrumentPage(await originalNewPage(...args));
+    };
+    return context;
+}
+export function instrumentBrowser(browser) {
+    if (instrumented.has(browser))
+        return browser;
+    instrumented.add(browser);
+    const originalNewContext = browser.newContext.bind(browser);
+    browser.newContext = async (...args) => {
+        return instrumentContext(await originalNewContext(...args));
+    };
+    const originalNewPage = browser.newPage.bind(browser);
+    browser.newPage = async (...args) => {
+        return instrumentPage(await originalNewPage(...args));
+    };
+    return browser;
+}
+//# sourceMappingURL=instrument.js.map