@isdk/web-fetcher 0.2.12 → 0.3.1

package/dist/index.d.mts

@@ -730,6 +730,181 @@ type _RequireAtLeastOne<
 // 3. Add the remaining keys not in `KeysType`
 Except<ObjectType, KeysType>;
 
+/**
+ * Represents the engine-specific execution scope (e.g., a Cheerio node or a Playwright Locator).
+ * It acts as the target for extraction and interaction actions.
+ */
+type FetchElementScope = any;
+/**
+ * Interface representing the minimal engine capabilities required for extraction.
+ *
+ * @remarks
+ * This interface abstracts the underlying DOM manipulation library (Cheerio or Playwright).
+ * Implementing classes must ensure consistent behavior across different engines, especially
+ * regarding scope handling (Element vs Array of Elements) and DOM traversal.
+ */
+interface IExtractEngine {
+    /**
+     * Finds all elements matching the selector within the given scope.
+     *
+     * @param scope - The context to search in. Can be a single element or an array of elements (e.g., in segmented mode).
+     * @param selector - The CSS selector to match.
+     * @returns A promise resolving to an array of found element scopes.
+     *
+     * @remarks
+     * **Behavior Contract:**
+     * 1. **Descendants**: It MUST search for descendants matching the selector within the scope.
+     * 2. **Self-Matching**: It MUST check if the scope element(s) *themselves* match the selector.
+     * 3. **Array Scope**: If `scope` is an array:
+     *    - It MUST process elements in the order they appear in the array (which should match document order).
+     *    - It MUST perform the check (Self + Descendants) for *each* element in the array.
+     *    - It MUST flatten the results into a single array.
+     *    - It SHOULD dedup the results if the engine's query mechanism naturally produces duplicates (e.g. nested scopes),
+     *      but generally, preserving document order is the priority.
+     */
+    _querySelectorAll(scope: FetchElementScope, selector: string): Promise<FetchElementScope[]>;
+    /**
+     * Extracts a primitive value from the element based on the schema configuration.
+     *
+     * @param schema - The value extraction schema defining `type`, `mode`, and `attribute`.
+     * @param scope - The specific element to extract data from.
+     * @returns A promise resolving to the extracted value (string, number, boolean, or null).
+     *
+     * @remarks
+     * **Behavior Contract:**
+     * - **Attribute**: If `schema.attribute` is set, returns the attribute value. If missing, returns `null` or empty string based on engine.
+     * - **HTML**: If `schema.mode` is 'html', returns `innerHTML`.
+     * - **OuterHTML**: If `schema.mode` is 'outerHTML', returns `outerHTML`.
+     * - **Text**: If `schema.mode` is 'text', returns `textContent` (trimmed by default in most implementations).
+     * - **InnerText**: If `schema.mode` is 'innerText', returns rendered text (visual approximation in Cheerio).
+     */
+    _extractValue(schema: ExtractValueSchema, scope: FetchElementScope): Promise<any>;
+    /**
+     * Gets the parent element of the given scope.
+     *
+     * @param scope - The element to find the parent of.
+     * @returns A promise resolving to the parent element scope, or `null` if the element is root or detached.
+     */
+    _parentElement(scope: FetchElementScope): Promise<FetchElementScope | null>;
+    /**
+     * Checks if two element scopes refer to the exact same DOM node.
+     *
+     * @param scope1 - The first element scope.
+     * @param scope2 - The second element scope.
+     * @returns A promise resolving to `true` if they are the same node, `false` otherwise.
+     *
+     * @remarks
+     * This comparison MUST be identity-based, not just content-based.
+     */
+    _isSameElement(scope1: FetchElementScope, scope2: FetchElementScope): Promise<boolean>;
+    /**
+     * Retrieves all subsequent sibling elements of the `scope` element, stopping *before* the first sibling that matches `untilSelector`.
+     *
+     * @param scope - The anchor element (starting point). The returned list starts *after* this element.
+     * @param untilSelector - Optional. A CSS selector. If provided, the scanning stops when a sibling matches this selector (exclusive).
+     *                        If omitted or null, returns all following siblings.
+     * @returns A promise resolving to an array of sibling element scopes.
+     *
+     * @remarks
+     * **Behavior Contract:**
+     * - **Starting Point**: The `scope` element itself IS NOT included in the result.
+     * - **Ending Point**: The element matching `untilSelector` IS NOT included in the result.
+     * - **Direction**: Only scans *following* siblings (next siblings).
+     * - **Flattening**: The result is a flat list of siblings, not a nested structure.
+     */
+    _nextSiblingsUntil(scope: FetchElementScope, untilSelector?: string): Promise<FetchElementScope[]>;
+    /**
+     * Finds the closest ancestor of the `scope` element (including the element itself) that is present in the `candidates` array.
+     *
+     * @param scope - The starting element from which to ascend the DOM tree.
+     * @param candidates - An array of potential ancestor elements to check against.
+     * @returns A promise resolving to the matching candidate element from the array, or `null` if no match is found.
+     *
+     * @remarks
+     * **Performance Critical**: This method is a key optimization for "bubbling up" logic (e.g., in Segmented extraction).
+     * It effectively answers: "Which of these container candidates does my current element belong to?"
+     *
+     * **Implementation Guidelines**:
+     * - **Cheerio**: Should use a `Set` for O(1) candidate lookup during tree traversal (Total O(Depth)).
+     * - **Playwright**: Should perform the entire traversal within a single `page.evaluate` call to avoid O(Depth) IPC round-trips.
+     */
+    _findClosestAncestor(scope: FetchElementScope, candidates: FetchElementScope[]): Promise<FetchElementScope | null>;
+    /**
+     * Checks if the `container` element contains the `element` (descendant).
+     *
+     * @param container - The potential ancestor element.
+     * @param element - The potential descendant element.
+     * @returns A promise resolving to `true` if `container` contains `element`, `false` otherwise.
+     *
+     * @remarks
+     * **Standard Compliance**: This mirrors the DOM [Node.contains()](https://developer.mozilla.org/en-US/docs/Web/API/Node/contains) behavior.
+     *
+     * @performance-critical Used extensively in boundary checks for Segmented extraction.
+     * - **Playwright**: MUST use `elementHandle.evaluate` to use native `Node.contains` in the browser context, reducing IPC overhead.
+     * - **Cheerio**: Should use efficient lookups like `$.contains` or `.find()`.
+     */
+    _contains(container: FetchElementScope, element: FetchElementScope): Promise<boolean>;
+    /**
+     * Finds the Lowest Common Ancestor (LCA) of two element scopes.
+     *
+     * @param scope1 - The first element.
+     * @param scope2 - The second element.
+     * @returns A promise resolving to the LCA element, or null if they are in different documents/trees.
+     *
+     * @remarks
+     * This is a fundamental tree operation used to find the point where two element paths diverge.
+     * **Performance Critical**: For Playwright, this MUST be implemented in a single `evaluate` call.
+     */
+    _findCommonAncestor(scope1: FetchElementScope, scope2: FetchElementScope): Promise<FetchElementScope | null>;
+    /**
+     * Finds the direct child of the `container` that contains the `element` (or is the `element` itself).
+     *
+     * @param element - The descendant element.
+     * @param container - The ancestor container.
+     * @returns A promise resolving to the child element, or null if `element` is not a descendant of `container`.
+     *
+     * @remarks
+     * This method traverses up from `element` until it finds the node whose parent is `container`.
+     * **Performance Critical**: This replaces the manual bubble-up loop in Node.js.
+     */
+    _findContainerChild(element: FetchElementScope, container: FetchElementScope): Promise<FetchElementScope | null>;
+    /**
+     * Logs debug information if debug mode is enabled.
+     * @param category - The category of the log message.
+     * @param args - Arguments to log.
+     */
+    _logDebug(category: string, ...args: any[]): void;
+}
+/**
+ * Base configuration for all extraction schemas.
+ */
+interface BaseExtractSchema {
+    /**
+     * Whether this field is required. If true and the value is null,
+     * the containing object or array item will be skipped (or throw error in strict mode).
+     */
+    required?: boolean;
+    /**
+     * Whether to enable strict mode for this extraction.
+     * If true, missing required fields will throw an error instead of being skipped.
+     */
+    strict?: boolean;
+    /**
+     * Specifies the starting anchor for extraction of this field.
+     * - Field Name: Uses the DOM element of a previously extracted field as the anchor.
+     * - CSS Selector: Re-queries the selector within the current context to find the anchor.
+     *
+     * Once anchored, the search scope for this field becomes the siblings following the anchor.
+     */
+    anchor?: string;
+    /**
+     * The maximum number of levels to bubble up from the anchor or matched element.
+     * - In 'anchor' mode: Defines how many parent levels to traverse to collect following siblings.
+     * - In 'segmented' mode: Defines the maximum levels to ascend from the anchor to find a container.
+     * - In 'object' mode: Enables "Try-And-Bubble". Attempts extraction at current level; if required fields are missing, bubbles up (max `depth` levels) to retry.
+     */
+    depth?: number;
+}
 /**
  * Extraction schema types.
  */
