dsh-browser-playwright-codex 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -1,3 +1,68 @@
+## 0.8.3 — 2026-11-12
+
+一句话摘要：**插件可以走代理了**——以前它启动的浏览器只能直连，凡是要代理的站点（维基、GitHub 网页、大量国外站）一律打不开。现在多一个 `launch.proxy` 配置项和设置页里的「代理」输入框；**默认留空 = 直连，行为与之前完全一样**。实测同一台机器：维基直连 31 秒超时，走代理 1 秒返回。
+
+### Added
+
+- **`launch.proxy`**：填 `http://host:port`、`https://host:port` 或 `socks5://host:port`，只写 `host:port` 会按 Playwright 的规则补成 `http://`。代理交给**浏览器启动参数**（`launchOptions.proxy`），整个浏览器走代理——不是在某个请求上加头。
+- **设置页「代理」输入框**：放在「已登录的站点」正前方（这张卡的最后一块），不再散落在中间。占位提示 `http://host:port`，示例用保留域名 `http://proxy.example:8080`，**不写任何本机真实地址**；默认值为空。
+- **强制绕过本机地址**：配置代理时自动带上 `bypass: localhost,127.0.0.1`。不加这个，插件自己的本地页面（verify、本地普查、任何本地服务）会被塞进代理而连不上。
+- **地址写错当场报错，绝不静默回退直连**：缺 scheme 时按 `host:port` 补 http；端口必须 1–65535；带路径/查询/片段、未知 scheme 都拒绝，并给出「写成 `scheme://host:port`」这句人话。静默回退会把"代理没生效"伪装成"网站打不开"，比报错更难查。
+- **不支持需要账号密码的代理**：带账号密码的地址在校验阶段就拒。两个理由——密码会明文落在用户的 `cordis.patch.yml` 里；而且 Chromium/Playwright 本身不支持 SOCKS5 认证（`Browser does not support socks5 proxy authentication`）。宁可少一个能力，不埋一个明文密码。
+
+### Changed
+
+- **保存代理只改一行**：`playwright.launch` 下的 `proxy:` 这一行，与三个能力闸门同一个模式（已知键、按行改）。其它键（`profileDir` / `channel` / `viewport` / `maxSessions` / `toolPrefix` / `maxWaitMs` 等）**逐字节不动**；清空 = 删掉那一行（留空=直连必须是干净的，不能留空值）；结构认不出就**拒绝写入**，绝不整块重渲染。
+- **生效时机**：代理是浏览器启动参数，插件在加载时读配置，所以**改完要重启 DSH 才生效**；设置页保存成功后会直接提示这一点。
+
+### Tests
+
+- 新增 `tests/proxy.test.ts`（9 条）：空配置不带 proxy；填了带 server + bypass；`host:port` 短写补 http；端口缺失/非数字/0/65536；认证代理拒绝；未知 scheme 与带路径拒绝；启动路径静态守卫（防止只加配置没接上）；**代理不影响 `allowedDomains` 判定**。
+- `tests/settings-card.test.ts` 新增 4 条：保存后 `launch.proxy` 出现且其它键完全不变（含 `profileDir`）；清空后那一行被删；非法地址 400 且文件不变；重复保存同一值幂等无重复键。
+- 全套现在 **390 条 / 387 过 / 0 失败 / cancelled 0 / skipped 3 / todo 0**。
+
+### Verified
+
+- **走代理真跑 live 三条：3/3 通过**。`example.com` 两条照常；`wikipedia REST summary` 在直连时 31 秒 `NAVIGATION_TIMEOUT` 失败，配代理后 **1.0 秒通过**——这就是这次改动的直接证据（此前 0.8.2 发布时这条是 2/3）。
+- verify 60 项全过、preflight 0 硬错误、打包 101 个文件（新增 `lib/proxy.js` / `lib/proxy.d.ts`）。
+- 已知限制：设置页里没有"测试代理连通性"的按钮；填错端口但格式合法时，要到实际启动浏览器才会发现连不上。
+
+## 0.8.2 — 2026-11-12
+
+一句话摘要：**发版门禁不再会"假绿"，快照引擎第一次在真实网站上被量过**——preflight 过去只读 `ℹ fail`（而且"fail 0"是写死的字符串），被取消的用例看不出、也不报；设置页这个全仓最大的零测试模块补上了走真实 HTTP 的测试，顺手修掉"已有未标记装载行时写出第二行"的坏文件路径；智能模式（aria）的解析器与可交互集对齐后，130 个任务页的降级从 18 页降到 3 页。
+
+### Fixed — 门禁与默认值
+
+- **preflight 的假绿通道（最要紧）**：旧实现只解析 `ℹ fail N`，摘要里的 `fail 0` 是硬编码字符串，`cancelled` / `todo` 一次都没读。0.7.8 有 7 条用例被打成 `cancelledByParent`，对外仍说"278 通过"，实际只跑了 271 条。现在判读抽成 `scripts/preflight-suite.mjs`，读全部六个计数，并把下列情形都判成硬错误：`fail > 0`、`cancelled > 0`、`todo > 0`、恒等式 `tests ≠ pass + fail + cancelled + skipped + todo`、任一计数读不到、命令非零退出、出现 `cancelledByParent > 0`。**生产脚本里不允许任何外部注入测试结果的入口**（第一版加过、被复核否掉，并留了守卫测试防止再加回来）。
+- **`swarm.enabled` 的默认方向反了**：`config.ts` 的 schema 是 `default(false)`，而 `swarm-intro.ts` 的三个入口写成 `?? true` —— 配置整体缺失时会播。改成 `?? false`，并补测试：`config` 为 `undefined` / `{}` / `{ swarm: {} }` 三种形状都不播，另有一条 `enabled: true` 的对照防止测试空转。
+- **设置页写出重复装载行**：补丁层里已有未标记的 `- id: browser` 行时，旧实现会再追加一次模板，同一个 id 被挂两行（与 issue #4 同一类"保存写出坏文件"）。现在改为**收编**那一行（保留用户键、外面套标记、只改三个闸门）；若那一行属于别的包，**拒绝写入并报错**，文件一个字节不动。
+- **SECURITY.md 与真实行为不符**：旧文写着"页面自己的 JS 仍能离开白名单"，实际名单装在浏览器 context 上、请求层就会拒。按真实行为重写，并保留两条诚实的限制（Chromium 自家网络栈里的跳转靠动作后校验最终 URL；已经停在不允许域名上的标签页仍打开、只是不驱动）。
+
+### Fixed — 快照引擎（aria / smart 模式）
+
+- **解析器读不懂"整行被引号包住"的节点**：Playwright 在名字含双引号时会写成 `- 'tab "Section #1" [ref=e5]'`（可能带尾冒号）。旧解析器把它算格式漂移，整页降级——MiniWoB 的标签页/折叠题共 8 页因此读不了。现在容忍外层引号 + 可选尾冒号，并加了"原来能读的行不许读坏"的守卫测试。
+- **两套"可交互"定义对不齐**：DOM 铸造集与 aria 树的可交互集不一致，会触发对齐守卫、整页回退。对齐了这几处：`tr→row`、`td→cell`、`th→columnheader`、`li→listitem`、`table/list/p/h1-6/img` 的隐式角色；`<option>` 的可见性看它的 `<select>`；`role="presentation"/"none"` 在可聚焦链接上忽略（ARIA 规范，jQuery-UI 标签页就是这样）；`<input type=number>` → `spinbutton`。
+- **实测**：MiniWoB++ 130 个任务页里，智能模式降级 **18 → 3**；`ref` 落不到 DOM 元素 **0 页 / 0 个**；130/130 有效、0 失败。真实网站 7 页 5 站（含 GitHub 仓库页、runoob 表格页、w3school 表单页、element-plus 组件页）全部 `unresolved = 0`，点击落点逐个核对。
+- **代价与旋钮**：GitHub 仓库页从此前的"读不了、回退 legacy（81 refs / 8,517 字符）"变成"智能模式可读（134 refs / 20,780 字符）"——结构更全、也更贵。真正决定体积的是 `snapshot.maxNodes`（默认 500），不是 `interactiveOnly`：同一页 `interactiveOnly` 是 18,351 字符 / 239 refs，**只省 12% 且 ref 反而更多**（预算重新分配，不减少总量）。README 与 PLUGIN-README 已写明这个旋钮。
+
+### Added — 测试与流程
+
+- **设置卡端到端测试**（`tests/settings-card.test.ts`）：全仓最大的零测试模块（537 行）补上 10 条，走**真实 HTTP**（`node:http` 起服务、把设置卡注册的 handler 原样接上：方法/请求头/请求体/状态码都走真实栈）。钉住 issue #4（保存后 YAML 可重新解析、无重复键、只有一个装载行）、切开关不抹 `profileDir` 等用户配置、六个路由的 `x-dsh-plugin` 防伪头、被拒请求不动文件。其中"重复装载行"与"拒绝写入"两条做过变异验证（把修复改回去，测试立刻红）。
+- **覆盖率**：`npm run coverage`（`scripts/coverage.mjs`）。用 Node 自带的 `--experimental-test-coverage`，不引入新依赖（本机 `@deepseek-ai/*` 是指向活运行时的软链接，不能 `npm install`）。自带报告只列被加载过的文件，脚本额外把 `src/**` 全清单求差集，**把 0 覆盖模块明着列出来**。首测：43 个模块、41 个被加载、2 个 0 覆盖（纯类型文件）。**不是门禁**。
+- **跨仓库检查显式化**：配套件文档检查移出默认套件（`tests/cross-repo/`），默认套件的数字在任何机器上一致；没设 `DSH_TOGGLE_DIR` 时 preflight 明写**「未验证」**，不再以"跳过"冒充通过。
+- **live 三条接进发版清单**：`docs/RELEASING.md` 新增发版清单，要求发版前手动跑 `DSH_BROWSER_LIVE=1 npm run test:live`，结论写进 Release；没跑就在 CHANGELOG 明写「本次未跑 live」。preflight 每次固定打一行「未验证：live 三条」，不再悄悄消失。
+- **一次性发布文档挪位**：`RELEASE-0.7.0.md` / `MERGE-PROGRESS.md` 移到 `docs/releases/`（**不删**，里面有回退命令），preflight 把整个目录当历史豁免——根目录发版噪声从 5 处降到 3 处。
+
+### live 三条：本次跑过，2/3 通过
+
+按 `docs/RELEASING.md` 手动跑了一次 `DSH_BROWSER_LIVE=1 npm run test:live`（2026-11-12）：
+
+- ✔ `example.com renders, snapshots, and screenshots`（1.3s）
+- ✔ `example.com rejects disallowed schemes consistently`（0.03s）
+- ✖ `wikipedia REST summary parses through evaluate` —— **本机网络到不了 wikipedia**：`page.goto` 在 30 秒后 `NAVIGATION_TIMEOUT`（这条不经过插件的新代码，属环境不可达）
+
+所以本次 live **未全绿**，原因记录在此；它不在 `prepublishOnly` 里，不影响发布门禁。preflight 的「未验证：live 三条」行同样保留。
+
 ## 0.8.1 — 2026-11-11
 
 一句话摘要：**快照第一次真正"看得见状态"**——填进去的值、勾选状态进快照也进页面指纹，正常的填字和勾选不再被误报成"疑似反爬墙"；密码 / 验证码 / 卡号即使有值也绝不进快照。顺带削掉真实站点快照里最贵的一类垃圾（跳转包裹 URL、同一 href 的重复打印），并让 `browser_evaluate` 返回非标量时给出能照着改的错误。**另外：进场动画重新随包分发——作者 Dhvanil Patel 于 2026-11-11 邮件书面许可打包与修改，默认仍然关闭。**

