dsh-browser-playwright-codex 0.7.8 → 0.8.0

package/lib/config.d.ts

@@ -41,6 +41,32 @@ export interface PlaywrightConfig {
         /** Incremental ref-diff mode; false = always full snapshots (zero behavioral change). */
         diff: boolean;
     };
+    /**
+     * 进场特效：把一个页面抹白，再用一群光标把它重新画出来。
+     *
+     * 可选：老配置对象里没有这一节时，由 Schemastery 的 Config 补齐默认值
+     * （见下面的 `swarm: z.object(...).default(...)`）。做成可选是为了让手写的
+     * 测试配置、以及旧部署的 patch 层都能直接通过类型检查。
+     */
+    swarm?: {
+        /** 出厂就开着：这是装完就能看见的那一下「哇」。设置卡上的开关可以随时关掉。 */
+        enabled: boolean;
+        /** 只在某个网站第一次打开时播；false = 每次导航都播（不建议）。 */
+        oncePerSite: boolean;
+        /** 播放速度档位 1–3（3 最快）。 */
+        speed: number;
+        /** 最多播多久（毫秒）。0 = 不限制，完整播完。 */
+        maxMs: number;
+        /** 遮罩页面（登录墙、密码框）也播。默认关：会把没解锁的内容画出来。 */
+        playOnVeiled: boolean;
+        /** 一直记住播过哪些站：关掉整个浏览器窗口也不重播。默认关（关窗就重播）。 */
+        persistPlayed: boolean;
+        /**
+         * 播放范围：`viewport` = 只画当前这一屏（默认，1–10 秒结束）；
+         * `page` = 由插件按节奏往下滚，一屏一屏把整页画完（会接管滚动，时间长得多）。
+         */
+        range: 'viewport' | 'page';
+    };
 }
 /** Bounded page data the extraction consumer feeds to a model. */
 export interface PageData {

package/lib/config.js

@@ -45,6 +45,26 @@ export const Config = z.object({
         diff: z.boolean().default(false),
     })
         .default({ engine: 'legacy', maxNodes: 500, maxNameLength: 120, maxTextLength: 300, diff: false }),
+    swarm: z
+        .object({
+        // 出厂关：动效资产不再随 npm 包分发（0.8.0 起），默认开会让每个新用户
+        // 在"文件根本不存在"的状态下开箱报错。想要的人把资产放回 assets/ 再打开。
+        enabled: z.boolean().default(false),
+        // 只在每个网站第一次打开时播，避免每次导航都把页面盖住。
+        oncePerSite: z.boolean().default(true),
+        // 1–3 档，脚本里对应点几次速度按钮。
+        speed: z.number().default(3),
+        // 硬上限：到点无条件退回真实页面。原版脚本在长页面上要约 12 秒，留 15 秒。
+        maxMs: z.number().default(15000),
+        // 默认关：遮罩后面的内容没解锁就不该被画出来。自己的面板想看可以打开。
+        playOnVeiled: z.boolean().default(false),
+        // 默认关：整个浏览器窗口一关就忘掉这趟播过哪些站，下次重开全部重播。
+        persistPlayed: z.boolean().default(false),
+        // 只画首屏：长页面不动，短页面也不会卡在"下半页永远等不到"。想看整页的人
+        // 到设置卡选「整页」——那会把滚动接过去几秒，所以不做默认。
+        range: z.union([z.const('viewport'), z.const('page')]).default('viewport'),
+    })
+        .default({ enabled: false, oncePerSite: true, speed: 3, maxMs: 15000, playOnVeiled: false, persistPlayed: false }),
 });
 /** Channels probed in order when none is configured. */
 export const AUTO_CHANNELS = ['chromium', 'chrome', 'msedge', 'edge'];

package/lib/page-actions.js

@@ -9,6 +9,8 @@ import { assertAllowedUrl } from "./url-policy.js";
 import { asTimeoutError, isAbortError } from "./page-diagnostics.js";
 import { clearLabelTargets, labelTargetProbe } from "./page-probes.js";
 import { createBackgroundPage, isWindowMinimized } from "./window-focus.js";
