@enricai/barnacle 1.12.1 → 1.12.2

package/dist/scraper/flow-runner.js

@@ -72,6 +72,7 @@ exports.waitForTransitionBody = waitForTransitionBody;
 exports.chooseRequiredSelectOption = chooseRequiredSelectOption;
 exports.buildRadioIdXPath = buildRadioIdXPath;
 exports.selectRadioGroupOption = selectRadioGroupOption;
+exports.hasUnfilledRequiredControlForStep = hasUnfilledRequiredControlForStep;
 exports.simulateDragDropUpload = simulateDragDropUpload;
 exports.dispatchJqueryChangeEvent = dispatchJqueryChangeEvent;
 exports.verifyDomEffect = verifyDomEffect;
@@ -376,6 +377,151 @@ const RADIO_SETTLE_MS = 400;
  * value that a later worklet re-render will wipe.
  */
 const SELECT_SETTLE_MS = 400;
+/**
+ * Same async-revalidation tick as {@link RADIO_SETTLE_MS}/{@link SELECT_SETTLE_MS},
+ * for the popup-dropdown widget family {@link tryPromptSelectorPrimitive} handles:
+ * after opening the popup, after typing into an in-popup filter, and after
+ * clicking an option, the DOM (option-list render, selection-label text,
+ * `aria-invalid` marker) settles a beat later than the trusted event that
+ * triggered it.
+ */
+const PROMPT_SELECTOR_SETTLE_MS = 400;
+/**
+ * Temporary attribute {@link tryPromptSelectorPrimitive} stamps onto each
+ * candidate widget during its read-only enumerate pass, so the Node-side click
+ * (a real Playwright gesture — these widgets ignore a bare `el.click()`) can
+ * address the exact widget chosen by index without re-deriving a CSS/xpath
+ * selector for an element with no stable id.
+ */
+const PROMPT_WIDGET_MARK_ATTR = "data-bcl-prompt-idx";
+/** Same role as {@link PROMPT_WIDGET_MARK_ATTR}, but for the popup's rendered option entries. */
+const PROMPT_OPTION_MARK_ATTR = "data-bcl-prompt-opt-idx";
+/**
+ * Cross-vendor selector union that identifies the TRIGGER of a native-control-less
+ * popup-dropdown widget (a combobox that opens a listbox popup and renders no
+ * `<select>`/`<input>` a focused `<select>`/`<input>` probe can see). Ordered as
+ * a UNION, standards first, with well-known widget-library markers as co-equal
+ * members — the same multi-vendor-union discipline as
+ * {@link INVALID_MARKER_CLASS_SOURCE} (`ng-invalid|Mui-error|…`). No member is a
+ * per-site branch; each is one recognizable spelling of the same widget shape.
+ * Growth is a one-line edit here — never a new hardcoded selector scattered into
+ * logic (the site-agnostic guard trips on the latter, allows this curated list).
+ *
+ * Members: ARIA combobox / listbox-owning triggers (`role=combobox`,
+ * `aria-haspopup=listbox`, `aria-controls`/`aria-owns`→listbox); and the
+ * `data-uxi-widget-type` / `data-automation-id` prompt family emitted by the
+ * Canvas/UXI widget kit some ATS front-ends build on (verified on a real
+ * capture: the trigger is an `<input data-uxi-widget-type="selectinput"
+ * aria-required aria-invalid>` beside a `data-automation-id="promptIcon"` icon,
+ * with NO `role=combobox` — hence ARIA alone under-selects it).
+ */
+const PROMPT_TRIGGER_SELECTORS = [
+    "[role='combobox'][aria-haspopup='listbox']",
+    "[role='combobox'][aria-controls]",
+    "[role='combobox'][aria-owns]",
+    "[aria-haspopup='listbox']",
+    "[data-uxi-widget-type='selectinput']",
+    "[data-uxi-widget-type='multiselect']",
+    "[data-automation-id='promptIcon']",
+    "[data-automation-id='multiSelectContainer']",
+    "[data-automation-id='promptSelectionLabel']",
+].join(",");
+/**
+ * Cross-vendor selector union for an OPTION rendered inside the opened popup —
+ * standards first (`role=option`), then the widget-kit option markers. Sibling
+ * of {@link PROMPT_TRIGGER_SELECTORS}; same union discipline and guard treatment.
+ */
+const PROMPT_OPTION_SELECTORS = [
+    "[role='option']",
+    "[data-automation-id='promptOption']",
+    "[data-uxi-widget-type='selectinputlistitem']",
+].join(",");
+/**
+ * Cross-vendor selector union for an in-popup filter/typeahead input — standards
+ * first, then the widget-kit's bare filter `<input>` (which carries no
+ * `role=searchbox`, only `data-uxi-widget-type='selectinput'` on the input
+ * itself). Sibling of {@link PROMPT_TRIGGER_SELECTORS}; same guard treatment.
+ */
+const PROMPT_SEARCH_SELECTORS = [
+    "[role='searchbox']",
+    "[role='combobox'] input[type='text']",
+    "[data-automation-id='searchBox'] input",
+    "[data-automation-id='searchBoxInput']",
+    "input[data-uxi-widget-type='selectinput']",
+].join(",");
+/**
+ * Cross-vendor selector union for the node that carries a widget's CURRENT
+ * (committed) value text — standards-poor here (no `aria-activedescendant` on
+ * the verified widget), so the widget-kit's selection-label node is a co-equal
+ * union member. Sibling of {@link PROMPT_TRIGGER_SELECTORS}.
+ */
+const PROMPT_VALUE_SELECTORS = [
+    "[data-automation-id='promptSelectionLabel']",
+    "[aria-live='polite'][data-automation-id='promptAriaInstruction']",
+].join(",");
+/**
+ * The widget-kit's empty-state value text ("0 items selected") — a filled
+ * widget's value node reads the chosen option instead. Matched
+ * case-insensitively as a whole phrase so a non-empty selection ("1 item
+ * selected, …") is correctly read as filled.
+ */
+const PROMPT_EMPTY_VALUE_RX = /^\s*0\s+items?\s+selected\s*$/i;
+/**
+ * {@link PROMPT_EMPTY_VALUE_RX}'s source and flags as plain strings, passed into
+ * the browser-evaluated expressions to reconstruct the RegExp there. Kept as
+ * separate literals (not a `.toString()` round-trip) so the reconstruction can't
+ * be corrupted if the pattern ever gains a `/`.
+ */
+const PROMPT_EMPTY_VALUE_RX_SRC = PROMPT_EMPTY_VALUE_RX.source;
+const PROMPT_EMPTY_VALUE_RX_FLAGS = PROMPT_EMPTY_VALUE_RX.flags;
+/**
+ * Browser-side expression reading a `<button>`-trigger's own committed-value
+ * text. A button's label may be a direct text node (`<button>Mobile</button>`)
+ * or a child element (`<button><span>Mobile</span></button>`), so a recursive
+ * read is needed — but it must exclude (a) a popup rendered INSIDE the trigger
+ * (`[role='option']`/`[role='listbox']`, which some libraries nest) and (b)
+ * decorative descendants (`[aria-hidden='true']`, a required-marker `<abbr>`, an
+ * icon `<svg>`) whose text would otherwise make an EMPTY placeholder button read
+ * as filled and get skipped as a candidate. Clone, strip those subtrees, read
+ * the remaining `textContent`.
+ */
+const BUTTON_VALUE_EXPR = "((el) => { const c = el.cloneNode(true); for (const n of c.querySelectorAll(\"[role='option'],[role='listbox'],[aria-hidden='true'],abbr,svg\")) n.remove(); return c.textContent || \"\"; })";
+/**
+ * Browser-side expression resolving the DOM root within which a chosen widget's
+ * popup options / filter input live. Popup placement is vendor-split: the ARIA
+ * standard and most libraries (MUI/Radix/react-select) render the listbox in a
+ * PORTAL at `document.body` linked by `aria-controls`/`aria-owns`, while others
+ * (the Canvas/UXI kit) render it INLINE inside the widget. So resolve in order:
+ * (1) the `aria-controls`/`aria-owns` target of the widget or its trigger
+ * descendant (portal-safe); (2) the widget subtree itself if it already
+ * contains the popup (inline); (3) `document` as a last resort. Returns the
+ * scope Element/Document; callers query options/search within it, which stops a
+ * sibling widget's options from being picked on a multi-widget page.
+ */
+const PROMPT_SCOPE_ROOT_EXPR = `((w) => {
+  const refAttr = (el) => (el && (el.getAttribute("aria-controls") || el.getAttribute("aria-owns"))) || "";
+  let ids = refAttr(w);
+  if (!ids) {
+    const inner = w.querySelector("[aria-controls],[aria-owns]");
+    if (inner) ids = refAttr(inner);
+  }
+  if (ids) {
+    // aria-controls/aria-owns may reference MULTIPLE ids (e.g. a listbox plus a
+    // status region). Prefer the referenced element that IS or CONTAINS a
+    // listbox/option (the portaled popup).
+    const refs = ids.split(/\\s+/).map((id) => document.getElementById(id)).filter(Boolean);
+    const withListbox = refs.find((el) => el.matches("[role='listbox']") || el.querySelector("[role='listbox'],[role='option']"));
+    if (withListbox) return withListbox;
+  }
+  // No referenced listbox: try the inline popup in the widget's own subtree
+  // BEFORE falling back to a resolved-but-listbox-less ref, then to document.
+  if (w.querySelector("[role='listbox'],[role='option']")) return w;
+  if (ids) {
+    const refs = ids.split(/\\s+/).map((id) => document.getElementById(id)).filter(Boolean);
+    if (refs.length) return refs[0];
+  }
+  return document;
+})`;
 /**
  * Extra bounded poll window for a network-only advance whose real
  * `TransitionWorklet(type="next")` POST lands AFTER the `STEP_PAUSE_MS`
@@ -2835,6 +2981,21 @@ async function readElementSelectionFingerprint(target, selector) {
  * nesting without over-reaching into an outer listbox/group.
  */
 const MAX_SELECTION_ANCESTOR_DEPTH = 6;
