@isdk/web-fetcher 0.3.1 → 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,1759 +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;
-    };
-} | {
-    type: 'keyboardType';
-    params: {
-        text: string;
-        delay?: number;
-    };
-} | {
-    type: 'keyboardPress';
-    params: {
-        key: string;
-        delay?: number;
-    };
-} | {
-    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
+     * @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()`.
      */
-    abstract _extractValue(schema: ExtractValueSchema, scope: FetchElementScope): Promise<any>;
+    _contains(container: FetchElementScope, element: FetchElementScope): Promise<boolean>;
     /**
-     * Gets the parent element of the given element.
+     * Finds the Lowest Common Ancestor (LCA) of two element scopes.
      *
-     * @param scope - The element scope.
-     * @returns Parent element or null.
-     * @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 _parentElement(scope: FetchElementScope): Promise<FetchElementScope | null>;
+    _findCommonAncestor(scope1: FetchElementScope, scope2: FetchElementScope): Promise<FetchElementScope | null>;
     /**
-     * Checks if two elements are the same identity.
+     * Finds the direct child of the `container` that contains the `element` (or is the `element` itself).
      *
-     * @param scope1 - First element scope.
-     * @param scope2 - Second element scope.
-     * @returns True if they are the same DOM node.
-     * @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 _isSameElement(scope1: FetchElementScope, scope2: FetchElementScope): Promise<boolean>;
+    _findContainerChild(element: FetchElementScope, container: FetchElementScope): Promise<FetchElementScope | null>;
     /**
-     * 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
+     * Logs debug information if debug mode is enabled.
+     * @param category - The category of the log message.
+     * @param args - Arguments to log.
      */
-    abstract _nextSiblingsUntil(scope: FetchElementScope, untilSelector?: string): Promise<FetchElementScope[]>;
+    _logDebug(category: string, ...args: any[]): void;
+}
+/**
+ * Base configuration for all extraction schemas.
+ */
+interface BaseExtractSchema {
     /**
-     * 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
+     * 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 _findClosestAncestor(scope: FetchElementScope, candidates: FetchElementScope[]): Promise<FetchElementScope | null>;
+    required?: boolean;
     /**
-     * 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 to enable strict mode for this extraction.
+     * If true, missing required fields will throw an error instead of being skipped.
      */
-    abstract _contains(container: FetchElementScope, element: FetchElementScope): Promise<boolean>;
+    strict?: boolean;
     /**
-     * Finds the Lowest Common Ancestor (LCA) of two element scopes.
+     * 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 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
+     * Once anchored, the search scope for this field becomes the siblings following the anchor.
      */
-    abstract _findCommonAncestor(scope1: FetchElementScope, scope2: FetchElementScope): Promise<FetchElementScope | null>;
+    anchor?: string;
     /**
-     * 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
+     * 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.
      */
-    abstract _findContainerChild(element: FetchElementScope, container: FetchElementScope): Promise<FetchElementScope | null>;
-    protected _extract(schema: ExtractSchema, scope: FetchElementScope, parentStrict?: boolean): Promise<any>;
+    depth?: number;
+}
+/**
+ * Extraction schema types.
+ */
+type ExtractSchema = ExtractObjectSchema | ExtractArraySchema | ExtractValueSchema;
+/**
+ * Configuration for extracting a single value.
+ */
+interface ExtractValueSchema extends BaseExtractSchema {
     /**
-     * Normalizes the array extraction mode into an options object.
-     * @param mode - The mode string or options object.
-     * @internal
+     * The data type to cast the extracted value to.
+     * @default 'string'
      */
-    protected _normalizeArrayMode(mode?: ExtractArrayMode): {
-        type: ExtractArrayModeName;
-    } & any;
+    type?: 'string' | 'number' | 'boolean' | 'html';
     /**
-     * Performs standard nested array extraction.
-     * @param items - The schema for each item.
-     * @param elements - The list of item elements.
-     * @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 _extractNested(items: ExtractSchema, elements: FetchElementScope[], opts?: {
-        strict?: boolean;
-    }): Promise<any[]>;
+    mode?: 'text' | 'innerText' | 'html' | 'outerHTML';
     /**
-     * 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
+     * CSS selector to locate the element within the current context.
      */
-    protected _extractColumnar(schema: ExtractSchema, container: FetchElementScope, opts?: ColumnarOptions): Promise<any[] | null>;
+    selector?: string;
     /**
-     * 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
+     * Attribute name to extract (e.g., 'href', 'src').
+     * If omitted, the text content or HTML is extracted based on `type`.
      */
-    protected _extractSegmented(schema: ExtractSchema, container: FetchElementScope, opts?: SegmentedOptions): Promise<any[] | null>;
+    attribute?: string;
     /**
-     * Creates the crawler instance for the specific engine implementation.
-     * @param options - The final crawler options.
-     * @internal
+     * Filter elements that contain a descendant matching this CSS selector.
      */
-    protected abstract _createCrawler(options: TOptions, config?: Configuration): TCrawler;
+    has?: string;
     /**
-     * Gets the crawler-specific options from the subclass.
-     * @param ctx - The fetch engine context.
-     * @internal
+     * Exclude elements matching this CSS selector.
      */
-    protected abstract _getSpecificCrawlerOptions(ctx: FetchEngineContext): Promise<Partial<TOptions>> | Partial<TOptions>;
+    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 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
+     * Whether to enable strict mode for this specific array mode.
+     * @default false
      */
-    protected abstract _buildResponse(context: TContext): Promise<FetchResponse>;
-    protected buildResponse(context: TContext): Promise<FetchResponse>;
+    strict?: boolean;
+}
+/**
+ * Options for columnar (column-alignment) extraction.
+ */
+interface ColumnarOptions extends BaseModeOptions {
+    type: 'columnar';
     /**
-     * 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 heuristic inference.
+     * If true, tries to find a common parent to infer item wrappers when counts mismatch.
+     * @default false
      */
-    protected abstract executeAction(context: TContext, action: FetchEngineAction): Promise<any>;
+    inference?: boolean;
+}
+/**
+ * Options for segmented (anchor-based) extraction.
+ */
+interface SegmentedOptions extends BaseModeOptions {
+    type: 'segmented';
     /**
-     * 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');
-     * ```
+     * 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`.
      */
-    abstract goto(url: string, params?: GotoActionOptions): Promise<void | FetchResponse>;
+    anchor?: string;
     /**
-     * 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
-     * ```
+     * 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.
      */
-    waitFor(params?: WaitForActionOptions): Promise<void>;
+    relativeTo?: 'anchor' | 'previous';
     /**
-     * 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
+     * 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.
      */
-    click(selector: string): 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';
     /**
-     * Moves mouse to specified position or element.
-     *
-     * @param params - Move parameters (x, y, selector, steps)
+     * CSS selector for items (in 'nested' mode) or the container (in 'columnar'/'segmented' modes).
      */
-    mouseMove(params: {
-        x?: number;
-        y?: number;
-        selector?: string;
-        steps?: number;
-    }): Promise<void>;
-    /**
-     * Clicks at current position or specified position.
-     *
-     * @param params - Click parameters (x, y, button, clickCount, delay)
-     */
-    mouseClick(params: {
-        x?: number;
-        y?: number;
-        button?: 'left' | 'right' | 'middle';
-        clickCount?: number;
-        delay?: number;
-    }): Promise<void>;
-    /**
-     * Types text into current focused element.
-     *
-     * @param text - Text to type
-     * @param delay - Delay between key presses
-     */
-    keyboardType(text: string, delay?: number): Promise<void>;
+    selector: string;
     /**
-     * Presses specified key.
-     *
-     * @param key - Key to press
-     * @param delay - Delay after key press
+     * Filter items/containers that contain a descendant matching this CSS selector.
      */
-    keyboardPress(key: string, delay?: number): Promise<void>;
+    has?: string;
     /**
-     * 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
+     * Exclude items/containers matching this CSS selector.
      */
-    fill(selector: string, value: string): Promise<void>;
+    exclude?: 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
+     * Schema applied recursively to each extracted item.
+     * If omitted, defaults to extracting text.
      */
-    submit(selector?: any, options?: SubmitActionOptions): Promise<void>;
+    items?: ExtractSchema;
     /**
-     * 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
+     * Shortcut for `items` to extract a specific attribute directly.
      */
-    trim(options: TrimActionOptions): Promise<void>;
+    attribute?: 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
+     * 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.
      */
-    pause(message?: string): Promise<void>;
+    mode?: ExtractArrayMode;
+}
+/**
+ * Configuration for extracting an object with multiple properties.
+ */
+interface ExtractObjectSchema extends BaseExtractSchema {
+    type: 'object';
     /**
-     * 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.
+     * Root selector for the object. If provided, sub-properties are searched within this element.
      */
-    evaluate(params: EvaluateActionOptions): Promise<any>;
+    selector?: 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.
+     * Filter the object element based on descendants.
      */
-    extract<T>(schema: ExtractSchema): Promise<T>;
+    has?: string;
     /**
-     * Gets the unique identifier of this engine implementation.
+     * Exclude the object element if it matches this selector.
      */
-    get id(): string;
+    exclude?: string;
     /**
-     * Returns the current state of the engine (cookies)
-     * that can be used to restore the session later.
+     * 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.
      */
-    getState(): Promise<{
-        cookies: Cookie[];
-        sessionState?: any;
-    }>;
+    relativeTo?: 'anchor' | 'previous';
     /**
-     * Gets the execution mode of this engine (`'http'` or `'browser'`).
+     * Explicit order of property extraction.
+     * Useful when using `relativeTo: 'previous'`.
      */
-    get mode(): FetchEngineType;
+    order?: string[];
     /**
-     * Gets the fetch engine context associated with this instance.
+     * Definition of the object's properties and their corresponding extraction schemas.
      */
-    get context(): FetchEngineContext | undefined;
+    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 {
     /**
-     * Initializes the fetch engine with provided context and options.
-     *
-     * @param context - Fetch engine context
-     * @param options - Configuration options
-     * @returns Promise resolving when initialization completes
+     * The function or expression to execute.
      *
      * @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()`.
+     * 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.
      */
-    initialize(context: FetchEngineContext, options?: BaseFetcherProperties): Promise<void>;
-    cleanup(): Promise<void>;
+    fn: string | ((...args: any[]) => any);
     /**
-     * Gets the initial scope for extraction for the specific engine.
-     * @param context - Crawlee crawling context
-     * @internal
+     * Data to pass to the function.
+     *
+     * @remarks
+     * This value is passed as the first and only argument to the function defined in {@link fn}.
+     * Recommended to use an array or object for multiple values.
      */
-    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.
-     *
-     * **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, error?: Error): Promise<void>;
-    protected dispatchAction<T>(action: FetchEngineAction): Promise<T>;
-    private _requestHandler;
-    private _failedRequestHandler;
-    protected _commonCleanup(): 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;
     /**
-     * Blocks specified resource types from loading.
+     * Registers a fetch engine implementation with the global registry.
      *
-     * @param types - Resource types to block
-     * @param overwrite - Whether to replace existing blocked types
-     * @returns Number of blocked resource types
+     * @param engineClass - The engine class to register
+     * @throws {Error} When engine class lacks static `id` or ID is already registered
      *
      * @example
      * ```ts
-     * await engine.blockResources(['image', 'stylesheet']);
-     * await engine.blockResources(['script'], true); // Replace existing
+     * FetchEngine.register(CheerioFetchEngine);
      * ```
      */
-    blockResources(types: ResourceType[], overwrite?: boolean): Promise<number>;
+    static register(engineClass: AnyFetchEngineCtor): void;
     /**
-     * Gets content of current page.
+     * Retrieves a fetch engine implementation by its unique ID.
      *
-     * @returns Promise resolving to fetch response
-     * @throws {Error} When no content has been fetched yet
+     * @param id - The ID of the engine to retrieve
+     * @returns Engine class if found, otherwise `undefined`
      */
-    getContent(): Promise<FetchResponse>;
+    static get(id: string): AnyFetchEngineCtor | undefined;
     /**
-     * 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
+     * Retrieves a fetch engine implementation by execution mode.
      *
-     * @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');
-     * ```
+     * @param mode - Execution mode (`'http'` or `'browser'`)
+     * @returns Engine class if found, otherwise `undefined`
      */
-    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 getByMode(mode: FetchEngineType): AnyFetchEngineCtor | undefined;
     /**
-     * Manages cookies for current session with multiple overloads.
-     *
-     * @overload
-     * Gets all cookies.
-     * @returns Array of cookies
+     * Factory method to create and initialize a fetch engine instance.
      *
-     * @overload
-     * Sets cookies for session.
-     * @param cookies - Cookies to set
-     * @returns `true` if successful
+     * @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
-     * const cookies = await engine.cookies();
-     * await engine.cookies([{ name: 'session', value: '123' }]);
-     * ```
+     * @remarks
+     * Primary entry point for engine creation. Selects appropriate implementation based on `engine` name of the option or context.
      */
-    cookies(): Promise<Cookie[]>;
-    cookies(cookies: Cookie[]): Promise<boolean>;
+    static create(ctx: FetchEngineContext, options?: BaseFetcherProperties): Promise<AnyFetchEngine | undefined>;
     /**
-     * Disposes of engine, cleaning up all resources.
+     * Unique identifier for the engine implementation.
      *
-     * @returns Promise resolving when disposal completes
-     */
-    dispose(): Promise<void>;
-}
-
-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 {
-    /**
-     * The 0-based index of the action in the execution sequence.
-     */
-    index?: number;
-    /**
-     * Error encountered during action execution, if any.
+     * @remarks
+     * Must be defined by concrete implementations. Used for registration and lookup in engine registry.
      */
-    error?: Error;
+    static readonly id: string;
     /**
-     * The nesting depth of the action. Top-level actions (executed directly by the session) have a depth of 0.
+     * Execution mode of the engine (`'http'` or `'browser'`).
+     *
+     * @remarks
+     * Must be defined by concrete implementations. Indicates whether engine operates at HTTP level or uses full browser.
      */
-    depth?: number;
-}
-/**
- * Base internal state used by fetch engines to maintain their runtime environment.
- *
- * @internal
- */
-interface BaseFetchContextInteralState {
+    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;
+    };
     /**
-     * The active engine instance (e.g., CheerioFetchEngine or PlaywrightFetchEngine)
-     * associated with this context.
+     * Finds all elements matching the selector within the given scope.
+     *
+     * @param scope - The scope to search in (Engine-specific element/node or array of nodes).
+     * @param selector - CSS selector.
+     * @returns List of matching elements.
+     * @see {@link IExtractEngine._querySelectorAll} for behavior contract.
+     * @internal
      */
