dsh-inner-browser-use 0.37.0 → 0.38.0

package/docs/ARCHITECTURE.md

@@ -160,6 +160,11 @@ Calls that touch the browser are marked not concurrency-safe; reading state, con
 requests is. `browser_open`, `browser_view`, `browser_wait` and `browser_shot` carry longer
 timeouts than the rest.
 
+`browser_wait` does not poll: one call hands the page a predicate and a `MutationObserver`, and the
+picture comes back on the mutation that satisfies it. A page that changes 137 ms after the wait
+starts answers at 138 ms, not at the next 100 ms tick — the same reason `idle` (a mutation-free
+window) costs one round trip on an animation-heavy page instead of one per frame.
+
 Sign-in state lives in the profile, and session cookies — the kind a sign-in usually sets,
 which Chrome would otherwise drop on exit — are saved next to it and restored on the next
 launch, so a restart of the app does not sign the person out.

package/docs/BENCH.md

@@ -1,3 +1,18 @@
+## 等到变化，而不是去问（0.38.0）
+
+`browser_wait` 以前在宿主侧每 100 毫秒读一次页面判断条件，命中与否都被凑到下一个整拍上。
+现在一次调用把谓词和 `MutationObserver` 交给页面，满足条件的那次变化直接 resolve，回程只走
+一次。
+
+| 同一件事 | 0.37.0（宿主轮询） | 0.38.0（页面观察） |
+| --- | --- | --- |
+| 五次不同时相的等待，平均耗时 | 205 ms | 140 ms |
+| 每次等待的探测来回 | 3 | 1 |
+| `idle` 判定 | 固定间隔重读页面 | 350 ms 无变化即停，一次来回 |
+
+`wait-late` 行就是上表：每次实验在等待开始的同一刻给页面装一个定时器，所以旧路径必然要走到
+下一个 100 毫秒整拍，新路径不必。预算 600 ms，实测 140 ms。
+
 ## 只列该看的那一个（0.37.0，同一台本地页面，加了两个广告请求）
 
 页面自己放一个 `<video src="/movie.mp4">`、一个 `<audio>`、fetch 一个 master 播放列表，再 fetch 两条广告（`/ads/preroll.mp4` 9 MB、`/px/beacon.mp4` 2 B）。不筛选时 5 条都在；默认列表剩 3 条，页面播放器那个标 `main` 排第一，`save: main` 存的就是它。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-inner-browser-use",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "An agent-owned Chromium sidecar mirrored into the DeepSeek Harness right column: the agent drives it, the person watches and can take the mouse, and logins survive restarts.",
   "type": "module",
   "main": "index.js",

package/tools.js

@@ -1070,13 +1070,64 @@ export async function settle(page, timeout = 5000, since = 0) {
  * @returns {Promise<boolean>} whether it ever held.
  */
 async function until(page, expression, timeout) {
-  const deadline = Date.now() + timeout
-  while (Date.now() < deadline) {
-    const value = await evaluate(page, expression)
-    if (value === true) return true
-    await wait(100)
-  }
-  return false
+  /* The page watches itself. One round trip that the page resolves on the
+     mutation which matters: no snapshot every 100 ms, no rounding the answer up
+     to the next tick, and nothing to miss between two polls. */
+  const ceiling = Math.max(200, Number(timeout) || 1000)
+  const script = `new Promise((done) => {
+    const deadline = Date.now() + ${String(ceiling)}
+    let watcher = null
+    let timer = null
+    let frame = null
+    const stop = (value) => {
+      if (watcher !== null) watcher.disconnect()
+      watcher = null
+      if (timer !== null) clearTimeout(timer)
+      timer = null
+      if (frame !== null) cancelAnimationFrame(frame)
+      frame = null
+      done(value)
+    }
+    const test = () => { try { return Boolean(${expression}) } catch (error) { return false } }
+    if (test()) return stop(true)
+    watcher = new MutationObserver(() => { if (test()) stop(true) })
+    if (document.documentElement !== null) watcher.observe(document.documentElement, { childList: true, subtree: true, attributes: true, characterData: true })
+    const tick = () => {
+      if (test()) return stop(true)
+      if (Date.now() >= deadline) return stop(false)
+      frame = requestAnimationFrame(tick)
+    }
+    frame = requestAnimationFrame(tick)
+    timer = setTimeout(() => stop(false), deadline - Date.now())
+  })`
+  const answer = await evaluate(page, script, undefined, ceiling + 3000)
+  return answer === true
+}
+
+/**
+ * How long the page has been still: a mutation resets the clock, and the call
+ * comes back the moment nothing has moved for `quiet` ms. Reads no node, so an
+ * animation-heavy page costs the same as a blank one.
+ */
+async function quietInPage(page, timeout = 5000, quiet = 350) {
+  const ceiling = Math.max(300, Number(timeout) || 5000)
+  const script = `new Promise((done) => {
+    const ceiling = Date.now() + ${String(ceiling)}
+    const settleMs = ${String(Math.max(50, Number(quiet) || 350))}
+    let changedAt = Date.now()
+    let frame = null
+    const watcher = new MutationObserver(() => { changedAt = Date.now() })
+    if (document.documentElement !== null) watcher.observe(document.documentElement, { childList: true, subtree: true, attributes: true, characterData: true })
+    const tick = () => {
+      const now = Date.now()
+      if (now - changedAt >= settleMs) { watcher.disconnect(); return done(true) }
+      if (now >= ceiling) { watcher.disconnect(); return done(false) }
+      frame = requestAnimationFrame(tick)
+    }
+    frame = requestAnimationFrame(tick)
+  })`
+  const answer = await evaluate(page, script, undefined, ceiling + 3000)
+  return answer === true
 }
 
 /**
@@ -3150,8 +3201,9 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
           const at = await until(page, `location.href.includes(${JSON.stringify(String(args.url))})`, timeout)
           return at ? `at ${String(await evaluate(page, 'location.href'))}` : `address never contained ${String(args.url)}`
         }
-        await settle(page, timeout)
-        return 'idle'
+        const quiet = await quietInPage(page, timeout)
+        if (typeof page.adoptOpened === 'function') await page.adoptOpened().catch(() => '')
+        return quiet ? 'idle' : 'still moving'
       }),
     },
     {