dsh-browser-playwright-codex 0.8.0 → 0.8.1

package/lib/challenge.d.ts

@@ -32,11 +32,14 @@ export declare function challengeNote(headless: boolean): string;
 export declare const CHALLENGE_NOTE = "[human verification] The page triggered an anti-bot challenge; it is NOT solvable by automation and must NOT be retried blindly. The browser window is open on the user's desktop \u2014 tell the user a verification appeared, wait for them to finish it (a few seconds), then call browser_snapshot again. The clearance cookie is saved to the profile automatically and keeps working for the session.";
 /**
  * Appended after an action that left the page byte-for-byte unchanged on a page
- * with almost nothing else to interact with. Worded as a guess, because that is
- * what it is: it is the shape an unrecognised wall has, and the whole point of
- * this tier is to cover the vendors we have no signature for.
+ * with almost nothing else to interact with. It states the observation and the
+ * recovery — re-snapshot in case the page is still rendering, then try another
+ * approach — and deliberately does NOT guess "anti-bot wall" or send the user to
+ * look at the window: a normal fill or checkbox toggle also lands here when the
+ * page state it changed is not in the compared subset, and scaring the user off
+ * on a successful action is worse than saying less.
  */
-export declare const NO_PROGRESS_NOTE = "[no visible change] that action left the page identical \u2014 same URL, same title, same elements \u2014 and the page offers almost nothing else to click. This is a guess, not a diagnosis: it is what an unrecognised anti-bot wall looks like. Take one browser_snapshot to confirm; if the page still looks unchanged, stop and tell the user what you were trying to do and ask them to look at the open window, instead of retrying the same action.";
+export declare const NO_PROGRESS_NOTE = "[no visible change] this action did not produce a visible change. If what you just did was a submit, a search or a navigation, the page may still be rendering \u2014 take one more browser_snapshot to confirm. If it still looks the same, try a different approach (for example another entry point on the page).";
 /** A page with at most this many actionable elements counts as "nearly empty". */
 export declare const NO_PROGRESS_MAX_REFS = 3;
 /**

package/lib/challenge.js

@@ -40,11 +40,27 @@ function scan(nodes, depth, maxDepth, out, cap) {
             return;
         const name = node.name ?? '';
         if (name !== '')
-            out.push({ role: (node.role ?? '').toLowerCase(), name });
+            out.push({ role: (node.role ?? '').toLowerCase(), name, state: stateOf(node) });
         if (depth < maxDepth)
             scan(node.children, depth + 1, maxDepth, out, cap);
     }
 }
+/**
+ * Compact interactive-state signature of one node. A fill or a toggle changes
+ * this without changing the role or name, so the no-progress fingerprint has to
+ * include it — otherwise a normal fill or checkbox toggle looks like "no visible
+ * change" and trips the anti-bot guess.
+ */
+function stateOf(node) {
+    const parts = [];
+    if (node.checked !== undefined)
+        parts.push(node.checked ? 'checked' : 'unchecked');
+    if (node.selected !== undefined)
+        parts.push(node.selected ? 'selected' : 'unselected');
+    if (node.value !== undefined && node.value !== '')
+        parts.push('v=' + node.value);
+    return parts.join(',');
+}
 /** Evidence string when one header rule holds, else null. */
 function headerEvidence(rule, headers) {
     if (headers === undefined)
@@ -232,11 +248,14 @@ export function challengeNote(headless) {
 export const CHALLENGE_NOTE = "[human verification] The page triggered an anti-bot challenge; it is NOT solvable by automation and must NOT be retried blindly. The browser window is open on the user's desktop — tell the user a verification appeared, wait for them to finish it (a few seconds), then call browser_snapshot again. The clearance cookie is saved to the profile automatically and keeps working for the session.";
 /**
  * Appended after an action that left the page byte-for-byte unchanged on a page
- * with almost nothing else to interact with. Worded as a guess, because that is
- * what it is: it is the shape an unrecognised wall has, and the whole point of
- * this tier is to cover the vendors we have no signature for.
+ * with almost nothing else to interact with. It states the observation and the
+ * recovery — re-snapshot in case the page is still rendering, then try another
+ * approach — and deliberately does NOT guess "anti-bot wall" or send the user to
+ * look at the window: a normal fill or checkbox toggle also lands here when the
+ * page state it changed is not in the compared subset, and scaring the user off
+ * on a successful action is worse than saying less.
  */
-export const NO_PROGRESS_NOTE = '[no visible change] that action left the page identical — same URL, same title, same elements — and the page offers almost nothing else to click. This is a guess, not a diagnosis: it is what an unrecognised anti-bot wall looks like. Take one browser_snapshot to confirm; if the page still looks unchanged, stop and tell the user what you were trying to do and ask them to look at the open window, instead of retrying the same action.';
+export const NO_PROGRESS_NOTE = '[no visible change] this action did not produce a visible change. If what you just did was a submit, a search or a navigation, the page may still be rendering — take one more browser_snapshot to confirm. If it still looks the same, try a different approach (for example another entry point on the page).';
 /** A page with at most this many actionable elements counts as "nearly empty". */
 export const NO_PROGRESS_MAX_REFS = 3;
 /** Cheap, order-stable hash (djb2) so a fingerprint costs no prompt budget. */
@@ -261,7 +280,10 @@ export function snapshotFingerprint(input) {
         input.url ?? '',
         input.title ?? '',
         String(input.refs ?? 0),
-        names.map((node) => node.role + '=' + node.name).join('\u0001'),
+        // Include interactive state (checked/selected/value) so a fill or a toggle
+        // registers as change — otherwise a normal fill looks like "no visible
+        // change" and trips the anti-bot guess.
+        names.map((node) => node.role + '=' + node.name + (node.state ? '[' + node.state + ']' : '')).join('\u0001'),
     ].join('\u0000');
     return hash(material);
 }

package/lib/client.js

@@ -894,7 +894,8 @@ window.__ModuleLoader__.load({
                     }),
                   ],
                 ),
