dsh-inner-browser-use 0.44.0 → 0.46.0

package/README.md

@@ -20,10 +20,13 @@ live picture of that browser, and your own cursor keeps working on the picture.
 | `browser_key` | Presses one key: Enter, Tab, Escape, Backspace, Delete, Insert, arrows, Home, End, PageUp, PageDown, F1-F12, the numeric keypad, letters, digits, punctuation and every shifted symbol, plus ContextMenu, CapsLock, PrintScreen and media keys. `Ctrl`/`Alt`/`Shift`/`Meta`/`Mod` modifiers, chords with `+`, and `Ctrl+C/X/V/A/Z/Y` run the real editing commands. |
 | `browser_scroll` | Scrolls the wheel at the centre of the page, or at `x`/`y`. `dy: 600` is about a screen down. |
 | `browser_shot` | Saves a full-size PNG into `~/.dsh-inner-browser-use/screenshots` and returns the path. |
+| `browser_look` | Looks at a page that draws itself — a game, a canvas, a Flash movie — and returns it as a grid of letters, one per block of screen, the same letter for the same colour: 12×8 costs about 200 characters, so a picture costs no image tokens. A second look reports only the cells that changed. `browser_shot` is still the tool for colour, layout and anything a person should see. |
 | `browser_media` | Lists the video and sound the page already fetched, with sizes, the one its own player shows first and marked `main`; `save: <row>`, `save: main` or part of the address keeps one. Ads and beacons stay out unless `all: true`; `watch: false` stops remembering the page. A stream is followed to its pieces and joined, so nothing has to be installed. |
 | `browser_login` | Keeps a sign-in by name: `save` stores this window's cookies and each site's local storage, `list` shows what is kept, `use` signs that account back in and reopens the page, `import` takes a sign-in that is already in Chrome, Brave, Edge or Chromium on this Mac and keeps it under a name, `drop` forgets it. Names survive a restart and belong to the browser rather than to one chat, so two accounts on one site are two names. What sits on disk is encrypted, with the key in the system keychain. |
 | `browser_state` | Reports whether the browser runs, which profile it uses, its address and title, how many columns are showing it, how much memory it holds right now and when it would close on its own if left alone. |
 
