dsh-browser-playwright-codex 0.7.8 → 0.8.0

package/lib/swarm-contract.d.ts

@@ -0,0 +1,226 @@
+/**
+ * swarm-contract — 这段第三方资产的**接口契约**：插件到底捏着上游脚本的哪几个把手。
+ *
+ * 为什么要有这个文件（2026-11-10）：
+ *
+ * 起因是"上游改版，我这边会不会突然失效"。查完事实是：**不会**。上游那份脚本是
+ * vendored 进来的（`assets/swarm-rebuild.upstream.js`），SHA-256 在 `scripts/swarm-patch.mjs`
+ * 里锁死，上游在 GitHub 上改成什么样，本地这份一个字节都不会动。真正会失效的是另一件事 ——
+ * 插件对上游内部结构的依赖**散落在三个文件的字符串里**（`swarm-intro.ts` 里 20 余处
+ * `page.evaluate` 的字面量、`swarm-curtain.ts` 的桥、`swarm-patch.mjs` 的匹配片段），
+ * 没有任何一处声明"这是我们要的接口"。于是：
+ *
+ *   - 加一处依赖，没人知道又多了个耦合点；
+ *   - 补丁改一处，插件侧不知道自己的前提已经变了；
+ *   - `docs/SWARM-CODE.md` 写着"改动 4 处"，实际已经是 7 处 —— 文档对不上代码，
+ *     而这份文档正是"上游改版时该查哪里"的唯一依据。
+ *
+ * 所以这里把三个层次钉死，并交给 `tests/swarm-contract.test.ts` 机械校验：
+ *
+ *   Tier A（硬接口）  上游自己挂在 window 上的句柄树。补丁一处都没动，插件主路径全走这里。
+ *                     上游改了 → 插件立刻坏 → 这是**必须盯住**的部分。
+ *   Tier B（兜底口）  `.hud` / `[data-a=*]`。上游原生，但**已被我们的补丁删掉**。
+ *                     插件只在"万一有人塞回未打补丁的原版"时才走这些分支。
+ *   Tier C（自造桥）  `__dshSwarm*`。我们自己注入的，上游永远不会提供，也不该指望。
+ *
+ * 契约的用法：**改任何一处依赖，先改这个文件**，再改实现，再看测试红绿。测试会去
+ * `assets/swarm-rebuild.upstream.js` 里逐条核对下面的每个名字是否真的存在 —— 上游换人、
+ * 改名、删节点，这里第一个报错，而不是等某天浏览器里莫名其妙不播了。
+ *
+ * 法律面（别绕过它）：上游仓库根目录**没有 LICENSE**（默认保留所有权利），
+ * issue #12 至今零回复。所以这段资产**不能 fork 成"我们自己的版本"** —— fork 不改变授权，
+ * 只多出一份照样没有许可的副本。它只能留在本机自用、默认关闭、不随包分发。
+ */
+/** 上游出处与入仓指纹。这三项之外的任何东西，都不该成为插件的依赖。 */
+export declare const SWARM_UPSTREAM: {
+    /** 上游仓库。注意：根目录没有 LICENSE 文件。 */
+    readonly repo: "DhvanilPatel/swarm-cursors";
+    /** 入仓的那份原始文件（**未经补丁**）。diff 的基准。 */
+    readonly vendoredFile: "assets/swarm-rebuild.upstream.js";
+    /**
+     * 入仓时那份上游文件的 SHA-256。
+     * `scripts/swarm-patch.mjs` 的 `UPSTREAM_SHA256` 必须与它逐字符相同（测试会比对），
+     * 否则"补丁按哪一版写的"就说不清了。
+     */
+    readonly sha256: "6a30f19daaa182d52673035feaeae775c398fa426655cc71a87a451fe00c7bfe";
+    /** 补丁后的产出（**随包分发的那份**）。 */
+    readonly patchedFile: "assets/swarm-rebuild.js";
+    /** 授权状态：`none` = 无许可证，默认保留所有权利。不是"宽松许可"。 */
+    readonly license: "none";
+};
+/**
+ * Tier A —— 硬接口。上游官方句柄树，补丁完全没碰，插件主路径全走这里。
+ *
+ * 事实依据（2026-11-10 在 `assets/swarm-rebuild.upstream.js` 里核对过）：
+ *   上游用 `const KEY = "__swarmRebuild"; window[KEY] = { toggle() {...}, stop(...) }` 暴露自己，
+ *   并把 `app`（engine / env / view / tour）挂在同一个对象上。这一段补丁一字未改。
+ */
+export declare const SWARM_API: {
+    /** 上游暴露自己的全局名。脚本第二次注入时会自己 `toggle()`。 */
+    readonly global: "__swarmRebuild";
+    /** 句柄上的方法。 */
+    readonly methods: {
+        readonly toggle: "toggle";
+        /**
+         * 停止。补丁后的脚本里 `stop(false)` = 立刻 destroy（取消 RAF、移除宿主），
+         * `stop(true)` = 淡出回真页面（原来 "Go live" 按钮走的路）。
+         * **插件一律用 `false`**：要的是立刻让路，不是让用户看淡出。
+         */
+        readonly stop: "stop";
+    };
+    /** `stop(reveal)` 的两种语义。 */
+    readonly stopArgs: {
+        /** 立即销毁，不留残余覆盖层。插件用这个。 */
+        readonly immediate: false;
+        /** 淡出到真页面。 */
+        readonly reveal: true;
+    };
+    /** `window.__swarmRebuild.app` 上插件用到的字段。 */
+    readonly app: {
+        /** 引擎：速度/启动都在这里。 */
+        readonly engine: {
+            readonly path: "engine";
+            /** 速度，上游初值 `1`；上游 UI 的 `speeds = [1, 2, 3]`，按钮点 N 次即 1+N 倍。**可直接写。** */
+            readonly speed: "speed";
+            /** 启动引擎（`app.tour = true` 之后调它才真正开始往下滚）。 */
+            readonly start: "start";
+            /** 是否已启动。已是 `true` 就别再 `start()` 一遍。 */
+            readonly started: "started";
+        };
+        /** 环境探针：整页滚动 / 局部滚动（`overflow:auto` 容器）都靠它。 */
+        readonly env: {
+            readonly path: "env";
+            /** `() => { ox, oy, sx, sy, vw, vh }`。局部滚动页里 `window.scrollY` 恒为 0，只有它知道真实位置。 */
+            readonly geom: "geom";
+            /** `(y, x) => void`，`behavior: 'instant'`。还原滚动位置用。 */
+            readonly scrollTo: "scrollTo";
+        };
+        /** 视图：影子树的入口。 */
+        readonly view: {
+            readonly path: "view";
+            /** 影子树（上游以 `mode: 'open'` 创建）。 */
+            readonly root: "root";
+        };
+        /** 整页模式开关。上游 Tour 按钮只做两件事之一就是这个；补丁删了按钮，所以直接写字段。 */
+        readonly tour: "tour";
+    };
+    /** 句柄自身的影子树兜底（`app.view.root` 拿不到时用它）。 */
+    readonly rootFallback: "root";
+    /** 覆盖层的宿主元素：自定义元素标签，`document.querySelector` 可直接选到。 */
+    readonly hostTag: "swarm-rebuild";
+};
+/**
+ * Tier B —— 兜底口。上游原生，但**已被补丁删除**，插件只在"塞回了未打补丁的原版"时才用到。
+ *
+ * 2026-11-10 核对 `assets/swarm-rebuild.js`：`data-a=` 从上游的 11 处降到 2 处 ——
+ * 控制条整个被删（`scripts/swarm-patch.mjs` 第 1 处改动），剩下两处是
+ * `[data-a="sound"]`（有 `if (!b || !this.sfx)` 防护）和一处 `name` 拼接的通用选择器。
+ *
+ * **所以这一层不是主路径。** 主路径全在 Tier A。这里留着是为了：有人把未打补丁的原版
+ * 塞回 `assets/`，插件仍然能用（点按钮），而不是当场白屏。
+ */
+export declare const SWARM_DOM: {
+    /** 控制条容器。CSS 里定义：`.hud` / `.hud.on` / `.hud .dots` / `.hud .txt` / `.hud .status`。 */
+    readonly hud: ".hud";
+    /** 头像组（控制条上的小圆点）。 */
+    readonly dots: ".hud .dots";
+    /** 状态文字。 */
+    readonly status: ".hud .status";
+    /** 进度条：`<div class="bar"><i></i></div>`。 */
+    readonly barFill: ".hud .bar i";
+    /** 插件往影子树里插的隐藏规则所带的标记（重试时据此判断"已经插过了"）。 */
+    readonly hideStyleAttr: "data-dsh-swarm-hide";
+    /** 隐藏规则本体。用 CSSOM/内联 + 这条规则双层压住，重建的节点也一并压。 */
+    readonly hideStyleText: ".hud{display:none!important}";
+    /**
+     * 控制条按钮。`selector` 是插件实际会用 `querySelector` 去点的那个字符串。
+     *
+     * `upstreamQuery` 标的是**另一件事**：上游自己的代码里有没有出现过这个选择器。
+     * 两者不等价，`close` 就是反例 —— 上游 HTML 里确实渲染了 `<button data-a="close" class="x">✕</button>`，
+     * 但它的代码从不 `querySelector('[data-a="close"]')`，点击走事件委托。
+     * 也就是说这一条是**我们自己声称有效**的选择器，靠的是 DOM 属性确实存在，而不是上游验证过。
+     * 上游哪天把 `data-a` 换成别的属性名、HTML 模板改了而代码没改（反之亦然），差别就在这里。
+     */
+    readonly buttons: {
+        /** 整页自动滚动。插件不点它（改 `app.tour = true`），留着仅为完整性。上游有查询。 */
+        readonly tour: {
+            readonly action: "tour";
+            readonly selector: "[data-a=\"tour\"]";
+            readonly upstreamQuery: true;
+        };
+        /** 帧速切换（1× → 2× → 3×）。插件直接写 `engine.speed`，不点它。上游有查询。 */
+        readonly speed: {
+            readonly action: "speed";
+            readonly selector: "[data-a=\"speed\"]";
+            readonly upstreamQuery: true;
+        };
+        /** 声音开关（快捷键 M）。插件从不碰。上游有查询（带 `if (!b || !this.sfx)` 空值防护）。 */
+        readonly sound: {
+            readonly action: "sound";
+            readonly selector: "[data-a=\"sound\"]";
+            readonly upstreamQuery: true;
+        };
+        /** Go live = `stop(true)`。兜底退出路径之一。上游有查询。 */
+        readonly live: {
+            readonly action: "live";
+            readonly selector: "[data-a=\"live\"]";
+            readonly upstreamQuery: true;
+        };
+        /** 重播。插件从不碰。上游有查询。 */
+        readonly replay: {
+            readonly action: "replay";
+            readonly selector: "[data-a=\"replay\"]";
+            readonly upstreamQuery: true;
+        };
+        /** ✕ = `stop(false)`。兜底退出路径之二。**上游不查询它**（事件委托），仅 HTML 属性存在。 */
+        readonly close: {
+            readonly action: "close";
+            readonly selector: "[data-a=\"close\"]";
+            readonly upstreamQuery: false;
+        };
+    };
+    /** 退出时的兜底顺序：先 live 再 close（对应 `stop(true)` / `stop(false)`）。 */
+    readonly exitFallbackOrder: readonly ["[data-a=\"live\"]", "[data-a=\"close\"]"];
+};
+/**
+ * Tier C —— 自造桥。插件注入页面、上游永远不会提供的那些全局名。
+ *
+ * 上游改版跟这一层**无关**（它根本不认识这些名字）。这一层坏的原因通常是插件自己改了
+ * 注入时机、或者有人重构时漏了某个赋值 —— 所以它更需要测试，而不是文档。
+ */
+export declare const SWARM_BRIDGE: {
+    /** `() => void`，插件注入的"立刻退出"入口。**Tier A 的 `stop(false)` 走不通时才用。** */
+    readonly stop: "__dshSwarmStop";
+    /** `{ x, y }`，播放前的滚动位置。局部滚动页由 `env.geom()` 覆盖掉 window 那份。 */
+    readonly start: "__dshSwarmStart";
+    /** `true` = 引擎已在 `addInitScript` 阶段提前起来，**绝不能再注入第二遍**（否则白底和光标全部重来）。 */
+    readonly early: "__dshSwarmEarly";
+    /** `true` = AI 已经在用这个页面，整页滚动循环看到它就停。 */
+    readonly aiWorking: "__dshSwarmAiWorking";
+    /** `true` = 快照已经拿到手，可以放行扫描。`swarm-patch.mjs` 第 5 处改动等它。 */
+    readonly go: "__dshSwarmGo";
+};
+/**
+ * 上游自带的诊断钩子。插件**不依赖**它们，列在这里是为了两件事：
+ *   ① 调试时知道这些名字是谁的，别误当成我们的桥；
+ *   ② 上游改版核对时，这些名字若消失，说明改动范围比预期大，值得警觉。
+ */
+export declare const SWARM_UPSTREAM_DEBUG_HOOKS: readonly ["__swarmShot", "__swarmSfxLog", "__swarmHidden", "__swarmUnhide"];
+/**
+ * 上游改版应急流程。**这是"有据可依"的落点** —— 不是祈祷上游别改，而是改了好核对。
+ *
+ * 触发条件：把新的上游文件换进 `assets/swarm-rebuild.upstream.js`（这一步必须是人主动做的）。
+ * 本地日常开发**不需要**做任何事：vendored 文件不会自己变。
+ *
+ * 核对顺序（严格按此序，否则会追错方向）：
+ *   1. `npm run swarm:patch` —— SHA 不符会当场拒绝，并报出新旧两个哈希。**先看这一条。**
+ *   2. 按新哈希更新 `SWARM_UPSTREAM.sha256` 和 `scripts/swarm-patch.mjs` 的 `UPSTREAM_SHA256`
+ *      （两处必须一致，测试会比对）。
+ *   3. `node --test tests/swarm-contract.test.ts` —— 它会逐条到新文件里找 Tier A/B 的每个名字。
+ *      红的每一条，就是上游这次真动过的地方，一条一条处理。
+ *   4. 只有 Tier A 变红才是**必须改代码**的。Tier B 变红通常只需更新选择器（它只是兜底）。
+ *      Tier C 变红说明插件自己的桥出了问题，与上游无关。
+ *   5. 改完实现后，跑 `npm test` 全量 —— `swarm-intro.test.ts` 会用假 page 校验调用序列。
+ *   6. 最后更新 `docs/SWARM-CODE.md`（改了几处、为什么）和 `docs/SWARM-CONTRACT.md` 的指纹段。
+ */
+export declare const SWARM_UPGRADE_CHECKLIST: readonly ["npm run swarm:patch", "sync SWARM_UPSTREAM.sha256 <-> scripts/swarm-patch.mjs UPSTREAM_SHA256", "node --test tests/swarm-contract.test.ts", "triage red: Tier A = code change, Tier B = selector update, Tier C = our own bug", "npm test", "update docs/SWARM-CODE.md + docs/SWARM-CONTRACT.md fingerprints"];

