scenescout 3.16.0 → 3.18.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # scenescout
 
+## 3.18.0
+
+### Minor Changes
+
+- 1a6ce12: Ask the start-of-run questions as one form where the client can show one. A new `scout_intake` tool checks whether the client declared MCP elicitation in form mode and, if it did, asks the address, whether and how to sign in, what to check and whether the site holds real data in a single form, then returns the `scout_login` and `scout_attach` calls the answers choose. With no form support, or when the person declines or closes the form, it returns the questions for the agent to ask in chat, as before. The form never asks for a password or a code: signing in stays in the window `scout_login` opens. The skill and the `explore` prompt call `scout_intake` before setup.
+
+### Patch Changes
+
+- 96bee5c: `scenescout check` and the first look no longer report a feed, a plain-text file, XML, JSON, a PDF or an image as a dead end. A route's response content type now decides whether it is a page: one served as anything but `text/html` or `application/xhtml+xml` is listed under "Not pages" in the report and as `resources` in `check.json`, is not checked against the page rules, and does not count towards the routes checked or `--max-routes`. One that answers 4xx or 5xx is still reported as the route's error.
+- 952fbf3: A check or first look with no signed-in session no longer reports each route that redirects to sign-in as an `auth-redirect` issue. It lists them once as a coverage gap ("N routes need sign-in; give a role to cover them"), under "Needs sign-in" in the report and as `needsSignIn` in `check.json`. With `--storage-state`, a redirect to sign-in is still reported as a lost session.
+- 6073a0d: A link or button with no text is now named by a descendant's `aria-label` (an icon element inside the link) and by an image's `title` when its alt text is empty, as the browser names it, so `unnamed-control` no longer reports those controls. Coverage recorded for them under their earlier keys carries over.
+- cd0639b: Text drawn over a positioned `<img>`, `<picture>`, `<video>` or `<canvas>` is no longer reported as a contrast failure measured against the page background (often as 1.00:1). Like text over a CSS background image, it has no single background colour, so the design audit and `scenescout check` leave it unmeasured.
+- 680e4f5: The focus-indicator rule no longer reports an iframe as a control with no visible focus indicator. A Tab onto a frame moves focus into the frame's document, so the design audit and `scenescout check` now follow focus into a same-origin frame and measure the control focused there, reported by its own name. A press that leaves focus inside another site's frame is skipped.
+- fe16d4c: A page that locks scrolling behind a modal opened inside a full-viewport frame is no longer reported as a leaked scroll lock. The overlay probe now counts a visible iframe that covers the viewport, is pinned itself or through a fixed ancestor, and is neither faded out nor click-through as an open overlay, provided that, when the frame is same-origin, a dialog or a dimming backdrop is showing inside it. A frame left mounted after its modal closed does not justify the lock, so that page is still reported at high severity.
+- 96b74aa: The design audit's `image-aspect` rule no longer reports an image that keeps its proportions through `object-fit: cover`, `contain`, `scale-down` or `none`, whether set inline or by a class. Only an image stretched to its box under `fill`, the default, is reported as distorted.
+- 7fc6013: The gap ledger's list of pages whose POST observe refused now names the page that sent the POST. A page whose script posted as it loaded could be listed as the page the session came from, because the browser had not yet reported the new page; the request's Referer now decides, with the session's page as the fallback.
+
+## 3.17.0
+
+### Minor Changes
+
+- b0709f0: `scenescout check` accepts `--ignore-path`: a path drops every rule filed on that route, and `rule:/path` drops that one rule there. A page meant to answer HTTP 500 can stay off the gate while the same status on another path still fails `--fail-on high`. The GitHub Action takes the same input.
+- 547d006: Add the `live` and `login` MCP prompts. `live` returns the current session's loopback live-view URL. `login` takes a role and tells the agent to call `scout_login`, with no password argument.
+- 7ba8712: Add `scout_status`, a run-status pane built as an MCP App (`io.modelcontextprotocol/ui`, specification 2026-01-26). In a client that renders MCP Apps it shows each session's objective and task, open findings by severity, coverage and a button for the live view, and refreshes itself every 2.5 seconds through the app-only `scout_status_poll` tool. Every other client gets the same as text, starting with the live view's loopback address. The pane's page loads nothing from outside and shows only what the live view already shows.
+
+### Patch Changes
+
+- 745a38e: On Windows, `scenescout install --client` starts an npm-installed client (a `.cmd` or `.bat` shim) through `cmd.exe`, so registration runs the client's own command instead of stopping and printing it to run by hand.
+
 ## 3.16.0
 
 ### Minor Changes

