scenescout 3.9.0 → 3.11.0

package/dist/engine/collector.js

@@ -19,21 +19,12 @@ export const VISIBLE_SRC = `(el) => {
     return style.visibility !== "hidden" && style.display !== "none";
   }`;
 /**
- * Anything that plausibly presents as a modal/dialog panel. Deliberately wider
- * than the ARIA set: a hand-rolled role-less modal must still count as "an
- * overlay is up", or the scroll-lock oracle files a false leaked-lock finding
- * against every healthy modal that locks the page behind it.
- */
-export const DIALOG_LIKE_SEL = '[role="dialog"], [role="alertdialog"], dialog[open], [aria-modal="true"], [class*="modal" i], [class*="dialog" i]';
-// Declared above the collector script because that script interpolates it.
-/**
- * Page-side interactable collector. Shipped as a STRING, not a function:
- * loader transforms (tsx/vitest esbuild hooks inject a `__name` helper) break
- * serialized functions inside the browser, where the helper doesn't exist.
- * A string expression is immune to any build/loader instrumentation.
+ * The collector's element path, as page-side source. Exported so a page-side
+ * probe that names an element (forms.ts) names it with the SAME path the
+ * snapshot listed it under, and the engine can map it back to that element's
+ * coverage key.
  */
-export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
-  const xpathOf = (el) => {
+export const XPATH_OF_SRC = `(el) => {
     const parts = [];
     let node = el;
     while (node && node.nodeType === 1 && node.tagName.toLowerCase() !== "html") {
@@ -47,9 +38,13 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
       node = node.parentElement;
     }
     return "/html/" + parts.join("/");
-  };
-  const visible = ${VISIBLE_SRC};
-  const accessibleName = (el) => {
+  }`;
+/**
+ * The collector's accessible name, as page-side source. Exported for the same
+ * reason as XPATH_OF_SRC: a page-side probe that names an element (forms.ts)
+ * must name it exactly as the snapshot did, or the two cannot be compared.
+ */
+export const ACCESSIBLE_NAME_SRC = `(el) => {
     const aria = el.getAttribute("aria-label");
     if (aria) return aria.trim();
     // aria-labelledby before any fallback: it is the standard way to name an
@@ -83,6 +78,51 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
     }
     const text = el.innerText || el.textContent || "";
     return text.trim().replace(/\\s+/g, " ").slice(0, 80);
+  }`;
+/**
+ * Anything that plausibly presents as a modal/dialog panel. Deliberately wider
+ * than the ARIA set: a hand-rolled role-less modal must still count as "an
+ * overlay is up", or the scroll-lock oracle files a false leaked-lock finding
+ * against every healthy modal that locks the page behind it.
+ */
+export const DIALOG_LIKE_SEL = '[role="dialog"], [role="alertdialog"], dialog[open], [aria-modal="true"], [class*="modal" i], [class*="dialog" i]';
+// Declared above the collector script because that script interpolates it.
+/**
+ * Page-side interactable collector. Shipped as a STRING, not a function:
+ * loader transforms (tsx/vitest esbuild hooks inject a `__name` helper) break
+ * serialized functions inside the browser, where the helper doesn't exist.
+ * A string expression is immune to any build/loader instrumentation.
+ */
+export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
+  const xpathOf = ${XPATH_OF_SRC};
+  const visible = ${VISIBLE_SRC};
+  const accessibleName = ${ACCESSIBLE_NAME_SRC};
+  // Whether a field's accessibleName came from something that is not a label. The
+  // name falls back to the placeholder, then the name attribute, then the type,
+  // so every field can be told apart and targeted, and it is half of the
+  // element's key, which project memory keeps across runs: it stays as it is.
+  // This says what the fallback hides. A real label is aria-label,
+  // aria-labelledby, a <label> (for= or wrapping, read through el.labels),
+  // title, or for a button-like input its value or the browser's default text.
+  // "placeholder" when the placeholder is all there is, "fallback" when not even
+  // that, null when the field is labelled or is not a field.
+  const nameFrom = (el) => {
+    const tag = el.tagName.toLowerCase();
+    if (tag !== "input" && tag !== "textarea") return null;
+    if ((el.getAttribute("aria-label") || "").trim()) return null;
+    const labelledBy = (el.getAttribute("aria-labelledby") || "").split(/\\s+/).filter(Boolean);
+    if (labelledBy.some((id) => { const n = document.getElementById(id); return n && (n.textContent || "").trim(); })) return null;
+    for (const label of Array.from(el.labels || [])) {
+      // A wrapping label's text includes a textarea's own content; that is not a label.
+      const own = label.contains(el) ? el.textContent || "" : "";
+      if ((label.textContent || "").replace(own, "").trim()) return null;
+    }
+    if ((el.getAttribute("title") || "").trim()) return null;
+    const type = tag === "input" ? el.type : "";
+    if (type === "submit" || type === "reset") return null;
+    if (type === "button" && (el.value || "").trim()) return null;
+    if (type === "image" && (el.getAttribute("alt") || "").trim()) return null;
+    return (el.getAttribute("placeholder") || "").trim() ? "placeholder" : "fallback";
   };
   const selector =
     'a[href], button, input, select, textarea, [role="button"], [role="link"], [role="tab"], ' +
@@ -257,6 +297,7 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
       tag,
       role,
       name: accessibleName(el),
+      nameFrom: nameFrom(el),
       testid: el.getAttribute("data-testid"),
       xpath: xpathOf(el),
       disabled: el.disabled === true || el.getAttribute("aria-disabled") === "true",
@@ -283,10 +324,45 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
  * as an accessibility defect — twice in one measured run.
  */
 const LIVE_REGION_ROLES = new Set(["status", "alert", "log", "timer", "marquee"]);
-/** Whether an element with this role and no accessible name is an unnamed control, as opposed to a live region with nothing in it yet. */
+/**
+ * Whether an element is an unnamed control, as opposed to a live region with
+ * nothing in it yet. A field whose shown name is only its name attribute or
+ * type is unnamed too: the collector fills those in so the field can be
+ * targeted, but nothing announces them.
+ */
 export function missingName(el) {
+    if (el.nameFrom === "fallback")
+        return true;
     return !el.name && !LIVE_REGION_ROLES.has(el.role);
 }
+/**
+ * Whether a field's only label is its placeholder. Kept apart from missingName
+ * because browsers do announce a placeholder when nothing else names the
+ * field, so it is not nameless; but the text is gone as soon as the user
+ * types, and it was never a label. The shown name must be non-empty: a blank
+ * aria-label ends the name before the placeholder is reached, so that field is
+ * unnamed (missingName) and only that.
+ */
+export function placeholderOnly(el) {
+    return el.nameFrom === "placeholder" && !!el.name;
+}
+/** How a crawl names a control in the check's evidence: by role and test id, or role and XPath. */
+export function describeControl(el) {
+    return `${el.role}${el.testid ? ` [testid=${el.testid}]` : ` at ${el.xpath}`}`;
+}
+/** A placeholder-only field's evidence: the control, then its placeholder, capped so a paragraph of hint text stays one line. */
+export function placeholderEvidence(el) {
+    const text = el.name.length > 80 ? `${el.name.slice(0, 79)}…` : el.name;
+    return `${describeControl(el)} "${text}"`;
+}
+/** The snapshot's flag for a field with no label, or null when it has one. */
+export function labelFlag(el) {
+    if (placeholderOnly(el))
+        return "no label: placeholder only";
+    if (el.nameFrom)
+        return "no label";
+    return null;
+}
 /** How the snapshot shows an element's name: an empty live region says so rather than reading as an unnamed control. */
 export function displayName(el) {
     if (el.name)

package/dist/engine/design.js

@@ -232,6 +232,9 @@ function hueOf([r, g, b]) {
     return Math.round((h * 60 + 360) % 360);
 }
 const label = (r) => (r.testid ? `[${r.testid}]` : `<${r.tag}> "${r.text.slice(0, 30) || "(no text)"}"`);
+/** One wording for a small target, page or shell alike: the shell section's, so its prose is unchanged. */
+const tinyTargetDetail = (r) => `${label(r)} — ${Math.round(r.rect.w)}×${Math.round(r.rect.h)}px tap target`;
+const clippedTextDetail = (r) => `${label(r)} — text is clipped by its container`;
 /**
  * Stable identity for one styled element, used to recognise the SAME component
  * across routes.
@@ -293,7 +296,7 @@ function tooSmall(r) {
 export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     const { records: allRecords, page } = payload;
     if (allRecords.length === 0) {
-        return { report: "DESIGN AUDIT: no visible styled elements found (page empty or not hydrated).", score: null, signatures: [] };
+        return { report: "DESIGN AUDIT: no visible styled elements found (page empty or not hydrated).", score: null, signatures: [], defects: [] };
     }
     const signatures = allRecords.map(styleSignature);
     const isChrome = (r) => chromeKeys.has(styleSignature(r));
@@ -302,7 +305,7 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     // set so no rule can accidentally reach past the page's own content.
     const records = chromeKeys.size > 0 ? allRecords.filter((r) => !isChrome(r)) : allRecords;
     if (records.length === 0) {
-        return { report: "DESIGN AUDIT: this page is entirely shared layout chrome — nothing page-specific to score.", score: null, signatures };
+        return { report: "DESIGN AUDIT: this page is entirely shared layout chrome — nothing page-specific to score.", score: null, signatures, defects: [] };
     }
     const sections = [];
     // ---- 1. CONTRAST (WCAG): normal text needs 4.5:1, large text (≥24px, or ≥18.7px bold) needs 3:1.
@@ -690,12 +693,10 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
     // shell — sub-minimum tap targets and clipped labels in a sidebar would be
     // seen by no page at all.
     const chromeSection = [];
+    const chromeDefects = [];
     if (chromeRecords.length > 0) {
-        const chromeIssues = [
-            ...contrastFailures(chromeRecords),
-            ...chromeRecords.filter((r) => r.interactive && tooSmall(r)).map((r) => `${label(r)} — ${Math.round(r.rect.w)}×${Math.round(r.rect.h)}px tap target`),
-            ...chromeRecords.filter((r) => r.clipped && r.textLen > 0).map((r) => `${label(r)} — text is clipped by its container`),
-        ];
+        chromeDefects.push(...contrastFailures(chromeRecords).map((detail) => ({ rule: "contrast", detail, chrome: true })), ...chromeRecords.filter((r) => r.interactive && tooSmall(r)).map((r) => ({ rule: "tiny-target", detail: tinyTargetDetail(r), chrome: true })), ...chromeRecords.filter((r) => r.clipped && r.textLen > 0).map((r) => ({ rule: "clipped-text", detail: clippedTextDetail(r), chrome: true })));
+        const chromeIssues = chromeDefects.map((d) => d.detail);
         if (chromeIssues.length > 0) {
             chromeSection.push(`SHARED CHROME (${chromeRecords.length} shell elements, excluded from this page's score and reported here instead):\n` +
                 [...new Set(chromeIssues)]
@@ -712,5 +713,20 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
         `\n\nJudge with product context: ⚠ lines are measurable defects; → lines are craft suggestions (how the page could be BETTER, not just what's broken). ` +
         `Not every flag is a bug — dense data tables legitimately use small targets. The score is a comparator across pages and runs, not an absolute verdict. ` +
         `File real defects with scout_finding (category "visual"/"a11y") and genuine improvement opportunities as severity-low "ux-polish", quoting the concrete numbers.`;
-    return { report, score, signatures };
+    const defects = [
+        ...contrastFails.map((detail) => ({ rule: "contrast", detail })),
+        // Worded exactly as the shell's (below), so one control is one fact whether or not it is known chrome yet.
+        ...tiny.map((r) => ({ rule: "tiny-target", detail: tinyTargetDetail(r) })),
+        ...clipped.filter((r) => r.textLen > 0).map((r) => ({ rule: "clipped-text", detail: clippedTextDetail(r) })),
+        ...focusless.map((f) => ({ rule: "focus-indicator", detail: `${f.label} — no visible focus indicator` })),
+        ...distorted.map(({ img, off }) => ({
+            rule: "image-aspect",
+            detail: `${img.label} — rendered ${img.rw}×${img.rh} vs natural ${img.nw}×${img.nh} (aspect off by ${Math.round(off * 100)}%)`,
+        })),
+        ...(page.scrollW > viewport.width + 8
+            ? [{ rule: "horizontal-scroll", detail: `content ${page.scrollW}px wide in a ${viewport.width}px viewport` }]
+            : []),
+        ...chromeDefects,
+    ];
+    return { report, score, signatures, defects };
 }

package/dist/engine/flow.js

@@ -0,0 +1,398 @@
+/**
+ * Saved flows: the steps `scenescout check` replays, as data.
+ *
+ * A flow is a short script a person or an agent wrote down once because it
+ * matters that it keeps working: open a page, click a control, see a result.
+ * The check replays every flow in `.scenescout/flows/*.json` after its crawl,
+ * with no model, so a flow that passed yesterday and breaks today fails the
+ * gate naming the flow and the step (ADR 12).
+ *
+ * The steps are `scout_run_plan`'s steps, so a plan that worked in an
+ * exploratory run can be saved as it is, plus three assertions a plan has no
+ * need for: text is visible, the URL matches, a request answered with a status.
+ *
+ * Everything here is pure: the schema and its error messages, the target
+ * grammar, and the rules that decide whether a URL or a request matched. The
+ * browser half is BrowserEngine.replayFlow, which only acts and reports.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { beaconResourceType, BROWSER_ENGINES } from "../browsers.js";
+import { MEMORY_DIRNAME, SELF_IGNORE_KEEP } from "./memory.js";
+/** Most steps one flow may hold. A longer flow is several flows, and each would fail more usefully on its own. */
+export const MAX_FLOW_STEPS = 50;
+/** Most flows one check replays. */
+export const MAX_FLOWS = 50;
+/** How long a step waits for its target, text, URL or request before it counts as broken. */
+export const FLOW_STEP_TIMEOUT_MS = 5000;
+/**
+ * How long a flow waits after its last step for a write that step set off
+ * late (a save on a timer, a debounced autosave), before it counts as passed.
+ */
+export const FLOW_AFTER_LAST_STEP_MS = 750;
+/** Where a project keeps its flows, relative to the project directory. */
+export const FLOWS_SUBDIR = path.join(MEMORY_DIRNAME, SELF_IGNORE_KEEP);
+export const TARGET_HELP = 'testid=…, text=…, label=… or role=<role>[name="…"]';
+/**
+ * The ARIA roles a `role=` target may name (WAI-ARIA 1.2, as Playwright's
+ * getByRole accepts them). A misspelt role matches nothing, so a flow using
+ * one would only ever fail at replay; it is refused when the file is read.
+ */
+export const ARIA_ROLE_LIST = [
+    "alert",
+    "alertdialog",
+    "application",
+    "article",
+    "banner",
+    "blockquote",
+    "button",
+    "caption",
+    "cell",
+    "checkbox",
+    "code",
+    "columnheader",
+    "combobox",
+    "complementary",
+    "contentinfo",
+    "definition",
+    "deletion",
+    "dialog",
+    "directory",
+    "document",
+    "emphasis",
+    "feed",
+    "figure",
+    "form",
+    "generic",
+    "grid",
+    "gridcell",
+    "group",
+    "heading",
+    "img",
+    "insertion",
+    "link",
+    "list",
+    "listbox",
+    "listitem",
+    "log",
+    "main",
+    "marquee",
+    "math",
+    "meter",
+    "menu",
+    "menubar",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "navigation",
+    "none",
+    "note",
+    "option",
+    "paragraph",
+    "presentation",
+    "progressbar",
+    "radio",
+    "radiogroup",
+    "region",
+    "row",
+    "rowgroup",
+    "rowheader",
+    "scrollbar",
+    "search",
+    "searchbox",
+    "separator",
+    "slider",
+    "spinbutton",
+    "status",
+    "strong",
+    "subscript",
+    "superscript",
+    "switch",
+    "tab",
+    "table",
+    "tablist",
+    "tabpanel",
+    "term",
+    "textbox",
+    "time",
+    "timer",
+    "toolbar",
+    "tooltip",
+    "tree",
+    "treegrid",
+    "treeitem",
+];
+export const ARIA_ROLES = new Set(ARIA_ROLE_LIST);
+export const ARIA_ROLES_MATCH_PLAYWRIGHT = ARIA_ROLE_LIST;
+/** Parse a target string, or null when it is not one. */
+export function parseTarget(target) {
+    for (const by of ["testid", "text", "label"]) {
+        if (target.startsWith(`${by}=`)) {
+            const value = target.slice(by.length + 1);
+            return value ? { by, value } : null;
+        }
+    }
+    const role = /^role=([a-z]+)(?:\[name=(?:"([^"]*)"|'([^']*)'|([^\]"']*))\])?$/i.exec(target);
+    if (!role)
+        return null;
+    const name = role[2] ?? role[3] ?? role[4];
+    return name === undefined ? { by: "role", role: role[1].toLowerCase() } : { by: "role", role: role[1].toLowerCase(), name };
+}
+const REQUEST_RE = /^(GET|POST|PUT|PATCH|DELETE|HEAD) (\/\S*)$/;
+function isRegex(pattern) {
+    try {
+        new RegExp(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const target = z
+    .string()
+    .refine((t) => parseTarget(t) !== null, { message: `must be ${TARGET_HELP}` })
+    .superRefine((t, ctx) => {
+    const parsed = parseTarget(t);
+    if (parsed?.by === "role" && !ARIA_ROLES.has(parsed.role)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `names the role "${parsed.role}", which is not an ARIA role (e.g. button, link, textbox, checkbox, tab)`,
+        });
+    }
+});
+const STEP_SCHEMAS = [
+    z.object({ action: z.literal("navigate"), target: z.string().regex(/^\//, "must be a path on the app, starting with /") }).strict(),
+    z.object({ action: z.literal("click"), target }).strict(),
+    z.object({ action: z.literal("type"), target, value: z.string(), pressEnter: z.boolean().optional(), replace: z.boolean().optional() }).strict(),
+    z.object({ action: z.literal("select"), target, value: z.string() }).strict(),
+    z.object({ action: z.literal("press"), value: z.string().min(1, "names the key to press, e.g. Enter") }).strict(),
+    z.object({ action: z.literal("expect-text"), text: z.string().min(1, "is the text that must be visible") }).strict(),
+    z.object({ action: z.literal("expect-url"), pattern: z.string().min(1).refine(isRegex, { message: "is not a valid regular expression" }) }).strict(),
+    z
+        .object({
+        action: z.literal("expect-request"),
+        request: z.string().regex(REQUEST_RE, 'must be a method and a path, e.g. "GET /api/things"'),
+        status: z.union([z.number().int().min(100).max(599), z.string().regex(/^[1-5]xx$/, 'must be a status such as 200, or a class such as "2xx"')]),
+    })
+        .strict(),
+];
+const stepSchema = z.discriminatedUnion("action", [...STEP_SCHEMAS]);
+export const FLOW_ACTIONS = STEP_SCHEMAS.map((s) => s.shape.action.value);
+const flowSchema = z
+    .object({
+    name: z.string().min(1).max(100).optional(),
+    description: z.string().max(500).optional(),
+    steps: z.array(stepSchema).min(1, "needs at least one step").max(MAX_FLOW_STEPS, `holds at most ${MAX_FLOW_STEPS} steps`),
+})
+    .strict()
+    .superRefine((flow, ctx) => {
+    // A flow starts from a page it names, never from wherever the crawl left the browser.
+    if (flow.steps[0] && flow.steps[0].action !== "navigate") {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["steps", 0, "action"], message: 'must be "navigate": a flow starts from a page it names' });
+    }
+});
+/** `steps[2].target`, the way a person would look for it in the file. */
+function fieldPath(p) {
+    if (p.length === 0)
+        return "(the whole file)";
+    return p.map((part, i) => (typeof part === "number" ? `[${part}]` : i === 0 ? part : `.${part}`)).join("");
+}
+function issueMessage(issue) {
+    if (issue.code === "unrecognized_keys")
+        return `unknown field(s) ${issue.keys.map((k) => `"${k}"`).join(", ")}`;
+    if (issue.code === "invalid_union_discriminator")
+        return `must be one of ${FLOW_ACTIONS.join(", ")}`;
+    if (issue.code === "invalid_type" && issue.received === "undefined")
+        return "is required";
+    return issue.message;
+}
+/** Validate one flow file's text. Every mistake names the file and the field. */
+export function parseFlow(text, file) {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        return { ok: false, error: `${file}: not valid JSON (${err instanceof Error ? err.message : String(err)})` };
+    }
+    const parsed = flowSchema.safeParse(json);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.slice(0, 5).map((i) => `${fieldPath(i.path)} ${issueMessage(i)}`);
+        const more = parsed.error.issues.length > 5 ? ` (and ${parsed.error.issues.length - 5} more)` : "";
+        return { ok: false, error: `${file}: ${issues.join("; ")}${more}` };
+    }
+    return { ok: true, flow: { name: parsed.data.name ?? file.replace(/\.json$/i, ""), file, steps: parsed.data.steps } };
+}
+/**
+ * Read every `*.json` in a flows directory, in name order. Throws on the first
+ * file that is not a valid flow: a flow that cannot be read would otherwise
+ * pass by never running. Everything else in the directory is returned as
+ * skipped with its reason, so nothing there is left out without saying so. A
+ * symbolic link is followed when it resolves to a file inside the directory,
+ * and skipped when it resolves anywhere else.
+ */
+export function loadFlows(dir) {
+    const realDir = fs.realpathSync(dir);
+    const files = [];
+    const skipped = [];
+    for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((x, y) => (x.name < y.name ? -1 : x.name > y.name ? 1 : 0))) {
+        if (e.isDirectory()) {
+            skipped.push({ file: e.name, reason: "a directory: flows are not read from subdirectories" });
+            continue;
+        }
+        if (!e.name.toLowerCase().endsWith(".json")) {
+            skipped.push({ file: e.name, reason: "not a .json file" });
+            continue;
+        }
+        if (e.isSymbolicLink()) {
+            let target;
+            try {
+                target = fs.realpathSync(path.join(dir, e.name));
+            }
+            catch {
+                skipped.push({ file: e.name, reason: "a symbolic link to nothing" });
+                continue;
+            }
+            if (!target.startsWith(realDir + path.sep)) {
+                skipped.push({ file: e.name, reason: "a symbolic link to a file outside the flows directory" });
+                continue;
+            }
+            if (!fs.statSync(target).isFile()) {
+                skipped.push({ file: e.name, reason: "a symbolic link to something that is not a file" });
+                continue;
+            }
+        }
+        else if (!e.isFile()) {
+            skipped.push({ file: e.name, reason: "not a regular file" });
+            continue;
+        }
+        files.push(e.name);
+    }
+    if (files.length > MAX_FLOWS)
+        throw new Error(`${dir} holds ${files.length} flows; a check replays at most ${MAX_FLOWS}`);
+    const flows = files.map((file) => {
+        const parsed = parseFlow(fs.readFileSync(path.join(dir, file), "utf8"), file);
+        if (!parsed.ok)
+            throw new Error(`flow ${parsed.error}`);
+        return parsed.flow;
+    });
+    return { flows, skipped };
+}
+/**
+ * Which flows directory a check uses: the one named, none for "off", and
+ * otherwise the project's own when it exists. A directory that was named and
+ * is missing is an error, never a quiet check with no flows.
+ */
+export function resolveFlowsDir(flag, projectDir, exists) {
+    if (flag === "off")
+        return { dir: null };
+    if (flag !== undefined)
+        return exists(flag) ? { dir: flag } : { error: `--flows: no directory at ${flag}` };
+    const own = path.join(projectDir, FLOWS_SUBDIR);
+    return { dir: exists(own) ? own : null };
+}
+/** A step as the report names it. */
+export function describeStep(step) {
+    switch (step.action) {
+        case "navigate":
+        case "click":
+        case "select":
+            return `${step.action} ${step.target}`;
+        case "type":
+            return `type into ${step.target}${step.pressEnter ? " and press Enter" : ""}`;
+        case "press":
+            return `press ${step.value}`;
+        case "expect-text":
+            return `expect text ${JSON.stringify(step.text)}`;
+        case "expect-url":
+            return `expect the URL to match /${step.pattern}/`;
+        case "expect-request":
+            return `expect ${step.request} → ${step.status}`;
+    }
+}
+/** Whether a step acts on the page (and so opens a new window for expect-request) rather than reading it. */
+export function isAction(step) {
+    return !step.action.startsWith("expect-");
+}
+/** Path, query and hash: what an expect-url pattern is tested against, so the same flow passes on a laptop and a preview deployment. */
+export function urlMatches(pattern, url) {
+    let tail;
+    try {
+        const u = new URL(url);
+        tail = `${u.pathname}${u.search}${u.hash}`;
+    }
+    catch {
+        tail = url;
+    }
+    return new RegExp(pattern).test(tail);
+}
+/** A path pattern against a request's path: equal segment for segment, where `*` stands for any one segment. A trailing slash is ignored. */
+export function requestPathMatches(pattern, pathname) {
+    const split = (p) => p.replace(/\/+$/, "").split("/");
+    const want = split(pattern);
+    const got = split(pathname);
+    return want.length === got.length && want.every((seg, i) => seg === "*" || seg === got[i]);
+}
+export function statusMatches(expected, status) {
+    return typeof expected === "number" ? status === expected : String(status)[0] === expected[0];
+}
+/**
+ * Whether the requests seen since the last action include the one a step
+ * expects. The reason says what was seen instead, which is what a person
+ * fixing it needs: the right request with the wrong status, or none at all.
+ */
+export function matchRequest(expect, seen) {
+    const [, method, pattern] = REQUEST_RE.exec(expect.request) ?? [];
+    const same = seen.filter((r) => {
+        if (r.method.toUpperCase() !== method)
+            return false;
+        try {
+            return requestPathMatches(pattern, new URL(r.url).pathname);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (same.some((r) => statusMatches(expect.status, r.status)))
+        return { ok: true };
+    if (same.length > 0) {
+        const statuses = [...new Set(same.map((r) => r.status))].join(", ");
+        return { ok: false, reason: `${expect.request} answered ${statuses}, expected ${expect.status}` };
+    }
+    return { ok: false, reason: `no ${expect.request} request was sent since the last action` };
+}
+/**
+ * The request kinds a refused write may be excused from a step for: what
+ * navigator.sendBeacon and <a ping> send, under every engine's name for it
+ * (browsers.ts `beaconResourceType`). They are fire-and-forget by design, a
+ * page sends them on its own schedule, and no step waits for one.
+ */
+export const BACKGROUND_REQUEST_TYPES = new Set(["ping", ...BROWSER_ENGINES.map(beaconResourceType)]);
+/**
+ * Split what the write policy refused during a step into what the step is
+ * charged with and background requests, which are only listed. The rule is
+ * the request's kind, never its origin: an app's API is often on another port
+ * or subdomain, and deciding by origin either hid a step's own write or
+ * blamed one on the app. So a fetch, an XHR or a form post is charged to the
+ * step wherever it goes, telemetry sent with fetch included; only a beacon or
+ * a ping is excused. A refusal with no kind recorded is charged. The app's
+ * origin is dropped from what is charged, for a shorter reason.
+ */
+export function splitRefusals(refusals, appOrigin) {
+    const charged = [];
+    const background = [];
+    for (const { sig, type } of refusals) {
+        if (type !== undefined && BACKGROUND_REQUEST_TYPES.has(type))
+            background.push(sig);
+        else
+            charged.push(sig.split(appOrigin).join(""));
+    }
+    return { charged, background };
+}
+/** The step a run stopped at, as the evidence of its issue or the reason the check could not run. */
+export function flowStepEvidence(run) {
+    if (run.outcome.status === "passed")
+        return "";
+    return `flow "${run.name}" (${run.file}) step ${run.outcome.step} of ${run.steps}, ${run.outcome.did}: ${run.outcome.reason}`;
+}