-            // 署名：原创作者 Joel Califa 的唯一条件（2026-11-08 书面授权）。放在卡片里，但不随开关隐藏——
+            // 署名：Joel Califa（2026-11-08 书面许可，唯一条件是署名）与 Dhvanil Patel
+            // （2026-11-11 邮件书面许可打包 + 修改）。放在卡片里，但不随开关隐藏——
             // 关掉特效不等于这份代码不在这台机器上。
             h(
               'div',
@@ -908,7 +909,32 @@ window.__ModuleLoader__.load({
                   color: T.tertiary,
                 },
               },
-              '动效：Joel Califa（Swarm）· 代码：Dhvanil Patel（swarm-cursors）',
+              [
+                '动效：',
+                h(
+                  'a',
+                  {
+                    key: 'joel',
+                    href: 'https://github.com/califa/swarm-site',
+                    target: '_blank',
+                    rel: 'noreferrer',
+                    style: { color: T.tertiary, textDecoration: 'underline' },
+                  },
+                  'Joel Califa（Swarm）',
+                ),
+                ' · 代码：',
+                h(
+                  'a',
+                  {
+                    key: 'dhvanil',
+                    href: 'https://github.com/DhvanilPatel/swarm-cursors',
+                    target: '_blank',
+                    rel: 'noreferrer',
+                    style: { color: T.tertiary, textDecoration: 'underline' },
+                  },
+                  'Dhvanil Patel（swarm-cursors）',
+                ),
+              ],
             ),
           ],
         ),

package/lib/config.d.ts

@@ -49,7 +49,7 @@ export interface PlaywrightConfig {
      * 测试配置、以及旧部署的 patch 层都能直接通过类型检查。
      */
     swarm?: {
-        /** 出厂就开着：这是装完就能看见的那一下「哇」。设置卡上的开关可以随时关掉。 */
+        /** 出厂默认关：动效资产随包分发（0.8.1 起已获作者授权），但默认不播；想要的人在设置卡里打开。 */
         enabled: boolean;
         /** 只在某个网站第一次打开时播；false = 每次导航都播（不建议）。 */
         oncePerSite: boolean;

package/lib/config.js

@@ -47,8 +47,7 @@ export const Config = z.object({
         .default({ engine: 'legacy', maxNodes: 500, maxNameLength: 120, maxTextLength: 300, diff: false }),
     swarm: z
         .object({
-        // 出厂关：动效资产不再随 npm 包分发（0.8.0 起），默认开会让每个新用户
-        // 在"文件根本不存在"的状态下开箱报错。想要的人把资产放回 assets/ 再打开。
+        // 出厂关：资产在包里（0.8.1 起已获作者授权），但默认不播，避免每次开新站先把页面盖住。
         enabled: z.boolean().default(false),
         // 只在每个网站第一次打开时播，避免每次导航都把页面盖住。
         oncePerSite: z.boolean().default(true),

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,6 +7,7 @@ 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";
@@ -542,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 () => {
@@ -552,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.');
         }