+A site you read twice is remembered by origin in `~/.dsh/inner-browser-use/sites.json` (override with `DSH_INNER_BROWSER_STATE_DIR`). After two reads, a site whose page text or control count is big opens in `browser_view` as a `map:` of what is there, and a site whose articles are long has `browser_read` cut at 3,500 characters with a line saying so. Both come with one sentence naming the measurement, and both yield to an explicit `mode`, `query` or `max_chars` — learning changes the default, not the answer to a direct question. `scripts/check-sites.mjs` is the live proof: three views of a 300-button page and three reads of a 12,000-character document, saying where the cut fell.
+
 `browser_read` on the same page is the words only, in Markdown (measured: 4,520
 characters of an about page against 2,987 characters of snapshot — and the
 snapshot spends most of its budget on controls; on a long article the gap grows
@@ -73,8 +76,16 @@ sign-in here is still there the next day.
 - **Harness restart.** The same directory is opened again, so cookies, `localStorage` and
   passwords that Chrome saved all survive.
 - **Shutdown.** The browser is asked to close rather than killed, which is when Chrome writes
-  the last of its cookies; an idle browser is closed after 15 minutes, and the clock stops
-  while a column is watching.
+  the last of its cookies.
+
+## When nobody is looking
+
+A browser used every two seconds rests after two minutes; one used every ninety seconds waits
+nine. The window is p95 of the person's own last 64 gaps, × 6 for rest and × 2 for a reversible
+pause, so it is learned rather than configured. Close the column and the rest is one minute
+away; leave it open and the page is frozen instead (DOM, scroll and sign-ins kept, screenshot
+stream stopped). A wake is 0.3–1.1 s and lands on the same address. `npm run rest` checks the
+whole chain headlessly; `docs/RESOURCES.md` has the memory ladder and how the neighbours do it.
 
 Screenshots are the only thing written outside the profile:
 `~/.dsh-inner-browser-use/screenshots/`.

package/README.zh.md

@@ -19,10 +19,13 @@ profile，不是产品自带的那个浏览页签：右栏放的是它的画面
 | `browser_key` | 按一个键：Enter、Tab、Escape、Backspace、Delete、上下左右、Home、End、PageUp、PageDown。 |
 | `browser_scroll` | 在页面中心滚轮，也可以指定 `x`/`y`。`dy: 600` 约一屏。 |
 | `browser_shot` | 存一张 PNG 到 `~/.dsh/inner-browser-use/screenshots`，返回路径；`region: [x, y, w, h]` 只截一块（游戏、图表、看局部）。 |
+| `browser_look` | 看自己画自己的页面（游戏、canvas、Flash）：把画面压成字母网格，一块屏幕一个字母、同色同字母，12×8 约 200 字符，不花图片 token；再看一次只报变了的格子。要颜色、布局或给人看图仍用 `browser_shot`。 |
 | `browser_media` | 列出页面已经请求过的视频和声音（带大小），页面自己播放器里那个排第一、标 `main`；`save: <行号>`、`save: main` 或地址片段存下来。广告和统计默认不出现（`all: true` 才看），`watch: false` 关掉这个页面的记录。流会顺着播放列表把片段取回拼好，不用装任何东西。 |
 | `browser_login` | 按名字留住登录：`save` 存下当前窗口的 cookie 和各站的 localStorage，`list` 看有哪些，`use` 切回那个账号并重开页面，`import` 把本机 Chrome/Brave/Edge 里已经登着的站直接留成一个名字，`drop` 忘掉。名字跟着浏览器走、不跟着一个会话走，重启也在；同一站点两个账号就存两个名字。磁盘上那一份是加密的，钥匙在系统钥匙串里。 |
 | `browser_state` | 报浏览器在不在跑、用的哪个 profile、地址、标题、有几个右栏在看它，以及它此刻占多少内存、没人用的话还有多久关闭。 |
 
+同一个站读两次就会被按 origin 记住（`~/.dsh/inner-browser-use/sites.json`，可用 `DSH_INNER_BROWSER_STATE_DIR` 改位置）。第二次之后：正文或控件多的站，`browser_view` 默认先给 `map:` 地标；文章长的站，`browser_read` 默认截到 3500 字符并说明截在哪。两者都带一句实测数字，也都会被显式 `mode`、`query`、`max_chars` 覆盖——学到的是默认值，不是对直接提问的答案。`scripts/check-sites.mjs` 是现场证据：300 个按钮的页看三次、12000 字的文档读三次，报出截断位置。
+
 点、输入、按键之后的那一行会多一句结果：`· navigated to …`（换页了）、`· content changed`（页内有变化）、`· no visible change`（点了没动）、Flash 页则是 `· screen updated` / `· no frame change`；`read: true` 时不再多说。
 
 `browser_view` 一次给一页文本：
@@ -65,8 +68,15 @@ profile 是独立目录：`~/.dsh/inner-browser-use/chrome/default`。它在产
 
 - **插件重载。** 重载会接上仍在运行的那个 Chrome，页面也还在原处。
 - **Harness 重启。** 重新打开同一个目录，cookie、`localStorage` 和 Chrome 存下的密码都留着。
-- **退出。** 关浏览器是请它自己关（`Browser.close`），Chrome 在这一步才把 cookie 落盘；空闲
-  15 分钟会关掉，有右栏在看时不计这段空闲。
+- **退出。** 关浏览器是请它自己关（`Browser.close`），Chrome 在这一步才把 cookie 落盘。
+
+## 没人看的时候
+
+每两秒用一次的人，两分钟后就休息；每九十秒用一次的人能等九分钟——窗口取自这个人最近 64 次
+调用间隔的 95 分位，休息乘 6、可逆停驻乘 2，是学出来的不是配出来的。右栏关掉后一分钟就真的
+释放（内存归零，cookies 先存好）；右栏还开着只是没人动，就走停驻——DOM、滚动位置、登录态都
+留着，截图流停掉。唤醒 0.3–1.1 秒，回到同一个地址。无头验证跑 `npm run rest`，内存阶梯与
+竞品对照在 `docs/RESOURCES.md`。
 
 profile 之外只写一样东西：`~/.dsh-inner-browser-use/screenshots/` 里的截图。
 

package/docs/ARCHITECTURE.md

@@ -61,9 +61,30 @@ One page per browser. `apply()` only constructs the `Sidecar`; no process exists
 first tool call, and `browser_state` reports a stopped browser without starting one.
 
 Shutdown asks Chrome to close (`Browser.close`), waits briefly, then sends `SIGTERM`, which is
-the point where Chrome flushes cookies. An idle timer closes the browser after 15 minutes; a
-tool call resets the clock, and a watching column defers the close when the timer fires, so a
-page someone is reading outlives the idle window.
+the point where Chrome flushes cookies.
+
+Lifetime is a ladder rather than one timer, because a browser that is being watched and one
+that was forgotten deserve different answers (`docs/RESOURCES.md` has the measurements and the
+comparison with other projects):
+
+| step | trigger | effect |
+| --- | --- | --- |
+| awake | a tool call, or a mirror watching | none |
+| quiet | no call for `quietAfter()` and a mirror is still open | screencast stopped, page frozen |
+| rest | no call for `restAfter()` and nothing watching | cookies saved, whole tree closed |
+
+`rest.js` derives both windows from the gap between the person's own calls: p95 of the last 64
+gaps × 6 for rest, × 2 for quiet, each clamped (`90 s – 15 min`, `20 s – 2 min`). A fresh
+process has no history and uses the floors. `decide()` is pure, so the clock is testable
+without a browser, and the watched count always beats the deadline: a page someone can see is
+frozen at most, never closed.
+
+Closing is single-flight (`shutdown()` returns the promise already in flight) and `launch()`
+waits for the outgoing browser before spawning the next one — without that, a rest that fires
+as a call arrives closes the socket the call is about to use. Every 30 s the tree is weighed
+against `DSH_INNER_BROWSER_MEMORY_MB` (default 2400): over budget, idle tabs are reclaimed by
+LRU and casts back off; over again with nobody watching, the browser rests on the spot. Three
+crashes inside ten minutes stop the restart loop and say why instead of trying forever.
 
 ## Routes
 
@@ -134,7 +155,7 @@ browser without pulling the column away from the person reading it.
 
 ## Tool surface
 
-`sidecarTools()` in `tools.js` builds the 28 definitions and `index.js` registers them on the
+`sidecarTools()` in `tools.js` builds the 39 definitions and `index.js` registers them on the
 plugin's tool scope. All of them return one text block. A page read numbers the controls and
 keeps those numbers across later reads, so `browser_click` by ref means the element the model
 last saw; navigation drops them and the model gets `REF_GONE` rather than a wrong click.
@@ -198,6 +219,32 @@ characters) and no text, and the tool turns that into a line saying nothing dire
 question plus those passages. The whole page is still one `browser_view` away, so the expensive
 fallback — a page pasted into the context for a question it never addressed — is gone.
 