package/lib/swarm-contract.js

@@ -0,0 +1,209 @@
+/**
+ * swarm-contract — 这段第三方资产的**接口契约**：插件到底捏着上游脚本的哪几个把手。
+ *
+ * 为什么要有这个文件（2026-11-10）：
+ *
+ * 起因是"上游改版，我这边会不会突然失效"。查完事实是：**不会**。上游那份脚本是
+ * vendored 进来的（`assets/swarm-rebuild.upstream.js`），SHA-256 在 `scripts/swarm-patch.mjs`
+ * 里锁死，上游在 GitHub 上改成什么样，本地这份一个字节都不会动。真正会失效的是另一件事 ——
+ * 插件对上游内部结构的依赖**散落在三个文件的字符串里**（`swarm-intro.ts` 里 20 余处
+ * `page.evaluate` 的字面量、`swarm-curtain.ts` 的桥、`swarm-patch.mjs` 的匹配片段），
+ * 没有任何一处声明"这是我们要的接口"。于是：
+ *
+ *   - 加一处依赖，没人知道又多了个耦合点；
+ *   - 补丁改一处，插件侧不知道自己的前提已经变了；
+ *   - `docs/SWARM-CODE.md` 写着"改动 4 处"，实际已经是 7 处 —— 文档对不上代码，
+ *     而这份文档正是"上游改版时该查哪里"的唯一依据。
+ *
+ * 所以这里把三个层次钉死，并交给 `tests/swarm-contract.test.ts` 机械校验：
+ *
+ *   Tier A（硬接口）  上游自己挂在 window 上的句柄树。补丁一处都没动，插件主路径全走这里。
+ *                     上游改了 → 插件立刻坏 → 这是**必须盯住**的部分。
+ *   Tier B（兜底口）  `.hud` / `[data-a=*]`。上游原生，但**已被我们的补丁删掉**。
+ *                     插件只在"万一有人塞回未打补丁的原版"时才走这些分支。
+ *   Tier C（自造桥）  `__dshSwarm*`。我们自己注入的，上游永远不会提供，也不该指望。
+ *
+ * 契约的用法：**改任何一处依赖，先改这个文件**，再改实现，再看测试红绿。测试会去
+ * `assets/swarm-rebuild.upstream.js` 里逐条核对下面的每个名字是否真的存在 —— 上游换人、
+ * 改名、删节点，这里第一个报错，而不是等某天浏览器里莫名其妙不播了。
+ *
+ * 法律面（别绕过它）：上游仓库根目录**没有 LICENSE**（默认保留所有权利），
+ * issue #12 至今零回复。所以这段资产**不能 fork 成"我们自己的版本"** —— fork 不改变授权，
+ * 只多出一份照样没有许可的副本。它只能留在本机自用、默认关闭、不随包分发。
+ */
+/** 上游出处与入仓指纹。这三项之外的任何东西，都不该成为插件的依赖。 */
+export const SWARM_UPSTREAM = {
+    /** 上游仓库。注意：根目录没有 LICENSE 文件。 */
+    repo: 'DhvanilPatel/swarm-cursors',
+    /** 入仓的那份原始文件（**未经补丁**）。diff 的基准。 */
+    vendoredFile: 'assets/swarm-rebuild.upstream.js',
+    /**
+     * 入仓时那份上游文件的 SHA-256。
+     * `scripts/swarm-patch.mjs` 的 `UPSTREAM_SHA256` 必须与它逐字符相同（测试会比对），
+     * 否则"补丁按哪一版写的"就说不清了。
+     */
+    sha256: '6a30f19daaa182d52673035feaeae775c398fa426655cc71a87a451fe00c7bfe',
+    /** 补丁后的产出（**随包分发的那份**）。 */
+    patchedFile: 'assets/swarm-rebuild.js',
+    /** 授权状态：`none` = 无许可证，默认保留所有权利。不是"宽松许可"。 */
+    license: 'none',
+};
+/**
+ * Tier A —— 硬接口。上游官方句柄树，补丁完全没碰，插件主路径全走这里。
+ *
+ * 事实依据（2026-11-10 在 `assets/swarm-rebuild.upstream.js` 里核对过）：
+ *   上游用 `const KEY = "__swarmRebuild"; window[KEY] = { toggle() {...}, stop(...) }` 暴露自己，
+ *   并把 `app`（engine / env / view / tour）挂在同一个对象上。这一段补丁一字未改。
+ */
+export const SWARM_API = {
+    /** 上游暴露自己的全局名。脚本第二次注入时会自己 `toggle()`。 */
+    global: '__swarmRebuild',
+    /** 句柄上的方法。 */
+    methods: {
+        toggle: 'toggle',
+        /**
+         * 停止。补丁后的脚本里 `stop(false)` = 立刻 destroy（取消 RAF、移除宿主），
+         * `stop(true)` = 淡出回真页面（原来 "Go live" 按钮走的路）。
+         * **插件一律用 `false`**：要的是立刻让路，不是让用户看淡出。
+         */
+        stop: 'stop',
+    },
+    /** `stop(reveal)` 的两种语义。 */
+    stopArgs: {
+        /** 立即销毁，不留残余覆盖层。插件用这个。 */
+        immediate: false,
+        /** 淡出到真页面。 */
+        reveal: true,
+    },
+    /** `window.__swarmRebuild.app` 上插件用到的字段。 */
+    app: {
+        /** 引擎：速度/启动都在这里。 */
+        engine: {
+            path: 'engine',
+            /** 速度，上游初值 `1`；上游 UI 的 `speeds = [1, 2, 3]`，按钮点 N 次即 1+N 倍。**可直接写。** */
+            speed: 'speed',
+            /** 启动引擎（`app.tour = true` 之后调它才真正开始往下滚）。 */
+            start: 'start',
+            /** 是否已启动。已是 `true` 就别再 `start()` 一遍。 */
+            started: 'started',
+        },
+        /** 环境探针：整页滚动 / 局部滚动（`overflow:auto` 容器）都靠它。 */
+        env: {
+            path: 'env',
+            /** `() => { ox, oy, sx, sy, vw, vh }`。局部滚动页里 `window.scrollY` 恒为 0，只有它知道真实位置。 */
+            geom: 'geom',
+            /** `(y, x) => void`，`behavior: 'instant'`。还原滚动位置用。 */
+            scrollTo: 'scrollTo',
+        },
+        /** 视图：影子树的入口。 */
+        view: {
+            path: 'view',
+            /** 影子树（上游以 `mode: 'open'` 创建）。 */
+            root: 'root',
+        },
+        /** 整页模式开关。上游 Tour 按钮只做两件事之一就是这个；补丁删了按钮，所以直接写字段。 */
+        tour: 'tour',
+    },
+    /** 句柄自身的影子树兜底（`app.view.root` 拿不到时用它）。 */
+    rootFallback: 'root',
+    /** 覆盖层的宿主元素：自定义元素标签，`document.querySelector` 可直接选到。 */
+    hostTag: 'swarm-rebuild',
+};
+/**
+ * Tier B —— 兜底口。上游原生，但**已被补丁删除**，插件只在"塞回了未打补丁的原版"时才用到。
+ *
+ * 2026-11-10 核对 `assets/swarm-rebuild.js`：`data-a=` 从上游的 11 处降到 2 处 ——
+ * 控制条整个被删（`scripts/swarm-patch.mjs` 第 1 处改动），剩下两处是
+ * `[data-a="sound"]`（有 `if (!b || !this.sfx)` 防护）和一处 `name` 拼接的通用选择器。
+ *
+ * **所以这一层不是主路径。** 主路径全在 Tier A。这里留着是为了：有人把未打补丁的原版
+ * 塞回 `assets/`，插件仍然能用（点按钮），而不是当场白屏。
+ */
+export const SWARM_DOM = {
+    /** 控制条容器。CSS 里定义：`.hud` / `.hud.on` / `.hud .dots` / `.hud .txt` / `.hud .status`。 */
+    hud: '.hud',
+    /** 头像组（控制条上的小圆点）。 */
+    dots: '.hud .dots',
+    /** 状态文字。 */
+    status: '.hud .status',
+    /** 进度条：`<div class="bar"><i></i></div>`。 */
+    barFill: '.hud .bar i',
+    /** 插件往影子树里插的隐藏规则所带的标记（重试时据此判断"已经插过了"）。 */
+    hideStyleAttr: 'data-dsh-swarm-hide',
+    /** 隐藏规则本体。用 CSSOM/内联 + 这条规则双层压住，重建的节点也一并压。 */
+    hideStyleText: '.hud{display:none!important}',
+    /**
+     * 控制条按钮。`selector` 是插件实际会用 `querySelector` 去点的那个字符串。
+     *
+     * `upstreamQuery` 标的是**另一件事**：上游自己的代码里有没有出现过这个选择器。
+     * 两者不等价，`close` 就是反例 —— 上游 HTML 里确实渲染了 `<button data-a="close" class="x">✕</button>`，
+     * 但它的代码从不 `querySelector('[data-a="close"]')`，点击走事件委托。
+     * 也就是说这一条是**我们自己声称有效**的选择器，靠的是 DOM 属性确实存在，而不是上游验证过。
+     * 上游哪天把 `data-a` 换成别的属性名、HTML 模板改了而代码没改（反之亦然），差别就在这里。
+     */
+    buttons: {
+        /** 整页自动滚动。插件不点它（改 `app.tour = true`），留着仅为完整性。上游有查询。 */
+        tour: { action: 'tour', selector: '[data-a="tour"]', upstreamQuery: true },
+        /** 帧速切换（1× → 2× → 3×）。插件直接写 `engine.speed`，不点它。上游有查询。 */
+        speed: { action: 'speed', selector: '[data-a="speed"]', upstreamQuery: true },
+        /** 声音开关（快捷键 M）。插件从不碰。上游有查询（带 `if (!b || !this.sfx)` 空值防护）。 */
+        sound: { action: 'sound', selector: '[data-a="sound"]', upstreamQuery: true },
+        /** Go live = `stop(true)`。兜底退出路径之一。上游有查询。 */
+        live: { action: 'live', selector: '[data-a="live"]', upstreamQuery: true },
+        /** 重播。插件从不碰。上游有查询。 */
+        replay: { action: 'replay', selector: '[data-a="replay"]', upstreamQuery: true },
+        /** ✕ = `stop(false)`。兜底退出路径之二。**上游不查询它**（事件委托），仅 HTML 属性存在。 */
+        close: { action: 'close', selector: '[data-a="close"]', upstreamQuery: false },
+    },
+    /** 退出时的兜底顺序：先 live 再 close（对应 `stop(true)` / `stop(false)`）。 */
+    exitFallbackOrder: ['[data-a="live"]', '[data-a="close"]'],
+};
+/**
+ * Tier C —— 自造桥。插件注入页面、上游永远不会提供的那些全局名。
+ *
+ * 上游改版跟这一层**无关**（它根本不认识这些名字）。这一层坏的原因通常是插件自己改了
+ * 注入时机、或者有人重构时漏了某个赋值 —— 所以它更需要测试，而不是文档。
+ */
+export const SWARM_BRIDGE = {
+    /** `() => void`，插件注入的"立刻退出"入口。**Tier A 的 `stop(false)` 走不通时才用。** */
+    stop: '__dshSwarmStop',
+    /** `{ x, y }`，播放前的滚动位置。局部滚动页由 `env.geom()` 覆盖掉 window 那份。 */
+    start: '__dshSwarmStart',
+    /** `true` = 引擎已在 `addInitScript` 阶段提前起来，**绝不能再注入第二遍**（否则白底和光标全部重来）。 */
+    early: '__dshSwarmEarly',
+    /** `true` = AI 已经在用这个页面，整页滚动循环看到它就停。 */
+    aiWorking: '__dshSwarmAiWorking',
+    /** `true` = 快照已经拿到手，可以放行扫描。`swarm-patch.mjs` 第 5 处改动等它。 */
+    go: '__dshSwarmGo',
+};
+/**
+ * 上游自带的诊断钩子。插件**不依赖**它们，列在这里是为了两件事：
+ *   ① 调试时知道这些名字是谁的，别误当成我们的桥；
+ *   ② 上游改版核对时，这些名字若消失，说明改动范围比预期大，值得警觉。
+ */
+export const SWARM_UPSTREAM_DEBUG_HOOKS = ['__swarmShot', '__swarmSfxLog', '__swarmHidden', '__swarmUnhide'];
+/**
+ * 上游改版应急流程。**这是"有据可依"的落点** —— 不是祈祷上游别改，而是改了好核对。
+ *
+ * 触发条件：把新的上游文件换进 `assets/swarm-rebuild.upstream.js`（这一步必须是人主动做的）。
+ * 本地日常开发**不需要**做任何事：vendored 文件不会自己变。
+ *
+ * 核对顺序（严格按此序，否则会追错方向）：
+ *   1. `npm run swarm:patch` —— SHA 不符会当场拒绝，并报出新旧两个哈希。**先看这一条。**
+ *   2. 按新哈希更新 `SWARM_UPSTREAM.sha256` 和 `scripts/swarm-patch.mjs` 的 `UPSTREAM_SHA256`
+ *      （两处必须一致，测试会比对）。
+ *   3. `node --test tests/swarm-contract.test.ts` —— 它会逐条到新文件里找 Tier A/B 的每个名字。
+ *      红的每一条，就是上游这次真动过的地方，一条一条处理。
+ *   4. 只有 Tier A 变红才是**必须改代码**的。Tier B 变红通常只需更新选择器（它只是兜底）。
+ *      Tier C 变红说明插件自己的桥出了问题，与上游无关。
+ *   5. 改完实现后，跑 `npm test` 全量 —— `swarm-intro.test.ts` 会用假 page 校验调用序列。
+ *   6. 最后更新 `docs/SWARM-CODE.md`（改了几处、为什么）和 `docs/SWARM-CONTRACT.md` 的指纹段。
+ */
+export const SWARM_UPGRADE_CHECKLIST = [
+    'npm run swarm:patch',
+    'sync SWARM_UPSTREAM.sha256 <-> scripts/swarm-patch.mjs UPSTREAM_SHA256',
+    'node --test tests/swarm-contract.test.ts',
+    'triage red: Tier A = code change, Tier B = selector update, Tier C = our own bug',
+    'npm test',
+    'update docs/SWARM-CODE.md + docs/SWARM-CONTRACT.md fingerprints',
+];