+import { maybePlaySwarm, stopSwarm, willPlaySwarm } from "./swarm-intro.js";
+import { armCurtain, clearCurtainToken } from "./swarm-curtain.js";
 /** Wrap a Playwright op so an aborted signal rejects while the op keeps draining in the background. */
 export async function withAbort(promise, signal) {
     // Attach handlers FIRST: the caller's promise may still be draining (a
@@ -99,6 +101,10 @@ export async function runAction(session, page, action) {
     const already = session.provider.pendingDialogFor(page);
     if (already !== undefined)
         return { blocked: true, pending: already };
+    // 进场特效运行时页面最上层盖着覆盖层。它不接管鼠标（pointer-events:none），
+    // 拦不住点击，但 AI 动手时它该让开。放在对话框检查之后：页面被原生对话框
+    // 卡住时 evaluate 会一直挂着，那会把整个动作拖死，所以还加了个 300ms 上限。
+    await Promise.race([stopSwarm(page), new Promise((resolve) => setTimeout(resolve, 300))]);
     const wait = session.provider.armDialogWait(page);
     const outcome = action().then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
     const winner = await Promise.race([outcome, wait.promise]);
@@ -113,12 +119,20 @@ export async function navigate(session, url, waitUntil, signal) {
     return session.run(async () => {
         const target = assertAllowedUrl(url, session.provider.config.allowedDomains ?? []);
         const page = await session.ensurePage();
+        // 提前启动要在导航**之前**打标记：addInitScript 读到它，就在页面脚本之前把
+        // 原版引擎拉起来（白底 + 18 个光标从第一帧就在），原页面不会闪出来。
+        if (willPlaySwarm(target.toString(), session.provider.config, session.provider.desiredHeadless())) {
+            await armCurtain(page);
+        }
         try {
             const racedNav = await session.runAction(page, () => withAbort(page.goto(target.toString(), { waitUntil, timeout: session.timeoutMs() }), signal));
             if (racedNav.blocked)
                 return session.blockedSnapshot(page, racedNav.pending);
         }
         catch (error) {
+            // 导航没走成：标记还留在 window.name 里，而它跨导航保留。不清掉的话，
+            // 下一次普通跳转会意外提前启动引擎（2026-11-09 复核 find B）。
+            await clearCurtainToken(page);
             if (isAbortError(error) || signal?.aborted === true)
                 throw error;
             // A redirect chain can leave the allow-list: the guard refuses the hop and
@@ -126,7 +140,24 @@ export async function navigate(session, url, waitUntil, signal) {
             session.throwIfNavigationBlocked();
             throw asTimeoutError('navigation', error);
         }
-        return session.settleAndSnapshot(page, true);
+        // **先放特效、再拍快照**：原版开场本身就是"页面被抹白 + 光标从两边飞进来打转"，
+        // 让它立刻登场，用户就不会先看见网页、过一会儿才播动画（2026-11-09 用户的判断：
+        // 与其自己做一套过场，不如用原版那一套）。资产里"扫描页面"那一步被改成等放行信号，
+        // 所以拍快照期间页面不会被它滚走；快照拍完再放行。
+        maybePlaySwarm(page, session.provider.config, session.provider.desiredHeadless());
+        // 放行必须放 finally：快照阶段抛错、被原生弹窗拦住、导航被拒，都不能把页面
+        // 一直扣在白幕下等满 5 秒兜底（2026-11-09 复核建议 1）。
+        try {
+            return await session.settleAndSnapshot(page, true);
+        }
+        finally {
+            await page
+                .evaluate(() => {
+                ;
+                window.__dshSwarmGo = true;
+            })
+                .catch(() => { });
+        }
     });
 }
 /**

package/lib/provider.js

@@ -13,6 +13,8 @@ import { PlaywrightSession } from "./session.js";
 import { getEffectiveHeadless, getEnabled, publishConfiguredEngine, publishLoginSites } from "./runtime-state.js";
 import { BrowserError } from "./errors.js";
 import { SNAPSHOT_SCRIPT } from "./injected.js";
+import { swarmBootScript } from "./swarm-curtain.js";
+import { forgetOnBrowserClose } from "./swarm-intro.js";
 import { isWindowMinimized } from "./window-focus.js";
 import { installHostGuard } from "./navigation-guard.js";
 export class PlaywrightProvider {
@@ -267,11 +269,17 @@ export class PlaywrightProvider {
         // Allow-list on the wire, not just at the entry points (navigation-guard.ts).
         await this.installHostGuard(context);
         await context.addInitScript(SNAPSHOT_SCRIPT);
+        // 提前启动「同一个引擎」：只有导航前打了标记的那次才在页面脚本之前启动原版特效
+        // （白底 + 18 个光标从第一帧就在），没标记的普通导航不会白闪。见 swarm-curtain.ts。
+        await context.addInitScript({ content: swarmBootScript() });
         const session = new PlaywrightSession(this, owner, context);
         const entry = { context, session, lastUsed: Date.now(), pending: 0, timer: undefined };
         this.entries.set(owner, entry);
         this.armIdle(entry);
         void context.on('close', () => {
+            // 这个浏览器上下文关掉：默认只忘掉它自己那趟播过哪些站。
+            // 别的窗口还开着时不清它们的记录（2026-11-09 复核 find B）。
+            forgetOnBrowserClose(context);
             if (this.entries.get(owner) === entry) {
                 if (entry.timer !== undefined)
                     clearTimeout(entry.timer);

package/lib/read-deadline.d.ts

@@ -10,8 +10,12 @@ import { isAbortError } from './page-diagnostics.ts';
  * @param timeoutMs - 硬期限（毫秒），应来自部署配置，且已校验有下限
  * @param label - 超时消息里说明卡在哪一步
  * @param signal - 可选的取消信号
+ * @param onTimeout - `reject` 抛 `ACTION_TIMEOUT`；`resolve-undefined` 供可降级场景
+ * @param consequence - 超时之后**实际发生了什么**。必须写真的后果：这里只报超时，
+ *   后续清理由调用方负责，别在这里替它许诺「下次会重开会话」——0.7.9 的超时消息
+ *   就写着这句，而实际做的是把那一页关掉，用户看到标签页凭空少了一个却没人告诉他。
  */
-export declare function withDeadline<T>(promise: Promise<T>, timeoutMs: number, label: string, signal?: AbortSignal, onTimeout?: 'reject' | 'resolve-undefined'): Promise<T | undefined>;
+export declare function withDeadline<T>(promise: Promise<T>, timeoutMs: number, label: string, signal?: AbortSignal, onTimeout?: 'reject' | 'resolve-undefined', consequence?: string): Promise<T | undefined>;
 /** 这个错误是不是「读内容超时」——调用方据此作废会话句柄，让下次自愈。 */
 export declare function isReadTimeout(error: unknown): boolean;
 /** 取消错误保持原样传递（不多包一层）。 */

package/lib/read-deadline.js

@@ -26,8 +26,12 @@ import { isAbortError } from "./page-diagnostics.js";
  * @param timeoutMs - 硬期限（毫秒），应来自部署配置，且已校验有下限
  * @param label - 超时消息里说明卡在哪一步
  * @param signal - 可选的取消信号
+ * @param onTimeout - `reject` 抛 `ACTION_TIMEOUT`；`resolve-undefined` 供可降级场景
+ * @param consequence - 超时之后**实际发生了什么**。必须写真的后果：这里只报超时，
+ *   后续清理由调用方负责，别在这里替它许诺「下次会重开会话」——0.7.9 的超时消息
+ *   就写着这句，而实际做的是把那一页关掉，用户看到标签页凭空少了一个却没人告诉他。
  */
-export async function withDeadline(promise, timeoutMs, label, signal, onTimeout = 'reject') {
+export async function withDeadline(promise, timeoutMs, label, signal, onTimeout = 'reject', consequence = 'The call was abandoned; the page may still be running its script.') {
     const guarded = Promise.resolve(promise);
     guarded.catch(() => { }); // 超时后原调用仍在跑：别让它的 rejection 冒到宿主
     return new Promise((resolve, reject) => {
@@ -50,9 +54,12 @@ export async function withDeadline(promise, timeoutMs, label, signal, onTimeout
                 label +
                 ' did not finish within ' +
                 String(timeoutMs) +
-                'ms; the page may be stuck running script. The next browser call reopens the session.')));
+                'ms; the page may be stuck running script. ' +
+                consequence)));
         }, timeoutMs);
