@glittering0717/ai-browser 2.1.12 → 2.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittering0717/ai-browser",
-  "version": "2.1.12",
+  "version": "2.1.14",
   "description": "AI-native browser — renders pixels for humans, structured semantic-tree API for agents. No screenshots, no OCR, no coordinate guessing.",
   "main": "src/main/index.js",
   "bin": {
@@ -82,7 +82,9 @@
     "install:app": "node scripts/install_app.cjs",
     "dialog": "node e2e/dialog_ws.cjs",
     "verify:app": "node e2e/shipped_ws.cjs",
-    "wrapper": "node e2e/wrapper_ws.cjs"
+    "wrapper": "node e2e/wrapper_ws.cjs",
+    "paint": "node e2e/paint_ws.cjs",
+    "layout": "node e2e/layout_ws.cjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/src/main/index.js

@@ -1,6 +1,6 @@
 // main/index.js — Electron entry v5 (multi-tab, real UI)
 // One process, one WS server, multiple tabs with real tab bar.
-import { app, BrowserWindow, BrowserView, ipcMain, net, session, dialog } from 'electron';
+import { app, BrowserWindow, BrowserView, ipcMain, net, session, dialog, screen, powerMonitor } from 'electron';
 import path from 'node:path';
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -454,10 +454,12 @@ function createWindow() {
     };
   });
   ipcMain.on('nav:go', (_e, input) => {
-    const wc = activeWebContents();
     const url = normalizeUrlInput(input);
-    if (!wc || !url) return;
-    try { wc.loadURL(url); } catch (e) { console.error('[index] nav:go failed:', e.message); }
+    if (!url) return;
+    // 走 pageManager.navigate 而不是裸 loadURL：裸的这条路上没有导航状态机
+    // （list_tabs 会一直报 ready）、没有失败错误页、也没有导航完成后的重绘。
+    // 地址栏是最常用的一条路，缺这三样的代价就是"有时白屏、说不清在干嘛"。
+    pageManager.navigate(url, pageManager.activeTab).catch(() => {});
   });
   ipcMain.on('nav:back', () => { const wc = activeWebContents(); if (wc && wc.navigationHistory) wc.navigationHistory.goBack(); });
   ipcMain.on('nav:forward', () => { const wc = activeWebContents(); if (wc && wc.navigationHistory) wc.navigationHistory.goForward(); });
