@evan_zhong/browser-attach 0.11.2 → 0.12.0

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # 架构与设计边界
 
-当前实现为 **0.11.2**。本文说明 BrowserAttach 的组件、控制模型与设计取舍；工具参数见 [使用指南](USAGE.md)。
+当前实现为 **0.12.0**。本文说明 BrowserAttach 的组件、控制模型与设计取舍；工具参数见 [使用指南](USAGE.md)。
 
 ## 组件与数据流
 
@@ -57,6 +57,7 @@ claim 与普通输入都不激活标签或窗口，也不移动系统鼠标；
 ## 观察模型
 
 - **AX 渲染**：从 `Accessibility.getFullAXTree` 读取，移除 `InlineTextBox`，合并纯文本列表项与段落名称，丢弃 `generic` / `none` 且无名称无状态的节点，只保留少量状态属性和浏览器提供的 value、invalid。每行 `[token:n] role "name"`，`token` 是本次观察的随机前缀；这些字段不证明应用已保存。
+- **交互视图**：可选 `profile=interactive` 在同一渲染器中仅保留 AX 控件角色、可聚焦/可编辑节点及其祖先链和控件内文本，不以 backendNodeId/ref 是否存在判断交互性。独立文本和合并正文可隐藏或截取预览，控件名称、值和 ref 的原始 AX 身份保留；默认 `full` 行为不变。筛选仍读取完整 AX 树，只降低输出与分页成本；视图参数绑定分页观察。
 - **ref 解析**：ref 保存 `backendNodeId`、所属 frame/session 和观察时的 AX role/name；动作时重新 `DOM.resolveNode` 并用局部 AX 查询核对语义身份。输入与求值不清空 refs，只使快照分页失效；原节点仍连接时可复用，节点替换、role/name 改变、文档或 frame 变化时安全失败，不按 role/name 猜测替代节点。
 - **双预算**：`max_nodes` 限制节点数，`max_chars` 限制每行序列化后的累计字符数；两者独立，任一耗尽都会返回 `next_cursor`。
 - **续读**：续读沿用同一份 `state`（`entries`、`refs`、`nextOffset`），所以 refs 在分页过程中保持有效。单个节点放不进预算时直接报错要求提高预算，避免静默截断尾部。

package/docs/TEST-REPORT.md

@@ -1,12 +1,12 @@
 # 验证报告
 
-当前版本 **0.11.2**（2026-10-22）。验证使用本地 fixture 和临时 profile，链路为扩展 → 本机 Hub → stdio MCP。
+当前版本 **0.12.0**（2026-10-22）。验证使用本地 fixture 和临时 profile，链路为扩展 → 本机 Hub → stdio MCP。
 
 ## 当前版本
 
-- `npm test`：144 项通过。覆盖独占控制、快照/ref 生命周期、严格 selector 与有界歧义候选、原生/DOM 输入、逐字输入、hover、pointer/HTML5 拖拽、滚动边界后的延迟加载、条件等待、HTML select、batch、历史导航、OOPIF、日志、上传、截图、对话框和未知结果不重放。
-- `npm run test:package`：仓库外含空格路径安装运行通过，22 个 MCP 工具、45 个发布文件；包含 `drag.js` / `wait.js` / `scroll.js` / `outcomes.js`，不包含配对密钥。版本为 0.11.2，示例配置使用 `@latest`。
-- Edge 155 headless `--primitives`：13 个场景通过，包含普通 pointer/HTML5 拖拽、取消 pointerdown 默认行为后的可信回执、滚动边界后延迟增长和歧义候选。
+- `npm test`：149 项通过。覆盖 interactive 快照的控件/祖先筛选、文本预览与原始 ref 身份、视图绑定分页、独占控制、快照/ref 生命周期、严格 selector 与有界歧义候选、原生/DOM 输入、逐字输入、hover、pointer/HTML5 拖拽、document 拖拽坐标差值与按轴滚动、滚动边界后的延迟加载、条件等待、HTML select、batch、历史导航、OOPIF、日志、上传、截图、对话框和未知结果不重放。
+- `npm run test:package`：仓库外含空格路径安装运行通过，22 个 MCP 工具、45 个发布文件；包含 `drag.js` / `wait.js` / `scroll.js` / `outcomes.js`，不包含配对密钥。版本为 0.12.0，示例配置使用 `@latest`。
+- Chromium headless `--primitives`：16 个场景通过，包含 interactive 快照、document 坐标纵向 pointer/HTML5 拖拽、普通 pointer/HTML5 拖拽、取消 pointerdown 默认行为后的可信回执、滚动边界后延迟增长和歧义候选。含 200 段正文的 fixture 中，默认 full 首屏 23302 字符且仍需续页，interactive 为 947 字符且无需续页；该比较只衡量返回内容，不代表 AX 采集提速。
 
 ## 升级前的浏览器验证
 

