scenescout 3.8.0 → 3.10.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.
+ * 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 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 = (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)
@@ -402,13 +478,89 @@ export const BROKEN_IMAGES_SCRIPT = `(() => {
   }
   return { images, total };
 })()`;
+/**
+ * An element's coverage key inside a frame: the frame's origin (another site)
+ * or path (the app's own) before the element's own key, so a "Submit" in an
+ * embed is not the page's "Submit". Elements of the page itself keep their key
+ * unchanged, so pages without frames keep the coverage they had.
+ */
+export function frameElementKey(baseKey, frame) {
+    if (!frame)
+        return baseKey;
+    let where = frame.origin || frame.url;
+    if (!frame.foreign) {
+        try {
+            const u = new URL(frame.url);
+            // A frame with no web address (srcdoc, about:blank) is told apart by its title.
+            where = u.protocol === "http:" || u.protocol === "https:" ? u.pathname : `${frame.url}#${frame.title}`;
+        }
+        catch {
+            where = `${frame.url}#${frame.title}`;
+        }
+    }
+    return `frame:${where}|${baseKey}`;
+}
+/** The longest name kept for a control in another site's frame: a chat that renders messages as buttons would otherwise print them whole. */
+export const MAX_FOREIGN_NAME = 40;
+/** A control's name from another site's frame, cut to MAX_FOREIGN_NAME. */
+export function capForeignName(name) {
+    return name.length > MAX_FOREIGN_NAME ? `${name.slice(0, MAX_FOREIGN_NAME)}…` : name;
+}
+/** A link's address from another site's frame without its query and fragment, where tokens and addresses travel. */
+export function stripForeignHref(href) {
+    try {
+        const u = new URL(href);
+        return u.origin + u.pathname;
+    }
+    catch {
+        return href.split(/[?#]/)[0];
+    }
+}
+/**
+ * A rect read inside a frame, in the page's document coordinates: the frame
+ * element's box on screen, less the frame's own scroll, plus the page's.
+ */
+export function frameToPageRect(rect, box, frameScroll, pageScroll) {
+    return { ...rect, x: rect.x + box.x + pageScroll.x - frameScroll.x, y: rect.y + box.y + pageScroll.y - frameScroll.y };
+}
+/** How a snapshot line names the frame an element is in. */
+export function frameLabel(frame) {
+    let where = frame.url;
+    if (!frame.foreign) {
+        try {
+            const u = new URL(frame.url);
+            where = u.pathname + u.search;
+        }
+        catch {
+            /* shown as it is */
+        }
+    }
+    else if (frame.origin)
+        where = frame.origin;
+    return `${frame.foreign ? "cross-origin" : "same-origin"} frame ${where.slice(0, 80)}${frame.title ? ` "${frame.title.slice(0, 40)}"` : ""}`;
+}
+/**
+ * Whether an element's name, read from another site's frame, is masked. A
+ * name taken from a container's text — a select's options, a textarea's
+ * contents, a tagged <div> — can carry other people's data (a support chat,
+ * a customer record) into the snapshot, the transcript and the report. The
+ * label of a link, a button or a field is the interface itself and is kept:
+ * the agent needs it to act.
+ */
+export function masksForeignName(tag, role) {
+    if (tag === "a" || tag === "button" || tag === "input")
+        return false;
+    return !/^(button|link|tab|menuitem|checkbox|switch|radio)$/.test(role);
+}
+/** The name shown for a masked element. */
+export const MASKED_NAME = "(content masked: another site's frame)";
 /** A frame smaller than this in both directions is plumbing (a tracking pixel, a messaging bridge), not something a user sees. */
 const VISIBLE_FRAME_PX = 2;
 /**
- * The snapshot's account of the page's frames. Nothing inside a frame is
- * collected or can be acted on yet, and a page that shows its form in an
- * embed used to look like a page with no form at all: say what is there,
- * where it comes from, and that it was not looked inside. `nested` counts
+ * The snapshot's account of the page's frames: what is embedded, where it
+ * comes from, and whether its controls were read (`read`, by frame URL) —
+ * a page that shows its form in an embed used to look like a page with no
+ * form at all. Without `read`, nothing was looked inside. `nested` counts
  * frames that are not read: nested inside others, or past the first 30; `writesRefused` is false only in
  * destructive mode, where a foreign frame's writes do go out.
  */
@@ -436,12 +588,22 @@ export function frameLines(appUrl, frames, opts = {}) {
             /* about:blank, srcdoc: shown as they are */
         }
         const label = f.title ? ` "${f.title.slice(0, 60)}"` : "";
+        let frameOrigin = "";
+        try {
+            frameOrigin = new URL(f.url).origin;
+        }
+        catch {
+            /* no origin */
+        }
         const writes = f.foreign
             ? opts.writesRefused === false
                 ? " — its writes go out (destructive mode)"
-                : " — writes it sends outside the app are refused"
+                : opts.trustedWrites?.has(frameOrigin)
+                    ? " — trusted embed: its writes go out (safe-write)"
+                    : " — writes it sends outside the app are refused"
             : "";
-        return `  ${f.foreign ? "cross-origin" : "same-origin"} ${where.slice(0, 120)}${label} ${f.width}×${f.height}${writes}`;
+        const read = opts.read ? (opts.read.has(f.url) ? " — controls listed above" : " — not read") : "";
+        return `  ${f.foreign ? "cross-origin" : "same-origin"} ${where.slice(0, 120)}${label} ${f.width}×${f.height}${read}${writes}`;
     });
     if (visible.length > 10)
         lines.push(`  … +${visible.length - 10} more`);
