dsh-browser-playwright-codex 0.7.8 → 0.8.1

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?: {
+        /** 出厂默认关：动效资产随包分发（0.8.1 起已获作者授权），但默认不播；想要的人在设置卡里打开。 */
+        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,25 @@ export const Config = z.object({
         diff: z.boolean().default(false),
     })
         .default({ engine: 'legacy', maxNodes: 500, maxNameLength: 120, maxTextLength: 300, diff: false }),
+    swarm: z
+        .object({
+        // 出厂关：资产在包里（0.8.1 起已获作者授权），但默认不播，避免每次开新站先把页面盖住。
+        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/errors.d.ts

@@ -35,3 +35,20 @@ export declare function evaluateDisabled(): BrowserError;
  * @returns the denial, ready to throw.
  */
 export declare function cdpDisabled(): BrowserError;
+/**
+ * Normalize a `browser_evaluate` result so it survives the harness's
+ * lossless-JSON output boundary.
+ *
+ * The harness (dsh-tools) rejects a tool result that is not losslessly
+ * JSON-serializable, and it is strictest about *top-level* shape: a bare array
+ * or `undefined` at the root fails its check with an opaque
+ * "value is not lossless JSON" that does not tell the model how to fix it. This
+ * wraps only those shapes — arrays, `undefined` and functions — into a JSON
+ * string plus a marker note, and leaves every other value (objects, strings,
+ * numbers, booleans, null) untouched so callers get back what their expression
+ * actually returned.
+ *
+ * @param value - the raw value the page expression evaluated to.
+ * @returns a lossless-JSON-safe value, with a note when it had to be stringified.
+ */
+export declare function normalizeEvaluateResult(value: unknown): unknown;

package/lib/errors.js

@@ -35,3 +35,31 @@ export function evaluateDisabled() {
 export function cdpDisabled() {
     return new BrowserError('CDP_DISABLED', "browser_cdp is disabled; set tool.allowCdp: true on the single '- id: browser' row of cordis.patch.yml (the Settings card rewrites that row for you) to enable raw CDP inspection commands");
 }
+/**
+ * Normalize a `browser_evaluate` result so it survives the harness's
+ * lossless-JSON output boundary.
+ *
+ * The harness (dsh-tools) rejects a tool result that is not losslessly
+ * JSON-serializable, and it is strictest about *top-level* shape: a bare array
+ * or `undefined` at the root fails its check with an opaque
+ * "value is not lossless JSON" that does not tell the model how to fix it. This
+ * wraps only those shapes — arrays, `undefined` and functions — into a JSON
+ * string plus a marker note, and leaves every other value (objects, strings,
+ * numbers, booleans, null) untouched so callers get back what their expression
+ * actually returned.
+ *
+ * @param value - the raw value the page expression evaluated to.
+ * @returns a lossless-JSON-safe value, with a note when it had to be stringified.
+ */
+export function normalizeEvaluateResult(value) {
+    if (Array.isArray(value)) {
+        return { note: 'array converted to JSON string', value: JSON.stringify(value) };
+    }
+    if (value === undefined) {
+        return { note: 'expression returned undefined' };
+    }
+    if (typeof value === 'function') {
+        return { note: 'function converted to string', value: String(value) };
+    }
+    return value;
+}

package/lib/gates-patch.d.ts

@@ -20,7 +20,46 @@ export declare function homePatchPath(env?: NodeJS.ProcessEnv): string;
  * @returns the YAML block, markers included
  */
 export declare function renderBrowserBlock(allowEvaluate: boolean, allowCdp: boolean, diagnostics: boolean): string;
-/** Merge the managed block into `original`, replacing an existing one in place. */
+/** The three gate keys, in the order a freshly created block writes them. */
+declare const GATE_KEYS: readonly ["allowEvaluate", "allowCdp", "diagnostics"];
+/** One of the three gate keys this writer owns. */
+type GateKey = (typeof GATE_KEYS)[number];
+/** The gate values as a record, for line-level rewriting. */
+type GateValues = Record<GateKey, boolean>;
+/**
+ * Rewrite ONLY the three gate shortcuts inside an existing block, keeping every
+ * other line byte for byte.
+ *
+ * Why not re-render the whole block: the loader replaces an entry's `config`
+ * wholesale, so the block has to carry every key the user cares about — and it
+ * cannot know all of them. Re-rendering the template silently reset whatever
+ * the template did not list: `profileDir` (which wiped the saved login), the
+ * launch channel, `snapshot.engine`, `toolPrefix`, `maxWaitMs`,
+ * `interactiveOnlyDefault`, `registerDisabledTools`, the swarm section. Measured
+ * 2026-11-10: toggling one switch in the settings card logged the user out of
+ * every site, because their block said profileDir: 'D:/dsh-profile' and the
+ * template does not.
+ *
+ * Documented consequence, deliberately kept: keys the user never wrote stay
+ * unwritten (the package default applies), which is exactly what the user chose
+ * by not writing them.
+ *
+ * @param body - the full block text, markers included
+ * @param gates - the three gate values to write
+ * @returns the block with only those lines changed or added
+ */
+export declare function patchBlockGates(body: string, gates: GateValues): string;
+/**
+ * Merge the gate values into `original`.
+ *
+ * - No managed block yet → append the full template (nothing to preserve).
+ * - Block present → rewrite ONLY the three gate lines (see patchBlockGates).
+ * - Block present but its structure defeats line editing (a flow-style
+ *   `tool: { ... }`, a truncated block) → fall back to the whole template, which
+ *   is the old behaviour: at least the switch the user just flipped takes
+ *   effect. Guarded by a read-back check so a half-edited block can never be
+ *   written out.
+ */
 export declare function mergeBrowserBlock(original: string, allowEvaluate: boolean, allowCdp: boolean, diagnostics: boolean): string;
 /** Read the current managed block, or undefined when there is none. */
 export declare function parseBrowserBlock(text: string): {
@@ -47,3 +86,4 @@ export declare function writeGates(allowEvaluate: boolean, allowCdp: boolean, di
     allowCdp: boolean;
     diagnostics: boolean;
 }>;
+export {};

package/lib/gates-patch.js

@@ -80,6 +80,82 @@ export function renderBrowserBlock(allowEvaluate, allowCdp, diagnostics) {
         '',
     ].join('\n');
 }
+/** The three gate keys, in the order a freshly created block writes them. */
+const GATE_KEYS = ['allowEvaluate', 'allowCdp', 'diagnostics'];
+/** One `key: value  # note` line of the managed block. */
+const GATE_LINE = /^(\s*)(allowEvaluate|allowCdp|diagnostics)(\s*:\s*)(?:true|false)?[ \t]*(#.*)?$/;
+/**
+ * Rewrite ONLY the three gate shortcuts inside an existing block, keeping every
+ * other line byte for byte.
+ *
+ * Why not re-render the whole block: the loader replaces an entry's `config`
+ * wholesale, so the block has to carry every key the user cares about — and it
+ * cannot know all of them. Re-rendering the template silently reset whatever
+ * the template did not list: `profileDir` (which wiped the saved login), the
+ * launch channel, `snapshot.engine`, `toolPrefix`, `maxWaitMs`,
+ * `interactiveOnlyDefault`, `registerDisabledTools`, the swarm section. Measured
+ * 2026-11-10: toggling one switch in the settings card logged the user out of
+ * every site, because their block said profileDir: 'D:/dsh-profile' and the
+ * template does not.
+ *
+ * Documented consequence, deliberately kept: keys the user never wrote stay
+ * unwritten (the package default applies), which is exactly what the user chose
+ * by not writing them.
+ *
+ * @param body - the full block text, markers included
+ * @param gates - the three gate values to write
+ * @returns the block with only those lines changed or added
+ */
+export function patchBlockGates(body, gates) {
+    const nl = body.includes('\r\n') ? '\r\n' : '\n';
+    const lines = body.split(/\r?\n/);
+    const seen = new Set();
+    let lastGateAt = -1;
+    let gateIndent = '';
+    let toolAt = -1;
+    let configIndent;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        const gate = GATE_LINE.exec(line);
+        if (gate !== null) {
+            const key = gate[2];
+            seen.add(key);
+            const indent = gate[1] ?? '';
+            const comment = gate[4] === undefined ? '' : '  ' + gate[4];
+            lines[index] = indent + key + ': ' + (gates[key] ? 'true' : 'false') + comment;
+            lastGateAt = index;
+            gateIndent = indent;
+            continue;
+        }
+        if (toolAt === -1 && /^\s*tool\s*:\s*(#.*)?$/.test(line))
+            toolAt = index;
+        const config = /^(\s*)config\s*:/.exec(line);
+        if (configIndent === undefined && config !== null)
+            configIndent = config[1] ?? '';
+    }
+    const missing = GATE_KEYS.filter((key) => !seen.has(key));
+    if (missing.length === 0)
+        return lines.join(nl);
+    const rendered = missing.map((key) => key + ': ' + (gates[key] ? 'true' : 'false'));
+    if (lastGateAt >= 0) {
+        // Beside the gates already present: same indentation, same section.
+        lines.splice(lastGateAt + 1, 0, ...rendered.map((line) => gateIndent + line));
+        return lines.join(nl);
+    }
+    if (toolAt >= 0) {
+        const indent = (/^\s*/.exec(lines[toolAt] ?? '')?.[0] ?? '') + '  ';
+        lines.splice(toolAt + 1, 0, ...rendered.map((line) => indent + line));
+        return lines.join(nl);
+    }
+    // No tool section at all: add one just above the closing marker, inside config.
+    const endAt = lines.findIndex((line) => line.trim() === END || line.trim() === LEGACY_END);
+    const configPad = (configIndent ?? '') + '  ';
+    const insert = [configPad + 'tool:', ...rendered.map((line) => configPad + '  ' + line)];
+    if (endAt === -1)
+        return lines.concat(insert).join(nl);
+    lines.splice(endAt, 0, ...insert);
+    return lines.join(nl);
+}
 /** Locate the managed block, preferring the current markers over the legacy ones. */
 function findBlock(original) {
     const markers = [
@@ -98,13 +174,35 @@ function findBlock(original) {
     }
     return undefined;
 }
-/** Merge the managed block into `original`, replacing an existing one in place. */
+/**
+ * Merge the gate values into `original`.
+ *
+ * - No managed block yet → append the full template (nothing to preserve).
+ * - Block present → rewrite ONLY the three gate lines (see patchBlockGates).
+ * - Block present but its structure defeats line editing (a flow-style
+ *   `tool: { ... }`, a truncated block) → fall back to the whole template, which
+ *   is the old behaviour: at least the switch the user just flipped takes
+ *   effect. Guarded by a read-back check so a half-edited block can never be
+ *   written out.
+ */
 export function mergeBrowserBlock(original, allowEvaluate, allowCdp, diagnostics) {
-    const block = renderBrowserBlock(allowEvaluate, allowCdp, diagnostics);
+    const gates = { allowEvaluate, allowCdp, diagnostics };
     const found = findBlock(original);
-    if (found !== undefined)
-        return original.slice(0, found.start) + block + original.slice(found.after);
-    return (original === '' || original.endsWith('\n') ? original : original + '\n') + '\n' + block;
+    if (found === undefined) {
+        const block = renderBrowserBlock(allowEvaluate, allowCdp, diagnostics);
+        return (original === '' || original.endsWith('\n') ? original : original + '\n') + '\n' + block;
+    }
+    const current = original.slice(found.start, found.after);
+    const edited = patchBlockGates(current, gates);
+    const check = parseBrowserBlock(edited);
+    if (check !== undefined &&
+        check.allowEvaluate === allowEvaluate &&
+        check.allowCdp === allowCdp &&
+        check.diagnostics === diagnostics) {
+        return original.slice(0, found.start) + edited + original.slice(found.after);
+    }
+    const rebuilt = renderBrowserBlock(allowEvaluate, allowCdp, diagnostics);
+    return original.slice(0, found.start) + rebuilt + original.slice(found.after);
 }
 /** Read the current managed block, or undefined when there is none. */
 export function parseBrowserBlock(text) {

package/lib/injected.js

@@ -66,6 +66,22 @@ export const SNAPSHOT_SCRIPT = String.raw `
     return text.length > max ? text.slice(0, max) + '…' : text
   }
 
+  // Autocomplete tokens that mark a credential field. Mirrors CREDENTIAL_AUTOCOMPLETE
+  // in page-actions.ts so the snapshot never reads back what the user typed into one.
+  const CREDENTIAL_AUTOCOMPLETE = ['current-password', 'new-password', 'one-time-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year']
+
+  // Whether an element holds a secret (password, one-time code, card number).
+  // Same judgement as isCredentialField in page-actions.ts: type=password, or an
+  // autocomplete token list containing a credential token (not just the last one).
+  function isCredentialEl(el) {
+    const tag = el.tagName.toLowerCase()
+    if (tag !== 'input' && tag !== 'textarea') return false
+    const type = tag === 'input' ? (el.getAttribute('type') || '').toLowerCase() : ''
+    if (type === 'password') return true
+    const tokens = (el.getAttribute('autocomplete') || '').toLowerCase().split(/\s+/)
+    return tokens.some((token) => CREDENTIAL_AUTOCOMPLETE.indexOf(token) !== -1)
+  }
+
   function ownText(el, maxText) {
     let out = ''
     for (const node of el.childNodes) {
@@ -77,6 +93,13 @@ export const SNAPSHOT_SCRIPT = String.raw `
   }
 
   function nameOf(el, maxName, maxText, actionable) {
+    // An <option> names itself with its own text — never the enclosing <label> or
+    // <select>, whose textContent contains every option. Without this every option
+    // in one <select> shares the same long name and the model cannot tell them
+    // apart (measured 2026-11-11 on selenium.dev's web-form).
+    if (el.tagName.toLowerCase() === 'option') {
+      return clip((el.textContent || '').replace(/\s+/g, ' ').trim(), maxName)
+    }
     const aria = el.getAttribute('aria-label')
     if (aria && aria.trim()) return clip(aria.trim(), maxName)
     if (el.id) {
@@ -256,6 +279,28 @@ export const SNAPSHOT_SCRIPT = String.raw `
     if (el.tagName.toLowerCase() === 'input' && (role === 'checkbox' || role === 'radio')) node.checked = !!el.checked
     if (role === 'option') node.selected = !!el.selected
     if (el.disabled) node.disabled = true
+    // Expose the current value of a text entry field so the model can see what a
+    // fill actually left behind, and so a value change registers as page change.
+    // Credential fields (password, one-time code, card number) are excluded: the
+    // user typed those in the visible window, and reading them back into the
+    // snapshot would send the secret to the model API. Mirrors isCredentialField
+    // in page-actions.ts.
+    //
+    // A real <select> is left out on purpose: its NAME already shows the chosen
+    // option (the branch above), so a value flag would print the same fact twice.
+    // Excluding by TAG, not by role, matters: autocomplete search boxes routinely
+    // carry an explicit role="combobox" and their value must still be visible.
+    // An <option> carries its value attribute only when it differs from its text.
+    const isSelectEl = el.tagName.toLowerCase() === 'select'
+    const textEntry =
+      role === 'textbox' || role === 'textarea' || role === 'searchbox' || role === 'combobox'
+    if (textEntry && !isSelectEl && !isCredentialEl(el)) {
+      const v = (el.value !== undefined ? String(el.value) : '').replace(/\s+/g, ' ').trim()
+      if (v !== '') node.value = clip(v, opts.maxTextLength)
+    } else if (role === 'option') {
+      const ov = (el.getAttribute('value') || '').trim()
+      if (ov !== '' && ov !== nodeName) node.value = clip(ov, opts.maxNameLength)
+    }
     if (role === 'link') {
       const href = el.getAttribute('href')
       if (href && href.trim() && href.indexOf('javascript:') !== 0) node.href = href

package/lib/page-actions.d.ts

@@ -84,6 +84,30 @@ export declare function isCredentialField(spec: {
     type?: string;
     autocomplete?: string;
 }): boolean;
+/** What the live element says about itself, as far as the credential check needs. */
+export interface FieldSpec {
+    tag: string;
+    type: string;
+    autocomplete: string;
+}
+/**
+ * Read tag/type/autocomplete from the live element — and refuse to guess.
+ *
+ * `browser_fill` promises it never types a secret. That promise used to depend
+ * on a read whose failure was swallowed (`.catch(() => ({tag:'input', type:'',
+ * autocomplete:''}))`): an unreadable field produced a spec that looks like a
+ * plain text box, the credential check said "not a credential", and the fill
+ * went ahead. Fail-open on a page whose attributes we cannot read is exactly
+ * the case where the answer is least certain, so it now fails closed: no spec,
+ * nothing typed, CREDENTIAL_FIELD with a clear next step.
+ *
+ * Cancel and deadline are NOT credential failures: they pass through untouched
+ * so the caller reports what actually happened.
+ *
+ * @param locator - the resolved target
+ * @returns the field spec read from the page
+ */
+export declare function readFieldSpec(locator: Locator): Promise<FieldSpec>;
 export declare function fill(session: PlaywrightSession, ref: string, text: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 /**
  * Normalize a field value before comparing. Two levels of forgiveness, both of them

package/lib/page-actions.js

@@ -7,8 +7,11 @@ import { clickTargetHrefProbe, hitTest } from "./page-probes.js";
 import { BrowserError } from "./errors.js";
 import { assertAllowedUrl } from "./url-policy.js";
 import { asTimeoutError, isAbortError } from "./page-diagnostics.js";
+import { isReadTimeout } from "./read-deadline.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 +102,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 +120,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 +141,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(() => { });
+        }
     });
 }
 /**
@@ -511,9 +543,45 @@ export function isCredentialField(spec) {
         return false;
     if ((spec.type ?? '').toLowerCase() === 'password')
         return true;
-    const tokens = (spec.autocomplete ?? '').toLowerCase().trim().split(/\s+/);
-    const token = tokens[tokens.length - 1] ?? '';
-    return CREDENTIAL_AUTOCOMPLETE.has(token);
+    // Every token, not just the last one. `autocomplete` is a space-separated
+    // token list ("section-a shipping new-password webauthn") and only its LAST
+    // token used to be checked, so any credential token that was not written last
+    // read as an ordinary field (measured 2026-11-10).
+    const tokens = (spec.autocomplete ?? '').toLowerCase().split(/\s+/);
+    return tokens.some((token) => CREDENTIAL_AUTOCOMPLETE.has(token));
+}
+/**
+ * Read tag/type/autocomplete from the live element — and refuse to guess.
+ *
+ * `browser_fill` promises it never types a secret. That promise used to depend
+ * on a read whose failure was swallowed (`.catch(() => ({tag:'input', type:'',
+ * autocomplete:''}))`): an unreadable field produced a spec that looks like a
+ * plain text box, the credential check said "not a credential", and the fill
+ * went ahead. Fail-open on a page whose attributes we cannot read is exactly
+ * the case where the answer is least certain, so it now fails closed: no spec,
+ * nothing typed, CREDENTIAL_FIELD with a clear next step.
+ *
+ * Cancel and deadline are NOT credential failures: they pass through untouched
+ * so the caller reports what actually happened.
+ *
+ * @param locator - the resolved target
+ * @returns the field spec read from the page
+ */
+export async function readFieldSpec(locator) {
+    try {
+        return await locator.evaluate((el) => {
+            const tag = el.tagName.toLowerCase();
+            const type = tag === 'input' ? String(el.type || '').toLowerCase() : '';
+            return { tag, type, autocomplete: el.getAttribute('autocomplete') ?? '' };
+        });
+    }
+    catch (error) {
+        if (isAbortError(error) || isReadTimeout(error))
+            throw error;
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new BrowserError('CREDENTIAL_FIELD', "browser_fill could not read this field's attributes, so it cannot rule out a password / one-time code / card field and typed nothing. Take a fresh snapshot (the element may have been replaced) and retry, or ask the user to fill it in the visible window. Underlying failure: " +
+            detail.slice(0, 200));
+    }
 }
 export async function fill(session, ref, text, signal) {
     return session.run(async () => {
@@ -521,13 +589,7 @@ export async function fill(session, ref, text, signal) {
         const page = session.currentPageSync();
         await session.waitForElementStable(locator);
         await session.assertActionable(locator, { editable: true });
-        const spec = await locator
-            .evaluate((el) => {
-            const tag = el.tagName.toLowerCase();
-            const type = tag === 'input' ? String(el.type || '').toLowerCase() : '';
-            return { tag, type, autocomplete: el.getAttribute('autocomplete') ?? '' };
-        })
-            .catch(() => ({ tag: 'input', type: '', autocomplete: '' }));
+        const spec = await readFieldSpec(locator);
         if (isCredentialField(spec)) {
             throw new BrowserError('CREDENTIAL_FIELD', 'browser_fill refuses credential fields (password, one-time code, card number): a human types those in the visible window. Ask the user to type it there, then take a fresh snapshot and continue with the rest.');
         }

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. */