@mearl/client 2.16.4 → 2.17.1

package/README.md

@@ -47,8 +47,8 @@ mearl send_request --payload '{"url":"https://api.example.com","method":"GET"}'
 # 以 multipart/form-data 上传本地文件
 mearl send_request --payload '{"url":"https://api.example.com/upload","method":"POST","formData":{"folder":"assets"},"files":[{"fieldName":"file","filePath":"/absolute/path/image.png"}]}'
 
-# 截图并保存
-mearl page_screenshot --output ./screenshot.png
+# 截图并保存（tabId 来自 tab_open 或 tab_list）
+mearl page_screenshot --payload '{"tabId":12345}' --output ./screenshot.png
 
 # 从文件读取大体积参数（如 mock 数据）
 mearl set_mock --payload-file ./mock-data.json
@@ -90,7 +90,8 @@ mearl browser_launch --payload '{"provider":"brow","providerOptions":{}}'
 mearl browser_list
 
 # 后续操作使用 browser_list 返回的全局 Browser ID
-mearl page_snapshot --browser '<browserId>'
+mearl tab_list --browser '<browserId>'
+mearl page_snapshot --payload '{"tabId":12345}' --browser '<browserId>'
 
 npx @mearl/setup provider update brow
 npx @mearl/setup provider uninstall brow