+## Looking at a page that draws itself
+
+A canvas, a game and a Flash movie have no text tree and no controls: a snapshot reads
+an empty page and a screenshot costs image tokens on every look. `browser_look` takes
+the captured frame, decodes the PNG inside Node (so no page policy and no browser
+decode step is involved) and prints a grid of palette letters — one letter per block of
+screen, the same letter for the same colour. A 12×8 look costs about 200 characters; a
+second look diffs against the first grid and reports only the cells that moved, plus the
+box they moved in. `browser_prepare` is the way in: it reports the surface, the frame
+rate and whether keys arrive, and says when the page needs the Flash runtime.
+
+## Sites that teach the next read
+
+Two calls into the same origin, the browser knows what it is looking at. A record per
+origin in `sites.json` holds an exponentially drifted average of the page's character
+count, its control count and its article length, updated by every `browser_view` and
+`browser_read` — measured before the budget cuts the output, so a cut does not shrink
+the site on the next visit. Past two reads, a site whose text or control count is big
+opens `browser_view` as the `map:` view instead of a page of numbered controls, and a
+site whose articles are long has `browser_read` land at 3,500 characters and say where
+it cut. Every learned default carries the measurement that produced it, and every one
+yields to what the model asked for: an explicit `mode`, `query` or `max_chars` is used
+as given. The record lives in `~/.dsh/inner-browser-use/sites.json` (override with
+`DSH_INNER_BROWSER_STATE_DIR`), is written at most once every two seconds, and never
+holds page text — only counts.
+
 ## Answering across tabs
 
 A question can be answered by a tab that is not the one on screen. Moving the mirror there and

package/docs/ARTIFACTS.md

@@ -1,35 +1,40 @@
 # 文件落在哪里
 
-浏览器产生的东西——截图、抓下来的图、打印的 PDF——不落在项目根目录，也不散在 home 下。固定规则：
+浏览器产生的东西——截图、抓下来的图、打印的 PDF、存下的视频——落在**当前项目里**，跟会话工作目录走；不在项目根目录，也不散在 home 下。
 
 ```
-~/.dsh-inner-browser-use/artifacts/<项目>/<会话>/<种类>/
+<项目>/.dsh/browser/<会话>/<种类>/
 ```
 
