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

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[];
+};

package/dist/browserEnhancement.js

@@ -0,0 +1,80 @@
+import { isDeviceEnvironmentObservation } from './deviceEnvironmentObservation.js';
+export const BROWSER_ENHANCEMENT_PROTOCOL_VERSION = 1;
+export const BROWSER_ENHANCEMENT_NAVIGATION_ORIGIN_VERSION = 1;
+export const BROWSER_ENHANCEMENT_PREPARATION_VERSION = 1;
+export const BROWSER_ENHANCEMENT_HOST_ENVIRONMENT_VERSION = 1;
+export 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 function isBrowserEnhancementPreparationUrl(value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        const url = new URL(value);
+        return /^[a-p]{32}$/.test(url.hostname) && value === `chrome-extension://${url.hostname}/${BROWSER_ENHANCEMENT_PREPARATION_PATH}`;
+    }
+    catch {
+        return false;
+    }
+}
+export function isBrowserEnhancementAction(value) {
+    return value === 'set_device_emulation' || value === 'set_app_profile' || value === 'set_timezone';
+}
+export function requiredBrowserEnhancementActions(invocation) {
+    return invocation.action === 'set_app_profile' && invocation.data?.emulation !== undefined
+        ? ['set_app_profile', 'set_device_emulation'] : [invocation.action];
+}
+export function isProviderInitialEnvironment(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const device = value.device;
+    const only = (record, keys) => Object.keys(record).every(key => keys.includes(key));
+    try {
+        return isDeviceEnvironmentObservation(device) && device.userAgent.length <= 4096 &&
+            device.platform.length <= 256 && JSON.stringify(value).length <= 32_768 && only(value, ['device', 'preserveHostPlatform', 'preserveHostInput']) &&
+            (value.preserveHostPlatform === undefined || value.preserveHostPlatform === true) &&
+            (value.preserveHostInput === undefined || value.preserveHostInput === true) &&
+            only(device, ['userAgent', 'platform', 'userAgentMetadata', 'screen', 'touchPoints', 'safeAreaInsets']) &&
+            only(device.screen, ['width', 'height', 'deviceScaleFactor', 'orientation', 'angle']) && only(device.safeAreaInsets, ['top', 'right', 'bottom', 'left']) &&
+            (device.userAgentMetadata === null || (only(device.userAgentMetadata, ['brands', 'fullVersionList', 'fullVersion', 'platform', 'platformVersion', 'architecture', 'model', 'mobile', 'bitness', 'wow64', 'formFactors']) &&
+                [...device.userAgentMetadata.brands, ...device.userAgentMetadata.fullVersionList].every(brand => only(brand, ['brand', 'version']))));
+    }
+    catch {
+        return false;
+    }
+}
+export function isEnhancementNavigationOrigin(value) {
+    if (typeof value !== 'string' || value.length > 4096)
+        return false;
+    try {
+        const url = new URL(value);
+        return ['http:', 'https:'].includes(url.protocol) && url.origin === value;
+    }
+    catch {
+        return false;
+    }
+}
+export function isProviderEnhancementTarget(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const target = value;
+    return Number.isSafeInteger(target.tabId) && target.tabId >= 0 &&
+        (value.ready === false || (target.ready === true &&
+            (target.mainFrameId === undefined || validIdentity(target.mainFrameId)) &&
+            (target.targetId === undefined || validIdentity(target.targetId)) &&
+            (target.initialEnvironment === undefined || isProviderInitialEnvironment(target.initialEnvironment)) &&
+            (target.mainFrameId !== undefined || target.targetId !== undefined) && typeof target.url === 'string' && Boolean(target.url)));
+}
+function validIdentity(value) { return typeof value === 'string' && value.length > 0 && value.length <= 256; }
+/** Match every identity asserted by the external owner; URL alone is never proof. */
+export function matchesProviderEnhancementTarget(target, physical) {
+    return Boolean(target.mainFrameId || target.targetId) &&
+        (target.mainFrameId === undefined || target.mainFrameId === physical.mainFrameId) &&
+        (target.targetId === undefined || target.targetId === physical.targetId);
+}
+export function requireReadyProviderEnhancementTarget(value, tabId) {
+    if (!isProviderEnhancementTarget(value) || value.tabId !== tabId)
+        throw new Error('BROWSER_ENHANCEMENT_PAGE_IDENTITY_UNAVAILABLE');
+    if (!value.ready)
+        throw new Error('EXTERNAL_CONTROL_PAUSED: the external page owner has not granted Agent control');
+    return value;
+}