-        timer.unref?.();
+        // 不要 unref：期限是「到点必须断」的承诺，unref 之后若这是进程里最后一个句柄，
+        // 事件循环会判定无事可做直接退出，调用方永远等不到这条 ACTION_TIMEOUT
+        // （tests/read-deadline.test.ts 就是这么被打成 cancelledByParent 的）。
         if (signal !== undefined && typeof signal.addEventListener === 'function') {
             if (signal.aborted)
                 onAbort();

package/lib/runtime-state.d.ts

@@ -27,6 +27,20 @@
 import type { LoginSites } from './login-sites.ts';
 /** How a page is read into a snapshot tree. */
 export type SnapshotEngine = 'legacy' | 'aria';
+/** 进场特效的播放参数（速度/时长/是否只播一次），只存用户改过的项。 */
+export interface SwarmTuning {
+    speed?: number;
+    maxMs?: number;
+    oncePerSite?: boolean;
+    /** 遮罩页面（登录墙、密码框）也播。默认关：会把没解锁的内容画出来。 */
+    playOnVeiled?: boolean;
+    /** AI 要动手时怎么办：'auto-close' = 立刻关掉动画（默认）；'keep-alive' = 动画继续但不挡点击。 */
+    whileAiWorks?: 'auto-close' | 'keep-alive';
+    /** 播放范围：只画首屏 / 整页（由插件接管滚动，一屏一屏画完）。 */
+    range?: 'viewport' | 'page';
+    /** 一直记住播过哪些站：关掉整个浏览器窗口也不重播。默认关（关窗就重播）。 */
+    persistPlayed?: boolean;
+}
 /** Current enable state (loads from disk on first call). */
 export declare function getEnabled(): boolean;
 /** Set the enable state. Returns true if the value actually changed. */
@@ -40,6 +54,18 @@ export declare function subscribe(fn: (enabled: boolean) => void): () => void;
 export declare function getHeadless(): boolean | undefined;
 /** Persist the window-mode choice. Returns true when the value changed. */
 export declare function setHeadless(next: boolean): boolean;
+/**
+ * 进场特效的开关：用户自己选过的值，没选过返回 undefined（由配置默认值说话）。
+ */
+export declare function getSwarm(): boolean | undefined;
+/** 记下用户对进场特效的选择。Returns true when the value changed. */
+export declare function setSwarm(next: boolean): boolean;
+/** 用户自己选过吗？（设置卡用来区分「你选的」和「默认的」。） */
+export declare function isSwarmUserChosen(): boolean;
+/** 播放参数：只含用户改过的项，其余跟配置默认值。 */
+export declare function getSwarmTuning(): SwarmTuning;
+/** 改播放参数（只传要改的项）。Returns true when something changed. */
+export declare function setSwarmTuning(patch: SwarmTuning): boolean;
 /** Publish the configured default (launch.headless) for display. */
 export declare function publishConfiguredHeadless(value: boolean): void;
 /** The configured default, when the provider has published it. */

package/lib/runtime-state.js

@@ -14,6 +14,9 @@ let _enabled = true;
 let _engine = undefined;
 /** User's window-mode choice: true = headless, undefined = follow the config. */
 let _headless = undefined;
+/** 进场特效的开关：true/false = 用户自己选的，undefined = 跟配置的默认值。 */
+let _swarm = undefined;
+let _swarmTuning = undefined;
 /** Config default pushed in by the provider (display only). */
 let _configuredHeadless = undefined;
 /** Default pushed in by the provider that is actually loaded (display only). */
@@ -40,6 +43,31 @@ function load() {
             // Same contract as engine: absent/unknown means "follow the configured
             // default", so files written before this setting existed stay valid.
             _headless = typeof obj.headless === 'boolean' ? obj.headless : undefined;
+            // 同一个约定：没写过或值不认识 = 跟配置默认值，老状态文件照样有效。
+            _swarm = typeof obj.swarm === 'boolean' ? obj.swarm : undefined;
+            const tuning = obj.swarmTuning;
+            if (tuning !== undefined && tuning !== null && typeof tuning === 'object') {
+                // 只收认识的项；缺的项不写，读的时候自然落回配置默认值。
+                const next = {};
+                if (typeof tuning.speed === 'number')
+                    next.speed = tuning.speed;
+                if (typeof tuning.maxMs === 'number')
+                    next.maxMs = tuning.maxMs;
+                if (typeof tuning.oncePerSite === 'boolean')
+                    next.oncePerSite = tuning.oncePerSite;
+                if (typeof tuning.playOnVeiled === 'boolean')
+                    next.playOnVeiled = tuning.playOnVeiled;
+                if (tuning.whileAiWorks === 'auto-close' || tuning.whileAiWorks === 'keep-alive')
+                    next.whileAiWorks = tuning.whileAiWorks;
+                if (tuning.range === 'viewport' || tuning.range === 'page')
+                    next.range = tuning.range;
+                if (typeof tuning.persistPlayed === 'boolean')
+                    next.persistPlayed = tuning.persistPlayed;
+                _swarmTuning = next;
+            }
+            else {
+                _swarmTuning = undefined;
+            }
         }
     }
     catch {
@@ -69,6 +97,10 @@ function persist() {
         const payload = _engine === undefined ? { enabled: _enabled } : { enabled: _enabled, engine: _engine };
         if (_headless !== undefined)
             payload.headless = _headless;
+        if (_swarm !== undefined)
+            payload.swarm = _swarm;
+        if (_swarmTuning !== undefined)
+            payload.swarmTuning = _swarmTuning;
         fs.writeFileSync(tmp, JSON.stringify(payload, null, 2));
         fs.renameSync(tmp, target);
     }
@@ -127,6 +159,74 @@ export function setHeadless(next) {
     persist();
     return true;
 }
+/**
+ * 进场特效的开关：用户自己选过的值，没选过返回 undefined（由配置默认值说话）。
+ */
+export function getSwarm() {
+    load();
+    return _swarm;
+}
+/** 记下用户对进场特效的选择。Returns true when the value changed. */
+export function setSwarm(next) {
+    load();
+    if (typeof next !== 'boolean')
+        return false;
+    if (_swarm === next)
+        return false;
+    _swarm = next;
+    persist();
+    return true;
+}
+/** 用户自己选过吗？（设置卡用来区分「你选的」和「默认的」。） */
+export function isSwarmUserChosen() {
+    load();
+    return _swarm !== undefined;
+}
+/** 播放参数：只含用户改过的项，其余跟配置默认值。 */
+export function getSwarmTuning() {
+    load();
+    return _swarmTuning ?? {};
+}
+/** 改播放参数（只传要改的项）。Returns true when something changed. */
+export function setSwarmTuning(patch) {
+    load();
+    const next = { ...(_swarmTuning ?? {}) };
+    let changed = false;
+    if (typeof patch.speed === 'number' && next.speed !== patch.speed) {
+        next.speed = patch.speed;
+        changed = true;
+    }
+    if (typeof patch.maxMs === 'number' && next.maxMs !== patch.maxMs) {
+        next.maxMs = patch.maxMs;
+        changed = true;
+    }
+    if (typeof patch.oncePerSite === 'boolean' && next.oncePerSite !== patch.oncePerSite) {
+        next.oncePerSite = patch.oncePerSite;
+        changed = true;
+    }
+    if (typeof patch.playOnVeiled === 'boolean' && next.playOnVeiled !== patch.playOnVeiled) {
+        next.playOnVeiled = patch.playOnVeiled;
+        changed = true;
+    }
+    if ((patch.whileAiWorks === 'auto-close' || patch.whileAiWorks === 'keep-alive') &&
+        next.whileAiWorks !== patch.whileAiWorks) {
+        next.whileAiWorks = patch.whileAiWorks;
+        changed = true;
+    }
+    if ((patch.range === 'viewport' || patch.range === 'page') && next.range !== patch.range) {
+        next.range = patch.range;
+        changed = true;
+    }
+    if (typeof patch.persistPlayed === 'boolean' && next.persistPlayed !== patch.persistPlayed) {
+        next.persistPlayed = patch.persistPlayed;
+        changed = true;
+    }
+    if (!changed)
+        return false;
+    _swarmTuning = next;
+    persist();
+    return true;
+}
 /** Publish the configured default (launch.headless) for display. */
 export function publishConfiguredHeadless(value) {
     _configuredHeadless = value === true;

package/lib/session.d.ts

@@ -149,6 +149,17 @@ export declare class PlaywrightSession {
     capture(page: Page, opts: {
         interactiveOnly?: boolean;
     } | undefined, afterAction?: boolean): Promise<BrowserSnapshot>;
+    /**
+     * Close one page whose script has stopped answering, so the next acquire starts
+     * on a live tab instead of inheriting it. Bounded and best-effort: main thread
+     * wedged badly enough to stall an evaluate may never answer close either, and
+     * this runs on the error path — it must never turn a timeout into a second hang.
+     *
+     * 代价要说清楚：`runBeforeUnload:false` 意味着**不弹**「确定要离开吗」，所以页面上
+     * 填了一半的表单、没提交的内容直接丢弃；如果那是唯一一个标签，接下来是一张空白页。
+     * 对真卡死的页这笔账划算，但用户必须被告知——所以 capture() 的报错文案里写明这件事。
+     */
+    private discardStuckPage;
     /**
      * Semantic-tree capture via Playwright's official ariaSnapshot(mode:'ai').
      * An unavailable or unreadable aria tree (`missing`) degrades to the legacy

package/lib/session.js

@@ -327,19 +327,42 @@ export class PlaywrightSession {
             return this.attachDiff(attachNoProgress(this, attachDocResponse(this, page, raw), afterAction));
         };
         try {
-            const snap = await withDeadline(read(), this.timeoutMs(), 'reading the page content', this.currentSignal);
+            const snap = await withDeadline(read(), this.timeoutMs(), 'reading the page content', this.currentSignal, 'reject', 
+            // 报错文案必须说人话、说真话：这一页真的被关掉了，页面里没提交的东西跟着没了。
+            // 关页不弹 beforeunload（弹了可能又卡死），所以用户只有从这条消息里才知道。
+            'That page has been closed; anything typed into it but not submitted is lost, and if it was the last tab the session now starts on a blank page.');
             return snap;
         }
         catch (error) {
             // 超时只能让我们这一侧返回，页面里那个 evaluate 还在跑。作废会话句柄，
-            // 下一次调用会重新拿到干净窗口，而不是继承这个卡住的页面。
+            // 再把那张卡死的页面真正关掉——否则持久化模式下 ensurePage() 会把同一个
+            // 页面交还给下一次调用，所谓「自愈」只是换了个句柄继续超时（issue #5）。
             if (isReadTimeout(error)) {
                 this.closed = true;
                 this.provider.invalidateOwner(this.owner);
+                await this.discardStuckPage(page);
             }
             throw error;
         }
     }
+    /**
+     * Close one page whose script has stopped answering, so the next acquire starts
+     * on a live tab instead of inheriting it. Bounded and best-effort: main thread
+     * wedged badly enough to stall an evaluate may never answer close either, and
+     * this runs on the error path — it must never turn a timeout into a second hang.
+     *
+     * 代价要说清楚：`runBeforeUnload:false` 意味着**不弹**「确定要离开吗」，所以页面上
+     * 填了一半的表单、没提交的内容直接丢弃；如果那是唯一一个标签，接下来是一张空白页。
+     * 对真卡死的页这笔账划算，但用户必须被告知——所以 capture() 的报错文案里写明这件事。
+     */
+    async discardStuckPage(page) {
+        try {
+            await withDeadline(page.close({ runBeforeUnload: false }), 2_000, 'closing the stuck page', undefined, 'resolve-undefined');
+        }
+        catch {
+            /* already gone, or too wedged to close: nothing better we can do */
+        }
+    }
     /**
      * Semantic-tree capture via Playwright's official ariaSnapshot(mode:'ai').
      * An unavailable or unreadable aria tree (`missing`) degrades to the legacy

package/lib/settings-card.js

@@ -63,6 +63,7 @@ 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 { onPersistPlayedChanged, resetPlayed } from "./swarm-intro.js";
 import { readFileSync } from 'node:fs';
 import { clean, isTargetId, resolvePaths, scan } from "./cache-clean.js";
 const { getEnabled, setEnabled, getEffectiveEngine, setSnapshotEngine, isEngineUserChosen } = runtimeState;
@@ -238,9 +239,119 @@ function registerWindowRoute(ctx) {
         },
     }));
 }
+/**
+ * POST /swarm { enabled } — 进场特效的开关。
+ *
+ * 只是用户在设置卡上的选择，落盘后立刻生效：下一次导航就会按新值决定播不播，
+ * 不用重启，也不用断开已经开着的窗口。
+ */
+function registerSwarmRoute(ctx) {
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: PREFIX + '/swarm',
+        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 (payload.enabled !== undefined && typeof payload.enabled !== 'boolean')
+                return sendJson(res, 400, { error: { code: 'INVALID_BODY', message: '`enabled` must be a boolean' } });
+            // 清空播放记录：打开开关之后想让每个网站重新播一遍，就顺手清一下。
+            const reset = payload.resetPlayed === true;
+            if (reset) {
+                try {
+                    resetPlayed();
+                }
+                catch {
+                    /* 文件不存在就是已经清过了 */
+                }
+            }
+            let changed = false;
+            if (typeof payload.enabled === 'boolean')
+                changed = runtimeState.setSwarm(payload.enabled) || changed;
+            // 播放参数：速度 1–3；时长 0（完整播完）或 3000–30000 毫秒；是否每站只播一次。
+            const patch = {};
+            if (payload.speed !== undefined) {
+                const speed = Number(payload.speed);
+                if (!Number.isFinite(speed) || speed < 1 || speed > 3)
+                    return sendJson(res, 400, { error: { code: 'INVALID_BODY', message: '`speed` must be 1–3' } });
+                patch.speed = Math.round(speed);
+            }
+            if (payload.maxMs !== undefined) {
+                const maxMs = Number(payload.maxMs);
+                if (!Number.isFinite(maxMs) || (maxMs !== 0 && (maxMs < 3000 || maxMs > 30000)))
+                    return sendJson(res, 400, {
+                        error: { code: 'INVALID_BODY', message: '`maxMs` must be 0 or 3000–30000' },
+                    });
+                patch.maxMs = Math.round(maxMs);
+            }
+            if (payload.oncePerSite !== undefined) {
+                if (typeof payload.oncePerSite !== 'boolean')
+                    return sendJson(res, 400, { error: { code: 'INVALID_BODY', message: '`oncePerSite` must be a boolean' } });
+                patch.oncePerSite = payload.oncePerSite;
+            }
+            if (payload.playOnVeiled !== undefined) {
+                if (typeof payload.playOnVeiled !== 'boolean')
+                    return sendJson(res, 400, { error: { code: 'INVALID_BODY', message: '`playOnVeiled` must be a boolean' } });
+                patch.playOnVeiled = payload.playOnVeiled;
+            }
+            if (payload.whileAiWorks !== undefined) {
+                if (payload.whileAiWorks !== 'auto-close' && payload.whileAiWorks !== 'keep-alive')
+                    return sendJson(res, 400, {
+                        error: { code: 'INVALID_BODY', message: '`whileAiWorks` must be auto-close or keep-alive' },
+                    });
+                patch.whileAiWorks = payload.whileAiWorks;
+            }
+            if (payload.range !== undefined) {
+                if (payload.range !== 'viewport' && payload.range !== 'page')
+                    return sendJson(res, 400, {
+                        error: { code: 'INVALID_BODY', message: '`range` must be viewport or page' },
+                    });
+                patch.range = payload.range;
+            }
+            if (payload.persistPlayed !== undefined) {
+                if (typeof payload.persistPlayed !== 'boolean')
+                    return sendJson(res, 400, { error: { code: 'INVALID_BODY', message: '`persistPlayed` must be a boolean' } });
+                patch.persistPlayed = payload.persistPlayed;
+            }
+            const wasPersist = runtimeState.getSwarmTuning().persistPlayed === true;
+            if (Object.keys(patch).length > 0)
+                changed = runtimeState.setSwarmTuning(patch) || changed;
+            // 开关真的翻了才动记录：打开立刻把这趟落盘，关掉删盘（防幽灵复活）。
+            const nowPersist = runtimeState.getSwarmTuning().persistPlayed === true;
+            if (nowPersist !== wasPersist)
+                onPersistPlayedChanged(nowPersist);
+            const tuning = runtimeState.getSwarmTuning();
+            sendJson(res, 200, {
+                swarm: runtimeState.getSwarm(),
+                swarmSpeed: tuning.speed ?? null,
+                swarmMaxMs: tuning.maxMs ?? null,
+                swarmOncePerSite: tuning.oncePerSite ?? null,
+                swarmPlayOnVeiled: tuning.playOnVeiled ?? null,
+                swarmWhileAiWorks: tuning.whileAiWorks ?? null,
+                swarmRange: tuning.range ?? null,
+                swarmPersistPlayed: tuning.persistPlayed ?? null,
+                changed,
+                resetPlayed: reset,
+                appliedOn: 'next-navigation',
+            });
+        },
+    }));
+}
 export function apply(ctx) {
     registerDiskRoutes(ctx);
     registerWindowRoute(ctx);
+    registerSwarmRoute(ctx);
     ctx.effect(() => ctx.webServer.register({
         kind: 'exact',
         path: `${PREFIX}/state`,
@@ -265,6 +376,18 @@ export function apply(ctx) {
                 headless: runtimeState.getEffectiveHeadless(),
                 headlessUserChosen: runtimeState.isHeadlessUserChosen(),
                 headlessConfigured: runtimeState.getConfiguredHeadless(),
+                // 进场特效：null = 用户没表态，跟配置默认（出厂开）。
+                swarm: runtimeState.getSwarm() ?? null,
+                swarmUserChosen: runtimeState.isSwarmUserChosen(),
+                // 播放参数：undefined = 跟配置默认（3× / 15 秒 / 每站一次）。
+                swarmSpeed: runtimeState.getSwarmTuning().speed ?? null,
+                swarmMaxMs: runtimeState.getSwarmTuning().maxMs ?? null,
+                swarmOncePerSite: runtimeState.getSwarmTuning().oncePerSite ?? null,
+                // null = 跟配置默认（遮罩不播 / AI 动手时自动关闭动画）。
+                swarmPlayOnVeiled: runtimeState.getSwarmTuning().playOnVeiled ?? null,
+                swarmWhileAiWorks: runtimeState.getSwarmTuning().whileAiWorks ?? null,
+                swarmRange: runtimeState.getSwarmTuning().range ?? null,
+                swarmPersistPlayed: runtimeState.getSwarmTuning().persistPlayed ?? null,
                 // 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,