scenescout 3.17.0 → 3.19.0

package/dist/engine/check.js

@@ -13,6 +13,7 @@
 import { createHash } from "node:crypto";
 import { BROWSER_ENGINES } from "../browsers.js";
 import { BASELINE_MODES, baselineEvidence, baselineFingerprint, countStatuses, describeChange, parseThreshold, VISUAL_RULE, } from "./baseline.js";
+import { isNonPageResource } from "./crawl.js";
 import { flowStepEvidence } from "./flow.js";
 import { parseLimitFlag } from "./limits.js";
 import { redactRoute, redactSecrets } from "./memory.js";
@@ -20,6 +21,23 @@ import { SARIF_ANCHOR_FALLBACKS, checkSarifAnchor, sarifFileFor, sarifLocation }
 import { httpErrorDetail, httpStatusOf } from "./oracles.js";
 export const CHECK_SEVERITIES = ["high", "medium", "low"];
 export const FAIL_ON = [...CHECK_SEVERITIES, "never"];
+/**
+ * The routes that answered as pages, and those that answered as something
+ * else. Only the pages are checked against the page rules and counted as
+ * routes; the rest are listed apart, so a feed or a licence file is neither a
+ * dead end nor a page the check claims to have measured.
+ */
+export function splitResources(routes) {
+    const pages = [];
+    const resources = [];
+    for (const r of routes) {
+        if (isNonPageResource(r) && r.status !== null && r.contentType)
+            resources.push({ path: r.path, status: r.status, contentType: r.contentType });
+        else
+            pages.push(r);
+    }
+    return { pages, resources };
+}
 export const CHECK_RULES = {
     "route-load-failed": { severity: "high", title: "Page did not load", help: "Navigating to the route failed or timed out." },
     "route-server-error": { severity: "high", title: "Page answered with a server error", help: "The document itself returned HTTP 5xx." },
@@ -45,7 +63,11 @@ export const CHECK_RULES = {
         title: "Credential posted to any origin",
         help: 'The page called postMessage with targetOrigin "*" and a token-shaped value in the message, so whatever origin the receiving window holds can read it. The value is never reported: its path in the message, its shape and its first four characters are.',
     },
-    "auth-redirect": { severity: "medium", title: "Sent to sign-in", help: "The route redirected to a sign-in page; the session is missing or expired." },
+    "auth-redirect": {
+        severity: "medium",
+        title: "Sent to sign-in",
+        help: "The route redirected to a sign-in page although the check was given a signed-in session, so the session is missing or expired. With no session given, such a route is listed as needing sign-in instead.",
+    },
     "dead-end": { severity: "medium", title: "Dead end", help: "The page has no controls at all: no navigation and no way back." },
     "blocking-overlay": {
         severity: "high",
@@ -81,7 +103,11 @@ export const CHECK_RULES = {
         title: "Field labelled only by its placeholder",
         help: "The field has no label, aria-label, aria-labelledby or title. Its placeholder is not a label: it disappears as soon as the user types, and some assistive technology does not announce it.",
     },
-    contrast: { severity: "low", title: "Text contrast below WCAG", help: "Text needs 4.5:1 (3:1 when large) against its background." },
+    contrast: {
+        severity: "low",
+        title: "Text contrast below WCAG",
+        help: "Text needs 4.5:1 (3:1 when large) against its background. Text over an image, gradient, video or canvas has no single background colour and is not measured.",
+    },
     "focus-indicator": { severity: "low", title: "No visible focus indicator", help: "Tabbing to the control changes nothing on screen." },
     "horizontal-scroll": { severity: "medium", title: "Page scrolls sideways", help: "Content is wider than the viewport." },
     "tiny-target": {
@@ -214,8 +240,15 @@ export function geometryRule(line) {
  * `--ignore-path` drops a fact on the route it names, or one rule there,
  * before the fact is filed. A fact also seen on a route that is not exempted
  * stays, on that route alone.
+ *
+ * A route that sends the browser to sign-in is an `auth-redirect` issue only
+ * when the check was `signedIn`: then a session it was given was lost. With
+ * no session, sending a signed-out visitor to sign-in is the route working,
+ * so it goes to `needsSignIn` instead, a coverage gap rather than a defect.
+ * The default is signed in, so a caller that does not say never hides one.
  */
-export function checkFindings(routes, origin, ignore = [], flows = [], baselines = null, ignorePaths = []) {
+export function checkFindings(routes, origin, ignore = [], flows = [], baselines = null, ignorePaths = [], signedIn = true) {
+    const needsSignIn = [];
     const byKey = new Map();
     const looks = new Map();
     /** A route (and, when named, one rule on it) that --ignore-path exempts. */
@@ -254,6 +287,10 @@ export function checkFindings(routes, origin, ignore = [], flows = [], baselines
     };
     for (const r of routes) {
         const route = r.path;
+        // A feed, a text file or an image is not a page: it has no controls to judge. Only one that answered without an
+        // error is one (crawl.ts isNonPageResource), so a feed that fails reaches the route's own error below.
+        if (isNonPageResource(r))
+            continue;
         if (r.loadError !== undefined) {
             add("route-load-failed", `${route}: ${r.loadError}`, route);
             continue;
@@ -262,7 +299,12 @@ export function checkFindings(routes, origin, ignore = [], flows = [], baselines
             add("route-server-error", `${route} → HTTP ${r.status}`, route);
         else if (r.status !== null && r.status >= 400)
             add("route-client-error", `${route} → HTTP ${r.status}`, route);
-        if (r.loginRedirect)
+        if (r.loginRedirect && !signedIn) {
+            // An --ignore-path exemption takes the route off the list too; --ignore auth-redirect does not, since this is coverage, not that rule.
+            if (!exempt("auth-redirect", route) && !needsSignIn.includes(route))
+                needsSignIn.push(route);
+        }
+        else if (r.loginRedirect)
             add("auth-redirect", `${route} → ${withoutOrigin(r.url, origin) || "/"}`, route);
         else if (r.elements === 0 && (r.status === null || r.status < 400))
             add("dead-end", `${route}: 0 controls`, route);
@@ -310,21 +352,39 @@ export function checkFindings(routes, origin, ignore = [], flows = [], baselines
     return {
         issues: [...byKey.values(), ...visual].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.rule.localeCompare(b.rule)),
         worthALook: [...looks.values()].sort((a, b) => a.rule.localeCompare(b.rule)),
+        needsSignIn,
     };
 }
 /** The defect tier of `checkFindings`: what counts, and what the gate reads. */
-export function issuesFromRoutes(routes, origin, ignore = [], flows = [], ignorePaths = []) {
-    return checkFindings(routes, origin, ignore, flows, null, ignorePaths).issues;
+export function issuesFromRoutes(routes, origin, ignore = [], flows = [], ignorePaths = [], signedIn = true) {
+    return checkFindings(routes, origin, ignore, flows, null, ignorePaths, signedIn).issues;
 }
+/**
+ * Fewest controls a start page must show for a check that measured nothing
+ * else to count as having measured the app (unmeasuredReason).
+ */
+export const START_PAGE_MIN_CONTROLS = 2;
 /**
  * Why a check has nothing to give a verdict on, or null when it measured the
  * app. Neither case is a pass: a gate that goes green on a login page or a
  * dead server would pass every pull request while the app was down.
  */
-export function unmeasuredReason(routes, startIsFirst) {
+export function unmeasuredReason(routes, startIsFirst, unvisited = []) {
     const loaded = routes.filter((r) => r.loadError === undefined);
     if (loaded.length === 0)
         return "no page loaded. Is the app running at that URL?";
+    // A start page measured before the app drew it (a client-rendered shell still loading, a blank page) links nowhere,
+    // so the crawl ends there and every rule is silent: a pass that checked nothing. A real one-page app has controls.
+    const start = routes[0];
+    // `unvisited` empty: the page linked nowhere. A crawl that --max-routes cut short did find more, and measured what it was asked to.
+    if (startIsFirst &&
+        unvisited.length === 0 &&
+        loaded.length === 1 &&
+        start === loaded[0] &&
+        !start.loginRedirect &&
+        start.elements < START_PAGE_MIN_CONTROLS) {
+        return `only the start page was measured, and it showed ${start.elements} control(s) and linked nowhere, so the app may not have finished drawing. Check again, raise --nav-timeout-ms if the app is slow to render, pass --project so routes come from the source, or name them with --paths.`;
+    }
     // Without --paths the first route is the start page. When it bounces, what follows is the sign-in
     // page's own links (sign-up, forgot password): pages that load, but not the app.
     // With --paths there is no start page, only a list, and one walled path among public ones is an auth-redirect issue.
@@ -818,7 +878,7 @@ const BASELINE_MARK = {
 /** One target's line in the report. */
 function baselineLine(r, run) {
     const what = `${BASELINE_MARK[r.status]} ${code(r.element)} on ${code(r.path)}`;
-    const notes = [r.platformNote, r.partial]
+    const notes = [r.platformNote, r.partial, r.unsteady]
         .filter(Boolean)
         .map((n) => ` _(${cell(n)})_`)
         .join("");
@@ -916,6 +976,42 @@ export function routesTable(result) {
     }
     return lines;
 }
+/** The routes that answered with a feed, a file or data, as their own table; nothing when there were none. */
+export function resourcesTable(resources) {
+    if (!resources || resources.length === 0)
+        return [];
+    const lines = [
+        "",
+        "## Not pages",
+        "",
+        "Answered with a feed, a file or data, so not checked as pages.",
+        "",
+        "| Route | Status | Content type |",
+        "|---|---|---|",
+    ];
+    for (const r of resources)
+        lines.push(`| ${cell(r.path)} | ${r.status} | ${cell(r.contentType)} |`);
+    return lines;
+}
+/** The coverage gap a check with no session leaves, in one sentence: how many routes (or pages) need sign-in, and `cover`, what covers them. */
+export function needsSignInText(count, cover, noun = "route") {
+    return `${count} ${noun}${count === 1 ? " needs" : "s need"} sign-in; give a role to cover them: ${cover}.`;
+}
+/** The routes that sent a check with no session to sign-in, as their own section; nothing when there were none. */
+export function needsSignInSection(result) {
+    const routes = result.needsSignIn ?? [];
+    if (routes.length === 0)
+        return [];
+    const cover = `pass ${code("--storage-state")} with a signed-in session, such as the profile ${code(`scenescout login ${result.url} --role <name>`)} saves`;
+    return [
+        "",
+        `## Needs sign-in (${routes.length})`,
+        "",
+        `${needsSignInText(routes.length, cover)} The check had no session, so sending it to sign-in is these routes working, not a defect: what is behind them was not measured.`,
+        "",
+        `${routes.slice(0, 20).map(code).join(", ")}${routes.length > 20 ? " …" : ""}`,
+    ];
+}
 /** The routes known and not visited, as one line; nothing when every known route was visited. */
 export function unvisitedLine(unvisited, why) {
     if (unvisited.length === 0)
@@ -942,22 +1038,26 @@ export function formatCheck(result) {
             : `${couldNotRun > 0 ? "failed" : "**FAILED**"} — ${failingText} · ${counts.high} high · ${counts.medium} medium · ${counts.low} low`) +
         (unaudited > 0 ? ` · design not measured on ${unaudited} route(s)` : "") +
         (uncompared > 0 ? ` · ${uncompared} visual target(s) not compared: no baseline yet` : "") +
-        (result.worthALook.length > 0 ? ` · ${result.worthALook.length} worth a look, never gated` : ""));
+        (result.worthALook.length > 0 ? ` · ${result.worthALook.length} worth a look, never gated` : "") +
+        (result.needsSignIn?.length ? ` · ${result.needsSignIn.length} route(s) need sign-in, not covered` : ""));
     // Right under the verdict: what a green check was allowed to do is part of what it means.
     lines.push("", `Settings — ${describeSettings(result)}`);
     lines.push(...issueSections(result.issues));
     lines.push(...worthALookSection(result.worthALook));
+    lines.push(...needsSignInSection(result));
     lines.push(...routesTable(result));
+    lines.push(...resourcesTable(result.resources));
     lines.push(...unvisitedLine(result.unvisited, "over --max-routes"));
     if (result.flows.length > 0 || result.skippedFlows.length > 0) {
         lines.push("", `## Flows (${result.flows.length})`, "");
         for (const f of result.flows) {
             const o = f.outcome;
+            const as = f.role === undefined ? "" : ` as ${code(f.role)}`;
             lines.push(o.status === "passed"
-                ? `- ✓ ${cell(f.name)} (${code(f.file)}): ${f.steps} step(s) passed`
+                ? `- ✓ ${cell(f.name)} (${code(f.file)})${as}: ${f.steps} step(s) passed`
                 : o.status === "refused"
-                    ? `- ⊘ ${cell(f.name)} (${code(f.file)}): could not run — step ${o.step} of ${f.steps}, ${cell(o.did)}: ${cell(o.reason)} _(--flow-writes ${result.settings.flowWrites})_`
-                    : `- ✗ ${cell(f.name)} (${code(f.file)}): step ${o.step} of ${f.steps}, ${cell(o.did)}: ${cell(o.reason)}`);
+                    ? `- ⊘ ${cell(f.name)} (${code(f.file)})${as}: could not run — step ${o.step} of ${f.steps}, ${cell(o.did)}: ${cell(o.reason)} _(--flow-writes ${result.settings.flowWrites})_`
+                    : `- ✗ ${cell(f.name)} (${code(f.file)})${as}: step ${o.step} of ${f.steps}, ${cell(o.did)}: ${cell(o.reason)}`);
             if (f.refusedBackground.length > 0)
                 lines.push(`  - refused background requests (beacons and pings, not charged to a step): ${f.refusedBackground.map(code).join(", ")}`);
             if (f.websockets.length > 0)
@@ -1023,6 +1123,7 @@ export function toSummaryJson(result, toolVersion) {
             controls: r.elements,
             ...(r.auditError !== undefined ? { designNotMeasured: r.auditError } : {}),
         })),
+        resources: result.resources ?? [],
         unvisited: result.unvisited,
         ...(result.timeBudget ? { timeBudget: result.timeBudget } : {}),
         ignored: result.ignored,
@@ -1030,6 +1131,7 @@ export function toSummaryJson(result, toolVersion) {
         flows: result.flows.map((f) => ({
             name: f.name,
             file: f.file,
+            ...(f.role === undefined ? {} : { role: f.role }),
             steps: f.steps,
             status: f.outcome.status,
             ...(f.outcome.status === "passed" ? {} : { step: f.outcome.step, did: f.outcome.did, reason: f.outcome.reason, path: f.outcome.path }),
@@ -1042,5 +1144,7 @@ export function toSummaryJson(result, toolVersion) {
         issues: result.issues,
         // Apart from `issues` and `counts`, which the gate reads: none of these is counted or gated.
         worthALook: result.worthALook,
+        // Routes a check with no session was sent to sign-in from: a coverage gap. Absent when the check had a session.
+        ...(result.needsSignIn ? { needsSignIn: result.needsSignIn } : {}),
     };
 }

package/dist/engine/collector.js

@@ -39,6 +39,25 @@ export const XPATH_OF_SRC = `(el) => {
     }
     return "/html/" + parts.join("/");
   }`;
+/**
+ * What one descendant of a control says toward the control's name, as
+ * page-side source, in the order the accessible-name computation reads it
+ * when a name comes from content: its aria-label; for an <img>, its alt text,
+ * and when that is empty or missing, its title (an avatar with alt="" and a
+ * title names the link around it); for an <svg>, its <title>. Anything else
+ * says nothing. Kept apart from NAME_FACTS_SRC so the order can be
+ * table-tested without a browser (contentSays).
+ */
+export const CONTENT_SAYS_SRC = `(d) => {
+    if (d.ariaLabel && d.ariaLabel.trim()) return d.ariaLabel;
+    if (d.tag === "img") return d.alt && d.alt.trim() ? d.alt : d.title;
+    if (d.tag === "svg") return d.svgTitle;
+    return "";
+  }`;
+/** CONTENT_SAYS_SRC run outside a page, from the same source the page runs. */
+export function contentSays(facts) {
+    return new Function(`return (${CONTENT_SAYS_SRC});`)()(facts);
+}
 /**
  * What an element's accessible name is read from, as page-side source: every
  * candidate source, read from the DOM and nothing decided. PICK_NAME_SRC
@@ -48,31 +67,45 @@ export const XPATH_OF_SRC = `(el) => {
  * holds the control, and a select's options or a textarea's contents are not
  * its label.
  *
- * `content` is what the element's image content says, which the text cannot
- * hold: the alt text of the first descendant <img>, else the aria-label or
- * <title> of a descendant <svg> or role="img", in document order, skipping
- * anything inside an aria-hidden part of the element.
+ * `content` is what the element's content says that its text cannot hold:
+ * the first descendant, in document order, that CONTENT_SAYS_SRC finds a word
+ * in (an aria-label, an image's alt or title, an svg's <title>), skipping
+ * anything inside an aria-hidden part of the element. `content2` is what the
+ * same content said under name rule 2 (memory.ts NAME_RULE), which read only
+ * an <img>'s alt and an <svg>'s or role="img"'s aria-label or <title>: it is
+ * read so a control renamed since keeps its coverage.
  */
 export const NAME_FACTS_SRC = `(el) => {
     const tag = el.tagName.toLowerCase();
     const role = el.getAttribute("role") || "";
     const inputType = tag === "input" ? el.type : "";
-    const byId = (id) => { const n = document.getElementById(id); return n ? n.textContent || "" : ""; };
+    const byId = (id) => { const n = (el.ownerDocument || document).getElementById(id); return n ? n.textContent || "" : ""; };
     const labels = [];
     for (const label of Array.from(el.labels || [])) {
       const own = label.contains(el) ? el.textContent || "" : "";
       labels.push((label.textContent || "").replace(own, ""));
     }
+    const says = ${CONTENT_SAYS_SRC};
     let content = "";
-    for (const d of el.querySelectorAll("img, svg, [role='img']")) {
+    let content2 = "";
+    for (const d of el.querySelectorAll("img, svg, [role='img'], [aria-label]")) {
       const hidden = d.closest('[aria-hidden="true"]');
       if (hidden && el.contains(hidden)) continue;
-      const title = d.tagName.toLowerCase() === "svg" ? d.querySelector(":scope > title") : null;
-      const said = (d.tagName === "IMG" ? d.getAttribute("alt") : d.getAttribute("aria-label") || (title ? title.textContent : "")) || "";
-      if (said.trim()) {
-        content = said;
-        break;
+      const svgTitle = d.tagName.toLowerCase() === "svg" ? d.querySelector(":scope > title") : null;
+      const said = says({
+        tag: d.tagName.toLowerCase(),
+        ariaLabel: d.getAttribute("aria-label"),
+        alt: d.getAttribute("alt"),
+        title: d.getAttribute("title") || "",
+        svgTitle: svgTitle ? svgTitle.textContent || "" : "",
+      });
+      if (!content && said.trim()) content = said;
+      // Name rule 2, frozen: what this content said before a descendant's aria-label and an image's title counted.
+      if (!content2 && d.matches("img, svg, [role='img']")) {
+        const said2 = (d.tagName === "IMG" ? d.getAttribute("alt") : d.getAttribute("aria-label") || (svgTitle ? svgTitle.textContent : "")) || "";
+        if (said2.trim()) content2 = said2;
       }
+      if (content && content2) break;
     }
     const live = /^(status|alert|log|timer|marquee)$/.test(role) || tag === "output" ||
       (el.hasAttribute("aria-live") && el.getAttribute("aria-live") !== "off");
@@ -91,6 +124,7 @@ export const NAME_FACTS_SRC = `(el) => {
       live,
       text: el.innerText || el.textContent || "",
       content,
+      content2,
     };
   }`;
 /**
@@ -105,15 +139,18 @@ export const NAME_FACTS_SRC = `(el) => {
  * fallback stays.
  *
  * - A select is never named by its options: their text is its value, not its name.
- * - Other elements are named by their text; with none, by their image content
+ * - Other elements are named by their text; with none, by their content
  *   (a link holding only a logo with alt text, a button holding only an svg
- *   with a <title>); and with neither, by title (an icon-only button with a
- *   tooltip). Text and image content are not joined: a control with both is
- *   named by its text, as it was before image content counted.
- * - A name taken from image content carries `prior`, the name the rule gave
- *   before image content counted (the title, or nothing). The name is half of
- *   the coverage key, so the key under the earlier rule is kept beside the new
- *   one and coverage recorded under it carries over (memory.ts keyAliases).
+ *   with a <title>, a link around an icon element with an aria-label or an
+ *   avatar with a title); and with neither, by title (an icon-only button
+ *   with a tooltip). Text and content are not joined: a control with both is
+ *   named by its text, as it was before content counted.
+ * - A name taken from content carries `priors`, the name each earlier rule
+ *   gave (memory.ts NAME_RULE), rule 1 first: rule 1 read no content (the
+ *   title, or nothing), rule 2 read only image content. The name is half of
+ *   the coverage key, so the key under each earlier rule is kept beside the
+ *   new one and coverage recorded under it carries over (memory.ts keyAliases,
+ *   ruleKeyAliases).
  * - A live region (status, alert, log, timer, an aria-live region, <output>)
  *   is named by the text it announces, which is what matters after an action.
  * - A whitespace-only aria-label ends the name with nothing, as it always has
@@ -145,7 +182,11 @@ export const PICK_NAME_SRC = `(f) => {
       return { name: (clean(f.nameAttr) || t || f.tag).slice(0, 80), from: "fallback" };
     }
     if (clean(f.text)) return named(clean(f.text));
-    if (clean(f.content)) return { ...named(clean(f.content)), prior: clean(f.title).slice(0, 80) };
+    if (clean(f.content)) {
+      // The name under rule 1 (no content) and under rule 2 (content2), so coverage keys can be carried across.
+      const title = clean(f.title).slice(0, 80);
+      return { ...named(clean(f.content)), priors: [title, clean(f.content2) ? clean(f.content2).slice(0, 80) : title] };
+    }
     return named(clean(f.title));
   }`;
 /**
@@ -656,7 +697,7 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
       name: named.name,
       ...policyText(el),
       nameFrom: named.from,
-      ...(named.prior !== undefined ? { priorName: named.prior } : {}),
+      ...(named.priors ? { priorNames: named.priors } : {}),
       testid: el.getAttribute("data-testid"),
       interactive,
       affords: affords && (affords.tabStop || affords.clickHandler || affords.pointer) ? affords : null,

package/dist/engine/crawl.js

@@ -47,3 +47,40 @@ export function crawlLine(o, counts, flags) {
         (counts.unnamed ? ` · ${counts.unnamed} unnamed` : "") +
         (allFlags.length ? ` · ${allFlags.join(" ")}` : ""));
 }
+/** The media types a browser renders as a page: anything else a route answers with is a file, a feed or data. */
+export const PAGE_MEDIA_TYPES = ["text/html", "application/xhtml+xml"];
+/**
+ * A Content-Type header's media type, lowercased and without its parameters
+ * ("text/HTML; charset=utf-8" → "text/html"); undefined when there is none.
+ */
+export function mediaTypeOf(header) {
+    const type = (header ?? "").split(";")[0].trim().toLowerCase();
+    return type === "" ? undefined : type;
+}
+/**
+ * Whether a route's document answered as something other than a page: an RSS
+ * or Atom feed, XML, JSON, plain text, a PDF, an image. Decided from the
+ * response's content type, not the path, because a feed at `/feed`, a licence
+ * file or a raw-file view has no extension to give it away, and a path ending
+ * `.xml` can be served as HTML. Such a route has no controls by nature, so the
+ * page rules (a dead end among them) do not apply to it, and it is not a page
+ * for the route count. Only a response that succeeded counts: the body of a
+ * 4xx or 5xx describes the error, not the route, and the error is reported as
+ * the route's own. A response with no content type is read as a page, the
+ * behaviour before the type was consulted.
+ */
+export function isNonPageResource(r) {
+    if (r.status === null || r.status >= 400)
+        return false;
+    return isFileMediaType(r.contentType);
+}
+/**
+ * Whether a response's content type names something other than a page, whatever
+ * its status. A browser may take such a response as a download and fail the
+ * navigation, so this is what says the route answered (with its status) rather
+ * than failed to load.
+ */
+export function isFileMediaType(contentType) {
+    const type = mediaTypeOf(contentType);
+    return type !== undefined && !PAGE_MEDIA_TYPES.includes(type);
+}

package/dist/engine/design.js

@@ -22,6 +22,32 @@
  * controls, visible keyboard focus.
  */
 import { missingName, NAME_SRC, placeholderOnly } from "./collector.js";
+/**
+ * The control a Tab press focused, as the focus-indicator rule measures it. It runs
+ * page-side (probes.ts embeds its source), so it is plain JavaScript once compiled.
+ *
+ * A Tab that lands on an iframe or frame moves focus into the frame's document: the
+ * frame element is not the control the user sees focused, and its own outline staying
+ * the same says nothing. So the walk follows focus into a same-origin frame and returns
+ * the element focused there. It returns "frame" when focus is inside a frame it cannot
+ * follow (another site's, whose document is not readable) or a frame whose document has
+ * nothing focused: that press is skipped, not sampled. It returns null when nothing in
+ * the page is focused, which ends the sampling.
+ */
+export function focusedControl(doc) {
+    let d = doc;
+    let el = d.activeElement;
+    while (el && /^i?frame$/i.test(el.tagName)) {
+        const inner = el.contentDocument ?? null;
+        if (!inner)
+            return "frame";
+        d = inner;
+        el = inner.activeElement;
+    }
+    if (!el || el === d.body || el === d.documentElement)
+        return d === doc ? null : "frame";
+    return el;
+}
 /**
  * Whether some text names a filter or a facet, as page-side source: one of its
  * words, split at camelCase and punctuation, is filter(s) or facet(s). Whole
@@ -63,20 +89,47 @@ export const DESIGN_COLLECT_SCRIPT = `(() => {
     const p = parseColor(c);
     return p ? "rgba(" + p[0] + ", " + p[1] + ", " + p[2] + ", " + p[3] + ")" : "unknown";
   };
+  // Replaced content that paints pixels the audit cannot read: an <img>,
+  // <picture>, <video> or <canvas>, often absolutely positioned under a hero
+  // heading as a sibling or cousin of the text rather than its ancestor.
+  let media = null;
+  const mediaUnder = (el, within) => {
+    if (media === null) media = Array.from(document.querySelectorAll("img, picture, video, canvas")).slice(0, 300);
+    const r = el.getBoundingClientRect();
+    const cx = r.left + r.width / 2, cy = r.top + r.height / 2;
+    for (const m of media) {
+      // The text's own subtree holds inline icons, not its background; and an
+      // image outside the opaque ancestor the text sits on is treated as hidden
+      // behind it. An opaque overlay that is NOT an ancestor (a sibling scrim)
+      // is not seen, so text on it over an image is skipped, not measured.
+      if (el.contains(m) || (within && !within.contains(m))) continue;
+      const mr = m.getBoundingClientRect();
+      if (mr.width === 0 || mr.height === 0 || cx < mr.left || cx > mr.right || cy < mr.top || cy > mr.bottom) continue;
+      const ms = window.getComputedStyle(m);
+      if (ms.visibility === "hidden" || ms.display === "none" || ms.opacity === "0") continue;
+      return true;
+    }
+    return false;
+  };
   // Effective background: COMPOSITE translucent ancestor layers (a chip with
   // rgba(...,0.12) over white is nearly white — treating it as opaque produces
   // false WCAG failures). Stops at the first opaque layer; white fallback.
+  // "image" when an ancestor's background-image or a media element under the
+  // text's centre paints behind it: no single colour stands for that, so the
+  // contrast check skips it rather than report a ratio against the page.
   const effBg = (el) => {
     const layers = [];
     let node = el;
+    let opaque = null;
     for (let i = 0; node && i < 20; i++, node = node.parentElement) {
       const s = window.getComputedStyle(node);
       if (s.backgroundImage && s.backgroundImage !== "none") return "image";
       const c = parseColor(s.backgroundColor);
       if (!c || c[3] === 0) continue;
       layers.push(c);
-      if (c[3] >= 1) break;
+      if (c[3] >= 1) { opaque = node; break; }
     }
+    if (mediaUnder(el, opaque)) return "image";
     let base = [255, 255, 255];
     for (let i = layers.length - 1; i >= 0; i--) {
       const [r, g, b, a] = layers[i];
@@ -264,7 +317,7 @@ export const DESIGN_COLLECT_SCRIPT = `(() => {
     if (img.naturalWidth <= 1 || img.naturalHeight <= 1 || r.width < 24 || r.height < 24) continue;
     const tid = img.getAttribute("data-testid");
     const label = tid ? "[" + tid + "]" : (img.getAttribute("alt") || (img.getAttribute("src") || "").split("/").pop() || "img").slice(0, 40);
-    images.push({ label, nw: img.naturalWidth, nh: img.naturalHeight, rw: Math.round(r.width), rh: Math.round(r.height) });
+    images.push({ label, nw: img.naturalWidth, nh: img.naturalHeight, rw: Math.round(r.width), rh: Math.round(r.height), fit: window.getComputedStyle(img).objectFit || "fill" });
   }
   const page = {
     scrollW: Math.max(document.documentElement.scrollWidth, document.body ? document.body.scrollWidth : 0),
@@ -359,6 +412,10 @@ function contrastFailures(records) {
     for (const r of records) {
         if (!r.text || r.bg === "image" || r.bg === "unknown" || r.color === "unknown")
             continue;
+        // Text whose own colour is fully transparent is not painted: a selectable text layer laid over a rendered
+        // document (a PDF viewer's), or text hidden for screen readers. Its 1:1 ratio is not what anyone sees.
+        if (parseRgb(r.color)?.[3] === 0)
+            continue;
         const ratio = contrastRatio(r.color, r.bg);
         if (ratio === null)
             continue;
@@ -574,6 +631,20 @@ export function spacedApart(r, others) {
 export function tooSmall(r, all) {
     return undersized(r) && !spacedApart(r, all);
 }
+/** Past this, a stretched image reads as distorted rather than as rounding. */
+export const ASPECT_TOLERANCE = 0.12;
+/**
+ * How far an image is stretched out of its proportions, or null when it is not.
+ * Only `fill`, the default, stretches the picture to its box: `cover` and `contain`
+ * scale it uniformly and crop or letterbox, `none` draws it at its own size and
+ * `scale-down` is one of those two. So a mismatched box is distortion only under `fill`.
+ */
+export function aspectDistortion(img) {
+    if (img.fit !== "fill")
+        return null;
+    const off = Math.abs(img.rw / img.rh / (img.nw / img.nh) - 1);
+    return off > ASPECT_TOLERANCE ? off : null;
+}
 /**
  * Reduce raw style records + page facts to a judgeable design digest + score.
  *
@@ -884,7 +955,10 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     if (affordances.length > 0)
         sections.push(`AFFORDANCES:\n` + affordances.map((s) => `  ${s}`).join("\n"));
     // ---- 12. IMAGES: aspect-ratio distortion (rendered box fights the source's proportions).
-    const distorted = page.images.map((img) => ({ img, off: Math.abs(img.rw / img.rh / (img.nw / img.nh) - 1) })).filter(({ off }) => off > 0.12);
+    const distorted = page.images.flatMap((img) => {
+        const off = aspectDistortion(img);
+        return off === null ? [] : [{ img, off }];
+    });
     if (distorted.length > 0) {
         sections.push(`IMAGES (${distorted.length} distorted):\n` +
             distorted