package/dist/deviceEnvironmentObservation.d.ts

@@ -0,0 +1,48 @@
+import type { ResolvedEmulationConfig } from './deviceEmulation.js';
+export interface DeviceUserAgentMetadata {
+    brands: Array<{
+        brand: string;
+        version: string;
+    }>;
+    fullVersionList: Array<{
+        brand: string;
+        version: string;
+    }>;
+    fullVersion?: string;
+    platform: string;
+    platformVersion: string;
+    architecture: string;
+    model: string;
+    mobile: boolean;
+    bitness?: string;
+    wow64?: boolean;
+    formFactors?: string[];
+}
+export interface DeviceEnvironmentObservation {
+    userAgent: string;
+    platform: string;
+    userAgentMetadata: DeviceUserAgentMetadata | null;
+    screen: {
+        width: number;
+        height: number;
+        deviceScaleFactor: number;
+        orientation: string;
+        angle: number;
+    };
+    touchPoints: number;
+    safeAreaInsets: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+/** Explicitly disables UA Client Hints for an emulated UA, matching Chrome's omitted-metadata behavior. */
+export declare function emptyDeviceUserAgentMetadata(): DeviceUserAgentMetadata;
+/** Self-contained observation for an isolated page world; no retained DOM or page globals. */
+export declare function observeDeviceEnvironment(): Promise<DeviceEnvironmentObservation>;
+export declare function isDeviceUserAgentMetadata(value: unknown): value is DeviceUserAgentMetadata;
+export declare function isDeviceEnvironmentObservation(value: unknown): value is DeviceEnvironmentObservation;
+/** CDP transports can reorder object keys. Values and array order remain significant. */
+export declare function deviceEnvironmentObservationsEqual(left: DeviceEnvironmentObservation, right: DeviceEnvironmentObservation): boolean;
+export declare function matchesEmulatedDeviceEnvironment(config: ResolvedEmulationConfig, observed: DeviceEnvironmentObservation): boolean;

package/dist/deviceEnvironmentObservation.js

@@ -0,0 +1,77 @@
+/** Explicitly disables UA Client Hints for an emulated UA, matching Chrome's omitted-metadata behavior. */
+export function emptyDeviceUserAgentMetadata() {
+    return { brands: [], fullVersionList: [], fullVersion: '', platform: '', platformVersion: '', architecture: '', model: '',
+        mobile: false, bitness: '', wow64: false, formFactors: [] };
+}
+/** Self-contained observation for an isolated page world; no retained DOM or page globals. */
+export async function observeDeviceEnvironment() {
+    const data = navigator.userAgentData;
+    let userAgentMetadata = null;
+    if (data) {
+        const values = await data.getHighEntropyValues(['architecture', 'bitness', 'fullVersionList', 'model', 'platformVersion', 'uaFullVersion', 'wow64', 'formFactors']);
+        userAgentMetadata = {
+            brands: values.brands, fullVersionList: values.fullVersionList,
+            ...(typeof values.uaFullVersion === 'string' ? { fullVersion: values.uaFullVersion } : {}),
+            platform: values.platform, platformVersion: values.platformVersion, architecture: values.architecture, model: values.model, mobile: values.mobile,
+            ...(typeof values.bitness === 'string' ? { bitness: values.bitness } : {}),
+            ...(typeof values.wow64 === 'boolean' ? { wow64: values.wow64 } : {}),
+            ...(Array.isArray(values.formFactors) ? { formFactors: values.formFactors } : {}),
+        };
+    }
+    const probe = document.createElement('div');
+    probe.style.cssText = 'all:initial!important;position:fixed!important;visibility:hidden!important;pointer-events:none!important;width:0!important;height:0!important;padding-top:env(safe-area-inset-top)!important;padding-right:env(safe-area-inset-right)!important;padding-bottom:env(safe-area-inset-bottom)!important;padding-left:env(safe-area-inset-left)!important;';
+    document.documentElement.appendChild(probe);
+    try {
+        const style = getComputedStyle(probe);
+        return {
+            userAgent: navigator.userAgent, platform: navigator.platform, userAgentMetadata,
+            screen: { width: screen.width, height: screen.height, deviceScaleFactor: devicePixelRatio, orientation: screen.orientation.type, angle: screen.orientation.angle },
+            touchPoints: navigator.maxTouchPoints,
+            safeAreaInsets: { top: parseFloat(style.paddingTop) || 0, right: parseFloat(style.paddingRight) || 0, bottom: parseFloat(style.paddingBottom) || 0, left: parseFloat(style.paddingLeft) || 0 },
+        };
+    }
+    finally {
+        probe.remove();
+    }
+}
+export function isDeviceUserAgentMetadata(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const metadata = value;
+    const brands = (value) => Array.isArray(value) && value.every(item => item && typeof item.brand === 'string' && typeof item.version === 'string');
+    return brands(metadata.brands) && brands(metadata.fullVersionList) &&
+        [metadata.platform, metadata.platformVersion, metadata.architecture, metadata.model].every(value => typeof value === 'string') &&
+        typeof metadata.mobile === 'boolean' && (metadata.fullVersion === undefined || typeof metadata.fullVersion === 'string') &&
+        (metadata.bitness === undefined || typeof metadata.bitness === 'string') && (metadata.wow64 === undefined || typeof metadata.wow64 === 'boolean') &&
+        (metadata.formFactors === undefined || (Array.isArray(metadata.formFactors) && metadata.formFactors.every(value => typeof value === 'string')));
+}
+export function isDeviceEnvironmentObservation(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const current = value;
+    return typeof current.userAgent === 'string' && typeof current.platform === 'string' &&
+        (current.userAgentMetadata === null || isDeviceUserAgentMetadata(current.userAgentMetadata)) &&
+        Boolean(current.screen) && [current.screen.width, current.screen.height, current.screen.deviceScaleFactor].every(value => Number.isFinite(value) && value > 0) &&
+        typeof current.screen.orientation === 'string' && Number.isFinite(current.screen.angle) &&
+        Number.isSafeInteger(current.touchPoints) && current.touchPoints >= 0 && Boolean(current.safeAreaInsets) &&
+        [current.safeAreaInsets.top, current.safeAreaInsets.right, current.safeAreaInsets.bottom, current.safeAreaInsets.left].every(value => Number.isFinite(value) && value >= 0);
+}
+/** CDP transports can reorder object keys. Values and array order remain significant. */
+export function deviceEnvironmentObservationsEqual(left, right) {
+    const ordered = (value) => {
+        if (Array.isArray(value))
+            return value.map(ordered);
+        if (value && typeof value === 'object')
+            return Object.fromEntries(Object.keys(value).sort().map(key => [key, ordered(value[key])]));
+        return value;
+    };
+    return JSON.stringify(ordered(left)) === JSON.stringify(ordered(right));
+}
+export function matchesEmulatedDeviceEnvironment(config, observed) {
+    return observed.userAgent === config.userAgent && observed.platform === config.platform &&
+        observed.screen.width === config.width && observed.screen.height === config.height &&
+        Math.abs(observed.screen.deviceScaleFactor - config.deviceScaleFactor) < 0.0001 &&
+        observed.screen.orientation.startsWith(config.orientation) && observed.screen.angle === (config.orientation === 'landscape' ? 90 : 0) &&
+        observed.touchPoints === (config.touch ? 5 : 0) &&
+        ['top', 'right', 'bottom', 'left'].every(edge => observed.safeAreaInsets[edge] === config.safeAreaInsets[edge]);
+}

package/dist/domClicking.d.ts

@@ -40,6 +40,7 @@ export interface PageClickDispatchTarget {
     frame?: PageClickFrameTarget;
     coordinates?: PageClickCoordinates;
     controlState?: PageClickControlState;
+    selectionState?: PageClickSelectionState;
     dispatchMode?: PageClickDispatchMode;
     pointerType?: PageClickPointerType;
 }
@@ -84,6 +85,15 @@ export interface PageClickControlState {
     checkedBefore: boolean;
     checkedAfter: boolean;
 }
+export interface PageClickSelectionState {
+    valueBefore: string;
+    valueAfter: string;
+    selectedAfter: boolean;
+}
+/** Native options need value selection; clicking their select only opens the menu. */
+export declare function isStateAwareClickTarget(target: PageClickDispatchTarget & {
+    inputType?: string;
+}): boolean;
 export interface PageClickResolvedTarget {
     tag: string;
     text: string;
@@ -102,6 +112,7 @@ export interface PageClickResultData {
     coordinates?: PageClickCoordinates;
     actionableAncestorCandidates?: PageClickAncestorCandidate[];
     controlState?: PageClickControlState;
+    selectionState?: PageClickSelectionState;
     dispatchMode?: PageClickDispatchMode;
     pointerType?: PageClickPointerType;
     fallbackReason?: PageClickFallbackReason;
@@ -127,6 +138,7 @@ export interface PageClickDispatchAttemptEvidence {
     coordinates?: PageClickCoordinates;
     actionableAncestorCandidates?: Array<Pick<PageClickAncestorCandidate, 'selector' | 'distance' | 'reason'>>;
     controlState?: PageClickControlState;
+    selectionState?: PageClickSelectionState;
     dispatchMode?: PageClickDispatchMode;
     pointerType?: PageClickPointerType;
 }
@@ -161,6 +173,7 @@ export declare function clickElementViaJS(this: any, expectedText?: string): {
         text: string;
     };
     controlState?: PageClickControlState;
+    selectionState?: PageClickSelectionState;
     error?: string;
 } | null;
 /**
@@ -179,6 +192,7 @@ export declare function clickElementBySelector(selector: string, invalidSelector
     strategy?: PageClickTargetStrategy;
     distance?: number;
     controlState?: PageClickControlState;
+    selectionState?: PageClickSelectionState;
     error?: string;
 };
 /**

package/dist/domClicking.js

@@ -12,6 +12,12 @@ export const PAGE_CLICK_INPUT_TIMEOUT_MS = 10_000;
 export const PAGE_CLICK_HIDDEN_TOUCH_ERROR = 'page_click: clickMode "touch" requires a visible page, but the target is hidden or in a background tab. ' +
     'Use clickMode "auto" for DOM fallback, or call tab_open for the same URL with reuse "require" and active true. ' +
     'Extension activation uses background focus emulation while Do not disturb is enabled; check activation.visibilityState before retrying trusted input; use "mouse" only when touch semantics are not required.';
+/** Native options need value selection; clicking their select only opens the menu. */
+export function isStateAwareClickTarget(target) {
+    return (target.tag === 'option' ||
+        target.sourceTarget?.tag === 'option' ||
+        /^(checkbox|radio)$/i.test(target.inputType ?? ''));
+}
 /** Resolve the click path from the requested mode, page visibility, and device emulation state. */
 export function resolvePageClickDispatchPolicy(clickMode, visibilityState, touchEmulationEnabled) {
     if (clickMode !== undefined && clickMode !== 'auto') {
@@ -62,6 +68,7 @@ export function createPageClickResult(requestedTarget, dispatchTarget) {
             ? { actionableAncestorCandidates: evidence.actionableAncestorCandidates }
             : {}),
         ...(evidence.controlState ? { controlState: evidence.controlState } : {}),
+        ...(evidence.selectionState ? { selectionState: evidence.selectionState } : {}),
         ...(evidence.dispatchMode ? { dispatchMode: evidence.dispatchMode } : {}),
         ...(evidence.pointerType ? { pointerType: evidence.pointerType } : {}),
     };
@@ -90,6 +97,7 @@ export function describePageClickDispatchTarget(dispatchTarget) {
             ? { actionableAncestorCandidates: dispatchTarget.actionableAncestorCandidates }
             : {}),
         ...(dispatchTarget.controlState ? { controlState: dispatchTarget.controlState } : {}),
+        ...(dispatchTarget.selectionState ? { selectionState: dispatchTarget.selectionState } : {}),
         ...(dispatchTarget.dispatchMode ? { dispatchMode: dispatchTarget.dispatchMode } : {}),
         ...(dispatchTarget.pointerType ? { pointerType: dispatchTarget.pointerType } : {}),
     };
@@ -126,6 +134,7 @@ export function describePageClickDispatchAttempt(dispatchTarget) {
             }
             : {}),
         ...(evidence.controlState ? { controlState: evidence.controlState } : {}),
+        ...(evidence.selectionState ? { selectionState: evidence.selectionState } : {}),
         ...(evidence.dispatchMode ? { dispatchMode: evidence.dispatchMode } : {}),
         ...(evidence.pointerType ? { pointerType: evidence.pointerType } : {}),
     };
