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

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/cookie.d.ts

@@ -25,6 +25,12 @@ export interface CookieCandidate {
     partitionKey?: unknown;
     partitionKeyOpaque?: boolean;
 }
+export type RequestCookie = Pick<CookieCandidate, 'name' | 'value'>;
+export declare function serializeRequestCookies(cookies: readonly RequestCookie[]): string;
+/** Token lookup follows the first (most specific path) occurrence in the Cookie header. */
+export declare function requestCookiesToMap(cookies: readonly RequestCookie[]): Map<string, string>;
+/** Chromium also treats localhost and loopback URLs as trustworthy for Secure cookies. */
+export declare function isSecureCookieUrl(url: URL): boolean;
 /** Filter browser-context storage results to the cookies applicable to the requested URL. */
 export declare function filterCookiesForUrl<T extends CookieCandidate>(cookies: readonly T[], cookieUrl: string): T[];
 /** Select one readable, non-partitioned named cookie from URL-filtered backend results. */

package/dist/cookie.js

@@ -1,3 +1,15 @@
+export function serializeRequestCookies(cookies) {
+    return cookies.map(cookie => `${cookie.name}=${cookie.value}`).join('; ');
+}
+/** Token lookup follows the first (most specific path) occurrence in the Cookie header. */
+export function requestCookiesToMap(cookies) {
+    const values = new Map();
+    for (const cookie of cookies) {
+        if (!values.has(cookie.name))
+            values.set(cookie.name, cookie.value);
+    }
+    return values;
+}
 function normalizeCookieDomain(input, action) {
     const value = input.trim();
     if (!value)
@@ -14,21 +26,24 @@ function normalizeCookieDomain(input, action) {
         throw new Error(`${action}: invalid domain "${input}"`);
     return hostname;
 }
-/** Filter browser-context storage results to the cookies applicable to the requested URL. */
-export function filterCookiesForUrl(cookies, cookieUrl) {
-    const url = new URL(cookieUrl);
+/** Chromium also treats localhost and loopback URLs as trustworthy for Secure cookies. */
+export function isSecureCookieUrl(url) {
     const hostname = url.hostname.replace(/\.$/, '');
     const isLocalhost = hostname === 'localhost' ||
         hostname.endsWith('.localhost') ||
         hostname === '[::1]' ||
         /^127\.\d+\.\d+\.\d+$/.test(hostname);
+    return url.protocol === 'https:' || isLocalhost;
+}
+/** Filter browser-context storage results to the cookies applicable to the requested URL. */
+export function filterCookiesForUrl(cookies, cookieUrl) {
+    const url = new URL(cookieUrl);
     return cookies.filter(item => {
         const domain = item.domain.replace(/^\./, '').toLowerCase();
         const hostOnly = item.hostOnly ?? !item.domain.startsWith('.');
         if (url.hostname !== domain && (hostOnly || !url.hostname.endsWith(`.${domain}`)))
             return false;
-        // Chromium treats localhost and loopback URLs as trustworthy for Secure cookies.
-        if (item.secure && url.protocol !== 'https:' && !isLocalhost)
+        if (item.secure && !isSecureCookieUrl(url))
             return false;
         return (url.pathname === item.path ||
             (url.pathname.startsWith(item.path) &&

package/dist/dataStructure.d.ts

@@ -0,0 +1,8 @@
+export interface StructureOptions {
+    maxDepth?: number;
+    maxKeys?: number;
+    arraySamples?: number;
+    maxNodes?: number;
+}
+/** Describes a bounded sample of a value without invoking accessors or exposing leaf values. */
+export declare function getStructure(data: unknown, options?: StructureOptions): unknown;

package/dist/dataStructure.js

@@ -0,0 +1,58 @@
+/** Describes a bounded sample of a value without invoking accessors or exposing leaf values. */
+export function getStructure(data, options = {}) {
+    const { maxDepth = 5, maxKeys = 50, arraySamples = 1, maxNodes = 2000 } = options;
+    for (const [name, value, limit] of [
+        ['maxDepth', maxDepth, 20],
+        ['maxKeys', maxKeys, 1000],
+        ['arraySamples', arraySamples, 20],
+        ['maxNodes', maxNodes, 10000],
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 1 || value > limit)
+            throw new Error(`${name} must be an integer between 1 and ${limit}`);
+    }
+    const ancestors = new WeakSet();
+    let nodes = 0;
+    const visit = (value, depth) => {
+        if (++nodes > maxNodes)
+            return '<max nodes reached>';
+        if (depth >= maxDepth)
+            return '<max depth reached>';
+        if (value === null)
+            return 'null';
+        if (typeof value !== 'object')
+            return typeof value;
+        if (ancestors.has(value))
+            return '<circular>';
+        ancestors.add(value);
+        try {
+            if (Array.isArray(value)) {
+                if (!value.length)
+                    return 'array[0]';
+                const samples = Array.from({ length: Math.min(value.length, arraySamples) }, (_, index) => {
+                    const descriptor = Object.getOwnPropertyDescriptor(value, index);
+                    return descriptor && 'value' in descriptor
+                        ? visit(descriptor.value, depth + 1)
+                        : descriptor
+                            ? '<accessor>'
+                            : 'undefined';
+                });
+                return {
+                    _type: `array[${value.length}]`,
+                    ...(arraySamples === 1 ? { _sample: samples[0] } : { _samples: samples }),
+                };
+            }
+            const keys = Object.keys(value);
+            const entries = keys.slice(0, maxKeys).map(key => {
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                return [key, 'value' in descriptor ? visit(descriptor.value, depth + 1) : '<accessor>'];
+            });
+            if (keys.length > maxKeys)
+                entries.push(['<truncated keys>', keys.length - maxKeys]);
+            return Object.fromEntries(entries);
+        }
+        finally {
+            ancestors.delete(value);
+        }
+    };
+    return visit(data, 0);
+}

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 },
             };
         }
     }
@@ -365,9 +388,22 @@ export function clickElementViaJS(expectedText) {
     let hitTarget = null;
     try {
         hitTarget = document.elementFromPoint(cx, cy);
+        const visited = new Set();
+        while (hitTarget?.shadowRoot?.elementFromPoint && !visited.has(hitTarget)) {
+            visited.add(hitTarget);
+            const inner = hitTarget.shadowRoot.elementFromPoint(cx, cy);
+            if (!inner || inner === hitTarget)
+                break;
+            hitTarget = inner;
+        }
     }
     catch { }
+    let composedHit = hitTarget;
+    while (composedHit && composedHit !== target) {
+        composedHit = composedHit.parentElement || composedHit.getRootNode?.().host;
+    }
     if (hitTarget &&
+        !composedHit &&
         hitTarget !== target &&
         !target.contains?.(hitTarget) &&
         !hitTarget.contains?.(target)) {
@@ -511,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();
@@ -527,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 },
             };
         }
     }
@@ -680,9 +729,22 @@ export function clickElementBySelector(selector, invalidSelectorHint) {
     let hitTarget = null;
     try {
         hitTarget = document.elementFromPoint(cx, cy);
+        const visited = new Set();
+        while (hitTarget?.shadowRoot?.elementFromPoint && !visited.has(hitTarget)) {
+            visited.add(hitTarget);
+            const inner = hitTarget.shadowRoot.elementFromPoint(cx, cy);
+            if (!inner || inner === hitTarget)
+                break;
+            hitTarget = inner;
+        }
     }
     catch { }
+    let composedHit = hitTarget;
+    while (composedHit && composedHit !== target) {
+        composedHit = composedHit.parentElement || composedHit.getRootNode?.().host;
+    }
     if (hitTarget &&
+        !composedHit &&
         hitTarget !== target &&
         !target.contains(hitTarget) &&
         !hitTarget.contains(target)) {
@@ -1001,9 +1063,22 @@ export function getClickCoordsFromSelector(selector, invalidSelectorHint) {
     let hitTarget = null;
     try {
         hitTarget = document.elementFromPoint(x, y);
+        const visited = new Set();
+        while (hitTarget?.shadowRoot?.elementFromPoint && !visited.has(hitTarget)) {
+            visited.add(hitTarget);
+            const inner = hitTarget.shadowRoot.elementFromPoint(x, y);
+            if (!inner || inner === hitTarget)
+                break;
+            hitTarget = inner;
+        }
     }
     catch { }
+    let composedHit = hitTarget;
+    while (composedHit && composedHit !== target) {
+        composedHit = composedHit.parentElement || composedHit.getRootNode?.().host;
+    }
     if (hitTarget &&
+        !composedHit &&
         hitTarget !== target &&
         !target.contains(hitTarget) &&
         !hitTarget.contains(target)) {
@@ -1295,9 +1370,22 @@ export function getClickCoordsFromNode(expectedText) {
     let hitTarget = null;
     try {
         hitTarget = document.elementFromPoint(x, y);
+        const visited = new Set();
+        while (hitTarget?.shadowRoot?.elementFromPoint && !visited.has(hitTarget)) {
+            visited.add(hitTarget);
+            const inner = hitTarget.shadowRoot.elementFromPoint(x, y);
+            if (!inner || inner === hitTarget)
+                break;
+            hitTarget = inner;
+        }
     }
     catch { }
+    let composedHit = hitTarget;
+    while (composedHit && composedHit !== target) {
+        composedHit = composedHit.parentElement || composedHit.getRootNode?.().host;
+    }
     if (hitTarget &&
+        !composedHit &&
         hitTarget !== target &&
         !target.contains?.(hitTarget) &&
         !hitTarget.contains?.(target)) {
@@ -1353,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/domInspection.js

@@ -211,9 +211,21 @@ export function inspectElementsInPage(selector, filter, styles, maxResults, inva
         let hit = null;
         try {
             hit = visible ? (documentRef.elementFromPoint?.(x, y) ?? null) : null;
+            const visited = new Set();
+            while (hit?.shadowRoot?.elementFromPoint && !visited.has(hit)) {
+                visited.add(hit);
+                const inner = hit.shadowRoot.elementFromPoint(x, y);
+                if (!inner || inner === hit)
+                    break;
+                hit = inner;
+            }
         }
         catch { }
-        const topmost = !!hit && (hit === element || element.contains?.(hit));
+        let composedHit = hit;
+        while (composedHit && composedHit !== element) {
+            composedHit = composedHit.parentElement || composedHit.getRootNode?.().host;
+        }
+        const topmost = !!hit && (!!composedHit || element.contains?.(hit));
         const target = hit
             ? {
                 selector: selectorFor(hit),

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;
@@ -206,6 +211,7 @@ export interface HostToExtensionActionMap {
     __control_cleanup: {
         request: BrowserReleaseParams & {
             tabIds: number[];
+            returningToAgent?: boolean;
         };
         response: BrowserReleaseResult;
     };
@@ -249,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;