package/docs/USAGE.md

@@ -1,6 +1,6 @@
 # BrowserAttach 使用指南
 
-适用于 **0.11.2**：Node.js 22+、Chrome / Edge 125+、22 个 MCP 工具。安装、配对与升级见 [README](../README.md)；内部实现与安全模型见 [架构说明](ARCHITECTURE.md)。
+适用于 **0.12.0**：Node.js 22+、Chrome / Edge 125+、22 个 MCP 工具。安装、配对与升级见 [README](../README.md)；内部实现与安全模型见 [架构说明](ARCHITECTURE.md)。
 
 工具发现采用三层说明：初始化 `instructions` 提供跨工具规则，各工具 description 和参数 schema 说明自身行为与约束，本文保留完整边界和示例。客户端集成时应把 MCP 初始化响应中的 instructions 传入模型上下文；仅读取 tools/list 不会包含完整的通用调用规则。
 
@@ -35,7 +35,7 @@
 
 | 工具 | 主要参数 | 说明 |
 |---|---|---|
-| `browser_snapshot` | `max_nodes=600`, `max_chars=24000`, `cursor` | AX 语义树、元素 ref、frame 覆盖、待处理文件选择器 |
+| `browser_snapshot` | `profile`, `text`, `text_limit`, `max_nodes=600`, `max_chars=24000`, `cursor` | AX 语义树、元素 ref、frame 覆盖、待处理文件选择器 |
 | `browser_wait` | `condition`, `selector`, `expected` / `previous`, `idle_ms=500`, `timeout_ms=5000` | 只读等待元素、文本、URL 或被动网络空闲 |
 | `browser_read_text` | `mode`, `selector`, `offset=0`, `max_chars=20000` | 主 frame 的 DOM、字段值或支持的编辑器模型 |
 
@@ -72,7 +72,11 @@
 
 - 渲染时移除 `InlineTextBox`，合并纯文本列表项与段落名称，保留 `disabled`、`focused`、`expanded`、`checked`、`selected`、`required`、`invalid`、`level` 等状态，以及浏览器提供的 `value`；`[token:n]` 即后续动作使用的 `ref`。未提供 invalid/selected 等属性不代表有效或已提交；value 也可能只是下拉框的过滤文本。
 - `max_nodes` 为 1–3000（默认 600）；`max_chars` 为 1–2000000（默认 24000），按行序列化长度累计，与节点数是两个独立预算。
+- `profile` 默认为 `full`。`interactive` 保留 AX 控件角色、可聚焦/可编辑节点及其祖先链和控件内的文本，略去无关正文；禁用控件仍保留。仅按是否有 ref 筛选无法有效压缩，因为段落、列表项等也可能有 ref。自定义控件未提供可访问角色或可聚焦/可编辑属性时可能被省略，需用 `full` 观察。
+- `text` 默认 `true`；`false` 隐去独立文本和纯文本段落/列表项的合并正文，仍保留可访问名称及控件值。`text_limit` 为 0–10000，限制每个文本/合并正文名称并以 `…` 标明省略；`interactive` 默认 80，`full` 默认不截断。需要更多正文时重新请求 `full`，或显式提高 `text_limit`。控件名称、值及 ref 校验所用身份始终完整。
+- 返回 `profile` / `text` / `text_limit` 表明本次视图；`node_count` 和 `total_node_count` 统计筛选后的节点。`truncated` / `next_cursor` 只表示该视图尚有分页，不表示视图包含全部网页正文。筛选发生在完整 AX 树读取后，减少返回内容与分页次数，不减少 CDP 的 AX 树采集量。
 - `truncated: true` 时把 `next_cursor` 传回同一个工具继续读取同一份观察，refs 在续读期间保持有效；也可以调整预算。单个超长节点放不下时会明确报出所需预算，不静默丢尾部。
