@mearl/native-host 2.21.0 → 3.0.0-beta.0

package/dist/cdp-backend/cdp-session.d.ts

@@ -0,0 +1,102 @@
+/**
+ * CDP session manager — maintains browser-level and page-level CDP connections.
+ *
+ * - Browser client: connected to the browser's top-level WebSocket endpoint.
+ *   Used for Target.* commands (list/open/close tabs).
+ * - Page sessions: per-target connections used for page interaction, screenshots,
+ *   and buffered network/log/event collection.
+ */
+import { type PageRuntimeOwner } from '../page-runtime-store.js';
+import type { ResolvedEmulationConfig } from '@mearl/browser-core';
+import { CdpClient, CdpChildSession } from './client.js';
+import { type CdpBuffers } from './buffers.js';
+export interface PageSession {
+    tabId: number;
+    client: CdpClient | CdpChildSession;
+    buffers: CdpBuffers;
+    targetId: string;
+    runtimeOwner?: PageRuntimeOwner;
+    url: string;
+    emulation?: {
+        mobile: boolean;
+        touch: boolean;
+        config?: ResolvedEmulationConfig;
+        deviceShell?: boolean;
+        splitScreen?: boolean;
+    };
+}
+export interface CdpSessionOptions {
+    port?: number;
+    userDataDir?: string;
+    endpointUrl?: string;
+    endpointResolver?: () => Promise<string>;
+    targetRegistryFile?: string;
+}
+export interface CdpAvailabilityProbe {
+    available: boolean;
+    error?: string;
+}
+export declare function isImplicitlySelectablePageUrl(url: string): boolean;
+export declare class CdpSession {
+    readonly port: number;
+    readonly userDataDir?: string;
+    private readonly endpointUrl?;
+    private readonly endpointResolver?;
+    private readonly targetRegistryFile?;
+    private browserClient;
+    private runtimeBrowserOwner?;
+    private browserClientPromise;
+    private browserConnectedListeners;
+    private pageSessions;
+    private pageSessionPromises;
+    private pageSessionInitializers;
+    /** Virtual tabId counter → CDP targetId */
+    private tabIdMap;
+    private nextTabId;
+    constructor(options?: number | CdpSessionOptions);
+    getBrowserClient(): Promise<CdpClient>;
+    onBrowserConnected(listener: () => void): () => void;
+    browserSessionIdentity(): Promise<string>;
+    /**
+     * Get (or create) a page session.
+     *
+     * @param virtualTabId  Numeric tabId returned by `tab_open` (optional).
+     *                      If omitted, connects to the first available page target.
+     */
+    getPageSession(virtualTabId?: number): Promise<PageSession>;
+    /** Register a newly opened target as a virtual tabId and return the numeric ID. */
+    registerTarget(targetId: string): Promise<number>;
+    /** Return the existing virtual tabId for a target, registering it when first discovered. */
+    ensureTargetRegistered(targetId: string): Promise<number>;
+    private restoreTargetRegistry;
+    private saveTargetRegistry;
+    addPageSessionInitializer(initializer: (session: PageSession) => Promise<void>): () => void;
+    attachOpenPageTargets(): Promise<void>;
+    private connectBrowserClient;
+    private createPageSession;
+    private getOrCreatePageSession;
+    private findTargetById;
+    private findDefaultPageTarget;
+    /** Effective port: from DevToolsActivePort file if present, else this.port */
+    private effectivePort;
+    /**
+     * Resolve the browser-level WebSocket URL.
+     * Priority: DevToolsActivePort file → HTTP /json/version → approval-mode WebSocket.
+     */
+    private resolveBrowserEndpoint;
+    /**
+     * Build a page-level WebSocket URL from a target ID.
+     * Used when HTTP /json is unavailable.
+     */
+    private pageWsUrl;
+    private isRemote;
+    private findTargetByIdViaCdp;
+    private findDefaultPageTargetViaCdp;
+    private fetchVersionInfo;
+    probeAvailability(): Promise<CdpAvailabilityProbe>;
+    isAvailable(): Promise<boolean>;
+    hasActiveConnections(): boolean;
+    listOpenPageSessions(): PageSession[];
+    listRegisteredTabIds(targetIds?: ReadonlySet<string>): number[];
+    close(): void;
+}

