@isdk/web-fetcher 0.3.2 → 0.3.3

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CrawlingContext, BasicCrawler, BasicCrawlerOptions, FinalStatistics, Configuration, RequestQueue, KeyValueStore, ProxyConfiguration, Cookie, Session, CheerioCrawlingContext, CheerioCrawler, CheerioCrawlerOptions, PlaywrightCrawlingContext, PlaywrightCrawler, PlaywrightCrawlerOptions, SessionPoolOptions } from 'crawlee';
+import { Cookie, SessionPoolOptions, CrawlingContext, BasicCrawler, BasicCrawlerOptions, FinalStatistics, Configuration, RequestQueue, KeyValueStore, ProxyConfiguration, Session, CheerioCrawlingContext, CheerioCrawler, CheerioCrawlerOptions, PlaywrightCrawlingContext, PlaywrightCrawler, PlaywrightCrawlerOptions } from 'crawlee';
 export { Cookie } from 'crawlee';
 import { EventEmitter } from 'events-ex';
 
@@ -731,1810 +731,1835 @@ type _RequireAtLeastOne<
 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.
+ * Represents the state of an action being executed within a context.
  *
  * @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.
+ * Extends the basic action properties with runtime metadata like execution index,
+ * nesting depth, and any errors encountered during execution.
  */
-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[]>;
+type FetchActionInContext = FetchActionOptions & {
     /**
-     * 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).
+     * The 0-based index of the action in the execution sequence.
      */
-    _extractValue(schema: ExtractValueSchema, scope: FetchElementScope): Promise<any>;
+    index?: number;
     /**
-     * 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.
+     * Error encountered during action execution, if any.
      */
-    _parentElement(scope: FetchElementScope): Promise<FetchElementScope | null>;
+    error?: Error;
     /**
-     * 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.
+     * The nesting depth of the action. Top-level actions (executed directly by the session) have a depth of 0.
      */
-    _isSameElement(scope1: FetchElementScope, scope2: FetchElementScope): Promise<boolean>;
+    depth?: number;
+};
+/**
+ * Base internal state used by fetch engines to maintain their runtime environment.
+ *
+ * @internal
+ */
+interface BaseFetchContextInteralState {
     /**
-     * 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.
+     * The active engine instance (e.g., CheerioFetchEngine or PlaywrightFetchEngine)
+     * associated with this context.
      */
-    _nextSiblingsUntil(scope: FetchElementScope, untilSelector?: string): Promise<FetchElementScope[]>;
+    engine?: any;
     /**
-     * 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.
+     * Additional implementation-specific internal state.
      */
-    _findClosestAncestor(scope: FetchElementScope, candidates: FetchElementScope[]): Promise<FetchElementScope | null>;
+    [key: string]: any;
+}
+/**
+ * Extended internal state for the fetch context, including action lifecycle management.
+ *
+ * @internal
+ */
+interface FetchContextInteralState extends BaseFetchContextInteralState {
     /**
-     * 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()`.
+     * Stack of actions currently being executed, used to manage nested action calls.
      */
-    _contains(container: FetchElementScope, element: FetchElementScope): Promise<boolean>;
+    actionStack?: FetchActionInContext[];
     /**
-     * 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.
+     * Global counter for actions executed within the session, used to assign auto-incrementing indices.
      */
-    _findCommonAncestor(scope1: FetchElementScope, scope2: FetchElementScope): Promise<FetchElementScope | null>;
+    actionIndex?: number;
+}
+/**
+ * Context provided to the Fetch Engine during navigation and request handling.
+ *
+ * @remarks
+ * This interface contains the minimum set of properties required by an engine
+ * to perform a fetch operation and build a response.
+ */
+interface FetchEngineContext extends BaseFetcherProperties {
     /**
-     * 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.
+     * Unique identifier for the session or request batch.
      */
-    _findContainerChild(element: FetchElementScope, container: FetchElementScope): Promise<FetchElementScope | null>;
+    id: string;
     /**
-     * Logs debug information if debug mode is enabled.
-     * @param category - The category of the log message.
-     * @param args - Arguments to log.
+     * The target URL for the next navigation, if specified.
      */
-    _logDebug(category: string, ...args: any[]): void;
-}
-/**
- * Base configuration for all extraction schemas.
- */
-interface BaseExtractSchema {
+    url?: string;
     /**
-     * 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).
+     * The final URL after all redirects have been followed.
      */
-    required?: boolean;
+    finalUrl?: string;
     /**
-     * Whether to enable strict mode for this extraction.
-     * If true, missing required fields will throw an error instead of being skipped.
+     * The standardized response object from the most recent navigation.
      */
-    strict?: boolean;
+    lastResponse?: FetchResponse;
     /**
-     * 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.
+     * The result object from the most recent action execution.
      */
-    anchor?: string;
+    lastResult?: FetchActionResult;
     /**
-     * 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.
+     * Engine-specific internal state.
      */
-    depth?: number;
+    internal: BaseFetchContextInteralState;
 }
 /**
- * Extraction schema types.
- */
-type ExtractSchema = ExtractObjectSchema | ExtractArraySchema | ExtractValueSchema;
-/**
- * Configuration for extracting a single value.
+ * The full execution context for a Web Fetcher session or action batch.
+ *
+ * @remarks
+ * This object is the central state container for the fetch operation. It provides
+ * access to configuration, the event bus, shared outputs, and the execution engine.
+ * It is passed to every action during execution.
  */
