@enricai/barnacle 1.10.1 → 1.12.0

package/dist/scraper/flow-runner.js

@@ -23,6 +23,7 @@ exports.findRecentBackendError = findRecentBackendError;
 exports.findRecentPageTransition = findRecentPageTransition;
 exports.isWizardExitAction = isWizardExitAction;
 exports.isAdvanceStep = isAdvanceStep;
+exports.shouldCaptureSelectionState = shouldCaptureSelectionState;
 exports.shouldWarnMissingAdvancePattern = shouldWarnMissingAdvancePattern;
 exports.parseCaptureIndex = parseCaptureIndex;
 exports.latestCaptureIndex = latestCaptureIndex;
@@ -32,9 +33,7 @@ exports.windowHasAdvanceTransition = windowHasAdvanceTransition;
 exports.shouldVetoFallbackAdvance = shouldVetoFallbackAdvance;
 exports.isDomOnlyAdvanceVerified = isDomOnlyAdvanceVerified;
 exports.isClickViewSwapVerified = isClickViewSwapVerified;
-exports.isClickStateToggleVerified = isClickStateToggleVerified;
 exports.selectionCountFromSignature = selectionCountFromSignature;
-exports.isSelectionCounterStalled = isSelectionCounterStalled;
 exports.shouldReadbackFillOnActSuccess = shouldReadbackFillOnActSuccess;
 exports.countNgInvalidContainers = countNgInvalidContainers;
 exports.describeAttemptEffectSignals = describeAttemptEffectSignals;