-- **项目**：会话工作目录的文件夹名，加路径哈希前 6 位，例如 `dsh-inner-browser-use-a1b2c3`。同名文件夹、不同路径不会混。
-- **会话**：会话 id 去掉 `session-` 后的前 8 位，例如 `72557d6e`。同一项目里两个会话各存各的。
+- **项目**：会话的工作目录。换项目就换目录，产出跟着项目走，方便直接拷进仓库或用项目里的工具看。
+- **会话**：会话 id 去掉 `session-` 后的前 8 位，例如 `72557d6e`。同一项目里两个会话各存各的，不会互相覆盖。
 - **种类**：`shots/` 是 `browser_shot` 的截图，`pictures/` 是 `browser_grab` 抓的图，`pdf/` 是 `browser_pdf` 打印的文档，`media/` 是 `browser_media` 存下的视频、音频和流。
 
-文件名默认带时间戳（`shot-20261028-124500.png`），给了 `name` 就用它；名字里的分隔符、连续点、开头点都会被去掉，跳不出这个目录。
+`browser_look` 不落文件：它把屏幕读成字母网格直接返回，用来反复看画面变化。
+
+文件名默认带时间戳（`shot-20261028-124500.png`），给了 `name` 就用它；名字里的分隔符、连续点、开头点都会被去掉，跳不出这个目录。`browser_state` 的 `files` 一行给出当前实际落点。
 
 每个种类保留最新 40 个文件，旧的自动删，免得跑一天的会话留下一个没人翻得动的文件夹。开着的文件不会被删掉（尽力删除，失败就留着）。
 
-调用环境里没有项目或会话信息时，落到 `no-project/no-chat/<种类>/`，不猜。
+`<项目>/.dsh/browser/.gitignore` 写一行 `*`，所以截图不会进 `git status`；这个文件只在项目里写。调用环境里没有项目信息时，落到 `~/.dsh-inner-browser-use/artifacts/no-project/`，不猜，也不写 `.gitignore`。
+
+`DSH_INNER_BROWSER_ARTIFACTS` 能把整个落点换到一个固定目录（测试用，也方便把产出收到别处），此时不写 `.gitignore`。
 
 ## 整个目录
 
 ```
+<项目>/.dsh/browser/                 截图、抓图、PDF、媒体（见上）
 ~/.dsh-inner-browser-use/
-  artifacts/<项目>/<会话>/<种类>/   给人看的产出，只在这里（见上）
-  chrome/                          浏览器自己的数据：登录态、Cookie、缓存
-  logins/                          按名字留住的登录，一个名字一个文件，加密
-  vault.key                        钥匙串拿不到钥匙时的替代文件，只有本人可读
-  flash/                           Flash 播放器运行时，第一次用 flash:true 才装
-  browser.log                     最近一次浏览器启动和页面记录
-  asks.log                        人问过什么、答了什么
+  artifacts/no-project/              没有项目时的产出
+  chrome/                            浏览器自己的数据：登录态、Cookie、缓存
+  logins/                            按名字留住的登录，一个名字一个文件，加密
+  vault.key                          钥匙串拿不到钥匙时的替代文件，只有本人可读
+  flash/                             Flash 播放器运行时，第一次用 flash:true 才装
+  browser.log                        最近一次浏览器启动和页面记录
+  asks.log                           人问过什么、答了什么
   tabs.json / mirror.json / flash.json / watcher.json   上次开着哪些页
 ```
 
-`chrome/session-cookies.json` 是 Chrome 退出时会丢的会话 cookie，加密后存在 profile 旁边；`logins/` 与 `vault.key` 由 `browser_login` 和启动时自动保存的登录备份共用，不要手动改或删，要清就用 `browser_login({action:"drop"})`。`chrome/` 其余部分是浏览器进程自己在读写，不要手动改；要清登录态，用 `browser_open` 的档位或插件自己的入口，别删目录里的某个文件。上面这些都在一个根目录下，卸载插件前想留产出就拷 `artifacts/`。
+`chrome/session-cookies.json` 是 Chrome 退出时会丢的会话 cookie，加密后存在 profile 旁边；`logins/` 与 `vault.key` 由 `browser_login` 和启动时自动保存的登录备份共用，不要手动改或删，要清就用 `browser_login({action:"drop"})`。`chrome/` 其余部分是浏览器进程自己在读写，不要手动改；要清登录态，用 `browser_open` 的档位或插件自己的入口，别删目录里的某个文件。
 
 测试里用 `DSH_INNER_BROWSER_ARTIFACTS` 指向临时目录，不写真实 home。

package/docs/BENCH.md