-    engine?: FetchEngine;
+    abstract _querySelectorAll(scope: FetchElementScope, selector: string): Promise<FetchElementScope[]>;
     /**
-     * Additional implementation-specific internal state.
+     * Extracts a primitive value from the element based on schema.
+     *
+     * @param schema - Value extraction schema.
+     * @param scope - The element scope.
+     * @returns Extracted value.
+     * @see {@link IExtractEngine._extractValue} for behavior contract.
+     * @internal
      */
-    [key: string]: any;
-}
-/**
- * Extended internal state for the fetch context, including action lifecycle management.
- *
- * @internal
- */
-interface FetchContextInteralState extends BaseFetchContextInteralState {
+    abstract _extractValue(schema: ExtractValueSchema, scope: FetchElementScope): Promise<any>;
     /**
-     * Stack of actions currently being executed, used to manage nested action calls.
+     * Gets the parent element of the given element.
+     *
+     * @param scope - The element scope.
+     * @returns Parent element or null.
+     * @internal
      */
-    actionStack?: FetchActionInContext[];
+    abstract _parentElement(scope: FetchElementScope): Promise<FetchElementScope | null>;
     /**
-     * Global counter for actions executed within the session, used to assign auto-incrementing indices.
+     * 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
      */
-    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 _isSameElement(scope1: FetchElementScope, scope2: FetchElementScope): Promise<boolean>;
     /**
-     * Unique identifier for the session or request batch.
+     * 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
      */
-    id: string;
+    abstract _nextSiblingsUntil(scope: FetchElementScope, untilSelector?: string): Promise<FetchElementScope[]>;
     /**
-     * The target URL for the next navigation, if specified.
+     * 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
      */
-    url?: string;
+    abstract _findClosestAncestor(scope: FetchElementScope, candidates: FetchElementScope[]): Promise<FetchElementScope | null>;
     /**
-     * The final URL after all redirects have been followed.
+     * 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
      */
-    finalUrl?: string;
+    abstract _contains(container: FetchElementScope, element: FetchElementScope): Promise<boolean>;
     /**
-     * The standardized response object from the most recent navigation.
+     * 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
      */
-    lastResponse?: FetchResponse;
+    abstract _findCommonAncestor(scope1: FetchElementScope, scope2: FetchElementScope): Promise<FetchElementScope | null>;
     /**
-     * The result object from the most recent action execution.
+     * 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
      */
-    lastResult?: FetchActionResult;
+    abstract _findContainerChild(element: FetchElementScope, container: FetchElementScope): Promise<FetchElementScope | null>;
+    protected _extract(schema: ExtractSchema, scope: FetchElementScope, parentStrict?: boolean): Promise<any>;
     /**
-     * Engine-specific internal state.
+     * Normalizes the array extraction mode into an options object.
+     * @param mode - The mode string or options object.
+     * @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 _normalizeArrayMode(mode?: ExtractArrayMode): {
+        type: ExtractArrayModeName;
+    } & any;
     /**
-     * Metadata about the action currently being executed.
+     * Performs standard nested array extraction.
+     * @param items - The schema for each item.
+     * @param elements - The list of item elements.
+     * @internal
      */
-    currentAction?: FetchActionInContext;
+    protected _extractNested(items: ExtractSchema, elements: FetchElementScope[], opts?: {
+        strict?: boolean;
+    }): Promise<any[]>;
     /**
-     * A shared key-value store for storing data extracted from pages or
-     * metadata generated during action execution.
+     * 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
      */
-    outputs: Record<string, any>;
+    protected _extractColumnar(schema: ExtractSchema, container: FetchElementScope, opts?: ColumnarOptions): Promise<any[] | null>;
     /**
-     * Executes a FetchAction within the current context.
+     * Performs segmented extraction (Anchor-based Scanning).
      *
-     * @param actionOptions - Configuration for the action to be executed.
-     * @returns A promise that resolves to the action's result.
+     * @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
      */
-    execute<R extends FetchReturnType = 'any'>(actionOptions: FetchActionOptions): Promise<FetchActionResult<R>>;
+    protected _extractSegmented(schema: ExtractSchema, container: FetchElementScope, opts?: SegmentedOptions): Promise<any[] | null>;
     /**
-     * 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 the action's result.
+     * Creates the crawler instance for the specific engine implementation.
+     * @param options - The final crawler options.
+     * @internal
      */
-    action<R extends FetchReturnType = 'any'>(name: string, params?: any, options?: Partial<FetchActionOptions>): Promise<FetchActionResult<R>>;
+    protected abstract _createCrawler(options: TOptions, config?: Configuration): TCrawler;
     /**
-     * Internal state for engine and lifecycle management.
+     * Gets the crawler-specific options from the subclass.
+     * @param ctx - The fetch engine context.
+     * @internal
      */
-    internal: FetchContextInteralState;
+    protected abstract _getSpecificCrawlerOptions(ctx: FetchEngineContext): Promise<Partial<TOptions>> | Partial<TOptions>;
     /**
-     * The central event bus for publishing and subscribing to session and action events.
+     * 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
      */
-    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 _getRandomDelay(base: number, variance?: number): number;
-    protected _getTrajectory(start: {
-        x: number;
-        y: number;
-    }, end: {
-        x: number;
-        y: number;
-    }, steps?: number): {
-        x: number;
-        y: number;
-    }[];
-    protected _moveToSelector(context: PlaywrightCrawlingContext, selector: string, steps?: number): Promise<{
-        x: number;
-        y: number;
-    }>;
-    protected executeAction(context: PlaywrightCrawlingContext, action: FetchEngineAction): Promise<any>;
-    protected _createCrawler(options: PlaywrightCrawlerOptions, config?: Configuration): PlaywrightCrawler;
-    protected _getSpecificCrawlerOptions(ctx: FetchEngineContext): Promise<Partial<PlaywrightCrawlerOptions>>;
-    goto(url: string, opts?: GotoActionOptions): Promise<FetchResponse>;
-}
-
-declare enum FetchActionResultStatus {
+    protected abstract _buildResponse(context: TContext): Promise<FetchResponse>;
+    protected buildResponse(context: TContext): Promise<FetchResponse>;
     /**
-     * 动作执行失败但未抛出（通常因 failOnError=false）；错误信息在 error 字段
+     * 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
      */
-    Failed = 0,
+    protected abstract executeAction(context: TContext, action: FetchEngineAction): Promise<any>;
     /**
-     * 动作按预期完成（即便产生 warnings）
+     * 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');
+     * ```
      */
-    Success = 1,
+    abstract goto(url: string, params?: GotoActionOptions): Promise<void | FetchResponse>;
     /**
-     * 动作被判定为不执行/降级为 noop（比如引擎不支持且 degradeTo='noop'）
-     * 能力不支持且 degradeTo='noop' 时：status='skipped'，warnings 增加 { code:'capability-not-supported' }
+     * 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
+     * ```
      */
-    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;
+    waitFor(params?: WaitForActionOptions): Promise<void>;
     /**
-     * Action 开始生命周期
-     * 负责：初始化 stack、设置 currentAction、触发事件、调用钩子
+     * 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
      */
-    beforeExec(context: FetchContext, options?: FetchActionProperties): Promise<{
-        entry: FetchActionInContext;
-        collectors: CollectorsRuntime | undefined;
-    }>;
+    click(selector: string): Promise<void>;
     /**
-     * Action 结束生命周期
-     * 负责：调用钩子、赋值lastResult, 触发事件、清理 stack、恢复 currentAction
+     * Moves mouse to specified position or element.
+     *
+     * @param params - Move parameters (x, y, selector, steps)
      */
-    afterExec(context: FetchContext, options?: BaseFetchCollectorActionProperties, result?: FetchActionResult, scope?: {
-        entry: FetchActionInContext;
-        collectors?: CollectorsRuntime;
+    mouseMove(params: {
+        x?: number;
+        y?: number;
+        selector?: string;
+        steps?: number;
     }): 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 {
     /**
-     * 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).
+     * Clicks at current position or specified position.
+     *
+     * @param params - Click parameters (x, y, button, clickCount, delay)
      */
-    id?: string;
+    mouseClick(params: {
+        x?: number;
+        y?: number;
+        button?: 'left' | 'right' | 'middle';
+        clickCount?: number;
+        delay?: number;
+    }): 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.
+     * Scrolls the mouse wheel.
+     *
+     * @param params - Wheel parameters (x, y, selector, deltaX, deltaY, steps)
      */
-    persist?: boolean;
+    mouseWheel(params: {
+        x?: number;
+        y?: number;
+        selector?: string;
+        deltaX?: number;
+        deltaY?: number;
+        steps?: number;
+    }): 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`.
+     * Scrolls the element into view.
+     *
+     * @param params - Scroll parameters (selector)
      */
-    purge?: boolean;
+    scrollIntoView(params: {
+        selector: string;
+    }): Promise<void>;
     /**
-     * Additional Crawlee configuration options.
-     * Allows fine-grained control over the underlying Crawlee instance.
+     * Types text into current focused element.
+     *
+     * @param text - Text to type
+     * @param delay - Delay between key presses
+     */
+    keyboardType(text: string, delay?: number): Promise<void>;
+    /**
+     * Presses specified key.
+     *
+     * @param key - Key to press
+     * @param delay - Delay after key press
+     */
+    keyboardPress(key: string, delay?: number): Promise<void>;
+    /**
+     * Fills input element with specified value.
+     *
+     * @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
+     */
+    fill(selector: string, value: string): Promise<void>;
+    /**
+     * 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
+     */
+    submit(selector?: any, options?: SubmitActionOptions): Promise<void>;
+    /**
+     * Removes elements from the DOM based on selectors and presets.
+     *
+     * @param options - Trim options specifying selectors and presets
+     * @returns Promise resolving when trim operation completes
+     * @throws {Error} When no active page context exists
+     */
+    trim(options: TrimActionOptions): Promise<void>;
+    /**
+     * Pauses execution, allowing for manual intervention or inspection.
+     *
+     * @param message - Optional message to display during pause
+     * @returns Promise resolving when execution is resumed
+     * @throws {Error} When no active page context exists
+     */
+    pause(message?: string): Promise<void>;
+    /**
+     * Executes a custom function or expression within the current page context.
+     *
+     * @remarks
+     * This is a powerful action that allows running custom logic to interact with the DOM,
+     * calculate values, or trigger navigations.
+     *
+     * - In **Browser Mode**, it runs in the real browser.
+     * - In **HTTP Mode**, it runs in a Node.js sandbox with a mocked DOM.
+     *
+     * The action handles automatic navigation if `window.location` is modified.
+     *
+     * @param params - Configuration for the execution, including the function and arguments.
+     * @returns A promise resolving to the result of the execution.
+     * @throws {Error} If no active page context exists or if execution fails.
+     *
+     * @see {@link EvaluateActionOptions} for detailed parameter options and examples.
+     */
+    evaluate(params: EvaluateActionOptions): Promise<any>;
+    /**
+     * Extracts structured data from the current page content.
+     *
+     * @param schema - An object defining the data to extract.
+     * @returns A promise that resolves to an object with the extracted data.
+     */
+    extract<T>(schema: ExtractSchema): Promise<T>;
+    /**
+     * Gets the unique identifier of this engine implementation.
+     */
+    get id(): string;
+    /**
+     * Returns the current state of the engine (cookies)
+     * that can be used to restore the session later.
+     */
+    getState(): Promise<{
+        cookies: Cookie[];
+        sessionState?: any;
+    }>;
+    /**
+     * Gets the execution mode of this engine (`'http'` or `'browser'`).
      */
-    config?: Record<string, any>;
-}
-interface BaseFetcherProperties {
+    get mode(): FetchEngineType;
     /**
-     * 抓取模式
-     *
-     * - `http`: 使用 HTTP 进行抓取
-     * - `browser`: 使用浏览器进行抓取
-     * - `auto`: auto 会走“智能探测”选择 http 或 browser, 但是如果没有启用 smart，并且在站点注册表中没有，那么则等价为 http.
+     * Gets the fetch engine context associated with this instance.
      */
-    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[];
+    get context(): FetchEngineContext | undefined;
     /**
-     * Storage configuration for session isolation and persistence.
+     * Initializes the fetch engine with provided context and options.
+     *
+     * @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()`.
      */
-    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;
+    initialize(context: FetchEngineContext, options?: BaseFetcherProperties): Promise<void>;
+    cleanup(): Promise<void>;
     /**
-     * Unique identifier for the session.
+     * Gets the initial scope for extraction for the specific engine.
+     * @param context - Crawlee crawling context
+     * @internal
      */
-    readonly id: string;
+    protected abstract _getInitialElementScope(context: TContext): FetchElementScope;
     /**
-     * The execution context for this session, containing configurations, event bus, and shared state.
+     * Unified action processor that handles engine-agnostic actions.
+     * @param context - Crawlee crawling context
+     * @param action - Action to execute
+     * @internal
      */
-    readonly context: FetchContext;
-    protected closed: boolean;
+    protected _processAction(context: TContext, action: FetchEngineAction): Promise<any>;
+    protected _handlePause(action: {
+        message?: string;
+    }): Promise<void>;
     /**
-     * Creates a new FetchSession.
+     * Executes all pending fetch engine actions within the current Crawlee request handler context.
      *
-     * @param options - Configuration options for the fetcher.
+     * **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
      */
-    constructor(options?: FetcherOptions);
-    protected _logDebug(category: string, ...args: any[]): void;
+    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>;
     /**
-     * Executes a single action within the session.
+     * Blocks specified resource types from loading.
      *
-     * @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.
+     * @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
+     *
+     * @overload
+     * Sets cookies for session.
+     * @param cookies - Cookies to set
+     * @returns `true` if successful
      *
-     * @returns A promise resolving to the session state, or undefined if no engine is initialized.
+     * @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;
@@ -2644,6 +2720,53 @@ declare class MouseClickAction extends FetchAction {
     };
     onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
 }
+interface ScrollIntoViewParams {
+    selector: string;
+}
+declare class ScrollIntoViewAction extends FetchAction {
+    static id: string;
+    static returnType: "none";
+    static capabilities: {
+        http: "noop";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
+interface MouseWheelParams {
+    /**
+     * Target X coordinate for the mouse wheel event.
+     */
+    x?: number;
+    /**
+     * Target Y coordinate for the mouse wheel event.
+     */
+    y?: number;
+    /**
+     * Selector for the element to scroll. If provided, mouse will move to this element before scrolling.
+     */
+    selector?: string;
+    /**
+     * Horizontal scroll delta.
+     */
+    deltaX?: number;
+    /**
+     * Vertical scroll delta.
+     */
+    deltaY?: number;
+    /**
+     * Number of steps to split the scroll into for simulating human-like behavior.
+     */
+    steps?: number;
+}
+declare class MouseWheelAction extends FetchAction {
+    static id: string;
+    static returnType: "none";
+    static capabilities: {
+        http: "noop";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
 
 interface KeyboardTypeParams {
     text: string;
@@ -2681,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, type OnFetchPauseCallback, PauseAction, type PendingEngineRequest, PlaywrightFetchEngine, type ResourceType, type StorageOptions, SubmitAction, type SubmitActionOptions, TRIM_PRESETS, TrimAction, type TrimActionOptions, type TrimPreset, WaitForAction, type WaitForActionOptions, WebFetcher, fetchWeb };
+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 };