@@ -486,6 +488,8 @@ function createWindow() {
   mainWindow.on('resize', () => {
     layoutWithBanner();
   });
+  // 注：resize 的重绘（repaintActiveSoon）在下面"几何变化"一段里统一绑定 ——
+  // 那里能看到 repaintActive 的定义。
 
   // === Window becoming visible again → force a compositor repaint ===
   //
@@ -501,9 +505,37 @@ function createWindow() {
   // looking at a stale frame. Repainting on show/restore/focus means the view
   // catches up the moment it becomes visible — no clicking tabs required.
   const repaintActive = () => { try { pageManager.repaint(pageManager.activeTab); } catch (e) {} };
+  // 拖动窗口边缘时会连发几十个 resize；逐个重绘会抖成幻灯片。150ms 去抖：松手就补一帧。
+  let repaintTimer = null;
+  const repaintActiveSoon = (ms = 150) => {
+    if (repaintTimer) clearTimeout(repaintTimer);
+    repaintTimer = setTimeout(repaintActive, ms);
+  };
   mainWindow.on('show', repaintActive);
   mainWindow.on('restore', repaintActive);
   mainWindow.on('focus', repaintActive);
+
+  // === 几何变化 → 必须让 surface 重新栅格化 ===
+  //
+  // 只重排（setBounds）不够：如果 surface 还是旧尺寸，合成器会把那张大图缩进新的
+  // bounds —— 用户看到"页面缩成左上角一小块、其余全白"，而 DOM、evaluate、截图
+  // 全都正常（2026-10-25 用户截图就是这个形态）。所以要连 invalidate 一起做。
+  //
+  // 触发点选这几个：窗口缩放、进出全屏（macOS 全屏会换 display）、显示器参数变化
+  // （分辨率/缩放/插拔外接屏）、系统从睡眠唤醒 —— 这四类都会让"窗口几何"和
+  // "合成器手里的 surface 尺寸"脱节，是最常见的来源。
+  mainWindow.on('resize', () => repaintActiveSoon(150));
+  mainWindow.on('enter-full-screen', () => { layoutWithBanner(); repaintActiveSoon(120); });
+  mainWindow.on('leave-full-screen', () => { layoutWithBanner(); repaintActiveSoon(120); });
+  const onDisplayChange = () => { try { layoutWithBanner(); } catch (e) {} repaintActiveSoon(60); };
+  try {
+    screen.on('display-metrics-changed', onDisplayChange);
+    screen.on('display-added', onDisplayChange);
+    screen.on('display-removed', onDisplayChange);
+  } catch (e) { /* 无 screen 模块（极老版本） */ }
+  try {
+    powerMonitor.on('resume', () => { onDisplayChange(); repaintActiveSoon(400); });
+  } catch (e) { /* 无 powerMonitor */ }
   mainWindow.on('app-command-added', (_e, cmd) => {
     // macOS window-management commands (zoom / minimize / fullscreen).
     if (cmd === 'togglefullscreen' || cmd === 'zoom' || cmd === 'minimize') repaintActive();

package/src/main/page_manager.js

@@ -1,7 +1,7 @@
 // main/page_manager.js — Multi-tab page lifecycle manager v2
 // One Electron process, one WS server, multiple tabs.
 // Agent routes via tab ID. Tab 0 is default.
-import { ipcMain, BrowserView } from 'electron';
+import { ipcMain, BrowserView, nativeImage } from 'electron';
 import path from 'node:path';
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -29,6 +29,9 @@ import { wrapperHintExpr, wrapperHintText } from '../shared/wrapper_hint.js';
 // normalizeAxTree 里已经自带，这条补的是默认路径 —— 见文件内注释。
 import editorsProbe from '../shared/editors_probe.js';
 import { newTracker, noteTree, diagnoseMissingRef } from '../shared/ref_epoch.js';
+// "这一页到底画出来没有"的判定口径（纯函数）。此前没有任何检测覆盖"加载成功但
+// 屏幕纯白"这一类 —— 见 shared/blank_page.cjs 顶部（2026-10-25 用户报百度白屏）。
+import blankPage from '../shared/blank_page.cjs';
 import { diffValues, previewOf, safeByteLength, DEFAULT_SNAPSHOT_JS, DIFF_MAX_ENTRIES, evictOldest } from './snapshot_diff.js';
 import { withDeadline, actionDeadlineMs } from '../shared/deadline.js';
 import { DownloadMonitor } from './download_monitor.js';
@@ -213,6 +216,26 @@ class PageManager {
     this._openDialogs = new Map();
     this._axDiffCache = new Map();  // tabId -> lite interactive snapshot (get_tree {mode:'diff'})
     this._repaintTimers = new Map();// tabId -> 正在排队/已调度的重绘（合并同一批导航事件）
+    // === 白屏自检（paint audit）===
+    // tabId -> {verdict, blank, white_ratio, unique, action, at, url}：最近一次自检的结论。
+    // 为什么必须有它：白屏是唯一一种"所有事件都成功、DOM 也正常、但用户看到的是空"的
+    // 失败形态，没有观测就只能靠人截图喊"白的"。有了它，list_tabs / paint_check
+    // 能把"这一页画出来了没有"当成一个可查询的事实。
+    this._paintState = new Map();
+    // tabId -> 本轮已经执行过几步补救（0=还没救过）。一有新的导航就清零，
+    // 所以"救不动"不会变成跨页面的永久状态。
+    this._paintSteps = new Map();
+    this._paintTimers = new Map();  // tabId -> 排队中的自检（合并 dom-ready/finish-load 的连发）
+    // tabId -> 正在跑的那一轮自检的 Promise。并发调用共享同一个 Promise，
+    // 而不是"发现有人在跑就返回 null"（那会让调用方拿到一个空结论）。
+    this._paintAuditInflight = new Map();
+    // 白屏自检的总开关。默认开；关掉它的唯一场景是"我要精确测量导航时延"。
+    this._paintAuditEnabled = process.env.AI_BROWSER_PAINT_AUDIT !== '0';
+    // 自己发起的 reload（自救用）。用它区分"这次 did-finish-load 是我们的补救"
+    // 还是"用户/页面自己导航了"—— 前者必须保留补救步数，否则会无限重载。
+    this._paintSelfReload = new Set();
+    // tabId -> 上次因渲染进程崩溃而重载的时刻（见 _attachCrashRecovery 的 15s 上限）
+    this._crashReloadAt = new Map();
     this._snapshots = new Map();    // snapshotId -> { tabId, js, value, at }（ui.snapshot 存基线）
     this._snapshotSeq = 0;
     this.networkMonitor = new NetworkMonitor({}, { captureEnabled: NETWORK_CAPTURE_DEFAULT });
@@ -650,6 +673,16 @@ class PageManager {
     // {ok:false, error:"ERR_ABORTED (-3) loading 'file://.../error_page.html'"}，
     // 它会以为自己的导航请求坏了，而实际上错误页已经接管、信息全在那儿。
     const pending = wc.loadURL(url);
+    // 导航状态机也在这里维护：此前只有 new_tab 的占位流程会写 _tabNavState，
+    // 于是 ui.navigate 期间 list_tabs 一直报 'ready' —— agent 看到 ready 就去
+    // 读树/截图，拿到的是旧页面或半张页面，然后开始"重试"。
+    this._tabNavState.set(tid, 'loading');
+    const markReady = () => {
+      if (this._tabNavState.get(tid) === 'loading') this._tabNavState.set(tid, 'ready');
+    };
+    wc.once('did-finish-load', markReady);
+    wc.once('did-fail-load', markReady);
+    setTimeout(markReady, 20000).unref?.();
     // commit / domcontentloaded 会**提前**返回；之后这个 Promise 仍可能 reject
     // （错误页接管、用户中止）。不接住就是 unhandledRejection，会把整个进程
     // 的日志淹掉。错误本身在返回结果里另行汇报。
@@ -3412,6 +3445,10 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
     }
 
     this._attachLoadFailureHooks(tabId, view);
+    // "画出来了没有"只能主动看（没有对应事件），"渲染进程崩了"要自己救
+    // （以前只打一行日志，用户看到的是永久白屏）。
+    this._attachPaintHook(tabId, view);
+    this._attachCrashRecovery(tabId, view);
     return tabId;
   }
 
@@ -3541,6 +3578,17 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
       this.window.removeBrowserView(view);
       this.window.addBrowserView(view);
       this._layoutView(view);
+      // remove+add 只改变合成树里的位置，**不保证 surface 重新栅格化**：
+      // 如果 surface 还是旧尺寸（窗口从大到小之后很常见），合成器会把那张大图
+      // 缩小/裁到新 bounds 里 —— 用户看到的就是"内容缩成左上角一小块、其余全白"。
+      // 真正的重栅格化要靠 invalidate()；再叠一次 1px 微调，是因为
+      // setBounds 尺寸没变时 Chromium 会直接忽略（不会重算 surface）。
+      try { view.webContents.invalidate(); } catch (_) {}
+      const b = view.getBounds();
+      try {
+        view.setBounds({ ...b, width: b.width + 1 });
+        view.setBounds(b);
+      } catch (_) {}
     } catch(e) { return false; }
     // Cumulative counter, reported by ui.repaint. Not just a debug aid: it is
     // the only externally observable proof that a repaint actually happened.
@@ -3568,6 +3616,390 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
     return null;
   }
 
+  // === 白屏自检 ==============================================================
+  //
+  // 为什么这一层以前不存在，而它必须存在：
+  //   "网络失败"有 did-fail-load（→ 错误页），"渲染进程死了"有 render-process-gone，
+  //   但**"页面加载成功、DOM 也有内容、屏幕上却是纯白"**这一类没有任何事件。
+  //   它是唯一一种"所有回调都成功"的失败形态，所以只能靠主动看一眼画面。
+  //   2026-10-25 用户报"打开了百度有时候是纯白屏"就是这一类 —— 当时工具侧
+  //   （evaluate / get_tree / screenshot）全都读得到内容，等于集体失明。
+  //
+  // 观测口径写在 shared/blank_page.cjs：白度 + 唯一色数 + DOM 事实，三者一起判。
+
+  /** 页面自述的事实：有多少字、多少个节点、到哪一步了。 */
+  static PAINT_DOM_JS =
+    '(function(){var b=document.body,d=document.documentElement;' +
+    'var t=b?(b.innerText||b.textContent||""):"";' +
+    'return JSON.stringify({' +
+    'text_len:t.replace(/\\s+/g," ").trim().length,' +
+    'nodes:document.querySelectorAll("*").length,' +
+    'ready_state:document.readyState,' +
+    // 渲染口径的三个数：布局视口宽高 + 设备像素比。它们是"窗口几何 vs 实际渲染"
+    // 对不上的唯一证据 —— 视图 bounds 1300 而 innerWidth 325，说明页面被按 1/4
+    // 缩放渲染（2026-10-25 用户截图那种"内容缩在左上角"就属于这一类）。
+    'iw:window.innerWidth,ih:window.innerHeight,dpr:window.devicePixelRatio,' +
+    'url:location.href});})()';
+
+  /**
+   * 看一眼这个 tab 现在到底画出来了没有（只读，不改任何东西）。
+   *
+   * 两个数据源，缺一不可：
+   *   1. 位图 —— webContents.capturePage()，走 view 自己的 surface，和用户截图同源。
+   *      缩到 240px 宽再统计：判"是不是白"不需要细节，缩图把统计开销从 ~3.5M 像素
+   *      降到 ~5 万，单次自检从几十毫秒降到个位数。
+   *   2. DOM 事实 —— 有文字/有节点却纯白，才是缺陷；本来就空的页纯白是正确的。
+   *
+   * @returns {Promise<{ok:boolean, tab:number, blank:boolean, verdict:string,
+   *   reason:string, white_ratio?:number, unique?:number, dom?:object,
+   *   bounds?:object, layout_ok?:boolean, ms?:number, error?:string}>}
+   */
+  async paintCheck(tabId) {
+    const tid = tabId !== undefined ? tabId : this.activeTab;
+    const view = this._getView(tid);
+    if (!view) return { ok: false, error: 'no-such-tab', tab: tid };
+    const wc = view.webContents;
+    if (!wc || wc.isDestroyed()) return { ok: false, error: 'tab-destroyed', tab: tid };
+    const startedAt = Date.now();
+
+    let bounds = null;
+    try { bounds = view.getBounds(); } catch (_) { /* 视图正在销毁 */ }
+
+    // 布局是否占了该占的地方。压在 0 高/0 宽上时页面"白"不是内容问题，
+    // 是没人给它地方画 —— 这两种在截图上长得一样，必须靠几何量分开。
+    let expected = null;
+    let layoutOk = null;
+    try {
+      const cb = this.window.getContentBounds();
+      expected = {
+        width: cb.width,
+        height: Math.max(0, cb.height - config.tabBarHeight - (this._bottomInset || 0)),
+      };
+      if (bounds) {
+        layoutOk = bounds.width >= expected.width - 2 && Math.abs(bounds.height - expected.height) <= 2;
+      }
+    } catch (_) { /* 窗口已销毁 */ }
+
+    let dom = { text_len: 0, nodes: 0, ready_state: '' };
+    try {
+      const raw = await withDeadline(this.evaluate(PageManager.PAINT_DOM_JS, tid), 2000, 'paint_dom');
+      const s = (raw && typeof raw === 'object' && 'value' in raw) ? raw.value : raw;
+      const parsed = typeof s === 'string' ? JSON.parse(s) : null;
+      if (parsed) dom = parsed;
+    } catch (_) {
+      // 读不到 DOM 事实（渲染器卡住/正在崩溃）。继续往下走：宁可只用位图判，
+      // 也不要因为"诊断都失败了"就跳过诊断本身。
+    }
+
+    let stats = null;
+    let frameError = null;
+    try {
+      // 位图来源优先走 CDP（和 ui.screenshot 同一条路），而不是
+      // webContents.capturePage()。实测（2026-10-25，e2e/paint 与真机）：
+      // capturePage 对**被其它窗口盖住**的窗口返回空图（isEmpty()===true），
+      // 而"窗口被盖住"恰恰是本产品最常见的状态（不抢焦点原则）。用 capturePage
+      // 就等于在最需要观测的场景下失明 —— 判出来是 no-frame，什么都没看见。
+      // CDP 的 Page.captureScreenshot 走渲染器自己的 surface，被遮挡也拿得到。
+      //
+      // clip.scale=0.25：判"是不是白的"不需要细节，缩到 1/4 后像素数从 350 万
+      // 降到 22 万，统计从几十毫秒降到几毫秒，而且和用户看到的是同一帧内容。
+      const w = bounds && bounds.width ? Math.max(1, Math.round(bounds.width)) : 0;
+      const h = bounds && bounds.height ? Math.max(1, Math.round(bounds.height)) : 0;
+      let shot = null;
+      if (w && h) {
+        try {
+          this._ensureCdp(tid, view, 'Page');
+          shot = await withDeadline(
+            view.webContents.debugger.sendCommand('Page.captureScreenshot', {
+              format: 'png',
+              fromSurface: true,
+              clip: { x: 0, y: 0, width: w, height: h, scale: 0.25 },
+            }),
+            4000, 'paint_shot'
+          );
+        } catch (_) { /* 落到 capturePage 兜底 */ }
+      }
+      if (shot && shot.data) {
+        const buf = Buffer.from(shot.data, 'base64');
+        const img = nativeImage.createFromBuffer(buf);
+        if (img && !img.isEmpty()) stats = blankPage.statsFromBitmap(img.toBitmap());
+      }
+      if (!stats) {
+        const img = await withDeadline(wc.capturePage(), 4000, 'capturePage');
+        if (img && typeof img.isEmpty === 'function' && !img.isEmpty()) {
+          const small = img.resize({ width: 240 });
+          stats = blankPage.statsFromBitmap(small.toBitmap());
+        }
+      }
+    } catch (e) {
+      frameError = e && e.message ? e.message : String(e);
+    }
+
+    let cls = blankPage.classifyPaint({ stats, dom, bounds });
+    // 渲染口径与视图几何必须相等。不等只有两种原因：用户主动缩放（合法）或
+    // **合成器把旧尺寸的 surface 缩进了新 bounds**（就是"内容缩成左上角一小块"）。
+    // 用 zoomFactor 把两者分开：页面缩放有明确的 zoom 值，surface 脱节时 zoom 仍是 1。
+    let zoom = null;
+    try { zoom = typeof wc.getZoomFactor === 'function' ? wc.getZoomFactor() : null; } catch (_) {}
+    const iw = Number(dom && dom.iw) || 0;
+    if (bounds && bounds.width > 0 && iw > 0 && Math.abs(iw - bounds.width) > 2
+        && (zoom === null || Math.abs(zoom - 1) < 0.01)) {
+      cls = {
+        verdict: 'scale-mismatch',
+        blank: cls.blank,
+        reason: `page lays out at ${iw}px but the view is ${bounds.width}px wide (zoom=${zoom})`
+          + ' — the compositor is drawing a stale surface',
+      };
+    }
+    // 还在"正在打开…"占位页（file:///…/loading.html?url=…）上：真实导航排在建
+    // 垫片之后，还没开始。这时既不是白屏也不是就绪 —— 报 not-ready 才会让调用方
+    // "等一会儿"而不是"这页坏了"。这个状态在 new_tab 回执后约 100–200ms 内可见。
+    const onPlaceholder = dom && dom.url && /\/loading\.html(\?|$)/.test(String(dom.url));
+    const verdict = onPlaceholder ? 'not-ready' : cls.verdict;
+    const reason = onPlaceholder
+      ? 'still on the loading placeholder — the real navigation has not started yet'
+      : cls.reason;
+    const blank = cls.blank;
+    // 观测到的就是最新结论，落进 _paintState —— 否则 list_tabs 报的是"上一轮自动
+    // 自检"的旧结论，和调用方刚刚 paint_check 到的结果自相矛盾。
+    // no-frame 不落（那不是对页面的判断，而是我们没看见）。
+    if (verdict !== 'no-frame') {
+      this._paintState.set(tid, { tab: tid, blank, verdict, reason, dom, at: Date.now(), action: 'none' });
+    }
+    return {
+      ok: true,
+      tab: tid,
+      blank,
+      verdict,
+      reason,
+      ...(stats ? {
+        white_ratio: Math.round(stats.white_ratio * 1000) / 1000,
+        unique: stats.unique,
+        ...(stats.unique_pinned ? { unique_pinned: true } : {}),
+      } : {}),
+      dom,
+      ...(bounds ? { bounds: { width: bounds.width, height: bounds.height } } : {}),
+      ...(expected ? { expected } : {}),
+      ...(layoutOk !== null ? { layout_ok: layoutOk } : {}),
+      ...(frameError ? { frame_error: frameError } : {}),
+      ms: Date.now() - startedAt,
+    };
+  }
+
+  /**
+   * 布局看门狗：活动视图的几何必须等于"内容区"。
+   *
+   * 为什么需要它：窗口尺寸变了而视图没跟上，是**没有任何事件会报**的一类失败 ——
+   * 事件只告诉你"窗口 resize 了"，不告诉你"视图还是旧尺寸"。视图比窗口大时，
+   * 合成器会把那张大 surface 缩进新 bounds，表现就是"页面缩成左上角一小块、
+   * 其余全白"（2026-10-25 用户截图）。此时 DOM/截图全都正常，只有窗口像素不对。
+   *
+   * 所以：每次自检顺手量一下几何，错了就当场纠正并落一条 layout_mismatch ——
+   * 这样下次再出现，error.jsonl 里会有窗口尺寸和视图尺寸的实际数字。
+   */
+  _auditLayout(tabId) {
+    const view = this._getView(tabId);
+    if (!view || !view.webContents || view.webContents.isDestroyed()) return null;
+    let expected;
+    try {
+      const cb = this.window.getContentBounds();
+      expected = {
+        x: 0,
+        y: config.tabBarHeight,
+        width: cb.width,
+        height: Math.max(0, cb.height - config.tabBarHeight - (this._bottomInset || 0)),
+      };
+    } catch (_) { return null; }
+    let actual;
+    try { actual = view.getBounds(); } catch (_) { return null; }
+    const bad = actual.width < expected.width - 2
+      || Math.abs(actual.height - expected.height) > 2
+      || actual.x !== expected.x
+      || actual.y !== expected.y;
+    if (!bad) return { ok: true, expected, actual };
+    try {
+      this._layoutView(view);
+      view.webContents.invalidate();
+    } catch (_) { /* 视图正在销毁 */ }
+    const info = { tab: tabId, expected, actual };
+    recordError('layout_mismatch', info);
+    this._broadcast('layout_mismatch', info);
+    return { ok: false, expected, actual, fixed: true };
+  }
+
+  /**
+   * 排一次自检。合并连发的导航事件；只对**活动** tab 做 —— 后台 tab 不在屏幕上，
+   * 它"白不白"没有用户可见的后果，为它反复 capturePage 只是白烧 CPU。
+   */
+  _schedulePaintAudit(tabId, delay = 450) {
+    if (!this._paintAuditEnabled) return;
+    if (tabId !== this.activeTab) return;
+    const prev = this._paintTimers.get(tabId);
+    if (prev) clearTimeout(prev);
+    const t = setTimeout(() => {
+      this._paintTimers.delete(tabId);
+      this._auditPaint(tabId).catch(() => {});
+    }, delay);
+    if (t && typeof t.unref === 'function') t.unref();
+    this._paintTimers.set(tabId, t);
+  }
+
+  /**
+   * 自检入口。合并并发调用：**同一 tab 同时只跑一轮**，后来的调用者拿到正在跑的那一轮。
+   *
+   * 为什么不是"发现已在跑就返回 null"：自动自检（did-finish-load 后 450ms）和
+   * 调用方的 ui.paint_check{heal:true} 很容易撞在一起，返回 null 会让调用方
+   * 拿到一个"什么都没有"的结论，然后自己猜。共享同一个 Promise 才是对的。
+   */
+  async _auditPaint(tabId) {
+    if (!this._paintAuditEnabled) return null;
+    const inflight = this._paintAuditInflight.get(tabId);
+    if (inflight) return inflight;
+    let p;
+    p = this._auditPaintNow(tabId).finally(() => {
+      if (this._paintAuditInflight.get(tabId) === p) this._paintAuditInflight.delete(tabId);
+    });
+    this._paintAuditInflight.set(tabId, p);
+    return p;
+  }
+
+  /**
+   * 自检 + 按阶梯自救（真正的执行体，递归时直接调它，避免绕回合并逻辑死等自己）。
+   *
+   * 阶梯（见 blank_page.decidePaintAction）：repaint → reload → give-up。
+   * 有上限是硬要求：CSS 自己把文字刷成白色的页面，reload 一万次也还是白，
+   * 而无限重试会变成一个看不见的死循环（CPU 烧着、页面反复重载、用户看到的仍是白屏，
+   * 而且没有任何地方说过"我试过了、没用"）。
+   */
+  async _auditPaintNow(tabId) {
+    {
+      // 先量几何再量画面：视图没跟上窗口时，像素判定的意义有限（看到的是一张
+      // 被缩放的旧 surface），而且这个错误必须先修，否则后面的重画都白做。
+      this._auditLayout(tabId);
+      const res = await this.paintCheck(tabId);
+      if (!res.ok) return res;
+      const steps = this._paintSteps.get(tabId) || 0;
+      const action = blankPage.decidePaintAction({ verdict: res.verdict, steps });
+      const rec = { ...res, action, at: Date.now() };
+      this._paintState.set(tabId, rec);
+
+      if (action === 'none') return rec;
+
+      const view = this._getView(tabId);
+      if (!view || !view.webContents || view.webContents.isDestroyed()) return rec;
+      if (action === 'repaint') {
+        this._paintSteps.set(tabId, steps + 1);
+        this._forceRepaint(view);
+        await new Promise((r) => { const t = setTimeout(r, 320); if (t.unref) t.unref(); });
+        return this._auditPaintNow(tabId);
+      }
+      if (action === 'reload') {
+        this._paintSteps.set(tabId, steps + 1);
+        this._paintSelfReload.add(tabId);
+        try {
+          view.webContents.reload();
+        } catch (e) {
+          this._paintSelfReload.delete(tabId);
+          return rec;
+        }
+        await this._waitFinishLoad(tabId, 10000);
+        await new Promise((r) => { const t = setTimeout(r, 450); if (t.unref) t.unref(); });
+        return this._auditPaintNow(tabId);
+      }
+      // give-up：救不动就如实上报。这是唯一能让人知道"白屏是真的、重试没用"的地方。
+      const info = {
+        tab: tabId,
+        url: res.dom && res.dom.url,
+        verdict: res.verdict,
+        reason: res.reason,
+        white_ratio: res.white_ratio,
+        unique: res.unique,
+        attempts: steps,
+      };
+      recordError('paint_blank', info);
+      this._broadcast('paint_blank', info);
+      return rec;
+    }
+  }
+
+  /** 等到 did-finish-load（或超时）。只用于自救后的确认，不影响导航本身。 */
+  _waitFinishLoad(tabId, timeoutMs) {
+    const view = this._getView(tabId);
+    if (!view || !view.webContents || view.webContents.isDestroyed()) return Promise.resolve(false);
+    const wc = view.webContents;
+    return new Promise((resolve) => {
+      let done = false;
+      const finish = (ok) => {
+        if (done) return;
+        done = true;
+        try { wc.removeListener('did-finish-load', onLoad); } catch (_) {}
+        clearTimeout(timer);
+        resolve(ok);
+      };
+      const onLoad = () => finish(true);
+      wc.once('did-finish-load', onLoad);
+      const timer = setTimeout(() => finish(false), timeoutMs);
+      if (timer.unref) timer.unref();
+    });
+  }
+
+  /**
+   * 给一个 tab 挂上自检钩子（幂等）。
+   *
+   * 为什么是 did-finish-load + dom-ready 两条：did-finish-load 在长轮询/SPA 上可能
+   * 迟迟不来（那正是首屏白最久的时候），dom-ready 是更早的第二落点。两次都被
+   * _schedulePaintAudit 按 tab 合并，不会真的跑两遍。
+   */
+  _attachPaintHook(tabId, view) {
+    if (!this._paintAuditEnabled) return;
+    if (!view || !view.webContents || view.webContents.isDestroyed()) return;
+    if (!this._paintAuditHooked) this._paintAuditHooked = new WeakSet();
+    if (this._paintAuditHooked.has(view)) return;
+    this._paintAuditHooked.add(view);
+    const onLoad = () => {
+      // 自己触发的 reload 不清零补救步数 —— 否则 "reload 后还是白" 会重新从
+      // repaint 开始，变成"重载 → 再重载"的无限循环。
+      if (this._paintSelfReload.has(tabId)) {
+        this._paintSelfReload.delete(tabId);
+      } else {
+        this._paintSteps.set(tabId, 0);
+        this._paintState.delete(tabId);
+      }
+      this._schedulePaintAudit(tabId, 450);
+    };
+    view.webContents.on('did-finish-load', onLoad);
+    view.webContents.on('dom-ready', () => this._schedulePaintAudit(tabId, 900));
+  }
+
+  /**
+   * 渲染进程崩了 → 自己重载一次。
+   *
+   * 以前这里只有 console.error：进程崩溃后 Chromium 给窗口留一块**白**的
+   * surface，事件不再来，DOM 读不到，用户看到的是永久白屏，而日志里只有一行。
+   * reload 之后 Chromium 会重新拉一个渲染进程，页面照常回来。
+   * 15 秒内只救一次：崩了又崩说明是死循环，重载只会让人反复看着它闪。
+   */
+  _attachCrashRecovery(tabId, view) {
+    if (!view || !view.webContents || view.webContents.isDestroyed()) return;
+    if (!this._crashHooked) this._crashHooked = new WeakSet();
+    if (this._crashHooked.has(view)) return;
+    this._crashHooked.add(view);
+    view.webContents.on('render-process-gone', (_e, details) => {
+      const reason = (details && details.reason) || 'unknown';
+      let url = null;
+      try { url = view.webContents.getURL(); } catch (_) {}
+      recordError('render_process_gone', { tab: tabId, reason, exit_code: details && details.exitCode, url });
+      if (reason === 'clean-exit') return;
+      const last = this._crashReloadAt.get(tabId) || 0;
+      if (Date.now() - last < 15000) return;
+      this._crashReloadAt.set(tabId, Date.now());
+      try {
+        view.webContents.reload();
+        this._broadcast('tab_recovered', { tab: tabId, reason, action: 'reload', url });
+      } catch (_) { /* 视图已销毁 */ }
+    });
+  }
+
   /**
    * Repaint on demand (ui.repaint). The "page shows stale content" case has
    * no observable state to detect it from — the DOM and evaluate already report
@@ -3657,6 +4089,30 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
     // 同理，下载记录只对"这个 tab 还在"有意义。注意**只清记录，不删文件** ——
     // 文件是用户要的东西，删文件是另一个决定，不能藏在关 tab 里。
     this.downloadMonitor.clearTab(tabId);
+    // 白屏自检 / 崩溃自救的 per-tab 状态。不清的话 tabId 会被新 tab 复用，
+    // 新 tab 一开就继承上一任的"已经救过两步"，白屏时直接被判定成 give-up。
+    this._paintState.delete(tabId);
+    this._paintSteps.delete(tabId);
+    this._paintSelfReload.delete(tabId);
+    this._crashReloadAt.delete(tabId);
+    const pt = this._paintTimers.get(tabId);
+    if (pt) { clearTimeout(pt); this._paintTimers.delete(tabId); }
+  }
+
+  /** 白屏相关的"值得报出去的结论"；正常页面返回 null（listTabs 不带这个字段）。 */
+  _paintProblem(tabId) {
+    const p = this._paintState.get(tabId);
+    if (!p) return null;
+    // 这四种都不是"用户可见的白屏"，不该出现在 list_tabs 里：
+    //   ok / empty-legit 是正常，not-ready 是还没加载完，no-frame 是**我们自己
+    //   没看到画面**（视图被销毁等）—— 把诊断失败说成页面故障，是最坏的一种谎。
+    if (p.verdict === 'ok' || p.verdict === 'empty-legit' || p.verdict === 'not-ready' || p.verdict === 'no-frame') return null;
+    return {
+      blank: !!p.blank,
+      verdict: p.verdict,
+      reason: p.reason,
+      action: p.action,
+    };
   }
 
   listTabs() {
@@ -3676,6 +4132,9 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
         // 只有 manual 策略下才会长期存在。auto 模式下对话框在打开的瞬间就被
         // 应答了，所以正常情况这个字段不出现 —— 出现即意味着"有人需要点它"。
         ...(this._openDialogs.has(id) ? { dialog: this._openDialogs.get(id) } : {}),
+        // 白屏只在与众不同时出现：正常页面不带这个字段（省 token，也不给
+        // 调用方制造"每次都要判"的噪音）。出现即"这一页没画出来"。
+        ...(this._paintProblem(id) ? { paint: this._paintProblem(id) } : {}),
       });
     }
     return list;
