scenescout 3.17.0 → 3.19.0

package/dist/engine/browser.js

@@ -1,23 +1,23 @@
 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";
 import { describeInjection, newInjections, probeQueries, probeScript, probeShape, rememberProbe } from "./injection.js";
 import { AuthLossTracker } from "./authloss.js";
 import { captureClip, cutByViewport } from "./capture.js";
-import { STOP_ANIMATIONS_SCRIPT } from "./baseline.js";
+import { NEXT_FRAME_SCRIPT, NEXT_FRAME_WAIT_MS, STOP_ANIMATIONS_SCRIPT, steadyPicture, unsteadyNote } from "./baseline.js";
 import { COLLECT_INTERACTABLES_SCRIPT, COLLECTOR_CAP, NAME_SRC, POLICY_TEXT_SRC, VISIBLE_SRC, XPATH_OF_SRC, affordanceFlags, cutSummary, matchPrevious, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, frameLines, hasVisibleFrame, frameElementKey, frameLabel, masksForeignName, MASKED_NAME, capForeignName, stripForeignHref, frameToPageRect, displayName, missingName, placeholderOnly, placeholderEvidence, describeControl, labelFlag, stateFlags, stateChange, trackedElements, inertKeys, MAIN_REGION_SCRIPT, mainRegionLine, mainRegionTag, mainState, describeCover, } from "./collector.js";
 import { OracleMonitor, formatViolations, httpErrorDetail, planStopsAt, requestKey } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 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 { describeStep, elementStateMatches, FLOW_AFTER_LAST_STEP_MS, isAction, matchRequest, notActionable, parseTarget, repeatFailure, 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";
@@ -263,6 +263,8 @@ function actionabilityDiagnostic(message) {
 const SCREENCAST_PAGELESS_TICKS = 20;
 /** A frame for the record is worth a moment, not a stall: the action has already happened. */
 const RECORD_SHOT_TIMEOUT_MS = 2500;
+/** How long a repeat step waits for its condition after each round of its actions, before running them again. */
+const REPEAT_CHECK_MS = 1000;
 export class BrowserEngine {
     browser = null;
     /** How long an action and a page load may take; set at attach (limits.ts). */
@@ -1406,7 +1408,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 +1828,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 +2334,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 +4345,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 +4465,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 +4569,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
@@ -4914,6 +4992,46 @@ export class BrowserEngine {
                 return page.getByRole(target.role, target.name === undefined ? {} : { name: target.name });
         }
     }
+    /**
+     * Wait up to the action limit for a visible target to accept `action`, and
+     * say why it never did (flow.ts notActionable), or null once it can. Without
+     * this a disabled control failed as a bare action timeout that never said the
+     * control was there but disabled.
+     */
+    async waitUntilActionable(loc, action) {
+        const read = async () => notActionable(action, {
+            enabled: await loc.isEnabled({ timeout: 1000 }).catch(() => true),
+            editable: action === "type" ? await loc.isEditable({ timeout: 1000 }).catch(() => null) : null,
+        });
+        const until = Date.now() + this.limits.actionMs;
+        let reason = await read();
+        while (reason && Date.now() < until) {
+            await loc
+                .page()
+                .waitForTimeout(100)
+                .catch(() => { });
+            reason = await read();
+        }
+        return reason;
+    }
+    /**
+     * What an expect-element step asks of its target, read once: whether any
+     * match is visible, and, for the first visible match (or the first match when
+     * none is), whether it is enabled and checked. Null when nothing matches.
+     * The verdict is flow.ts's elementStateMatches, so the rules stay testable.
+     */
+    static async elementFacts(matches) {
+        const total = await matches.count().catch(() => 0);
+        if (total === 0)
+            return null;
+        const visible = matches.filter({ visible: true });
+        const anyVisible = (await visible.count().catch(() => 0)) > 0;
+        const el = anyVisible ? visible.first() : matches.first();
+        const enabled = await el.isEnabled({ timeout: 1000 }).catch(() => null);
+        // isChecked throws for an element that is not a checkbox, radio or [role=checkbox]: it has no checked state.
+        const checked = await el.isChecked({ timeout: 1000 }).catch(() => null);
+        return { visible: anyVisible, enabled, checked };
+    }
     /**
      * Replay one saved flow for `scenescout check`. Acts and reports only: the
      * schema, the matching rules and what an outcome means live in flow.ts and
@@ -4969,8 +5087,8 @@ export class BrowserEngine {
                 if (v.detail !== except)
                     violations.push({ path, violation: { kind: v.kind, severity: v.severity, detail: v.detail, url: v.url, ...(v.embed ? { embed: v.embed } : {}) } });
         };
-        const poll = async (done) => {
-            const until = Date.now() + this.limits.actionMs;
+        const poll = async (done, ms = this.limits.actionMs) => {
+            const until = Date.now() + ms;
             for (;;) {
                 if (done())
                     return true;
@@ -4979,119 +5097,170 @@ export class BrowserEngine {
                 await (this.page ?? page).waitForTimeout(100).catch(() => { });
             }
         };
-        try {
-            for (const [i, step] of steps.entries()) {
-                const n = i + 1;
-                const did = describeStep(step);
-                if (isAction(step))
-                    seen = [];
-                let failure = null;
-                let refusal = null;
-                this.actionStartedAt = Date.now();
-                if (step.action === "click" || step.action === "type" || step.action === "select" || step.action === "press")
-                    await this.beginInput();
-                try {
-                    const current = this.requirePage();
-                    if (step.action === "navigate") {
-                        const resolved = resolveTarget(this.baseUrl, step.target);
-                        if (!("url" in resolved))
-                            throw new Error(resolved.problem);
-                        const url = resolved.url;
-                        const resp = await current
-                            .goto(url, { waitUntil: "domcontentloaded", timeout: this.limits.crawlNavMs })
-                            .catch((err) => Promise.reject(explainTimeout(err, "nav", this.limits.crawlNavMs)));
+        /**
+         * Run one step that acts or asserts once, with the bookkeeping every step gets: the requests it caused, the
+         * writes the policy refused while it ran, and the oracles' violations. `actionMs` is how long it may wait; a
+         * repeat's condition is checked with a shorter wait, since the next repeat is what it waits for.
+         */
+        const runStep = async (step, actionMs = this.limits.actionMs) => {
+            if (isAction(step))
+                seen = [];
+            let failure = null;
+            let refusal = null;
+            this.actionStartedAt = Date.now();
+            if (step.action === "click" || step.action === "type" || step.action === "select" || step.action === "press")
+                await this.beginInput();
+            try {
+                const current = this.requirePage();
+                if (step.action === "navigate") {
+                    const resolved = resolveTarget(this.baseUrl, step.target);
+                    if (!("url" in resolved))
+                        throw new Error(resolved.problem);
+                    const url = resolved.url;
+                    const resp = await current
+                        .goto(url, { waitUntil: "domcontentloaded", timeout: this.limits.crawlNavMs })
+                        .catch((err) => Promise.reject(explainTimeout(err, "nav", this.limits.crawlNavMs)));
+                    await this.settle();
+                    const status = resp?.status() ?? null;
+                    if (status !== null && status >= 400) {
+                        failure = `the page answered HTTP ${status}`;
+                        // The page's own status is this step's failure; the oracle's record of the same response is not a second issue.
+                        // The oracle stores its details redacted (redactViolation), so the comparison is redacted too.
+                        collect(redactSecrets(httpErrorDetail("GET", current.url().replace(/#.*$/, ""), status)));
+                    }
+                }
+                else if (step.action === "upload") {
+                    const loc = step.target ? BrowserEngine.locatorFor(current, parseTarget(step.target)).first() : null;
+                    const outcome = await this.performUpload(loc, { ...(step.fixture ? { fixture: step.fixture } : {}), ...(step.name ? { name: step.name } : {}) });
+                    if (outcome.refused)
+                        failure = outcome.refused.split("\n")[0];
+                    else
+                        await this.settle();
+                }
+                else if (step.action === "press") {
+                    refusal = await this.vetFocusedActivation(step.value);
+                    if (!refusal) {
+                        await current.keyboard.press(step.value);
                         await this.settle();
-                        const status = resp?.status() ?? null;
-                        if (status !== null && status >= 400) {
-                            failure = `the page answered HTTP ${status}`;
-                            // The page's own status is this step's failure; the oracle's record of the same response is not a second issue.
-                            // The oracle stores its details redacted (redactViolation), so the comparison is redacted too.
-                            collect(redactSecrets(httpErrorDetail("GET", current.url().replace(/#.*$/, ""), status)));
-                        }
                     }
-                    else if (step.action === "press") {
-                        refusal = await this.vetFocusedActivation(step.value);
-                        if (!refusal) {
-                            await current.keyboard.press(step.value);
-                            await this.settle();
-                        }
+                }
+                else if (step.action === "click" || step.action === "type" || step.action === "select") {
+                    const loc = BrowserEngine.locatorFor(current, parseTarget(step.target)).first();
+                    const found = await loc
+                        .waitFor({ state: "visible", timeout: actionMs })
+                        .then(() => true)
+                        .catch(() => false);
+                    const blocked = found ? await this.waitUntilActionable(loc, step.action) : null;
+                    if (!found) {
+                        failure = `nothing visible matches ${step.target} within ${actionMs / 1000}s — ${limitHint("action", actionMs)}`;
                     }
-                    else if (step.action === "click" || step.action === "type" || step.action === "select") {
-                        const loc = BrowserEngine.locatorFor(current, parseTarget(step.target)).first();
-                        const found = await loc
-                            .waitFor({ state: "visible", timeout: this.limits.actionMs })
-                            .then(() => true)
-                            .catch(() => false);
-                        if (!found) {
-                            failure = `nothing visible matches ${step.target} within ${this.limits.actionMs / 1000}s — ${limitHint("action", this.limits.actionMs)}`;
+                    else if (blocked) {
+                        // The state first, since it is what is true; the hint still applies when the app enables it late.
+                        failure = `${step.target} ${blocked} after ${actionMs / 1000}s — ${limitHint("action", actionMs)}`;
+                    }
+                    else {
+                        const label = ((await loc.getAttribute("aria-label").catch(() => null)) ??
+                            (await loc.textContent({ timeout: 1000 }).catch(() => null)) ??
+                            "").trim();
+                        // A dropdown is named by all its options; a select step is judged by the option it picks (destructiveLabelOf).
+                        const isSelect = step.action === "select" && (await loc.evaluate((n) => n.tagName.toLowerCase() === "select").catch(() => false));
+                        const testid = await loc.getAttribute("data-testid").catch(() => null);
+                        if (this.readOnly &&
+                            step.action !== "type" &&
+                            (isSelect
+                                ? pickIsDestructive(step.value, testid, await BrowserEngine.chosenOptionLabel(loc, step.value))
+                                : isDestructive(label, step.action === "select" ? step.value : undefined))) {
+                            refusal = destructiveRefusal(label || step.target, this.mode);
+                        }
+                        else if (step.action === "click") {
+                            await loc.click({ timeout: actionMs });
+                        }
+                        else if (step.action === "select") {
+                            await loc.selectOption(step.value, { timeout: actionMs });
                         }
                         else {
-                            const label = ((await loc.getAttribute("aria-label").catch(() => null)) ??
-                                (await loc.textContent({ timeout: 1000 }).catch(() => null)) ??
-                                "").trim();
-                            // A dropdown is named by all its options; a select step is judged by the option it picks (destructiveLabelOf).
-                            const isSelect = step.action === "select" && (await loc.evaluate((n) => n.tagName.toLowerCase() === "select").catch(() => false));
-                            const testid = await loc.getAttribute("data-testid").catch(() => null);
-                            if (this.readOnly &&
-                                step.action !== "type" &&
-                                (isSelect
-                                    ? pickIsDestructive(step.value, testid, await BrowserEngine.chosenOptionLabel(loc, step.value))
-                                    : isDestructive(label, step.action === "select" ? step.value : undefined))) {
-                                refusal = destructiveRefusal(label || step.target, this.mode);
-                            }
-                            else if (step.action === "click") {
-                                await loc.click({ timeout: this.limits.actionMs });
-                            }
-                            else if (step.action === "select") {
-                                await loc.selectOption(step.value, { timeout: this.limits.actionMs });
-                            }
-                            else {
-                                await this.noteProbe(step.value, step.target);
-                                await this.fillOrAppend(loc, step.value, step.replace ?? false);
-                                if (step.pressEnter) {
-                                    const submit = loc.locator("xpath=ancestor::form[1]").locator('[type="submit"], button:not([type="button"]):not([type="reset"])').first();
-                                    const submitLabel = ((await submit.textContent({ timeout: 1000 }).catch(() => "")) ?? "").trim();
-                                    if (this.readOnly && isDestructive(submitLabel))
-                                        refusal = destructiveRefusal(submitLabel, this.mode);
-                                    else
-                                        await loc.press("Enter", { timeout: this.limits.actionMs });
-                                }
+                            await this.noteProbe(step.value, step.target);
+                            await this.fillOrAppend(loc, step.value, step.replace ?? false);
+                            if (step.pressEnter) {
+                                const submit = loc.locator("xpath=ancestor::form[1]").locator('[type="submit"], button:not([type="button"]):not([type="reset"])').first();
+                                const submitLabel = ((await submit.textContent({ timeout: 1000 }).catch(() => "")) ?? "").trim();
+                                if (this.readOnly && isDestructive(submitLabel))
+                                    refusal = destructiveRefusal(submitLabel, this.mode);
+                                else
+                                    await loc.press("Enter", { timeout: actionMs });
                             }
-                            if (!refusal)
-                                await this.settle();
                         }
+                        if (!refusal)
+                            await this.settle();
                     }
-                    else if (step.action === "expect-text") {
-                        const visible = current.getByText(step.text, { exact: false }).filter({ visible: true }).first();
-                        const ok = await visible
-                            .waitFor({ state: "visible", timeout: this.limits.actionMs })
-                            .then(() => true)
-                            .catch(() => false);
-                        if (!ok)
-                            failure = `no visible text ${JSON.stringify(step.text)} within ${this.limits.actionMs / 1000}s — ${limitHint("action", this.limits.actionMs)}`;
-                    }
-                    else if (step.action === "expect-url") {
-                        const ok = await poll(() => urlMatches(step.pattern, this.page?.url() ?? ""));
-                        if (!ok)
-                            failure = `the page is at ${here()}, which does not match /${step.pattern}/`;
-                    }
-                    else {
-                        let last = { ok: false, reason: "" };
-                        await poll(() => (last = matchRequest(step, seen)).ok);
-                        if (!last.ok)
-                            failure = last.reason;
+                }
+                else if (step.action === "expect-text") {
+                    const visible = current.getByText(step.text, { exact: false }).filter({ visible: true }).first();
+                    const ok = await visible
+                        .waitFor({ state: "visible", timeout: actionMs })
+                        .then(() => true)
+                        .catch(() => false);
+                    if (!ok)
+                        failure = `no visible text ${JSON.stringify(step.text)} within ${actionMs / 1000}s — ${limitHint("action", actionMs)}`;
+                }
+                else if (step.action === "expect-element") {
+                    const matches = BrowserEngine.locatorFor(current, parseTarget(step.target));
+                    const until = Date.now() + actionMs;
+                    let verdict = elementStateMatches(step.state, await BrowserEngine.elementFacts(matches));
+                    while (!verdict.ok && Date.now() < until) {
+                        await current.waitForTimeout(100).catch(() => { });
+                        verdict = elementStateMatches(step.state, await BrowserEngine.elementFacts(matches));
                     }
+                    if (!verdict.ok)
+                        failure = `${step.target} ${verdict.actual}, expected ${step.state}, after ${actionMs / 1000}s`;
                 }
-                catch (err) {
-                    failure = firstLineOf(explainTimeout(err, "action", this.limits.actionMs));
+                else if (step.action === "expect-url") {
+                    const ok = await poll(() => urlMatches(step.pattern, this.page?.url() ?? ""), actionMs);
+                    if (!ok)
+                        failure = `the page is at ${here()}, which does not match /${step.pattern}/`;
                 }
-                await this.scanForInjections().catch(() => { });
-                await this.scanForContradictions().catch(() => { });
-                // What the write policy refused of the app's own requests while this step ran is the step's, whatever caused it.
-                const blocked = ownRefusals();
-                if (!refusal && blocked.length > 0)
-                    refusal = `the ${this.writeRule.at()} write policy refused ${blocked.join(", ")}`;
-                collect();
+                else {
+                    let last = { ok: false, reason: "" };
+                    await poll(() => (last = matchRequest(step, seen)).ok, actionMs);
+                    if (!last.ok)
+                        failure = last.reason;
+                }
+            }
+            catch (err) {
+                failure = firstLineOf(explainTimeout(err, "action", actionMs));
+            }
+            await this.scanForInjections().catch(() => { });
+            await this.scanForContradictions().catch(() => { });
+            // What the write policy refused of the app's own requests while this step ran is the step's, whatever caused it.
+            const blocked = ownRefusals();
+            if (!refusal && blocked.length > 0)
+                refusal = `the ${this.writeRule.at()} write policy refused ${blocked.join(", ")}`;
+            collect();
+            return { failure, refusal };
+        };
+        /** A repeat step: its condition first, then its actions and the condition again, at most `max` times. */
+        const runRepeat = async (step) => {
+            for (let k = 0;; k++) {
+                // A short wait every time, the first look included: an instant one misses what is already on the page.
+                const check = await runStep(step.until, Math.min(REPEAT_CHECK_MS, this.limits.actionMs));
+                if (check.refusal)
+                    return check;
+                if (!check.failure)
+                    return { failure: null, refusal: null };
+                if (k === step.max)
+                    return { failure: repeatFailure(step.until, step.max, check.failure), refusal: null };
+                for (const inner of step.steps) {
+                    const r = await runStep(inner);
+                    if (r.refusal || r.failure)
+                        return { failure: r.failure && `repeat ${k + 1} of at most ${step.max}, ${describeStep(inner)}: ${r.failure}`, refusal: r.refusal };
+                }
+            }
+        };
+        try {
+            for (const [i, step] of steps.entries()) {
+                const n = i + 1;
+                const did = describeStep(step);
+                const { failure, refusal } = step.action === "repeat" ? await runRepeat(step) : await runStep(step);
                 if (refusal)
                     return done({ status: "refused", step: n, did, reason: refusal.split("\n")[0], path: here() });
                 if (failure)
@@ -5307,7 +5476,9 @@ export class BrowserEngine {
      * stopped, then either the viewport from the top (no target) or one element,
      * found the way a saved flow finds its target, with `how.margin` around it.
      * The screenshot is taken with `how`'s animation and caret settings, at one
-     * picture pixel per CSS pixel. Reads only. Throws a sentence when it cannot
+     * picture pixel per CSS pixel, and again a frame later until two in a row
+     * are the same (steadyPicture); `unsteady` says so when the page never held
+     * still within the action limit. Reads only. Throws a sentence when it cannot
      * take the picture. `cut` says when an element reaches outside the window.
      * What is compared and what it means is baseline.ts, which also holds the
      * settings; the rectangle is capture.ts. Call endBaselineCaptures when done.
@@ -5346,11 +5517,10 @@ export class BrowserEngine {
         const viewport = page.viewportSize() ?? (await page.evaluate("({ width: innerWidth, height: innerHeight })"));
         const deviceScaleFactor = Number(await page.evaluate("window.devicePixelRatio"));
         const settings = { type: "png", animations: how.animations, caret: how.caret, scale: "css", timeout: this.limits.actionMs };
-        let png;
+        let clip;
         let cut = null;
         if (!target) {
             await page.evaluate("window.scrollTo(0, 0)");
-            png = await action(page.screenshot(settings));
         }
         else {
             const locator = BrowserEngine.locatorFor(page, target).first();
@@ -5361,14 +5531,18 @@ export class BrowserEngine {
             const box = await action(locator.boundingBox({ timeout: this.limits.actionMs }));
             if (!box)
                 throw new Error("it is not displayed");
-            const clip = captureClip(box, how.margin, viewport);
+            clip = captureClip(box, how.margin, viewport) ?? undefined;
             if (!clip)
                 throw new Error("it is outside the viewport");
             cut = cutByViewport(box, viewport);
-            png = await action(page.screenshot({ ...settings, clip }));
         }
+        // Two pictures in a row the same, a frame apart: the page has drawn the stop and stopped changing (steadyPicture).
+        const { png, steady } = await steadyPicture(() => action(page.screenshot(clip ? { ...settings, clip } : settings)), 
+        // Bounded here too, since a page whose main thread is stuck never runs the script's own fallback. A wait that
+        // fails (the page navigated) is not the picture's error: the next take reports what is wrong with the page.
+        () => BrowserEngine.settleWithin(page.evaluate(NEXT_FRAME_SCRIPT), NEXT_FRAME_WAIT_MS), this.limits.actionMs);
         this.logAction({ action: "capture", target: target ? `baseline ${pathOnApp}` : `baseline ${pathOnApp} (page)`, url: page.url() });
-        return { png, viewport, deviceScaleFactor, cut };
+        return { png, viewport, deviceScaleFactor, cut, unsteady: steady ? null : unsteadyNote(this.limits.actionMs) };
     }
     /** Stop telling the page to reduce motion, so what runs after the baselines (saved flows) sees the page as a user does. */
     async endBaselineCaptures() {