package/dist/cdp-backend/cdp-utils.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared utilities for CDP backend handlers.
+ *
+ * Contains: HTTP helper (nodeFetch), cookie utilities, page-load waiters,
+ * viewport helpers, and serialized function sources for page injection.
+ */
+import { type PageClickPointerType, type PageDragPoint, type PageDragPointerType } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export declare const TYPE_INTO_ELEMENT_SRC: string;
+export declare const CLICK_ELEMENT_VIA_JS_SRC: string;
+export declare const GET_CLICK_COORDS_FROM_NODE_SRC: string;
+export declare function readCdpCurrentUrl(session: PageSession, action: string): Promise<string>;
+export declare function nodeFetch(urlStr: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+    timeoutMs?: number;
+}): Promise<{
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+    bodyBuffer: Buffer;
+}>;
+export declare function getCookiesForUrl(session: PageSession, targetUrl: string): Promise<Map<string, string>>;
+export declare function buildMultipartFormBody(fields: Record<string, string>): {
+    contentType: string;
+    body: string;
+};
+export declare function waitForPageLoad(session: PageSession, timeoutMs: number, options?: {
+    probeReadyState?: boolean;
+}): Promise<void>;
+export declare function toCdpInputPoint(session: PageSession, x: number, y: number): Promise<{
+    x: number;
+    y: number;
+}>;
+export declare function dispatchCdpClick(session: PageSession, x: number, y: number, pointerType: PageClickPointerType): Promise<void>;
+export declare function dispatchCdpDrag(session: PageSession, from: PageDragPoint, to: PageDragPoint, pointerType: PageDragPointerType, durationMs: number): Promise<{
+    steps: number;
+}>;
+export declare function resolveBackendNodeObjectId(session: PageSession, backendNodeId: number): Promise<string>;

package/dist/cdp-backend/client.d.ts

@@ -0,0 +1,41 @@
+/** WebSocket CDP client shared by local and remote browser sessions. */
+type EventCallback = (params: any) => void;
+export declare class CdpChildSession {
+    private readonly parent;
+    readonly sessionId: string;
+    getDefaultExecutionContexts(): ReadonlyMap<string, number>;
+    constructor(parent: CdpClient, sessionId: string);
+    sendCommand(method: string, params?: Record<string, any>, timeoutMs?: number): Promise<any>;
+    on(method: string, callback: EventCallback): () => void;
+    createChildSession(sessionId: string): CdpChildSession;
+    get closed(): boolean;
+    close(): void;
+}
+export declare class CdpClient {
+    private readonly socket;
+    /** Stable across reconnects to one browser endpoint without exposing its credentials. */
+    get identity(): string;
+    private nextId;
+    private pending;
+    private eventHandlers;
+    private sessionEventHandlers;
+    private _closed;
+    private defaultContexts;
+    /** Contexts emitted before a page subsystem starts listening remain available for reconnection. */
+    getDefaultExecutionContexts(sessionId?: string): ReadonlyMap<string, number>;
+    private constructor();
+    static connect(wsUrl: string, handshakeTimeoutMs?: number): Promise<CdpClient>;
+    createChildSession(sessionId: string): CdpChildSession;
+    sendCommandInSession(sessionId: string, method: string, params?: Record<string, any>, timeoutMs?: number): Promise<any>;
+    onSession(sessionId: string, method: string, callback: EventCallback): () => void;
+    sendCommand(method: string, params?: Record<string, any>, timeoutMs?: number): Promise<any>;
+    on(method: string, callback: EventCallback): () => void;
+    close(): void;
+    get closed(): boolean;
+    private sendRequest;
+    private consumeMessage;
+    private handleMessage;
+    private handleClosed;
+    private rejectPending;
+}
+export {};

