@mearl/browser-core 3.0.0-beta.4 → 3.0.0-beta.7

package/dist/browserActionProtocol.d.ts

@@ -1,3 +1,8 @@
+import type { BrowserCapabilityCatalog } from './browserCapabilities.js';
+export interface GetCapabilitiesParams {
+    /** Include method and setting details for this installed App ID. */
+    app?: string;
+}
 export interface GetRequestsParams {
     tabId: number;
     count?: number;
@@ -13,7 +18,7 @@ export interface GetRequestsParams {
     fields?: string[];
     keysOnly?: boolean;
     applyHiddenFilter?: boolean;
-    source?: 'mtop' | 'requests' | 'all';
+    source?: 'protocol' | 'requests' | 'all';
 }
 export interface GetLogsParams {
     tabId: number;
@@ -107,18 +112,14 @@ export interface SendRequestParams {
     responseType?: 'json' | 'text' | 'auto';
     timeout?: number;
 }
-export type MtopEnvironmentTarget = 'prod' | 'pre';
-export type MtopEnvironment = 'default' | MtopEnvironmentTarget;
-export interface SendMtopRequestParams {
-    api: string;
-    data?: unknown;
-    version?: string;
-    method?: string;
-    appKey?: string;
-    env?: MtopEnvironmentTarget;
+export interface NetworkControlSelection {
+    id: string;
+    value: string;
+}
+/** Parameters are interpreted and validated by the installed request protocol. */
+export interface SendProtocolRequestParams {
     timeout?: number;
-    headers?: Record<string, string>;
-    ttid?: string;
+    [key: string]: unknown;
 }
 export type BrowserStatus = 'connected' | 'pairing' | 'running_disconnected' | 'stopped';
 export type BrowserTransport = 'extension' | 'cdp' | 'provider';
@@ -184,6 +185,7 @@ export interface BrowserInfoBase {
     pairing?: BrowserPairingInfo;
 }
 export type BrowserScreenshotKind = 'native' | 'reconstructed' | 'none';
+export type BrowserControlSessionMode = 'mearl' | 'external';
 /** Browser-targeted actions that an external provider may implement. */
 export type BrowserCapabilityAction = ExtensionBrowserAction | 'page_download';
 /** Capabilities advertised by an external browser-control provider. */
@@ -191,6 +193,8 @@ export interface BrowserCapabilities {
     actions: BrowserCapabilityAction[];
     /** Pixel fidelity of page_screenshot, or none when that action is unavailable. */
     screenshot: BrowserScreenshotKind;
+    /** Fixed per instance. Omitted means Mearl sessions; external delegates task control. */
+    controlSessionMode?: BrowserControlSessionMode;
 }
 export interface RegularBrowserInfo extends BrowserInfoBase {
     type: 'regular';
@@ -204,6 +208,13 @@ export interface ManagedBrowserInfo extends BrowserInfoBase {
     operations: BrowserProviderOperation[];
 }
 export type BrowserInfo = RegularBrowserInfo | ManagedBrowserInfo;
+export interface BrowserListParams {
+    provider: string;
+    launchForm: {
+        variant?: string;
+        values: Record<string, BrowserJsonValue>;
+    };
+}
 export interface BrowserListResult {
     count: number;
     connectedCount: number;
@@ -211,6 +222,11 @@ export interface BrowserListResult {
     browsers: BrowserInfo[];
     /** Partial discovery failures; successfully inspected browser sources remain in the result. */
     warnings?: string[];
+    /** Present only for an explicit, source-local Provider launch-form query. */
+    discovery?: {
+        provider: string;
+        launchForm: BrowserProviderLaunchForm;
+    };
 }
 export interface SelectBrowserParams {
     browser?: string;
@@ -366,6 +382,7 @@ export interface BrowserProviderDefinition {
     provider: BrowserProviderIdentity;
     browserType: {
         name: string;
+        controlSessionModes?: readonly BrowserControlSessionMode[];
         documentationUrl?: string;
         inputSchema: BrowserProviderObjectSchema;
         configuration?: {
@@ -457,7 +474,8 @@ export interface BrowserEmulationOptions {
     /** App 容器横屏时将根页面与业务页面分置左右 WebView；仅与 deviceShell、App 档案同时生效。 */
     splitScreen?: boolean;
 }
-export type AppBridgeConfigBehavior = 'navigate' | 'closeAll' | 'closeBackData' | 'postMessage' | 'notifySubscribe' | 'notifyUnsubscribe' | 'notifyPost' | 'sharedFileRead' | 'sharedFileWrite' | 'sharedDataGet' | 'sharedDataSet' | 'legacyBroadcastCreate' | 'legacyBroadcastPost' | 'legacyBroadcastClose' | 'memoryGet' | 'memorySet' | 'memoryDelete' | 'availabilityMap' | 'userInfo' | 'authCode' | 'networkInfo' | 'geolocation' | 'permission' | 'imagePicker' | 'prefetch' | 'fptTrack' | 'mtopStream' | 'previewFile' | 'toast' | 'unsupportedNativeInput' | 'payment' | 'userTrack' | 'calendar' | 'networkQualityMonitor' | 'beaconRequest' | 'voiceRecognition';
+/** Provider-defined behavior ID; core does not execute or enumerate business behaviors. */
+export type AppBridgeConfigBehavior = string;
 /** 单个桥方法的声明式覆盖；行为、固定回包、成功空实现三选一。 */
 export interface AppBridgeMethodConfig {
     behavior?: AppBridgeConfigBehavior;
@@ -486,8 +504,8 @@ export interface TabOpenParams {
     emulation?: BrowserEmulationOptions;
     group?: string;
     /**
-     * 客户端容器模拟档案名（如 'fliggy'）。只注入容器 UA、环境变量、JSBridge 与桥协议；
-     * 设备视口和 iframe 系统外壳由 emulation.deviceShell 独立控制。可用档案见 APP_PROFILE_NAMES。
+     * 客户端容器模拟档案名（由已安装能力目录提供）。只注入容器 UA、环境变量、JSBridge 与桥协议；
+     * 设备视口和 iframe 系统外壳由 emulation.deviceShell 独立控制。可用档案通过 get_capabilities 查询。
      */
     appProfile?: AppProfileName;
     /** 与 appProfile 配合使用；容器系统，默认 ios */
@@ -504,16 +522,9 @@ export type TabGroupParams = {
     ungroup: true;
     title?: never;
 };
-/**
- * 客户端容器模拟可用档案名。
- *
- * 档案数据（UA / 桥对象 / 方法映射）在 @mearl/app-profiles 维护，但名单属于协议：
- * 它是 set_app_profile.profile 与 tab_open.appProfile 的取值域，CLI 帮助与 MCP 工具
- * schema 的 enum 也由它生成。app-profiles 反向引用本清单约束自己的档案表，
- * 因此新增档案时只需改两处（名单 + 档案数据），且漏改会在类型检查时暴露。
- */
-export declare const APP_PROFILE_NAMES: readonly ["fliggy", "taobao", "wechat", "alipay"];
-export type BuiltinAppProfileName = (typeof APP_PROFILE_NAMES)[number];
+/** App identities are supplied by installed capability catalogs. */
+export declare const APP_PROFILE_NAMES: readonly string[];
+export type BuiltinAppProfileName = string;
 /** Hosts validate dynamic profile IDs against the active capability catalog. */
 export type AppProfileName = string;
 export interface SetAppProfileParams {
@@ -534,10 +545,10 @@ export interface SetAppProfileParams {
     /** 按方法覆盖档案内置桥配置，仅支持受控行为、固定 JSON 回包和成功空实现 */
     bridgeConfig?: AppBridgeConfig;
     /**
-     * 可选 MTop 接口环境。default 关闭环境改写；省略时保持当前设置。
+     * 可选已安装的网络控件选择；null 清除，省略时保持当前设置。
      * 仅作用于目标 tab，扩展模式与该 tab 的快捷设置共享。
      */
-    mtopEnv?: MtopEnvironment;
+    networkControl?: NetworkControlSelection | null;
     /**
      * 可选设备联动参数。传入时显式字段覆盖档案推荐设备，空对象使用推荐设备且默认开启
      * deviceShell；省略时不设置或清除该 tab 的设备状态。
@@ -672,6 +683,10 @@ export interface PageInspectParams {
 export interface PagePressParams {
     tabId: number;
     key: string;
+    /** Explicit native JavaScript dialog target obtained from a receipt or page_snapshot. */
+    dialogId?: string;
+    /** Only for accepting a native prompt with dialogId + Enter. */
+    promptText?: string;
     modifiers?: string[];
     /** Dispatch strategy. Auto uses DOM events when the page is hidden. */
     pressMode?: 'auto' | 'dom' | 'keyboard';
@@ -762,10 +777,10 @@ export interface SetCookieResult {
     path: string;
     reloaded: boolean;
 }
-export interface RequestDomainPermissionParams {
+export interface RequestPermissionParams {
     domain: string;
 }
-export type RunActionName = Exclude<ExtensionBrowserAction, 'run_actions' | 'browser_release'>;
+export type RunActionName = Exclude<ExtensionBrowserAction, 'run_actions' | 'browser_release' | 'get_capabilities'>;
 export interface ActionStep {
     action: RunActionName;
     data?: Record<string, unknown>;
@@ -775,6 +790,10 @@ export interface RunActionsParams {
     tabId: number;
 }
 export interface BrowserActionMap {
+    get_capabilities: {
+        request: GetCapabilitiesParams;
+        response: BrowserCapabilityCatalog;
+    };
     tab_checkpoint: {
         request: CaptureCheckpointParams;
         response: CaptureCheckpointResult;
@@ -816,12 +835,12 @@ export interface BrowserActionMap {
         request: SendRequestParams;
         response: unknown;
     };
-    send_mtop_request: {
-        request: SendMtopRequestParams;
+    send_protocol_request: {
+        request: SendProtocolRequestParams;
         response: unknown;
     };
     browser_list: {
-        request: undefined;
+        request: BrowserListParams | undefined;
         response: BrowserListResult;
     };
     browser_select_browser: {
@@ -946,8 +965,8 @@ export interface BrowserActionMap {
         request: SetCookieParams;
         response: SetCookieResult;
     };
-    request_domain_permission: {
-        request: RequestDomainPermissionParams;
+    request_permission: {
+        request: RequestPermissionParams;
         response: unknown;
     };
     run_actions: {
@@ -979,8 +998,9 @@ export declare const BROWSER_ACTIONS: {
     readonly get_mocks: true;
     readonly set_rule: true;
     readonly get_rules: true;
+    readonly get_capabilities: true;
     readonly send_request: true;
-    readonly send_mtop_request: true;
+    readonly send_protocol_request: true;
     readonly browser_list: true;
     readonly browser_select_browser: true;
     readonly browser_release: true;
@@ -1012,7 +1032,7 @@ export declare const BROWSER_ACTIONS: {
     readonly set_timezone: true;
     readonly get_cookie: true;
     readonly set_cookie: true;
-    readonly request_domain_permission: true;
+    readonly request_permission: true;
     readonly run_actions: true;
 };
 export declare const BROWSER_COMMAND_ACTIONS: {
@@ -1025,8 +1045,9 @@ export declare const BROWSER_COMMAND_ACTIONS: {
     readonly get_mocks: true;
     readonly set_rule: true;
     readonly get_rules: true;
+    readonly get_capabilities: true;
     readonly send_request: true;
-    readonly send_mtop_request: true;
+    readonly send_protocol_request: true;
     readonly browser_list: true;
     readonly browser_release: true;
     readonly browser_control: true;
@@ -1057,7 +1078,7 @@ export declare const BROWSER_COMMAND_ACTIONS: {
     readonly set_timezone: true;
     readonly get_cookie: true;
     readonly set_cookie: true;
-    readonly request_domain_permission: true;
+    readonly request_permission: true;
     readonly run_actions: true;
 };
 export declare const EXTENSION_BROWSER_ACTIONS: {
@@ -1070,8 +1091,9 @@ export declare const EXTENSION_BROWSER_ACTIONS: {
     readonly get_mocks: true;
     readonly set_rule: true;
     readonly get_rules: true;
+    readonly get_capabilities: true;
     readonly send_request: true;
-    readonly send_mtop_request: true;
+    readonly send_protocol_request: true;
     readonly browser_release: true;
     readonly page_screenshot: true;
     readonly tab_open: true;
@@ -1097,7 +1119,7 @@ export declare const EXTENSION_BROWSER_ACTIONS: {
     readonly set_timezone: true;
     readonly get_cookie: true;
     readonly set_cookie: true;
-    readonly request_domain_permission: true;
+    readonly request_permission: true;
     readonly run_actions: true;
 };
 export declare const BROWSER_CAPABILITY_ACTIONS: {
@@ -1111,8 +1133,9 @@ export declare const BROWSER_CAPABILITY_ACTIONS: {
     readonly get_mocks: true;
     readonly set_rule: true;
     readonly get_rules: true;
+    readonly get_capabilities: true;
     readonly send_request: true;
-    readonly send_mtop_request: true;
+    readonly send_protocol_request: true;
     readonly browser_release: true;
     readonly page_screenshot: true;
     readonly tab_open: true;
@@ -1138,7 +1161,7 @@ export declare const BROWSER_CAPABILITY_ACTIONS: {
     readonly set_timezone: true;
     readonly get_cookie: true;
     readonly set_cookie: true;
-    readonly request_domain_permission: true;
+    readonly request_permission: true;
     readonly run_actions: true;
 };
 export declare function isBrowserAction(value: unknown): value is BrowserAction;

package/dist/browserActionProtocol.js

@@ -20,15 +20,8 @@ export const BROWSER_DEVICE_PRESET_NAMES = [
     'ipad-mini',
     'galaxy-s23',
 ];
-/**
- * 客户端容器模拟可用档案名。
- *
- * 档案数据（UA / 桥对象 / 方法映射）在 @mearl/app-profiles 维护，但名单属于协议：
- * 它是 set_app_profile.profile 与 tab_open.appProfile 的取值域，CLI 帮助与 MCP 工具
- * schema 的 enum 也由它生成。app-profiles 反向引用本清单约束自己的档案表，
- * 因此新增档案时只需改两处（名单 + 档案数据），且漏改会在类型检查时暴露。
- */
-export const APP_PROFILE_NAMES = ['fliggy', 'taobao', 'wechat', 'alipay'];
+/** App identities are supplied by installed capability catalogs. */
+export const APP_PROFILE_NAMES = [];
 export function resolvePageEvalExpression(params) {
     if (typeof params.expression !== 'string' || !params.expression.trim())
         throw new Error('Invalid expression');
@@ -83,6 +76,10 @@ export function actionRequiresTabId(action) {
     return typeof action === 'string' && TAB_ID_REQUIRED_ACTION_SET.has(action);
 }
 export function validateRequiredActionTabId(action, data) {
+    if (action === 'get_capabilities' && data && typeof data === 'object' &&
+        ['tabId', 'tabIds', 'openerTabId'].some(key => Object.hasOwn(data, key))) {
+        throw new Error('get_capabilities does not accept page targets');
+    }
     const cookieAction = action === 'get_cookie' || action === 'set_cookie';
     if (!actionRequiresTabId(action) && !cookieAction)
         return;
@@ -123,8 +120,9 @@ export const BROWSER_ACTIONS = {
     get_mocks: true,
     set_rule: true,
     get_rules: true,
+    get_capabilities: true,
     send_request: true,
-    send_mtop_request: true,
+    send_protocol_request: true,
     browser_list: true,
     browser_select_browser: true,
     browser_release: true,
@@ -156,7 +154,7 @@ export const BROWSER_ACTIONS = {
     set_timezone: true,
     get_cookie: true,
     set_cookie: true,
-    request_domain_permission: true,
+    request_permission: true,
     run_actions: true,
 };
 export const BROWSER_COMMAND_ACTIONS = {
@@ -169,8 +167,9 @@ export const BROWSER_COMMAND_ACTIONS = {
     get_mocks: true,
     set_rule: true,
     get_rules: true,
+    get_capabilities: true,
     send_request: true,
-    send_mtop_request: true,
+    send_protocol_request: true,
     browser_list: true,
     browser_release: true,
     browser_control: true,
@@ -201,7 +200,7 @@ export const BROWSER_COMMAND_ACTIONS = {
     set_timezone: true,
     get_cookie: true,
     set_cookie: true,
-    request_domain_permission: true,
+    request_permission: true,
     run_actions: true,
 };
 export const EXTENSION_BROWSER_ACTIONS = {
@@ -214,8 +213,9 @@ export const EXTENSION_BROWSER_ACTIONS = {
     get_mocks: true,
     set_rule: true,
     get_rules: true,
+    get_capabilities: true,
     send_request: true,
-    send_mtop_request: true,
+    send_protocol_request: true,
     browser_release: true,
     page_screenshot: true,
     tab_open: true,
@@ -241,7 +241,7 @@ export const EXTENSION_BROWSER_ACTIONS = {
     set_timezone: true,
     get_cookie: true,
     set_cookie: true,
-    request_domain_permission: true,
+    request_permission: true,
     run_actions: true,
 };
 export const BROWSER_CAPABILITY_ACTIONS = {

package/dist/browserCapabilities.d.ts

@@ -0,0 +1,47 @@
+import type { AppProfileCatalogEntry, AppProfileSetting, AppProfileUsage } from './appProfileDefinition.js';
+import type { GetCapabilitiesParams } from './browserActionProtocol.js';
+export interface AppCapability {
+    id: string;
+    label: string;
+    source: AppProfileCatalogEntry['source'];
+    plugin?: string;
+    available: boolean;
+    features: string[];
+    usage?: AppProfileUsage;
+    details?: {
+        defaultAppVersion: string;
+        bridges: string[];
+        methods: Record<string, string[]>;
+        behaviors: Record<string, string>;
+        settings: AppProfileSetting[];
+    };
+}
+export interface BrowserCapabilityCatalog {
+    /** Supported operations, not a grant of page permissions or business authorization. */
+    actions: string[];
+    devicePresets: string[];
+    apps: {
+        status: 'available' | 'partial' | 'unsupported';
+        entries: AppCapability[];
+        issues: Array<{
+            plugin: string;
+            error: string;
+        }>;
+    };
+    limitations: string[];
+    help: {
+        skill: string;
+        commands: string[];
+    };
+}
+/** Project validated installed metadata without scripts, global values or Mock response bodies. */
+export declare function describeBrowserCapabilities(actions: readonly string[], catalog: {
+    profiles: AppProfileCatalogEntry[];
+    errors: Array<{
+        plugin: string;
+        error: string;
+    }>;
+    offline?: boolean;
+} | {
+    apps: BrowserCapabilityCatalog['apps'];
+} | undefined, params?: GetCapabilitiesParams): BrowserCapabilityCatalog;

package/dist/browserCapabilities.js

@@ -0,0 +1,63 @@
+import { BROWSER_DEVICE_PRESET_NAMES } from './browserActionProtocol.js';
+/** Project validated installed metadata without scripts, global values or Mock response bodies. */
+export function describeBrowserCapabilities(actions, catalog, params = {}) {
+    if (!params || typeof params !== 'object' || Array.isArray(params))
+        throw new Error('Invalid capability query');
+    if (params.app !== undefined && (typeof params.app !== 'string' || !params.app || params.app.length > 161))
+        throw new Error('Invalid App capability ID');
+    const installed = catalog && 'profiles' in catalog ? catalog : undefined;
+    const projected = catalog && 'apps' in catalog ? catalog.apps : undefined;
+    if (params.app && installed && !installed.offline && !installed.errors.length && !installed.profiles.some(entry => entry.id === params.app))
+        throw new Error(`App profile is not installed: ${params.app}`);
+    if (params.app && projected?.status === 'available' && !projected.entries.some(entry => entry.id === params.app))
+        throw new Error(`App profile is not installed: ${params.app}`);
+    const supportsApps = actions.includes('set_app_profile');
+    const profiles = supportsApps ? installed?.profiles ?? [] : [];
+    return {
+        actions: [...new Set(actions)],
+        devicePresets: actions.includes('set_device_emulation') ? [...BROWSER_DEVICE_PRESET_NAMES] : [],
+        apps: supportsApps && projected ? {
+            status: projected.status,
+            entries: projected.entries.filter(entry => !params.app || entry.id === params.app).map(entry => ({
+                id: entry.id, label: entry.label, source: entry.source,
+                ...(entry.plugin ? { plugin: entry.plugin } : {}), available: entry.available,
+                features: [...entry.features],
+                ...(entry.usage ? { usage: structuredClone(entry.usage) } : {}),
+                ...(params.app && entry.details ? { details: structuredClone(entry.details) } : {}),
+            })),
+            issues: projected.issues.map(({ plugin, error }) => ({ plugin, error })),
+        } : {
+            status: !supportsApps || !installed ? 'unsupported' : installed.offline || installed.errors.length || profiles.some(entry => entry.available === false) ? 'partial' : 'available',
+            entries: profiles.filter(entry => !params.app || entry.id === params.app).map(entry => {
+                const definition = entry.definition;
+                const methods = {};
+                for (const [name, values] of Object.entries(definition.actions)) {
+                    const names = Array.isArray(values) ? values : Object.keys(values ?? {});
+                    if (names.length)
+                        methods[name] = [...names];
+                }
+                return {
+                    id: entry.id, label: entry.label, source: entry.source, plugin: entry.plugin,
+                    available: entry.available !== false,
+                    features: ['userAgent', ...(definition.bridges.length ? ['jsBridge'] : []), ...Object.keys(methods), ...(definition.schemes.length ? ['schemes'] : []), ...(definition.settings?.length ? ['settings'] : [])],
+                    ...(definition.usage ? { usage: structuredClone(definition.usage) } : {}),
+                    ...(params.app ? { details: {
+                            defaultAppVersion: definition.defaultAppVersion,
+                            bridges: definition.bridges.map(bridge => bridge.global),
+                            methods,
+                            behaviors: { ...definition.actions.behaviors },
+                            settings: structuredClone(definition.settings ?? []),
+                        } } : {}),
+                };
+            }),
+            issues: (installed?.errors ?? projected?.issues)?.map(({ plugin, error }) => ({ plugin, error })) ?? [],
+        },
+        limitations: [
+            'Actions describe support, not current domain permissions, login state or device connectivity.',
+            'App profiles simulate a WebView. Declared bridge methods, behaviors and response stubs do not guarantee real native authorization, payment or other business effects.',
+            'Package usage and Skill names are guidance from the package author; referenced Skills may need separate installation. Read the relevant help only when needed.',
+            ...(!catalog && supportsApps ? ['This Provider does not expose an installed App catalog.'] : []),
+        ],
+        help: { skill: 'mearl', commands: ['mearl get_capabilities --help', 'mearl set_device_emulation --help', 'mearl set_app_profile --help', 'mearl tab_open --help'] },
+    };
+}

package/dist/browserDiscovery.d.ts

@@ -0,0 +1,3 @@
+import type { BrowserListParams } from './browserActionProtocol.js';
+/** An empty request retains ordinary discovery; partial or unknown options cannot be ignored. */
+export declare function parseBrowserListParams(value: unknown): BrowserListParams | undefined;

package/dist/browserDiscovery.js

@@ -0,0 +1,20 @@
+/** An empty request retains ordinary discovery; partial or unknown options cannot be ignored. */
+export function parseBrowserListParams(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid browser_list request');
+    const keys = Object.keys(value);
+    if (!keys.length)
+        return undefined;
+    const params = value;
+    const form = params.launchForm;
+    if (keys.some(key => key !== 'provider' && key !== 'launchForm') ||
+        typeof params.provider !== 'string' || !params.provider.trim() ||
+        !form || typeof form !== 'object' || Array.isArray(form) ||
+        Object.keys(form).some(key => key !== 'variant' && key !== 'values') ||
+        (form.variant !== undefined && typeof form.variant !== 'string') ||
+        !form.values || typeof form.values !== 'object' || Array.isArray(form.values))
+        throw new Error('browser_list discovery requires provider and launchForm with values');
+    return params;
+}

package/dist/browserEnhancement.d.ts

@@ -0,0 +1,161 @@
+import type { BrowserActionMap } from './browserActionProtocol.js';
+import { type DeviceEnvironmentObservation } from './deviceEnvironmentObservation.js';
+export declare const BROWSER_ENHANCEMENT_PROTOCOL_VERSION = 1;
+export declare const BROWSER_ENHANCEMENT_NAVIGATION_ORIGIN_VERSION = 1;
+export declare const BROWSER_ENHANCEMENT_PREPARATION_VERSION = 1;
+export declare const BROWSER_ENHANCEMENT_HOST_ENVIRONMENT_VERSION = 1;
+export declare const BROWSER_ENHANCEMENT_PREPARATION_PATH = "src/pages/browser-transport/index.html";
+/** Only the installed Extension's inert top-level page can prepare a new document. */
+export declare function isBrowserEnhancementPreparationUrl(value: unknown): value is string;
+/** Narrow internal host contract. Ordinary input, navigation and browser lifecycle are excluded. */
+export type BrowserEnhancementAction = 'set_device_emulation' | 'set_app_profile' | 'set_timezone';
+export declare function isBrowserEnhancementAction(value: unknown): value is BrowserEnhancementAction;
+export type BrowserEnhancementInvocation = {
+    [A in BrowserEnhancementAction]: {
+        action: A;
+        data: BrowserActionMap[A]['request'];
+    };
+}[BrowserEnhancementAction];
+export declare function requiredBrowserEnhancementActions(invocation: BrowserEnhancementInvocation): BrowserEnhancementAction[];
+export interface BrowserEnhancementBinding {
+    bindingId: string;
+    generation: number;
+    tabId: number;
+    mainFrameId: string;
+    targetId?: string;
+    actions: BrowserEnhancementAction[];
+}
+export interface BrowserEnhancementCapabilities {
+    protocolVersion: typeof BROWSER_ENHANCEMENT_PROTOCOL_VERSION;
+    actions: BrowserEnhancementAction[];
+    navigationOriginVersion?: typeof BROWSER_ENHANCEMENT_NAVIGATION_ORIGIN_VERSION;
+    preparationVersion?: typeof BROWSER_ENHANCEMENT_PREPARATION_VERSION;
+    hostEnvironmentVersion?: typeof BROWSER_ENHANCEMENT_HOST_ENVIRONMENT_VERSION;
+}
+export interface BrowserEnhancementPreparation {
+    tabId: number;
+    targetId: string;
+    url: string;
+    capabilities: BrowserEnhancementCapabilities;
+}
+export interface ProviderEnhancementPreparation extends BrowserEnhancementPreparation {
+    nativeBrowserId: string;
+    providerTabId: number;
+}
+/** Captured by the accepted external owner immediately after creating this target. */
+export interface ProviderInitialEnvironment {
+    device: DeviceEnvironmentObservation;
+    /** Keep the physical root's captured platform while logical App/device identities remain unchanged. */
+    preserveHostPlatform?: true;
+    /** The external host owns native pointer/touch delivery; Chrome must not convert its mouse events. */
+    preserveHostInput?: true;
+}
+export declare function isProviderInitialEnvironment(value: unknown): value is ProviderInitialEnvironment;
+export declare function isEnhancementNavigationOrigin(value: unknown): value is string;
+/** owner is derived by the accepted Provider control host, never from an ordinary action payload. */
+export type BrowserEnhancementRequest = ({
+    operation: 'probe';
+    tabId: number;
+} | {
+    operation: 'inspect';
+    owner: string;
+    tabId: number;
+    targetId: string;
+    actions: BrowserEnhancementAction[];
+    navigationOrigin: string;
+} | {
+    operation: 'bind';
+    owner: string;
+    tabId: number;
+    mainFrameId: string;
+    targetId?: string;
+    actions: BrowserEnhancementAction[];
+    navigationOrigin?: string;
+    initialEnvironment?: ProviderInitialEnvironment;
+} | ({
+    operation: 'invoke';
+    owner: string;
+    bindingId: string;
+    generation: number;
+} & BrowserEnhancementInvocation) | {
+    operation: 'release';
+    owner: string;
+    bindingId: string;
+    generation: number;
+}) & {
+    deadline?: number;
+};
+export type BrowserEnhancementResponse = {
+    capabilities: BrowserEnhancementCapabilities;
+    tabId: number;
+    mainFrameId: string;
+    targetId?: string;
+} | {
+    preparation: BrowserEnhancementPreparation;
+} | {
+    binding: BrowserEnhancementBinding;
+} | {
+    result: unknown;
+} | {
+    released: boolean;
+    conflicts?: string[];
+};
+export interface ProviderEnhancementBinding extends BrowserEnhancementBinding {
+    nativeBrowserId: string;
+    providerTabId: number;
+}
+/** Read-only control/identity preflight supplied by the external page owner. */
+export type ProviderEnhancementTarget = {
+    tabId: number;
+    ready: false;
+} | {
+    tabId: number;
+    ready: true;
+    mainFrameId?: string;
+    targetId?: string;
+    url: string;
+    initialEnvironment?: ProviderInitialEnvironment;
+};
+export declare function isProviderEnhancementTarget(value: unknown): value is ProviderEnhancementTarget;
+/** Match every identity asserted by the external owner; URL alone is never proof. */
+export declare function matchesProviderEnhancementTarget(target: Extract<ProviderEnhancementTarget, {
+    ready: true;
+}>, physical: {
+    mainFrameId: string;
+    targetId?: string;
+}): boolean;
+export declare function requireReadyProviderEnhancementTarget(value: unknown, tabId: number): Extract<ProviderEnhancementTarget, {
+    ready: true;
+}>;
+/** Provider-side request. The control host supplies ownership and physical tab mappings. */
+export type ProviderEnhancementRequest = {
+    operation: 'inspect';
+    providerTabId: number;
+    nativeBrowserId?: string;
+    actions: BrowserEnhancementAction[];
+    navigationOrigin: string;
+} | {
+    operation: 'bind';
+    providerTabId: number;
+    nativeBrowserId?: string;
+    actions: BrowserEnhancementAction[];
+    navigationOrigin?: string;
+} | ({
+    operation: 'invoke';
+    bindingId: string;
+    generation: number;
+} & BrowserEnhancementInvocation) | {
+    operation: 'release';
+    bindingId: string;
+    generation: number;
+};
+export type ProviderEnhancementResponse = {
+    preparation: ProviderEnhancementPreparation;
+} | {
+    binding: ProviderEnhancementBinding;
+} | {
+    result: unknown;
+} | {
+    released: boolean;
+    conflicts?: string[];
+};