dsh-browser-playwright-codex 0.7.8 → 0.8.1

package/CHANGELOG.md

@@ -1,3 +1,95 @@
+## 0.8.1 — 2026-11-11
+
+一句话摘要：**快照第一次真正"看得见状态"**——填进去的值、勾选状态进快照也进页面指纹，正常的填字和勾选不再被误报成"疑似反爬墙"；密码 / 验证码 / 卡号即使有值也绝不进快照。顺带削掉真实站点快照里最贵的一类垃圾（跳转包裹 URL、同一 href 的重复打印），并让 `browser_evaluate` 返回非标量时给出能照着改的错误。**另外：进场动画重新随包分发——作者 Dhvanil Patel 于 2026-11-11 邮件书面许可打包与修改，默认仍然关闭。**
+
+### Restored
+
+- **`assets/swarm-rebuild.js` 回到 npm 包**：Dhvanil Patel 于 2026-11-11 邮件书面许可本项目**打包 + 修改**（原话 "you are welcome to bundle and modify it as needed"），`package.json#files` 重新列入 `assets/`（原始基线 `assets/swarm-rebuild.upstream.js` 仍只留在仓库）。**功能保持默认关闭**（`swarm.enabled: false`），在设置卡里打开才播。署名与许可切分见 `README.md` 的 Credits 与 `NOTICE.md` §3。
+- **许可不是 MIT**：邮件许可只覆盖本项目随插件分发，没有附 MIT 许可文本，也不给第三方通用许可。第三方想复用得自己去问两位作者（Joel Califa / Dhvanil Patel）。
+
+### Fixed
+
+- **填字 / 勾选不再被误报成"疑似反爬墙"**：`snapshotFingerprint` 原来只比 url / title / refs / role=name，`checked` / `selected` / 值的变化都不算"页面变了"，正常的填字、勾选会触发 no-progress 兜底并劝用户去看窗口。现在 `scan` 收集这些状态、指纹纳入，填字和勾选算成真实变化。
+- **快照显示输入框 / 文本域里的值**：`BrowserNode` / `ChallengeNode` 新增 `value`，模型填完能看见填了什么；`<textarea>`（角色是 `textarea`，不是 `textbox`）也覆盖；`<select>` 不打印 value（它的名字已经显示当前选项）；`<option>` 只在 value 属性与文本不同时才带。
+- **`role="combobox"` 的输入框按标签判定**：排除 value 只针对真正的 `<select>`，不再按 role 排除——自动补全搜索框常带显式 `role="combobox"`，按 role 判会把它们的值也一起藏掉。
+- **密码 / 一次性验证码 / 卡号绝不进快照**：读取 value 前先过 `isCredentialEl`（`type=password`，或 autocomplete 含 `current-password` / `new-password` / `one-time-code` / `cc-*`），与 `browser_fill` 的凭据判据一致。
+- **`<option>` 的名字不再被整段 select 文本污染**：`closest('label')` 会把外层 label 的全部文字塞进每个 option，下拉里所有选项名字原来看起来一模一样。
+- **no-progress 文案改成实话**：不再猜"反爬墙"、不再要求用户去看窗口，改成"这次动作没有带来可见变化；如果是提交 / 搜索 / 跳转，页面可能还在渲染，再拍一次快照确认"。
+
+### Performance
+
+- **跳转包裹 URL 不再打印 160 字符**：`/ck/a?`、`/url?q=`、`l.php?u=` 这类知名跳转端点渲染成 `-> (redirect wrapper)`。实测 Bing 搜索结果页每次快照省约 6,080 字符（约 1,520 token）。
+- **同一快照内重复 href 只打印第一次**：第二次起渲染 `-> (same as e1)`，只去重显示、不合并 ref，点击行为完全不变。实测百度结果页 552 → 263 字节，ref 4 → 4 一个不少。
+
+### Changed
+
+- **`browser_evaluate` 返回非标量时归一化**：数组转 JSON 字符串，`undefined` / 函数转成说明文字并附改法；对象 / 字符串 / 数字 / 布尔 / null 原样返回。DSH 执行器那层的 `value is not lossless JSON` 不再让人靠猜。
+- **新增测试**：`tests/normalize-evaluate.test.ts`、`tests/value-privacy.test.ts`、`tests/combobox-value.test.ts`，分别钉住归一化、凭据不泄漏（有牙齿：去掉守卫立刻红）、`role=combobox` 与 `<textarea>` 的 value 显示。
+
+## 0.8.0 — 2026-11-10
+
+一句话摘要：**动效资产被移出 npm 发布包，swarm 默认关掉**——这是主动选的合规路径，不是修 bug：那套资产的授权状态不允许再分发，与其在授权上纠缠，不如不让它随包出去。代码一行没删，本地开发者把资产放回 `assets/` 打开开关就还是完整功能；代价是 npm 用户升级后默认看不到这个效果。顺带把 0.7.9 那批修复一起封进来——npm 上的 `latest` 一直停在 0.7.8，`v0.7.9` 只是本地 tag，所以从 0.7.8 直接升上来的用户会一次拿到两个版本的全部内容。
+
+### Breaking
+
+- **`swarm.enabled` 默认值 `true` → `false`**：出厂不再播动效。资产不在包里的时候，默认开等于让每个新用户在"文件根本不存在"的状态下开箱即撞。
+- **`assets/` 不再进入 npm 包**：`package.json` 的 `files` 移除了 `assets` 与 `!assets/swarm-rebuild.upstream.js`。仓库里两个文件都还在（`swarm-rebuild.upstream.js` 原始基线 + `swarm-rebuild.js` 补丁后产物），`npm run swarm:check` 的 SHA 校验照旧在本地生效，只是发布出去的 tarball 里没有了。
+- **资产缺失现在静默降级，不是崩溃**：`swarmBootScript()` 读资产改成 `try/catch`，读不到就返回一段空注释脚本。这一点是本次改动的**安全底线**——它的两个调用点都长在 `await ctx.addInitScript({ content: swarmBootScript() })` 上，原来裸读会让资产缺失直接把上下文创建打断，浏览器连开都开不了，等于把"动效没了"放大成"插件挂了"。
+- **`playSwarm` 的旧兜底继续有效**：`readScript()` 早就是 `catch → return`（资源缺失就当没这个功能），这次没有动它。
+
+### 迁移
+
+| 你的情况 | 升级后表现 | 要做的事 |
+| --- | --- | --- |
+| 只是装包用浏览器 | 动效不再出现，其余功能不变 | 无需操作 |
+| 想要动效 | 默认关，开了也看不到（包里没资产） | 把 `assets/swarm-rebuild.js` 放进包根 `assets/`，再把设置卡里 swarm 的 `enabled` 打开 |
+| 本地从仓库开发 | 资产就在仓库里，开关一打开即恢复 | 无 |
+
+以下这批是 0.7.9 的内容：**已经写好、但从未在 npm 上发布过**（`latest` 一直是 0.7.8，`v0.7.9` 只有本地 tag），随本版首次交付。
+
+一句话摘要：**0.7.9 的行为对了，话没跟上**——超时之后实际做的是"把那一页关掉"，报错文案却还在承诺"下一次调用会重开会话"；用户会莫名其妙发现标签页少了一个，而且页面上没提交的内容跟着没了，全程没人告诉他。顺手补上真正走完整链路的回归测试：0.7.9 那三条是单元级假绿，删掉 `capture()` 里那行关页调用照样全过。
+
+### Fixed
+
+- **超时文案和真实行为对齐**：`withDeadline()` 新增 `consequence` 参数，由调用方写明超时之后**真的发生了什么**。`capture()` 现在报的是：那一页已经关掉、填了没提交的内容丢失、如果那是唯一标签则从空白页开始。默认值也去掉了"下一次调用会重开会话"这句不再成立的承诺。
+- **关页代价写进代码注释**：`discardStuckPage()` 明说 `runBeforeUnload:false` 意味着不弹确认、未提交内容直接丢弃——对真卡死的页这笔账划算，但必须让人知道（现在由报错文案负责告知）。
+
+### Tests
+
+- **新增 `tests/read-timeout-e2e.test.ts`（真端到端）**：真浏览器打开一页 → 主线程真死循环 → 读内容真超时 → 断言 ① 报错是 `ACTION_TIMEOUT` 且文案写明页被关、未提交内容丢失；② 那张卡死的页 `isClosed()`；③ 下一次 `acquire()` 拿到的不是同一页，且读得动（活页）。变异验证：把 `capture()` 里 `await this.discardStuckPage(page)` 注释掉，这条用例在"the wedged page must actually be closed"处红；恢复后绿（约 4.5 秒）。
+- **诚实标注旧用例的覆盖面**：`tests/regressions.test.ts` 里那三条（两条直调私有方法塞假页、一条正则读源码）注释里写明只是单元级、`capture()` 不调它就失效，端到端证据在 `read-timeout-e2e.test.ts`。
+
+### Known trade-offs（未在本次行为里改动，仅记录）
+
+- **导航默认不等 `load`**：首屏全靠脚本渲染的页面，快照可能拍到还没长出来的空壳；后面有"等页面稳定"兜着，影响被削弱。
+- **启动锁重试的正则放宽**：任何启动超时都会触发"清一次锁再重试"，卡住的原因与锁无关时（杀软拦截等）会白多等一个 30 秒窗口。
+
+---
+
+## 0.7.9 — 2026-11-10
+
+一句话摘要：**0.7.8 的硬期限只治了"读内容"那一步，四周还留着四个口子** ——最要紧的是读内容超时之后，下一次调用拿回来的还是同一个卡死的页面，所以 0.7.8 承诺的"自动换一个干净的句柄"从来没有真的发生。本版补上这一处，另外三处是顺势加固：启动阶段原本一次超时都没传、配置锁的重试一直在等一个不会出现的错误形状、导航默认等 `load` 让长连接页面白等到超时。这四项里只有第一项对得上 issue #5 报的"自愈无效"，其余三项不是报告人提的，也不是原判定的缺口。发版自查时另外揪出一处 0.7.8 自己的毛病：期限定时器被 `unref`，进程里只剩它一个句柄时事件循环直接收工，那条 `ACTION_TIMEOUT` 永远发不出来——顺带让 7 条回归测试变成"未运行"，而报告仍是 `fail 0`（详见下面第二条）。
+
+### Fixed
+
+- **超时之后把卡死的页面原样发回来**：`invalidateOwner()` 只把条目从表里删掉，持久化模式下 `ensurePage()` 下一次又按索引把同一个页面交回去，于是"下一次调用重开会话"这句承诺落空，页面继续烂在原地。现在超时后由 `discardStuckPage()` 真正关闭那一页——带期限、尽力而为，关不掉也不拖住报错路径——下一个 `acquire()` 从活着的标签页开始。
+- **期限定时器不该 `unref`**：0.7.8 写的 `timer.unref?.()` 会让"到点必须断"变成"到点看心情"——若这是进程里最后一个句柄，事件循环判定无事可做直接退出，调用方等不到超时、也等不到别的东西。同样因为这个，`tests/read-deadline.test.ts` 那 7 条在孤立运行时全部被打成 `cancelledByParent`（`Promise resolution is still pending but the event loop has already resolved`），而 `node --test` 只报 `fail 0`、不报错，看起来是一片绿。所以 0.7.8 记的"通过 278 / 跳过 3 / 失败 0"里，实际只有 271 条真的跑过。去掉 `unref` 后 7 条全部实跑通过。
+
+### Changed
+
+- **启动阶段补上限**：`launchPersistentContext` 原来没传 timeout，配置目录被占用、单例握手卡住、GPU 初始化挂死都会让 `acquire()` 无限等下去。现在传 `max(navigationTimeoutMs, 30s)`——`navigationTimeoutMs` 允许低到 1 秒，冷启动浏览器根本不够用，所以另设 30 秒地板。
+- **锁重试认错了错误形状**：原逻辑只匹配锁文件名，而 Playwright 把同一种情况报成 `Timeout 30000ms exceeded`，等于这段重试从来没触发过。现在两种形状都认。
+- **导航默认不再等 `load`**：`navigate` / `open_tab` 的默认 `waitUntil` 从 `load` 改成 `domcontentloaded`。长轮询、流式、下载类页面的 `load` 永远不来，导航超时全花在一个早就可用的页面上。
+- **README / PLUGIN-README 的 token 表按新测量重抄**：11,283 / 15,886 字符。
+
+### Tests
+
+- 新增 3 条回归：卡死页只关一次、`close()` 不返回也不能再把错误路径挂住、两个默认值钉死。
+- 全套 **305 条**：通过 302、跳过 3、失败 0，**302 + 3 = 305，一条没漏**。这次特意核对总数而不是只看 `fail 0`——0.7.8 就是在这个位置看走眼的。
+- 复跑方式（本机 Node 22 需要显式打开类型剥离，否则 `npm test` 会以 `Unknown file extension ".ts"` 全崩）：`set NODE_OPTIONS=--experimental-strip-types && npm test`。
+
+---
+
 ## 0.7.8 — 2026-11-10
 
 一句话摘要：**工具调用不会再无限挂着** —— 打开网页之后"读页面内容"这一步一直没有超时上限，也不接取消信号，页面自己的脚本把浏览器主线程占住时，整个工具调用就停在那里等（GitHub issue #5 报的就是这个，实测能卡到分钟级）。现在读内容有硬期限、能按取消退出，超时后自动换一个干净的会话句柄。