package/lib/swarm-curtain.d.ts

@@ -0,0 +1,22 @@
+import type { Page } from 'playwright-core';
+/**
+ * 生成注册进 `addInitScript` 的脚本全文。
+ *
+ * 必须用**字符串拼接**把资产塞进去，不能用模板字符串：资产里有大量反引号和
+ * `${...}`，放进外层模板字符串会被当成插值直接炸掉。
+ * 每次现读资产：和 playSwarm 里 `readScript()` 一样，改完磁盘立即用新的，不缓存。
+ */
+export declare function swarmBootScript(): string;
+/** 导航前打标记：下一次文档创建时，addInitScript 会把原版引擎提前启动。 */
+export declare function armCurtain(page: Page): Promise<void>;
+/** 清掉导航标记（导航失败时别让它留到下一次普通跳转）。 */
+export declare function clearCurtainToken(page: Page): Promise<void>;
+/**
+ * 决定"这一页不播"时：把可能已经提前启动的引擎彻底关掉。
+ *
+ * 这层原是"撤掉自造白幕"，现在没有白幕了 —— 引擎是真的、会一直等放行，所以必须
+ * 调它自己的 stop(false)、把宿主立刻摘掉、把滚动还原，否则那一页会永远盖着白。
+ * 触发场景：遮罩页不播、CSP 把影子树样式表挡成半成品、oncePerSite 判定跳过、
+ * 用户关掉特效等。顺手把标记和几个开关清干净，免得同文档内 toggle/replay 被旧值影响。
+ */
+export declare function dropCurtain(page: Page, _waitForSwarm?: boolean): Promise<void>;

