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

package/README.md

@@ -2,7 +2,7 @@
 
 浏览器与 Node 可共享的页面控制逻辑和协议：DOM/AX 快照、动作观察、输入、滚动、导航、请求序列化、捕获游标、设备模拟、通用设备外观、Cookie/域名权限和插件任务、页面、状态合同。模块没有浏览器扩展或本机进程的安装副作用。
 
-`APP_PROFILE_NAMES` 只列出飞猪、淘宝、微信、支付宝四个基础身份；动态档案 ID 由宿主的已激活能力目录校验。App 档案 schema、显式选项、revision 和页面运行时绑定是数据合同，完整桥实现由独立能力包提供。
+核心不预置 App 身份；档案 ID 由宿主的已激活能力目录校验。App 档案 schema、显式选项、revision 和页面运行时绑定是数据合同，完整桥实现由独立能力包提供。
 
 `@mearl/browser-core/appProfileRuntime` 的内置安装器只同步 UA、navigator.appVersion、navigator.platform 和触摸点，不安装 App 桥、业务全局变量、容器栈或授权处理。有 pageRuntime 绑定时，宿主必须先从已安装的能力包准备确切代码，再通过页面运行时派发器执行；不能调用基础安装器代替。资源准备和派发见 [能力包](../../docs/browser-bundles.md#页面运行时)。
 

package/dist/app-profile-runtime/types.d.ts

@@ -2,7 +2,7 @@ import type { AppProfileBinding, AppProfilePolicies, AppProfileSetting } from '.
 import type { BrowserDevicePresetName } from '../browserActionProtocol.js';
 import type { DeviceCutout } from '../deviceEmulation.js';
 /** 桥调用风格，与页面适配器使用的端内调用约定一一对应。 */
-export type AppBridgeStyle = 'windvane' | 'fliggy' | 'alipay' | 'callback' | 'btrip' | 'invoke' | 'callHandler' | 'amap' | 'didi' | 'easybikeNative' | 'mega' | 'wechat' | 'wechatMiniProgram';
+export type AppBridgeStyle = string;
 export interface AppBridgeSpec {
     global: string;
     style: AppBridgeStyle;
@@ -10,7 +10,7 @@ export interface AppBridgeSpec {
     persistent?: boolean;
 }
 export type AppBridgeBehavior = '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';
-/** 桥方法名到标准化动作的映射。WindVane 风格使用 `Class.method`，其余使用 api 名。 */
+/** 桥方法名到标准化动作的映射。命名空间桥使用 `Class.method`，其余使用 api 名。 */
 export interface BridgeActionMap {
     open: string[];
     close: string[];
@@ -68,14 +68,14 @@ export interface AppMiniProgramMessageRule {
 }
 export type AppMiniProgramNativeAction = 'navigateMiniProgram' | 'subscribeMessage';
 export interface AppMiniProgramNativeRoute {
-    /** 承接微信原生能力的小程序页面 pathname。 */
+    /** 承接原生能力的小程序页面 pathname。 */
     pathname: string;
     /** 该页面允许模拟的固定原生动作，动作名读取 URL 的 action 参数。 */
     actions: AppMiniProgramNativeAction[];
     /** 限制业务根域，避免其他小程序的同名页面被接管。 */
     hostSuffixes?: string[];
 }
-/** 微信小程序容器相关规则统一收口，避免为每种业务页增加顶层配置。 */
+/** 小程序容器相关规则统一收口，避免为每种业务页增加顶层配置。 */
 export interface AppMiniProgramConfig {
     paymentRoutes?: AppMiniProgramPaymentRoute[];
     nativeRoutes?: AppMiniProgramNativeRoute[];
@@ -187,6 +187,8 @@ export interface InjectedAppProfileConfig {
     binding?: AppProfileBinding;
     policies?: AppProfilePolicies;
     settings?: AppProfileSetting[];
+    settingsUi?: 'runtime';
+    settingsGroup?: string;
     profile: string;
     label: string;
     globals: Record<string, string>;

package/dist/appProfileDefinition.d.ts

@@ -1,9 +1,9 @@
 import type { BrowserDevicePresetName, AppBridgeConfig } from './browserActionProtocol.js';
 import type { AppBridgeSpec, AppImagePickerConfig, AppLayerUrlProxyConfig, AppMiniProgramConfig, AppNativeBackConfig, AppOverlayConfig, AppSchemeRule, AppTitleBarHostStyle, BridgeActionMap } from './app-profile-runtime/types.js';
 export interface AppProfilePolicies {
-    titleBar?: 'default' | 'taobao' | 'fliggy' | 'alipay' | 'wechat';
+    titleBar?: string;
     navigatorLanguage?: boolean;
-    networkResult?: 'default' | 'alipay';
+    networkResult?: string;
     languages?: string[];
     defaultLanguage?: string;
 }
@@ -56,28 +56,49 @@ export interface AppProfileCatalogEntry {
     revision: string;
     definition: AppProfileDefinition;
 }
+/** Short, author-supplied guidance; discovery does not load Skills or follow links. */
+export interface AppProfileUsage {
+    description?: string;
+    limitations?: string[];
+    skills?: string[];
+    documentation?: Array<{
+        title: string;
+        url: string;
+    }>;
+}
 /** 单容器档案（纯数据） */
 export interface AppProfileDefinition {
     name: string;
+    usage?: AppProfileUsage;
     /** Content-addressed installer supplied by the selected browser capability package. */
     pageRuntime?: {
         id: string;
         sha256: string;
     };
     label: string;
-    /** 容器的应用标识，如 LX / TB / AP / WeChat */
+    actionIcon?: string;
+    labels?: {
+        en: string;
+        zh_CN?: string;
+    };
+    /** 容器的应用标识，由能力包定义 */
     appName: string;
     defaultAppVersion: string;
-    /** UA 主体格式；默认使用 AliApp(appName/version) */
-    uaFamily?: 'aliapp' | 'wechatMiniProgram';
+    /** UA 主体格式；未提供时使用标准浏览器 UA */
+    uaFamily?: string;
     uaTemplate?: {
         ios: string;
         android: string;
     };
     policies?: AppProfilePolicies;
     settings?: AppProfileSetting[];
-    settingsGroup?: 'fliggy' | 'alipay';
-    /** AliApp UA 主体之后追加的 token，{v} 占位会被替换为 appVersion */
+    authorization?: {
+        hook: string;
+        method: string;
+    };
+    settingsUi?: 'runtime';
+    settingsGroup?: string;
+    /** UA 主体之后追加的 token，{v} 占位会被替换为 appVersion */
     uaTokens: string[];
     /** 额外注入到 window 的变量（公共变量由 resolve 统一生成） */
     globals: Record<string, string>;

package/dist/appProfileDefinition.js

@@ -1,18 +1,3 @@
-const BRIDGE_STYLES = new Set([
-    'windvane',
-    'fliggy',
-    'alipay',
-    'callback',
-    'btrip',
-    'invoke',
-    'callHandler',
-    'amap',
-    'didi',
-    'easybikeNative',
-    'mega',
-    'wechat',
-    'wechatMiniProgram',
-]);
 export const APP_BRIDGE_BEHAVIORS = [
     'navigate',
     'closeAll',
@@ -133,12 +118,17 @@ export function validateAppProfileDefinition(value) {
         'schemes',
     ];
     const optional = [
+        'usage',
+        'actionIcon',
+        'labels',
         'pageRuntime',
         'uaFamily',
         'uaTemplate',
         'policies',
         'settings',
         'settingsGroup',
+        'settingsUi',
+        'authorization',
         'miniProgram',
         'imagePicker',
         'geolocation',
@@ -160,6 +150,37 @@ export function validateAppProfileDefinition(value) {
             invalid(key);
     if (!/^[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)?$/.test(value.name))
         invalid('name');
+    if (value.usage !== undefined) {
+        const usage = value.usage;
+        fields(usage, [], ['description', 'limitations', 'skills', 'documentation'], 'usage');
+        if (new TextEncoder().encode(JSON.stringify(usage)).byteLength > 4096)
+            invalid('usage exceeds 4 KiB');
+        if (usage.description !== undefined && (!text(usage.description) || usage.description.length > 512))
+            invalid('usage.description');
+        for (const key of ['limitations', 'skills']) {
+            const items = usage[key];
+            if (items !== undefined && (!Array.isArray(items) || items.length > 8 || items.some(item => !text(item) || !item || item.length > 256)))
+                invalid(`usage.${key}`);
+        }
+        if (usage.documentation !== undefined) {
+            if (!Array.isArray(usage.documentation) || usage.documentation.length > 8)
+                invalid('usage.documentation');
+            for (const link of usage.documentation) {
+                fields(link, ['title', 'url'], [], 'usage.documentation');
+                if (!text(link.title) || !link.title || link.title.length > 128 || !text(link.url) || link.url.length > 1024)
+                    invalid('usage.documentation');
+                let url;
+                try {
+                    url = new URL(link.url);
+                }
+                catch {
+                    invalid('usage.documentation.url');
+                }
+                if (url.protocol !== 'https:' || url.username || url.password)
+                    invalid('usage.documentation.url');
+            }
+        }
+    }
     if (value.pageRuntime !== undefined) {
         fields(value.pageRuntime, ['id', 'sha256'], [], 'pageRuntime');
         const runtime = value.pageRuntime;
@@ -191,17 +212,28 @@ export function validateAppProfileDefinition(value) {
                 .split('.')
                 .some(part => ['__proto__', 'prototype', 'constructor'].includes(part)) ||
             globals.has(bridge.global) ||
-            !BRIDGE_STYLES.has(bridge.style) ||
+            (typeof bridge.style !== 'string' || !/^[a-zA-Z][a-zA-Z0-9-]{0,63}$/.test(bridge.style)) ||
             (bridge.persistent !== undefined && typeof bridge.persistent !== 'boolean'))
             invalid('bridge');
         globals.add(bridge.global);
     }
     validateActions(value.actions);
+    if (value.labels !== undefined) {
+        fields(value.labels, ['en'], ['zh_CN'], 'labels');
+        if (!text(value.labels.en) || !value.labels.en || value.labels.en.length > 120 || value.labels.zh_CN !== undefined && (!text(value.labels.zh_CN) || value.labels.zh_CN.length > 120))
+            invalid('labels');
+    }
+    if (value.actionIcon !== undefined && (typeof value.actionIcon !== 'string' || value.actionIcon.length > 32768 || !/^data:image\/png;base64,iVBORw0KGgo[A-Za-z0-9+/]*={0,2}$/.test(value.actionIcon)))
+        invalid('actionIcon');
+    if (value.authorization !== undefined && (!record(value.authorization) || Object.keys(value.authorization).sort().join(',') !== 'hook,method' || typeof value.authorization.hook !== 'string' || !/^[a-z][a-zA-Z0-9_.-]{0,95}$/.test(value.authorization.hook) || typeof value.authorization.method !== 'string' || !value.authorization.method || value.authorization.method.length > 200))
+        invalid('authorization');
+    if (value.settingsUi !== undefined && value.settingsUi !== 'runtime')
+        throw new Error('Invalid App settings UI');
     if (value.settingsGroup !== undefined &&
-        !['fliggy', 'alipay'].includes(value.settingsGroup))
+        (typeof value.settingsGroup !== 'string' || value.settingsGroup.length > 64))
         invalid('settingsGroup');
     if (value.uaFamily !== undefined &&
-        !['aliapp', 'wechatMiniProgram'].includes(value.uaFamily))
+        (typeof value.uaFamily !== 'string' || value.uaFamily.length > 64))
         invalid('uaFamily');
     if (value.uaTemplate !== undefined) {
         fields(value.uaTemplate, ['ios', 'android'], [], 'uaTemplate');
@@ -212,9 +244,9 @@ export function validateAppProfileDefinition(value) {
         fields(value.policies, [], ['titleBar', 'navigatorLanguage', 'networkResult', 'languages', 'defaultLanguage'], 'policies');
         const p = value.policies;
         if (p.titleBar !== undefined &&
-            !['default', 'taobao', 'fliggy', 'alipay', 'wechat'].includes(p.titleBar))
+            (typeof p.titleBar !== 'string' || p.titleBar.length > 64))
             invalid('policies.titleBar');
-        if (p.networkResult !== undefined && !['default', 'alipay'].includes(p.networkResult))
+        if (p.networkResult !== undefined && (typeof p.networkResult !== 'string' || p.networkResult.length > 64))
             invalid('policies.networkResult');
         if (p.navigatorLanguage !== undefined && typeof p.navigatorLanguage !== 'boolean')
             invalid('policies.navigatorLanguage');

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;
@@ -486,8 +491,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 +509,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 {
@@ -765,7 +763,7 @@ export interface SetCookieResult {
 export interface RequestDomainPermissionParams {
     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 +773,10 @@ export interface RunActionsParams {
     tabId: number;
 }
 export interface BrowserActionMap {
+    get_capabilities: {
+        request: GetCapabilitiesParams;
+        response: BrowserCapabilityCatalog;
+    };
     tab_checkpoint: {
         request: CaptureCheckpointParams;
         response: CaptureCheckpointResult;
@@ -979,6 +981,7 @@ 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 browser_list: true;
@@ -1025,6 +1028,7 @@ 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 browser_list: true;
@@ -1070,6 +1074,7 @@ 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 browser_release: true;
@@ -1111,6 +1116,7 @@ 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 browser_release: true;

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,6 +120,7 @@ export const BROWSER_ACTIONS = {
     get_mocks: true,
     set_rule: true,
     get_rules: true,
+    get_capabilities: true,
     send_request: true,
     send_mtop_request: true,
     browser_list: true,
@@ -169,6 +167,7 @@ export const BROWSER_COMMAND_ACTIONS = {
     get_mocks: true,
     set_rule: true,
     get_rules: true,
+    get_capabilities: true,
     send_request: true,
     send_mtop_request: true,
     browser_list: true,
@@ -214,6 +213,7 @@ export const EXTENSION_BROWSER_ACTIONS = {
     get_mocks: true,
     set_rule: true,
     get_rules: true,
+    get_capabilities: true,
     send_request: true,
     send_mtop_request: true,
     browser_release: true,

package/dist/browserCapabilities.d.ts

@@ -0,0 +1,45 @@
+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;
+} | undefined, params?: GetCapabilitiesParams): BrowserCapabilityCatalog;

package/dist/browserCapabilities.js

@@ -0,0 +1,49 @@
+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');
+    if (params.app && catalog && !catalog.offline && !catalog.errors.length && !catalog.profiles.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 ? catalog?.profiles ?? [] : [];
+    return {
+        actions: [...new Set(actions)],
+        devicePresets: actions.includes('set_device_emulation') ? [...BROWSER_DEVICE_PRESET_NAMES] : [],
+        apps: {
+            status: !supportsApps || !catalog ? 'unsupported' : catalog.offline || catalog.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: catalog?.errors.map(issue => ({ ...issue })) ?? [],
+        },
+        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/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/domClicking.js

@@ -365,9 +365,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)) {
@@ -680,9 +693,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 +1027,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 +1334,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)) {

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

@@ -206,6 +206,7 @@ export interface HostToExtensionActionMap {
     __control_cleanup: {
         request: BrowserReleaseParams & {
             tabIds: number[];
+            returningToAgent?: boolean;
         };
         response: BrowserReleaseResult;
     };

package/dist/index.d.ts

@@ -37,6 +37,7 @@ export * from './pluginPages.js';
 export * from './pluginPageRuntime.js';
 export * from './pluginPageHost.js';
 export * from './browserActionProtocol.js';
+export * from './browserCapabilities.js';
 export * from './runActions.js';
 export * from './sendRequestFiles.js';
 export * from './sendRequestHeaders.js';
@@ -57,3 +58,4 @@ export * from './consumeSseResponse.js';
 export { parseQueryString } from './queryString.js';
 export * from './extensionVersion.js';
 export { MEARL_NATIVE_HOST_NAMES, type NativeHostIntegrationMode } from './nativeHostNames.js';
+export * from './dataStructure.js';

package/dist/index.js

@@ -36,6 +36,7 @@ export * from './pluginPages.js';
 export * from './pluginPageRuntime.js';
 export * from './pluginPageHost.js';
 export * from './browserActionProtocol.js';
+export * from './browserCapabilities.js';
 export * from './runActions.js';
 export * from './sendRequestFiles.js';
 export * from './sendRequestHeaders.js';
@@ -56,3 +57,4 @@ export * from './consumeSseResponse.js';
 export { parseQueryString } from './queryString.js';
 export * from './extensionVersion.js';
 export { MEARL_NATIVE_HOST_NAMES } from './nativeHostNames.js';
+export * from './dataStructure.js';

package/dist/proxyPermissions.js

@@ -85,6 +85,7 @@ export function isDomainAuthorized(domain, allowedOrigins) {
 export const ACTIONS_SKIP_DOMAIN_CHECK = new Set([
     'request_domain_permission',
     'get_browser_info',
+    'get_capabilities',
     '__export_cookies',
     'send_mtop_request',
     'run_actions',

package/dist/requestSerializer.js

@@ -1,6 +1,7 @@
 /**
  * Request serialization utilities — pure computation, no environment dependencies.
  */
+import { getStructure } from './dataStructure.js';
 // ─── Path utilities ───────────────────────────────────────────────────────────
 function parsePath(path) {
     if (path.length > 1000)
@@ -67,35 +68,6 @@ export function setValueByPath(obj, path, value) {
     current[keys[keys.length - 1]] = value;
 }
 // ─── Structure helpers ────────────────────────────────────────────────────────
-function getStructure(data, maxDepth = 5, currentDepth = 0) {
-    if (currentDepth >= maxDepth)
-        return '<max depth reached>';
-    if (data === null)
-        return 'null';
-    if (data === undefined)
-        return 'undefined';
-    const type = typeof data;
-    if (type === 'string' || type === 'number' || type === 'boolean')
-        return type;
-    if (Array.isArray(data)) {
-        if (data.length === 0)
-            return 'array[0]';
-        return {
-            _type: `array[${data.length}]`,
-            _sample: getStructure(data[0], maxDepth, currentDepth + 1),
-        };
-    }
-    if (type === 'object') {
-        const structure = {};
-        for (const key in data) {
-            if (Object.prototype.hasOwnProperty.call(data, key)) {
-                structure[key] = getStructure(data[key], maxDepth, currentDepth + 1);
-            }
-        }
-        return structure;
-    }
-    return type;
-}
 function truncateData(data, maxSize) {
     const str = JSON.stringify(data);
     if (str.length <= maxSize)

package/dist/runActions.js

@@ -22,7 +22,7 @@ export async function runActionBatch(data, execute, options = {}) {
             validationError = `unsupported action "${action}"`;
         else if (action === 'run_actions')
             validationError = `composite action "${action}" is not allowed in run_actions`;
-        else if (action === 'browser_release')
+        else if (action === 'browser_release' || action === 'get_capabilities')
             validationError = `browser-level action "${action}" is not allowed in run_actions`;
         if (validationError)
             return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/browser-core",
-  "version": "3.0.0-beta.4",
+  "version": "3.0.0-beta.5",
   "description": "Shared pure-logic utilities for Mearl — usable in both browser extension and Node.js environments",
   "type": "module",
   "main": "dist/index.js",