@@ -449,7 +611,14 @@ export function frameLines(appUrl, frames, opts = {}) {
         lines.push(`  (+${hidden} hidden frame${hidden === 1 ? "" : "s"})`);
     if (nested > 0)
         lines.push(`  (+${nested} more frame${nested === 1 ? "" : "s"}, nested inside those or past the first 30, not read)`);
-    return [`FRAMES not explored — their controls are not listed above and cannot be acted on:`, ...lines];
+    const header = opts.read && opts.read.size > 0
+        ? "FRAMES — the controls of each frame read are listed above, marked ⟨in … frame⟩, and can be acted on by ref" +
+            (visible.some((f) => f.foreign)
+                ? "; in another site's frame, content is masked and hostile input, repeated-click probes and uploads are refused"
+                : "") +
+            ":"
+        : "FRAMES not explored — their controls are not listed above and cannot be acted on:";
+    return [header, ...lines];
 }
 /** Whether any frame on the page is one a user can see. */
 export function hasVisibleFrame(frames) {

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/forms.js

@@ -0,0 +1,290 @@
+/**
+ * Forms never submitted empty.
+ *
+ * The commonest defect behind a form is a submit that silently does nothing
+ * when its required fields are blank: no request, no message. The engine
+ * already notes a submit-style click that fires no request, but only when
+ * somebody tries the empty submit, and lanes that fill a form in and submit
+ * it rarely do. So scout_coverage lists every form a session saw that no
+ * session has yet submitted empty.
+ *
+ * THE DEFINITION. A form is a `<form>` element. Its controls are the ones the
+ * browser associates with it (`form.elements`), so a submit button outside
+ * the element linked back by `form="id"` is one of them. It is tracked when it
+ * has a native submit control (a `<button>` with no type or type="submit", an
+ * `<input type="submit|image">`) and at least one TEXT-ENTRY field.
+ *
+ * IDENTITY (formIdentity), per route, first match wins:
+ *   1. the form's own `id` attribute         → `form:#signup`
+ *   2. its `name` attribute                  → `form:name=pay`
+ *   3. its `action` attribute with its method → `form:POST /things`
+ *   4. only when it has none of those, the coverage key the snapshot gives its
+ *      first submit control (`tid:thing-save`, `button:save`).
+ * The form's own attributes come first because a submit control's key is the
+ * weakest name it has: an untagged "Save" in two tab panels is the same key
+ * for two forms, and a label that changes ("Pay $12", "Saving…") is a new key
+ * for the same one. Attributes are read with getAttribute, never `form.id` or
+ * `form.name`, which a field named "id" or "name" shadows.
+ *
+ * Only the inventory (a snapshot, a crawl, a plan's capture) puts a form on
+ * the list. A submit only marks a listed form; one that cannot be matched to
+ * a listed form is logged (FORMS_SUBMIT_UNMATCHED), never guessed.
+ *
+ * A text-entry field is a `<textarea>`, or an `<input>` whose type takes typed
+ * text (TEXT_ENTRY_TYPES), that is visible, not disabled (itself or by a
+ * disabled fieldset) and not read-only. Checkboxes, radios, selects, file,
+ * hidden, search, range and colour inputs are not: none of them can be "left
+ * blank" by typing, and a search box's empty submit is a filter, not the
+ * defect this looks for.
+ *
+ * A form counts as SUBMITTED EMPTY when a submit happened while every one of
+ * its text-entry fields held the empty string (whitespace is content: that is
+ * a separate boundary probe). A submit is a click on one of its native submit
+ * controls, or Enter where the browser's implicit submission applies: in one
+ * of its text-like inputs (IMPLICIT_SUBMIT_TYPES) while its default button is
+ * enabled, or on a focused submit control. It counts whether the click or key
+ * came from scout_click, scout_type's pressEnter, scout_press or a plan step.
+ * A form with no text-entry field is never listed, and neither is one whose
+ * every submit control is disabled while its fields are blank: the page
+ * already refuses the empty submit, and nothing could clear the entry.
+ *
+ * WHY ONLY `<form>`. A "form-like group" of loose fields and buttons had to be
+ * guessed from layout and button labels. The guess listed page chrome (a
+ * header search box beside "Sign in", under an app root that held every
+ * row's "Add" button) and walked the whole document once per button. A real
+ * form is the one grouping the browser itself submits, so it is exact and
+ * cheap (`document.forms`).
+ *
+ * NOT CAUGHT, by design of the above:
+ *   - fields and a save button with no `<form>` around them (a JS-driven panel);
+ *   - forms whose only submit control is a `role="button"` element, or a
+ *     `<button type="button">` wired up in script;
+ *   - forms that submit from script on change (`form.submit()` in a handler);
+ *   - Ctrl+Enter or Cmd+Enter in a textarea, which some apps treat as send.
+ * And kept apart imperfectly, by design of IDENTITY:
+ *   - forms with no id or name that share an action and method are one entry,
+ *     so an empty submit of one clears them all;
+ *   - forms with no id, name or action whose first submit controls are the
+ *     same untagged button ("Save") are one entry too;
+ *   - on a page with more controls than a snapshot lists (150), a form with
+ *     none of those attributes whose submit control is past the cap is not
+ *     tracked at all.
+ *
+ * The page reports facts; the rule deciding what they mean lives here as pure
+ * functions, so it is table-tested (memory-test) without a browser.
+ */
+import { ACCESSIBLE_NAME_SRC, VISIBLE_SRC, XPATH_OF_SRC } from "./collector.js";
+import { normalizePath } from "./fingerprint.js";
+/**
+ * Action-log entries this bookkeeping writes. They record what the engine
+ * could not do, not a step anyone took on the page: pace.ts does not count
+ * them as actions and a finding's repro trace leaves them out.
+ */
+export const FORMS_READ_FAILED = "forms:read-failed";
+export const FORMS_SUBMIT_UNMATCHED = "forms:submit-unmatched";
+/** Whether an action-log entry is this bookkeeping rather than a step. */
+export function isFormBookkeeping(action) {
+    return action === FORMS_READ_FAILED || action === FORMS_SUBMIT_UNMATCHED;
+}
+/** The form's identity from its own attributes, or null when it has none (see IDENTITY above). */
+export function formIdentity(attrs) {
+    const id = attrs.id.trim();
+    if (id)
+        return `form:#${id.slice(0, 80)}`;
+    const name = attrs.name.trim();
+    if (name)
+        return `form:name=${name.slice(0, 80)}`;
+    // Normalized as a route is: a record id or a per-load token in the action
+    // would otherwise name a new form on every record or every load.
+    const action = attrs.action.trim();
+    if (action)
+        return `form:${(attrs.method.trim() || "get").toUpperCase()} ${normalizePath(action).slice(0, 120)}`;
+    return null;
+}
+/**
+ * Whether a snapshot element is the submit control the probe found. An xpath
+ * alone is not enough: a sibling added or removed since the snapshot makes the
+ * same path name another button (a "Cancel" where "Send" was). The testid and
+ * the accessible name, computed by the collector's own rule, must agree too.
+ */
+export function sameControl(el, probe) {
+    return (el.testid ?? null) === (probe.submitTestid ?? null) && el.name === probe.submitName;
+}
+/** Input types that take typed text. `search` is left out on purpose (see above). */
+export const TEXT_ENTRY_TYPES = new Set([
+    "text",
+    "email",
+    "number",
+    "tel",
+    "url",
+    "password",
+    "date",
+    "datetime-local",
+    "month",
+    "week",
+    "time",
+]);
+/**
+ * Input types in which Enter submits the form (the HTML standard's implicit
+ * submission). Not checkboxes, radios or buttons: Enter does nothing there.
+ */
+export const IMPLICIT_SUBMIT_TYPES = new Set([...TEXT_ENTRY_TYPES, "search"]);
+/** Whether a field takes typed text and a user could type into it right now. */
+export function isTextEntry(f) {
+    if (!f.visible || f.disabled || f.readOnly)
+        return false;
+    if (f.tag === "textarea")
+        return true;
+    return f.tag === "input" && TEXT_ENTRY_TYPES.has(f.type || "text");
+}
+/** Whether a form is tracked at all: it must hold something to leave blank. */
+export function tracksForm(fields) {
+    return fields.some(isTextEntry);
+}
+/** Whether every text-entry field is empty — and there is at least one. */
+export function allTextEmpty(fields) {
+    const text = fields.filter(isTextEntry);
+    return text.length > 0 && text.every((f) => !f.filled);
+}
+/**
+ * What the inventory makes of a form: not tracked, tracked and owed an empty
+ * submit, or GUARDED — every submit control disabled while the fields are
+ * blank, so the page itself refuses the empty submit and nobody could clear
+ * the entry by trying it.
+ */
+export function formStatus(form) {
+    if (!tracksForm(form.fields))
+        return "untracked";
+    return form.submitDisabled && allTextEmpty(form.fields) ? "guarded" : "open";
+}
+/**
+ * Whether the action submitted the form. A click submits when it lands on a
+ * native submit control. Enter submits from a focused submit control, or from
+ * a text-like input while the form's default button is enabled.
+ */
+export function submits(kind, probe) {
+    if (probe.selfIsSubmit)
+        return true;
+    if (kind !== "enter" || probe.defaultDisabled)
+        return false;
+    return probe.self.tag === "input" && IMPLICIT_SUBMIT_TYPES.has(probe.self.type || "text");
+}
+/** Whether this action was an empty submit of a tracked form. */
+export function isEmptySubmit(kind, probe) {
+    return probe !== null && submits(kind, probe) && allTextEmpty(probe.fields);
+}
+/**
+ * Whether a failed page read is the page going away under it (a navigation
+ * or a closed tab), which is expected after a submit and says nothing. Any
+ * other failure is worth a line in the action log.
+ */
+export function isNavigationTeardown(message) {
+    return /execution context was destroyed|target (page, context or browser )?(has been )?closed|frame (was|has been) detached|navigat/i.test(message);
+}
+/** Page-side helpers shared by the inventory and the probe. Statements, not an expression. */
+const FORM_HELPERS_SRC = `
+  const visible = ${VISIBLE_SRC};
+  const xpathOf = ${XPATH_OF_SRC};
+  const facts = (f) => ({
+    tag: f.tagName.toLowerCase(),
+    type: f.tagName.toLowerCase() === "input" ? String(f.type || "text").toLowerCase() : "",
+    disabled: f.matches(":disabled"),
+    readOnly: f.readOnly === true,
+    visible: visible(f),
+    filled: typeof f.value === "string" && f.value !== "",
+  });
+  // The type PROPERTY: a button with no type, or an unknown one, reports "submit".
+  const isSubmit = (el) => {
+    const tag = el.tagName.toLowerCase();
+    return (tag === "button" && el.type === "submit") || (tag === "input" && (el.type === "submit" || el.type === "image"));
+  };
+  const submitsOf = (form) => Array.from(form.elements).filter((c) => isSubmit(c) && visible(c));
+  // Each DISTINCT set of field facts once. The rules ask whether any field is
+  // text entry and whether every one is blank, which repeats do not change,
+  // and a form of 2000 identical rows would otherwise ship 2000 objects back.
+  const fieldFactsOf = (form) => {
+    const seen = new Map();
+    for (const c of Array.from(form.elements)) {
+      if (!/^(input|textarea|select)$/i.test(c.tagName) || c.type === "hidden") continue;
+      const f = facts(c);
+      const id = f.tag + "|" + f.type + "|" + f.disabled + "|" + f.readOnly + "|" + f.visible + "|" + f.filled;
+      if (!seen.has(id)) seen.set(id, f);
+    }
+    return Array.from(seen.values());
+  };
+  // Resolved against the base URL, so a relative and an absolute action agree;
+  // one that is not a URL at all is kept as written.
+  const resolvedAction = (form) => {
+    const raw = (form.getAttribute("action") || "").trim();
+    if (!raw) return "";
+    try { return new URL(raw, document.baseURI).href; } catch (e) { return raw; }
+  };
+  // getAttribute, not form.id / form.name: a field named "id" or "name" shadows those.
+  const attrsOf = (form) => ({
+    id: form.getAttribute("id") || "",
+    name: form.getAttribute("name") || "",
+    action: resolvedAction(form),
+    method: form.getAttribute("method") || "",
+  });
+`;
+/**
+ * Page-side: every form on the page with a visible native submit control, as
+ * the xpath of its first one and the facts of its fields. One pass over
+ * `document.forms`; which of them are tracked is decided in Node (formStatus).
+ */
+export const FORMS_INVENTORY_SCRIPT = `(() => {
+  ${FORM_HELPERS_SRC}
+  const out = [];
+  for (const form of Array.from(document.forms)) {
+    const submits = submitsOf(form);
+    if (submits.length === 0) continue;
+    out.push({
+      attrs: attrsOf(form),
+      submit: xpathOf(submits[0]),
+      fields: fieldFactsOf(form),
+      submitDisabled: submits.every((s) => s.matches(":disabled")),
+    });
+  }
+  return out;
+})()`;
+/**
+ * Page-side body of the probe run on the element an action is about to
+ * submit through: `(node) => FormProbe | null`, null when it belongs to no
+ * form. Shipped as source rather than a transpiled function, for the reason
+ * the collector is a string: a loader's helpers do not exist in the page.
+ */
+export const FORM_PROBE_BODY = `
+  if (!node || node.nodeType !== 1 || !node.form) return null;
+  ${FORM_HELPERS_SRC}
+  const form = node.form;
+  const submits = submitsOf(form);
+  if (submits.length === 0) return null;
+  const accessibleName = ${ACCESSIBLE_NAME_SRC};
+  return {
+    attrs: attrsOf(form),
+    submit: xpathOf(submits[0]),
+    submitTestid: submits[0].getAttribute("data-testid"),
+    submitName: accessibleName(submits[0]),
+    fields: fieldFactsOf(form),
+    self: facts(node),
+    selfIsSubmit: isSubmit(node),
+    defaultDisabled: submits[0].matches(":disabled"),
+  };
+`;
+/** The probe as an expression over a node expression, for a page-level evaluate. */
+export function formProbeExpression(nodeExpression) {
+    return `((node) => {${FORM_PROBE_BODY}})(${nodeExpression})`;
+}
+/**
+ * The scout_coverage lines for forms no session has submitted empty this
+ * run. Empty when there is nothing to say.
+ */
+export function formatNeverSubmittedEmpty(forms) {
+    if (forms.length === 0)
+        return [];
+    return [
+        "Forms never submitted empty this run (submit each once with every text field blank: a submit that silently does nothing — no request, no message — hides there):",
+        ...forms.slice(0, 15).map((f) => `  ${f.route} ${f.key}`),
+        ...(forms.length > 15 ? [`  … +${forms.length - 15} more`] : []),
+    ];
+}