@@ -1,3 +1,19 @@
+## 读过的站第二次更便宜（0.45.0，本地页面，`scripts/check-sites.mjs`）
+
+同一台机器、无头 Chrome、两个本地 origin。第一次走老路（整页读），第二次之后用学到的默认值。
+所有数字来自一次真实运行，不是估算。
+
+| 页面 | 第一次 | 学到之后 | 省下 | 说明 |
+| --- | --- | --- | --- | --- |
+| 300 个按钮的页面，`browser_view` | 1801 字符 | 760 字符（`map: 90 controls`） | 58% | 两次之后自动改成地标视图，并说明「this site reads big」 |
+| 12000 字文档，`browser_read` | 6096 字符（满预算） | 3726 字符（截到 3500） | 39% | 截断处自带 `cut at 3500 characters`，用 `max_chars` 可要全文 |
+
+- 学的尺子量的是页面本身，不是这次输出：`read.js` 的 `chars` 在截断前取值，所以第一次就把整篇长度记下来，不会被 3500 的预算越读越小
+- 显式 `mode` / `query` / `max_chars` 一律优先；学到的是默认值，附一句带数字的理由
+- 记录写在 `sites.json`，每进程最多每 2 秒一次；两次运行之间只留计数，不留正文
+- `scripts/check-look.mjs`：12×8 的字母网格，三次看共 639 字符，全程没有图片 token
+- `scripts/soak.mjs`：无头浏览器 24 轮开页/读页/截图/重读，34.9 秒，进程树内存 1440 → 1287 MB（−153 MB），页数始终 1，8 次截图、24 次读；没有页签或内存随轮数上涨
+
 ## 读页先读正文（0.44.0，本地页面，`scripts/bench.mjs`）
 
 同一台机器、同一档预算。旧法是按页面顺序把预算灌满的整页读。
@@ -1014,3 +1030,23 @@ not.
 | frame size, JPEG q72 | 96–103 KB |
 | mirror SSE | 15 fps（66 ms 一轮），4 s 收 60 帧，均值 97.8 KB |
 | switch cost | 一次浏览器重启（`browser_open({flash:true})` → `browser_open({flash:false})`） |
+
+## Phase 24 — 长期运行的资源回收，0.46.0
+
+一台窗口隐藏的 Chrome 空转一晚就是几百 MB。这一版把「多久收」交给用法自己决定：记住这个人
+最近 64 次调用之间的间隔，取 95 分位，休息乘 6、可逆停驻乘 2，各自夹在上下限里；有人看时
+永不关闭、只冻结。关闭与启动串行，避免休息和下一次调用撞在一起。
+
+| what | measured |
+| --- | --- |
+| 20 次调用、间隔 20 秒 | p95 20 s → 休息 120 s，停驻 40 s |
+| 30 次调用、间隔 90 秒 | p95 90 s → 休息 540 s，停驻 180 s |
+| 没有历史的新进程 | 用下限：休息 90 s，停驻 20 s |
+| 右栏关掉（`/sidecar/forget`） | 60 s 后休息，内存归零 |
+| 唤醒 | 326–1010 ms，回到同一页同一地址 |
+| soak 24 轮＋3 次真实休息 | 40.1 s，内存 1427 → 956 MB，页数始终 1 |
+| soak 16 轮＋2 次真实休息 | 26.8 s，内存 1308 → 900 MB |
+| 休息与调用相撞 | 关闭单飞、启动等待；0.45.0 会在第 8 轮把新连接关掉（已复现、已修） |
+| 内存预算 | 2400 MB / 30 s 一次称重；超预算先收 LRU 页签、降码率，无人看才休息 |
+| 崩溃循环 | 10 分钟内 3 次 → 拒绝启动并说明原因 |
+| suite | 42 pass（sidecar）· rest 9 pass · soak/rest 端到端全过 |

package/docs/FLASH.md

@@ -56,6 +56,16 @@ Electron 11 的两个真实限制，代码里已按它们写：
 - 它不会用当前 Chrome 的 profile 目录（会降级并上锁），Flash 分支固定用 `<profile>-flash` 独立目录；两边登录态各自独立。
 - `/json/new` 在 Chromium 87 上是 404，单窗口应用也没有第二个窗口，所以 Flash 分支不建新页签：会话要页签时把唯一那个窗口导航过去。
 