package/NOTICE.md

@@ -1,8 +1,8 @@
 # NOTICE — licensing split, provenance, and third-party content
 
-This repository mixes work from three different origins. They are **not** under one licence, and the split is deliberate.
+This repository mixes work from four different origins. They are **not** under one licence, and the split is deliberate.
 
-本仓库的内容来自三个不同来源，**不是单一许可**，切分如下。
+本仓库的内容来自四个不同来源，**不是单一许可**，切分如下。
 
 ## 1. The plugin — MIT (`./LICENSE`)
 
@@ -24,15 +24,36 @@ Covers only the two analysis documents produced *for this repository*:
 
 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: 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.
+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). As of 0.8.1 the tarball also carries the third-party file described in §3, under its own written permission — that file is **not** MIT, and §1 does not cover it.
 
-## 3. Third-party content that is **not** redistributed here
+## 3. The intro effect asset — third-party code, bundled with written permission
+
+`assets/swarm-rebuild.js` (**shipped again in the npm tarball as of 0.8.1** — `package.json#files` lists `assets/`, minus the pristine baseline) is **not** this project's work. The position, stated plainly:
+
+1. **We hold written permission from Joel Califa for the effect and its choreography** (2026-11-08, on file; his one condition was that he be credited). That credit is in [`README.md`](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/README.md#credits--the-intro-effect) and in the settings card.
+2. **We hold written permission from Dhvanil Patel for the script** (email, 2026-11-11, on file): he is "happy for you to use and adapt the animation", and answers "yes, you are welcome to bundle and modify it as needed". **Bundling and modification are both covered.** No MIT (or other OSI) licence was granted — the grant is that written email, not a licence text, and it does **not** give third parties a general licence to extract and re-use the file.
+3. **This project claims and grants no rights in that file.** It travels inside this package under that permission only. If either author withdraws it, the file — and the feature that injects it — will be removed on request.
+
+| Origin | What | Status |
+|---|---|---|
+| [califa/swarm-site](https://github.com/califa/swarm-site) — **Joel Califa** | The effect itself: the page wiped white, the swarm of cursors, and the choreography that draws boxes, text and images back. The published copy declares no licence. | Written permission, 2026-11-08, condition: credit. Done. |
+| [DhvanilPatel/swarm-cursors](https://github.com/DhvanilPatel/swarm-cursors) — **Dhvanil Patel** | `swarm-rebuild/swarm.js` at commit `3d49e0ac` (2026-11-06). That repository declares no licence ("None yet") and its README says the original Swarm was released without one. | Written permission by email, 2026-11-11: bundle + modify. Bounded to this project. |
+
+**Modified, and the modification is disclosed.** `assets/swarm-rebuild.js` is that upstream file **with seven changes**, applied by [`scripts/swarm-patch.mjs`](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/scripts/swarm-patch.mjs): (1) the vendor's own bottom control bar is removed; (2) its four DOM fields are pointed at off-screen placeholders so the rest of the code keeps working; (3) its per-frame HUD refresh returns early; (4) the end-of-playback button updates are null-guarded — that last one is a real crash fix: without it the asset throws as soon as the animation completes; (5) scanning waits for the plugin's go-ahead (so the snapshot is taken before the page is scrolled); (6) the white background no longer fades in over 0.5 s, and on early starts the scroll environment is re-detected once after the page loads; (7) its final self-start is deferred until `<html>` exists, so the whole engine can run from `addInitScript` before the page's own scripts. The patched file ships inside the npm package as of 0.8.1, while the pristine upstream baseline stays **in the repository only** (`assets/swarm-rebuild.upstream.js`, SHA-256 `6a30f19d…c7bfe`) — so anyone can diff what we changed and regenerate the patched file with `npm run swarm:patch`, or check that it still matches with `npm run swarm:check`.
+
+**运行方式也被改了**：本项目不是等网页加载完再运行这份第三方脚本，而是通过 Playwright 的 `addInitScript` 把它放到**网页自己的脚本之前**执行（只在顶层文档、且带一个 30 秒内有效的 `window.name` 标记时启动），启动时机再由 `window.__dshSwarmGo` 放行控制。也就是说，第三方作品的启动流程、注入时机和运行上下文都由本项目重新安排过；这一步同样落在 Dhvanil 邮件许可的「modify」范围内。
+
+**中文**：`assets/swarm-rebuild.js` **改过**（0.8.1 起重新随 npm 包分发；原始基线只留在仓库），改动共七处 —— ①删掉原版自带的底部控制条；②把它的四个界面字段指向离屏占位元素（否则下游代码会抛错）；③让每帧的界面刷新提前返回；④播完那一下设置按钮显示状态的代码加空值保护（这一处是**真崩溃修复**：不改的话动画一播完就抛错）；⑤扫描改成等插件放行、开场至少停 2.8 秒（拍快照前不滚页面）；⑥白底去掉 0.5 秒淡入、第一帧就盖死，提前启动时页面加载完再重认一次滚动环境；⑦结尾自启动改成「等 `<html>` 出现」，这样整台引擎能在网页脚本之前就跑起来。**打包和修改都已获得 Dhvanil Patel 邮件书面许可（2026-11-11）**；许可只覆盖本项目随插件分发，不是给第三方的通用许可，也没有附 MIT 许可文本。补丁产物随包走，原始基线 `assets/swarm-rebuild.upstream.js` 留在仓库（SHA-256 可核对），所以任何人都能 diff 出我们改了什么，用 `npm run swarm:patch` 复原生成、用 `npm run swarm:check` 校验。
+
+What this means for you: §1 (MIT) does **not** cover `assets/swarm-rebuild.js`; it travels in the package under the authors' written permission to this project. That permission is **not** a licence to you — if you want to re-use that file elsewhere, ask the two authors yourself.
+
+## 4. Third-party content that is **not** redistributed here
 
 - **No OpenAI code is included in this repository.** Nothing from the bundled Codex browser plugin (`extension-host.exe`, the Chrome extension, `browser-client.mjs`, its `node_modules`) is copied, linked, decompiled or redistributed here.
 - `codex-rules.md` is an **independently written Chinese summary of browser-automation behaviour**, produced by studying publicly observable behaviour and a locally installed copy of that plugin's documentation. It contains no verbatim reproduction of that documentation; what it does contain is a *source map* (file names such as `docs/browser-safety.md`) so readers can consult the originals themselves. Facts and ideas are not copyrightable; the expression here is this project's own.
 - **Rights in the original Codex documentation and browser plugin remain with their owner (OpenAI).** If you are that owner and you object to the source map or to any phrasing here, open an issue and it will be removed.
 - `openai/codex` (the CLI) is Apache-2.0. It is mentioned for context only; no code from it is included.
 
-## 4. If you need a different split
+## 5. If you need a different split
 
 Want the analysis prose under a permissive licence, or the whole thing MIT? Open an issue — that licence is a choice, not a constraint. The plugin's licence is not (see §1).

package/README.md

@@ -1,8 +1,8 @@
 # dsh-browser-playwright-codex
 
-[![npm 版本](https://img.shields.io/npm/v/dsh-browser-playwright-codex?label=npm)](https://www.npmjs.com/package/dsh-browser-playwright-codex) [![License](https://img.shields.io/npm/l/dsh-browser-playwright-codex)](LICENSE) [![Node](https://img.shields.io/node/v/dsh-browser-playwright-codex)](package.json) [![最新发布](https://img.shields.io/github/v/release/miqian-nomad/dsh-browser-playwright-codex)](https://github.com/miqian-nomad/dsh-browser-playwright-codex/releases)
+[![CI](https://github.com/miqian-nomad/dsh-browser-playwright-codex/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/miqian-nomad/dsh-browser-playwright-codex/actions/workflows/ci.yml) [![npm 版本](https://img.shields.io/npm/v/dsh-browser-playwright-codex?label=npm)](https://www.npmjs.com/package/dsh-browser-playwright-codex) [![npm 下载](https://img.shields.io/npm/dm/dsh-browser-playwright-codex?label=%E4%B8%8B%E8%BD%BD)](https://www.npmjs.com/package/dsh-browser-playwright-codex) [![License](https://img.shields.io/npm/l/dsh-browser-playwright-codex)](LICENSE) [![Node](https://img.shields.io/node/v/dsh-browser-playwright-codex)](package.json) [![最新发布](https://img.shields.io/github/v/release/miqian-nomad/dsh-browser-playwright-codex)](https://github.com/miqian-nomad/dsh-browser-playwright-codex/releases) [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
 
-> [![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/)
+> [![dsh.so 安装验证 · harness 0.2.2-rc.1](https://www.dsh.so/badge/install/dsh-browser-playwright-codex@0.2.2-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 用你**已经登录的账号**在真实网页上干活 —— 填表、抓取列表、多标签查后台；浏览器窗口就在你桌面上、你随时看得见。原生弹框会被挂起、**绝不替你点「确定」**（机制级）；验证码/挑战页会被识别出来，并以提示要求模型停下交给你（**提示不是阻断**）。登录/二次验证**没有探测器**，靠模型从快照看出来并停下；密码、一次性验证码、卡号字段 `browser_fill` **直接拒绝**——这类字由你本人在窗口里输。
 
@@ -41,6 +41,8 @@ dsh plugin --profile <name> add github:miqian-nomad/dsh-browser-playwright-codex
   silently clicking a different element.
 - **强力工具默认关闭** — `browser_evaluate` / `browser_cdp` are **not registered at all** unless your
   deployment opts in; this package ships both off.
+- **第一次打开一个网站时，页面会自己「长」出来** — 整页被抹白，然后一群光标把方框、文字、图片一笔一笔画回来，播完自动退回真实页面（可关，设置卡里可调速度/时长）。动效与编排出自 **Joel Califa** 的 [Swarm](https://github.com/califa/swarm-site) — 他 2026-11-08 书面同意本项目使用，条件是**署名**，见 [Credits](#credits--the-intro-effect)。
+  The page is wiped white, then a swarm of cursors draws it back — boxes, text and images, one stroke at a time, before handing the real page over. The effect and its choreography are **Joel Califa's** [Swarm](https://github.com/califa/swarm-site), used with his written permission on the one condition that he is credited ([Credits](#credits--the-intro-effect)).
 
 **安全一览 / 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.
@@ -68,12 +70,12 @@ 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`. 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
+**Compatibility.** Built and tested against DSH `0.2.2-rc.1`. The dependency ranges are **floors, not
+wildcards**: peers `@deepseek-ai/cordis` `>=4.1.0`, `@deepseek-ai/dsh-llm` `>=0.2.2-rc.1`,
+`@deepseek-ai/dsh-tools` `>=0.2.2-rc.1`, and the direct dependency `@deepseek-ai/schemastery` `^3.19.0`. 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
+`0.2.2` (for example `0.2.3-rc.*`) is outside a `>=0.2.2-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".
@@ -380,9 +382,9 @@ Measured with ``npm run cost`` (per-turn, resident in the system prompt):
 
 | Surface | Tools | Schema characters | ≈ tokens/turn |
 |---|---|---|---|
-| Schema defaults (`Config({})`, no patch layer) | 16 | 11,095 | ≈ 3,082 |
-| Shipped bundle layer (this package's `cordis.patch.yml`: both power gates off) | 16 | 11,095 | ≈ 3,082 |
-| Everything registered (`registerDisabledTools: true`, plus `extract`) | 21 | 15,698 | ≈ 4,361 |
+| Schema defaults (`Config({})`, no patch layer) | 16 | 11,283 | ≈ 3,134 |
+| Shipped bundle layer (this package's `cordis.patch.yml`: both power gates off) | 16 | 11,283 | ≈ 3,134 |
+| Everything registered (`registerDisabledTools: true`, plus `extract`) | 21 | 16,146 | ≈ 4,485 |
 
 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
@@ -460,9 +462,22 @@ The scenario suites originally surfaced four hazards, now fixed and regression-t
 - **Idle disposal defers during operations** — a navigation slower than `idleTimeoutMs` completes normally; disposal only fires when the session is truly idle.
 - **Mid-navigation snapshots settle** — a `browser_snapshot` racing a JS navigation waits for the new document and retries instead of surfacing a raw "Execution context was destroyed" error.
 
+## Credits — the intro effect
+
+The first-open effect (the page is wiped white, then a swarm of cursors draws the boxes, text and images back) is **not this project's work**, and its code is one third-party file — **shipped inside the npm package again as of 0.8.1, with the authors' written permission** (still off by default):
+
+- **The effect and its choreography** — [Swarm](https://github.com/califa/swarm-site) by **Joel Califa** ([swarm.joelcalifa.com](https://swarm.joelcalifa.com)). Used with his written permission (2026-11-08), on his one condition: **credit him** — this section is that credit.
+- **The code** — `assets/swarm-rebuild.js`, from [`DhvanilPatel/swarm-cursors`](https://github.com/DhvanilPatel/swarm-cursors) at commit `3d49e0ac` (2026-11-06, file `swarm-rebuild/swarm.js`), **with seven changes** (all in [`scripts/swarm-patch.mjs`](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/scripts/swarm-patch.mjs): the vendor's own control bar removed, its four DOM fields retargeted at off-screen placeholders, the per-frame HUD refresh short-circuited, the end-of-playback updates null-guarded — that one fixes a crash the removal would otherwise cause — scanning gated on the plugin's go-ahead, the 0.5 s white fade-in dropped, and its self-start deferred until `<html>` exists. **Dhvanil Patel granted written permission by email on 2026-11-11 to bundle and modify it**; that grant covers this plugin, not third-party re-use, and comes with no MIT licence text. The pristine baseline stays in the repository as `assets/swarm-rebuild.upstream.js`, SHA-256 `6a30f19d…c7bfe`).
+
+The exact licensing split, and what is still outstanding, is recorded in [`NOTICE.md`](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/NOTICE.md).
+
+**中文**：首次打开网页的「进场特效」——页面被抹白，再由一群光标把方框、文字、图片一笔一笔画回来——**不是本项目自己的作品**。动效与编排出自 **Joel Califa** 的 [Swarm](https://github.com/califa/swarm-site)，他于 2026-11-08 书面同意本项目使用，唯一条件是**署名**，此节即为署名；代码取自 [DhvanilPatel/swarm-cursors](https://github.com/DhvanilPatel/swarm-cursors) 的 `assets/swarm-rebuild.js`（改过七处）。**Dhvanil Patel 于 2026-11-11 邮件书面许可本项目打包与修改**，所以从 **0.8.1 起这份资产重新随 npm 包分发**（仍默认关闭）；该许可只覆盖本插件，不附 MIT 许可文本。许可切分与仍在等的事见 `NOTICE.md`。
+
 ## License
 
-MIT
+MIT — **except `assets/swarm-rebuild.js`** (third-party work, shipped in the package as of 0.8.1 under the authors' written permission — no MIT licence text), which is covered by [Credits](#credits--the-intro-effect) above and [`NOTICE.md`](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/NOTICE.md) §3. This project grants no rights in that file.
+
+**中文**：插件本体与随包文档是 MIT；**`assets/swarm-rebuild.js` 除外**（第三方作品，**0.8.1 起在作者书面许可下重新随包分发**，无 MIT 许可文本），本项目不对它主张也不授予任何权利，详见上文 Credits 与 `NOTICE.md` §3。
 
 
 <!-- changelog:today -->
@@ -470,6 +485,14 @@ MIT
 
 （此列表只记 **minor 里程碑**；每个补丁版本见 [CHANGELOG.md](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/CHANGELOG.md)。）
 
+### 0.8.0（2026-11-10）
+
+- **动效资产移出发布包（破坏性）**：`assets/swarm-rebuild.js` 不再随 npm 包分发，`package.json` 的 `files` 移除了 `assets` 相关两条。原因是那套资产是第三方作品、授权状态不允许再分发 —— 与其在授权上纠缠，不如不让它进 tarball。仓库里文件仍在，`npm run swarm:check` 的 SHA 校验照旧有效。
+- **`swarm.enabled` 出厂默认改为 `false`（破坏性）**：包内没有资产的前提下默认开，等于让每个新用户开箱撞一个不存在的文件。所有开关、代码路径一律保留，不动一行行为逻辑。
+- **资产缺失改为静默降级**：`swarmBootScript()` 读资产包了 `try/catch`，读不到就注入一段空注释脚本。它挂在上下文创建的 `addInitScript` 上，裸抛会把"动效没了"放大成"浏览器打不开"，这条是本次改动的安全底线。
+- **想要动效的人**：把 `assets/swarm-rebuild.js` 放进包根 `assets/`，再在设置卡里打开 swarm 开关即可恢复，功能与 0.7.x 完全一致。
+- **0.7.9 一并交付**：该版只有本地 tag，npm 上一直停在 0.7.8，从 0.7.8 升级会一次拿到 0.7.9 + 0.8.0 的全部内容，细节见 CHANGELOG。
+
 ### 0.7.0（2026-10-19）
 
 - **两个插件合成一个（破坏性）**：设置卡片并入本包（`dsh.client` + `./client`），`dsh-browser-toggle` 退役；`cordis.patch.yml` 从三行 loader 收成**一行** —— `- id: browser` 加嵌套的 `service` / `playwright` / `tool`。这是硬约束：`dsh-client-modules` 拒绝一个包被多个 loader 行挂载，所以带 client 的包只能有一个入口。