dsh-browser-playwright-codex 0.7.7 → 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

@@ -22,7 +22,10 @@ export const Config = z.object({
         viewport: z
             .object({ width: z.number().default(1280), height: z.number().default(800) })
             .default({ width: 1280, height: 800 }),
-        navigationTimeoutMs: z.number().default(30000),
+        // 0 used to be accepted, and Playwright reads timeout: 0 as "no timeout",
+        // so a stuck page could hang the tool forever (issue #5). Require at least
+        // one second; the default stays 30s.
+        navigationTimeoutMs: z.number().min(1000).default(30000),
         ignoreHTTPSErrors: z.boolean().default(false),
     }),
     allowedDomains: z.array(z.string()),
@@ -42,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

@@ -0,0 +1,22 @@
+import { isAbortError } from './page-diagnostics.ts';
+/**
+ * 让一个可能挂住的 Promise 同时响应「到点」和「取消」。
+ *
+ * - 到点：抛 `ACTION_TIMEOUT`，消息里带上限和这一步在做什么，模型/用户能看懂。
+ * - 取消：原样抛 `AbortError`，和工具层其它取消行为一致。
+ * - 原始 Promise 无论多晚才 settle，都不会变成未捕获的 rejection（和 withAbort 同规矩）。
+ *
+ * @param promise - 可能挂住的调用
+ * @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', consequence?: string): Promise<T | undefined>;
+/** 这个错误是不是「读内容超时」——调用方据此作废会话句柄，让下次自愈。 */
+export declare function isReadTimeout(error: unknown): boolean;
+/** 取消错误保持原样传递（不多包一层）。 */
+export { isAbortError };

package/lib/read-deadline.js

@@ -0,0 +1,77 @@
+/**
+ * 给「读页面内容」这类**可能永远不返回**的调用加一道硬期限。
+ *
+ * 为什么需要它：Playwright 的 `page.evaluate` / `ariaSnapshot` 没有 timeout 参数。
+ * 页面脚本一旦占住主线程（着色器编译、同步重绘循环、死循环），这些调用会一直
+ * 挂着，工具调用、甚至整个对话就卡死在那里（GitHub issue #5：报告人卡了 12 分钟）。
+ * `withAbort` 只解决了「用户按取消」，没有「到点自己断」；而且取消信号也不会被
+ * 传进读内容那一步。这里把**硬期限 + 取消**合成一个包装。
+ *
+ * 注意：超时只能让我们这一侧返回，底层那个 evaluate 仍在浏览器里跑（Playwright
+ * 不提供取消它的办法）。所以调用方在超时后要作废会话句柄，让下一次调用别继承
+ * 这个卡住的页面；页面自己恢复后浏览器照常可用，不需要杀进程。
+ *
+ * @module dsh-browser-playwright-codex/read-deadline
+ */
+import { BrowserError } from "./errors.js";
+import { isAbortError } from "./page-diagnostics.js";
+/**
+ * 让一个可能挂住的 Promise 同时响应「到点」和「取消」。
+ *
+ * - 到点：抛 `ACTION_TIMEOUT`，消息里带上限和这一步在做什么，模型/用户能看懂。
+ * - 取消：原样抛 `AbortError`，和工具层其它取消行为一致。
+ * - 原始 Promise 无论多晚才 settle，都不会变成未捕获的 rejection（和 withAbort 同规矩）。
+ *
+ * @param promise - 可能挂住的调用
+ * @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', 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) => {
+        let settled = false;
+        const finish = (act) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            act();
+        };
+        const onAbort = () => finish(() => reject(new DOMException('The operation was aborted', 'AbortError')));
+        const timer = setTimeout(() => {
+            if (onTimeout === 'resolve-undefined') {
+                finish(() => resolve(undefined));
+                return;
+            }
+            finish(() => reject(new BrowserError('ACTION_TIMEOUT', '[ACTION_TIMEOUT] ' +
+                label +
+                ' did not finish within ' +
+                String(timeoutMs) +
+                'ms; the page may be stuck running script. ' +
+                consequence)));
+        }, timeoutMs);
+        // 不要 unref：期限是「到点必须断」的承诺，unref 之后若这是进程里最后一个句柄，
+        // 事件循环会判定无事可做直接退出，调用方永远等不到这条 ACTION_TIMEOUT
+        // （tests/read-deadline.test.ts 就是这么被打成 cancelledByParent 的）。
+        if (signal !== undefined && typeof signal.addEventListener === 'function') {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
+        guarded.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}
+/** 这个错误是不是「读内容超时」——调用方据此作废会话句柄，让下次自愈。 */
+export function isReadTimeout(error) {
+    return error instanceof BrowserError && error.code === 'ACTION_TIMEOUT';
+}
+/** 取消错误保持原样传递（不多包一层）。 */
+export { isAbortError };

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

