@glittering0717/ai-browser 2.1.13 → 2.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittering0717/ai-browser",
-  "version": "2.1.13",
+  "version": "2.1.15",
   "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": {
@@ -83,7 +83,8 @@
     "dialog": "node e2e/dialog_ws.cjs",
     "verify:app": "node e2e/shipped_ws.cjs",
     "wrapper": "node e2e/wrapper_ws.cjs",
-    "paint": "node e2e/paint_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';
@@ -488,6 +488,8 @@ function createWindow() {
   mainWindow.on('resize', () => {
     layoutWithBanner();
   });
+  // 注：resize 的重绘（repaintActiveSoon）在下面"几何变化"一段里统一绑定 ——
+  // 那里能看到 repaintActive 的定义。
 
   // === Window becoming visible again → force a compositor repaint ===
   //
@@ -503,9 +505,45 @@ 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 尺寸"脱节，是最常见的来源。
+  // 几何变化后不能只重画：还要确认"渲染视口真的跟上了新尺寸"（见 afterGeometryChange
+  // 的注释 —— 视图 800 而页面还按 1280 排版，就是用户看到的"大一下小一下"）。
+  const afterGeometry = () => { try { pageManager.afterGeometryChange(); } catch (e) {} };
+  let geomTimer = null;
+  const afterGeometrySoon = (ms = 150) => {
+    if (geomTimer) clearTimeout(geomTimer);
+    geomTimer = setTimeout(afterGeometry, ms);
+  };
+  mainWindow.on('resize', () => afterGeometrySoon(150));
+  mainWindow.on('enter-full-screen', () => { layoutWithBanner(); afterGeometrySoon(120); });
+  mainWindow.on('leave-full-screen', () => { layoutWithBanner(); afterGeometrySoon(120); });
+  const onDisplayChange = () => { try { layoutWithBanner(); } catch (e) {} afterGeometrySoon(80); };
+  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(); afterGeometrySoon(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

@@ -216,6 +216,10 @@ class PageManager {
     this._openDialogs = new Map();
     this._axDiffCache = new Map();  // tabId -> lite interactive snapshot (get_tree {mode:'diff'})
     this._repaintTimers = new Map();// tabId -> 正在排队/已调度的重绘（合并同一批导航事件）
+    // 重绘计数：soft = 只 invalidate；hard = 额外 1px 微调（会重排两次，肉眼可见）。
+    // 高频路径（导航完成/窗口焦点）只许走 soft —— 这条要被回归钉住。
+    this._repaintCount = 0;
+    this._hardRepaintCount = 0;
     // === 白屏自检（paint audit）===
     // tabId -> {verdict, blank, white_ratio, unique, action, at, url}：最近一次自检的结论。
     // 为什么必须有它：白屏是唯一一种"所有事件都成功、DOM 也正常、但用户看到的是空"的
@@ -3571,32 +3575,83 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
    * (only the active view is normally attached, so re-adding an inactive one
    * would show it — guard by re-asserting the active view afterwards).
    */
-  _forceRepaint(view) {
+  /**
+   * 窗口几何变过之后调一次：重排 → 软重绘 → 160ms 后确认渲染视口真的跟上了。
+   *
+   * 为什么不能只 setBounds：实测（e2e/layout_ws 的 G2，2026-10-25）窗口从
+   * 1280 缩到 800 之后，视图 bounds 已经是 800，但页面 `innerWidth` 还是 1280 ——
+   * 也就是渲染器没接到/没应用这次尺寸变化。此时合成器会把 1280 宽的内容画进
+   * 800 的框里，内容整体缩小或错位；等它某一刻突然追上，就是用户说的
+   * "一闪一闪、大一下小一下"。
+   * 确认的方式和判定口径一致：innerWidth 必须等于视图宽度。不等就做一次 hard
+   * 重绘（1px 微调会强制 Chromium 重算 surface 与布局）—— 这时代价是值得的，
+   * 因为画面本来就是错的。
+   */
+  afterGeometryChange() {
+    const tid = this.activeTab;
+    const view = this._getView(tid);
+    if (!view || !view.webContents || view.webContents.isDestroyed()) return;
+    try { this._layoutView(view); } catch (_) { return; }
+    this._forceRepaint(view);           // soft：不可见
+    const timer = setTimeout(async () => {
+      try {
+        const v = this._getView(tid);
+        if (!v || !v.webContents || v.webContents.isDestroyed()) return;
+        const b = v.getBounds();
+        const raw = await withDeadline(this.evaluate('(function(){return String(window.innerWidth);})()', tid), 1500, 'geom_iw');
+        const iw = Number((raw && typeof raw === 'object' && 'value' in raw) ? raw.value : raw) || 0;
+        if (iw > 0 && b.width > 0 && Math.abs(iw - b.width) > 2) {
+          recordError('layout_mismatch', {
+            tab: tid, phase: 'after-resize',
+            expected: { width: b.width }, actual: { innerWidth: iw },
+          });
+          this._forceRepaint(v, { hard: true });
+        }
+      } catch (_) { /* renderer 正在忙/已销毁：下一次 resize 会再来一次 */ }
+    }, 160);
+    if (timer.unref) timer.unref();
+  }
+
+  /**
+   * 让合成器重新画一次，分两档。
+   *
+   * soft（默认）：只 webContents.invalidate() —— 不改几何、不重排、不可见。
+   * hard：额外做 1px 微调（width+1 再 width），因为**只有尺寸变化才会让 surface
+   *       重新栅格化**（尺寸不变时 setBounds 被 Chromium 直接忽略）。
+   *
+   * 为什么要分档（2026-10-25 用户报"一闪一闪、大一下小一下"）：
+   * 1px 微调必然触发两次重排，文字会肉眼可见地跳一下；再叠 removeBrowserView /
+   * addBrowserView 还会闪一帧白。把这套放在"每次导航完成 / 每次窗口焦点变化"
+   * 这种高频路径上，就变成了用户看到的抽搐。
+   * 所以高频路径一律 soft；只有"确认 surface 尺寸脱节"（scale-mismatch、白屏阶梯）
+   * 才付 hard 的代价。
+   *
+   * 也不再 remove/add：那是过去没有 invalidate 时的唯一手段，代价是闪一帧白，
+   * 而现在 invalidate 覆盖了它的作用。
+   */
+  _forceRepaint(view, opts = {}) {
+    const hard = opts && opts.hard === true;
     const tabId = this._tabIdOfView(view);
-    const wasActive = tabId === this.activeTab;
+    if (tabId === null) return false;
+    const wc = view.webContents;
+    if (!wc || (typeof wc.isDestroyed === 'function' && wc.isDestroyed())) return false;
     try {
-      this.window.removeBrowserView(view);
-      this.window.addBrowserView(view);
-      this._layoutView(view);
-    } 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.
-    // "The window looks stale" has no other symptom to check, and a caller
-    // cannot poll for it — polling calls repaint itself, which *consumes* the
-    // queued debounce timer and destroys the very evidence being looked for.
-    this._repaintCount = (this._repaintCount || 0) + 1;
-    // If we just re-added an inactive view it is now on top of the stack —
-    // put the real active view back so the user sees the tab they selected.
-    if (!wasActive) {
-      const active = this._getView(this.activeTab);
-      if (active) {
-        try {
-          this.window.removeBrowserView(view);
-          this.window.addBrowserView(active);
-          this._layoutView(active);
-        } catch(e) {}
-      }
+      wc.invalidate();
+    } catch (e) {
+      return false;
     }
+    // Cumulative counter, reported by ui.repaint / ui.window_bounds. Not just a
+    // debug aid: it is the only externally observable proof that a repaint
+    // actually happened, and (for hard) that no geometry nudge leaked into a
+    // hot path.
+    this._repaintCount = (this._repaintCount || 0) + 1;
+    if (!hard) return true;
+    try {
+      const b = view.getBounds();
+      view.setBounds({ ...b, width: b.width + 1 });
+      view.setBounds(b);
+      this._hardRepaintCount = (this._hardRepaintCount || 0) + 1;
+    } catch (e2) { /* 视图正在销毁 */ }
     return true;
   }
 
@@ -3624,6 +3679,10 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
     '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});})()';
 
   /**
@@ -3720,7 +3779,41 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
       frameError = e && e.message ? e.message : String(e);
     }
 
-    const cls = blankPage.classifyPaint({ stats, dom, bounds });
+    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 (_) {}
+    let iw = Number(dom && dom.iw) || 0;
+    let mismatched = bounds && bounds.width > 0 && iw > 0 && Math.abs(iw - bounds.width) > 2
+      && (zoom === null || Math.abs(zoom - 1) < 0.01);
+    if (mismatched) {
+      // 刚 resize 完的那一两帧里 innerWidth 会短暂滞后（布局还没跟上新尺寸），
+      // 直接判 scale-mismatch 就会误触发 hard 重绘 —— 而 hard 会重排两次，
+      // 用户看到的就是"大一下小一下"（2026-10-25 真机就这么抖的）。
+      // 所以等 120ms 再读一次：还是不一致才算 surface 真的脱节。
+      await new Promise((r) => { const t = setTimeout(r, 120); if (t.unref) t.unref(); });
+      let iw2 = 0;
+      try {
+        const raw2 = await withDeadline(this.evaluate(PageManager.PAINT_DOM_JS, tid), 2000, 'paint_dom2');
+        const s2 = (raw2 && typeof raw2 === 'object' && 'value' in raw2) ? raw2.value : raw2;
+        const parsed2 = typeof s2 === 'string' ? JSON.parse(s2) : null;
+        iw2 = Number(parsed2 && parsed2.iw) || 0;
+      } catch (_) { /* 读不到就按原判断 */ }
+      if (iw2 > 0) {
+        if (Math.abs(iw2 - bounds.width) <= 2) mismatched = false;
+        else iw = iw2;
+      }
+    }
+    if (mismatched) {
+      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 内可见。
@@ -3756,6 +3849,47 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
     };
   }
 
+  /**
+   * 布局看门狗：活动视图的几何必须等于"内容区"。
+   *
+   * 为什么需要它：窗口尺寸变了而视图没跟上，是**没有任何事件会报**的一类失败 ——
+   * 事件只告诉你"窗口 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。
@@ -3802,6 +3936,9 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
    */
   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;
@@ -3815,7 +3952,9 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
       if (!view || !view.webContents || view.webContents.isDestroyed()) return rec;
       if (action === 'repaint') {
         this._paintSteps.set(tabId, steps + 1);
-        this._forceRepaint(view);
+        // 这里必须 hard：被判成白屏/scale-mismatch 时，surface 很可能就是旧尺寸，
+        // 只 invalidate 不会重新栅格化。用户已经看到坏画面了，1px 重排的代价无所谓。
+        this._forceRepaint(view, { hard: true });
         await new Promise((r) => { const t = setTimeout(r, 320); if (t.unref) t.unref(); });
         return this._auditPaintNow(tabId);
       }
@@ -3933,7 +4072,7 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
    * explicit "I know this window looks wrong, redraw it" call rather than a
    * heuristic.
    */
-  repaint(tabId) {
+  repaint(tabId, opts = {}) {
     const tid = tabId !== undefined && tabId !== null ? tabId : this.activeTab;
     const view = this._getView(tid);
     if (!view) return { ok: false, error: 'no-such-tab', tab: tid };
@@ -3945,7 +4084,7 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
     // to ask, the browser already scheduled one" — i.e. the window was stale
     // for ~120ms and has since caught up on its own.
     if (pending) { clearTimeout(pending); this._repaintTimers.delete(tid); }
-    const ok = this._forceRepaint(view);
+    const ok = this._forceRepaint(view, { hard: opts && opts.hard === true });
     return { ok, tab: tid, was_active: tid === this.activeTab, was_pending: !!pending, repaint_count: this._repaintCount || 0 };
   }
 
@@ -4127,6 +4266,51 @@ 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 (_) { /* 窗口已销毁 */ }
+      out.repaints = { soft: this._repaintCount || 0, hard: this._hardRepaintCount || 0 };
+      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

@@ -181,7 +181,9 @@ export function startWSServer(pageManager, port = config.wsPort, onQuit = null)
             // the DOM tree / evaluate already report the NEW page while the
             // screen shows the OLD one. So the agent's only handle on it is an
             // explicit "this window looks wrong, redraw it".
-            const r = pageManager.repaint(tabId);
+            // hard:true 才做 1px 微调（会让页面重排两次，肉眼可见）。
+            // 默认 soft：只 invalidate —— 高频调用不会把窗口刷成幻灯片。
+            const r = pageManager.repaint(tabId, { hard: params && params.hard === true });
             send({ jsonrpc: '2.0', id, result: r });
             break;
           }
@@ -201,6 +203,15 @@ export function startWSServer(pageManager, port = config.wsPort, onQuit = null)
             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

@@ -88,6 +88,8 @@ function statsFromBitmap(bitmap) {
  *   collapsed        视图本身被压成 0 高/0 宽 —— 不是没画，是没地方画
  *   blank-with-text  DOM 里有文字，但屏幕上纯白 —— **真白屏**
  *   blank-with-dom   DOM 有几十个节点却纯白 —— **真白屏**（内容层失败）
+ *   scale-mismatch   页面按 A 宽排版、视图只有 B 宽（合成器画了一张陈旧尺寸的
+ *                    surface）—— 表现为"内容缩在左上角，其余全白"
  *   no-frame         拿不到位图（视图不可见/被销毁），无法判定
  */
 function classifyPaint({ stats, dom, bounds } = {}) {
@@ -137,6 +139,7 @@ function decidePaintAction({ verdict, steps = 0 } = {}) {
   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';                   // 第三步：如实上报，不再折腾

package/src/shared/protocol.js

@@ -69,6 +69,8 @@ export const VALID_METHODS = [
   // 与 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.13';
+export const VERSION = '2.1.15';