+### 起来之后还要证明它真在
+
+端口能连上不等于插件装上了：`/json/version` 由浏览器进程回答，插件加载失败时它照样 200，页面只是画出一块黑。所以启动流程在端口就绪之后还问页面一句 `navigator.plugins`，只认名字里带 `Shockwave Flash` 的那条，结果存成浏览器自己的状态：
+
+- `browser_open` 在正文里给一行 `flash runtime: plugin loaded (Shockwave Flash)`，或者 `open, but no Flash plugin is loaded — movies will not play; run scripts/flash-setup.mjs`；还没问到时写 `plugin not checked yet`，不猜。
+- `browser_state` 的运行时行把「模式」和「插件」分开：`Flash-era runtime — plugin loaded (…)` / `— no Flash plugin is loaded`。
+- `browser_prepare` 在真的找到 movie、但插件缺失时补一句「它们跑不起来」，免得把黑帧当成游戏还在加载。
+
+问不到（页面崩溃、CDP 早断）时记 `null`——没有证据就不下结论，这跟「没装运行时」是两回事：后者在启动阶段就抛 `sidecar: no Flash runtime on this machine`。
+
 实测数字（Apple 芯片 + Rosetta，1440×900）：
 
 | 指标 | 值 |

package/docs/RESOURCES.md

@@ -0,0 +1,83 @@
+# Long-term resources: what keeps a browser cheap when nobody is looking
+
+A sidecar is only worth keeping if leaving it open overnight costs nothing. This
+document describes the ladder a browser steps down when it goes unused, how the
+timings are chosen, and how the same problem is solved by the four projects a
+person is most likely to compare this plugin to.
+
+## The ladder
+
+| step | when | what happens | cost while parked |
+| --- | --- | --- | --- |
+| `awake` | calls are arriving, or someone is watching the mirror | nothing | one headless Chrome |
+| `quiet` | no call for a while, but a pane still shows the page | screencast stopped, page frozen (`Page.setWebLifecycleState`) | JS/timers paused, DOM and cookies kept, still one process tree |
+| `rest` | no call for a while and no pane watching | cookies saved, `Browser.close`, whole tree gone | zero |
+
+The rest step is what the pane closing at `x` earns: the plugin tells the
+sidecar the mirror is gone, and if nobody else is watching it arms a one-minute
+rest. A chat that never closed its pane still gets the quiet step, which is
+reversible and keeps the page exactly where the person left it.
+
+## Choosing the timings without guessing
+
+Fixed timeouts are wrong in both directions: too short and every pause pays a
+cold start, too long and an abandoned browser outlives the work. The rest and
+quiet windows are therefore derived from what the user actually did in this
+process. `rest.js` keeps the last 64 gaps between calls, takes the 95th
+percentile, and multiplies it:
+
+```text
+rest  = clamp(p95(gaps) × 6,  90 s, 15 min)
+quiet = clamp(p95(gaps) × 2,  20 s,  2 min)
+```
+
+A person clicking every two seconds gets a two-minute rest; one coming back
+every ninety seconds gets nine minutes. Gaps longer than the maximum rest are
+treated as a new session, not as evidence. With no history at all the floors
+apply, so a fresh process parks quickly instead of waiting for a pattern that
+does not exist yet.
+
+The decision itself is a pure function of four numbers — now, last use, the
+rest deadline, and how many mirrors are watching — which is what makes it
+testable without a browser (`test/rest.test.mjs`). The watched count wins over
+the deadline: a pane on screen always means `quiet` at most, never `rest`.
+
+## Memory pressure
+
+Timings are the first line; memory is the second. Every 30 s the sidecar weighs
+the whole process tree and compares it with a budget (2400 MB by default,
+`DSH_INNER_BROWSER_MEMORY_MB`). Over budget while a pane is open, it stops
+screencasts and reclaims unused tabs (LRU, pinned pages excluded). Over budget
+again with nobody watching, it puts the browser away on the spot rather than
+waiting for the clock. Being over once is not enough to close a browser the
+person is looking at.
+
+## What breaks a long run, and what is done about it
+
+| failure | response |
+| --- | --- |
+| a rest and the next call arrive together | `shutdown()` is single-flight and `launch()` awaits the outgoing browser, so a fresh socket is never closed by the one leaving |
+| the browser dies three times in ten minutes | the crash-loop guard refuses to start it again and says why, instead of spinning |
+| a tab is left in a chat that stopped using it | 10-minute LRU, skipped while it streams or holds a popup |
+| the last call was minutes ago but the pane is open | freeze, not close: scroll position, DOM and sign-ins are still there on wake |
+
+## Neighbours
+
+Compared with the projects this one is usually put next to (`--idle-timeout`,
+`keep_alive`, and their documentation):
+
+| project | idle handling | what a wake costs | notes |
+| --- | --- | --- | --- |
+| Playwright MCP | one flag, `--idle-timeout`, default one hour for headless, whole browser closed | a cold start | no viewer awareness; each client gets its own Chrome; `src/` is no longer in the repository |
+| Chrome DevTools MCP | none — the browser lives until the process exits | n/a | one dispose chain, no idle clock, screencast never pauses for a detached viewer |
+| browser-use | `keep_alive` flag, no timeout value | n/a | teardown skipped while `keep_alive`; no idle timer, no memory policy |
+| Stagehand | none | n/a | deliberately disables Chrome's background throttling, then tears down and removes the profile |
+| this plugin | viewer-aware ladder, timings learned from use, memory pressure, single-flight close | 0.3–1.1 s, same page and address | freeze keeps the DOM; rest keeps the cookies; nothing cold-starts unless the process is new |
+
+The gaps that remain in the field, and that this document treats as the design
+brief: nobody freezes a page instead of closing it; nobody pauses a screencast
+because the viewer looked away; cold restart is the documented recovery
+everywhere; tab caps and LRU are left to the caller; memory is a diagnostic
+rather than a policy; multi-agent isolation is all-or-nothing. Those are the
+five places where this plugin is deliberately ahead rather than equal — see
+`docs/ARCHITECTURE.md` and `docs/BENCH.md` for the measured side of it.

