@glittering0717/ai-browser 1.2.2 → 1.3.0

package/src/main/page_manager.js

@@ -3,6 +3,7 @@
 // Agent routes via tab ID. Tab 0 is default.
 import { ipcMain, BrowserView } from 'electron';
 import path from 'node:path';
+import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { config } from '../shared/config.js';
 import axExtractor from './axExtractor.js';
@@ -14,12 +15,53 @@ import { withDeadline, actionDeadlineMs } from '../shared/deadline.js';
 import { DownloadMonitor } from './download_monitor.js';
 import { probeCapabilities } from './capability_probe.js';
 import valueContract from '../shared/value_contract.cjs';
+// 输入成功与否的判定口径（纯函数，独立模块便于单测）。详见文件内注释：
+// 富文本编辑器会把一个语义换行渲染成一串 \n，逐字比对会把成功的输入误判成失败。
+import { normalizeInputText, skeletalInputText } from '../shared/input_verify.js';
+// 截图参数规范化（纯函数）：坏参数在入口就给可读错误，不拖到 CDP 层。
+import screenshotOpts from '../shared/screenshot_opts.cjs';
+// 跨进程子帧（OOPIF）判定与自动路由回执（纯函数）：默认读法检测到不可读
+// 子帧时自己补一次 AX 读取，调用方无需知道 ax:true 的存在。
+import frameProbe from '../shared/frame_probe.cjs';
+// ui.act target 形状体检（纯函数）：传了可见文字而不是 data-ai-id 时，
+// 入口就给可操作的错误，而不是等到选择器查空才说 "Target not found"。
+import refGuard from '../shared/ref_guard.cjs';
+// 错误日志：导航失败（界面会显示错误页）必须落盘 —— load_failed 只是内存里的
+// 一次广播，进程一退出就再也查不到"哪个 tab、哪个网址、什么错误码"。
+import { recordError } from './error_log.js';
+// navigate 的完成信号（commit | domcontentloaded | load）：默认不再是 load ——
+// SPA 永不 fire load，把它当完成信号等于把"页面可用"报成"超时"。
+import navWait from '../shared/nav_wait.cjs';
+// 穿透影子根的 ref 查找（纯字符串构造，见 shared/find_ref.cjs 顶部注释）
+import findRefUtil from '../shared/find_ref.cjs';
+// 真正的焦点元素（穿透 shadow root）。`document.activeElement` 在 Web Component
+// 里只到宿主为止，用它做输入校验会读到空串，把"已打进去"报成"没打进去"。
+import deepActiveUtil from '../shared/deep_active.cjs';
+// 悬停前后语义树的差异（ui.peek）。数据源是 DOM 语义树而不是 AX 树，理由与两条
+// 实测证据都写在 shared/tree_diff.cjs 顶部。
+import treeDiff from '../shared/tree_diff.cjs';
+// 按键派发计划（纯函数）：rawKeyDown 不产生 keypress，Enter 的默认动作会落空。
+import keyDispatchUtil from '../shared/key_dispatch.cjs';
+// 命中探测（穿透影子根）。`document.elementFromPoint` 不跨 shadow boundary，
+// 对影子内部的元素恒返回宿主 —— 于是"点击前证明坐标会落在目标上"这道校验
+// 恒为假，点击只能降级成非受信的 el.click()。详见 shared/hit_point.cjs 顶部。
+import hitPointUtil from '../shared/hit_point.cjs';
 
 const { expandValueFetchTree } = valueContract;
+const deepActiveExpr = deepActiveUtil.deepActiveExpr;
+const keyDispatchPlan = keyDispatchUtil.keyDispatchPlan;
+const { hitTestExpr, hitInfoExpr, deepHitExpr } = hitPointUtil;
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+// 穿透影子根的 ref 查找（返回自包含 JS 表达式，可原地替换 document.querySelector）。
+// 实现与理由见 src/shared/find_ref.cjs —— 那里的注释解释了为什么查询必须穿 shadow
+// boundary，以及为什么返回"表达式字符串"而不是"运行时函数"。
+const findRefExpr = findRefUtil.findRefExpr;
+const findDescExpr = findRefUtil.findDescExpr;
+
+
 // canvas 绘制调用记录：默认开。关闭开关 AI_BROWSER_CANVAS_HOOK=0。
 const CANVAS_BRIDGE_KEY = '__aiCanvasBridge';
 