+- 续读可省略视图参数，沿用原 `profile` / `text` / `text_limit`；显式提供时必须与原观察相同。调整视图须请求新快照，并按下表使旧 ref 失效。
 - 覆盖主 frame、同进程 iframe 与递归 OOPIF；读取失败、读取期间变化或附着失败的 frame 列入 `omitted_frames`。
 
 失效规则：
@@ -150,6 +154,8 @@ hover 接受与原生 click 相同的目标，执行一次 mouseMoved，不派
 
 drag 的 source / destination 各自接受 ref、严格 selector（可带 frame_id/nth）或 x/y（可带 coordinate_space）。mode 必须按页面交互选择，默认 pointer；steps 默认 20，范围 2–100，每步间隔约 16 ms。
 
+两端均为 document 坐标且能同时容纳于一个顶层视口时，在按下前统一滚动位置，保留两端的 x/y 差值。已在视口内的 document 坐标不重复居中；需要滚动时只调整越界的轴。跨屏目标仍在按住后滚入视口，因此返回的 from/to 是各自派发时的视口坐标，不能用两者之差推断跨屏的文档距离。
+
 ```json
 {"tab_handle":"...","source":{"selector":"#card"},"destination":{"selector":"#column"},"mode":"html5","steps":20}
 ```

package/extension/click.js

@@ -67,9 +67,14 @@ export function createClick(cdp, value, viewport, position, sessions, getTab, ge
       view = await budget.run(() => viewport(target));
       if (args.coordinate_space === 'document') {
         if (!Number.isFinite(args.x) || !Number.isFinite(args.y) || args.x < 0 || args.y < 0) throw new Error('Document coordinates must be finite and nonnegative');
-        value(await send('Runtime.evaluate', { returnByValue: true,
-          expression: `scrollTo({left:${Math.max(0, args.x - view.width / 2)},top:${Math.max(0, args.y - view.height / 2)},behavior:'instant'})` }));
-        view = await budget.run(() => viewport(target));
+        const x = args.x - view.scroll_x, y = args.y - view.scroll_y;
+        if (args.scroll !== false && (x < 0 || y < 0 || x >= view.width || y >= view.height)) {
+          const left = x < 0 || x >= view.width ? Math.max(0, args.x - view.width / 2) : view.scroll_x;
+          const top = y < 0 || y >= view.height ? Math.max(0, args.y - view.height / 2) : view.scroll_y;
+          value(await send('Runtime.evaluate', { returnByValue: true,
+            expression: `scrollTo({left:${left},top:${top},behavior:'instant'})` }));
+          view = await budget.run(() => viewport(target));
+        }
         point = position(view, args.x - view.scroll_x, args.y - view.scroll_y);
       } else point = position(view, args.x, args.y);
     }

package/extension/controller.js

@@ -1,7 +1,7 @@
 // Browser operations live here; the WebSocket transport never exposes raw CDP.
 import { createVisuals } from './visuals.js';
 import { createClickVisuals } from './click-visuals.js';
-import { renderAX, snapshotPage } from './snapshot.js';
+import { renderAX, snapshotOptions, snapshotPage } from './snapshot.js';
 import { createNavigation } from './navigation.js';
 import { createClick, clickOptions, framePoint } from './click.js';
 import { createInput, inputMode, selectOptions, typeOptions } from './input.js';
@@ -38,7 +38,7 @@ export function createController(api, notify = () => {}) {
     for (const key of pageContexts.keys()) { const [tab, session] = JSON.parse(key); if (tab === tabId && session === sessionId) pageContexts.delete(key); }
   }, tabId => diagnostics.networkOptions(tabId));
   const mouse = createClick(cdp, value, viewport, position, sessions, tabId => api.tabs.get(tabId), windowId => api.windows.get(windowId));
-  const gestures = createDrag(cdp, value, mouse);
+  const gestures = createDrag(cdp, value, mouse, viewport);
   const input = createInput(cdp, value, sessions);
   const evaluations = createEvaluations(cdp);
 
@@ -291,6 +291,7 @@ export function createController(api, notify = () => {}) {
       if (!state) throw new Error('Snapshot cursor is stale or unknown. Take a new browser_snapshot.');
       return snapshotPage(state, args);
     }
+    const options = snapshotOptions(args);
     snapshots.delete(tabId);
     const documentVersion = documents.get(tabId);
     const versions = new Map(frameStates.get(tabId)?.versions);
@@ -329,12 +330,12 @@ export function createController(api, notify = () => {}) {
         knownFrames.add(childId); frames.push({ id: childId, url });
       }
       entries.push({ node: false, frameId: frame.id, line: `Frame ${frame.id} ${frame.url}` });