package/docs/VERIFY.md

@@ -97,6 +97,67 @@ still hold the cookies.
   内置浏览器 means the page half is stale: reload the GUI page.
 - Guest-era logins are not migrated; sign in once in the new profile.
 
+## 7. A page that draws itself
+
+```bash
+node scripts/check-look.mjs
+```
+
+Headless Chrome paints a page, `browser_look` returns a 12×8 letter grid, the page
+paints a red square, and the second look names only the cells that moved. Expected:
+`three looks cost 639 characters and no picture`. A look that returns words instead
+of a grid, or a diff of the whole screen, means the PNG was not decoded locally.
+
+## 8. The next visit is cheaper
+
+```bash
+node scripts/check-sites.mjs
+```
+
+Two local origins: a page of 300 buttons and a 12,000-character document. Expected,
+in order: the first view is the page, the second is still the page (one read is not a
+lesson), the third opens as `map: 90 controls` and says `this site reads big (2 read(s),
+~2946 chars of page, ~90 controls)`; the first document read is the whole thing (6,096
+characters), a forced second read is the whole thing again, and the third comes back
+`cut at 3500 characters` with `this site reads long (2 read(s), ~6000 chars of text)`.
+The run ends with `sites: ok` and leaves `sites.json` in a temporary directory.
+
+A third view that is still the page, or a third read that is not cut, means the record
+is written after the default is chosen, or the size recorded is the output's rather
+than the page's: a cut must not shrink the site for the next visit.
+
+## 9. It does not grow
+
+```bash
+npm run soak
+```
+
+Twenty-four cycles of open, read, snapshot, re-read through one headless browser,
+and every eighth cycle the browser is really put away and woken again.
+Expected: `soak: ok · 24 cycles` with `pages 1`, memory lower at the end than at
+the start, and a summary naming at least one rest (`3 rests` here, 1427 → 956 MB
+in 40.1 s). Memory climbing with the cycle count, a second page appearing, or a
+rest that leaves memory held means something is kept per read rather than per
+page, or the rest does not close the whole tree. The run is bounded on purpose —
+under a minute, no internet.
+
+## 10. It comes back where it was
+
+```bash
+npm run rest
+```
+
+A headless sidecar is told to rest 1.2 s after the last call. Expected chain:
+`browser_state` says `rests in`, then `stopped` with `memory 0 MB` once the rest
+lands; touching the browser again wakes it on its own, `pageFor(session).url` is
+still the page that was open, the text is either the same paragraph or
+`nothing changed since the last read`, and the wake takes under 4 s. `rest and
+wake hold.` is the bar.
+
+A rest that never happens while nobody is watching means the watched count is
+not reaching the clock; a wake that lands on a blank tab means the page-per-chat
+map was dropped by the close instead of being restored by the launch.
+
 ## Live
 
 `node scripts/live.mjs` does the same work on the open internet, with no local

package/index.js

