autokap 1.9.4 → 1.9.6

package/dist/overlay-engine.js

@@ -57,7 +57,13 @@ export async function dismissAllOverlays(adapter) {
     catch {
         // Non-fatal
     }
-    // Pass 3: Try clicking common close patterns in AKTree
+    // Pass 3: Try clicking common close patterns in AKTree.
+    //
+    // Only hunt for a close button inside nodes that are GENUINELY overlay-like
+    // (modal/dialog/popup/toast surfaces) — not every entry in `tree.overlays`,
+    // which over-includes fixed/sticky high-z chrome (navbars, headers, sticky
+    // CTAs). Clicking a navbar control or an in-page "Skip to content" anchor is
+    // never the right move and silently scrolls the capture off-target.
     const closePatterns = [
         'close', 'dismiss', 'fermer', 'schließen', 'cerrar', 'chiudi',
         'no thanks', 'non merci', 'maybe later', 'not now', 'skip',
@@ -65,16 +71,25 @@ export async function dismissAllOverlays(adapter) {
     for (const overlay of tree.overlays) {
         if (!overlay.blocksInteraction)
             continue;
+        const overlayNode = findNodeById(tree.root, overlay.nodeId);
+        if (!overlayNode || !isGenuineOverlaySurface(overlayNode))
+            continue;
         // Look for close buttons within the overlay's subtree
-        const closeNode = findCloseButton(tree, overlay.nodeId, closePatterns);
+        const closeNode = findCloseButton(overlayNode, closePatterns);
         if (closeNode) {
             try {
                 // Build selector from the close node's sourceRef
                 const selector = buildSelectorFromSourceRef(closeNode.sourceRef);
                 if (selector) {
-                    await adapter.click(selector);
+                    // Mirror the cookie path's scroll-transparency: snapshot the page
+                    // scroll, click via JS dispatch (Playwright `dispatchEvent` never
+                    // auto-scrolls the target into view), then restore any drift so the
+                    // capture stays on the section the program navigated to.
+                    const beforeScroll = readPageScroll(tree);
+                    await adapter.click(selector, { useJsDispatch: true });
                     methods.push(`close-button:${selector}`);
                     await sleep(300);
+                    await restorePageScroll(adapter, beforeScroll);
                 }
             }
             catch {
@@ -106,20 +121,61 @@ async function readOverlaySnapshot(adapter) {
         return null;
     }
 }
-function findCloseButton(tree, overlayNodeId, patterns) {
-    // Find the overlay node first
-    const overlayNode = findNodeById(tree.root, overlayNodeId);
-    if (!overlayNode)
-        return null;
+/**
+ * True when `node` is a genuine overlay surface (a modal/dialog/popup/toast)
+ * rather than fixed/sticky page chrome. Mirrors the live-DOM `isInsideOverlay`
+ * guard the cookie path uses, but reads the already-computed AKTree signals:
+ * node type, semantic pattern/traits, and dialog/modal attributes. A bare
+ * `fixed`/`sticky` trait is NOT enough — that matches navbars and headers.
+ */
+function isGenuineOverlaySurface(node) {
+    if (node.type === 'modal')
+        return true;
+    const pattern = node.semantic?.pattern;
+    if (pattern === 'modal' || pattern === 'cookie-banner' || pattern === 'dropdown' || pattern === 'toast') {
+        return true;
+    }
+    const traits = node.semantic?.traits ?? [];
+    if (traits.includes('overlay'))
+        return true;
+    const attrs = node.attributes ?? {};
+    const role = (attrs.role || '').toLowerCase();
+    if (role === 'dialog' || role === 'alertdialog')
+        return true;
+    if (attrs['aria-modal'] === 'true')
+        return true;
+    return false;
+}
+/**
+ * True when `node` is an in-page anchor "skip" link (e.g. "Skip to content",
+ * `<a href="#main">`). These are accessibility navigation aids, never overlay
+ * close buttons — clicking one jumps the page to a fragment and the capture
+ * ends up scrolled off-target.
+ */
+function isInPageAnchorLink(node) {
+    if (node.type !== 'link')
+        return false;
+    const ref = node.sourceRef.toLowerCase();
+    // `<a href="#...">` or a resolved selector carrying an in-page href.
+    const hrefMatch = ref.match(/href="([^"]*)"/);
+    if (hrefMatch) {
+        const href = hrefMatch[1].trim();
+        return href.startsWith('#') || href === '' || href === 'javascript:void(0)';
+    }
+    return false;
+}
+function findCloseButton(overlayNode, patterns) {
     // Search for interactive close-like buttons within this subtree
     let best = null;
     function walk(node) {
-        if (node.visible && node.interactive) {
-            const label = node.label.toLowerCase();
-            const ref = node.sourceRef.toLowerCase();
-            const combined = label + ' ' + ref;
+        if (node.visible && node.interactive && !isInPageAnchorLink(node)) {
+            // Match on the accessible NAME (label + aria-label/title/value) and the
+            // explicit role/type — never the raw sourceRef. Matching the sourceRef
+            // pulled in unrelated controls whose markup merely contained "skip" or
+            // "close" (e.g. a `.skip-link` class on a content anchor).
+            const accessibleName = accessibleNameOf(node);
             for (const pattern of patterns) {
-                if (combined.includes(pattern)) {
+                if (accessibleName.includes(pattern)) {
                     // Prefer buttons over links, and shorter labels over longer ones
                     if (!best || (node.type === 'button' && best.type !== 'button') || node.label.length < best.label.length) {
                         best = node;
@@ -127,8 +183,12 @@ function findCloseButton(tree, overlayNodeId, patterns) {
                     break;
                 }
             }
-            // Also match aria-label="close" or title="close" in sourceRef
-            if (ref.includes('aria-label="close"') || ref.includes('title="close"') || ref.includes('class="close"')) {
+            // Also honour an explicit close affordance expressed via accessible
+            // attributes (aria-label/title="close"). These are unambiguous.
+            const attrs = node.attributes ?? {};
+            const ariaLabel = (attrs['aria-label'] || '').toLowerCase();
+            const title = (attrs.title || '').toLowerCase();
+            if (ariaLabel === 'close' || title === 'close') {
                 if (!best)
                     best = node;
             }
@@ -138,6 +198,39 @@ function findCloseButton(tree, overlayNodeId, patterns) {
     walk(overlayNode);
     return best;
 }
+/** Accessible name = visible label plus aria-label / title / value text. */
+function accessibleNameOf(node) {
+    const attrs = node.attributes ?? {};
+    return [node.label, attrs['aria-label'], attrs.title, attrs.value]
+        .filter((part) => typeof part === 'string' && part.length > 0)
+        .join(' ')
+        .toLowerCase();
+}
+function readPageScroll(tree) {
+    return {
+        top: tree.page?.scroll?.scrollTop ?? 0,
+        left: tree.page?.scroll?.scrollLeft ?? 0,
+    };
+}
+/**
+ * Restore the document scroll if the close click drifted the viewport. The
+ * close click uses JS dispatch (no Playwright auto-scroll), so this is a
+ * defensive belt-and-suspenders against focus-induced or fragment scroll. Uses
+ * the relative `scroll` adapter lever since no absolute setter is exposed.
+ */
+async function restorePageScroll(adapter, before) {
+    try {
+        const after = await adapter.getAKTree();
+        const top = after.page?.scroll?.scrollTop ?? 0;
+        const deltaY = top - before.top;
+        if (Math.abs(deltaY) >= 1) {
+            await adapter.scroll(deltaY > 0 ? 'up' : 'down', Math.abs(deltaY));
+        }
+    }
+    catch {
+        // Scroll restore is best-effort; never fail the dismissal over it.
+    }
+}
 function findNodeById(node, id) {
     if (node.id === id)
         return node;

package/dist/postcondition.js

@@ -4,6 +4,7 @@
  * Deterministic evaluation of postconditions after each opcode.
  * No LLM calls — purely structural checks against AKTree, URL, and screenshots.
  */
+import sharp from 'sharp';
 import { runWithProgressBudget } from './wait-contract.js';
 export async function evaluatePostcondition(adapter, spec) {
     const maxWait = spec.waitMs ?? 5000;
@@ -80,7 +81,15 @@ async function checkRouteMatches(adapter, pattern) {
         const { pathname, search } = new URL(url);
         const fullPath = pathname + search;
         const regex = compileRoutePattern(pattern);
-        if (regex.test(fullPath) || regex.test(pathname)) {
+        // Only patterns that explicitly mention the query string (`?`) are tested
+        // against pathname+search; bare patterns match the pathname ONLY. Otherwise
+        // the search concatenation lets `/dashboard` falsely "match"
+        // `/login?next=/dashboard`, defeating login-failure detection.
+        const matchesQuery = pattern.includes('?');
+        const matched = matchesQuery
+            ? regex.test(fullPath) || regex.test(pathname)
+            : regex.test(pathname);
+        if (matched) {
             return { passed: true, reason: `URL "${fullPath}" matches pattern "${pattern}"` };
         }
         return { passed: false, reason: `URL "${fullPath}" does not match pattern "${pattern}"` };
@@ -122,13 +131,24 @@ function compileRoutePattern(pattern) {
             regexStr += ch;
         }
     }
-    // Substring (contains) match — NOT anchored. Generated programs author bare
-    // patterns that are either a prefix of the real path (`/projects/` ⊂
-    // `/projects/<id>`) or a nested segment (`/tracking` ⊂
+    // Substring (contains) match — NOT anchored at the start. Generated programs
+    // author bare patterns that are either a prefix of the real path (`/projects/`
+    // ⊂ `/projects/<id>`) or a nested segment (`/tracking` ⊂
     // `/projects/<id>/tracking`). An anchored `^…$` could match neither, which
     // surfaced as a misleading "page stuck, no progress" failure after the
     // navigation had actually succeeded. Callers needing strict matching pass an
     // anchored regex (handled above).
+    //
+    // We DO anchor the *end* on a segment boundary so a bare `/home` no longer
+    // matches `/home-old` (and `/dashboard` no longer matches `/dashboard-v2`).
+    // Skip the terminator when the pattern already ends in a glob (`*`/`**`, which
+    // consume their own boundary) or a trailing `/` (an explicit prefix match like
+    // `/projects/` that should match `/projects/<id>`).
+    const endsInGlob = pattern.endsWith('*');
+    const endsInSlash = pattern.endsWith('/');
+    if (!endsInGlob && !endsInSlash) {
+        regexStr += '(?:/|$)';
+    }
     return new RegExp(regexStr);
 }
 async function checkElementVisible(adapter, selector) {
@@ -250,14 +270,14 @@ async function checkScreenshotStable(adapter, threshold, context) {
             context.lastScreenshot = screenshot;
             await sleep(250);
             const screenshot2 = await adapter.takeScreenshot();
-            const diff = sampledBufferDiffRatio(screenshot, screenshot2);
+            const diff = await pixelDiffRatio(screenshot, screenshot2);
             context.lastScreenshot = screenshot2;
             if (diff <= threshold) {
                 return { passed: true, reason: `consecutive screenshots stable (diff=${diff.toFixed(4)})` };
             }
             return { passed: false, reason: `consecutive screenshots differ (diff=${diff.toFixed(4)})` };
         }
-        const diff = sampledBufferDiffRatio(context.lastScreenshot, screenshot);
+        const diff = await pixelDiffRatio(context.lastScreenshot, screenshot);
         context.lastScreenshot = screenshot;
         if (diff <= threshold) {
             return { passed: true, reason: `screenshot stable (diff=${diff.toFixed(4)})` };
@@ -343,20 +363,57 @@ function matchesSelectorHeuristic(sourceRef, selector) {
     // Fallback: contains
     return lower.includes(selectorLower);
 }
-function sampledBufferDiffRatio(a, b) {
-    const maxLength = Math.max(a.length, b.length);
-    if (maxLength === 0)
+/** A pixel counts as changed only if a channel moves by more than this (out of 255). */
+const PIXEL_CHANNEL_TOLERANCE = 8;
+/**
+ * Real normalized per-pixel diff ratio between two screenshots.
+ *
+ * The previous implementation byte-diffed the *compressed* PNG buffers, where a
+ * single changed pixel reshuffles the deflate stream and yields ratios of
+ * ~0.5-0.75 — far above the 0.01 stability threshold. So `screenshot_stable`
+ * never passed on pages with any animation (blinking caret, clock, CSS anim)
+ * and surfaced as a false "page stuck" failure.
+ *
+ * We now decode both PNGs to raw RGBA via `sharp` and count the fraction of
+ * pixels that moved on any channel beyond a small tolerance. The returned ratio
+ * is in [0, 1], preserving the existing `diff <= threshold` semantics.
+ */
+async function pixelDiffRatio(a, b) {
+    if (a.length === b.length && a.equals(b))
+        return 0;
+    let decodedA;
+    let decodedB;
+    try {
+        [decodedA, decodedB] = await Promise.all([
+            sharp(a).ensureAlpha().raw().toBuffer({ resolveWithObject: true }),
+            sharp(b).ensureAlpha().raw().toBuffer({ resolveWithObject: true }),
+        ]);
+    }
+    catch {
+        // Undecodable buffers (e.g. a stubbed adapter): treat as fully different if
+        // the bytes differ at all, fully stable otherwise. Never claim stability on
+        // content we cannot inspect.
+        return 1;
+    }
+    // Dimension change is a wholesale layout change — treat as fully different.
+    if (decodedA.info.width !== decodedB.info.width || decodedA.info.height !== decodedB.info.height) {
+        return 1;
+    }
+    const da = decodedA.data;
+    const db = decodedB.data;
+    const totalPixels = decodedA.info.width * decodedA.info.height;
+    if (totalPixels === 0)
         return 0;
-    const sampleCount = Math.min(10000, maxLength);
-    const step = Math.max(1, Math.floor(maxLength / sampleCount));
-    let checked = 0;
     let changed = 0;
-    for (let i = 0; i < maxLength; i += step) {
-        checked++;
-        if (a[i] !== b[i])
+    for (let i = 0; i < da.length; i += 4) {
+        if (Math.abs(da[i] - db[i]) > PIXEL_CHANNEL_TOLERANCE ||
+            Math.abs(da[i + 1] - db[i + 1]) > PIXEL_CHANNEL_TOLERANCE ||
+            Math.abs(da[i + 2] - db[i + 2]) > PIXEL_CHANNEL_TOLERANCE ||
+            Math.abs(da[i + 3] - db[i + 3]) > PIXEL_CHANNEL_TOLERANCE) {
             changed++;
+        }
     }
-    return checked === 0 ? 0 : changed / checked;
+    return changed / totalPixels;
 }
 function normalizeText(value) {
     return value.replace(/\s+/g, ' ').trim();

package/dist/recovery-chain.js

@@ -181,8 +181,7 @@ async function tryAltInteraction(opcode, adapter, _credentials) {
         const tree = await adapter.getAKTree();
         const node = findInteractiveNodeBySelector(tree, sel);
         if (node) {
-            const x = node.bounds.x + node.bounds.w / 2;
-            const y = node.bounds.y + node.bounds.h / 2;
+            const { x, y } = nodeCenterViewportPoint(node, tree);
             await adapter.click(sel, { coordinates: { x, y } });
             await sleep(500);
             const postcondition = await evaluatePostcondition(adapter, opcode.postcondition);
@@ -341,7 +340,7 @@ function cloneOpcodeWithSelector(opcode, newSelector) {
 }
 function findInteractiveNodeBySelector(tree, selector) {
     function walk(node) {
-        if (node.visible && node.interactive && node.sourceRef.includes(selector.replace(/[[\]"#.]/g, ''))) {
+        if (node.visible && node.interactive && matchesNodeSelectorHeuristic(node, selector)) {
             return node;
         }
         for (const child of node.children) {
@@ -353,15 +352,81 @@ function findInteractiveNodeBySelector(tree, selector) {
     }
     return walk(tree.root);
 }
+/**
+ * Heuristic match between an AKTree node and a CSS-like selector. Mirrors the
+ * canonical matcher in `postcondition.ts` (which is module-private there) so
+ * coordinate-fallback recovery resolves the *same* node a postcondition would.
+ *
+ * The previous `sourceRef.includes(selector.replace(/[[\]"#.]/g, ''))` was
+ * doubly wrong: it stripped the selector's structural characters but compared
+ * against the raw `sourceRef`, so `[data-ak="x"]` (stripped to `data-akx`)
+ * never matched, while `#a` (stripped to `a`) matched any sourceRef containing
+ * an "a".
+ */
+function matchesNodeSelectorHeuristic(node, selector) {
+    if (node.sourceRef && matchesSelectorHeuristic(node.sourceRef, selector)) {
+        return true;
+    }
+    const attrMatch = selector.match(/\[([a-z0-9_-]+)=["'](.+?)["']\]/i);
+    if (attrMatch) {
+        const [, attr, rawValue] = attrMatch;
+        return (node.attributes[attr] ?? '').toLowerCase() === rawValue.toLowerCase();
+    }
+    if (selector.startsWith('#')) {
+        return (node.attributes.id ?? '').toLowerCase() === selector.slice(1).toLowerCase();
+    }
+    return false;
+}
+function matchesSelectorHeuristic(sourceRef, selector) {
+    const lower = sourceRef.toLowerCase();
+    const selectorLower = selector.toLowerCase();
+    if (selectorLower === lower) {
+        return true;
+    }
+    // Generic attribute selector match, including AutoKap's canonical data-ak
+    // selectors and legacy test-id selectors.
+    const attrMatch = selector.match(/\[([a-z0-9_-]+)=["'](.+?)["']\]/i);
+    if (attrMatch) {
+        const [, attr, rawValue] = attrMatch;
+        const value = rawValue.toLowerCase();
+        return lower === `[${attr.toLowerCase()}="${value}"]`
+            || lower.includes(`[${attr.toLowerCase()}="${value}"]`)
+            || lower.includes(`${attr.toLowerCase()}="${value}"`);
+    }
+    // ID match
+    if (selector.startsWith('#')) {
+        return lower.includes(`id="${selector.slice(1)}"`) || lower.includes(`#${selector.slice(1)}`);
+    }
+    // Tag name match
+    if (/^[a-z][a-z0-9]*$/i.test(selector)) {
+        return lower.startsWith(`<${selectorLower}`) || lower.includes(`<${selectorLower} `);
+    }
+    // Fallback: contains
+    return lower.includes(selectorLower);
+}
 async function resolveSelectorCoordinates(adapter, selector) {
     const tree = await adapter.getAKTree();
     const node = findInteractiveNodeBySelector(tree, selector);
     if (!node) {
         throw new Error(`healer could not resolve coordinates for selector "${selector}"`);
     }
+    return nodeCenterViewportPoint(node, tree);
+}
+/**
+ * Center point of an AKTree node in *viewport* coordinates.
+ *
+ * AKTree bounds are document-absolute (`rect.x + window.scrollX`, see
+ * `Browser.buildAKNode`), but `adapter.click({ coordinates })` ultimately
+ * routes to `page.mouse.click`, which is viewport-relative. Without subtracting
+ * the live scroll offset, a coordinate click after any SCROLL lands off-screen
+ * (mirrors the transform in `Browser.clickAKNodeEntryByBounds`).
+ */
+function nodeCenterViewportPoint(node, tree) {
+    const scrollX = tree.page.scroll.scrollLeft;
+    const scrollY = tree.page.scroll.scrollTop;
     return {
-        x: node.bounds.x + node.bounds.w / 2,
-        y: node.bounds.y + node.bounds.h / 2,
+        x: node.bounds.x + node.bounds.w / 2 - scrollX,
+        y: node.bounds.y + node.bounds.h / 2 - scrollY,
     };
 }
 function sleep(ms) {

package/dist/security.d.ts

@@ -17,10 +17,18 @@ export interface SecurityDecision {
     target?: InteractiveElement | null;
 }
 /**
- * Is `candidateUrl` part of the same first-party site as `scopeUrl`? Shares the
- * navigation site-scope model (`isWithinProjectScope`): exact-host for IPs /
- * localhost / shared-hosting suffixes (so sibling `*.vercel.app` previews are
- * NOT same-site), sub-domain family match for real registrable domains.
+ * Is `candidateUrl` part of the same first-party site as `scopeUrl`, for the
+ * purpose of the PROGRESS signal and analytics-blocking (NOT navigation
+ * guarding)? This is deliberately MORE permissive than the navigation
+ * site-scope model so the app's own backend on a sibling host/port still reads
+ * as first-party:
+ *  - real domains: same registrable domain (eTLD+1) match — `app.example.com`,
+ *    `api.example.com` and `example.com` are all the same site (the navigation
+ *    guard, in contrast, requires a strict sub-domain match);
+ *  - localhost / private IPs: same host, REGARDLESS of port — a Vite app on
+ *    `:5173` calling its API on `:3000` is the same first-party app;
+ *  - shared-hosting suffixes (`*.vercel.app`, …): exact host (so sibling
+ *    previews stay foreign — they are genuinely distinct sites).
  *
  * Used to scope the adaptive-wait progress signal (AUT-240) to the app's own
  * traffic, so third-party telemetry (PostHog beacons, analytics/ad pixels,
@@ -35,6 +43,15 @@ export interface SecurityDecision {
  *    navigation commits) ⇒ true (don't filter);
  *  - non-http(s) `candidateUrl` (`data:` / `blob:` / `about:`) ⇒ true (in-page
  *    resource).
+ *
+ * NOTE: this MUST NOT be used to gate navigation — it intentionally does not use
+ * the navigation `isWithinProjectScope` model. Use `isAllowedNavigation` there.
+ */
+export declare function isFirstPartyForProgress(scopeUrl: string | null | undefined, candidateUrl: string): boolean;
+/**
+ * Back-compat alias for the progress / analytics first-party predicate.
+ * @deprecated Prefer {@link isFirstPartyForProgress}; this name is kept so the
+ * progress listeners and analytics-block guard keep compiling unchanged.
  */
 export declare function isFirstPartyUrl(scopeUrl: string | null | undefined, candidateUrl: string): boolean;
 export declare function evaluateResolvedActionSecurity(action: ActionType, args: Record<string, unknown>, context: SecurityContext, target: InteractiveElement | null): SecurityDecision;

package/dist/security.js

@@ -106,6 +106,41 @@ function isLocalHostname(hostname) {
 function isSharedHostingHostname(hostname) {
     return SHARED_HOSTING_SUFFIXES.some(suffix => hostname === suffix || hostname.endsWith(`.${suffix}`));
 }
+/**
+ * Multi-label public suffixes where the registrable domain is the last THREE
+ * labels (e.g. `example.co.uk`), not the usual two. Conservative, dependency-free
+ * subset (no bundled PSL) covering the common ccTLD second levels — enough to
+ * avoid collapsing `a.example.co.uk` and `b.other.co.uk` to a shared `co.uk`.
+ */
+const TWO_LABEL_PUBLIC_SUFFIXES = new Set([
+    'co.uk', 'org.uk', 'gov.uk', 'ac.uk', 'me.uk', 'ltd.uk', 'plc.uk', 'net.uk',
+    'com.au', 'net.au', 'org.au', 'edu.au', 'gov.au', 'id.au',
+    'co.nz', 'net.nz', 'org.nz', 'govt.nz',
+    'co.jp', 'or.jp', 'ne.jp', 'go.jp', 'ac.jp',
+    'com.br', 'net.br', 'org.br', 'gov.br',
+    'co.in', 'net.in', 'org.in', 'gov.in',
+    'com.cn', 'net.cn', 'org.cn', 'gov.cn',
+    'co.za', 'org.za', 'gov.za',
+    'co.kr', 'or.kr', 'go.kr',
+    'com.mx', 'com.tr', 'com.sg', 'com.hk', 'com.tw',
+]);
+/**
+ * The registrable domain (eTLD+1) of a hostname, e.g. `app.example.com` and
+ * `api.example.com` both reduce to `example.com`. Returns the host unchanged
+ * when it has too few labels to reduce. Conservative public-suffix handling via
+ * {@link TWO_LABEL_PUBLIC_SUFFIXES}; callers must only use this for the
+ * progress signal (fail-open), never for the navigation-scope guard.
+ */
+function registrableDomain(hostname) {
+    const labels = hostname.split('.');
+    if (labels.length <= 2)
+        return hostname;
+    const lastTwo = labels.slice(-2).join('.');
+    if (TWO_LABEL_PUBLIC_SUFFIXES.has(lastTwo)) {
+        return labels.slice(-3).join('.');
+    }
+    return lastTwo;
+}
 function normalizeScopeHostname(hostname) {
     return hostname.startsWith('www.') ? hostname.slice(4) : hostname;
 }
@@ -135,10 +170,18 @@ function buildNavigationScopes(context) {
     return Array.from(dedup.values());
 }
 /**
- * Is `candidateUrl` part of the same first-party site as `scopeUrl`? Shares the
- * navigation site-scope model (`isWithinProjectScope`): exact-host for IPs /
- * localhost / shared-hosting suffixes (so sibling `*.vercel.app` previews are
- * NOT same-site), sub-domain family match for real registrable domains.
+ * Is `candidateUrl` part of the same first-party site as `scopeUrl`, for the
+ * purpose of the PROGRESS signal and analytics-blocking (NOT navigation
+ * guarding)? This is deliberately MORE permissive than the navigation
+ * site-scope model so the app's own backend on a sibling host/port still reads
+ * as first-party:
+ *  - real domains: same registrable domain (eTLD+1) match — `app.example.com`,
+ *    `api.example.com` and `example.com` are all the same site (the navigation
+ *    guard, in contrast, requires a strict sub-domain match);
+ *  - localhost / private IPs: same host, REGARDLESS of port — a Vite app on
+ *    `:5173` calling its API on `:3000` is the same first-party app;
+ *  - shared-hosting suffixes (`*.vercel.app`, …): exact host (so sibling
+ *    previews stay foreign — they are genuinely distinct sites).
  *
  * Used to scope the adaptive-wait progress signal (AUT-240) to the app's own
  * traffic, so third-party telemetry (PostHog beacons, analytics/ad pixels,
@@ -153,8 +196,11 @@ function buildNavigationScopes(context) {
  *    navigation commits) ⇒ true (don't filter);
  *  - non-http(s) `candidateUrl` (`data:` / `blob:` / `about:`) ⇒ true (in-page
  *    resource).
+ *
+ * NOTE: this MUST NOT be used to gate navigation — it intentionally does not use
+ * the navigation `isWithinProjectScope` model. Use `isAllowedNavigation` there.
  */
-export function isFirstPartyUrl(scopeUrl, candidateUrl) {
+export function isFirstPartyForProgress(scopeUrl, candidateUrl) {
     const scopeParsed = parseHttpUrl(scopeUrl ?? undefined);
     if (!scopeParsed)
         return true;
@@ -167,7 +213,28 @@ export function isFirstPartyUrl(scopeUrl, candidateUrl) {
     }
     if (candidate.protocol !== 'http:' && candidate.protocol !== 'https:')
         return true;
-    return isWithinProjectScope(candidate, [scopeFromParsedUrl(scopeParsed)]);
+    const scopeHost = scopeParsed.hostname.toLowerCase();
+    const candidateHost = candidate.hostname.toLowerCase();
+    // localhost / private IPs: same host is first-party regardless of port (the
+    // dev server and its API commonly live on different ports of the same host).
+    if (isLocalHostname(scopeHost) || isIpv4Hostname(scopeHost) || isIpv6Hostname(scopeHost)) {
+        return candidateHost === scopeHost;
+    }
+    // Shared-hosting previews are distinct sites: keep exact-host so a sibling
+    // `*.vercel.app` beacon never masquerades as first-party progress.
+    if (isSharedHostingHostname(scopeHost)) {
+        return candidateHost === scopeHost || candidateHost.endsWith(`.${scopeHost}`);
+    }
+    // Real registrable domain: any candidate sharing the eTLD+1 is first-party.
+    return registrableDomain(candidateHost) === registrableDomain(scopeHost);
+}
+/**
+ * Back-compat alias for the progress / analytics first-party predicate.
+ * @deprecated Prefer {@link isFirstPartyForProgress}; this name is kept so the
+ * progress listeners and analytics-block guard keep compiling unchanged.
+ */
+export function isFirstPartyUrl(scopeUrl, candidateUrl) {
+    return isFirstPartyForProgress(scopeUrl, candidateUrl);
 }
 function isWithinProjectScope(candidate, scopes) {
     const hostname = candidate.hostname.toLowerCase();

package/dist/wait-contract.d.ts

@@ -47,16 +47,30 @@ export declare const PIXEL_FALLBACK_DIFF_THRESHOLD = 0.01;
  */
 export declare function resolveGlobalWaitDeadlineMs(startedAtMs: number, compiledTimeoutMs: number, mediaMode: MediaMode): number;
 /**
- * Did the page make observable progress between two snapshots? Any of: a
- * navigation in flight, new network events, in-flight count change, network
- * activity advancing, readyState change, or DOM node-count change. A null
- * current reading is treated conservatively as "no progress"; the first real
- * reading (null `prev`) counts as progress to seed the watchdog window.
+ * Did the page make observable, CORROBORATED progress between two snapshots?
+ * Progress is one of:
+ *  - a navigation in flight (`navigating`);
+ *  - a first-party request COMPLETING — a net decrease in `inflightRequests`
+ *    (something finished or failed, i.e. a response the page can act on);
+ *  - a `readyState` transition;
+ *  - a `domNodeCount` change (the page rendered/mutated something).
  *
- * The network fields are first-party-scoped at the source (see
- * `getProgressSnapshot` / `isFirstPartyUrl`): background third-party telemetry
- * (analytics beacons, ad pixels, polling to other origins) is excluded, so it
- * cannot keep this `true` forever and starve the stuck-cut.
+ * A null current reading is treated conservatively as "no progress"; the first
+ * real reading (null `prev`) counts as progress to seed the watchdog window.
+ *
+ * Deliberately does NOT key on monotonic counters that a steady self-poll bumps
+ * forever (`networkEventCount`, `lastNetworkActivityAtMs`) nor on a request
+ * merely STARTING (an INCREASE in `inflightRequests`): an app polling its own
+ * origin every tick would otherwise keep this `true` indefinitely, `lastProgressAt`
+ * would keep resetting, and the stuck-cut would never fire — burning the global
+ * deadline and skipping recovery (AUT-240 D2). Requiring a completion or a
+ * DOM/readyState change means real loads (requests resolve, the DOM fills,
+ * readyState advances) still register, while idle chatter does not.
+ *
+ * The network fields are also first-party-scoped at the source (see
+ * `getProgressSnapshot` / `isFirstPartyForProgress`): background third-party
+ * telemetry (analytics beacons, ad pixels, polling to other origins) is
+ * excluded so it cannot masquerade as the app's own work.
  */
 export declare function hasProgress(prev: ProgressSnapshot | null | undefined, cur: ProgressSnapshot | null | undefined): boolean;
 export type ProgressBudgetCut = 'stuck' | 'deadline';

package/dist/wait-contract.js

@@ -53,16 +53,30 @@ export function resolveGlobalWaitDeadlineMs(startedAtMs, compiledTimeoutMs, medi
     return startedAtMs + Math.max(compiledTimeoutMs, cap);
 }
 /**
- * Did the page make observable progress between two snapshots? Any of: a
- * navigation in flight, new network events, in-flight count change, network
- * activity advancing, readyState change, or DOM node-count change. A null
- * current reading is treated conservatively as "no progress"; the first real
- * reading (null `prev`) counts as progress to seed the watchdog window.
+ * Did the page make observable, CORROBORATED progress between two snapshots?
+ * Progress is one of:
+ *  - a navigation in flight (`navigating`);
+ *  - a first-party request COMPLETING — a net decrease in `inflightRequests`
+ *    (something finished or failed, i.e. a response the page can act on);
+ *  - a `readyState` transition;
+ *  - a `domNodeCount` change (the page rendered/mutated something).
  *
- * The network fields are first-party-scoped at the source (see
- * `getProgressSnapshot` / `isFirstPartyUrl`): background third-party telemetry
- * (analytics beacons, ad pixels, polling to other origins) is excluded, so it
- * cannot keep this `true` forever and starve the stuck-cut.
+ * A null current reading is treated conservatively as "no progress"; the first
+ * real reading (null `prev`) counts as progress to seed the watchdog window.
+ *
+ * Deliberately does NOT key on monotonic counters that a steady self-poll bumps
+ * forever (`networkEventCount`, `lastNetworkActivityAtMs`) nor on a request
+ * merely STARTING (an INCREASE in `inflightRequests`): an app polling its own
+ * origin every tick would otherwise keep this `true` indefinitely, `lastProgressAt`
+ * would keep resetting, and the stuck-cut would never fire — burning the global
+ * deadline and skipping recovery (AUT-240 D2). Requiring a completion or a
+ * DOM/readyState change means real loads (requests resolve, the DOM fills,
+ * readyState advances) still register, while idle chatter does not.
+ *
+ * The network fields are also first-party-scoped at the source (see
+ * `getProgressSnapshot` / `isFirstPartyForProgress`): background third-party
+ * telemetry (analytics beacons, ad pixels, polling to other origins) is
+ * excluded so it cannot masquerade as the app's own work.
  */
 export function hasProgress(prev, cur) {
     if (!cur)
@@ -71,9 +85,7 @@ export function hasProgress(prev, cur) {
         return true;
     if (!prev)
         return true;
-    return (cur.networkEventCount !== prev.networkEventCount
-        || cur.inflightRequests !== prev.inflightRequests
-        || cur.lastNetworkActivityAtMs !== prev.lastNetworkActivityAtMs
+    return (cur.inflightRequests < prev.inflightRequests
         || cur.readyState !== prev.readyState
         || cur.domNodeCount !== prev.domNodeCount);
 }