@@ -59,6 +59,17 @@ export declare class PlaywrightSession {
     lastRefSignatures: Map<string, RefSignature> | undefined;
     /** Nonce of the baseline ref space; a change means navigation reset. */
     lastRefNonce: string | undefined;
+    /**
+     * The cancellation signal of the tool call currently driving this session.
+     * Tools set it via `setSignal` before an action; `capture()` reads it so a
+     * stuck page read can be aborted without threading a signal through every
+     * action function (issue #5).
+     */
+    private currentSignal;
+    /** Bind the current tool call's cancellation signal to this session. */
+    setSignal(signal: AbortSignal | undefined): void;
+    /** Cancellation signal for the current tool call, if any. */
+    signal(): AbortSignal | undefined;
     constructor(provider: PlaywrightProvider, owner: string, context: BrowserContext);
     /**
      * Turn a navigation the host guard refused into a named refusal.
@@ -138,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

@@ -2,6 +2,7 @@ import { looksLikeToken, registrableDomain } from "./login-sites.js";
 import { BrowserError, cdpDisabled, evaluateDisabled } from "./errors.js";
 import { isCdpMethodAllowed, cdpDenialMessage } from "./cdp-policy.js";
 import { getGates } from "./runtime-state.js";
+import { isReadTimeout, withDeadline } from "./read-deadline.js";
 import { asTimeoutError, isAbortError, isContextDestroyed, isCrashError } from "./page-diagnostics.js";
 import { consoleMessages, networkRequests, pageData, trackPage } from "./page-diagnostics.js";
 import { elementStabilityProbe, pageStabilityProbe } from "./page-probes.js";
@@ -53,6 +54,21 @@ export class PlaywrightSession {
     lastRefSignatures = undefined;
     /** Nonce of the baseline ref space; a change means navigation reset. */
     lastRefNonce = undefined;
+    /**
+     * The cancellation signal of the tool call currently driving this session.
+     * Tools set it via `setSignal` before an action; `capture()` reads it so a
+     * stuck page read can be aborted without threading a signal through every
+     * action function (issue #5).
+     */
+    currentSignal = undefined;
+    /** Bind the current tool call's cancellation signal to this session. */
+    setSignal(signal) {
+        this.currentSignal = signal;
+    }
+    /** Cancellation signal for the current tool call, if any. */
+    signal() {
+        return this.currentSignal;
+    }
     constructor(provider, owner, context) {
         this.provider = provider;
         this.owner = owner;
@@ -216,7 +232,11 @@ export class PlaywrightSession {
     }
     /** Page-level render stability, bounded — a busy page never stalls the agent. */
     async waitForPageStable(page, timeoutMs = 1200) {
-        await page.evaluate(pageStabilityProbe, { frames: 2, timeoutMs }).catch(() => false);
+        // page.evaluate has no timeout: a page whose script holds the main thread
+        // would hang here before capture even starts (issue #5). Give the probe a
+        // hard outer deadline; on timeout degrade to "not stable" and carry on —
+        // the same best-effort semantics as the existing .catch(() => false).
+        await withDeadline(page.evaluate(pageStabilityProbe, { frames: 2, timeoutMs }).catch(() => false), Math.max(2000, timeoutMs + 1000), 'waiting for the page to settle', this.currentSignal, 'resolve-undefined').catch(() => false);
     }
     /** Element-level stability before a pointer/keyboard action, bounded. Returns true when stable. */
     async waitForElementStable(locator) {
@@ -294,13 +314,54 @@ export class PlaywrightSession {
     /** Read the snapshot tree from one page (must run inside a run()). */
     async capture(page, opts, afterAction = false) {
         this.provider.armDialogGuard(page);
-        const raw = resolveSnapshotEngine(this.provider.config.snapshot.engine) === 'aria'
-            ? await this.captureAria(page, opts)
-            : await this.captureLegacy(page, opts);
-        // Order matters: the response metadata is attached before the diff, so the
-        // snapshot the model reads carries the same evidence the detector used, and
-        // the no-progress backstop sees the final tree.
-        return this.attachDiff(attachNoProgress(this, attachDocResponse(this, page, raw), afterAction));
+        // 读页面内容（page.evaluate / ariaSnapshot）没有 timeout 参数：页面脚本占住
+        // 主线程时它会永远挂着，连工具调用一起卡死（issue #5）。这里给整次读加
+        // 硬期限 + 取消信号。所有读内容都经过这个咽喉点，一处覆盖全部动作。
+        const read = async () => {
+            const raw = resolveSnapshotEngine(this.provider.config.snapshot.engine) === 'aria'
+                ? await this.captureAria(page, opts)
+                : await this.captureLegacy(page, opts);
+            // Order matters: the response metadata is attached before the diff, so the
+            // snapshot the model reads carries the same evidence the detector used, and
+            // the no-progress backstop sees the final tree.
+            return this.attachDiff(attachNoProgress(this, attachDocResponse(this, page, raw), afterAction));
+        };
+        try {
+            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').