@@ -200,18 +201,28 @@ MCP Server 通过固定工具 `mearl_plugin` 接受同样的 `plugin`、`command
 | API 调试      | `tab_checkpoint` `get_requests` `get_logs` `get_events`                                                                              |
 | Mock & 规则   | `set_mock` `get_mocks` `set_rule` `get_rules`                                                                                        |
 | 网络请求      | `send_request` `send_mtop_request` `request_domain_permission`                                                                       |
-| 标签页        | `tab_open` `tab_close` `tab_list`                                                                                                    |
-| 页面操作      | `page_click` `page_drag` `page_type` `page_hover` `page_scroll` `page_eval` `page_press` `page_wait` `page_navigate` `page_upload`    |
+| 标签页        | `tab_open` `tab_list` `tab_close`                                                                                                    |
+| 页面感知      | `page_snapshot` `page_inspect` `page_screenshot` `page_frames`                                                                       |
+| 页面操作      | `page_click` `page_drag` `page_type` `page_hover` `page_scroll` `page_press` `page_wait` `page_navigate` `page_upload` `page_eval`    |
 | 组合调用      | `run_actions`                                                                                                                        |
-| 页面感知      | `page_snapshot` `page_screenshot` `page_selected_element` `page_frames`                                                              |
 | 环境与 Cookie | `set_device_emulation` `set_app_profile` `set_timezone` `get_cookie` `set_cookie`                                                     |
-| 浏览器        | `browser_list` `browser_release` `browser_launch` `browser_close`                                                                    |
+| 浏览器        | `browser_list` `browser_launch` `browser_release` `browser_close`                                                                    |
 
-页面交互动作（`page_click` / `page_drag` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认等待异步稳定并返回 `{ action, observation }`。参数、ref 或目标解析在派发前失败时返回 `action.stage: "precondition"`，省略无意义的 `observation` / `diagnostics`，CLI 退出码为 1。传 `observe: false` 可执行裸动作；需要同一动作期间的新增 error logs 和业务 requests 时传 `diagnostics: true`，埋点通过 `diagnostics.events` 按需开启。`page_eval` 默认裸执行，可按需开启观察或诊断。
+页面交互动作（`page_click` / `page_drag` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认等待异步稳定并返回 `{ action, observation }`。参数、ref 或目标解析在派发前失败时返回 `action.stage: "precondition"`，省略无意义的 `observation` / `diagnostics`；浏览器可能已收到输入但确认超时时返回 `action.stage: "dispatch-uncertain"`，并保留 observation 供核验当前状态。能够在超时前确定的目标、命中、坐标、派发模式和输入序列状态保存在 `action.attempt`，它是诊断证据，不表示动作已经生效。失败时 CLI 退出码为 1。传 `observe: false` 可执行裸动作；需要同一动作期间的新增 error logs 和业务 requests 时传 `diagnostics: true`，埋点通过 `diagnostics.events` 按需开启。`page_eval` 默认裸执行，可按需开启观察或诊断。
 
-`page_snapshot` 默认返回完整 AX Tree；长列表可传 `mode: "viewport"`，只需要当前视口内的控件时传 `mode: "interactive"`，已知 CSS 区域时传 `rootSelector`，已有 ref 时传 `rootRef`（可用 `ancestorDepth` 向上补充上下文），只查找特定文案或角色时传 `query`。视口内缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
+`tab_open active:true` 会激活目标 Tab、恢复最小化窗口，并通过 `activation` 返回实际标签页、窗口和 `visibilityState`；依赖可信触摸时先确认页面为 `visible`。页面动作的稳定观察会在有限预算内等待有限时长 CSS 动画。selector/ref 点击遇到嵌套滚动裁剪时会先滚动目标，仍不可见时才以明确的裁剪错误停止。
 
-重复文本点击可用 `page_click.scope` 限定 CSS / ref 子树；浏览器扩展后端中，容器或 iframe 内的点坐标使用 `coordinateSpace: "active-frame"`，CSS/text 查询可用 `frameId` 显式指定 frame。点击结果通过 `requestedTarget`、`resolvedTarget`、`dispatchTarget`、`hitTarget` 和 `coordinates` 区分请求语义、DOM 解析、派发节点与可信输入实际命中；ref 指向滚动容器内的子节点时，可用 `page_scroll.containerPolicy: "nearest"` 自动解析最近可滚动祖先。
+`page_click` 默认 `auto` 在隐藏页使用 DOM fallback，selector、文本、ref 和坐标定位都保持可用，并通过 `dispatchMode: "dom"`、`fallbackReason: "page-hidden"` 明确说明实际路径。普通后台任务不需要为了点击主动激活页面；只有站点明确拒绝非可信事件时才切换到可见页并强制 `mouse` / `touch`。
+
+`observation.effects.interactives` 会把内容未变化但 DOM 节点被框架重建的控件标记为 `recreated`，保留 selector/ref 与语义信息供后续定位，同时省略未变化的 value 和状态字段；值或状态确实变化时仍返回完整差异。
+
+`page_press.pressMode` 支持 `auto` / `dom` / `keyboard`。默认 `auto` 在隐藏页使用 DOM 键盘事件，并通过返回的 `dispatchMode`、`fallbackReason` 和 `defaultAction` 说明实际派发及默认行为模拟结果；依赖浏览器原生编辑、选择或滚动行为时使用可见页面和 `keyboard`。
+
+`page_snapshot` 默认返回完整 AX Tree；长列表可传 `mode: "viewport"`，只需要当前视口内的控件时传 `mode: "interactive"`，AX 信息为空或过于稀疏时可显式传 `mode: "dom"`，返回实际渲染文本、原生控件、显式 role 和高置信 clickable 节点。DOM 模式同样返回可供后续动作使用的 `@ref`，但不会猜测任意容器的业务语义。已知 CSS 区域时传 `rootSelector`，已有 ref 时传 `rootRef`（可用 `ancestorDepth` 向上补充上下文），只查找特定文案或角色时传 `query`。`interactive` 在视口内缺少 AX 控件语义时仍只回退到 AX viewport，并返回 `fallbackMode: "viewport"`，不会自动切换数据来源。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
+
+`page_inspect` 用 CSS、snapshot `@ref` 或 DevTools 当前选中元素 `$0` 返回命中数、边框盒、指定计算样式、中心点遮挡、横纵溢出像素和最近滚动容器。省略 selector 并传 `filter: "horizontal-overflow"` / `"vertical-overflow"` / `"scrollable"` 可直接做全页布局诊断。按文本定位时先用 `page_snapshot.query` 取得 `matches` / `matchCount` 和 ref，再把 ref 交给 `page_inspect`，不需要手写 `page_eval`。
+
+重复文本点击可用 `page_click.scope` 限定 CSS / ref 子树；浏览器扩展后端中，容器或 iframe 内的点坐标使用 `coordinateSpace: "active-frame"`，CSS/text 查询可用 `frameId` 显式指定 frame。点击结果通过 `requestedTarget`、`resolvedTarget`、`dispatchTarget`、`hitTarget` 和 `coordinates` 区分请求语义、DOM 解析、派发节点与可信输入实际命中；selector/ref 目标被嵌套滚动容器裁剪时会自动滚动到可点击区域，只有仍被 overflow 裁剪时才要求显式处理。需要主动浏览列表时，`page_scroll.containerPolicy: "nearest"` 可自动解析最近可滚动祖先。未指定 selector 时，`page_scroll` 会优先选择代表性视口位置命中的最近内部滚动容器，再使用文档滚动区域或层级最高且可视面积最大的滚动容器。
 
 `browser_list` 统一列出普通浏览器、Provider 浏览器和托管浏览器。`type` 区分
 `regular` / `managed`，`status` 区分 `connected` / `pairing` / `running_disconnected` /

package/dist/cli.js

@@ -21,7 +21,11 @@ const CATEGORIES = [
         title: '网络请求',
         names: ['send_request', 'send_mtop_request', 'request_domain_permission'],
     },
-    { title: '标签页', names: ['tab_open', 'tab_close', 'tab_list'] },
+    { title: '标签页', names: ['tab_open', 'tab_list', 'tab_close'] },
+    {
+        title: '页面感知',
+        names: ['page_snapshot', 'page_inspect', 'page_screenshot', 'page_frames'],
+    },
     {
         title: '页面操作',
         names: [
@@ -30,25 +34,21 @@ const CATEGORIES = [
             'page_type',
             'page_hover',
             'page_scroll',
-            'page_eval',
             'page_press',
             'page_wait',
             'page_navigate',
             'page_upload',
+            'page_eval',
         ],
     },
     { title: '组合调用', names: ['run_actions'] },
-    {
-        title: '页面感知',
-        names: ['page_snapshot', 'page_screenshot', 'page_selected_element', 'page_frames'],
-    },
     {
         title: '环境与 Cookie',
         names: ['set_device_emulation', 'set_app_profile', 'set_timezone', 'get_cookie', 'set_cookie'],
     },
     {
         title: '浏览器',
-        names: ['browser_list', 'browser_release', 'browser_launch', 'browser_close'],
+        names: ['browser_list', 'browser_launch', 'browser_release', 'browser_close'],
     },
 ];
 const BUILTIN_COMMANDS = [
@@ -111,10 +111,6 @@ function printUsage(commandName, version) {
         `  ${commandName} <action> --help`,
         `  ${commandName} check [选项]`,
         '',
-        '统一目标发现：',
-        '  browser_list 默认聚合当前机器及已配置 cloud-server 下的浏览器。',
-        '  后续操作通过 --browser <browserId> 指定目标，客户端会自动选择本地或远端传输。',
-        '',
         '常用选项：',
         '  --payload <json>      直接传入 JSON 参数',
         '  --payload-file <path> 从文件读取整个 JSON 参数',
@@ -162,7 +158,6 @@ function printUsage(commandName, version) {
     if (providers.length) {
         lines.push('', '已注册 Provider：', ...providers.map(provider => `  ${provider.providerId.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}${provider.name} v${provider.version} (${provider.packageName})`));
     }
-    lines.push('', `运行 ${commandName} <action> --help 查看 action 参数。`);
     console.error(lines.join('\n'));
 }
 function providerSchemaLine(name, schema, required, indent = 2) {
@@ -554,9 +549,6 @@ function screenshotData(action, result) {
     }
     if (action === 'page_screenshot' && typeof result?.data === 'string')
         return result.data;
-    if (action === 'page_selected_element' && typeof result?.screenshot?.data === 'string') {
-        return result.screenshot.data;
-    }
     return null;
 }
 function writeOutput(action, result, outputPath) {
@@ -659,9 +651,6 @@ export async function runMearlCli(args, options = {}) {
         }
         return (await runUnifiedCheck(checkOptions)) ? 0 : 1;
     }
-    if (parsed.action === 'page_selected_element' && parsed.outputPath) {
-        parsed.payload = { ...parsed.payload, includeScreenshot: true };
-    }
     const client = new UnifiedClient({
         ...(parsed.serverUrl ? { serverUrl: parsed.serverUrl } : {}),
         requestTimeoutSec: parsed.timeoutSec,

package/dist/commands.d.ts

@@ -308,8 +308,8 @@ export declare const COMMANDS: readonly [{
         readonly description: "签名使用的 appKey，默认 12574478";
     }, {
         readonly name: "env";
-        readonly type: "\"online\" | \"pre\"";
-        readonly description: "请求环境，默认 online";
+        readonly type: "\"prod\" | \"pre\"";
+        readonly description: "请求环境，默认 prod";
     }, {
         readonly name: "timeout";
         readonly type: "number";
@@ -393,7 +393,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "active";
         readonly type: "boolean";
-        readonly description: "是否激活新 Tab，默认 false";
+        readonly description: "是否激活目标 Tab 并恢复最小化窗口，默认 false；响应返回 activation 验证结果";
     }, {
         readonly name: "openerTabId";
         readonly type: "number";
@@ -497,7 +497,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_click --payload '{\"text\":\"提交\"}'", "page_click --payload '{\"text\":\"退款明细\",\"role\":\"button\"}'", "page_click --payload '{\"text\":\"确定\",\"scope\":\"@e12\"}'", "page_click --payload '{\"selector\":\"@e3\"}'", "page_click --payload '{\"selector\":\".submit-btn\"}'", "page_click --payload '{\"selector\":\".gesture-btn\",\"clickMode\":\"touch\"}'", "page_click --payload '{\"point\":{\"x\":336,\"y\":117}}'", "page_click --payload '{\"point\":{\"x\":196,\"y\":240},\"coordinateSpace\":\"active-frame\"}'"];
+    readonly examples: ["page_click --payload '{\"tabId\":12345,\"text\":\"提交\"}'", "page_click --payload '{\"tabId\":12345,\"text\":\"退款明细\",\"role\":\"button\"}'", "page_click --payload '{\"tabId\":12345,\"text\":\"确定\",\"scope\":\"@e12\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\"@e3\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\".submit-btn\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\".gesture-btn\",\"clickMode\":\"touch\"}'", "page_click --payload '{\"tabId\":12345,\"point\":{\"x\":336,\"y\":117}}'", "page_click --payload '{\"tabId\":12345,\"point\":{\"x\":196,\"y\":240},\"coordinateSpace\":\"active-frame\"}'"];
 }, {
     readonly name: "page_drag";
     readonly description: "拖动页面元素或视口坐标，适用于轮播图、滑块和拖放";
@@ -525,7 +525,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_drag --payload '{\"from\":{\"x\":350,\"y\":80},\"to\":{\"x\":80,\"y\":80}}'", "page_drag --payload '{\"from\":\"@e3\",\"to\":\"#drop-zone\",\"dragMode\":\"mouse\"}'"];
+    readonly examples: ["page_drag --payload '{\"tabId\":12345,\"from\":{\"x\":350,\"y\":80},\"to\":{\"x\":80,\"y\":80}}'", "page_drag --payload '{\"tabId\":12345,\"from\":\"@e3\",\"to\":\"#drop-zone\",\"dragMode\":\"mouse\"}'"];
 }, {
     readonly name: "page_type";
     readonly description: "向输入框填写文本，兼容 React 受控组件";
@@ -549,7 +549,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_type --payload '{\"selector\":\"@e6\",\"text\":\"搜索关键词\"}'"];
+    readonly examples: ["page_type --payload '{\"tabId\":12345,\"selector\":\"@e6\",\"text\":\"搜索关键词\"}'"];
 }, {
     readonly name: "page_hover";
     readonly description: "将鼠标悬停在页面元素上";
@@ -564,10 +564,10 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_hover --payload '{\"selector\":\".nav-menu\"}'"];
+    readonly examples: ["page_hover --payload '{\"tabId\":12345,\"selector\":\".nav-menu\"}'"];
 }, {
     readonly name: "page_scroll";
-    readonly description: "滚动页面或指定容器";
+    readonly description: "滚动页面或指定容器；页面根不可滚动时自动发现活动滚动区";
     readonly params: [{
         readonly name: "direction";
         readonly type: "\"up\" | \"down\" | \"top\" | \"bottom\"";
@@ -591,7 +591,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_scroll --payload '{\"direction\":\"down\"}'", "page_scroll --payload '{\"direction\":\"bottom\"}'", "page_scroll --payload '{\"selector\":\".virtual-list\",\"direction\":\"down\",\"distance\":800}'", "page_scroll --payload '{\"selector\":\"@e8\",\"containerPolicy\":\"nearest\",\"direction\":\"bottom\"}'"];
+    readonly examples: ["page_scroll --payload '{\"tabId\":12345,\"direction\":\"down\"}'", "page_scroll --payload '{\"tabId\":12345,\"direction\":\"bottom\"}'", "page_scroll --payload '{\"tabId\":12345,\"selector\":\".virtual-list\",\"direction\":\"down\",\"distance\":800}'", "page_scroll --payload '{\"tabId\":12345,\"selector\":\"@e8\",\"containerPolicy\":\"nearest\",\"direction\":\"bottom\"}'"];
 }, {
     readonly name: "page_eval";
     readonly description: "在页面上下文中执行任意 JavaScript 表达式";
@@ -614,7 +614,37 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_eval --payload '{\"expression\":\"document.title\"}'"];
+    readonly examples: ["page_eval --payload '{\"tabId\":12345,\"expression\":\"document.title\"}'"];
+}, {
+    readonly name: "page_inspect";
+    readonly description: "查询 DOM 元素的数量、边框盒、计算样式、遮挡、溢出和最近滚动容器";
+    readonly params: [{
+        readonly name: "selector";
+        readonly type: "string";
+        readonly description: "原生 CSS、page_snapshot 返回的 @eN ref，或 DevTools Elements 当前选区 $0；做全页溢出诊断时可省略";
+    }, {
+        readonly name: "filter";
+        readonly type: "\"all\" | \"overflowing\" | \"horizontal-overflow\" | \"vertical-overflow\" | \"scrollable\"";
+        readonly description: "结果过滤；省略 selector 时必须指定非 all 的过滤条件";
+    }, {
+        readonly name: "styles";
+        readonly type: "string[]";
+        readonly description: "要返回的计算样式属性，默认 display/position/box-sizing/overflow-x/overflow-y";
+    }, {
+        readonly name: "maxResults";
+        readonly type: "number";
+        readonly description: "最多返回的明细数，默认 20，最大 100；未触发 scanTruncated 时 count 为完整命中数";
+    }, {
+        readonly name: "includeOuterHTML";
+        readonly type: "boolean";
+        readonly description: "是否返回 outerHTML（最多 3000 字符）；$0 默认 true，其他目标默认 false";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_inspect --payload '{\"tabId\":12345,\"selector\":\".form-field\",\"styles\":[\"display\",\"width\"]}'", "page_inspect --payload '{\"tabId\":12345,\"selector\":\"@e8\"}'", "page_inspect --payload '{\"tabId\":12345,\"selector\":\"$0\"}'", "page_inspect --payload '{\"tabId\":12345,\"filter\":\"horizontal-overflow\"}'", "page_inspect --payload '{\"tabId\":12345,\"filter\":\"scrollable\"}'"];
 }, {
     readonly name: "page_press";
     readonly description: "在页面中按下键盘按键或组合键";
@@ -627,24 +657,40 @@ export declare const COMMANDS: readonly [{
         readonly name: "modifiers";
         readonly type: "string[]";
         readonly description: "修饰键数组：ctrl/alt/shift/meta/cmd";
+    }, {
+        readonly name: "pressMode";
+        readonly type: "\"auto\" | \"dom\" | \"keyboard\"";
+        readonly description: "派发模式；auto 默认在隐藏页降级为 DOM 键盘事件";
     }, ParamDef, ParamDef, {
         readonly name: "tabId";
         readonly type: "number";
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_press --payload '{\"key\":\"Enter\"}'"];
+    readonly examples: ["page_press --payload '{\"tabId\":12345,\"key\":\"Enter\"}'"];
 }, {
     readonly name: "page_wait";
-    readonly description: "等待指定时间、元素出现或页面条件成立";
+    readonly description: "等待指定时间、元素状态、可见文本或页面条件成立";
     readonly params: [{
         readonly name: "time";
         readonly type: "number";
-        readonly description: "等待毫秒数（与 selector 二选一）";
+        readonly description: "等待毫秒数（与 selector/text/condition 四选一）";
     }, {
         readonly name: "selector";
         readonly type: "string";
-        readonly description: "等待元素出现的 CSS 选择器（与 time/condition 三选一）";
+        readonly description: "目标 CSS 选择器（与 time/text/condition 四选一）";
+    }, {
+        readonly name: "state";
+        readonly type: "\"attached\" | \"detached\" | \"visible\" | \"hidden\"";
+        readonly description: "selector 的目标状态，默认 attached";
+    }, {
+        readonly name: "text";
+        readonly type: "string";
+        readonly description: "等待页面出现的可见文本";
+    }, {
+        readonly name: "exact";
+        readonly type: "boolean";
+        readonly description: "text 是否精确匹配，默认 false";
     }, {
         readonly name: "condition";
         readonly type: "string";
@@ -663,7 +709,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_wait --payload '{\"time\":1000}'", "page_wait --payload '{\"selector\":\".loaded\"}'", "page_wait --payload '{\"condition\":\"window.appReady === true\",\"timeout\":30000}'"];
+    readonly examples: ["page_wait --payload '{\"tabId\":12345,\"time\":1000}'", "page_wait --payload '{\"tabId\":12345,\"selector\":\".dialog\",\"state\":\"visible\"}'", "page_wait --payload '{\"tabId\":12345,\"selector\":\".loading\",\"state\":\"hidden\"}'", "page_wait --payload '{\"tabId\":12345,\"text\":\"提交成功\"}'", "page_wait --payload '{\"tabId\":12345,\"condition\":\"window.appReady === true\",\"timeout\":30000}'"];
 }, {
     readonly name: "page_navigate";
     readonly description: "在当前标签页内导航到 URL、刷新页面，或沿浏览历史后退/前进";
@@ -705,26 +751,26 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_upload --payload '{\"selector\":\"#file-input\",\"filePaths\":[\"/Users/me/photo.jpg\"]}'"];
+    readonly examples: ["page_upload --payload '{\"tabId\":12345,\"selector\":\"#file-input\",\"filePaths\":[\"/Users/me/photo.jpg\"]}'"];
 }, {
     readonly name: "page_snapshot";
-    readonly description: "获取页面无障碍树快照，支持完整、交互元素或当前视口范围（含 @ref）";
+    readonly description: "获取带 @ref 的页面结构快照，默认使用无障碍树，也可显式读取渲染 DOM";
     readonly params: [{
         readonly name: "depth";
         readonly type: "number";
         readonly description: "树深度，默认 15，复杂页面可调大";
     }, {
         readonly name: "mode";
-        readonly type: "\"full\" | \"interactive\" | \"viewport\"";
-        readonly description: "输出范围，默认 full；interactive 只保留当前视口内的语义控件；长列表优先使用 viewport";
+        readonly type: "\"full\" | \"interactive\" | \"viewport\" | \"dom\"";
+        readonly description: "默认 full；interactive/viewport 裁剪 AX 树；AX 信息缺失时可显式使用 dom 读取渲染 DOM";
     }, {
         readonly name: "rootSelector";
         readonly type: "string";
-        readonly description: "只获取指定 CSS 元素的 AX 子树，可与 mode 组合；与 rootRef 互斥";
+        readonly description: "只获取指定 CSS 元素的局部子树，可与 mode 组合；与 rootRef 互斥";
     }, {
         readonly name: "rootRef";
         readonly type: "string";
-        readonly description: "以已有 @eN ref 为根获取局部 AX 子树；与 rootSelector 互斥";
+        readonly description: "以已有 @eN ref 为根获取局部子树；与 rootSelector 互斥";
     }, {
         readonly name: "ancestorDepth";
         readonly type: "number";
@@ -732,7 +778,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "query";
         readonly type: "{ text?: string; role?: string; exact?: boolean }";
-        readonly description: "服务端过滤 AX 树，只保留按 accessibility name / role 命中的节点及祖先路径";
+        readonly description: "服务端按 name / role 过滤当前模式的树，只保留命中节点及祖先路径";
     }, {
         readonly name: "maxNodes";
         readonly type: "number";
@@ -747,7 +793,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_snapshot", "page_snapshot --payload '{\"tabId\":1,\"mode\":\"viewport\"}'", "page_snapshot --payload '{\"tabId\":1,\"rootSelector\":\"[role=dialog]\"}'", "page_snapshot --payload '{\"tabId\":1,\"rootRef\":\"@e8\",\"ancestorDepth\":1}'", "page_snapshot --payload '{\"tabId\":1,\"query\":{\"text\":\"保存\",\"role\":\"button\"}}'"];
+    readonly examples: ["page_snapshot --payload '{\"tabId\":12345}'", "page_snapshot --payload '{\"tabId\":1,\"mode\":\"viewport\"}'", "page_snapshot --payload '{\"tabId\":1,\"mode\":\"dom\"}'", "page_snapshot --payload '{\"tabId\":1,\"rootSelector\":\"[role=dialog]\"}'", "page_snapshot --payload '{\"tabId\":1,\"rootRef\":\"@e8\",\"ancestorDepth\":1}'", "page_snapshot --payload '{\"tabId\":1,\"query\":{\"text\":\"保存\",\"role\":\"button\"}}'"];
 }, {
     readonly name: "page_screenshot";
     readonly description: "获取当前视口或指定元素截图";
@@ -770,26 +816,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["page_screenshot --output ./screenshot.png", "page_screenshot --payload '{\"selector\":\".product-card\"}' --output ./card.png"];
-}, {
-    readonly name: "page_selected_element";
-    readonly description: "获取 DevTools Elements 面板当前选中元素的详细信息";
-    readonly outputFlag: true;
-    readonly params: [{
-        readonly name: "includeOuterHTML";
-        readonly type: "boolean";
-        readonly description: "是否返回 outerHTML（最多 3000 字符），默认 true";
-    }, {
-        readonly name: "includeScreenshot";
-        readonly type: "boolean";
-        readonly description: "是否附带元素截图，默认 false；指定 --output 时自动开启";
-    }, {
-        readonly name: "tabId";
-        readonly type: "number";
-        readonly required: true;
-        readonly description: "目标标签页 ID";
-    }];
-    readonly examples: ["page_selected_element", "page_selected_element --output ./element.png"];
+    readonly examples: ["page_screenshot --payload '{\"tabId\":12345}' --output ./screenshot.png", "page_screenshot --payload '{\"tabId\":12345,\"selector\":\".product-card\"}' --output ./card.png"];
 }, {
     readonly name: "set_device_emulation";
     readonly description: "把目标 tab 切换为移动端模拟（视口/DPR/UA/触摸/视觉比例），等价 DevTools 设备工具栏，作用域 per-tab；需保持调试控制才持续生效";
@@ -853,10 +880,10 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["set_device_emulation --payload '{\"enabled\":true,\"preset\":\"iphone-17-pro\"}'", "set_device_emulation --payload '{\"enabled\":true,\"preset\":\"pixel-11\",\"orientation\":\"landscape\"}'", "set_device_emulation --payload '{\"enabled\":true,\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}'", "set_device_emulation --payload '{\"enabled\":false}'"];
+    readonly examples: ["set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"iphone-17-pro\"}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"pixel-11\",\"orientation\":\"landscape\"}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":false}'"];
 }, {
     readonly name: "set_app_profile";
-    readonly description: "设置 App 客户端环境与 JSBridge；传 emulation 时由同一个命令联动设备模拟，省略时不改变设备状态";
+    readonly description: "设置 App 客户端环境与 JSBridge；可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟";
     readonly summary: "设置或清除目标标签页的 App 容器模拟";
     readonly params: [{
         readonly name: "enabled";
@@ -883,6 +910,10 @@ export declare const COMMANDS: readonly [{
         readonly name: "bridgeConfig";
         readonly type: "object";
         readonly description: "声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本";
+    }, {
+        readonly name: "mtopEnv";
+        readonly type: "\"default\" | \"prod\" | \"pre\"";
+        readonly description: "可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab";
     }, {
         readonly name: "emulation";
         readonly type: "object";
@@ -897,7 +928,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\"}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\",\"emulation\":{}}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"alipay\",\"emulation\":{\"preset\":\"pixel-11\",\"deviceShell\":true}}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\",\"emulation\":{\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}}'", "set_app_profile --payload '{\"enabled\":false}'", "set_app_profile --payload '{\"enabled\":false,\"emulation\":{}}'"];
+    readonly examples: ["set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"fliggy\"}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"fliggy\",\"mtopEnv\":\"pre\"}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":false,\"mtopEnv\":\"prod\"}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"fliggy\",\"emulation\":{}}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"alipay\",\"emulation\":{\"preset\":\"pixel-11\",\"deviceShell\":true}}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"fliggy\",\"emulation\":{\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":false}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":false,\"emulation\":{}}'"];
 }, {
     readonly name: "set_timezone";
     readonly description: "覆盖目标 tab 的时区，传空字符串恢复浏览器默认时区";

package/dist/commands.js

@@ -214,7 +214,7 @@ export const COMMANDS = [
             { name: 'version', type: 'string', description: 'API 版本，默认 1.0' },
             { name: 'method', type: 'string', description: 'HTTP 方法，默认 GET' },
             { name: 'appKey', type: 'string', description: '签名使用的 appKey，默认 12574478' },
-            { name: 'env', type: '"online" | "pre"', description: '请求环境，默认 online' },
+            { name: 'env', type: '"prod" | "pre"', description: '请求环境，默认 prod' },
             { name: 'timeout', type: 'number', description: '超时毫秒数，默认 10000' },
         ],
         examples: [
@@ -310,7 +310,11 @@ export const COMMANDS = [
         aliases: ['tab_new', 'new_tab', 'tab_create', 'create_tab'],
         params: [
             { name: 'url', type: 'string', required: true, description: '要打开的 URL' },
-            { name: 'active', type: 'boolean', description: '是否激活新 Tab，默认 false' },
+            {
+                name: 'active',
+                type: 'boolean',
+                description: '是否激活目标 Tab 并恢复最小化窗口，默认 false；响应返回 activation 验证结果',
+            },
             {
                 name: 'openerTabId',
                 type: 'number',
@@ -440,14 +444,14 @@ export const COMMANDS = [
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [
-            `page_click --payload '{"text":"提交"}'`,
-            `page_click --payload '{"text":"退款明细","role":"button"}'`,
-            `page_click --payload '{"text":"确定","scope":"@e12"}'`,
-            `page_click --payload '{"selector":"@e3"}'`,
-            `page_click --payload '{"selector":".submit-btn"}'`,
-            `page_click --payload '{"selector":".gesture-btn","clickMode":"touch"}'`,
-            `page_click --payload '{"point":{"x":336,"y":117}}'`,
-            `page_click --payload '{"point":{"x":196,"y":240},"coordinateSpace":"active-frame"}'`,
+            `page_click --payload '{"tabId":12345,"text":"提交"}'`,
+            `page_click --payload '{"tabId":12345,"text":"退款明细","role":"button"}'`,
+            `page_click --payload '{"tabId":12345,"text":"确定","scope":"@e12"}'`,
+            `page_click --payload '{"tabId":12345,"selector":"@e3"}'`,
+            `page_click --payload '{"tabId":12345,"selector":".submit-btn"}'`,
+            `page_click --payload '{"tabId":12345,"selector":".gesture-btn","clickMode":"touch"}'`,
+            `page_click --payload '{"tabId":12345,"point":{"x":336,"y":117}}'`,
+            `page_click --payload '{"tabId":12345,"point":{"x":196,"y":240},"coordinateSpace":"active-frame"}'`,
         ],
     },
     {
@@ -481,8 +485,8 @@ export const COMMANDS = [
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [
-            `page_drag --payload '{"from":{"x":350,"y":80},"to":{"x":80,"y":80}}'`,
-            `page_drag --payload '{"from":"@e3","to":"#drop-zone","dragMode":"mouse"}'`,
+            `page_drag --payload '{"tabId":12345,"from":{"x":350,"y":80},"to":{"x":80,"y":80}}'`,
+            `page_drag --payload '{"tabId":12345,"from":"@e3","to":"#drop-zone","dragMode":"mouse"}'`,
         ],
     },
     {
@@ -501,7 +505,7 @@ export const COMMANDS = [
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
-        examples: [`page_type --payload '{"selector":"@e6","text":"搜索关键词"}'`],
+        examples: [`page_type --payload '{"tabId":12345,"selector":"@e6","text":"搜索关键词"}'`],
     },
     {
         name: 'page_hover',
@@ -517,11 +521,11 @@ export const COMMANDS = [
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
-        examples: [`page_hover --payload '{"selector":".nav-menu"}'`],
+        examples: [`page_hover --payload '{"tabId":12345,"selector":".nav-menu"}'`],
     },
     {
         name: 'page_scroll',
-        description: '滚动页面或指定容器',
+        description: '滚动页面或指定容器；页面根不可滚动时自动发现活动滚动区',
         params: [
             {
                 name: 'direction',
@@ -545,10 +549,10 @@ export const COMMANDS = [
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [
-            `page_scroll --payload '{"direction":"down"}'`,
-            `page_scroll --payload '{"direction":"bottom"}'`,
-            `page_scroll --payload '{"selector":".virtual-list","direction":"down","distance":800}'`,
-            `page_scroll --payload '{"selector":"@e8","containerPolicy":"nearest","direction":"bottom"}'`,
+            `page_scroll --payload '{"tabId":12345,"direction":"down"}'`,
+            `page_scroll --payload '{"tabId":12345,"direction":"bottom"}'`,
+            `page_scroll --payload '{"tabId":12345,"selector":".virtual-list","direction":"down","distance":800}'`,
+            `page_scroll --payload '{"tabId":12345,"selector":"@e8","containerPolicy":"nearest","direction":"bottom"}'`,
         ],
     },
     {
@@ -569,7 +573,46 @@ export const COMMANDS = [
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
-        examples: [`page_eval --payload '{"expression":"document.title"}'`],
+        examples: [`page_eval --payload '{"tabId":12345,"expression":"document.title"}'`],
+    },
+    {
+        name: 'page_inspect',
+        description: '查询 DOM 元素的数量、边框盒、计算样式、遮挡、溢出和最近滚动容器',
+        params: [
+            {
+                name: 'selector',
+                type: 'string',
+                description: '原生 CSS、page_snapshot 返回的 @eN ref，或 DevTools Elements 当前选区 $0；做全页溢出诊断时可省略',
+            },
+            {
+                name: 'filter',
+                type: '"all" | "overflowing" | "horizontal-overflow" | "vertical-overflow" | "scrollable"',
+                description: '结果过滤；省略 selector 时必须指定非 all 的过滤条件',
+            },
+            {
+                name: 'styles',
+                type: 'string[]',
+                description: '要返回的计算样式属性，默认 display/position/box-sizing/overflow-x/overflow-y',
+            },
+            {
+                name: 'maxResults',
+                type: 'number',
+                description: '最多返回的明细数，默认 20，最大 100；未触发 scanTruncated 时 count 为完整命中数',
+            },
+            {
+                name: 'includeOuterHTML',
+                type: 'boolean',
+                description: '是否返回 outerHTML（最多 3000 字符）；$0 默认 true，其他目标默认 false',
+            },
+            { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
+        ],
+        examples: [
+            `page_inspect --payload '{"tabId":12345,"selector":".form-field","styles":["display","width"]}'`,
+            `page_inspect --payload '{"tabId":12345,"selector":"@e8"}'`,
+            `page_inspect --payload '{"tabId":12345,"selector":"$0"}'`,
+            `page_inspect --payload '{"tabId":12345,"filter":"horizontal-overflow"}'`,
+            `page_inspect --payload '{"tabId":12345,"filter":"scrollable"}'`,
+        ],
     },
     {
         name: 'page_press',
@@ -582,22 +625,38 @@ export const COMMANDS = [
                 description: '按键名称：Enter/Tab/Escape/Backspace 等',
             },
             { name: 'modifiers', type: 'string[]', description: '修饰键数组：ctrl/alt/shift/meta/cmd' },
+            {
+                name: 'pressMode',
+                type: '"auto" | "dom" | "keyboard"',
+                description: '派发模式；auto 默认在隐藏页降级为 DOM 键盘事件',
+            },
             PAGE_OBSERVE_PARAM,
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
-        examples: [`page_press --payload '{"key":"Enter"}'`],
+        examples: [`page_press --payload '{"tabId":12345,"key":"Enter"}'`],
     },
     {
         name: 'page_wait',
-        description: '等待指定时间、元素出现或页面条件成立',
+        description: '等待指定时间、元素状态、可见文本或页面条件成立',
         params: [
-            { name: 'time', type: 'number', description: '等待毫秒数（与 selector 二选一）' },
+            {
+                name: 'time',
+                type: 'number',
+                description: '等待毫秒数（与 selector/text/condition 四选一）',
+            },
             {
                 name: 'selector',
                 type: 'string',
-                description: '等待元素出现的 CSS 选择器（与 time/condition 三选一）',
+                description: '目标 CSS 选择器（与 time/text/condition 四选一）',
             },
+            {
+                name: 'state',
+                type: '"attached" | "detached" | "visible" | "hidden"',
+                description: 'selector 的目标状态，默认 attached',
+            },
+            { name: 'text', type: 'string', description: '等待页面出现的可见文本' },
+            { name: 'exact', type: 'boolean', description: 'text 是否精确匹配，默认 false' },
             {
                 name: 'condition',
                 type: 'string',
@@ -608,9 +667,11 @@ export const COMMANDS = [
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [
-            `page_wait --payload '{"time":1000}'`,
-            `page_wait --payload '{"selector":".loaded"}'`,
-            `page_wait --payload '{"condition":"window.appReady === true","timeout":30000}'`,
+            `page_wait --payload '{"tabId":12345,"time":1000}'`,
+            `page_wait --payload '{"tabId":12345,"selector":".dialog","state":"visible"}'`,
+            `page_wait --payload '{"tabId":12345,"selector":".loading","state":"hidden"}'`,
+            `page_wait --payload '{"tabId":12345,"text":"提交成功"}'`,
+            `page_wait --payload '{"tabId":12345,"condition":"window.appReady === true","timeout":30000}'`,
         ],
     },
     {
@@ -656,29 +717,29 @@ export const COMMANDS = [
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [
-            `page_upload --payload '{"selector":"#file-input","filePaths":["/Users/me/photo.jpg"]}'`,
+            `page_upload --payload '{"tabId":12345,"selector":"#file-input","filePaths":["/Users/me/photo.jpg"]}'`,
         ],
     },
     // ── 页面感知 ──────────────────────────────────────────────────────────────
     {
         name: 'page_snapshot',
-        description: '获取页面无障碍树快照，支持完整、交互元素或当前视口范围（含 @ref）',
+        description: '获取带 @ref 的页面结构快照，默认使用无障碍树，也可显式读取渲染 DOM',
         params: [
             { name: 'depth', type: 'number', description: '树深度，默认 15，复杂页面可调大' },
             {
                 name: 'mode',
-                type: '"full" | "interactive" | "viewport"',
-                description: '输出范围，默认 full；interactive 只保留当前视口内的语义控件；长列表优先使用 viewport',
+                type: '"full" | "interactive" | "viewport" | "dom"',
+                description: '默认 full；interactive/viewport 裁剪 AX 树；AX 信息缺失时可显式使用 dom 读取渲染 DOM',
             },
             {
                 name: 'rootSelector',
                 type: 'string',
-                description: '只获取指定 CSS 元素的 AX 子树，可与 mode 组合；与 rootRef 互斥',
+                description: '只获取指定 CSS 元素的局部子树，可与 mode 组合；与 rootRef 互斥',
             },
             {
                 name: 'rootRef',
                 type: 'string',
-                description: '以已有 @eN ref 为根获取局部 AX 子树；与 rootSelector 互斥',
+                description: '以已有 @eN ref 为根获取局部子树；与 rootSelector 互斥',
             },
             {
                 name: 'ancestorDepth',
@@ -688,7 +749,7 @@ export const COMMANDS = [
             {
                 name: 'query',
                 type: '{ text?: string; role?: string; exact?: boolean }',
-                description: '服务端过滤 AX 树，只保留按 accessibility name / role 命中的节点及祖先路径',
+                description: '服务端按 name / role 过滤当前模式的树，只保留命中节点及祖先路径',
             },
             { name: 'maxNodes', type: 'number', description: '最多输出节点数，0 表示不限制' },
             {
@@ -699,8 +760,9 @@ export const COMMANDS = [
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [
-            'page_snapshot',
+            `page_snapshot --payload '{"tabId":12345}'`,
             `page_snapshot --payload '{"tabId":1,"mode":"viewport"}'`,
+            `page_snapshot --payload '{"tabId":1,"mode":"dom"}'`,
             `page_snapshot --payload '{"tabId":1,"rootSelector":"[role=dialog]"}'`,
             `page_snapshot --payload '{"tabId":1,"rootRef":"@e8","ancestorDepth":1}'`,
             `page_snapshot --payload '{"tabId":1,"query":{"text":"保存","role":"button"}}'`,
@@ -717,29 +779,10 @@ export const COMMANDS = [
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [
-            'page_screenshot --output ./screenshot.png',
-            `page_screenshot --payload '{"selector":".product-card"}' --output ./card.png`,
+            `page_screenshot --payload '{"tabId":12345}' --output ./screenshot.png`,
+            `page_screenshot --payload '{"tabId":12345,"selector":".product-card"}' --output ./card.png`,
         ],
     },
-    {
-        name: 'page_selected_element',
-        description: '获取 DevTools Elements 面板当前选中元素的详细信息',
-        outputFlag: true,
-        params: [
-            {
-                name: 'includeOuterHTML',
-                type: 'boolean',
-                description: '是否返回 outerHTML（最多 3000 字符），默认 true',
-            },
-            {
-                name: 'includeScreenshot',
-                type: 'boolean',
-                description: '是否附带元素截图，默认 false；指定 --output 时自动开启',
-            },
-            { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
-        ],
-        examples: ['page_selected_element', 'page_selected_element --output ./element.png'],
-    },
     // ── 移动端模拟 ────────────────────────────────────────────────────────────
     {
         name: 'set_device_emulation',
@@ -786,15 +829,15 @@ export const COMMANDS = [
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [
-            `set_device_emulation --payload '{"enabled":true,"preset":"iphone-17-pro"}'`,
-            `set_device_emulation --payload '{"enabled":true,"preset":"pixel-11","orientation":"landscape"}'`,
-            `set_device_emulation --payload '{"enabled":true,"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}'`,
-            `set_device_emulation --payload '{"enabled":false}'`,
+            `set_device_emulation --payload '{"tabId":12345,"enabled":true,"preset":"iphone-17-pro"}'`,
+            `set_device_emulation --payload '{"tabId":12345,"enabled":true,"preset":"pixel-11","orientation":"landscape"}'`,
+            `set_device_emulation --payload '{"tabId":12345,"enabled":true,"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}'`,
+            `set_device_emulation --payload '{"tabId":12345,"enabled":false}'`,
         ],
     },
     {
         name: 'set_app_profile',
-        description: '设置 App 客户端环境与 JSBridge；传 emulation 时由同一个命令联动设备模拟，省略时不改变设备状态',
+        description: '设置 App 客户端环境与 JSBridge；可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟',
         summary: '设置或清除目标标签页的 App 容器模拟',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
@@ -815,6 +858,11 @@ export const COMMANDS = [
                 type: 'object',
                 description: '声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本',
             },
+            {
+                name: 'mtopEnv',
+                type: '"default" | "prod" | "pre"',
+                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab',
+            },
             {
                 name: 'emulation',
                 type: 'object',
@@ -824,12 +872,14 @@ export const COMMANDS = [
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         examples: [
-            `set_app_profile --payload '{"enabled":true,"profile":"fliggy"}'`,
-            `set_app_profile --payload '{"enabled":true,"profile":"fliggy","emulation":{}}'`,
-            `set_app_profile --payload '{"enabled":true,"profile":"alipay","emulation":{"preset":"pixel-11","deviceShell":true}}'`,
-            `set_app_profile --payload '{"enabled":true,"profile":"fliggy","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
-            `set_app_profile --payload '{"enabled":false}'`,
-            `set_app_profile --payload '{"enabled":false,"emulation":{}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy"}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy","mtopEnv":"pre"}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":false,"mtopEnv":"prod"}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy","emulation":{}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"alipay","emulation":{"preset":"pixel-11","deviceShell":true}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":false}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":false,"emulation":{}}'`,
         ],
     },
     {

package/dist/generated-browser-action-protocol.d.ts

@@ -95,13 +95,15 @@ export interface SendRequestParams {
     responseType?: 'json' | 'text' | 'auto';
     timeout?: number;
 }
+export type MtopEnvironmentTarget = 'prod' | 'pre';
+export type MtopEnvironment = 'default' | MtopEnvironmentTarget;
 export interface SendMtopRequestParams {
     api: string;
     data?: unknown;
     version?: string;
     method?: string;
     appKey?: string;
-    env?: string;
+    env?: MtopEnvironmentTarget;
     timeout?: number;
     headers?: Record<string, string>;
     ttid?: string;
@@ -341,16 +343,11 @@ export interface RulesResult {
     rules: Array<Record<string, unknown>>;
 }
 export interface PageScreenshotParams {
-    tabId?: number;
+    tabId: number;
     selector?: string;
     format?: 'png' | 'jpeg';
     quality?: number;
 }
-export interface PageSelectedElementParams {
-    tabId?: number;
-    includeOuterHTML?: boolean;
-    includeScreenshot?: boolean;
-}
 export declare const BROWSER_DEVICE_PRESET_NAMES: readonly ["iphone-17-pro", "iphone-17e", "pixel-11", "ipad-mini-a17-pro", "galaxy-s26", "pura-x-max", "iphone-15-pro", "iphone-se", "pixel-8", "ipad-mini", "galaxy-s23"];
 export type BrowserDevicePresetName = (typeof BROWSER_DEVICE_PRESET_NAMES)[number];
 export interface BrowserEmulationOptions {
@@ -417,7 +414,7 @@ export interface TabOpenParams {
 export declare const APP_PROFILE_NAMES: readonly ["fliggy", "taobao", "wechat", "tmall", "alipay", "koubei", "taobao-tj", "taobao-live", "xianyu", "etao", "eleme", "damai", "btrip", "amap", "qianwen", "lingyou", "didi", "easybike"];
 export type AppProfileName = (typeof APP_PROFILE_NAMES)[number];
 export interface SetAppProfileParams {
-    tabId?: number;
+    tabId: number;
     /** false 时清除该 tab 的容器模拟并刷新 */
     enabled: boolean;
     /** 容器档案名（enabled=true 时必填） */
@@ -427,6 +424,11 @@ export interface SetAppProfileParams {
     deviceModel?: string;
     /** 按方法覆盖档案内置桥配置，仅支持受控行为、固定 JSON 回包和成功空实现 */
     bridgeConfig?: AppBridgeConfig;
+    /**
+     * 可选 MTop 接口环境。default 关闭环境改写；省略时保持当前设置。
+     * 扩展模式与插件设置页共享并全局生效；CDP 模式仅作用于目标 tab。
+     */
+    mtopEnv?: MtopEnvironment;
     /**
      * 可选设备联动参数。传入时显式字段覆盖档案推荐设备，空对象使用推荐设备且默认开启
      * deviceShell；省略时不设置或清除该 tab 的设备状态。
@@ -454,7 +456,7 @@ export interface PageDiagnosticsOptions {
 }
 export type PageDiagnosticsSetting = PageDiagnosticsOptions | boolean;
 export interface PageClickParams {
-    tabId?: number;
+    tabId: number;
     selector?: string;
     text?: string;
     point?: {
@@ -478,7 +480,7 @@ export interface PageDragPoint {
 }
 export type PageDragEndpoint = string | PageDragPoint;
 export interface PageDragParams {
-    tabId?: number;
+    tabId: number;
     from: PageDragEndpoint;
     to: PageDragEndpoint;
     dragMode?: 'auto' | 'dom' | 'mouse' | 'touch';
@@ -487,7 +489,7 @@ export interface PageDragParams {
     diagnostics?: PageDiagnosticsSetting;
 }
 export interface PageTypeParams {
-    tabId?: number;
+    tabId: number;
     selector: string;
     text: string;
     clearFirst?: boolean;
@@ -495,7 +497,7 @@ export interface PageTypeParams {
     diagnostics?: PageDiagnosticsSetting;
 }
 export interface PageScrollParams {
-    tabId?: number;
+    tabId: number;
     direction: 'up' | 'down' | 'top' | 'bottom';
     distance?: number;
     selector?: string;
@@ -504,13 +506,13 @@ export interface PageScrollParams {
     diagnostics?: PageDiagnosticsSetting;
 }
 export interface PageHoverParams {
-    tabId?: number;
+    tabId: number;
     selector: string;
     observe?: PageObservationWaitOptions | false;
     diagnostics?: PageDiagnosticsSetting;
 }
 export interface PageEvalParams {
-    tabId?: number;
+    tabId: number;
     expression: string;
     frameId?: string;
     awaitPromise?: boolean;
@@ -523,7 +525,7 @@ export interface PageSnapshotQuery {
     exact?: boolean;
 }
 export interface PageSnapshotParams {
-    tabId?: number;
+    tabId: number;
     depth?: number;
     maxChars?: number;
     maxNodes?: number;
@@ -531,46 +533,65 @@ export interface PageSnapshotParams {
     rootRef?: string;
     ancestorDepth?: number;
     query?: PageSnapshotQuery;
-    mode?: 'full' | 'interactive' | 'viewport';
+    mode?: 'full' | 'interactive' | 'viewport' | 'dom';
+}
+export type PageInspectFilter = 'all' | 'overflowing' | 'horizontal-overflow' | 'vertical-overflow' | 'scrollable';
+export interface PageInspectParams {
+    tabId: number;
+    /** Native CSS selector, a page_snapshot @ref, or DevTools' current selection ($0). */
+    selector?: string;
+    /** Limit results after filtering. Defaults to 20, maximum 100. */
+    maxResults?: number;
+    /** Computed-style properties to return. Defaults to common layout properties. */
+    styles?: string[];
+    /** Page-wide or selector-scoped layout filter. Defaults to all. */
+    filter?: PageInspectFilter;
+    /** Include a trimmed outerHTML string for returned matches. Defaults to true for $0. */
+    includeOuterHTML?: boolean;
 }
 export interface PagePressParams {
-    tabId?: number;
+    tabId: number;
     key: string;
     modifiers?: string[];
+    /** Dispatch strategy. Auto uses DOM events when the page is hidden. */
+    pressMode?: 'auto' | 'dom' | 'keyboard';
     observe?: PageObservationWaitOptions | false;
     diagnostics?: PageDiagnosticsSetting;
 }
 export interface PageWaitParams {
-    tabId?: number;
+    tabId: number;
     time?: number;
     selector?: string;
+    state?: 'attached' | 'detached' | 'visible' | 'hidden';
+    text?: string;
+    exact?: boolean;
     condition?: string;
     timeout?: number;
     interval?: number;
 }
 export interface PageNavigateParams {
-    tabId?: number;
+    tabId: number;
     url?: string;
     refresh?: boolean;
     history?: 'back' | 'forward';
 }
 export interface PageUploadParams {
-    tabId?: number;
+    tabId: number;
     selector: string;
     filePaths: string[];
     observe?: PageObservationWaitOptions | false;
     diagnostics?: PageDiagnosticsSetting;
 }
 export interface PageFramesParams {
-    tabId?: number;
+    tabId: number;
 }
 export interface SetDeviceEmulationParams extends BrowserEmulationOptions {
-    tabId?: number;
+    tabId: number;
     enabled: boolean;
     reload?: boolean;
 }
 export interface SetTimezoneParams {
-    tabId?: number;
+    tabId: number;
     timezone: string;
 }
 export interface SetTimezoneResult {
@@ -578,7 +599,7 @@ export interface SetTimezoneResult {
     timezone: string | null;
 }
 export interface GetCookieParams {
-    tabId?: number;
+    tabId: number;
     name: string;
     /** Cookie lookup URL; defaults to the current tab URL. */
     url?: string;
@@ -595,7 +616,7 @@ export interface GetCookieResult {
     path?: string;
 }
 export interface SetCookieParams {
-    tabId?: number;
+    tabId: number;
     name: string;
     value: string;
     domain?: string;
@@ -692,10 +713,6 @@ export interface BrowserActionMap {
         request: PageScreenshotParams;
         response: unknown;
     };
-    page_selected_element: {
-        request: PageSelectedElementParams;
-        response: unknown;
-    };
     tab_open: {
         request: TabOpenParams;
         response: unknown;
@@ -732,6 +749,10 @@ export interface BrowserActionMap {
         request: PageEvalParams;
         response: unknown;
     };
+    page_inspect: {
+        request: PageInspectParams;
+        response: unknown;
+    };
     page_snapshot: {
         request: PageSnapshotParams;
         response: unknown;
@@ -790,6 +811,10 @@ export type BrowserActionRequest<A extends BrowserAction> = BrowserActionMap[A][
 export type BrowserActionResponse<A extends BrowserAction> = BrowserActionMap[A]['response'];
 export type BrowserCommandAction = Exclude<BrowserAction, 'browser_select_browser'>;
 export type ExtensionBrowserAction = Exclude<BrowserCommandAction, 'browser_list' | 'browser_launch' | 'browser_close'>;
+export declare const TAB_ID_REQUIRED_ACTIONS: readonly ["page_screenshot", "tab_close", "page_click", "page_drag", "page_type", "page_scroll", "page_hover", "page_eval", "page_inspect", "page_snapshot", "page_press", "page_wait", "page_navigate", "page_upload", "page_frames", "set_device_emulation", "set_app_profile", "set_timezone", "get_cookie", "set_cookie", "run_actions"];
+export type TabIdRequiredAction = (typeof TAB_ID_REQUIRED_ACTIONS)[number];
+export declare function actionRequiresTabId(action: unknown): action is TabIdRequiredAction;
+export declare function validateRequiredActionTabId(action: string, data: unknown): void;
 export declare const PAGE_ACT_ACTIONS: readonly ["page_click", "page_drag", "page_type", "page_hover", "page_scroll", "page_press", "page_upload", "page_eval"];
 export type PageActAction = (typeof PAGE_ACT_ACTIONS)[number];
 export declare const BROWSER_ACTIONS: {
@@ -810,7 +835,6 @@ export declare const BROWSER_ACTIONS: {
     readonly browser_launch: true;
     readonly browser_close: true;
     readonly page_screenshot: true;
-    readonly page_selected_element: true;
     readonly tab_open: true;
     readonly tab_close: true;
     readonly tab_list: true;
@@ -820,6 +844,7 @@ export declare const BROWSER_ACTIONS: {
     readonly page_scroll: true;
     readonly page_hover: true;
     readonly page_eval: true;
+    readonly page_inspect: true;
     readonly page_snapshot: true;
     readonly page_press: true;
     readonly page_wait: true;
@@ -851,7 +876,6 @@ export declare const BROWSER_COMMAND_ACTIONS: {
     readonly browser_launch: true;
     readonly browser_close: true;
     readonly page_screenshot: true;
-    readonly page_selected_element: true;
     readonly tab_open: true;
     readonly tab_close: true;
     readonly tab_list: true;
@@ -861,6 +885,7 @@ export declare const BROWSER_COMMAND_ACTIONS: {
     readonly page_scroll: true;
     readonly page_hover: true;
     readonly page_eval: true;
+    readonly page_inspect: true;
     readonly page_snapshot: true;
     readonly page_press: true;
     readonly page_wait: true;
@@ -889,7 +914,6 @@ export declare const EXTENSION_BROWSER_ACTIONS: {
     readonly send_mtop_request: true;
     readonly browser_release: true;
     readonly page_screenshot: true;
-    readonly page_selected_element: true;
     readonly tab_open: true;
     readonly tab_close: true;
     readonly tab_list: true;
@@ -899,6 +923,7 @@ export declare const EXTENSION_BROWSER_ACTIONS: {
     readonly page_scroll: true;
     readonly page_hover: true;
     readonly page_eval: true;
+    readonly page_inspect: true;
     readonly page_snapshot: true;
     readonly page_press: true;
     readonly page_wait: true;

package/dist/generated-browser-action-protocol.js

@@ -48,6 +48,43 @@ export const APP_PROFILE_NAMES = [
     'didi',
     'easybike',
 ];
+export const TAB_ID_REQUIRED_ACTIONS = [
+    'page_screenshot',
+    'tab_close',
+    'page_click',
+    'page_drag',
+    'page_type',
+    'page_scroll',
+    'page_hover',
+    'page_eval',
+    'page_inspect',
+    'page_snapshot',
+    'page_press',
+    'page_wait',
+    'page_navigate',
+    'page_upload',
+    'page_frames',
+    'set_device_emulation',
+    'set_app_profile',
+    'set_timezone',
+    'get_cookie',
+    'set_cookie',
+    'run_actions',
+];
+const TAB_ID_REQUIRED_ACTION_SET = new Set(TAB_ID_REQUIRED_ACTIONS);
+export function actionRequiresTabId(action) {
+    return typeof action === 'string' && TAB_ID_REQUIRED_ACTION_SET.has(action);
+}
+export function validateRequiredActionTabId(action, data) {
+    if (!actionRequiresTabId(action))
+        return;
+    const tabId = data && typeof data === 'object' && !Array.isArray(data)
+        ? data.tabId
+        : undefined;
+    if (typeof tabId !== 'number' || !Number.isSafeInteger(tabId) || tabId < 0) {
+        throw new Error(`${action} requires a numeric tabId. Call tab_open or tab_list to obtain a tabId.`);
+    }
+}
 export const PAGE_ACT_ACTIONS = [
     'page_click',
     'page_drag',
@@ -76,7 +113,6 @@ export const BROWSER_ACTIONS = {
     browser_launch: true,
     browser_close: true,
     page_screenshot: true,
-    page_selected_element: true,
     tab_open: true,
     tab_close: true,
     tab_list: true,
@@ -86,6 +122,7 @@ export const BROWSER_ACTIONS = {
     page_scroll: true,
     page_hover: true,
     page_eval: true,
+    page_inspect: true,
     page_snapshot: true,
     page_press: true,
     page_wait: true,
@@ -117,7 +154,6 @@ export const BROWSER_COMMAND_ACTIONS = {
     browser_launch: true,
     browser_close: true,
     page_screenshot: true,
-    page_selected_element: true,
     tab_open: true,
     tab_close: true,
     tab_list: true,
@@ -127,6 +163,7 @@ export const BROWSER_COMMAND_ACTIONS = {
     page_scroll: true,
     page_hover: true,
     page_eval: true,
+    page_inspect: true,
     page_snapshot: true,
     page_press: true,
     page_wait: true,
@@ -155,7 +192,6 @@ export const EXTENSION_BROWSER_ACTIONS = {
     send_mtop_request: true,
     browser_release: true,
     page_screenshot: true,
-    page_selected_element: true,
     tab_open: true,
     tab_close: true,
     tab_list: true,
@@ -165,6 +201,7 @@ export const EXTENSION_BROWSER_ACTIONS = {
     page_scroll: true,
     page_hover: true,
     page_eval: true,
+    page_inspect: true,
     page_snapshot: true,
     page_press: true,
     page_wait: true,

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invok
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
 export type { PluginInvocation, PluginInvokeOptions } from './plugin.js';
 export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
-export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from './generated-browser-action-protocol.js';
+export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageInspectFilter, PageInspectParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from './generated-browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from './generated-browser-action-protocol.js';
 export declare function tabCheckpoint(params?: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
@@ -29,7 +29,6 @@ export declare function browserClose(params: Protocol.BrowserCloseParams, option
 export declare function setRule(params: Protocol.SetRuleParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_rule'>>;
 export declare function getRules(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_rules'>>;
 export declare function pageScreenshot(params: Protocol.PageScreenshotParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_screenshot'>>;
-export declare function pageSelectedElement(params: Protocol.PageSelectedElementParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_selected_element'>>;
 export declare function tabOpen(params: Protocol.TabOpenParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_open'>>;
 export declare function tabClose(params: Protocol.TabCloseParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_close'>>;
 export declare function tabList(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_list'>>;
@@ -39,6 +38,7 @@ export declare function pageType(params: Protocol.PageTypeParams, options?: Unif
 export declare function pageScroll(params: Protocol.PageScrollParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_scroll'>>;
 export declare function pageHover(params: Protocol.PageHoverParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_hover'>>;
 export declare function pageEval(params: Protocol.PageEvalParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_eval'>>;
+export declare function pageInspect(params: Protocol.PageInspectParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_inspect'>>;
 export declare function pageSnapshot(params: Protocol.PageSnapshotParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_snapshot'>>;
 export declare function pagePress(params: Protocol.PagePressParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_press'>>;
 export declare function pageWait(params: Protocol.PageWaitParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_wait'>>;

package/dist/index.js

@@ -59,9 +59,6 @@ export function getRules(options) {
 export function pageScreenshot(params, options) {
     return invoke('page_screenshot', params, options);
 }
-export function pageSelectedElement(params, options) {
-    return invoke('page_selected_element', params, options);
-}
 export function tabOpen(params, options) {
     return invoke('tab_open', params, options);
 }
@@ -89,6 +86,9 @@ export function pageHover(params, options) {
 export function pageEval(params, options) {
     return invoke('page_eval', params, options);
 }
+export function pageInspect(params, options) {
+    return invoke('page_inspect', params, options);
+}
 export function pageSnapshot(params, options) {
     return invoke('page_snapshot', params, options);
 }

package/dist/socket.js

@@ -117,6 +117,9 @@ function supportsAction(browser, action, data) {
         const required = data.deleteProfile === true ? 'deleteData' : 'close';
         return browser.operations?.includes(required) === true;
     }
+    if (action === 'browser_release') {
+        return browser.transport !== 'provider' || browser.operations?.includes('detach') === true;
+    }
     if (!isConnectedBrowser(browser))
         return false;
     return (browser.transport !== 'provider' ||
@@ -282,7 +285,10 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
         if (transport === 'cdp' && match.transport === 'provider') {
             throw new Error(`Browser ${describeBrowser(match)} does not support the CDP transport`);
         }
-        if (match.status === 'pairing' && action !== 'get_versions' && action !== 'browser_close') {
+        if (match.status === 'pairing' &&
+            action !== 'get_versions' &&
+            action !== 'browser_close' &&
+            action !== 'browser_release') {
             throw new Error(`Browser ${describeBrowser(match)} is waiting for device pairing`);
         }
         if (!supportsAction(match, action, data)) {

package/dist/unified.js

@@ -1,6 +1,7 @@
 import WebSocket from 'ws';
 import { DEFAULT_CONNECT_TIMEOUT, DEFAULT_HEARTBEAT_INTERVAL, DEFAULT_REQUEST_TIMEOUT, MAX_BUFFER_SIZE, isHeartbeatMessage, resolveCloudConnectorSelector, } from '@mearl/cloud-types';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
+import { validateRequiredActionTabId, } from './generated-browser-action-protocol.js';
 import { invoke as invokeLocalBrowser } from './socket.js';
 import { loadCloudServerConfig, loadLocalConnectorId } from './unifiedConfig.js';
 const RESPONSE_GRACE_MS = 1_000;
@@ -126,6 +127,7 @@ export class UnifiedClient {
         }, options);
     }
     async invoke(action, data = {}, options = {}) {
+        validateRequiredActionTabId(action, data);
         const timeoutSec = options.timeoutSec ?? resolveActionTimeoutSec(action, data, this.options.requestTimeoutSec);
         if (action === 'connector_list')
             return this.listConnectors(timeoutSec);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.16.4",
+  "version": "2.17.1",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -59,8 +59,8 @@
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.16.4",
-    "@mearl/provider": "2.16.4"
+    "@mearl/cloud-types": "2.17.1",
+    "@mearl/provider": "2.17.1"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",