@@ -149,11 +158,24 @@ export function clickElementViaJS(expectedText) {
     if (el.tagName === 'OPTION') {
         const select = el.closest('select');
         if (select) {
-            const desc = Object.getOwnPropertyDescriptor(window.HTMLSelectElement.prototype, 'value');
+            if (select.matches(':disabled') || el.disabled || el.closest('optgroup')?.disabled) {
+                return {
+                    tag: 'option',
+                    text: sourceTarget.text,
+                    cx: 0,
+                    cy: 0,
+                    strategy: 'self',
+                    distance: 0,
+                    sourceTarget,
+                    error: 'Cannot select a disabled option',
+                };
+            }
+            const valueBefore = select.value;
+            const desc = Object.getOwnPropertyDescriptor(window.HTMLSelectElement.prototype, 'selectedIndex');
             if (desc && desc.set)
-                desc.set.call(select, el.value);
+                desc.set.call(select, el.index);
             else
-                select.value = el.value;
+                select.selectedIndex = el.index;
             select.dispatchEvent(new Event('input', { bubbles: true }));
             select.dispatchEvent(new Event('change', { bubbles: true }));
             const rect = select.getBoundingClientRect();
@@ -165,6 +187,7 @@ export function clickElementViaJS(expectedText) {
                 strategy: 'self',
                 distance: 0,
                 sourceTarget,
+                selectionState: { valueBefore, valueAfter: select.value, selectedAfter: el.selected },
             };
         }
     }
@@ -524,11 +547,23 @@ export function clickElementBySelector(selector, invalidSelectorHint) {
     if (element.tagName === 'OPTION') {
         const select = element.closest('select');
         if (select) {
-            const desc = Object.getOwnPropertyDescriptor(window.HTMLSelectElement.prototype, 'value');
+            const option = element;
+            if (select.matches(':disabled') || option.disabled || option.closest('optgroup')?.disabled) {
+                return {
+                    clicked: false,
+                    tag: 'option',
+                    text: (option.textContent || '').trim().slice(0, 100),
+                    cx: 0,
+                    cy: 0,
+                    error: 'Cannot select a disabled option',
+                };
+            }
+            const valueBefore = select.value;
+            const desc = Object.getOwnPropertyDescriptor(window.HTMLSelectElement.prototype, 'selectedIndex');
             if (desc && desc.set)
-                desc.set.call(select, element.value);
+                desc.set.call(select, option.index);
             else
-                select.value = element.value;
+                select.selectedIndex = option.index;
             select.dispatchEvent(new Event('input', { bubbles: true }));
             select.dispatchEvent(new Event('change', { bubbles: true }));
             const rect = select.getBoundingClientRect();
@@ -540,6 +575,7 @@ export function clickElementBySelector(selector, invalidSelectorHint) {
                 cy: rect.y + rect.height / 2,
                 strategy: 'self',
                 distance: 0,
+                selectionState: { valueBefore, valueAfter: select.value, selectedAfter: option.selected },
             };
         }
     }
@@ -1405,12 +1441,12 @@ export function showClickIndicator(px, py, mode) {
             ring +
             ';' +
             'pointer-events:none; z-index:2147483647;' +
-            'animation:__mtop_click_fade 600ms ease-out forwards;';
-    if (!document.getElementById('__mtop_click_style')) {
+            'animation:__mearl_click_fade 600ms ease-out forwards;';
+    if (!document.getElementById('__mearl_click_style')) {
         const style = document.createElement('style');
-        style.id = '__mtop_click_style';
+        style.id = '__mearl_click_style';
         style.textContent =
-            '@keyframes __mtop_click_fade {' +
+            '@keyframes __mearl_click_fade {' +
                 '0% { opacity:1; transform:scale(1); }' +
                 '50% { opacity:0.8; transform:scale(1.8); }' +
                 '100% { opacity:0; transform:scale(2.2); }' +

package/dist/extensionServiceProtocol.d.ts

@@ -1,5 +1,6 @@
 import type { BrowserAccessResult, BrowserActionMap, BrowserJsonValue, BrowserProviderListResult, BrowserProviderLaunchForm, ControlSessionInfo, CookieCopyScope, ManagedBrowserInfo, BrowserReleaseParams, BrowserReleaseResult, PageDownloadParams } from './browserActionProtocol.js';
 import { type AgentServiceActionMap } from './agentServiceProtocol.js';
+import type { BrowserEnhancementRequest, BrowserEnhancementResponse } from './browserEnhancement.js';
 import { type ToolboxServiceActionMap, type ToolboxTaskRequest, type ToolboxTaskResponse } from './toolbox.js';
 export declare const EXTENSION_RPC_VERSION = 1;
 export type OperationRequest<M> = {
@@ -171,6 +172,10 @@ export type ExtensionUiServiceRequest<A extends ExtensionUiServiceAction> = Exte
 export type ExtensionUiServiceResponse<A extends ExtensionUiServiceAction, R> = A extends BrowserManagementAction ? BrowserManagementResponse<A, R> : A extends 'toolbox_task' ? R extends ToolboxTaskRequest ? ToolboxTaskResponse<R> : never : ExtensionUiServiceActionMap[A]['response'];
 export declare function isExtensionUiServiceAction(value: unknown): value is ExtensionUiServiceAction;
 export interface HostToExtensionActionMap {
+    __browser_enhancement: {
+        request: BrowserEnhancementRequest;
+        response: BrowserEnhancementResponse;
+    };
     __preset_installation: {
         request: Record<string, unknown>;
         response: unknown;
@@ -250,6 +255,7 @@ export interface HostToExtensionActionMap {
     };
 }
 export declare const HOST_TO_EXTENSION_ACTIONS: {
+    readonly __browser_enhancement: true;
     readonly __preset_installation: true;
     readonly __preset_browser: true;
     readonly __export_cookies: true;

package/dist/extensionServiceProtocol.js

@@ -28,6 +28,7 @@ export function isExtensionUiServiceAction(value) {
         isCloudConnectorAction(value));
 }
 export const HOST_TO_EXTENSION_ACTIONS = {
+    __browser_enhancement: true,
     __preset_installation: true,
     __preset_browser: true,
     __export_cookies: true,

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export * from './appProfileDefinition.js';
 export * from './types.js';
+export * from './browserEnhancement.js';
+export * from './browserDiscovery.js';
+export * from './providerAppResources.js';
 export * from './eventFilters.js';
 export * from './requestSerializer.js';
 export * from './boundedRequestBuffer.js';
@@ -10,6 +13,7 @@ export * from './domScrolling.js';
 export * from './domInspection.js';
 export * from './domSnapshot.js';
 export * from './deviceEmulation.js';
+export * from './deviceEnvironmentObservation.js';
 export * from './debuggerTarget.js';
 export * from './rootWebViewNavigation.js';
 export type { AppBridgeStyle, AppBridgeSpec, AppBridgeBehavior, BridgeActionMap, AppSchemeRule, AppMiniProgramConfig, AppMiniProgramPaymentRoute, AppMiniProgramMessageAction, AppMiniProgramMessageRule, AppMiniProgramNativeAction, AppMiniProgramNativeRoute, AppImagePickerConfig, AppOverlayConfig, AppNativeBackConfig, AppLayerUrlProxyConfig, AppTitleBarConfig, AppTitleBarHostStyle, AppSafeAreaInsets, AppRootContainerCookie, AppRootContainerConfig, InjectedAppProfileConfig, AppProfileHostCapabilities, } from './app-profile-runtime/types.js';
@@ -21,6 +25,7 @@ export * from './axSnapshot.js';
 export * from './pageObserver.js';
 export * from './navigationTracker.js';
 export * from './pageAct.js';
+export * from './pageDialog.js';
 export * from './backendNodeRefs.js';
 export * from './pageEffectRefs.js';
 export * from './pageWait.js';
@@ -59,3 +64,4 @@ export { parseQueryString } from './queryString.js';
 export * from './extensionVersion.js';
 export { MEARL_NATIVE_HOST_NAMES, type NativeHostIntegrationMode } from './nativeHostNames.js';
 export * from './dataStructure.js';
+export * from './requestMetadata.js';

package/dist/index.js

@@ -1,5 +1,8 @@
 export * from './appProfileDefinition.js';
 export * from './types.js';
+export * from './browserEnhancement.js';
+export * from './browserDiscovery.js';
+export * from './providerAppResources.js';
 export * from './eventFilters.js';
 export * from './requestSerializer.js';
 export * from './boundedRequestBuffer.js';
@@ -10,6 +13,7 @@ export * from './domScrolling.js';
 export * from './domInspection.js';
 export * from './domSnapshot.js';
 export * from './deviceEmulation.js';
+export * from './deviceEnvironmentObservation.js';
 export * from './debuggerTarget.js';
 export * from './rootWebViewNavigation.js';
 export * from './axTextMatch.js';
@@ -20,6 +24,7 @@ export * from './axSnapshot.js';
 export * from './pageObserver.js';
 export * from './navigationTracker.js';
 export * from './pageAct.js';
+export * from './pageDialog.js';
 export * from './backendNodeRefs.js';
 export * from './pageEffectRefs.js';
 export * from './pageWait.js';
@@ -58,3 +63,4 @@ export { parseQueryString } from './queryString.js';
 export * from './extensionVersion.js';
 export { MEARL_NATIVE_HOST_NAMES } from './nativeHostNames.js';
 export * from './dataStructure.js';
+export * from './requestMetadata.js';

package/dist/pageAct.d.ts

@@ -61,6 +61,7 @@ export interface PageActNavigationObserver {
     dispose(): void | Promise<void>;
 }
 export interface PageActDependencies {
+    dialogs?: import('./pageDialog.js').PageDialogState;
     startObservation(): Promise<PageObservationCheckpoint>;
     finishObservation(checkpoint: PageObservationCheckpoint, options: PageObservationWaitOptions): Promise<PageActObservation>;
     startNavigationObserver(options: {
@@ -89,6 +90,7 @@ interface PageActUnavailableObservation {
 export type PageActObservation = PageChangeSet | PageNavigationChange | PageActUnavailableObservation;
 export type PageActObservationResponse = (Omit<PageChangeSet, 'url' | 'title'> & Partial<Pick<PageChangeSet, 'url' | 'title'>>) | PageNavigationChange | PageActUnavailableObservation;
 export interface PageActResult {
+    dialog?: import('./pageDialog.js').PageDialogInfo;
     action: {
         name: string;
         success: boolean;