+/**
+ * Cross-vendor selector union for a selection-state widget that carries NO
+ * standard selection `role` or `aria-*`/`data-state` marker — a component-kit
+ * container whose selected-ness lives only in the library's own private
+ * attribute. Same multi-vendor-union discipline as {@link INVALID_MARKER_CLASS_SOURCE}
+ * and the `PROMPT_*_SELECTORS` unions: standards are checked FIRST (see
+ * `hasMarker` in {@link selectionAncestorChanged}); this union is the fallback
+ * for widgets that under-annotate ARIA, and no member is a per-site branch —
+ * each is one component library's signature. Grows by a one-line edit.
+ *
+ * Members: `data-baseweb` (Uber Base Web — verified in a real capture to mark
+ * 150 selection elements that expose no role/aria-state, so dropping it loses
+ * real coverage). Add other under-annotating kits here as they surface.
+ */
+const WIDGET_KIT_SELECTION_MARKER_SELECTORS = ["[data-baseweb]"].join(",");
 /**
  * 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
@@ -2847,7 +3008,8 @@ const MAX_SELECTION_ANCESTOR_DEPTH = 6;
  *
  * 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
+ * field, a selection `role`, or a component-kit marker from
+ * {@link WIDGET_KIT_SELECTION_MARKER_SELECTORS} — `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
@@ -2866,10 +3028,13 @@ async function selectionAncestorChanged(target, leafXpath, 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 KIT_MARKER_SEL = ${JSON.stringify(WIDGET_KIT_SELECTION_MARKER_SELECTORS)};
     const hasMarker = (el, f) => {
+      // Standards first: fingerprint fields / aria-states, then a selection role.
       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;
+      // Fallback: a component-kit selection widget that exposes no standard marker.
+      if (el.matches(KIT_MARKER_SEL)) return true;
       return false;
     };
     const changed = (a, b) =>
@@ -4652,6 +4817,427 @@ async function applyRadioSelection(target, gi, ri, hint) {
     await target.evaluate(applyExpr).catch(() => ({ ok: false }));
     return await readback();
 }
+/**
+ * Answer a native-control-less popup-dropdown widget (a combobox that opens a
+ * listbox popup and renders NO `<select>`/`<input>` a focused `<select>`/
+ * `<input>` probe can see). Detected by a cross-vendor UNION of shape signals
+ * ({@link PROMPT_TRIGGER_SELECTORS}/{@link PROMPT_OPTION_SELECTORS}), not any
+ * one vendor's private attribute — standards (ARIA `combobox`/`listbox`/
+ * `option`) where the widget exposes them, plus the well-known Canvas/UXI
+ * widget-kit markers as co-equal union members for the widgets that under-
+ * annotate ARIA (some emit `role=option` only once the popup is open, and no
+ * `role=combobox` at all).
+ *
+ * Why this exists (parallels `trySelectPrimitive`/`tryRadioPrimitive`): such a
+ * widget renders as neither a native `<select>` nor a control the observe
+ * cascade resolves to a click target, so the focused probe reports "0
+ * candidates" and the step strands. This primitive finds the widget by the
+ * trigger union, opens the popup with a real Playwright click gesture (a bare
+ * `el.click()` does not fire these widgets' open handler — the same failure
+ * mode as the MUI radio/select widgets), types into an in-popup filter input
+ * when one is present (the searchable/typeahead variant renders only a partial
+ * option slice until filtered), and clicks the matching option with a real
+ * click.
+ *
+ * Accepts a SELECT-shaped step (`parseSelectStep`, "select 'X' in the Y
+ * dropdown"), a FILL-shaped step (`parseFillStep`, "Fill in the Y field with
+ * 'X'"), or an ANSWER/RADIO-shaped step (`parseRadioStep`, "click the 'Yes'
+ * answer for the question '…'") — flow/replan generation describes this
+ * widget family's searchable variant as a fill because its filter box renders
+ * a real `<input>`, and describes its Yes/No variant with the same
+ * answer-verb phrasing used for native radio groups, even though committing
+ * either still requires the popup-open/option-click gesture below, not typed
+ * text or a bare click. `tryRadioPrimitive` (called first, see the call site)
+ * already claims answer-verb steps whose target has native
+ * `input[type=radio]` elements; this primitive only ever sees an answer-verb
+ * step after that primitive has fallen through for lack of any, so there is
+ * no double-claim. A fill or radio step's `value`/`option` becomes the option
+ * to match and its `fieldLabel`/`questionLabel` becomes the question label;
+ * downstream matching is identical across all three shapes.
+ *
+ * Matches the target widget by `questionLabel` (when the step carries one) or,
+ * failing that, by there being exactly one unfilled widget on the page —
+ * deliberately conservative: an ambiguous multi-widget page with no question
+ * label falls through to the cascade rather than guessing which widget the
+ * step means. Option matching mirrors `trySelectPrimitive`: an exact
+ * (normalized) text match is applied directly; otherwise, when an LLM client
+ * is present, `judgeSelectOptionWithLLM` picks the best rendered option
+ * (per-requisition option variance).
+ *
+ * Returns the resolved widget's DOM id (or `""`) on success — the step's
+ * `targetId` — or `null` when unhandled (no widget, no unambiguous widget
+ * match, no option match, or the selection didn't commit), so the caller
+ * falls through to the cascade unchanged, matching
+ * `trySelectPrimitive`/`tryRadioPrimitive`'s null-fallthrough contract.
+ */
+async function tryPromptSelectorPrimitive(params) {
+    const { page, target, instruction, logger, anthropic, captureFn } = params;
+    // A prompt-selector widget's search box renders a real <input>, so flow/
+    // replan generation routinely describes filling it as a FILL step ("Fill in
+    // the 'How Did You Hear About Us?' field with 'Internet/Online'") rather
+    // than a SELECT step, and its Yes/No variant renders no native radio inputs
+    // at all, so flow/replan generation describes it with the same answer-verb
+    // phrasing used for native radios ("Click the 'Yes' answer for the question
+    // '…'"). Accept all three shapes: parseSelectStep first, then parseFillStep
+    // (fieldLabel -> questionLabel, value -> option), then parseRadioStep
+    // (option/questionLabel already in this primitive's shape) so the widget-
+    // matching/open/readback phases below run unchanged regardless of which
+    // verb the instruction used.
+    const parsedSelect = parseSelectStep(instruction);
+    const parsedFill = parsedSelect ? null : parseFillStep(instruction);
+    const parsedAnswer = parsedSelect || parsedFill ? null : parseRadioStep(instruction);
+    const parsed = parsedSelect
+        ? parsedSelect
+        : parsedFill
+            ? { option: parsedFill.value, questionLabel: stripQuotedLabel(parsedFill.fieldLabel) }
+            : parsedAnswer;
+    if (!parsed)
+        return null;
+    const { option, questionLabel } = parsed;
+    const optLabel = `option "${option.slice(0, 40)}"${questionLabel ? `, question "${questionLabel.slice(0, 40)}"` : ""}`;
+    const norm = (s) => s.replace(/\s+/g, " ").trim().toLowerCase();
+    // Phase 1 (browser, read-only except for the marker attribute stamped for
+    // Phase 2's click addressing): find candidate widgets — popup-dropdown
+    // triggers with no native <select> — that are still unfilled/invalid. Options
+    // are NOT enumerated here; these widgets only render option entries once the
+    // popup is open.
+    const enumerateWidgetsExpr = `((markAttr, triggerSel, valueSel, emptyRxSrc, emptyRxFlags) => {
+    const norm = (s) => (s || "").replace(/\\s+/g, " ").trim().toLowerCase();
+    const buttonValue = ${BUTTON_VALUE_EXPR};
+    const emptyRx = new RegExp(emptyRxSrc, emptyRxFlags);
+    const triggers = Array.from(document.querySelectorAll(triggerSel));
+    if (triggers.length === 0) return { widgetPresent: false };
+    const seen = new Set();
+    const resolved = [];
+    for (const el of triggers) {
+      // Resolve each union hit to ONE widget container. A single widget often
+      // matches the union more than once (e.g. an outer container AND its inner
+      // filter input both carry data-uxi-widget-type), so prefer a real
+      // interactive ancestor, else the OUTERMOST widget-kit container on the
+      // ancestor chain (so the inner input and its container collapse to the
+      // same node), else the element itself.
+      const interactive = el.closest("button,[role='button'],[role='combobox']");
+      let container = interactive || el;
+      if (!interactive) {
+        const kitSel = "[data-uxi-widget-type='selectinput'],[data-uxi-widget-type='multiselect'],[data-automation-id='multiSelectContainer']";
+        let node = el.closest(kitSel);
+        while (node) {
+          container = node;
+          const up = node.parentElement && node.parentElement.closest(kitSel);
+          if (!up || up === node) break;
+          node = up;
+        }
+      }
+      if (seen.has(container)) continue;
+      seen.add(container);
+      resolved.push(container);
+    }
+    // Drop any candidate contained by another (belt-and-suspenders against a
+    // widget whose union hits resolve to nested containers).
+    const widgets = resolved.filter((w) => !resolved.some((o) => o !== w && o.contains(w)));
+    if (widgets.length === 0) return { widgetPresent: false };
+    const isInvalid = ${INVALID_MARKER_EL_EXPR};
+    const widgetLabel = (w) => {
+      // Standard first: aria-labelledby, aria-label, then a <label for=id>
+      // referencing the widget or a control inside it, then a labelled group
+      // ancestor (role=group[aria-labelledby] / fieldset<legend>), then the
+      // nearest non-empty ancestor text as a last resort.
+      const alb = w.getAttribute("aria-labelledby");
+      if (alb) {
+        const parts = [];
+        for (const id of alb.split(/\\s+/)) { const el = document.getElementById(id); if (el) parts.push(el.textContent); }
+        if (parts.length) return parts.join(" ").replace(/\\s+/g, " ").trim().slice(0, 120);
+      }
+      const al = w.getAttribute("aria-label");
+      if (al) return al.replace(/\\s+/g, " ").trim().slice(0, 120);
+      const labelledIds = [w.id, ...Array.from(w.querySelectorAll("[id]")).map((e) => e.id)].filter(Boolean);
+      for (const id of labelledIds) {
+        const lab = document.querySelector("label[for='" + (window.CSS && CSS.escape ? CSS.escape(id) : id) + "']");
+        if (lab && lab.textContent.trim()) return lab.textContent.replace(/\\s+/g, " ").trim().slice(0, 120);
+      }
+      const grp = w.closest("[role='group'][aria-labelledby],fieldset");
+      if (grp) {
+        const gid = grp.getAttribute("aria-labelledby");
+        const gref = gid ? document.getElementById(gid.split(/\\s+/)[0]) : grp.querySelector("legend");
+        if (gref && gref.textContent.trim()) return gref.textContent.replace(/\\s+/g, " ").trim().slice(0, 120);
+      }
+      let node = w.parentElement;
+      for (let d = 0; d < 5 && node; d++) {
+        const t = (node.textContent || "").trim();
+        if (t) return t.replace(/\\s+/g, " ").trim().slice(0, 120);
+        node = node.parentElement;
+      }
+      return "";
+    };
+    const currentText = (w) => {
+      // Value via the union: aria-activedescendant → option text, the widget's
+      // own value (an <input>'s value, or a <button>-trigger's own label text —
+      // a button that IS the trigger carries the committed choice as its own
+      // text), else a selection-label node — treating the widget-kit empty-state
+      // phrase as no value.
+      const adid = w.getAttribute && w.getAttribute("aria-activedescendant");
+      if (adid) { const opt = document.getElementById(adid); if (opt && opt.textContent.trim()) return norm(opt.textContent); }
+      if (w.tagName === "INPUT" && (w.value || "").trim()) return norm(w.value);
+      if (w.tagName === "BUTTON" && buttonValue(w).trim()) return norm(buttonValue(w));
+      const lbl = w.matches(valueSel) ? w : w.querySelector(valueSel);
+      const raw = lbl ? (lbl.textContent || "") : "";
+      if (raw.trim() && !emptyRx.test(raw.trim())) return norm(raw);
+      return "";
+    };
+    const isUnfilled = (w) => {
+      let node = w;
+      for (let d = 0; d < 6 && node; d++) {
+        if (node.getAttribute && isInvalid(node)) return true;
+        node = node.parentElement;
+      }
+      return currentText(w) === "";
+    };
+    // Clear stale marks from a prior call on this same page (this primitive
+    // runs once per "select 'X'" step, and an application wizard answers several
+    // such steps on the same unreloaded page) — otherwise a widget already
+    // filled by an earlier call keeps its old index and collides with whatever
+    // new widget claims that index this round, and the trigger-click selector's
+    // \`.first()\` can resolve to the stale widget.
+    for (const el of document.querySelectorAll("[" + markAttr + "]")) el.removeAttribute(markAttr);
+    const candidates = [];
+    let idx = 0;
+    for (const w of widgets) {
+      if (!isUnfilled(w)) continue;
+      w.setAttribute(markAttr, String(idx));
+      candidates.push({ wIdx: idx, label: widgetLabel(w) });
+      idx++;
+    }
+    if (candidates.length === 0) return { widgetPresent: true, candidates: [] };
+    return { widgetPresent: true, candidates };
+  })(${JSON.stringify(PROMPT_WIDGET_MARK_ATTR)}, ${JSON.stringify(PROMPT_TRIGGER_SELECTORS)}, ${JSON.stringify(PROMPT_VALUE_SELECTORS)}, ${JSON.stringify(PROMPT_EMPTY_VALUE_RX_SRC)}, ${JSON.stringify(PROMPT_EMPTY_VALUE_RX_FLAGS)})`;
+    try {
+        const enumResult = await pollEnumerate(page, target, enumerateWidgetsExpr, (r) => r?.widgetPresent === true);
+        if (!enumResult?.widgetPresent) {
+            logger.info(`prompt-selector primitive: no prompt widget on page for ${optLabel}; falling through to cascade`);
+            return null;
+        }
+        const candidates = enumResult.candidates ?? [];
+        if (candidates.length === 0) {
+            logger.info(`prompt-selector primitive: no unfilled prompt widget for ${optLabel}; falling through to cascade`);
+            return null;
+        }
+        // Deliberately conservative widget disambiguation (see doc comment): a
+        // labeled match must be UNIQUE, and an unlabeled step only resolves when
+        // there is exactly one unfilled widget on the page.
+        const labelMatches = questionLabel
+            ? candidates.filter((c) => c.label !== "" &&
+                (norm(c.label).includes(norm(questionLabel)) ||
+                    norm(questionLabel).includes(norm(c.label))))
+            : [];
+        const chosen = labelMatches.length === 1
+            ? labelMatches[0]
+            : !questionLabel && candidates.length === 1
+                ? candidates[0]
+                : null;
+        if (!chosen) {
+            logger.info(`prompt-selector primitive: no unambiguous widget match for ${optLabel}; falling through to cascade`);
+            return null;
+        }
+        // Phase 2 (real gesture): open the popup. These widgets' trigger requires a
+        // genuine click — a synthetic dispatchEvent does not fire its handler.
+        const triggerSel = `[${PROMPT_WIDGET_MARK_ATTR}="${chosen.wIdx}"]`;
+        try {
+            await target.locator(triggerSel).first().click();
+        }
+        catch (err) {
+            logger.info(`prompt-selector primitive: trigger click failed for ${optLabel}: ${(0, errors_1.toErrorMessage)(err)}; falling through`);
+            return null;
+        }
+        await page.waitForTimeout(PROMPT_SELECTOR_SETTLE_MS);
+        const enumerateOptionsExpr = `((widgetMarkAttr, wIdx, markAttr, optionSel, searchSel) => {
+      const w = document.querySelector("[" + widgetMarkAttr + '="' + wIdx + '"]');
+      if (!w) return { optionsPresent: false };
+      // Clear stale option + filter marks from a PRIOR prompt-selector call on
+      // this same unreloaded page (an application wizard answers several "select
+      // X" steps without a reload). Both the option-click and the filter-fill
+      // address these marks with a document-wide \`.first()\`, so a leftover mark
+      // on an earlier widget's popup would otherwise win in DOM order — the
+      // inter-call sibling collision (mirrors the widget-mark reset).
+      for (const el of document.querySelectorAll("[" + markAttr + "],[" + markAttr + "-search]")) {
+        el.removeAttribute(markAttr);
+        el.removeAttribute(markAttr + "-search");
+      }
+      // Scope options/search to THIS widget's popup (aria-controls portal, or
+      // inline subtree), so a sibling widget's options are never picked. Fall
+      // back to document only when neither a portal nor an inline popup is found.
+      const scope = ${PROMPT_SCOPE_ROOT_EXPR}(w);
+      const all = Array.from(scope.querySelectorAll(optionSel));
+      // A union hit may be an ancestor of another (e.g. role=listbox > li > p):
+      // keep only leaf-most option nodes with their own text so we don't double
+      // count or address a wrapper.
+      const opts = all.filter((el) => !all.some((o) => o !== el && el.contains(o)));
+      const searchInput = scope.querySelector(searchSel);
+      // Mark the scoped filter input so the Node-side fill addresses THIS
+      // widget's input (Playwright's locator can't re-run the scope resolution).
+      if (searchInput) searchInput.setAttribute(markAttr + "-search", "1");
+      // A searchable/typeahead widget renders NO options until its filter input
+      // is typed into — report the popup as present (with searchable=true) so the
+      // caller types the filter first, rather than falling through as "no popup".
+      if (opts.length === 0) {
+        return searchInput ? { optionsPresent: true, searchable: true, options: [] } : { optionsPresent: false };
+      }
+      const options = [];
+      for (let i = 0; i < opts.length; i++) {
+        opts[i].setAttribute(markAttr, String(i));
+        const label = opts[i].getAttribute("data-automation-label") || opts[i].getAttribute("aria-label") || opts[i].textContent || "";
+        options.push({ oIdx: i, text: label.replace(/\\s+/g, " ").trim() });
+      }
+      return { optionsPresent: true, searchable: !!searchInput, options };
+    })(${JSON.stringify(PROMPT_WIDGET_MARK_ATTR)}, ${JSON.stringify(chosen.wIdx)}, ${JSON.stringify(PROMPT_OPTION_MARK_ATTR)}, ${JSON.stringify(PROMPT_OPTION_SELECTORS)}, ${JSON.stringify(PROMPT_SEARCH_SELECTORS)})`;
+        const optionsInitial = await pollEnumerate(page, target, enumerateOptionsExpr, (r) => r?.optionsPresent === true);
+        if (!optionsInitial?.optionsPresent) {
+            logger.info(`prompt-selector primitive: popup for ${optLabel} did not render options; falling through`);
+            return null;
+        }
+        // Searchable/typeahead variant: type the option text to filter before the
+        // matching option is even rendered (a searchable widget may show only a
+        // paginated slice until filtered). Non-searchable widgets (no in-popup
+        // filter input) commit directly from the already-rendered list — a widget
+        // without a search box must NOT fall through to the cascade.
+        if (!optionsInitial.searchable) {
+            const optionsResult = optionsInitial;
+            return await commitPromptOption({
+                page,
+                target,
+                logger,
+                anthropic,
+                captureFn,
+                optLabel,
+                option,
+                questionLabel,
+                chosen,
+                optionsResult,
+            });
+        }
+        try {
+            // Fill the filter input marked for THIS widget during enumeration (scoped
+            // to its popup), falling back to the union only if the mark is absent.
+            const scopedSearchSel = `[${PROMPT_OPTION_MARK_ATTR}-search="1"]`;
+            const marked = await target.locator(scopedSearchSel).count();
+            await target
+                .locator(marked > 0 ? scopedSearchSel : PROMPT_SEARCH_SELECTORS)
+                .first()
+                .fill(option);
+        }
+        catch (err) {
+            logger.info(`prompt-selector primitive: filter-input type failed for ${optLabel}: ${(0, errors_1.toErrorMessage)(err)}; falling through`);
+            return null;
+        }
+        await page.waitForTimeout(PROMPT_SELECTOR_SETTLE_MS);
+        const optionsFiltered = await pollEnumerate(page, target, enumerateOptionsExpr, (r) => r?.optionsPresent === true);
+        if (!optionsFiltered?.optionsPresent) {
+            logger.info(`prompt-selector primitive: filtered popup for ${optLabel} rendered no options; falling through`);
+            return null;
+        }
+        return await commitPromptOption({
+            page,
+            target,
+            logger,
+            anthropic,
+            captureFn,
+            optLabel,
+            option,
+            questionLabel,
+            chosen,
+            optionsResult: optionsFiltered,
+        });
+    }
+    catch (err) {
+        logger.warn(`prompt-selector primitive: evaluate threw: ${(0, errors_1.toErrorMessage)(err)}; falling through`);
+        return null;
+    }
+}
+/**
+ * Phase 3 of {@link tryPromptSelectorPrimitive}: given the popup's rendered
+ * (possibly filtered) option list, match the requested option — deterministic
+ * exact-text match first, `judgeSelectOptionWithLLM` fallback for per-req
+ * variance — click it with a real gesture, and verify the selection committed
+ * (the widget's accessible value / selection-label reflects the chosen option
+ * by the value union, or its invalid marker cleared). Split out from the main
+ * function because both the static and searchable-then-filtered branches need
+ * the identical match/click/verify sequence.
+ */
+async function commitPromptOption(params) {
+    const { page, target, logger, anthropic, captureFn, optLabel, option, questionLabel, chosen, optionsResult, } = params;
+    const norm = (s) => s.replace(/\s+/g, " ").trim().toLowerCase();
+    const wantOpt = norm(option);
+    const options = optionsResult.options ?? [];
+    const detMatch = options.find((o) => norm(o.text) === wantOpt) ?? null;
+    if (detMatch === null && (anthropic === null || options.length === 0)) {
+        logger.info(`prompt-selector primitive: no option match for ${optLabel}${anthropic === null ? " (no LLM client)" : ""}; falling through to cascade`);
+        return null;
+    }
+    const verdict = detMatch === null
+        ? await (0, select_option_1.judgeSelectOptionWithLLM)({
+            client: anthropic,
+            input: {
+                questionLabel,
+                desiredHint: option,
+                candidates: [{ label: chosen.label || null, options: options.map((o) => o.text) }],
+            },
+            captureFn,
+        })
+        : null;
+    if (detMatch === null &&
+        (!verdict || verdict.selectIndex === null || verdict.optionIndex === null)) {
+        logger.info(`prompt-selector primitive: LLM found no matching option for ${optLabel}${verdict ? ` (${verdict.reason})` : ""}; falling through to cascade`);
+        return null;
+    }
+    const chosenOption = detMatch ??
+        (verdict && verdict.optionIndex !== null ? (options[verdict.optionIndex] ?? null) : null);
+    if (!chosenOption) {
+        logger.info(`prompt-selector primitive: option match out of range for ${optLabel}; falling through`);
+        return null;
+    }
+    const matchReason = detMatch ? "deterministic" : `LLM: ${(verdict?.reason ?? "").slice(0, 60)}`;
+    const optionSel = `[${PROMPT_OPTION_MARK_ATTR}="${chosenOption.oIdx}"]`;
+    try {
+        await target.locator(optionSel).first().click();
+    }
+    catch (err) {
+        logger.info(`prompt-selector primitive: option click failed for ${optLabel}: ${(0, errors_1.toErrorMessage)(err)}; falling through`);
+        return null;
+    }
+    await page.waitForTimeout(PROMPT_SELECTOR_SETTLE_MS);
+    const readbackExpr = `((wIdx, markAttr, valueSel, emptyRxSrc, emptyRxFlags, wantText) => {
+    const isInvalid = ${INVALID_MARKER_EL_EXPR};
+    const norm = (s) => (s || "").replace(/\\s+/g, " ").trim().toLowerCase();
+    const buttonValue = ${BUTTON_VALUE_EXPR};
+    const emptyRx = new RegExp(emptyRxSrc, emptyRxFlags);
+    const w = document.querySelector("[" + markAttr + '="' + wIdx + '"]');
+    if (!w) return { ok: false, id: "" };
+    // Value via the union: aria-activedescendant, own input value, a <button>'s
+    // own value text (popup-pollution-safe, see BUTTON_VALUE_EXPR), or a
+    // selection-label node (empty-state phrase treated as no value).
+    const adid = w.getAttribute && w.getAttribute("aria-activedescendant");
+    const adText = adid && document.getElementById(adid) ? norm(document.getElementById(adid).textContent) : "";
+    const own = w.tagName === "INPUT" ? norm(w.value || "") : w.tagName === "BUTTON" ? norm(buttonValue(w)) : "";
+    const lbl = w.matches(valueSel) ? w : w.querySelector(valueSel);
+    const lblRaw = lbl ? (lbl.textContent || "") : "";
+    const lblText = lblRaw.trim() && !emptyRx.test(lblRaw.trim()) ? norm(lblRaw) : "";
+    const text = adText || own || lblText;
+    const textMatches = wantText ? text.includes(wantText) : text !== "";
+    let node = w;
+    let stillInvalid = false;
+    for (let d = 0; d < 6 && node; d++) {
+      if (node.getAttribute && isInvalid(node)) { stillInvalid = true; break; }
+      node = node.parentElement;
+    }
+    return { ok: textMatches || !stillInvalid, id: w.id || "" };
+  })(${JSON.stringify(chosen.wIdx)}, ${JSON.stringify(PROMPT_WIDGET_MARK_ATTR)}, ${JSON.stringify(PROMPT_VALUE_SELECTORS)}, ${JSON.stringify(PROMPT_EMPTY_VALUE_RX_SRC)}, ${JSON.stringify(PROMPT_EMPTY_VALUE_RX_FLAGS)}, ${JSON.stringify(norm(chosenOption.text))})`;
+    const readback = (await target.evaluate(readbackExpr).catch(() => ({ ok: false, id: "" })));
+    if (!readback?.ok) {
+        logger.info(`prompt-selector primitive: selection for ${optLabel} did not commit; falling through to cascade`);
+        return null;
+    }
+    logger.info(`prompt-selector primitive: selected "${chosenOption.text.slice(0, 40)}" for ${optLabel} (${matchReason})`);
+    return readback.id;
+}
 /**
  * Guard for the optional-step fast-skip: is there a REQUIRED, still-empty (or
  * aria-invalid) form control on the page whose nearby label matches this step's
@@ -4673,16 +5259,20 @@ async function hasUnfilledRequiredControlForStep(target, instruction) {
     const label = extractRequiredControlProbeLabel(instruction);
     if (!label)
         return false;
-    const expr = `((label) => {
+    const expr = `((label, triggerSel) => {
     const norm = (s) => (s || "").replace(/\\s+/g, " ").trim().toLowerCase();
     const want = norm(label);
     if (!want) return false;
     const isInvalid = ${INVALID_MARKER_EL_EXPR};
-    // Required markers: the control itself, or a required-asterisk label nearby.
+    // Required markers: the control itself, a required-asterisk label nearby,
+    // or (the UXI widget-kit shape) a trailing "Required" suffix baked into the
+    // accessible name rather than exposed as aria-required at all.
     const isRequired = (el) => {
       if (!el || !el.getAttribute) return false;
       if (el.hasAttribute("required")) return true;
       if (el.getAttribute("aria-required") === "true") return true;
+      const al = el.getAttribute("aria-label");
+      if (al && /required\\s*$/i.test(al.trim())) return true;
       return false;
     };
     const isEmptyish = (el) => {
@@ -4692,11 +5282,38 @@ async function hasUnfilledRequiredControlForStep(target, instruction) {
       const v = ("value" in el) ? el.value : "";
       return !v || String(v).trim() === "";
     };
-    // Scan form controls; for each required+empty one, check whether a nearby
-    // label (ancestor label/legend, or [aria-labelledby], or preceding label)
-    // contains the question text.
+    // Standards-first, depth-independent label lookup: aria-labelledby, then
+    // a <label for=id> referencing the control or a control inside it, then
+    // the depth-capped ancestor label/legend walk as a last resort (real
+    // markup can nest a control several wrapper divs below its <label>,
+    // deeper than any fixed ancestor cap can safely assume).
+    const labelFor = (el) => {
+      const alb = el.getAttribute && el.getAttribute("aria-labelledby");
+      if (alb) {
+        const parts = [];
+        for (const id of alb.split(/\\s+/)) { const ref = document.getElementById(id); if (ref) parts.push(ref.textContent); }
+        if (parts.length) return norm(parts.join(" "));
+      }
+      const ids = [el.id, ...Array.from(el.querySelectorAll ? el.querySelectorAll("[id]") : []).map((e) => e.id)].filter(Boolean);
+      for (const id of ids) {
+        const lab = document.querySelector("label[for='" + (window.CSS && CSS.escape ? CSS.escape(id) : id) + "']");
+        if (lab && lab.textContent && lab.textContent.trim()) return norm(lab.textContent);
+      }
+      let node = el;
+      for (let d = 0; d < 6 && node; d++) {
+        const lbl = node.querySelector && node.querySelector("label,legend");
+        const txt = lbl && lbl.textContent ? norm(lbl.textContent) : "";
+        if (txt) return txt;
+        node = node.parentElement;
+      }
+      return "";
+    };
+    // Scan form controls; for each required+empty one, check whether its
+    // label matches the question. Adds the prompt-selector trigger union
+    // (button/aria-haspopup shapes with no native input/select at all) to
+    // the container-widget union already covered.
     const controls = Array.from(document.querySelectorAll(
-      "input,select,textarea,[role=combobox],[role=listbox],.bb-custom-select-container,[class*='MultiCheckboxInput']"
+      "input,select,textarea,[role=combobox],[role=listbox],.bb-custom-select-container,[class*='MultiCheckboxInput']," + triggerSel
     ));
     for (const el of controls) {
       if (!isRequired(el) && !(el.querySelector && el.querySelector("[required],[aria-required=true]"))) {
@@ -4706,17 +5323,11 @@ async function hasUnfilledRequiredControlForStep(target, instruction) {
       // is it empty/invalid?
       const emptyOrInvalid = isEmptyish(el) || (el.querySelector && !!el.querySelector("[aria-invalid=true]"));
       if (!emptyOrInvalid) continue;
-      // does a nearby label match the question?
-      let node = el;
-      for (let d = 0; d < 6 && node; d++) {
-        const lbl = node.querySelector && node.querySelector("label,legend");
-        const txt = lbl && lbl.textContent ? norm(lbl.textContent) : "";
-        if (txt && (txt.includes(want) || want.includes(txt))) return true;
-        node = node.parentElement;
-      }
+      const txt = labelFor(el);
+      if (txt && (txt.includes(want) || want.includes(txt))) return true;
     }
     return false;
-  })(${JSON.stringify(label)})`;
+  })(${JSON.stringify(label)}, ${JSON.stringify(PROMPT_TRIGGER_SELECTORS)})`;
     try {
         return (await target.evaluate(expr)) === true;
     }
@@ -5686,6 +6297,30 @@ async function executeStepWithHealing(params) {
         trajectory?.push({ stepIndex, verifiedBy: "dom", targetId: radioTargetId });
         return "completed";
     }
+    // When the step is a "select 'X'" OR a "Fill in the Y field with 'X'" step
+    // (the latter shape is how flow/replan generation describes this widget's
+    // searchable filter box, which renders a real <input>) whose only matching
+    // control is a native-control-less popup-dropdown widget (a combobox that
+    // opens a listbox popup, options rendered on-demand — see
+    // PROMPT_TRIGGER_SELECTORS) rather than a <select> or MUI radio group,
+    // answer it directly. Runs AFTER select/checkbox/radio (which own their own
+    // widget shapes and would already have claimed the step) and BEFORE the
+    // cascade, since the widget's trigger exposes no native control the observe
+    // cascade resolves. No-op (falls through) when there's no unfilled/
+    // unambiguous prompt widget or no confident option match.
+    const promptSelectorTargetId = await tryPromptSelectorPrimitive({
+        page,
+        target: selectFrameTarget,
+        instruction: step,
+        logger,
+        anthropic,
+        captureFn,
+    });
+    if (promptSelectorTargetId !== null) {
+        logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by prompt-selector primitive`);
+        trajectory?.push({ stepIndex, verifiedBy: "dom", targetId: promptSelectorTargetId });
+        return "completed";
+    }
     // On a CATCH-ALL step ("for any remaining … question"), fill every
     // required-but-empty native <select> — including MuiNativeSelect dropdowns
     // (tabindex=-1) that Stagehand observe can't see and that no concrete flow