dsh-browser-playwright-codex 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -3,6 +3,61 @@
 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.5.4
+
+一句话摘要：**把第三方评审（2026-10-11，8.6/10）指出的"对外表述与现实脱节"修干净，并把这些说法变成守卫** —— 运行时行为零变化。但 README / SECURITY / NOTICE 是**随包发布**的，所以必须发一版：不发版，从 npm 装的用户看到的仍是那句"不在 npm 上"。
+
+### Fixed
+
+- **README 声称"这个包不在 npm 上"**（与同一文件里的 `# from npm` 自相矛盾）：包从 v0.5.1 起已在 npm 上。改为「From npm (published since v0.5.1)」并给出 npm 安装命令，仓库与本地 link 两种方式保留。
+- **NOTICE.md 的 7 个路径全部失效**（写成 `docs/PLUGIN-README.md`、`docs/DIALOG-POLICY.md` …，实际都在仓库根目录）：已按根相对路径改正。同一段里指向**上游文档**的 `docs/browser-safety.md` 保持原样 —— 那是给读者的来源索引，不是我们的文件。顺带修掉 `MODE-TRADE-OFFS.md` 里同类一处。
+- **README"安全一览"写死"2 Critical"**，而 dsh.so 当前扫描是 **1 Critical / 3 Warning / 22 Info**（v0.5.3、75 文件）：改为不含数字的说法。
+- **SECURITY.md §2 与表格按当前扫描重写**：Critical 就是 `browser_evaluate` 的动态求值（`src/session.ts` → `lib/session.js`，出厂关闭）、3 条 Warning、22 条 Info；v0.4.9 的 2/5/26 作为历史留在引用块里，并写明"以他们的报告为准"。
+- **SECURITY.md 里 `src/playwright.ts (~:2041)` 这类"文件名 + 行号"引用在 0.5.x 拆分后失效**（该文件现在 55 行）：改为模块名 —— 行号会漂，模块名不会。
+- **三份发帖草稿里的"2 个 Critical"**：去掉数字，改为"那个 Critical"。
+- **几处把上游文件写得像我们自己的**：`docs/articles/focus-stealing.md`、`patches/README.md`、`codex-rules.md` 里标明那是**上游仓库**的文件。
+- **README 增加 "Compatibility" 段**：写明构建与测试用的 DSH 版本是 `0.2.0-rc.1`、peer 范围故意留 `*`（换新版 harness 仍可安装）、升级后跑 `npm run doctor` 复核本插件导入的具名导出是否还在。
+
+### Added
+
+- **`tests/doc-reality.test.ts`（5 条守卫）**，把"文档对世界说的话"变成 CI 会拦的事实：
+  1. 现行文档不得声称"不在 npm 上"（CHANGELOG 是历史，跳过）；
+  2. README 必须给出 npm 安装路径（与第 1 条互为孪生）；
+  3. 反引号包着的仓库路径必须真的在那个位置（规则：该路径不存在、但同名文件在本仓库里存在才报 —— 不误伤上游引用；`./`、`../` 相对所在文档解析，其余相对仓库根）；
+  4. 文档里的「文件:行号」引用不得越界（行号 > 该文件现在的行数即报错 —— 正是 0.5.x 重构制造的那类腐烂）；
+  5. 带数字的 `N Critical` 只允许出现在 SECURITY.md（计数会变，其它文档一律用文字指过去）。
+  每条都做了"有牙复检"：把对应的旧文案塞回去，守卫立刻报红。
+
+## 0.5.3
+
+一句话摘要：**源码按职责拆开、可维护性大幅提升，并修掉拆分过程中暴露的三处隐患** —— 对用户可见的行为零变化：工具面、配置接口、出厂默认值全部不动。本版同时修掉中文说明里一处会让人误判权限状态的过期说法。
+
+### Changed
+
+- 源码按职责拆开：`playwright.ts` **2,727 → 55 行**，只剩注册入口 `apply()` 与一张给来访者的模块地图；对外零变化（loader 三行、`package.json` exports、`lib/` 入口、工具面全都不动）。做法是"纯搬运、一次一个接缝"：每步 `npm test` + `npm run verify` + 解析一致性脚本全绿才提交，任何一步不绿就当场回退（过程中真回退过一次：拆 `tool.ts` 时用启发式切错边界，回退后改用 TypeScript 解析器取精确范围）。
+  - `provider.ts`（370 行）：profile/context 生命周期、会话注册、空闲回收、弹窗登记、标签记账。
+  - `session.ts`（668）：会话骨架 —— 持有 page/context，处理弹窗、截图、页面数据、evaluate/CDP，并把动作/快照/诊断转发给对应模块。
+  - `page-actions.ts`（786）：可点击性检查、点击（几何阶梯 + Playwright 兜底）、填充与写后核对、按键、悬停、滚动、前进后退、标签切换。
+  - `page-snapshot.ts`（335）：等页面稳定、兼容/智能两种采集、ref 签名与差异、ref 解析与存活校验。
+  - `page-diagnostics.ts`（198）：控制台消息、页面错误、网络请求的有界记录 + 失败原因归类。
+  - `page-probes.ts`（288）：会被序列化进浏览器的页内函数（铁律：必须自包含）。
+  - `window-focus.ts`（56）：承载窗口是否最小化、后台建标签 —— 只为了让窗口/标签不打扰用户。
+  - `browser-lifecycle.ts`（183）：启动/复用持久化 context、清理 Chrome 锁、启动与 profile 参数。
+  - `login-state.ts`（90）：登录态导出/恢复（窗口最小化读不到状态时只取 cookies）。
+  - `config.ts` / `url-policy.ts` / `challenge.ts` / `extract.ts` / `tool-types.ts` / `tool-schemas.ts` / `tool-render.ts`：配置与常量、URL 策略、人机验证识别、提取工具辅助、工具面类型/schema/渲染。
+- 12 个模块的文件说明与内容对齐（此前 6 处内容变了没改、5 处还留着拆分当天的占位文案）。
+
+### Fixed
+
+- **入口子路径恢复 `Config` 导出**（`./playwright`）：拆分时 schema 被搬进 `config.ts` 而入口忘了转出 —— Cordis 因此不会补默认值，而配置块里没有 `snapshot`，provider 又直接读 `config.snapshot.engine`，**下次重启就起不来**。该回归只存在于 main、从未随版本发布。现已补上入口契约测试：从 `src` 与 `lib` 两条路检查导出、校验 schema 补出默认值、复现"不含 `snapshot` 的 profile 配置"这一故障场景，并断言 `lib/` 与 `src/` 行为一致（防漂移）。
+- **页内探测守卫覆盖不到 `hitTest`**：它原本是 `resolveClickPoint` 里的嵌套命名函数（同样会被 `keepNames` 改写成 `__name`），现已搬进 `page-probes.ts`；守卫从"手写 4 个函数"改成**枚举该模块所有函数导出**（并断言至少 5 个，避免空跑）。
+- **中文说明写明两个闸门出厂关闭**：原文写"本包自带的 bundle 层是… `allowEvaluate`/`allowCdp` 打开"，与出厂 `false`/`false` 矛盾，读者会以为"页面任意 JS / 原始 CDP"默认可用。现在写明出厂关闭并指向 §4.6。
+- **文档守卫补洞**：原规则要求行内出现 `: true|false`，而措辞检查写在这个提前返回**之后** → "…`allowCdp` 打开"这类写法永远走不进检查。现改为两条带邻近性的规则；负向自检三种坏写法全部被抓住，且 `SECURITY.md` 里那句合法表述不被误报。
+- **新增两条守卫**：模块文件说明不得留下拆分脚本的占位文案；页内函数必须自包含（第 5 个函数 `hitTest` 因此归位）。
+- **测试的导航预算 2500ms → 15s**：冷启动的 windows runner 连加载本机 fixture 页都超时（`page.goto: Timeout 2500ms exceeded`），一次挂掉 4 条与超时无关的用例；没有任何测试断言导航超时行为，journeys 另有 25s 兜底。
+- **拆分过程中暴露的 3 处隐患**：`WeakMap<Request>` 实际落在浏览器内置的 DOM `Request`（两个类型身份）、`provider.ts` ⇄ `session.ts` 的**运行时**循环依赖（多个测试文件直接加载失败，用例从 119 掉到 46）、测试与脚本仍在旧路径引用搬走的符号。
+- 清掉搬迁后残留的未使用 import/参数（以 `tsc --noUnusedLocals --noUnusedParameters` 为裁判，28 处 → 0）。
+
 ## 0.5.2
 
 一句话摘要：**查出 Windows CI 抖动的真正根因并修掉**—— 测试用的转译器 tsx/esbuild 会开启 `keepNames`，把"要送进浏览器执行"的页内函数里的**命名内部函数**改写成 `__name(fn, "名字")`，而 `__name` 只存在于模块作用域、页面里没有 → 探测每次抛 `ReferenceError`，且被 `catch` 吞成无声的 `unreachable`。后果是**几何点击路径从来没工作过**：所有点击都退化成 Playwright 兜底点击（上限 3 秒），慢速 Windows runner 一超时，就把几何路径那句**误导性**的错误抛了出来。

