scenescout 3.17.0 → 3.19.0

package/dist/engine/memory.js

@@ -7,9 +7,11 @@ import { addReading, addVerdict, MAX_TICKETS_KEPT, mergeTicketData } from "./tic
 /**
  * The element-name rule current keys are made under. 2: a link or button with
  * no text is named by its image content (an <img>'s alt text, an <svg>'s
- * aria-label or <title>) before its title attribute.
+ * aria-label or <title>) before its title attribute. 3: that content also
+ * counts a descendant's aria-label and an <img>'s title when its alt is empty
+ * (collector.ts CONTENT_SAYS_SRC).
  */
-export const NAME_RULE = 2;
+export const NAME_RULE = 3;
 /**
  * The kinds a finding can be. One list: scout_finding's input schema, the lane
  * report a parallel agent hands back, and the skill text all read it from
@@ -278,6 +280,20 @@ export function rekeyed(elements, aliases) {
     }
     return out;
 }
+/** A route's aliases for the step that leads to `rule`: key under rule - 1 → key under rule. */
+function stepAliases(data, rule, route) {
+    return rule === 2 ? data.keyAliases?.[route] : data.ruleKeyAliases?.[String(rule)]?.[route];
+}
+/**
+ * A state's elements moved from the keys of name rule `from` to those of rule
+ * `to`, one step at a time, each through the route's aliases for that step.
+ */
+function keysUnderRule(elements, from, to, data, route) {
+    let out = elements;
+    for (let rule = from + 1; rule <= to; rule++)
+        out = rekeyed(out, stepAliases(data, rule, route));
+    return out;
+}
 /**
  * Fold another process's memory into ours, losing nothing from either side.
  *
@@ -300,6 +316,15 @@ export function mergeMemory(mine, theirs) {
     }
     if (Object.keys(out.keyAliases).length === 0)
         delete out.keyAliases;
+    out.ruleKeyAliases = {};
+    for (const rule of new Set([...Object.keys(theirs.ruleKeyAliases ?? {}), ...Object.keys(mine.ruleKeyAliases ?? {})])) {
+        const step = { ...(theirs.ruleKeyAliases?.[rule] ?? {}) };
+        for (const [route, aliases] of Object.entries(mine.ruleKeyAliases?.[rule] ?? {}))
+            step[route] = { ...aliases, ...(step[route] ?? {}) };
+        out.ruleKeyAliases[rule] = step;
+    }
+    if (Object.keys(out.ruleKeyAliases).length === 0)
+        delete out.ruleKeyAliases;
     out.states = { ...theirs.states };
     for (const [fp, ours] of Object.entries(mine.states)) {
         const other = theirs.states[fp];
@@ -308,10 +333,10 @@ export function mergeMemory(mine, theirs) {
             continue;
         }
         const nameRule = Math.max(ours.nameRule ?? 0, other.nameRule ?? 0);
-        // When one side is under the current name rule and the other is not, the
-        // other's keys are moved to current ones before the union, as a revisit
-        // moves them (MemoryStore visitState).
-        const current = (side) => nameRule >= NAME_RULE && (side.nameRule ?? 1) < NAME_RULE ? rekeyed(side.elements, out.keyAliases?.[routeIdentity(side.route)]) : side.elements;
+        // When one side is under a later name rule than the other, the other's
+        // keys are moved to that rule's before the union, as a revisit moves them
+        // (MemoryStore visitState).
+        const current = (side) => keysUnderRule(side.elements, side.nameRule ?? 1, Math.max(nameRule, 1), out, routeIdentity(side.route));
         const elements = { ...current(other) };
         for (const [key, el] of Object.entries(current(ours))) {
             const prev = elements[key];
@@ -384,6 +409,7 @@ export function mergeMemory(mine, theirs) {
     const unionRecord = (a, b) => (a || b ? { ...(b ?? {}), ...(a ?? {}) } : undefined);
     out.discoveredRoutes = unionRecord(mine.discoveredRoutes, theirs.discoveredRoutes);
     out.attemptedRoutes = unionRecord(mine.attemptedRoutes, theirs.attemptedRoutes);
+    out.resourceRoutes = unionRecord(mine.resourceRoutes, theirs.resourceRoutes);
     out.designElements = unionRecord(mine.designElements, theirs.designElements);
     out.pageScores = { ...(theirs.pageScores ?? {}) };
     for (const [route, score] of Object.entries(mine.pageScores ?? {})) {
@@ -1289,6 +1315,31 @@ export class MemoryStore {
     get discoveredRoutes() {
         return this.data.discoveredRoutes ?? {};
     }
+    /**
+     * Record that a route answered with a feed, a file or data (crawl.ts
+     * isNonPageResource). A route harvested from a link joins the contract before
+     * anything knows what it serves; this takes it back out, for every role and
+     * every later run, so a feed linked from every page is not a gap forever.
+     */
+    markResource(route, mediaType) {
+        const map = this.data.resourceRoutes ?? {};
+        if (map[route] !== mediaType) {
+            map[route] = mediaType;
+            this.data.resourceRoutes = map;
+            this.save();
+        }
+    }
+    /** A route that has since answered as a page is one again: back into the contract. */
+    clearResource(route) {
+        const map = this.data.resourceRoutes;
+        if (map && route in map) {
+            delete map[route];
+            this.save();
+        }
+    }
+    get resourceRoutes() {
+        return this.data.resourceRoutes ?? {};
+    }
     /**
      * Record that a route was attempted but landed elsewhere (e.g. auth-redirect).
      *
@@ -1827,9 +1878,10 @@ export class MemoryStore {
      * listed keys a user cannot act on (collector inertKeys): they stay known,
      * so a click on one still registers, but coverage does not count them.
      * `session` names who visited, for this run's per-session coverage.
-     * `aliases` maps a listed key to the key the same control had under the
-     * earlier name rule (fingerprint.ts keyAliases); the route keeps them so
-     * states written before the rule changed are read under current keys.
+     * `aliases` maps, for each step between name rules, a listed key to the
+     * key the same control had under the rule before (KeyAliasSteps); the route
+     * keeps them so states written before a rule changed are read under
+     * current keys.
      */
     visitState(fingerprint, url, route, elementKeys, inertKeys = [], session, aliases = {}) {
         this.runStates.add(fingerprint);
@@ -1856,7 +1908,7 @@ export class MemoryStore {
         // named like a text button beside it) leaves it unchanged. Its keys are
         // moved to the current ones before it is marked current.
         if ((rec.nameRule ?? 1) < NAME_RULE)
-            rec.elements = rekeyed(rec.elements, this.data.keyAliases?.[routeIdentity(route)]);
+            rec.elements = keysUnderRule(rec.elements, rec.nameRule ?? 1, NAME_RULE, this.data, routeIdentity(route));
         rec.nameRule = NAME_RULE;
         const present = new Set(elementKeys);
         const inert = new Set(inertKeys);
@@ -1888,16 +1940,18 @@ export class MemoryStore {
      * hand out ordinals differently, and the states written under the earlier
      * rule do not change, so neither should what their keys are read as.
      */
-    learnAliases(route, aliases) {
-        const pairs = Object.entries(aliases);
-        if (pairs.length === 0)
-            return;
-        const byRoute = (this.data.keyAliases ??= {});
+    learnAliases(route, steps) {
         const id = routeIdentity(route);
-        const known = (byRoute[id] ??= {});
-        for (const [key, prior] of pairs)
-            if (!Object.hasOwn(known, prior))
-                known[prior] = key;
+        for (const [rule, aliases] of Object.entries(steps)) {
+            const pairs = Object.entries(aliases);
+            if (pairs.length === 0)
+                continue;
+            const byRoute = rule === "2" ? (this.data.keyAliases ??= {}) : ((this.data.ruleKeyAliases ??= {})[rule] ??= {});
+            const known = (byRoute[id] ??= {});
+            for (const [key, prior] of pairs)
+                if (!Object.hasOwn(known, prior))
+                    known[prior] = key;
+        }
     }
     markExercised(fingerprint, key, action) {
         const rec = this.data.states[fingerprint];
@@ -2265,7 +2319,7 @@ export class MemoryStore {
             const route = routeIdentity(rec.route);
             const keys = only && !only.has(fp) ? null : bucket(listed, route);
             // A state written under an earlier name rule is read under current keys.
-            const elements = (rec.nameRule ?? 1) < NAME_RULE ? rekeyed(rec.elements, this.data.keyAliases?.[route]) : rec.elements;
+            const elements = keysUnderRule(rec.elements, rec.nameRule ?? 1, NAME_RULE, this.data, route);
             for (const [key, v] of Object.entries(elements)) {
                 if (v.inert)
                     bucket(inert, route).add(key);

package/dist/engine/policy.js

@@ -887,6 +887,37 @@ export function matchReadPost(entries, appUrl, url) {
     const segments = target.pathname.split("/").filter(Boolean);
     return (entries.find((e) => (e.origin ?? app) === target.origin && e.segments.length === segments.length && e.segments.every((seg, i) => seg === "*" || seg === segments[i])) ?? null);
 }
+/**
+ * The page a script's POST was sent from, for the gap ledger's list of pages
+ * observe refused a POST on. The Referer of a request the top document sent,
+ * when it is a page of the app; otherwise the page the session drives when the
+ * request is seen. A frame's Referer is its own document, which the session
+ * never navigates to, so the caller passes none for a frame's request.
+ *
+ * The Referer comes first because the session's page URL can lag: a page's
+ * script can send its first request before the browser has told Playwright
+ * that the page committed, so the session still reports the page it came
+ * from. A Referer that is the app's bare origin is set aside for the session's
+ * page: an app whose referrer policy sends only the origin would otherwise
+ * charge every page's POST to "/". The price is that the app's root page,
+ * whose own Referer is that bare origin, still relies on the session's page
+ * URL, lag and all.
+ */
+export function refusedPostPage(appUrl, referer, pageUrl) {
+    if (!referer)
+        return pageUrl;
+    let from;
+    try {
+        from = new URL(referer);
+        if (from.origin !== new URL(appUrl).origin)
+            return pageUrl;
+    }
+    catch {
+        return pageUrl;
+    }
+    const bareOrigin = from.pathname === "/" && !from.search;
+    return bareOrigin && pageUrl ? pageUrl : referer;
+}
 /** The longest body read for a GraphQL operation; a longer one cannot be vetted and is refused. */
 export const MAX_READ_POST_BODY = 100_000;
 /** A GraphQL operation that writes: `mutation` or `subscription`, then an optional name, then its variables, directives or selection. */

package/dist/engine/probes.js

@@ -1,5 +1,6 @@
 import { ACCESSIBLE_NAME_SRC, DIALOG_LIKE_SEL } from "./collector.js";
 import { focusAdvanceKey, isBrowserEngine } from "../browsers.js";
+import { focusedControl } from "./design.js";
 /**
  * Scroll ONE named region rather than the page. The page-level heuristic
  * picks the largest scrollable pane, so a smaller independently-scrolling
@@ -158,6 +159,12 @@ export async function probeOverlays(page) {
         const s = getComputedStyle(el);
         return r.width > 0 && r.height > 0 && s.visibility !== "hidden" && s.display !== "none";
       };
+      // A translucent background or a blur: what dims the page behind a modal.
+      const darkens = (s) => {
+        const m = (s.backgroundColor || "").match(/rgba?\\((\\d+)\\s*,\\s*(\\d+)\\s*,\\s*(\\d+)(?:\\s*,\\s*([0-9.]+))?/);
+        const alpha = m ? (m[4] === undefined ? 1 : Number(m[4])) : 0;
+        return (alpha > 0.05 && alpha < 0.98) || ((s.backdropFilter || "") + "").includes("blur");
+      };
       // Backdrops: fixed, near-full-viewport, visually darkening/blurring.
       const backdrops = [];
       for (const el of document.querySelectorAll("body *")) {
@@ -166,10 +173,7 @@ export async function probeOverlays(page) {
         if (s.position !== "fixed") continue;
         const r = el.getBoundingClientRect();
         if (r.width < vw * 0.9 || r.height < vh * 0.9) continue;
-        const m = (s.backgroundColor || "").match(/rgba?\\((\\d+)\\s*,\\s*(\\d+)\\s*,\\s*(\\d+)(?:\\s*,\\s*([0-9.]+))?/);
-        const alpha = m ? (m[4] === undefined ? 1 : Number(m[4])) : 0;
-        const darkens = (alpha > 0.05 && alpha < 0.98) || ((s.backdropFilter || "") + "").includes("blur");
-        if (darkens) backdrops.push(el);
+        if (darkens(s)) backdrops.push(el);
       }
       const hasContent = (el) => {
         const t = (el.textContent || "").trim();
@@ -183,12 +187,47 @@ export async function probeOverlays(page) {
       const dialogsAll = [...document.querySelectorAll('${DIALOG_LIKE_SEL}')].filter((d) => visible(d));
       // Leaked modal scroll-lock: content extends past the fold, the page
       // itself cannot scroll (overflow hidden on body/html), and NO overlay
-      // of any kind — dialog-like panel OR backdrop — is up to justify the
+      // of any kind — dialog-like panel, backdrop or framed modal — is up to justify the
       // lock; everything below the fold is unreachable and the page looks
       // perfectly healthy otherwise.
+      // A modal can also live inside a frame: the top document then holds only
+      // a pinned wrapper around a full-viewport iframe, and the dialog and its
+      // backdrop are in the frame's document, out of reach of the selectors
+      // above. Such an iframe justifies the lock when it is visible, covers the
+      // viewport, is pinned (itself or through a fixed ancestor) and is not
+      // faded out or click-through, and, when its document can be read (same
+      // origin), something in it is open: a dialog-like panel or a dimming
+      // backdrop. A frame left mounted after its modal closed holds neither.
+      // Another site's frame cannot be read, so its geometry has to do.
+      const frameOverlay = (f) => {
+        if (!visible(f)) return false;
+        const r = f.getBoundingClientRect();
+        if (r.width < vw * 0.9 || r.height < vh * 0.9) return false;
+        let pinned = false;
+        for (let e = f; e && e !== document.body; e = e.parentElement) {
+          const s = getComputedStyle(e);
+          if (Number(s.opacity) === 0 || s.pointerEvents === "none") return false;
+          if (s.position === "fixed") pinned = true;
+        }
+        if (!pinned) return false;
+        // contentDocument is null for another site's frame.
+        const doc = f.contentDocument;
+        const win = doc && doc.defaultView;
+        if (!win) return true;
+        const fw = win.innerWidth, fh = win.innerHeight;
+        const shown = (el) => { const b = el.getBoundingClientRect(); const s = win.getComputedStyle(el); return b.width > 0 && b.height > 0 && s.visibility !== "hidden" && s.display !== "none"; };
+        if ([...doc.querySelectorAll('${DIALOG_LIKE_SEL}')].some(shown)) return true;
+        return [...doc.querySelectorAll("body *")].some((el) => {
+          const s = win.getComputedStyle(el);
+          if (s.position !== "fixed" || !shown(el)) return false;
+          const b = el.getBoundingClientRect();
+          return b.width >= fw * 0.9 && b.height >= fh * 0.9 && darkens(s);
+        });
+      };
+      const framedOverlay = [...document.querySelectorAll("iframe")].some(frameOverlay);
       const docH = Math.max(document.documentElement.scrollHeight, document.body ? document.body.scrollHeight : 0);
       const ovLock = [getComputedStyle(document.documentElement).overflowY, document.body ? getComputedStyle(document.body).overflowY : ""].some((o) => o === "hidden" || o === "clip");
-      if (ovLock && docH > vh + 50 && dialogsAll.length === 0 && backdrops.length === 0) {
+      if (ovLock && docH > vh + 50 && dialogsAll.length === 0 && backdrops.length === 0 && !framedOverlay) {
         issues.push("OVERLAY: page scrolling is DISABLED (overflow hidden on body/html) with " + Math.round(docH - vh) + "px of content below the fold and NO open dialog to justify it — likely a leaked modal scroll-lock; users cannot reach the rest of the page");
       }
       if (backdrops.length === 0) return issues;
@@ -249,8 +288,11 @@ export async function probeOverlays(page) {
  * focusless. As Tab advances, the previous stop is naturally blurred, so
  * each stop's focused style (captured at visit time) can be diffed against
  * its blurred style (captured in one pass at the end) without fighting the
- * tab order. Best-effort: any failure returns an empty sample set rather
- * than failing the audit.
+ * tab order. A Tab onto a frame is followed into a same-origin frame's
+ * document and the control focused there is sampled; a press that leaves
+ * focus inside a frame it cannot read is skipped (design.ts focusedControl).
+ * Best-effort: any failure returns an empty sample set rather than failing
+ * the audit.
  */
 export async function probeFocusIndicators(page) {
     const name = page.context().browser()?.browserType().name();
@@ -261,11 +303,11 @@ export async function probeFocusIndicators(page) {
         for (let i = 0; i < 15; i++) {
             await page.keyboard.press(advanceKey);
             const info = (await page.evaluate(`(() => {
-        const el = document.activeElement;
-        if (!el || el === document.body || el === document.documentElement) return null;
+        const el = (${focusedControl.toString()})(document);
+        if (el === null || el === "frame") return el;
         if (el.hasAttribute("data-scout-focus-probe")) return "wrapped";
         el.setAttribute("data-scout-focus-probe", "${i}");
-        const s = getComputedStyle(el);
+        const s = el.ownerDocument.defaultView.getComputedStyle(el);
         const tid = el.getAttribute("data-testid");
         // Named as the snapshot names it, so an icon button reads by its aria-label here too.
         const name = (${ACCESSIBLE_NAME_SRC})(el).slice(0, 30);
@@ -273,15 +315,32 @@ export async function probeFocusIndicators(page) {
       })()`));
             if (info === null || info === "wrapped")
                 break;
+            if (info === "frame")
+                continue;
             stops.push({ i, ...info });
         }
-        await page.evaluate("document.activeElement && document.activeElement.blur && document.activeElement.blur()");
+        // Blur from the innermost focused element out, so a control focused inside a frame loses focus too.
+        await page.evaluate(`(() => {
+      const chain = [];
+      for (let d = document; d; ) {
+        const a = d.activeElement;
+        if (!a || a === d.body || a === d.documentElement) break;
+        chain.push(a);
+        d = /^i?frame$/i.test(a.tagName) ? a.contentDocument : null;
+      }
+      for (const a of chain.reverse()) if (a.blur) a.blur();
+    })()`);
+        // The marked stops live in the page and in every same-origin frame the walk followed focus into.
         const blurred = (await page.evaluate(`(() => {
       const out = {};
-      for (const el of document.querySelectorAll("[data-scout-focus-probe]")) {
-        const s = getComputedStyle(el);
-        out[el.getAttribute("data-scout-focus-probe")] = ${styleSig};
-        el.removeAttribute("data-scout-focus-probe");
+      const docs = [document];
+      for (let k = 0; k < docs.length; k++) {
+        for (const f of docs[k].querySelectorAll("iframe, frame")) if (f.contentDocument) docs.push(f.contentDocument);
+        for (const el of docs[k].querySelectorAll("[data-scout-focus-probe]")) {
+          const s = el.ownerDocument.defaultView.getComputedStyle(el);
+          out[el.getAttribute("data-scout-focus-probe")] = ${styleSig};
+          el.removeAttribute("data-scout-focus-probe");
+        }
       }
       return out;
     })()`));