@@ -737,7 +912,7 @@ type ExtractSchema = ExtractObjectSchema | ExtractArraySchema | ExtractValueSche
 /**
  * Configuration for extracting a single value.
  */
-interface ExtractValueSchema {
+interface ExtractValueSchema extends BaseExtractSchema {
     /**
      * The data type to cast the extracted value to.
      * @default 'string'
@@ -774,16 +949,21 @@ interface ExtractValueSchema {
  */
 type ExtractArrayModeName = 'nested' | 'columnar' | 'segmented';
 /**
- * Options for columnar (column-alignment) extraction.
+ * Base options for array extraction modes.
  */
-interface ColumnarOptions {
-    type: 'columnar';
+interface BaseModeOptions {
+    type: ExtractArrayModeName;
     /**
-     * Whether to enable strict mode.
-     * If true, throws an error if fields in `items` have different match counts.
-     * @default true
+     * Whether to enable strict mode for this specific array mode.
+     * @default false
      */
     strict?: boolean;
+}
+/**
+ * Options for columnar (column-alignment) extraction.
+ */
+interface ColumnarOptions extends BaseModeOptions {
+    type: 'columnar';
     /**
      * Whether to enable heuristic inference.
      * If true, tries to find a common parent to infer item wrappers when counts mismatch.
@@ -794,13 +974,24 @@ interface ColumnarOptions {
 /**
  * Options for segmented (anchor-based) extraction.
  */
-interface SegmentedOptions {
+interface SegmentedOptions extends BaseModeOptions {
     type: 'segmented';
     /**
-     * The name of the field in `items` to use as a segment anchor.
-     * Defaults to the first property key defined in `items`.
+     * The name of the field in `items` to use as a segment anchor, or a direct CSS selector.
+     * Defaults to the first property key's selector defined in `items`.
      */
     anchor?: string;
+    /**
+     * Where to start searching for fields within each segment.
+     * - 'anchor': (Default) All fields are searched within the entire segment.
+     * - 'previous': Each field is searched starting from after the previous field's match.
+     */
+    relativeTo?: 'anchor' | 'previous';
+    /**
+     * The maximum number of levels to bubble up from the anchor to find a segment container.
+     * If omitted, it bubbles up as high as possible without conflicting with neighboring segments.
+     */
+    depth?: number;
 }
 /**
  * Union type for array extraction modes and their options.
@@ -809,7 +1000,7 @@ type ExtractArrayMode = ExtractArrayModeName | ColumnarOptions | SegmentedOption
 /**
  * Configuration for extracting an array of items.
  */
-interface ExtractArraySchema {
+interface ExtractArraySchema extends BaseExtractSchema {
     type: 'array';
     /**
      * CSS selector for items (in 'nested' mode) or the container (in 'columnar'/'segmented' modes).
@@ -843,7 +1034,7 @@ interface ExtractArraySchema {
 /**
  * Configuration for extracting an object with multiple properties.
  */
-interface ExtractObjectSchema {
+interface ExtractObjectSchema extends BaseExtractSchema {
     type: 'object';
     /**
      * Root selector for the object. If provided, sub-properties are searched within this element.
@@ -857,6 +1048,18 @@ interface ExtractObjectSchema {
      * Exclude the object element if it matches this selector.
      */
     exclude?: string;
+    /**
+     * Where to start searching for fields within this object.
+     * Only applicable when the object is being extracted from an array of elements (e.g. in 'segmented' mode).
+     * - 'anchor': (Default) All fields are searched within the entire scope.
+     * - 'previous': Each field is searched starting from after the previous field's match.
+     */
+    relativeTo?: 'anchor' | 'previous';
+    /**
+     * Explicit order of property extraction.
+     * Useful when using `relativeTo: 'previous'`.
+     */
+    order?: string[];
     /**
      * Definition of the object's properties and their corresponding extraction schemas.
      */
@@ -891,6 +1094,7 @@ interface GotoActionOptions {
     headers?: Record<string, string>;
     waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
     timeoutMs?: number;
+    simulate?: boolean;
 }
 /**
  * Options for the {@link FetchEngine.waitFor} action, specifying conditions to wait for before continuing.
@@ -913,6 +1117,78 @@ interface WaitForActionOptions {
 interface SubmitActionOptions {
     enctype?: 'application/x-www-form-urlencoded' | 'application/json' | 'multipart/form-data';
 }
+/**
+ * Predefined cleanup groups for the {@link FetchEngine.trim} action.
+ */
+type TrimPreset = 'scripts' | 'styles' | 'svgs' | 'images' | 'comments' | 'hidden' | 'all';
+/**
+ * Options for the {@link FetchEngine.trim} action, specifying which elements to remove from the DOM.
+ */
+interface TrimActionOptions {
+    selectors?: string | string[];
+    presets?: TrimPreset | TrimPreset[];
+}
+declare const TRIM_PRESETS: Record<string, string[]>;
+/**
+ * Options for the {@link FetchEngine.evaluate} action, specifying the function to execute and its arguments.
+ *
+ * @remarks
+ * This action allows executing custom JavaScript logic within the page context.
+ *
+ * **Execution Environments:**
+ * - **`browser` mode (Playwright)**: Executes directly in the real browser's execution context.
+ * - **`http` mode (Cheerio)**: Executes in a Node.js sandbox using `newFunction`. It provides a mocked browser environment
+ *   including `window`, `document` (with `querySelector`, `querySelectorAll`, etc.), and `console`.
+ *
+ * **Navigation Handling:**
+ * If the executed code modifies `window.location.href` (or calls `assign()`/`replace()`), the engine will
+ * automatically detect the change, trigger a navigation, and wait for the new page to load before resolving the action.
+ *
+ * @example
+ * ```json
+ * {
+ *   "action": "evaluate",
+ *   "params": {
+ *     "fn": "([a, b]) => a + b",
+ *     "args": [1, 2]
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * {
+ *   "action": "evaluate",
+ *   "params": {
+ *     "fn": "({ x, y }) => x * y",
+ *     "args": { "x": 6, "y": 7 }
+ *   }
+ * }
+ * ```
+ */
+interface EvaluateActionOptions {
+    /**
+     * The function or expression to execute.
+     *
+     * @remarks
+     * Can be:
+     * 1. A function object (only available when using the API directly).
+     * 2. A string containing a function definition, e.g., `"async (args) => { ... }"`
+     * 3. A string containing a direct expression, e.g., `"document.title"`
+     *
+     * **Note:** When using a function, it receives exactly ONE argument: the value provided in {@link args}.
+     * Use destructuring to handle multiple parameters.
+     */
+    fn: string | ((...args: any[]) => any);
+    /**
+     * Data to pass to the function.
+     *
+     * @remarks
+     * This value is passed as the first and only argument to the function defined in {@link fn}.
+     * Recommended to use an array or object for multiple values.
+     */
+    args?: any;
+}
 /**
  * Union type representing all possible engine actions that can be dispatched.
  *
@@ -927,6 +1203,35 @@ type FetchEngineAction = {
     type: 'fill';
     selector: string;
     value: string;
+} | {
+    type: 'mouseMove';
+    params: {
+        x?: number;
+        y?: number;
+        selector?: string;
+        steps?: number;
+    };
+} | {
+    type: 'mouseClick';
+    params: {
+        x?: number;
+        y?: number;
+        button?: 'left' | 'right' | 'middle';
+        clickCount?: number;
+        delay?: number;
+    };
+} | {
+    type: 'keyboardType';
+    params: {
+        text: string;
+        delay?: number;
+    };
+} | {
+    type: 'keyboardPress';
+    params: {
+        key: string;
+        delay?: number;
+    };
 } | {
     type: 'waitFor';
     options?: WaitForActionOptions;
@@ -946,6 +1251,12 @@ type FetchEngineAction = {
 } | {
     type: 'pause';
     message?: string;
+} | {
+    type: 'trim';
+    options: TrimActionOptions;
+} | {
+    type: 'evaluate';
+    params: EvaluateActionOptions;
 } | {
     type: 'dispose';
 };
@@ -995,7 +1306,7 @@ interface PendingEngineRequest {
  */
 type AnyFetchEngine = FetchEngine<any, any, any>;
 type AnyFetchEngineCtor = new (...args: any[]) => AnyFetchEngine;
-declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCrawler extends BasicCrawler<TContext> = any, TOptions extends BasicCrawlerOptions<TContext> = any> {
+declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCrawler extends BasicCrawler<TContext> = any, TOptions extends BasicCrawlerOptions<TContext> = any> implements IExtractEngine {
     private static registry;
     /**
      * Registers a fetch engine implementation with the global registry.
@@ -1068,46 +1379,105 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
     protected isPageActive: boolean;
     protected isEngineDisposed: boolean;
     protected navigationLock: PromiseLock;
+    protected activeContext?: TContext;
+    protected isExecutingAction: boolean;
     protected lastResponse?: FetchResponse;
+    protected actionQueue: DispatchedEngineAction[];
+    protected isProcessingActionLoop: boolean;
     protected blockedTypes: Set<string>;
+    _logDebug(category: string, ...args: any[]): void;
     protected _cleanup?(): Promise<void>;
+    protected _getTrimInfo(options: TrimActionOptions): {
+        selectors: string[];
+        removeComments: boolean;
+        removeHidden: boolean;
+    };
     /**
-     * Finds all elements matching the selector within the given context.
-     * @param context - The context to search in (Engine-specific element/node or array of nodes).
+     * Finds all elements matching the selector within the given scope.
+     *
+     * @param scope - The scope to search in (Engine-specific element/node or array of nodes).
      * @param selector - CSS selector.
+     * @returns List of matching elements.
+     * @see {@link IExtractEngine._querySelectorAll} for behavior contract.
      * @internal
      */
-    protected abstract _querySelectorAll(context: any, selector: string): Promise<any[]>;
+    abstract _querySelectorAll(scope: FetchElementScope, selector: string): Promise<FetchElementScope[]>;
     /**
      * Extracts a primitive value from the element based on schema.
+     *
      * @param schema - Value extraction schema.
-     * @param context - The element context.
+     * @param scope - The element scope.
+     * @returns Extracted value.
+     * @see {@link IExtractEngine._extractValue} for behavior contract.
      * @internal
      */
-    protected abstract _extractValue(schema: ExtractValueSchema, context: any): Promise<any>;
+    abstract _extractValue(schema: ExtractValueSchema, scope: FetchElementScope): Promise<any>;
     /**
      * Gets the parent element of the given element.
-     * @param element - The element.
+     *
+     * @param scope - The element scope.
+     * @returns Parent element or null.
      * @internal
      */
-    protected abstract _parentElement(element: any): Promise<any | null>;
+    abstract _parentElement(scope: FetchElementScope): Promise<FetchElementScope | null>;
     /**
-     * Checks if two elements are the same.
-     * @param element1 - First element.
-     * @param element2 - Second element.
+     * Checks if two elements are the same identity.
+     *
+     * @param scope1 - First element scope.
+     * @param scope2 - Second element scope.
+     * @returns True if they are the same DOM node.
      * @internal
      */
-    protected abstract _isSameElement(element1: any, element2: any): Promise<boolean>;
+    abstract _isSameElement(scope1: FetchElementScope, scope2: FetchElementScope): Promise<boolean>;
     /**
      * Gets all subsequent siblings of an element until a sibling matches the selector.
      * Used in 'segmented' extraction mode.
-     * @param element - The anchor element.
-     * @param untilSelector - Optional selector that marks the end of the segment.
+     *
+     * @param scope - The anchor element scope.
+     * @param untilSelector - Optional selector that marks the end of the segment (exclusive).
+     * @returns List of sibling elements between anchor and untilSelector.
      * @internal
      */
-    protected abstract _nextSiblingsUntil(element: any, untilSelector?: string): Promise<any[]>;
-    protected _isImplicitObject(schema: any): boolean;
-    protected _extract(schema: ExtractSchema, context: any): Promise<any>;
+    abstract _nextSiblingsUntil(scope: FetchElementScope, untilSelector?: string): Promise<FetchElementScope[]>;
+    /**
+     * Finds the closest ancestor of `scope` (including itself) that exists in the `candidates` array.
+     *
+     * @param scope - The starting element.
+     * @param candidates - The array of potential ancestor scopes.
+     * @returns A promise resolving to the matching candidate scope, or `null` if none found.
+     * @see {@link IExtractEngine._findClosestAncestor} for implementation details.
+     * @internal
+     */
+    abstract _findClosestAncestor(scope: FetchElementScope, candidates: FetchElementScope[]): Promise<FetchElementScope | null>;
+    /**
+     * Checks if the `container` scope contains the `element` scope.
+     *
+     * @param container - The potential ancestor element.
+     * @param element - The potential descendant element.
+     * @returns A promise resolving to `true` if `container` contains `element`.
+     * @see {@link IExtractEngine._contains} for implementation details.
+     * @internal
+     */
+    abstract _contains(container: FetchElementScope, element: FetchElementScope): Promise<boolean>;
+    /**
+     * Finds the Lowest Common Ancestor (LCA) of two element scopes.
+     *
+     * @param scope1 - The first element scope.
+     * @param scope2 - The second element scope.
+     * @returns A promise resolving to the LCA element scope, or `null` if none found.
+     * @internal
+     */
+    abstract _findCommonAncestor(scope1: FetchElementScope, scope2: FetchElementScope): Promise<FetchElementScope | null>;
+    /**
+     * Finds the direct child of container that contains element.
+     *
+     * @param element - The descendant element.
+     * @param container - The container element.
+     * @returns The child element of container, or null.
+     * @internal
+     */
+    abstract _findContainerChild(element: FetchElementScope, container: FetchElementScope): Promise<FetchElementScope | null>;
+    protected _extract(schema: ExtractSchema, scope: FetchElementScope, parentStrict?: boolean): Promise<any>;
     /**
      * Normalizes the array extraction mode into an options object.
      * @param mode - The mode string or options object.
@@ -1122,7 +1492,9 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
      * @param elements - The list of item elements.
      * @internal
      */
-    protected _extractNested(items: ExtractSchema, elements: any[]): Promise<any[]>;
+    protected _extractNested(items: ExtractSchema, elements: FetchElementScope[], opts?: {
+        strict?: boolean;
+    }): Promise<any[]>;
     /**
      * Performs columnar extraction (Column Alignment Mode).
      *
@@ -1132,7 +1504,7 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
      * @returns An array of extracted items, or null if requirements aren't met.
      * @internal
      */
-    protected _extractColumnar(schema: ExtractSchema, container: any, opts?: ColumnarOptions): Promise<any[] | null>;
+    protected _extractColumnar(schema: ExtractSchema, container: FetchElementScope, opts?: ColumnarOptions): Promise<any[] | null>;
     /**
      * Performs segmented extraction (Anchor-based Scanning).
      *
@@ -1142,7 +1514,7 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
      * @returns An array of extracted items.
      * @internal
      */
-    protected _extractSegmented(schema: ExtractSchema, container: any, opts?: SegmentedOptions): Promise<any[] | null>;
+    protected _extractSegmented(schema: ExtractSchema, container: FetchElementScope, opts?: SegmentedOptions): Promise<any[] | null>;
     /**
      * Creates the crawler instance for the specific engine implementation.
      * @param options - The final crawler options.
@@ -1213,6 +1585,43 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
      * @throws {Error} When no active page context exists
      */
     click(selector: string): Promise<void>;
+    /**
+     * Moves mouse to specified position or element.
+     *
+     * @param params - Move parameters (x, y, selector, steps)
+     */
+    mouseMove(params: {
+        x?: number;
+        y?: number;
+        selector?: string;
+        steps?: number;
+    }): Promise<void>;
+    /**
+     * Clicks at current position or specified position.
+     *
+     * @param params - Click parameters (x, y, button, clickCount, delay)
+     */
+    mouseClick(params: {
+        x?: number;
+        y?: number;
+        button?: 'left' | 'right' | 'middle';
+        clickCount?: number;
+        delay?: number;
+    }): Promise<void>;
+    /**
+     * Types text into current focused element.
+     *
+     * @param text - Text to type
+     * @param delay - Delay between key presses
+     */
+    keyboardType(text: string, delay?: number): Promise<void>;
+    /**
+     * Presses specified key.
+     *
+     * @param key - Key to press
+     * @param delay - Delay after key press
+     */
+    keyboardPress(key: string, delay?: number): Promise<void>;
     /**
      * Fills input element with specified value.
      *
@@ -1231,6 +1640,14 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
      * @throws {Error} When no active page context exists
      */
     submit(selector?: any, options?: SubmitActionOptions): Promise<void>;
+    /**
+     * Removes elements from the DOM based on selectors and presets.
+     *
+     * @param options - Trim options specifying selectors and presets
+     * @returns Promise resolving when trim operation completes
+     * @throws {Error} When no active page context exists
+     */
+    trim(options: TrimActionOptions): Promise<void>;
     /**
      * Pauses execution, allowing for manual intervention or inspection.
      *
@@ -1239,6 +1656,25 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
      * @throws {Error} When no active page context exists
      */
     pause(message?: string): Promise<void>;
+    /**
+     * Executes a custom function or expression within the current page context.
+     *
+     * @remarks
+     * This is a powerful action that allows running custom logic to interact with the DOM,
+     * calculate values, or trigger navigations.
+     *
+     * - In **Browser Mode**, it runs in the real browser.
+     * - In **HTTP Mode**, it runs in a Node.js sandbox with a mocked DOM.
+     *
+     * The action handles automatic navigation if `window.location` is modified.
+     *
+     * @param params - Configuration for the execution, including the function and arguments.
+     * @returns A promise resolving to the result of the execution.
+     * @throws {Error} If no active page context exists or if execution fails.
+     *
+     * @see {@link EvaluateActionOptions} for detailed parameter options and examples.
+     */
+    evaluate(params: EvaluateActionOptions): Promise<any>;
     /**
      * Extracts structured data from the current page content.
      *
@@ -1246,7 +1682,6 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
      * @returns A promise that resolves to an object with the extracted data.
      */
     extract<T>(schema: ExtractSchema): Promise<T>;
-    protected _normalizeSchema(schema: ExtractSchema): ExtractSchema;
     /**
      * Gets the unique identifier of this engine implementation.
      */
@@ -1280,6 +1715,22 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
      */
     initialize(context: FetchEngineContext, options?: BaseFetcherProperties): Promise<void>;
     cleanup(): Promise<void>;
+    /**
+     * Gets the initial scope for extraction for the specific engine.
+     * @param context - Crawlee crawling context
+     * @internal
+     */
+    protected abstract _getInitialElementScope(context: TContext): FetchElementScope;
+    /**
+     * Unified action processor that handles engine-agnostic actions.
+     * @param context - Crawlee crawling context
+     * @param action - Action to execute
+     * @internal
+     */
+    protected _processAction(context: TContext, action: FetchEngineAction): Promise<any>;
+    protected _handlePause(action: {
+        message?: string;
+    }): Promise<void>;
     /**
      * Executes all pending fetch engine actions within the current Crawlee request handler context.
      *
@@ -1543,29 +1994,64 @@ declare class CheerioFetchEngine extends FetchEngine<CheerioCrawlingContext, Che
     static readonly mode = "http";
     private _ensureCheerioContext;
     protected _buildResponse(context: CheerioCrawlingContext): Promise<FetchResponse>;
-    protected _querySelectorAll(context: {
+    _querySelectorAll(scope: {
         $: CheerioAPI;
         el: any;
-    } | any[], selector: string): Promise<any[]>;
-    protected _nextSiblingsUntil(context: {
+    } | any[], selector: string): Promise<FetchElementScope[]>;
+    _nextSiblingsUntil(scope: {
+        $: CheerioAPI;
+        el: CheerioNode;
+    }, untilSelector?: string): Promise<FetchElementScope[]>;
+    _parentElement(scope: {
+        $: CheerioAPI;
+        el: CheerioNode;
+    }): Promise<FetchElementScope | null>;
+    _isSameElement(scope1: {
+        el: CheerioNode;
+    }, scope2: {
+        el: CheerioNode;
+    }): Promise<boolean>;
+    _findClosestAncestor(scope: {
         $: CheerioAPI;
         el: CheerioNode;
-    }, untilSelector?: string): Promise<any[]>;
-    protected _parentElement(context: {
+    }, candidates: {
         $: CheerioAPI;
         el: CheerioNode;
-    }): Promise<any | null>;
-    protected _isSameElement(context1: {
+    }[]): Promise<FetchElementScope | null>;
+    _contains(container: {
+        $: CheerioAPI;
         el: CheerioNode;
-    }, context2: {
+    }, element: {
+        $: CheerioAPI;
         el: CheerioNode;
     }): Promise<boolean>;
-    protected _extractValue(schema: ExtractValueSchema, context: {
+    _findCommonAncestor(scope1: {
+        $: CheerioAPI;
+        el: CheerioNode;
+    }, scope2: {
+        $: CheerioAPI;
+        el: CheerioNode;
+    }): Promise<FetchElementScope | null>;
+    _findContainerChild(element: {
+        $: CheerioAPI;
+        el: CheerioNode;
+    }, container: {
+        $: CheerioAPI;
+        el: CheerioNode;
+    }): Promise<FetchElementScope | null>;
+    _extractValue(schema: ExtractValueSchema, scope: {
         $: CheerioAPI;
         el: CheerioNode;
     }): Promise<any>;
+    protected _getInitialElementScope(context: CheerioCrawlingContext): FetchElementScope;
     protected executeAction(context: CheerioCrawlingContext, action: FetchEngineAction): Promise<any>;
-    private _updateStateAfterNavigation;
+    protected _requestWithRedirects(context: CheerioCrawlingContext, options: {
+        url: string;
+        method: string;
+        body?: any;
+        headers?: Record<string, string>;
+    }): Promise<any>;
+    protected _updateStateAfterNavigation(context: CheerioCrawlingContext, loadedRequest: any): Promise<void>;
     protected _createCrawler(options: CheerioCrawlerOptions, config?: Configuration): CheerioCrawler;
     protected _getSpecificCrawlerOptions(ctx: FetchEngineContext): CheerioCrawlerOptions;
     goto(url: string, params?: GotoActionOptions): Promise<void | FetchResponse>;
@@ -1577,11 +2063,36 @@ declare class PlaywrightFetchEngine extends FetchEngine<PlaywrightCrawlingContex
     static readonly id = "playwright";
     static readonly mode = "browser";
     protected _buildResponse(context: PlaywrightCrawlingContext): Promise<FetchResponse>;
-    protected _querySelectorAll(context: Locator | Locator[], selector: string): Promise<any[]>;
-    protected _nextSiblingsUntil(context: Locator, untilSelector?: string): Promise<any[]>;
-    protected _parentElement(context: Locator): Promise<any | null>;
-    protected _isSameElement(context1: Locator, context2: Locator): Promise<boolean>;
-    protected _extractValue(schema: ExtractValueSchema, context: Locator): Promise<any>;
+    _querySelectorAll(scope: Locator | Locator[], selector: string): Promise<FetchElementScope[]>;
+    _nextSiblingsUntil(scope: Locator, untilSelector?: string): Promise<FetchElementScope[]>;
+    _parentElement(scope: Locator): Promise<FetchElementScope | null>;
+    _isSameElement(scope1: Locator, scope2: Locator): Promise<boolean>;
+    _findClosestAncestor(scope: Locator, candidates: Locator[]): Promise<FetchElementScope | null>;
+    _contains(container: Locator, element: Locator): Promise<boolean>;
+    _findCommonAncestor(scope1: Locator, scope2: Locator): Promise<FetchElementScope | null>;
+    _findContainerChild(element: Locator, container: Locator): Promise<FetchElementScope | null>;
+    _extractValue(schema: ExtractValueSchema, scope: Locator): Promise<any>;
+    protected _getInitialElementScope(context: PlaywrightCrawlingContext): FetchElementScope;
+    protected _waitForNavigation(context: PlaywrightCrawlingContext, oldUrl: string, actionType: string): Promise<void>;
+    protected currentMousePos: {
+        x: number;
+        y: number;
+    };
+    protected _getRandomDelay(base: number, variance?: number): number;
+    protected _getTrajectory(start: {
+        x: number;
+        y: number;
+    }, end: {
+        x: number;
+        y: number;
+    }, steps?: number): {
+        x: number;
+        y: number;
+    }[];
+    protected _moveToSelector(context: PlaywrightCrawlingContext, selector: string, steps?: number): Promise<{
+        x: number;
+        y: number;
+    }>;
     protected executeAction(context: PlaywrightCrawlingContext, action: FetchEngineAction): Promise<any>;
     protected _createCrawler(options: PlaywrightCrawlerOptions, config?: Configuration): PlaywrightCrawler;
     protected _getSpecificCrawlerOptions(ctx: FetchEngineContext): Promise<Partial<PlaywrightCrawlerOptions>>;
@@ -1742,7 +2253,7 @@ interface BaseFetcherProperties {
     enableSmart?: boolean;
     useSiteRegistry?: boolean;
     antibot?: boolean;
-    debug?: boolean;
+    debug?: boolean | string | string[];
     headers?: Record<string, string>;
     cookies?: Cookie[];
     sessionState?: any;
@@ -1770,6 +2281,7 @@ interface BaseFetcherProperties {
         engine?: BrowserEngine;
         headless?: boolean;
         waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+        launchOptions?: Record<string, any>;
     };
     http?: {
         method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -1860,6 +2372,7 @@ declare class FetchSession {
      * @param options - Configuration options for the fetcher.
      */
     constructor(options?: FetcherOptions);
+    protected _logDebug(category: string, ...args: any[]): void;
     /**
      * Executes a single action within the session.
      *
@@ -2055,6 +2568,110 @@ declare class PauseAction extends FetchAction {
     onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
 }
 
+declare class TrimAction extends FetchAction {
+    static id: string;
+    static returnType: "none";
+    static capabilities: {
+        http: "simulate";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
+
+/**
+ * Action that evaluates a JavaScript function or expression in the context of the page.
+ *
+ * @remarks
+ * This action is cross-engine compatible. In Cheerio (HTTP) mode, it simulates a browser environment
+ * by providing `window` and `document` objects linked to the Cheerio instance.
+ *
+ * Key features:
+ * - Supports async functions.
+ * - Supports direct expressions (e.g., `"document.title"`).
+ * - Detects URL changes and triggers navigation.
+ * - Consistent parameter passing with Playwright (single argument).
+ *
+ * @example
+ * ```json
+ * {
+ *   "action": "evaluate",
+ *   "params": {
+ *     "fn": "({ selector }) => document.querySelector(selector).textContent",
+ *     "args": { "selector": "h1" }
+ *   },
+ *   "storeAs": "pageTitle"
+ * }
+ * ```
+ */
+declare class EvaluateAction extends FetchAction {
+    static id: string;
+    static returnType: "any";
+    static capabilities: {
+        http: "simulate";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<any>;
+}
+
+interface MouseMoveParams {
+    x?: number;
+    y?: number;
+    selector?: string;
+    steps?: number;
+}
+declare class MouseMoveAction extends FetchAction {
+    static id: string;
+    static returnType: "none";
+    static capabilities: {
+        http: "noop";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
+interface MouseClickParams {
+    x?: number;
+    y?: number;
+    button?: 'left' | 'right' | 'middle';
+    clickCount?: number;
+    delay?: number;
+}
+declare class MouseClickAction extends FetchAction {
+    static id: string;
+    static returnType: "none";
+    static capabilities: {
+        http: "noop";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
+
+interface KeyboardTypeParams {
+    text: string;
+    delay?: number;
+}
+declare class KeyboardTypeAction extends FetchAction {
+    static id: string;
+    static returnType: "none";
+    static capabilities: {
+        http: "noop";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
+interface KeyboardPressParams {
+    key: string;
+    delay?: number;
+}
+declare class KeyboardPressAction extends FetchAction {
+    static id: string;
+    static returnType: "none";
+    static capabilities: {
+        http: "noop";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
+
 declare function fetchWeb(options: FetcherOptions): Promise<{
     result: FetchResponse | undefined;
     outputs: Record<string, any>;
@@ -2064,4 +2681,4 @@ declare function fetchWeb(url: string, options?: FetcherOptions): Promise<{
     outputs: Record<string, any>;
 }>;
 
-export { type BaseFetchActionOptions, type BaseFetchActionProperties, type BaseFetchCollectorActionProperties, type BaseFetchCollectorOptions, type BaseFetcherProperties, type BrowserEngine, CheerioFetchEngine, ClickAction, DefaultFetcherProperties, type DispatchedEngineAction, ExtractAction, type ExtractActionProperties, FetchAction, type FetchActionCapabilities, type FetchActionCapabilityMode, type FetchActionInContext, type FetchActionOptions, type FetchActionProperties, type FetchActionResult, FetchActionResultStatus, type FetchContext, FetchEngine, type FetchEngineAction, type FetchEngineContext, type FetchEngineType, type FetchMetadata, type FetchResponse, type FetchReturnType, type FetchReturnTypeFor, type FetchReturnTypeRegistry, FetchSession, type FetchSite, FetcherOptionKeys, type FetcherOptions, FillAction, GetContentAction, GotoAction, type GotoActionOptions, type OnFetchPauseCallback, PauseAction, type PendingEngineRequest, PlaywrightFetchEngine, type ResourceType, type StorageOptions, SubmitAction, type SubmitActionOptions, WaitForAction, type WaitForActionOptions, WebFetcher, fetchWeb };
+export { type BaseFetchActionOptions, type BaseFetchActionProperties, type BaseFetchCollectorActionProperties, type BaseFetchCollectorOptions, type BaseFetcherProperties, type BrowserEngine, CheerioFetchEngine, ClickAction, DefaultFetcherProperties, type DispatchedEngineAction, EvaluateAction, type EvaluateActionOptions, ExtractAction, type ExtractActionProperties, FetchAction, type FetchActionCapabilities, type FetchActionCapabilityMode, type FetchActionInContext, type FetchActionOptions, type FetchActionProperties, type FetchActionResult, FetchActionResultStatus, type FetchContext, FetchEngine, type FetchEngineAction, type FetchEngineContext, type FetchEngineType, type FetchMetadata, type FetchResponse, type FetchReturnType, type FetchReturnTypeFor, type FetchReturnTypeRegistry, FetchSession, type FetchSite, FetcherOptionKeys, type FetcherOptions, FillAction, GetContentAction, GotoAction, type GotoActionOptions, KeyboardPressAction, type KeyboardPressParams, KeyboardTypeAction, type KeyboardTypeParams, MouseClickAction, type MouseClickParams, MouseMoveAction, type MouseMoveParams, type OnFetchPauseCallback, PauseAction, type PendingEngineRequest, PlaywrightFetchEngine, type ResourceType, type StorageOptions, SubmitAction, type SubmitActionOptions, TRIM_PRESETS, TrimAction, type TrimActionOptions, type TrimPreset, WaitForAction, type WaitForActionOptions, WebFetcher, fetchWeb };