@lhremote/core 0.8.0 → 0.9.0

package/dist/linkedin/dom-automation.d.ts

@@ -1,4 +1,5 @@
 import type { CDPClient } from "../cdp/client.js";
+import type { HumanizedMouse } from "./humanized-mouse.js";
 /** Options for {@link waitForElement}. */
 export interface WaitForElementOptions {
     /** Maximum time to wait in ms (default: 30 000). */
@@ -11,12 +12,30 @@ export type TypeMethod = "type";
 /**
  * Poll the DOM until an element matching the selector appears.
  *
+ * When a {@link HumanizedMouse} is provided, tiny idle mouse movements
+ * (1–5 px) are dispatched on ~20% of poll cycles once the wait exceeds
+ * 500 ms.  This prevents the cursor from remaining perfectly still
+ * during long element waits — a detectable automation fingerprint.
+ *
  * @param client   - Connected CDP client targeting the page.
  * @param selector - CSS selector to query.
  * @param options  - Timeout and polling interval.
+ * @param mouse    - Optional humanized mouse (enables idle drift).
  * @throws {CDPTimeoutError} If the element does not appear within the timeout.
  */
-export declare function waitForElement(client: CDPClient, selector: string, options?: WaitForElementOptions): Promise<void>;
+export declare function waitForElement(client: CDPClient, selector: string, options?: WaitForElementOptions, mouse?: HumanizedMouse | null): Promise<void>;
+/**
+ * Wait until the DOM stops mutating for `quietMs` milliseconds.
+ *
+ * Installs a `MutationObserver` via `Runtime.evaluate` that tracks
+ * the timestamp of the last mutation.  Polls until no mutations have
+ * occurred for the configured quiet period, then adds a "visual
+ * scanning" Gaussian delay to simulate a human pausing to read.
+ *
+ * @param client  - Connected CDP client targeting the page.
+ * @param quietMs - Milliseconds of mutation silence required (default: 500).
+ */
+export declare function waitForDOMStable(client: CDPClient, quietMs?: number): Promise<void>;
 /**
  * Scroll the page until the target element is visible in the viewport.
  *
@@ -54,8 +73,14 @@ export declare function click(client: CDPClient, selector: string): Promise<void
  * Type text into a focused element character-by-character.
  *
  * The element is focused first, then each character is dispatched via
- * CDP `Input.dispatchKeyEvent` with randomised inter-keystroke delays
- * (50–150 ms) to approximate human typing cadence.
+ * CDP `Input.dispatchKeyEvent` with character-context-aware Gaussian
+ * delays to approximate human typing cadence:
+ *
+ * - **Intra-word** (letters, digits): ~65 ms mean — fast, rhythmic typing
+ * - **Word boundary** (space): ~180 ms mean — natural pause between words
+ * - **Sentence boundary** (space after `.!?`): ~350 ms mean — thinking pause
+ * - **Paragraph boundary** (newline): ~700 ms mean — composing the next thought
+ * - **Micro-hesitation** (5% per character): ~300 ms extra — brief mid-word thinking
  *
  * @param client   - Connected CDP client targeting the page.
  * @param selector - CSS selector for the input element.
@@ -64,4 +89,136 @@ export declare function click(client: CDPClient, selector: string): Promise<void
  * @throws {CDPEvaluationError} If the element is not found.
  */
 export declare function typeText(client: CDPClient, selector: string, text: string, method?: TypeMethod): Promise<void>;
+/** Bounding rect returned by element bounds queries. */
+export interface ElementBounds {
+    top: number;
+    bottom: number;
+    height: number;
+}
+/**
+ * Get the bounding rect of a DOM element selected by CSS selector.
+ *
+ * @returns `null` if the element is not found.
+ */
+export declare function getElementBounds(client: CDPClient, selector: string): Promise<ElementBounds | null>;
+/**
+ * Get the bounding rect of the Nth element matching a CSS selector.
+ *
+ * Equivalent to `document.querySelectorAll(baseSelector)[index]`.
+ *
+ * @returns `null` if no element exists at the given index.
+ */
+export declare function getElementBoundsByIndex(client: CDPClient, baseSelector: string, index: number): Promise<ElementBounds | null>;
+/**
+ * Get the viewport height (`window.innerHeight`).
+ */
+export declare function getViewportHeight(client: CDPClient): Promise<number>;
+/**
+ * Scroll the page until the target element is centered in the viewport,
+ * using incremental humanized mouse-wheel strokes.
+ *
+ * When a {@link HumanizedMouse} is available, the cursor scrolls the page
+ * in small increments until the element's bounding rect is in the viewport
+ * center zone.  Falls back to instant `scrollIntoView` otherwise.
+ *
+ * @param client   - Connected CDP client targeting the page.
+ * @param selector - CSS selector for the element to scroll to.
+ * @param mouse    - Optional humanized mouse instance.
+ */
+export declare function humanizedScrollTo(client: CDPClient, selector: string, mouse?: HumanizedMouse | null): Promise<void>;
+/**
+ * Scroll the page until the Nth element matching a selector is centered,
+ * using incremental humanized mouse-wheel strokes.
+ *
+ * Falls back to instant `scrollIntoView` when humanized mouse is unavailable.
+ *
+ * @param client       - Connected CDP client targeting the page.
+ * @param baseSelector - CSS selector matching multiple elements.
+ * @param index        - Zero-based index into the matched elements.
+ * @param mouse        - Optional humanized mouse instance.
+ */
+export declare function humanizedScrollToByIndex(client: CDPClient, baseSelector: string, index: number, mouse?: HumanizedMouse | null): Promise<void>;
+/** Viewport-relative point returned by `getElementCenter`. */
+interface ElementCenter {
+    x: number;
+    y: number;
+}
+/**
+ * Get a jittered viewport-relative point near the center of a DOM element.
+ *
+ * A Gaussian offset is applied so the click target varies naturally within
+ * the element bounds, removing the dead-center automation fingerprint.
+ *
+ * @returns `null` if the element is not found.
+ */
+export declare function getElementCenter(client: CDPClient, selector: string): Promise<ElementCenter | null>;
+/**
+ * Click an element with humanized mouse movement when available.
+ *
+ * When a {@link HumanizedMouse} is provided and available, the cursor
+ * follows a Bezier path to the element center before clicking.  The
+ * VirtualMouse dispatches `mousePressed` / `mouseReleased` via CDP.
+ *
+ * **Pre-focus hover** (60% probability, HumanizedMouse only): before
+ * clicking, the cursor first moves to a point 20–50 px from the target,
+ * pauses briefly to simulate visual scanning, then proceeds to the
+ * target — a two-phase approach that mimics how a human visually locates
+ * a button before moving to click it.
+ *
+ * **Viewport comfort zone**: if the target sits in the outer 20% of the
+ * viewport, a small scroll brings it more central before interacting.
+ *
+ * Falls back to the standard JS `.click()` when humanized mouse is
+ * unavailable (or the element cannot be located by bounding rect).
+ *
+ * @param client - Connected CDP client targeting the LinkedIn page.
+ * @param selector - CSS selector for the element to click.
+ * @param mouse  - Optional humanized mouse instance.
+ */
+export declare function humanizedClick(client: CDPClient, selector: string, mouse?: HumanizedMouse | null): Promise<void>;
+/**
+ * Hover over an element with humanized mouse movement when available.
+ *
+ * When a {@link HumanizedMouse} is provided, the cursor physically
+ * moves to the element center — which is more realistic than
+ * dispatching synthetic `mouseenter` / `mouseover` JS events.
+ *
+ * Falls back to synthetic JS events when unavailable.
+ *
+ * @param client - Connected CDP client targeting the LinkedIn page.
+ * @param selector - CSS selector for the element to hover.
+ * @param mouse  - Optional humanized mouse instance.
+ */
+export declare function humanizedHover(client: CDPClient, selector: string, mouse?: HumanizedMouse | null): Promise<void>;
+/**
+ * Scroll the page vertically with humanized mouse-wheel strokes.
+ *
+ * When a {@link HumanizedMouse} is provided, scrolling is emulated as
+ * incremental wheel strokes (150 px / 25 ms) at the given position,
+ * matching the behavior of a physical mouse wheel.
+ *
+ * Falls back to a single CDP `mouseWheel` event when unavailable.
+ *
+ * @param client - Connected CDP client targeting the LinkedIn page.
+ * @param deltaY - Pixels to scroll (positive = down).
+ * @param x      - Viewport X coordinate for the scroll position.
+ * @param y      - Viewport Y coordinate for the scroll position.
+ * @param mouse  - Optional humanized mouse instance.
+ */
+export declare function humanizedScrollY(client: CDPClient, deltaY: number, x: number, y: number, mouse?: HumanizedMouse | null): Promise<void>;
+/**
+ * Retry an interaction function with escalating Gaussian-distributed
+ * delays between attempts.
+ *
+ * Wraps critical interaction sequences (click after scroll, hover after
+ * navigate) where elements may vanish due to React re-renders.  Each
+ * retry waits progressively longer — `800 * (attempt + 1)` ms mean —
+ * giving the page time to stabilise.
+ *
+ * @param fn          - The async interaction to attempt.
+ * @param maxAttempts - Maximum number of attempts (default: 2).
+ * @returns The result of the first successful attempt.
+ */
+export declare function retryInteraction<T>(fn: () => Promise<T>, maxAttempts?: number): Promise<T>;
+export {};
 //# sourceMappingURL=dom-automation.d.ts.map

package/dist/linkedin/dom-automation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dom-automation.d.ts","sourceRoot":"","sources":["../../src/linkedin/dom-automation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAgBlD,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,8CAA8C;AAC9C,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;;;;GASG;AACH,wBAAsB,KAAK,CACzB,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;;;;GASG;AACH,wBAAsB,KAAK,CACzB,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,UAAmB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAoCf"}
+{"version":3,"file":"dom-automation.d.ts","sourceRoot":"","sources":["../../src/linkedin/dom-automation.ts"],"names":[],"mappings":"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"}