dsh-browser-playwright-codex 0.6.5 → 0.6.6

package/CHANGELOG.md

@@ -3,6 +3,34 @@
 Bilingual by intent: the version headings and the summary of each release are given in both
 languages, the individual entries follow the language the surrounding code and docs use.
 
+## 0.6.6 — 2026-10-17
+
+一句话摘要：**四份独立审查（文档漂移 / 代码对抗 / 发行打包 / 中性冷读）查出的问题集中修掉**——两条安全缺陷、几处"假成功/假失败"、随包自检的假承诺、发布门禁漏洞与一批文档漂移。
+
+### Security
+
+- **点击白名单可被祖先 `<a>` 绕过**：`browser_click` 的 `ref` / `text` / `precise` 三条路径只校验**被点元素自身**的 href，外层 `<a href="http://外站/">` 包住它时点击会导航到站外并返回成功。现在改为「自身 → 最近祖先 `<a href>`（穿 shadow host）」，与裸坐标路径同层，统一交给 URL 策略。两处独立审查各自用本地 fixture 复现过。
+- **密码/验证码/卡号曾进入 prompt**：`browser_extract` 把 `pageData()` 拼进辅助模型的 prompt，而 `pageData()` 采集输入框**当前值**——登录页的明文密码会随请求发出去（实测 prompt 里出现 `hunter2`）。现在 `type=password` 与 `autocomplete` 为 `current-password` / `new-password` / `one-time-code` / `cc-number` / `cc-csc` / `cc-exp` 的字段一律置空值，**字段本身保留**（模型仍知道"这里有个码要填"）。
+
+### Fixed
+
+- **填表核对两头错**：上一版把回读改成严格相等后，页面自动改写格式的输入框（全大写、千分位 `1,000`）被误判成"没写进去"，而 `browser_fill` 的描述恰恰把 input-mask / currency 列为预期场景；更早的版本则相反，`ABCD→ZZZZ`、`John→Jane` 会被判成功。现在的归一化只放过"页面改写、不是我们写错"：NFKC + 去大小写 + 去掉非字母数字；`1000≡1,000`、`abc≡ABC` 通过，`ABCD↔ZZZZ`、`1234↔12345` 仍然失败。contenteditable 也不再假失败（改读 `textContent`/`innerText`）。
+- **挑战页识别的两处回归**（本轮自查引入的）：给控件层加"页面得够空"的门控后，**正常登录页里嵌的真 reCAPTCHA / hCaptcha / Turnstile 完全不再识别**（登录页正是主要场景），已移除该门控；`CAPTCHA_ROLES` 曾删掉 `iframe`，导致名字就叫「验证码」的非厂商 iframe 不被识别，已恢复。
+- **`[nothing here]` 提示三类误报**：静默页扫描深度 4 → 8 层（正文藏得深的正常页曾被判"几乎没有文字"，与同一结果树里的正文自相矛盾）；无标题的裸文档（`about:blank`、直接打开图片）不再提示；有挂起弹窗时不出这条（否则与 `[dialog]` 指令冲突）。
+- **提示互斥**：已判定为拦截页时不再叠 `[http NNN]`；已识别为挑战时不再叠行为兜底提示。
+
+### Added
+
+- **测试 159 → 220**（+61）：挑战识别 50 条（含真实页面测得的门控数值与反例：讲 hCaptcha 的文章、`验证码说明` 帮助链接、`获取验证码` 按钮、百度搜索页标题）、真浏览器端到端 6 条（真实 `cf-mitigated` 头、无签名拦截面被行为兜底抓住、`interactiveOnly` 下 iframe 仍识别、单页应用改 URL 后旧响应头不复用、真实 404 显示状态码、真实访客门显示静默页提示）、安全回归 5 条（外链祖先点击被拒、密码/OTP 不进 prompt、contenteditable 成功、同长度不同值失败）、本机路径守卫。
+
+### Changed
+
+- **随包自检不再在 npm 安装形态崩溃**：`scripts/dsh-browser-verify.mjs` 的「`lib/` 与 `src/` 同步」一组在没有 `src/` 时**跳过**并打印说明，退出码 0 —— 安装形态显示「全部通过 (56 项，跳过 1 项)」，仓库形态仍是「(57 项)」。README / CHANGELOG 此前承诺的"装上即可跑"现在才真的成立。
+- **依赖不再全是 `*`**：`@deepseek-ai/schemastery` 固定 `^3.18.4`，peer `cordis >=4.0.4`、`dsh-llm` / `dsh-tools >=0.2.0-rc.1`。修前空项目安装会解析到 `dsh-tools 0.0.1-rc.1`、`dsh-llm 0.0.1-rc.5`（远旧于测试基线）；修后解析到 `0.2.0-rc.2`。代价：不同版本元组的预发布版（如 `0.2.1-rc.*`）会收到 **peer 警告**（不是失败，pnpm 默认不严格）。
+- **发布门禁补齐**：CI 增加 `npm run typecheck` 与 `npm run preflight`（与 `prepublishOnly` 对齐）；CI 与 publish 都新增「`npm run build` + `git diff --exit-code -- lib`」守卫——以前先 build 再比 mtime，`src` 改完忘重建也能全绿，而 `dsh plugin add github:…` 的安装路径会拿到旧 `lib/`。
+- **文档漂移**：独立审查列出 13 条硬错误 / 11 条过期 / 8 条矛盾 / 8 条缺失，全部修掉——随包文档死链由 12 条清零（改 GitHub 绝对链接）、测试计数与成本数字按实际命令重取、`npm test:live` 与 `browser-plugin/dev.cordis.yml` 这类跑不通/不存在的引用纠正、URL 白名单不再声称覆盖 `hover`（实际不覆盖）、补写 `snapshot.engine` 说明，并在 `中文说明.md` 新增 **§4.14 挑战页识别**（四层判定与两条结果提示，明确"产出提示不是阻断，认不出来就停下来问人"）。许可表述收敛为：代码与说明文档 MIT，CC BY-NC-SA 仅限 `FOCUS-STEALING.md` / `MODE-TRADE-OFFS.md` 两篇分析长文。
+- **`.gitignore` 补登录态**：`dsh-storage-state.json` / `browser-profiles/` / `profile/`。默认写在 `~/.dsh/browser-profiles/`（仓库外），但只要有人把 `launch.profileDir` 指进 checkout，那个文件里就是明文 cookie。
+
 ## 0.6.5 — 2026-10-16
 
 一句话摘要：**挑战页识别不再靠一份关键词表** —— 判定改成「厂商自有的机器信号优先，认不出来就问一句『页面变了吗』」，所以新出现的验证方式也能被接住；顺带清掉漏网的 4 处本机路径，并把 npm 包里 12 个用不上的开发脚本收成 2 个。

package/NOTICE.md

@@ -6,26 +6,25 @@ This repository mixes work from three different origins. They are **not** under
 
 ## 1. The plugin — MIT (`./LICENSE`)
 