package/README.md

@@ -378,6 +378,19 @@ The tool schemas join the system-prompt assembly through `ctx.tools.register()`;
 
 One tool schema block per tool (small, fixed), plus per-call result text proportional to the visible page, capped by ``snapshot.maxNodes`` and name/text limits. Actions return a fresh snapshot, so interactive flows cost roughly one snapshot per step.
 
+The merged tools carry their own allowance rather than the default 1,650 characters. `browser_click` (
+which absorbed the old separate point-click and hover tools) measures **2,165 characters** against a
+budget of **2,400** — about **235 characters** of headroom left. `npm run cost` prints that per-tool
+figure on every run, so it is measured, not estimated.
+
+**The size knob is `snapshot.maxNodes`, not the reading mode.** The node cap decides how many
+characters a snapshot can spend: at the default 500 the engine stops once 500 nodes are in the tree.
+On a very large page whose snapshot is re-sent at every step, lowering it is the lever — the price is
+fewer elements visible. `interactiveOnly` does **not** shrink the total: it spends the same node
+budget on actionable elements only, so the same page can carry *more* refs that way. Measured on one
+real page (a GitHub repository page, 2026-11-12): full snapshot **20,780 characters / 134 refs**; the
+same page with `interactiveOnly: true` **18,351 characters / 239 refs**.
+
 Measured with ``npm run cost`` (per-turn, resident in the system prompt):
 
 | Surface | Tools | Schema characters | ≈ tokens/turn |

package/SECURITY.md

@@ -37,10 +37,18 @@ call — a click that raises `confirm()` returns the parked dialog instead of ac
 
 **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,
-raw coordinates) and `browser_switch_tab`. It is **not** a sandbox: a page's own JavaScript
-(`location.href = …`) can still leave the list, and a tab already sitting on a disallowed host stays
-open (the agent simply refuses to drive it). For hard isolation, put an external network guard around
-it.
+raw coordinates) and `browser_switch_tab`. **The list is also installed on the browser context itself**
+(`src/navigation-guard.ts`), so the browser — not just the tool layer — refuses a document request to a
+host outside it. A page's own JavaScript (`location.href = …`), a `meta refresh`, a `<form>` posting
+off-list and a page-opened popup all stop at the request; `fetch` / `xhr` / `EventSource` to an
+off-list host are refused too, while rendering assets are left alone so a page does not look broken.
+
+Two limits remain, and they are the honest part of this section. (1) Chromium follows a redirect inside
+its own network stack, where request interception never sees the hop: after every action the page's
+final URL is checked, an off-list landing is refused with `URL_NOT_ALLOWED`, and the tab is reset to
+`about:blank`. (2) A tab that was **already** sitting on a disallowed host when this session took it over
+(a profile written by an older version) stays open — the agent simply refuses to drive it. For hard
+isolation from the whole host stack, still put an external network guard around it.
 
 **`browser_cdp` is CDP with an allow-list.** Nineteen methods pass, matched by **exact name with no
 family prefixes**: DOM reads (geometry, node lookup, attributes, markup), one focus action, the four

package/lib/browser-lifecycle.js

@@ -7,6 +7,7 @@ import { chromium } from 'playwright-core';
 import path from 'node:path';
 import fs from 'node:fs';
 import { AUTO_CHANNELS, HUMANIZED_LAUNCH } from "./config.js";
