@glittering0717/ai-browser 1.2.2 → 1.3.1

package/src/shared/input_verify.js

@@ -0,0 +1,47 @@
+// 输入校验用的文本归一化。
+//
+// 为什么需要它：`ui.act {action:'type'|'setContent'}` 走 CDP 受信键入，输完之后要
+// 回读可编辑区内容，确认"字真的打出去了"。回读来的文本和输入的目标文本不会逐字节
+// 相等 —— 富文本编辑器会按自己的排版规则重写内容（最常见的是把一个语义换行渲染成
+// 一串 \n）。直接逐字比对会让**已经成功**的输入被判成失败，回一个
+// `cdp-input-failed`，调用方据此重试或放弃。这属于谎报，是本项目最忌讳的一类问题。
+//
+// 用法：
+//   normalizeInputText(s)  —— 校验主口径：忽略排版空白 + 压缩连续换行
+//   skeletalInputText(s)   —— 兜底口径：连换行一起剥，只用于判断"内容有没有落上去"
+//
+// 设计取舍（重要）：绝不能简单粗暴地把 \s 全剥掉。那样 "a\nb\nc" 与 "abc" 会等价，
+// 段落结构整个没了还判成功 —— 等于把谎报换成另一种谎报。所以：
+//   - 排版空白（空格 / tab）压掉：编辑器加缩进用户看不出来，不算差异；
+//   - 换行**参与**比对：段落结构必须保住；
+//   - 但连续换行压成一个：分几层由编辑器决定，不该由调用方的文本决定。
+
+/** 校验主口径：\r\n 归一 → 压排版空白 → 连续换行压成一个。 */
+export function normalizeInputText(s) {
+  return String(s || '')
+    .replace(/\r\n?/g, '\n')
+    .replace(/[^\S\n]+/g, '')
+    .replace(/\n{2,}/g, '\n');
+}
+
+/** 兜底口径：在 normalizeInputText 之上再剥掉所有换行，得到纯内容指纹。 */
+export function skeletalInputText(s) {
+  return normalizeInputText(s).replace(/\n+/g, '');
+}
+
+/**
+ * 判定一次输入是否达到了预期。
+ * @param {string} expected 调用方想写入的文本
+ * @param {string} actual   回读到的可编辑区内容
+ * @returns {{ok: boolean, landed: boolean}} ok=按主口径达标；landed=忽略全部空白后内容已到位（排版被重排过）
+ */
+export function verifyInputText(expected, actual) {
+  const want = normalizeInputText(expected);
+  const got = normalizeInputText(actual);
+  // clear（空目标）：允许残留空块外壳 —— 浏览器永远会留一个空块承载光标。
+  if (!want) return { ok: skeletalInputText(actual) === '', landed: true };
+  const ok = got.includes(want);
+  // 忽略全部空白后再比一次：相等说明东西其实打进去了、只是被编辑器重新排了版。
+  const landed = ok || skeletalInputText(actual) === skeletalInputText(expected);
+  return { ok, landed };
+}

package/src/shared/key_dispatch.cjs