package/lib/swarm-curtain.js

@@ -0,0 +1,115 @@
+/**
+ * 「同一个引擎」的提前启动：从打开网页的第一帧起，画面就是**原版特效自己**的
+ * 白底 + 18 个光标在转，全程只有这一套，不再有「自造白幕 → 切到原版」的交接断层。
+ *
+ * 做法：把随包的 `assets/swarm-rebuild.js`（原版引擎）整段塞进 `addInitScript`，
+ * 它在页面自己的脚本之前、<html> 一出现就启动（脚本里的"延后到 <html>"补丁见
+ * scripts/swarm-patch.mjs）。所以它比"打开页面→加载完→再注入"早得多，原页面
+ * 来不及露脸（用户 2026-11-09 最在意的那"一瞬间原画面"就此压住）。
+ *
+ * 只在真的要播的那次启动：导航前用 `window.name` 打标记（实测**跨域导航会保留**），
+ * addInitScript 读到标记才启动、并立刻清掉。三重保险防"残留标记误启动"：
+ *   · 只在顶层文档启动（`window.top === window`），iframe 不另起一套；
+ *   · 标记带时间戳，超过 30 秒的旧标记不认（导航失败后残留的那枚会自己过期）；
+ *   · 任何"不播"路径都调 dropCurtain，把 name 和引擎一起清干净。
+ * 万一标记没落到最终文档（少见的重定向），playSwarm 会检测到"引擎不在"并回退到
+ * 旧的"加载后注入"，功能仍可用，只是那一页会先露一下。
+ *
+ * 为什么不再自画 canvas 假光标：那是第二套引擎，和原版的光标参数再像也是两套，
+ * 交接必然"断一下、突然重新开始"（用户反复指出的缝）。用原版自己从第一帧登场，
+ * 缝就没了 —— 这正是用户 16:38 选过的「删掉自造的、用原版开场」，这次真正落地。
+ */
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/** 导航前写进 window.name 的标记：新文档第一帧读到它才启动引擎。 */
+const TOKEN = '__dsh_swarm__:';
+/**
+ * 生成注册进 `addInitScript` 的脚本全文。
+ *
+ * 必须用**字符串拼接**把资产塞进去，不能用模板字符串：资产里有大量反引号和
+ * `${...}`，放进外层模板字符串会被当成插值直接炸掉。
+ * 每次现读资产：和 playSwarm 里 `readScript()` 一样，改完磁盘立即用新的，不缓存。
+ */
+export function swarmBootScript() {
+    let asset;
+    try {
+        asset = fs.readFileSync(fileURLToPath(new URL('../assets/swarm-rebuild.js', import.meta.url)), 'utf8');
+    }
+    catch {
+        // 资产不在（0.8.0 起 assets/ 不再随 npm 包分发）。这里**绝不能往外抛**：
+        // 两个调用点都是 `await ctx.addInitScript({ content: swarmBootScript() })`，
+        // 抛出去就是上下文创建失败、浏览器直接打不开 —— 把"动效没了"放大成"插件挂了"。
+        // 返回一段空注释脚本，等于这次启动不注入任何东西，行为与"没开这个功能"一致。
+        return '/* dsh: swarm asset not shipped (0.8.0+) — nothing injected */\n';
+    }
+    return ('if (window.top === window && typeof window.name === "string" &&\n' +
+        '    window.name.indexOf("' +
+        TOKEN +
+        '") === 0 &&\n' +
+        '    Date.now() - Number(window.name.slice(' +
+        TOKEN.length +
+        ')) < 30000) {\n' +
+        '  window.name = "";\n' +
+        '  window.__dshSwarmEarly = true;\n' +
+        asset +
+        '\n}\n');
+}
+/** 导航前打标记：下一次文档创建时，addInitScript 会把原版引擎提前启动。 */
+export async function armCurtain(page) {
+    try {
+        await page.evaluate((token) => {
+            window.name = token;
+        }, TOKEN + Date.now());
+    }
+    catch {
+        /* 页面还没就绪（about:blank 之前），下一次导航照样会带标记 */
+    }
+}
+/** 清掉导航标记（导航失败时别让它留到下一次普通跳转）。 */
+export async function clearCurtainToken(page) {
+    try {
+        await page.evaluate(() => {
+            window.name = '';
+        });
+    }
+    catch {
+        /* 页面已经走了 */
+    }
+}
+/**
+ * 决定"这一页不播"时：把可能已经提前启动的引擎彻底关掉。
+ *
+ * 这层原是"撤掉自造白幕"，现在没有白幕了 —— 引擎是真的、会一直等放行，所以必须
+ * 调它自己的 stop(false)、把宿主立刻摘掉、把滚动还原，否则那一页会永远盖着白。
+ * 触发场景：遮罩页不播、CSP 把影子树样式表挡成半成品、oncePerSite 判定跳过、
+ * 用户关掉特效等。顺手把标记和几个开关清干净，免得同文档内 toggle/replay 被旧值影响。
+ */
+export async function dropCurtain(page, _waitForSwarm = false) {
+    try {
+        await page.evaluate(() => {
+            const w = window;
+            const api = w.__swarmRebuild;
+            if (api !== undefined && typeof api.stop === 'function')
+                api.stop(false);
+            // 还原滚动（提前启动的引擎在等放行、还没扫描，通常没滚过；保险起见照做）。
+            const start = w.__dshSwarmStart;
+            if (start !== undefined) {
+                const env = api?.app?.env;
+                if (env !== undefined && typeof env.scrollTo === 'function')
+                    env.scrollTo(start.y, start.x);
+                else
+                    window.scrollTo(start.x, start.y);
+                delete w.__dshSwarmStart;
+            }
+            // stop(false) 是延时移除，这里立刻摘，免得 AI 紧接着的点击命中测试被盖住。
+            for (const host of document.querySelectorAll('swarm-rebuild'))
+                host.remove();
+            w.name = '';
+            delete w.__dshSwarmEarly;
+            delete w.__dshSwarmGo;
+        });
+    }
+    catch {
+        /* 页面已经走了 */
+    }
+}