+import { proxyLaunchOption } from "./proxy.js";
 import { SNAPSHOT_SCRIPT } from "./injected.js";
 import { BrowserError, launchFailed } from "./errors.js";
 import { forgetOnBrowserClose, showWelcome } from "./swarm-intro.js";
@@ -72,6 +73,9 @@ async function launchContext(provider) {
         // Headless mode keeps the fixed viewport (no window to track).
         ...(headless ? { viewport: provider.config.launch.viewport } : { viewport: null }),
         ignoreHTTPSErrors: provider.config.launch.ignoreHTTPSErrors,
+        // Proxy at the browser level (launchOptions.proxy): request headers cannot route a whole
+        // browser. Empty proxy yields {} so the default stays a direct connection.
+        ...proxyLaunchOption(provider.config.launch.proxy),
         ...HUMANIZED_LAUNCH,
         args: [
             '--no-first-run',
@@ -226,7 +230,12 @@ async function launchBrowser(provider) {
     const attempts = [];
     if (executablePath !== undefined) {
         try {
-            provider.browser = await chromium.launch({ executablePath, headless, ...HUMANIZED_LAUNCH });
+            provider.browser = await chromium.launch({
+                executablePath,
+                headless,
+                ...HUMANIZED_LAUNCH,
+                ...proxyLaunchOption(provider.config.launch.proxy),
+            });
             provider.launchedHeadless = headless;
             return provider.browser;
         }
@@ -239,7 +248,12 @@ async function launchBrowser(provider) {
         const channels = channel !== undefined && channel !== '' ? [channel] : [...AUTO_CHANNELS];
         for (const candidate of channels) {
             try {
-                provider.browser = await chromium.launch({ channel: candidate, headless, ...HUMANIZED_LAUNCH });
+                provider.browser = await chromium.launch({
+                    channel: candidate,
+                    headless,
+                    ...HUMANIZED_LAUNCH,
+                    ...proxyLaunchOption(provider.config.launch.proxy),
+                });
                 provider.launchedHeadless = headless;
                 return provider.browser;
             }

package/lib/client.js

@@ -403,6 +403,13 @@ window.__ModuleLoader__.load({
       const [logins, setLogins] = useState(null)
       const [headless, setHeadless] = useState(null)
       const [headlessUserChosen, setHeadlessUserChosen] = useState(false)
+      // 代理（浏览器启动参数）：'' = 直连。
+      const [proxy, setProxy] = useState('')
+      const [proxyDraft, setProxyDraft] = useState('')
+      const [proxyBusy, setProxyBusy] = useState(false)
+      const [proxyMsg, setProxyMsg] = useState(null)
+      // 输入框有焦点时，5 秒一次的轮询不许覆盖用户正在打的字。
+      const proxyFocusedRef = useRef(false)
       const [showAll, setShowAll] = useState(false)
       const [openGroups, setOpenGroups] = useState([])
       const [hiddenDomains, setHiddenDomains] = useState(readHiddenDomains())
@@ -436,6 +443,10 @@ window.__ModuleLoader__.load({
           if (typeof s.swarmPersistPlayed === 'boolean') setSwarmPersist(s.swarmPersistPlayed)
           if (typeof s.headless === 'boolean') setHeadless(s.headless)
           setHeadlessUserChosen(s.headlessUserChosen === true)
+          if (typeof s.proxy === 'string') {
+            setProxy(s.proxy)
+            if (!proxyFocusedRef.current) setProxyDraft(s.proxy)
+          }
           setGates({
             allowEvaluate: typeof s.allowEvaluate === 'boolean' ? s.allowEvaluate : null,
             allowCdp: typeof s.allowCdp === 'boolean' ? s.allowCdp : null,
@@ -573,6 +584,30 @@ window.__ModuleLoader__.load({
         }
       }
 
+      // 保存代理：只改 cordis.patch.yml 里 launch.proxy 那一行；空 = 删掉（直连）。
+      const saveProxy = async () => {
+        if (proxyBusy) return
+        setProxyBusy(true)
+        setProxyMsg(null)
+        try {
+          const r = await api('/proxy', 'POST', { proxy: proxyDraft })
+          if (r && r.error) {
+            setProxyMsg({ kind: 'error', text: r.error.message || r.error.code || '保存失败' })
+            return
+          }
+          const saved = typeof r.proxy === 'string' ? r.proxy : ''
+          setProxy(saved)
+          setProxyDraft(saved)
+          setProxyMsg({
+            kind: 'ok',
+            text: (saved === '' ? '已保存：留空 = 直连。' : '已保存：' + saved + '。') + '重启 DSH 后生效。',
+          })
+        } catch (error) {
+          setProxyMsg({ kind: 'error', text: '保存失败：' + (error?.message ?? String(error)) })
+        } finally {
+          setProxyBusy(false)
+        }
+      }
       const chooseWindow = async (nextHeadless) => {
         if (headless === null || busy || nextHeadless === headless) return
         setBusy(true)
@@ -1153,6 +1188,68 @@ window.__ModuleLoader__.load({
             )
           : null,
 
+        // ---- 代理（浏览器启动参数）----
+        // 放在「已登录的站点」正前方（用户要求的最后一块），样式与其它分组一致：
+        // 标题行 + 一整块内容。留空 = 直连；改了要重启 DSH 才生效（保存成功时会说明）。
+        h('div', { key: 'proxyGroup', style: S.group }, ['代理']),
+        h('div', { key: 'proxyBody', style: { ...S.list, marginTop: 8 } }, [
+          h('div', { key: 'row', style: { display: 'flex', alignItems: 'center', gap: 8 } }, [
+            h('input', {
+              key: 'input',
+              type: 'text',
+              value: proxyDraft,
+              placeholder: 'http://host:port',
+              disabled: proxyBusy,
+              spellCheck: false,
+              onFocus: () => {
+                proxyFocusedRef.current = true
+              },
+              onBlur: () => {
+                proxyFocusedRef.current = false
+              },
+              onChange: (e) => {
+                setProxyDraft(e.target.value)
+                setProxyMsg(null)
+              },
+              style: {
+                flex: '1 1 auto',
+                minWidth: 160,
+                height: 28,
+                padding: '0 10px',
+                border: '0.5px solid ' + T.borderL3,
+                borderRadius: 14,
+                background: 'transparent',
+                font: 'inherit',
+                fontSize: 12,
+                lineHeight: '18px',
+                color: T.primary,
+              },
+            }),
+            h(
+              Btn,
+              {
+                key: 'save',
+                disabled: proxyBusy || proxyDraft === proxy,
+              },
+              proxyBusy ? '保存中…' : '保存',
+            ),
+          ]),
+          h(
+            'p',
+            { key: 'hint', style: S.note },
+            '留空 = 直连。要填的话写成 http://主机:端口 或 socks5://主机:端口，例如 http://proxy.example:8080；本机页面不走代理。不支持需要账号密码的代理。',
+          ),
+          proxyMsg
+            ? h(
+                'p',
+                {
+                  key: 'msg',
+                  style: { ...S.note, color: proxyMsg.kind === 'error' ? T.error : T.success },
+                },
+                proxyMsg.text,
+              )
+            : null,
+        ]),
         // ---- 已登录站点（默认收起） ----
         h(
           'div',

package/lib/config.d.ts

@@ -25,6 +25,11 @@ export interface PlaywrightConfig {
         navigationTimeoutMs: number;
         /** Ignore HTTPS certificate errors. */
         ignoreHTTPSErrors: boolean;
+        /**
+         * Proxy for the whole browser, e.g. `http://proxy.example:8080` (http / https / socks5).
+         * Empty = connect directly — the default, and the previous behaviour.
+         */
+        proxy?: string;
     };
     /** Host suffixes the browser may visit. Empty = any http(s) host. */
     allowedDomains?: string[];

package/lib/config.js

@@ -27,6 +27,11 @@ export const Config = z.object({
         // one second; the default stays 30s.
         navigationTimeoutMs: z.number().min(1000).default(30000),
         ignoreHTTPSErrors: z.boolean().default(false),
+        // Proxy for the whole browser (launchOptions.proxy), e.g. http://proxy.example:8080.
+        // Empty = direct, which is the default and keeps every existing deployment unchanged.
+        // Validation lives in src/proxy.ts so a bad address fails loudly instead of silently
+        // connecting directly (which would look like "the site is down").
+        proxy: z.string().default(''),
     }),
     allowedDomains: z.array(z.string()),
     idleTimeoutMs: z.number().default(600000),

package/lib/gates-patch.d.ts

@@ -86,4 +86,33 @@ export declare function writeGates(allowEvaluate: boolean, allowCdp: boolean, di
     allowCdp: boolean;
     diagnostics: boolean;
 }>;
+/**
+ * 改写块里的 proxy 行：有就改、没有就插、空字符串就删。其它行逐字节保留。
+ *
+ * @param body - 托管块全文（含标记）
+ * @param proxy - 已经过 normalizeProxy 校验的地址；'' 表示删掉这一行
+ * @returns 改好的块
+ */
+export declare function patchBlockProxy(body: string, proxy: string): string;
+/** 读托管块里的 proxy 值；没有就是 ''（= 直连）。 */
+export declare function parseBrowserBlockProxy(text: string): string;
+/**
+ * 把 proxy 合并进文件内容：没有托管块就先按模板建一个，再改这一行。
+ *
+ * @param original - 原文件内容
+ * @param proxy - 已校验的地址；'' = 删掉
+ * @returns 新文件内容
+ */
+export declare function mergeBrowserBlockProxy(original: string, proxy: string): string;
+/**
+ * 写 proxy：备份 → 原子替换 → 读回校验；校验失败恢复原文件。
+ *
+ * @param proxy - 已校验的地址；'' 表示删掉这一行（= 直连）
+ * @param env - 环境（测试用 DSH_HOME 覆盖）
+ * @returns 写到的文件与现在的值
+ */
+export declare function writeProxy(proxy: string, env?: NodeJS.ProcessEnv): Promise<{
+    patch: string;
+    proxy: string;
+}>;
 export {};

package/lib/gates-patch.js

@@ -174,6 +174,41 @@ function findBlock(original) {
     }
     return undefined;
 }
+/**
+ * A **top-level** loader row for `id: browser` that is not inside a managed block.
+ *
+ * Why this exists (2026-11-12, found while writing the settings-card tests): when the
+ * user's patch layer already carried an unmarked `- id: browser` row (hand-edited, or
+ * written by a version before the markers existed), `mergeBrowserBlock` used to append
+ * the full template — producing **two loader rows for the same id**. The loader then
+ * sees the package twice, which is the same class of failure as issue #4 (a save writes
+ * a patch that breaks the next start). Adopting the row instead keeps the user's keys
+ * and leaves exactly one row.
+ *
+ * @param original - the whole patch file
+ * @returns the row's bounds, or undefined when there is none
+ */
+function findUnmarkedRow(original) {
+    const head = /^([ \t]*)-[ \t]+id:[ \t]*browser[ \t]*(?:#.*)?$/m.exec(original);
+    if (head === null)
+        return undefined;
+    const start = head.index;
+    const indent = (head[1] ?? '').length;
+    const bodyStart = start + head[0].length;
+    // The row ends at the next sequence item at the same (or a shallower) indent.
+    let end = original.length;
+    const item = /^([ \t]*)-[ \t]+/gm;
+    item.lastIndex = bodyStart;
+    for (let found = item.exec(original); found !== null; found = item.exec(original)) {
+        if ((found[1] ?? '').length <= indent) {
+            end = found.index;
+            break;
+        }
+    }
+    const body = original.slice(start, end);
+    const namesUs = /['"]dsh-browser-playwright-codex['"]/.test(body);
+    return { start, end, namesUs, indent };
+}
 /**
  * Merge the gate values into `original`.
  *
@@ -189,6 +224,31 @@ export function mergeBrowserBlock(original, allowEvaluate, allowCdp, diagnostics
     const gates = { allowEvaluate, allowCdp, diagnostics };
     const found = findBlock(original);
     if (found === undefined) {
+        const row = findUnmarkedRow(original);
+        if (row !== undefined) {
+            // An unmarked row already mounts this package. Wrapping it (instead of appending a
+            // second one) is what keeps "one loader row per package" true — the same invariant
+            // the 0.7.0 merge had to satisfy.
+            if (!row.namesUs) {
+                // It is somebody else's `- id: browser` row. Refuse rather than write a file that
+                // mounts two different packages under one id: a clear error now beats a fatal start.
+                throw new Error('the home patch already has an `- id: browser` row that is not this package; ' +
+                    'refusing to add a second row for the same id — rename one of them by hand, then retry');
+            }
+            const nl = original.includes('\r\n') ? '\r\n' : '\n';
+            const body = original.slice(row.start, row.end).replace(/[ \t]+$/, '');
+            const wrapped = BEGIN + nl + body + nl + END + nl;
+            const edited = patchBlockGates(wrapped, gates);
+            const check = parseBrowserBlock(edited);
+            if (check !== undefined &&
+                check.allowEvaluate === allowEvaluate &&
+                check.allowCdp === allowCdp &&
+                check.diagnostics === diagnostics) {
+                return original.slice(0, row.start) + edited + original.slice(row.end);
+            }
+            const rebuilt = BEGIN + nl + renderBrowserBlock(allowEvaluate, allowCdp, diagnostics) + END + nl;
+            return original.slice(0, row.start) + rebuilt + original.slice(row.end);
+        }
         const block = renderBrowserBlock(allowEvaluate, allowCdp, diagnostics);
         return (original === '' || original.endsWith('\n') ? original : original + '\n') + '\n' + block;
     }
@@ -263,3 +323,152 @@ export async function writeGates(allowEvaluate, allowCdp, diagnostics, env = pro
     }
     return { patch: file, allowEvaluate, allowCdp, diagnostics };
 }
+/** 在块的文本里找 `launch:` 与它的 `proxy:` 子行。认不出结构就抛错（拒绝写入）。 */
+function findLaunchSection(lines) {
+    let launchAt = -1;
+    let launchIndent = '';
+    for (let i = 0; i < lines.length; i += 1) {
+        const m = /^(\s*)launch\s*:\s*(#.*)?$/.exec(lines[i] ?? '');
+        if (m !== null) {
+            launchAt = i;
+            launchIndent = m[1] ?? '';
+            break;
+        }
+    }
+    if (launchAt === -1) {
+        throw new Error('the managed block has no `playwright.launch:` section, so launch.proxy cannot be edited safely; ' +
+            'nothing was written. Fix the block by hand (or remove it and save a gate once to rebuild it).');
+    }
+    const baseIndent = launchIndent.length;
+    let childIndent = '';
+    let proxy;
+    for (let i = launchAt + 1; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        const indent = (/^\s*/.exec(line)?.[0] ?? '').length;
+        if (indent <= baseIndent)
+            break; // 出了 launch 这一节
+        if (trimmed.startsWith('#'))
+            continue;
+        if (childIndent === '')
+            childIndent = ' '.repeat(indent);
+        const p = /^(\s*)proxy\s*:/.exec(line);
+        if (p !== null)
+            proxy = { at: i, indent: p[1] ?? '' };
+    }
+    return {
+        at: launchAt,
+        indent: baseIndent,
+        childIndent: childIndent === '' ? ' '.repeat(baseIndent + 2) : childIndent,
+        ...(proxy === undefined ? {} : { proxy }),
+    };
+}
+/**
+ * 改写块里的 proxy 行：有就改、没有就插、空字符串就删。其它行逐字节保留。
+ *
+ * @param body - 托管块全文（含标记）
+ * @param proxy - 已经过 normalizeProxy 校验的地址；'' 表示删掉这一行
+ * @returns 改好的块
+ */
+export function patchBlockProxy(body, proxy) {
+    const nl = body.includes('\r\n') ? '\r\n' : '\n';
+    const lines = body.split(/\r?\n/);
+    const section = findLaunchSection(lines);
+    const value = proxy.trim();
+    const rendered = section.childIndent + 'proxy: ' + JSON.stringify(value);
+    if (section.proxy !== undefined) {
+        if (value === '')
+            lines.splice(section.proxy.at, 1);
+        else
+            lines[section.proxy.at] = rendered;
+        return lines.join(nl);
+    }
+    if (value === '')
+        return lines.join(nl); // 本来就没有，删空是幂等的
+    lines.splice(section.at + 1, 0, rendered);
+    return lines.join(nl);
+}
+/** 读托管块里的 proxy 值；没有就是 ''（= 直连）。 */
+export function parseBrowserBlockProxy(text) {
+    const found = findBlock(text);
+    if (found === undefined)
+        return '';
+    const body = text.slice(found.start, found.after);
+    const lines = body.split(/\r?\n/);
+    let section;
+    try {
+        section = findLaunchSection(lines);
+    }
+    catch {
+        return '';
+    }
+    if (section?.proxy === undefined)
+        return '';
+    const raw = (lines[section.proxy.at] ?? '').replace(/^\s*proxy\s*:\s*/, '');
+    const withoutComment = raw.replace(/\s+#.*$/, '').trim();
+    if (withoutComment === '')
+        return '';
+    if ((withoutComment.startsWith('"') && withoutComment.endsWith('"')) ||
+        (withoutComment.startsWith("'") && withoutComment.endsWith("'"))) {
+        return withoutComment.slice(1, -1);
+    }
+    return withoutComment;
+}
+/**
+ * 把 proxy 合并进文件内容：没有托管块就先按模板建一个，再改这一行。
+ *
+ * @param original - 原文件内容
+ * @param proxy - 已校验的地址；'' = 删掉
+ * @returns 新文件内容
+ */
+export function mergeBrowserBlockProxy(original, proxy) {
+    const value = proxy.trim();
+    let base = original;
+    let found = findBlock(base);
+    if (found === undefined) {
+        base = (base === '' || base.endsWith('\n') ? base : base + '\n') + '\n' + renderBrowserBlock(false, false, false);
+        found = findBlock(base);
+    }
+    if (found === undefined)
+        throw new Error('could not create the managed block; nothing was written');
+    const edited = patchBlockProxy(base.slice(found.start, found.after), value);
+    if (parseBrowserBlockProxy(edited) !== value) {
+        throw new Error('proxy line self-check failed; nothing was written');
+    }
+    return base.slice(0, found.start) + edited + base.slice(found.after);
+}
+/**
+ * 写 proxy：备份 → 原子替换 → 读回校验；校验失败恢复原文件。
+ *
+ * @param proxy - 已校验的地址；'' 表示删掉这一行（= 直连）
+ * @param env - 环境（测试用 DSH_HOME 覆盖）
+ * @returns 写到的文件与现在的值
+ */
+export async function writeProxy(proxy, env = process.env) {
+    const file = homePatchPath(env);
+    const value = proxy.trim();
+    let original = '';
+    try {
+        original = await readFile(file, 'utf8');
+    }
+    catch {
+        original = '';
+    }
+    const next = mergeBrowserBlockProxy(original, value);
+    if (original !== '')
+        await copyFile(file, file + '.bak-browser-toggle').catch(() => { });
+    const tmp = file + '.tmp-browser-toggle';
+    await writeFile(tmp, next, 'utf8');
+    await rename(tmp, file);
+    const check = await readFile(file, 'utf8');
+    if (parseBrowserBlockProxy(check) !== value) {
+        if (original !== '') {
+            await writeFile(file, original, 'utf8');
+            throw new Error('proxy self-check failed after write; previous content restored');
+        }
+        throw new Error('proxy self-check failed after write');
+    }
+    return { patch: file, proxy: value };
+}

package/lib/provider.js

@@ -17,6 +17,7 @@ import { swarmBootScript } from "./swarm-curtain.js";
 import { forgetOnBrowserClose } from "./swarm-intro.js";
 import { isWindowMinimized } from "./window-focus.js";
 import { installHostGuard } from "./navigation-guard.js";
+import { normalizeProxy } from "./proxy.js";
 export class PlaywrightProvider {
     config;
     id = 'playwright';
@@ -62,6 +63,9 @@ export class PlaywrightProvider {
     blockedNavigation = undefined;
     constructor(config) {
         this.config = config;
+        // Fail at load time, not at launch time: a bad proxy address must produce the one
+        // message that explains it (src/proxy.ts), not a wrapped "tried channel …" failure.
+        normalizeProxy(config.launch.proxy);
         // Tell the settings card which page-reading mode this deployment was
         // configured with, so it can show "当前：X（默认）" truthfully instead of
         // assuming the built-in default.

package/lib/proxy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Proxy support for the browser launch (2026-11-12).
+ *
+ * The plugin starts its own Chromium-family browser, so a proxy has to go into the
+ * **launch** options (`launchOptions.proxy`) — request headers cannot route a whole
+ * browser. Measured here: Wikipedia through a proxy answered in 4.4 s; direct it timed
+ * out at 15 s, which is what every proxied site looked like before this.
+ *
+ * Three rules, each with a reason:
+ *
+ * 1. **Empty means direct.** No configured proxy keeps today's behaviour exactly.
+ * 2. **`bypass` always includes the local addresses.** Without it the plugin's own
+ *    `127.0.0.1` pages (verify, the MiniWoB sweep, any local server) would be pushed
+ *    through the proxy and fail. Playwright passes `bypass` straight to Chromium's
+ *    proxy bypass list.
+ * 3. **A bad address is an error, never a silent fallback to direct.** Quietly going
+ *    direct would look like "the site is down" and send the user debugging the wrong thing.
+ *
+ * Authentication is deliberately **not** supported in this version: a password in the
+ * config would be stored in plain text in the user's `cordis.patch.yml`, and Playwright
+ * refuses SOCKS5 authentication outright (`Browser does not support socks5 proxy
+ * authentication`). Rather than ship a plaintext password path, credentials are rejected
+ * here with a message that says why.
+ *
+ * @module dsh-browser-playwright-codex/proxy
+ */
+/** The shape Playwright accepts in `launchOptions.proxy`. */
+export interface LaunchProxy {
+    /** `http://host:port`, `https://host:port` or `socks5://host:port`. */
+    server: string;
+    /** Local addresses bypass the proxy, so the plugin's own local pages keep working. */
+    bypass: string;
+}
+/** Hosts that must never be proxied (the plugin's own local pages live there). */
+export declare const PROXY_BYPASS = "localhost,127.0.0.1";
+/**
+ * Turn a configured proxy address into Playwright's proxy object.
+ *
+ * Accepted shapes: `host:port` (treated as HTTP, like Playwright does), `http://host:port`,
+ * `https://host:port`, `socks5://host:port`. The port is required and must be 1–65535.
+ *
+ * @param raw - the configured value; empty/undefined means "connect directly"
+ * @returns the proxy settings (server + local bypass), or undefined for a direct connection
+ * @throws Error with an actionable message when the address cannot be used
+ */
+export declare function normalizeProxy(raw: string | undefined | null): LaunchProxy | undefined;
+/**
+ * The spread-in fragment for Playwright's launch options: `{}` when direct,
+ * `{ proxy: … }` when configured. Every launch path uses this so they cannot drift.
+ *
+ * @param raw - the configured proxy value
+ * @returns an object to spread into the launch options
+ */
+export declare function proxyLaunchOption(raw: string | undefined | null): {
+    proxy?: LaunchProxy;
+};

package/lib/proxy.js

@@ -0,0 +1,131 @@
+/**
+ * Proxy support for the browser launch (2026-11-12).
+ *
+ * The plugin starts its own Chromium-family browser, so a proxy has to go into the
+ * **launch** options (`launchOptions.proxy`) — request headers cannot route a whole
+ * browser. Measured here: Wikipedia through a proxy answered in 4.4 s; direct it timed
+ * out at 15 s, which is what every proxied site looked like before this.
+ *
+ * Three rules, each with a reason:
+ *
+ * 1. **Empty means direct.** No configured proxy keeps today's behaviour exactly.
+ * 2. **`bypass` always includes the local addresses.** Without it the plugin's own
+ *    `127.0.0.1` pages (verify, the MiniWoB sweep, any local server) would be pushed
+ *    through the proxy and fail. Playwright passes `bypass` straight to Chromium's
+ *    proxy bypass list.
+ * 3. **A bad address is an error, never a silent fallback to direct.** Quietly going
+ *    direct would look like "the site is down" and send the user debugging the wrong thing.
+ *
+ * Authentication is deliberately **not** supported in this version: a password in the
+ * config would be stored in plain text in the user's `cordis.patch.yml`, and Playwright
+ * refuses SOCKS5 authentication outright (`Browser does not support socks5 proxy
+ * authentication`). Rather than ship a plaintext password path, credentials are rejected
+ * here with a message that says why.
+ *
+ * @module dsh-browser-playwright-codex/proxy
+ */
+const ALLOWED_SCHEMES = new Set(['http:', 'https:', 'socks5:']);
+/** Hosts that must never be proxied (the plugin's own local pages live there). */
+export const PROXY_BYPASS = 'localhost,127.0.0.1';
+/** One clear sentence for every rejection; the value is echoed so a typo is visible. */
+function reject(value, why) {
+    throw new Error('launch.proxy is not a usable proxy address (' +
+        why +
+        '): "' +
+        value +
+        '". ' +
+        'Write it as scheme://host:port (or just host:port) — e.g. http://proxy.example:8080, ' +
+        'https://proxy.example:8443 or socks5://proxy.example:1080. ' +
+        'Leave it empty to connect directly. Authenticated proxies are not supported in this version.');
+}
+/**
+ * Turn a configured proxy address into Playwright's proxy object.
+ *
+ * Accepted shapes: `host:port` (treated as HTTP, like Playwright does), `http://host:port`,
+ * `https://host:port`, `socks5://host:port`. The port is required and must be 1–65535.
+ *
+ * @param raw - the configured value; empty/undefined means "connect directly"
+ * @returns the proxy settings (server + local bypass), or undefined for a direct connection
+ * @throws Error with an actionable message when the address cannot be used
+ */
+export function normalizeProxy(raw) {
+    const value = (raw ?? '').trim();
+    if (value === '')
+        return undefined;
+    // Credentials would have to live in plain text in the user's patch file, and SOCKS5
+    // authentication is not supported by the browser anyway — refuse before launch.
+    if (/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*@/i.test(value) || /^[^/?#]*@/.test(value)) {
+        throw new Error('launch.proxy must not carry a username or password (found a credential in "' +
+            value +
+            '"). ' +
+            'This version supports proxies WITHOUT authentication only: a password in the config ' +
+            'would be stored in plain text in your patch file, and SOCKS5 authentication is not ' +
+            'supported by Chromium/Playwright at all. Configure an unauthenticated proxy, or leave ' +
+            'this empty to connect directly.');
+    }
+    // Short form: Playwright itself reads `host:port` as HTTP, so accept it the same way.
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : 'http://' + value;
+    // Check the port by hand first: `new URL('http://host:abc')` throws a generic message,
+    // and "the port is not a number" is what the user needs to read.
+    const hostPart = withScheme.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '').split('/')[0] ?? '';
+    const hostOnly = hostPart.split('?')[0] ?? '';
+    const portText = (() => {
+        if (hostOnly.startsWith('[')) {
+            const close = hostOnly.indexOf(']');
+            if (close === -1)
+                return '';
+            const rest = hostOnly.slice(close + 1);
+            return rest.startsWith(':') ? rest.slice(1) : '';
+        }
+        const colon = hostOnly.lastIndexOf(':');
+        return colon === -1 ? '' : hostOnly.slice(colon + 1);
+    })();
+    if (portText === '')
+        reject(value, 'the port is missing');
+    if (!/^\d+$/.test(portText ?? ''))
+        reject(value, 'the port is not a number');
+    // Check the range before `new URL` does: an out-of-range port makes the constructor
+    // throw a generic error, and the useful sentence is "the port must be 1–65535".
+    const portNumber = Number(portText);
+    if (!Number.isInteger(portNumber) || portNumber < 1 || portNumber > 65535) {
+        reject(value, 'the port must be 1–65535');
+    }
+    let url;
+    try {
+        url = new URL(withScheme);
+    }
+    catch {
+        return reject(value, 'it does not parse as a URL');
+    }
+    if (!ALLOWED_SCHEMES.has(url.protocol.toLowerCase())) {
+        reject(value, 'only http, https and socks5 are supported');
+    }
+    if (url.hostname === '')
+        reject(value, 'the host is empty');
+    if (url.port === '' || !/^\d+$/.test(url.port))
+        reject(value, 'the port is not a number');
+    const port = Number(url.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        reject(value, 'the port must be 1–65535');
+    // A non-special scheme (socks5) parses with an EMPTY pathname while http/https give '/',
+    // so both are "no path". Anything else means the user appended something.
+    if ((url.pathname !== '' && url.pathname !== '/') || url.search !== '' || url.hash !== '') {
+        reject(value, 'a proxy address has no path, query or fragment');
+    }
+    return {
+        server: url.protocol + '//' + url.hostname + ':' + url.port,
+        // Never proxy the plugin's own local pages.
+        bypass: PROXY_BYPASS,
+    };
+}
+/**
+ * The spread-in fragment for Playwright's launch options: `{}` when direct,
+ * `{ proxy: … }` when configured. Every launch path uses this so they cannot drift.
+ *
+ * @param raw - the configured proxy value
+ * @returns an object to spread into the launch options
+ */
+export function proxyLaunchOption(raw) {
+    const proxy = normalizeProxy(raw);
+    return proxy === undefined ? {} : { proxy };
+}

package/lib/settings-card.js

@@ -62,7 +62,8 @@
 import * as runtimeState from "./runtime-state.js";
 // The patch writer lives in its own dependency-free module so it can be tested
 // without a DSH host (a half-written patch layer would break every plugin load).
-import { homePatchPath, parseGatesBlock, writeGates } from "./gates-patch.js";
+import { homePatchPath, parseBrowserBlockProxy, parseGatesBlock, writeGates, writeProxy } from "./gates-patch.js";
+import { normalizeProxy } from "./proxy.js";
 import { onPersistPlayedChanged, resetPlayed } from "./swarm-intro.js";
 import { readFileSync } from 'node:fs';
 import { clean, isTargetId, resolvePaths, scan } from "./cache-clean.js";
@@ -90,6 +91,14 @@ function readGates() {
  * shows the *effective* gates from readGates(); this is the file-level view used
  * for diagnostics when the two disagree (i.e. the reload has not landed yet).
  */
+function managedBlockProxy() {
+    try {
+        return parseBrowserBlockProxy(readFileSync(homePatchPath(), 'utf8'));
+    }
+    catch {
+        return '';
+    }
+}
 function managedBlockGates() {
     try {
         const text = readFileSync(homePatchPath(), 'utf8');
@@ -391,6 +400,8 @@ export function apply(ctx) {
                 // What the user's own layer says right now. Differs from the above
                 // between a write and the live reload that applies it.
                 patchGates: managedBlockGates() ?? null,
+                // launch.proxy（设置页的「代理」输入框）。空 = 直连。
+                proxy: managedBlockProxy(),
             });
         },
     }));
@@ -523,5 +534,55 @@ export function apply(ctx) {
             sendJson(res, 200, { logins });
         },
     }));
+    // ---- launch.proxy：设置页里的「代理」输入框 ----
+    // 只改托管块里 `playwright.launch.proxy` 这一行（与三个闸门同一个模式），
+    // 其它键逐字节不动；空字符串 = 删掉那一行 = 直连。
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: `${PREFIX}/proxy`,
+        handler: async (req, res) => {
+            if (req.method !== 'POST')
+                return sendJson(res, 405, { error: { code: 'METHOD', message: 'POST only' } });
+            if (req.headers[HEADER] !== 'browser-toggle')
+                return sendJson(res, 403, { error: { code: 'CSRF', message: 'missing plugin header' } });
+            const body = await readBody(req);
+            if (!body.ok)
+                return sendJson(res, 400, { error: { code: 'BODY_READ', message: body.error } });
+            let payload;
+            try {
+                payload = JSON.parse(body.text || '{}');
+            }
+            catch {
+                return sendJson(res, 400, { error: { code: 'INVALID_JSON', message: 'body must be JSON' } });
+            }
+            if (typeof payload.proxy !== 'string')
+                return sendJson(res, 400, { error: { code: 'INVALID_BODY', message: '`proxy` must be a string' } });
+            // 校验直接用 proxy.ts 的同一份实现：非法地址当场报错，文件一个字节不动。
+            let server = '';
+            try {
+                const normalized = normalizeProxy(payload.proxy);
+                server = normalized === undefined ? '' : normalized.server;
+            }
+            catch (error) {
+                return sendJson(res, 400, {
+                    error: { code: 'INVALID_PROXY', message: String(error?.message ?? error) },
+                });
+            }
+            try {
+                const written = await writeProxy(server);
+                sendJson(res, 200, {
+                    proxy: written.proxy,
+                    patch: written.patch,
+                    // 代理是浏览器启动参数：插件在加载时读配置，所以下次启动 DSH 才生效。
+                    appliedOn: 'restart',
+                });
+            }
+            catch (error) {
+                sendJson(res, 500, {
+                    error: { code: 'PATCH_WRITE', message: String(error?.message ?? error) },
+                });
+            }
+        },
+    }));
 }
 export default { name, inject, apply };

package/lib/snapshot-aria.d.ts

@@ -48,26 +48,6 @@ export interface AriaParseResult {
     /** Content lines that could not be parsed — non-empty means format drift. */
     readonly unparsed: string[];
 }
-/**
- * Parse Playwright's official ariaSnapshot YAML into a semantic node tree.
- *
- * The real format (verified against playwright-core 1.62, 2026-09-30) is:
- *
- *   - generic [active] [ref=e1]:          ← trailing ':' = the node has children
- *     - link "One" [ref=e6] [cursor=pointer]:
- *       - /url: /one                       ← href rides a deeper child line
- *     - text: Name                         ← text content uses 'text: <value>'
- *
- * The first version of this parser assumed a hand-rolled dialect
- * (`- role "name" [flags] -> href`, nothing after the flags) that real output
- * never produces. Every container line ends in ':', so that regex matched none
- * of them: the whole hierarchy was dropped, links and their hrefs vanished, and
- * `captureAriaSnapshot` still reported success. Unreadable lines are now
- * collected in `unparsed` so the capture layer can refuse the tree and let the
- * provider fall back to the legacy engine.
- * @param yaml - the ariaSnapshot text.
- * @returns parsed roots plus any unreadable content lines.
- */
 export declare function parseAriaSnapshotWithStats(yaml: string): AriaParseResult;
 /**
  * Parse Playwright's ariaSnapshot YAML into a semantic node tree.

package/lib/snapshot-aria.js

@@ -54,12 +54,19 @@ export const ARIA_REF_SCRIPT = String.raw `
   window.__dshAriaRefsV = 2
   const INTERACTIVE = new Set(['button','link','checkbox','radio','menuitem','menuitemcheckbox','menuitemradio','tab','switch','combobox','listbox','option','textbox','searchbox','slider','spinbutton','row','gridcell'])
   const TAGS = new Set(['a','button','select','textarea','option','summary'])
-  const INPUT_ROLE = { checkbox:'checkbox', radio:'radio', button:'button', submit:'button', reset:'button', image:'button', range:'slider', search:'searchbox', hidden:'null' }
+  const INPUT_ROLE = { checkbox:'checkbox', radio:'radio', button:'button', submit:'button', reset:'button', image:'button', range:'slider', number:'spinbutton', search:'searchbox', hidden:'null' }
   const DOC_NONCE = String(Math.floor(Math.random() * 1e9)).padStart(9, '0')
   let refSeq = 0
   const roleOf = (el) => {
     const explicit = el.getAttribute && el.getAttribute('role')
-    if (explicit && explicit.trim()) return explicit.trim().toLowerCase()
+    const explicitRole = explicit && explicit.trim() ? explicit.trim().toLowerCase() : ''
+    // aria: an explicit role="presentation"/"none" is IGNORED on a focusable
+    // element — the tree still exposes its native role. jQuery-UI tabs do exactly
+    // this: <a href="#tabs-1" role="presentation"> shows up as a link in the aria
+    // tree (measured 2026-11-12 on MiniWoB click-tab).
+    const presentational = explicitRole === 'presentation' || explicitRole === 'none'
+    const focusableLink = el.tagName.toLowerCase() === 'a' && el.hasAttribute('href')
+    if (explicitRole !== '' && !(presentational && focusableLink)) return explicitRole
     const tag = el.tagName.toLowerCase()
     if (tag === 'input') return INPUT_ROLE[(el.getAttribute('type') || 'text').toLowerCase()] || 'textbox'
     if (tag === 'a') return 'link'
@@ -68,10 +75,34 @@ export const ARIA_REF_SCRIPT = String.raw `
     if (tag === 'textarea') return 'textarea'
     if (tag === 'option') return 'option'
     if (tag === 'summary') return 'summary'
+    // Implicit roles for the elements the accessibility tree annotates anyway.
+    // Without these the DOM side said "generic" for a <tr> while the tree said
+    // "row" (an actionable role), so the minted ref list and the tree disagreed
+    // and the whole page fell back (measured 2026-11-12: 6 of the 18 fallback
+    // MiniWoB pages were table/row tasks).
+    if (tag === 'tr') return 'row'
+    if (tag === 'td') return 'cell'
+    if (tag === 'th') return 'columnheader'
+    if (tag === 'li') return 'listitem'
+    if (tag === 'table') return 'table'
+    if (tag === 'ul' || tag === 'ol') return 'list'
+    if (tag === 'p') return 'paragraph'
+    if (tag === 'h1' || tag === 'h2' || tag === 'h3' || tag === 'h4' || tag === 'h5' || tag === 'h6') return 'heading'
+    if (tag === 'img') return 'img'
     return 'generic'
   }
   const isActionable = (el) => {
     if (!(el instanceof Element)) return false
+    // An explicit role of presentation / none tells the accessibility tree to drop
+    // the element's own semantics — EXCEPT on a focusable link, where the spec says
+    // the role is ignored (see roleOf). Skipping those here would mint one ref too
+    // few and put the lists out of step (measured 2026-11-12: the MiniWoB tab strips
+    // wrap each tab in <a href role="presentation">; 4 pages fell back).
+    const explicit = el.getAttribute('role')
+    const explicitRole = explicit && explicit.trim() ? explicit.trim().toLowerCase() : ''
+    const presentational = explicitRole === 'presentation' || explicitRole === 'none'
+    const focusableLink = el.tagName.toLowerCase() === 'a' && el.hasAttribute('href')
+    if (presentational && !focusableLink) return false
     const tag = el.tagName.toLowerCase()
     if (TAGS.has(tag)) return true
     const role = roleOf(el)
@@ -89,6 +120,17 @@ export const ARIA_REF_SCRIPT = String.raw `
       if (el.getAttribute('hidden') !== null || el.getAttribute('aria-hidden') === 'true') return false
       const style = getComputedStyle(el)
       if (style.display === 'none' || style.visibility === 'hidden') return false
+      // <option> has no layout box of its own inside a closed <select>, yet the
+      // accessibility tree lists it — so it must keep its slot here, or the two
+      // lists drift (measured 2026-11-12: choose-list minted 2 refs while the tree
+      // had 7 actionable nodes). Its <select> is the visibility signal: options of
+      // a display:none select are absent from the tree too.
+      if (el.tagName.toLowerCase() === 'option') {
+        const select = el.closest('select')
+        if (select === null) return false
+        const selectStyle = getComputedStyle(select)
+        return selectStyle.display !== 'none' && selectStyle.visibility !== 'hidden'
+      }
       // A 'display: contents' box has no rect of its own but lays its children
       // out normally — it belongs to the tree, so it keeps its slot.
       if (style.display === 'contents') return true
@@ -177,6 +219,29 @@ function readQuoted(text) {
  * @param yaml - the ariaSnapshot text.
  * @returns parsed roots plus any unreadable content lines.
  */
+/**
+ * Playwright quotes a whole node line when the name itself contains a double quote:
+ *   - 'tab "Section #1" [ref=e5]'
+ *   - 'link "Tab #1" [ref=e7] [cursor=pointer]':
+ * Strip the outer single quotes (and the optional trailing ':' that marks children),
+ * then parse the inner text like any other line. Measured 2026-11-12: 8 of 130
+ * MiniWoB pages fell back to the legacy engine purely over this shape (tab strips,
+ * collapsible sections), while the pages themselves read perfectly.
+ */
+function unwrapQuotedNodeBody(body) {
+    if (body.length < 3 || body[0] !== "'")
+        return body;
+    const close = body.lastIndexOf("'");
+    if (close <= 0)
+        return body;
+    const inside = body.slice(1, close);
+    const after = body.slice(close + 1).trim();
+    // Anything else after the closing quote is not the shape we know; leave it to
+    // the normal path so an unknown line is reported rather than silently accepted.
+    if (after !== '' && after !== ':')
+        return body;
+    return inside;
+}
 export function parseAriaSnapshotWithStats(yaml) {
     const roots = [];
     const stack = [];
@@ -206,7 +271,7 @@ export function parseAriaSnapshotWithStats(yaml) {
             continue;
         }
         const indent = Math.floor((m[1] ?? '').length / 2);
-        const body = m[2] ?? '';
+        const body = unwrapQuotedNodeBody(m[2] ?? '');
         // Attribute child lines describe the node declared above: '- /url: /one',
         // '- /placeholder: Search'. Playwright adds facts over time, and an attribute
         // line carries no tree structure — so an unknown one is safe to ignore.

package/lib/swarm-intro.js

@@ -729,7 +729,7 @@ export async function showWelcome(page, config) {
         return; // 页面还没准备好：留一张空白页也不影响任何事
     }
     const userChoice = runtimeState.getSwarm();
-    const enabled = userChoice ?? config?.swarm?.enabled ?? true;
+    const enabled = userChoice ?? config?.swarm?.enabled ?? false;
     if (!enabled)
         return;
     const tuning = runtimeState.getSwarmTuning();
@@ -756,7 +756,7 @@ export function willPlaySwarm(targetUrl, config, headless) {
         if (host === '')
             return false;
         const userChoice = runtimeState.getSwarm();
-        const enabled = userChoice ?? config?.swarm?.enabled ?? true;
+        const enabled = userChoice ?? config?.swarm?.enabled ?? false;
         if (!enabled)
             return false;
         const tuning = runtimeState.getSwarmTuning();
@@ -783,9 +783,9 @@ export function maybePlaySwarm(page, config, headless) {
             const host = new URL(url).hostname;
             if (host === '')
                 return;
-            // 用户的开关优先；没表态就用配置里的默认值（出厂是开）。
+            // 用户的开关优先；没表态就用配置里的默认值（出厂是关，与 config.ts 的 schema 一致）。
             const userChoice = runtimeState.getSwarm();
-            const enabled = userChoice ?? config?.swarm?.enabled ?? true;
+            const enabled = userChoice ?? config?.swarm?.enabled ?? false;
             if (!enabled) {
                 // 关着也要把可能已提前启动的引擎撤掉：标记可能是上一次导航残留的，
                 // 不清就会白屏卡住（2026-11-09 复核 find B）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-playwright-codex",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Browser automation for DeepSeek Harness, one plugin: 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; native dialogs are parked instead of confirmed, CAPTCHA pages are flagged with a note that says stop and hand the page back, password / one-time-code / card fields are refused by browser_fill, and the Settings card (enable/disable, page-reading mode, capability gates) now lives inside this package.",
   "license": "MIT",
   "type": "module",
@@ -65,7 +65,9 @@
     "format": "node node_modules/prettier/bin/prettier.cjs --write \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.mjs\"",
     "format:check": "node node_modules/prettier/bin/prettier.cjs --check \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.mjs\"",
     "prepublishOnly": "npm run build && npm run typecheck && npm test && npm run swarm:check && npm run verify && npm run preflight",
-    "preflight": "node scripts/preflight.mjs ."
+    "preflight": "node scripts/preflight.mjs .",
+    "test:toggle": "node --test tests/cross-repo/*.test.ts",
+    "coverage": "node scripts/coverage.mjs"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",