package/dist/cdp-backend/composite-handlers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CDP composite action handlers.
+ *
+ * Provides `run_actions` — sequential batch execution of multiple actions
+ * within a single request, sharing the same CDP session — and the observed
+ * page-action wrapper that gives page interaction actions their default
+ * built-in observation.
+ */
+import type { CdpSession } from './cdp-session.js';
+import { type ControlSource, type PageActAction, type RunActionsParams } from '@mearl/browser-core';
+export declare function cdpRunActions(session: CdpSession, data: RunActionsParams, controlSource?: ControlSource): Promise<any>;
+/**
+ * Runs a page interaction action with built-in observation. Diagnostics are
+ * collected only when the caller requests them.
+ * `run_actions` stays lightweight and never enters this wrapper.
+ */
+export declare function cdpObservedPageAction(session: CdpSession, action: PageActAction, data: any, controlSource?: ControlSource): Promise<any>;

package/dist/cdp-backend/controlled-indicator.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CDP 模式的受控页面视觉标识。
+ *
+ * 与扩展模式共享同一套 Mearl favicon 变体，本地操作显示绿色圆点角标，云端操作
+ * 显示紫色云朵角标。图标通过 data URL 内联到新文档脚本，不依赖扩展资源或网络。
+ *
+ * 注入通过 Page.addScriptToEvaluateOnNewDocument + runImmediately 完成：脚本在
+ * PageSession 存续期内跨导航生效；控制来源变化时替换脚本并立即更新当前文档。
+ */
+import { type ControlSource } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+/**
+ * 确保受控标识已注入到该 page session。相同来源幂等；来源变化时替换跨导航脚本，
+ * runImmediately 同步更新当前文档。任何异常都不阻断 agent 动作本身。
+ */
+export declare function ensureControlledIndicator(session: PageSession, controlSource?: ControlSource): Promise<void>;
+/** browser_release 使用：停止跨导航注入并恢复当前文档的 favicon。 */
+export declare function releaseControlledIndicator(session: PageSession): Promise<void>;

package/dist/cdp-backend/cookie-handlers.d.ts

@@ -0,0 +1,7 @@
+/** Read or write one named cookie in the default browser context or a selected tab's context. */
+import { type ControlSource, type GetCookieParams, type SetCookieParams } from '@mearl/browser-core';
+import type { CdpSession, PageSession } from './cdp-session.js';
+export declare function cdpSetCookie(session: PageSession, data: SetCookieParams): Promise<any>;
+export declare function cdpGetCookie(session: PageSession, data: GetCookieParams): Promise<any>;
+export declare function cdpGetBrowserCookie(session: CdpSession, data: GetCookieParams): Promise<any>;
+export declare function cdpSetBrowserCookie(session: CdpSession, data: SetCookieParams, controlSource?: ControlSource): Promise<any>;

package/dist/cdp-backend/cookie-transfer.d.ts

@@ -0,0 +1,37 @@
+/** Cookie export/import helpers for copying selected domains between CDP browsers. */
+import type { BuiltinBrowserLaunchOptions } from '../builtin-provider-options.js';
+import type { CdpSession } from './cdp-session.js';
+export interface TransferableCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    expires?: number;
+    priority?: 'Low' | 'Medium' | 'High';
+    sameParty?: boolean;
+    sourceScheme?: 'Unset' | 'NonSecure' | 'Secure';
+    sourcePort?: number;
+    partitionKey?: {
+        topLevelSite: string;
+        hasCrossSiteAncestor?: boolean;
+    };
+}
+interface CookieCommandClient {
+    sendCommand(method: string, params?: Record<string, any>, timeoutMs?: number): Promise<any>;
+}
+export declare function normalizeCookieDomain(input: string): string;
+export declare function normalizeCookieDomains(inputs: unknown): string[];
+export interface CookieCopyPlan {
+    domains: string[];
+    select(cookies: TransferableCookie[]): TransferableCookie[];
+}
+/** Explicit domains use the generic transport; named scopes belong to installed capabilities. */
+export declare function resolveCookieCopyPlan(input: BuiltinBrowserLaunchOptions['copyCookieDomains']): CookieCopyPlan;
+export declare function cookieMatchesDomain(cookieDomain: string, requestedDomain: string): boolean;
+export declare function cdpExportCookies(session: CdpSession, domains: string[]): Promise<TransferableCookie[]>;
+export declare function cdpImportCookies(session: CdpSession, cookies: TransferableCookie[]): Promise<number>;
+export declare function cdpImportCookiesWithClient(browser: CookieCommandClient, cookies: TransferableCookie[]): Promise<number>;
+export {};

