dsh-browser-playwright-codex 0.6.1 → 0.6.5

package/lib/challenge.js

@@ -1,35 +1,166 @@
+import { CAPTCHA_ROLES, CAPTCHA_WORD, CHALLENGE_SIGNATURES, WIDGET_CORROBORATION, WORDING_COMMAND, WORDING_EXCLUDE, WORDING_TITLE, } from "./challenge-signatures.js";
+/** How many accessible names the wording tiers may look at. */
+const MAX_NAMES = 60;
+/** Cap on the joined text handed to the wording tiers. */
+const MAX_TEXT = 900;
+/** A control label is short; a sentence that merely mentions captchas is not. */
+const MAX_CONTROL_LABEL = 32;
+/** Cap on names folded into one page-state fingerprint. */
+const MAX_FINGERPRINT_NAMES = 200;
 /**
- * Detect anti-bot / human-verification challenge pages (Cloudflare
- * interstitial, Turnstile, reCAPTCHA-style) from a snapshot's title, url and
- * visible text. We do NOT try to solve them: the correct move for an agent is
- * to hand the challenge to the human who can see the open window. Returns the
- * engine name when matched, else null. Matching is conservative to avoid
- * false positives on ordinary pages.
+ * How deep the fingerprint reads. Deeper than the wording tiers on purpose: a
+ * fingerprint that only saw the top of the tree would call a page "unchanged"
+ * when a deep section revealed text without adding a new actionable element,
+ * and the backstop would then warn about a wall that is not there.
+ */
+const FINGERPRINT_DEPTH = 4;
+/** Collect accessible names breadth-first, bounded by depth and count. */
+function scan(nodes, depth, maxDepth, out, cap) {
+    if (nodes === undefined || out.length >= cap)
+        return;
+    for (const node of nodes) {
+        if (out.length >= cap)
+            return;
+        const name = node.name ?? '';
+        if (name !== '')
+            out.push({ role: (node.role ?? '').toLowerCase(), name });
+        if (depth < maxDepth)
+            scan(node.children, depth + 1, maxDepth, out, cap);
+    }
+}
+/** Evidence string when one header rule holds, else null. */
+function headerEvidence(rule, headers) {
+    if (headers === undefined)
+        return null;
+    const wanted = rule.name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() !== wanted)
+            continue;
+        const value = headers[key] ?? '';
+        const lower = value.toLowerCase();
+        if (rule.equals !== undefined && lower !== rule.equals.toLowerCase())
+            return null;
+        if (rule.contains !== undefined && !lower.includes(rule.contains.toLowerCase()))
+            return null;
+        return key + ': ' + value;
+    }
+    return null;
+}
+/** Evidence string when any header name carries the prefix, else null. */
+function prefixEvidence(prefix, headers) {
+    if (headers === undefined)
+        return null;
+    const wanted = prefix.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase().startsWith(wanted))
+            return key + ': ' + (headers[key] ?? '');
+    }
+    return null;
+}
+/**
+ * Detect an anti-bot / human-verification surface from the MAIN document
+ * response metadata, the page's accessible names and, as a last resort, its
+ * wording. We never try to solve one: the correct move for an agent is to hand
+ * it to the human who can see the open window.
+ * @param snapshot - title, url, accessible tree and (when available) the main document response.
+ * @returns the matched engine with its tier and the concrete evidence, else null.
  */
 export function detectChallenge(snapshot) {
     const title = snapshot.title ?? '';
     const url = snapshot.url ?? '';
-    const parts = [];
-    const walk = (nodes, depth) => {
-        for (const node of nodes) {
-            if (parts.length >= 60)
-                return;
-            if (node.name !== undefined && node.name !== '')
-                parts.push(node.name);
-            if (depth < 2 && node.children !== undefined && node.children.length > 0)
-                walk(node.children, depth + 1);
+    const names = [];
+    scan(snapshot.nodes, 0, 2, names, MAX_NAMES);
+    const headers = snapshot.response?.headers;
+    // Tier 1 — the vendor's own response metadata. This is their published API:
+    // Cloudflare documents cf-mitigated: challenge as the supported way to detect
+    // a challenge page, so a rename breaks every customer integration, not just us.
+    for (const signature of CHALLENGE_SIGNATURES) {
+        for (const rule of signature.headers ?? []) {
+            const evidence = headerEvidence(rule, headers);
+            if (evidence !== null) {
+                return { engine: signature.engine, hint: signature.hint, tier: 'response-header', evidence };
+            }
+        }
+        for (const prefix of signature.headerPrefixes ?? []) {
+            const evidence = prefixEvidence(prefix, headers);
+            if (evidence !== null) {
+                return { engine: signature.engine, hint: signature.hint, tier: 'response-header', evidence };
+            }
+        }
+    }
+    // Tier 2 — the vendor's own widget, by accessible name. An iframe's title is
+    // authored by the vendor, so it stands alone; the same word on an ordinary
+    // node needs corroboration from somewhere else on the page, because a page may
+    // simply discuss that vendor. Corroboration deliberately excludes the matched
+    // node itself: "reCAPTCHA" contains "captcha", and letting a token corroborate
+    // itself would make this guard vacuous.
+    for (const signature of CHALLENGE_SIGNATURES) {
+        const tokens = signature.widgetTokens;
+        if (tokens === undefined)
+            continue;
+        for (const node of names) {
+            if (!tokens.some((token) => token.test(node.name)))
+                continue;
+            const onFrame = node.role === 'iframe' || node.role === 'frame';
+            if (!onFrame) {
+                const others = [title, url, ...names.filter((other) => other !== node).map((other) => other.name)]
+                    .join(' | ')
+                    .slice(0, MAX_TEXT);
+                const corroborated = WIDGET_CORROBORATION.some((token) => token.test(others));
+                if (!corroborated)
+                    continue;
+            }
+            return {
+                engine: signature.engine,
+                hint: signature.hint,
+                tier: 'widget',
+                evidence: node.name.slice(0, 60),
+            };
+        }
+    }
+    // Tier 3 — wording, weakest of the three. A title is short and written by the
+    // interceptor, so it stands alone; on a node we require a command form (or a
+    // captcha control), which is the difference between a challenge and a help
+    // page about captchas.
+    const head = title + ' ' + url;
+    for (const signature of CHALLENGE_SIGNATURES) {
+        for (const pattern of signature.titleWording ?? []) {
+            if (!pattern.test(head))
+                continue;
+            return {
+                engine: signature.engine,
+                hint: signature.hint,
+                tier: 'wording',
+                evidence: 'title: ' + title.slice(0, 60),
+            };
         }
-    };
-    walk(snapshot.nodes ?? [], 0);
-    const text = [title, url, ...parts].join(' | ').slice(0, 900);
-    const saidCaptcha = parts.some((name) => /(captcha|turnstile|recaptcha|hcaptcha)/i.test(name));
-    if (/just a moment|attention required|checking (your )?browser|cf-chl-|请稍候|验证你的浏览器/i.test(text))
-        return { engine: 'Cloudflare', hint: 'Cloudflare is challenging the browser before letting the page load' };
-    if (/verify (you are|you're|that you are) (a )?human|人机验证|验证您(是|为)人类/i.test(text))
-        return { engine: 'human-verification', hint: 'the page is asking to verify a human visitor' };
-    if (/(captcha|turnstile|recaptcha|hcaptcha)/i.test(text) &&
-        (saidCaptcha || /(captcha|turnstile|recaptcha)/i.test(title)))
-        return { engine: 'captcha', hint: 'the page embedded a captcha-style challenge' };
+    }
+    for (const pattern of WORDING_TITLE) {
+        if (!pattern.test(head))
+            continue;
+        return {
+            engine: 'human-verification',
+            hint: 'the page is asking to verify a human visitor',
+            tier: 'wording',
+            evidence: 'title: ' + title.slice(0, 60),
+        };
+    }
+    for (const node of names) {
+        if (node.name.length > MAX_CONTROL_LABEL)
+            continue;
+        if (WORDING_EXCLUDE.some((pattern) => pattern.test(node.name)))
+            continue;
+        const captchaControl = CAPTCHA_WORD.test(node.name) && CAPTCHA_ROLES.has(node.role);
+        const command = WORDING_COMMAND.some((pattern) => pattern.test(node.name));
+        if (!captchaControl && !command)
+            continue;
+        return {
+            engine: 'human-verification',
+            hint: 'the page is asking to verify a human visitor',
+            tier: 'wording',
+            evidence: node.role + ': ' + node.name.slice(0, 60),
+        };
+    }
     return null;
 }
 /**
@@ -38,3 +169,57 @@ export function detectChallenge(snapshot) {
  * should pause and ask the user to complete it by hand, then re-snapshot.
  */
 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.
+ */
+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.';
+/** 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. */
+function hash(text) {
+    let value = 5381;
+    for (let index = 0; index < text.length; index += 1) {
+        value = ((value << 5) + value + text.charCodeAt(index)) >>> 0;
+    }
+    return value.toString(36);
+}
+/**
+ * Identity of one page state: URL, title, actionable-element count and the
+ * accessible labels. Two captures with the same fingerprint look the same to a
+ * human glancing at the window, which is exactly the question this tier asks.
+ * @param input - the slice of a snapshot the backstop compares.
+ * @returns an opaque fingerprint string.
+ */
+export function snapshotFingerprint(input) {
+    const names = [];
+    scan(input.nodes, 0, FINGERPRINT_DEPTH, names, MAX_FINGERPRINT_NAMES);
+    const material = [
+        input.url ?? '',
+        input.title ?? '',
+        String(input.refs ?? 0),
+        names.map((node) => node.role + '=' + node.name).join('\u0001'),
+    ].join('\u0000');
+    return hash(material);
+}
+/**
+ * The no-progress backstop: a vendor we have never seen leaves no signature, so
+ * we stop asking "which wall is this" and ask "did anything happen". Deliberately
+ * conservative — it needs an identical page AND (a nearly empty page, or a second
+ * identical result), so an ordinary click that is not meant to change anything
+ * stays quiet.
+ * @param input - whether an action just ran, the identical-capture streak, and the ref count.
+ * @returns the advisory note, or null when the page is still plausibly alive.
+ */
+export function detectNoProgress(input) {
+    if (!input.afterAction)
+        return null;
+    if (input.unchangedStreak < 1)
+        return null;
+    const nearlyEmpty = input.refs <= NO_PROGRESS_MAX_REFS;
+    if (!nearlyEmpty && input.unchangedStreak < 2)
+        return null;
+    return NO_PROGRESS_NOTE;
+}

package/lib/injected.js

@@ -203,6 +203,19 @@ export const SNAPSHOT_SCRIPT = String.raw `
     // Nearest ancestor name, used to fold a child that only repeats it.
     const inherited = typeof inheritedName === 'string' ? inheritedName : ''
     if (opts.interactiveOnly && !actionable) {
+      // Frames are the one non-actionable node kept. An iframe's accessible name
+      // is the embedded widget's own title ("reCAPTCHA", "Widget containing a
+      // Cloudflare security challenge"), and that title appears nowhere else in
+      // the tree — pruning it would hide a challenge widget from exactly the
+      // check that is supposed to recognise one.
+      if (role === 'iframe') {
+        state.count += 1
+        if (state.count > opts.maxNodes) {
+          state.truncated = true
+          return null
+        }
+        return { role, name: nameOf(el, opts.maxNameLength, opts.maxTextLength, false), children: [] }
+      }
       const kids = []
       for (const child of el.children) {
         if (SKIP_TAGS.has(child.tagName.toLowerCase())) continue

package/lib/page-actions.d.ts

@@ -26,14 +26,7 @@ export declare function assertActionable(_session: PlaywrightSession, locator: L
  * and hand the caller the pending state instead (Playwright-MCP pattern).
  */
 export declare function runAction(session: PlaywrightSession, page: Page, action: () => Promise<unknown>): Promise<ActionResult>;
-export declare function navigate(session: PlaywrightSession, url: string, waitUntil: LoadState, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot | {
-    url: string;
-    title: string;
-    nodes: never[];
-    totalRefs: number;
-    truncated: boolean;
-    dialogNote: string;
-}>;
+export declare function navigate(session: PlaywrightSession, url: string, waitUntil: LoadState, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 /**
  * Codex-style click-point resolution. Tries a scroll-alignment ladder
  * (centre, then end, then start). For each alignment: scroll the element
@@ -56,55 +49,20 @@ export declare function resolveClickPoint(session: PlaywrightSession, locator: L
  * and the landing note names what was actually clicked plus how many
  * elements shared the label.
  */
-export declare function clickText(session: PlaywrightSession, text: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot | {
-    url: string;
-    title: string;
-    nodes: never[];
-    totalRefs: number;
-    truncated: boolean;
-    dialogNote: string;
-}>;
+export declare function clickText(session: PlaywrightSession, text: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 /**
  * Shared click core: enforce the URL policy for link targets, run the
  * Codex-style geometry ladder with the Playwright actionability fallback,
  * then report what actually received the click. The label names the target
  * in the landing note; shared is how many elements matched it (0 for refs).
  */
-export declare function clickLocator(session: PlaywrightSession, locator: Locator, signal: AbortSignal | undefined, label: string, shared: number): Promise<import("./types.ts").BrowserSnapshot | {
-    url: string;
-    title: string;
-    nodes: never[];
-    totalRefs: number;
-    truncated: boolean;
-    dialogNote: string;
-}>;
-export declare function clickAt(session: PlaywrightSession, x: number, y: number, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot | {
-    url: string;
-    title: string;
-    nodes: never[];
-    totalRefs: number;
-    truncated: boolean;
-    dialogNote: string;
-}>;
-export declare function clickAtRef(session: PlaywrightSession, ref: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot | {
-    url: string;
-    title: string;
-    nodes: never[];
-    totalRefs: number;
-    truncated: boolean;
-    dialogNote: string;
-}>;
+export declare function clickLocator(session: PlaywrightSession, locator: Locator, signal: AbortSignal | undefined, label: string, shared: number): Promise<import("./types.ts").BrowserSnapshot>;
+export declare function clickAt(session: PlaywrightSession, x: number, y: number, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
+export declare function clickAtRef(session: PlaywrightSession, ref: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 export declare function fill(session: PlaywrightSession, ref: string, text: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 /** Read the field back and decide whether the fill landed. */
 export declare function verifyFill(_session: PlaywrightSession, locator: Locator, tag: string, text: string): Promise<boolean>;
-export declare function press(session: PlaywrightSession, ref: string, key: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot | {
-    url: string;
-    title: string;
-    nodes: never[];
-    totalRefs: number;
-    truncated: boolean;
-    dialogNote: string;
-}>;
+export declare function press(session: PlaywrightSession, ref: string, key: string, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 /**
  * Hover a trigger the snapshot gave no ref, addressed by its visible label
  * (e.g. a plain span that reveals a menu on mouseenter). The label must
@@ -122,13 +80,6 @@ export declare function hoverLocator(session: PlaywrightSession, locator: Locato
 export declare function scroll(session: PlaywrightSession, direction: 'up' | 'down', amount: number, ref: string | undefined, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 export declare function back(session: PlaywrightSession, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 export declare function forward(session: PlaywrightSession, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
-export declare function switchTab(session: PlaywrightSession, index: number, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot | {
-    url: string;
-    title: string;
-    nodes: never[];
-    totalRefs: number;
-    truncated: boolean;
-    dialogNote: string;
-}>;
+export declare function switchTab(session: PlaywrightSession, index: number, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 export declare function openTab(session: PlaywrightSession, url: string, waitUntil: LoadState, signal: AbortSignal | undefined): Promise<import("./types.ts").BrowserSnapshot>;
 export declare function closeTab(session: PlaywrightSession, index: number, signal: AbortSignal | undefined): Promise<void>;

package/lib/page-actions.js

@@ -630,7 +630,7 @@ export async function scroll(session, direction, amount, ref, signal) {
         // loaders a beat, then settle (bounded) before capturing.
         await withAbort(new Promise((resolve) => setTimeout(resolve, 450)), signal);
         await session.waitForPageStable(page, 1200);
-        return session.capture(page, undefined);
+        return session.capture(page, undefined, true);
     });
 }
 export async function back(session, signal) {

package/lib/page-diagnostics.js

@@ -65,11 +65,29 @@ export function trackPage(session, page) {
         });
         page.on('response', (response) => {
             const slot = session.requestEntries.get(response.request());
-            if (slot === undefined)
-                return;
-            slot.entry.status = response.status();
-            slot.entry.ms = Date.now() - slot.startedAt;
-            session.requestEntries.delete(response.request());
+            if (slot !== undefined) {
+                slot.entry.status = response.status();
+                slot.entry.ms = Date.now() - slot.startedAt;
+                session.requestEntries.delete(response.request());
+            }
+            // The main document response carries whatever the interceptor put on the
+            // wire. Challenge detection reads this before it reads a single word of the
+            // page: `cf-mitigated: challenge` is Cloudflare's published detection
+            // contract, and unlike page wording it cannot be reworded by accident.
+            try {
+                if (!response.request().isNavigationRequest())
+                    return;
+                if (response.frame() !== page.mainFrame())
+                    return;
+                session.docResponses.set(page, {
+                    status: response.status(),
+                    url: response.url(),
+                    headers: { ...response.headers() },
+                });
+            }
+            catch {
+                // A response that detached mid-flight must never break capture.
+            }
         });
         page.on('requestfailed', (request) => {
             const slot = session.requestEntries.get(request);

package/lib/page-snapshot.d.ts

@@ -80,17 +80,23 @@ export declare function captureLegacy(session: PlaywrightSession, page: Page, op
  * data-dsh-ref, so legacy and aria engines share the same contract.
  */
 export declare function attachDiff(session: PlaywrightSession, snap: BrowserSnapshot): BrowserSnapshot;
+/**
+ * Attach the main document response metadata observed for this page, when there
+ * is one. Challenge detection reads it before it reads a word of the page: a
+ * response header is the interceptor's own published API, unlike its prose.
+ */
+export declare function attachDocResponse(session: PlaywrightSession, page: Page, snap: BrowserSnapshot): BrowserSnapshot;
+/**
+ * The no-progress backstop — the tier that needs no vendor signature at all. It
+ * compares this capture's page-state fingerprint with the previous one and, for a
+ * post-action capture, appends an advisory note when nothing moved. The note says
+ * it is a guess on purpose: covering walls we have no signature for is the point.
+ */
+export declare function attachNoProgress(session: PlaywrightSession, snap: BrowserSnapshot, afterAction: boolean): BrowserSnapshot;
 /** Build ref -> feature signature map from a captured tree, with parent refs. */
 export declare function buildRefSignatures(_session: PlaywrightSession, nodes: readonly BrowserNode[]): Map<string, RefSignature>;
 export declare function snapshot(session: PlaywrightSession, opts?: {
     interactiveOnly?: boolean;
-}): Promise<BrowserSnapshot | {
-    url: string;
-    title: string;
-    nodes: never[];
-    totalRefs: number;
-    truncated: boolean;
-    dialogNote: string;
-}>;
+}): Promise<BrowserSnapshot>;
 export declare function refLocator(session: PlaywrightSession, ref: string): Promise<import("playwright-core").Locator>;
 export declare function assertLive(session: PlaywrightSession): void;

package/lib/page-snapshot.js

@@ -1,4 +1,5 @@
 import { captureAriaSnapshot } from "./snapshot-aria.js";
+import { detectNoProgress, snapshotFingerprint } from "./challenge.js";
 import { isContextDestroyed } from "./page-diagnostics.js";
 import { REF_PATTERN } from "./config.js";
 import { BrowserError } from "./errors.js";
@@ -72,7 +73,7 @@ export async function settleAndSnapshot(session, page, navChanged) {
             await page.waitForLoadState('load', { timeout: session.timeoutMs() }).catch(() => { });
         }
         await session.waitForPageStable(page, navChanged ? 1500 : 800);
-        return await session.capture(page, undefined);
+        return await session.capture(page, undefined, true);
     });
     if (raced.blocked)
         return session.blockedSnapshot(page, raced.pending);
@@ -206,6 +207,52 @@ export function attachDiff(session, snap) {
     }
     return { ...snap, diff: { added, removed, changed, same, navigationReset: false } };
 }
+/**
+ * Attach the main document response metadata observed for this page, when there
+ * is one. Challenge detection reads it before it reads a word of the page: a
+ * response header is the interceptor's own published API, unlike its prose.
+ */
+export function attachDocResponse(session, page, snap) {
+    const response = session.docResponses.get(page);
+    if (response === undefined)
+        return snap;
+    // Only the response that produced the document we are actually looking at
+    // counts. A single-page app changes the URL with no document load, and reusing
+    // the previous document's headers there would report a wall on a page that is
+    // fine. Falling back to the lower tiers is the fail-safe direction: they still
+    // run, and so does the no-progress backstop.
+    if (withoutHash(response.url) !== withoutHash(snap.url))
+        return snap;
+    return { ...snap, response };
+}
+/** URL without its fragment, for comparing a page against the response it came from. */
+function withoutHash(url) {
+    const hash = url.indexOf('#');
+    return hash === -1 ? url : url.slice(0, hash);
+}
+/**
+ * The no-progress backstop — the tier that needs no vendor signature at all. It
+ * compares this capture's page-state fingerprint with the previous one and, for a
+ * post-action capture, appends an advisory note when nothing moved. The note says
+ * it is a guess on purpose: covering walls we have no signature for is the point.
+ */
+export function attachNoProgress(session, snap, afterAction) {
+    const fingerprint = snapshotFingerprint({
+        url: snap.url,
+        title: snap.title,
+        refs: snap.totalRefs,
+        nodes: snap.nodes,
+    });
+    const identical = session.lastFingerprint !== undefined && session.lastFingerprint === fingerprint;
+    session.unchangedStreak = identical ? session.unchangedStreak + 1 : 0;
+    session.lastFingerprint = fingerprint;
+    const note = detectNoProgress({
+        afterAction,
+        unchangedStreak: session.unchangedStreak,
+        refs: snap.totalRefs,
+    });
+    return note === null ? snap : { ...snap, stallNote: note };
+}
 /** Build ref -> feature signature map from a captured tree, with parent refs. */
 export function buildRefSignatures(_session, nodes) {
     const out = new Map();