@skrillex1224/playwright-toolkit 2.1.190 → 2.1.192

package/index.d.ts

@@ -1,636 +1,636 @@
-import type { Page, BrowserContext, Browser, ElementHandle } from 'playwright';
-
-// =============================================================================
-// Constants
-// =============================================================================
-export interface CodeType {
-    Success: 0;
-    UnknownError: -1;
-    NotLogin: 30000001;
-    Chaptcha: 30000002;
-    Timeout: 30000003;
-    InitialTimeout: 30000004;
-    OverallTimeout: 30000005;
-}
-
-export interface StatusType {
-    Success: 'SUCCESS';
-    Failed: 'FAILED';
-}
-
-export interface ConstantsModule {
-    Code: CodeType;
-    Status: StatusType;
-    PresetOfLiveViewKey: string;
-    ActorInfo: Record<string, ActorInfoItem>;
-}
-
-export interface ActorShareInfo {
-    mode: 'dom' | 'response';
-    prefix: string;
-    xurl: Array<string | string[]>;
-}
-
-export interface ActorInfoItem {
-    key: string;
-    name: string;
-    icon: string;
-    domain: string;
-    protocol: string;
-    path: string;
-    share: ActorShareInfo;
-    readonly landingUrl: string;
-}
-
-// =============================================================================
-// Errors
-// =============================================================================
-export interface CrawlerErrorInfo {
-    message: string;
-    code?: number;
-    context?: Record<string, any>;
-}
-
-export declare class CrawlerError extends Error {
-    name: 'CrawlerError';
-    code: number;
-    context: Record<string, any>;
-    timestamp: string;
-
-    constructor(info: string | CrawlerErrorInfo);
-    toJSON(): Record<string, any>;
-    static isCrawlerError(error: any): error is CrawlerError;
-    static from(error: Error, options?: { code?: number; context?: Record<string, any> }): CrawlerError;
-}
-
-export interface ErrorsModule {
-    CrawlerError: typeof CrawlerError;
-}
-
-// =============================================================================
-// Logger
-// =============================================================================
-export interface LoggerTemplate {
-    step(
-        step: string,
-        status?: string,
-        details?: string[],
-        level?: 'info' | 'warn' | 'warning' | 'error' | 'success' | 'start'
-    ): void;
-    taskStart(url?: string): void;
-    taskSuccess(): void;
-    taskFail(url?: string, err?: unknown): void;
-    runtimeHeadless(): void;
-    loginInjectSuccess(detail?: string): void;
-    loginInjectSkip(reason?: string): void;
-    loginInjectFail(err?: unknown): void;
-    loginVerifySuccess(detail?: string): void;
-    loginVerifySkip(reason?: string): void;
-    loginVerifyFail(err?: unknown): void;
-    envCheckSuccess(detail?: string): void;
-    envCheckFail(err?: unknown): void;
-    inputQuery(query?: string): void;
-    sendAction(): void;
-    responseListenStart(label?: string, timeoutSec?: number): void;
-    responseListenReady(label?: string): void;
-    responseListenDetected(label?: string): void;
-    responseListenTimeout(label?: string, err?: unknown): void;
-    responseListenEnd(label?: string): void;
-    domWaitStart(label?: string): void;
-    domWaitSuccess(mutationCount?: number, stableTime?: number, wasPaused?: boolean): void;
-    domWaitFail(label?: string, err?: unknown): void;
-    domChunk(length?: number, snippet?: string, paused?: boolean): void;
-    streamChunk(length?: number, snippet?: string): void;
-    streamEventsParsed(count?: number): void;
-    streamCompleteEvent(): void;
-    streamEnd(): void;
-    responseWaitStart(label?: string): void;
-    responseWaitSuccess(label?: string): void;
-    responseWaitFail(label?: string, err?: unknown): void;
-    responseWaitRetry(label?: string, attempt?: number): void;
-    referenceExpandStart(label?: string): void;
-    referenceExpandFail(err?: unknown): void;
-    screenshotStart(): void;
-    screenshotSuccess(): void;
-    screenshotFail(err?: unknown): void;
-    shareStart(): void;
-    shareProgress(label?: string): void;
-    shareDomHit(link?: string, domSnapshot?: string): void;
-    shareSource(source?: 'response' | 'dom' | 'none' | string, link?: string, domSnapshot?: string): void;
-    shareSuccess(link?: string): void;
-    shareFail(err?: unknown): void;
-    shareSkip(reason?: string): void;
-    dataPushSuccess(label?: string): void;
-    dataPushFail(err?: unknown): void;
-    popupDetected(detail?: string): void;
-    popupCloseAttempt(detail?: string): void;
-    popupCloseSuccess(): void;
-    popupCloseFail(err?: unknown): void;
-    info(message: string): void;
-    success(message: string): void;
-    warning(message: string): void;
-    warn(message: string): void;
-    error(message: string): void;
-    debug(message: string): void;
-    start(message: string): void;
-}
-
-export interface LoggerAdapter {
-    info(message: string): void;
-    warning?(message: string): void;
-    warn?(message: string): void;
-    error(message: string): void;
-    debug?(message: string): void;
-}
-
-export interface LoggerModule {
-    info(message: string): void;
-    success(message: string): void;
-    warning(message: string): void;
-    warn(message: string): void;
-    error(message: string): void;
-    debug(message: string): void;
-    start(message: string): void;
-    setLogger(logger: LoggerAdapter | null): void;
-    useTemplate(logger?: LoggerAdapter | null): LoggerTemplate;
-}
-
-export interface LogTemplate {
-    key: string;
-    label: string;
-    group: string;
-    attention: 'low' | 'medium' | 'high' | 'critical';
-    patterns: RegExp[];
-    defaultSelected?: boolean;
-}
-
-
-// =============================================================================
-// ApifyKit
-// =============================================================================
-export interface RetryOptions {
-    /** 重试次数 */
-    times?: number;
-    /** 重试模式: 'direct' 等待 3 秒后直接重试, 'refresh' 刷新页面后重试 */
-    mode?: 'direct' | 'refresh';
-    /** 重试前的自定义钩子，会替代默认的等待/刷新行为 */
-    before?: (page: Page, attemptNumber: number) => Promise<void>;
-}
-
-export interface RunStepOptions {
-    failActor?: boolean;
-    /** 重试配置 */
-    retry?: RetryOptions;
-}
-
-export interface ApifyKitInstance {
-    runStep<T>(step: string, page: Page | null, actionFn: () => Promise<T>, options?: RunStepOptions): Promise<T>;
-    runStepLoose<T>(step: string, page: Page | null, fn: () => Promise<T>, options?: RunStepOptions): Promise<T>;
-    pushSuccess(data: Record<string, any>, options?: { page?: Page | null }): Promise<void>;
-    pushFailed(error: Error | CrawlerError, meta?: Record<string, any>, options?: { page?: Page | null }): Promise<void>;
-}
-
-export interface ApifyKitModule {
-    useApifyKit(): Promise<ApifyKitInstance>;
-}
-
-// =============================================================================
-// Humanize
-// =============================================================================
-export interface HumanTypeOptions {
-    baseDelay?: number;
-    jitterPercent?: number;
-}
-
-export interface HumanClickOptions {
-    reactionDelay?: number;
-    jitterPercent?: number;
-    throwOnMissing?: boolean;
-    scrollIfNeeded?: boolean;
-}
-
-export interface HumanizeModule {
-    initializeCursor(page: Page): Promise<void>;
-    jitterMs(base: number, jitterPercent?: number): number;
-    humanType(page: Page, selector: string, text: string, options?: HumanTypeOptions): Promise<void>;
-    humanClick(page: Page, target: string | ElementHandle, options?: HumanClickOptions): Promise<void>;
-    warmUpBrowsing(page: Page, baseDuration?: number): Promise<void>;
-    simulateGaze(page: Page, baseDurationMs?: number): Promise<void>;
-    randomSleep(baseMs: number, jitterPercent?: number): Promise<void>;
-}
-
-// =============================================================================
-// AntiCheat
-// =============================================================================
-export interface AntiDetectConfig {
-    locale: string;
-    acceptLanguage: string;
-    timezoneId: string;
-    timezoneOffset: number;
-    geolocation: { latitude: number; longitude: number; accuracy?: number } | null;
-}
-
-export interface AntiDetectApplyOptions {
-    locale?: string;
-    acceptLanguage?: string;
-    timezoneId?: string;
-    timezoneOffset?: number;
-    geolocation?: { latitude: number; longitude: number; accuracy?: number } | null;
-    permissions?: string[];
-}
-
-export interface AntiDetectModule {
-    getBaseConfig(): AntiDetectConfig;
-    getFingerprintGeneratorOptions(): Record<string, any>;
-    getLaunchArgs(): string[];
-    getAdvancedLaunchArgs(): string[];
-    applyContext(context: BrowserContext, options?: AntiDetectApplyOptions): Promise<void>;
-    applyPage(page: Page, options?: AntiDetectApplyOptions): Promise<void>;
-    syncViewportWithScreen(page: Page): Promise<void>;
-    getTlsFingerprintOptions(userAgent?: string, acceptLanguage?: string): Record<string, any>;
-    applyLocaleHeaders(headers: Record<string, string>, acceptLanguage?: string): Record<string, string>;
-}
-
-// =============================================================================
-// Launch
-// =============================================================================
-export interface LaunchOptions {
-    headless?: boolean;
-    args?: string[];
-    ignoreDefaultArgs?: string[];
-    proxy?: {
-        server: string;
-        username?: string;
-        password?: string;
-        bypass?: string;
-    };
-    [key: string]: any;
-}
-
-export interface ProxyConfiguration {
-    proxy_url?: string;
-    by_pass_domains?: string[];
-    enable_proxy?: boolean;
-}
-
-export interface CrawlerBaseOptions {
-    maxConcurrency: number;
-    maxRequestRetries: number;
-    requestHandlerTimeoutSecs: number;
-    navigationTimeoutSecs: number;
-    headless: boolean;
-    browserPoolOptions: {
-        useFingerprints: boolean;
-        fingerprintOptions: {
-            fingerprintGeneratorOptions: Record<string, any>;
-        };
-    };
-    launchContext: {
-        launcher?: any;
-        useIncognitoPages: boolean;
-        launchOptions: LaunchOptions;
-    };
-}
-
-export interface CrawlerNavigationHook {
-    (crawlingContext: any, gotoOptions: Record<string, any>): Promise<void> | void;
-}
-
-export interface GetPlaywrightCrawlerOptionsInput {
-    customArgs?: string[];
-    proxyConfiguration?: ProxyConfiguration;
-    log?: {
-        enable: boolean;
-    };
-    runInHeadfulMode?: boolean;
-    debugMode?: boolean;
-    isRunningOnApify?: boolean;
-    launcher?: any;
-    runtimeState?: RuntimeEnvState | null;
-    preNavigationHooks?: CrawlerNavigationHook[];
-    postNavigationHooks?: CrawlerNavigationHook[];
-}
-
-export interface PlaywrightCrawlerOptions extends CrawlerBaseOptions {
-    preNavigationHooks: CrawlerNavigationHook[];
-    postNavigationHooks?: CrawlerNavigationHook[];
-}
-
-export interface LaunchModule {
-    getPlaywrightCrawlerOptions(options?: GetPlaywrightCrawlerOptionsInput): PlaywrightCrawlerOptions;
-}
-
-// =============================================================================
-// LiveView
-// =============================================================================
-export interface LiveViewInstance {
-    startLiveViewServer(): Promise<void>;
-    takeLiveScreenshot(page: Page, label?: string): Promise<void>;
-}
-
-export interface LiveViewModule {
-    useLiveView(): LiveViewInstance;
-}
-
-// =============================================================================
-// Captcha
-// =============================================================================
-export interface CaptchaMonitorOptions {
-    domSelector?: string;
-    urlPattern?: string;
-    onDetected?: () => Promise<void>;
-}
-
-export interface CaptchaModule {
-    useCaptchaMonitor(page: Page, options: CaptchaMonitorOptions): { stop: () => Promise<void> };
-}
-
-// =============================================================================
-// Utils
-// =============================================================================
-export interface ParsedCookie {
-    name: string;
-    value: string;
-    domain: string;
-    path?: string;
-}
-
-export interface UtilsModule {
-    parseCookies(cookieString: string, domain: string): ParsedCookie[];
-    parseLinks(text: string, options?: { prefix?: string }): string[];
-}
-
-export interface RuntimeEnvState {
-    actor: string;
-    runtime: Record<string, any>;
-    envId: string;
-    auth: Record<string, string>;
-    cookies: ParsedCookie[];
-    cookieMap: Record<string, string>;
-    localStorage: Record<string, string>;
-    sessionStorage: Record<string, string>;
-    browserProfile: {
-        core?: Record<string, any>;
-        observed?: Record<string, any>;
-    };
-    browserProfileCore: Record<string, any>;
-    browserProfileObserved: Record<string, any>;
-}
-
-export interface RuntimeEnvApplyOptions {
-    actor?: string;
-}
-
-export interface RuntimeEnvSnapshot {
-    page_url?: string;
-    pageUrl?: string;
-    frame_urls?: string[];
-    frameUrls?: string[];
-    resource_urls?: string[];
-    resourceUrls?: string[];
-    cookies?: Array<Record<string, any>>;
-    local_storage?: Record<string, any>;
-    localStorage?: Record<string, any>;
-    session_storage?: Record<string, any>;
-    sessionStorage?: Record<string, any>;
-    browser_profile?: Record<string, any>;
-    browserProfile?: Record<string, any>;
-    browser_profile_observed?: Record<string, any>;
-    browserProfileObserved?: Record<string, any>;
-    auth?: Record<string, any>;
-}
-
-export interface RuntimeEnvModule {
-    parseInput(input?: Record<string, any>, actor?: string): RuntimeEnvState;
-    buildEnvPatch(source?: Record<string, any>, actor?: string): Record<string, any> | null;
-    normalizeSnapshot(snapshot?: RuntimeEnvSnapshot): RuntimeEnvSnapshot;
-    collectCookieUrls(snapshot?: RuntimeEnvSnapshot): string[];
-    buildRuntimeEnvFromSnapshot(snapshot?: RuntimeEnvSnapshot, options?: { browserProfileCore?: Record<string, any>; auth?: Record<string, any> }): Record<string, any> | null;
-    buildEnvPatchFromSnapshot(snapshot?: RuntimeEnvSnapshot, options?: { browserProfileCore?: Record<string, any>; auth?: Record<string, any> }): Record<string, any> | null;
-    mergeEnvPatches(...patches: Array<Record<string, any> | null | undefined>): Record<string, any> | null;
-    hasLoginState(source?: Record<string, any>, actor?: string): boolean;
-    getAuthValue(source?: Record<string, any>, key?: string, actor?: string): string;
-    rememberState(source?: Record<string, any>): RuntimeEnvState | null;
-    peekRememberedState(): RuntimeEnvState | null;
-    getBrowserProfileCore(source?: Record<string, any>, actor?: string): Record<string, any>;
-    setBrowserProfileCore(source?: Record<string, any>, core?: Record<string, any>, actor?: string): RuntimeEnvState;
-    applyToPage(page: Page, source?: Record<string, any>, options?: RuntimeEnvApplyOptions): Promise<void>;
-    captureEnvPatch(page: Page | null, source?: Record<string, any>, options?: RuntimeEnvApplyOptions): Promise<Record<string, any> | null>;
-    tryParseJSON(value: any): any;
-    normalizeCookies(value: any): ParsedCookie[];
-    normalizeLocalStorage(value: any): Record<string, string>;
-    normalizeSessionStorage(value: any): Record<string, string>;
-    normalizeAuth(value: any): Record<string, string>;
-    normalizeBrowserProfileCore(value: any): Record<string, any>;
-    normalizeObservedBrowserProfile(value: any): Record<string, any>;
-}
-
-// =============================================================================
-// Share
-// =============================================================================
-export interface ShareLinkCaptureOptions {
-    share: {
-        mode?: 'dom' | 'response';
-        /** 允许空串 ''，但不允许 undefined/null */
-        prefix: string;
-        xurl?: Array<string | string[]>;
-    };
-    timeoutMs?: number;
-    payloadSnapshotMaxLen?: number;
-    domSelectors?: string | string[];
-    domMode?: 'added' | 'changed' | 'all';
-    performActions?: () => Promise<void>;
-}
-
-export interface ShareLinkCaptureResult {
-    link: string | null;
-    payloadText: string;
-    payloadSnapshot: string;
-    source: 'response' | 'dom' | 'none';
-}
-
-export interface ShareScreenCaptureOptions {
-    /** 额外缓冲高度 (默认: 视口高度的一半) */
-    buffer?: number;
-    /** 截图后是否恢复页面高度和样式 (默认: false) */
-    restore?: boolean;
-    /** 最大截图高度 (默认: 8000px) */
-    maxHeight?: number;
-}
-
-export interface ShareModule {
-    captureLink(page: Page, options?: ShareLinkCaptureOptions): Promise<ShareLinkCaptureResult>;
-    captureScreen(page: Page, options?: ShareScreenCaptureOptions): Promise<string>;
-}
-
-// =============================================================================
-// Display
-// =============================================================================
-export interface DisplayModule {
-    parseTokenDisplayName(value?: string): { owner: string; envType: string; note: string };
-    parseEnvDisplayName(value?: string): { env: string; owner: string; envType: string; note: string };
-    buildTokenDisplayName(input: { owner: string; envType: string; note?: string }): string;
-    shortId(value?: string, max?: number): string;
-    resolveTokenIdentity(
-        displayName?: string,
-        tokenId?: string
-    ): { primary: string; secondary: string; fullId: string; shortId: string };
-    resolveEnvIdentity(
-        displayName?: string,
-        envId?: string
-    ): { primary: string; secondary: string; fullId: string; shortId: string; parts: { env: string; owner: string; envType: string; note: string } };
-}
-
-// =============================================================================
-// Mutation
-// =============================================================================
-export interface MutationNodeSnapshot {
-    /** 节点 HTML 快照（实际来源 outerHTML） */
-    html: string;
-    /** 节点文本快照（实际来源 innerText/textContent） */
-    text: string;
-    /** 变化类型 */
-    mutationType: string;
-}
-
-export interface OnMutationContext {
-    /** 当前累计变化次数 */
-    mutationCount: number;
-    /** 本次变化节点聚合 HTML（实际来源 outerHTML） */
-    html: string;
-    /** 本次变化节点聚合文本（实际来源 innerText） */
-    text: string;
-    /** 本次全部变化节点快照 */
-    mutationNodes: MutationNodeSnapshot[];
-}
-
-export interface WaitForStableOptions {
-    /** 等待元素出现的超时 (毫秒, 默认: 30000) */
-    initialTimeout?: number;
-    /** 无变化持续时间后 resolve (毫秒, 默认: 5000) */
-    stableTime?: number;
-    /** 整体超时时间 (毫秒, 默认: 120000) */
-    timeout?: number;
-    /** 变化时的回调钩子
-     * 返回 null/undefined: 正常重置稳定计时
-     * 返回其他值: 暂停稳定计时（timeout 仍然生效）
-     */
-    onMutation?: (context: OnMutationContext) => any;
-}
-
-export interface WaitForStableResult {
-    /** 总变化次数 */
-    mutationCount: number;
-    /** 稳定时长 */
-    stableTime: number;
-    /** 是否曾经暂停过计时 */
-    wasPaused: boolean;
-}
-
-export type MutationMonitorMode = 'added' | 'changed' | 'all';
-
-export interface MutationModeConstants {
-    Added: 'added';
-    Changed: 'changed';
-    All: 'all';
-}
-
-export interface useMonitorOptions {
-    /** 变化时的回调 */
-    onMutation?: (context: OnMutationContext) => void;
-    /** 监控模式 (默认 'added') */
-    mode?: MutationMonitorMode;
-}
-
-export interface MutationMonitor {
-    /** 停止监控并返回统计 */
-    stop: () => Promise<{ totalMutations: number }>;
-}
-
-export interface MutationModule {
-    /** 监控模式常量 */
-    Mode: MutationModeConstants;
-    /** 等待 DOM 元素稳定（无变化） */
-    waitForStable(page: Page, selectors: string | string[], options?: WaitForStableOptions): Promise<WaitForStableResult>;
-    /** 等待跨 root DOM 元素稳定（主文档 + iframe 内容） */
-    waitForStableAcrossRoots(page: Page, selectors: string | string[], options?: WaitForStableOptions): Promise<WaitForStableResult>;
-    /** 创建持续监控 DOM 变化的监控器，selectors 支持 'document.documentElement' */
-    useMonitor(page: Page, selectors: string | string[], options?: useMonitorOptions): Promise<MutationMonitor>;
-}
-
-// =============================================================================
-// ByPass Matcher
-// =============================================================================
-export interface ByPassDomainRule {
-    pattern: string;
-    test(hostname: string): boolean;
-}
-
-export interface ByPassMatchResult {
-    rule: ByPassDomainRule | null;
-    hostname: string;
-}
-
-export interface ByPassRouteResult {
-    route: 'direct' | 'proxy';
-    matchedRule: ByPassDomainRule | null;
-    hostname: string;
-}
-
-export interface ResolveRouteByProxyInput {
-    requestUrl?: string;
-    enableProxy?: boolean;
-    byPassRules?: ByPassDomainRule[];
-}
-
-export interface ByPassModule {
-    normalizeByPassDomains(domains: unknown): string[];
-    normalizeHostname(value?: string): string;
-    buildByPassDomainRule(rawPattern: string): ByPassDomainRule | null;
-    buildByPassDomainRules(domains?: unknown): ByPassDomainRule[];
-    findMatchedByPassRule(rules?: ByPassDomainRule[], requestUrl?: string): ByPassMatchResult | null;
-    isDomainCoveredByByPass(domain?: string, rules?: ByPassDomainRule[]): boolean;
-    resolveRouteByProxy(input?: ResolveRouteByProxyInput): ByPassRouteResult;
-}
-
-// =============================================================================
-// Toolkit Entry Point
-// =============================================================================
-
-/** Node.js version of the toolkit */
-export interface PlaywrightToolKit {
-    ApifyKit: ApifyKitModule;
-    AntiCheat: AntiDetectModule;
-    Humanize: HumanizeModule;
-    Launch: LaunchModule;
-    LiveView: LiveViewModule;
-    Constants: ConstantsModule;
-    Utils: UtilsModule;
-    RuntimeEnv: RuntimeEnvModule;
-    Display: DisplayModule;
-    Captcha: CaptchaModule;
-    Errors: ErrorsModule;
-    Mutation: MutationModule;
-    ByPass: ByPassModule;
-    Logger: LoggerModule;
-    Share: ShareModule;
-    $Internals: {
-        LOG_TEMPLATES: LogTemplate[];
-        stripAnsi(input: string): string;
-    };
-}
-
-/** Browser/Extension version of the toolkit */
-export interface BrowserPlaywrightToolKit {
-    Logger: LoggerModule;
-    Display: DisplayModule;
-    ByPass: ByPassModule;
-    Constants: ConstantsModule;
-    RuntimeEnv: RuntimeEnvModule;
-    $Internals: {
-        LOG_TEMPLATES: LogTemplate[];
-        stripAnsi(input: string): string;
-    };
-}
-
-export declare function usePlaywrightToolKit(): PlaywrightToolKit;
+import type { Page, BrowserContext, Browser, ElementHandle } from 'playwright';
+
+// =============================================================================
+// Constants
+// =============================================================================
+export interface CodeType {
+    Success: 0;
+    UnknownError: -1;
+    NotLogin: 30000001;
+    Chaptcha: 30000002;
+    Timeout: 30000003;
+    InitialTimeout: 30000004;
+    OverallTimeout: 30000005;
+}
+
+export interface StatusType {
+    Success: 'SUCCESS';
+    Failed: 'FAILED';
+}
+
+export interface ConstantsModule {
+    Code: CodeType;
+    Status: StatusType;
+    PresetOfLiveViewKey: string;
+    ActorInfo: Record<string, ActorInfoItem>;
+}
+
+export interface ActorShareInfo {
+    mode: 'dom' | 'response';
+    prefix: string;
+    xurl: Array<string | string[]>;
+}
+
+export interface ActorInfoItem {
+    key: string;
+    name: string;
+    icon: string;
+    domain: string;
+    protocol: string;
+    path: string;
+    share: ActorShareInfo;
+    readonly landingUrl: string;
+}
+
+// =============================================================================
+// Errors
+// =============================================================================
+export interface CrawlerErrorInfo {
+    message: string;
+    code?: number;
+    context?: Record<string, any>;
+}
+
+export declare class CrawlerError extends Error {
+    name: 'CrawlerError';
+    code: number;
+    context: Record<string, any>;
+    timestamp: string;
+
+    constructor(info: string | CrawlerErrorInfo);
+    toJSON(): Record<string, any>;
+    static isCrawlerError(error: any): error is CrawlerError;
+    static from(error: Error, options?: { code?: number; context?: Record<string, any> }): CrawlerError;
+}
+
+export interface ErrorsModule {
+    CrawlerError: typeof CrawlerError;
+}
+
+// =============================================================================
+// Logger
+// =============================================================================
+export interface LoggerTemplate {
+    step(
+        step: string,
+        status?: string,
+        details?: string[],
+        level?: 'info' | 'warn' | 'warning' | 'error' | 'success' | 'start'
+    ): void;
+    taskStart(url?: string): void;
+    taskSuccess(): void;
+    taskFail(url?: string, err?: unknown): void;
+    runtimeHeadless(): void;
+    loginInjectSuccess(detail?: string): void;
+    loginInjectSkip(reason?: string): void;
+    loginInjectFail(err?: unknown): void;
+    loginVerifySuccess(detail?: string): void;
+    loginVerifySkip(reason?: string): void;
+    loginVerifyFail(err?: unknown): void;
+    envCheckSuccess(detail?: string): void;
+    envCheckFail(err?: unknown): void;
+    inputQuery(query?: string): void;
+    sendAction(): void;
+    responseListenStart(label?: string, timeoutSec?: number): void;
+    responseListenReady(label?: string): void;
+    responseListenDetected(label?: string): void;
+    responseListenTimeout(label?: string, err?: unknown): void;
+    responseListenEnd(label?: string): void;
+    domWaitStart(label?: string): void;
+    domWaitSuccess(mutationCount?: number, stableTime?: number, wasPaused?: boolean): void;
+    domWaitFail(label?: string, err?: unknown): void;
+    domChunk(length?: number, snippet?: string, paused?: boolean): void;
+    streamChunk(length?: number, snippet?: string): void;
+    streamEventsParsed(count?: number): void;
+    streamCompleteEvent(): void;
+    streamEnd(): void;
+    responseWaitStart(label?: string): void;
+    responseWaitSuccess(label?: string): void;
+    responseWaitFail(label?: string, err?: unknown): void;
+    responseWaitRetry(label?: string, attempt?: number): void;
+    referenceExpandStart(label?: string): void;
+    referenceExpandFail(err?: unknown): void;
+    screenshotStart(): void;
+    screenshotSuccess(): void;
+    screenshotFail(err?: unknown): void;
+    shareStart(): void;
+    shareProgress(label?: string): void;
+    shareDomHit(link?: string, domSnapshot?: string): void;
+    shareSource(source?: 'response' | 'dom' | 'none' | string, link?: string, domSnapshot?: string): void;
+    shareSuccess(link?: string): void;
+    shareFail(err?: unknown): void;
+    shareSkip(reason?: string): void;
+    dataPushSuccess(label?: string): void;
+    dataPushFail(err?: unknown): void;
+    popupDetected(detail?: string): void;
+    popupCloseAttempt(detail?: string): void;
+    popupCloseSuccess(): void;
+    popupCloseFail(err?: unknown): void;
+    info(message: string): void;
+    success(message: string): void;
+    warning(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+    start(message: string): void;
+}
+
+export interface LoggerAdapter {
+    info(message: string): void;
+    warning?(message: string): void;
+    warn?(message: string): void;
+    error(message: string): void;
+    debug?(message: string): void;
+}
+
+export interface LoggerModule {
+    info(message: string): void;
+    success(message: string): void;
+    warning(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+    start(message: string): void;
+    setLogger(logger: LoggerAdapter | null): void;
+    useTemplate(logger?: LoggerAdapter | null): LoggerTemplate;
+}
+
+export interface LogTemplate {
+    key: string;
+    label: string;
+    group: string;
+    attention: 'low' | 'medium' | 'high' | 'critical';
+    patterns: RegExp[];
+    defaultSelected?: boolean;
+}
+
+
+// =============================================================================
+// ApifyKit
+// =============================================================================
+export interface RetryOptions {
+    /** 重试次数 */
+    times?: number;
+    /** 重试模式: 'direct' 等待 3 秒后直接重试, 'refresh' 刷新页面后重试 */
+    mode?: 'direct' | 'refresh';
+    /** 重试前的自定义钩子，会替代默认的等待/刷新行为 */
+    before?: (page: Page, attemptNumber: number) => Promise<void>;
+}
+
+export interface RunStepOptions {
+    failActor?: boolean;
+    /** 重试配置 */
+    retry?: RetryOptions;
+}
+
+export interface ApifyKitInstance {
+    runStep<T>(step: string, page: Page | null, actionFn: () => Promise<T>, options?: RunStepOptions): Promise<T>;
+    runStepLoose<T>(step: string, page: Page | null, fn: () => Promise<T>, options?: RunStepOptions): Promise<T>;
+    pushSuccess(data: Record<string, any>, options?: { page?: Page | null }): Promise<void>;
+    pushFailed(error: Error | CrawlerError, meta?: Record<string, any>, options?: { page?: Page | null }): Promise<void>;
+}
+
+export interface ApifyKitModule {
+    useApifyKit(): Promise<ApifyKitInstance>;
+}
+
+// =============================================================================
+// Humanize
+// =============================================================================
+export interface HumanTypeOptions {
+    baseDelay?: number;
+    jitterPercent?: number;
+}
+
+export interface HumanClickOptions {
+    reactionDelay?: number;
+    jitterPercent?: number;
+    throwOnMissing?: boolean;
+    scrollIfNeeded?: boolean;
+}
+
+export interface HumanizeModule {
+    initializeCursor(page: Page): Promise<void>;
+    jitterMs(base: number, jitterPercent?: number): number;
+    humanType(page: Page, selector: string, text: string, options?: HumanTypeOptions): Promise<void>;
+    humanClick(page: Page, target: string | ElementHandle, options?: HumanClickOptions): Promise<void>;
+    warmUpBrowsing(page: Page, baseDuration?: number): Promise<void>;
+    simulateGaze(page: Page, baseDurationMs?: number): Promise<void>;
+    randomSleep(baseMs: number, jitterPercent?: number): Promise<void>;
+}
+
+// =============================================================================
+// AntiCheat
+// =============================================================================
+export interface AntiDetectConfig {
+    locale: string;
+    acceptLanguage: string;
+    timezoneId: string;
+    timezoneOffset: number;
+    geolocation: { latitude: number; longitude: number; accuracy?: number } | null;
+}
+
+export interface AntiDetectApplyOptions {
+    locale?: string;
+    acceptLanguage?: string;
+    timezoneId?: string;
+    timezoneOffset?: number;
+    geolocation?: { latitude: number; longitude: number; accuracy?: number } | null;
+    permissions?: string[];
+}
+
+export interface AntiDetectModule {
+    getBaseConfig(): AntiDetectConfig;
+    getFingerprintGeneratorOptions(): Record<string, any>;
+    getLaunchArgs(): string[];
+    getAdvancedLaunchArgs(): string[];
+    applyContext(context: BrowserContext, options?: AntiDetectApplyOptions): Promise<void>;
+    applyPage(page: Page, options?: AntiDetectApplyOptions): Promise<void>;
+    syncViewportWithScreen(page: Page): Promise<void>;
+    getTlsFingerprintOptions(userAgent?: string, acceptLanguage?: string): Record<string, any>;
+    applyLocaleHeaders(headers: Record<string, string>, acceptLanguage?: string): Record<string, string>;
+}
+
+// =============================================================================
+// Launch
+// =============================================================================
+export interface LaunchOptions {
+    headless?: boolean;
+    args?: string[];
+    ignoreDefaultArgs?: string[];
+    proxy?: {
+        server: string;
+        username?: string;
+        password?: string;
+        bypass?: string;
+    };
+    [key: string]: any;
+}
+
+export interface ProxyConfiguration {
+    proxy_url?: string;
+    by_pass_domains?: string[];
+    enable_proxy?: boolean;
+}
+
+export interface CrawlerBaseOptions {
+    maxConcurrency: number;
+    maxRequestRetries: number;
+    requestHandlerTimeoutSecs: number;
+    navigationTimeoutSecs: number;
+    headless: boolean;
+    browserPoolOptions: {
+        useFingerprints: boolean;
+        fingerprintOptions: {
+            fingerprintGeneratorOptions: Record<string, any>;
+        };
+    };
+    launchContext: {
+        launcher?: any;
+        useIncognitoPages: boolean;
+        launchOptions: LaunchOptions;
+    };
+}
+
+export interface CrawlerNavigationHook {
+    (crawlingContext: any, gotoOptions: Record<string, any>): Promise<void> | void;
+}
+
+export interface GetPlaywrightCrawlerOptionsInput {
+    customArgs?: string[];
+    proxyConfiguration?: ProxyConfiguration;
+    log?: {
+        enable: boolean;
+    };
+    runInHeadfulMode?: boolean;
+    debugMode?: boolean;
+    isRunningOnApify?: boolean;
+    launcher?: any;
+    runtimeState?: RuntimeEnvState | null;
+    preNavigationHooks?: CrawlerNavigationHook[];
+    postNavigationHooks?: CrawlerNavigationHook[];
+}
+
+export interface PlaywrightCrawlerOptions extends CrawlerBaseOptions {
+    preNavigationHooks: CrawlerNavigationHook[];
+    postNavigationHooks?: CrawlerNavigationHook[];
+}
+
+export interface LaunchModule {
+    getPlaywrightCrawlerOptions(options?: GetPlaywrightCrawlerOptionsInput): PlaywrightCrawlerOptions;
+}
+
+// =============================================================================
+// LiveView
+// =============================================================================
+export interface LiveViewInstance {
+    startLiveViewServer(): Promise<void>;
+    takeLiveScreenshot(page: Page, label?: string): Promise<void>;
+}
+
+export interface LiveViewModule {
+    useLiveView(): LiveViewInstance;
+}
+
+// =============================================================================
+// Captcha
+// =============================================================================
+export interface CaptchaMonitorOptions {
+    domSelector?: string;
+    urlPattern?: string;
+    onDetected?: () => Promise<void>;
+}
+
+export interface CaptchaModule {
+    useCaptchaMonitor(page: Page, options: CaptchaMonitorOptions): { stop: () => Promise<void> };
+}
+
+// =============================================================================
+// Utils
+// =============================================================================
+export interface ParsedCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+}
+
+export interface UtilsModule {
+    parseCookies(cookieString: string, domain: string): ParsedCookie[];
+    parseLinks(text: string, options?: { prefix?: string }): string[];
+}
+
+export interface RuntimeEnvState {
+    actor: string;
+    runtime: Record<string, any>;
+    envId: string;
+    auth: Record<string, string>;
+    cookies: ParsedCookie[];
+    cookieMap: Record<string, string>;
+    localStorage: Record<string, string>;
+    sessionStorage: Record<string, string>;
+    browserProfile: {
+        core?: Record<string, any>;
+        observed?: Record<string, any>;
+    };
+    browserProfileCore: Record<string, any>;
+    browserProfileObserved: Record<string, any>;
+}
+
+export interface RuntimeEnvApplyOptions {
+    actor?: string;
+}
+
+export interface RuntimeEnvSnapshot {
+    page_url?: string;
+    pageUrl?: string;
+    frame_urls?: string[];
+    frameUrls?: string[];
+    resource_urls?: string[];
+    resourceUrls?: string[];
+    cookies?: Array<Record<string, any>>;
+    local_storage?: Record<string, any>;
+    localStorage?: Record<string, any>;
+    session_storage?: Record<string, any>;
+    sessionStorage?: Record<string, any>;
+    browser_profile?: Record<string, any>;
+    browserProfile?: Record<string, any>;
+    browser_profile_observed?: Record<string, any>;
+    browserProfileObserved?: Record<string, any>;
+    auth?: Record<string, any>;
+}
+
+export interface RuntimeEnvModule {
+    parseInput(input?: Record<string, any>, actor?: string): RuntimeEnvState;
+    buildEnvPatch(source?: Record<string, any>, actor?: string): Record<string, any> | null;
+    normalizeSnapshot(snapshot?: RuntimeEnvSnapshot): RuntimeEnvSnapshot;
+    collectCookieUrls(snapshot?: RuntimeEnvSnapshot): string[];
+    buildRuntimeEnvFromSnapshot(snapshot?: RuntimeEnvSnapshot, options?: { browserProfileCore?: Record<string, any>; auth?: Record<string, any> }): Record<string, any> | null;
+    buildEnvPatchFromSnapshot(snapshot?: RuntimeEnvSnapshot, options?: { browserProfileCore?: Record<string, any>; auth?: Record<string, any> }): Record<string, any> | null;
+    mergeEnvPatches(...patches: Array<Record<string, any> | null | undefined>): Record<string, any> | null;
+    hasLoginState(source?: Record<string, any>, actor?: string): boolean;
+    getAuthValue(source?: Record<string, any>, key?: string, actor?: string): string;
+    rememberState(source?: Record<string, any>): RuntimeEnvState | null;
+    peekRememberedState(): RuntimeEnvState | null;
+    getBrowserProfileCore(source?: Record<string, any>, actor?: string): Record<string, any>;
+    setBrowserProfileCore(source?: Record<string, any>, core?: Record<string, any>, actor?: string): RuntimeEnvState;
+    applyToPage(page: Page, source?: Record<string, any>, options?: RuntimeEnvApplyOptions): Promise<void>;
+    captureEnvPatch(page: Page | null, source?: Record<string, any>, options?: RuntimeEnvApplyOptions): Promise<Record<string, any> | null>;
+    tryParseJSON(value: any): any;
+    normalizeCookies(value: any): ParsedCookie[];
+    normalizeLocalStorage(value: any): Record<string, string>;
+    normalizeSessionStorage(value: any): Record<string, string>;
+    normalizeAuth(value: any): Record<string, string>;
+    normalizeBrowserProfileCore(value: any): Record<string, any>;
+    normalizeObservedBrowserProfile(value: any): Record<string, any>;
+}
+
+// =============================================================================
+// Share
+// =============================================================================
+export interface ShareLinkCaptureOptions {
+    share: {
+        mode?: 'dom' | 'response';
+        /** 允许空串 ''，但不允许 undefined/null */
+        prefix: string;
+        xurl?: Array<string | string[]>;
+    };
+    timeoutMs?: number;
+    payloadSnapshotMaxLen?: number;
+    domSelectors?: string | string[];
+    domMode?: 'added' | 'changed' | 'all';
+    performActions?: () => Promise<void>;
+}
+
+export interface ShareLinkCaptureResult {
+    link: string | null;
+    payloadText: string;
+    payloadSnapshot: string;
+    source: 'response' | 'dom' | 'none';
+}
+
+export interface ShareScreenCaptureOptions {
+    /** 额外缓冲高度 (默认: 视口高度的一半) */
+    buffer?: number;
+    /** 截图后是否恢复页面高度和样式 (默认: false) */
+    restore?: boolean;
+    /** 最大截图高度 (默认: 8000px) */
+    maxHeight?: number;
+}
+
+export interface ShareModule {
+    captureLink(page: Page, options?: ShareLinkCaptureOptions): Promise<ShareLinkCaptureResult>;
+    captureScreen(page: Page, options?: ShareScreenCaptureOptions): Promise<string>;
+}
+
+// =============================================================================
+// Display
+// =============================================================================
+export interface DisplayModule {
+    parseTokenDisplayName(value?: string): { owner: string; envType: string; note: string };
+    parseEnvDisplayName(value?: string): { env: string; owner: string; envType: string; note: string };
+    buildTokenDisplayName(input: { owner: string; envType: string; note?: string }): string;
+    shortId(value?: string, max?: number): string;
+    resolveTokenIdentity(
+        displayName?: string,
+        tokenId?: string
+    ): { primary: string; secondary: string; fullId: string; shortId: string };
+    resolveEnvIdentity(
+        displayName?: string,
+        envId?: string
+    ): { primary: string; secondary: string; fullId: string; shortId: string; parts: { env: string; owner: string; envType: string; note: string } };
+}
+
+// =============================================================================
+// Mutation
+// =============================================================================
+export interface MutationNodeSnapshot {
+    /** 节点 HTML 快照（实际来源 outerHTML） */
+    html: string;
+    /** 节点文本快照（实际来源 innerText/textContent） */
+    text: string;
+    /** 变化类型 */
+    mutationType: string;
+}
+
+export interface OnMutationContext {
+    /** 当前累计变化次数 */
+    mutationCount: number;
+    /** 本次变化节点聚合 HTML（实际来源 outerHTML） */
+    html: string;
+    /** 本次变化节点聚合文本（实际来源 innerText） */
+    text: string;
+    /** 本次全部变化节点快照 */
+    mutationNodes: MutationNodeSnapshot[];
+}
+
+export interface WaitForStableOptions {
+    /** 等待元素出现的超时 (毫秒, 默认: 30000) */
+    initialTimeout?: number;
+    /** 无变化持续时间后 resolve (毫秒, 默认: 5000) */
+    stableTime?: number;
+    /** 整体超时时间 (毫秒, 默认: 120000) */
+    timeout?: number;
+    /** 变化时的回调钩子
+     * 返回 null/undefined: 正常重置稳定计时
+     * 返回其他值: 暂停稳定计时（timeout 仍然生效）
+     */
+    onMutation?: (context: OnMutationContext) => any;
+}
+
+export interface WaitForStableResult {
+    /** 总变化次数 */
+    mutationCount: number;
+    /** 稳定时长 */
+    stableTime: number;
+    /** 是否曾经暂停过计时 */
+    wasPaused: boolean;
+}
+
+export type MutationMonitorMode = 'added' | 'changed' | 'all';
+
+export interface MutationModeConstants {
+    Added: 'added';
+    Changed: 'changed';
+    All: 'all';
+}
+
+export interface useMonitorOptions {
+    /** 变化时的回调 */
+    onMutation?: (context: OnMutationContext) => void;
+    /** 监控模式 (默认 'added') */
+    mode?: MutationMonitorMode;
+}
+
+export interface MutationMonitor {
+    /** 停止监控并返回统计 */
+    stop: () => Promise<{ totalMutations: number }>;
+}
+
+export interface MutationModule {
+    /** 监控模式常量 */
+    Mode: MutationModeConstants;
+    /** 等待 DOM 元素稳定（无变化） */
+    waitForStable(page: Page, selectors: string | string[], options?: WaitForStableOptions): Promise<WaitForStableResult>;
+    /** 等待跨 root DOM 元素稳定（主文档 + iframe 内容） */
+    waitForStableAcrossRoots(page: Page, selectors: string | string[], options?: WaitForStableOptions): Promise<WaitForStableResult>;
+    /** 创建持续监控 DOM 变化的监控器，selectors 支持 'document.documentElement' */
+    useMonitor(page: Page, selectors: string | string[], options?: useMonitorOptions): Promise<MutationMonitor>;
+}
+
+// =============================================================================
+// ByPass Matcher
+// =============================================================================
+export interface ByPassDomainRule {
+    pattern: string;
+    test(hostname: string): boolean;
+}
+
+export interface ByPassMatchResult {
+    rule: ByPassDomainRule | null;
+    hostname: string;
+}
+
+export interface ByPassRouteResult {
+    route: 'direct' | 'proxy';
+    matchedRule: ByPassDomainRule | null;
+    hostname: string;
+}
+
+export interface ResolveRouteByProxyInput {
+    requestUrl?: string;
+    enableProxy?: boolean;
+    byPassRules?: ByPassDomainRule[];
+}
+
+export interface ByPassModule {
+    normalizeByPassDomains(domains: unknown): string[];
+    normalizeHostname(value?: string): string;
+    buildByPassDomainRule(rawPattern: string): ByPassDomainRule | null;
+    buildByPassDomainRules(domains?: unknown): ByPassDomainRule[];
+    findMatchedByPassRule(rules?: ByPassDomainRule[], requestUrl?: string): ByPassMatchResult | null;
+    isDomainCoveredByByPass(domain?: string, rules?: ByPassDomainRule[]): boolean;
+    resolveRouteByProxy(input?: ResolveRouteByProxyInput): ByPassRouteResult;
+}
+
+// =============================================================================
+// Toolkit Entry Point
+// =============================================================================
+
+/** Node.js version of the toolkit */
+export interface PlaywrightToolKit {
+    ApifyKit: ApifyKitModule;
+    AntiCheat: AntiDetectModule;
+    Humanize: HumanizeModule;
+    Launch: LaunchModule;
+    LiveView: LiveViewModule;
+    Constants: ConstantsModule;
+    Utils: UtilsModule;
+    RuntimeEnv: RuntimeEnvModule;
+    Display: DisplayModule;
+    Captcha: CaptchaModule;
+    Errors: ErrorsModule;
+    Mutation: MutationModule;
+    ByPass: ByPassModule;
+    Logger: LoggerModule;
+    Share: ShareModule;
+    $Internals: {
+        LOG_TEMPLATES: LogTemplate[];
+        stripAnsi(input: string): string;
+    };
+}
+
+/** Browser/Extension version of the toolkit */
+export interface BrowserPlaywrightToolKit {
+    Logger: LoggerModule;
+    Display: DisplayModule;
+    ByPass: ByPassModule;
+    Constants: ConstantsModule;
+    RuntimeEnv: RuntimeEnvModule;
+    $Internals: {
+        LOG_TEMPLATES: LogTemplate[];
+        stripAnsi(input: string): string;
+    };
+}
+
+export declare function usePlaywrightToolKit(): PlaywrightToolKit;