package/dist/cdp-backend/device-shell.d.ts

@@ -0,0 +1,26 @@
+import { type WebViewNavigationRequest, type WebViewDocumentResponse, type AppLayerUrlProxyConfig, type ResolvedEmulationConfig } from '@mearl/browser-core';
+import type { CdpChildSession, CdpClient } from './client.js';
+import type { PageSession } from './cdp-session.js';
+export type CdpDeviceShellCommandClient = CdpClient | CdpChildSession;
+interface ApplyCdpDeviceShellOptions {
+    rootContainerManagedByApp?: boolean;
+}
+export declare function setCdpDeviceShellNavigationProxy(session: PageSession, proxy?: AppLayerUrlProxyConfig): void;
+/** 响应覆盖仍通过根文档交付，避免 Mock HTML 再次导航到业务地址。 */
+export declare function fulfillCdpDeviceShellDocument(session: PageSession, params: WebViewNavigationRequest, response: WebViewDocumentResponse): Promise<boolean>;
+export declare function isCdpDeviceShellActive(session: PageSession): boolean;
+export declare function setCdpDeviceShellChildEnvironmentManagedByApp(session: PageSession, managed: boolean): void;
+export declare function resolveCdpDeviceShellPageEndpoint(session: PageSession): Promise<{
+    client: CdpDeviceShellCommandClient;
+    frameId?: string;
+    url?: string;
+}>;
+export declare function sendCdpDeviceShellPageCommand(session: PageSession, method: string, params?: Record<string, any>, timeoutMs?: number): Promise<any>;
+export declare function getCdpDeviceShellInputOffset(session: PageSession): Promise<{
+    x: number;
+    y: number;
+}>;
+export declare function applyCdpDeviceShell(session: PageSession, emulation: ResolvedEmulationConfig, options?: ApplyCdpDeviceShellOptions): Promise<boolean>;
+export declare function clearCdpDeviceShell(session: PageSession): Promise<boolean>;
+export declare function waitForCdpDeviceShellLoad(session: PageSession, timeoutMs?: number): Promise<void>;
+export {};