@@ -119,7 +161,6 @@ class PageManager {
     this._wsClients = new Map();
     this._openedTabs = new Map();   // sourceTabId -> { id, url } (new tab opened by window.open)
     this._axDiffCache = new Map();  // tabId -> lite interactive snapshot (get_tree {mode:'diff'})
-    this._revertTimers = new Map(); // tabId -> 挂起的 ui.peek 自动回撤定时器（新 peek 会取消它）
     this._repaintTimers = new Map();// tabId -> 正在排队/已调度的重绘（合并同一批导航事件）
     this._snapshots = new Map();    // snapshotId -> { tabId, js, value, at }（ui.snapshot 存基线）
     this._snapshotSeq = 0;
@@ -268,12 +309,16 @@ class PageManager {
   }
 
   _layoutAllViews(bounds) {
+    // `_bottomInset`：窗口底部被别的东西占掉的高度（目前只有主进程异常横幅）。
+    // 由 index.js 设置、这里统一扣减 —— 让每个"给视图定尺寸"的地方各自记住
+    // 这 34px 必然会漏掉一处（新建 tab 走的是 _layoutView，不是这里）。
+    const inset = this._bottomInset || 0;
     for (const [id, view] of this.tabs) {
       view.setBounds({
         x: 0,
         y: config.tabBarHeight,
         width: bounds.width,
-        height: bounds.height - config.tabBarHeight,
+        height: Math.max(0, bounds.height - config.tabBarHeight - inset),
       });
     }
   }
@@ -451,11 +496,15 @@ class PageManager {
    * （挂起的连接、不结束的加载）。这与 ui.act 是同一类故障：await 一个可能不返回的
    * 东西。所以同样套 deadline。
    */
-  async navigate(url, tabId) {
+  async navigate(url, tabId, opts = {}) {
     const tid = tabId !== undefined ? tabId : this.activeTab;
     const view = this._getView(tid);
     if (!view) return { ok: false, error: 'Tab not found' };
+    const w = navWait.normalizeWaitUntil(opts.waitUntil);
+    if (w.error) return { ok: false, error: w.error, wait_until_valid: navWait.LEVELS };
+    const waitUntil = w.value;
     this._axDiffCache.delete(tid); // fresh page → drop stale incremental snapshot
+    const wc = view.webContents;
     // loadURL resolves at did-finish-load, which is exactly when the old
     // pixels may still be on screen — repaint here as well as from the event
     // hooks, so a programmatic navigate never depends on hook timing.
@@ -466,30 +515,102 @@ class PageManager {
     // 打断当前这次 loadURL 的 Promise —— 如果不区分，agent 收到的就是
     // {ok:false, error:"ERR_ABORTED (-3) loading 'file://.../error_page.html'"}，
     // 它会以为自己的导航请求坏了，而实际上错误页已经接管、信息全在那儿。
+    const pending = wc.loadURL(url);
+    // commit / domcontentloaded 会**提前**返回；之后这个 Promise 仍可能 reject
+    // （错误页接管、用户中止）。不接住就是 unhandledRejection，会把整个进程
+    // 的日志淹掉。错误本身在返回结果里另行汇报。
+    pending.catch(() => {});
+
     try {
-      await withDeadline(view.webContents.loadURL(url), 30000, 'navigate');
-    } catch (e) {
-      const msg = String((e && e.message) || e);
-      // 错误页已接管：这不是调用方的错，是目标站点不可达。
-      // 两个判据（都不可省）：_failureGuard 里还有这个 tab（错误页刚加载、
-      // did-finish-load 还没来清标记），或者当前 URL 已经是我们的错误页。
-      const onErrorPage = String(view.webContents.getURL() || '').indexOf('error_page.html') >= 0;
-      if ((this._failureGuard && this._failureGuard.has(tid)) || onErrorPage) {
-        return {
-          ok: false,
-          error: msg,
-          error_page: true,
-          hint: '目标站点加载失败，已显示错误页（可重试 / 改网址）。'
-            + ' 失败详情在页面里，用 ui.get_tree 或 ui.evaluate 读取。',
-        };
-      }
-      if (e && e.__deadline) {
-        return { ok: false, error: `${e.message} — the page never finished loading; it may still be loading in the background` };
+      if (waitUntil === 'load') {
+        await withDeadline(pending, 30000, 'navigate');
+      } else {
+        // 事件驱动，不等 did-finish-load。与 loadURL 自身的结果赛跑：同文档
+        // 导航（#hash、history.pushState）不会 fire did-navigate，但那类导航
+        // 的 loadURL 会立刻 resolve —— 不赛跑就会白等一整个 deadline。
+        await withDeadline(Promise.race([
+          this._waitForNavStep(wc, waitUntil, url),
+          pending.then(() => ({ at: 'resolved' }), () => ({ at: 'resolved' })),
+        ]), waitUntil === 'commit' ? 15000 : 20000, 'navigate');
       }
-      return { ok: false, error: msg.slice(0, 300) };
+    } catch (e) {
+      return this._navigateFailure(e, view, tid, waitUntil);
     }
     this.repaint(tid);
-    return { ok: true };
+    if (waitUntil === 'load') return { ok: true, waited_for: 'load' };
+    // load 还没来是**正常**的（SPA 本来就不 fire load）。如实说明，并给出
+    // 下一步：调用方需要等某个具体内容时该用 ui.wait，而不是等 load。
+    const stillLoading = typeof wc.isLoading === 'function' ? !!wc.isLoading() : false;
+    return {
+      ok: true,
+      waited_for: waitUntil,
+      url: wc.getURL(),
+      load_pending: stillLoading,
+      hint: stillLoading
+        ? 'returned at ' + waitUntil + ' — the load event has not fired (normal for SPAs); the page is usable now. Wait for specific content with ui.wait, not for load.'
+        : null,
+    };
+  }
+
+  // commit / domcontentloaded 的事件等待。只认主帧：子帧导航不改变"这个 tab 到了
+  // 没有"。任一事件先到就 resolve；did-fail-load 立刻 reject（错误页逻辑在外层）。
+  //
+  // 两个必须忽略的迟到事件（都实测踩到过）：
+  //   -3 ERR_ABORTED：上一次导航被这次导航打断，这是**正常**的取代，不是失败。
+  //      不忽略的话，连续两次 navigate 的第二跳稳定被报成 "did-fail-load -3"。
+  //   failedUrl ≠ 本次目标：上一轮导航的迟到事件。它描述的不是我们等的东西。
+  _waitForNavStep(wc, step, expectedUrl) {
+    const norm = (u) => String(u || '').split('#')[0];
+    return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        wc.removeListener('did-navigate', onCommit);
+        wc.removeListener('dom-ready', onDom);
+        wc.removeListener('did-fail-load', onFail);
+      };
+      const onCommit = () => {
+        if (step !== 'commit') return; // domcontentloaded 还要再等一步
+        cleanup();
+        resolve({ at: 'commit' });
+      };
+      const onDom = () => { cleanup(); resolve({ at: 'domcontentloaded' }); };
+      const onFail = (_e, code, desc, failedUrl, isMainFrame) => {
+        if (isMainFrame === false) return;
+        if (code === -3) return; // 被新的导航取代（见上）
+        if (expectedUrl && failedUrl && norm(failedUrl) !== norm(expectedUrl)) return;
+        cleanup();
+        reject(Object.assign(new Error('did-fail-load ' + code + ' ' + desc), { __navFail: true }));
+      };
+      wc.once('did-navigate', onCommit);
+      wc.once('dom-ready', onDom);
+      wc.once('did-fail-load', onFail);
+    });
+  }
+
+  _navigateFailure(e, view, tid, waitUntil) {
+    const msg = String((e && e.message) || e);
+    // 错误页已接管：这不是调用方的错，是目标站点不可达。
+    // 两个判据（都不可省）：_failureGuard 里还有这个 tab（错误页刚加载、
+    // did-finish-load 还没来清标记），或者当前 URL 已经是我们的错误页。
+    const onErrorPage = String(view.webContents.getURL() || '').indexOf('error_page.html') >= 0;
+    if ((this._failureGuard && this._failureGuard.has(tid)) || onErrorPage) {
+      return {
+        ok: false,
+        error: msg,
+        error_page: true,
+        hint: '目标站点加载失败，已显示错误页（可重试 / 改网址）。'
+          + ' 失败详情在页面里，用 ui.get_tree 或 ui.evaluate 读取。',
+      };
+    }
+    if (e && e.__deadline) {
+      return {
+        ok: false,
+        error: `${e.message} — navigation did not reach "${waitUntil}" in time; the page may still be loading in the background`,
+        waited_for: waitUntil,
+        hint: 'If the page is a SPA that never fires load, use wait_until:"domcontentloaded" or "commit". '
+          + 'If the tab is stuck altogether, rebuild it: ui.close_tab + ui.new_tab.',
+      };
+    }
+    return { ok: false, error: msg.slice(0, 300), waited_for: waitUntil };
   }
 
   async getTree(focusedOnly = false, tabId) {
@@ -511,9 +632,213 @@ class PageManager {
     // 截断的 node.value 带内部字段 value_fetch_ref —— 展开成含实际 tab 的
     // value_fetch（mcp/ws 两种可直接执行的调用提示），再删掉内部字段。
     if (res && res.tree) expandValueFetchTree(res.tree, tid);
+    // P1-1：页面有可见的跨进程子帧时，自动把子帧内容合并进默认树。
+    // 此前这条通路只在 ax:true 下存在，而**没有任何地方告诉调用方 ax:true
+    // 的存在** —— B站图文编辑器（正文在 OOPIF 里）因此隐形了两小时，agent
+    // 得出"编辑器没加载"的错误结论。现在默认读法自己补上这一步。
+    if (!focusedOnly) await this._autoMergeOpaqueFrames(res, tid);
     return res;
   }
 
+  // 把跨进程子帧的内容读出来、合并进默认（DOM）树。轻量：只读子帧，
+  // 不重建主树，所以默认树的形状/id 全部保持原样。
+  // 三种结局都写进 context.frame_hints（见 shared/frame_probe.describeAutoAx）：
+  // merged / no-new-content / failed+reason。调用方必须能区分"已尽力"和
+  // "还有一条没走过的路"。
+  async _autoMergeOpaqueFrames(res, tid) {
+    try {
+      if (!res || !res.tree || !res.context) return;
+      if (res.tree.__oopif_merged) return; // 幂等：合并过的树不重复做
+      const summary = res.context.cross_process_frames;
+      if (!frameProbe.shouldAutoAx(summary)) return;
+      const view = this._getView(tid);
+      if (!view) return;
+      const frames = await withDeadline(this._readOopifFrames(view, tid), 15000, 'get_tree(auto-oopif)');
+      if (frames && frames.length) {
+        res.tree = axExtractor.mergeFrameTrees(res.tree, frames);
+        res.tree.__oopif_merged = true;
+        // 子帧里的必填提示 / 校验错误也一并合进 context（否则最该有这些字段的
+        // 页面恰好是空的，见 frame_probe.mergeFrameContext 顶部注释）。
+        const mergedCtx = frameProbe.mergeFrameContext(res.context, frames);
+        if (mergedCtx) Object.assign(res.context, mergedCtx);
+      }
+      res.context.frame_hints = frameProbe.describeAutoAx({
+        merged: !!(frames && frames.length),
+        framesRead: (frames || []).length,
+      });
+    } catch (e) {
+      // 自动合并失败绝不拖垮主读法：默认树照常返回，只在 hints 里说明原因。
+      // 调用方看到 failed 可以手动切 ax:true 重试。
+      if (res && res.context) {
+        res.context.frame_hints = frameProbe.describeAutoAx({
+          error: (e && e.__deadline ? e.message + ' — the page main thread is likely blocked' : e && e.message) || String(e),
+        });
+      }
+    }
+  }
+
+  // 登录态 / 登录墙自查。长任务里每个关键步骤前都可以问一次，成本只是走一次
+  // extractPageContext（不建树）。
+  //
+  // 为什么单独开一个原语而不是让调用方自己去 getTree().context 里翻：CSDN 那次
+  // 事故里，登录态信息其实一直在 context 里，但它是个不显眼的小字段，且当时的
+  // 判定还是错的（csrfToken 子串命中 "token" → 谎报已登录）。显式暴露成
+  // "问一句就答一句"的原语，才能让"先验登录态"变成低成本的第一步。
+  // 一次性 DOM 侧上下文（不建树）。authState 与 AX 读法共用：AX 自身的
+  // context 只有 modals/session/stats，登录墙、校验错误、必填提示全都来自
+  // 这条 DOM 扫描 —— 两条读法给出不一致的 context 只会让调用方怀疑读数。
+  async _readContext(view) {
+    const res = await new Promise((resolve, reject) => {
+      const id = ++this._requestId;
+      this._pendingRequests.set(id, { resolve, reject });
+      view.webContents.send('ai:context', { id });
+      setTimeout(() => {
+        if (this._pendingRequests.has(id)) {
+          this._pendingRequests.delete(id);
+          reject(new Error('context read timeout'));
+        }
+      }, 5000);
+    });
+    return (res && res.context) || {};
+  }
+
+  async authState(tabId) {
+    const tid = tabId !== undefined ? tabId : this.activeTab;
+    const view = this._getView(tid);
+    if (!view) return { ok: false, error: 'no-such-tab', tab: tid };
+    try {
+      const ctx = (await this._readContext(view)) || {};
+      const wall = ctx.auth_wall || null;
+      return {
+        ok: true,
+        tab: tid,
+        url: ctx.url || null,
+        auth_wall: wall,
+        // 兼容旧形状：session.logged_in 仍从 context 取，但语义已收紧（见
+        // shared/auth_wall.cjs）。auth_wall.detected 是硬事实，优先级高于它。
+        logged_in: ctx.session ? !!ctx.session.logged_in : null,
+        evidence: (ctx.session && ctx.session.evidence) || [],
+        // 一句话结论，方便直接读：调用方不必自己组合字段。
+        verdict: wall && wall.detected
+          ? 'AUTH_WALL — this tab is on a login page, not the site you meant to operate'
+          : (ctx.session && ctx.session.logged_in
+            ? 'looks-logged-in (heuristic)'
+            : 'not-logged-in (heuristic) — verify before continuing'),
+      };
+    } catch (e) {
+      return { ok: false, error: e.message, tab: tid };
+    }
+  }
+
+  // 视口截图（P0-1）。此前 ai-browser 只有元素树这一只"眼睛"：树里没有的
+  // 东西（浮层、canvas、图片、CSS 遮挡、渲染错位）就完全不可见，而这类情况
+  // 恰恰是操作失败的主因。调用方失败时第一反应是"看截图"，工具面必须支持。
+  //
+  // 走 webContents.debugger 的 Page.captureScreenshot —— 与 AX/Network 域
+  // 共用同一个 per-tab attach（_ensureCdp 幂等），不额外占用调试器。
+  // 截图是同步渲染快照，主线程卡住时它不返回，所以带 deadline。
+  async screenshot(tabId, opts = {}) {
+    const tid = tabId !== undefined ? tabId : this.activeTab;
+    const view = this._getView(tid);
+    if (!view) return { ok: false, error: 'no-such-tab', tab: tid };
+
+    const norm = screenshotOpts.normalizeScreenshotOpts(opts);
+    if (!norm.ok) return { ok: false, error: norm.error, tab: tid };
+    const o = norm.opts;
+
+    let meta = {};
+    try {
+      this._ensureCdp(tid, view, 'Page');
+    } catch (e) {
+      return { ok: false, error: 'cdp-unavailable: ' + e.message, tab: tid };
+    }
+    const dbg = view.webContents.debugger;
+    if (!dbg) return { ok: false, error: 'cdp-unavailable', tab: tid };
+
+    try {
+      // 视口尺寸：clip 缺省时用于回执，也让调用方知道拍的到底是哪块。
+      // 失败不致命（老页面没布局完也会返回 0），降级为 null。
+      try {
+        const lm = await withDeadline(dbg.sendCommand('Page.getLayoutMetrics'), 10000, 'getLayoutMetrics');
+        const vp = lm && lm.cssLayoutViewport ? lm.cssLayoutViewport : (lm && lm.layoutViewport) || null;
+        if (vp) meta = { width: Math.round(vp.clientWidth || 0), height: Math.round(vp.clientHeight || 0) };
+      } catch (_) { /* 布局指标拿不到就算了，截图本身才是主目标 */ }
+
+      const params = {
+        format: o.format,
+        fromSurface: true,
+        captureBeyondViewport: o.fullPage,
+      };
+      if (o.quality !== undefined) params.quality = o.quality;
+      if (o.clip) params.clip = o.clip;
+      const shot = await withDeadline(
+        dbg.sendCommand('Page.captureScreenshot', params),
+        20000, 'captureScreenshot'
+      );
+      if (!shot || typeof shot.data !== 'string') {
+        return { ok: false, error: 'empty screenshot result', tab: tid };
+      }
+
+      const mime = 'image/' + (o.format === 'jpeg' ? 'jpeg' : o.format);
+      // 一次 evaluate 拿两样东西：可见密码框（截图不脱敏，泄密了得让调用方
+      // 知道）和 devicePixelRatio —— 后者因为 CDP 的 clip 是 CSS 像素而输出
+      // 是设备像素：调用方按 getBoundingClientRect 传 500 宽，Retina 上会
+      // 拿到 1000 像素的图。没有这个比值，"zoom 拍元素"的调用方无法把图上的
+      // 坐标换算回页面坐标。
+      let hasPwd = false;
+      let dpr = null;
+      try {
+        const p = await this.evaluate(
+          `(function(){var els=document.querySelectorAll('input[type=password]');` +
+          `var pwd=false;for(var i=0;i<els.length;i++){var r=els[i].getBoundingClientRect();` +
+          `if(r.width>0&&r.height>0)pwd=true;}return JSON.stringify({pwd:pwd,dpr:window.devicePixelRatio||1});})()`, tid);
+        let parsed = null;
+        try { parsed = typeof p === 'string' ? JSON.parse(p) : p; } catch (_) { /* evaluate 可能返回 undefined */ }
+        if (parsed) { hasPwd = parsed.pwd === true; dpr = Number(parsed.dpr) || null; }
+      } catch (_) { /* 探测失败不影响截图交付 */ }
+
+      const summary = screenshotOpts.describeShot({
+        format: o.format,
+        mime,
+        bytes: Buffer.byteLength(shot.data, 'base64'),
+        width: meta.width,
+        height: meta.height,
+        url: (this._getView(tid) && this._getView(tid).webContents.getURL()) || undefined,
+        hasVisiblePasswordInput: hasPwd,
+        devicePixelRatio: dpr,
+      });
+      // path：直接把图写到磁盘。写失败要如实报错（不是"截图成功但没文件"）。
+      let filePath = null;
+      if (o.path) {
+        try {
+          fs.mkdirSync(path.dirname(o.path), { recursive: true });
+          fs.writeFileSync(o.path, Buffer.from(shot.data, 'base64'));
+          filePath = o.path;
+        } catch (e) {
+          return { ok: false, tab: tid, error: 'screenshot captured but writing to ' + o.path + ' failed: ' + ((e && e.message) || e), ...summary };
+        }
+      }
+      // 未知参数不再静默丢弃：调用方传了什么没被用上，回执里点名。
+      const known = { format: 1, quality: 1, fullPage: 1, clip: 1, path: 1 };
+      const ignored = Object.keys(opts || {}).filter((k) => !known[k]);
+      return {
+        ok: true,
+        tab: tid,
+        // data 是 base64 裸数据（不带 data: 前缀）—— 调用方按需自己拼。
+        data: shot.data,
+        mime,
+        ...(filePath ? { path: filePath } : {}),
+        ...(ignored.length ? { ignored_params: ignored } : {}),
+        ...summary,
+      };
+    } catch (e) {
+      if (e && e.__deadline) {
+        return { ok: false, error: e.message + ' — the page main thread is likely blocked', tab: tid };
+      }
+      return { ok: false, error: e.message, tab: tid };
+    }
+  }
+
   // AX probe read layer (P0). Additive — the default getTree path is untouched.
   // Reuses the per-tab shared debugger: enables the Accessibility + DOM domains
   // into the same reference-counted _cdpTabs entry as Network/Runtime, so teardown
@@ -544,7 +869,22 @@ class PageManager {
           15000, 'get_tree(ax).attachHrefs'
         );
       }
-      return await this._finishAxTree(main, view, tid, opts);
+      const out = await this._finishAxTree(main, view, tid, opts);
+      // AX 树的 context 只有 modals/session/stats —— 登录墙、校验错误、必填提示
+      // 都在 DOM 扫描里。此前 ax:true 的调用方拿到的是一份"更薄"的上下文：
+      // 同一个页面，默认读法说"这是登录页"，ax 读法什么都不说。这里把 DOM 侧
+      // 缺的字段补齐（不覆盖 AX 已有的），两条读法的 context 才可比。
+      if (out && out.context) {
+        try {
+          const ctx = await this._readContext(view);
+          for (const k of ['auth_wall', 'validation_errors', 'field_errors', 'required_hints', 'errors', 'hints', 'forms', 'cross_process_frames']) {
+            if (out.context[k] == null && ctx[k] != null) out.context[k] = ctx[k];
+          }
+          if (!out.context.session || !Object.keys(out.context.session).length) out.context.session = ctx.session || {};
+          if (out.context.stats && ctx.stats) Object.assign(out.context.stats, { inputs: ctx.stats.inputs, buttons: ctx.stats.buttons, links: ctx.stats.links, iframes: ctx.stats.iframes });
+        } catch (e) { /* context 补全失败不影响树 */ }
+      }
+      return out;
     } catch (e) {
       if (e && e.__deadline) {
         return { tree: null, context: null, error: e.message + ' — the page main thread is likely blocked' };
@@ -562,6 +902,10 @@ class PageManager {
     const frames = await this._readOopifFrames(view, tid);
     if (frames.length && main && main.tree) {
       main.tree = axExtractor.mergeFrameTrees(main.tree, frames);
+      if (main.context) {
+        const mergedCtx = frameProbe.mergeFrameContext(main.context, frames);
+        if (mergedCtx) Object.assign(main.context, mergedCtx);
+      }
     }
     // #4: incremental diff — return only newly appeared / hidden interactive
     // nodes since the last ax read on this tab (feeds: small payload per scroll).
@@ -597,6 +941,34 @@ class PageManager {
     return out;
   }
 
+  // 子帧侧的上下文探测（在子帧自己的 JS 上下文里执行）。只做两件读操作：
+  // 收集"请输入/必填"类占位符，以及 aria-invalid 字段对应的错误文案。
+  // 规则与顶层 extractor 的 scanRequiredHints / validation_errors 同源 ——
+  // 两边给出不同口径的提示，等于让调用方自己判断信谁。
+  _frameCtxJs() {
+    return `(function(){
+      var hints=[], ves=[];
+      try{
+        var els=document.querySelectorAll('input[placeholder],textarea[placeholder],[contenteditable][data-placeholder]');
+        for(var i=0;i<els.length&&hints.length<10;i++){
+          var p=els[i].getAttribute('placeholder')||els[i].getAttribute('data-placeholder');
+          if(p&&/请\\s*(输入|填写|选择)|必填|必选|不能为空/.test(p)&&hints.indexOf(p)<0)hints.push(p.slice(0,50));
+        }
+      }catch(e){}
+      try{
+        var inv=document.querySelectorAll('[aria-invalid="true"]');
+        for(var j=0;j<inv.length&&ves.length<10;j++){
+          var el=inv[j],t='';
+          var ids=(el.getAttribute('aria-describedby')||'').split(/\\s+/);
+          for(var k=0;k<ids.length;k++){var d=ids[k]&&document.getElementById(ids[k]);if(d){t=(d.textContent||'').trim();if(t)break;}}
+          if(!t){var par=el.parentElement;if(par){var e=par.querySelector('[class*=error],[class*=err],[role=alert]');if(e)t=(e.textContent||'').trim();}}
+          ves.push({text:t.slice(0,120),near:el.id||el.name||el.getAttribute('aria-label')||el.getAttribute('placeholder')||''});
+        }
+      }catch(e){}
+      return JSON.stringify({required_hints:hints,validation_errors:ves});
+    })()`;
+  }
+
   // Read editable/interactive fields out of each out-of-process sub-frame via
   // Frame.executeJavaScript (runs in that frame's own context). Returns
   // [{ key, label, tree }] — pure mergeFrameTrees input. Stamps idempotent
@@ -654,6 +1026,16 @@ class PageManager {
             return out.length?out:null;
           })(${JSON.stringify(prefix)})`);
           if (!dto || !dto.length) continue;
+          // 子帧里的"该填什么 / 错在哪"。顶层 extractPageContext 只能看顶层文档，
+          // 而 B站图文的标题框、掘金编辑器都住在 OOPIF 里 —— 上下文扫描不跟着
+          // 走一遍子帧，required_hints / validation_errors 就会在**真正需要它们
+          // 的地方**恰好是空的（实测：B站标题框 placeholder="请输入标题"，顶层扫描
+          // 结果为空）。失败不影响建树。
+          let frameCtx = null;
+          try {
+            const rawCtx = await frame.executeJavaScript(this._frameCtxJs());
+            frameCtx = typeof rawCtx === 'string' ? JSON.parse(rawCtx) : rawCtx;
+          } catch (e) { /* 子帧上下文探测失败：树照常返回 */ }
           const tree = {
             id: key,
             role: 'generic',
@@ -672,7 +1054,7 @@ class PageManager {
               bounds: n.bounds,
             })),
           };
-          out.push({ key, label: frame.name || ('frame-' + frameSeq), tree });
+          out.push({ key, label: frame.name || ('frame-' + frameSeq), tree, context: frameCtx });
         } catch (e) { /* skip unreachable frame */ }
       }
       return out;
@@ -701,23 +1083,14 @@ class PageManager {
     const view = this._getView(tid);
     if (!view) return { revealed: [], hidden: [], mode: 'hover', error: 'Tab not found' };
     if (!target) return { revealed: [], hidden: [], mode: 'hover', error: 'No target' };
-    // 取消上一次 peek 挂起的自动回撤。回撤是"把鼠标挪走"的延迟动作，若前一次的
-    // 定时器还在，它会在本次 peek 已经把鼠标放到新目标上之后才触发，把刚刚探出来的
-    // 菜单又关掉 —— 表现为 revertMs=0（语义：别回撤）依然失效。谁后动手谁说了算。
-    const staleRevert = this._revertTimers.get(tid);
-    if (staleRevert) { clearTimeout(staleRevert); this._revertTimers.delete(tid); }
     const out = { revealed: [], hidden: [], mode: 'hover' };
     try {
-      this._ensureCdp(tid, view, 'Accessibility');
-      this._ensureCdp(tid, view, 'DOM');
+      this._ensureCdp(tid, view, 'Page'); // 只为挂上 debugger（Input 域没有 enable）
     } catch (e) { return { ...out, error: 'cdp-unavailable' }; }
     const dbg = view.webContents.debugger;
     try {
-      const beforeRaw = await axExtractor.axRaw(dbg);
-      if (!beforeRaw.length) return out;
-      await axExtractor.ensureHandles(dbg); // give the target a stable append id
       const center = await this.evaluate(
-        `(function(){var el=document.querySelector('[data-ai-id="${target}"]');if(!el)return null;` +
+        `(function(){var el=${findRefExpr(JSON.stringify(target))};if(!el)return null;` +
         `el.scrollIntoView({block:'center',inline:'center',behavior:'instant'});` +
         `var r=el.getBoundingClientRect();return {x:Math.round(r.x+r.width/2),y:Math.round(r.y+r.height/2)};})()`,
         tid);
@@ -727,31 +1100,71 @@ class PageManager {
       if (!center) {
         return { ...out, error: 'target_not_found: no element with data-ai-id=' + String(target) };
       }
+      const send = (method, params) => dbg.sendCommand(method, params);
+      // 区分"没传"与"显式传 0"：0 是合法语义（hoverMs=0 不等、revertMs=0 不回撤）。
+      // 原来的 `Number(x) || 450` 把 0 当 falsy 顶成默认值，revertMs=0 永远失效。
+      const msOr = (v, dflt) => (v === undefined || v === null || v === '') ? dflt : Math.max(0, Number(v) || 0);
       try {
     // 抢焦点会打断人正在做的事（agent 干活时人几乎不能用电脑）。
     // 策略见 _focusWindow：默认只保证窗口可见，不把它拽到最前、不抢焦点。
     this._focusWindow(view);
       } catch (e) {}
-      const send = (method, params) => dbg.sendCommand(method, params);
+      //
+      // 顺序是「先悬停拍一张，再挪开拍一张」，不是反过来。
+      //
+      // 反过来（先挪开落基线、再悬停）要求基线是"干净的"，也就是鼠标必须真的已经
+      // 离开目标、且菜单已经收完。这条做不到：菜单是带动画收起的，等多久取决于
+      // 站点 —— 实测 B站 头部「收藏」的下拉，鼠标挪开后 3 轮分别要 522 / 496 /
+      // 491ms 才从 DOM 里消失。写死等待时长不是 150ms 只有 2/4 命中，就是 550ms
+      // 也照样会漏（都试过）。
+      //
+      // 更麻烦的是"判断鼠标是否还在目标上"这一步本身也不可靠（el.matches(':hover')
+      // 在连续调用时给出的结果会跳），于是连"要不要等"都判断错。
+      //
+      // 换成先悬停再挪开，两张快照都是自己亲手造成的，与调用前的鼠标位置无关：
+      //   A = 悬停着（菜单在）  B = 挪开后（菜单不在）
+      //   revealed = A \ B  → "悬停带来的东西"，无论鼠标一开始在哪。
       await send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: center.x, y: center.y });
-      // 区分"没传"与"显式传 0"：0 是合法语义（hoverMs=0 不等、revertMs=0 不回撤）。
-      // 原来的 `Number(x) || 450` 把 0 当 falsy 顶成默认值，revertMs=0 永远失效。
-      const msOr = (v, dflt) => (v === undefined || v === null || v === '') ? dflt : Math.max(0, Number(v) || 0);
       const hoverMs = msOr(opts.hoverMs, 450);
       await new Promise((r) => setTimeout(r, hoverMs));
-      const afterRaw = await axExtractor.axRaw(dbg);
-      const diff = axExtractor.diffAx(beforeRaw, afterRaw);
+      const snapWith = await this.getTree(false, tid);
+      // 取不到快照就必须报错，不能拿空数组当基线 —— 那样另一张里的每一个节点都会
+      // 变成"新出现的"，一屏假结果比报错危险得多。
+      if (!snapWith || !snapWith.tree) {
+        return { ...out, error: 'snapshot_failed: 拿不到悬停时的语义树' };
+      }
+      const nodesWith = treeDiff.flattenTree(snapWith.tree);
+      // 挪开鼠标后要等菜单真的收完，再拍第二张。
+      //
+      // 试过"轮询元素总数直到不再减少"来适配不同站点，行不通：页面自己一直在抖
+      // （B站 首页有轮播与懒加载，元素总数常态波动），"稳定"永远达不到，每回都
+      // 跑满 12 次轮询（1080ms）。所以回到固定时长 —— 但 600 这个数是实测出来的：
+      // 轮询 B站 头部「收藏」下拉的收起耗时，3 轮分别是 491 / 496 / 522ms。
+      // 想换更短的等待可以传 opts.settleMs。
+      await send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: 4, y: 4 });
+      await new Promise((r) => setTimeout(r, msOr(opts.settleMs, 600)));
+      const snapWithout = await this.getTree(false, tid);
+      if (!snapWithout || !snapWithout.tree) {
+        return { ...out, error: 'snapshot_failed: 拿不到挪开鼠标后的语义树' };
+      }
+      const nodesWithout = treeDiff.flattenTree(snapWithout.tree);
+      const diff = treeDiff.diffTree(nodesWithout, nodesWith);
       out.revealed = diff.revealed;
       out.hidden = diff.hidden;
-      // revertMs=0 表示"别回撤，我要接着点" —— 只有显式传 0 才不该回撤，
-      // 未传则沿用 1500ms 默认（同上，0 不再是 falsy）。
+      // revertMs=0 表示"别回撤，我要接着点" —— 这时把鼠标放回目标上，让菜单重新
+      // 展开，调用方下一步可以直接点 revealed 里的东西。其余情况鼠标已经挪开了，
+      // 天然就是"回撤"，不需要延迟定时器（原先那套 per-tab 定时器也因此删掉了）。
+      //
+      // 移回之后必须重新拍一张并把 id 重绑：菜单重开时 DOM 是新造的节点，id 全变
+      // 了，直接返回刚才那批 id 的话，调用方点下去只会拿到 target_not_found。
       const revertMs = msOr(opts.revertMs, 1500);
-      if (revertMs > 0) {
-        const h = setTimeout(() => {
-          this._revertTimers.delete(tid);
-          try { send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: 4, y: 4 }); } catch (e) {}
-        }, revertMs);
-        this._revertTimers.set(tid, h);
+      if (revertMs === 0) {
+        await send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: center.x, y: center.y });
+        await new Promise((r) => setTimeout(r, msOr(opts.reopenMs, 350)));
+        const snapBack = await this.getTree(false, tid);
+        if (snapBack && snapBack.tree) {
+          out.revealed = treeDiff.remapIds(out.revealed, treeDiff.flattenTree(snapBack.tree));
+        }
       }
     } catch (e) {
       out.error = String((e && e.message) || e).slice(0, 200);
@@ -811,6 +1224,17 @@ class PageManager {
     if (!target && !targetOptional) return { success: false, error: 'No target' };
     target = target || '';
 
+    // target 形状体检：传了可见文字（"发布"）而不是 data-ai-id 时，这里就明说。
+    // 否则要等到 `[data-ai-id="发布"]` 查空，回一句不带方向的
+    // "Target not found"，调用方很难想到真正原因是形状错了。
+    if (target) {
+      // upload 额外接受 CSS 选择器：上传控件经常没有 data-ai-id（纯 div 的
+      // 「本地上传」），只能靠选择器定位。其它动作仍只认 ref —— 放行一个
+      // 它们解析不了的选择器，只会把失败推到更远、信息更少的地方。
+      const shapeErr = refGuard.refShapeError(target, { allowSelector: action === 'upload' });
+      if (shapeErr) return { success: false, error: shapeErr, method: 'bad-target-shape' };
+    }
+
     // 只读分支：取 node.value 的完整内容（树里只给前 200 code point）。
     // 不聚焦、不触发 input/change、不改页面，也不走输入动作的 fallback。
     if (action === 'get_value') return await this._getValue(view, target, params, tid);
@@ -860,14 +1284,29 @@ class PageManager {
         );
         if (r) return r;
       } catch (e) { /* fall through to preload */ }
+    } else if (action === 'paste') {
+      // 富文本粘贴：把 text/html 经合成 ClipboardEvent 送进编辑器，Draft.js /
+      // ProseMirror / Quill 的粘贴处理器会完成格式转换（与真人粘贴等效）。
+      // 支持 OOPIF 子帧（B站 read-editor 那种 ui.evaluate 到不了的上下文）。
+      try {
+        await this._ensureAxHandles(view, tid);
+        const r = await this._pasteViaCdp(view, target, params, tid);
+        if (r) return r;
+      } catch (e) { /* fall through to preload */ }
     } else if (action === 'upload') {
       try {
         await this._ensureAxHandles(view, tid);
         const r = await this._uploadViaCdp(view, target, params.file || '', tid);
+        if (r && r.success !== false) return r;
+      } catch (e) { /* fall through */ }
+      // CDP 的 DOM.setFileInputFiles 只能写顶层文档里的 input；跨进程 iframe 里的
+      // 上传控件（B站封面、编辑器插图等都属于这一类）必须走帧内注入。
+      try {
+        const r = await this._uploadViaFrameJs(view, target, params.file || '', tid);
         if (r) return r;
-      } catch (e) { /* fall through to preload */ }
+      } catch (e) { /* fall through */ }
       // 无 CDP 时 preload 无法真正赋值文件（受安全限制），返回失败让 agent 感知。
-      return { success: false, error: 'Upload requires CDP (input file set) — no file input found' };
+      return { success: false, error: 'Upload requires CDP (input file set) — no file input found for target ' + JSON.stringify(String(target || '')) };
     } else if (action === 'drag') {
       try {
         const r = await this._cdpDrag(view, target, params, tid);
@@ -920,7 +1359,7 @@ class PageManager {
     // 通过 target 内容跳出字符串。
     const js =
       "(function(){"
-      + "var el=document.querySelector('[data-ai-id=' + " + JSON.stringify(String(target)) + " + ']');"
+      + "var el=" + findRefExpr(JSON.stringify(String(target))) + ";"
       + "if(!el)return {__miss:true};"
       + "var tag=(el.tagName||'').toUpperCase();"
       + "if(tag==='INPUT'){var ty=String(el.type||'').toLowerCase();"
@@ -1026,21 +1465,40 @@ class PageManager {
     return result?.tree?.focused_element_id || null;
   }
 
-  async evaluate(js, tabId) {
+  async evaluate(js, tabId, opts = {}) {
     const tid = tabId !== undefined ? tabId : this.activeTab;
     const view = this._getView(tid);
     if (!view) throw new Error('Tab not found');
 
-    // OOPIF routing: if the JS targets a sub-frame `data-ai-id` (`axf-...`), run
-    // it inside that frame's own context via Frame.executeJavaScript — the
-    // top-frame CDP Runtime.evaluate cannot see OOPIF (cross-process iframe)
-    // DOM, so probes/`ui.evaluate` would otherwise read `null` back.
-    const m = /data-ai-id="(axf-\d+-\d+)"/.exec(js);
-    if (m) {
-      const frame = await this._owningFrame(view, m[1]);
+    // OOPIF routing. Two ways in, explicit beats implicit:
+    //   opts.frameRef  — caller passes the axf-... ref directly. Reliable:
+    //     works no matter how the JS string was built.
+    //   literal match  — the old behavior: /data-ai-id="(axf-...)/ inside the
+    //     JS source. Kept for compatibility, but it is a trap: a caller that
+    //     builds the selector by concatenation ('[data-ai-id="' + ref + '"]')
+    //     produces no literal, routing silently does not happen, and the
+    //     top-frame evaluate returns null for an element that exists.
+    //     Hit for real during the P1-2 rollout.
+    const frameRef = opts.frameRef || (/data-ai-id="(axf-\d+-\d+)"/.exec(js) || [])[1];
+    if (frameRef) {
+      const frame = await this._owningFrame(view, frameRef);
       if (frame) {
         try { return await frame.executeJavaScript(js.startsWith('(') ? js : `(function(){return ${js};})()`); }
-        catch (e) { /* fall through to top-frame path */ }
+        catch (e) {
+          // 帧找到了、但脚本自己抛了异常。不能继续走下面的 frame_not_found ——
+          // 那会把"脚本报错"误报成"引用失效"，把调用方引到"反复重读树"的死路上。
+          // 实测踩过：上传脚本里一个 TypeError 被包装成 frame_not_found，白查了半天。
+          if (opts.frameRef) {
+            throw new Error('frame_eval_failed: ' + String((e && e.message) || e).slice(0, 300));
+          }
+          /* 自动推导出的 ref：允许回落到顶层路径 */
+        }
+      }
+      // 显式给了 frameRef 却找不到帧：不能静默落到顶层 —— 调用方会拿到 null
+      // 并以为"元素不存在"。明说是路由失败。
+      if (opts.frameRef) {
+        throw new Error('frame_not_found: no cross-process frame owns ' + String(opts.frameRef)
+          + ' — the ref may be stale (page re-rendered). Re-read the tree and retry.');
       }
     }
     // Preferred path: CDP Runtime.evaluate. It runs on the DevTools protocol
@@ -1071,7 +1529,13 @@ class PageManager {
     const cmd = dbg.sendCommand('Runtime.evaluate', {
       expression: js,
       returnByValue: true,
-      awaitPromise: false,
+      // awaitPromise:true —— 调用方在页面里写 async/await 是常态（等一个请求、
+      // 等一帧渲染、等编辑器提交），此前是 false，于是 async IIFE 原样返回
+      // 一个 Promise 对象，序列化后调用方看到 **{}**，会以为"页面什么都没
+      // 返回"。实测症状：往掘金标签框写"已选中"的探测脚本明明 await 了网络
+      // 响应，回执却是空对象，据此得出"标签没选上"的错误结论。
+      // 对非 thenable 表达式此参数无副作用（CDP 直接返回值本身）。
+      awaitPromise: true,
     });
     const timeout = new Promise((_, rej) =>
       setTimeout(() => rej(new Error('cdp evaluate timeout')), 5000));
@@ -1113,7 +1577,13 @@ class PageManager {
     } catch(e) { return false; }
   }
 
-  async _cdpKey(inputCmd, p) {
+  async _cdpKey(inputCmd, p, opts) {
+    // 「按键的默认动作」要的是 keypress，不是 keydown。决策本身抽在
+    // shared/key_dispatch.cjs（纯函数，可单测），这里只负责按计划派发。
+    // 两种语义：
+    //   opts.activate = true  （ui.act press 用）→ 带 text 的 keyDown，产生默认动作
+    //   否则（type 里的段间换行/删除）→ 保持 rawKeyDown，行为不变
+    const plan = keyDispatchPlan(p, opts);
     const base = {
       windowsVirtualKeyCode: p.vk,
       nativeVirtualKeyCode: p.vk,
@@ -1122,11 +1592,16 @@ class PageManager {
       text: p.text || '',
       modifiers: p.mod || 0,
     };
-    await inputCmd('Input.dispatchKeyEvent', { ...base, type: 'rawKeyDown' });
-    // CDP 的 rawKeyDown 会忽略 text —— 带字符的键（换行）必须再发一个带
-    // text 的 char 事件才会真的把字符插进去，否则 Enter 在 textarea /
-    // 原生 contenteditable 里不产生任何换行（"a\nb\nc" 静默变成 "abc"）。
-    if (base.text) await inputCmd('Input.dispatchKeyEvent', { ...base, type: 'char' });
+    if (plan.type === 'keyDown') {
+      // keyDown 带 text：一次派发同时产出 keydown 与 char，等价真实按键。
+      await inputCmd('Input.dispatchKeyEvent', { ...base, type: 'keyDown', text: plan.text });
+    } else {
+      await inputCmd('Input.dispatchKeyEvent', { ...base, type: 'rawKeyDown' });
+      // CDP 的 rawKeyDown 会忽略 text —— 带字符的键（换行）必须再发一个带
+      // text 的 char 事件才会真的把字符插进去，否则 Enter 在 textarea /
+      // 原生 contenteditable 里不产生任何换行（"a\nb\nc" 静默变成 "abc"）。
+      if (plan.charText) await inputCmd('Input.dispatchKeyEvent', { ...base, type: 'char' });
+    }
     await inputCmd('Input.dispatchKeyEvent', { ...base, type: 'keyUp' });
   }
 
@@ -1140,7 +1615,7 @@ class PageManager {
     if (/^axf-/.test(aiId)) return await this._owningFrame(view, aiId);
     try {
       const inTop = await this.evaluate(
-        `!!document.querySelector('[data-ai-id="${aiId}"]')`,
+        `!!${findRefExpr(JSON.stringify(aiId))}`,
         tabId
       );
       if (inTop) return null;
@@ -1158,7 +1633,7 @@ class PageManager {
       if (frame === root) continue;
       try {
         const has = await frame.executeJavaScript(
-          `!!document.querySelector('[data-ai-id="${aiId}"]')`
+          `!!${findRefExpr(JSON.stringify(aiId))}`
         );
         if (has) return frame;
       } catch (e) { /* skip */ }
@@ -1227,7 +1702,7 @@ class PageManager {
       } else {
         try {
           const ok = await owning.executeJavaScript(
-            `(function(){var el=document.querySelector('[data-ai-id="${aiId}"]');if(!el)return false;` +
+            `(function(){var el=${findRefExpr(JSON.stringify(aiId))};if(!el)return false;` +
             `el.scrollIntoView({block:'center',inline:'center',behavior:'instant'});` +
             `el.focus();el.click();return true;})()`);
           return ok ? 'oopif-click' : null;
@@ -1237,11 +1712,11 @@ class PageManager {
     // 定位 → 滚入视口居中 → 返回滚动后的中心点（frame 内局部坐标）。
     const center = inFrame
       ? await owning.executeJavaScript(
-          `(function(){var el=document.querySelector('[data-ai-id="${aiId}"]');if(!el)return null;` +
+          `(function(){var el=${findRefExpr(JSON.stringify(aiId))};if(!el)return null;` +
           `el.scrollIntoView({block:'center',inline:'center',behavior:'instant'});` +
           `var r=el.getBoundingClientRect();return {x:Math.round(r.x+r.width/2),y:Math.round(r.y+r.height/2)};})()`)
       : await this.evaluate(
-          `(function(){var el=document.querySelector('[data-ai-id="${aiId}"]');if(!el)return null;` +
+          `(function(){var el=${findRefExpr(JSON.stringify(aiId))};if(!el)return null;` +
           `el.scrollIntoView({block:'center',inline:'center',behavior:'instant'});` +
           `var r=el.getBoundingClientRect();return {x:Math.round(r.x+r.width/2),y:Math.round(r.y+r.height/2)};})()`,
           tabId);
@@ -1262,18 +1737,19 @@ class PageManager {
     // 命中校验必须在派发【之前】做，且派发成功就不再回退 —— 否则一次 act 会点两次。
     // 事后校验的致命漏洞：mousePressed/mouseReleased 一发出，点击就已生效；而"点了
     // 之后自身消失/收起"的目标（话题候选收起列表、提交后置灰、菜单项、@提及、点赞）
-    // 此刻已经被自己点没了，elementFromPoint 必然命中不到 → 返回 null → executeAction
+    // 此刻已经被自己点没了，命中探测必然拿不到 → 返回 null → executeAction
     // 回退 preload 再点一次 → DOM 上出现两份插入/两次提交。派发前的坐标命中才是
     // "这一下会不会落在目标上"的唯一可信判断；校验失败（被遮挡/屏外/已隐藏）才回退。
+    //
+    // 命中探测必须穿透 shadow：不穿透的话，影子内部的元素（B站 整块评论区装在
+    // <bili-comments> 里）永远返回宿主 → contains 判定 false → 每次点击都静默
+    // 降级成非受信的 el.click()。降级本身不报错，所以表现为"能点但对某些编辑器
+    // 没反应"。hitTestExpr 同时把 contains 换成含 shadow 的祖先判定。
     if (action === 'click') {
+      const hitJs = hitTestExpr(JSON.stringify(aiId), String(center.x), String(center.y));
       const hit = inFrame
-        ? await owning.executeJavaScript(
-            `(function(){var el=document.querySelector('[data-ai-id="${aiId}"]');if(!el)return false;` +
-            `var h=document.elementFromPoint(${center.x},${center.y});return !!(h&&(h===el||el.contains(h)));})()`)
-        : await this.evaluate(
-            `(function(){var el=document.querySelector('[data-ai-id="${aiId}"]');if(!el)return false;` +
-            `var h=document.elementFromPoint(${center.x},${center.y});return !!(h&&(h===el||el.contains(h)));})()`,
-            tabId);
+        ? await owning.executeJavaScript(hitJs)
+        : await this.evaluate(hitJs, tabId);
       if (!hit) return null; // 坐标落不到目标上 —— 交给 preload 的 focus()+click 兜底
     }
     await send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: vp.x, y: vp.y });
@@ -1310,8 +1786,10 @@ class PageManager {
     if (params.at && Number.isFinite(Number(params.at.x))) {
       at = { x: Math.round(Number(params.at.x)), y: Math.round(Number(params.at.y)) };
     } else if (aiId) {
+      // 穿透 shadow：目标在 Web Component 里时 document.querySelector 够不着，
+      // 落点会静默退化成视口中心 —— 滚轮打到完全无关的地方，还报成功。
       const c = await run(
-        `var el=document.querySelector(${JSON.stringify(`[data-ai-id="${aiId}"]`)});if(!el)return null;` +
+        `var el=${findRefExpr(JSON.stringify(aiId))};if(!el)return null;` +
         `el.scrollIntoView({block:'center',inline:'center',behavior:'instant'});` +
         `var r=el.getBoundingClientRect();return {x:Math.round(r.x+r.width/2),y:Math.round(r.y+r.height/2)};`
       );
@@ -1385,9 +1863,12 @@ class PageManager {
     // 连接点识别用 classList 逐 token 词边界匹配 —— 上一版用
     // `[class*="anchor"]` 会把 `is-node-anchored` 这类无关类名当成连接点
     // （实测抢到了"标签"按钮），拖拽起点完全错位。
-    const pointFor = async (sel, anchor, offset) => {
+    // 传 aiId 而不是选择器：目标可能在 shadow 里，`document.querySelector` 够不着，
+    // 报出来是 "drag: start element not found"，读起来像元素不存在。定位统一走
+    // findRefExpr（穿透影子根），与点击路径口径一致。
+    const pointFor = async (aiId, anchor, offset) => {
       const body =
-        `var el=document.querySelector(${JSON.stringify(sel)});if(!el)return null;` +
+        `var el=${findRefExpr(JSON.stringify(aiId))};if(!el)return null;` +
         `var r=el.getBoundingClientRect();var side=${JSON.stringify(anchor)};` +
         `var cx=r.x+r.width/2,cy=r.y+r.height/2;` +
         `function isHandle(h){var cl=h.classList;for(var i=0;i<cl.length;i++){var t=cl[i];` +
@@ -1417,8 +1898,13 @@ class PageManager {
         // 判定必须是"命中即是连接点，或连接点的子孙"。**不能**接受
         // `hit.contains(handle)`：节点本体当然包含自己的连接点，那样会把这个
         // 失败情形原样放行（第一版就是这么写的，实测仍然报 handle）。
-        `if(best){var hit=document.elementFromPoint(best.x,best.y);` +
-        `if(!(hit&&(hit===best.el||best.el.contains(hit))))best=null;}` +
+        // 命中探测同样要穿透 shadow（连接点在 Web Component 里时，不穿透就
+        // 恒判"没命中"，于是永远回退到 via:'edge'，把"按在连接点上"降级成
+        // "按在节点边沿"）。跨 shadow 后用含 shadow 的祖先判定。
+        `if(best){var hit=${deepHitExpr('best.x', 'best.y')};` +
+        `var ok=false,c=hit,g=0;` +
+        `while(c&&g++<128){if(c===best.el){ok=true;break;}c=c.parentNode||c.host||null;}` +
+        `if(!ok)best=null;}` +
         `if(best){delete best.el;return best;}` +
         `if(side==='right')return {x:r.right,y:r.y+r.height/2,via:'edge'};` +
         `if(side==='left')return {x:r.left,y:r.y+r.height/2,via:'edge'};` +
@@ -1436,19 +1922,21 @@ class PageManager {
     // 同时向上找最近的 data-ai-id：如果它**不是**本次目标，说明抓错了节点
     // （实测踩过：两个节点视觉重叠时，拖 A 实际按在叠在上面的 B 的浮层上，
     // 事件照常派发、success 照常返回，但什么都没动）。
+    //
+    // 穿透 shadow + 含 shadow 的上溯，理由同上。原来那版用 e.closest('[data-ai-id]')：
+    // closest 走到影子树顶就停，影子内部的元素永远得到 id:null，于是 `is_target`
+    // 恒为 true —— "抓错节点"的检测被静默跳过，正是它存在的意义所在。
     const atPointJs = (p, selfId) =>
-      `var e=document.elementFromPoint(${p.x},${p.y});if(!e)return null;` +
-      `var anc=e.closest?e.closest('[data-ai-id]'):null;` +
-      `var id=anc?anc.getAttribute('data-ai-id'):null;` +
-      `return {el:(e.tagName||'')+' '+(typeof e.className==='string'?e.className:'').slice(0,60),` +
-      `id:id,is_target:(id===null||id===${JSON.stringify(String(selfId))})};`;
+      `var info=${hitInfoExpr(String(p.x), String(p.y))};if(!info)return null;` +
+      `return {el:info.el,id:info.id,` +
+      `is_target:(info.id===null||info.id===${JSON.stringify(String(selfId))})};`;
 
     // 起点
     let from = null;
     if (params.from && Number.isFinite(Number(params.from.x))) {
       from = { x: Math.round(Number(params.from.x)), y: Math.round(Number(params.from.y)), via: 'explicit' };
     } else if (aiId) {
-      from = await pointFor(`[data-ai-id="${aiId}"]`, anchorOf(params.from_anchor), params.from_offset);
+      from = await pointFor(aiId, anchorOf(params.from_anchor), params.from_offset);
     }
     if (!from) return { success: false, error: 'drag: start element not found: ' + aiId };
 
@@ -1466,7 +1954,7 @@ class PageManager {
     if (explicitTo && Number.isFinite(Number(explicitTo.x)) && Number.isFinite(Number(explicitTo.y))) {
       to = { x: Math.round(Number(explicitTo.x)), y: Math.round(Number(explicitTo.y)), via: 'explicit' };
     } else if (params.to_target) {
-      to = await pointFor(`[data-ai-id="${params.to_target}"]`, anchorOf(params.to_anchor), params.to_offset);
+      to = await pointFor(params.to_target, anchorOf(params.to_anchor), params.to_offset);
       if (!to) return { success: false, error: 'drag: to_target not found: ' + params.to_target };
     } else if (Number.isFinite(Number(params.dx)) || Number.isFinite(Number(params.dy))) {
       to = { x: Math.round(from.x + Number(params.dx || 0)), y: Math.round(from.y + Number(params.dy || 0)), via: 'delta' };
@@ -1573,7 +2061,10 @@ class PageManager {
       this._focusWindow(view);
     } catch (e) {}
     if (aiId) {
-      await run(`var el=document.querySelector(${JSON.stringify('[data-ai-id="' + String(aiId) + '"]')});if(el&&el.focus)el.focus();return true;`);
+      // 穿透 shadow：目标在 Web Component 里时 querySelector 拿不到 el，
+      // focus 这一步被静默跳过 —— 按键发给"当前焦点"（多半是 body），
+      // 现象是快捷键完全没生效，但回执照常 success。
+      await run(`var el=${findRefExpr(JSON.stringify(String(aiId)))};if(el&&el.focus)el.focus();return true;`);
     }
     const list = Array.isArray(params.keys) && params.keys.length
       ? params.keys
@@ -1584,13 +2075,113 @@ class PageManager {
     for (const name of list) {
       const spec = keySpec(name, params.modifiers);
       if (!spec) return { success: false, error: 'press: unsupported key: ' + String(name), pressed: done };
-      await this._cdpKey(send, spec);
+      await this._cdpKey(send, spec, { activate: true });
       done.push(spec.key);
       await new Promise((r) => setTimeout(r, Math.max(20, Number(params.interval_ms) || 60)));
     }
     return { success: true, pressed_via: 'cdp-key', pressed: done };
   }
 
+  // 富文本粘贴（ui.act {action:'paste'}）—— 把带格式内容（HTML）送进编辑器的
+  // 唯一可靠通路。
+  //
+  // 为什么需要这个动作而不是让调用方自己合成事件：
+  //   1) setContent/type 走 CDP 受信键盘，只能送**纯文本** —— 标题层级、代码块、
+  //      加粗、列表全丢失。B站图文那篇只能发纯文本版，就是这个原因。
+  //   2) 在 OOPIF 子帧里（B站 read-editor），ui.evaluate 到不了那个执行上下文，
+  //      调用方连"自己搓一个 paste 事件"都做不到 —— 这是最疼的一条。
+  //   3) 粘贴是编辑器的**一等公民路径**：Draft.js 的 DraftPasteProcessor、
+  //      ProseMirror 的 transformPastedHTML、Quill 的 clipboard 模块都会把
+  //      text/html 转成各自的内部文档模型。合成一个带 clipboardData 的
+  //      ClipboardEvent('paste') 正是触发这条路径的正规方式，与真人粘贴等效。
+  //
+  // 参数契约：params.html（优先）或 params.text。两者都空 → 明确报错，
+  // 不静默成功（同 cdp-input-empty-text 的教训）。
+  async _pasteViaCdp(view, aiId, params, tabId) {
+    if (!this._canCdp(view)) return null;
+    const html = typeof params.html === 'string' ? params.html : '';
+    const text = typeof params.text === 'string' ? params.text : '';
+    if (!html && !text) {
+      return {
+        success: false,
+        error: 'paste called with neither html nor text — nothing to paste. '
+          + 'Pass params: {html: "<h2>...</h2>"} for rich text, or {text: "..."} for plain.',
+        method: 'paste-empty',
+      };
+    }
+    const owning = await this._owningFrameFor(view, aiId, tabId);
+    const inFrame = !!owning;
+    const run = async (jsBody) => {
+      const fn = `(function(){${jsBody}})()`;
+      return inFrame ? owning.executeJavaScript(fn) : this.evaluate(fn, tabId);
+    };
+    try { this._focusWindow(view); } catch (e) {}
+
+    // 定位 + 聚焦 + 派发**必须在同一次帧内执行里完成**。拆成两步（先 prep 聚焦、
+    // 再回来派发）会丢目标：OOPIF 里 focus() 之后 document.activeElement 的
+    // 读回可能仍是旧值，且 Draft.js 这类编辑器把 paste 监听挂在**最内层的
+    // contenteditable 面子节点**上（.public-DraftEditor-content）——事件从容器
+    // 派发不会向下传播到子节点，监听器收不到，defaultPrevented 恒为 false。
+    // 实测：B站 read-editor 拆两步派发 → 编辑器完全无反应；合并 + 选定最深层
+    // 可编辑元素后成功。
+    const payload = JSON.stringify({ html, text });
+    const res = await run(
+      `var p=${payload};` +
+      `var el=${findRefExpr(JSON.stringify(aiId))};if(!el)return {ok:false,err:'no-ref'};` +
+      // 选定真正的编辑面：el 自己可编辑就用 el；否则取内部第一个可编辑后代
+      // （Draft.js/ProseMirror 的编辑面都是容器里的一个子 div）。
+      `var ed=el;` +
+      `var elEditable=(ed.contentEditable==='true')||(ed.tagName==='TEXTAREA')||(ed.tagName==='INPUT');` +
+      `if(!elEditable&&ed.querySelector){var inner=${findDescExpr('ed', JSON.stringify('[contenteditable=true],input,textarea'))};if(inner)ed=inner;}` +
+      `var editable=(ed.contentEditable==='true')||(ed.tagName==='TEXTAREA')||(ed.tagName==='INPUT');` +
+      `if(!editable)return {ok:false,err:'not-editable'};` +
+      `ed.focus();` +
+      `var dt=new DataTransfer();` +
+      `if(p.html)dt.setData('text/html',p.html);` +
+      `dt.setData('text/plain',p.text||p.html.replace(/<[^>]+>/g,' ').replace(/&nbsp;/g,' ').replace(/\\s+/g,' ').trim());` +
+      `var ev=new ClipboardEvent('paste',{clipboardData:dt,bubbles:true,cancelable:true,composed:true});` +
+      `var notPrevented=ed.dispatchEvent(ev);` +
+      `return {ok:true,prevented:!notPrevented,tag:ed.tagName};`
+    );
+    if (!res || !res.ok) {
+      return { success: false, error: (res && res.err) || 'paste failed', method: 'synthetic-clipboard-event' };
+    }
+    // 编辑器没接管粘贴（prevented=false）= 页面对合成粘贴不买账。如实报告，
+    // 并给出可操作建议，而不是报 success 让调用方以为内容进去了。
+    if (!res.prevented) {
+      return {
+        success: false,
+        error: 'paste event was not consumed by the page (defaultPrevented=false) — this editor likely listens on a different surface (e.g. a child element or shadow root). Try pasting into a child node ref, or fall back to setContent for plain text.',
+        method: 'synthetic-clipboard-event',
+        consumed: false,
+      };
+    }
+    // 落盘校验：读回编辑器内容。归一化沿用 P0-2 修过的口径（换行会被编辑器
+    // 膨胀，逐字比对必然失配）。只给 html 时无法文本比对，退而检查"有内容"。
+    await new Promise((r) => setTimeout(r, 350)); // 编辑器处理粘贴多为异步（React 提交）
+    const landed = await run(`var e=${deepActiveExpr()};return {text:(e&&(e.innerText||e.value||''))||'',html:(e&&e.innerHTML||'')};`);
+    const landedText = (landed && landed.text) || '';
+    const landedLen = landedText.replace(/\s+/g, '').length;
+    if (!landedLen) {
+      return {
+        success: false,
+        error: 'paste was consumed but nothing landed — the editor may have rejected the payload (unsanitized HTML?). Read the editor content back to confirm.',
+        method: 'synthetic-clipboard-event',
+        consumed: true,
+        landed_chars: 0,
+      };
+    }
+    return {
+      success: true,
+      method: 'synthetic-clipboard-event',
+      consumed: true,
+      in_frame: inFrame,
+      landed_chars: landedLen,
+      // 只给 html 时调用方无法预知文本形态，把读回内容捎上，省一轮查询。
+      ...(html && !text ? { landed_preview: landedText.slice(0, 200) } : {}),
+    };
+  }
+
   // 文件上传（封面/附件等，跨框架通用）：HTMLInputElement[type=file] 只能由
   // DevTools 的 DOM.setFileInputFiles 写入真实文件路径（网页脚本无法伪造
   // FileList，preload 同样受限），对任何站点/上传组件一视同仁。找到目标 input
@@ -1604,7 +2195,7 @@ class PageManager {
     // 用户在系统选择器选中）；若再对它 click 会重新唤起系统文件框并清空 files，
     // 导致刚写入的状态被覆盖。由调用方负责先让上传组件就绪。
     const idRes = await dbg.sendCommand('Runtime.evaluate', {
-      expression: `(function(){var el=document.querySelector('[data-ai-id="${aiId}"]');return el&&el.__proto__&&el.matches?el.matches('input[type=file],input')?el:null:null;})()`,
+      expression: `(function(){var el=${findRefExpr(JSON.stringify(aiId))};return el&&el.__proto__&&el.matches?el.matches('input[type=file],input')?el:null:null;})()`,
       returnByValue: false,
     });
     const objId = idRes && idRes.result && idRes.result.objectId;
@@ -1612,7 +2203,7 @@ class PageManager {
     await dbg.sendCommand('DOM.setFileInputFiles', { files: [filePath], objectId: objId });
     // 兜底校验：确认 files 已写入
     const ver = await dbg.sendCommand('Runtime.evaluate', {
-      expression: `(function(){var f=document.querySelector('[data-ai-id="${aiId}"]').files;return f&&f.length>0?{name:f[0].name,size:f[0].size}:null;})()`,
+      expression: `(function(){var f=${findRefExpr(JSON.stringify(aiId))}.files;return f&&f.length>0?{name:f[0].name,size:f[0].size}:null;})()`,
       returnByValue: true,
     });
     const v = ver && ver.result && ver.result.value;
@@ -1620,6 +2211,189 @@ class PageManager {
     return { success: true, uploaded: v.name, size: v.size };
   }
 
+  // 跨帧文件上传（含 OOPIF）。CDP 的 DOM.setFileInputFiles 需要顶层文档里的
+  // nodeId/objectId，够不着 iframe 内部的 input —— B站封面上传、多数编辑器的
+  // "插入图片"都在 iframe 里，实测只得出一条 "no file input found"。
+  // 走到帧内：文件读成字节 → 在目标帧构造 File → DataTransfer 赋给 input.files
+  // → 派发 change，与"用户在系统选择器里选中文件"等价。
+  //
+  // 三种状态的控件都要能对付（实测各站点轮流出现）：
+  //   1. 目标本身就是 input[type=file] —— 直接写；
+  //   2. 目标是容器，input 预挂在里面 —— 取容器里的第一个 file input；
+  //   3. 容器里**一个 input 都没有**（组件在"已上传"状态下把上传区整个卸载了，
+  //      CSDN 的封面就是：有封面时 .container-coverimage-box 里连
+  //      .el-upload__input 都不存在）—— 临时接管 HTMLInputElement.prototype.click
+  //      再把容器点开，捕获"点击时才创建"的那个 input。
+  // 第 3 种是 target 写成 `.box .el-upload__input` 这类"指向 input 本身的选择器"
+  // 时最容易踩的：整条选择器查不到元素，但它的祖先还在。所以 target 先展开成
+  // 由长到短的回退候选（selectorAncestors），用第一个命中的祖先当锚点。
+  async _uploadViaFrameJs(view, aiId, filePath, tabId) {
+    if (!aiId) return null;
+    if (!filePath) throw new Error('upload requires a file path');
+    // 上传控件经常没有语义节点（B站的「本地上传」就是个纯 div 菜单项，AX 树里
+    // 根本没有它），此时调用方给不出 ref，只能给 CSS 选择器。所以 target 先按
+    // data-ai-id 找，找不到再当作选择器：先找帧、再找顶层文档。
+    const target = String(aiId);
+    // 由长到短的候选：`.a .b` → ['.a .b', '.a']。data-ai-id 形状的 target
+    // 走 selectorAncestors 会原样返回单元素，行为不变。
+    const cands = refGuard.selectorAncestors(target);
+    let owning = await this._owningFrameFor(view, aiId, tabId);
+    let inTop = false;
+    if (!owning) {
+      const probe = `(function(){var C=${JSON.stringify(cands)};for(var i=0;i<C.length;i++){try{if(document.querySelector(C[i]))return true;}catch(e){}}return false;})()`;
+      for (const frame of (view.webContents.mainFrame.framesInSubtree || [])) {
+        if (frame === view.webContents.mainFrame) continue;
+        try { if (await frame.executeJavaScript(probe)) { owning = frame; break; } }
+        catch (e) { /* skip */ }
+      }
+      if (!owning) {
+        try { inTop = !!(await this.evaluate(probe, tabId)); } catch (e) { inTop = false; }
+      }
+    }
+    if (!owning && !inTop) {
+      // 连锚点都找不到：明确说"选择器没命中任何元素"，而不是笼统的
+      // "no file input found"（后者会让人以为选择器命中了但里面没 input）。
+      return {
+        success: false,
+        method: 'frame-file-inject',
+        error: 'upload target not found: no element matches '
+          + JSON.stringify(cands[0] || target) + (cands.length > 1 ? ' (nor its ancestors ' + JSON.stringify(cands.slice(1)) + ')' : '')
+          + ' — pass the control that OPENS the file picker, or a CSS selector for it',
+        candidates: cands,
+      };
+    }
+    let buf;
+    try { buf = fs.readFileSync(filePath); } catch (e) {
+      return { success: false, method: 'frame-file-inject', error: 'cannot read file: ' + String((e && e.message) || e).slice(0, 160) };
+    }
+    const name = path.basename(filePath);
+    const ext = name.toLowerCase().slice(name.lastIndexOf('.'));
+    const mime = ext === '.png' ? 'image/png'
+      : (ext === '.jpg' || ext === '.jpeg') ? 'image/jpeg'
+        : ext === '.webp' ? 'image/webp'
+          : ext === '.gif' ? 'image/gif' : 'application/octet-stream';
+    // 内联 base64 直接走 frame.executeJavaScript —— 不受 WS 侧 evaluate 的
+    // 5000 字符守卫约束（那个守卫只拦 ui.evaluate 的 js 参数）。
+    const b64 = buf.toString('base64');
+    const refSel = JSON.stringify('[data-ai-id="' + target + '"]');
+    const js = `(function(){
+var C=${JSON.stringify(cands)};
+var REF=${refSel};
+var b64=${JSON.stringify(b64)};
+var name=${JSON.stringify(name)};
+var mime=${JSON.stringify(mime)};
+function isFileInput(e){return !!e&&e.tagName==='INPUT'&&e.type==='file';}
+function q(sel,root){try{return (root||document).querySelector(sel);}catch(e){return null;}}
+// 1) 先按 data-ai-id 找（ref 才是权威），再按选择器候选由长到短找。
+// 按 ref 找必须穿透 shadow：上传控件装在 Web Component 里时，顶层 querySelector
+// 拿不到，报出来是 "no-el" —— 看起来像没有上传入口，实际是查询路径够不着。
+var host=null,hostSel=null;
+var byRef=${findRefExpr('REF')};
+if(byRef){host=byRef;hostSel=REF;}
+for(var i=0;i<C.length&&!host;i++){var el=q(C[i]);if(el){host=el;hostSel=C[i];break;}}
+if(!host) return {ok:false,err:'no-el'};
+// <label for=...> 的点击会由浏览器直接激活目标 input、绕过 JS 层拦截 → 系统文件框
+// 会真的弹出来。所以遇到 label 先顺着 control 拿 input，拿不到就不点它。
+// 找后代同样要穿透 shadow（findDescExpr 会下钻 el.shadowRoot）：宿主可能是
+// <bili-*> 之类，真正的 input[type=file] 在它自己的影子树里。
+function labelInput(el){try{var c=el.control;if(isFileInput(c))return c;var n=el.querySelector&&${findDescExpr('el', JSON.stringify('input[type=file]'))};if(n)return n;}catch(e){}return null;}
+function find(root){
+  if(!root)return null;
+  if(isFileInput(root))return root;
+  if(root.tagName==='LABEL'){var li=labelInput(root);if(li)return li;}
+  var r=null;try{r=${findDescExpr('root', JSON.stringify('input[type=file]'))};}catch(e){r=null;}
+  return r;
+}
+var inp=find(host),via='direct';
+// 2) 点击捕获：接管原型 click（元素的 .click() 会走到这里），挡住系统框，
+//    同时暂时让 showOpenFilePicker 挂起，避免 File System Access API 那条路漏网。
+function captureOnce(t){
+  if(!t)return null;
+  var cap=null,proto=HTMLInputElement.prototype,orig=proto.click,origPicker=window.showOpenFilePicker;
+  try{window.showOpenFilePicker=function(){return new Promise(function(){});};}catch(e){}
+  proto.click=function(){if(this.type==='file'){cap=this;return;}try{return orig.apply(this,arguments);}catch(e){}};
+  try{t.click();}catch(e){}
+  try{proto.click=orig;}catch(e){}
+  try{window.showOpenFilePicker=origPicker;}catch(e){}
+  return cap;
+}
+var clicked=[];
+if(!inp){
+  inp=captureOnce(host);
+  if(inp)via='click';
+  else{
+    clicked.push((host.className||host.tagName||'').toString().slice(0,40));
+    // 3) 锚点自己点不出东西就往下探一层：只挑"长得像触发器"的、且真正可见的
+    //    后代，最多 8 次就收手（每次点击都可能改变页面状态，不能无限试）。
+    //    负向词表必须有：封面区里常驻一个「删除封面」按钮，类名带 cover，
+    //    正向匹配会命中它 —— 一旦可见就会被点掉用户的封面。
+    var RX=/upload|file|add|plus|replace|change|select|image|cover/i;
+    var BAD=/remove|delete|del-|trash|clear|cancel|close|drop/i;
+    var nodes=[],all=[];
+    try{all=host.querySelectorAll('button,label,[role=button],a,div,span,i');}catch(e){all=[];}
+    for(var k=0;k<all.length&&nodes.length<8;k++){
+      var e2=all[k],cls=String(e2.className||''),tag=e2.tagName,role=e2.getAttribute&&e2.getAttribute('role');
+      if(BAD.test(cls))continue;
+      if(!(RX.test(cls)||tag==='BUTTON'||tag==='LABEL'||tag==='A'||role==='button'))continue;
+      var rc=e2.getBoundingClientRect();
+      if(rc.width<2||rc.height<2)continue;   // 不可见的不点（0×0 的多是布局占位）
+      nodes.push(e2);
+    }
+    for(var j=0;j<nodes.length&&!inp;j++){
+      var nd=nodes[j];
+      if(nd.tagName==='LABEL'&&!labelInput(nd))continue;
+      inp=captureOnce(nd);
+      clicked.push((nd.className||nd.tagName||'').toString().slice(0,40));
+      if(inp)via='click-descendant';
+    }
+  }
+}
+if(!inp)inp=find(host);
+if(!inp)return {ok:false,err:'no-file-input',host_sel:hostSel,clicked:clicked};
+if(!inp.isConnected){
+  // 捕获到的 input 往往是"创建了但还没插进文档"（组件打算点完就丢），
+  // 挂在锚点下、藏起来：change 才能沿组件自己的 DOM 树冒泡到它的委托处理器。
+  try{inp.style.display='none';host.appendChild(inp);}catch(e){}
+}
+var bin=atob(b64),n=bin.length,arr=new Uint8Array(n);
+for(var m=0;m<n;m++)arr[m]=bin.charCodeAt(m);
+var file=new File([arr],name,{type:mime});
+var dt=new DataTransfer();dt.items.add(file);
+inp.files=dt.files;
+inp.dispatchEvent(new Event('change',{bubbles:true}));
+return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:clicked};
+})()`;
+    const res = owning ? await owning.executeJavaScript(js) : await this.evaluate(js, tabId);
+    if (!res || !res.ok) {
+      const err = (res && res.err) || 'upload-failed';
+      if (err === 'no-file-input') {
+        return {
+          success: false,
+          method: 'frame-file-inject',
+          error: 'found ' + JSON.stringify((res && res.host_sel) || target)
+            + ' but no <input type=file> appeared after clicking it'
+            + ' (clicked: ' + JSON.stringify((res && res.clicked) || []) + ')'
+            + ' — pass the element that OPENS the file picker (e.g. the "upload local file" menu item) as target',
+          candidates: cands,
+        };
+      }
+      return { success: false, method: 'frame-file-inject', error: err, candidates: cands };
+    }
+    // in_frame 如实反映实际执行位置：顶层文档上传（CSDN 那种）不应报 true。
+    return {
+      success: true,
+      method: 'frame-file-inject',
+      uploaded: res.name,
+      size: res.size,
+      in_frame: !!owning,
+      // 上传组件可能有三种入口状态，回执如实说明用了哪条路：
+      //   direct = input 本来就在；click = 点了锚点才创建；
+      //   click-descendant = 锚点里再往下探了一层才点出 input。
+      resolved_by: res.via || 'direct',
+      host_sel: res.host_sel === refSel ? '[data-ai-id]' : (res.host_sel || null),
+    };
+  }
+
   // 通用文本输入（type/setContent 共用）：先让窗口/视图拿到焦点，再在页面里
   // DOM 原生聚焦（一次 evaluate 同步完成）→ CDP 受信 Cmd+A 全选 + Delete 清空
   // → 逐字符受信键入 + Enter。清空必须走编辑器自身的受信按键链路：Draft 等
@@ -1649,8 +2423,8 @@ class PageManager {
     } catch(e) {}
     // 定位可编辑区并原生聚焦（不做 DOM 全选——交给 Cmd+A 受信按键）
     const prep = await run(
-      `var el=document.querySelector('[data-ai-id="${aiId}"]');if(!el)return {ok:false,err:'no-ref'};` +
-      `var ed=el;if(ed.querySelector){var inner=ed.querySelector('[contenteditable=true],input,textarea');if(inner)ed=inner;}` +
+      `var el=${findRefExpr(JSON.stringify(aiId))};if(!el)return {ok:false,err:'no-ref'};` +
+      `var ed=el;if(ed.querySelector){var inner=${findDescExpr('ed', JSON.stringify('[contenteditable=true],input,textarea'))};if(inner)ed=inner;}` +
       `var editable=(ed.contentEditable==='true')||(ed.tagName==='TEXTAREA')||(ed.tagName==='INPUT');` +
       `if(!editable)return {ok:false,err:'not-editable'};` +
       `ed.focus();` +
@@ -1663,8 +2437,11 @@ class PageManager {
     // h2>blockquote>pre>ul>li 的套娃），editor_blocks 的 role 也随之失真。
     // 只在"确实已经没有文本内容"时拆，有内容的块一个都不动。
     const stripEmptyShells = () => run(
-      `var el=document.querySelector(${JSON.stringify('[data-ai-id="' + String(aiId) + '"]')});if(!el)return false;` +
-      `var ed=el;if(ed.querySelector){var inner=ed.querySelector('[contenteditable=true],input,textarea');if(inner)ed=inner;}` +
+      // 与上面 prep 同一口径（穿透 shadow 的 findRefExpr）。两处必须一致：
+      // prep 认得的元素、这里也要认得，否则"清空校验"读到空、把已经清干净的
+      // 编辑器判成没清掉，接着又拆一遍。
+      `var el=${findRefExpr(JSON.stringify(aiId))};if(!el)return false;` +
+      `var ed=el;if(ed.querySelector){var inner=${findDescExpr('ed', JSON.stringify('[contenteditable=true],input,textarea'))};if(inner)ed=inner;}` +
       `if(ed.tagName==='INPUT'||ed.tagName==='TEXTAREA')return false;` +
       `if(ed.contentEditable!=='true')return false;` +
       `if((ed.innerText||'').trim()!=='')return false;` +
@@ -1681,15 +2458,23 @@ class PageManager {
     // clear 时先拆一遍：编辑器可能已经是"空但带外壳"的状态，不拆的话下面的
     // 幂等短路会把它当成"已经是空的"直接返回，外壳就永远留在那儿。
     if (!text) await stripEmptyShells();
-    // 校验用的归一化。\r\n 统一成 \n，再压掉"排版空白"（空格/tab），但换行
-    // 本身必须参与比对：把 \s 全剥掉会让 "a\nb\nc" 与 "abc" 等价，段落结构
-    // 丢失就被判成成功 —— 那是对调用方的谎报，出了问题无从察觉。
-    const norm = (s) => String(s || '').replace(/\r\n?/g, '\n').replace(/[^\S\n]+/g, '');
+    // 校验用的归一化，依次做三件事：
+    //   1. \r\n 统一成 \n（Windows 换行与受信 Enter 产出的 \r 不该算差异）；
+    //   2. 压掉"排版空白"（空格/tab），但换行本身必须参与比对 —— 把 \s 全剥掉
+    //      会让 "a\nb\nc" 与 "abc" 等价，段落结构丢了还判成功，那是谎报；
+    //   3. 连续换行压成一个。
+    // 第 3 条来自实测：contenteditable 编辑器（Quill/ProseMirror/Slate…）普遍把
+    // 一个语义换行渲染成一串 \n —— 往 B站 read-editor 输入 "AA\nBB"，读回是
+    // "AA\n\nBB"。逐字比对必然失配，于是**内容明明写进去了却回 success:false /
+    // cdp-input-failed**，调用方据此重试或放弃，而页面其实已经是想要的样子。
+    // 压缩换行仍然保留"有没有分段"这一层信息，只是不再纠结分了几层。
+    const norm = normalizeInputText;
+    const skeletal = skeletalInputText;
     // 幂等短路：若可编辑区当前内容已恰好等于目标文本，直接返回而不做清空+重打。
     // 每次全量重写都会把草稿标脏，重新触发编辑器自身的"草稿备份"/版本气泡——对
     // 相同文本的重复调用（重试/校正）不应让它反复闪烁。
     const curText = await run(
-      `var e=document.activeElement;return (e&&(e.innerText||e.value||''))||'';`
+      `var e=${deepActiveExpr()};return (e&&(e.innerText||e.value||''))||'';`
     );
     if (norm(curText) === norm(text)) {
       // "目标就是当前内容" 与 "目标本来就是空的" 必须区分开。
@@ -1726,8 +2511,8 @@ class PageManager {
       const at = opts.at === 'start' || opts.at === 'cursor' ? opts.at : 'end';
       if (at !== 'cursor') {
         await run(
-          `var el=document.querySelector(${JSON.stringify('[data-ai-id="' + String(aiId) + '"]')});if(!el)return false;` +
-          `var ed=el;if(ed.querySelector){var inner=ed.querySelector('[contenteditable=true],input,textarea');if(inner)ed=inner;}` +
+          `var el=${findRefExpr(JSON.stringify(String(aiId)))};if(!el)return false;` +
+          `var ed=el;if(ed.querySelector){var inner=${findDescExpr('ed', JSON.stringify('[contenteditable=true],input,textarea'))};if(inner)ed=inner;}` +
           `if(ed.tagName==='INPUT'||ed.tagName==='TEXTAREA'){var L=(ed.value||'').length;` +
           `var p=(${JSON.stringify(at)}==='start')?0:L;try{ed.setSelectionRange(p,p);}catch(e){}return true;}` +
           `if(ed.contentEditable!=='true')return false;` +
@@ -1757,14 +2542,14 @@ class PageManager {
         // 实测残留 "第一段<div>第二段</div><h2>第三段</h2>"。因此清完校验一次，
         // 仍有文本就换编辑器原生 selectAll+delete 再清一遍。
         const left = await run(
-          `var el=document.querySelector(${JSON.stringify('[data-ai-id="' + String(aiId) + '"]')});if(!el)return 0;` +
-          `var ed=el;if(ed.querySelector){var inner=ed.querySelector('[contenteditable=true],input,textarea');if(inner)ed=inner;}` +
+          `var el=${findRefExpr(JSON.stringify(String(aiId)))};if(!el)return 0;` +
+          `var ed=el;if(ed.querySelector){var inner=${findDescExpr('ed', JSON.stringify('[contenteditable=true],input,textarea'))};if(inner)ed=inner;}` +
           `return String((ed.innerText!=null?ed.innerText:ed.value)||'').trim().length;`
         );
         if (left > 0) {
           await run(
-            `var el=document.querySelector(${JSON.stringify('[data-ai-id="' + String(aiId) + '"]')});if(!el)return false;` +
-            `var ed=el;if(ed.querySelector){var inner=ed.querySelector('[contenteditable=true],input,textarea');if(inner)ed=inner;}` +
+            `var el=${findRefExpr(JSON.stringify(String(aiId)))};if(!el)return false;` +
+            `var ed=el;if(ed.querySelector){var inner=${findDescExpr('ed', JSON.stringify('[contenteditable=true],input,textarea'))};if(inner)ed=inner;}` +
             `try{ed.focus();document.execCommand('selectAll');document.execCommand('delete');}catch(e){}return true;`
           );
           await new Promise((r) => setTimeout(r, 150)); // 等编辑器状态提交
@@ -1775,7 +2560,7 @@ class PageManager {
     const paras = String(text == null ? '' : text).split('\n');
     // 段落内容快照：用来判断"这一下 Enter 到底有没有生效"。
     const snap = () => run(
-      `var e=document.activeElement;var t=String((e&&(e.innerText||e.value))||'');` +
+      `var e=${deepActiveExpr()};var t=String((e&&(e.innerText||e.value))||'');` +
       `var b=(e&&e.querySelectorAll)?e.querySelectorAll('p,div,br').length:0;` +
       `return {len:t.length,nl:(t.match(/\\n/g)||[]).length,blocks:b};`
     );
@@ -1801,16 +2586,29 @@ class PageManager {
     // 通用校验：非空文本要求内容包含目标文本；空文本要求已清空（只允许空块残留）。
     // 任一框架均可，无占位符/块数特判。
     const after = await run(
-      `var e=document.activeElement;return {text:(e.innerText||e.value||'')};`
+      `var e=${deepActiveExpr()};return {text:(e.innerText||e.value||'')};`
     );
     const want = norm(text);
     const got = norm(after && after.text);
-    const ok = want
-      ? got.includes(want)
-      : got === '';
-    return ok
-      ? { success: true, method: 'cdp-input', chars: (after && after.text) ? after.text.length : 0 }
-      : { success: false, error: 'Input not verified — please re-read the tree and retry', method: 'cdp-input-failed' };
+    // clear（空目标）：允许残留空块外壳 —— 编辑器永远乐于留下一个空 <p>。
+    const ok = want ? got.includes(want) : skeletal(got) === '';
+    if (ok) {
+      return { success: true, method: 'cdp-input', chars: (after && after.text) ? after.text.length : 0 };
+    }
+    // 诊断：忽略全部空白后再比一次。相等说明东西其实打进去了、只是被编辑器
+    // 重新排了版；不等说明大概率压根没落上去。两者的处置方式完全相反。
+    const landed = want ? skeletal(after && after.text) === skeletal(text) : false;
+    return {
+      success: false,
+      error: 'Input not verified — please re-read the tree and retry',
+      method: 'cdp-input-failed',
+      expected_chars: want.length,
+      actual_chars: got.length,
+      content_landed_ignoring_whitespace: landed,
+      hint: landed
+        ? 'the text matches once all whitespace is ignored — the editor most likely re-formatted line breaks/padding. Treat as applied and re-read the tree to confirm.'
+        : 'the text does not match even after stripping whitespace — the input probably did not land. Check focus/target before retrying.',
+    };
   }
 
   // OOPIF 内整段清空：在所属子帧上下文里聚焦 contenteditable，用 execCommand
@@ -1819,8 +2617,8 @@ class PageManager {
   async _clearInFrame(frame, aiId) {
     try {
       const r = await frame.executeJavaScript(`(function(){
-        var ref=document.querySelector('[data-ai-id="${aiId}"]');if(!ref)return {ok:false,reason:'no-ref'};
-        var e=ref;if(ref.querySelector){var inner=ref.querySelector('[contenteditable="true"],textarea,input[type="text"],input[type="search"],input[type="title"],input:not([type])');if(inner)e=inner;}
+        var ref=${findRefExpr(JSON.stringify(aiId))};if(!ref)return {ok:false,reason:'no-ref'};
+        var e=ref;if(ref.querySelector){var inner=${findDescExpr('ref', JSON.stringify('[contenteditable="true"],textarea,input[type="text"],input[type="search"],input[type="title"],input:not([type])'))};if(inner)e=inner;}
         var isInput=(e.tagName==='INPUT'||e.tagName==='TEXTAREA');
         var isCE=e.contentEditable==='true';
         if(!(isInput||isCE))return {ok:false,reason:'not-editable'};
@@ -1844,8 +2642,8 @@ class PageManager {
   async _selectAllFallback(view, aiId, tabId, frame) {
     const r = frame
       ? await frame.executeJavaScript(
-          `(function(){var el=document.querySelector('[data-ai-id="${aiId}"]');if(!el)return false;` +
-          `var ed=el;if(ed.querySelector){var inner=ed.querySelector('[contenteditable=true],input,textarea');if(inner)ed=inner;}` +
+          `(function(){var el=${findRefExpr(JSON.stringify(aiId))};if(!el)return false;` +
+          `var ed=el;if(ed.querySelector){var inner=${findDescExpr('ed', JSON.stringify('[contenteditable=true],input,textarea'))};if(inner)ed=inner;}` +
           `var s=window.getSelection();` +
           `if(s&&!s.isCollapsed&&s.toString().length>0)return true;` +
           `if(ed.tagName==='TEXTAREA'||ed.tagName==='INPUT'){var v=ed.value||'';if(v){ed.focus();ed.setSelectionRange(0,v.length);}return v.length>0;}` +
@@ -1857,8 +2655,8 @@ class PageManager {
           `s.removeAllRanges();s.addRange(rng);` +
           `return rng.toString().length>0;})()`)
       : await this.evaluate(
-          `(function(){var el=document.querySelector('[data-ai-id="${aiId}"]');if(!el)return false;` +
-          `var ed=el;if(ed.querySelector){var inner=ed.querySelector('[contenteditable=true],input,textarea');if(inner)ed=inner;}` +
+          `(function(){var el=${findRefExpr(JSON.stringify(aiId))};if(!el)return false;` +
+          `var ed=el;if(ed.querySelector){var inner=${findDescExpr('ed', JSON.stringify('[contenteditable=true],input,textarea'))};if(inner)ed=inner;}` +
           `var s=window.getSelection();` +
           `if(s&&!s.isCollapsed&&s.toString().length>0)return true;` +
           `if(ed.tagName==='TEXTAREA'||ed.tagName==='INPUT'){var v=ed.value||'';if(v){ed.focus();ed.setSelectionRange(0,v.length);}return v.length>0;}` +
@@ -2052,6 +2850,15 @@ class PageManager {
         error_code: errorCode,
         error: String(errorDescription || ''),
       });
+      // 同一件事落盘。错误页在界面上看得见，但"哪个 tab、哪个网址、错误码多少"
+      // 一旦进程退出就查不回来了（load_failed 只是一次内存广播）。
+      recordError('nav_fail', {
+        tab: tabId,
+        url: String(validatedURL || ''),
+        error_code: errorCode,
+        error: String(errorDescription || ''),
+        error_page: 'shown',
+      });
       // 错误页本身加载成功后清掉防重入标记，否则同 tab 后续失败都不显示。
       view.webContents.once('did-finish-load', () => {
         if (this._failureGuard) this._failureGuard.delete(tabId);
@@ -2292,11 +3099,12 @@ class PageManager {
 
   _layoutView(view) {
     const bounds = this.window.getContentBounds();
+    const inset = this._bottomInset || 0;
     view.setBounds({
       x: 0,
       y: config.tabBarHeight,
       width: bounds.width,
-      height: bounds.height - config.tabBarHeight,
+      height: Math.max(0, bounds.height - config.tabBarHeight - inset),
     });
   }