package/lib/swarm-intro.d.ts

@@ -0,0 +1,66 @@
+import type { Page } from 'playwright-core';
+/** 这个域名播过没有。跨所有活着的窗口判断。 */
+export declare function hasPlayed(host: string): boolean;
+/** 记下这个域名已经播过；ctx 传所属浏览器上下文，不传则用兜底。 */
+export declare function markPlayed(host: string, ctx?: object): void;
+/** 清空播放记录（设置卡上的「清空记录」用）：内存和磁盘一起清。 */
+export declare function resetPlayed(): void;
+/**
+ * 「一直记住」开关切换时调用：打开就把这趟已有记录立刻落盘（别等关窗，
+ * 免得宿主崩溃丢记录）；关掉就删掉磁盘记录，防止以后切回来时幽灵复活
+ * （2026-11-09 复核 find A）。这个文件是插件自己写的，删它不动用户数据。
+ */
+export declare function onPersistPlayedChanged(enabled: boolean): void;
+/**
+ * 某个浏览器上下文关掉时调用：只忘掉**它自己**那趟播过哪些站。
+ * 还有别的窗口活着时，别的窗口的记录一律保留（复核 find B）。
+ * persist 打开时把这趟记录落盘，下次接着记。
+ * 关单个标签不会走到这里 —— 那是 closeTab，不是 context 关闭。
+ */
+export declare function forgetOnBrowserClose(ctx?: object): void;
+/** 这个页面正在播吗。 */
+export declare function isPlaying(page: Page): boolean;
+/**
+ * 关掉正在播的特效。任何工具动作开始前都调用它 —— 覆盖层本身不接管鼠标
+ * （pointer-events: none），所以拦不住点击；但 AI 动手时它该让开，画面才
+ * 不会被人当成页面坏了。
+ *
+ * 失败一律吞掉：页面可能已经关掉、正在跳转，或者根本没播过。
+ */
+export declare function stopSwarm(page: Page): Promise<void>;
+/**
+ * 启动页。原来浏览器刚打开时停在 about:blank —— 一张纯白页，除了占位没有
+ * 任何用处，用户看见只会问「这是干嘛的」。这里换成一张说明卡：告诉人它已经
+ * 就绪、地址栏为什么是 about:blank、以及怎么用。没有外部资源，纯内联样式，
+ * 断网也是秒开。
+ */
+export declare const WELCOME_HTML = "<!doctype html><html lang=\"zh-CN\"><head><meta charset=\"utf-8\">\n<title>\u6D4F\u89C8\u5668\u5DF2\u5C31\u7EEA</title>\n<style>\n  :root { color-scheme: light; }\n  * { box-sizing: border-box; }\n  body {\n    margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;\n    background: #f5f6f8; color: #1d1d1f;\n    font: 15px/1.7 system-ui, -apple-system, \"Segoe UI\", \"Microsoft YaHei\", sans-serif;\n  }\n  .card {\n    width: min(560px, 86vw); padding: 38px 40px 34px; background: #fff; border-radius: 18px;\n    box-shadow: 0 1px 2px rgba(0,0,0,.04), 0 12px 40px rgba(0,0,0,.08);\n  }\n  .dot { width: 9px; height: 9px; border-radius: 50%; background: #34c759; display: inline-block; margin-right: 9px; vertical-align: middle; }\n  h1 { font-size: 23px; margin: 0 0 6px; letter-spacing: -.01em; }\n  .sub { color: #6b6b70; margin: 0 0 26px; }\n  .row { display: flex; gap: 12px; padding: 13px 0; border-top: 1px solid #ececf0; }\n  .k { color: #8a8a8f; min-width: 96px; font-size: 13px; }\n  .v { flex: 1; font-size: 14px; }\n  code { font-family: ui-monospace, Consolas, monospace; background: #f2f2f5; padding: 1px 6px; border-radius: 5px; font-size: 13px; }\n  .foot { margin: 24px 0 0; color: #9a9aa0; font-size: 12.5px; }\n</style></head><body>\n<div class=\"card\">\n  <h1><span class=\"dot\"></span>\u6D4F\u89C8\u5668\u5DF2\u5C31\u7EEA</h1>\n  <p class=\"sub\">\u60F3\u8BA9\u6211\u6253\u5F00\u54EA\u4E2A\u7F51\u7AD9\uFF0C\u8BF4\u4E00\u53E5\u5C31\u884C\u3002</p>\n  <div class=\"row\"><div class=\"k\">\u5730\u5740\u680F</div><div class=\"v\"><code>about:blank</code> \u2014\u2014 \u6D4F\u89C8\u5668\u5185\u7F6E\u7684\u7A7A\u767D\u9875\uFF0C\u8868\u793A\u8FD8\u6CA1\u53BB\u4EFB\u4F55\u7F51\u7AD9</div></div>\n  <div class=\"row\"><div class=\"k\">\u8FD9\u4E00\u9875</div><div class=\"v\">\u662F\u5149\u6807\u4E00\u7B14\u4E00\u7B14\u753B\u51FA\u6765\u7684\uFF0C\u6309 <code>Esc</code> \u53EF\u4EE5\u7ACB\u5373\u8DF3\u8FC7</div></div>\n  <div class=\"row\"><div class=\"k\">\u767B\u5F55\u72B6\u6001</div><div class=\"v\">\u4FDD\u5B58\u5728\u8FD9\u4E2A\u6D4F\u89C8\u5668\u91CC\uFF0C\u5173\u6389\u7A97\u53E3\u4E5F\u4E0D\u4F1A\u4E22</div></div>\n  <p class=\"foot\">\u7B2C\u4E00\u6B21\u6253\u5F00\u67D0\u4E2A\u7F51\u7AD9\u65F6\uFF0C\u90A3\u9875\u4E5F\u4F1A\u8FD9\u6837\u81EA\u5DF1\u957F\u51FA\u6765\u4E00\u6B21\u3002</p>\n</div></body></html>";
+/**
+ * 把空白页换成启动卡片，并在上面放一次特效。特效不等它播完（启动不能被
+ * 拖住 9 秒），放出去就返回；真有工具动作要执行时 stopSwarm 会先把它关掉。
+ */
+export declare function showWelcome(page: Page, config: {
+    swarm?: {
+        enabled?: boolean;
+        speed?: number;
+        maxMs?: number;
+    };
+} | undefined): Promise<void>;
+/**
+ * 这次导航要不要播（只看不费时的条件，用来决定"开场白幕"要不要提前挂）。
+ *
+ * 注意传的是**目标地址**：导航前的 `page.url()` 还是旧页面，拿它判断会永远不播。
+ * 遮罩页那种需要读页面的判断留到注入之后做，那时会顺手把白幕撤掉。
+ */
+export declare function willPlaySwarm(targetUrl: string, config: Parameters<typeof maybePlaySwarm>[1], headless?: boolean): boolean;
+/** 导航之后调用：够条件就播一次，不等它播完（导航照常立刻返回快照）。 */
+export declare function maybePlaySwarm(page: Page, config: {
+    swarm?: {
+        enabled?: boolean;
+        oncePerSite?: boolean;
+        speed?: number;
+        maxMs?: number;
+        playOnVeiled?: boolean;
+        range?: 'viewport' | 'page';
+    };
+} | undefined, headless?: boolean): void;