package/dist/cdp-backend/discover.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CDP target discovery.
+ *
+ * Strategy (in order):
+ * 1. Read Chrome's DevToolsActivePort file — written by Chrome when remote
+ *    debugging is enabled (including via chrome://inspect/#remote-debugging).
+ *    Contains the actual port and browser WebSocket path.
+ * 2. Fall back to HTTP /json REST API on the given port (requires Chrome
+ *    launched with --remote-debugging-port).
+ * Chrome's approval-mode server also accepts /devtools/browser directly.
+ */
+export interface CdpTarget {
+    id: string;
+    title: string;
+    type: string;
+    url: string;
+    webSocketDebuggerUrl: string;
+    faviconUrl?: string;
+}
+/**
+ * Read Chrome's DevToolsActivePort file.
+ * Returns { port, browserWsPath } or null if unavailable. Reports read failures
+ * other than a missing file to callers that need discovery diagnostics.
+ */
+export declare function readDevToolsActivePort(userDataDir?: string, onError?: (error: Error) => void): {
+    port: number;
+    browserWsPath: string;
+} | null;
+export declare function discoverTargets(port?: number): Promise<CdpTarget[]>;

package/dist/cdp-backend/domain-manager.d.ts

@@ -0,0 +1,4 @@
+import type { CdpChildSession, CdpClient } from './client.js';
+type DomainClient = CdpClient | CdpChildSession;
+export declare function ensureCdpDomain(client: DomainClient, domain: string, params?: Record<string, unknown>): Promise<void>;
+export {};

package/dist/cdp-backend/download-handlers.d.ts

@@ -0,0 +1,9 @@
+import type { PageDownloadParams } from '@mearl/browser-core';
+import type { CdpSession } from './cdp-session.js';
+export declare function captureCdpDownload(session: CdpSession, data: PageDownloadParams, isolated: boolean, trigger: () => Promise<unknown>): Promise<{
+    filename: string;
+    filePath: string;
+    action: unknown;
+    owned: boolean;
+    directory: string | undefined;
+}>;

package/dist/cdp-backend/fetch-interceptor.d.ts

@@ -0,0 +1,26 @@
+/** Shared CDP Fetch-domain dispatcher for features that pause network requests. */
+import type { PageSession } from './cdp-session.js';
+export interface CdpFetchHeader {
+    name: string;
+    value: string;
+}
+export interface CdpFetchPauseContext {
+    session: PageSession;
+    params: any;
+    isResponseStage: boolean;
+}
+export interface CdpFetchPattern {
+    urlPattern: string;
+    requestStage: 'Request' | 'Response';
+    resourceType?: string;
+}
+export type CdpFetchPauseHandler = (context: CdpFetchPauseContext) => Promise<boolean> | boolean;
+/** 注册一个有序 Fetch 处理器；同一 page session 只启用一个 CDP Fetch 监听器。 */
+export declare function registerCdpFetchPauseHandler(session: PageSession, key: string, priority: number, handler: CdpFetchPauseHandler, patterns?: CdpFetchPattern[]): Promise<void>;
+/** 移除一个处理器；没有其它功能依赖 Fetch 时恢复 CDP 默认网络行为。 */
+export declare function unregisterCdpFetchPauseHandler(session: PageSession, key: string): Promise<void>;
+/** browser_release 使用：丢弃指定会话注册表；底层 CDP 连接随后关闭并恢复默认网络行为。 */
+export declare function clearCdpFetchInterceptionState(sessions?: Iterable<PageSession>): void;
+export declare function ensureCorsHeaders(headers: CdpFetchHeader[], request: {
+    headers?: Record<string, string>;
+}): CdpFetchHeader[];

package/dist/cdp-backend/frame-evaluation.d.ts

@@ -0,0 +1,3 @@
+import type { PageSession } from './cdp-session.js';
+/** A temporary session enumerates main-world contexts without resetting ongoing page capture. */
+export declare function evaluateCdpFrame(session: PageSession, frameId: string, params: Record<string, unknown>): Promise<any>;

package/dist/cdp-backend/frame-tree.d.ts

@@ -0,0 +1,16 @@
+import type { CdpChildSession } from './client.js';
+import type { PageSession } from './cdp-session.js';
+interface FrameEntry {
+    targetId: string;
+    frame: {
+        frameId: string;
+        parentFrameId: string | null;
+        url: string;
+        name: string;
+        isMainFrame: boolean;
+    };
+}
+export declare function withCdpFrameTarget<T>(session: PageSession, targetId: string, callback: (client: CdpChildSession) => Promise<T>): Promise<T>;
+/** OOPIF trees belong to separate targets; parent relationships keep discovery within this page. */
+export declare function readCdpFrameEntries(session: PageSession, requestedFrameId?: string): Promise<FrameEntry[]>;
+export {};

package/dist/cdp-backend/handlers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CDP backend action handlers — re-export hub.
+ *
+ * All handler implementations live in dedicated sub-modules.
+ * Importing this file triggers side-effect registrations in the action registry.
+ */
+import './request-handlers.js';
+import './mock-handlers.js';
+import './http-handlers.js';
+import './browser-handlers.js';
+import './rule-handlers.js';
+import './tab-handlers.js';
+import './interaction-handlers.js';
+import './app-profile-handlers.js';
+import './timezone-handlers.js';
+import './cookie-handlers.js';
+import './snapshot-handlers.js';
+import './composite-handlers.js';
+export { dispatchCdpAction, getRegisteredActionNames } from './action-registry.js';
+export { cdpGetRequests, cdpGetLogs, cdpGetEvents } from './request-handlers.js';
+export { cdpSetMock, cdpGetMocks } from './mock-handlers.js';
+export { cdpSendRequest, cdpSendMtopRequest } from './http-handlers.js';
+export { cdpPageScreenshot } from './browser-handlers.js';
+export { cdpTabOpen, cdpTabClose, cdpTabList } from './tab-handlers.js';
+export { cdpPageClick, cdpPageType, cdpPageScroll, cdpPageInspect, cdpPageEval, cdpPagePress, cdpPageWait, cdpPageNavigate, cdpPageUpload, cdpSetDeviceEmulation, } from './interaction-handlers.js';
+export { cdpSetAppProfile } from './app-profile-handlers.js';
+export { cdpPageSnapshot, cdpPageFrames } from './snapshot-handlers.js';
+export { cdpRunActions, cdpObservedPageAction } from './composite-handlers.js';
+export { cdpSetTimezone } from './timezone-handlers.js';
+export { cdpGetCookie, cdpSetCookie } from './cookie-handlers.js';

package/dist/cdp-backend/http-handlers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CDP HTTP proxy / MTOP request / API schema handlers.
+ */
+import type { SendMtopRequestParams, SendRequestParams } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export interface CdpMtopStreamRequestMetadata {
+    method: 'GET' | 'POST';
+    url: string;
+    requestHeaders: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+export interface CdpMtopStreamResponseMetadata {
+    status: number;
+    statusText: string;
+    responseHeaders: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+export interface CdpMtopStreamCallbacks {
+    onRequestPrepared?: (metadata: CdpMtopStreamRequestMetadata) => void | Promise<void>;
+    onResponse?: (metadata: CdpMtopStreamResponseMetadata) => void | Promise<void>;
+    onReceive: (data: unknown) => void | Promise<void>;
+}
+export declare function cdpSendRequest(session: PageSession, data: SendRequestParams): Promise<any>;
+export declare function cdpSendMtopRequest(session: PageSession, data: SendMtopRequestParams): Promise<any>;
+export declare function cdpSendMtopStreamRequest(session: PageSession, data: SendMtopRequestParams, callbacks: CdpMtopStreamCallbacks): Promise<{
+    success: true;
+    response: unknown;
+    requestData: unknown;
+}>;

package/dist/cdp-backend/interaction-handlers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CDP page interaction handlers.
+ *
+ * Covers: click, type, scroll, eval, press, wait, navigate, upload, device emulation.
+ */
+import { type PageClickParams, type PageDragParams, type PageDragResultData, type PageEvalParams, type PageHoverParams, type PageInspectParams, type PageInspectResult, type PageNavigateParams, type PagePressParams, type PageScrollParams, type PageTypeParams, type PageUploadParams, type PageWaitParams, type SetDeviceEmulationParams } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export declare function cdpPageClick(session: PageSession, data: PageClickParams): Promise<any>;
+export declare function cdpPageDrag(session: PageSession, data: PageDragParams): Promise<PageDragResultData>;
+export declare function cdpPageType(session: PageSession, data: PageTypeParams): Promise<any>;
+export declare function cdpPageScroll(session: PageSession, data: PageScrollParams): Promise<any>;
+export declare function cdpPageEval(session: PageSession, data: PageEvalParams): Promise<any>;
+export declare function cdpPagePress(session: PageSession, data: PagePressParams): Promise<any>;
+export declare function cdpPageWait(session: PageSession, data: PageWaitParams): Promise<any>;
+export declare function cdpPageNavigate(session: PageSession, data: PageNavigateParams): Promise<any>;
+export declare function cdpPageUpload(session: PageSession, data: PageUploadParams): Promise<any>;
+export declare function cdpSetDeviceEmulation(session: PageSession, data: SetDeviceEmulationParams): Promise<any>;
+export declare function cdpPageHover(session: PageSession, data: PageHoverParams): Promise<any>;
+export declare function cdpPageInspect(session: PageSession, data: PageInspectParams): Promise<PageInspectResult>;

package/dist/cdp-backend/mock-handlers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CDP mock interception handlers.
+ */
+import { type GetMocksParams, type SetMockParams } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export declare function clearCdpPageMocks(session: PageSession): void;
+/** browser_release 使用：丢弃所有依赖当前 CDP 会话的 mock 状态。 */
+export declare function clearCdpMockState(): void;
+export declare function cdpSetMock(session: PageSession, data: SetMockParams): Promise<any>;
+export declare function cdpGetMocks(session: PageSession, data: GetMocksParams): any;

package/dist/cdp-backend/mtop-environment.d.ts

@@ -0,0 +1,7 @@
+/** Per-tab MTop gateway environment switching for direct CDP browsers. */
+import type { MtopEnvironment, MtopEnvironmentTarget } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export declare function setCdpMtopEnvironment(session: PageSession, target: MtopEnvironment): Promise<void>;
+export declare function getCdpMtopEnvironment(session: PageSession): MtopEnvironmentTarget | undefined;
+/** browser_release 使用：清除指定 tab 的 MTop 环境选择。 */
+export declare function clearCdpMtopEnvironmentState(sessions?: Iterable<PageSession>): void;

package/dist/cdp-backend/navigation-observer.d.ts

@@ -0,0 +1,9 @@
+import { type PageActNavigationObserver } from '@mearl/browser-core';
+import type { CdpSession, PageSession } from './cdp-session.js';
+export declare function startCdpNavigationObserver(cdpSession: CdpSession, pageSession: PageSession, urlBefore: string, options?: {
+    trackNetwork?: boolean;
+    networkIdleMs?: number;
+    contentReadyAfterMs?: number;
+    trackOpenedTabs?: boolean;
+    sourceTabId?: number;
+}): Promise<PageActNavigationObserver>;

package/dist/cdp-backend/page-observer.d.ts

@@ -0,0 +1,5 @@
+import { type PageChangeSet, type PageNavigationChange, type PageObservationCheckpoint, type PageObservationWaitOptions } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export declare function startPageObservation(session: PageSession): Promise<PageObservationCheckpoint>;
+export declare function finishPageObservation(session: PageSession, checkpoint: PageObservationCheckpoint, options?: PageObservationWaitOptions): Promise<PageChangeSet | PageNavigationChange>;
+export declare function disposePageObservation(session: PageSession): Promise<void>;

package/dist/cdp-backend/page-refs.d.ts

@@ -0,0 +1,9 @@
+import { BackendNodeRefRegistry, type BackendNodeSnapshotRefAllocator, type PageChangeSet, type PageEffectRefEntry } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export type PageRefEntry = PageEffectRefEntry;
+export declare function getPageRefRegistry(session: PageSession): BackendNodeRefRegistry<PageRefEntry>;
+export declare function beginPageSnapshotRefs(session: PageSession): BackendNodeSnapshotRefAllocator<PageRefEntry>;
+export declare function resolvePageRef(session: PageSession, ref: string): PageRefEntry | undefined;
+export declare function deletePageRef(session: PageSession, ref: string): void;
+export declare function clearPageRefsForNavigation(session: PageSession): void;
+export declare function enrichCdpPageChangeSetWithRefs(session: PageSession, observation: PageChangeSet): Promise<PageChangeSet>;

package/dist/cdp-backend/page-session-initializers.d.ts

@@ -0,0 +1,6 @@
+import type { PageSession } from './cdp-session.js';
+type PageSessionInitializer = (session: PageSession) => Promise<void>;
+/** Register state that must be reconstructed whenever a daemon attaches to a page target. */
+export declare function registerPageSessionInitializer(initializer: PageSessionInitializer): void;
+export declare function initializePageSession(session: PageSession): Promise<void>;
+export {};

package/dist/cdp-backend/plugin-pages.d.ts

@@ -0,0 +1,12 @@
+import { PluginPageRuntimeHost, type PluginPageNativeCall } from '@mearl/browser-core';
+import type { CdpSession } from './cdp-session.js';
+/** Session values belong to one browser lifetime; persistent activation rules outlive it. */
+export declare function pruneCdpSessionStorage(storageFile: string, currentIdentity?: string): void;
+/** Port-shaped bridge keeps the document runtime independent of Chrome extension APIs. */
+export declare function installCdpPluginPageBridge(binding: string): void;
+export declare class CdpPluginPageHost extends PluginPageRuntimeHost {
+    constructor(cdp: CdpSession, native: PluginPageNativeCall, options: {
+        browserId: string;
+        storageFile?: string;
+    });
+}

package/dist/cdp-backend/release-control.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Browser-level CDP control release.
+ *
+ * Closes Mearl's browser/page WebSocket sessions while keeping Chrome and all
+ * targets alive. A later browser action may create a fresh CdpSession.
+ */
+import type { CdpSession } from './cdp-session.js';
+export interface CdpReleaseResult {
+    released: boolean;
+    hadActiveControl: boolean;
+    affectedTabIds: number[];
+}
+export declare function releaseCdpControl(session: CdpSession): Promise<CdpReleaseResult>;

package/dist/cdp-backend/request-handlers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CDP request/log/event buffer query handlers.
+ */
+import type { CaptureCheckpointParams, GetEventsParams, GetLogsParams, GetRequestsParams, PageDiagnosticsOptions } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export declare function cdpGetRequests(session: PageSession, data: GetRequestsParams): Promise<any>;
+export declare function cdpGetLogs(session: PageSession, data: GetLogsParams): Promise<any>;
+export declare function cdpCaptureCheckpoint(session: PageSession, _data: CaptureCheckpointParams): Promise<any>;
+export declare function collectCdpPageDiagnostics(session: PageSession, after: string, diagnostics: PageDiagnosticsOptions): Promise<Record<string, any>>;
+export declare function cdpGetEvents(session: PageSession, data: GetEventsParams): Promise<any>;

package/dist/cdp-backend/rule-handlers.d.ts

@@ -0,0 +1,11 @@
+/** CDP request-header rules, scoped to the current browser control session. */
+import type { RulesResult, SetRuleParams } from '@mearl/browser-core';
+import type { CdpSession } from './cdp-session.js';
+export declare function cdpSetRule(session: CdpSession, data: SetRuleParams): Promise<{
+    success: boolean;
+    ruleId: number;
+    affectedCount: number;
+    message: string;
+}>;
+export declare function cdpGetRules(session: CdpSession): Promise<RulesResult>;
+export declare function clearCdpRuleState(session: CdpSession): void;

package/dist/cdp-backend/send-request.d.ts

@@ -0,0 +1,2 @@
+import { type SendRequestParams } from '@mearl/browser-core';
+export declare function executeNodeSendRequest(data: SendRequestParams, cookieMap?: Map<string, string>): Promise<any>;

package/dist/cdp-backend/snapshot-handlers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CDP accessibility tree snapshot and frame handlers.
+ */
+import { type PageFramesParams, type PageSnapshotParams } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export declare function cdpPageSnapshot(session: PageSession, data: PageSnapshotParams): Promise<any>;
+export declare function cdpPageFrames(session: PageSession, _data: PageFramesParams): Promise<any>;

package/dist/cdp-backend/tab-handlers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CDP tab management handlers.
+ */
+import { type ControlSource, type TabCloseParams, type TabOpenParams } from '@mearl/browser-core';
+import { type CdpSession } from './cdp-session.js';
+export declare function cdpTabOpen(session: CdpSession, data: TabOpenParams, controlSource?: ControlSource): Promise<any>;
+export declare function cdpTabClose(session: CdpSession, data: TabCloseParams): Promise<any>;
+export declare function cdpTabList(session: CdpSession, _data: any): Promise<any>;

package/dist/cdp-backend/timezone-handlers.d.ts

@@ -0,0 +1,4 @@
+/** CDP timezone override handler. */
+import type { SetTimezoneParams } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export declare function cdpSetTimezone(session: PageSession, data: SetTimezoneParams): Promise<any>;