-Covers everything that is part of the plugin: `src/`, `tests/`, `scripts/`, `cordis.patch.yml`, `tsconfig.json`, `package.json`, `CHANGELOG.md`, and the plugin's own documentation (`PLUGIN-README.md`, `DIALOG-POLICY.md`, `SAFETY-RULES.md`, `SNAPSHOT-RULES.md`, `codex-rules.md`).
+Covers everything that is part of the plugin: `src/`, `tests/`, `scripts/`, `cordis.patch.yml`, `tsconfig.json`, `package.json`, `CHANGELOG.md`, and the plugin's own documentation (`README.md`, `SECURITY.md`, `NOTICE.md`, `PLUGIN-README.md`, `DIALOG-POLICY.md`, `SAFETY-RULES.md`, `SNAPSHOT-RULES.md`, `codex-rules.md`, `中文说明.md`, `对比与优势.md`, and the articles under `docs/articles/`).
 
 | Origin | What | Licence |
 |---|---|---|
 | [ChenyuHeee/dsh-browser-playwright](https://github.com/ChenyuHeee/dsh-browser-playwright) v0.1.1 | The accessibility-snapshot engine (`src/injected.ts`, `src/snapshot-render.ts`), the tool family (`src/tool.ts`), the service/provider seams (`src/service.ts`, `src/playwright.ts`), the URL policy, and the test-suite shape. Copyright (c) 2026 dsh-browser-playwright contributors. | **MIT** |
-| This fork's merged layer | Geometric click (`browser_click` with `precise: true`) with landing-element reporting, the CDP policy layer (`src/cdp-policy.ts`), the persistent profile + login-state export (`src/runtime-state.ts`, `persistState`/`restoreState`), dialog parking, the console/network diagnostics tools, the contract/compat modules, and the fixes listed in [`CHANGELOG.md`](CHANGELOG.md) | **MIT** |
+| This fork's merged layer | Geometric click (`browser_click` with `precise: true`) with landing-element reporting, the CDP policy layer (`src/cdp-policy.ts`), the persistent profile + login-state export (`src/provider.ts`, `persistState`/`restoreState`), dialog parking, the console/network diagnostics tools, the contract/compat modules, and the fixes listed in [`CHANGELOG.md`](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/CHANGELOG.md) | **MIT** |
 
 **Why the plugin cannot be non-commercial:** it is a derivative of MIT-licensed work. MIT grants everyone the right to use, modify and redistribute the software **including commercially**, and a redistributor cannot add a non-commercial restriction to it. Any non-commercial claim over `src/` would be an unauthorised restriction — worse for downstream users than leaving it MIT. The MIT text in `./LICENSE` (including the upstream copyright notice) is unchanged.
 
 ## 2. This repository's analysis prose — CC BY-NC-SA 4.0 (`./LICENSE-DOCS`)
 
-Covers only the writing produced *for this repository*:
+Covers only the two analysis documents produced *for this repository*:
 
-- `README.md` (this repository's landing page)
 - `FOCUS-STEALING.md`
 - `MODE-TRADE-OFFS.md`
 
-Share and adapt for **non-commercial** purposes with attribution and share-alike; commercial use is not permitted. Legal code: [`LICENSE-DOCS`](LICENSE-DOCS).
+Share and adapt for **non-commercial** purposes with attribution and share-alike; commercial use is not permitted. Legal code: [`LICENSE-DOCS`](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/LICENSE-DOCS) (the licence text lives in the repository; it is not part of the npm tarball).
 
-Note the deliberate boundary: the plugin's *own* documentation is not in this set — it ships with the plugin under MIT, so that the whole plugin stays redistributable on MIT terms.
+Note the deliberate boundary: these two documents are **not shipped in the npm package** — only `README.md`, `CHANGELOG.md`, `SECURITY.md` and `NOTICE.md` travel with the plugin, and all four are MIT (§1). So everything an npm installer actually receives stays redistributable on MIT terms.
 
 ## 3. Third-party content that is **not** redistributed here
 

package/README.md

@@ -2,12 +2,13 @@
 
 > [![dsh.so 安装验证 · harness 0.2.0-rc.1](https://www.dsh.so/badge/install/dsh-browser-playwright-codex@0.2.0-rc.1.svg)](https://www.dsh.so/zh/artifact/dsh-browser-playwright-codex/) [![dsh.so 风险](https://www.dsh.so/badge/dsh-browser-playwright-codex.svg)](https://www.dsh.so/zh/artifact/dsh-browser-playwright-codex/)
 
-**一句话**：让 AI 用你**已经登录的账号**在真实网页上干活 —— 填表、抓取列表、多标签查后台；浏览器窗口就在你桌面上、你随时看得见；遇到登录、验证码、原生弹框，它会**停下来等你**，绝不替你点「确定」。
+**一句话**：让 AI 用你**已经登录的账号**在真实网页上干活 —— 填表、抓取列表、多标签查后台；浏览器窗口就在你桌面上、你随时看得见。原生弹框会被挂起、**绝不替你点「确定」**；验证码/登录页会被识别出来并把情况报给你、请你本人接手（识别不出来时也会停下来问人，而不是硬闯）。
 
 **In one line**: the agent drives a **visible, profile-backed browser window** with the logins you
 already have — filling in forms, scraping lists and working across tabs in real pages — through
-accessibility snapshots with stable element refs, and it stops for logins, captchas and native dialogs
-instead of guessing. No CSS-selector guessing, no full-DOM dumps.
+accessibility snapshots with stable element refs. Native dialogs are parked and reported instead of
+auto-accepted; a login, 2FA or challenge page is handed back to you rather than guessed at. No
+CSS-selector guessing, no full-DOM dumps.
 
 ```sh
 # from npm
@@ -22,14 +23,16 @@ dsh plugin --profile <name> add github:miqian-nomad/dsh-browser-playwright-codex
 - **登录一次，一直用** — a profile-backed window plus an exported session state, so a closed window or
   a restarted harness comes back logged in.
 - **全程看得见，也不抢你的焦点** — a real window you can watch, minimise or take over; the provider
-  keeps working while it is minimised ([FOCUS-STEALING.md](FOCUS-STEALING.md)).
+  keeps working while it is minimised ([FOCUS-STEALING.md](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/FOCUS-STEALING.md)).
 - **遇事停下来叫人** — `alert` / `confirm` / `prompt` are parked and reported, answered only by an
-  explicit `browser_dialog` call; a login, 2FA or captcha is handed back to you
-  ([DIALOG-POLICY.md](DIALOG-POLICY.md)). A challenge page is recognised from the interceptor's own
-  response headers first (`cf-mitigated: challenge` and friends), then from its widget, and only then
-  from wording; if none of those match, a page that stops changing after an action is reported as a
-  possible wall instead of being retried
-  ([docs/articles/dialogs-and-captcha.md](docs/articles/dialogs-and-captcha.md)).
+  explicit `browser_dialog` call ([DIALOG-POLICY.md](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/DIALOG-POLICY.md)).
+  A challenge page is recognised from the interceptor's own response headers first
+  (`cf-mitigated: challenge` and friends; `x-iinfo` / `x-datadome*` additionally need a blocking
+  status), then from the vendor widget's accessible name, then from wording; if none of those match,
+  a page that stops changing after an action is reported as a possible wall instead of being retried.
+  Recognition adds a note that tells the agent to stop and hand the window back to you — that note is
+  advice to the model, not a hard block; the mechanism-level guarantee exists for native dialogs only
+  ([docs/articles/dialogs-and-captcha.md](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/docs/articles/dialogs-and-captcha.md)).
 - **ref 失效会明说** — per-document nonce refs; a stale ref fails fast with an explanation instead of
   silently clicking a different element.
 - **强力工具默认关闭** — `browser_evaluate` / `browser_cdp` are **not registered at all** unless your
@@ -37,9 +40,11 @@ dsh plugin --profile <name> add github:miqian-nomad/dsh-browser-playwright-codex
 
 **安全一览 / Security at a glance** — dsh.so's scanner flags this repository's **one Critical finding**, and that finding **is** the
 implementation of `browser_evaluate` (its dynamic evaluation), which this package ships switched off.
-[SECURITY.md](SECURITY.md) maps every finding to the gate that contains it, and explains what the plugin
-can and cannot do with your logins (URL policy, CDP allow-list, dialog policy, no telemetry, and it never
-types passwords or 2FA codes). Counts move as the scanner and the code change — their own report is the
+[SECURITY.md](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/SECURITY.md) says what each
+finding actually is, whether a capability gate makes it reachable (two of the warnings are not gate-controlled:
+the login-state write and the local test server in the acceptance script), and explains what the plugin can and
+cannot do with your logins (URL policy, CDP allow-list, dialog policy, no telemetry, and it never types
+passwords or 2FA codes). Counts move as the scanner and the code change — their own report is the
 live number.
 
 ## Install
@@ -59,9 +64,15 @@ dsh plugin --profile <name> add github:miqian-nomad/dsh-browser-playwright-codex
 dsh plugin --profile <name> add link:<absolute path to this directory>
 ```
 
-**Compatibility.** Built and tested against DSH `0.2.0-rc.1` (`@deepseek-ai/*` peer ranges are deliberately
-`*` so a newer harness still installs). After a harness upgrade, `npm run doctor` re-checks that every named
-export this plugin imports still exists — that is the fast way to tell "the harness moved" from "the plugin broke".
+**Compatibility.** Built and tested against DSH `0.2.0-rc.1`. The dependency ranges are **floors, not
+wildcards**: peers `@deepseek-ai/cordis` `>=4.0.4`, `@deepseek-ai/dsh-llm` `>=0.2.0-rc.1`,
+`@deepseek-ai/dsh-tools` `>=0.2.0-rc.1`, and the direct dependency `@deepseek-ai/schemastery` `^3.18.4`. The
+floors exist so an empty project cannot resolve a very old `0.0.1-rc.*` build, while a newer harness still
+installs. One cost of npm's prerelease rules: a prerelease whose `[major, minor, patch]` tuple differs from
+`0.2.0` (for example `0.2.1-rc.*`) is outside a `>=0.2.0-rc.1` range, so you may see a **peer warning** — a
+warning, not an install failure (pnpm does not enforce peer ranges strictly by default). After a harness
+upgrade, `npm run doctor` re-checks that every named export this plugin imports still exists — that is the
+fast way to tell "the harness moved" from "the plugin broke".
 
 `lib/` ships in the repository (and there is deliberately no `prepare` hook), so a fresh clone loads
 without a build step — `npm run build` is only needed after editing `src/`.
@@ -80,8 +91,9 @@ Install it and ask for something that leaves a visible result — there is nothi
 
 What you should see: a real browser window on your desktop doing the clicking, and the page coming back to
 the model as a `ref`-numbered list. The first time it meets a sign-in, a 2FA prompt or a verification page
-it **stops and tells you** — take the window over by hand and it continues from where it left off. The
-logins already in that profile are what make the rest work.
+it **reports the page back to you** — take the window over by hand and it continues from where it left off.
+Native dialogs are the one case that is enforced at the interface: they are parked and never auto-accepted.
+The logins already in that profile are what make the rest work.
 
 Two habits worth having on day one:
 
@@ -104,7 +116,7 @@ Or pin a binary: `launch.executablePath` / `launch.channel` in the plugin config
 
 ## Tools
 
-The default `toolPrefix` is `browser_`. Every action returns a fresh snapshot, so refs always come from the latest result. The registered set is capability-gated: `browser_evaluate`, `browser_cdp` and `browser_extract` appear only when their capability is switched on (their schemas are resident in the system prompt on every turn, so a tool that could only answer "disabled" would be pure prompt cost). Count the live surface with `npm run cost` — the shipped `cordis.patch.yml` keeps **both power gates off** (since 0.4.7), so a profile mounting this bundle sees **18 tools**; 19 or 20 once your deployment opts into `evaluate` / `cdp`, 21 once `extract` is configured. How to opt in: [SECURITY.md](SECURITY.md) §1.
+The default `toolPrefix` is `browser_`. Every action returns a fresh snapshot, so refs always come from the latest result. The registered set is capability-gated: `browser_evaluate`, `browser_cdp` and `browser_extract` appear only when their capability is switched on (their schemas are resident in the system prompt on every turn, so a tool that could only answer "disabled" would be pure prompt cost). Count the live surface with `npm run cost` — the shipped `cordis.patch.yml` keeps **both power gates off** (since 0.4.7), so a profile mounting this bundle sees **18 tools**; 19 or 20 once your deployment opts into `evaluate` / `cdp`, 21 once `extract` is configured. How to opt in: paste the snippet under Known Limitations below, or use the settings card in `dsh-browser-toggle`.
 
 | Tool | Purpose |
 |---|---|
@@ -118,10 +130,10 @@ The default `toolPrefix` is `browser_`. Every action returns a fresh snapshot, s
 | `browser_wait` | Wait a bounded duration for lazy content |
 | `browser_tabs` / `browser_open_tab` / `browser_switch_tab` / `browser_close_tab` | Tab management; `browser_tabs` marks the `[active]` tab the other tools act on |
 | `browser_screenshot` | PNG capture stored as a durable image attachment the model can view |
-| `browser_extract` | Structured extraction: natural-language instruction → one parsed JSON value | **Only registered when enabled.**
-| `browser_evaluate` | Run one JavaScript expression in the page (disabled by default) | **Only registered when enabled.**
+| `browser_extract` | Structured extraction: natural-language instruction → one parsed JSON value; **only registered when its capability is enabled** |
+| `browser_evaluate` | Run one JavaScript expression in the page (disabled by default); **only registered when its capability is enabled** |
 | `browser_dialog` | Answer the native dialog blocking the page: `{ accept: true }` confirms, `false` cancels; errors with `NO_DIALOG` when nothing is pending |
-| `browser_cdp` | Send one raw CDP command (DOM inspection / Input simulation allow-list only; disabled by default) | **Only registered when enabled.**
+| `browser_cdp` | Send one raw CDP command (DOM inspection / Input simulation allow-list only; disabled by default); **only registered when its capability is enabled** |
 | `browser_close` | Close the session's browser window; the profile keeps login state, so the next call reopens signed in |
 | `browser_console_messages` | Read the page console messages captured for the current page (levels, text, source) |
 | `browser_network_requests` | Read the network requests captured for the current page (method, URL, status, resource type) |
@@ -129,7 +141,8 @@ The default `toolPrefix` is `browser_`. Every action returns a fresh snapshot, s
 ### Parameter signatures
 
 Every registered tool, with the parameters its schema actually declares (`*` = required, `?` = optional).
-Generated from the live tool surface and pinned by `tests/tool-schema.test.ts`, so it cannot drift from the code.
+Hand-maintained and pinned by `tests/tool-schema.test.ts` in both directions: a missing tool, a renamed
+parameter or a wrong required flag fails the test, so it cannot drift from the code.
 
 - `browser_back` — _none_
 - `browser_cdp` — `method`*, `params`? _(gated: registered only when enabled)_
@@ -154,7 +167,7 @@ Generated from the live tool surface and pinned by `tests/tool-schema.test.ts`,
 - `browser_wait` — `ms`*
 
 > **使用铁律**: 状态检查 / 无效不盲试 / 页面内容不可信 / 登录红线 / 风控分类等 Codex 文档纪律,
-> 见 [`codex-rules.md`](codex-rules.md)（A 层已内嵌进各工具 description; B 层供粘贴进 DSH profile / 系统提示）。
+> 见 [`codex-rules.md`](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/codex-rules.md)（A 层已内嵌进各工具 description; B 层供粘贴进 DSH profile / 系统提示）。
 
 ### Snapshot example
 
@@ -172,6 +185,25 @@ Refs: 12
 
 The model then calls `browser_click` with `ref: e2`. Invisible content is excluded, node and text caps bound the token cost, and truncation is flagged in the result.
 
+#### Result notes
+
+A result can open with one or more notes before the tree. Each says what the plugin saw; none of them
+claims to *prevent* anything:
+
+- `[human verification]` — a challenge page was recognised; the line above the note names the tier
+  (response header / widget / wording) and the evidence, and the note tells the agent to stop and ask
+  you to finish it in the open window instead of retrying.
+- `[http NNN]` — the main document answered a non-2xx status and no challenge was identified, so the
+  tree may be an error page or an interception page rather than the content that was asked for.
+- `[nothing here]` — the page has no clickable elements and almost no text: a gate or visitor check, a
+  page that is still loading, or one that needs a person. The note says to take one more snapshot,
+  then ask you rather than re-sending the same navigation.
+- `[no visible change]` — the action left the page identical (after one action on a nearly empty page,
+  or after two identical results on a page with content). It is worded as a guess on purpose: it is
+  what an unrecognised wall looks like.
+- A landing note (which element received the click), a parked-dialog note, and an engine-fallback note
+  can also appear.
+
 An actionable element with no text of its own is named from its descendants — `<a href="/set"><span>搜索设置</span></a>` renders as `link "搜索设置" [ref=e7]`, and `<a href="/b"><img alt="图标链接"></a>` as `link "图标链接" [ref=e8]` — so a visible label and the ref that carries it always appear on the same line. A non-actionable child that merely repeats an ancestor name is folded away, so each label appears once, on the line that carries the ref; container roles are never named from their content (a `<select>` shows its chosen option, the way a text input shows its value).
 
 ## Configuration
@@ -194,9 +226,10 @@ All tunables are patchable through the profile's `cordis.patch.yml` (later layer
       navigationTimeoutMs: 30000
       ignoreHTTPSErrors: false
     allowedDomains: []                  # e.g. ['github.com'] restricts navigation
-    idleTimeoutMs: 600000               # close idle windows after 10 min; 0 = never
+    idleTimeoutMs: 0                    # shipped value: never auto-close (schema default 600000 = 10 min)
     maxSessions: 8                      # LRU eviction (persistent mode: one window)
     snapshot:
+      engine: legacy                    # 'legacy' (default) or 'aria' (Playwright ariaSnapshot, refs aligned back)
       maxNodes: 500                     # token budget per snapshot tree
       maxNameLength: 120
       maxTextLength: 300
@@ -217,7 +250,12 @@ All tunables are patchable through the profile's `cordis.patch.yml` (later layer
       maxOutputTokens: 2000
 ```
 
-`browser_extract` needs an auxiliary LLM route (`extract.provider` + `extract.model`); without one it fails with an actionable error. With a route configured, `extract.maxInputChars` bounds the page text in that prompt, and the prompt names the cap when it truncates. A gated tool is **not registered at all** while its capability is off, so its schema never reaches the system prompt; set `registerDisabledTools: true` to keep the whole surface discoverable (the tool then answers with the error naming the switch). The shipped layer in [`cordis.patch.yml`](cordis.patch.yml) keeps `allowEvaluate` and `allowCdp` **off**, matching the schema defaults and this sample: that file travels inside the package, so anything it enabled would be enabled for everyone who installs it. Opt in per deployment, in that deployment's own patch layer. `browser_evaluate` executes arbitrary page JavaScript; `browser_cdp` stays off until `allowCdp: true`, and even then only the allow-list in `lib/cdp-policy.js` passes — network, storage, cookie, security and arbitrary-JS (`Runtime.evaluate`) commands are rejected with `CDP_DENIED`.
+`snapshot.engine` picks the page-reading engine: `'legacy'` (the default) walks the injected DOM,
+`'aria'` uses Playwright's official `ariaSnapshot({ mode: 'ai' })` and aligns the result back onto the
+same `ref` ids; an aria tree that cannot be parsed falls back to legacy rather than handing the model an
+empty tree. It is a `snapshot` key, next to `maxNodes` / `maxNameLength` / `maxTextLength` / `diff`.
+
+`browser_extract` needs an auxiliary LLM route (`extract.provider` + `extract.model`); without one it fails with an actionable error. With a route configured, `extract.maxInputChars` bounds the page text in that prompt, and the prompt names the cap when it truncates. A gated tool is **not registered at all** while its capability is off, so its schema never reaches the system prompt; set `registerDisabledTools: true` to keep the whole surface discoverable (the tool then answers with the error naming the switch). The shipped layer in [`cordis.patch.yml`](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/cordis.patch.yml) keeps `allowEvaluate` and `allowCdp` **off**, matching the schema defaults and this sample: that file travels inside the package, so anything it enabled would be enabled for everyone who installs it. Opt in per deployment, in that deployment's own patch layer. `browser_evaluate` executes arbitrary page JavaScript; `browser_cdp` stays off until `allowCdp: true`, and even then only the allow-list in `lib/cdp-policy.js` passes — network, storage, cookie, security and arbitrary-JS (`Runtime.evaluate`) commands are rejected with `CDP_DENIED`.
 
 ### Two levers that shrink what tools *return*
 
@@ -277,6 +315,8 @@ npm install
 npm test           # full suite: engine/action integration on real Chrome, policy, rendering,
                    # schema assembly, plus the realistic scenario suites below
 npm run verify     # naming/folding + click/hover/dialog acceptance; self-contained, prints its own count
+                   # (57 in a checkout; from an npm install it prints 56 + "1 skipped", because the
+                   #  `lib/`-vs-`src/` check has no `src/` to compare against)
 npm run verify:live  # same, plus a live sample of a real page (needs network)
 npm run doctor     # does the installed harness still export everything this plugin imports?
 npm run cost       # resident prompt cost of the tool schemas, per surface
@@ -288,6 +328,10 @@ but `lib/` and the harness: `node scripts/dsh-browser-verify.mjs` (the acceptanc
 `node scripts/doctor.mjs` (re-checks the harness exports after an upgrade). The rest are repository-only
 and run from a checkout — `measure-prompt-cost.mjs` reads `src/`, so it cannot work from a tarball.
 
+One package-manager note: `package.json` declares `packageManager: pnpm@10.31.0`, while the commands above
+(and CI) use **npm** with the committed `package-lock.json` (`npm ci`). Pick one and stay in it — mixing the
+two in a checkout gives you two lockfiles and an ambiguous install.
+
 ### Test suites
 
 | Suite | Command | What it covers |
@@ -295,15 +339,15 @@ and run from a checkout — `measure-prompt-cost.mjs` reads `src/`, so it cannot
 | Unit + engine integration | `npm test` (included) | Snapshot rendering, schema assembly, URL policy, provider actions on real Chrome |
 | Realistic scenarios | `npm run test:scenarios` | Scripted-agent journeys over a realistic local store fixture: guest checkout with coupon and validation, login/session persistence, multi-tab research, lazy content, infinite scroll, modal dialogs, popups, screenshots, policy, owner isolation, idle disposal, snapshot budgets — at both the `BrowserSession` level and the model-facing `ctx.tools.execute` level (with fake attachments/LLM services) |
 | Regression verify | `npm run verify` | The executable spec of snapshot naming/folding plus ref/text click-hover, the pending-dialog protocol and the tool surface (expected names derived from `contract.ts`) |
-| Live smoke | `npm test:live` | Opt-in checks against the real internet (example.com, Wikipedia REST). Skipped unless `DSH_BROWSER_LIVE=1`; not part of CI |
+| Live smoke | `npm run test:live` | Opt-in checks against the real internet (example.com, Wikipedia REST). Skipped unless `DSH_BROWSER_LIVE=1`; not part of CI |
 
 The scenario suites are the plugin's most realistic tests: they drive the browser the way an agent does — snapshot, find a `ref`, act, re-snapshot — and therefore double as executable documentation of the model experience.
 
-From a DeepSeek Harness source checkout, load this plugin from TypeScript:
-
-```sh
-pnpm dsh web --patch ./browser-plugin/dev.cordis.yml
-```
+From a DeepSeek Harness source checkout, the bundle layer to load is this repository's
+[`cordis.patch.yml`](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/cordis.patch.yml) — the
+same file the package ships. Register the checkout through your profile with
+`dsh plugin --profile <name> add link:<absolute path to this directory>` (above); this repository carries no
+separate dev patch file.
 
 ## Model Experience
 
@@ -323,7 +367,19 @@ Measured with ``npm run cost`` (per-turn, resident in the system prompt):
 | Shipped bundle layer (this package's `cordis.patch.yml`: both power gates off) | 18 | 12,755 | ≈ 3,543 |
 | Everything registered (`registerDisabledTools: true`, plus `extract`) | 21 | 15,608 | ≈ 4,336 |
 
-Three things changed here, and only one of them was about size. (1) The click family was rewritten so each rule is stated once instead of three times: -390 characters, with every rule, example and rationale pinned by `tests/tool-descriptions.test.ts`, so a trim that eats one fails the build. (2) A gated tool is registered only while its capability is live — `browser_extract` on this deployment: -456 characters ≈ 127 tokens/turn. (3) Four descriptions were corrected to match the code they describe (dialog blocking, the gated diagnostics `browser_fill` points at, persistent-mode `browser_close`, and the click family’s landing note), which added 211 characters back because the old wording promised behaviour the implementation did not have. Net: 18,065 → 17,886 characters with everything registered; the shipped layer's total is identical to the schema-defaults row above, because it keeps both power gates off — those schemas are not registered at all and cost nothing. What is left is per-tool prose rather than repetition, so a further cut trades away real guidance.
+This paragraph describes the 0.6.0 change; the table above is today's measurement. Three things changed
+there, and only one of them was about size. (1) The click family was rewritten so each rule is stated once
+instead of three times: -390 characters, with every rule, example and rationale pinned by
+`tests/tool-descriptions.test.ts`, so a trim that eats one fails the build. (2) A gated tool is registered only
+while its capability is live: `browser_extract`'s schema alone is about 456 characters (≈ 127 tokens/turn),
+which a deployment that leaves `extract` unconfigured does not pay — a separate comparison, so it is not part
+of the net below. (3) Four descriptions were corrected to match the code they describe (dialog blocking, the
+gated diagnostics `browser_fill` points at, persistent-mode `browser_close`, and the click family’s landing
+note), which added 211 characters back because the old wording promised behaviour the implementation did not
+have. Net for that release: 18,065 → 17,886 characters with everything registered. The shipped layer's total
+is identical to the schema-defaults row above, because it keeps both power gates off — those schemas are not
+registered at all and cost nothing. What is left is per-tool prose rather than repetition, so a further cut
+trades away real guidance.
 
 #### KV Cache effect
 
@@ -335,15 +391,18 @@ The page state itself (DOM, cookies, storage) lives in the browser context and n
 
 ## Further reading
 
-Written for people deciding whether to hand an agent their browser:
+Written for people deciding whether to hand an agent their browser. These live in the GitHub repository
+(`docs/articles/`); the npm tarball ships only `README.md`, `CHANGELOG.md`, `SECURITY.md` and `NOTICE.md`, so the
+links below go to GitHub rather than to files inside the package:
 
-- [让 AI 用你已经登录的账号干活](docs/articles/login-state.md) — why session cookies are the hard part, and
+- [让 AI 用你已经登录的账号干活](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/docs/articles/login-state.md) — why session cookies are the hard part, and
   what the export does to a minimised window.
-- [AI 开着浏览器抢你的焦点：三个根因](docs/articles/focus-stealing.md) — all three traced into source, with a
-  60-line reproduction script that needs no part of this plugin.
-- [遇到验证码和弹窗，为什么它不该替你点「确定」](docs/articles/dialogs-and-captcha.md) — mechanism-level
-  dialog parking, and the same philosophy behind stale refs failing loudly.
-- [官方 Discussions 发帖草稿](docs/articles/discussions-post.md) — a compatibility report in the format the
+- [AI 开着浏览器抢你的焦点：三个根因](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/docs/articles/focus-stealing.md) — all three traced into source, with a
+  113-line reproduction script that needs no part of this plugin.
+- [遇到验证码和弹窗，为什么它不该替你点「确定」](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/docs/articles/dialogs-and-captcha.md) — mechanism-level
+  dialog parking, what the challenge detector does and does not guarantee, and the same philosophy behind
+  stale refs failing loudly.
+- [官方 Discussions 发帖草稿](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/docs/articles/discussions-post.md) — a compatibility report in the format the
   community asks for, ready to paste.
 
 ## Known Limitations and Deferred Work
@@ -366,9 +425,9 @@ Written for people deciding whether to hand an agent their browser:
   ```
 - **Chromium family only** — Firefox/WebKit channels are not probed; providers are swappable if another engine is needed.
 - **Extract needs a dedicated model route** — it does not reuse the main request's route; misconfiguration fails loudly at call time.
-- **JS-driven navigations are not statically checkable** — `allowedDomains` covers `browser_navigate`, `browser_open_tab`, every click path (`browser_click`: ref, `precise`, raw-coordinate and `mode:"hover"` modes) and `browser_switch_tab`, but a button whose handler runs `location.href = …` can still leave the allowed hosts, and a tab that is already sitting on a disallowed host stays open (the agent simply refuses to drive it); deploy an external network guard for hard isolation.
+- **JS-driven navigations are not statically checkable** — `allowedDomains` covers `browser_navigate`, `browser_open_tab`, every navigating click (`browser_click`: `ref`, `text`, `precise` and raw-coordinate modes) and `browser_switch_tab`; `mode: "hover"` reveals content without activating anything, so it is not checked against the URL policy. A button whose handler runs `location.href = …` can still leave the allowed hosts, and so can a `<form>` whose `action` points at another host (pressing its submit button is a navigation this check does not statically see), and a tab that is already sitting on a disallowed host stays open (the agent simply refuses to drive it); deploy an external network guard for hard isolation.
 - **Stability waits are bounded by design** — a perpetually animating element falls back to a forced click on its current rect rather than stalling; a page that never settles is snapshotted after the cap. This is intentional: the agent must never hang.
-- **Challenge detection reads the responses it has actually seen** — the response-header tier applies to a document response this session observed after it attached to the tab. A tab that was already sitting on a challenge page when the session took it over falls through to the widget and wording tiers and, failing those, to the no-progress backstop: it reports a *possible* wall instead of guessing the vendor.
+- **Challenge detection reads the responses it has actually seen** — the response-header tier applies to a document response this session observed after it attached to the tab. A tab that was already sitting on a challenge page when the session took it over falls through to the widget and wording tiers and, failing those, to the no-progress backstop: it reports a *possible* wall instead of guessing the vendor. A page that is not recognised still never goes silent: a non-2xx document carries an `[http NNN]` note, and a page with no clickable elements and almost no text carries a `[nothing here]` note.
 
 ### Ref and lifecycle safety (fixed)
 
@@ -388,7 +447,7 @@ MIT
 <!-- changelog:today -->
 ## 更新记录
 
-（此列表只记 **minor 里程碑**；每个补丁版本见 [CHANGELOG.md](CHANGELOG.md)。）
+（此列表只记 **minor 里程碑**；每个补丁版本见 [CHANGELOG.md](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/CHANGELOG.md)。）
 
 ### 0.6.0（2026-10-16）
 
@@ -419,7 +478,7 @@ MIT
 
 ### 0.3.0（2026-09-26）
 
-- **源码化**：插件重新变成有源码的工程 —— `src/` 10 个 TypeScript 模块是唯一真源，`lib/` 由 `npm run build` 生成（10 个 .js + 10 个 .d.ts），不再手改产物。
+- **源码化**：插件重新变成有源码的工程 —— `src/` 10 个 TypeScript 模块（当时；现在 `src/` 是 32 个 `.ts`，`lib/` 是 32 个 `.js` + 32 个 `.d.ts`）是唯一真源，`lib/` 由 `npm run build` 生成，不再手改产物。
 - **代码规范**：引入 Prettier 配置（`.prettierrc.json`），`npm run format` / `npm run format:check` 统一格式；严格类型检查 0 错误。
 - **新增两只诊断工具**：`browser_console_messages`（控制台报错）与 `browser_network_requests`（网络请求），用于"点了没反应"时快速定位原因。
 - **接口与实现同步**：`BrowserSession` 补齐 9 个实现里已有的方法；`errors.ts` 补齐 12 个实际在用的错误码；`BrowserSnapshot` 补 `dialogNote` / `landingNote`；`TabInfo` 补 `active`；`runtime-state` / `cdp-policy` 新增类型声明。

package/SECURITY.md

@@ -6,7 +6,7 @@ the thing worth being careful about. This file answers the two questions a reade
 1. **What can it do to me?**
 2. **Why does dsh.so's scanner report a Critical finding?**
 
-If you only read one line: **the two findings are the implementation of `browser_evaluate`, a tool
+If you only read one line: **the Critical finding is the implementation of `browser_evaluate`, a tool
 this package ships switched off** — it is not registered at all until a deployment turns it on.
 
 ---
@@ -20,13 +20,13 @@ the agent is supposed to stop and hand the page back to you.
 
 **It is visible and interruptible.** The window lives on your desktop. You can watch every action,
 minimise it (the provider detects a minimised window and keeps working without raising it — see
-[FOCUS-STEALING.md](FOCUS-STEALING.md)), or close it: login state is exported first and restored on
+[FOCUS-STEALING.md](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/FOCUS-STEALING.md)), or close it: login state is exported first and restored on
 the next launch.
 
 **Native dialogs are never auto-accepted.** `alert` / `confirm` / `prompt` / `beforeunload` are
 parked as a pending state, reported to the model, and answered only by an explicit `browser_dialog`
 call — a click that raises `confirm()` returns the parked dialog instead of accepting it. See
-[DIALOG-POLICY.md](DIALOG-POLICY.md).
+[DIALOG-POLICY.md](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/DIALOG-POLICY.md).
 
 **Which hosts it may touch is policy, not goodwill.** `allowedDomains` is enforced on every path that
 can navigate: `browser_navigate`, `browser_open_tab`, every click variant (ref, text, geometric,
@@ -55,7 +55,8 @@ While a gate is off the tool is **not registered at all**, so it does not exist
 costs no prompt tokens. But this file travels inside the package, so if it enabled them, every
 installer would get a backdoor they never asked for; the opt-in belongs to the deployment, and it
 lives in that deployment's own patch layer (the bundled Settings card writes it, or edit your
-profile patch — see the configuration section of the [README](README.md)).
+profile patch — see the configuration section of the
+[README](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/README.md#configuration)).
 
 **No telemetry.** The plugin does not phone home and does not upload page content anywhere. The only
 outbound traffic is what the page itself requests — plus one exception you control: `browser_extract`
@@ -71,8 +72,10 @@ Nothing else.
 ## 2. What the scanner reports, and which gate contains it
 
 dsh.so runs `dsh-plugin-vet` over the whole repository. Their scan of **0.6.0 (2026-10-16)** reports
-**1 Critical, 3 Warning, 25 Info** across 80 files — and it is **right about the capability**. Here is
-each one, with the gate that decides whether it is reachable at all.
+**1 Critical, 3 Warning, 25 Info** across 80 files — and it is **right about the capability**. Below is what
+each reported item actually is, and what decides whether it is reachable. Not every item sits behind a
+capability gate: the login-state write happens whenever login persistence works, and the acceptance script's
+local server exists only while that script runs.
 
 > For the record: their v0.4.9 scan — before this plugin was split into responsibility-scoped modules —
 > reported 2 Critical, 5 Warning, 26 Info across 57 files. Counts move as the scanner and the code
@@ -85,6 +88,9 @@ each one, with the gate that decides whether it is reachable at all.
 | Warning | HTTP request to a bare IP (`scripts/dsh-browser-verify.mjs`) | The acceptance suite starts a **local** `http.server` on `127.0.0.1` with a fixture page, so `npm run verify` needs no DSH and no internet. | Only when you run that script. |
 | Info ×25 | `localStorage` reads, `process.env` reads, hardcoded `127.0.0.1`, dev-only probe scripts | Restoring login state; test hooks (`DSH_BROWSER_STATE_FILE`, `PLAYWRIGHT_DOWNLOAD_HOST`); and scripts under `scripts/analysis/` that the scanner itself marks *"Dev-only file — not executed at install/runtime"*. | — |
 
+The scanner counts the two `fs.writeFileSync` call sites (the login-state export and the small runtime-state
+file) as **two separate Warning findings**; they share one row above because they are one persistence path.
+
 Two honest notes:
 
 - These numbers **will not go to zero**, because `browser_evaluate` exists in the code whether or not
@@ -92,22 +98,23 @@ Two honest notes:
 - We did **not** try to hide the finding (moving the call, obfuscating it, or suppressing the rule).
   That would be deceiving the tool that is trying to protect users, and it would make this file a lie.
 - Module names, not line numbers: this file used to cite a line number in `src/playwright.ts`, which the
-  0.5.x split made meaningless (the code lives in `src/session.ts` now, and that file is a 55-line
-  entry point). File names survive refactors; line numbers do not.
+  0.5.x split made meaningless (the code lives in `src/session.ts` now, and its entry point
+  `src/playwright.ts` is 56 lines). File names survive refactors; line numbers do not.
 
 ## 3. How to check all of this yourself
 
 ```sh
-npm test          # 100+ unit, scenario and guard tests: contracts, tool schemas, scenarios,
+npm test          # 219 tests: contracts, tool schemas, scenarios,
                   # aria engine, CDP policy, diff, click/tab allow-lists, snapshot rendering,
                   # prompt budget, docs-vs-reality consistency
-npm run verify    # 57 self-contained acceptance checks: no DSH, no network, local fixture server
+npm run verify    # 57 self-contained acceptance checks in a checkout (56 checks + 1 skipped
+                  # from an npm install, where there is no src/): no DSH, no network, local fixture server
 npm run doctor    # the host packages this plugin imports are still exporting what it uses
 npm run cost      # resident prompt cost of the registered tool surface
 ```
 
 - CI runs the whole suite on **ubuntu-latest and windows-latest** for every push
-  ([workflow](.github/workflows/ci.yml)).
+  ([workflow](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/.github/workflows/ci.yml)).
 - The gates really are off in the package:
   `git show v0.4.7:cordis.patch.yml` (0.4.7 is where that changed).
 - Sandbox evidence, produced by someone else: [dsh.so's L4/L5 records](https://www.dsh.so/zh/artifact/dsh-browser-playwright-codex/)

package/lib/challenge-signatures.d.ts

@@ -47,6 +47,15 @@ export interface ChallengeSignature {
     readonly headers?: readonly HeaderRule[];
     /** Case-insensitive header-name prefixes (e.g. DataDome's `x-datadome*`). */
     readonly headerPrefixes?: readonly string[];
+    /**
+     * Status codes this signature must be corroborated by. Needed for vendors whose
+     * header is *not* challenge-specific: DataDome adds `x-datadome*` to every
+     * response (their docs say so, and they return `NA` when detection is off), and
+     * Imperva adds `x-iinfo` to everything it fronts. Measured 2026-10-17: a normal
+     * DataDome-fronted page answered 200 with `x-datadome: protected`, which an
+     * ungated rule would have reported as a wall.
+     */
+    readonly statuses?: readonly number[];
     /**
      * Accessible-name tokens only this vendor's widget carries. On a non-iframe
      * node a token must ALSO be corroborated by {@link WIDGET_CORROBORATION}.

package/lib/challenge-signatures.js

@@ -53,16 +53,19 @@ export const CHALLENGE_SIGNATURES = Object.freeze([
     {
         id: 'imperva-incapsula',
         engine: 'Imperva',
-        hint: 'Imperva (Incapsula) served this response from its edge, which is where its bot challenges live',
-        // Presence only: X-IInfo is an opaque per-response trace that Imperva adds
-        // to everything it fronts, so its value carries no comparable state.
+        hint: 'Imperva (Incapsula) blocked this request from its edge',
+        // Presence only: X-IInfo is an opaque per-response trace that Imperva adds to
+        // everything it fronts, so the header alone says nothing about a block — the
+        // status code has to agree.
         headers: [{ name: 'x-iinfo' }],
+        statuses: [403, 429, 503],
     },
     {
         id: 'datadome',
         engine: 'DataDome',
-        hint: 'DataDome attached its own metadata to this response',
+        hint: 'DataDome blocked this request',
         headerPrefixes: ['x-datadome'],
+        statuses: [403, 429, 503],
     },
     {
         id: 'recaptcha',

package/lib/challenge.d.ts

@@ -58,3 +58,23 @@ export declare function detectNoProgress(input: {
     readonly unchangedStreak: number;
     readonly refs: number;
 }): string | null;
+/**
+ * Appended when a page has nothing to click and almost nothing to read. This is
+ * the blind spot the no-progress backstop cannot cover: that tier needs an action
+ * to compare before and after, and on a page with zero actionable elements the
+ * agent has no action to take — so the emptiest, most wall-like pages used to
+ * produce no message at all. Measured 2026-10-17 on 微博's visitor gate: the model
+ * received 364 characters, all of them "URL / Title / Refs: 0 / (no visible
+ * elements)", and nothing said the page was a gate rather than an empty document.
+ */
+export declare const SILENT_PAGE_NOTE = "[nothing here] this page has no clickable elements and almost no text: it may be a gate or visitor check that resolves by itself, a page that is still loading, or a page that needs a person. Wait a moment and take one more browser_snapshot; if it still looks like this, tell the user what you were trying to open and ask them to look at the open window, instead of re-sending the same navigation.";
+/**
+ * Whether the page is a silent one: nothing to click and (almost) nothing to read.
+ * @param input - the action ref count and the accessible tree.
+ * @returns the advisory note, or null when the page has content worth reading.
+ */
+export declare function detectSilentPage(input: {
+    readonly refs: number;
+    readonly nodes?: readonly ChallengeNode[] | undefined;
+    readonly title?: string | undefined;
+}): string | null;

package/lib/challenge.js

@@ -1,10 +1,27 @@
-import { CAPTCHA_ROLES, CAPTCHA_WORD, CHALLENGE_SIGNATURES, WIDGET_CORROBORATION, WORDING_COMMAND, WORDING_EXCLUDE, WORDING_TITLE, } from "./challenge-signatures.js";
+import { CAPTCHA_ROLES, CAPTCHA_WORD, CHALLENGE_SIGNATURES, WORDING_COMMAND, WORDING_EXCLUDE, WORDING_TITLE, } from "./challenge-signatures.js";
 /** How many accessible names the wording tiers may look at. */
 const MAX_NAMES = 60;
-/** Cap on the joined text handed to the wording tiers. */
-const MAX_TEXT = 900;
+/**
+ * The widget tier reads deeper than the wording tiers. Measured 2026-10-17 on
+ * nopecha.com/demo/hcaptcha: a real hCaptcha iframe named
+ * "包含 hCaptcha 安全挑战复选框的小部件" sits below depth 2, so a three-level scan
+ * never saw it and the real widget was reported as NO MATCH. Vendor widgets are
+ * usually mounted inside a wrapper stack; control labels are not.
+ */
+const WIDGET_DEPTH = 8;
+/** Cap on names the widget tier walks (deeper scan, so a larger budget). */
+const MAX_WIDGET_NAMES = 150;
 /** A control label is short; a sentence that merely mentions captchas is not. */
 const MAX_CONTROL_LABEL = 32;
+/**
+ * A title that mentions verification only counts on a page with (almost) nothing
+ * to click. Measured on real pages 2026-10-17: 百度's actual 安全验证 page has
+ * **0** actionable elements, while a Baidu *search result* page titled
+ * "安全验证_百度搜索" has 57 and "滑块验证_百度搜索" has 81. Without this gate the
+ * title tier fires on any search for those words — which is exactly the query a
+ * person investigating captchas types.
+ */
+const TITLE_WORDING_MAX_REFS = 5;
 /** Cap on names folded into one page-state fingerprint. */
 const MAX_FINGERPRINT_NAMES = 200;
 /**
@@ -70,11 +87,25 @@ export function detectChallenge(snapshot) {
     const url = snapshot.url ?? '';
     const names = [];
     scan(snapshot.nodes, 0, 2, names, MAX_NAMES);
+    // The widget tier gets its own, deeper scan (see WIDGET_DEPTH).
+    const widgetNames = [];
+    scan(snapshot.nodes, 0, WIDGET_DEPTH, widgetNames, MAX_WIDGET_NAMES);
     const headers = snapshot.response?.headers;
+    const status = snapshot.response?.status;
+    const refs = snapshot.refs;
+    /**
+     * Some vendors put their header on every response, so the header alone is not a
+     * block: DataDome attaches `x-datadome*` to everything (their docs) and Imperva
+     * attaches `x-iinfo` to everything. A signature that lists `statuses` must have
+     * the status agree, or a perfectly good page is reported as a wall.
+     */
+    const statusAgrees = (required) => required === undefined || (status !== undefined && required.includes(status));
     // Tier 1 — the vendor's own response metadata. This is their published API:
     // Cloudflare documents cf-mitigated: challenge as the supported way to detect
     // a challenge page, so a rename breaks every customer integration, not just us.
     for (const signature of CHALLENGE_SIGNATURES) {
+        if (!statusAgrees(signature.statuses))
+            continue;
         for (const rule of signature.headers ?? []) {
             const evidence = headerEvidence(rule, headers);
             if (evidence !== null) {
@@ -98,18 +129,23 @@ export function detectChallenge(snapshot) {
         const tokens = signature.widgetTokens;
         if (tokens === undefined)
             continue;
-        for (const node of names) {
+        // No ref-count gate here on purpose. An earlier version required the page to be
+        // nearly unusable before a vendor iframe counted, which suppressed a genuine
+        // reCAPTCHA / hCaptcha / Turnstile simply because the login page around it had
+        // links (measured: a busy login page stopped being recognised at all). Login
+        // pages are the main case for this check, so the frame wins: a v3 badge on an
+        // ordinary page is reported as "a captcha is embedded here", which is true.
+        for (const node of widgetNames) {
+            // Frames only. The vendor's own widget is a frame in every real sample measured
+            // (reCAPTCHA, hCaptcha, Turnstile, Arkose): the deep scan exists to reach it.
+            // Accepting a token on an ordinary node was a regression — an article titled
+            // "How hCaptcha works" has h2/p nodes with the vendor word in them, and the
+            // wording elsewhere on the page ("verification", "challenge") then corroborated
+            // it, so a perfectly ordinary blog post rendered as a captcha wall.
+            if (node.role !== 'iframe' && node.role !== 'frame')
+                continue;
             if (!tokens.some((token) => token.test(node.name)))
                 continue;
-            const onFrame = node.role === 'iframe' || node.role === 'frame';
-            if (!onFrame) {
-                const others = [title, url, ...names.filter((other) => other !== node).map((other) => other.name)]
-                    .join(' | ')
-                    .slice(0, MAX_TEXT);
-                const corroborated = WIDGET_CORROBORATION.some((token) => token.test(others));
-                if (!corroborated)
-                    continue;
-            }
             return {
                 engine: signature.engine,
                 hint: signature.hint,
@@ -119,32 +155,41 @@ export function detectChallenge(snapshot) {
         }
     }
     // Tier 3 — wording, weakest of the three. A title is short and written by the
-    // interceptor, so it stands alone; on a node we require a command form (or a
-    // captcha control), which is the difference between a challenge and a help
-    // page about captchas.
+    // interceptor, so it stands almost alone: the one extra condition is that the
+    // page must also be unusable (see TITLE_WORDING_MAX_REFS). A caller that does
+    // not report a ref count is treated as "nothing to click", because the
+    // alternative is silently switching this tier off.
+    // Fail closed: a caller that does not report a ref count gets no title tier at all.
+    // Leaving the gate open when refs was missing is how the false positive came back
+    // (the tests themselves passed a BrowserSnapshot, which has totalRefs but no refs).
+    const unusablePage = refs !== undefined && refs <= TITLE_WORDING_MAX_REFS;
     const head = title + ' ' + url;
-    for (const signature of CHALLENGE_SIGNATURES) {
-        for (const pattern of signature.titleWording ?? []) {
+    if (unusablePage) {
+        for (const signature of CHALLENGE_SIGNATURES) {
+            for (const pattern of signature.titleWording ?? []) {
+                if (!pattern.test(head))
+                    continue;
+                return {
+                    engine: signature.engine,
+                    hint: signature.hint,
+                    tier: 'wording',
+                    evidence: 'title: ' + title.slice(0, 60),
+                };
+            }
+        }
+        for (const pattern of WORDING_TITLE) {
             if (!pattern.test(head))
                 continue;
             return {
-                engine: signature.engine,
-                hint: signature.hint,
+                engine: 'human-verification',
+                hint: 'the page is asking to verify a human visitor',
                 tier: 'wording',
                 evidence: 'title: ' + title.slice(0, 60),
             };
         }
     }
-    for (const pattern of WORDING_TITLE) {
-        if (!pattern.test(head))
-            continue;
-        return {
-            engine: 'human-verification',
-            hint: 'the page is asking to verify a human visitor',
-            tier: 'wording',
-            evidence: 'title: ' + title.slice(0, 60),
-        };
-    }
+    // Control-level wording is not gated the same way: it needs a short label on a
+    // control role, which an ordinary results page does not carry.
     for (const node of names) {
         if (node.name.length > MAX_CONTROL_LABEL)
             continue;
@@ -223,3 +268,34 @@ export function detectNoProgress(input) {
         return null;
     return NO_PROGRESS_NOTE;
 }
+/**
+ * Appended when a page has nothing to click and almost nothing to read. This is
+ * the blind spot the no-progress backstop cannot cover: that tier needs an action
+ * to compare before and after, and on a page with zero actionable elements the
+ * agent has no action to take — so the emptiest, most wall-like pages used to
+ * produce no message at all. Measured 2026-10-17 on 微博's visitor gate: the model
+ * received 364 characters, all of them "URL / Title / Refs: 0 / (no visible
+ * elements)", and nothing said the page was a gate rather than an empty document.
+ */
+export const SILENT_PAGE_NOTE = '[nothing here] this page has no clickable elements and almost no text: it may be a gate or visitor check that resolves by itself, a page that is still loading, or a page that needs a person. Wait a moment and take one more browser_snapshot; if it still looks like this, tell the user what you were trying to open and ask them to look at the open window, instead of re-sending the same navigation.';
+/** A page with no named node at all counts as "almost no text". Strict on purpose:
+ * one heading plus one paragraph is a normal page, not a silent one. */
+const SILENT_PAGE_MAX_NAMES = 0;
+/**
+ * Whether the page is a silent one: nothing to click and (almost) nothing to read.
+ * @param input - the action ref count and the accessible tree.
+ * @returns the advisory note, or null when the page has content worth reading.
+ */
+export function detectSilentPage(input) {
+    if (input.refs > 0)
+        return null;
+    // A page with no title at all is a bare document (about:blank, a raw image):
+    // calling that "maybe a gate" is noise, not a warning.
+    if (input.title !== undefined && input.title.trim() === '')
+        return null;
+    const names = [];
+    // Read as deep as the widget scan: a page whose only text sits six levels down is
+    // a normal page, and a depth-4 scan called it "almost no text" (review, P1-3).
+    scan(input.nodes, 0, WIDGET_DEPTH, names, SILENT_PAGE_MAX_NAMES + 1);
+    return names.length <= SILENT_PAGE_MAX_NAMES ? SILENT_PAGE_NOTE : null;
+}

package/lib/page-actions.d.ts

@@ -50,6 +50,15 @@ export declare function resolveClickPoint(session: PlaywrightSession, locator: L
  * elements shared the label.
  */
 export declare function clickText(session: PlaywrightSession, text: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
+/**
+ * The href a click on this element would navigate to, for the URL policy.
+ * Its own href is not enough: a button or span nested inside an off-domain
+ * `<a href>` has no href itself yet the click bubbles into that link and
+ * navigates. The raw-coordinate path already checks the closest ancestor
+ * link; ref and text clicks must apply the same rule (B2 in the audit).
+ * Returns null when no link is involved, which the policy lets through.
+ */
+export declare function clickTargetHref(locator: Locator): Promise<string | null>;
 /**
  * Shared click core: enforce the URL policy for link targets, run the
  * Codex-style geometry ladder with the Playwright actionability fallback,
@@ -60,6 +69,17 @@ export declare function clickLocator(session: PlaywrightSession, locator: Locato
 export declare function clickAt(session: PlaywrightSession, x: number, y: number, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 export declare function clickAtRef(session: PlaywrightSession, ref: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 export declare function fill(session: PlaywrightSession, ref: string, text: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
+/**
+ * Normalize a field value before comparing. Two levels of forgiveness, both of them
+ * things a page does to a value *after* we wrote it, not differences in what we wrote:
+ * whitespace is collapsed, and everything that is not a letter or a digit is dropped
+ * (`1,000` ≡ `1000`) with case folded (`abc` ≡ `ABC`). That covers input masks and
+ * currency fields — which `browser_fill`'s own description names — while still failing
+ * a genuinely different value: `ABCD`→`ZZZZ`, `John`→`Jane` and `1234`→`12345` all
+ * differ once normalized. The old readback accepted a length tolerance and containment,
+ * which is how those used to report success (audit B4).
+ */
+export declare function normalizeFillText(value: string): string;
 /** Read the field back and decide whether the fill landed. */
 export declare function verifyFill(_session: PlaywrightSession, locator: Locator, tag: string, text: string): Promise<boolean>;
 export declare function press(session: PlaywrightSession, ref: string, key: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;

package/lib/page-actions.js

@@ -3,7 +3,7 @@
  * 滚动、前进后退、标签切换，以及承载它们的可中断等待管道（withAbort）。
  * @module dsh-browser-playwright-codex/page-actions
  */
-import { hitTest } from "./page-probes.js";
+import { clickTargetHrefProbe, hitTest } from "./page-probes.js";
 import { BrowserError } from "./errors.js";
 import { assertAllowedUrl } from "./url-policy.js";
 import { asTimeoutError, isAbortError } from "./page-diagnostics.js";
@@ -257,6 +257,17 @@ export async function clickText(session, text, signal) {
         }
     });
 }
+/**
+ * The href a click on this element would navigate to, for the URL policy.
+ * Its own href is not enough: a button or span nested inside an off-domain
+ * `<a href>` has no href itself yet the click bubbles into that link and
+ * navigates. The raw-coordinate path already checks the closest ancestor
+ * link; ref and text clicks must apply the same rule (B2 in the audit).
+ * Returns null when no link is involved, which the policy lets through.
+ */
+export async function clickTargetHref(locator) {
+    return (await locator.evaluate(clickTargetHrefProbe)) ?? null;
+}
 /**
  * Shared click core: enforce the URL policy for link targets, run the
  * Codex-style geometry ladder with the Playwright actionability fallback,
@@ -264,7 +275,7 @@ export async function clickText(session, text, signal) {
  * in the landing note; shared is how many elements matched it (0 for refs).
  */
 export async function clickLocator(session, locator, signal, label, shared) {
-    session.assertClickTargetAllowed(await locator.getAttribute('href'));
+    session.assertClickTargetAllowed(await clickTargetHref(locator));
     const page = session.currentPageSync();
     const urlBefore = page.url();
     let point;
@@ -396,8 +407,9 @@ export async function clickAtRef(session, ref, signal) {
         const page = session.currentPageSync();
         const urlBefore = page.url();
         // Ref mode resolves the element before clicking, so the link policy can
-        // be enforced up front — the same rule browser_click applies.
-        session.assertClickTargetAllowed(await locator.getAttribute('href'));
+        // be enforced up front — the same rule browser_click applies, including the
+        // ancestor link a nested control would navigate through.
+        session.assertClickTargetAllowed(await clickTargetHref(locator));
         try {
             // Codex-style geometry click with obstruction awareness:
             // scroll (centre → end → start), wait for the bounding rect to
@@ -492,9 +504,9 @@ export async function fill(session, ref, text, signal) {
                 lastError = error;
                 continue;
             }
-            // Post-action verification: read the value back. Lenient match
-            // so formatted/masked inputs do not false-positive, but a value
-            // that never stuck gets one retry then a clear diagnostic.
+            // Post-action verification: read the value back and require it to match
+            // what was typed (whitespace-normalized only), so a value the page ignored
+            // or rewrote gets one retry then a clear diagnostic.
             written = await session.verifyFill(locator, tag, text);
             if (written)
                 break;
@@ -507,24 +519,44 @@ export async function fill(session, ref, text, signal) {
         return session.settleAndSnapshot(page, false);
     });
 }
+/**
+ * Normalize a field value before comparing. Two levels of forgiveness, both of them
+ * things a page does to a value *after* we wrote it, not differences in what we wrote:
+ * whitespace is collapsed, and everything that is not a letter or a digit is dropped
+ * (`1,000` ≡ `1000`) with case folded (`abc` ≡ `ABC`). That covers input masks and
+ * currency fields — which `browser_fill`'s own description names — while still failing
+ * a genuinely different value: `ABCD`→`ZZZZ`, `John`→`Jane` and `1234`→`12345` all
+ * differ once normalized. The old readback accepted a length tolerance and containment,
+ * which is how those used to report success (audit B4).
+ */
+export function normalizeFillText(value) {
+    return String(value)
+        .normalize('NFKC')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, '');
+}
 /** Read the field back and decide whether the fill landed. */
 export async function verifyFill(_session, locator, tag, text) {
+    const expected = normalizeFillText(text);
     try {
         if (tag === 'select') {
             const label = await locator.evaluate((el) => {
                 const o = el.selectedOptions[0];
                 return o === undefined ? '' : o.label;
             });
-            return label === text;
-        }
-        const value = await locator.inputValue();
-        if (value === text)
-            return true;
-        // Lenient: formatted inputs (masks, prefixes) rewrite the display
-        // value; accept containment or a near-equal length as "written".
-        return (text.length > 0 &&
-            value.length > 0 &&
-            (value.includes(text) || text.includes(value) || Math.abs(value.length - text.length) <= 2));
+            return normalizeFillText(label) === expected;
+        }
+        if (tag === 'input' || tag === 'textarea') {
+            return normalizeFillText(await locator.inputValue()) === expected;
+        }
+        // contenteditable / role=textbox elements have no inputValue(); calling it
+        // throws, which used to turn a fill that HAD landed into VALUE_NOT_SET.
+        // Judge the text the page would show instead.
+        const contents = await locator.evaluate((el) => {
+            const node = el;
+            return [el.textContent ?? '', typeof node.innerText === 'string' ? node.innerText : ''];
+        });
+        return contents.some((candidate) => normalizeFillText(candidate) === expected);
     }
     catch {
         return false;

package/lib/page-diagnostics.d.ts

@@ -62,4 +62,9 @@ export declare function networkRequests(session: PlaywrightSession, args: {
         failure: string | null | undefined;
     }[];
 };
+/**
+ * Bounded page data for browser_extract. Credential values (password fields and
+ * password-autocomplete fields) are blanked inside the page before the payload
+ * leaves the browser: the extract prompt is sent to an auxiliary model.
+ */
 export declare function pageData(session: PlaywrightSession): Promise<unknown>;

package/lib/page-diagnostics.js

@@ -173,6 +173,11 @@ export function networkRequests(session, args) {
         })),
     };
 }
+/**
+ * Bounded page data for browser_extract. Credential values (password fields and
+ * password-autocomplete fields) are blanked inside the page before the payload
+ * leaves the browser: the extract prompt is sent to an auxiliary model.
+ */
 export async function pageData(session) {
     return session.run(async () => {
         session.assertLive();
@@ -182,7 +187,38 @@ export async function pageData(session) {
             const fn = window.__dshPageData;
             if (typeof fn !== 'function')
                 return { url: location.href, title: document.title, text: '', truncated: false, links: [], inputs: [] };
-            return fn({ maxTextChars: 30000, maxLinks: 300, maxInputs: 200 });
+            const data = fn({ maxTextChars: 30000, maxLinks: 300, maxInputs: 200 });
+            // Credentials never leave the page. __dshPageData reads every field's current
+            // value, and browser_extract pastes that object into an auxiliary model's
+            // prompt, so a login or change-password page put the plaintext password into
+            // that prompt (audit B3). The field itself stays — "there is a password box
+            // here" is useful page structure — but its value is blanked. The collector and
+            // this pass use the same selector over the same document, so the i-th entry is
+            // the i-th field.
+            if (data !== null && Array.isArray(data.inputs)) {
+                const fields = document.querySelectorAll('input, select, textarea');
+                for (let index = 0; index < data.inputs.length; index += 1) {
+                    const entry = data.inputs[index];
+                    const field = fields[index];
+                    if (entry === undefined || field === undefined)
+                        continue;
+                    const type = (field.getAttribute('type') ?? '').toLowerCase();
+                    const autocomplete = (field.getAttribute('autocomplete') ?? '').toLowerCase();
+                    if (type === 'password' ||
+                        autocomplete.includes('current-password') ||
+                        autocomplete.includes('new-password') ||
+                        // One-time codes and card numbers are just as sensitive as passwords: a
+                        // 2FA code in the prompt can be replayed, and a card number is payment
+                        // data (independent review, P2-7). The field stays, its value does not.
+                        autocomplete.includes('one-time-code') ||
+                        autocomplete.includes('cc-number') ||
+                        autocomplete.includes('cc-csc') ||
+                        autocomplete.includes('cc-exp')) {
+                        entry['value'] = '';
+                    }
+                }
+            }
+            return data;
         };
         let data;
         try {

package/lib/page-probes.d.ts

@@ -55,6 +55,18 @@ export declare const pageStabilityProbe: (arg: {
     frames: number;
     timeoutMs: number;
 }) => Promise<boolean>;
+/**
+ * The href a click on this element would follow: the element's own href, or the
+ * nearest ancestor `<a href>` — crossing shadow-root boundaries, the same way the
+ * hit-test walks. Raw-coordinate clicks already check `closest('a[href]')`; ref and
+ * text clicks used to look only at the element itself, so a button/span nested in an
+ * off-domain `<a>` reached the outside host while every check passed. This probe is
+ * that missing layer: locator.evaluate(clickTargetHrefProbe).
+ *
+ * A policy check, not a navigation: `javascript:` hrefs are returned as-is and the
+ * caller's session policy keeps its existing exemption for them.
+ */
+export declare const clickTargetHrefProbe: (el: Element) => string | null;
 /**
  * The click-point hit test, moved out of the session so it lives with the other page-side
  * functions: it is serialized into the page by locator.evaluate(), so the same

package/lib/page-probes.js

@@ -201,6 +201,39 @@ export const pageStabilityProbe = (arg) => new Promise((resolve) => {
     ];
     requestAnimationFrame(tick);
 });
+/**
+ * The href a click on this element would follow: the element's own href, or the
+ * nearest ancestor `<a href>` — crossing shadow-root boundaries, the same way the
+ * hit-test walks. Raw-coordinate clicks already check `closest('a[href]')`; ref and
+ * text clicks used to look only at the element itself, so a button/span nested in an
+ * off-domain `<a>` reached the outside host while every check passed. This probe is
+ * that missing layer: locator.evaluate(clickTargetHrefProbe).
+ *
+ * A policy check, not a navigation: `javascript:` hrefs are returned as-is and the
+ * caller's session policy keeps its existing exemption for them.
+ */
+export const clickTargetHrefProbe = (el) => {
+    const own = el.getAttribute('href');
+    if (own !== null && own !== '')
+        return own;
+    let node = el;
+    // Document order upward, hopping from a shadow root to its host when the
+    // element lives inside one. The seen guard makes a malformed cycle terminate.
+    const seen = [];
+    while (node !== null) {
+        if (seen.indexOf(node) !== -1)
+            break;
+        seen.push(node);
+        const anchor = node.closest('a[href]');
+        if (anchor !== null)
+            return anchor.getAttribute('href');
+        const root = node.getRootNode
+            ? node.getRootNode()
+            : null;
+        node = root !== null && root !== undefined && root.host !== undefined ? root.host : null;
+    }
+    return null;
+};
 export const hitTest = (el) => {
     const r = el.getBoundingClientRect();
     const w = r.width;

package/lib/page-snapshot.js

@@ -110,9 +110,9 @@ export async function captureAria(session, page, opts) {
         const legacy = await session.captureLegacy(page, opts);
         return {
             ...legacy,
-            engineNote: 'smart mode could not read session page, so it was rendered with the compatible engine. ' +
+            engineNote: 'smart mode could not read this page, so it was rendered with the compatible engine. ' +
                 'The refs below belong to the compatible engine. Nothing is wrong with the page; ' +
-                'switch the page-reading mode in Settings if you want to stop seeing session.',
+                'switch the page-reading mode in Settings if you would rather not see this fallback notice.',
         };
     }
     return {

package/lib/tool-render.js

@@ -1,4 +1,4 @@
-import { CHALLENGE_NOTE, detectChallenge } from "./challenge.js";
+import { CHALLENGE_NOTE, detectChallenge, detectSilentPage } from "./challenge.js";
 import { renderSnapshot, renderSnapshotDiff } from "./snapshot-render.js";
 /**
  * Render one diagnostics payload as one line per entry. Diagnostics are read when
@@ -57,9 +57,32 @@ export function renderDiagnostics(kind, value) {
 }
 /** Project a provider snapshot into its canonical tool value. */
 export function snapshotValue(snapshot) {
-    const challenge = detectChallenge(snapshot);
+    // The ref count travels with the snapshot on purpose: the wording tier needs it
+    // to tell a real wall (nothing to click) from a results page whose title merely
+    // contains the phrase. Measured on 百度: 0 refs on the challenge, 57/81 on the
+    // search pages titled "安全验证_百度搜索" / "滑块验证_百度搜索".
+    const challenge = detectChallenge({
+        url: snapshot.url,
+        title: snapshot.title,
+        nodes: snapshot.nodes,
+        refs: snapshot.totalRefs,
+        ...(snapshot.response !== undefined ? { response: snapshot.response } : {}),
+    });
     const tree = renderSnapshot(snapshot);
     const notes = [];
+    // The HTTP status was captured for challenge detection but never shown, so a
+    // 404/500 error page reached the model looking like an ordinary page — measured
+    // 2026-10-17 on a real MDN 404: status 404, 35 refs, and nothing in the result
+    // said so. Suppressed when a challenge was identified, because that note
+    // already names the reason.
+    const status = snapshot.response?.status;
+    if (challenge === null && status !== undefined && (status < 200 || status >= 300)) {
+        notes.push('[http ' +
+            String(status) +
+            '] the server answered ' +
+            String(status) +
+            ' for this document, so what follows may be an error page or an interception page rather than the content you asked for.');
+    }
     const dialog = snapshot.dialogNote;
     if (dialog !== undefined && dialog !== '')
         notes.push(dialog);
@@ -80,6 +103,18 @@ export function snapshotValue(snapshot) {
     const stall = snapshot.stallNote;
     if (challenge === null && stall !== undefined && stall !== '')
         notes.push(stall);
+    // The backstop above needs an action to compare before and after; a page with
+    // nothing to click never gets one, so the emptiest wall-like pages used to say
+    // nothing at all. Only on a successful status: a 4xx/5xx already has its own line.
+    const healthyStatus = status === undefined || (status >= 200 && status < 300);
+    // A parked dialog means the page is fine, it is the dialog that blocks us: the
+    // dialog note already says what to do, and adding "nothing here" contradicts it.
+    const dialogPending = snapshot.dialogNote !== undefined && snapshot.dialogNote !== '';
+    if (challenge === null && healthyStatus && !dialogPending) {
+        const silent = detectSilentPage({ refs: snapshot.totalRefs, nodes: snapshot.nodes, title: snapshot.title });
+        if (silent !== null)
+            notes.push(silent);
+    }
     const head = notes.length > 0 ? notes.join('\n\n') + '\n\n' : '';
     // Incremental diff rides along when the provider computed one (snapshot.diff).
     const diffBlock = snapshot.diff !== undefined ? '\n\n' + renderSnapshotDiff(snapshot.diff) : '';

package/lib/tool-types.d.ts

@@ -53,6 +53,12 @@ export interface ChallengeSnapshot {
     readonly title?: string;
     readonly url?: string;
     readonly nodes?: readonly ChallengeNode[];
+    /**
+     * Actionable-element count. The wording tier uses it to tell a challenge page
+     * (nothing to click) from an ordinary page whose *title* merely contains the
+     * phrase — searching Baidu for "安全验证" produces exactly that false positive.
+     */
+    readonly refs?: number;
     /** Main document response metadata; absent when no navigation response was seen. */
     readonly response?: DocumentResponse;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-playwright-codex",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "Browser automation for DeepSeek Harness: fill in forms, scrape lists and work across tabs in real pages, using the logins you already have. Runs in a visible window that stays quiet when minimised, and stops for sign-ins, CAPTCHAs and native dialogs instead of confirming for you.",
   "license": "MIT",
   "type": "module",
@@ -57,13 +57,13 @@
     "preflight": "node scripts/preflight.mjs ."
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "*",
+    "@deepseek-ai/schemastery": "^3.18.4",
     "playwright-core": "~1.62.1"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "*",
-    "@deepseek-ai/dsh-llm": "*",
-    "@deepseek-ai/dsh-tools": "*"
+    "@deepseek-ai/cordis": ">=4.0.4",
+    "@deepseek-ai/dsh-llm": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": ">=0.2.0-rc.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.4",

package/scripts/dsh-browser-verify.mjs

@@ -13,6 +13,8 @@
  *
  * 读 lib/，但**必须先 build**：npm run verify 会先跑 npm run build，直接
  * node scripts/... 跑则会撞上最后一组检查（lib/ 不旧于 src/）。
+ * npm 安装形态没有 src/（files 里不含它）：最后一组自动**跳过并说明**，不算失败，
+ * 所以从 npm 装上之后这条命令照样能跑通 —— README 的「装到即可跑」必须是真的。
  *
  * 为什么不像测试那样用 tsx 直读 src/：tsx（esbuild keepNames）会把传给
  * page.evaluate 的函数包成 __name(...)，而页面里没有这个符号 ——
@@ -20,7 +22,7 @@
  * 失效。lib/ 是编译产物，没有这层包裹，也正好是宿主真正加载的东西。
  */
 import http from 'node:http'
-import { readdirSync, statSync } from 'node:fs'
+import { existsSync, readdirSync, statSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { PlaywrightProvider } from '../lib/provider.js'
@@ -32,12 +34,13 @@ import { getEffectiveEngine, setSnapshotEngine } from '../lib/runtime-state.js'
 // 设置页的「页面识别方式」存在 ~/.dsh/dsh-browser-playwright.state.json，运行时状态层
 // 允许用 DSH_BROWSER_STATE_FILE 把它指向别处（src/runtime-state.ts 里为测试留的开关）。
 // 指向一个不存在的文件 = engine 回到配置默认值 legacy，本脚本的期望值就是按它写的。
-// 不隔离的话：用户把开关拨到「智能模式」，这份 57 项验收就会假失败（2026-10-01 实测）。
+// 不隔离的话：用户把开关拨到「智能模式」，这份验收就会假失败（2026-10-01 实测）。
 // 注意 [1]–[7] 因此都跑在兼容模式下；智能模式由 [8] 显式切过去跑（隔离状态文件里切，
 // 不碰用户的真实选择）。
 process.env.DSH_BROWSER_STATE_FILE = path.join(os.tmpdir(), 'dsh-browser-verify-state-isolated.json')
 
 let pass = 0
+let skipped = 0
 const failures = []
 function check(name, ok, detail) {
   if (ok) {
@@ -455,22 +458,31 @@ await provider.dispose()
 server.close()
 
 // [7] lib/ 是宿主真正加载的产物：源码改完没 build，跑绿了也是白跑。
+// npm 包里没有 src/（package.json 的 files 只收 lib/），安装形态下这一组无从比较：
+// 跳过并说明原因，不记失败、不影响退出码 —— 否则装上 npm 包之后这条命令必崩，
+// 与 README/CHANGELOG 的「装到即可跑」直接矛盾。
 console.log('[7] lib/ 与 src/ 同步（宿主加载 lib/）')
-const stale = []
-for (const file of readdirSync(new URL('../src', import.meta.url))) {
-  if (!file.endsWith('.ts') || file.endsWith('.d.ts')) continue
-  const src = statSync(new URL('../src/' + file, import.meta.url)).mtimeMs
-  const built = statSync(new URL('../lib/' + file.replace(/\.ts$/, '.js'), import.meta.url), {
-    throwIfNoEntry: false,
-  })
-  if (built === undefined || built.mtimeMs < src) stale.push(file.replace(/\.ts$/, '.js'))
+if (!existsSync(new URL('../src', import.meta.url))) {
+  skipped += 1
+  console.log('  （跳过）没有 src/：这是 npm 安装形态')
+} else {
+  const stale = []
+  for (const file of readdirSync(new URL('../src', import.meta.url))) {
+    if (!file.endsWith('.ts') || file.endsWith('.d.ts')) continue
+    const src = statSync(new URL('../src/' + file, import.meta.url)).mtimeMs
+    const built = statSync(new URL('../lib/' + file.replace(/\.ts$/, '.js'), import.meta.url), {
+      throwIfNoEntry: false,
+    })
+    if (built === undefined || built.mtimeMs < src) stale.push(file.replace(/\.ts$/, '.js'))
+  }
+  check('lib/ 不旧于 src/（旧了就先 npm run build）', stale.length === 0, stale.join(', '))
 }
-check('lib/ 不旧于 src/（旧了就先 npm run build）', stale.length === 0, stale.join(', '))
 
 console.log('')
+const skipNote = skipped > 0 ? '，跳过 ' + skipped + ' 项' : ''
 console.log(
   failures.length === 0
-    ? '全部通过 (' + pass + ' 项)'
+    ? '全部通过 (' + pass + ' 项' + skipNote + ')'
     : '失败 ' + failures.length + ' 项 / 共 ' + (pass + failures.length) + ' 项: ' + failures.join(', '),
 )
 process.exit(failures.length === 0 ? 0 : 1)