@@ -947,7 +947,7 @@ export function apply(ctx) {
         '页面很长、只想确认某句话/按钮在哪时用 `browser_find`，别整页读。要读长文（文章、文档、issue、论坛帖）用 `browser_read`：它回 Markdown，只花几十分之一的 token，链接可点；要动手点、填表才用 `browser_view` 拿编号。',
         '要保存页面样子用 `browser_shot`，它会给出 PNG 绝对路径；要交给人看的文件，把绝对路径写进回复。',
         '页面放视频或音乐、人想留下它时用 `browser_media`：它列的是页面自己已经请求过的媒体（带大小），页面自己播放器里那个标 `main` 排第一，广告和统计请求默认不出现（`all:true` 才看），`save: main` 存第一个；视频是流的话会顺着播放列表把片段取回拼成整段，不用装 yt-dlp 或 ffmpeg。先让页面播一下再列，播放请求才是文件。不想要这个页面的记录就 `watch:false`。',
-        '游戏、canvas、Flash：画面自己画的地方，`browser_view` 和 `browser_read` 读不出里面是什么。先 `browser_prepare` 拿画面位置、帧率、按键是否到达和下一步；之后看 `browser_shot` 的图定位置，按坐标点、按住、按组合键，再拍一张看画面变了没有——变了就是这一步生效了。当年用 Flash 做的游戏用 `browser_open` 带 `flash:true` 在栏内跑，不装播放器、不开窗口；Flash 默认关，`flash:true` 开、`flash:false` 回到普通 Chrome，两边都只在本会话右栏。',
+        '游戏、canvas、Flash：画面自己画的地方，`browser_view` 和 `browser_read` 读不出里面是什么。先 `browser_prepare` 拿画面位置、帧率、按键是否到达和下一步；之后用 `browser_look` 读屏：它把画面压成字母网格、点完再看一次只报变了哪块，不花图片 token；要定位置或看颜色再 `browser_shot`。按坐标点、按住、按组合键后先 `browser_look` 确认这一步生效，别每步截图。当年用 Flash 做的游戏用 `browser_open` 带 `flash:true` 在栏内跑，不装播放器、不开窗口；Flash 默认关，`flash:true` 开、`flash:false` 回到普通 Chrome，两边都只在本会话右栏。',
       ].join('\n'),
     }), 'dsh-inner-browser-use: system prompt section')
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-inner-browser-use",
-  "version": "0.44.0",
+  "version": "0.46.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",
@@ -14,10 +14,12 @@
   "files": [
     "index.js",
     "sidecar.js",
+    "rest.js",
     "tools.js",
     "read.js",
     "review.js",
     "media.js",
+    "pixels.js",
     "vault.js",
     "chromecookies.js",
     "client.js",
@@ -29,6 +31,10 @@
     "scripts/check-flash-mirror.mjs",
     "scripts/check-flash-local.mjs",
     "scripts/check-flash-tools.mjs",
+    "scripts/check-look.mjs",
+    "scripts/check-sites.mjs",
+    "scripts/soak.mjs",
+    "scripts/check-rest.mjs",
     "runtime/",
     "docs/",
     "README.md",
@@ -51,7 +57,7 @@
     "dsh": ">=0.2.0"
   },
   "scripts": {
-    "test": "node --test test/artifacts.test.mjs test/client.test.mjs test/cookies.test.mjs test/diff.test.mjs test/fresh.test.mjs test/host.test.mjs test/input.test.mjs test/isolation.test.mjs test/keyboard.test.mjs test/leak.test.mjs test/login.test.mjs test/media.test.mjs test/no-duplicate.test.mjs test/package.test.mjs test/blocks.test.mjs test/readfault.test.mjs test/refs.test.mjs test/review.test.mjs test/session.test.mjs test/settle.test.mjs test/sidecar.test.mjs test/swf.test.mjs test/tabs.test.mjs test/trouble.test.mjs test/vault.test.mjs",
+    "test": "node --test test/artifacts.test.mjs test/client.test.mjs test/cookies.test.mjs test/diff.test.mjs test/fresh.test.mjs test/host.test.mjs test/input.test.mjs test/isolation.test.mjs test/keyboard.test.mjs test/leak.test.mjs test/login.test.mjs test/media.test.mjs test/no-duplicate.test.mjs test/package.test.mjs test/blocks.test.mjs test/rest.test.mjs test/readfault.test.mjs test/refs.test.mjs test/review.test.mjs test/session.test.mjs test/settle.test.mjs test/sidecar.test.mjs test/swf.test.mjs test/tabs.test.mjs test/trouble.test.mjs test/vault.test.mjs",
     "doctor": "node scripts/doctor.mjs",
     "breadth": "node scripts/breadth.mjs",
     "live": "node scripts/live.mjs",
@@ -65,7 +71,11 @@
     "flash-mirror": "node scripts/check-flash-mirror.mjs",
     "flash-tools": "node scripts/check-flash-tools.mjs",
     "flash-local": "node scripts/check-flash-local.mjs",
-    "keys": "node scripts/keyboard.mjs"
+    "keys": "node scripts/keyboard.mjs",
+    "look": "node scripts/check-look.mjs",
+    "sites": "node scripts/check-sites.mjs",
+    "soak": "node scripts/soak.mjs",
+    "rest": "node scripts/check-rest.mjs"
   },
   "license": "MIT",
   "author": {