@@ -0,0 +1,37 @@
+'use strict';
+// src/shared/key_dispatch.cjs —— 「这一次按键该发什么 CDP 事件」的纯决策。
+//
+// 抽成纯函数只为一件事：这是"按了等于没按"那类缺陷的唯一入口，必须能单测。
+// 藏在 PageManager 里就只能靠真起一个 Electron 才能验证。
+//
+// 核心事实：CDP 的 `rawKeyDown` **刻意不带 text**，浏览器只派发 keydown、
+// 不产生 keypress。而 Enter 激活聚焦元素（<button> 的 click、<a> 的跳转、
+// 表单的隐式提交）走的正是默认动作 —— 也就是 keypress。
+// 实测（tools/_oneoff/probe_press_enter.cjs，file:// 页面）：focus 一个 button
+// 后 ui.act press Enter，页面收到 keydown（e.key==='Enter'、isTrusted=true），
+// 但 onclick **一次都没触发**；同元素 click 正常。
+// Puppeteer 的 keyboard.press('Enter') 有效，是因为它的键表给 Enter 配了
+// text='\r'，走的是**带 text 的 keyDown**。
+//
+// 两种语义必须分开，不能全局替换：
+//   activate=true  → 带 text 的 keyDown（产生默认动作）
+//   activate 缺省  → rawKeyDown（+ 可选 char），type 的段间换行依赖它
+// 理由见 page_manager._cdpKey 的注释：type 里"先发不带 text 的 Enter，看编辑器
+// 有没有自己分段，没分才补 char"这个策略不能被改坏。
+function keyDispatchPlan(p, opts) {
+  const spec = p || {};
+  const activating = !!(opts && opts.activate);
+  // 只有 Enter 需要"补"一个默认文本：它的默认动作在 keypress 上。
+  // 其它键（Tab/Delete/方向键）的默认动作在 keydown 上，rawKeyDown 已经够。
+  let text = '';
+  if (activating) {
+    if (spec.text === undefined) text = spec.key === 'Enter' ? '\r' : '';
+    else text = spec.text || '';
+  }
+  if (activating && text) {
+    return { type: 'keyDown', text, charText: '' };
+  }
+  return { type: 'rawKeyDown', text: '', charText: spec.text || '' };
+}
+
+module.exports = { keyDispatchPlan };

package/src/shared/nav_wait.cjs

@@ -0,0 +1,47 @@
+// src/shared/nav_wait.cjs — ui.navigate 的完成信号（纯函数）
+//
+// 事故：SPA（尤其带 markdown 高亮的编辑器）永远不 fire `load`，而 navigate 走的是
+// `webContents.loadURL()` —— 它在 did-finish-load 才 resolve。于是导航"成功"的页面
+// 被当成超时：30s 空等，期间 tab 被拖到无响应，之后所有 act/evaluate 连锁超时，
+// agent 据此得出"编辑器坏了"的结论。
+//
+// load 不是可用的完成信号。这里把"等到哪一步"显式化：
+//   commit          主帧导航已提交（最快；内容可能还没渲染）
+//   domcontentloaded DOM 就绪（默认；SPA 在这一步就能返回）
+//   load            连子资源一起等（老行为，只在确实需要时用）
+
+'use strict';
+
+const LEVELS = ['commit', 'domcontentloaded', 'load'];
+const DEFAULT_LEVEL = 'domcontentloaded';
+
+// 同义词归一。刻意不接受 networkidle：它需要网络空闲探测，本实现里没有对应
+// 机制 —— 承诺一个做不到的档位，比只给三个真实档位更糟。
+const ALIASES = {
+  commit: 'commit',
+  dom: 'domcontentloaded',
+  domready: 'domcontentloaded',
+  domcontentloaded: 'domcontentloaded',
+  interactive: 'domcontentloaded',
+  load: 'load',
+  full: 'load',
+};
+
+/**
+ * 归一 wait_until。返回 { value } 或 { error }（error 可直接给调用方看）。
+ */
+function normalizeWaitUntil(v) {
+  if (v === undefined || v === null || v === '') return { value: DEFAULT_LEVEL };
+  const key = String(v).toLowerCase().replace(/[\s_-]/g, '');
+  const hit = ALIASES[key];
+  if (!hit) {
+    return {
+      error: 'unknown wait_until: ' + JSON.stringify(String(v))
+        + ' — valid values are ' + LEVELS.join(' | ')
+        + '. Default is domcontentloaded; use load only when you really need subresources.',
+    };
+  }
+  return { value: hit };
+}
+
+module.exports = { normalizeWaitUntil, LEVELS, DEFAULT_LEVEL };

package/src/shared/protocol.js