-interface ExtractValueSchema extends BaseExtractSchema {
+interface FetchContext extends FetchEngineContext {
     /**
-     * The data type to cast the extracted value to.
-     * @default 'string'
+     * Metadata about the action currently being executed.
      */
-    type?: 'string' | 'number' | 'boolean' | 'html';
+    currentAction?: FetchActionInContext;
     /**
-     * Extraction behavior mode.
-     * - 'text': (Default) Uses textContent.
-     * - 'innerText': Uses rendered text (respects CSS line breaks).
-     * - 'html': Returns innerHTML.
-     * - 'outerHTML': Returns HTML including the element's tag.
+     * A shared key-value store for storing data extracted from pages or
+     * metadata generated during action execution.
      */
-    mode?: 'text' | 'innerText' | 'html' | 'outerHTML';
+    outputs: Record<string, any>;
     /**
-     * CSS selector to locate the element within the current context.
+     * Executes a FetchAction within the current context.
+     *
+     * @param actionOptions - Configuration for the action to be executed.
+     * @returns A promise that resolves to the action's result.
      */
-    selector?: string;
+    execute<R extends FetchReturnType = 'any'>(actionOptions: FetchActionOptions): Promise<FetchActionResult<R>>;
     /**
-     * Attribute name to extract (e.g., 'href', 'src').
-     * If omitted, the text content or HTML is extracted based on `type`.
+     * Convenience method to execute an action by its registered name or ID.
+     *
+     * @param name - The registered name or ID of the action.
+     * @param params - Parameters specific to the action type.
+     * @param options - Additional execution options (e.g., storeAs, failOnError).
+     * @returns A promise that resolves to a result.
      */
-    attribute?: string;
+    action<R extends FetchReturnType = 'any'>(name: string, params?: any, options?: Partial<FetchActionOptions>): Promise<FetchActionResult<R>>;
     /**
-     * Filter elements that contain a descendant matching this CSS selector.
+     * Internal state for engine and lifecycle management.
      */
-    has?: string;
+    internal: FetchContextInteralState;
     /**
-     * Exclude elements matching this CSS selector.
+     * The central event bus for publishing and subscribing to session and action events.
      */
-    exclude?: string;
+    eventBus: EventEmitter;
 }
-/**
- * Names of the supported array extraction modes.
- */
-type ExtractArrayModeName = 'nested' | 'columnar' | 'segmented';
-/**
- * Base options for array extraction modes.
- */
-interface BaseModeOptions {
-    type: ExtractArrayModeName;
-    /**
-     * 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.
-     * @default false
-     */
-    inference?: boolean;
+
+type FetchReturnType = 'response' | 'context' | 'outputs' | 'any' | 'none';
+interface FetchReturnTypeRegistry {
+    response: FetchResponse;
+    context: FetchContext;
+    result: FetchActionResult<any> | undefined;
+    outputs: Record<string, any>;
+    any: any;
+    none: void;
 }
-/**
- * Options for segmented (anchor-based) extraction.
- */
-interface SegmentedOptions extends BaseModeOptions {
-    type: 'segmented';
+type FetchReturnTypeFor<R extends FetchReturnType> = R extends keyof FetchReturnTypeRegistry ? FetchReturnTypeRegistry[R] : never;
+
+declare enum FetchActionResultStatus {
     /**
-     * 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`.
+     * 动作执行失败但未抛出（通常因 failOnError=false）；错误信息在 error 字段
      */
-    anchor?: string;
+    Failed = 0,
     /**
-     * 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.
+     * 动作按预期完成（即便产生 warnings）
      */
-    relativeTo?: 'anchor' | 'previous';
+    Success = 1,
     /**
-     * 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.
+     * 动作被判定为不执行/降级为 noop（比如引擎不支持且 degradeTo='noop'）
+     * 能力不支持且 degradeTo='noop' 时：status='skipped'，warnings 增加 { code:'capability-not-supported' }
      */
-    depth?: number;
+    Skipped = 2
 }
-/**
- * Union type for array extraction modes and their options.
- */
-type ExtractArrayMode = ExtractArrayModeName | ColumnarOptions | SegmentedOptions;
-/**
- * Configuration for extracting an array of items.
- */
-interface ExtractArraySchema extends BaseExtractSchema {
-    type: 'array';
-    /**
-     * CSS selector for items (in 'nested' mode) or the container (in 'columnar'/'segmented' modes).
-     */
-    selector: string;
-    /**
-     * Filter items/containers that contain a descendant matching this CSS selector.
-     */
-    has?: string;
-    /**
-     * Exclude items/containers matching this CSS selector.
-     */
-    exclude?: string;
-    /**
-     * Schema applied recursively to each extracted item.
-     * If omitted, defaults to extracting text.
-     */
-    items?: ExtractSchema;
-    /**
-     * Shortcut for `items` to extract a specific attribute directly.
-     */
-    attribute?: string;
-    /**
-     * Array extraction mode.
-     * - 'nested': (Default) Items are elements matched by `selector`.
-     * - 'columnar': `selector` is a container, fields in `items` are parallel columns aligned by index.
-     * - 'segmented': `selector` is a container, items are segmented by an anchor field.
-     */
-    mode?: ExtractArrayMode;
+type FetchActionCapabilityMode = 'native' | 'simulate' | 'noop';
+interface FetchActionMeta {
+    id: string;
+    index?: number;
+    engineType?: FetchEngineType;
+    capability?: FetchActionCapabilityMode;
+    response?: FetchResponse;
+    timings?: {
+        start: number;
+        total: number;
+    };
+    retries?: number;
+}
+interface FetchActionResult<R extends FetchReturnType = FetchReturnType> {
+    status: FetchActionResultStatus;
+    returnType?: R;
+    result?: FetchReturnTypeFor<R>;
+    error?: Error;
+    meta?: FetchActionMeta;
+}
+interface BaseFetchActionProperties {
+    id?: string;
+    name?: string;
+    action?: string | any;
+    index?: number;
+    params?: any;
+    args?: any;
+    storeAs?: string;
+    failOnError?: boolean;
+    failOnTimeout?: boolean;
+    timeoutMs?: number;
+    maxRetries?: number;
+    [key: string]: any;
+}
+type BaseFetchActionOptions = RequireAtLeastOne<BaseFetchActionProperties, 'id' | 'name' | 'action'>;
+interface BaseFetchCollectorActionProperties extends BaseFetchActionProperties {
+    activateOn?: string | RegExp | Array<string | RegExp>;
+    deactivateOn?: string | RegExp | Array<string | RegExp>;
+    collectOn?: string | RegExp | Array<string | RegExp>;
+    background?: boolean;
+}
+type BaseFetchCollectorOptions = RequireAtLeastOne<BaseFetchCollectorActionProperties, 'id' | 'name' | 'action'>;
+interface FetchActionProperties extends BaseFetchActionProperties {
+    collectors?: BaseFetchCollectorOptions[];
+}
+type FetchActionOptions = RequireAtLeastOne<FetchActionProperties, 'id' | 'name' | 'action'>;
+declare class EngineUpgradeError extends Error {
+    res: FetchResponse;
+    code: string;
+    constructor(res: FetchResponse);
 }
+type FetchEngineType = 'http' | 'browser';
+type BrowserEngine = 'playwright' | 'puppeteer';
+type FetchEngineMode = FetchEngineType | 'auto' | string;
+type ResourceType = 'image' | 'stylesheet' | 'font' | 'script' | 'media' | string;
 /**
- * Configuration for extracting an object with multiple properties.
+ * Storage configuration options for the fetch engine.
+ *
+ * @remarks
+ * Controls how Crawlee's internal storage (RequestQueue, KeyValueStore, SessionPool) is managed.
  */
-interface ExtractObjectSchema extends BaseExtractSchema {
-    type: 'object';
+interface StorageOptions {
     /**
-     * Root selector for the object. If provided, sub-properties are searched within this element.
+     * Custom identifier for the storage.
+     * If provided, multiple sessions can share the same storage by using the same ID.
+     * If not provided, a unique session ID is used (strong isolation).
      */
-    selector?: string;
+    id?: string;
     /**
-     * Filter the object element based on descendants.
+     * Whether to persist storage to disk.
+     * If true, uses Crawlee's disk persistence. If false, data might be stored in memory or temporary directory.
+     * Corresponds to Crawlee's `persistStorage` configuration.
      */
-    has?: string;
+    persist?: boolean;
     /**
-     * Exclude the object element if it matches this selector.
+     * Whether to delete the storage (RequestQueue and KeyValueStore) when the session is closed.
+     * Defaults to true. Set to false if you want to keep data for future reuse with the same `id`.
      */
-    exclude?: string;
+    purge?: boolean;
     /**
-     * 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.
+     * Additional Crawlee configuration options.
+     * Allows fine-grained control over the underlying Crawlee instance.
      */
-    relativeTo?: 'anchor' | 'previous';
+    config?: Record<string, any>;
+}
+interface BaseFetcherProperties {
     /**
-     * Explicit order of property extraction.
-     * Useful when using `relativeTo: 'previous'`.
+     * 抓取模式
+     *
+     * - `http`: 使用 HTTP 进行抓取
+     * - `browser`: 使用浏览器进行抓取
+     * - `auto`: auto 会走“智能探测”选择 http 或 browser, 但是如果没有启用 smart，并且在站点注册表中没有，那么则等价为 http.
      */
-    order?: string[];
+    engine?: FetchEngineMode;
+    enableSmart?: boolean;
+    syncStateOnUpgrade?: boolean;
+    upgradeThresholdMs?: number;
+    useSiteRegistry?: boolean;
+    antibot?: boolean;
+    debug?: boolean | string | string[];
+    headers?: Record<string, string>;
+    cookies?: Cookie[];
+    sessionState?: any;
+    sessionPoolOptions?: SessionPoolOptions;
+    overrideSessionState?: boolean;
+    throwHttpErrors?: boolean;
+    output?: {
+        cookies?: boolean;
+        sessionState?: boolean;
+    };
+    proxy?: string | string[];
+    blockResources?: ResourceType[];
     /**
-     * Definition of the object's properties and their corresponding extraction schemas.
+     * Storage configuration for session isolation and persistence.
      */
-    properties: {
-        [key: string]: ExtractSchema;
+    storage?: StorageOptions;
+    ignoreSslErrors?: boolean;
+    browser?: {
+        /**
+         * 浏览器引擎，默认为 playwright
+         *
+         * - `playwright`: 使用 Playwright 引擎
+         * - `puppeteer`: 使用 Puppeteer 引擎
+         */
+        engine?: BrowserEngine;
+        headless?: boolean;
+        waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+        launchOptions?: Record<string, any>;
+    };
+    http?: {
+        method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        body?: any;
     };
-}
-
-interface PromiseLock extends Promise<void> {
-    release: () => void;
-}
-
-/**
- * Options for the {@link FetchEngine.goto}, allowing configuration of HTTP method, payload, headers, and navigation behavior.
- *
- * @remarks
- * Used when navigating to a URL to specify additional parameters beyond the basic URL.
- *
- * @example
- * ```ts
- * await engine.goto('https://example.com', {
- *   method: 'POST',
- *   payload: { username: 'user', password: 'pass' },
- *   headers: { 'Content-Type': 'application/json' },
- *   waitUntil: 'networkidle'
- * });
- * ```
- */
-interface GotoActionOptions {
-    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE' | 'OPTIONS' | 'CONNECT' | 'PATCH';
-    payload?: any;
-    headers?: Record<string, string>;
-    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
     timeoutMs?: number;
-    simulate?: boolean;
+    requestHandlerTimeoutSecs?: number;
+    maxConcurrency?: number;
+    maxRequestsPerMinute?: number;
+    delayBetweenRequestsMs?: number;
+    retries?: number;
+    sites?: FetchSite[];
+    url?: string;
 }
-/**
- * Options for the {@link FetchEngine.waitFor} action, specifying conditions to wait for before continuing.
- *
- * @remarks
- * Controls timing behavior for interactions, allowing waiting for elements, time intervals, or network conditions.
- */
-interface WaitForActionOptions {
-    ms?: number;
-    selector?: string;
-    networkIdle?: boolean;
-    failOnTimeout?: boolean;
+interface FetchSite extends BaseFetcherProperties {
+    domain: string;
+    pathScope?: string[];
+    meta?: {
+        updatedAt?: number;
+        ttlMs?: number;
+        source?: 'manual' | 'smart';
+    };
+}
+type OnFetchPauseCallback = (options: {
+    message?: string;
+}) => Promise<void>;
+interface FetcherOptions extends BaseFetcherProperties {
+    actions?: FetchActionOptions[];
+    onPause?: OnFetchPauseCallback;
+}
+interface FetchMetadata {
+    mode: FetchEngineType;
+    engine?: BrowserEngine;
+    timings?: {
+        start: number;
+        total: number;
+        ttfb?: number;
+        dns?: number;
+        tcp?: number;
+        firstByte?: number;
+        download?: number;
+    };
+    proxy?: string;
+    [key: string]: any;
+}
+interface FetchResponse {
+    url: string;
+    finalUrl: string;
+    statusCode?: number;
+    statusText?: string;
+    headers: Record<string, string>;
+    contentType?: string;
+    body?: string | Buffer<ArrayBufferLike>;
+    html?: string;
+    text?: string;
+    json?: any;
+    cookies?: Cookie[];
+    sessionState?: any;
+    metadata?: FetchMetadata;
 }
+declare const DefaultFetcherProperties: BaseFetcherProperties;
+declare const FetcherOptionKeys: string[];
+
 /**
- * Options for the {@link FetchEngine.submit} action, configuring form submission behavior.
+ * Represents a stateful web fetching session.
  *
  * @remarks
- * Specifies encoding type for form submissions, particularly relevant for JSON-based APIs.
- */
-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.
+ * A `FetchSession` manages the lifecycle of a single crawling operation, including engine initialization,
+ * cookie persistence, and sequential action execution. It maintains a `FetchContext` that stores
+ * session-level configurations and outputs.
+ *
+ * Sessions are isolated; each has its own unique ID and (by default) its own storage and cookies.
  */
-interface TrimActionOptions {
-    selectors?: string | string[];
-    presets?: TrimPreset | TrimPreset[];
+declare class FetchSession {
+    protected options: FetcherOptions;
+    /**
+     * Unique identifier for the session.
+     */
+    readonly id: string;
+    /**
+     * The execution context for this session, containing configurations, event bus, and shared state.
+     */
+    readonly context: FetchContext;
+    protected closed: boolean;
+    /**
+     * Creates a new 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.
+     *
+     * @param actionOptions - Configuration for the action to be executed.
+     * @param context - Optional context override for this specific execution. Defaults to the session context.
+     * @returns A promise that resolves to the result of the action.
+     * @template R - The expected return type of the action.
+     *
+     * @example
+     * ```ts
+     * await session.execute({ name: 'goto', params: { url: 'https://example.com' } });
+     * ```
+     */
+    execute<R extends FetchReturnType = 'response'>(actionOptions: FetchActionOptions, context?: FetchContext): Promise<FetchActionResult<R>>;
+    /**
+     * Executes a sequence of actions.
+     *
+     * @param actions - An array of action options to be executed in order.
+     * @param options - Optional temporary configuration overrides (e.g., timeoutMs, headers) for this batch of actions.
+     *                  These overrides do not affect the main session context.
+     * @returns A promise that resolves to an object containing the result of the last action and all accumulated outputs.
+     *
+     * @example
+     * ```ts
+     * const { result, outputs } = await session.executeAll([
+     *   { name: 'goto', params: { url: 'https://example.com' } },
+     *   { name: 'extract', params: { schema: { title: 'h1' } }, storeAs: 'data' }
+     * ], { timeoutMs: 30000 });
+     * ```
+     */
+    executeAll(actions: FetchActionOptions[], options?: Partial<FetcherOptions> & {
+        index?: number;
+    }): Promise<{
+        result: FetchResponse | undefined;
+        outputs: Record<string, any>;
+    }>;
+    /**
+     * Retrieves all outputs accumulated during the session.
+     *
+     * @returns A record of stored output data.
+     */
+    getOutputs(): Record<string, any>;
+    /**
+     * Gets the current state of the session, including cookies and engine-specific state.
+     *
+     * @returns A promise resolving to the session state, or undefined if no engine is initialized.
+     */
+    getState(): Promise<{
+        cookies: Cookie[];
+        sessionState?: any;
+    } | undefined>;
+    /**
+     * Disposes of the session and its associated engine.
+     *
+     * @remarks
+     * This method should be called when the session is no longer needed to free up resources
+     * (e.g., closing browser instances, purging temporary storage).
+     */
+    dispose(): Promise<void>;
+    private ensureEngine;
+    protected createContext(options?: FetcherOptions): FetchContext;
 }
-declare const TRIM_PRESETS: Record<string, string[]>;
+
 /**
- * Options for the {@link FetchEngine.evaluate} action, specifying the function to execute and its arguments.
+ * High-level entry point for the Web Fetcher library.
  *
  * @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]
- *   }
- * }
- * ```
+ * The `WebFetcher` provides a simplified API for fetching web content without manually managing sessions.
+ * It can be used for one-off requests or as a factory for more complex `FetchSession` instances.
  *
  * @example
- * ```json
- * {
- *   "action": "evaluate",
- *   "params": {
- *     "fn": "({ x, y }) => x * y",
- *     "args": { "x": 6, "y": 7 }
- *   }
- * }
+ * ```ts
+ * const fetcher = new WebFetcher();
+ * const { result } = await fetcher.fetch('https://example.com');
  * ```
  */
-interface EvaluateActionOptions {
+declare class WebFetcher {
+    private defaults;
     /**
-     * The function or expression to execute.
+     * Creates a new WebFetcher with default options.
      *
-     * @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"`
+     * @param defaults - Default configuration options applied to all sessions and requests.
+     */
+    constructor(defaults?: FetcherOptions);
+    /**
+     * Creates a new FetchSession.
      *
-     * **Note:** When using a function, it receives exactly ONE argument: the value provided in {@link args}.
-     * Use destructuring to handle multiple parameters.
+     * @param options - Configuration options for the session, merged with defaults.
+     * @returns A promise resolving to a new FetchSession instance.
      */
-    fn: string | ((...args: any[]) => any);
+    createSession(options?: FetcherOptions): Promise<FetchSession>;
     /**
-     * Data to pass to the function.
+     * Fetches content from a URL or executes a complex action script.
      *
      * @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.
+     * This method automatically creates a session, executes the specified actions,
+     * retrieves the content, and disposes of the session.
+     *
+     * @param url - The target URL or a complete FetcherOptions object.
+     * @param options - Additional options when the first parameter is a URL string.
+     * @returns A promise resolving to the final response and any extracted outputs.
      */
-    args?: any;
+    fetch(url: string, options?: FetcherOptions): Promise<{
+        result: FetchResponse | undefined;
+        outputs: Record<string, any>;
+    }>;
+    fetch(options: FetcherOptions): Promise<{
+        result: FetchResponse | undefined;
+        outputs: Record<string, any>;
+    }>;
 }
+
 /**
- * Union type representing all possible engine actions that can be dispatched.
+ * 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
- * Defines the command structure processed during page interactions. Each action type corresponds to
- * a specific user interaction or navigation command within the action loop architecture.
+ * 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.
  */
-type FetchEngineAction = {
-    type: 'click';
-    selector: string;
-} | {
-    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;
-        steps?: number;
-    };
-} | {
-    type: 'mouseWheel';
-    params: {
-        x?: number;
-        y?: number;
-        selector?: string;
-        deltaX?: number;
-        deltaY?: number;
-        steps?: number;
-    };
-} | {
-    type: 'keyboardType';
-    params: {
-        text: string;
-        delay?: number;
-    };
-} | {
-    type: 'keyboardPress';
-    params: {
-        key: string;
-        delay?: number;
-    };
-} | {
-    type: 'scrollIntoView';
-    params: {
-        selector: string;
-    };
-} | {
-    type: 'waitFor';
-    options?: WaitForActionOptions;
-} | {
-    type: 'submit';
-    selector?: any;
-    options?: SubmitActionOptions;
-} | {
-    type: 'getContent';
-} | {
-    type: 'navigate';
-    url: string;
-    opts?: GotoActionOptions;
-} | {
-    type: 'extract';
-    schema: ExtractSchema;
-} | {
-    type: 'pause';
-    message?: string;
-} | {
-    type: 'trim';
-    options: TrimActionOptions;
-} | {
-    type: 'evaluate';
-    params: EvaluateActionOptions;
-} | {
-    type: 'dispose';
-};
-/**
- * Represents an action that has been dispatched and is awaiting execution in the active page context.
- *
- * @remarks
- * Connects the action request with its resolution mechanism. Used internally by the action dispatch system
- * to handle promises while maintaining the page context validity window.
- */
-interface DispatchedEngineAction {
-    action: FetchEngineAction;
-    resolve: (value?: any) => void;
-    reject: (reason?: any) => void;
-}
-/**
- * Represents a pending navigation request awaiting resolution.
- *
- * @remarks
- * Tracks navigation requests that have been queued but not yet processed by the request handler.
- */
-interface PendingEngineRequest {
-    resolve: (value: any) => void;
-    reject: (reason?: any) => void;
-}
-/**
- * Abstract base class for all fetch engines, providing a unified interface for web content fetching and interaction.
- *
- * @remarks
- * The `FetchEngine` class serves as the foundation for concrete engine implementations (e.g., `CheerioFetchEngine`,
- * `PlaywrightFetchEngine`). It abstracts underlying crawling technology and provides a consistent API for navigation,
- * content retrieval, and user interaction.
- *
- * The engine architecture uses an event-driven action loop to bridge Crawlee's stateless request handling with
- * the need for a stateful, sequential API for page interactions. This solves the critical challenge of maintaining
- * page context validity across asynchronous operations.
- *
- * @example
- * ```ts
- * import "./playwright"; // 引入注册 Playwright browser 引擎
- * const engine = await FetchEngine.create(context, { engine: 'browser' });
- * await engine.goto('https://example.com');
- * await engine.fill('#username', 'user');
- * await engine.click('#submit');
- * const response = await engine.getContent();
- * ```
- */
-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> implements IExtractEngine {
-    private static registry;
+interface IExtractEngine {
     /**
-     * Registers a fetch engine implementation with the global registry.
+     * Finds all elements matching the selector within the given scope.
      *
-     * @param engineClass - The engine class to register
-     * @throws {Error} When engine class lacks static `id` or ID is already registered
+     * @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.
      *
-     * @example
-     * ```ts
-     * FetchEngine.register(CheerioFetchEngine);
-     * ```
+     * @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.
      */
-    static register(engineClass: AnyFetchEngineCtor): void;
+    _querySelectorAll(scope: FetchElementScope, selector: string): Promise<FetchElementScope[]>;
     /**
-     * Retrieves a fetch engine implementation by its unique ID.
+     * Extracts a primitive value from the element based on the schema configuration.
      *
-     * @param id - The ID of the engine to retrieve
-     * @returns Engine class if found, otherwise `undefined`
+     * @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).
      */
-    static get(id: string): AnyFetchEngineCtor | undefined;
+    _extractValue(schema: ExtractValueSchema, scope: FetchElementScope): Promise<any>;
     /**
-     * Retrieves a fetch engine implementation by execution mode.
+     * Gets the parent element of the given scope.
      *
-     * @param mode - Execution mode (`'http'` or `'browser'`)
-     * @returns Engine class if found, otherwise `undefined`
+     * @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.
      */
-    static getByMode(mode: FetchEngineType): AnyFetchEngineCtor | undefined;
+    _parentElement(scope: FetchElementScope): Promise<FetchElementScope | null>;
     /**
-     * Factory method to create and initialize a fetch engine instance.
+     * Checks if two element scopes refer to the exact same DOM node.
      *
-     * @param ctx - Fetch engine context
-     * @param options - Configuration options
-     * @returns Initialized fetch engine instance
-     * @throws {Error} When no suitable engine implementation is found
+     * @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
-     * Primary entry point for engine creation. Selects appropriate implementation based on `engine` name of the option or context.
+     * This comparison MUST be identity-based, not just content-based.
      */
-    static create(ctx: FetchEngineContext, options?: BaseFetcherProperties): Promise<AnyFetchEngine | undefined>;
+    _isSameElement(scope1: FetchElementScope, scope2: FetchElementScope): Promise<boolean>;
     /**
-     * Unique identifier for the engine implementation.
+     * 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
-     * Must be defined by concrete implementations. Used for registration and lookup in engine registry.
+     * **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.
      */
-    static readonly id: string;
+    _nextSiblingsUntil(scope: FetchElementScope, untilSelector?: string): Promise<FetchElementScope[]>;
     /**
-     * Execution mode of the engine (`'http'` or `'browser'`).
+     * 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
-     * Must be defined by concrete implementations. Indicates whether engine operates at HTTP level or uses full browser.
-     */
-    static readonly mode: FetchEngineType;
-    protected ctx?: FetchEngineContext;
-    protected opts?: BaseFetcherProperties;
-    protected crawler?: TCrawler;
-    protected isCrawlerReady?: boolean;
-    protected crawlerRunPromise?: Promise<FinalStatistics>;
-    protected config?: Configuration;
-    protected requestQueue?: RequestQueue;
-    protected kvStore?: KeyValueStore;
-    protected proxyConfiguration?: ProxyConfiguration;
-    protected hdrs: Record<string, string>;
-    protected _initialCookies?: Cookie[];
-    protected _initializedSessions: Set<string>;
-    protected currentSession?: Session;
-    protected pendingRequests: Map<string, PendingEngineRequest>;
-    protected requestCounter: number;
-    protected actionEmitter: EventEmitter;
-    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 scope.
+     * **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?"
      *
-     * @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
+     * **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.
      */
-    abstract _querySelectorAll(scope: FetchElementScope, selector: string): Promise<FetchElementScope[]>;
+    _findClosestAncestor(scope: FetchElementScope, candidates: FetchElementScope[]): Promise<FetchElementScope | null>;
     /**
-     * Extracts a primitive value from the element based on schema.
+     * Checks if the `container` element contains the `element` (descendant).
      *
-     * @param schema - Value extraction schema.
-     * @param scope - The element scope.
-     * @returns Extracted value.
-     * @see {@link IExtractEngine._extractValue} for behavior contract.
-     * @internal
-     */
-    abstract _extractValue(schema: ExtractValueSchema, scope: FetchElementScope): Promise<any>;
-    /**
-     * Gets the parent element of the given element.
+     * @param container - The potential ancestor element.
+     * @param element - The potential descendant element.
+     * @returns A promise resolving to `true` if `container` contains `element`, `false` otherwise.
      *
-     * @param scope - The element scope.
-     * @returns Parent element or null.
-     * @internal
+     * @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()`.
      */
-    abstract _parentElement(scope: FetchElementScope): Promise<FetchElementScope | null>;
+    _contains(container: FetchElementScope, element: FetchElementScope): Promise<boolean>;
     /**
-     * Checks if two elements are the same identity.
+     * Finds the Lowest Common Ancestor (LCA) of two element scopes.
      *
-     * @param scope1 - First element scope.
-     * @param scope2 - Second element scope.
-     * @returns True if they are the same DOM node.
-     * @internal
+     * @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.
      */
-    abstract _isSameElement(scope1: FetchElementScope, scope2: FetchElementScope): Promise<boolean>;
+    _findCommonAncestor(scope1: FetchElementScope, scope2: FetchElementScope): Promise<FetchElementScope | null>;
     /**
-     * Gets all subsequent siblings of an element until a sibling matches the selector.
-     * Used in 'segmented' extraction mode.
+     * Finds the direct child of the `container` that contains the `element` (or is the `element` itself).
      *
-     * @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
+     * @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.
      */
-    abstract _nextSiblingsUntil(scope: FetchElementScope, untilSelector?: string): Promise<FetchElementScope[]>;
+    _findContainerChild(element: FetchElementScope, container: FetchElementScope): Promise<FetchElementScope | null>;
     /**
-     * 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
+     * Logs debug information if debug mode is enabled.
+     * @param category - The category of the log message.
+     * @param args - Arguments to log.
      */
-    abstract _findClosestAncestor(scope: FetchElementScope, candidates: FetchElementScope[]): Promise<FetchElementScope | null>;
+    _logDebug(category: string, ...args: any[]): void;
+}
+/**
+ * Base configuration for all extraction schemas.
+ */
+interface BaseExtractSchema {
     /**
-     * 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
+     * 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).
      */
-    abstract _contains(container: FetchElementScope, element: FetchElementScope): Promise<boolean>;
+    required?: 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
+     * Whether to enable strict mode for this extraction.
+     * If true, missing required fields will throw an error instead of being skipped.
      */
-    abstract _findCommonAncestor(scope1: FetchElementScope, scope2: FetchElementScope): Promise<FetchElementScope | null>;
+    strict?: boolean;
     /**
-     * Finds the direct child of container that contains element.
+     * 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.
      *
-     * @param element - The descendant element.
-     * @param container - The container element.
-     * @returns The child element of container, or null.
-     * @internal
+     * Once anchored, the search scope for this field becomes the siblings following the anchor.
      */
-    abstract _findContainerChild(element: FetchElementScope, container: FetchElementScope): Promise<FetchElementScope | null>;
-    protected _extract(schema: ExtractSchema, scope: FetchElementScope, parentStrict?: boolean): Promise<any>;
+    anchor?: string;
     /**
-     * Normalizes the array extraction mode into an options object.
-     * @param mode - The mode string or options object.
-     * @internal
+     * 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.
      */
-    protected _normalizeArrayMode(mode?: ExtractArrayMode): {
-        type: ExtractArrayModeName;
-    } & any;
+    depth?: number;
+}
+/**
+ * Extraction schema types.
+ */
+type ExtractSchema = ExtractObjectSchema | ExtractArraySchema | ExtractValueSchema;
+/**
+ * Configuration for extracting a single value.
+ */
+interface ExtractValueSchema extends BaseExtractSchema {
     /**
-     * Performs standard nested array extraction.
-     * @param items - The schema for each item.
-     * @param elements - The list of item elements.
-     * @internal
+     * The data type to cast the extracted value to.
+     * @default 'string'
      */
-    protected _extractNested(items: ExtractSchema, elements: FetchElementScope[], opts?: {
-        strict?: boolean;
-    }): Promise<any[]>;
+    type?: 'string' | 'number' | 'boolean' | 'html';
     /**
-     * Performs columnar extraction (Column Alignment Mode).
-     *
-     * @param schema - The schema for a single item (must be an object or implicit object).
-     * @param container - The container element to search within.
-     * @param opts - Columnar extraction options (strict, inference).
-     * @returns An array of extracted items, or null if requirements aren't met.
-     * @internal
+     * Extraction behavior mode.
+     * - 'text': (Default) Uses textContent.
+     * - 'innerText': Uses rendered text (respects CSS line breaks).
+     * - 'html': Returns innerHTML.
+     * - 'outerHTML': Returns HTML including the element's tag.
      */
-    protected _extractColumnar(schema: ExtractSchema, container: FetchElementScope, opts?: ColumnarOptions): Promise<any[] | null>;
+    mode?: 'text' | 'innerText' | 'html' | 'outerHTML';
     /**
-     * Performs segmented extraction (Anchor-based Scanning).
-     *
-     * @param schema - The schema for a single item (must be an object).
-     * @param container - The container element to scan.
-     * @param opts - Segmented extraction options (anchor).
-     * @returns An array of extracted items.
-     * @internal
+     * CSS selector to locate the element within the current context.
      */
-    protected _extractSegmented(schema: ExtractSchema, container: FetchElementScope, opts?: SegmentedOptions): Promise<any[] | null>;
+    selector?: string;
     /**
-     * Creates the crawler instance for the specific engine implementation.
-     * @param options - The final crawler options.
-     * @internal
+     * Attribute name to extract (e.g., 'href', 'src').
+     * If omitted, the text content or HTML is extracted based on `type`.
      */
-    protected abstract _createCrawler(options: TOptions, config?: Configuration): TCrawler;
+    attribute?: string;
     /**
-     * Gets the crawler-specific options from the subclass.
-     * @param ctx - The fetch engine context.
-     * @internal
+     * Filter elements that contain a descendant matching this CSS selector.
      */
-    protected abstract _getSpecificCrawlerOptions(ctx: FetchEngineContext): Promise<Partial<TOptions>> | Partial<TOptions>;
+    has?: string;
     /**
-     * Abstract method for building standard [FetchResponse] from Crawlee context.
-     *
-     * @param context - Crawlee crawling context
-     * @returns Promise resolving to [FetchResponse] object
-     *
-     * @remarks
-     * Converts implementation-specific context (Playwright `page` or Cheerio `$`) to standardized response.
-     * @internal
+     * Exclude elements matching this CSS selector.
      */
-    protected abstract _buildResponse(context: TContext): Promise<FetchResponse>;
-    protected buildResponse(context: TContext): Promise<FetchResponse>;
+    exclude?: string;
+}
+/**
+ * Names of the supported array extraction modes.
+ */
+type ExtractArrayModeName = 'nested' | 'columnar' | 'segmented';
+/**
+ * Base options for array extraction modes.
+ */
+interface BaseModeOptions {
+    type: ExtractArrayModeName;
     /**
-     * Abstract method for executing action within current page context.
-     *
-     * @param context - Crawlee crawling context
-     * @param action - Action to execute
-     * @returns Promise resolving to action result
-     *
-     * @remarks
-     * Handles specific user interactions using underlying technology (Playwright/Cheerio).
-     * @internal
+     * Whether to enable strict mode for this specific array mode.
+     * @default false
      */
-    protected abstract executeAction(context: TContext, action: FetchEngineAction): Promise<any>;
+    strict?: boolean;
+}
+/**
+ * Options for columnar (column-alignment) extraction.
+ */
+interface ColumnarOptions extends BaseModeOptions {
+    type: 'columnar';
     /**
-     * Navigates to the specified URL.
-     *
-     * @param url - Target URL
-     * @param params - Navigation options
-     * @returns Promise resolving when navigation completes
-     *
-     * @example
-     * ```ts
-     * await engine.goto('https://example.com');
-     * ```
+     * Whether to enable heuristic inference.
+     * If true, tries to find a common parent to infer item wrappers when counts mismatch.
+     * @default false
      */
-    abstract goto(url: string, params?: GotoActionOptions): Promise<void | FetchResponse>;
+    inference?: boolean;
+}
+/**
+ * Options for segmented (anchor-based) extraction.
+ */
+interface SegmentedOptions extends BaseModeOptions {
+    type: 'segmented';
     /**
-     * Waits for specified condition before continuing.
-     *
-     * @param params - Wait conditions
-     * @returns Promise resolving when wait condition is met
-     *
-     * @example
-     * ```ts
-     * await engine.waitFor({ ms: 1000 }); // Wait 1 second
-     * await engine.waitFor({ selector: '#content' }); // Wait for element
-     * ```
+     * 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`.
      */
-    waitFor(params?: WaitForActionOptions): Promise<void>;
+    anchor?: string;
     /**
-     * Clicks on element matching selector.
-     *
-     * @param selector - CSS selector of element to click
-     * @returns Promise resolving when click is processed
-     * @throws {Error} When no active page context exists
+     * 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.
      */
-    click(selector: string): Promise<void>;
+    relativeTo?: 'anchor' | 'previous';
     /**
-     * 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)
+     * 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.
      */
-    mouseClick(params: {
-        x?: number;
-        y?: number;
-        button?: 'left' | 'right' | 'middle';
-        clickCount?: number;
-        delay?: number;
-    }): Promise<void>;
+    depth?: number;
+}
+/**
+ * Union type for array extraction modes and their options.
+ */
+type ExtractArrayMode = ExtractArrayModeName | ColumnarOptions | SegmentedOptions;
+/**
+ * Configuration for extracting an array of items.
+ */
+interface ExtractArraySchema extends BaseExtractSchema {
+    type: 'array';
     /**
-     * Scrolls the mouse wheel.
-     *
-     * @param params - Wheel parameters (x, y, selector, deltaX, deltaY, steps)
+     * CSS selector for items (in 'nested' mode) or the container (in 'columnar'/'segmented' modes).
      */
-    mouseWheel(params: {
-        x?: number;
-        y?: number;
-        selector?: string;
-        deltaX?: number;
-        deltaY?: number;
-        steps?: number;
-    }): Promise<void>;
+    selector: string;
     /**
-     * Scrolls the element into view.
-     *
-     * @param params - Scroll parameters (selector)
+     * Filter items/containers that contain a descendant matching this CSS selector.
      */
-    scrollIntoView(params: {
-        selector: string;
-    }): Promise<void>;
+    has?: string;
     /**
-     * Types text into current focused element.
-     *
-     * @param text - Text to type
-     * @param delay - Delay between key presses
+     * Exclude items/containers matching this CSS selector.
      */
-    keyboardType(text: string, delay?: number): Promise<void>;
+    exclude?: string;
     /**
-     * Presses specified key.
-     *
-     * @param key - Key to press
-     * @param delay - Delay after key press
+     * Schema applied recursively to each extracted item.
+     * If omitted, defaults to extracting text.
      */
-    keyboardPress(key: string, delay?: number): Promise<void>;
+    items?: ExtractSchema;
     /**
-     * Fills input element with specified value.
-     *
-     * @param selector - CSS selector of input element
-     * @param value - Value to fill
-     * @returns Promise resolving when fill operation completes
-     * @throws {Error} When no active page context exists
+     * Shortcut for `items` to extract a specific attribute directly.
      */
-    fill(selector: string, value: string): Promise<void>;
+    attribute?: string;
     /**
-     * Submits a form.
-     *
-     * @param selector - Optional form/submit button selector
-     * @param options - Submission options
-     * @returns Promise resolving when form is submitted
-     * @throws {Error} When no active page context exists
+     * Array extraction mode.
+     * - 'nested': (Default) Items are elements matched by `selector`.
+     * - 'columnar': `selector` is a container, fields in `items` are parallel columns aligned by index.
+     * - 'segmented': `selector` is a container, items are segmented by an anchor field.
      */
-    submit(selector?: any, options?: SubmitActionOptions): Promise<void>;
+    mode?: ExtractArrayMode;
+}
+/**
+ * Configuration for extracting an object with multiple properties.
+ */
+interface ExtractObjectSchema extends BaseExtractSchema {
+    type: 'object';
     /**
-     * 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
+     * Root selector for the object. If provided, sub-properties are searched within this element.
      */
-    trim(options: TrimActionOptions): Promise<void>;
+    selector?: string;
     /**
-     * Pauses execution, allowing for manual intervention or inspection.
-     *
-     * @param message - Optional message to display during pause
-     * @returns Promise resolving when execution is resumed
-     * @throws {Error} When no active page context exists
+     * Filter the object element based on descendants.
      */
-    pause(message?: string): Promise<void>;
+    has?: string;
     /**
-     * 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.
+     * Exclude the object element if it matches this selector.
      */
-    evaluate(params: EvaluateActionOptions): Promise<any>;
+    exclude?: string;
     /**
-     * Extracts structured data from the current page content.
-     *
-     * @param schema - An object defining the data to extract.
-     * @returns A promise that resolves to an object with the extracted data.
+     * 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.
      */
-    extract<T>(schema: ExtractSchema): Promise<T>;
+    relativeTo?: 'anchor' | 'previous';
     /**
-     * Gets the unique identifier of this engine implementation.
+     * Explicit order of property extraction.
+     * Useful when using `relativeTo: 'previous'`.
      */
-    get id(): string;
+    order?: string[];
     /**
-     * Returns the current state of the engine (cookies)
-     * that can be used to restore the session later.
+     * Definition of the object's properties and their corresponding extraction schemas.
      */
-    getState(): Promise<{
-        cookies: Cookie[];
-        sessionState?: any;
-    }>;
+    properties: {
+        [key: string]: ExtractSchema;
+    };
+}
+
+interface PromiseLock extends Promise<void> {
+    release: () => void;
+}
+
+/**
+ * Options for the {@link FetchEngine.goto}, allowing configuration of HTTP method, payload, headers, and navigation behavior.
+ *
+ * @remarks
+ * Used when navigating to a URL to specify additional parameters beyond the basic URL.
+ *
+ * @example
+ * ```ts
+ * await engine.goto('https://example.com', {
+ *   method: 'POST',
+ *   payload: { username: 'user', password: 'pass' },
+ *   headers: { 'Content-Type': 'application/json' },
+ *   waitUntil: 'networkidle'
+ * });
+ * ```
+ */
+interface GotoActionOptions {
+    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE' | 'OPTIONS' | 'CONNECT' | 'PATCH';
+    payload?: any;
+    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.
+ *
+ * @remarks
+ * Controls timing behavior for interactions, allowing waiting for elements, time intervals, or network conditions.
+ */
+interface WaitForActionOptions {
+    ms?: number;
+    selector?: string;
+    networkIdle?: boolean;
+    failOnTimeout?: boolean;
+}
+/**
+ * Options for the {@link FetchEngine.submit} action, configuring form submission behavior.
+ *
+ * @remarks
+ * Specifies encoding type for form submissions, particularly relevant for JSON-based APIs.
+ */
+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 {
     /**
-     * Gets the execution mode of this engine (`'http'` or `'browser'`).
-     */
-    get mode(): FetchEngineType;
-    /**
-     * Gets the fetch engine context associated with this instance.
+     * 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.
      */
-    get context(): FetchEngineContext | undefined;
+    fn: string | ((...args: any[]) => any);
     /**
-     * Initializes the fetch engine with provided context and options.
-     *
-     * @param context - Fetch engine context
-     * @param options - Configuration options
-     * @returns Promise resolving when initialization completes
+     * Data to pass to the function.
      *
      * @remarks
-     * Sets up internal state and calls implementation-specific [_initialize](file:///home/riceball/Documents/mywork/public/@isdk/ai-tools/packages/web-fetcher/src/engine/cheerio.ts#L169-L204) method.
-     * Automatically called when creating engine via `FetchEngine.create()`.
+     * 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.
      */
-    initialize(context: FetchEngineContext, options?: BaseFetcherProperties): Promise<void>;
-    cleanup(): Promise<void>;
+    args?: any;
+}
+/**
+ * Union type representing all possible engine actions that can be dispatched.
+ *
+ * @remarks
+ * Defines the command structure processed during page interactions. Each action type corresponds to
+ * a specific user interaction or navigation command within the action loop architecture.
+ */
+type FetchEngineAction = {
+    type: 'click';
+    selector: string;
+} | {
+    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;
+        steps?: number;
+    };
+} | {
+    type: 'mouseWheel';
+    params: {
+        x?: number;
+        y?: number;
+        selector?: string;
+        deltaX?: number;
+        deltaY?: number;
+        steps?: number;
+    };
+} | {
+    type: 'keyboardType';
+    params: {
+        text: string;
+        delay?: number;
+    };
+} | {
+    type: 'keyboardPress';
+    params: {
+        key: string;
+        delay?: number;
+    };
+} | {
+    type: 'scrollIntoView';
+    params: {
+        selector: string;
+    };
+} | {
+    type: 'waitFor';
+    options?: WaitForActionOptions;
+} | {
+    type: 'submit';
+    selector?: any;
+    options?: SubmitActionOptions;
+} | {
+    type: 'getContent';
+} | {
+    type: 'navigate';
+    url: string;
+    opts?: GotoActionOptions;
+} | {
+    type: 'extract';
+    schema: ExtractSchema;
+} | {
+    type: 'pause';
+    message?: string;
+} | {
+    type: 'trim';
+    options: TrimActionOptions;
+} | {
+    type: 'evaluate';
+    params: EvaluateActionOptions;
+} | {
+    type: 'dispose';
+};
+/**
+ * Represents an action that has been dispatched and is awaiting execution in the active page context.
+ *
+ * @remarks
+ * Connects the action request with its resolution mechanism. Used internally by the action dispatch system
+ * to handle promises while maintaining the page context validity window.
+ */
+interface DispatchedEngineAction {
+    action: FetchEngineAction;
+    resolve: (value?: any) => void;
+    reject: (reason?: any) => void;
+}
+/**
+ * Represents a pending navigation request awaiting resolution.
+ *
+ * @remarks
+ * Tracks navigation requests that have been queued but not yet processed by the request handler.
+ */
+interface PendingEngineRequest {
+    resolve: (value: any) => void;
+    reject: (reason?: any) => void;
+}
+/**
+ * Abstract base class for all fetch engines, providing a unified interface for web content fetching and interaction.
+ *
+ * @remarks
+ * The `FetchEngine` class serves as the foundation for concrete engine implementations (e.g., `CheerioFetchEngine`,
+ * `PlaywrightFetchEngine`). It abstracts underlying crawling technology and provides a consistent API for navigation,
+ * content retrieval, and user interaction.
+ *
+ * The engine architecture uses an event-driven action loop to bridge Crawlee's stateless request handling with
+ * the need for a stateful, sequential API for page interactions. This solves the critical challenge of maintaining
+ * page context validity across asynchronous operations.
+ *
+ * @example
+ * ```ts
+ * import "./playwright"; // 引入注册 Playwright browser 引擎
+ * const engine = await FetchEngine.create(context, { engine: 'browser' });
+ * await engine.goto('https://example.com');
+ * await engine.fill('#username', 'user');
+ * await engine.click('#submit');
+ * const response = await engine.getContent();
+ * ```
+ */
+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> implements IExtractEngine {
+    private static registry;
     /**
-     * Gets the initial scope for extraction for the specific engine.
-     * @param context - Crawlee crawling context
-     * @internal
+     * Registers a fetch engine implementation with the global registry.
+     *
+     * @param engineClass - The engine class to register
+     * @throws {Error} When engine class lacks static `id` or ID is already registered
+     *
+     * @example
+     * ```ts
+     * FetchEngine.register(CheerioFetchEngine);
+     * ```
      */
-    protected abstract _getInitialElementScope(context: TContext): FetchElementScope;
+    static register(engineClass: AnyFetchEngineCtor): void;
     /**
-     * Unified action processor that handles engine-agnostic actions.
-     * @param context - Crawlee crawling context
-     * @param action - Action to execute
-     * @internal
+     * Retrieves a fetch engine implementation by its unique ID.
+     *
+     * @param id - The ID of the engine to retrieve
+     * @returns Engine class if found, otherwise `undefined`
      */
-    protected _processAction(context: TContext, action: FetchEngineAction): Promise<any>;
-    protected _handlePause(action: {
-        message?: string;
-    }): Promise<void>;
+    static get(id: string): AnyFetchEngineCtor | undefined;
     /**
-     * Executes all pending fetch engine actions within the current Crawlee request handler context.
-     *
-     * **Critical Execution Constraint**: This method **MUST** be awaited within the synchronous execution path
-     * of Crawlee's [requestHandler](https://crawlee.dev/js/api/basic-crawler) (before any `await` that yields control back to the event loop).
-     *
-     * ### Why This Constraint Exists
-     * - Crawlee's page context ([PlaywrightCrawler](https://crawlee.dev/js/api/playwright-crawler)'s `page` or [CheerioCrawler](https://crawlee.dev/js/api/cheerio-crawler)'s `$`)
-     *   is **only valid during the synchronous execution phase** of the request handler
-     * - After any `await` (e.g., `await page.goto()`), the page context may be destroyed
-     *   due to Crawlee's internal resource management
-     *
-     * ### How It Works
-     * 1. Processes all actions queued via {@link dispatchAction} (click, fill, submit, etc.)
-     * 2. Maintains the page context validity window via {@link isPageActive} lifecycle flag
-     * 3. Automatically cleans up event listeners upon completion
+     * Retrieves a fetch engine implementation by execution mode.
      *
-     * Usage see {@link _sharedRequestHandler}
-     * @see {@link _sharedRequestHandler}
-     * @param context The active Crawlee crawling context containing the page/$ object
-     * @throws {Error} If called outside valid page context window (`!this.isPageActive`)
-     * @internal Engine infrastructure method - not for direct consumer use
+     * @param mode - Execution mode (`'http'` or `'browser'`)
+     * @returns Engine class if found, otherwise `undefined`
      */
-    protected _executePendingActions(context: TContext): Promise<void>;
-    protected _sharedRequestHandler(context: TContext): Promise<void>;
-    protected _sharedFailedRequestHandler(context: TContext, error?: Error): Promise<void>;
-    protected dispatchAction<T>(action: FetchEngineAction): Promise<T>;
-    private _requestHandler;
-    private _failedRequestHandler;
-    protected _commonCleanup(): Promise<void>;
+    static getByMode(mode: FetchEngineType): AnyFetchEngineCtor | undefined;
     /**
-     * Blocks specified resource types from loading.
+     * Factory method to create and initialize a fetch engine instance.
      *
-     * @param types - Resource types to block
-     * @param overwrite - Whether to replace existing blocked types
-     * @returns Number of blocked resource types
+     * @param ctx - Fetch engine context
+     * @param options - Configuration options
+     * @returns Initialized fetch engine instance
+     * @throws {Error} When no suitable engine implementation is found
      *
-     * @example
-     * ```ts
-     * await engine.blockResources(['image', 'stylesheet']);
-     * await engine.blockResources(['script'], true); // Replace existing
-     * ```
+     * @remarks
+     * Primary entry point for engine creation. Selects appropriate implementation based on `engine` name of the option or context.
      */
-    blockResources(types: ResourceType[], overwrite?: boolean): Promise<number>;
+    static create(ctx: FetchEngineContext, options?: BaseFetcherProperties): Promise<AnyFetchEngine | undefined>;
     /**
-     * Gets content of current page.
+     * Unique identifier for the engine implementation.
      *
-     * @returns Promise resolving to fetch response
-     * @throws {Error} When no content has been fetched yet
+     * @remarks
+     * Must be defined by concrete implementations. Used for registration and lookup in engine registry.
      */
-    getContent(): Promise<FetchResponse>;
+    static readonly id: string;
     /**
-     * Manages HTTP headers for requests with multiple overloads.
-     *
-     * @overload
-     * Gets all headers.
-     * @returns All headers as record
+     * Execution mode of the engine (`'http'` or `'browser'`).
      *
-     * @overload
-     * Gets specific header value.
-     * @param name - Header name
-     * @returns Header value
-     *
-     * @overload
-     * Sets multiple headers.
-     * @param headers - Headers to set
-     * @param replaced - Whether to replace all existing headers
-     * @returns `true` if successful
-     *
-     * @overload
-     * Sets single header.
-     * @param name - Header name
-     * @param value - Header value or `null` to remove
-     * @returns `true` if successful
-     *
-     * @example
-     * ```ts
-     * const allHeaders = await engine.headers();
-     * const userAgent = await engine.headers('user-agent');
-     * await engine.headers({ 'x-custom': 'value' });
-     * await engine.headers('auth', 'token');
-     * ```
+     * @remarks
+     * Must be defined by concrete implementations. Indicates whether engine operates at HTTP level or uses full browser.
      */
-    headers(): Promise<Record<string, string>>;
-    headers(name: string): Promise<string>;
-    headers(headers: Record<string, string>, replaced?: boolean): Promise<boolean>;
-    headers(name: string, value: string | null): Promise<boolean>;
+    static readonly mode: FetchEngineType;
+    protected ctx?: FetchEngineContext;
+    protected opts?: BaseFetcherProperties;
+    protected crawler?: TCrawler;
+    protected isCrawlerReady?: boolean;
+    protected crawlerRunPromise?: Promise<FinalStatistics>;
+    protected config?: Configuration;
+    protected requestQueue?: RequestQueue;
+    protected kvStore?: KeyValueStore;
+    protected proxyConfiguration?: ProxyConfiguration;
+    protected hdrs: Record<string, string>;
+    protected _initialCookies?: Cookie[];
+    protected _initializedSessions: Set<string>;
+    protected currentSession?: Session;
+    protected pendingRequests: Map<string, PendingEngineRequest>;
+    protected requestCounter: number;
+    protected actionEmitter: EventEmitter;
+    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;
+    };
     /**
-     * Manages cookies for current session with multiple overloads.
-     *
-     * @overload
-     * Gets all cookies.
-     * @returns Array of cookies
-     *
-     * @overload
-     * Sets cookies for session.
-     * @param cookies - Cookies to set
-     * @returns `true` if successful
+     * Finds all elements matching the selector within the given scope.
      *
-     * @example
-     * ```ts
-     * const cookies = await engine.cookies();
-     * await engine.cookies([{ name: 'session', value: '123' }]);
-     * ```
+     * @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
      */
-    cookies(): Promise<Cookie[]>;
-    cookies(cookies: Cookie[]): Promise<boolean>;
+    abstract _querySelectorAll(scope: FetchElementScope, selector: string): Promise<FetchElementScope[]>;
     /**
-     * Disposes of engine, cleaning up all resources.
+     * Extracts a primitive value from the element based on schema.
      *
-     * @returns Promise resolving when disposal completes
+     * @param schema - Value extraction schema.
+     * @param scope - The element scope.
+     * @returns Extracted value.
+     * @see {@link IExtractEngine._extractValue} for behavior contract.
+     * @internal
      */
-    dispose(): Promise<void>;
-}
-declare function getRandomDelay(base: number, variance?: number): number;
-
-type FetchReturnType = 'response' | 'context' | 'outputs' | 'any' | 'none';
-interface FetchReturnTypeRegistry {
-    response: FetchResponse;
-    context: FetchContext;
-    result: FetchActionResult<any> | undefined;
-    outputs: Record<string, any>;
-    any: any;
-    none: void;
-}
-type FetchReturnTypeFor<R extends FetchReturnType> = R extends keyof FetchReturnTypeRegistry ? FetchReturnTypeRegistry[R] : never;
-
-/**
- * Represents the state of an action being executed within a context.
- *
- * @remarks
- * Extends the basic action properties with runtime metadata like execution index,
- * nesting depth, and any errors encountered during execution.
- */
-interface FetchActionInContext extends FetchActionProperties {
+    abstract _extractValue(schema: ExtractValueSchema, scope: FetchElementScope): Promise<any>;
     /**
-     * The 0-based index of the action in the execution sequence.
+     * Gets the parent element of the given element.
+     *
+     * @param scope - The element scope.
+     * @returns Parent element or null.
+     * @internal
      */
-    index?: number;
+    abstract _parentElement(scope: FetchElementScope): Promise<FetchElementScope | null>;
     /**
-     * Error encountered during action execution, if any.
+     * 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
      */
-    error?: Error;
+    abstract _isSameElement(scope1: FetchElementScope, scope2: FetchElementScope): Promise<boolean>;
     /**
-     * The nesting depth of the action. Top-level actions (executed directly by the session) have a depth of 0.
+     * Gets all subsequent siblings of an element until a sibling matches the selector.
+     * Used in 'segmented' extraction mode.
+     *
+     * @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
      */
-    depth?: number;
-}
-/**
- * Base internal state used by fetch engines to maintain their runtime environment.
- *
- * @internal
- */
-interface BaseFetchContextInteralState {
+    abstract _nextSiblingsUntil(scope: FetchElementScope, untilSelector?: string): Promise<FetchElementScope[]>;
     /**
-     * The active engine instance (e.g., CheerioFetchEngine or PlaywrightFetchEngine)
-     * associated with this context.
+     * 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
      */
-    engine?: FetchEngine;
+    abstract _findClosestAncestor(scope: FetchElementScope, candidates: FetchElementScope[]): Promise<FetchElementScope | null>;
     /**
-     * Additional implementation-specific internal state.
+     * 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
      */
-    [key: string]: any;
-}
-/**
- * Extended internal state for the fetch context, including action lifecycle management.
- *
- * @internal
- */
-interface FetchContextInteralState extends BaseFetchContextInteralState {
+    abstract _contains(container: FetchElementScope, element: FetchElementScope): Promise<boolean>;
     /**
-     * Stack of actions currently being executed, used to manage nested action calls.
+     * 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
      */
-    actionStack?: FetchActionInContext[];
+    abstract _findCommonAncestor(scope1: FetchElementScope, scope2: FetchElementScope): Promise<FetchElementScope | null>;
     /**
-     * Global counter for actions executed within the session, used to assign auto-incrementing indices.
+     * 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
      */
-    actionIndex?: number;
-}
-/**
- * Context provided to the Fetch Engine during navigation and request handling.
- *
- * @remarks
- * This interface contains the minimum set of properties required by an engine
- * to perform a fetch operation and build a response.
- */
-interface FetchEngineContext extends BaseFetcherProperties {
+    abstract _findContainerChild(element: FetchElementScope, container: FetchElementScope): Promise<FetchElementScope | null>;
+    protected _extract(schema: ExtractSchema, scope: FetchElementScope, parentStrict?: boolean): Promise<any>;
     /**
-     * Unique identifier for the session or request batch.
+     * Normalizes the array extraction mode into an options object.
+     * @param mode - The mode string or options object.
+     * @internal
      */
-    id: string;
+    protected _normalizeArrayMode(mode?: ExtractArrayMode): {
+        type: ExtractArrayModeName;
+    } & any;
     /**
-     * The target URL for the next navigation, if specified.
+     * Performs standard nested array extraction.
+     * @param items - The schema for each item.
+     * @param elements - The list of item elements.
+     * @internal
      */
-    url?: string;
+    protected _extractNested(items: ExtractSchema, elements: FetchElementScope[], opts?: {
+        strict?: boolean;
+    }): Promise<any[]>;
     /**
-     * The final URL after all redirects have been followed.
+     * Performs columnar extraction (Column Alignment Mode).
+     *
+     * @param schema - The schema for a single item (must be an object or implicit object).
+     * @param container - The container element to search within.
+     * @param opts - Columnar extraction options (strict, inference).
+     * @returns An array of extracted items, or null if requirements aren't met.
+     * @internal
      */
-    finalUrl?: string;
+    protected _extractColumnar(schema: ExtractSchema, container: FetchElementScope, opts?: ColumnarOptions): Promise<any[] | null>;
     /**
-     * The standardized response object from the most recent navigation.
+     * Performs segmented extraction (Anchor-based Scanning).
+     *
+     * @param schema - The schema for a single item (must be an object).
+     * @param container - The container element to scan.
+     * @param opts - Segmented extraction options (anchor).
+     * @returns An array of extracted items.
+     * @internal
      */
-    lastResponse?: FetchResponse;
+    protected _extractSegmented(schema: ExtractSchema, container: FetchElementScope, opts?: SegmentedOptions): Promise<any[] | null>;
     /**
-     * The result object from the most recent action execution.
+     * Creates the crawler instance for the specific engine implementation.
+     * @param options - The final crawler options.
+     * @internal
      */
-    lastResult?: FetchActionResult;
+    protected abstract _createCrawler(options: TOptions, config?: Configuration): TCrawler;
     /**
-     * Engine-specific internal state.
+     * Gets the crawler-specific options from the subclass.
+     * @param ctx - The fetch engine context.
+     * @internal
      */
-    internal: BaseFetchContextInteralState;
-}
-/**
- * The full execution context for a Web Fetcher session or action batch.
- *
- * @remarks
- * This object is the central state container for the fetch operation. It provides
- * access to configuration, the event bus, shared outputs, and the execution engine.
- * It is passed to every action during execution.
- */
-interface FetchContext extends FetchEngineContext {
+    protected abstract _getSpecificCrawlerOptions(ctx: FetchEngineContext): Promise<Partial<TOptions>> | Partial<TOptions>;
     /**
-     * Metadata about the action currently being executed.
+     * Abstract method for building standard [FetchResponse] from Crawlee context.
+     *
+     * @param context - Crawlee crawling context
+     * @returns Promise resolving to [FetchResponse] object
+     *
+     * @remarks
+     * Converts implementation-specific context (Playwright `page` or Cheerio `$`) to standardized response.
+     * @internal
      */
-    currentAction?: FetchActionInContext;
+    protected abstract _buildResponse(context: TContext): Promise<FetchResponse>;
+    protected buildResponse(context: TContext): Promise<FetchResponse>;
     /**
-     * A shared key-value store for storing data extracted from pages or
-     * metadata generated during action execution.
+     * Abstract method for executing action within current page context.
+     *
+     * @param context - Crawlee crawling context
+     * @param action - Action to execute
+     * @returns Promise resolving to action result
+     *
+     * @remarks
+     * Handles specific user interactions using underlying technology (Playwright/Cheerio).
+     * @internal
      */
-    outputs: Record<string, any>;
+    protected abstract executeAction(context: TContext, action: FetchEngineAction): Promise<any>;
     /**
-     * Executes a FetchAction within the current context.
+     * Navigates to the specified URL.
      *
-     * @param actionOptions - Configuration for the action to be executed.
-     * @returns A promise that resolves to the action's result.
+     * @param url - Target URL
+     * @param params - Navigation options
+     * @returns Promise resolving when navigation completes
+     *
+     * @example
+     * ```ts
+     * await engine.goto('https://example.com');
+     * ```
      */
-    execute<R extends FetchReturnType = 'any'>(actionOptions: FetchActionOptions): Promise<FetchActionResult<R>>;
+    abstract goto(url: string, params?: GotoActionOptions): Promise<void | FetchResponse>;
     /**
-     * Convenience method to execute an action by its registered name or ID.
+     * Waits for specified condition before continuing.
      *
-     * @param name - The registered name or ID of the action.
-     * @param params - Parameters specific to the action type.
-     * @param options - Additional execution options (e.g., storeAs, failOnError).
-     * @returns A promise that resolves to the action's result.
+     * @param params - Wait conditions
+     * @returns Promise resolving when wait condition is met
+     *
+     * @example
+     * ```ts
+     * await engine.waitFor({ ms: 1000 }); // Wait 1 second
+     * await engine.waitFor({ selector: '#content' }); // Wait for element
+     * ```
      */
-    action<R extends FetchReturnType = 'any'>(name: string, params?: any, options?: Partial<FetchActionOptions>): Promise<FetchActionResult<R>>;
+    waitFor(params?: WaitForActionOptions): Promise<void>;
     /**
-     * Internal state for engine and lifecycle management.
+     * Clicks on element matching selector.
+     *
+     * @param selector - CSS selector of element to click
+     * @returns Promise resolving when click is processed
+     * @throws {Error} When no active page context exists
      */
-    internal: FetchContextInteralState;
+    click(selector: string): Promise<void>;
     /**
-     * The central event bus for publishing and subscribing to session and action events.
+     * Moves mouse to specified position or element.
+     *
+     * @param params - Move parameters (x, y, selector, steps)
      */
-    eventBus: EventEmitter;
-}
-
-type CheerioAPI = NonNullable<CheerioCrawlingContext['$']>;
-type CheerioSelection = ReturnType<CheerioAPI>;
-type CheerioNode = ReturnType<CheerioSelection['first']>;
-declare class CheerioFetchEngine extends FetchEngine<CheerioCrawlingContext, CheerioCrawler, CheerioCrawlerOptions> {
-    static readonly id = "cheerio";
-    static readonly mode = "http";
-    private _ensureCheerioContext;
-    protected _buildResponse(context: CheerioCrawlingContext): Promise<FetchResponse>;
-    _querySelectorAll(scope: {
-        $: CheerioAPI;
-        el: any;
-    } | 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;
-    }, candidates: {
-        $: CheerioAPI;
-        el: CheerioNode;
-    }[]): Promise<FetchElementScope | null>;
-    _contains(container: {
-        $: CheerioAPI;
-        el: CheerioNode;
-    }, element: {
-        $: CheerioAPI;
-        el: CheerioNode;
-    }): Promise<boolean>;
-    _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>;
-    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>;
-}
-
-type Page = NonNullable<PlaywrightCrawlingContext['page']>;
-type Locator = ReturnType<Page['locator']>;
-declare class PlaywrightFetchEngine extends FetchEngine<PlaywrightCrawlingContext, PlaywrightCrawler, PlaywrightCrawlerOptions> {
-    static readonly id = "playwright";
-    static readonly mode = "browser";
-    protected _buildResponse(context: PlaywrightCrawlingContext): Promise<FetchResponse>;
-    _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 _sharedRequestHandler(context: PlaywrightCrawlingContext): Promise<void>;
-    protected mouseInitialized: boolean;
-    protected _initializeMousePos(page: Page): Promise<void>;
-    protected _getTrajectory(start: {
-        x: number;
-        y: number;
-    }, end: {
-        x: number;
-        y: number;
-    }, steps?: number): {
-        x: number;
-        y: number;
-    }[];
-    protected _moveToPos(context: PlaywrightCrawlingContext, target: {
-        x: number;
-        y: number;
-    }, steps?: number): Promise<{
-        x: number;
-        y: number;
-    }>;
-    protected _ensureVisible(context: PlaywrightCrawlingContext, selector: string): Promise<{
-        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>>;
-    goto(url: string, opts?: GotoActionOptions): Promise<FetchResponse>;
-}
-
-declare enum FetchActionResultStatus {
+    mouseMove(params: {
+        x?: number;
+        y?: number;
+        selector?: string;
+        steps?: number;
+    }): Promise<void>;
     /**
-     * 动作执行失败但未抛出（通常因 failOnError=false）；错误信息在 error 字段
+     * Clicks at current position or specified position.
+     *
+     * @param params - Click parameters (x, y, button, clickCount, delay)
      */
-    Failed = 0,
+    mouseClick(params: {
+        x?: number;
+        y?: number;
+        button?: 'left' | 'right' | 'middle';
+        clickCount?: number;
+        delay?: number;
+    }): Promise<void>;
     /**
-     * 动作按预期完成（即便产生 warnings）
+     * Scrolls the mouse wheel.
+     *
+     * @param params - Wheel parameters (x, y, selector, deltaX, deltaY, steps)
      */
-    Success = 1,
+    mouseWheel(params: {
+        x?: number;
+        y?: number;
+        selector?: string;
+        deltaX?: number;
+        deltaY?: number;
+        steps?: number;
+    }): Promise<void>;
     /**
-     * 动作被判定为不执行/降级为 noop（比如引擎不支持且 degradeTo='noop'）
-     * 能力不支持且 degradeTo='noop' 时：status='skipped'，warnings 增加 { code:'capability-not-supported' }
+     * Scrolls the element into view.
+     *
+     * @param params - Scroll parameters (selector)
      */
-    Skipped = 2
-}
-type FetchActionCapabilityMode = 'native' | 'simulate' | 'noop';
-interface FetchActionMeta {
-    id: string;
-    index?: number;
-    engineType?: FetchEngineType;
-    capability?: FetchActionCapabilityMode;
-    response?: FetchResponse;
-    timings?: {
-        start: number;
-        total: number;
-    };
-    retries?: number;
-}
-interface FetchActionResult<R extends FetchReturnType = FetchReturnType> {
-    status: FetchActionResultStatus;
-    returnType?: R;
-    result?: FetchReturnTypeFor<R>;
-    error?: Error;
-    meta?: FetchActionMeta;
-}
-interface BaseFetchActionProperties {
-    id?: string;
-    name?: string;
-    action?: string | FetchAction;
-    index?: number;
-    params?: any;
-    args?: any;
-    storeAs?: string;
-    failOnError?: boolean;
-    failOnTimeout?: boolean;
-    timeoutMs?: number;
-    maxRetries?: number;
-    [key: string]: any;
-}
-type BaseFetchActionOptions = RequireAtLeastOne<BaseFetchActionProperties, 'id' | 'name' | 'action'>;
-interface BaseFetchCollectorActionProperties extends BaseFetchActionProperties {
-    activateOn?: string | RegExp | Array<string | RegExp>;
-    deactivateOn?: string | RegExp | Array<string | RegExp>;
-    collectOn?: string | RegExp | Array<string | RegExp>;
-    background?: boolean;
-}
-type BaseFetchCollectorOptions = RequireAtLeastOne<BaseFetchCollectorActionProperties, 'id' | 'name' | 'action'>;
-interface FetchActionProperties extends BaseFetchActionProperties {
-    collectors?: BaseFetchCollectorOptions[];
-}
-type FetchActionOptions = RequireAtLeastOne<FetchActionProperties, 'id' | 'name' | 'action'>;
-type FetchActionCapabilities = {
-    [mode in FetchEngineType]?: FetchActionCapabilityMode;
-};
-declare abstract class FetchAction {
-    private static registry;
-    static register(actionClass: typeof FetchAction): void;
-    static get(id: string): typeof FetchAction | undefined;
-    static create(id: FetchActionOptions): FetchAction | undefined;
-    static create(id: string): FetchAction | undefined;
-    static has(name: string): boolean;
-    static list(): string[];
-    static id: string;
-    static returnType: FetchReturnType;
-    static capabilities: FetchActionCapabilities;
-    static getCapability(mode?: FetchEngineType): FetchActionCapabilityMode;
-    getCapability(mode?: FetchEngineType): FetchActionCapabilityMode;
-    get id(): string;
-    get returnType(): FetchReturnType;
-    get capabilities(): FetchActionCapabilities;
-    protected onBeforeExec?(context: FetchContext, options?: FetchActionProperties): Promise<void> | void;
-    protected onAfterExec?(context: FetchContext, options?: FetchActionProperties): Promise<void> | void;
-    abstract onExecute(context: FetchContext, options?: FetchActionProperties, eventPayload?: any): Promise<any> | any;
-    protected delegateToEngine(context: FetchContext, method: keyof FetchEngine, ...args: any[]): Promise<any>;
-    protected installCollectors(context: FetchContext, options?: FetchActionProperties): CollectorsRuntime | undefined;
+    scrollIntoView(params: {
+        selector: string;
+    }): Promise<void>;
     /**
-     * Action 开始生命周期
-     * 负责：初始化 stack、设置 currentAction、触发事件、调用钩子
+     * Types text into current focused element.
+     *
+     * @param text - Text to type
+     * @param delay - Delay between key presses
      */
-    beforeExec(context: FetchContext, options?: FetchActionProperties): Promise<{
-        entry: FetchActionInContext;
-        collectors: CollectorsRuntime | undefined;
-    }>;
+    keyboardType(text: string, delay?: number): Promise<void>;
     /**
-     * Action 结束生命周期
-     * 负责：调用钩子、赋值lastResult, 触发事件、清理 stack、恢复 currentAction
+     * Presses specified key.
+     *
+     * @param key - Key to press
+     * @param delay - Delay after key press
      */
-    afterExec(context: FetchContext, options?: BaseFetchCollectorActionProperties, result?: FetchActionResult, scope?: {
-        entry: FetchActionInContext;
-        collectors?: CollectorsRuntime;
-    }): Promise<void>;
-    execute<R extends FetchReturnType = 'any'>(context: FetchContext, options?: FetchActionProperties): Promise<FetchActionResult<R>>;
-}
-type CollectorsRuntime = {
-    cleanup: () => void;
-    awaitExecPendings: () => Promise<void>;
-};
-
-type FetchEngineType = 'http' | 'browser';
-type BrowserEngine = 'playwright' | 'puppeteer';
-type FetchEngineMode = FetchEngineType | 'auto' | string;
-type ResourceType = 'image' | 'stylesheet' | 'font' | 'script' | 'media' | string;
-/**
- * Storage configuration options for the fetch engine.
- *
- * @remarks
- * Controls how Crawlee's internal storage (RequestQueue, KeyValueStore, SessionPool) is managed.
- */
-interface StorageOptions {
+    keyboardPress(key: string, delay?: number): Promise<void>;
     /**
-     * Custom identifier for the storage.
-     * If provided, multiple sessions can share the same storage by using the same ID.
-     * If not provided, a unique session ID is used (strong isolation).
+     * Fills input element with specified value.
+     *
+     * @param selector - CSS selector of input element
+     * @param value - Value to fill
+     * @returns Promise resolving when fill operation completes
+     * @throws {Error} When no active page context exists
      */
-    id?: string;
+    fill(selector: string, value: string): Promise<void>;
     /**
-     * Whether to persist storage to disk.
-     * If true, uses Crawlee's disk persistence. If false, data might be stored in memory or temporary directory.
-     * Corresponds to Crawlee's `persistStorage` configuration.
+     * Submits a form.
+     *
+     * @param selector - Optional form/submit button selector
+     * @param options - Submission options
+     * @returns Promise resolving when form is submitted
+     * @throws {Error} When no active page context exists
      */
-    persist?: boolean;
+    submit(selector?: any, options?: SubmitActionOptions): Promise<void>;
     /**
-     * Whether to delete the storage (RequestQueue and KeyValueStore) when the session is closed.
-     * Defaults to true. Set to false if you want to keep data for future reuse with the same `id`.
+     * 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
      */
-    purge?: boolean;
+    trim(options: TrimActionOptions): Promise<void>;
     /**
-     * Additional Crawlee configuration options.
-     * Allows fine-grained control over the underlying Crawlee instance.
+     * Pauses execution, allowing for manual intervention or inspection.
+     *
+     * @param message - Optional message to display during pause
+     * @returns Promise resolving when execution is resumed
+     * @throws {Error} When no active page context exists
      */
-    config?: Record<string, any>;
-}
-interface BaseFetcherProperties {
+    pause(message?: string): Promise<void>;
     /**
-     * 抓取模式
+     * Executes a custom function or expression within the current page context.
      *
-     * - `http`: 使用 HTTP 进行抓取
-     * - `browser`: 使用浏览器进行抓取
-     * - `auto`: auto 会走“智能探测”选择 http 或 browser, 但是如果没有启用 smart，并且在站点注册表中没有，那么则等价为 http.
+     * @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.
      */
-    engine?: FetchEngineMode;
-    enableSmart?: boolean;
-    useSiteRegistry?: boolean;
-    antibot?: boolean;
-    debug?: boolean | string | string[];
-    headers?: Record<string, string>;
-    cookies?: Cookie[];
-    sessionState?: any;
-    sessionPoolOptions?: SessionPoolOptions;
-    overrideSessionState?: boolean;
-    throwHttpErrors?: boolean;
-    output?: {
-        cookies?: boolean;
-        sessionState?: boolean;
-    };
-    proxy?: string | string[];
-    blockResources?: ResourceType[];
+    evaluate(params: EvaluateActionOptions): Promise<any>;
     /**
-     * Storage configuration for session isolation and persistence.
+     * Extracts structured data from the current page content.
+     *
+     * @param schema - An object defining the data to extract.
+     * @returns A promise that resolves to an object with the extracted data.
      */
-    storage?: StorageOptions;
-    ignoreSslErrors?: boolean;
-    browser?: {
-        /**
-         * 浏览器引擎，默认为 playwright
-         *
-         * - `playwright`: 使用 Playwright 引擎
-         * - `puppeteer`: 使用 Puppeteer 引擎
-         */
-        engine?: BrowserEngine;
-        headless?: boolean;
-        waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
-        launchOptions?: Record<string, any>;
-    };
-    http?: {
-        method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-        body?: any;
-    };
-    timeoutMs?: number;
-    requestHandlerTimeoutSecs?: number;
-    maxConcurrency?: number;
-    maxRequestsPerMinute?: number;
-    delayBetweenRequestsMs?: number;
-    retries?: number;
-    sites?: FetchSite[];
-    url?: string;
-}
-interface FetchSite extends BaseFetcherProperties {
-    domain: string;
-    pathScope?: string[];
-    meta?: {
-        updatedAt?: number;
-        ttlMs?: number;
-        source?: 'manual' | 'smart';
-    };
-}
-type OnFetchPauseCallback = (options: {
-    message?: string;
-}) => Promise<void>;
-interface FetcherOptions extends BaseFetcherProperties {
-    actions?: FetchActionOptions[];
-    onPause?: OnFetchPauseCallback;
-}
-interface FetchMetadata {
-    mode: FetchEngineType;
-    engine?: BrowserEngine;
-    timings?: {
-        start: number;
-        total: number;
-        ttfb?: number;
-        dns?: number;
-        tcp?: number;
-        firstByte?: number;
-        download?: number;
-    };
-    proxy?: string;
-    [key: string]: any;
-}
-interface FetchResponse {
-    url: string;
-    finalUrl: string;
-    statusCode?: number;
-    statusText?: string;
-    headers: Record<string, string>;
-    contentType?: string;
-    body?: string | Buffer<ArrayBufferLike>;
-    html?: string;
-    text?: string;
-    json?: any;
-    cookies?: Cookie[];
-    sessionState?: any;
-    metadata?: FetchMetadata;
-}
-declare const DefaultFetcherProperties: BaseFetcherProperties;
-declare const FetcherOptionKeys: string[];
-
-/**
- * Represents a stateful web fetching session.
- *
- * @remarks
- * A `FetchSession` manages the lifecycle of a single crawling operation, including engine initialization,
- * cookie persistence, and sequential action execution. It maintains a `FetchContext` that stores
- * session-level configurations and outputs.
- *
- * Sessions are isolated; each has its own unique ID and (by default) its own storage and cookies.
- */
-declare class FetchSession {
-    protected options: FetcherOptions;
+    extract<T>(schema: ExtractSchema): Promise<T>;
     /**
-     * Unique identifier for the session.
+     * Gets the unique identifier of this engine implementation.
      */
-    readonly id: string;
+    get id(): string;
     /**
-     * The execution context for this session, containing configurations, event bus, and shared state.
+     * Returns the current state of the engine (cookies)
+     * that can be used to restore the session later.
      */
-    readonly context: FetchContext;
-    protected closed: boolean;
+    getState(): Promise<{
+        cookies: Cookie[];
+        sessionState?: any;
+    }>;
     /**
-     * Creates a new FetchSession.
+     * Gets the execution mode of this engine (`'http'` or `'browser'`).
+     */
+    get mode(): FetchEngineType;
+    /**
+     * Gets the fetch engine context associated with this instance.
+     */
+    get context(): FetchEngineContext | undefined;
+    /**
+     * Initializes the fetch engine with provided context and options.
      *
-     * @param options - Configuration options for the fetcher.
+     * @param context - Fetch engine context
+     * @param options - Configuration options
+     * @returns Promise resolving when initialization completes
+     *
+     * @remarks
+     * Sets up internal state and calls implementation-specific [_initialize](file:///home/riceball/Documents/mywork/public/@isdk/ai-tools/packages/web-fetcher/src/engine/cheerio.ts#L169-L204) method.
+     * Automatically called when creating engine via `FetchEngine.create()`.
      */
-    constructor(options?: FetcherOptions);
-    protected _logDebug(category: string, ...args: any[]): void;
+    initialize(context: FetchEngineContext, options?: BaseFetcherProperties): Promise<void>;
+    cleanup(): Promise<void>;
     /**
-     * Executes a single action within the session.
+     * 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.
      *
-     * @param actionOptions - Configuration for the action to be executed.
-     * @param context - Optional context override for this specific execution. Defaults to the session context.
-     * @returns A promise that resolves to the result of the action.
-     * @template R - The expected return type of the action.
+     * **Critical Execution Constraint**: This method **MUST** be awaited within the synchronous execution path
+     * of Crawlee's [requestHandler](https://crawlee.dev/js/api/basic-crawler) (before any `await` that yields control back to the event loop).
+     *
+     * ### Why This Constraint Exists
+     * - Crawlee's page context ([PlaywrightCrawler](https://crawlee.dev/js/api/playwright-crawler)'s `page` or [CheerioCrawler](https://crawlee.dev/js/api/cheerio-crawler)'s `$`)
+     *   is **only valid during the synchronous execution phase** of the request handler
+     * - After any `await` (e.g., `await page.goto()`), the page context may be destroyed
+     *   due to Crawlee's internal resource management
+     *
+     * ### How It Works
+     * 1. Processes all actions queued via {@link dispatchAction} (click, fill, submit, etc.)
+     * 2. Maintains the page context validity window via {@link isPageActive} lifecycle flag
+     * 3. Automatically cleans up event listeners upon completion
+     *
+     * Usage see {@link _sharedRequestHandler}
+     * @see {@link _sharedRequestHandler}
+     * @param context The active Crawlee crawling context containing the page/$ object
+     * @throws {Error} If called outside valid page context window (`!this.isPageActive`)
+     * @internal Engine infrastructure method - not for direct consumer use
+     */
+    protected _executePendingActions(context: TContext): Promise<void>;
+    protected _sharedRequestHandler(context: TContext): Promise<void>;
+    protected _sharedFailedRequestHandler(context: TContext & {
+        response?: FetchResponse;
+        body?: string | Buffer;
+    }, error?: Error): Promise<void>;
+    protected dispatchAction<T>(action: FetchEngineAction): Promise<T>;
+    private _requestHandler;
+    private _failedRequestHandler;
+    protected _commonCleanup(): Promise<void>;
+    /**
+     * Blocks specified resource types from loading.
+     *
+     * @param types - Resource types to block
+     * @param overwrite - Whether to replace existing blocked types
+     * @returns Number of blocked resource types
      *
      * @example
      * ```ts
-     * await session.execute({ name: 'goto', params: { url: 'https://example.com' } });
+     * await engine.blockResources(['image', 'stylesheet']);
+     * await engine.blockResources(['script'], true); // Replace existing
      * ```
      */
-    execute<R extends FetchReturnType = 'response'>(actionOptions: FetchActionOptions, context?: FetchContext): Promise<FetchActionResult<R>>;
+    blockResources(types: ResourceType[], overwrite?: boolean): Promise<number>;
     /**
-     * Executes a sequence of actions.
+     * Gets content of current page.
      *
-     * @param actions - An array of action options to be executed in order.
-     * @param options - Optional temporary configuration overrides (e.g., timeoutMs, headers) for this batch of actions.
-     *                  These overrides do not affect the main session context.
-     * @returns A promise that resolves to an object containing the result of the last action and all accumulated outputs.
+     * @returns Promise resolving to fetch response
+     * @throws {Error} When no content has been fetched yet
+     */
+    getContent(): Promise<FetchResponse>;
+    /**
+     * Manages HTTP headers for requests with multiple overloads.
+     *
+     * @overload
+     * Gets all headers.
+     * @returns All headers as record
+     *
+     * @overload
+     * Gets specific header value.
+     * @param name - Header name
+     * @returns Header value
+     *
+     * @overload
+     * Sets multiple headers.
+     * @param headers - Headers to set
+     * @param replaced - Whether to replace all existing headers
+     * @returns `true` if successful
+     *
+     * @overload
+     * Sets single header.
+     * @param name - Header name
+     * @param value - Header value or `null` to remove
+     * @returns `true` if successful
      *
      * @example
      * ```ts
-     * const { result, outputs } = await session.executeAll([
-     *   { name: 'goto', params: { url: 'https://example.com' } },
-     *   { name: 'extract', params: { schema: { title: 'h1' } }, storeAs: 'data' }
-     * ], { timeoutMs: 30000 });
+     * const allHeaders = await engine.headers();
+     * const userAgent = await engine.headers('user-agent');
+     * await engine.headers({ 'x-custom': 'value' });
+     * await engine.headers('auth', 'token');
      * ```
      */
-    executeAll(actions: FetchActionOptions[], options?: Partial<FetcherOptions> & {
-        index?: number;
-    }): Promise<{
-        result: FetchResponse | undefined;
-        outputs: Record<string, any>;
-    }>;
+    headers(): Promise<Record<string, string>>;
+    headers(name: string): Promise<string>;
+    headers(headers: Record<string, string>, replaced?: boolean): Promise<boolean>;
+    headers(name: string, value: string | null): Promise<boolean>;
     /**
-     * Retrieves all outputs accumulated during the session.
+     * Manages cookies for current session with multiple overloads.
      *
-     * @returns A record of stored output data.
-     */
-    getOutputs(): Record<string, any>;
-    /**
-     * Gets the current state of the session, including cookies and engine-specific state.
+     * @overload
+     * Gets all cookies.
+     * @returns Array of cookies
      *
-     * @returns A promise resolving to the session state, or undefined if no engine is initialized.
+     * @overload
+     * Sets cookies for session.
+     * @param cookies - Cookies to set
+     * @returns `true` if successful
+     *
+     * @example
+     * ```ts
+     * const cookies = await engine.cookies();
+     * await engine.cookies([{ name: 'session', value: '123' }]);
+     * ```
      */
-    getState(): Promise<{
-        cookies: Cookie[];
-        sessionState?: any;
-    } | undefined>;
+    cookies(): Promise<Cookie[]>;
+    cookies(cookies: Cookie[]): Promise<boolean>;
     /**
-     * Disposes of the session and its associated engine.
+     * Disposes of engine, cleaning up all resources.
      *
-     * @remarks
-     * This method should be called when the session is no longer needed to free up resources
-     * (e.g., closing browser instances, purging temporary storage).
+     * @returns Promise resolving when disposal completes
      */
     dispose(): Promise<void>;
-    private ensureEngine;
-    protected createContext(options?: FetcherOptions): FetchContext;
 }
+declare function getRandomDelay(base: number, variance?: number): number;
 
-/**
- * High-level entry point for the Web Fetcher library.
- *
- * @remarks
- * The `WebFetcher` provides a simplified API for fetching web content without manually managing sessions.
- * It can be used for one-off requests or as a factory for more complex `FetchSession` instances.
- *
- * @example
- * ```ts
- * const fetcher = new WebFetcher();
- * const { result } = await fetcher.fetch('https://example.com');
- * ```
- */
-declare class WebFetcher {
-    private defaults;
-    /**
-     * Creates a new WebFetcher with default options.
-     *
-     * @param defaults - Default configuration options applied to all sessions and requests.
-     */
-    constructor(defaults?: FetcherOptions);
+type CheerioAPI = NonNullable<CheerioCrawlingContext['$']>;
+type CheerioSelection = ReturnType<CheerioAPI>;
+type CheerioNode = ReturnType<CheerioSelection['first']>;
+declare class CheerioFetchEngine extends FetchEngine<CheerioCrawlingContext, CheerioCrawler, CheerioCrawlerOptions> {
+    static readonly id = "cheerio";
+    static readonly mode = "http";
+    private _ensureCheerioContext;
+    protected _buildResponse(context: CheerioCrawlingContext): Promise<FetchResponse>;
+    _querySelectorAll(scope: {
+        $: CheerioAPI;
+        el: any;
+    } | 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;
+    }, candidates: {
+        $: CheerioAPI;
+        el: CheerioNode;
+    }[]): Promise<FetchElementScope | null>;
+    _contains(container: {
+        $: CheerioAPI;
+        el: CheerioNode;
+    }, element: {
+        $: CheerioAPI;
+        el: CheerioNode;
+    }): Promise<boolean>;
+    _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>;
+    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>;
+}
+
+type Page = NonNullable<PlaywrightCrawlingContext['page']>;
+type Locator = ReturnType<Page['locator']>;
+declare class PlaywrightFetchEngine extends FetchEngine<PlaywrightCrawlingContext, PlaywrightCrawler, PlaywrightCrawlerOptions> {
+    static readonly id = "playwright";
+    static readonly mode = "browser";
+    protected _buildResponse(context: PlaywrightCrawlingContext): Promise<FetchResponse>;
+    _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 _sharedRequestHandler(context: PlaywrightCrawlingContext): Promise<void>;
+    protected mouseInitialized: boolean;
+    protected _initializeMousePos(page: Page): Promise<void>;
+    protected _getTrajectory(start: {
+        x: number;
+        y: number;
+    }, end: {
+        x: number;
+        y: number;
+    }, steps?: number): {
+        x: number;
+        y: number;
+    }[];
+    protected _moveToPos(context: PlaywrightCrawlingContext, target: {
+        x: number;
+        y: number;
+    }, steps?: number): Promise<{
+        x: number;
+        y: number;
+    }>;
+    protected _ensureVisible(context: PlaywrightCrawlingContext, selector: string): Promise<{
+        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>>;
+    goto(url: string, opts?: GotoActionOptions): Promise<FetchResponse>;
+}
+
+type FetchActionCapabilities = {
+    [mode in FetchEngineType]?: FetchActionCapabilityMode;
+};
+declare abstract class FetchAction {
+    private static registry;
+    static register(actionClass: any): void;
+    static get(id: string): any | undefined;
+    static create(id: FetchActionOptions): FetchAction | undefined;
+    static create(id: string): FetchAction | undefined;
+    static has(name: string): boolean;
+    static list(): string[];
+    static id: string;
+    static returnType: FetchReturnType;
+    static capabilities: FetchActionCapabilities;
+    static getCapability(mode?: FetchEngineType): FetchActionCapabilityMode;
+    getCapability(mode?: FetchEngineType): FetchActionCapabilityMode;
+    get id(): string;
+    get returnType(): FetchReturnType;
+    get capabilities(): FetchActionCapabilities;
+    protected onBeforeExec?(context: FetchContext, options?: FetchActionProperties): Promise<void> | void;
+    protected onAfterExec?(context: FetchContext, options?: FetchActionProperties): Promise<void> | void;
+    abstract onExecute(context: FetchContext, options?: FetchActionProperties, eventPayload?: any): Promise<any> | any;
+    protected delegateToEngine(context: FetchContext, method: keyof FetchEngine, ...args: any[]): Promise<any>;
+    protected installCollectors(context: FetchContext, options?: FetchActionProperties): CollectorsRuntime | undefined;
     /**
-     * Creates a new FetchSession.
-     *
-     * @param options - Configuration options for the session, merged with defaults.
-     * @returns A promise resolving to a new FetchSession instance.
+     * Action 开始生命周期
+     * 负责：初始化 stack、设置 currentAction、触发事件、调用钩子
      */
-    createSession(options?: FetcherOptions): Promise<FetchSession>;
+    beforeExec(context: FetchContext, options?: FetchActionProperties): Promise<{
+        entry: Required<Pick<FetchActionProperties, "action">> & Partial<Pick<FetchActionProperties, "id" | "name">> & {
+            [x: string]: any;
+            collectors?: BaseFetchCollectorOptions[] | undefined;
+            index?: number | undefined;
+            params?: any;
+            args?: any;
+            storeAs?: string | undefined;
+            failOnError?: boolean | undefined;
+            failOnTimeout?: boolean | undefined;
+            timeoutMs?: number | undefined;
+            maxRetries?: number | undefined;
+        } & {
+            index?: number;
+            error?: Error;
+            depth?: number;
+        };
+        collectors: CollectorsRuntime | undefined;
+    }>;
     /**
-     * Fetches content from a URL or executes a complex action script.
-     *
-     * @remarks
-     * This method automatically creates a session, executes the specified actions,
-     * retrieves the content, and disposes of the session.
-     *
-     * @param url - The target URL or a complete FetcherOptions object.
-     * @param options - Additional options when the first parameter is a URL string.
-     * @returns A promise resolving to the final response and any extracted outputs.
+     * Action 结束生命周期
+     * 负责：调用钩子、赋值lastResult, 触发事件、清理 stack、恢复 currentAction
      */
-    fetch(url: string, options?: FetcherOptions): Promise<{
-        result: FetchResponse | undefined;
-        outputs: Record<string, any>;
-    }>;
-    fetch(options: FetcherOptions): Promise<{
-        result: FetchResponse | undefined;
-        outputs: Record<string, any>;
-    }>;
+    afterExec(context: FetchContext, options?: BaseFetchCollectorActionProperties, result?: FetchActionResult, scope?: {
+        entry: FetchActionInContext;
+        collectors?: CollectorsRuntime;
+    }): Promise<void>;
+    execute<R extends FetchReturnType = 'any'>(context: FetchContext, options?: FetchActionProperties): Promise<FetchActionResult<R>>;
 }
+type CollectorsRuntime = {
+    cleanup: () => void;
+    awaitExecPendings: () => Promise<void>;
+};
 
 declare class ClickAction extends FetchAction {
     static id: string;
@@ -2779,4 +2804,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, 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, MouseWheelAction, type MouseWheelParams, type OnFetchPauseCallback, PauseAction, type PendingEngineRequest, PlaywrightFetchEngine, type ResourceType, ScrollIntoViewAction, type ScrollIntoViewParams, type StorageOptions, SubmitAction, type SubmitActionOptions, TRIM_PRESETS, TrimAction, type TrimActionOptions, type TrimPreset, WaitForAction, type WaitForActionOptions, WebFetcher, fetchWeb, getRandomDelay };
+export { type BaseFetchActionOptions, type BaseFetchActionProperties, type BaseFetchCollectorActionProperties, type BaseFetchCollectorOptions, type BaseFetcherProperties, type BrowserEngine, CheerioFetchEngine, ClickAction, DefaultFetcherProperties, type DispatchedEngineAction, EngineUpgradeError, EvaluateAction, type EvaluateActionOptions, ExtractAction, type ExtractActionProperties, FetchAction, type FetchActionCapabilities, type FetchActionCapabilityMode, type FetchActionInContext, type FetchActionMeta, 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, MouseWheelAction, type MouseWheelParams, type OnFetchPauseCallback, PauseAction, type PendingEngineRequest, PlaywrightFetchEngine, type ResourceType, ScrollIntoViewAction, type ScrollIntoViewParams, type StorageOptions, SubmitAction, type SubmitActionOptions, TRIM_PRESETS, TrimAction, type TrimActionOptions, type TrimPreset, WaitForAction, type WaitForActionOptions, WebFetcher, fetchWeb, getRandomDelay };