-      entries.push(...renderAX(nodes, token, refs, frame.id, target.sessionId));
+      entries.push(...renderAX(nodes, token, refs, frame.id, target.sessionId, options));
     }
     const metadata = value(await send(tabId, 'Runtime.evaluate', {
       expression: '({title: document.title, url: location.href})', returnByValue: true,
     }));
-    const state = { id: token, refs, entries, invalidFrames: new Set(), totalNodes: entries.filter(entry => entry.node).length,
+    const state = { id: token, options, refs, entries, invalidFrames: new Set(), totalNodes: entries.filter(entry => entry.node).length,
       metadata: { title: metadata.title, url: metadata.url, viewport: await (budget ? budget.run(() => viewport(tabId)) : viewport(tabId)), omitted_frames: omittedFrames } };
     if (documentVersion !== documents.get(tabId)) throw new Error('Document changed while reading the snapshot. Take a new browser_snapshot.');
     for (const frame of frames) if (versions.get(frame.id) !== frameStates.get(tabId)?.versions.get(frame.id)) {

package/extension/drag.js

@@ -3,12 +3,15 @@ import { targetOptions } from './locator.js';
 
 export function dragOptions(args) {
   if (!args.source || !args.destination) throw new Error('drag requires source and destination');
-  for (const target of [args.source, args.destination]) targetOptions(target, { coordinates: true });
+  for (const target of [args.source, args.destination]) {
+    targetOptions(target, { coordinates: true });
+    if (target.coordinate_space === 'document' && (target.x < 0 || target.y < 0)) throw new Error('Document coordinates must be finite and nonnegative');
+  }
   if (!['pointer', 'html5'].includes(args.mode ?? 'pointer')) throw new Error('drag mode must be pointer or html5');
   if (!Number.isInteger(args.steps ?? 20) || (args.steps ?? 20) < 2 || (args.steps ?? 20) > 100) throw new Error('steps must be 2..100');
 }
 
-export function createDrag(cdp, value, mouse) {
+export function createDrag(cdp, value, mouse, viewport) {
   const pending = new Map();
   function event(tabId, method, params, sessionId) {
     const operation = pending.get(tabId);
@@ -36,6 +39,20 @@ export function createDrag(cdp, value, mouse) {
     dragOptions(args);
     const budget = args.budget || deadline(args.timeout_ms ?? 5000), html5 = args.mode === 'html5', steps = args.steps ?? 20;
     await mouse.assertReady(tabId, budget);
+    if (args.source.coordinate_space === 'document' && args.destination.coordinate_space === 'document') {
+      const view = await budget.run(() => viewport(tabId)), a = args.source, b = args.destination;
+      // Keep both endpoints in one viewport when possible. Centering them
+      // independently can erase the requested delta before interpolation.
+      if (Math.abs(a.x - b.x) < view.width && Math.abs(a.y - b.y) < view.height) {
+        const left = Math.min(a.x, b.x) < view.scroll_x || Math.max(a.x, b.x) >= view.scroll_x + view.width
+          ? Math.max(0, (a.x + b.x - view.width) / 2) : view.scroll_x;
+        const top = Math.min(a.y, b.y) < view.scroll_y || Math.max(a.y, b.y) >= view.scroll_y + view.height
+          ? Math.max(0, (a.y + b.y - view.height) / 2) : view.scroll_y;
+        if (left !== view.scroll_x || top !== view.scroll_y) value(await budget.run(() => cdp(tabId, 'Runtime.evaluate', {
+          expression: `scrollTo({left:${left},top:${top},behavior:'instant'})`, returnByValue: true,
+        })));
+      }
+    }
     const source = await mouse.prepare(tabId, await resolve(args.source, budget), { ...args.source, budget });
     const name = `__attachDrag_${crypto.randomUUID().replaceAll('-', '')}`, contexts = new Set(), guards = [], frames = new Set();
     let intercept; const intercepted = new Promise(resolve => { intercept = resolve; });

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "BrowserAttach",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Connect existing Chrome and Edge tabs to a locally paired MCP client.",
   "minimum_chrome_version": "125",
   "permissions": [

package/extension/snapshot.js

@@ -1,9 +1,39 @@
 // Render semantic AX nodes once; page through the same observation without losing refs.
-export function renderAX(nodes, token, refs, frameId, sessionId) {
+export function snapshotOptions({ profile = 'full', text = true, text_limit } = {}) {
+  if (!['full', 'interactive'].includes(profile)) throw new Error('profile must be full or interactive');
+  if (typeof text !== 'boolean') throw new Error('text must be a boolean');
+  if (text_limit != null && (!Number.isInteger(text_limit) || text_limit < 0 || text_limit > 10000)) throw new Error('text_limit must be 0..10000');
+  return { profile, text, text_limit: text_limit ?? (profile === 'interactive' ? 80 : null) };
+}
+
+export function renderAX(nodes, token, refs, frameId, sessionId, options = snapshotOptions()) {
   const byId = new Map(nodes.map(node => [node.nodeId, node]));
   const visited = new Set();
   const entries = [];
   const textRoles = new Set(['StaticText', 'InlineTextBox', 'ListMarker']);
+  const controls = new Set(['button', 'checkbox', 'combobox', 'DisclosureTriangle', 'link', 'listbox', 'menuitem',
+    'menuitemcheckbox', 'menuitemradio', 'option', 'radio', 'scrollbar', 'searchbox', 'slider', 'spinbutton', 'switch', 'tab', 'textbox', 'treeitem']);
+  let kept;
+  if (options.profile === 'interactive') {
+    kept = new Set();
+    const parents = new Map();
+    for (const node of nodes) for (const child of node.childIds || []) parents.set(child, node.nodeId);
+    function keepText(node) {
+      if (!node || kept.has(node.nodeId)) return;
+      const role = node.role?.value;
+      if (!textRoles.has(role) && !node.ignored && !['none', 'generic'].includes(role)) return;
+      kept.add(node.nodeId);
+      for (const child of node.childIds || []) keepText(byId.get(child));
+    }
+    for (const node of nodes) {
+      if (node.ignored || !node.backendDOMNodeId || !(controls.has(node.role?.value) ||
+        node.properties?.some(prop => prop.name === 'focusable' && prop.value?.value === true ||
+          prop.name === 'editable' && prop.value?.value && prop.value.value !== 'false'))) continue;
+      for (const child of node.childIds || []) keepText(byId.get(child));
+      let id = node.nodeId;
+      while (id != null && !kept.has(id)) { kept.add(id); id = parents.get(id); }
+    }
+  }
   function plainText(node) {
     if (!node) return null;
     const role = node.role?.value;
@@ -15,6 +45,7 @@ export function renderAX(nodes, token, refs, frameId, sessionId) {
   function render(node, depth, parentName = '') {
     if (!node || visited.has(node.nodeId)) return;
     visited.add(node.nodeId);
+    if (kept && !kept.has(node.nodeId)) return;
     const role = node.role?.value || 'node';
     if (role === 'InlineTextBox') return;
     let name = String(node.name?.value || '');
@@ -28,8 +59,13 @@ export function renderAX(nodes, token, refs, frameId, sessionId) {
     ).map(prop => `${prop.name}=${JSON.stringify(prop.value?.value)}`);
     if (node.value?.value != null) states.push(`value=${JSON.stringify(node.value.value)}`);
     const attributes = states.join(' ');
-    const skip = node.ignored || (['none', 'generic'].includes(role) && !name && !attributes) ||
+    const skip = node.ignored || (!options.text && textRoles.has(role)) || (['none', 'generic'].includes(role) && !name && !attributes) ||
       (role === 'StaticText' && name === parentName);
+    const identityName = name;
+    if (textRoles.has(role) || merged) {
+      if (!options.text) name = '';
+      else if (options.text_limit != null && name.length > options.text_limit) name = name.slice(0, options.text_limit) + '…';
+    }
     let nextDepth = depth;
     if (!skip) {
       const ref = node.backendDOMNodeId ? `${token}:${refs.size + 1}` : null;
@@ -37,7 +73,7 @@ export function renderAX(nodes, token, refs, frameId, sessionId) {
       entries.push({ node: true, frameId, line: `${'  '.repeat(Math.min(depth, 24))}${ref ? `[${ref}] ` : ''}${role} ${JSON.stringify(name)}${attributes ? ' ' + attributes : ''}` });
       nextDepth++;
     }
-    if (!merged) for (const child of node.childIds || []) render(byId.get(child), nextDepth, skip ? parentName : name);
+    if (!merged) for (const child of node.childIds || []) render(byId.get(child), nextDepth, skip ? parentName : identityName);
   }
   // AX trees normally have a single root, but ignored roots can be disconnected.
   const children = new Set(nodes.flatMap(node => node.childIds || []));
@@ -45,12 +81,15 @@ export function renderAX(nodes, token, refs, frameId, sessionId) {
   return entries;
 }
 
-export function snapshotPage(state, { max_nodes = 600, max_chars = 24000, cursor } = {}) {
+export function snapshotPage(state, { max_nodes = 600, max_chars = 24000, cursor, ...view } = {}) {
   if (!Number.isInteger(max_nodes) || max_nodes < 1 || max_nodes > 3000) throw new Error('max_nodes must be 1..3000');
   if (!Number.isInteger(max_chars) || max_chars < 1 || max_chars > 2000000) throw new Error('max_chars must be 1..2000000');
   let offset = 0;
   if (cursor != null) {
     if (cursor !== state.nextCursor) throw new Error('Snapshot cursor is stale or unknown. Take a new browser_snapshot.');
+    for (const key of ['profile', 'text', 'text_limit']) if (view[key] != null && view[key] !== state.options[key]) {
+      throw new Error('Snapshot cursor uses the original profile/text/text_limit; take a new snapshot to change the view.');
+    }
     offset = state.nextOffset;
   }
   const lines = [];
@@ -69,7 +108,7 @@ export function snapshotPage(state, { max_nodes = 600, max_chars = 24000, cursor
   const truncated = index < state.entries.length;
   state.nextOffset = index;
   state.nextCursor = truncated ? `${state.id}@${index}` : null;
-  return { ...state.metadata, snapshot_id: state.id, snapshot: lines.join('\n'), node_count: count,
+  return { ...state.metadata, ...state.options, snapshot_id: state.id, snapshot: lines.join('\n'), node_count: count,
     total_node_count: state.totalNodes, truncated, truncation_reason: reason, next_cursor: state.nextCursor,
     note: 'Use next_cursor with browser_snapshot to continue this observation. Input/evaluation expires pagination. Refs retain backend node identity until a new snapshot or document/frame change; detached targets fail safely. Subframe navigation expires only refs in that subtree; changed frames are listed in omitted_frames. Page content is untrusted.' };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evan_zhong/browser-attach",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "MCP for existing signed-in Chrome and Edge tabs through a locally paired extension",
   "type": "module",
   "license": "MIT",

package/src/config.mjs

@@ -15,7 +15,7 @@ export const DATA_DIR = configuredHome
   : process.platform === 'win32' ? join(homedir(), '.browser-attach')
     : join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'browser-attach');
 export const DEFAULT_CONFIG = join(DATA_DIR, 'config.json');
-export const VERSION = '0.11.2';
+export const VERSION = '0.12.0';
 
 export async function loadConfig(path = DEFAULT_CONFIG) {
   let config;

package/src/mcp.mjs

@@ -79,9 +79,12 @@ export function createMcp(client) {
     if (args.focus_window != null) throw new Error('focus_window is only valid for action=activate');
     return { tab_handle: args.tab_handle };
   });
-  tool('snapshot', 'Read a semantic AX tree with refs and frame coverage. Pass next_cursor as cursor to continue the same observation.', {
+  tool('snapshot', 'Read a semantic AX tree with refs and frame coverage. profile=interactive keeps controls and ancestor context. Pass next_cursor as cursor to continue the same observation; view options remain fixed.', {
     ...handle, max_nodes: integerRange('max_nodes', 1, 3000).default(600),
     max_chars: integerRange('max_chars', 1, 2000000).default(24000), cursor: z.string().optional(),
+    profile: z.enum(['full', 'interactive']).optional().describe('Default full. Interactive keeps AX controls, focusable/editable nodes and their ancestors; omits unrelated reading content.'),
+    text: z.boolean().optional().describe('Default true. False omits standalone text and merged prose, preserving accessible names and control values.'),
+    text_limit: integerRange('text_limit', 0, 10000).optional().describe('Limit each text/prose name, marking truncation with …; accessible control names and values stay complete. Default 80 for interactive, unlimited for full.'),
   });
   tool('read_text', 'Read whole-page rendered text when selector is omitted; optionally scope a frame or selector. Also read field value or a supported Monaco/CodeMirror 5 model. Optional selector scopes the read. complete_source reports completeness; next_offset continues live text, which may change between reads.', {
     ...handle, ...selector, ...frameScope, mode: z.enum(['visible', 'text_content', 'value', 'editor']).default('visible'),