@@ -3742,6 +4201,50 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
     } catch (e) { /* debugger 未 attach / 页面已销毁 —— 忽略 */ }
   }
 
+  /**
+   * 窗口尺寸诊断 / 复现入口（ui.window_bounds）。
+   *
+   * 存在的理由：**布局类缺陷此前无法复现也无法回归** —— 没有入口能把窗口改成
+   * 另一个尺寸，于是"窗口放大/缩小/全屏之后视图错位、内容缩成一小块"这类问题
+   * 只能靠人手拖窗口碰运气。读的时候返回窗口 bounds / content bounds / 各视图
+   * 实际 bounds，一眼就能看出"视图没跟上窗口"。
+   *
+   * 不传尺寸时纯读；传了就 setBounds + 立刻重排，再回读实际结果（不做乐观报告）。
+   */
+  windowBounds(next) {
+    const snapshot = () => {
+      const out = { ok: true };
+      try { out.bounds = this.window.getBounds(); } catch (_) { /* 窗口已销毁 */ }
+      try { out.content = this.window.getContentBounds(); } catch (_) { /* 窗口已销毁 */ }
+      const views = {};
+      for (const [id, view] of this.tabs) {
+        try { views[id] = view.getBounds(); } catch (_) { /* 视图已销毁 */ }
+      }
+      out.views = views;
+      return out;
+    };
+    if (!next || typeof next !== 'object') return snapshot();
+    let cur;
+    try { cur = this.window.getBounds(); } catch (e) { return { ok: false, error: 'no-window' }; }
+    const nb = { x: cur.x, y: cur.y, width: cur.width, height: cur.height };
+    for (const k of ['x', 'y', 'width', 'height']) {
+      if (typeof next[k] === 'number' && isFinite(next[k]) && next[k] > 0) nb[k] = Math.round(next[k]);
+    }
+    try {
+      this.window.setBounds(nb);
+    } catch (e) {
+      return { ok: false, error: 'setBounds failed: ' + (e && e.message), ...snapshot() };
+    }
+    // 尺寸变了就必须让每个视图重新栅格化：setBounds 只改几何，surface 可能还是
+    // 旧尺寸的 —— 那正是"内容缩成左上角一小块、其余全白"的成因（见 SPEC 白屏一节）。
+    const view = this._getView(this.activeTab);
+    if (view) {
+      this._layoutView(view);
+      try { view.webContents.invalidate(); } catch (_) { /* 已销毁 */ }
+    }
+    return snapshot();
+  }
+
   _layoutView(view) {
     const bounds = this.window.getContentBounds();
     const inset = this._bottomInset || 0;

package/src/main/ws_server.js

@@ -185,6 +185,31 @@ export function startWSServer(pageManager, port = config.wsPort, onQuit = null)
             send({ jsonrpc: '2.0', id, result: r });
             break;
           }