@@ -526,8 +525,15 @@ const DOM_SNAPSHOT_EXPR = `(() => { const b = document.body; if (!b) return { ht
  * `url()` rejects (OOPIF detached by the submit it just fired) can still
  * report the main frame's post-navigation URL instead of throwing the
  * whole attempt out of `executeStepWithHealing`.
+ *
+ * `captureSelectionState` (default false) additionally builds the per-element
+ * `selectionStateByXpath` baseline for the element-scoped click verifier. The
+ * caller sets it only for the pre/post pair of a selection/field-answer click
+ * step — never for submit/advance steps (so a self-toggling submit/Next button
+ * can't false-credit) nor for the mid-probe/retry snapshots — which also keeps
+ * this second full-DOM evaluate off the common (non-selection) path.
  */
-async function snapshotPage(target, signalCounter, page) {
+async function snapshotPage(target, signalCounter, page, captureSelectionState = false) {
     let bodyHtmlLength = 0;
     let visibleTextSignature = "";
     let formValueSignature = "";
@@ -552,6 +558,25 @@ async function snapshotPage(target, signalCounter, page) {
         // Snapshot is observational; on failure, defaults to 0/"" so the verifier
         // sees no delta. Real state-class checks already cover the verified path.
     }
+    // Per-element selection baseline for the element-scoped click verifier
+    // (see StepSnapshot.selectionStateByXpath). Captured ONLY when the caller
+    // asks (`captureSelectionState`) — the pre/post pair of a selection/field-
+    // answer click step. Skipping it for submit/advance steps is both the perf
+    // guard (this is a second full-DOM evaluate on a hot function) AND the
+    // correctness gate: with no baseline, verifyDomEffect's element read-back
+    // finds nothing to diff and defers to network/URL, so a submit/advance
+    // button's own self-toggle can never false-credit the step. Its own
+    // try/catch so a failure here can't lose the coarse signals above; an empty
+    // map leaves the verifier deferring to network/URL, never a false credit.
+    let selectionStateByXpath = {};
+    if (captureSelectionState) {
+        try {
+            selectionStateByXpath = asSelectionStateMap(await target.evaluate(SELECTION_STATE_MAP_EXPR));
+        }
+        catch {
+            // observational — empty baseline on failure
+        }
+    }
     // A resolved child FrameTarget's url() reads location.href off the CDP
     // frame session (frame-target.ts's childFrameTarget), which rejects (or
     // trips its watchdog) once the OOPIF detaches — most commonly right after
@@ -566,6 +591,7 @@ async function snapshotPage(target, signalCounter, page) {
         visibleTextSignature,
         formValueSignature,
         selectionStateSignature,
+        selectionStateByXpath,
     };
 }
 /**
@@ -737,6 +763,22 @@ function isAdvanceStep(instruction) {
     const haystack = instruction.toLowerCase();
     return ADVANCE_STEP_PHRASES.some((p) => haystack.includes(p));
 }
+/**
+ * Whether `snapshotPage` should build the per-element selection baseline
+ * (`StepSnapshot.selectionStateByXpath`) for this step — i.e. whether
+ * `verifyDomEffect`'s element-scoped click read-back is allowed to credit it.
+ * True ONLY for a field-answer/selection step: a submit, a final, or an advance
+ * step must be verified by a real network/URL transition, so its own
+ * self-toggling button (a submit flipping to a loading/pressed class, a "Next"
+ * flipping `aria-pressed`) must never earn an element-scoped credit — matching
+ * the `!submit`/`!final`/`!advance` exclusions the former
+ * `isClickStateToggleVerified` gate enforced. Pure + exported so the gate the
+ * cascade depends on is unit-testable, not buried in `executeStepWithHealing`.
+ */
+function shouldCaptureSelectionState(params) {
+    const { step, isFinalStep, submitStep } = params;
+    return !(isFinalStep || submitStep || isAdvanceStep(step));
+}
 /**
  * Whether a flow should be WARNed that its DOM-only advance guard is disarmed.
  * `isDomOnlyAdvanceVerified` only vetoes a DOM-only "advance" when
@@ -1009,38 +1051,6 @@ function isClickViewSwapVerified(params) {
         return true;
     return textChanged && bytesDelta >= VIEW_SWAP_REVEAL_MIN_BYTES;
 }
-/**
- * Credits a network-free click when it flipped a client-side SELECTION state —
- * an `aria-pressed`/`aria-checked`/`aria-selected` attribute, a `data-state`,
- * or a `selected`/`active`/`checked` class on the toggled control (captured by
- * `StepSnapshot.selectionStateSignature`). React/SPA multi-select wizards toggle
- * options this way with a trivial or NEGATIVE byte delta and no
- * network/URL/innerText/input-value change, so `isClickViewSwapVerified` and
- * the byte-floor phantom check both miss them and score the real selection a
- * phantom no-op. This is the size-independent counterpart to that gate. Scope
- * guards: only a plain `click`, never a final/submit step (those keep their
- * stronger submit-judge gate), and only when zero network fired (a network POST
- * is authoritative). **Stricter than `isClickViewSwapVerified` on advance
- * steps:** it excludes ANY advance/"Next" step (`isAdvance`), not just an
- * advance-WITH-pattern step. The selection signal fires on a validation-render
- * that toggles a control's own state, and an advance without a configured
- * `advanceTransitionBodyPattern` has no real-transition veto
- * (see `shouldWarnMissingAdvancePattern`) — so crediting a bare selection change
- * would desync the wizard step pointer. A real advance still verifies via
- * network/URL; a field-toggle answer step (not an advance) keeps this credit.
- */
-function isClickStateToggleVerified(params) {
-    const { resolvedAction, isFinalStep, submitStep, isAdvance, networkDelta, selectionStateChanged, } = params;
-    if (resolvedAction?.method !== "click")
-        return false;
-    if (isFinalStep || submitStep)
-        return false;
-    if (isAdvance)
-        return false;
-    if (networkDelta !== 0)
-        return false;
-    return selectionStateChanged;
-}
 /**
  * Reads the "N settings/items selected" running count that multi-select wizard
  * steps render as a live heading above the option grid. Returns the integer, or
@@ -1049,11 +1059,12 @@ function isClickStateToggleVerified(params) {
  * `"<len>:<first-200-chars-of-innerText>"` — the counter idiom sits at the top
  * of these steps, so it is always inside the 200-char window.
  *
- * Exists because some SPA multi-selects (obfuscated hashed classes, no
- * `aria-pressed`/`data-state`) expose no selection-state attribute at all, so
- * {@link isClickStateToggleVerified}'s fingerprint is structurally blind and a
- * phantom option click rides the generic DOM-delta gate to a FALSE credit — the
- * running counter is the only trustworthy "did the selection register" signal.
+ * Used by the deep-locator candidate walk to disambiguate WHICH of several
+ * option candidates registered a selection: after clicking a candidate, the
+ * running counter rising confirms that candidate was the real option (a
+ * candidate-selection signal, distinct from the click verifier — which now
+ * reads the resolved element's own committed state directly via
+ * {@link verifyDomEffect}).
  */
 function selectionCountFromSignature(visibleTextSignature) {
     const colon = visibleTextSignature.indexOf(":");
@@ -1062,27 +1073,6 @@ function selectionCountFromSignature(visibleTextSignature) {
     const digits = match?.[1];
     return digits === undefined ? null : Number.parseInt(digits, 10);
 }
-/**
- * Veto for a SELECTION-intent step whose weak DOM signals (view-swap byte delta,
- * a non-advance `domVerified` reflow) would otherwise credit a click that did
- * NOT register the selection. When the step's snapshot exposes a running
- * "N selected" counter (see {@link selectionCountFromSignature}) and that count
- * did not increase across the click, the option was not actually selected — a
- * phantom the fingerprint can't catch — so the caller must NOT treat the weak
- * signals as verification and should keep healing. Returns `true` only when a
- * counter is present on BOTH snapshots and did not rise; absent a counter it
- * returns `false` (no veto), so counter-less selection widgets are untouched.
- */
-function isSelectionCounterStalled(params) {
-    const { isSelectionStep, preVisibleTextSignature, postVisibleTextSignature } = params;
-    if (!isSelectionStep)
-        return false;
-    const pre = selectionCountFromSignature(preVisibleTextSignature);
-    const post = selectionCountFromSignature(postVisibleTextSignature);
-    if (pre === null || post === null)
-        return false;
-    return post <= pre;
-}
 /**
  * Whether an act-success step warrants a committed-value read-back before the
  * weak view-swap/form-value signals are allowed to accept it. A controlled
@@ -2454,13 +2444,12 @@ async function fillTextDatepickerInput(target, selector, value) {
     // Month/year-picker variant: click the target month cell (0-based month
     // index maps to the __month-N class) — THIS is the commit. The year/month
     // dropdowns are set first only so the calendar shows the right year's month
-    // page. NOTE: "range-select" is a SITE-SPECIFIC class (the ATS site's own
-    // CSS), not a react-datepicker class; the bare "select" fallback covers
-    // other wrappers.
+    // page. The bare "select" query covers every wrapper generically (site CSS
+    // classes are never named here).
     // Stock react-datepicker renders its month/year dropdowns as clickable divs,
     // so on those the select loop is inert and the month-cell click carries it.
     if (monthCells.length > 0) {
-      const selects = cal.querySelectorAll("select.range-select, select");
+      const selects = cal.querySelectorAll("select");
       for (const sel of selects) {
         const opts = Array.from(sel.options).map((o) => (o.value || "").trim());
         const yearOpt = opts.indexOf(String(year));
@@ -2660,6 +2649,239 @@ function xpathBodyForEvaluate(selector) {
     const stripped = selector.startsWith("xpath=") ? selector.slice("xpath=".length) : selector;
     return stripped.startsWith("/") || stripped.startsWith("(") ? stripped : null;
 }
+/**
+ * In-page source for the absolute positional xpath walk, shared by every
+ * expression that must produce keys byte-identical to Stagehand's resolved
+ * `xpath=/html[1]/…` selectors AND to each other: the baseline map
+ * ({@link SELECTION_STATE_MAP_EXPR}) and the ancestor read-back
+ * ({@link selectionAncestorChanged}). Kept as one constant so a future edit
+ * can't drift one copy — a divergent walk would silently produce keys that miss
+ * the baseline, making the ancestor read-back a no-op. Hardcoded
+ * `/html[1]/body[1]/` prefix, `previousElementSibling` index,
+ * `nodeName.toLowerCase()`, stop at `document.body`.
+ */
+const XPATH_OF_FN_SRC = `(node) => {
+    const parts = [];
+    while (node && node.nodeType === 1 && node !== document.body) {
+      const tag = node.nodeName.toLowerCase();
+      let idx = 1;
+      let sib = node.previousElementSibling;
+      while (sib) {
+        if (sib.nodeName.toLowerCase() === tag) idx++;
+        sib = sib.previousElementSibling;
+      }
+      parts.unshift(tag + "[" + idx + "]");
+      node = node.parentElement;
+    }
+    return "/html[1]/body[1]/" + parts.join("/");
+  }`;
+/**
+ * In-page source for one element's {@link ElementSelectionFingerprint} object
+ * literal, given the name of the element variable (`elVar`) and a variable
+ * (`dsVar`) already bound to `elVar.getAttribute("data-state") || ""`. Shared by
+ * {@link elementSelectionFingerprintExpr}, {@link SELECTION_STATE_MAP_EXPR}, and
+ * {@link selectionAncestorChanged} so all three compute the SAME fingerprint —
+ * a field drifting in one copy would make the pre/post diff compare mismatched
+ * shapes. The `data-state` disclosure values `open`/`closed` (the
+ * `aria-expanded` equivalent) are blanked by the caller's `dsVar` so opening a
+ * popover isn't mistaken for a selection.
+ */
+function selectionFingerprintObjSrc(elVar, dsVar) {
+    return `{ kind: ${elVar}.getAttribute("kind") || "", cls: ${elVar}.getAttribute("class") || "", ariaPressed: ${elVar}.getAttribute("aria-pressed") || "", ariaChecked: ${elVar}.getAttribute("aria-checked") || "", ariaSelected: ${elVar}.getAttribute("aria-selected") || "", dataState: (${dsVar} === "open" || ${dsVar} === "closed") ? "" : ${dsVar}, dataSelected: ${elVar}.hasAttribute("data-selected") ? "1" : "", dataChecked: ${elVar}.hasAttribute("data-checked") ? "1" : "", checked: (${elVar}.type === "checkbox" || ${elVar}.type === "radio") ? (${elVar}.checked ? "1" : "0") : "", value: typeof ${elVar}.value === "string" ? ${elVar}.value.slice(0, 200) : "" }`;
+}
+/**
+ * Browser-side expression body that resolves `xpath` and returns that one
+ * element's {@link ElementSelectionFingerprint} (or `null` when the node is
+ * absent). Trust boundary: `xpath` is a Stagehand-resolved selector, and
+ * `JSON.stringify` produces a safe JS string literal, so composing it cannot
+ * inject behavior. The `data-state` disclosure values `open`/`closed` (the
+ * `aria-expanded` equivalent) are blanked so opening a popover isn't mistaken
+ * for a selection.
+ */
+function elementSelectionFingerprintExpr(xpath) {
+    return `(() => { const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); const el = r.singleNodeValue; if (!el) return null; const ds = el.getAttribute("data-state") || ""; return ${selectionFingerprintObjSrc("el", "ds")}; })()`;
+}
+/**
+ * Browser-side expression: build `{ absolutePositionalXpath →
+ * ElementSelectionFingerprint }` for every VISIBLE interactive element, the
+ * pre-action baseline {@link verifyDomEffect} diffs the resolved element
+ * against. Trust boundary: composed only from the {@link XPATH_OF_FN_SRC} and
+ * {@link selectionFingerprintObjSrc} constants (no external interpolation). The
+ * xpath is generated by the shared {@link XPATH_OF_FN_SRC} walk — the SAME
+ * source {@link selectionAncestorChanged} recomputes ancestor keys with, so the
+ * two byte-match each other and Stagehand's resolved `xpath=/html[1]/…`
+ * selectors. `[role=dialog],[role=tooltip],[aria-live]` subtrees are
+ * skipped — they churn without a selection change. Visibility uses the same
+ * rect + `getComputedStyle` idiom as `deep-locator-scan.ts`'s `IS_VISIBLE_EXPR`
+ * (rather than `offsetParent`), so on-screen `position:fixed` controls — a
+ * sticky Next/Submit bar, whose `offsetParent` is `null` — still enter the map.
+ */
+const SELECTION_STATE_MAP_EXPR = `(() => {
+  const b = document.body;
+  if (!b) return {};
+  const xpathOf = ${XPATH_OF_FN_SRC};
+  const visible = (el) => {
+    const rect = el.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0) return false;
+    const style = getComputedStyle(el);
+    return style.display !== "none" && style.visibility !== "hidden";
+  };
+  const sel = "button,[role=button],a,[tabindex],input,select,textarea,[role=option],[role=tab],[role=switch],[role=checkbox],[role=menuitemcheckbox]";
+  const skip = (el) => el.closest("[role=dialog],[role=tooltip],[aria-live]") !== null;
+  const out = {};
+  for (const el of b.querySelectorAll(sel)) {
+    if (!visible(el) || skip(el)) continue;
+    const ds = el.getAttribute("data-state") || "";
+    out[xpathOf(el)] = ${selectionFingerprintObjSrc("el", "ds")};
+  }
+  return out;
+})()`;
+/**
+ * Narrows an unknown `evaluate` result into the
+ * {@link StepSnapshot.selectionStateByXpath} map, discarding any malformed
+ * entry. Defaults to `{}` so a snapshot failure leaves the verifier with an
+ * empty baseline (defer-to-network), never a throw.
+ */
+function asSelectionStateMap(raw) {
+    if (raw === null || typeof raw !== "object")
+        return {};
+    const out = {};
+    for (const [xpath, value] of Object.entries(raw)) {
+        const fp = asSelectionFingerprint(value);
+        if (fp)
+            out[xpath] = fp;
+    }
+    return out;
+}
+/** True when two {@link ElementSelectionFingerprint}s differ in any tracked field. */
+function selectionFingerprintChanged(pre, post) {
+    return (pre.kind !== post.kind ||
+        pre.cls !== post.cls ||
+        pre.ariaPressed !== post.ariaPressed ||
+        pre.ariaChecked !== post.ariaChecked ||
+        pre.ariaSelected !== post.ariaSelected ||
+        pre.dataState !== post.dataState ||
+        pre.dataSelected !== post.dataSelected ||
+        pre.dataChecked !== post.dataChecked ||
+        pre.checked !== post.checked ||
+        pre.value !== post.value);
+}
+/**
+ * Narrows an unknown `evaluate` result to an {@link ElementSelectionFingerprint}.
+ * Every field is emitted as a string by {@link elementSelectionFingerprintExpr},
+ * so a present object with a string `kind` is a sufficient shape check.
+ */
+function asSelectionFingerprint(raw) {
+    if (raw === null || typeof raw !== "object")
+        return null;
+    const r = raw;
+    if (typeof r.kind !== "string")
+        return null;
+    return {
+        kind: r.kind,
+        cls: typeof r.cls === "string" ? r.cls : "",
+        ariaPressed: typeof r.ariaPressed === "string" ? r.ariaPressed : "",
+        ariaChecked: typeof r.ariaChecked === "string" ? r.ariaChecked : "",
+        ariaSelected: typeof r.ariaSelected === "string" ? r.ariaSelected : "",
+        dataState: typeof r.dataState === "string" ? r.dataState : "",
+        dataSelected: typeof r.dataSelected === "string" ? r.dataSelected : "",
+        dataChecked: typeof r.dataChecked === "string" ? r.dataChecked : "",
+        checked: typeof r.checked === "string" ? r.checked : "",
+        value: typeof r.value === "string" ? r.value : "",
+    };
+}
+/**
+ * Reads one element's {@link ElementSelectionFingerprint} off `target` by
+ * xpath, or `null` when the selector isn't an xpath / the node is absent / the
+ * evaluate throws. Used by the click branch of {@link verifyDomEffect} to
+ * compare the resolved element's committed selection state against the
+ * pre-action baseline captured in {@link StepSnapshot.selectionStateByXpath}.
+ */
+async function readElementSelectionFingerprint(target, selector) {
+    const xpath = xpathBodyForEvaluate(selector);
+    if (!xpath)
+        return null;
+    try {
+        return asSelectionFingerprint(await target.evaluate(elementSelectionFingerprintExpr(xpath)));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * How far up from the clicked leaf {@link selectionAncestorChanged} walks
+ * looking for the option/toggle that carries the selection. Design-system
+ * options nest their label 1-2 levels deep (a `<span title>` inside a
+ * `role="option"`, plus the odd icon/wrapper); 6 matches the vacuous-click
+ * ancestor guard in {@link verifyDomEffect}'s click branch and covers that
+ * nesting without over-reaching into an outer listbox/group.
+ */
+const MAX_SELECTION_ANCESTOR_DEPTH = 6;
+/**
+ * Element-scoped selection read-back for the case the clicked node's OWN
+ * fingerprint can't credit: a design-system option that wraps its label in a
+ * child element (Base Web `tag`, and the standard listbox/combobox idiom where
+ * an option's accessible name comes from its descendant content). Stagehand
+ * resolves the click to the label leaf, but `aria-selected` / the hashed class
+ * flips on the ancestor `role="option"` — so the leaf has no baseline entry and
+ * never changes state, and the leaf-only read-back mis-scores a genuine
+ * selection as a phantom click.
+ *
+ * Walks from the leaf up to {@link MAX_SELECTION_ANCESTOR_DEPTH}, and on the
+ * NEAREST ancestor that (a) carries a selection marker (a non-empty fingerprint
+ * field, a selection `role`, or a `data-baseweb` attribute — `aria-expanded` is
+ * deliberately NOT a marker so a bare disclosure/expander is skipped) AND (b) is
+ * present in the pre-baseline map, diffs that ancestor's current fingerprint
+ * against its baseline. Nearest-wins and returns even when unchanged, so a
+ * re-click of an already-selected option (or a decoy marker on an outer group)
+ * can never be laundered into a credit. Authoritative and element-scoped: only
+ * baseline-keyed ancestors are consulted, so an unrelated element's change can
+ * never credit the step. Recomputes ancestor xpaths with the SAME
+ * {@link XPATH_OF_FN_SRC} walk that built the baseline so the keys byte-match.
+ * Returns `false` on any miss / malformed result / evaluate throw (defer to the
+ * network/URL signal).
+ */
+async function selectionAncestorChanged(target, leafXpath, preSelectionState) {
+    const expr = `(() => {
+    const LEAF = ${JSON.stringify(leafXpath)};
+    const BASE = ${JSON.stringify(preSelectionState)};
+    const xpathOf = ${XPATH_OF_FN_SRC};
+    const fp = (el) => { const ds = el.getAttribute("data-state") || ""; return ${selectionFingerprintObjSrc("el", "ds")}; };
+    const SELECTION_ROLES = new Set(["option", "tab", "switch", "radio", "checkbox", "menuitemcheckbox"]);
+    const hasMarker = (el, f) => {
+      if (f.kind || f.ariaPressed || f.ariaChecked || f.ariaSelected || f.dataState || f.dataSelected || f.dataChecked || f.checked) return true;
+      if (SELECTION_ROLES.has((el.getAttribute("role") || "").toLowerCase())) return true;
+      if (el.hasAttribute("data-baseweb")) return true;
+      return false;
+    };
+    const changed = (a, b) =>
+      a.kind !== b.kind || a.cls !== b.cls || a.ariaPressed !== b.ariaPressed ||
+      a.ariaChecked !== b.ariaChecked || a.ariaSelected !== b.ariaSelected ||
+      a.dataState !== b.dataState || a.dataSelected !== b.dataSelected ||
+      a.dataChecked !== b.dataChecked || a.checked !== b.checked || a.value !== b.value;
+    const r = document.evaluate(LEAF, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+    let node = r.singleNodeValue;
+    if (!node) return false;
+    for (let depth = 0; depth < ${MAX_SELECTION_ANCESTOR_DEPTH} && node; depth++) {
+      if (node.getAttribute) {
+        const now = fp(node);
+        if (hasMarker(node, now)) {
+          const pre = BASE[xpathOf(node)];
+          if (!pre) return false;
+          return changed(pre, now);
+        }
+      }
+      node = node.parentElement;
+    }
+    return false;
+  })()`;
+    try {
+        return (await target.evaluate(expr)) === true;
+    }
+    catch {
+        return false;
+    }
+}
 /** How long the upload primitive waits for a post-setInputFiles network POST. */
 const UPLOAD_NETWORK_TIMEOUT_MS = 5_000;
 /** Polling interval while waiting for the upload's network signal. */
@@ -4572,8 +4794,16 @@ async function dispatchJqueryChangeEvent(target, selector) {
  *
  * `target` scopes both the locator/evaluate reads and the jQuery-change
  * dispatch to the resolved frame (main or a cross-origin child).
+ *
+ * `preSelectionState` is the pre-action per-element baseline
+ * ({@link StepSnapshot.selectionStateByXpath}) the click branch diffs the
+ * resolved element against — the element-scoped authoritative "did this
+ * selection register" signal for design-system option/toggle buttons that
+ * expose no native `checked` (Base Web `kind`, hashed styletron class, ARIA).
+ * Defaults to `{}` so callers/tests that don't supply it keep the prior
+ * radio/checkbox-and-network behavior.
  */
-async function verifyDomEffect(target, action) {
+async function verifyDomEffect(target, action, preSelectionState = {}) {
     const selector = action.selector;
     const method = action.method;
     if (!selector || !method)
@@ -4717,9 +4947,15 @@ async function verifyDomEffect(target, action) {
                 return true;
             case "click": {
                 // Clicks on radios and checkboxes toggle `:checked` without firing a
-                // network request — same false-fail class as fill. For every other
-                // click (buttons, links, custom toggles) return false so the verifier
-                // falls back to the network/URL signal, which is the right signal there.
+                // network request — same false-fail class as fill. Every OTHER click
+                // (design-system option/toggle buttons, links, custom controls) is
+                // verified element-scoped: compare the RESOLVED element's own committed
+                // selection state before vs. after the click. A Base Web option flips
+                // its `kind` (`tertiary`→`primary`) + a hashed styletron class with no
+                // network, no URL change, and a trivial/negative byte delta — the
+                // authoritative signal is that the clicked element's own fingerprint
+                // moved, which this reads directly instead of guessing from page-wide
+                // DOM deltas.
                 const xpath = xpathBody(selector);
                 if (!xpath)
                     return false;
@@ -4740,8 +4976,26 @@ async function verifyDomEffect(target, action) {
                     return false;
                 }
                 if (inputType !== "radio" && inputType !== "checkbox") {
-                    // Real button/link click — let network/URL signal decide.
-                    return false;
+                    // Element-scoped selection read-back. The pre-map is keyed by the
+                    // same absolute positional xpath Stagehand resolves to, so a lookup
+                    // by the resolved element's xpath body yields THAT element's baseline.
+                    // Credit the click iff the element's own committed state moved across
+                    // it. A selection change on any OTHER element can never credit this
+                    // step.
+                    const preFingerprint = preSelectionState[xpath];
+                    if (preFingerprint) {
+                        const postFingerprint = await readElementSelectionFingerprint(target, selector);
+                        if (postFingerprint && selectionFingerprintChanged(preFingerprint, postFingerprint)) {
+                            return true;
+                        }
+                    }
+                    // The clicked node's own state didn't credit it (no baseline for the
+                    // leaf, or the leaf carries no selection state). A design-system
+                    // option that wraps its label in a child element commits its
+                    // selection on the ancestor `role="option"`, not the clicked leaf —
+                    // so walk up to the nearest baseline-present selection ancestor and
+                    // diff THAT. No eligible ancestor → false (defer to network/URL).
+                    return await selectionAncestorChanged(target, xpath, preSelectionState);
                 }
                 const isCheckedNow = await locator.isChecked();
                 if (!isCheckedNow)
@@ -5281,6 +5535,13 @@ async function executeStepWithHealing(params) {
     // (verified 2026-06-15 on one measured tenant's telemetry). Site-agnostic: any flow
     // whose submit is mid-list can mark its submit step explicitly.
     const requireSubmitEndpoint = (isFinalStep || submitStep) && submitEndpointPattern !== null;
+    // Capture the per-element selection baseline (for verifyDomEffect's element-
+    // scoped click read-back) ONLY for selection/field-answer click steps — never
+    // for submit/advance steps, whose own self-toggling buttons must not
+    // false-credit the step, and whose advance/submit verdicts require a real
+    // network/URL transition. Also keeps the extra full-DOM evaluate off the
+    // submit/advance path. Step-level intent (available before the attempt loop).
+    const captureSelectionState = shouldCaptureSelectionState({ step, isFinalStep, submitStep });
     const attempts = [];
     const triedSelectors = [];
     const failureReasons = [];
@@ -5538,6 +5799,7 @@ async function executeStepWithHealing(params) {
                 visibleTextSignature: "",
                 selectionStateSignature: "",
                 formValueSignature: "",
+                selectionStateByXpath: {},
             };
             attempts.push({
                 attempt: 0,
@@ -5719,7 +5981,7 @@ async function executeStepWithHealing(params) {
         if (attempt > 1) {
             await page.waitForTimeout(attempt * ATTEMPT_BACKOFF_MS);
         }
-        const pre = await snapshotPage(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), signalCounter, page);
+        const pre = await snapshotPage(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), signalCounter, page, captureSelectionState);
         // Snapshot the meta-tail length so the final-step pattern gate can scope
         // its URL scan to captures added DURING this attempt (not historical
         // tail from earlier steps).
@@ -6576,11 +6838,14 @@ async function executeStepWithHealing(params) {
         // State-class actions (fill/check/etc.) never move the network counter or URL,
         // so the legacy heuristic false-negatived every form fill. Re-read DOM state
         // for those; keep the navigation signal authoritative for clicks/links —
-        // but ALSO route clicks through verifyDomEffect, which internally returns
-        // false for non-radio/non-checkbox clicks so the network/URL signal still
-        // decides those. Radios/checkboxes are click-but-no-network just like fills.
+        // but ALSO route clicks through verifyDomEffect, which authoritatively
+        // credits a radio/checkbox toggle OR (via the pre/post element fingerprint
+        // baseline `pre.selectionStateByXpath`) a design-system option/toggle whose
+        // own committed state changed; otherwise it returns false and the
+        // network/URL signal decides. Radios/checkboxes are click-but-no-network
+        // just like fills.
         const domVerified = resolvedAction !== null && (isStateClass || isClick)
-            ? await verifyDomEffect(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), resolvedAction)
+            ? await verifyDomEffect(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), resolvedAction, pre.selectionStateByXpath)
             : false;
         // Interior-advance transition gate (opt-in). On SPAs where a page advance
         // and a mere field-edit share one endpoint URL (the wizard ATS's `/gq`:
@@ -6654,20 +6919,15 @@ async function executeStepWithHealing(params) {
             bytesDelta: post.bodyHtmlLength - pre.bodyHtmlLength,
             textChanged: post.visibleTextSignature !== pre.visibleTextSignature,
         });
-        // Client-side state-toggle gate: credit a network-free click that flipped a
-        // selection-state signature (aria-pressed/checked/selected, data-state, or a
-        // selected/active/checked class) regardless of byte size. Fixes React/SPA
-        // multi-select wizards whose option buttons toggle client state with a
-        // trivial or NEGATIVE byte delta — which clickViewSwapVerified's byte floor
-        // and the phantom byte-check both miss.
-        const clickStateToggleVerified = isClickStateToggleVerified({
-            resolvedAction,
-            isFinalStep,
-            submitStep,
-            isAdvance: isAdvanceStep(step),
-            networkDelta: post.networkCount - pre.networkCount,
-            selectionStateChanged: post.selectionStateSignature !== pre.selectionStateSignature,
-        });
+        // A network-free selection/option toggle — including a Base Web `kind`
+        // flip or hashed-class swap that exposes no aria/data-state marker and
+        // moves a trivial or NEGATIVE byte delta — is now credited authoritatively
+        // and element-scoped by `verifyDomEffect` (via the pre/post per-element
+        // fingerprint baseline), flowing through `domVerified`. The former
+        // page-wide `clickStateToggleVerified` guess and its `selectionCounterStalled`
+        // veto (which only existed to suppress that guess's false positives) are
+        // removed: there is nothing to guess or veto when the resolved element's own
+        // committed state is read directly.
         // Form-value-diff signal: `visibleTextSignature` never reflects a plain
         // <input>/<textarea>/<select>'s `value` property, so a fill with no
         // secondary UI side effect (no toggle, no formatted display) had ZERO
@@ -6731,33 +6991,11 @@ async function executeStepWithHealing(params) {
                 }
             }
         }
-        // Selection-counter veto. A multi-select option click whose widget exposes
-        // no aria/data-state marker (obfuscated hashed classes) leaves
-        // `clickStateToggleVerified` blind, so a phantom that merely reflowed the
-        // DOM would ride the weak `domVerifiedForStep`/`clickViewSwapVerified`
-        // signals to a FALSE credit — the flow then advances to a "Next" that
-        // no-ops because nothing was actually selected. When the step's running
-        // "N selected" counter did not rise, suppress those weak DOM-delta signals
-        // so the cascade keeps trying a real selection. Strong signals (real
-        // network/URL transition) and the counter-independent state-toggle /
-        // form-value signals — each of which IS the selection registering — are
-        // never vetoed; counter-less widgets are untouched (the helper no-ops).
-        const selectionCounterStalled = isSelectionCounterStalled({
-            isSelectionStep: parseSelectStep(step) !== null,
-            preVisibleTextSignature: pre.visibleTextSignature,
-            postVisibleTextSignature: post.visibleTextSignature,
-        });
-        if (selectionCounterStalled && (domVerifiedForStep || clickViewSwapVerified)) {
-            logger.info(`${formatStepPrefix(stepIndex, totalSteps)} selection step credited only via DOM reflow but the "N selected" counter did not rise — the option did not register; not treating the weak DOM signal as verified`);
-        }
-        const domVerifiedAfterCounter = selectionCounterStalled ? false : domVerifiedForStep;
-        const clickViewSwapAfterCounter = selectionCounterStalled ? false : clickViewSwapVerified;
         let verified = networkIsRealAdvance ||
             urlChanged ||
-            domVerifiedAfterCounter ||
+            domVerifiedForStep ||
             datepickerCommitted ||
-            (!datepickerRejected &&
-                (clickViewSwapAfterCounter || formValueVerified || clickStateToggleVerified));
+            (!datepickerRejected && (clickViewSwapVerified || formValueVerified));
         // Final-step submit-verification gate. Replaces the deterministic
         // submitEndpointPattern regex with a Haiku 4.5 LLM judgment over
         // multi-signal evidence (network captures, page URL/title, DOM
@@ -6884,9 +7122,7 @@ async function executeStepWithHealing(params) {
                                 ? "dom"
                                 : formValueVerified
                                     ? "form-value"
-                                    : clickStateToggleVerified
-                                        ? "state-toggle"
-                                        : "dom";
+                                    : "dom";
         }
         // N+16 probe: Stagehand's CDP click sometimes lands on the button without
         // triggering React's SyntheticEvent layer (or jQuery delegated handlers).
@@ -6974,13 +7210,36 @@ async function executeStepWithHealing(params) {
                     const retryHtmlDelta = retryPost.bodyHtmlLength - pre.bodyHtmlLength;
                     const retryTextChanged = retryPost.visibleTextSignature !== pre.visibleTextSignature;
                     const retryFormValueChanged = retryPost.formValueSignature !== pre.formValueSignature;
-                    // Excludes advance/"Next" steps for the same reason the primary
-                    // isClickStateToggleVerified does: a validation re-render can flip a
-                    // control's selection state without moving the wizard, and an advance
-                    // without a configured transition pattern has no real-transition veto,
-                    // so crediting a bare selection change here would desync the step pointer.
+                    // Element-scoped selection read-back for the n+16 fallback — the same
+                    // authoritative signal the primary verifier uses via `verifyDomEffect`,
+                    // applied to the element this fallback just re-clicked. Credits only
+                    // when the RESOLVED element's own committed state moved across the
+                    // fallback click (Base Web `kind`/class, ARIA, native checked), read
+                    // against the pre-action baseline. Excludes advance/"Next" steps: an
+                    // advance without a configured transition pattern has no real-transition
+                    // veto, so crediting a bare selection change would desync the step
+                    // pointer. No page-wide signature, no counter veto — nothing to guess
+                    // or suppress when the element's own state is read directly.
                     const retrySelectionStateChanged = !isAdvanceStep(step) &&
-                        retryPost.selectionStateSignature !== pre.selectionStateSignature;
+                        (await (async () => {
+                            if (!xpath || !resolvedAction?.selector)
+                                return false;
+                            const preFingerprint = pre.selectionStateByXpath[xpath];
+                            if (preFingerprint) {
+                                const postFingerprint = await readElementSelectionFingerprint(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), resolvedAction.selector);
+                                if (postFingerprint !== null &&
+                                    selectionFingerprintChanged(preFingerprint, postFingerprint)) {
+                                    return true;
+                                }
+                            }
+                            // Leaf had no baseline entry (or carried no selection state): a
+                            // design-system option that wraps its label commits its selection
+                            // on the ancestor `role="option"`, not the clicked leaf — walk up
+                            // to the nearest baseline-present selection ancestor and diff THAT,
+                            // the same fallback `verifyDomEffect`'s primary read-back uses. No
+                            // eligible ancestor → false (defer to the other retry signals).
+                            return await selectionAncestorChanged(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), xpath, pre.selectionStateByXpath);
+                        })());
                     // RC2: an advance/`kind=click` "Next" that only grew the DOM
                     // (validation errors rendered) with NO network/URL change is a
                     // validation-blocked no-op, not a real transition — but the
@@ -7031,41 +7290,25 @@ async function executeStepWithHealing(params) {
                         logger.info(`${formatStepPrefix(stepIndex, totalSteps)} n+16 fallback advanced but no real transition (non-advancing POST / field toggle); not treating as verified`);
                     }
                     // Weak DOM-only signals (an html-byte delta, a visible-text change, a
-                    // form-value change, a selection-state flip) are NOT sufficient to
+                    // form-value change) are NOT sufficient to
                     // verify a final/submit step on their own: a validation re-render
                     // produces exactly these without the submit landing. The primary
-                    // verifier is safe here because clickViewSwapVerified/formValueVerified/
-                    // clickStateToggleVerified all self-exclude final/submit; the n+16
+                    // verifier is safe here because clickViewSwapVerified/formValueVerified
+                    // self-exclude final/submit; the n+16
                     // fallback ORs the raw deltas, so gate them explicitly. On a
                     // final/submit step they only count when the submit-endpoint judge will
                     // actually run below (requireSubmitEndpoint) to corroborate — otherwise
                     // only a strong signal (network/url) or a verified checkbox state may
                     // pass. Non-final/submit steps are unaffected.
                     const weakDomSignalsAllowed = (!isFinalStep && !submitStep) || requireSubmitEndpoint;
-                    // Selection-counter veto for the n+16 fallback — the same gate the
-                    // primary verifier applies, recomputed against `retryPost`. Without
-                    // it this path would re-credit a stalled selection the primary veto
-                    // already suppressed: the fallback `el.click()` can reflow the DOM
-                    // (html/text/selection-state delta) without registering the option,
-                    // and those weak deltas are exactly what the OR below admits for a
-                    // non-final selection step. Only the weak-delta disjunct is vetoed;
-                    // strong signals (network/url) and a verified checkbox state pass.
-                    const retrySelectionCounterStalled = isSelectionCounterStalled({
-                        isSelectionStep: parseSelectStep(step) !== null,
-                        preVisibleTextSignature: pre.visibleTextSignature,
-                        postVisibleTextSignature: retryPost.visibleTextSignature,
-                    });
                     let retryVerified = !clickBlockedByInvalid &&
                         !fallbackDomOnlyAdvance &&
                         (retryNetworkFired ||
                             retryUrlChanged ||
                             checkboxStateVerified ||
+                            retrySelectionStateChanged ||
                             (weakDomSignalsAllowed &&
-                                !retrySelectionCounterStalled &&
-                                (retryHtmlDelta !== 0 ||
-                                    retryTextChanged ||
-                                    retryFormValueChanged ||
-                                    retrySelectionStateChanged)));
+                                (retryHtmlDelta !== 0 || retryTextChanged || retryFormValueChanged)));
                     // Apply the same submit-endpoint gate the primary verifier uses.
                     // Without this, the n+16 fallback would still ride past a
                     // tracking-pixel-only click on the final step. Same Haiku LLM
@@ -7141,17 +7384,7 @@ async function executeStepWithHealing(params) {
                     logger.info(`n+16 probe: step=${stepIndex + 1}/${totalSteps?.() ?? "?"} attempt=${attempt} el.click() fallback fired=${fired === true} kind=${probeResult.kind ?? "none"} checkboxStateVerified=${checkboxStateVerified} ancestorStillInvalid=${ancestorStillInvalid}; network=${retryNetworkFired} url=${retryUrlChanged} htmlDelta=${retryHtmlDelta} textChanged=${retryTextChanged} formValueChanged=${retryFormValueChanged} selectionStateChanged=${retrySelectionStateChanged} verified=${retryVerified}`);
                     if (retryVerified) {
                         if (record.verifiedBy === null) {
-                            record.verifiedBy = retryUrlChanged
-                                ? "url"
-                                : retryNetworkFired
-                                    ? "network"
-                                    : retryHtmlDelta === 0 &&
-                                        !retryTextChanged &&
-                                        !retryFormValueChanged &&
-                                        !checkboxStateVerified &&
-                                        retrySelectionStateChanged
-                                        ? "state-toggle"
-                                        : "dom";
+                            record.verifiedBy = retryUrlChanged ? "url" : retryNetworkFired ? "network" : "dom";
                         }
                         record.post = retryPost;
                         attempts.push(record);
@@ -7173,7 +7406,7 @@ async function executeStepWithHealing(params) {
         attempts.push(record);
         if (verified) {
             if (attempt > 1) {
-                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} healed on attempt ${attempt} via ${record.technique} (network=${networkFired} url=${urlChanged} dom=${domVerified} stateToggle=${clickStateToggleVerified} verifiedBy=${record.verifiedBy})`);
+                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} healed on attempt ${attempt} via ${record.technique} (network=${networkFired} url=${urlChanged} dom=${domVerified} verifiedBy=${record.verifiedBy})`);
             }
             else {
                 // Why log first-try wins explicitly: prior to this change, attempt-1
@@ -7183,7 +7416,7 @@ async function executeStepWithHealing(params) {
                 // collapse" (log showed 2 heals) but telemetry calls.ndjson showed
                 // 32 successful Stagehand acts. Surfacing attempt-1 wins lets the
                 // log match telemetry and prevents the same false alarm.
-                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} succeeded on attempt 1 via ${record.technique} (network=${networkFired} url=${urlChanged} dom=${domVerified} stateToggle=${clickStateToggleVerified} verifiedBy=${record.verifiedBy})`);
+                logger.info(`${formatStepPrefix(stepIndex, totalSteps)} succeeded on attempt 1 via ${record.technique} (network=${networkFired} url=${urlChanged} dom=${domVerified} verifiedBy=${record.verifiedBy})`);
             }
             trajectory?.push({ stepIndex, verifiedBy: record.verifiedBy });
             return "completed";
@@ -7198,6 +7431,11 @@ async function executeStepWithHealing(params) {
             actResultSuccess: record.actResultSuccess,
             pre,
             post,
+            // Authoritative element-scoped signal: `verifyDomEffect` read the resolved
+            // element's own committed-state delta (Base Web `kind`/class, ARIA, native
+            // checked) into `domVerified`. A registered selection toggle no longer
+            // reads as a phantom just because it moved no network/URL/bytes.
+            elementStateChanged: domVerified,
             isSubmitShapedStep: isFinalStep || submitStep,
         });
         const reason = record.errorMessage