package/README.md

@@ -31,16 +31,22 @@ dsh plugin --profile <name> add github:miqian-nomad/dsh-browser-playwright-codex
 - **强力工具默认关闭** — `browser_evaluate` / `browser_cdp` are **not registered at all** unless your
   deployment opts in; this package ships both off.
 
-**安全一览 / Security at a glance** — dsh.so's scanner reports *2 Critical* on this repository, and
-both findings **are** the implementation of `browser_evaluate`, which this package ships switched off.
-Every finding is explained gate by gate in [SECURITY.md](SECURITY.md), together with 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).
+**安全一览 / 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
+live number.
 
 ## Install
 
-This package is **not on npm** — the repository is the distribution channel, so install it from GitHub
-(or link a checkout):
+From npm (published since v0.5.1 — [npmjs.com/package/dsh-browser-playwright-codex](https://www.npmjs.com/package/dsh-browser-playwright-codex)):
+
+```sh
+dsh plugin --profile <name> add dsh-browser-playwright-codex
+```
+
+Or straight from the repository / a checkout:
 
 ```sh
 dsh plugin --profile <name> add github:miqian-nomad/dsh-browser-playwright-codex
@@ -49,6 +55,10 @@ 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".
+
 `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/`.
 

package/SECURITY.md

@@ -4,7 +4,7 @@ This plugin drives a **real browser with your login state**. That is the point o
 the thing worth being careful about. This file answers the two questions a reader actually has:
 
 1. **What can it do to me?**
-2. **Why does dsh.so's scanner report "2 Critical"?**
+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
 this package ships switched off** — it is not registered at all until a deployment turns it on.
@@ -68,18 +68,22 @@ Nothing else.
 
 ---
 
-## 2. Why the scanner reports "2 Critical"
+## 2. What the scanner reports, and which gate contains it
 
-dsh.so runs `dsh-plugin-vet` over the whole repository. On v0.4.9 it reports **2 Critical, 5 Warning,
-26 Info** across 57 files — and it is **right about the capability**. Here is each one, with the gate
-that decides whether it is reachable at all.
+dsh.so runs `dsh-plugin-vet` over the whole repository. Their scan of **v0.5.3 (2026-10-11)** reports
+**1 Critical, 3 Warning, 22 Info** across 75 files — and it is **right about the capability**. Here is
+each one, with the gate that decides whether it is reachable at all.
+
+> 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
+> change; **their report is the live number**, and this table is a map, not a snapshot.
 
 | Level | Finding (as reported) | What it actually is | Reachable when |
 |---|---|---|---|
-| Critical | `new Function('return (' + expression + ')')` — `src/playwright.ts` (~:2041) and its `lib/` mirror | The body of **`browser_evaluate`**: it wraps your expression and runs it in the page. This is what "run JavaScript in the page" means; there is no way to implement it without dynamic evaluation. | Only when `allowEvaluate: true`. **The package ships `false`, so the tool is not registered.** |
-| Warning | `fs.writeFileSync` of a JSON blob (3 sites: `playwright.ts` ×2, `runtime-state.ts`) | Exporting the login state (`cookies` + `localStorage`) so a closed window can be reopened still logged in, and the small runtime state file behind the Settings switches. | Always — it is how login persistence works. The files live under your DSH home. |
+| Critical | `new Function('return (' + expression + ')')` — reported in `lib/session.js` (source: `src/session.ts`) | The body of **`browser_evaluate`**: it wraps your expression and runs it in the page. This is what "run JavaScript in the page" means; there is no way to implement it without dynamic evaluation. | Only when `allowEvaluate: true`. **The package ships `false`, so the tool is not registered.** |
+| Warning | `fs.writeFileSync` of a JSON blob (`lib/login-state.js`, `lib/runtime-state.js`) | Exporting the login state (`cookies` + `localStorage`) so a closed window can be reopened still logged in, and the small runtime state file behind the Settings switches. | Always — it is how login persistence works. The files live under your DSH home. |
 | 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 ×26 | `localStorage` reads, `process.env` reads, 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"*. | — |
+| Info ×22 | `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"*. | — |
 
 Two honest notes:
 
@@ -87,8 +91,9 @@ Two honest notes:
   your deployment turns it on. A scanner that reads code cannot see a runtime gate.
 - 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.
 
 ## 3. How to check all of this yourself
 

package/lib/browser-lifecycle.d.ts

@@ -0,0 +1,12 @@
+import type { PlaywrightProvider } from './provider.ts';
+/**
+ * Ensure the shared persistent context is alive (persistent mode). A
+ * profile-backed window is launched once and reused until closed by the
+ * last owner, idle disposal, or an external close; login state lives in
+ * the profile plus the exported state file, so reopening is seamless.
+ */
+export declare function ensureContext(provider: PlaywrightProvider): Promise<import("playwright-core").BrowserContext>;
+/** Remove stale Chrome singleton lock files inside the profile directory. */
+export declare function clearChromeLocks(provider: PlaywrightProvider): Promise<void>;
+/** Launch the browser once, probing the configured or auto-detected channel. */
+export declare function ensureBrowser(provider: PlaywrightProvider): Promise<import("playwright-core").Browser>;

package/lib/browser-lifecycle.js

@@ -0,0 +1,186 @@
+/**
+ * 浏览器的生命：启动/复用持久化 context、清理 Chrome 锁、以及启动与 profile 相关参数。
+ * 窗口**焦点**行为（承载窗口是否最小化、要不要在后台建标签）在 window-focus.ts。
+ * @module dsh-browser-playwright-codex/browser-lifecycle
+ */
+import { chromium } from 'playwright-core';
+import path from 'node:path';
+import fs from 'node:fs';
+import { AUTO_CHANNELS, HUMANIZED_LAUNCH } from "./config.js";
+import { SNAPSHOT_SCRIPT } from "./injected.js";
+import { BrowserError, launchFailed } from "./errors.js";
+/**
+ * Ensure the shared persistent context is alive (persistent mode). A
+ * profile-backed window is launched once and reused until closed by the
+ * last owner, idle disposal, or an external close; login state lives in
+ * the profile plus the exported state file, so reopening is seamless.
+ */
+export async function ensureContext(provider) {
+    if (provider.context !== undefined) {
+        try {
+            const browser = provider.context.browser();
+            if (browser !== null && browser.isConnected())
+                return provider.context;
+        }
+        catch {
+            /* context died underneath us: relaunch */
+        }
+        provider.context = undefined;
+    }
+    fs.mkdirSync(provider.profileDir, { recursive: true });
+    const { executablePath, channel, headless } = provider.config.launch;
+    const headful = !headless;
+    const attempts = [];
+    const baseOptions = {
+        headless,
+        // Headful windows must render like a normal Chrome the user opened
+        // by hand: the page viewport equals the real window size and the
+        // system DPI scaling (e.g. 150%) is honoured. Playwright's default
+        // is the opposite — it pins every page to a fixed CSS viewport at
+        // deviceScaleFactor 1 via Emulation.setDeviceMetricsOverride, which
+        // on scaled displays overflows the window: content looks zoomed in
+        // and clipped. viewport: null disables that override entirely.
+        // Headless mode keeps the fixed viewport (no window to track).
+        ...(headless ? { viewport: provider.config.launch.viewport } : { viewport: null }),
+        ignoreHTTPSErrors: provider.config.launch.ignoreHTTPSErrors,
+        ...HUMANIZED_LAUNCH,
+        args: [
+            '--no-first-run',
+            '--no-default-browser-check',
+            // Open maximised like a human would, so the first paint fills
+            // the screen instead of a small default window.
+            ...(headful ? ['--start-maximized'] : []),
+            ...HUMANIZED_LAUNCH.args,
+        ],
+    };
+    const start = async (extra) => {
+        try {
+            provider.context = await chromium.launchPersistentContext(provider.profileDir, { ...baseOptions, ...extra });
+        }
+        catch (error) {
+            // A stale Chrome singleton lock from a dirty shutdown breaks a
+            // relaunch into the same profile; clear the lock files and
+            // retry once before surfacing the failure.
+            if (error instanceof Error && /user data directory|SingletonLock|ProcessSingleton/i.test(error.message)) {
+                await provider.clearChromeLocks();
+                provider.context = await chromium.launchPersistentContext(provider.profileDir, { ...baseOptions, ...extra });
+            }
+            else {
+                throw error;
+            }
+        }
+        const ctx = provider.context;
+        // External close (user closed the window, crash): forget every
+        // session handle bound to this context; the next acquire relaunches.
+        void ctx.on('close', () => {
+            if (provider.context !== ctx)
+                return;
+            provider.context = undefined;
+            for (const [key, entry] of [...provider.entries]) {
+                if (entry.context !== ctx)
+                    continue;
+                if (entry.timer !== undefined)
+                    clearTimeout(entry.timer);
+                provider.entries.delete(key);
+            }
+        });
+        ctx.on('page', (page) => provider.armDialogGuard(page));
+        try {
+            await provider.restoreState(ctx);
+        }
+        catch {
+            /* malformed state file must not block startup */
+        }
+        await ctx.addInitScript(SNAPSHOT_SCRIPT);
+        // The initial blank page predates addInitScript: reload so the
+        // snapshot engine and restored localStorage apply on first use.
+        for (const page of ctx.pages()) {
+            await page.reload({ waitUntil: 'domcontentloaded' }).catch(() => { });
+        }
+        return ctx;
+    };
+    if (executablePath !== undefined) {
+        try {
+            return await start({ executablePath });
+        }
+        catch (error) {
+            provider.launchError = error;
+            attempts.push('executablePath ' + executablePath);
+        }
+    }
+    else {
+        const channels = channel !== undefined && channel !== '' ? [channel] : [...AUTO_CHANNELS];
+        for (const candidate of channels) {
+            try {
+                return await start({ channel: candidate });
+            }
+            catch (error) {
+                provider.launchError = error;
+                attempts.push('channel ' + candidate);
+            }
+        }
+    }
+    const hint = 'Tried: ' +
+        attempts.join(', ') +
+        '. ' +
+        'Install a Chromium-family browser, or run: npx playwright-core install chromium ' +
+        '(in restricted networks set PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright), ' +
+        'or configure launch.channel / launch.executablePath.';
+    if (provider.launchError instanceof Error &&
+        /executable doesn't exist|not found/i.test(provider.launchError.message)) {
+        throw new BrowserError('NO_BROWSER', hint);
+    }
+    throw launchFailed(provider.launchError);
+}
+/** Remove stale Chrome singleton lock files inside the profile directory. */
+export async function clearChromeLocks(provider) {
+    for (const lock of ['SingletonLock', 'SingletonCookie', 'SingletonSocket']) {
+        try {
+            fs.rmSync(path.join(provider.profileDir, lock), { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+/** Launch the browser once, probing the configured or auto-detected channel. */
+export async function ensureBrowser(provider) {
+    if (provider.browser !== undefined)
+        return provider.browser;
+    const { executablePath, channel, headless } = provider.config.launch;
+    const attempts = [];
+    if (executablePath !== undefined) {
+        try {
+            provider.browser = await chromium.launch({ executablePath, headless, ...HUMANIZED_LAUNCH });
+            return provider.browser;
+        }
+        catch (error) {
+            provider.launchError = error;
+            attempts.push('executablePath ' + executablePath);
+        }
+    }
+    else {
+        const channels = channel !== undefined && channel !== '' ? [channel] : [...AUTO_CHANNELS];
+        for (const candidate of channels) {
+            try {
+                provider.browser = await chromium.launch({ channel: candidate, headless, ...HUMANIZED_LAUNCH });
+                return provider.browser;
+            }
+            catch (error) {
+                provider.launchError = error;
+                attempts.push('channel ' + candidate);
+            }
+        }
+    }
+    const hint = 'Tried: ' +
+        attempts.join(', ') +
+        '. ' +
+        'Install a Chromium-family browser, or run: npx playwright-core install chromium ' +
+        '(in restricted networks set PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright), ' +
+        'or configure launch.channel / launch.executablePath.';
+    if (provider.launchError instanceof Error &&
+        /executable doesn't exist|not found/i.test(provider.launchError.message)) {
+        throw new BrowserError('NO_BROWSER', hint);
+    }
+    throw launchFailed(provider.launchError);
+}

package/lib/challenge.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 人机验证页识别：从快照里判断是否撞上 Cloudflare 之类的挑战页，并给出对应的提示文案。
+ * @module dsh-browser-playwright-codex/challenge
+ */
+import type { ChallengeMatch, ChallengeSnapshot } from './tool-types.ts';
+/**
+ * Detect anti-bot / human-verification challenge pages (Cloudflare
+ * interstitial, Turnstile, reCAPTCHA-style) from a snapshot's title, url and
+ * visible text. We do NOT try to solve them: the correct move for an agent is
+ * to hand the challenge to the human who can see the open window. Returns the
+ * engine name when matched, else null. Matching is conservative to avoid
+ * false positives on ordinary pages.
+ */
+export declare function detectChallenge(snapshot: ChallengeSnapshot): ChallengeMatch | null;
+/**
+ * Instruction appended above a snapshot when the page is an anti-bot
+ * challenge. The browser window is visible on the user's desktop: the agent
+ * should pause and ask the user to complete it by hand, then re-snapshot.
+ */
+export declare const CHALLENGE_NOTE = "[human verification] The page triggered an anti-bot challenge; it is NOT solvable by automation and must NOT be retried blindly. The browser window is open on the user's desktop \u2014 tell the user a verification appeared, wait for them to finish it (a few seconds), then call browser_snapshot again. The clearance cookie is saved to the profile automatically and keeps working for the session.";

package/lib/challenge.js

@@ -0,0 +1,40 @@
+/**
+ * Detect anti-bot / human-verification challenge pages (Cloudflare
+ * interstitial, Turnstile, reCAPTCHA-style) from a snapshot's title, url and
+ * visible text. We do NOT try to solve them: the correct move for an agent is
+ * to hand the challenge to the human who can see the open window. Returns the
+ * engine name when matched, else null. Matching is conservative to avoid
+ * false positives on ordinary pages.
+ */
+export function detectChallenge(snapshot) {
+    const title = snapshot.title ?? '';
+    const url = snapshot.url ?? '';
+    const parts = [];
+    const walk = (nodes, depth) => {
+        for (const node of nodes) {
+            if (parts.length >= 60)
+                return;
+            if (node.name !== undefined && node.name !== '')
+                parts.push(node.name);
+            if (depth < 2 && node.children !== undefined && node.children.length > 0)
+                walk(node.children, depth + 1);
+        }
+    };
+    walk(snapshot.nodes ?? [], 0);
+    const text = [title, url, ...parts].join(' | ').slice(0, 900);
+    const saidCaptcha = parts.some((name) => /(captcha|turnstile|recaptcha|hcaptcha)/i.test(name));
+    if (/just a moment|attention required|checking (your )?browser|cf-chl-|请稍候|验证你的浏览器/i.test(text))
+        return { engine: 'Cloudflare', hint: 'Cloudflare is challenging the browser before letting the page load' };
+    if (/verify (you are|you're|that you are) (a )?human|人机验证|验证您(是|为)人类/i.test(text))
+        return { engine: 'human-verification', hint: 'the page is asking to verify a human visitor' };
+    if (/(captcha|turnstile|recaptcha|hcaptcha)/i.test(text) &&
+        (saidCaptcha || /(captcha|turnstile|recaptcha)/i.test(title)))
+        return { engine: 'captcha', hint: 'the page embedded a captcha-style challenge' };
+    return null;
+}
+/**
+ * Instruction appended above a snapshot when the page is an anti-bot
+ * challenge. The browser window is visible on the user's desktop: the agent
+ * should pause and ask the user to complete it by hand, then re-snapshot.
+ */
+export const CHALLENGE_NOTE = "[human verification] The page triggered an anti-bot challenge; it is NOT solvable by automation and must NOT be retried blindly. The browser window is open on the user's desktop — tell the user a verification appeared, wait for them to finish it (a few seconds), then call browser_snapshot again. The clearance cookie is saved to the profile automatically and keeps working for the session.";

package/lib/config.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 插件配置与常量：schema、启动参数、通道白名单、ref 形态。
+ * @module dsh-browser-playwright-codex/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** Schemastery validation for {@link PlaywrightConfig}. */
+/** Launch configuration for the Playwright provider. */
+export interface PlaywrightConfig {
+    launch: {
+        /** Absolute path to a Chromium-family binary; takes precedence over channel. */
+        executablePath?: string;
+        /** Browser channel: chromium, chrome, msedge. Omitted = auto-detect in that order. */
+        channel?: string;
+        /** Run headful so the user can watch and rescue the browser by hand. */
+        headless: boolean;
+        /** Persistent mode: one shared profile-backed window whose login survives. */
+        persistent: boolean;
+        /** Profile directory for persistent mode; empty means ~/.dsh/browser-profiles/playwright. */
+        profileDir: string;
+        viewport: {
+            width: number;
+            height: number;
+        };
+        /** Per-action navigation/click timeout in milliseconds. */
+        navigationTimeoutMs: number;
+        /** Ignore HTTPS certificate errors. */
+        ignoreHTTPSErrors: boolean;
+    };
+    /** Host suffixes the browser may visit. Empty = any http(s) host. */
+    allowedDomains?: string[];
+    /** Close an idle session's browser context after this many milliseconds. 0 disables. */
+    idleTimeoutMs: number;
+    /** Maximum concurrent browser contexts; acquiring beyond it evicts the least recently used. */
+    maxSessions: number;
+    snapshot: {
+        /** 'legacy' keeps the injected DOM walker; 'aria' uses the official ariaSnapshot(mode:'ai') engine. */
+        engine: 'legacy' | 'aria';
+        maxNodes: number;
+        maxNameLength: number;
+        maxTextLength: number;
+        /** Incremental ref-diff mode; false = always full snapshots (zero behavioral change). */
+        diff: boolean;
+    };
+}
+/** Bounded page data the extraction consumer feeds to a model. */
+export interface PageData {
+    readonly url: string;
+    readonly title: string;
+    readonly text: string;
+    readonly truncated: boolean;
+    readonly links: readonly {
+        readonly text: string;
+        readonly href: string;
+    }[];
+    readonly inputs: readonly {
+        readonly tag: string;
+        readonly type: string;
+        readonly name: string;
+        readonly value: string;
+        readonly label: string;
+        readonly checked: boolean | null;
+    }[];
+}
+/** Schemastery validation for {@link PlaywrightConfig}. */
+export declare const Config: z<PlaywrightConfig>;
+/** Channels probed in order when none is configured. */
+export declare const AUTO_CHANNELS: string[];
+/**
+ * Launch flags that strip Playwright's obvious automation markers (anti-bot
+ * detection layer L1). --enable-automation is what sets navigator.webdriver
+ * and the "controlled by automated test software" infobar; dropping it plus
+ * --disable-blink-features=AutomationControlled makes the browser present as
+ * a plain real Chrome, which it is. No fingerprint spoofing is added: real
+ * Chrome's own values are consistent by construction (spoofing would invent
+ * a device that never existed and draw MORE suspicion).
+ */
+export declare const HUMANIZED_LAUNCH: {
+    ignoreDefaultArgs: string[];
+    args: string[];
+};
+export declare const REF_PATTERN: RegExp;

package/lib/config.js

@@ -0,0 +1,61 @@
+/**
+ * 插件配置与常量：schema、启动参数、通道白名单、ref 形态。
+ * @module dsh-browser-playwright-codex/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** Schemastery validation for {@link PlaywrightConfig}. */
+export const Config = z.object({
+    launch: z.object({
+        executablePath: z.string(),
+        channel: z.string(),
+        // Visible window by default: the agent drives a browser the user can
+        // watch and rescue by hand (login, captcha, dialogs).
+        headless: z.boolean().default(false),
+        // Persistent context mode: one shared profile-backed window whose
+        // login state survives close/reopen. false = legacy launch() mode.
+        persistent: z.boolean().default(true),
+        // Profile directory for persistent mode. Empty = ~/.dsh/browser-profiles/playwright.
+        profileDir: z.string().default(''),
+        // Headless only: a headful window must behave like a normal Chrome the
+        // user opened by hand, so the fixed CSS viewport is ignored there (see
+        // ensureContext) and the page tracks the real window size instead.
+        viewport: z
+            .object({ width: z.number().default(1280), height: z.number().default(800) })
+            .default({ width: 1280, height: 800 }),
+        navigationTimeoutMs: z.number().default(30000),
+        ignoreHTTPSErrors: z.boolean().default(false),
+    }),
+    allowedDomains: z.array(z.string()),
+    idleTimeoutMs: z.number().default(600000),
+    maxSessions: z.number().default(8),
+    snapshot: z
+        .object({
+        // 'legacy' keeps the injected DOM walker as the default: existing
+        // tests, verify and every consumer see byte-identical snapshots until
+        // a caller opts into the aria engine.
+        engine: z.union([z.const('legacy'), z.const('aria')]).default('legacy'),
+        maxNodes: z.number().default(500),
+        maxNameLength: z.number().default(120),
+        maxTextLength: z.number().default(300),
+        // diff=false keeps every return path a full snapshot: zero behavioral
+        // change unless a caller explicitly turns the incremental mode on.
+        diff: z.boolean().default(false),
+    })
+        .default({ engine: 'legacy', maxNodes: 500, maxNameLength: 120, maxTextLength: 300, diff: false }),
+});
+/** Channels probed in order when none is configured. */
+export const AUTO_CHANNELS = ['chromium', 'chrome', 'msedge', 'edge'];
+/**
+ * Launch flags that strip Playwright's obvious automation markers (anti-bot
+ * detection layer L1). --enable-automation is what sets navigator.webdriver
+ * and the "controlled by automated test software" infobar; dropping it plus
+ * --disable-blink-features=AutomationControlled makes the browser present as
+ * a plain real Chrome, which it is. No fingerprint spoofing is added: real
+ * Chrome's own values are consistent by construction (spoofing would invent
+ * a device that never existed and draw MORE suspicion).
+ */
+export const HUMANIZED_LAUNCH = {
+    ignoreDefaultArgs: ['--enable-automation'],
+    args: ['--disable-blink-features=AutomationControlled'],
+};
+export const REF_PATTERN = /^e[0-9]+$/;

package/lib/extract.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 提取工具的辅助：容错地解析模型返回的 JSON，以及为提取请求拼装提示词。
+ * @module dsh-browser-playwright-codex/extract
+ */
+import type { JsonValue } from './tool-types.ts';
+/** Strip markdown fences and whitespace, then parse one JSON document. */
+export declare function parseJsonText(raw: string): JsonValue;
+/**
+ * Prompt template for structured page extraction. `maxInputChars` bounds the page
+ * data handed to the auxiliary model — that model is billed on this prompt, so an
+ * unbounded page is a tax on every extraction.
+ */
+export declare function extractionPrompt(instruction: string, data: unknown, maxInputChars: number): string;

package/lib/extract.js

@@ -0,0 +1,34 @@
+/** Strip markdown fences and whitespace, then parse one JSON document. */
+export function parseJsonText(raw) {
+    let text = raw.trim();
+    const fenced = /^\s*```(?:json)?\s*([\s\S]*?)```\s*$/.exec(text);
+    if (fenced !== null) {
+        const inner = fenced[1];
+        if (inner !== undefined)
+            text = inner.trim();
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error('browser_extract: the model output is not valid JSON: ' + text.slice(0, 500));
+    }
+}
+/**
+ * Prompt template for structured page extraction. `maxInputChars` bounds the page
+ * data handed to the auxiliary model — that model is billed on this prompt, so an
+ * unbounded page is a tax on every extraction.
+ */
+export function extractionPrompt(instruction, data, maxInputChars) {
+    const page = JSON.stringify(data);
+    const bounded = page.length > maxInputChars
+        ? page.slice(0, maxInputChars) + ' [page data truncated at ' + String(maxInputChars) + ' characters]'
+        : page;
+    return ('Extract the following from the page data according to the instruction. ' +
+        'Answer with ONLY one valid JSON value (object, array, or scalar), no prose, no markdown fences.\n\n' +
+        'Instruction: ' +
+        instruction +
+        '\n\n' +
+        'Page data (JSON):\n' +
+        bounded);
+}

package/lib/index.d.ts

@@ -14,7 +14,9 @@ export { SNAPSHOT_SCRIPT } from './injected.ts';
 export type { SnapshotOptions, PageDataOptions } from './injected.ts';
 export { default as BrowserRuntime } from './service.ts';
 export type { BrowserRuntimeConfig } from './service.ts';
-export { PlaywrightProvider, assertAllowedUrl, Config as PlaywrightConfigSchema } from './playwright.ts';
-export type { PlaywrightConfig, PageData } from './playwright.ts';
+export { PlaywrightProvider } from './provider.ts';
+export { assertAllowedUrl } from './url-policy.ts';
+export { Config as PlaywrightConfigSchema } from './config.ts';
+export type { PlaywrightConfig, PageData } from './config.ts';
 export type { BrowserNode, BrowserProvider, BrowserSession, BrowserSnapshot, LoadState, ScreenshotCapture, TabInfo, } from './types.ts';
 export type { ToolConfig } from './tool.ts';

package/lib/index.js

@@ -9,4 +9,6 @@ export { ALWAYS_ON_SUFFIXES, ERROR_CODES, GATED_SUFFIXES, TOOL_SUFFIXES, registe
 export { CallId, toolCallId } from "./compat.js";
 export { SNAPSHOT_SCRIPT } from "./injected.js";
 export { default as BrowserRuntime } from "./service.js";
-export { PlaywrightProvider, assertAllowedUrl, Config as PlaywrightConfigSchema } from "./playwright.js";
+export { PlaywrightProvider } from "./provider.js";
+export { assertAllowedUrl } from "./url-policy.js";
+export { Config as PlaywrightConfigSchema } from "./config.js";