@@ -59,6 +59,10 @@ export function parseMessage(msg) {
 export const VALID_METHODS = [
   'ui.get_tree',
   'ui.act',
+  'ui.auth_state',
+  // 视口截图（P0-1）：操作失败时的第一诊断手段，弥补元素树看不见的
+  // 浮层/canvas/遮挡/渲染错位。返回 base64，默认 png。
+  'ui.screenshot',
   'ui.navigate',
   'ui.repaint',
   'ui.snapshot',
@@ -68,6 +72,10 @@ export const VALID_METHODS = [
   'ui.subscribe',
   'ui.unsubscribe',
   'ui.downloads',
+  // 主进程错误日志（只读）。界面弹过"js 崩溃"原生框、或某个动作莫名失败时，
+  // 这里是唯一能查到 stack 与"出错那一刻在调什么"的地方 —— 此前这类异常只活在
+  // 那个框里，点掉即永久丢失。
+  'ui.errors',
   'ui.get_focused',
   'ui.peek',
   'ui.wait',

package/src/shared/ref_guard.cjs

@@ -0,0 +1,133 @@
+// src/shared/ref_guard.cjs — ui.act target 的形状体检（纯函数）
+//
+// 坑：ui.act 的 target 是 get_tree 返回的 data-ai-id（如 `e:button-12`、
+// `axf-3-1`，或元素原生 id），**不是按钮上可见的文字**。传 "发布" 这类
+// label 时，最终以 `[data-ai-id="发布"]` 去查，命中不到，回一句
+// "Target not found for ref: 发布" —— 字面没错，但完全没有指出"你传的是
+// 文字不是 id"这个真正原因，调用方容易反复重试同一个错误形状。
+//
+// 这里在入口把明显不像 ref 的形状挡下来，并给可操作的提示。判定从宽：
+// 只拒**几乎不可能是 id** 的输入（含空白字符、超长、以引号/括号开头），
+// 原生 id 一律放行 —— 误拒一个合法 id 比漏放一个 label 更糟。
+
+'use strict';
+
+const MAX_REF_LEN = 120;
+
+// CJK（含全角标点）。ref 里不会出现，文案里必然出现。
+const CJK_RE = /[\u3000-\u303f\u4e00-\u9fff\uff00-\uffef]/;
+// 选择器的"结构符"。要求**至少有一个**，而不是"有空格就算"——
+// 否则 "Publish now" 这种英文按钮文案会被当成后代选择器放行，
+// 那恰恰是这套体检要拦的东西。
+const SELECTOR_MARK_RE = /[.#\[>]|\*/;
+// 选择器里允许出现的字符集合（够覆盖后代/子代/属性/伪类/分组选择器的常见写法）。
+const SELECTOR_CHARS_RE = /^[A-Za-z0-9_\-.#\[\]="'>+~:*()\s]+$/;
+
+/**
+ * 是否"像一条 CSS 选择器"。
+ * 用于 upload：上传控件常常既没有 data-ai-id、也没有可用的原生 id
+ * （B站「本地上传」是个纯 div 菜单项，AX 树里根本没有它），只能靠选择器定位。
+ * 判定刻意从严：必须**无 CJK + 含结构符 + 字符集合法**，避免把页面文案放进来。
+ */
+function looksLikeCssSelector(t) {
+  if (!t) return false;
+  if (CJK_RE.test(t)) return false;
+  if (!SELECTOR_MARK_RE.test(t)) return false;
+  return SELECTOR_CHARS_RE.test(t);
+}
+
+/**
+ * 把复合选择器拆成"逐段"的简单选择器（只按**顶层**复合子拆，属性值/伪类
+ * 参数里的空格引号不算）。返回形如 ['.a', '.b', '[type=file]']。
+ * 拆的时候丢掉组合子（`>` `+` `~` 与空格一样处理），因为回退只关心"哪几层"，
+ * 不关心层与层之间是父子还是兄弟 —— 原始写法会由调用方原样保留为第一个候选。
+ */
+function splitCompoundSelector(t) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let cur = '';
+  for (let i = 0; i < t.length; i++) {
+    const ch = t[i];
+    if (quote) {
+      cur += ch;
+      if (ch === '\\') { cur += t[i + 1] || ''; i++; continue; }
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; cur += ch; continue; }
+    if (ch === '[' || ch === '(') { depth++; cur += ch; continue; }
+    if (ch === ']' || ch === ')') { depth = Math.max(0, depth - 1); cur += ch; continue; }
+    if (depth === 0 && /[\s>+~]/.test(ch)) {
+      if (cur) { parts.push(cur); cur = ''; }
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur) parts.push(cur);
+  return parts;
+}
+
+/**
+ * 选择器的回退候选，**由长到短**：`.a .b .c` → `['.a .b .c', '.a .b', '.a']`。
+ *
+ * 为什么需要：大量上传组件在"已经有文件"的状态下会把上传区（连同它内部那个
+ * 永远隐藏的 `<input type=file>`）整个卸载，只留一个封面预览。此时
+ * `.container-coverimage-box .el-upload__input` 查不到任何元素 —— 但它的祖先
+ * `.container-coverimage-box` 还在，点它能重新唤出选择器。调用方拿这串候选
+ * 逐个试，第一个命中的就是"还能点的那一层"。
+ *
+ * 非选择器形状（真的 data-ai-id）原样返回单元素数组，不改变既有行为。
+ */
+function selectorAncestors(t) {
+  const s = String(t || '').trim();
+  if (!s) return [];
+  if (!looksLikeCssSelector(s)) return [s];
+  const parts = splitCompoundSelector(s);
+  if (parts.length <= 1) return [s];
+  // 第一个永远是原样的完整选择器（保留 `>` `+` 这些精确组合子），后面才是
+  // 逐层退化的版本 —— 优先精确命中，实在没有才放宽成后代匹配。
+  const out = [s];
+  for (let n = parts.length - 1; n >= 1; n--) {
+    const cand = parts.slice(0, n).join(' ');
+    if (cand !== s) out.push(cand);
+  }
+  return out;
+}
+
+/**
+ * target 是否"看着像"一个 data-ai-id。
+ * @param {string} target
+ * @param {{allowSelector?: boolean}} [opts] allowSelector：该动作是否接受 CSS
+ *        选择器（目前只有 upload）。开启后选择器形态直接放行，其余判定不变。
+ * @returns {string|null} null 表示放行；字符串是拒绝原因（可直接给调用方看）。
+ */
+function refShapeError(target, opts) {
+  if (target === undefined || target === null || target === '') return null; // 空由调用方按各动作规则处理
+  const t = String(target);
+  const allowSelector = !!(opts && opts.allowSelector);
+  if (allowSelector && looksLikeCssSelector(t)) return null;
+  if (/\s/.test(t)) {
+    return 'target looks like visible text, not a data-ai-id: ' + JSON.stringify(t.slice(0, 60))
+      + ' — pass the id from get_tree (e.g. "e:button-12", "axf-3-1", or the element\'s native id), not the label on screen'
+      + (allowSelector ? '; a CSS selector (e.g. ".el-upload__input") is also accepted for upload' : '');
+  }
+  // 纯 CJK、且不含任何 ASCII 字母/数字/结构符（`:` `-` `_` 等）——不可能是
+  // data-ai-id。树里的 ref 要么带结构前缀（`e:button-12` / `axf-3-1`），要么
+  // 是站点的原生 id（ASCII）。真实站点上"发布"/"点击发布"这类输入就是按钮
+  // 文案，放行只会让它变成一句无方向的 "Target not found"。
+  // 混了 ASCII 的一律放行（`e:按钮-1` 可能是合法 id）。
+  if (CJK_RE.test(t) && !/[A-Za-z0-9]/.test(t)) {
+    return 'target looks like visible text, not a data-ai-id: ' + JSON.stringify(t.slice(0, 60))
+      + ' — pass the id from get_tree (e.g. "e:button-12", "axf-3-1"). If this really is the element\'s native id, locate it with ui.evaluate instead';
+  }
+  if (t.length > MAX_REF_LEN) {
+    return 'target is ' + t.length + ' chars — data-ai-id values are short ids from get_tree, not text';
+  }
+  if (/^["'`()[\]{}]/.test(t)) {
+    return 'target starts with a quote/bracket — pass the bare id from get_tree, not a selector';
+  }
+  return null;
+}
+
+module.exports = { refShapeError, looksLikeCssSelector, selectorAncestors, splitCompoundSelector, MAX_REF_LEN };

package/src/shared/screenshot_opts.cjs

@@ -0,0 +1,130 @@
+// src/shared/screenshot_opts.cjs — ui.screenshot / browse_screenshot 参数规范化
+//
+// 为什么值得单独一个模块：截图是"把页面原样交给调用方"的动作，参数错了
+// （quality 传了字符串、clip 越界、fullPage 与 clip 同传）要么静默出坏图，
+// 要么让 CDP 报一句看不懂的错。这里在入口一次性把参数收敛成合法形状，
+// 坏参数当场给出可读错误，而不是拖到 CDP 那一层。
+
+'use strict';
+
+const FORMATS = ['png', 'jpeg', 'webp'];
+const DEFAULT_FORMAT = 'png';
+// 512KB base64 ≈ 684KB 原始字节。单次回执再大，WS 帧和模型上下文都吃不消。
+const MAX_DATA_URL_CHARS = 512 * 1024;
+
+/**
+ * 规范化截图参数。
+ * @param {object} opts 调用方传入（可能缺项/错型）
+ * @returns {{ok: true, opts: object} | {ok: false, error: string}}
+ */
+function normalizeScreenshotOpts(opts) {
+  const src = opts && typeof opts === 'object' ? opts : {};
+  const out = {};
+
+  // --- format ---
+  let format = DEFAULT_FORMAT;
+  if (src.format !== undefined && src.format !== null) {
+    if (typeof src.format !== 'string' || !FORMATS.includes(src.format)) {
+      return { ok: false, error: `format must be one of ${FORMATS.join('/')} (got ${JSON.stringify(src.format)})` };
+    }
+    format = src.format;
+  }
+  out.format = format;
+
+  // --- quality（仅 jpeg/webp 有意义；png 无损，传了忽略而不是报错）---
+  if (src.quality !== undefined && src.quality !== null) {
+    const q = Number(src.quality);
+    if (!Number.isFinite(q) || q < 0 || q > 100) {
+      return { ok: false, error: 'quality must be a number in 0..100' };
+    }
+    out.quality = Math.round(q);
+  } else if (format === 'jpeg') {
+    out.quality = 85; // 文字页面 85 肉眼无损，体积约为 png 的 1/5
+  }
+
+  // --- fullPage（captureBeyondViewport）---
+  // null 与 undefined 同样视为"未提供"：JSON 里显式传 null 表示"用默认值"，
+  // 不该和传错类型（'yes'/1）一样报错。
+  if (src.fullPage != null && typeof src.fullPage !== 'boolean') {
+    return { ok: false, error: 'fullPage must be a boolean' };
+  }
+  out.fullPage = src.fullPage === true;
+
+  // --- path（可选：把图直接落盘，省得调用方自己解 base64）---
+  // 此前传 path 会被**静默忽略**：调用方拿到 ok:true 以为文件写好了。
+  // 这是本项目反复踩的同一类坑（参数被吞 → 结论错），所以在规范层直接支持。
+  if (src.path !== undefined && src.path !== null && src.path !== '') {
+    if (typeof src.path !== 'string' || !src.path.trim()) {
+      return { ok: false, error: 'path must be a non-empty absolute file path' };
+    }
+    out.path = src.path;
+  }
+
+  // --- clip（设备像素坐标；不传则整视口）---
+  if (src.clip !== undefined && src.clip !== null) {
+    const c = src.clip;
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : NaN);
+    const clip = {
+      x: num(c.x),
+      y: num(c.y),
+      width: num(c.width),
+      height: num(c.height),
+      scale: c.scale === undefined ? 1 : num(c.scale),
+    };
+    if (['x', 'y', 'width', 'height'].some((k) => Number.isNaN(clip[k]))) {
+      return { ok: false, error: 'clip.x/y/width/height must all be numbers' };
+    }
+    if (!Number.isFinite(clip.scale) || clip.scale <= 0 || clip.scale > 4) {
+      return { ok: false, error: 'clip.scale must be a number in (0, 4]' };
+    }
+    if (clip.width <= 0 || clip.height <= 0) {
+      return { ok: false, error: 'clip.width/height must be positive' };
+    }
+    if (clip.x < 0 || clip.y < 0) {
+      return { ok: false, error: 'clip.x/y must be >= 0' };
+    }
+    // clip 与 captureBeyondViewport 同时传时，Chromium 的语义是"从 clip 顶部
+    // 开始一路拍到页面底部"——调用方九成不是这个意思，且极易拍出几十 MB 的图。
+    // 当场拦下，让调用方明确二选一。
+    if (out.fullPage) {
+      return { ok: false, error: 'fullPage and clip are mutually exclusive (captureBeyondViewport+clip means "clip top through page bottom" — pick one)' };
+    }
+    out.clip = clip;
+  }
+
+  return { ok: true, opts: out };
+}
+
+/**
+ * 回执摘要：调用方拿到图之后最想知道的几件事，省得它再发一轮查询。
+ * 敏感字段（密码框在场）单独标，因为 captureScreenshot 不会模糊它。
+ */
+function describeShot(meta) {
+  const m = meta && typeof meta === 'object' ? meta : {};
+  const out = {
+    format: m.format || 'png',
+    mime: m.mime || 'image/png',
+    bytes: typeof m.bytes === 'number' ? m.bytes : null,
+    width: typeof m.width === 'number' ? m.width : null,
+    height: typeof m.height === 'number' ? m.height : null,
+    truncated: false,
+  };
+  if (typeof m.url === 'string') out.url = m.url;
+  if (typeof m.title === 'string') out.title = m.title;
+  // CDP 的 clip/视口坐标是 CSS 像素，输出图是设备像素。带上 DPR，调用方才能
+  // 把图上的像素坐标换算回页面坐标（Retina 上差 2 倍）。
+  if (typeof m.devicePixelRatio === 'number' && m.devicePixelRatio > 0) {
+    out.device_pixel_ratio = m.devicePixelRatio;
+  }
+  if (m.hasVisiblePasswordInput === true) {
+    out.warning = 'page has a visible password input — the screenshot may contain typed secrets';
+  }
+  return out;
+}
+
+module.exports = {
+  FORMATS,
+  MAX_DATA_URL_CHARS,
+  normalizeScreenshotOpts,
+  describeShot,
+};

package/src/shared/tree_diff.cjs

@@ -0,0 +1,105 @@
+// 悬停前后两棵语义树的差异（ui.peek 的核心）。
+//
+// 数据源从 AX 换成 DOM 语义树，是实测逼出来的两个理由：
+//
+// 1. 自绘菜单在 AX 里是「无名的 generic」。实测（tools/_oneoff/peek 对照页）：
+//    一个 hover 后展开的纯 div 菜单，AX 报 7 个新节点，但两个菜单项都长这样 ——
+//      generic ""            ← 名字是空的，文字跑到子节点 StaticText 去了
+//      StaticText "普通选项一"
+//    而 AX 侧的"可交互"判据是 role 名单 / editable / focusable，generic 一条都不占
+//    → 被过滤掉 → peek 对这类菜单一律报空。DOM 读层有 isHumanClickable +
+//    floatingLayerOf + elementName，正好能认出它们（同一次实测：DOM 侧报出 2 项，
+//    都带 actions=["click"] 和坐标）。
+//
+// 2. 更致命：AX 的 id 形如 ax-{backendNodeId}，动作层解析不了（实测
+//    "Target not found for ref: ax-291"）。就算 AX 探到了，报出去的 id 也点不了。
+//    DOM 的 e:div-N 是 ui.act 直接可用的。
+//
+// 代价：DOM 抽取会写 data-ai-id 属性（get_tree 本来就在做，peek 此前也调
+// ensureHandles 打过标记），不再是"纯读"。换取的是报出来的东西真能点。
+
+// 拍平。保留根节点（它是 body 的映射，diff 时两边一致，会被自然抵消）。
+function flattenTree(root) {
+  var out = [];
+  (function walk(n) {
+    if (!n) return;
+    out.push(n);
+    var kids = n.children || [];
+    for (var i = 0; i < kids.length; i++) walk(kids[i]);
+  })(root);
+  return out;
+}
+
+// 输出给调用方的精简节点。带 actions 与 bounds，是为了让"探到了"直接等于"能点"。
+function toLite(n) {
+  var o = { id: n.id, role: n.role || 'generic', label: n.label == null ? '' : n.label };
+  if (n.actions && n.actions.length) o.actions = n.actions.slice();
+  if (n.bounds) o.bounds = n.bounds;
+  return o;
+}
+
+// 位置对得上就算同一个（菜单重开时会有 1~2px 的抖动）。
+function sameBounds(a, b) {
+  if (!a || !b) return false;
+  return Math.abs(a.x - b.x) <= 4 && Math.abs(a.y - b.y) <= 4
+    && Math.abs(a.width - b.width) <= 4 && Math.abs(a.height - b.height) <= 4;
+}
+
+// 菜单收起再展开时，DOM 节点是新造的，id 跟着变 —— 上一张快照报出去的 id 就点不动了
+// （实测 B站 头部「收藏」：revertMs=0 把鼠标移回目标后，原先报出的三个 id
+// e:div-208 / e:div-209 / e:a-229 全部消失）。想让"探到就能点"成立，必须把 id
+// 重新绑到新节点上。
+//
+// 认亲用 (role, label, bounds) 三元组：同一个菜单项重开后文本和位置不会变，
+// 而 id 会。三者全中才认，宁可对不上也不乱指 —— 对不上时保留原 id，调用方会拿到
+// target_not_found，这比悄悄点到别的东西上安全得多。
+function remapIds(liteNodes, nowNodes) {
+  var now = nowNodes || [];
+  return (liteNodes || []).map(function (n) {
+    var i;
+    for (i = 0; i < now.length; i++) if (now[i].id === n.id) return n; // 还在就别动
+    for (i = 0; i < now.length; i++) {
+      var c = now[i];
+      if (c.role === n.role && (c.label || '') === (n.label || '') && sameBounds(c.bounds, n.bounds)) {
+        // 只换 id，其余（actions / bounds）沿用原来那份 —— 重绑是为了让 id 活过来，
+        // 不是为了重算一次，顺手把已经报给调用方的信息弄丢反而更糟。
+        var o = {};
+        for (var k in n) if (Object.prototype.hasOwnProperty.call(n, k)) o[k] = n[k];
+        o.id = c.id;
+        return o;
+      }
+    }
+    return n;
+  });
+}
+
+// 可点的排前面：悬停探出来的东西里，菜单项永远比包裹它的容器有用。
+function actionableFirst(a, b) {
+  var ac = (a.actions && a.actions.length) ? 1 : 0;
+  var bc = (b.actions && b.actions.length) ? 1 : 0;
+  if (ac !== bc) return bc - ac;
+  return 0;
+}
+
+function diffTree(beforeNodes, afterNodes) {
+  var before = beforeNodes || [];
+  var after = afterNodes || [];
+  var bi = {}, ai = {}, i;
+  for (i = 0; i < before.length; i++) if (before[i] && before[i].id != null) bi[before[i].id] = before[i];
+  for (i = 0; i < after.length; i++) if (after[i] && after[i].id != null) ai[after[i].id] = after[i];
+  var revealed = [], hidden = [];
+  for (i = 0; i < after.length; i++) {
+    var n = after[i];
+    if (!n || n.id == null) continue;
+    if (!Object.prototype.hasOwnProperty.call(bi, n.id)) revealed.push(toLite(n));
+  }
+  for (i = 0; i < before.length; i++) {
+    var m = before[i];
+    if (!m || m.id == null) continue;
+    if (!Object.prototype.hasOwnProperty.call(ai, m.id)) hidden.push(toLite(m));
+  }
+  revealed.sort(actionableFirst);
+  return { revealed: revealed, hidden: hidden };
+}
+
+module.exports = { flattenTree, diffTree, toLite, remapIds, sameBounds };

package/src/shared/version.js

@@ -2,4 +2,4 @@
 // Kept in JS (not imported from package.json) to avoid Node import-attribute
 // (JSON module) compatibility issues inside Electron. package.json "version"
 // is manually synced to this value; tests assert they match.
-export const VERSION = '1.2.2';
+export const VERSION = '1.3.1';