@mrrisega/dsh-remote 0.6.12 → 0.6.14

package/clients/dsh-remote/test/boot-tip.test.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * 镜像页首屏加载提示的契约与行为测试（0.6.14）。
+ *
+ * 用户反馈：「普通用户加载进入镜像页面时等待时间较长，目前等待过程中一直在转圈。
+ *          建议给普通用户增加一个友好的提示（例如提示"正在排队中"）。」
+ *
+ * 首屏为什么慢：镜像页要拉 dsh web 的全部客户端插件（实测 ~14 MB 的一个**不可拆分**聚合请求），
+ * 免费档限速下几十秒起步。官方那个转圈不告诉用户任何事，用户只能反复刷新 —— 反而更慢。
+ *
+ * 这里守四件事：
+ *   ① 提示必须在**页面解析的第一时间**出现（早于所有主机判定 —— 首屏慢的正是判定等不到的时候）；
+ *   ② 分阶段补充说明（8s / 30s）与秒表，让"到底等了多久"可见；
+ *   ③ 官方 UI 就绪后自动撤下；且有 4 分钟兜底 + pagehide/unload 清理，绝不留悬挂定时器；
+ *   ④ 只做提示、不做拦截（pointer-events:none），提示失效也绝不挡住用户操作。
+ *
+ * 用法: node --test test/boot-tip.test.mjs
+ */
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import vm from "node:vm";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SRC = readFileSync(path.join(HERE, "..", "mobile-adapter.mjs"), "utf8");
+const STYLE = SRC.slice(SRC.indexOf("const STYLE = `") + "const STYLE = `".length, SRC.indexOf("`;\n\n/**", SRC.indexOf("const STYLE = `")));
+const SCRIPT_START = SRC.indexOf("const SCRIPT = `(() => {") + "const SCRIPT = `".length;
+const SCRIPT = SRC.slice(SCRIPT_START, SRC.indexOf("`;\n\n/**", SCRIPT_START));
+/**
+ * 只取「首屏提示」这一段来跑行为。
+ * 为什么不像别的用例那样跑整个适配层：整段要一整套 DOM 桩（抽屉/遮罩/设置面板…），
+ * 而这里要验的是**提示的生命周期**，隔离出来既稳又准（改动范围也正好是这一段）。
+ */
+const BOOT = SCRIPT.slice(SCRIPT.indexOf("var maBootTip"), SCRIPT.indexOf("/* —— 主机门解除"));
+
+/** 极简 DOM 桩：只支撑"提示出现/撤下"这条路径。 */
+function makeDom({ body = true, ready = false, frame = false } = {}) {
+  const nodes = [];
+  const el = (tag) => {
+    const n = {
+      tagName: String(tag).toUpperCase(), className: "", _text: "", children: [], attrs: {}, parentNode: null,
+      set innerHTML(v) { this._html = v; }, get innerHTML() { return this._html || ""; },
+      set textContent(v) { this._text = String(v); }, get textContent() { return this._text; },
+      setAttribute(k, v) { this.attrs[k] = String(v); },
+      appendChild(c) { c.parentNode = this; this.children.push(c); return c; },
+      removeChild(c) { this.children = this.children.filter((x) => x !== c); c.parentNode = null; return c; },
+      querySelector(sel) {
+        const cls = String(sel).replace(/^\./, "");
+        const hit = (x) => (x.className || "").split(/\s+/).includes(cls);
+        const walk = (x) => { for (const c of x.children) { if (hit(c)) return c; const d = walk(c); if (d) return d; } return null; };
+        return walk(this);
+      }
+    };
+    return n;
+  };
+  const doc = {
+    readyState: ready ? "complete" : "loading",
+    listeners: {},
+    createElement: el,
+    querySelector(sel) {
+      if (sel === ".dsh-ma-boot") return nodes.find((n) => (n.className || "").includes("dsh-ma-boot")) || null;
+      if (frame && /frame|textarea|contenteditable|textbox|sidebar-collapsed/.test(sel)) return el("div");
+      return null;
+    },
+    addEventListener(type, fn) { (this.listeners[type] = this.listeners[type] || []).push(fn); },
+    dispatch(type) { (this.listeners[type] || []).forEach((fn) => fn({})); }
+  };
+  if (body) { doc.body = el("body"); doc.body.className = ""; }
+  else { doc.body = null; doc.bodyHolder = el("body"); }
+  return { doc, nodes, el, attachBody() { doc.body = doc.bodyHolder; } };
+}
+
+function run(env) {
+  const timers = [];
+  const intervals = [];
+  const win = {
+    listeners: {},
+    addEventListener(type, fn) { (this.listeners[type] = this.listeners[type] || []).push(fn); },
+    dispatch(type) { (this.listeners[type] || []).forEach((fn) => fn({})); },
+    innerWidth: 390, innerHeight: 844,
+    location: { href: "https://example.test/remote/dev-x/", origin: "https://example.test" },
+    MutationObserver: class { observe() {} disconnect() {} },
+    requestAnimationFrame: (fn) => { timers.push({ fn, ms: 0 }); return timers.length; },
+    cancelAnimationFrame() {}, matchMedia: () => ({ matches: false, addEventListener() {}, removeEventListener() {} })
+  };
+  const ctx = {
+    window: win,
+    document: env.doc,
+    location: win.location,
+    navigator: { userAgent: "node-test", language: "zh-CN" },
+    console: { warn() {}, log() {}, error() {} },
+    setTimeout: (fn, ms) => { timers.push({ fn, ms }); return timers.length; },
+    clearTimeout: () => {},
+    setInterval: (fn, ms) => { intervals.push({ fn, ms }); return intervals.length; },
+    clearInterval: () => {},
+    Date, Math, JSON, Object, Array, String, Number, Boolean, Error, RegExp, Promise, Map, Set
+  };
+  vm.createContext(ctx);
+  vm.runInContext(BOOT, ctx, { timeout: 5000 });
+  return { win, timers, intervals };
+}
+
+test("样式：提示层不挡点击（pointer-events:none）、覆盖所有宽度、有转圈与秒表样式", () => {
+  assert.match(STYLE, /\.dsh-ma-boot\s*\{[\s\S]*?pointer-events:\s*none/, "提示层绝不能拦截点击");
+  assert.ok(!/@media \(max-width: 820px\) \{\s*\.dsh-ma-boot/.test(STYLE), "提示不受窄屏限定（Windows/桌面浏览器同样要等）");
+  assert.match(STYLE, /\.dsh-ma-boot-spin/, "要有加载动画");
+  assert.match(STYLE, /\.dsh-ma-boot-elapsed/, "要有秒表");
+});
+
+test("★ 行为：页面还在解析（readyState=loading）也要立刻挂出提示", () => {
+  const env = makeDom({ ready: false, frame: false });
+  const { win, timers } = run(env);
+  // 提示挂载挂在 DOMContentLoaded 上（此时 body 可能还没出来）
+  assert.ok((env.doc.listeners.DOMContentLoaded || []).length > 0, "必须监听 DOMContentLoaded 再挂提示");
+  env.doc.dispatch("DOMContentLoaded");
+  const tip = env.doc.body.children.find((c) => (c.className || "").includes("dsh-ma-boot"));
+  assert.ok(tip, "解析阶段就要出现提示（这正是首屏最慢的时候）");
+  assert.match(tip.innerHTML, /正在加载远程桌面/);
+  assert.match(tip.innerHTML, /首次打开需要下载/, "要说明为什么慢");
+  assert.ok(timers.some((t) => t.ms === 8000) && timers.some((t) => t.ms === 30000), "要有 8s/30s 两段补充说明");
+  assert.ok(timers.some((t) => t.ms === 240000), "要有 4 分钟兜底撤下");
+  assert.ok((win.listeners.pagehide || []).length > 0, "pagehide 要清理（不留悬挂定时器）");
+});
+
+test("★ 行为：官方 UI 就绪后自动撤下提示", () => {
+  const env = makeDom({ ready: true, frame: true }); // ready=complete → 立即挂；frame=true → 已就绪
+  const { intervals } = run(env);
+  const tip = env.doc.body.children.find((c) => (c.className || "").includes("dsh-ma-boot"));
+  assert.ok(tip, "先挂上");
+  assert.ok(intervals.length >= 2, "要有秒表 + 就绪轮询两个定时器");
+  // 两个 interval 都是 1000ms（秒表 / 就绪轮询），顺序不保证 —— 全部推一次，模拟"1 秒过去"
+  intervals.forEach((t) => t.fn());
+  assert.equal(tip.attrs["data-fading"], "1", "官方 UI 就绪后应进入淡出");
+});
+
+test("行为：脚本在 <head> 里先跑（readyState=loading，body 还没出来）也绝不能抛，body 就位后补挂", () => {
+  // 真实时序就是这条：适配层被内联在 <head>，执行时 body 可能还不存在
+  const env = makeDom({ body: false, ready: false });
+  assert.doesNotThrow(() => run(env), "body 缺失时绝不能抛（适配层其他逻辑还要跑）");
+  env.attachBody();
+  env.doc.dispatch("DOMContentLoaded");
+  const tip = env.doc.body.children.find((c) => (c.className || "").includes("dsh-ma-boot"));
+  assert.ok(tip, "body 就位后补挂提示");
+  assert.match(tip.innerHTML, /正在加载远程桌面/);
+});
+
+test("源码契约：提示必须早于主机判定（HOSTISH/NARROW），否则首屏最慢那段没有提示", () => {
+  // ⚠️ 基准要用 **HOSTISH 的定义**（const HOSTISH =），不能用 indexOf("HOSTISH")：
+  //    提示那段自己的注释里就提到了 HOSTISH，拿注释当基准会把顺序判反（第一版就这么红的）。
+  const iTip = SCRIPT.indexOf("var maBootTip");
+  const iHost = SCRIPT.indexOf("const HOSTISH");
+  assert.ok(iTip > 0 && iHost > 0, "找不到提示段或主机判定");
+  assert.ok(iTip < iHost, "提示段必须在主机判定之前");
+  assert.ok(BOOT.includes("pointer-events: none") || STYLE.includes("pointer-events: none"), "必须写明不拦截点击");
+  assert.ok(!/dsh-ma-boot[\s\S]{0,400}?pointer-events:\s*auto/.test(STYLE), "提示层不得改成可点击拦截");
+});

package/clients/dsh-remote/test/bridge-gzip.test.mjs

@@ -15,7 +15,7 @@ import http from "node:http";
 import os from "node:os";
 import path from "node:path";
 import test, { after } from "node:test";
-import { gunzipSync } from "node:zlib";
+import { gunzipSync, gzipSync } from "node:zlib";
 
 // ---------- 本地假上游(doHttp 全链路用;端口先占再 import,UPSTREAM 在模块加载时固定) ----------
 
@@ -31,6 +31,25 @@ const upstream = http.createServer((req, res) => {
     res.end(BIG_JSON);
     return;
   }
+  /* 模拟**真实 dsh web**:上游自己就把响应 gzip 掉并回 content-encoding: gzip
+     (线上 `/plugins/??` 那个 13.4MB 的聚合包正是这样发的)。
+     这条路由是 bridge「丢弃上游压缩」那个 bug 的回归哨兵 —— 见文件末尾的集成用例。 */
+  if (req.url === "/upstream-gzip") {
+    const body = Buffer.from(BIG_JSON, "utf8");
+    if (String(req.headers["accept-encoding"] || "").includes("gzip")) {
+      const z = gzipSync(body);
+      res.writeHead(200, {
+        "content-type": "application/json; charset=utf-8",
+        "content-encoding": "gzip",
+        "content-length": String(z.length)
+      });
+      res.end(z);
+      return;
+    }
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    res.end(body);
+    return;
+  }
   if (req.url === "/tiny") {
     res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
     res.end(TINY_TEXT);
@@ -213,3 +232,51 @@ test("集成:204 响应不压缩", async () => {
   assert.equal(reply.status, 204);
   assert.equal(reply.headers["content-encoding"], undefined);
 });
+
+test("★ 回归:上游自己 gzip 过(content-encoding: gzip),bridge 仍必须重压回传", async () => {
+  /* 事故原貌(2026-09-23):
+   *   undici 的 fetch 会**自动解压** body,但**保留** `content-encoding: gzip` 响应头。
+   *   旧代码把该头当作"buf 已编码"传给 maybeCompressResponse → 函数保守 return null →
+   *   **永不重压**。于是线上 dsh web 的 /plugins/?? 聚合包(上游 gzip 后 5.12MB)
+   *   被按 13.39MB 原样塞进隧道(实测 3 次,每次 bridge 日志都是 13707KB)。
+   *   免费档 1Mbps 下这一条就把首屏从 ~40 秒拖到 100+ 秒。
+   *
+   * 这条用例守的是:**上游压过 ≠ 我们手上是压缩数据**。bridge 手上永远是 undici 解压后的明文,
+   * 所以必须照常走压缩分支 —— 一旦有人把这个头又接回去,这里立刻红。
+   */
+  const reply = await request({
+    id: "g5",
+    method: "GET",
+    path: "/upstream-gzip",
+    headers: { "accept-encoding": GZIP_ACCEPT, "user-agent": "phone-browser" }
+  });
+  assert.equal(reply.status, 200);
+  assert.equal(
+    reply.headers["content-encoding"],
+    "gzip",
+    "上游压过也照样要重压 —— 少了这个头,隧道里就是 2.6 倍的白流量"
+  );
+  const raw = Buffer.from(reply.body, "base64");
+  const plainLen = Buffer.byteLength(BIG_JSON);
+  assert.ok(raw.length < plainLen, `重压后必须小于明文 (${raw.length} < ${plainLen})`);
+  assert.ok(
+    raw.length < plainLen * 0.6,
+    `应当真正压下去(实测明文 ${plainLen} → ${raw.length});若接近明文说明压缩没生效`
+  );
+  // 只解压一次就应得到原文 —— 这一条同时排除"双重 gzip"这种更坏的结果
+  assert.equal(gunzipSync(raw).toString("utf8"), BIG_JSON, "只能有一层 gzip;解压一次必须就是原文");
+});
+
+test("★ 回归:上游 gzip + 客户端没带 Accept-Encoding → 不压缩,但内容仍是明文原文", async () => {
+  // 上游按 accept-encoding 决定压不压;bridge 解压后原样回传(不带 content-encoding),
+  // 手机端按 identity 处理 → 内容正确,只是没省流量。绝不能出现"标了 gzip 其实是明文"。
+  const reply = await request({
+    id: "g6",
+    method: "GET",
+    path: "/upstream-gzip",
+    headers: { "user-agent": "phone-browser" }
+  });
+  assert.equal(reply.status, 200);
+  assert.equal(reply.headers["content-encoding"], undefined);
+  assert.equal(Buffer.from(reply.body, "base64").toString("utf8"), BIG_JSON);
+});

package/clients/dsh-remote/test/mobile-adapter-late-frame.test.mjs

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+/**
+ * mobile-adapter 回归测试：**网络再慢，左侧抽屉按钮（汉堡）也必须最终出现**。
+ *
+ * 用户原话（2026-09-2x 手机实测）：
+ *   「在网络比较慢的情况下，左边的抽屉按钮有时候出不来。你要考虑修复这个问题，
+ *     甭管网络有多慢，都要让那个抽屉能加载出来。」
+ *
+ * 根因（本文件针对的 bug）：
+ *   注入脚本 boot() 的**执行时机**是写死的一组固定重试
+ *   （DOMContentLoaded + 700 / 1600 / 3200 / 7000 / 12000 ms），
+ *   而汉堡按钮的创建排在 `if (!frame) return;` **之后**：
+ *     · 官方 SPA bundle 有 13.4MB（实测未压缩），免费档被中继限速到 128KB/s 时冷启动要 1-2 分钟；
+ *     · 官方 frame 在 12 秒内根本没出现 → 5 次重试全部在那一行 return
+ *       → `done` 永远为 false → 汉堡按钮永远不创建 → 用户看到"左边抽屉按钮出不来"。
+ *
+ * 修法（本文件断言的契约）：
+ *   ① 不再依赖任何固定重试窗口 —— 改成「事件驱动（MutationObserver 观察 document/subtree）
+ *      + 低频兜底（setInterval 1000ms）」的**无限期**等待：只要 done 还是 false 就继续 boot()；
+ *   ② done=true 之后仍有「存在性看门狗」：官方重渲染把 dsh-ma-hamburger / dsh-ma-scrim
+ *      从 DOM 里冲掉时，按引用补回（节点不变 = 事件处理与类名都还在）；
+ *   ③ 两条路都必须幂等、有节流（观察者回调走 rAF 合并，兜底表 1s 一跳），
+ *      且页面卸载（pagehide/unload）时断开观察者与表。
+ *
+ * 本文件用假 DOM + vm 跑**真实注入脚本**，并把时间轴完全握在手里（不依赖真实计时器）：
+ *   · flushTimeouts()  —— 把旧的固定重试窗口一次性走完（正是"窗口耗尽"的现场）；
+ *   · tickIntervals()  —— 模拟兜底 setInterval 每秒一跳，可以一直跳到第 15 秒、第 60 秒；
+ *   · mountFrame()     —— 模拟官方 DOM 迟到挂载，并按真实 MutationObserver 语义通知观察者。
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import vm from "node:vm";
+import { injectMobileAdapter } from "../mobile-adapter.mjs";
+
+/** 取注入结果里的真实 <script> 内容（不加壳，原样执行）。 */
+function adapterScript() {
+  const { html } = injectMobileAdapter("<!doctype html><html><head></head><body></body></html>");
+  const m = /<script id="[^"]*-js"[^>]*>([\s\S]*?)<\/script>/.exec(html);
+  assert.ok(m, "应能取出注入脚本");
+  return m[1];
+}
+
+// ── 极简假 DOM（与 mobile-adapter-runtime.test.mjs 同风格，另加父子链/isConnected） ──────
+
+class El {
+  constructor(tag = "div", attrs = {}) {
+    this.tagName = String(tag).toUpperCase();
+    this.attrs = { ...attrs };
+    this.children = [];
+    this.parent = null;
+    this._cls = new Set(String(attrs.class || "").split(/\s+/).filter(Boolean));
+    this._l = new Map();
+    this.style = {
+      setProperty: (k, v) => { this._cssVars[k] = v; },
+      removeProperty: (k) => { delete this._cssVars[k]; },
+      display: "",
+    };
+    this._cssVars = {};
+    this._rect = { left: 0, right: 0, top: 0, bottom: 0, width: 0, height: 0 };
+    this.hidden = false;
+    this.classList = {
+      add: (...cs) => cs.forEach((c) => this._cls.add(c)),
+      remove: (...cs) => cs.forEach((c) => this._cls.delete(c)),
+      contains: (c) => this._cls.has(c),
+      toggle: (c, on) => {
+        const want = on === undefined ? !this._cls.has(c) : !!on;
+        if (want) this._cls.add(c); else this._cls.delete(c);
+        return want;
+      },
+    };
+  }
+  set innerHTML(html) {
+    this._html = String(html);
+    this.children = [];
+    for (const m of String(html).matchAll(/<(\w+)([^>]*)>/g)) {
+      const el = new El(m[1]);
+      const cls = /class="([^"]*)"/.exec(m[2] || "");
+      if (cls) el.className = cls[1];
+      const type = /type="([^"]*)"/.exec(m[2] || "");
+      if (type) el.attrs.type = type[1];
+      this.appendChild(el);
+    }
+  }
+  get innerHTML() { return this._html || ""; }
+  get className() { return [...this._cls].join(" "); }
+  set className(v) { this._cls = new Set(String(v).split(/\s+/).filter(Boolean)); }
+  get textContent() { return this._text || ""; }
+  set textContent(v) { this._text = String(v); }
+  getAttribute(n) { return n in this.attrs ? this.attrs[n] : null; }
+  setAttribute(n, v) { this.attrs[n] = String(v); }
+  removeAttribute(n) { delete this.attrs[n]; }
+  hasAttribute(n) { return n in this.attrs; }
+  appendChild(c) { c.parent = this; this.children.push(c); return c; }
+  removeChild(c) { this.children = this.children.filter((x) => x !== c); if (c.parent === this) c.parent = null; return c; }
+  remove() { if (this.parent) this.parent.removeChild(this); }
+  contains(el) { let n = el; while (n) { if (n === this) return true; n = n.parent; } return false; }
+  /* 真实 DOM 语义：节点是否还挂在文档里。本假 DOM 以"能沿 parent 链走到 doc"为准。 */
+  get isConnected() { let n = this; while (n) { if (n._inDoc) return true; n = n.parent; } return false; }
+  prepend() {} focus() {} blur() {} scrollIntoView() {} setPointerCapture() {}
+  matches() { return false; }
+  addEventListener(t, fn) { if (!this._l.has(t)) this._l.set(t, []); this._l.get(t).push(fn); }
+  removeEventListener() {}
+  dispatchEvent() { return true; }
+  dispatch(t, ev = {}) { for (const fn of this._l.get(t) || []) fn({ stopPropagation() {}, preventDefault() {}, ...ev }); }
+  getBoundingClientRect() { return this._rect; }
+  querySelector(sel) {
+    const s = String(sel);
+    const hit = (el) => {
+      if (s.includes('input[type="range"]')) return el.tagName === "INPUT" && el.attrs.type === "range";
+      if (s.startsWith(".")) return el._cls.has(s.slice(1));
+      if (s.startsWith("input")) return el.tagName === "INPUT";
+      return false;
+    };
+    return this.children.find(hit) || null;
+  }
+  querySelectorAll(sel) { const one = this.querySelector(sel); return one ? [one] : []; }
+}
+
+/** 记录型 MutationObserver：可被手工触发，也可被 mountFrame 按真实语义叫醒。 */
+class MutationObserverStub {
+  constructor(cb) { this.cb = cb; this.targets = []; this.disconnected = false; MutationObserverStub.instances.push(this); }
+  observe(t, opts) { this.targets.push({ t, opts }); }
+  disconnect() { this.disconnected = true; }
+  fire(records) { if (!this.disconnected) this.cb(records, this); }
+  static reset() { MutationObserverStub.instances = []; }
+}
+MutationObserverStub.instances = [];
+
+/**
+ * 搭一个"官方 index.html 已经回来、但 13.4MB 的 SPA bundle 还没渲染出 frame"的现场：
+ *   · html.outerHTML 只有官方外壳特征（__ModuleLoader__ / DeepSeek Harness）——
+ *     与真实 index.html 一致，**不含** frame 的任何 data-* 标记；
+ *   · document.querySelector(官方 frame 选择器) 在 mountFrame() 之前一律返回 null
+ *     （= 官方 UI 还没挂载，正是用户网络慢时看到的状态）。
+ */
+function harness({ width = 390, height = 844 } = {}) {
+  MutationObserverStub.reset();
+  const intervals = [];
+  const timeouts = [];
+  let rafs = [];
+  const state = { mounted: false, pagehide: null };
+
+  const doc = new El("#document");
+  doc.tagName = "#DOCUMENT";
+  doc._inDoc = true;                     // 文档根：沿 parent 链能走到它就说明"在文档里"
+  const html = new El("html");
+  const body = new El("body");
+  doc.appendChild(html);
+  html.appendChild(body);
+  // 官方 index.html 外壳（真实 HTML 里就是这些字样；frame 是 bundle 跑起来之后才有的）
+  // outerHTML 做成计数器：boot() 第一行的 HOSTISH() 会整段序列化它，读数就是"整页判定"的次数
+  let outerHtmlReads = 0;
+  Object.defineProperty(html, "outerHTML", {
+    configurable: true,
+    get() { outerHtmlReads += 1; return '<html><head><script>window.__ModuleLoader__ = { mode: "queue" }</script>'
+      + "<title>DeepSeek Harness</title></head><body></body></html>"; },
+    set() { /* 允许写入（本用例不依赖） */ },
+  });
+
+  const frame = new El("div", { class: "pI_x6G_frame" });
+  frame.setAttribute("data-sidebar-collapsed", "true");
+  frame.querySelector = () => null;      // 本用例不涉及第三列/overlay 识别
+
+  doc.readyState = "complete";
+  doc.documentElement = html;
+  doc.body = body;
+  doc.createElement = (t) => new El(t);
+  doc.createTextNode = (t) => ({ nodeValue: t });
+  doc.getElementById = () => null;
+  doc.addEventListener = () => {};
+  doc.removeEventListener = () => {};
+  doc.querySelector = (sel) => {
+    const s = String(sel);
+    if (s.includes(".pI_x6G_frame") || /\[data-(sidebar|details|rightbar)-collapsed\]/.test(s) || s.includes("[data-shell-overlay]")) {
+      return state.mounted ? frame : null;   // ⬅️ 官方 UI 迟到：挂载前一律查不到
+    }
+    return null;
+  };
+  doc.querySelectorAll = () => [];
+
+  const loc = { href: "https://n.risegao.cn:13443/remote/dev-x/", host: "n.risegao.cn", pathname: "/remote/dev-x/", origin: "https://n.risegao.cn:13443" };
+  const win = {
+    innerWidth: width,
+    innerHeight: height,
+    devicePixelRatio: 2,
+    localStorage: { _d: {}, getItem(k) { return k in this._d ? this._d[k] : null; }, setItem(k, v) { this._d[k] = String(v); }, removeItem(k) { delete this._d[k]; } },
+    location: loc,
+    MutationObserver: MutationObserverStub,
+    ResizeObserver: class { observe() {} disconnect() {} },
+    getComputedStyle: () => ({ getPropertyValue: () => "", pointerEvents: "none" }),
+    addEventListener(t, fn) {
+      if (t === "pagehide" || t === "unload") state.pagehide = fn;
+      if (t === "pageshow") state.pageshow = fn;
+    },
+    removeEventListener() {},
+    /* 计时器全部"抓住不放"，时间轴由用例自己推 —— 不依赖真实时钟，也不会有测试结束后的悬挂回调。 */
+    setTimeout: (fn) => timeouts.push(fn),
+    clearTimeout: () => {},
+    setInterval: (fn) => { intervals.push(fn); return intervals.length; },
+    clearInterval: (id) => { if (id) intervals[id - 1] = null; },
+    requestAnimationFrame: (fn) => { rafs.push(fn); return rafs.length; },
+  };
+
+  const ctx = vm.createContext({
+    window: win, document: doc, console,
+    navigator: { userAgent: "iPhone Safari", maxTouchPoints: 5, platform: "iPhone" },
+    location: loc, localStorage: win.localStorage,
+    setTimeout: win.setTimeout, clearTimeout: win.clearTimeout,
+    setInterval: win.setInterval, clearInterval: win.clearInterval,
+    MutationObserver: MutationObserverStub, ResizeObserver: win.ResizeObserver,
+    requestAnimationFrame: win.requestAnimationFrame,
+    URL, Math, JSON, Object, Array, String, Number, RegExp, Boolean, Promise, Error, isNaN, parseInt, parseFloat,
+    HTMLElement: El,
+  });
+  ctx.globalThis = ctx;
+  ctx.self = win;
+
+  /** 官方 UI 迟到挂载：把 frame 挂进 body，并按真实 MutationObserver 语义通知观察祖先树的观察者。 */
+  const mountFrame = ({ notify = true } = {}) => {
+    state.mounted = true;
+    body.appendChild(frame);
+    if (!notify) return;
+    for (const ob of MutationObserverStub.instances.slice()) {
+      if (ob.disconnected) continue;
+      const targets = ob.targets.map((x) => x.t);
+      // 新节点加进 body → 观察 body / documentElement / document（subtree）的观察者都会收到 childList 记录
+      if (targets.includes(body) || targets.includes(html) || targets.includes(doc)) {
+        ob.fire([{ type: "childList", target: body, addedNodes: [frame] }]);
+      }
+    }
+  };
+  /** 把旧的"固定重试窗口"（700/1600/3200/7000/12000ms 那批 setTimeout）一次性走完。 */
+  const flushTimeouts = () => { const q = timeouts.splice(0, timeouts.length); for (const fn of q) fn(); };
+  /** 模拟兜底 setInterval 每秒一跳（间隔由实现决定，用例只关心"它一直在跳"）。 */
+  const tickIntervals = (seconds = 1) => {
+    for (let i = 0; i < seconds; i++) for (const fn of intervals.slice()) if (fn) fn();
+  };
+  const flushRaf = () => { const q = rafs; rafs = []; for (const fn of q) fn(); };
+  /** 模拟官方 SPA 的 DOM 变更风暴（流式输出时每帧都在改 DOM），并按真实语义通知观察者。 */
+  const churn = (n = 20) => {
+    for (let i = 0; i < n; i++) {
+      const d = new El("div");
+      body.appendChild(d);
+      for (const ob of MutationObserverStub.instances.slice()) {
+        if (ob.disconnected) continue;
+        const targets = ob.targets.map((x) => x.t);
+        if (targets.includes(body) || targets.includes(html) || targets.includes(doc)) {
+          ob.fire([{ type: "childList", target: body, addedNodes: [d] }]);
+        }
+      }
+      flushRaf();
+    }
+  };
+
+  return { ctx, doc, html, body, frame, win, state, mountFrame, flushTimeouts, tickIntervals, flushRaf, churn,
+    intervals, outerHtmlReads: () => outerHtmlReads };
+}
+
+function run(env, js) {
+  vm.runInContext(js, env.ctx, { timeout: 5000 });
+  return env;
+}
+
+const findHamburger = (env) => env.body.children.find((c) => c._cls.has("dsh-ma-hamburger"));
+const findScrim = (env) => env.body.children.find((c) => c._cls.has("dsh-ma-scrim"));
+
+// ── 用例 ─────────────────────────────────────────────────────────────────────
+
+test("慢网回归：官方 frame 第 15 秒才出现，汉堡按钮最终仍必须创建（旧的 12s 固定重试窗口会永久放弃）", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+
+  assert.ok(!findHamburger(env), "前提：官方 frame 还没出现时，不该凭空造出汉堡按钮");
+  assert.ok(!findScrim(env), "前提：官方 frame 还没出现时，不该凭空造出遮罩");
+
+  // ① 先把旧的固定重试窗口整批走完（700…12000ms 全部到点）—— 这正是当年"窗口耗尽"的现场
+  env.flushTimeouts();
+  assert.ok(!findHamburger(env), "官方 frame 未出现时仍不得创建汉堡按钮（不能提前造出无锚点的入口）");
+
+  // ② 再把时间推过 15 秒（兜底表每秒一跳），官方 frame 依然没来
+  env.tickIntervals(15);
+  assert.ok(!findHamburger(env), "前提：frame 还没来");
+
+  // ③ 第 15 秒：13.4MB 的 bundle 终于在 128KB/s 的限制下加载完，官方 frame 挂上 DOM。
+  //    这里刻意不通知观察者（notify:false）—— 只留"低频兜底 setInterval"这一条路，
+  //    证明它不是"靠事件侥幸"，而是真的无限期重试。
+  env.mountFrame({ notify: false });
+  assert.ok(!findHamburger(env), "前提：这一瞬间还没轮到兜底表跳");
+
+  env.tickIntervals(1);
+  assert.ok(findHamburger(env),
+    "网络再慢，官方 frame 一出现抽屉按钮也必须最终创建出来（本次 bug 的回归点：固定重试窗口耗尽就永久放弃）");
+  assert.ok(findScrim(env), "遮罩同样必须补上（它和汉堡按钮在同一段之后创建）");
+});
+
+test("慢网回归：跳到第 60 秒（远超旧窗口 5 倍）官方 frame 才出现，汉堡按钮仍必须出现", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  env.flushTimeouts();
+  env.tickIntervals(60);                        // 60 秒过去，frame 还没来
+  assert.ok(!findHamburger(env), "前提：frame 仍然没来");
+  env.mountFrame({ notify: false });            // 第 60 秒才挂上
+  env.tickIntervals(1);
+  assert.ok(findHamburger(env), "「甭管网络有多慢」——60 秒后才出现官方 frame 也必须能拿到抽屉按钮");
+});
+
+test("事件驱动：官方 frame 挂载的 DOM 变更直接叫醒适配层（观察者回调经 rAF 合并，不等兜底表）", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  assert.ok(!findHamburger(env), "前提：frame 未挂载");
+  env.mountFrame();                             // 通知观察者
+  env.flushRaf();                               // 合并后的那一帧
+  assert.ok(findHamburger(env), "官方 frame 一挂上就必须立刻跟上（事件驱动路径），不必等 1s 兜底表");
+});
+
+test("存在性看门狗：done 之后官方重渲染把汉堡/遮罩冲掉，必须按引用补回来", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  env.mountFrame({ notify: false });
+  env.tickIntervals(1);
+  const ham = findHamburger(env);
+  const scrim = findScrim(env);
+  assert.ok(ham && scrim, "前提：抽屉入口已建好");
+
+  // 模拟官方 SPA 重渲染：整片换掉 body 子树（实测某些路由/会话切换会重建 DOM）
+  env.body.removeChild(ham);
+  env.body.removeChild(scrim);
+  assert.ok(!findHamburger(env), "前提：官方重渲染把我们的节点冲掉了");
+  assert.equal(ham.isConnected, false, "假 DOM 语义：被移除的节点应报 isConnected=false");
+
+  env.tickIntervals(2);
+  assert.equal(findHamburger(env), ham, "补回的必须是**同一个节点**（事件处理与类名原样保留），而不是重建一个");
+  assert.equal(findScrim(env), scrim, "遮罩同样必须补回");
+  assert.equal(ham.isConnected, true, "补回后应重新在文档里");
+});
+
+test("清理：pagehide 必须断开观察者与兜底表（避免 bfcache/长驻页面泄漏）", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  assert.equal(typeof env.state.pagehide, "function", "应注册 pagehide 清理钩子");
+  const observers = MutationObserverStub.instances.slice();
+  env.state.pagehide();
+  assert.ok(observers.every((o) => o.disconnected), "pagehide 必须 disconnect 所有已挂观察者");
+  // 断开后时间轴上再跳也不再工作（表已清）
+  env.mountFrame({ notify: false });
+  env.tickIntervals(2);
+  assert.ok(!findHamburger(env), "卸载后不得再往页面里塞东西");
+});
+
+test("bfcache：切走再切回来（pageshow persisted）必须重新武装看门狗，否则回来后就永久失灵", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  env.mountFrame({ notify: false });
+  env.tickIntervals(1);
+  const ham = findHamburger(env);
+  assert.ok(ham, "前提：抽屉入口已就位");
+
+  env.state.pagehide();                          // 切走（进入 bfcache）
+  env.state.pageshow({ persisted: true });       // 切回来（从 bfcache 恢复）
+  env.body.removeChild(ham);                     // 官方此时重渲染冲掉我们的节点
+  env.tickIntervals(1);
+  assert.equal(findHamburger(env), ham, "bfcache 恢复后看门狗必须仍然有效（重新武装）");
+  env.state.pageshow({ persisted: false });      // 普通 pageshow 不得重复武装出第二套计时器
+  const live = env.intervals.filter(Boolean).length;
+  env.state.pageshow({ persisted: true });
+  assert.equal(env.intervals.filter(Boolean).length, live, "重新武装必须先清旧表（不能越切越多计时器）");
+});
+
+test("幂等：兜底表长时间空转不得重复插入节点（每类节点在 body 里最多一个）", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  env.mountFrame({ notify: false });
+  env.tickIntervals(30);                        // 空转 30 秒
+  const count = (cls) => env.body.children.filter((c) => c._cls.has(cls)).length;
+  assert.equal(count("dsh-ma-hamburger"), 1, "汉堡按钮必须只有一个（幂等，不能每次 tick 都插一个）");
+  assert.equal(count("dsh-ma-scrim"), 1, "遮罩必须只有一个");
+});
+
+test("开销：抽屉入口就位后，官方的 DOM 变更风暴不得再触发整页判定（HOSTISH 会序列化整个 outerHTML）", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  env.mountFrame({ notify: false });
+  env.tickIntervals(1);
+  assert.ok(findHamburger(env), "前提：抽屉入口已就位");
+
+  // 官方流式输出时每帧都在改 DOM —— 这时适配层必须已经"静默"，不能再做昂贵判定
+  const before = env.outerHtmlReads();
+  env.churn(30);                                 // 30 帧 DOM 变更（每帧都通知观察者）
+  env.tickIntervals(3);                          // 兜底表再空转 3 秒
+  assert.equal(env.outerHtmlReads(), before,
+    "入口已经建好且都在文档里时，不得再为每次 DOM 变更/每秒 tick 重新序列化整页（那是每秒几十次全量 outerHTML）");
+  // 但"看门狗"必须还在：真被冲掉时依然能补回来（静默 ≠ 失灵）
+  env.body.removeChild(findHamburger(env));
+  env.churn(1);
+  assert.ok(findHamburger(env), "静默之后看门狗仍必须工作");
+});