package/README.md

@@ -205,7 +205,7 @@ The agent scans the project (if there is one), attaches read-only, explores, and
 
 **Common flags** — `--level minimal|medium|extensive` · `--url <app>` · `--role <name\|path>` (who to explore as: a login saved with `scenescout login`, a storage state found by the scan, or a path to a Playwright storage-state JSON) · `--focus <text>` (a ticket or a sentence to check) · `--observe` / `--read-only` / `--safe-write` / `--allow-destructive`.
 
-**No flags at all** (`/scenescout` on its own) and the agent asks four plain questions instead: the address, whether and how you sign in, what to check (tickets or a description), and whether the site holds real data. Real data, or not being sure, means nothing but `GET` requests leave the page; you are never asked to pick a mode. Any flag skips the questions. See [Plain questions instead of flags](docs/guide/Ways-to-use-it.md#plain-questions-instead-of-flags).
+**No flags at all** (`/scenescout` on its own) and the agent asks four plain questions instead: the address, whether and how you sign in, what to check (tickets or a description), and whether the site holds real data. Where your client can show a form, `scout_intake` asks them as one form, never for a password; otherwise the agent asks in chat. Real data, or not being sure, means nothing but `GET` requests leave the page; you are never asked to pick a mode. Any flag skips the questions. See [Plain questions instead of flags](docs/guide/Ways-to-use-it.md#plain-questions-instead-of-flags).
 
 ### 🔑 Signing in as a role
 
@@ -229,7 +229,7 @@ Before a parallel run, `scout_lane_brief` checks that the planner's saved login
 
 ## 📺 Watching a run live
 
-When a session attaches, the engine starts a small live view and hands the agent its address on a `Live view:` line, which the agent passes on to you. On a desktop the engine also opens it in your default browser, and opens the report when it is written; nothing opens in CI or over SSH, and `SCENESCOUT_OPEN=none` (or `live`, `report`, `both`) chooses otherwise. From a terminal, `scenescout watch` opens the same page. There is one card per session:
+When a session attaches, the engine starts a small live view and hands the agent its address on a `Live view:` line, which the agent passes on to you. On a local desktop it also opens that page in your default browser as the session attaches, and opens `report.html` when `scout_report` writes it, whether or not the browser window is shown. Nothing opens in CI, over SSH, or on Linux with no display. `SCENESCOUT_OPEN` (`live`, `report`, `both` or `none`) in the server's environment chooses otherwise, and `scout_attach {open}` wins over it. `scenescout ci` opens nothing unless `SCENESCOUT_OPEN` is set. From a terminal, `scenescout watch` opens the same page. There is one card per session:
 
 <p align="center"><img src="examples/screenshots/live-view.png" alt="The live view during a run of three parallel agents against the demo app: one card per session, each with its role and objective, the task it is on, the tool it is running, the page it is on, a live thumbnail, and a feed of the actions it just took, tinted one colour per task" width="880" /></p>
 
@@ -329,11 +329,11 @@ Snapshots are cheap: re-snapshotting a route returns only *what changed*, with s
 
 ## 🧰 The toolbox
 
-34 deterministic tools. The agent picks; you rarely call these by hand.
+35 deterministic tools. The agent picks; you rarely call these by hand.
 
 | Phase | Tools | What they do |
 |---|---|---|
-| **Set up** | `scout_playbook` `scout_scan` `scout_attach` `scout_session` | Hand the testing method to an agent that has no skill loaded; discover routes; launch a browser in a write-mode; keep several authenticated roles alive at once |
+| **Set up** | `scout_playbook` `scout_intake` `scout_scan` `scout_attach` `scout_session` | Hand the testing method to an agent that has no skill loaded; ask the start-of-run questions as one form where the client can show one; discover routes; launch a browser in a write-mode; keep several authenticated roles alive at once |
 | **Explore** | `scout_crawl` `scout_coverage` | Sweep every route in one call; ask what's still untested |
 | **Look** | `scout_snapshot` `scout_hover` `scout_screenshot` `scout_capture` | Read the structured scene (diffed); reveal tooltips/hover cards; capture pixels only when needed; save one element as a PNG to show someone |
 | **Ask the server** | `scout_request` `scout_network` | Call the app's own API as this session, with the UI bypassed — the check that turns a hidden button into a proven refusal; list the requests the page itself made since it loaded |
@@ -378,7 +378,7 @@ That refusal *is* the guarantee: an extensive report can only exist when nothing
 - 🟢 **`read-only` by default.** Destructive-labeled elements (delete/revoke/archive/…) **and** all `PUT/PATCH/DELETE` + destructive `POST`s are blocked at the network layer — see [`src/engine/policy.ts`](src/engine/policy.ts). Non-destructive `POST`s are allowed, because submitting forms is how a tester finds validation bugs — so read-only means *nothing existing is changed or removed*, not *nothing is ever created*.
 - 🟡 **`safe-write`** (`--safe-write`) lets the agent create data and edit/delete **only what it created** this run — never pre-existing records.
 - 🔴 **`destructive`** (`--allow-destructive`) allows everything, and only ever when *you* confirm the environment is disposable. The skill will never choose this itself.
-- 📂 Findings, memory, and reports live in a `.scenescout/` folder where you ran it. It ignores itself in git, so a stray `git add -A` never commits test data.
+- 📂 Findings, memory, and reports live in a `.scenescout/` folder in the project. A client with no project folder, such as a desktop chat, gets one folder per tested site under `Documents/SceneScout/<host>/` by default, and the attach says where; `SCENESCOUT_PROJECTS_DIR` moves it. The folder ignores itself in git, so a stray `git add -A` never commits test data.
 
 A `🛡 WRITE-POLICY blocked` notice is the safety net doing its job, not an app bug. The server never sees a blocked request, but a page's own `fetch` or XHR is answered with a `403` in its place rather than dropped, so the page's handling of a refusal really runs: a page that then claims success is reported as a `false_success` ([ADR 9](docs/adr/0009-a-refused-write-is-answered-not-dropped.md)).
 
@@ -388,6 +388,8 @@ A control is judged by its own label: a dropdown by the option picked, a row by
 
 ## 📋 What you get
 
+`.scenescout/report.md` and `report.html` open **In plain words**: a short summary, then each problem this run found, worst first, with its impact, the steps that led to it, what was expected, what happened and a picture when there is one. The technical detail (id, category, evidence, route) stays one click away.
+
 `.scenescout/report.md` — a deduplicated, worst-first report with:
 
 - 🐛 **Findings** with repro traces and generated Playwright regression-test skeletons.
@@ -398,9 +400,9 @@ A control is judged by its own label: a dropdown by the option picked, a row by
 - ⏱️ **How the run was paced** — how closely each session kept working, and apart from that, how long finished lanes held their browsers waiting to be collected, so neither hides the other.
 - 🎯 **How well the lanes judged** — on a parallel run, whether the confidence each lane stated matched what the project went on to file, beside what later re-tests found ([ADR 10](docs/adr/0010-a-confidence-is-checked-not-trusted.md)).
 
-`.scenescout/report.html` — the same report as one self-contained page, with every session's trail beside it, and on a [recorded run](#-recording-a-run-and-reading-it-back) the screenshots under each finding.
+`.scenescout/report.html` — the same report as one self-contained page, with every session's trail beside it. Each finding shows a picture of the element it is about, or of the page as it was. A [recorded run](#-recording-a-run-and-reading-it-back) also shows the screenshots around each finding.
 
-👀 Watch a run live: `node dist/cli.js status <project-path>`.
+👀 Watch a run live: `npx scenescout watch`, or `npx scenescout status <project-path>` for the same information as text.
 
 ---
 
@@ -759,6 +761,7 @@ test-app/           fixtures for the real-browser smoke tests
 skills/scenescout/   the testing method (SKILL.md): a skill in Claude Code, served by the server everywhere else
 docs/how-it-works.md  what happens at each stage, in diagrams
 docs/benchmark.md   measuring whether a change made runs better
+docs/validation.md  scorecards from runs against public open-source apps
 docs/adr/           why it's built this way
 ```
 
@@ -772,6 +775,8 @@ docs/adr/           why it's built this way
 
 **[Measuring whether a change helped](docs/benchmark.md)** — the demo app's answer key, the scorecard (recall, precision, judged-not-filed, severity, calibration), and the results log of every run, including what did not help.
 
+**[Validation on public open-source apps](docs/validation.md)** — runs against three well-known open-source web apps, with a scorecard for each: issues by severity, how many were real and how many were false positives, and the engine problems the runs exposed.
+
 The load-bearing choices are recorded as ADRs — read the relevant one before changing a rule it covers:
 
 - [1 · Completion is an enforced contract, not a claim](docs/adr/0001-completion-is-a-contract-not-a-vibe.md)
@@ -787,6 +792,7 @@ The load-bearing choices are recorded as ADRs — read the relevant one before c
 - [11 · A gate is deterministic, and fails only on what it can prove](docs/adr/0011-a-gate-is-deterministic-and-fails-only-on-what-it-can-prove.md)
 - [12 · A check replays saved flows and re-tests open findings, within settings whose defaults do the least harm](docs/adr/0012-a-check-replays-saved-flows-and-reports-re-tests.md)
 - [13 · What depends on a project's convention is the project's to decide](docs/adr/0013-a-convention-is-the-projects-to-decide.md)
+- [21 · Update the docs in the same pull request, unless the change has no user-facing surface](docs/adr/0021-update-the-docs-in-the-pull-request.md)
 
 ---
 

package/dist/check-run.js

@@ -11,11 +11,12 @@ import os from "node:os";
 import path from "node:path";
 import { BASELINE_CAPTURE, baselineFiles, baselineMeta, defaultBaselinesDir, elementTarget, isVisualPicture, judgeBaseline, missingTargetsMessage, parseBaselineTargets, readStoredBaseline, TARGETS_FILE, VISUAL_DIRNAME, visualFiles, } from "./engine/baseline.js";
 import { BrowserEngine } from "./engine/browser.js";
-import { checkFindings, redactBaselineRun, MAX_DISCOVERY_ROUNDS, redactFlowRuns, redactRoute, redactRoutes, settingsOf, unmeasuredReason, withoutOwnResponse, } from "./engine/check.js";
+import { checkFindings, redactBaselineRun, MAX_DISCOVERY_ROUNDS, redactFlowRuns, redactRoute, redactRoutes, settingsOf, splitResources, unmeasuredReason, withoutOwnResponse, } from "./engine/check.js";
 import { loadFlows, resolveFlowsDir } from "./engine/flow.js";
 import { MemoryStore, MEMORY_DIRNAME, writeSelfIgnore } from "./engine/memory.js";
 import { decodePng, encodePng } from "./engine/png.js";
 import { firstLineOf } from "./engine/limits.js";
+import { isNonPageResource } from "./engine/crawl.js";
 import { checkRetestPlan, retestResults, wellFormedFindings } from "./engine/verify.js";
 /** The baselines folder a check uses: the one --baselines names, else the project's own. */
 export function baselinesDirOf(options) {
@@ -107,6 +108,8 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
         if (authFailed)
             throw new Error(authFailed.replace(/ Continuing now tests a logged-out app\.$/, "").replace(/re-attach/, "run the check again"));
         const routes = [];
+        // A feed or a file the crawl followed is not a page, so it does not use up --max-routes.
+        const pagesSoFar = () => routes.filter((r) => !isNonPageResource(r)).length;
         const crawl = async (paths, limit, deadline) => {
             await engine.crawl(paths, { inspect: true, limit, deadline });
             routes.push(...engine.lastCrawlHealth);
@@ -118,15 +121,15 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
             // The start page first, whatever else is known: it is the one route the user named. The
             // time budget does not apply to it, so a run always measures at least the page it was given.
             await crawl([`${start.pathname}${start.search}${start.hash}`], 1);
-            for (let round = 0; round < MAX_DISCOVERY_ROUNDS && routes.length < options.maxRoutes; round++) {
+            for (let round = 0; round < MAX_DISCOVERY_ROUNDS && pagesSoFar() < options.maxRoutes; round++) {
                 if (engine.crawlableRoutes().length === 0 || pastDeadline())
                     break;
-                await crawl(undefined, options.maxRoutes - routes.length, deadline);
-                log(`  ${routes.length} route(s) checked`);
+                await crawl(undefined, options.maxRoutes - pagesSoFar(), deadline);
+                log(`  ${pagesSoFar()} route(s) checked`);
             }
         }
         // Out of time with routes still to visit; a cap of routes reached first is --max-routes's to report.
-        const timeLimitReached = pastDeadline() && routes.length < options.maxRoutes && engine.crawlableRoutes().length > 0;
+        const timeLimitReached = pastDeadline() && pagesSoFar() < options.maxRoutes && engine.crawlableRoutes().length > 0;
         // Pages of open findings the crawl did not load exactly: loaded now, so each re-test has its own measurement.
         // Kept apart from `routes`: they are measured only to re-test, never checked against the page rules, and do not count
         // towards --max-routes. With --paths the check stays on the paths it was given.
@@ -172,22 +175,27 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
                 }))),
             }
             : null;
-        const measured = redactRoutes(routes.map(withoutOwnResponse));
+        const { pages: measured, resources } = splitResources(redactRoutes(routes.map(withoutOwnResponse)));
         const flows = redactFlowRuns(flowRuns);
         const pictured = baselines ? redactBaselineRun(baselines) : null;
-        const { issues, worthALook } = checkFindings(measured, start.origin, options.ignore, flows, pictured);
+        // Signed in only when given a session: with none, a route that sends the browser to sign-in needs one, and is not a lost session.
+        const signedIn = options.storageStatePath !== undefined;
+        const { issues, worthALook, needsSignIn } = checkFindings(measured, start.origin, options.ignore, flows, pictured, options.ignorePaths, signedIn);
         return {
             url: redactRoute(options.url),
             generatedAt: new Date().toISOString(),
             mode: options.mode,
             failOn: options.failOn,
             routes: measured,
+            resources,
             issues,
             worthALook,
+            ...(signedIn ? {} : { needsSignIn }),
             // Routes that failed to load are issues already; "not visited" is only what --max-routes (or the time budget) left out.
             unvisited: options.paths ? [] : engine.crawlableRoutes().map(redactRoute),
             ...(options.timeBudgetMs !== undefined ? { timeBudget: { ms: options.timeBudgetMs, reached: timeLimitReached } } : {}),
             ignored: options.ignore,
+            ignoredPaths: options.ignorePaths,
             flows,
             skippedFlows: inputs.skippedFlows ?? [],
             retest,

package/dist/cli.js

@@ -78,7 +78,8 @@ Usage:
                                     so it can gate a pull request. Writes report.md, check.sarif and check.json.
                                     (--fail-on high|medium|low|never (default high); --mode observe|read-only;
                                      --max-routes N (default 50); --paths /a,/b to check only those;
-                                     --ignore rule,rule; --storage-state file to check signed in;
+                                     --ignore rule,rule; --ignore-path /a,rule:/b to exempt a path, or one rule on it;
+                                     --storage-state file to check signed in;
                                      --project dir (default: here); --out dir (default: .scenescout/check);
                                      --browser chromium|firefox|webkit;
                                      --action-timeout-ms N (default 5000), --nav-timeout-ms N (default 20000;
@@ -482,10 +483,8 @@ async function install(flags) {
             }
             else {
                 failed = true;
-                // On Windows a client installed through npm is a .cmd shim, which node cannot start directly.
-                const windowsNote = process.platform === "win32" ? " (or it is installed as a .cmd shim, which cannot be started from here)" : "";
                 console.log(reg.status === "client-missing"
-                    ? `· ${label} was not found on this machine${windowsNote}, so nothing was registered with it.`
+                    ? `· ${label} was not found on this machine, so nothing was registered with it.`
                     : `✗ Registering with ${label} failed: ${reg.detail}`);
                 console.log(`  To do it by hand, ${reg.manual}\n`);
             }

package/dist/engine/browser.js

@@ -1,8 +1,8 @@
 import { chromium, firefox, webkit, } from "playwright";
 import fs from "node:fs";
 import path from "node:path";
-import { elementKey, fingerprintState, isNonPageRoute, keyAliases, normalizePath, ordinalKeys, refsSurviveUrlChange, routeBase, } from "./fingerprint.js";
-import { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore, reachedRoutes, redactSecrets, TASK_SET } from "./memory.js";
+import { elementKey, fingerprintState, isNonPageRoute, keyAliasSteps, normalizePath, ordinalKeys, refsSurviveUrlChange, routeBase, } from "./fingerprint.js";
+import { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore, NAME_RULE, reachedRoutes, redactSecrets, TASK_SET, } from "./memory.js";
 import { normalizeTask } from "./task.js";
 import { ACTED_CONTROL_SRC, CLAIM_SCAN_SCRIPT, findContradictions, INFRASTRUCTURE_WRITE_RE, isBackgroundRequest, OPEN_DIALOGS_SCRIPT, quietAnswer, saidSince, } from "./claims.js";
 import { POSTMESSAGE_BINDING, describeTokenPost, postMessageCaptureScript, tokenHits, tokenPostKey } from "./postmessage.js";
@@ -17,7 +17,7 @@ import { formatJourney, journeyTime, measureJourney } from "./journey.js";
 import { describeStep, FLOW_AFTER_LAST_STEP_MS, isAction, matchRequest, parseTarget, splitRefusals, TARGET_HELP, urlMatches, } from "./flow.js";
 import { framePath, RECORD_MAX_FRAMES } from "./replay.js";
 import { InFlightRequests, keepWatchingUrl, normalizePace, SETTLE_TICK_MS, shouldKeepWaiting } from "./settle.js";
-import { crawledRoute, crawlLine, mainStateFlag } from "./crawl.js";
+import { crawledRoute, crawlLine, isFileMediaType, isNonPageResource, mainStateFlag, mediaTypeOf } from "./crawl.js";
 import { authToRemember, BODY_FETCH_MAX, buildRequestScript, formatPageRequests, formatReplay, PageRequests, replaySignature, requestHeaders, resolveMethod, resolveRequestUrl, resolveTarget, staleCredentialNote, toReplayResult, wantsView, } from "./request.js";
 import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, screencastSupport, serviceWorkerPolicy, sharedWorkersAllowed, unloadWriteInterception, closeWaitsForLeavingWrites, } from "../browsers.js";
 import { revealedLines } from "./hover.js";
@@ -28,7 +28,7 @@ import { performScroll, probeFocusIndicators, probeOverlays, scrollContainer } f
 import { boundedTeardown } from "./teardown.js";
 import { BROWSER_MARKER, reapOrphanBrowsers } from "./reaper.js";
 import { planUploadOptions, resolveDiskUpload } from "./uploads.js";
-import { answersWithRefusal, destructiveRefusal, destructiveLabelOf, pickIsDestructive, isDestructive, isDestructiveWire, blockSignature, BlockNotices, dialogNote, dialogResponse, ESCAPE_REFUSAL, allowsWrite, policyRefusal, foreignFrameOrigin, foreignWrite, withForeignFrameSandbox, offAppPageWrite, embedOfRequest, hostileForEmbed, trustedEmbedOrigins, MAX_TRUSTED_EMBEDS, MAX_READ_POSTS, READ_POSTS_ENV, readPostAllowed, matchReadPost, readPostEntries, readPostsSetting, trustsForeignWrite, embedProbeRefusal, EmbedMoveTracker, sandboxedRedirectPage, allowsForeignWriteOnSignIn, isAuthExempt, WriteRule, } from "./policy.js";
+import { answersWithRefusal, destructiveRefusal, destructiveLabelOf, pickIsDestructive, isDestructive, isDestructiveWire, blockSignature, BlockNotices, dialogNote, dialogResponse, ESCAPE_REFUSAL, allowsWrite, policyRefusal, foreignFrameOrigin, foreignWrite, withForeignFrameSandbox, offAppPageWrite, embedOfRequest, hostileForEmbed, trustedEmbedOrigins, MAX_TRUSTED_EMBEDS, MAX_READ_POSTS, READ_POSTS_ENV, readPostAllowed, matchReadPost, refusedPostPage, readPostEntries, readPostsSetting, trustsForeignWrite, embedProbeRefusal, EmbedMoveTracker, sandboxedRedirectPage, allowsForeignWriteOnSignIn, isAuthExempt, WriteRule, } from "./policy.js";
 import { scanProject } from "../scan.js";
 import { analyzeDesign, DESIGN_COLLECT_SCRIPT } from "./design.js";
 import { acceptMatches, generatedUpload } from "./fixtures.js";
@@ -1406,7 +1406,7 @@ export class BrowserEngine {
                 const refuse = (why) => {
                     const answered = answersWithRefusal(req.resourceType());
                     if (rule === "observe" && method === "POST" && !why && answered && !BENIGN_MUTATION_RE.test(url))
-                        this.noteObserveRefusedPost(url, req.postData());
+                        this.noteObserveRefusedPost(url, req.postData(), this.sentByMainFrame(req) ? req.headers()["referer"] : undefined);
                     this.noteBlocked({ at: Date.now(), sig: `${method} ${url.slice(0, 140)}`, answered, why, type: req.resourceType() });
                     this.logAction({ action: "write-policy:blocked", target: `${method} ${pathname}${why ? ` (${why})` : ""}`, url: this.page?.url() ?? "" });
                     this.refusedByPolicy.add(req);
@@ -1826,16 +1826,16 @@ export class BrowserEngine {
         // A live region listed for what it says is known by its role, not its
         // text, so a new message reads as the same region saying something else.
         const baseKeyOf = (el, name, tag) => frameElementKey(el.liveOnly ? `live:${el.role}` : elementKey({ ...el, name }), tag);
+        // Each element's base key under every name rule, rule 1 first, so each step between two rules gets its own aliases.
         const bases = all.map(({ raw: el, tag }) => ({
-            base: baseKeyOf(el, el.name, tag),
-            prior: baseKeyOf(el, el.priorName ?? el.name, tag),
+            byRule: Array.from({ length: NAME_RULE }, (_, i) => baseKeyOf(el, i < NAME_RULE - 1 ? (el.priorNames?.[i] ?? el.name) : el.name, tag)),
             tracked: !el.liveOnly,
         }));
-        const keys = ordinalKeys(bases.map((b) => b.base));
-        const aliases = keyAliases(bases);
+        const keys = ordinalKeys(bases.map((b) => b.byRule[NAME_RULE - 1]));
+        const aliases = keyAliasSteps(bases);
         const built = all.map(({ raw: el, frame, tag }, i) => {
             const key = keys[i];
-            const { ownText: _ownText, centre: _centre, cut: _cut, priorName: _priorName, ...listed } = el;
+            const { ownText: _ownText, centre: _centre, cut: _cut, priorNames: _priorNames, ...listed } = el;
             const full = {
                 ...listed,
                 ...(tag ? { frame: tag } : {}),
@@ -2332,18 +2332,29 @@ export class BrowserEngine {
     }
     /**
      * Remember in project memory, for the gap ledger, a script's POST that
-     * observe refused on the page the session is on. Not one that looks
-     * destructive, nor one to an endpoint already named as a read (its body was
-     * a mutation): naming it would change nothing.
+     * observe refused, charged to the page that sent it (policy.ts
+     * refusedPostPage). Not one that looks destructive, nor one to an endpoint
+     * already named as a read (its body was a mutation): naming it would change
+     * nothing.
      */
-    noteObserveRefusedPost(url, body) {
-        const pageUrl = this.page?.url();
+    noteObserveRefusedPost(url, body, referer) {
+        const pageUrl = refusedPostPage(this.baseUrl, referer, this.page?.url());
         if (!pageUrl || !this.memory || isDestructiveWire(pathnameOf(url), body) || matchReadPost(this.readPosts, this.baseUrl, url))
             return;
         const endpoint = this.refusedPostEndpoint(url);
         if (endpoint)
             this.memory.noteObserveRefusedPost(normalizePath(pageUrl), endpoint);
     }
+    /** Whether the session's page sent `req` from its top document, not from a frame or a service worker. */
+    sentByMainFrame(req) {
+        try {
+            return !!this.page && req.frame() === this.page.mainFrame();
+        }
+        catch {
+            // A service worker's request has no frame.
+            return false;
+        }
+    }
     /** A POST to this endpoint went out, so the pages observe refused it on are no longer a gap for it. */
     clearRefusedPost(url) {
         const endpoint = this.refusedPostEndpoint(url);
@@ -4332,7 +4343,9 @@ export class BrowserEngine {
     /** The full route contract: scanned filesystem routes ∪ link-discovered route classes. */
     allKnownRoutes() {
         const discovered = this.memory ? Object.keys(this.memory.discoveredRoutes) : [];
-        return [...new Set([...this.knownRoutes, ...discovered])].filter((r) => !isNonPageRoute(r));
+        // A route that answered with a feed or a file is not a page, whatever its path looks like.
+        const resources = new Set(Object.keys(this.memory?.resourceRoutes ?? {}).map(normalizePath));
+        return [...new Set([...this.knownRoutes, ...discovered])].filter((r) => !isNonPageRoute(r) && !resources.has(normalizePath(r)));
     }
     /**
      * Contract routes neither visited nor attempted by THIS role.
@@ -4450,29 +4463,89 @@ export class BrowserEngine {
             this.actionStartedAt = Date.now();
             this.oracles.drain(false); // discard pre-route leftovers WITHOUT marking their signatures as reported
             let status = "ERR";
+            // The main document's response, as the browser received it. Kept apart from goto's own result: a browser that
+            // treats a PDF, a feed or an attachment as a download throws from goto, and this is then the only record of it.
+            const answered = { last: null };
+            const asked = new URL(url).href;
+            const onResponse = (r) => {
+                if (r.frame() !== page.mainFrame() || !r.request().isNavigationRequest())
+                    return;
+                // A late event from the page before is not this route's: its redirect chain must start at the URL asked for.
+                let first = r.request();
+                for (let from = first.redirectedFrom(); from; from = from.redirectedFrom())
+                    first = from;
+                if (first.url() !== asked)
+                    return;
+                answered.last = { url: r.url(), status: r.status(), contentType: mediaTypeOf(r.headers()["content-type"]) };
+            };
+            page.on("response", onResponse);
+            let resource = null;
             try {
                 const resp = await page.goto(url, { waitUntil: "domcontentloaded", timeout: this.limits.crawlNavMs });
                 status = resp?.status() ?? "no-response";
+                const contentType = mediaTypeOf(resp?.headers()["content-type"]);
+                if (resp && isNonPageResource({ status: resp.status(), contentType }))
+                    resource = { url: page.url(), status: resp.status(), contentType: contentType };
             }
             catch (err) {
-                const explained = explainTimeout(err, "nav", this.limits.crawlNavMs);
-                const reason = explained instanceof Error ? explained.message.split("\n")[0] : String(explained);
-                // Not retried by later crawls in this process (a check would otherwise try it
-                // on every discovery round). Deliberately not written to memory: one outage
-                // must not count a route as covered in every later run's gap ledger.
-                if (!opts.measureOnly)
-                    this.loadFailedRoutes.add(normalizePath(url));
-                await this.errorPageCommitted(page);
-                summary.push(`${path} — LOAD FAILED`);
-                // The page a re-attach went back to never loaded, so nothing says whether it worked.
-                if (this.authLoss.reattaching)
-                    this.authLoss.abortReattach(`the page it went back to, ${path}, did not load (${reason})`);
-                problems.push(`${path}: ${reason}`);
+                // A browser that took the answer as a download failed the navigation, but the route did answer, with its status:
+                // a feed that is missing is the route's 404, not a page that did not load.
+                const seen = answered.last;
+                if (seen && isFileMediaType(seen.contentType))
+                    resource = { url: seen.url, status: seen.status, contentType: seen.contentType };
+                else {
+                    const explained = explainTimeout(err, "nav", this.limits.crawlNavMs);
+                    const reason = explained instanceof Error ? explained.message.split("\n")[0] : String(explained);
+                    // Not retried by later crawls in this process (a check would otherwise try it
+                    // on every discovery round). Deliberately not written to memory: one outage
+                    // must not count a route as covered in every later run's gap ledger.
+                    if (!opts.measureOnly)
+                        this.loadFailedRoutes.add(normalizePath(url));
+                    await this.errorPageCommitted(page);
+                    summary.push(`${path} — LOAD FAILED`);
+                    // The page a re-attach went back to never loaded, so nothing says whether it worked.
+                    if (this.authLoss.reattaching)
+                        this.authLoss.abortReattach(`the page it went back to, ${path}, did not load (${reason})`);
+                    problems.push(`${path}: ${reason}`);
+                    this.crawlHealth.push({
+                        path,
+                        url,
+                        status: null,
+                        loadError: reason,
+                        loginRedirect: false,
+                        elements: 0,
+                        unnamed: [],
+                        placeholderOnly: [],
+                        violations: [],
+                        geometry: [],
+                        brokenImages: [],
+                        design: [],
+                    });
+                    continue;
+                }
+            }
+            finally {
+                page.off("response", onResponse);
+            }
+            // A feed, a file or data: recorded as what it is and left there. It has no controls to collect or audit, and one
+            // that answered leaves the route contract, so it is neither a dead end nor a gap.
+            if (resource) {
+                if (!opts.measureOnly) {
+                    // Only a file that answered leaves the contract; a failing one is attempted with its status, as a failing page is.
+                    if (isNonPageResource(resource))
+                        memory.markResource(normalizePath(url), resource.contentType);
+                    else
+                        memory.markAttempted(normalizePath(url), `status:${resource.status}`, this.role);
+                }
+                this.oracles.drain(false);
+                summary.push(`${path} — ${resource.status} · not a page (${resource.contentType})`);
+                if (!isNonPageResource(resource))
+                    problems.push(`${path} → HTTP ${resource.status} (${resource.contentType})`);
                 this.crawlHealth.push({
                     path,
-                    url,
-                    status: null,
-                    loadError: reason,
+                    url: resource.url,
+                    status: resource.status,
+                    contentType: resource.contentType,
                     loginRedirect: false,
                     elements: 0,
                     unnamed: [],
@@ -4494,6 +4567,9 @@ export class BrowserEngine {
                 memory.visitState(fp, finalUrl, route, trackedElements(elements).map((el) => el.key), inertKeys(elements), this.sessionKey, aliases);
                 for (const f of forms)
                     memory.recordForm(fp, f.key, f.guarded, this.sessionKey);
+                // A route remembered as a feed or a file that now answers as a page (a route class whose ids serve both, or
+                // one that served a plain-text maintenance reply once) is a page again, so it rejoins the contract.
+                memory.clearResource(normalizePath(url));
                 memory.recordRoleAccess(this.role, route, "reached");
             }
             // If we landed somewhere else (auth wall, canonical redirect), the