+          case 'ui.paint_check': {
+            // "这一页到底画出来了没有"—— 只读，不改任何东西。
+            //
+            // 为什么必须有这个入口：白屏是唯一一种"did-finish-load 到了、
+            // readyState=complete、evaluate 读得到文字、CDP 截图也有内容，
+            // 但屏幕上就是纯白"的失败形态。所有既有观测口在这里集体失明，
+            // 于是用户说"白的"、工具说"好的"，谁也拿不出证据。
+            // 判定口径见 shared/blank_page.cjs。
+            //
+            // heal:true 时才走自救阶梯（repaint → reload → 给结论并上报），
+            // 默认只观测 —— 调用方问"是不是白的"时，不该顺手把页面重载掉。
+            const tid = params.tab !== undefined ? params.tab : pageManager.activeTab;
+            const r = params.heal ? await pageManager._auditPaint(tid) : await pageManager.paintCheck(tid);
+            send({ jsonrpc: '2.0', id, result: r });
+            break;
+          }
+          case 'ui.window_bounds': {
+            // 读：窗口 bounds / content bounds / 每个视图实际 bounds（一眼看出视图有没有
+            // 跟上窗口）。写：setBounds + 立刻重排 + invalidate，然后回读实际结果。
+            // 存在的理由：布局类缺陷（窗口缩放/全屏后内容缩成左上角一小块）此前无法
+            // 复现也无法回归 —— 没有任何入口能改窗口尺寸。
+            const r = pageManager.windowBounds(params && params.set ? params.set : null);
+            send({ jsonrpc: '2.0', id, result: r });
+            break;
+          }
           case 'ui.snapshot': {
             const r = await pageManager.snapshot({ js: params.js, label: params.label, tab: tabId });
             send({ jsonrpc: '2.0', id, result: r });

package/src/shared/blank_page.cjs

@@ -0,0 +1,151 @@
+// shared/blank_page.cjs — "这一页到底画出来没有"的判定口径（纯函数）。
+//
+// 事故（2026-10-25，用户报"打开了百度有时候是纯白屏"）：
+//   页面加载事件全都到了（did-finish-load / readyState=complete）、DOM 里有内容、
+//   agent 通过 ui.evaluate 也能读到文字，但**用户看到的那块区域是纯白的**。
+//   这类白屏此前没有任何检测手段：
+//     - did-fail-load 只覆盖"网络失败"，不覆盖"画布是空的"；
+//     - chrome-error:// 的错误页覆盖"连接失败"，也不覆盖这个；
+//     - capturePage / CDP 截图**不测**它 —— 它们走 view 自己的 surface，
+//       视图内部画得好好的，白的是窗口那一层。
+//   结果就是"用户说白屏，工具说一切正常"，双方都拿不出证据。
+//
+// 这份模块只做一件事：给一张**位图**和一份**DOM 事实**，回答
+//   "它是不是白的？白是因为这页本来就空，还是因为它该有内容却没画出来？"
+// 判定与"怎么修"分开：修有副作用（reload 会丢掉页面里的临时状态），
+// 所以由 decidePaintAction 单独决定，且**有上限**（见下）。
+//
+// 为什么白度 + 唯一色两个指标都要：
+//   - 只用白度：百度首页本身 90%+ 是白的，会天天误报；
+//   - 只用唯一色：深色加载页只有 400 多种颜色，也会误报成"空白"。
+//   两个一起看才分得清"内容页（白底但有正文/图标 → 唯一色几千）"和
+//   "真的什么都没画（纯白 → 唯一色个位数）"。
+
+'use strict';
+
+// 位图格式：Electron 的 nativeImage.toBitmap() 给的是 BGRA（4 字节/像素，
+// 从上到下、无 padding）。这里不假设调用方用什么解码，只要求同一约定。
+const BPP = 4;
+
+// 阈值定了两个数，都有实测依据（2026-10-25，1280x800 窗口、2x 屏）：
+//   - 真实页面：百度首页 90–93% 白 / 3.9k–6.1k 唯一色；
+//     纯白故障帧：99–100% 白 / 3–25 唯一色（抗锯齿边缘也会贡献几个色阶）；
+//   - 深色页面（我们的 loading.html）：0% 白 / 400+ 唯一色。
+// 取 white ≥ 99% 且 unique ≤ 32：两侧都留了余量，既不会把"白底文章页"算进来
+// （它的唯一色必然上千），也不会因为一个圆角边框的四个渐变色就漏掉真白屏。
+const WHITE_MIN_RATIO = 0.99;
+const WHITE_PIXEL = 250;   // 单通道 ≥ 250 算"白"（250 而不是 255：留点压缩/缩放余量）
+const UNIQUE_MAX = 32;
+
+/**
+ * 统计位图的白度与唯一色数。
+ * @param {Buffer|Uint8Array} bitmap BGRA 位图
+ * @returns {{total:number, white:number, white_ratio:number, unique:number}}
+ */
+function statsFromBitmap(bitmap) {
+  if (!bitmap || !bitmap.length) {
+    return { total: 0, white: 0, white_ratio: 0, unique: 0 };
+  }
+  const total = Math.floor(bitmap.length / BPP);
+  let white = 0;
+  // 唯一色用 Set 存打包后的 24 位整数。纯白图只有 1–3 个元素，正常页面几千个。
+  // 数过 UNIQUE_MAX 就不再往 Set 里塞（内存有界），但白色像素要继续数到最后一个 ——
+  // 提前 break 会让 white_ratio 变成"扫过的部分"的比例，回执里的数字就成了假话。
+  const seen = new Set();
+  let overflow = false;
+  for (let i = 0; i + 3 < bitmap.length; i += BPP) {
+    const b = bitmap[i], g = bitmap[i + 1], r = bitmap[i + 2];
+    if (r >= WHITE_PIXEL && g >= WHITE_PIXEL && b >= WHITE_PIXEL) white++;
+    if (!overflow) {
+      seen.add((r << 16) | (g << 8) | b);
+      if (seen.size > UNIQUE_MAX) overflow = true;
+    }
+  }
+  return {
+    total,
+    white,
+    white_ratio: total ? white / total : 0,
+    // pinned = "颜色数已超过上限，这里只是下限"。回执里要如实标注，
+    // 否则一个信息丰富的页面会被显示成"33 种颜色"。
+    unique: seen.size,
+    unique_pinned: overflow,
+  };
+}
+
+/**
+ * 判定一帧画面。
+ *
+ * @param {object} p
+ * @param {{total:number,white:number,white_ratio:number,unique:number}} p.stats
+ * @param {{text_len:number, nodes:number, ready_state:string}} p.dom 页面自述的事实
+ * @param {{width:number,height:number}} [p.bounds] 视图当前尺寸
+ * @returns {{verdict:string, blank:boolean, reason:string}}
+ *
+ * verdict：
+ *   ok               有内容（正常）
+ *   empty-legit      这页本来就是空的（about:blank / 空文档），白是正确结果
+ *   not-ready        页面还没到 interactive/complete，白是暂时的，等它
+ *   collapsed        视图本身被压成 0 高/0 宽 —— 不是没画，是没地方画
+ *   blank-with-text  DOM 里有文字，但屏幕上纯白 —— **真白屏**
+ *   blank-with-dom   DOM 有几十个节点却纯白 —— **真白屏**（内容层失败）
+ *   scale-mismatch   页面按 A 宽排版、视图只有 B 宽（合成器画了一张陈旧尺寸的
+ *                    surface）—— 表现为"内容缩在左上角，其余全白"
+ *   no-frame         拿不到位图（视图不可见/被销毁），无法判定
+ */
+function classifyPaint({ stats, dom, bounds } = {}) {
+  const d = dom || {};
+  const textLen = Number(d.text_len) || 0;
+  const nodes = Number(d.nodes) || 0;
+  const ready = String(d.ready_state || '');
+
+  if (bounds && (Number(bounds.width) <= 0 || Number(bounds.height) <= 0)) {
+    return { verdict: 'collapsed', blank: true, reason: `view is ${bounds.width}x${bounds.height} — nothing to paint into` };
+  }
+  if (!stats || !stats.total) {
+    return { verdict: 'no-frame', blank: false, reason: 'no bitmap (view not visible or destroyed)' };
+  }
+  const isWhite = stats.white_ratio >= WHITE_MIN_RATIO && stats.unique <= UNIQUE_MAX;
+  const colourDesc = `${stats.unique}${stats.unique_pinned ? '+' : ''} colours`;
+  if (ready && ready !== 'interactive' && ready !== 'complete') {
+    // 还没就绪时"白"是暂时的，不是缺陷 —— blank 字段仍要如实反映画面。
+    return { verdict: 'not-ready', blank: isWhite, reason: `document.readyState = ${ready}` };
+  }
+  if (!isWhite) {
+    return { verdict: 'ok', blank: false, reason: `${Math.round(stats.white_ratio * 100)}% white, ${colourDesc}` };
+  }
+  // 到这里：屏幕上确实是纯白。白得对不对，只能问 DOM。
+  if (textLen === 0 && nodes <= 2) {
+    return { verdict: 'empty-legit', blank: false, reason: 'empty document — white is the correct result' };
+  }
+  if (textLen > 0) {
+    return { verdict: 'blank-with-text', blank: true, reason: `${textLen} chars of text in the DOM but the screen is white` };
+  }
+  return { verdict: 'blank-with-dom', blank: true, reason: `${nodes} DOM nodes but the screen is white` };
+}
+
+/**
+ * 白屏了该怎么救 —— 阶梯，且有上限。
+ *
+ * 为什么要有上限：救不动的时候（比如页面 CSS 自己把文字刷成白色），reload 一百次
+ * 也还是白。无上限重试会变成一个看不见的循环：CPU 烧着、页面反复重载、
+ * 用户看到的仍是白屏，而且没有任何地方说过"我试过了、没用"。
+ *
+ * @param {{verdict:string, steps:number}} p steps = 已执行过的补救次数
+ * @returns {'none'|'repaint'|'reload'|'give-up'}
+ */
+function decidePaintAction({ verdict, steps = 0 } = {}) {
+  // ok / empty-legit / not-ready / no-frame 都不该动。not-ready 尤其重要：
+  // 首屏那一刻本来就可能是白的，这时候 reload 等于把正在下载的页面打断。
+  if (verdict === 'ok' || verdict === 'empty-legit' || verdict === 'not-ready' || verdict === 'no-frame') {
+    return 'none';
+  }
+  // scale-mismatch 和 blank-* 走同一个阶梯：先重画，再重载，最后如实上报。
+  if (steps <= 0) return 'repaint';   // 第一步：remove+add 逼合成器重画（代价最小、不丢状态）
+  if (steps === 1) return 'reload';   // 第二步：重载（会丢页面临时状态，所以排在重画之后）
+  return 'give-up';                   // 第三步：如实上报，不再折腾
+}
+
+/** 位图统计的阈值（供测试与回执引用，避免两处写死）。 */
+const THRESHOLDS = { WHITE_MIN_RATIO, WHITE_PIXEL, UNIQUE_MAX };
+
+module.exports = { statsFromBitmap, classifyPaint, decidePaintAction, THRESHOLDS };

package/src/shared/protocol.js

@@ -65,6 +65,12 @@ export const VALID_METHODS = [
   'ui.screenshot',
   'ui.navigate',
   'ui.repaint',
+  // "这一页到底画出来了没有"—— 只读观测，heal:true 才走自救阶梯。
+  // 与 ui.repaint 的区别：repaint 是"外面的人说窗口不对，重画一次"；
+  // paint_check 是"工具自己看一眼，白的话按阶梯救，救不动就如实上报"。
+  'ui.paint_check',
+  // 窗口/视图几何（读 + 改）。布局类缺陷需要它才能复现与回归。
+  'ui.window_bounds',
   'ui.snapshot',
   'ui.diff',
   'ui.capabilities',

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 = '2.1.12';
+export const VERSION = '2.1.14';