@geometra/proxy 1.63.2 → 1.65.0

package/dist/dom-actions.js

@@ -1,10 +1,12 @@
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
 import { canonicalizeHtmlInputValue } from './input-canonical.js';
 export function delay(ms) {
     return new Promise(r => setTimeout(r, ms));
 }
 const LABELED_CONTROL_SELECTOR = 'input, select, textarea, button, [role="combobox"], [role="textbox"], [aria-haspopup="listbox"], [aria-haspopup="menu"], [aria-haspopup="true"], [contenteditable="true"]';
+const EDITABLE_FIELD_SELECTOR = 'input:not([type="checkbox"]):not([type="radio"]):not([type="file"]):not([type="button"]):not([type="submit"]):not([type="reset"]):not([type="hidden"]), textarea, [role="textbox"], [role="combobox"], [contenteditable="true"]';
+const TOGGLE_CONTROL_SELECTOR = 'input[type="checkbox"], input[type="radio"], [role="checkbox"], [role="radio"], [role="switch"]';
 const MENU_TRIGGER_SELECTOR = 'button[aria-haspopup="menu"], button[aria-haspopup="true"], [role="button"][aria-haspopup="menu"], [role="button"][aria-haspopup="true"]';
 const POPUP_CONTAINER_SELECTOR = '[role="listbox"], [role="menu"], [role="dialog"], [aria-modal="true"], [data-radix-popper-content-wrapper], [class*="menu"], [class*="option"], [class*="select"], [class*="dropdown"]';
 const POPUP_ROOT_SELECTOR = '[role="listbox"], [role="menu"], [role="dialog"], [aria-modal="true"], [data-radix-popper-content-wrapper], [class*="menu"], [class*="dropdown"], [class*="popover"], [class*="listbox"], [class*="options"]';
@@ -43,10 +45,12 @@ export function clearFillLookupCache(cache) {
 function lookupCacheKey(kind, label, exact) {
     return `${kind}:${exact ? 'exact' : 'fuzzy'}:${normalizedOptionLabel(label)}`;
 }
-function lookupCacheKeys(kind, label, exact, fieldId) {
+function lookupCacheKeys(kind, label, exact, fieldId, fieldKey) {
     const keys = [lookupCacheKey(kind, label, exact)];
     if (fieldId)
         keys.unshift(`${kind}:id:${fieldId}`);
+    if (fieldKey)
+        keys.unshift(`${kind}:key:${fieldKey}`);
     return keys;
 }
 function cacheMapForKind(cache, kind) {
@@ -56,23 +60,157 @@ function cacheMapForKind(cache, kind) {
         return cache.editable;
     return cache.fileInput;
 }
-function readCachedLocator(cache, kind, label, exact, fieldId) {
+async function readCachedLocator(cache, kind, label, exact, fieldId, fieldKey) {
     if (!cache)
         return undefined;
     const map = cacheMapForKind(cache, kind);
+    const readLive = async (key) => {
+        if (!map.has(key))
+            return undefined;
+        const locator = map.get(key);
+        // Never retain negative lookups across reactive re-renders.
+        if (!locator) {
+            map.delete(key);
+            return undefined;
+        }
+        try {
+            const attached = await locator.count() > 0;
+            const usable = attached && (kind === 'file' || await locator.isVisible());
+            const identityMatches = usable && fieldKey && key === `${kind}:key:${fieldKey}`
+                ? await locatorMatchesAuthoredFieldKey(locator, fieldKey)
+                : usable;
+            if (identityMatches)
+                return locator;
+        }
+        catch {
+            // Detached locators are normal after controlled-form re-renders.
+        }
+        map.delete(key);
+        return undefined;
+    };
+    // A newly supplied authored fieldKey must get a chance to resolve before a
+    // locator cached under the looser schema id or label is reused.
+    if (fieldKey) {
+        const key = `${kind}:key:${fieldKey}`;
+        return await readLive(key);
+    }
     for (const key of lookupCacheKeys(kind, label, exact, fieldId)) {
-        if (map.has(key))
-            return map.get(key) ?? null;
+        const locator = await readLive(key);
+        if (locator)
+            return locator;
     }
     return undefined;
 }
-function writeCachedLocator(cache, kind, label, exact, fieldId, locator) {
+function writeCachedLocator(cache, kind, label, exact, fieldId, fieldKey, locator) {
     if (!cache)
         return;
     const map = cacheMapForKind(cache, kind);
-    for (const key of lookupCacheKeys(kind, label, exact, fieldId)) {
-        map.set(key, locator);
+    const keys = fieldKey
+        ? [`${kind}:key:${fieldKey}`, ...(fieldId ? [`${kind}:id:${fieldId}`] : [])]
+        : lookupCacheKeys(kind, label, exact, fieldId);
+    for (const key of keys) {
+        if (locator)
+            map.set(key, locator);
+        else
+            map.delete(key);
+    }
+}
+function parseAuthoredFieldKey(fieldKey) {
+    const normalized = fieldKey.trim();
+    if (!normalized || normalized !== fieldKey) {
+        throw new Error('fieldKey must be a trimmed, non-empty string');
+    }
+    if (normalized.startsWith('id:')) {
+        try {
+            const id = decodeURIComponent(normalized.slice(3));
+            if (id)
+                return { kind: 'id', id };
+        }
+        catch {
+            throw new Error('fieldKey contains an invalid encoded id');
+        }
+    }
+    if (normalized.startsWith('name:')) {
+        const parts = normalized.split(':');
+        const tag = parts[1]?.trim().toLowerCase();
+        const type = parts[2]?.trim().toLowerCase();
+        try {
+            const name = decodeURIComponent(parts.slice(3).join(':'));
+            if (tag && type && name)
+                return { kind: 'name', tag, type, name };
+        }
+        catch {
+            throw new Error('fieldKey contains an invalid encoded name');
+        }
+    }
+    throw new Error('fieldKey must use id:<id> or name:<tag>:<type-or-default>:<name>');
+}
+async function locatorMatchesAuthoredFieldKey(locator, fieldKey) {
+    const parsed = parseAuthoredFieldKey(fieldKey);
+    try {
+        return await locator.evaluate((element, key) => {
+            if (!(element instanceof Element))
+                return false;
+            if (key.kind === 'id')
+                return element.getAttribute('id') === key.id;
+            const authoredType = element.getAttribute('type')?.trim().toLowerCase() || 'default';
+            return element.tagName.toLowerCase() === key.tag &&
+                authoredType === key.type &&
+                element.getAttribute('name') === key.name;
+        }, parsed);
+    }
+    catch {
+        return false;
+    }
+}
+function selectorForAuthoredFieldKind(kind) {
+    if (kind === 'editable')
+        return EDITABLE_FIELD_SELECTOR;
+    if (kind === 'file')
+        return 'input[type="file"]';
+    if (kind === 'toggle')
+        return TOGGLE_CONTROL_SELECTOR;
+    return LABELED_CONTROL_SELECTOR;
+}
+async function findAuthoredFieldByKeyInPage(page, fieldKey, kind) {
+    const parsed = parseAuthoredFieldKey(fieldKey);
+    const matches = [];
+    for (const frame of page.frames()) {
+        const candidates = frame.locator(selectorForAuthoredFieldKind(kind));
+        const indices = await candidates.evaluateAll((elements, key) => {
+            const result = [];
+            for (let index = 0; index < elements.length; index++) {
+                const element = elements[index];
+                if (!(element instanceof Element))
+                    continue;
+                if (key.kind === 'id') {
+                    if (element.getAttribute('id') === key.id)
+                        result.push(index);
+                    continue;
+                }
+                const authoredType = element.getAttribute('type')?.trim().toLowerCase() || 'default';
+                if (element.tagName.toLowerCase() === key.tag &&
+                    authoredType === key.type &&
+                    element.getAttribute('name') === key.name) {
+                    result.push(index);
+                }
+            }
+            return result;
+        }, parsed);
+        for (const index of indices) {
+            const locator = candidates.nth(index);
+            if (kind === 'editable' && !(await locatorIsEditable(locator)))
+                continue;
+            if (kind !== 'file' && !(await locator.isVisible()))
+                continue;
+            matches.push({ locator, frameUrl: frame.url() });
+        }
     }
+    if (matches.length > 1) {
+        const frames = [...new Set(matches.map(match => match.frameUrl || '<top-frame>'))];
+        throw new Error(`fieldKey "${fieldKey}" is ambiguous: matched ${matches.length} controls across ${frames.join(', ')}`);
+    }
+    return matches[0]?.locator ?? null;
 }
 function normalizedOptionLabel(value) {
     return value
@@ -298,6 +436,97 @@ async function locatorIsEditable(locator) {
         return false;
     }
 }
+/**
+ * Return the effective browser state that makes a control unsafe to mutate.
+ * This deliberately walks the composed tree: framework controls often put
+ * the clickable/editable node inside a shadow root while disabled/inert ARIA
+ * state lives on the host.
+ */
+function mutationBlockReasonInPage(target, intent) {
+    function composedParent(node) {
+        if (node.parentElement)
+            return node.parentElement;
+        const root = node.getRootNode();
+        return root instanceof ShadowRoot ? root.host : null;
+    }
+    function composedDescendantOf(node, ancestor) {
+        let current = node;
+        while (current) {
+            if (current === ancestor)
+                return true;
+            current = composedParent(current);
+        }
+        return false;
+    }
+    // Native :disabled includes the disabled-fieldset/first-legend rules for
+    // form controls in the light DOM. The explicit ancestor walk below extends
+    // the same fail-closed behavior to custom and shadow-root controls.
+    try {
+        if (target.matches(':disabled'))
+            return 'disabled';
+    }
+    catch { /* non-HTML namespaces may reject pseudo classes */ }
+    if ((target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) &&
+        target.readOnly) {
+        return 'readonly';
+    }
+    let current = target;
+    while (current) {
+        if (current.hasAttribute('inert'))
+            return 'inert';
+        if (current.getAttribute('aria-disabled')?.trim().toLowerCase() === 'true')
+            return 'aria-disabled';
+        if (current.getAttribute('aria-readonly')?.trim().toLowerCase() === 'true')
+            return 'aria-readonly';
+        if (current instanceof HTMLFieldSetElement && current.disabled) {
+            const firstLegend = Array.from(current.children).find(child => child instanceof HTMLLegendElement);
+            if (!(firstLegend instanceof HTMLLegendElement) || !composedDescendantOf(target, firstLegend)) {
+                return 'disabled fieldset';
+            }
+        }
+        current = composedParent(current);
+    }
+    // Keep the argument explicit for call-site readability and future
+    // intent-specific platform states even though every current intent shares
+    // the effective ARIA/inert/fieldset policy.
+    void intent;
+    return null;
+}
+async function locatorMutationBlockReason(locator, intent) {
+    try {
+        return await locator.evaluate(mutationBlockReasonInPage, intent);
+    }
+    catch {
+        return 'detached or unavailable';
+    }
+}
+async function assertLocatorMutable(locator, intent, action) {
+    const reason = await locatorMutationBlockReason(locator, intent);
+    if (reason)
+        throw new Error(`${action}: matched control is not mutable (${reason})`);
+}
+async function elementHandleAtPoint(page, x, y) {
+    const handle = await page.evaluateHandle(({ pointX, pointY }) => document.elementFromPoint(pointX, pointY), { pointX: x, pointY: y });
+    const element = handle.asElement();
+    if (element)
+        return element;
+    await handle.dispose();
+    return null;
+}
+async function assertPointMutable(page, x, y, intent, action) {
+    const element = await elementHandleAtPoint(page, x, y);
+    if (!element) {
+        throw new Error(`${action}: no element at the supplied coordinates`);
+    }
+    try {
+        const reason = await element.evaluate(mutationBlockReasonInPage, intent);
+        if (reason)
+            throw new Error(`${action}: matched control is not mutable (${reason})`);
+    }
+    finally {
+        await element.dispose();
+    }
+}
 async function locatorAnchorY(locator) {
     const bounds = await locator.boundingBox();
     return bounds ? bounds.y + bounds.height / 2 : undefined;
@@ -438,7 +667,15 @@ async function findLabeledControl(frame, fieldLabel, exact, opts) {
             const style = getComputedStyle(el);
             return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
         }
-        function referencedText(ids, visited) {
+        function rootScopedElementById(owner, id) {
+            const root = owner.getRootNode();
+            if (root instanceof ShadowRoot)
+                return root.getElementById(id);
+            if (root instanceof Document)
+                return root.getElementById(id);
+            return null;
+        }
+        function referencedText(owner, ids, visited) {
             if (!ids)
                 return undefined;
             const seen = visited ?? new Set();
@@ -448,12 +685,12 @@ async function findLabeledControl(frame, fieldLabel, exact, opts) {
                 if (seen.has(id))
                     return '';
                 seen.add(id);
-                const target = document.getElementById(id);
+                const target = rootScopedElementById(owner, id);
                 if (!target)
                     return '';
                 const chained = target.getAttribute('aria-labelledby');
                 if (chained)
-                    return referencedText(chained, seen) ?? '';
+                    return referencedText(target, chained, seen) ?? '';
                 return target.textContent?.trim() ?? '';
             })
                 .filter(Boolean)
@@ -465,7 +702,7 @@ async function findLabeledControl(frame, fieldLabel, exact, opts) {
             const aria = el.getAttribute('aria-label')?.trim();
             if (aria)
                 return aria;
-            const labelledBy = referencedText(el.getAttribute('aria-labelledby'));
+            const labelledBy = referencedText(el, el.getAttribute('aria-labelledby'));
             if (labelledBy)
                 return labelledBy;
             if ((el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement) &&
@@ -474,7 +711,10 @@ async function findLabeledControl(frame, fieldLabel, exact, opts) {
                 return el.labels[0]?.textContent?.trim() || undefined;
             }
             if (el instanceof HTMLElement && el.id) {
-                const label = document.querySelector(`label[for="${CSS.escape(el.id)}"]`);
+                const root = el.getRootNode();
+                const label = (root instanceof Document || root instanceof ShadowRoot)
+                    ? root.querySelector(`label[for="${CSS.escape(el.id)}"]`)
+                    : null;
                 const text = label?.textContent?.trim();
                 if (text)
                     return text;
@@ -631,6 +871,14 @@ async function findMenuTriggerByContainerLabel(frame, fieldLabel, exact) {
             const style = getComputedStyle(el);
             return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
         }
+        function rootScopedElementById(owner, id) {
+            const root = owner.getRootNode();
+            if (root instanceof ShadowRoot)
+                return root.getElementById(id);
+            if (root instanceof Document)
+                return root.getElementById(id);
+            return null;
+        }
         function containerLabelText(el) {
             // Walk up a few parent levels looking for a container that holds BOTH
             // the trigger and some sibling label text. The label text is the
@@ -673,7 +921,7 @@ async function findMenuTriggerByContainerLabel(frame, fieldLabel, exact) {
             if (labelledBy) {
                 const text = labelledBy
                     .split(/\s+/)
-                    .map(id => document.getElementById(id)?.textContent?.trim() ?? '')
+                    .map(id => rootScopedElementById(el, id)?.textContent?.trim() ?? '')
                     .filter(Boolean)
                     .join(' ')
                     .trim();
@@ -697,12 +945,94 @@ async function findMenuTriggerByContainerLabel(frame, fieldLabel, exact) {
     }, { fieldLabel, exact });
     return bestIndex >= 0 ? triggers.nth(bestIndex) : null;
 }
+async function locatorMatchesControlLabel(locator, fieldLabel, exact) {
+    const accessibleName = await locator.evaluate((el) => {
+        function rootScopedElementById(owner, id) {
+            const root = owner.getRootNode();
+            if (root instanceof ShadowRoot)
+                return root.getElementById(id);
+            if (root instanceof Document)
+                return root.getElementById(id);
+            return null;
+        }
+        function textWithoutNestedControls(node) {
+            if (node.nodeType === Node.TEXT_NODE)
+                return node.textContent ?? '';
+            if (!(node instanceof Element))
+                return '';
+            const tag = node.tagName.toLowerCase();
+            if (tag === 'input' || tag === 'select' || tag === 'textarea' || tag === 'button')
+                return '';
+            return Array.from(node.childNodes).map(textWithoutNestedControls).join('');
+        }
+        function referencedText(owner, ids, visited) {
+            if (!ids)
+                return '';
+            const seen = visited ?? new Set();
+            return ids
+                .split(/\s+/)
+                .map(id => {
+                if (seen.has(id))
+                    return '';
+                seen.add(id);
+                const target = rootScopedElementById(owner, id);
+                if (!target)
+                    return '';
+                const chained = target.getAttribute('aria-labelledby');
+                if (chained)
+                    return referencedText(target, chained, seen);
+                return textWithoutNestedControls(target).replace(/\s+/g, ' ').trim();
+            })
+                .filter(Boolean)
+                .join(' ');
+        }
+        const explicit = el.getAttribute('aria-label')?.trim() || referencedText(el, el.getAttribute('aria-labelledby'));
+        if (explicit)
+            return explicit;
+        if (el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement) {
+            const associated = Array.from(el.labels ?? [])
+                .map(label => textWithoutNestedControls(label).replace(/\s+/g, ' ').trim())
+                .find(Boolean);
+            if (associated)
+                return associated;
+            const placeholder = el.getAttribute('placeholder')?.trim();
+            if (placeholder)
+                return placeholder;
+        }
+        if (el.parentElement instanceof HTMLLabelElement) {
+            return textWithoutNestedControls(el.parentElement).replace(/\s+/g, ' ').trim();
+        }
+        return el.getAttribute('title')?.trim() || el.textContent?.trim() || '';
+    }).catch(() => '');
+    const candidate = normalizedOptionLabel(accessibleName);
+    const expected = normalizedOptionLabel(fieldLabel);
+    if (!candidate || !expected)
+        return false;
+    return exact ? candidate === expected : candidate === expected || candidate.includes(expected);
+}
 async function findLabeledControlInPage(page, fieldLabel, exact, opts) {
     const cacheable = !opts?.preferredAnchor;
-    const cached = cacheable ? readCachedLocator(opts?.cache, 'control', fieldLabel, exact, opts?.fieldId) : undefined;
+    const cached = cacheable
+        ? await readCachedLocator(opts?.cache, 'control', fieldLabel, exact, opts?.fieldId, opts?.fieldKey)
+        : undefined;
     if (cached !== undefined) {
+        if (cached && opts?.fieldKey && fieldLabel && !(await locatorMatchesControlLabel(cached, fieldLabel, exact))) {
+            throw new Error(`fieldKey "${opts.fieldKey}" did not match field label "${fieldLabel}"`);
+        }
         return cached;
     }
+    if (opts?.fieldKey) {
+        const authored = await findAuthoredFieldByKeyInPage(page, opts.fieldKey, 'control');
+        if (authored) {
+            if (fieldLabel && !(await locatorMatchesControlLabel(authored, fieldLabel, exact))) {
+                throw new Error(`fieldKey "${opts.fieldKey}" did not match field label "${fieldLabel}"`);
+            }
+            if (cacheable)
+                writeCachedLocator(opts?.cache, 'control', fieldLabel, exact, opts?.fieldId, opts.fieldKey, authored);
+            return authored;
+        }
+        throw new Error(`fieldKey "${opts.fieldKey}" did not resolve to a visible control; refresh geometra_form_schema`);
+    }
     // Try the label as-is first. If the caller passed a fully-qualified DOM
     // label, that's the most accurate match.
     for (const frame of page.frames()) {
@@ -710,7 +1040,7 @@ async function findLabeledControlInPage(page, fieldLabel, exact, opts) {
         if (!locator)
             continue;
         if (cacheable)
-            writeCachedLocator(opts?.cache, 'control', fieldLabel, exact, opts?.fieldId, locator);
+            writeCachedLocator(opts?.cache, 'control', fieldLabel, exact, opts?.fieldId, undefined, locator);
         return locator;
     }
     // Fallback: if the label looks truncated (ends in U+2026 or "..."), strip
@@ -726,7 +1056,7 @@ async function findLabeledControlInPage(page, fieldLabel, exact, opts) {
             if (!locator)
                 continue;
             if (cacheable)
-                writeCachedLocator(opts?.cache, 'control', fieldLabel, exact, opts?.fieldId, locator);
+                writeCachedLocator(opts?.cache, 'control', fieldLabel, exact, opts?.fieldId, undefined, locator);
             return locator;
         }
     }
@@ -741,12 +1071,12 @@ async function findLabeledControlInPage(page, fieldLabel, exact, opts) {
             if (!locator)
                 continue;
             if (cacheable)
-                writeCachedLocator(opts?.cache, 'control', fieldLabel, exact, opts?.fieldId, locator);
+                writeCachedLocator(opts?.cache, 'control', fieldLabel, exact, opts?.fieldId, undefined, locator);
             return locator;
         }
     }
     if (cacheable)
-        writeCachedLocator(opts?.cache, 'control', fieldLabel, exact, opts?.fieldId, null);
+        writeCachedLocator(opts?.cache, 'control', fieldLabel, exact, opts?.fieldId, undefined, null);
     return null;
 }
 function textMatches(candidate, expected, exact) {
@@ -763,9 +1093,10 @@ function displayedValueMatchesSelection(candidate, expected, exact, selectedOpti
         return false;
     return (normalizedSelectedOption.includes(normalizedCandidate) || normalizedCandidate.includes(normalizedSelectedOption));
 }
-async function openDropdownControl(page, fieldLabel, exact, cache, fieldId) {
-    const locator = await findLabeledControlInPage(page, fieldLabel, exact, { cache, fieldId });
+async function openDropdownControl(page, fieldLabel, exact, cache, fieldId, fieldKey) {
+    const locator = await findLabeledControlInPage(page, fieldLabel, exact, { cache, fieldId, fieldKey });
     if (locator) {
+        await assertLocatorMutable(locator, 'select', 'listboxPick');
         await locator.scrollIntoViewIfNeeded();
         const handle = await locator.elementHandle();
         const clickTarget = await resolveMeaningfulClickTarget(locator);
@@ -866,11 +1197,19 @@ async function resolveOwnedPopupHandle(triggerHandle) {
                 }
                 return ids;
             }
+            function rootScopedElementById(owner, id) {
+                const root = owner.getRootNode();
+                if (root instanceof ShadowRoot)
+                    return root.getElementById(id);
+                if (root instanceof Document)
+                    return root.getElementById(id);
+                return null;
+            }
             function lookupReferenced() {
                 const attributes = ['aria-controls', 'aria-owns', 'aria-activedescendant'];
                 for (const attribute of attributes) {
                     for (const id of readIdRefs(el, attribute)) {
-                        const referenced = document.getElementById(id);
+                        const referenced = rootScopedElementById(el, id);
                         const popup = asPopupRoot(referenced);
                         if (popup)
                             return popup;
@@ -1506,6 +1845,8 @@ async function clickScopedOptionCandidate(popupScope, label, exact) {
         }, hit.selector)).asElement();
         if (!target)
             return null;
+        if (await target.evaluate(mutationBlockReasonInPage, 'select'))
+            return null;
         try {
             await target.scrollIntoViewIfNeeded({ timeout: 500 });
         }
@@ -1690,6 +2031,8 @@ async function clickVisibleOptionCandidate(page, label, exact, anchor, popupScop
         });
         if (bestIndex >= 0) {
             const candidate = candidates.nth(bestIndex);
+            if (await locatorMutationBlockReason(candidate, 'select'))
+                return null;
             const selectedText = (await candidate.evaluate(el => el.getAttribute('aria-label')?.trim() || el.textContent?.trim() || '').catch(() => '')) || null;
             const clickTarget = await resolveMeaningfulOptionClickTarget(candidate);
             // Only scrollIntoView if the option is NOT inside a popup/dropdown container.
@@ -1876,116 +2219,6 @@ async function readTriggerShowsPlaceholder(handle) {
         return false;
     }
 }
-/**
- * Detect whether a combobox trigger is a "searchable/autocomplete style"
- * combobox (React Select, Headless UI, Radix, Ant Design Select, etc.).
- *
- * These libraries commit their controlled `onChange` state on **keyboard
- * Enter**, not on a synthetic mouse click dispatched via Playwright's
- * `.click()`. For regular mouse interactions they use a bubbling
- * `mousedown`/`pointerdown` path that does not round-trip through React
- * Select's internal `selectOption` handler in some Remix-wrapped builds
- * (notably Greenhouse's ATS embed), so the option click fires visually but
- * the form state stays empty. Pressing Enter on the focused combobox input
- * after the click puts the selection through the keyboard code path which
- * ALWAYS commits.
- *
- * Detection is fully generic — no hostname or site-specific branching.
- * The signals we look for are:
- *
- *   1. `aria-autocomplete` on the element or its nearest ancestor input is
- *      `"list"` or `"both"`. This is the standards-aligned signal for any
- *      combobox that filters options as the user types.
- *   2. A class pattern indicative of React Select (`select__control`,
- *      `select__`), React Suite picker (`rs-picker`), or Ant Design Select
- *      (`ant-select`) on the element or any ancestor up to 5 levels.
- *   3. `role="combobox"` present together with `aria-expanded` on the
- *      element or an ancestor — the ARIA 1.2 combobox pattern.
- *
- * Native `<select>` elements do NOT match any of these signals, so the
- * caller can safely gate its `Enter` dispatch on this check without
- * breaking non-searchable listboxes.
- */
-async function isAutocompleteCombobox(handle) {
-    if (!handle)
-        return false;
-    try {
-        return await handle.evaluate((el) => {
-            if (!(el instanceof Element))
-                return false;
-            let cur = el;
-            let depth = 0;
-            while (cur && depth < 5) {
-                // aria-autocomplete on the element or an ancestor input/combobox.
-                const ac = cur.getAttribute('aria-autocomplete');
-                if (ac === 'list' || ac === 'both')
-                    return true;
-                // Class-based fingerprint for known autocomplete libraries.
-                const className = (cur.getAttribute('class') ?? '').toLowerCase();
-                if (className) {
-                    if (className.includes('select__control') ||
-                        className.includes('select__') ||
-                        className.includes('rs-picker') ||
-                        className.includes('ant-select') ||
-                        className.includes('headlessui-combobox') ||
-                        className.includes('cmdk-')) {
-                        return true;
-                    }
-                }
-                // ARIA 1.2 combobox pattern: role="combobox" + aria-expanded is a
-                // strong signal that the control commits via keyboard semantics.
-                if (cur.getAttribute('role') === 'combobox' && cur.hasAttribute('aria-expanded')) {
-                    return true;
-                }
-                cur = cur.parentElement;
-                depth++;
-            }
-            // Also look downward for a descendant input that declares
-            // aria-autocomplete — some Headless UI wrappers expose the control via
-            // a sibling input inside the trigger container.
-            const descendant = el.querySelector?.('[aria-autocomplete="list"], [aria-autocomplete="both"]');
-            return !!descendant;
-        });
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Dispatch a keyboard `Enter` to commit an autocomplete-style combobox's
- * selection after the option has been clicked. Only fires if the trigger
- * looks like a searchable combobox per {@link isAutocompleteCombobox}.
- *
- * Why this exists: Playwright's `.click()` on a React Select option DOM
- * element dispatches a synthetic `pointerdown`/`mouseup`/`click` sequence
- * that a subset of React Select forks (and every Remix-wrapped Greenhouse
- * ATS build we've seen) will NOT commit through `selectOption`. The
- * library's `keydown Enter` handler, however, unconditionally commits via
- * the same internal `setValue` the visual selection uses. Pressing Enter
- * after the click is therefore a universal "force commit" primitive for
- * searchable comboboxes that benefit every library without touching the
- * native-<select> happy path.
- *
- * Intentionally swallows errors — this is a best-effort commit helper and
- * a missing page/focus should not break the surrounding selection flow.
- */
-async function pressEnterToCommitListbox(page, handle) {
-    if (!handle)
-        return false;
-    if (!(await isAutocompleteCombobox(handle)))
-        return false;
-    try {
-        await page.keyboard.press('Enter');
-        // Short settle window for the library to run its onChange -> form
-        // state update. 80ms is the same budget used elsewhere in this file
-        // for React Select commit propagation.
-        await delay(80);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * After a custom listbox option click, make the committed value visible to
  * framework state managers that listen on the backing input/select instead of
@@ -2507,6 +2740,22 @@ async function confirmListboxSelection(page, fieldLabel, label, exact, anchor, c
     }
     return false;
 }
+async function confirmListboxSelectionWithoutLabel(page, label, exact, anchor, currentHandle, selectedOptionText) {
+    const deadline = Date.now() + 800;
+    while (Date.now() < deadline) {
+        if (currentHandle) {
+            const values = await elementHandleDisplayedValues(currentHandle);
+            const matches = values.some(value => displayedValueMatchesSelection(value, label, exact, selectedOptionText));
+            if (matches && !(await readAriaInvalid(currentHandle)) && !(await readTriggerShowsPlaceholder(currentHandle))) {
+                return true;
+            }
+        }
+        if (await visibleOptionIsSelected(page, label, exact, anchor))
+            return true;
+        await delay(80);
+    }
+    return false;
+}
 const PLACEHOLDER_PATTERN = /^(select|choose|pick|--|—\s)/i;
 /**
  * Dismiss the dropdown (Tab) and re-verify the field value didn't revert to a placeholder.
@@ -2537,7 +2786,7 @@ async function dismissAndReVerifySelection(page, label, exact, currentHandle, se
     }
     await delay(50);
     if (!currentHandle)
-        return true;
+        return false;
     // Re-verify using the original element handle (immune to DOM reordering)
     const deadline = Date.now() + 800;
     let sawAnyValue = false;
@@ -2572,8 +2821,9 @@ async function dismissAndReVerifySelection(page, label, exact, currentHandle, se
             }
         }
         catch {
-            // Handle detached — trust the earlier confirmation
-            return true;
+            // A detached trigger has no observable committed state. Fail closed;
+            // callers can re-resolve the live field and retry.
+            return false;
         }
         await delay(100);
     }
@@ -2609,192 +2859,580 @@ async function dismissAndReVerifySelection(page, label, exact, currentHandle, se
 /**
  * Resolve and validate paths on the machine running the proxy (not the agent host).
  */
-export function resolveExistingFiles(rawPaths) {
+export function resolveExistingFiles(rawPaths, allowedRoots = []) {
     if (!Array.isArray(rawPaths) || rawPaths.length === 0) {
         throw new Error('file: paths must be a non-empty array of strings');
     }
+    if (allowedRoots.length === 0) {
+        throw new Error('file: uploads are disabled; configure one or more canonical roots with GEOMETRA_PROXY_FILE_ROOTS');
+    }
+    const canonicalRoots = allowedRoots.map(root => {
+        const absoluteRoot = resolve(root);
+        if (!existsSync(absoluteRoot))
+            throw new Error(`file: allowed root does not exist: ${absoluteRoot}`);
+        const canonicalRoot = realpathSync(absoluteRoot);
+        if (!statSync(canonicalRoot).isDirectory()) {
+            throw new Error(`file: allowed root is not a directory: ${absoluteRoot}`);
+        }
+        return canonicalRoot;
+    });
     const paths = [];
     for (const p of rawPaths) {
         if (typeof p !== 'string' || p.trim() === '')
             continue;
-        paths.push(resolve(p));
+        const absolutePath = resolve(p);
+        if (!existsSync(absolutePath))
+            throw new Error(`file: path does not exist: ${absolutePath}`);
+        const canonicalPath = realpathSync(absolutePath);
+        if (!statSync(canonicalPath).isFile())
+            throw new Error(`file: path is not a regular file: ${absolutePath}`);
+        const allowed = canonicalRoots.some(root => {
+            const rel = relative(root, canonicalPath);
+            return rel !== '' && rel !== '..' && !rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) && !isAbsolute(rel);
+        });
+        if (!allowed)
+            throw new Error(`file: path is outside configured upload roots: ${absolutePath}`);
+        paths.push(canonicalPath);
     }
     if (paths.length === 0)
         throw new Error('file: paths must contain at least one non-empty string');
-    for (const p of paths) {
-        if (!existsSync(p))
-            throw new Error(`file: path does not exist: ${p}`);
-    }
     return paths;
 }
-async function findLabeledFileInput(frame, fieldLabel, exact) {
-    // Try exact-match candidates first, even when the caller passed
-    // exact=false. Same Greenhouse-style failure mode as findLabeledControl:
-    // a substring match (e.g. file labeled "Resume" hijacked by another
-    // "Please attach your resume below" field) silently picks the wrong
-    // input. Trying exact first guarantees the literal label wins when
-    // present, and only falls through to substring matching otherwise.
-    const exactDirect = frame.getByLabel(fieldLabel, { exact: true });
-    const exactDirectCount = await exactDirect.count();
-    for (let i = 0; i < exactDirectCount; i++) {
-        const candidate = exactDirect.nth(i);
-        const isFileInput = await candidate.evaluate(el => el instanceof HTMLInputElement && el.type === 'file').catch(() => false);
-        if (isFileInput)
-            return candidate;
-    }
-    if (!exact) {
-        const direct = frame.getByLabel(fieldLabel, { exact: false });
-        const directCount = await direct.count();
-        for (let i = 0; i < directCount; i++) {
-            const candidate = direct.nth(i);
-            const isFileInput = await candidate.evaluate(el => el instanceof HTMLInputElement && el.type === 'file').catch(() => false);
-            if (isFileInput)
-                return candidate;
+async function fileInputLabel(locator) {
+    return await locator.evaluate((el) => {
+        function rootScopedElementById(owner, id) {
+            const root = owner.getRootNode();
+            if (root instanceof ShadowRoot)
+                return root.getElementById(id);
+            if (root instanceof Document)
+                return root.getElementById(id);
+            return null;
         }
-    }
-    const loc = frame.locator('input[type="file"]');
-    const count = await loc.count();
-    if (count === 0)
-        return null;
-    const bestIndex = await loc.evaluateAll((elements, payload) => {
+        function referencedText(owner, ids) {
+            if (!ids)
+                return '';
+            return ids
+                .split(/\s+/)
+                .map(id => rootScopedElementById(owner, id)?.textContent?.trim() ?? '')
+                .filter(Boolean)
+                .join(' ')
+                .trim();
+        }
+        if (!(el instanceof HTMLInputElement) || el.type !== 'file')
+            return '';
+        return el.getAttribute('aria-label')?.trim() ||
+            referencedText(el, el.getAttribute('aria-labelledby')) ||
+            Array.from(el.labels ?? []).map(label => label.textContent?.trim() ?? '').find(Boolean) ||
+            el.getAttribute('title')?.trim() ||
+            el.getAttribute('name')?.trim() ||
+            el.getAttribute('id')?.trim() ||
+            '';
+    }).catch(() => '');
+}
+async function locatorMatchesFileScope(locator, contextText, sectionText) {
+    if (!contextText && !sectionText)
+        return true;
+    return await locator.evaluate((el, payload) => {
         function normalize(value) {
-            return value.replace(/\s+/g, ' ').trim().toLowerCase();
+            return (value ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
         }
-        function matches(candidate) {
-            if (!candidate)
-                return false;
-            const normalizedCandidate = normalize(candidate);
-            const normalizedExpected = normalize(payload.fieldLabel);
-            if (!normalizedCandidate || !normalizedExpected)
-                return false;
-            return payload.exact ? normalizedCandidate === normalizedExpected : normalizedCandidate.includes(normalizedExpected);
+        function rootScopedElementById(owner, id) {
+            const root = owner.getRootNode();
+            if (root instanceof ShadowRoot)
+                return root.getElementById(id);
+            if (root instanceof Document)
+                return root.getElementById(id);
+            return null;
         }
-        function referencedText(ids, visited) {
+        function referencedText(owner, ids) {
             if (!ids)
-                return undefined;
-            const seen = visited ?? new Set();
-            const text = ids
+                return '';
+            return ids
                 .split(/\s+/)
-                .map(id => {
-                if (seen.has(id))
-                    return '';
-                seen.add(id);
-                const target = document.getElementById(id);
-                if (!target)
-                    return '';
-                const chained = target.getAttribute('aria-labelledby');
-                if (chained)
-                    return referencedText(chained, seen) ?? '';
-                return target.textContent?.trim() ?? '';
-            })
+                .map(id => rootScopedElementById(owner, id)?.textContent?.trim() ?? '')
                 .filter(Boolean)
                 .join(' ')
                 .trim();
-            return text || undefined;
         }
-        function explicitLabelText(el) {
-            const aria = el.getAttribute('aria-label')?.trim();
-            if (aria)
-                return aria;
-            const labelledBy = referencedText(el.getAttribute('aria-labelledby'));
-            if (labelledBy)
-                return labelledBy;
-            if (el instanceof HTMLInputElement && el.labels && el.labels.length > 0) {
-                return el.labels[0]?.textContent?.trim() || undefined;
-            }
-            if (el instanceof HTMLElement && el.id) {
-                const label = document.querySelector(`label[for="${CSS.escape(el.id)}"]`);
-                const text = label?.textContent?.trim();
-                if (text)
-                    return text;
-            }
-            if (el.parentElement?.tagName.toLowerCase() === 'label') {
-                const text = el.parentElement.textContent?.trim();
-                if (text)
-                    return text;
+        function labelText(input) {
+            if (!(input instanceof HTMLInputElement))
+                return '';
+            return input.getAttribute('aria-label')?.trim() ||
+                referencedText(input, input.getAttribute('aria-labelledby')) ||
+                Array.from(input.labels ?? []).map(label => label.textContent?.trim() ?? '').find(Boolean) ||
+                input.getAttribute('title')?.trim() ||
+                input.getAttribute('name')?.trim() ||
+                input.getAttribute('id')?.trim() ||
+                '';
+        }
+        const contextNeedle = normalize(payload.contextText);
+        const sectionNeedle = normalize(payload.sectionText);
+        if (contextNeedle) {
+            const normalizedLabel = normalize(labelText(el));
+            let nearestContext = '';
+            let current = el.parentElement;
+            for (let depth = 0; current && depth < 7; depth++, current = current.parentElement) {
+                if (current === document.body || current === document.documentElement)
+                    break;
+                if (current instanceof HTMLFormElement)
+                    break;
+                const text = current.innerText.replace(/\s+/g, ' ').trim();
+                if (text && normalize(text) !== normalizedLabel) {
+                    nearestContext = text;
+                    break;
+                }
+                if (current.matches('fieldset, section, [role="group"], [role="region"]'))
+                    break;
             }
-            const title = el.getAttribute('title')?.trim();
-            if (title)
-                return title;
-            return undefined;
+            if (!normalize(nearestContext).includes(contextNeedle))
+                return false;
         }
-        for (let i = 0; i < elements.length; i++) {
-            const el = elements[i];
-            if (!(el instanceof HTMLInputElement) || el.type !== 'file')
-                continue;
-            if (matches(explicitLabelText(el)))
-                return i;
+        if (sectionNeedle) {
+            const section = el.closest('fieldset, section, form, dialog, [role="group"], [role="region"], [role="dialog"]');
+            if (!section)
+                return false;
+            const explicit = section.getAttribute('aria-label')?.trim() ||
+                referencedText(section, section.getAttribute('aria-labelledby')) ||
+                section.querySelector('legend, h1, h2, h3, h4, h5, h6')?.textContent?.trim() ||
+                (section instanceof HTMLElement ? section.innerText : section.textContent || '');
+            if (!normalize(explicit).includes(sectionNeedle))
+                return false;
         }
-        return -1;
-    }, { fieldLabel, exact });
-    return bestIndex >= 0 ? loc.nth(bestIndex) : null;
+        return true;
+    }, { contextText: contextText ?? '', sectionText: sectionText ?? '' }).catch(() => false);
 }
-async function findLabeledFileInputInPage(page, fieldLabel, exact, cache, fieldId) {
-    const cached = readCachedLocator(cache, 'file', fieldLabel, exact, fieldId);
-    if (cached !== undefined)
-        return cached;
+async function findScopedFileInputsInPage(page, fieldLabel, exact, contextText, sectionText) {
+    const exactMatches = [];
+    const fuzzyMatches = [];
+    const expected = normalizedOptionLabel(fieldLabel);
     for (const frame of page.frames()) {
-        const locator = await findLabeledFileInput(frame, fieldLabel, exact);
-        if (!locator)
-            continue;
-        writeCachedLocator(cache, 'file', fieldLabel, exact, fieldId, locator);
-        return locator;
-    }
-    writeCachedLocator(cache, 'file', fieldLabel, exact, fieldId, null);
-    return null;
+        const inputs = frame.locator('input[type="file"]');
+        const count = await inputs.count();
+        for (let index = 0; index < count; index++) {
+            const candidate = inputs.nth(index);
+            if (!(await locatorMatchesFileScope(candidate, contextText, sectionText)))
+                continue;
+            const label = normalizedOptionLabel(await fileInputLabel(candidate));
+            if (expected) {
+                if (label === expected)
+                    exactMatches.push(candidate);
+                else if (!exact && label.includes(expected))
+                    fuzzyMatches.push(candidate);
+            }
+            else {
+                fuzzyMatches.push(candidate);
+            }
+        }
+    }
+    return exactMatches.length > 0 ? exactMatches : fuzzyMatches;
 }
-async function attachHiddenInAllFrames(page, paths, opts) {
-    if (opts?.fieldLabel) {
-        const labeled = await findLabeledFileInputInPage(page, opts.fieldLabel, opts.exact ?? false, opts.cache, opts.fieldId);
-        if (labeled) {
-            try {
-                await labeled.setInputFiles(paths);
-                return true;
+async function findLabeledFileInputInPage(page, fieldLabel, exact, cache, fieldId, fieldKey, contextText, sectionText) {
+    const scoped = Boolean(contextText || sectionText);
+    const cached = scoped ? undefined : await readCachedLocator(cache, 'file', fieldLabel, exact, fieldId, fieldKey);
+    if (cached !== undefined) {
+        if (cached && fieldKey && fieldLabel) {
+            const resolvedLabel = normalizedOptionLabel(await fileInputLabel(cached));
+            const expectedLabel = normalizedOptionLabel(fieldLabel);
+            const matches = exact
+                ? resolvedLabel === expectedLabel
+                : resolvedLabel === expectedLabel || resolvedLabel.includes(expectedLabel);
+            if (!matches)
+                throw new Error(`file: fieldKey "${fieldKey}" did not match field label "${fieldLabel}"`);
+        }
+        return cached;
+    }
+    if (fieldKey) {
+        const authored = await findAuthoredFieldByKeyInPage(page, fieldKey, 'file');
+        if (authored) {
+            if (fieldLabel) {
+                const resolvedLabel = normalizedOptionLabel(await fileInputLabel(authored));
+                const expectedLabel = normalizedOptionLabel(fieldLabel);
+                const labelMatches = exact
+                    ? resolvedLabel === expectedLabel
+                    : resolvedLabel === expectedLabel || resolvedLabel.includes(expectedLabel);
+                if (!labelMatches) {
+                    throw new Error(`file: fieldKey "${fieldKey}" did not match field label "${fieldLabel}"`);
+                }
             }
-            catch {
-                /* fall through to uncached scan */
+            if (!(await locatorMatchesFileScope(authored, contextText, sectionText))) {
+                throw new Error(`file: fieldKey "${fieldKey}" did not match the requested context/section`);
             }
+            if (!scoped)
+                writeCachedLocator(cache, 'file', fieldLabel, exact, fieldId, fieldKey, authored);
+            return authored;
         }
+        throw new Error(`fieldKey "${fieldKey}" did not resolve to a file input; refresh geometra_form_schema`);
     }
-    for (const frame of page.frames()) {
-        if (opts?.fieldLabel) {
-            const labeled = await findLabeledFileInput(frame, opts.fieldLabel, opts.exact ?? false);
-            if (!labeled)
-                continue;
+    if (scoped) {
+        const matches = await findScopedFileInputsInPage(page, fieldLabel, exact, contextText, sectionText);
+        if (matches.length > 1) {
+            throw new Error(`file: ambiguous scoped match for field "${fieldLabel || '<unlabeled>'}"; matched ${matches.length} file inputs`);
+        }
+        return matches[0] ?? null;
+    }
+    if (fieldLabel) {
+        const matches = await findScopedFileInputsInPage(page, fieldLabel, exact);
+        if (matches.length > 1) {
+            throw new Error(`file: ambiguous label "${fieldLabel}" matched ${matches.length} file inputs; provide fieldKey, contextText, or sectionText`);
+        }
+        const locator = matches[0];
+        if (locator) {
+            writeCachedLocator(cache, 'file', fieldLabel, exact, fieldId, undefined, locator);
+            return locator;
+        }
+    }
+    writeCachedLocator(cache, 'file', fieldLabel, exact, fieldId, undefined, null);
+    return null;
+}
+function expectedUploadNames(paths) {
+    return paths.map(path => path.split(/[/\\\\]/).pop() ?? path);
+}
+function uploadedNamesMatch(actual, expected) {
+    return actual.length === expected.length && actual.every((name, index) => name === expected[index]);
+}
+class FileAcceptValidationError extends Error {
+}
+class FileUploadOutcomeAmbiguousError extends Error {
+    constructor(reason, cleanupOutcome) {
+        super(`file: upload outcome is ambiguous (${reason}); ${cleanupOutcome}. ` +
+            'Do not retry this upload automatically; inspect the current field first.');
+        this.name = 'FileUploadOutcomeAmbiguousError';
+    }
+}
+/** Parse only definite HTML file accept contracts; malformed tokens are inert. */
+function parseFileAcceptSpecifiers(rawAccept) {
+    if (!rawAccept)
+        return [];
+    const specifiers = [];
+    for (const rawToken of rawAccept.split(',')) {
+        const token = rawToken.trim().toLowerCase();
+        if (!token)
+            continue;
+        if (/^\.[a-z0-9][a-z0-9._+-]*$/i.test(token)) {
+            specifiers.push({ kind: 'extension', value: token });
+            continue;
+        }
+        const mimeParts = token.split('/');
+        const mimeToken = /^[a-z0-9!#$%&'*+.^_`|~-]+$/i;
+        if (mimeParts.length !== 2 ||
+            !mimeToken.test(mimeParts[0] ?? '') ||
+            (mimeParts[1] !== '*' && (!mimeToken.test(mimeParts[1] ?? '') || mimeParts[1].includes('*'))))
+            continue;
+        if (mimeParts[1] === '*') {
+            specifiers.push({ kind: 'mime-wildcard', value: `${mimeParts[0]}/` });
+        }
+        else {
+            specifiers.push({ kind: 'mime', value: token });
+        }
+    }
+    return specifiers;
+}
+function pathMatchesFileAccept(path, specifiers) {
+    const fileName = path.split(/[/\\]/).pop()?.toLowerCase() ?? path.toLowerCase();
+    if (specifiers.some(specifier => specifier.kind === 'extension' && fileName.endsWith(specifier.value)))
+        return true;
+    const mimeSpecifiers = specifiers.filter(specifier => specifier.kind !== 'extension');
+    const mime = mimeTypeForPath(path);
+    if (!mime)
+        return mimeSpecifiers.length > 0 ? 'unknown-mime' : false;
+    return mimeSpecifiers.some(specifier => specifier.kind === 'mime-wildcard'
+        ? mime.startsWith(specifier.value)
+        : mime === specifier.value);
+}
+function assertPathsMatchFileAccept(paths, rawAccept) {
+    const specifiers = parseFileAcceptSpecifiers(rawAccept);
+    // Invalid-only accept strings do not establish a definite file contract.
+    if (specifiers.length === 0)
+        return;
+    const unknownMime = paths.filter(path => pathMatchesFileAccept(path, specifiers) === 'unknown-mime');
+    if (unknownMime.length > 0) {
+        const names = unknownMime.map(path => path.split(/[/\\]/).pop() ?? path);
+        throw new FileAcceptValidationError(`file: cannot safely infer MIME type for ${names.map(name => `"${name}"`).join(', ')} ` +
+            `to validate input accept="${rawAccept ?? ''}"; no files were attached`);
+    }
+    const mismatches = paths.filter(path => pathMatchesFileAccept(path, specifiers) === false);
+    if (mismatches.length === 0)
+        return;
+    const names = mismatches.map(path => path.split(/[/\\]/).pop() ?? path);
+    throw new FileAcceptValidationError(`file: supplied file${names.length === 1 ? '' : 's'} ${names.map(name => `"${name}"`).join(', ')} ` +
+        `did not match input accept="${rawAccept ?? ''}"; no files were attached`);
+}
+async function handleFileAccept(handle) {
+    return await handle.evaluate(el => el instanceof HTMLInputElement && el.type === 'file'
+        ? el.getAttribute('accept')
+        : null);
+}
+/**
+ * Playwright owns local-path transfer, so there is no practical atomic
+ * in-page check+commit that works for arbitrarily large files without first
+ * buffering and serializing their full contents. Keep the exact ElementHandle
+ * instead and guard the short protocol-call window. Any relevant mutation in
+ * that window makes the result explicitly ambiguous, even if the page toggles
+ * the attribute back before our post-commit read.
+ */
+async function beginFileInputCommitGuard(handle) {
+    const guard = await handle.evaluateHandle((element) => {
+        function composedParent(node) {
+            if (node.parentElement)
+                return node.parentElement;
+            const root = node.getRootNode();
+            return root instanceof ShadowRoot ? root.host : null;
+        }
+        function composedContains(ancestor, descendant) {
+            let current = descendant;
+            while (current) {
+                if (current === ancestor)
+                    return true;
+                current = composedParent(current);
+            }
+            return false;
+        }
+        function mutationBlockReason(target) {
             try {
-                await labeled.setInputFiles(paths);
-                return true;
+                if (target.matches(':disabled'))
+                    return 'disabled';
+            }
+            catch { /* non-HTML namespaces may reject pseudo classes */ }
+            if ((target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) &&
+                target.readOnly)
+                return 'readonly';
+            let current = target;
+            while (current) {
+                if (current.hasAttribute('inert'))
+                    return 'inert';
+                if (current.getAttribute('aria-disabled')?.trim().toLowerCase() === 'true')
+                    return 'aria-disabled';
+                if (current.getAttribute('aria-readonly')?.trim().toLowerCase() === 'true')
+                    return 'aria-readonly';
+                if (current instanceof HTMLFieldSetElement && current.disabled) {
+                    const firstLegend = Array.from(current.children).find(child => child instanceof HTMLLegendElement);
+                    if (!(firstLegend instanceof HTMLLegendElement) || !composedContains(firstLegend, target)) {
+                        return 'disabled fieldset';
+                    }
+                }
+                current = composedParent(current);
             }
-            catch {
-                /* try next frame */
+            return null;
+        }
+        const input = element instanceof HTMLInputElement && element.type === 'file' ? element : null;
+        const guardedAncestors = new Set();
+        let current = input;
+        while (current) {
+            guardedAncestors.add(current);
+            current = composedParent(current);
+        }
+        const initial = {
+            validFileInput: Boolean(input?.isConnected),
+            blockReason: input ? mutationBlockReason(input) : 'detached or no longer a file input',
+            accept: input?.getAttribute('accept') ?? null,
+            names: input ? Array.from(input.files ?? []).map(file => file.name) : [],
+        };
+        const state = {
+            input,
+            initial,
+            invalidReason: null,
+            observer: null,
+            record: () => { },
+            finalize: () => ({ invalidReason: 'commit guard was not initialized', names: [] }),
+        };
+        function markInvalid(reason) {
+            state.invalidReason ??= reason;
+        }
+        function removedGuardedTarget(node) {
+            if (!(node instanceof Element))
+                return false;
+            for (const ancestor of guardedAncestors) {
+                if (node === ancestor || node.contains(ancestor))
+                    return true;
             }
-            continue;
+            return false;
+        }
+        state.record = (records) => {
+            for (const record of records) {
+                if (record.type === 'childList' && Array.from(record.removedNodes).some(removedGuardedTarget)) {
+                    markInvalid('the exact target identity changed during commit');
+                    continue;
+                }
+                if (record.type !== 'attributes' || !(record.target instanceof Element))
+                    continue;
+                if (!guardedAncestors.has(record.target))
+                    continue;
+                const attribute = record.attributeName ?? 'state';
+                if (attribute === 'accept')
+                    markInvalid('the target accept contract changed during commit');
+                else if (attribute === 'type')
+                    markInvalid('the exact target stopped being a file input during commit');
+                else
+                    markInvalid(`the target mutability changed during commit (${attribute})`);
+            }
+        };
+        const observer = new MutationObserver(records => state.record(records));
+        state.observer = observer;
+        const roots = new Set();
+        for (const ancestor of guardedAncestors)
+            roots.add(ancestor.getRootNode());
+        for (const root of roots) {
+            observer.observe(root, {
+                subtree: true,
+                childList: true,
+                attributes: true,
+                attributeOldValue: true,
+                attributeFilter: ['accept', 'type', 'disabled', 'readonly', 'inert', 'aria-disabled', 'aria-readonly'],
+            });
+        }
+        state.finalize = () => {
+            state.record(observer.takeRecords());
+            observer.disconnect();
+            if (!input?.isConnected)
+                markInvalid('the exact target detached during commit');
+            else if (input.type !== 'file')
+                markInvalid('the exact target is no longer a file input');
+            else if (input.getAttribute('accept') !== initial.accept)
+                markInvalid('the target accept contract changed during commit');
+            else {
+                const blocked = mutationBlockReason(input);
+                if (blocked)
+                    markInvalid(`the target is not mutable after commit (${blocked})`);
+            }
+            return {
+                invalidReason: state.invalidReason,
+                names: input ? Array.from(input.files ?? []).map(file => file.name) : [],
+            };
+        };
+        return state;
+    });
+    const initial = await guard.evaluate(value => value.initial);
+    return { guard, initial };
+}
+async function finalizeFileInputCommitGuard(guard) {
+    return await guard.evaluate(value => value.finalize());
+}
+async function stopFileInputCommitGuard(guard) {
+    await guard.evaluate(value => {
+        value.observer.disconnect();
+    }).catch(() => { });
+}
+async function clearAmbiguousRetainedFiles(handle, actualNames, initialNames) {
+    const selectionChanged = !uploadedNamesMatch(actualNames, initialNames);
+    if (!selectionChanged) {
+        return actualNames.length === 0
+            ? 'no retained file selection remained to clear'
+            : 'the preexisting selection was preserved because a same-named replacement could not be proven';
+    }
+    if (actualNames.length === 0)
+        return 'no newly retained files remained on the target';
+    try {
+        await handle.setInputFiles([]);
+    }
+    catch {
+        await handle.evaluate((el) => {
+            if (el instanceof HTMLInputElement && el.type === 'file')
+                el.value = '';
+        }).catch(() => { });
+    }
+    return 'the changed selection was cleared best-effort without trying another candidate';
+}
+async function commitFilesToExactInput(handle, paths, targetName) {
+    const { guard, initial } = await beginFileInputCommitGuard(handle);
+    try {
+        if (!initial.validFileInput) {
+            await stopFileInputCommitGuard(guard);
+            throw new Error(`file: ${targetName} detached or is no longer a file input`);
+        }
+        if (initial.blockReason) {
+            await stopFileInputCommitGuard(guard);
+            throw new Error(`file: ${targetName} is not mutable (${initial.blockReason})`);
+        }
+        try {
+            assertPathsMatchFileAccept(paths, initial.accept);
+        }
+        catch (error) {
+            await stopFileInputCommitGuard(guard);
+            throw error;
+        }
+        let operationError;
+        try {
+            await handle.setInputFiles(paths);
         }
+        catch (error) {
+            operationError = error;
+        }
+        // Give synchronous handlers, their microtasks, and one timer turn a chance
+        // to reject/clear the selection before calling the outcome confirmed.
+        await delay(40);
+        const final = await finalizeFileInputCommitGuard(guard).catch(() => ({
+            invalidReason: 'the exact target could not be inspected after commit',
+            names: [],
+        }));
+        const retained = uploadedNamesMatch(final.names, expectedUploadNames(paths));
+        if (!operationError && !final.invalidReason && retained)
+            return;
+        const cleanupOutcome = await clearAmbiguousRetainedFiles(handle, final.names, initial.names);
+        const operationReason = operationError instanceof Error
+            ? `Playwright could not confirm the exact-target commit: ${operationError.message}`
+            : operationError
+                ? 'Playwright could not confirm the exact-target commit'
+                : null;
+        const reason = final.invalidReason ?? operationReason ?? 'the exact target did not retain the supplied filenames';
+        throw new FileUploadOutcomeAmbiguousError(reason, cleanupOutcome);
+    }
+    finally {
+        await guard.dispose().catch(() => { });
+    }
+}
+async function attachHiddenInAllFrames(page, paths, opts) {
+    if (opts?.fieldLabel || opts?.fieldKey || opts?.contextText || opts?.sectionText) {
+        const labeled = await findLabeledFileInputInPage(page, opts.fieldLabel ?? '', opts.exact ?? false, opts.cache, opts.fieldId, opts.fieldKey, opts.contextText, opts.sectionText);
+        if (labeled) {
+            const handle = await labeled.elementHandle();
+            if (!handle)
+                throw new Error('file: matched input detached before upload');
+            await commitFilesToExactInput(handle, paths, 'matched input');
+            return true;
+        }
+        return false;
+    }
+    let acceptError;
+    for (const frame of page.frames()) {
         const loc = frame.locator('input[type="file"]');
         const n = await loc.count();
         for (let i = 0; i < n; i++) {
+            if (await locatorMutationBlockReason(loc.nth(i), 'file'))
+                continue;
+            const handle = await loc.nth(i).elementHandle();
+            if (!handle)
+                continue;
             try {
-                await loc.nth(i).setInputFiles(paths);
+                await commitFilesToExactInput(handle, paths, 'matched input');
                 return true;
             }
-            catch {
-                /* try next */
+            catch (error) {
+                if (error instanceof FileAcceptValidationError) {
+                    acceptError ??= error;
+                    continue;
+                }
+                throw error;
             }
         }
     }
+    if (acceptError)
+        throw acceptError;
     return false;
 }
 async function attachViaChooser(page, paths, clickX, clickY) {
+    await assertPointMutable(page, clickX, clickY, 'file', 'file');
     const [chooser] = await Promise.all([
         page.waitForEvent('filechooser', { timeout: 12_000 }),
         page.mouse.click(clickX, clickY),
     ]);
-    await chooser.setFiles(paths);
+    const input = chooser.element();
+    await commitFilesToExactInput(input, paths, 'chooser input');
 }
 /**
  * Map common file extensions to MIME types so react-dropzone's `accept` filter
- * does not silently drop our synthetic files. Defaults to application/octet-stream
- * for unknowns, which is rejected by most dropzones configured with accept.
+ * does not silently drop our synthetic files. A null result means MIME cannot
+ * be inferred reliably from the path and must not be used to reject a MIME
+ * accept contract as though application/octet-stream were authoritative.
  */
 function mimeTypeForPath(path) {
     const ext = path.toLowerCase().split('.').pop() ?? '';
@@ -2802,7 +3440,20 @@ function mimeTypeForPath(path) {
         case 'pdf': return 'application/pdf';
         case 'doc': return 'application/msword';
         case 'docx': return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+        case 'xls': return 'application/vnd.ms-excel';
+        case 'xlsx': return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+        case 'ppt': return 'application/vnd.ms-powerpoint';
+        case 'pptx': return 'application/vnd.openxmlformats-officedocument.presentationml.presentation';
+        case 'json': return 'application/json';
+        case 'xml': return 'application/xml';
+        case 'zip': return 'application/zip';
+        case 'gz': return 'application/gzip';
+        case 'tar': return 'application/x-tar';
+        case '7z': return 'application/x-7z-compressed';
         case 'txt': return 'text/plain';
+        case 'csv': return 'text/csv';
+        case 'htm':
+        case 'html': return 'text/html';
         case 'rtf': return 'application/rtf';
         case 'png': return 'image/png';
         case 'jpg':
@@ -2810,9 +3461,76 @@ function mimeTypeForPath(path) {
         case 'gif': return 'image/gif';
         case 'webp': return 'image/webp';
         case 'svg': return 'image/svg+xml';
-        default: return 'application/octet-stream';
+        case 'avif': return 'image/avif';
+        case 'bmp': return 'image/bmp';
+        case 'tif':
+        case 'tiff': return 'image/tiff';
+        case 'mp3': return 'audio/mpeg';
+        case 'm4a': return 'audio/mp4';
+        case 'wav': return 'audio/wav';
+        case 'ogg': return 'audio/ogg';
+        case 'mp4': return 'video/mp4';
+        case 'mov': return 'video/quicktime';
+        case 'webm': return 'video/webm';
+        default: return null;
     }
 }
+async function dropFileInputAtPoint(page, x, y) {
+    const handle = await page.mainFrame().evaluateHandle(({ x: clientX, y: clientY }) => {
+        const deepest = document.elementFromPoint(clientX, clientY);
+        if (!deepest)
+            return null;
+        function composedParent(element) {
+            if (element.parentElement)
+                return element.parentElement;
+            const root = element.getRootNode();
+            return root instanceof ShadowRoot ? root.host : null;
+        }
+        function isExplicitLocalBoundary(element) {
+            const tag = element.tagName.toLowerCase();
+            const className = typeof element.className === 'string' ? element.className : '';
+            const testId = element.getAttribute('data-testid') ?? '';
+            const buttonText = `${element.getAttribute('aria-label') ?? ''} ${element.textContent ?? ''}`;
+            return tag === 'label' ||
+                element.hasAttribute('data-dropzone') ||
+                element.getAttributeNames().some(attribute => attribute.startsWith('data-rfd')) ||
+                /drop[-_]?zone|file[-_]?upload|attach|upload/i.test(className) ||
+                /drop|file|upload|attach/i.test(testId) ||
+                (element.getAttribute('role') === 'button' && /drop|file|upload|attach/i.test(buttonText));
+        }
+        function isBroadContainer(element) {
+            return element.matches('form, [role="form"], fieldset, section');
+        }
+        let current = deepest;
+        let associationClosed = false;
+        for (let depth = 0; current && depth < 16; depth++, current = composedParent(current)) {
+            if (current instanceof HTMLInputElement && current.type === 'file')
+                return current;
+            // Do not infer a relationship from an unrelated page-global input.
+            if (current === document.body || current === document.documentElement)
+                break;
+            const inputs = current.querySelectorAll('input[type="file"]');
+            if (inputs.length > 1) {
+                throw new Error(`file: coordinate-only drop target is ambiguous; nearest candidate container has ${inputs.length} file inputs`);
+            }
+            const input = inputs[0];
+            const explicitBoundary = isExplicitLocalBoundary(current);
+            const broadContainer = isBroadContainer(current);
+            if (input instanceof HTMLInputElement &&
+                !associationClosed &&
+                explicitBoundary)
+                return input;
+            if (explicitBoundary || broadContainer)
+                associationClosed = true;
+        }
+        return null;
+    }, { x, y });
+    const element = handle.asElement();
+    if (element)
+        return element;
+    await handle.dispose();
+    return null;
+}
 /**
  * Synthetic drop at (x,y) using file bytes from the proxy host.
  *
@@ -2830,91 +3548,260 @@ function mimeTypeForPath(path) {
  * button layer and the wrapper that actually has the listeners.
  */
 async function attachViaDropPlaywright(page, paths, dropX, dropY) {
-    const fs = await import('node:fs/promises');
-    const buffers = await Promise.all(paths.map(p => fs.readFile(p)));
-    const names = paths.map(p => p.split(/[/\\\\]/).pop() ?? 'file');
-    const mimes = paths.map(mimeTypeForPath);
-    await page.mouse.move(dropX, dropY);
-    await page.mainFrame().evaluate(({ bufs, ns, ms, x, y }) => {
-        const makeDataTransfer = () => {
-            const dt = new DataTransfer();
-            for (let i = 0; i < bufs.length; i++) {
-                const u8 = new Uint8Array(bufs[i]);
-                const blob = new Blob([u8], { type: ms[i] });
-                dt.items.add(new File([blob], ns[i], { type: ms[i] }));
-            }
-            return dt;
-        };
-        const dispatchSequence = (target) => {
-            // Each event needs its own DataTransfer because some frameworks
-            // consume the items list during dragenter/dragover inspection.
-            for (const type of ['dragenter', 'dragover', 'drop']) {
-                const dt = makeDataTransfer();
-                const ev = new DragEvent(type, {
-                    bubbles: true,
-                    cancelable: true,
-                    composed: true,
-                    clientX: x,
-                    clientY: y,
-                    dataTransfer: dt,
-                });
-                // Some browsers/frameworks freeze the dataTransfer getter; re-define
-                // it defensively so listeners read the files.
+    const dropFileInput = await dropFileInputAtPoint(page, dropX, dropY);
+    try {
+        // A real scoped input establishes the drop contract. Validate before
+        // mouse movement, drag events, input assignment, or application callbacks.
+        // Pure dropzones without an input retain their framework-defined behavior.
+        const observedAccept = dropFileInput ? await handleFileAccept(dropFileInput) : null;
+        if (dropFileInput) {
+            const inputBlockReason = await dropFileInput.evaluate(mutationBlockReasonInPage, 'file');
+            if (inputBlockReason) {
+                throw new Error(`file: associated drop input is not mutable (${inputBlockReason})`);
+            }
+        }
+        assertPathsMatchFileAccept(paths, observedAccept);
+        const fs = await import('node:fs/promises');
+        const buffers = await Promise.all(paths.map(p => fs.readFile(p)));
+        const names = paths.map(p => p.split(/[/\\\\]/).pop() ?? 'file');
+        const mimes = paths.map(path => mimeTypeForPath(path) ?? 'application/octet-stream');
+        await page.mouse.move(dropX, dropY);
+        const result = await page.mainFrame().evaluate(async ({ bufs, ns, ms, x, y, expectedAccept, expectedFileInput }) => {
+            function blockReason(target) {
+                function parent(node) {
+                    if (node.parentElement)
+                        return node.parentElement;
+                    const root = node.getRootNode();
+                    return root instanceof ShadowRoot ? root.host : null;
+                }
+                function within(node, ancestor) {
+                    let current = node;
+                    while (current) {
+                        if (current === ancestor)
+                            return true;
+                        current = parent(current);
+                    }
+                    return false;
+                }
                 try {
-                    Object.defineProperty(ev, 'dataTransfer', { value: dt, configurable: true });
+                    if (target.matches(':disabled'))
+                        return 'disabled';
                 }
                 catch { /* ignore */ }
-                target.dispatchEvent(ev);
-            }
-        };
-        const deepest = document.elementFromPoint(x, y);
-        const targets = [];
-        if (deepest)
-            targets.push(deepest);
-        // Walk up a few ancestors looking for anything that looks like a dropzone
-        // root (react-dropzone emits `data-rfd-*`; Greenhouse uses div.drop-zone;
-        // Ashby uses role="button" wrappers). We dispatch on the first dropzone-ish
-        // ancestor AND the deepest element, because we cannot tell statically
-        // which one has the real listener.
-        let p = deepest?.parentElement ?? null;
-        for (let depth = 0; depth < 12 && p; depth++) {
-            const tag = p.tagName.toLowerCase();
-            const attrs = p.getAttributeNames();
-            const looksLikeDropzone = attrs.some(a => a.startsWith('data-rfd') || a === 'data-dropzone' || a === 'data-testid') ||
-                (p.className && typeof p.className === 'string' && /drop[-_]?zone|file[-_]?upload|attach|upload/i.test(p.className)) ||
-                tag === 'label' ||
-                p.getAttribute('role') === 'button';
-            if (looksLikeDropzone && !targets.includes(p))
-                targets.push(p);
-            p = p.parentElement;
-        }
-        if (targets.length === 0)
-            targets.push(document.body);
-        for (const t of targets)
-            dispatchSequence(t);
-        // As a final fallback, if there is a hidden input[type=file] scoped to
-        // the nearest form/section, set its `files` via DataTransfer and dispatch
-        // the React-friendly native input value setter so react-hook-form notices.
-        const host = deepest?.closest('form, [role="form"], fieldset, section, div') ?? document.body;
-        const fileInput = host.querySelector('input[type="file"]');
-        if (fileInput) {
-            const dt = makeDataTransfer();
-            try {
-                Object.defineProperty(fileInput, 'files', { value: dt.files, configurable: true });
+                if ((target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) && target.readOnly)
+                    return 'readonly';
+                let current = target;
+                while (current) {
+                    if (current.hasAttribute('inert'))
+                        return 'inert';
+                    if (current.getAttribute('aria-disabled')?.trim().toLowerCase() === 'true')
+                        return 'aria-disabled';
+                    if (current.getAttribute('aria-readonly')?.trim().toLowerCase() === 'true')
+                        return 'aria-readonly';
+                    if (current instanceof HTMLFieldSetElement && current.disabled) {
+                        const legend = Array.from(current.children).find(child => child instanceof HTMLLegendElement);
+                        if (!(legend instanceof HTMLLegendElement) || !within(target, legend))
+                            return 'disabled fieldset';
+                    }
+                    current = parent(current);
+                }
+                return null;
             }
-            catch { /* ignore */ }
-            try {
-                // React overrides the input value setter; we need the native prototype
-                // setter so React sees the change.
-                const proto = Object.getPrototypeOf(fileInput);
-                const descriptor = Object.getOwnPropertyDescriptor(proto, 'value');
-                descriptor?.set?.call(fileInput, '');
+            const makeDataTransfer = () => {
+                const dt = new DataTransfer();
+                for (let i = 0; i < bufs.length; i++) {
+                    const u8 = new Uint8Array(bufs[i]);
+                    const blob = new Blob([u8], { type: ms[i] });
+                    dt.items.add(new File([blob], ns[i], { type: ms[i] }));
+                }
+                return dt;
+            };
+            const dispatchSequence = (target) => {
+                let handled = false;
+                // Each event needs its own DataTransfer because some frameworks
+                // consume the items list during dragenter/dragover inspection.
+                for (const type of ['dragenter', 'dragover', 'drop']) {
+                    const dt = makeDataTransfer();
+                    const ev = new DragEvent(type, {
+                        bubbles: true,
+                        cancelable: true,
+                        composed: true,
+                        clientX: x,
+                        clientY: y,
+                        dataTransfer: dt,
+                    });
+                    try {
+                        Object.defineProperty(ev, 'dataTransfer', { value: dt, configurable: true });
+                    }
+                    catch { /* ignore */ }
+                    const dispatched = target.dispatchEvent(ev);
+                    if (!dispatched || ev.defaultPrevented)
+                        handled = true;
+                }
+                return handled;
+            };
+            const deepest = document.elementFromPoint(x, y);
+            if (!deepest) {
+                return { accepted: false, blockReason: null, acceptContractChanged: false, ambiguousTarget: false };
+            }
+            const blocked = blockReason(deepest);
+            if (blocked) {
+                return { accepted: false, blockReason: blocked, acceptContractChanged: false, ambiguousTarget: false };
+            }
+            function resolveFileInput(start) {
+                function composedParent(element) {
+                    if (element.parentElement)
+                        return element.parentElement;
+                    const root = element.getRootNode();
+                    return root instanceof ShadowRoot ? root.host : null;
+                }
+                function isExplicitLocalBoundary(element) {
+                    const tag = element.tagName.toLowerCase();
+                    const className = typeof element.className === 'string' ? element.className : '';
+                    const testId = element.getAttribute('data-testid') ?? '';
+                    const buttonText = `${element.getAttribute('aria-label') ?? ''} ${element.textContent ?? ''}`;
+                    return tag === 'label' ||
+                        element.hasAttribute('data-dropzone') ||
+                        element.getAttributeNames().some(attribute => attribute.startsWith('data-rfd')) ||
+                        /drop[-_]?zone|file[-_]?upload|attach|upload/i.test(className) ||
+                        /drop|file|upload|attach/i.test(testId) ||
+                        (element.getAttribute('role') === 'button' && /drop|file|upload|attach/i.test(buttonText));
+                }
+                function isBroadContainer(element) {
+                    return element.matches('form, [role="form"], fieldset, section');
+                }
+                let current = start;
+                let associationClosed = false;
+                for (let depth = 0; current && depth < 16; depth++, current = composedParent(current)) {
+                    if (current instanceof HTMLInputElement && current.type === 'file') {
+                        return { input: current, host: current, ambiguous: false };
+                    }
+                    if (current === document.body || current === document.documentElement)
+                        break;
+                    const inputs = current.querySelectorAll('input[type="file"]');
+                    if (inputs.length > 1)
+                        return { input: null, host: current, ambiguous: true };
+                    const input = inputs[0];
+                    const explicitBoundary = isExplicitLocalBoundary(current);
+                    const broadContainer = isBroadContainer(current);
+                    if (input instanceof HTMLInputElement &&
+                        !associationClosed &&
+                        explicitBoundary)
+                        return { input, host: current, ambiguous: false };
+                    if (explicitBoundary || broadContainer)
+                        associationClosed = true;
+                }
+                return {
+                    input: null,
+                    host: start.closest('form, [role="form"], fieldset, section, div') ?? document.body,
+                    ambiguous: false,
+                };
+            }
+            const targets = [deepest];
+            let p = deepest.parentElement;
+            for (let depth = 0; depth < 12 && p; depth++) {
+                const tag = p.tagName.toLowerCase();
+                const attrs = p.getAttributeNames();
+                const looksLikeDropzone = attrs.some(a => a.startsWith('data-rfd') || a === 'data-dropzone' || a === 'data-testid') ||
+                    (p.className && typeof p.className === 'string' && /drop[-_]?zone|file[-_]?upload|attach|upload/i.test(p.className)) ||
+                    tag === 'label' ||
+                    p.getAttribute('role') === 'button';
+                if (looksLikeDropzone && !targets.includes(p))
+                    targets.push(p);
+                p = p.parentElement;
+            }
+            const resolvedTarget = resolveFileInput(deepest);
+            if (resolvedTarget.ambiguous) {
+                return { accepted: false, blockReason: null, acceptContractChanged: false, ambiguousTarget: true };
+            }
+            const host = resolvedTarget.host;
+            const fileInput = resolvedTarget.input;
+            if (fileInput !== expectedFileInput) {
+                return { accepted: false, blockReason: null, acceptContractChanged: true, ambiguousTarget: false };
+            }
+            const currentAccept = fileInput?.getAttribute('accept') ?? null;
+            if (currentAccept !== expectedAccept) {
+                return { accepted: false, blockReason: null, acceptContractChanged: true, ambiguousTarget: false };
+            }
+            if (fileInput) {
+                const inputBlockReason = blockReason(fileInput);
+                if (inputBlockReason) {
+                    throw new Error(`file: associated drop input is not mutable (${inputBlockReason})`);
+                }
             }
-            catch { /* ignore */ }
-            fileInput.dispatchEvent(new Event('input', { bubbles: true }));
-            fileInput.dispatchEvent(new Event('change', { bubbles: true }));
+            const beforeFileNames = Array.from(fileInput?.files ?? []).map(file => file.name);
+            const beforeRenderedText = [host, ...targets]
+                .map(node => node.textContent ?? '')
+                .join(' ')
+                .toLowerCase();
+            let handled = false;
+            for (const target of targets) {
+                if (!blockReason(target))
+                    handled = dispatchSequence(target) || handled;
+            }
+            // A scoped file input can provide strong acceptance evidence, but only
+            // after application handlers have had a chance to reject/clear it.
+            if (fileInput && !blockReason(fileInput)) {
+                const dt = makeDataTransfer();
+                try {
+                    Object.defineProperty(fileInput, 'files', { value: dt.files, configurable: true });
+                }
+                catch { /* ignore */ }
+                try {
+                    const proto = Object.getPrototypeOf(fileInput);
+                    const descriptor = Object.getOwnPropertyDescriptor(proto, 'value');
+                    descriptor?.set?.call(fileInput, '');
+                }
+                catch { /* ignore */ }
+                fileInput.dispatchEvent(new Event('input', { bubbles: true }));
+                fileInput.dispatchEvent(new Event('change', { bubbles: true }));
+            }
+            // Framework drop handlers commonly commit on a microtask or animation
+            // frame. Only report success after observable page state contains every
+            // submitted filename; canceling dragover alone is not acceptance.
+            await Promise.resolve();
+            await new Promise(resolveTimer => setTimeout(resolveTimer, 32));
+            const settledFileNames = Array.from(fileInput?.files ?? []).map(file => file.name);
+            const fileInputAccepted = Boolean(fileInput && !blockReason(fileInput)) &&
+                ns.every(name => settledFileNames.includes(name)) &&
+                (settledFileNames.length !== beforeFileNames.length || settledFileNames.some((name, index) => name !== beforeFileNames[index]));
+            const renderedText = [host, ...targets]
+                .map(node => node.textContent ?? '')
+                .join(' ')
+                .toLowerCase();
+            const renderedAcceptance = renderedText !== beforeRenderedText &&
+                ns.every(name => renderedText.includes(name.toLowerCase()));
+            return {
+                accepted: fileInputAccepted || (handled && renderedAcceptance),
+                blockReason: null,
+                acceptContractChanged: false,
+                ambiguousTarget: false,
+            };
+        }, {
+            bufs: buffers.map(b => Array.from(b)),
+            ns: names,
+            ms: mimes,
+            x: dropX,
+            y: dropY,
+            expectedAccept: observedAccept,
+            expectedFileInput: dropFileInput,
+        });
+        if (result.ambiguousTarget) {
+            throw new Error('file: coordinate-only drop target became ambiguous between multiple file inputs');
+        }
+        if (result.acceptContractChanged) {
+            throw new Error('file: drop target accept contract changed before upload; retry with a fresh target');
+        }
+        if (result.blockReason) {
+            throw new Error(`file: drop target is not mutable (${result.blockReason})`);
+        }
+        if (!result.accepted) {
+            throw new Error('file: drop target did not accept the supplied files');
         }
-    }, { bufs: buffers.map(b => Array.from(b)), ns: names, ms: mimes, x: dropX, y: dropY });
+    }
+    finally {
+        await dropFileInput?.dispose().catch(() => { });
+    }
 }
 /**
  * `strategy`:
@@ -2928,7 +3815,8 @@ const ATTACH_BUTTON_PATTERN = /attach|upload|add.file|choose.file|browse/i;
  * Find an Attach/Upload button near a field label (e.g. Greenhouse's "Attach" button
  * inside a "Resume/CV" section). Returns the button Locator or null.
  */
-async function findAttachButtonNearLabel(page, fieldLabel) {
+async function findAttachButtonNearLabel(page, fieldLabel, contextText, sectionText) {
+    const matches = [];
     for (const frame of page.frames()) {
         // Find all buttons/links whose text matches attach-like patterns
         const buttons = frame.locator('button, a, [role="button"]');
@@ -2952,15 +3840,18 @@ async function findAttachButtonNearLabel(page, fieldLabel) {
                     }
                     return false;
                 }, fieldLabel);
-                if (nearLabel)
-                    return btn;
+                if (nearLabel && await locatorMatchesFileScope(btn, contextText, sectionText))
+                    matches.push(btn);
             }
             catch {
                 continue;
             }
         }
     }
-    return null;
+    if (matches.length > 1) {
+        throw new Error(`file: ambiguous Attach/Upload control for field "${fieldLabel}"; provide a more specific contextText or sectionText`);
+    }
+    return matches[0] ?? null;
 }
 export async function attachFiles(page, paths, opts) {
     const strategy = opts?.strategy ?? 'auto';
@@ -2970,6 +3861,51 @@ export async function attachFiles(page, paths, opts) {
     const exact = opts?.exact ?? false;
     const dropX = opts?.dropX;
     const dropY = opts?.dropY;
+    const hasClickX = clickX !== undefined;
+    const hasClickY = clickY !== undefined;
+    const hasDropX = dropX !== undefined;
+    const hasDropY = dropY !== undefined;
+    const hasClick = hasClickX && hasClickY;
+    const hasDrop = hasDropX && hasDropY;
+    const hasFieldLabel = Boolean(fieldLabel?.trim());
+    const hasFieldKey = Boolean(opts?.fieldKey);
+    const hasSemanticTarget = hasFieldLabel || hasFieldKey;
+    const hasSemanticExtras = Boolean(opts?.fieldId || opts?.fieldKey || fieldLabel || opts?.contextText || opts?.sectionText || opts?.exact !== undefined);
+    if (hasClickX !== hasClickY)
+        throw new Error('file: clickX and clickY must be provided together');
+    if (hasDropX !== hasDropY)
+        throw new Error('file: dropX and dropY must be provided together');
+    if ((opts?.contextText || opts?.sectionText || opts?.exact !== undefined) && !hasFieldLabel) {
+        throw new Error('file: contextText, sectionText, and exact require fieldLabel');
+    }
+    if (opts?.fieldId && !hasSemanticTarget) {
+        throw new Error('file: fieldId requires fieldLabel or fieldKey');
+    }
+    if (strategy === 'chooser') {
+        if (!hasClick)
+            throw new Error('file: chooser strategy requires x,y click coordinates');
+        if (hasDrop || hasSemanticExtras)
+            throw new Error('file: chooser strategy accepts only a coordinate target');
+    }
+    else if (strategy === 'drop') {
+        if (!hasDrop)
+            throw new Error('file: drop strategy requires dropX, dropY');
+        if (hasClick || hasSemanticExtras)
+            throw new Error('file: drop strategy accepts only a drop coordinate target');
+    }
+    else if (strategy === 'hidden') {
+        if (!hasSemanticTarget)
+            throw new Error('file: hidden strategy requires fieldLabel or fieldKey');
+        if (hasClick || hasDrop)
+            throw new Error('file: hidden strategy does not accept coordinates');
+    }
+    else {
+        if (hasDrop)
+            throw new Error('file: dropX/dropY require strategy "drop"');
+        if (hasClick === hasSemanticTarget) {
+            throw new Error('file: auto strategy requires exactly one explicit target: click coordinates, fieldLabel, or fieldKey');
+        }
+    }
     if (strategy === 'chooser' || (strategy === 'auto' && clickX !== undefined && clickY !== undefined)) {
         if (clickX === undefined || clickY === undefined) {
             throw new Error('file: chooser strategy requires x,y click coordinates');
@@ -2978,7 +3914,15 @@ export async function attachFiles(page, paths, opts) {
         return;
     }
     if (strategy === 'hidden' || strategy === 'auto') {
-        if (await attachHiddenInAllFrames(page, paths, { fieldId: opts?.fieldId, fieldLabel, exact, cache: opts?.cache }))
+        if (await attachHiddenInAllFrames(page, paths, {
+            fieldId: opts?.fieldId,
+            fieldKey: opts?.fieldKey,
+            fieldLabel,
+            exact,
+            contextText: opts?.contextText,
+            sectionText: opts?.sectionText,
+            cache: opts?.cache,
+        }))
             return;
         if (strategy === 'hidden') {
             if (fieldLabel) {
@@ -2988,9 +3932,10 @@ export async function attachFiles(page, paths, opts) {
         }
         // Fallback: look for an Attach/Upload button near the field label and use the file chooser
         if (fieldLabel && strategy === 'auto') {
-            const attachBtn = await findAttachButtonNearLabel(page, fieldLabel);
+            const attachBtn = await findAttachButtonNearLabel(page, fieldLabel, opts?.contextText, opts?.sectionText);
             if (attachBtn) {
                 try {
+                    await assertLocatorMutable(attachBtn, 'file', 'file');
                     await attachBtn.scrollIntoViewIfNeeded();
                     const box = await attachBtn.boundingBox();
                     if (box) {
@@ -3004,6 +3949,12 @@ export async function attachFiles(page, paths, opts) {
         if (fieldLabel) {
             throw new Error(`file: no input[type=file] matching field "${fieldLabel}"`);
         }
+        if (opts?.fieldKey) {
+            throw new Error(`file: no input[type=file] matching fieldKey "${opts.fieldKey}"`);
+        }
+        if (opts?.contextText || opts?.sectionText) {
+            throw new Error('file: no input[type=file] matched the requested context/section');
+        }
     }
     if (strategy === 'drop' || (strategy === 'auto' && dropX !== undefined && dropY !== undefined)) {
         if (dropX === undefined || dropY === undefined) {
@@ -3012,20 +3963,20 @@ export async function attachFiles(page, paths, opts) {
         await attachViaDropPlaywright(page, paths, dropX, dropY);
         return;
     }
-    for (const frame of page.frames()) {
-        const loc = frame.locator('input[type="file"]');
-        const n = await loc.count();
-        if (n > 0) {
-            await loc.first().setInputFiles(paths);
-            return;
-        }
-    }
-    throw new Error('file: no input[type=file] in any frame; pass x,y (chooser), dropX/dropY (drop), or strategy hidden');
+    throw new Error('file: explicit upload target did not accept the supplied files');
 }
-async function findLabeledEditableField(page, fieldLabel, exact, cache, fieldId) {
-    const cached = readCachedLocator(cache, 'editable', fieldLabel, exact, fieldId);
+async function findLabeledEditableField(page, fieldLabel, exact, cache, fieldId, fieldKey) {
+    const cached = await readCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, fieldKey);
     if (cached !== undefined)
         return cached;
+    if (fieldKey) {
+        const authored = await findAuthoredFieldByKeyInPage(page, fieldKey, 'editable');
+        if (authored) {
+            writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, fieldKey, authored);
+            return authored;
+        }
+        throw new Error(`fieldKey "${fieldKey}" did not resolve to a visible editable control; refresh geometra_form_schema`);
+    }
     for (const frame of page.frames()) {
         // Always try exact-match candidates first, even when the caller passed
         // exact=false. Same Greenhouse-style failure as findLabeledControl: a
@@ -3045,7 +3996,7 @@ async function findLabeledEditableField(page, fieldLabel, exact, cache, fieldId)
             if (!visible)
                 continue;
             if (await locatorIsEditable(visible)) {
-                writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, visible);
+                writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, undefined, visible);
                 return visible;
             }
         }
@@ -3061,14 +4012,14 @@ async function findLabeledEditableField(page, fieldLabel, exact, cache, fieldId)
                 if (!visible)
                     continue;
                 if (await locatorIsEditable(visible)) {
-                    writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, visible);
+                    writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, undefined, visible);
                     return visible;
                 }
             }
         }
         const fallback = await findLabeledControl(frame, fieldLabel, exact);
         if (fallback && await locatorIsEditable(fallback)) {
-            writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, fallback);
+            writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, undefined, fallback);
             return fallback;
         }
     }
@@ -3091,18 +4042,18 @@ async function findLabeledEditableField(page, fieldLabel, exact, cache, fieldId)
                 if (!visible)
                     continue;
                 if (await locatorIsEditable(visible)) {
-                    writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, visible);
+                    writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, undefined, visible);
                     return visible;
                 }
             }
             const fallback = await findLabeledControl(frame, stripped, exact);
             if (fallback && await locatorIsEditable(fallback)) {
-                writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, fallback);
+                writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, undefined, fallback);
                 return fallback;
             }
         }
     }
-    writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, null);
+    writeCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, undefined, null);
     return null;
 }
 async function locatorCurrentValue(locator) {
@@ -3141,13 +4092,63 @@ function fieldValueMatches(actual, expected) {
     const normalizedExpected = normalizedFieldValue(expected);
     if (!normalizedActual || !normalizedExpected)
         return false;
-    return normalizedActual === normalizedExpected || normalizedActual.includes(normalizedExpected);
+    return normalizedActual === normalizedExpected;
 }
 async function setLocatorTextValue(locator, value, opts) {
+    if (await locatorMutationBlockReason(locator, 'text'))
+        return false;
     try {
         return await locator.evaluate((el, payload) => {
             const nextValue = payload.value;
             const imeFriendly = payload.imeFriendly;
+            // Preflight and commit are separate Playwright round-trips. Reactive
+            // applications can make a control readonly/disabled in between, so the
+            // final guard must live in the same page task as the first mutation.
+            function commitMutationBlockReason(target) {
+                function composedParent(node) {
+                    if (node.parentElement)
+                        return node.parentElement;
+                    const root = node.getRootNode();
+                    return root instanceof ShadowRoot ? root.host : null;
+                }
+                function composedDescendantOf(node, ancestor) {
+                    let current = node;
+                    while (current) {
+                        if (current === ancestor)
+                            return true;
+                        current = composedParent(current);
+                    }
+                    return false;
+                }
+                try {
+                    if (target.matches(':disabled'))
+                        return 'disabled';
+                }
+                catch { /* non-HTML namespaces may reject pseudo classes */ }
+                if ((target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) &&
+                    target.readOnly) {
+                    return 'readonly';
+                }
+                let current = target;
+                while (current) {
+                    if (current.hasAttribute('inert'))
+                        return 'inert';
+                    if (current.getAttribute('aria-disabled')?.trim().toLowerCase() === 'true')
+                        return 'aria-disabled';
+                    if (current.getAttribute('aria-readonly')?.trim().toLowerCase() === 'true')
+                        return 'aria-readonly';
+                    if (current instanceof HTMLFieldSetElement && current.disabled) {
+                        const firstLegend = Array.from(current.children).find(child => child instanceof HTMLLegendElement);
+                        if (!(firstLegend instanceof HTMLLegendElement) || !composedDescendantOf(target, firstLegend)) {
+                            return 'disabled fieldset';
+                        }
+                    }
+                    current = composedParent(current);
+                }
+                return null;
+            }
+            if (commitMutationBlockReason(el))
+                return false;
             // React Greenhouse/Workday/Lever fix: React stores the previous value on
             // a hidden `_valueTracker` property that React uses to short-circuit
             // onChange when the value "hasn't changed". If we set el.value through
@@ -3267,6 +4268,11 @@ async function attemptNativeBatchFill(page, fields) {
             if (results[index])
                 continue;
             const field = fields[index];
+            // Authored field keys are global, exact identities. The per-frame
+            // native batch path only knows labels, so let the normal resolvers scan
+            // all frames before committing a keyed action.
+            if (field.fieldKey)
+                continue;
             if (field.kind === 'file')
                 continue;
             if (field.kind === 'auto') {
@@ -3307,6 +4313,11 @@ async function attemptNativeBatchFill(page, fields) {
                 continue;
             }
             if (field.kind === 'choice') {
+                // An option index is an exact schema identity. The label-only native
+                // batch path cannot preserve or validate it, so route this field
+                // through setFieldChoice below.
+                if (field.optionIndex !== undefined)
+                    continue;
                 pending.push({
                     index,
                     kind: 'choice',
@@ -3317,14 +4328,9 @@ async function attemptNativeBatchFill(page, fields) {
                 });
                 continue;
             }
-            pending.push({
-                index,
-                kind: 'toggle',
-                label: field.label,
-                checked: field.checked ?? true,
-                exact: field.exact ?? false,
-                controlType: field.controlType ?? null,
-            });
+            // Toggle resolution must collect every candidate before committing so
+            // duplicate labels are rejected instead of silently selecting the first.
+            continue;
         }
         if (pending.length === 0)
             break;
@@ -3348,7 +4354,57 @@ async function attemptNativeBatchFill(page, fields) {
                 const style = getComputedStyle(el);
                 return style.display !== 'none' && style.visibility !== 'hidden';
             }
-            function referencedText(ids, visited) {
+            function mutationBlockReason(target) {
+                function composedParent(node) {
+                    if (node.parentElement)
+                        return node.parentElement;
+                    const root = node.getRootNode();
+                    return root instanceof ShadowRoot ? root.host : null;
+                }
+                function composedDescendantOf(node, ancestor) {
+                    let current = node;
+                    while (current) {
+                        if (current === ancestor)
+                            return true;
+                        current = composedParent(current);
+                    }
+                    return false;
+                }
+                try {
+                    if (target.matches(':disabled'))
+                        return 'disabled';
+                }
+                catch { /* ignore */ }
+                if ((target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) &&
+                    target.readOnly)
+                    return 'readonly';
+                let current = target;
+                while (current) {
+                    if (current.hasAttribute('inert'))
+                        return 'inert';
+                    if (current.getAttribute('aria-disabled')?.trim().toLowerCase() === 'true')
+                        return 'aria-disabled';
+                    if (current.getAttribute('aria-readonly')?.trim().toLowerCase() === 'true')
+                        return 'aria-readonly';
+                    if (current instanceof HTMLFieldSetElement && current.disabled) {
+                        const firstLegend = Array.from(current.children).find(child => child instanceof HTMLLegendElement);
+                        if (!(firstLegend instanceof HTMLLegendElement) || !composedDescendantOf(target, firstLegend)) {
+                            return 'disabled fieldset';
+                        }
+                    }
+                    current = composedParent(current);
+                }
+                return null;
+            }
+            function rootScopedElementById(owner, id) {
+                const root = owner.getRootNode();
+                if (root instanceof ShadowRoot)
+                    return root.getElementById(id);
+                if (root instanceof Document)
+                    return root.getElementById(id);
+                return null;
+            }
+            function referencedText(owner, ids, visited) {
                 if (!ids)
                     return undefined;
                 const seen = visited ?? new Set();
@@ -3358,12 +4414,12 @@ async function attemptNativeBatchFill(page, fields) {
                     if (seen.has(id))
                         return '';
                     seen.add(id);
-                    const target = document.getElementById(id);
+                    const target = rootScopedElementById(owner, id);
                     if (!target)
                         return '';
                     const chained = target.getAttribute('aria-labelledby');
                     if (chained)
-                        return referencedText(chained, seen) ?? '';
+                        return referencedText(target, chained, seen) ?? '';
                     return target.textContent?.trim() ?? '';
                 })
                     .filter(Boolean)
@@ -3375,7 +4431,7 @@ async function attemptNativeBatchFill(page, fields) {
                 const aria = el.getAttribute('aria-label')?.trim();
                 if (aria)
                     return aria;
-                const labelledBy = referencedText(el.getAttribute('aria-labelledby'));
+                const labelledBy = referencedText(el, el.getAttribute('aria-labelledby'));
                 if (labelledBy)
                     return labelledBy;
                 if ((el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement) &&
@@ -3384,7 +4440,10 @@ async function attemptNativeBatchFill(page, fields) {
                     return el.labels[0]?.textContent?.trim() || undefined;
                 }
                 if (el instanceof HTMLElement && el.id) {
-                    const label = document.querySelector(`label[for="${CSS.escape(el.id)}"]`);
+                    const root = el.getRootNode();
+                    const label = (root instanceof Document || root instanceof ShadowRoot)
+                        ? root.querySelector(`label[for="${CSS.escape(el.id)}"]`)
+                        : null;
                     const text = label?.textContent?.trim();
                     if (text)
                         return text;
@@ -3437,6 +4496,8 @@ async function attemptNativeBatchFill(page, fields) {
                     target.value = next;
             }
             function setInputCheckedReactAware(target, next) {
+                if (mutationBlockReason(target))
+                    return false;
                 const hadReactTracker = clearReactTracker(target, next);
                 if (!hadReactTracker && target.checked === next)
                     return true;
@@ -3596,6 +4657,8 @@ async function attemptNativeBatchFill(page, fields) {
                     }
                     if (!matches(explicitLabelText(control), fieldLabel, exact))
                         continue;
+                    if (mutationBlockReason(control))
+                        return false;
                     if (control instanceof HTMLInputElement || control instanceof HTMLTextAreaElement) {
                         const inputType = control instanceof HTMLInputElement ? control.type : 'textarea';
                         const v = canonicalizeHtmlInputValueInPage(inputType, value);
@@ -3603,7 +4666,7 @@ async function attemptNativeBatchFill(page, fields) {
                         clearReactTracker(control);
                         setInputLikeValue(control, v);
                         dispatch(control);
-                        return matches(currentValue(control), v, false);
+                        return normalize(currentValue(control)) === normalize(v);
                     }
                     if (control instanceof HTMLElement && control.isContentEditable) {
                         if (!isPlainContentEditableBatch(control))
@@ -3612,7 +4675,7 @@ async function attemptNativeBatchFill(page, fields) {
                         clearReactTracker(control);
                         control.textContent = value;
                         dispatch(control);
-                        return matches(currentValue(control), value, false);
+                        return normalize(currentValue(control)) === normalize(value);
                     }
                 }
                 return false;
@@ -3624,8 +4687,12 @@ async function attemptNativeBatchFill(page, fields) {
                         continue;
                     if (!matches(explicitLabelText(control), fieldLabel, exact))
                         continue;
+                    if (mutationBlockReason(control))
+                        return false;
                     const expected = normalize(value);
                     const option = Array.from(control.options).find((candidate) => {
+                        if (candidate.disabled || (candidate.parentElement instanceof HTMLOptGroupElement && candidate.parentElement.disabled))
+                            return false;
                         const label = normalize(candidate.textContent);
                         const rawValue = normalize(candidate.value);
                         return exact ? label === expected || rawValue === expected : label.includes(expected) || rawValue.includes(expected);
@@ -3634,7 +4701,7 @@ async function attemptNativeBatchFill(page, fields) {
                         return false;
                     control.value = option.value;
                     dispatch(control);
-                    return matches(currentValue(control), value, false) || normalize(control.value) === expected;
+                    return control.selectedIndex === option.index;
                 }
                 return false;
             }
@@ -3694,13 +4761,17 @@ async function attemptNativeBatchFill(page, fields) {
                             const control = option.control;
                             if (control instanceof HTMLInputElement)
                                 return setInputCheckedReactAware(control, true);
+                            if (mutationBlockReason(option))
+                                return false;
                             option.click();
-                            return true;
+                            return false;
                         }
                         // role=radio / role=checkbox: click and verify aria-checked
                         // / aria-selected. The native batch fill used to silently return
                         // true here, which masked Pinecone's commit-on-rerender bug.
                         if (option.getAttribute('role') === 'radio' || option.getAttribute('role') === 'checkbox') {
+                            if (mutationBlockReason(option))
+                                return false;
                             option.click();
                             return (option.getAttribute('aria-checked') === 'true' ||
                                 option.getAttribute('aria-selected') === 'true');
@@ -3717,6 +4788,8 @@ async function attemptNativeBatchFill(page, fields) {
                         // JobForge round-2 marathon — Pinecone Sr SWE Database Team
                         // #320 and LangChain SE Manager #325.
                         const beforeSig = selectionSignature(options);
+                        if (mutationBlockReason(option))
+                            return false;
                         option.click();
                         const afterSig = selectionSignature(options);
                         if (beforeSig === afterSig)
@@ -3735,6 +4808,8 @@ async function attemptNativeBatchFill(page, fields) {
                         continue;
                     if (!matches(explicitLabelText(input), label, exact))
                         continue;
+                    if (mutationBlockReason(input))
+                        return false;
                     if (!setInputCheckedReactAware(input, checked))
                         return false;
                     return input.checked === checked;
@@ -3750,6 +4825,8 @@ async function attemptNativeBatchFill(page, fields) {
                         continue;
                     if (controlType && control.type !== controlType)
                         continue;
+                    if (mutationBlockReason(control))
+                        return false;
                     if (!setInputCheckedReactAware(control, checked))
                         return false;
                     return control.checked === checked;
@@ -4037,6 +5114,9 @@ export async function fillOtp(page, value, opts) {
     if (liveCount !== group.cellCount) {
         throw new Error(`fillOtp: OTP cell group went stale before fill (expected ${group.cellCount} cells, found ${liveCount}). The form likely re-rendered between detection and fill — retry the call.`);
     }
+    for (let index = 0; index < liveCount; index++) {
+        await assertLocatorMutable(group.boxes.nth(index), 'text', `fillOtp: OTP cell ${index + 1}`);
+    }
     // Click the leftmost box via its center point. We use a low-level
     // bounding-box click because a semantic "click the first input" path
     // resolves to whichever input paints topmost in the stacking order,
@@ -4230,7 +5310,7 @@ export async function setFieldText(page, fieldLabel, value, opts) {
     // from fillOtp propagates out of setFieldText unchanged: silent fallback
     // to the plain text-fill path would write the whole string into box 0
     // and pretend success, which is the bug we're fixing.
-    if (labelLooksLikeOtp(fieldLabel) && /^\S{4,}$/.test(value)) {
+    if (!opts?.fieldKey && labelLooksLikeOtp(fieldLabel) && /^\S{4,}$/.test(value)) {
         const group = await findOtpBoxGroup(page, fieldLabel, value.length);
         if (group) {
             await fillOtp(page, value, { fieldLabel });
@@ -4238,10 +5318,11 @@ export async function setFieldText(page, fieldLabel, value, opts) {
         }
     }
     const exact = opts?.exact ?? false;
-    const locator = await findLabeledEditableField(page, fieldLabel, exact, opts?.cache, opts?.fieldId);
+    const locator = await findLabeledEditableField(page, fieldLabel, exact, opts?.cache, opts?.fieldId, opts?.fieldKey);
     if (!locator) {
         throw new Error(`setFieldText: no visible editable field matching "${fieldLabel}"`);
     }
+    await assertLocatorMutable(locator, 'text', 'setFieldText');
     await locator.scrollIntoViewIfNeeded();
     const inputType = await locator.evaluate(el => {
         if (el instanceof HTMLInputElement)
@@ -4253,6 +5334,7 @@ export async function setFieldText(page, fieldLabel, value, opts) {
     const normalized = canonicalizeHtmlInputValue(inputType, value);
     const applied = await setLocatorTextValue(locator, normalized, { imeFriendly: opts?.imeFriendly });
     if (!applied) {
+        await assertLocatorMutable(locator, 'text', 'setFieldText');
         try {
             await locator.fill(normalized);
         }
@@ -4263,6 +5345,7 @@ export async function setFieldText(page, fieldLabel, value, opts) {
             });
         }
     }
+    await delay(40);
     const current = await locatorCurrentValue(locator);
     if (fieldValueMatches(current, normalized))
         return;
@@ -4271,31 +5354,88 @@ export async function setFieldText(page, fieldLabel, value, opts) {
         return;
     throw new Error(`setFieldText: set "${fieldLabel}" but could not confirm value ${JSON.stringify(value)}`);
 }
-async function setNativeSelectByLabel(locator, value, exact) {
+async function setNativeSelectByLabel(locator, value, exact, optionIndex) {
+    if (await locatorMutationBlockReason(locator, 'select'))
+        return false;
     try {
-        return await locator.evaluate((el, payload) => {
+        return await locator.evaluate(async (el, payload) => {
             if (!(el instanceof HTMLSelectElement))
                 return false;
+            // Keep the final state check atomic with selectedIndex/event mutation.
+            // The earlier host-side preflight can race a reactive disable/inert
+            // update while Playwright crosses back into the page.
+            function commitMutationBlockReason(target) {
+                function composedParent(node) {
+                    if (node.parentElement)
+                        return node.parentElement;
+                    const root = node.getRootNode();
+                    return root instanceof ShadowRoot ? root.host : null;
+                }
+                function composedDescendantOf(node, ancestor) {
+                    let current = node;
+                    while (current) {
+                        if (current === ancestor)
+                            return true;
+                        current = composedParent(current);
+                    }
+                    return false;
+                }
+                try {
+                    if (target.matches(':disabled'))
+                        return 'disabled';
+                }
+                catch { /* non-HTML namespaces may reject pseudo classes */ }
+                let current = target;
+                while (current) {
+                    if (current.hasAttribute('inert'))
+                        return 'inert';
+                    if (current.getAttribute('aria-disabled')?.trim().toLowerCase() === 'true')
+                        return 'aria-disabled';
+                    if (current.getAttribute('aria-readonly')?.trim().toLowerCase() === 'true')
+                        return 'aria-readonly';
+                    if (current instanceof HTMLFieldSetElement && current.disabled) {
+                        const firstLegend = Array.from(current.children).find(child => child instanceof HTMLLegendElement);
+                        if (!(firstLegend instanceof HTMLLegendElement) || !composedDescendantOf(target, firstLegend)) {
+                            return 'disabled fieldset';
+                        }
+                    }
+                    current = composedParent(current);
+                }
+                return null;
+            }
+            if (commitMutationBlockReason(el))
+                return false;
             const normalize = (input) => input?.replace(/\s+/g, ' ').trim().toLowerCase() ?? '';
             const expected = normalize(payload.value);
-            if (!expected)
-                return false;
-            const option = Array.from(el.options).find((candidate) => {
-                if (candidate.disabled)
+            const enabled = (candidate) => !candidate.disabled && !(candidate.parentElement instanceof HTMLOptGroupElement && candidate.parentElement.disabled);
+            let option;
+            if (payload.optionIndex !== undefined) {
+                const indexed = el.options.item(payload.optionIndex) ?? undefined;
+                if (!indexed || !enabled(indexed) || indexed.value !== payload.value)
                     return false;
-                const label = normalize(candidate.textContent);
-                const rawValue = normalize(candidate.value);
-                if (payload.exact)
-                    return label === expected || rawValue === expected;
-                return label.includes(expected) || rawValue.includes(expected);
-            });
+                option = indexed;
+            }
+            else {
+                const options = Array.from(el.options).filter(enabled);
+                // Values are the submitted identity and take precedence over labels.
+                // This prevents an earlier option whose label happens to equal a
+                // different option's value from being selected silently.
+                option = options.find(candidate => normalize(candidate.value) === expected);
+                if (!option)
+                    option = options.find(candidate => normalize(candidate.textContent) === expected);
+                if (!option && !payload.exact && expected) {
+                    option = options.find(candidate => normalize(candidate.value).includes(expected))
+                        ?? options.find(candidate => normalize(candidate.textContent).includes(expected));
+                }
+            }
             if (!option)
                 return false;
-            el.value = option.value;
+            el.selectedIndex = option.index;
             el.dispatchEvent(new Event('input', { bubbles: true }));
             el.dispatchEvent(new Event('change', { bubbles: true }));
-            return true;
-        }, { value, exact });
+            await new Promise(resolveTimer => setTimeout(resolveTimer, 40));
+            return el.selectedIndex === option.index && el.selectedOptions[0] === option;
+        }, { value, exact, optionIndex });
     }
     catch {
         return false;
@@ -4316,6 +5456,46 @@ async function chooseValueFromLabeledGroup(page, fieldLabel, value, exact) {
                 const style = getComputedStyle(el);
                 return style.display !== 'none' && style.visibility !== 'hidden';
             }
+            function blocked(target) {
+                function parent(node) {
+                    if (node.parentElement)
+                        return node.parentElement;
+                    const root = node.getRootNode();
+                    return root instanceof ShadowRoot ? root.host : null;
+                }
+                function within(node, ancestor) {
+                    let current = node;
+                    while (current) {
+                        if (current === ancestor)
+                            return true;
+                        current = parent(current);
+                    }
+                    return false;
+                }
+                try {
+                    if (target.matches(':disabled'))
+                        return true;
+                }
+                catch { /* ignore */ }
+                if ((target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) && target.readOnly)
+                    return true;
+                let current = target;
+                while (current) {
+                    if (current.hasAttribute('inert'))
+                        return true;
+                    if (current.getAttribute('aria-disabled')?.trim().toLowerCase() === 'true')
+                        return true;
+                    if (current.getAttribute('aria-readonly')?.trim().toLowerCase() === 'true')
+                        return true;
+                    if (current instanceof HTMLFieldSetElement && current.disabled) {
+                        const legend = Array.from(current.children).find(child => child instanceof HTMLLegendElement);
+                        if (!(legend instanceof HTMLLegendElement) || !within(target, legend))
+                            return true;
+                    }
+                    current = parent(current);
+                }
+                return false;
+            }
             function matches(candidate) {
                 const normalizedCandidate = normalize(candidate);
                 const normalizedExpected = normalize(payload.fieldLabel);
@@ -4330,7 +5510,15 @@ async function chooseValueFromLabeledGroup(page, fieldLabel, value, exact) {
                     return false;
                 return payload.exact ? normalizedCandidate === normalizedExpected : normalizedCandidate.includes(normalizedExpected);
             }
-            function referencedText(ids, visited) {
+            function rootScopedElementById(owner, id) {
+                const root = owner.getRootNode();
+                if (root instanceof ShadowRoot)
+                    return root.getElementById(id);
+                if (root instanceof Document)
+                    return root.getElementById(id);
+                return null;
+            }
+            function referencedText(owner, ids, visited) {
                 if (!ids)
                     return undefined;
                 const seen = visited ?? new Set();
@@ -4340,12 +5528,12 @@ async function chooseValueFromLabeledGroup(page, fieldLabel, value, exact) {
                     if (seen.has(id))
                         return '';
                     seen.add(id);
-                    const target = document.getElementById(id);
+                    const target = rootScopedElementById(owner, id);
                     if (!target)
                         return '';
                     const chained = target.getAttribute('aria-labelledby');
                     if (chained)
-                        return referencedText(chained, seen) ?? '';
+                        return referencedText(target, chained, seen) ?? '';
                     return target.textContent?.trim() ?? '';
                 })
                     .filter(Boolean)
@@ -4357,7 +5545,7 @@ async function chooseValueFromLabeledGroup(page, fieldLabel, value, exact) {
                 const aria = el.getAttribute('aria-label')?.trim();
                 if (aria)
                     return aria;
-                const labelledBy = referencedText(el.getAttribute('aria-labelledby'));
+                const labelledBy = referencedText(el, el.getAttribute('aria-labelledby'));
                 if (labelledBy)
                     return labelledBy;
                 if (el instanceof HTMLInputElement && el.labels && el.labels.length > 0) {
@@ -4391,7 +5579,7 @@ async function chooseValueFromLabeledGroup(page, fieldLabel, value, exact) {
                 const aria = el.getAttribute('aria-label')?.trim();
                 if (aria)
                     return aria;
-                const labelledBy = referencedText(el.getAttribute('aria-labelledby'));
+                const labelledBy = referencedText(el, el.getAttribute('aria-labelledby'));
                 if (labelledBy)
                     return labelledBy;
                 return el.textContent?.trim() || undefined;
@@ -4469,6 +5657,8 @@ async function chooseValueFromLabeledGroup(page, fieldLabel, value, exact) {
                 return false;
             }
             function setInputCheckedReactAware(target, next) {
+                if (blocked(target))
+                    return false;
                 const hadReactTracker = clearReactTracker(target, next);
                 if (!hadReactTracker && target.checked === next)
                     return true;
@@ -4495,6 +5685,8 @@ async function chooseValueFromLabeledGroup(page, fieldLabel, value, exact) {
                         const control = option.control;
                         if (control instanceof HTMLInputElement)
                             return setInputCheckedReactAware(control, true);
+                        if (blocked(option))
+                            return false;
                         option.click();
                         // No backing input — verify via group signature change so we don't
                         // silently no-op on label wrappers whose target is unparented.
@@ -4502,6 +5694,8 @@ async function chooseValueFromLabeledGroup(page, fieldLabel, value, exact) {
                         return labelBeforeSig !== labelAfterSig;
                     }
                     if (option.getAttribute('role') === 'radio' || option.getAttribute('role') === 'checkbox') {
+                        if (blocked(option))
+                            return false;
                         option.click();
                         return option.getAttribute('aria-checked') === 'true' || option.getAttribute('aria-selected') === 'true';
                     }
@@ -4511,6 +5705,8 @@ async function chooseValueFromLabeledGroup(page, fieldLabel, value, exact) {
                     // was a no-op — return false so the caller can try the next strategy
                     // (pickListboxOption fallback, etc) instead of silently succeeding.
                     const beforeSig = selectionSignature(options);
+                    if (blocked(option))
+                        return false;
                     option.click();
                     const afterSig = selectionSignature(options);
                     if (beforeSig === afterSig) {
@@ -4553,20 +5749,29 @@ async function autoFieldLocatorKind(locator) {
 export async function setAutoFieldValue(page, fieldLabel, value, opts) {
     const exact = opts?.exact ?? false;
     if (typeof value === 'boolean') {
+        if (opts?.fieldKey) {
+            await setCheckedControl(page, fieldLabel, { fieldKey: opts.fieldKey, checked: value, exact });
+            return;
+        }
         if (await chooseValueFromLabeledGroup(page, fieldLabel, value ? 'Yes' : 'No', exact))
             return;
-        await setCheckedControl(page, fieldLabel, { checked: value, exact });
+        await setCheckedControl(page, fieldLabel, { fieldKey: opts?.fieldKey, checked: value, exact });
         return;
     }
-    if (prefersGroupedChoiceValue(value) && await chooseValueFromLabeledGroup(page, fieldLabel, value, exact)) {
+    if (!opts?.fieldKey && prefersGroupedChoiceValue(value) && await chooseValueFromLabeledGroup(page, fieldLabel, value, exact)) {
         return;
     }
-    const locator = await findLabeledControlInPage(page, fieldLabel, exact, { cache: opts?.cache, fieldId: opts?.fieldId });
+    const locator = await findLabeledControlInPage(page, fieldLabel, exact, {
+        cache: opts?.cache,
+        fieldId: opts?.fieldId,
+        fieldKey: opts?.fieldKey,
+    });
     if (locator) {
         const kind = await autoFieldLocatorKind(locator);
         if (kind === 'select') {
             await setFieldChoice(page, fieldLabel, value, {
                 fieldId: opts?.fieldId,
+                fieldKey: opts?.fieldKey,
                 exact,
                 choiceType: 'select',
                 cache: opts?.cache,
@@ -4576,6 +5781,7 @@ export async function setAutoFieldValue(page, fieldLabel, value, opts) {
         if (kind === 'text') {
             await setFieldText(page, fieldLabel, value, {
                 fieldId: opts?.fieldId,
+                fieldKey: opts?.fieldKey,
                 exact,
                 cache: opts?.cache,
             });
@@ -4584,17 +5790,22 @@ export async function setAutoFieldValue(page, fieldLabel, value, opts) {
         if (kind === 'choice') {
             await setFieldChoice(page, fieldLabel, value, {
                 fieldId: opts?.fieldId,
+                fieldKey: opts?.fieldKey,
                 exact,
                 cache: opts?.cache,
             });
             return;
         }
     }
+    if (opts?.fieldKey) {
+        throw new Error(`fieldKey "${opts.fieldKey}" resolved to an unsupported control for field "${fieldLabel}"`);
+    }
     if (await chooseValueFromLabeledGroup(page, fieldLabel, value, exact))
         return;
     try {
         await setFieldText(page, fieldLabel, value, {
             fieldId: opts?.fieldId,
+            fieldKey: opts?.fieldKey,
             exact,
             cache: opts?.cache,
         });
@@ -4603,6 +5814,7 @@ export async function setAutoFieldValue(page, fieldLabel, value, opts) {
     catch {
         await setFieldChoice(page, fieldLabel, value, {
             fieldId: opts?.fieldId,
+            fieldKey: opts?.fieldKey,
             exact,
             cache: opts?.cache,
         });
@@ -4610,11 +5822,22 @@ export async function setAutoFieldValue(page, fieldLabel, value, opts) {
 }
 export async function setFieldChoice(page, fieldLabel, value, opts) {
     const exact = opts?.exact ?? false;
-    const locator = await findLabeledControlInPage(page, fieldLabel, exact, { cache: opts?.cache, fieldId: opts?.fieldId });
+    const locator = await findLabeledControlInPage(page, fieldLabel, exact, {
+        cache: opts?.cache,
+        fieldId: opts?.fieldId,
+        fieldKey: opts?.fieldKey,
+    });
     if (locator) {
+        await assertLocatorMutable(locator, 'select', 'setFieldChoice');
         await locator.scrollIntoViewIfNeeded();
         const isNativeSelect = await locator.evaluate(el => el instanceof HTMLSelectElement);
-        if (await setNativeSelectByLabel(locator, value, exact)) {
+        if (await setNativeSelectByLabel(locator, value, exact, opts?.optionIndex)) {
+            if (opts?.optionIndex !== undefined) {
+                const selectedIndex = await locator.evaluate(el => el instanceof HTMLSelectElement ? el.selectedIndex : -1);
+                if (selectedIndex === opts.optionIndex)
+                    return;
+                throw new Error(`setFieldChoice: selected native option index ${opts.optionIndex} for field "${fieldLabel}" but could not confirm it`);
+            }
             const displayed = await locatorDisplayedValues(locator);
             if (displayed.some(candidate => displayedValueMatchesSelection(candidate, value, exact)))
                 return;
@@ -4633,6 +5856,7 @@ export async function setFieldChoice(page, fieldLabel, value, opts) {
     try {
         await pickListboxOption(page, value, {
             fieldId: opts?.fieldId,
+            fieldKey: opts?.fieldKey,
             fieldLabel,
             exact,
             query: opts?.query,
@@ -4678,6 +5902,7 @@ export async function fillFields(page, fields, cache = createFillLookupCache())
     if (textFills.length > 0) {
         const results = await Promise.allSettled(textFills.map(({ field }) => setFieldText(page, field.fieldLabel, field.value, {
             fieldId: field.fieldId,
+            fieldKey: field.fieldKey,
             exact: field.exact,
             cache,
             typingDelayMs: field.typingDelayMs,
@@ -4708,6 +5933,7 @@ export async function fillFields(page, fields, cache = createFillLookupCache())
             if (field.kind === 'auto') {
                 await setAutoFieldValue(page, field.fieldLabel, field.value, {
                     fieldId: field.fieldId,
+                    fieldKey: field.fieldKey,
                     exact: field.exact,
                     cache,
                 });
@@ -4716,7 +5942,9 @@ export async function fillFields(page, fields, cache = createFillLookupCache())
             if (field.kind === 'choice') {
                 await setFieldChoice(page, field.fieldLabel, field.value, {
                     fieldId: field.fieldId,
+                    fieldKey: field.fieldKey,
                     exact: field.exact,
+                    optionIndex: field.optionIndex,
                     query: field.query,
                     choiceType: field.choiceType,
                     cache,
@@ -4725,14 +5953,25 @@ export async function fillFields(page, fields, cache = createFillLookupCache())
             }
             if (field.kind === 'toggle') {
                 await setCheckedControl(page, field.label, {
+                    fieldKey: field.fieldKey,
                     checked: field.checked,
                     exact: field.exact,
                     controlType: field.controlType,
+                    contextText: field.contextText,
+                    sectionText: field.sectionText,
                 });
                 continue;
             }
             if (field.kind === 'file') {
-                await attachFiles(page, field.paths, { fieldId: field.fieldId, fieldLabel: field.fieldLabel, exact: field.exact, cache });
+                await attachFiles(page, field.paths, {
+                    fieldId: field.fieldId,
+                    fieldKey: field.fieldKey,
+                    fieldLabel: field.fieldLabel,
+                    contextText: field.contextText,
+                    sectionText: field.sectionText,
+                    exact: field.exact,
+                    cache,
+                });
             }
         }
         catch (e) {
@@ -4767,65 +6006,46 @@ export async function selectNativeOption(page, x, y, opt) {
     if (opt.value === undefined && opt.label === undefined && opt.index === undefined) {
         throw new Error('selectOption: provide at least one of value, label, or index');
     }
+    if (opt.index !== undefined && (!Number.isFinite(opt.index) || !Number.isInteger(opt.index) || opt.index < 0)) {
+        throw new Error('selectOption: index must be a non-negative integer');
+    }
+    await assertPointMutable(page, x, y, 'select', 'selectOption');
     await page.mouse.click(x, y);
     await delay(40);
     for (const frame of page.frames()) {
-        const applied = await frame.evaluate((payload) => {
+        const applied = await frame.evaluate(async (payload) => {
             const normalize = (input) => input?.replace(/\s+/g, ' ').trim().toLowerCase() ?? '';
-            const optionMatchesExpected = (o, expected) => {
-                if (o.disabled)
+            const enabled = (o) => !o.disabled && !(o.parentElement instanceof HTMLOptGroupElement && o.parentElement.disabled);
+            const optionMatchesPayload = (o) => {
+                if (o.disabled || (o.parentElement instanceof HTMLOptGroupElement && o.parentElement.disabled))
                     return false;
-                const label = normalize(o.textContent);
-                const rawValue = normalize(o.value);
-                return label === expected || rawValue === expected || label.includes(expected) || rawValue.includes(expected);
+                if (payload.value !== null && normalize(o.value) !== normalize(payload.value))
+                    return false;
+                if (payload.label !== null && normalize(o.textContent) !== normalize(payload.label))
+                    return false;
+                if (payload.index !== undefined && o.index !== payload.index)
+                    return false;
+                return true;
             };
             const a = document.activeElement;
             if (!a || a.tagName !== 'SELECT')
                 return false;
             const sel = a;
-            if (typeof payload.index === 'number' && Number.isFinite(payload.index)) {
-                const i = Math.trunc(payload.index);
-                if (i < 0 || i >= sel.options.length)
-                    return false;
-                if (sel.options[i].disabled)
-                    return false;
-                sel.selectedIndex = i;
-            }
-            else if (payload.value !== null && payload.value !== undefined) {
-                const raw = String(payload.value);
-                sel.value = raw;
-                const expected = normalize(raw);
-                if (!expected)
-                    return false;
-                const selected = sel.selectedOptions[0];
-                const ok = selected &&
-                    !selected.disabled &&
-                    (normalize(selected.value) === expected ||
-                        normalize(selected.textContent) === expected ||
-                        normalize(selected.value).includes(expected) ||
-                        normalize(selected.textContent).includes(expected));
-                if (!ok) {
-                    const found = Array.from(sel.options).find(o => optionMatchesExpected(o, expected));
-                    if (!found)
-                        return false;
-                    sel.value = found.value;
-                }
-            }
-            else if (payload.label !== null && payload.label !== undefined) {
-                const expected = normalize(payload.label);
-                if (!expected)
-                    return false;
-                const optEl = Array.from(sel.options).find(o => optionMatchesExpected(o, expected));
-                if (!optEl)
-                    return false;
-                sel.value = optEl.value;
-            }
-            else {
+            if (sel.matches(':disabled') || sel.getAttribute('aria-disabled') === 'true' || sel.getAttribute('aria-readonly') === 'true')
                 return false;
-            }
+            if (sel.closest('[inert], [aria-disabled="true"], [aria-readonly="true"]'))
+                return false;
+            const candidate = payload.index !== undefined
+                ? sel.options.item(payload.index)
+                : Array.from(sel.options).find(optionMatchesPayload) ?? null;
+            if (!candidate || !enabled(candidate) || !optionMatchesPayload(candidate))
+                return false;
+            sel.selectedIndex = candidate.index;
             sel.dispatchEvent(new Event('input', { bubbles: true }));
             sel.dispatchEvent(new Event('change', { bubbles: true }));
-            return true;
+            await new Promise(resolveTimer => setTimeout(resolveTimer, 40));
+            const selected = sel.selectedOptions[0];
+            return sel.selectedIndex === candidate.index && selected === candidate && optionMatchesPayload(selected);
         }, {
             value: opt.value ?? null,
             label: opt.label ?? null,
@@ -4842,6 +6062,23 @@ export async function selectNativeOption(page, x, y, opt) {
 export async function pickListboxOption(page, label, opts) {
     let anchor;
     const exact = opts?.exact ?? false;
+    const hasOpenX = opts?.openX !== undefined;
+    const hasOpenY = opts?.openY !== undefined;
+    if (hasOpenX !== hasOpenY) {
+        throw new Error('listboxPick: openX and openY must be provided together');
+    }
+    if ((hasOpenX || hasOpenY) && (opts?.fieldLabel || opts?.fieldId || opts?.fieldKey)) {
+        throw new Error('listboxPick: coordinate opening cannot be combined with fieldLabel, fieldId, or fieldKey');
+    }
+    if (hasOpenX && opts?.query !== undefined) {
+        throw new Error('listboxPick: query cannot be combined with coordinate opening');
+    }
+    if (opts?.fieldId && !opts.fieldLabel && !opts.fieldKey) {
+        throw new Error('listboxPick: fieldId requires fieldLabel or fieldKey and cannot be used as an unscoped hint');
+    }
+    if (!opts?.fieldLabel && !opts?.fieldKey && !hasOpenX) {
+        throw new Error('listboxPick: provide fieldLabel, fieldKey, or a complete openX/openY target before selecting an option');
+    }
     let attemptedSelection = false;
     let selectedOptionText;
     let openedHandle;
@@ -4867,16 +6104,16 @@ export async function pickListboxOption(page, label, opts) {
         await releasePopupScope();
         popupScope = await resolveOwnedPopupHandle(openedHandle);
     };
-    if (opts?.fieldLabel) {
+    if (opts?.fieldLabel || opts?.fieldKey) {
         let opened;
         try {
-            opened = await openDropdownControl(page, opts.fieldLabel, exact, opts.cache, opts.fieldId);
+            opened = await openDropdownControl(page, opts.fieldLabel ?? '', exact, opts.cache, opts.fieldId, opts.fieldKey);
         }
         catch {
             throw new Error(listboxErrorMessage({
                 reason: 'field_not_found',
                 requestedLabel: label,
-                fieldLabel: opts.fieldLabel,
+                fieldLabel: opts.fieldLabel ?? opts.fieldKey,
                 query: opts?.query,
                 exact,
             }));
@@ -4896,6 +6133,10 @@ export async function pickListboxOption(page, label, opts) {
         await refreshPopupScope();
     }
     else if (opts?.openX !== undefined && opts?.openY !== undefined) {
+        await assertPointMutable(page, opts.openX, opts.openY, 'select', 'listboxPick');
+        openedHandle = await elementHandleAtPoint(page, opts.openX, opts.openY);
+        if (!openedHandle)
+            throw new Error('listboxPick: no control at openX/openY');
         await page.mouse.click(opts.openX, opts.openY);
         anchor = { x: opts.openX, y: opts.openY };
         await delay(120);
@@ -4905,29 +6146,27 @@ export async function pickListboxOption(page, label, opts) {
         if (!selectedOptionText)
             return false;
         attemptedSelection = true;
-        // Force-commit for searchable/autocomplete comboboxes (React Select,
-        // Headless UI, Radix, Ant Design, etc.). Some library versions — most
-        // notably Greenhouse's Remix-wrapped react-select — visually select the
-        // option on synthetic mouse click but never invoke `onChange`, leaving
-        // the controlled form state empty. Dispatching a keyboard `Enter` on
-        // the focused combobox input puts the selection through the keyboard
-        // commit path, which ALL tested libraries honor. No-op for native
-        // <select> / plain ARIA listboxes — see isAutocompleteCombobox.
-        await pressEnterToCommitListbox(page, openedHandle);
+        // Do not press Enter after a successful pointer selection. Both
+        // react-select and non-editable Radix triggers can interpret Enter on
+        // the now-closed control as "open again", leaving several adjacent
+        // dropdowns expanded and making later shared-label picks hit the wrong
+        // popup. If the pointer click did not commit, the keyboard fallback
+        // below deliberately reopens this exact control and selects by Enter.
         await dispatchListboxCommitEvents(openedHandle);
-        if (!opts?.fieldLabel ||
-            await confirmListboxSelection(page, opts.fieldLabel, label, exact, anchor, openedHandle, selectedOptionText, {
+        if (opts?.fieldLabel) {
+            if (await confirmListboxSelection(page, opts.fieldLabel, label, exact, anchor, openedHandle, selectedOptionText, {
                 editable: openedEditable,
-            })) {
-            return true;
+            }))
+                return true;
+            return false;
         }
-        return false;
+        return await confirmListboxSelectionWithoutLabel(page, label, exact, anchor, openedHandle, selectedOptionText);
     };
     const dismissAfterSelection = async () => {
         if (!opts?.fieldLabel) {
             await page.keyboard.press('Tab');
             await delay(50);
-            return true;
+            return await confirmListboxSelectionWithoutLabel(page, label, exact, anchor, openedHandle, selectedOptionText);
         }
         if (await dismissAndReVerifySelection(page, label, exact, openedHandle, selectedOptionText)) {
             return true;
@@ -5024,10 +6263,12 @@ export async function pickListboxOption(page, label, opts) {
             selectedOptionText = keyboardSelection;
             attemptedSelection = true;
             await dispatchListboxCommitEvents(openedHandle);
-            if (!opts?.fieldLabel ||
-                await confirmListboxSelection(page, opts.fieldLabel, label, exact, anchor, openedHandle, selectedOptionText, {
+            const keyboardConfirmed = opts?.fieldLabel
+                ? await confirmListboxSelection(page, opts.fieldLabel, label, exact, anchor, openedHandle, selectedOptionText, {
                     editable: openedEditable,
-                })) {
+                })
+                : await confirmListboxSelectionWithoutLabel(page, label, exact, anchor, openedHandle, selectedOptionText);
+            if (keyboardConfirmed) {
                 if (await dismissAfterSelection() && await postCommitVerify())
                     return;
             }
@@ -5060,57 +6301,129 @@ export async function pickListboxOption(page, label, opts) {
         await releasePopupScope();
     }
 }
-/**
- * Set a checkbox/radio by accessible label instead of brittle coordinate clicks.
- * Helps custom form UIs that keep the real control opacity-hidden but still interactive.
- */
-export async function setCheckedControl(page, label, opts) {
-    const exact = opts?.exact ?? false;
-    const desiredChecked = opts?.checked ?? true;
-    const controlType = opts?.controlType;
+async function applyToggleState(locator, desiredChecked) {
+    return await locator.evaluate((target, checked) => {
+        function rootScopedElementById(owner, id) {
+            const root = owner.getRootNode();
+            if (root instanceof ShadowRoot)
+                return root.getElementById(id);
+            if (root instanceof Document)
+                return root.getElementById(id);
+            return null;
+        }
+        function referencedText(owner, ids, visited) {
+            if (!ids)
+                return undefined;
+            const seen = visited ?? new Set();
+            const text = ids.split(/\s+/).map(id => {
+                if (seen.has(id))
+                    return '';
+                seen.add(id);
+                const node = rootScopedElementById(owner, id);
+                if (!node)
+                    return '';
+                return referencedText(node, node.getAttribute('aria-labelledby'), seen) ?? node.textContent?.trim() ?? '';
+            }).filter(Boolean).join(' ').trim();
+            return text || undefined;
+        }
+        function kindOf(el) {
+            if (el instanceof HTMLInputElement && el.type === 'radio')
+                return 'radio';
+            return el.getAttribute('role') === 'radio' ? 'radio' : 'checkbox';
+        }
+        function nameOf(el) {
+            const aria = el.getAttribute('aria-label')?.trim();
+            if (aria)
+                return aria;
+            const labelledBy = referencedText(el, el.getAttribute('aria-labelledby'));
+            if (labelledBy)
+                return labelledBy;
+            if (el instanceof HTMLInputElement) {
+                const labelText = Array.from(el.labels ?? []).map(label => label.textContent?.trim()).find(Boolean);
+                if (labelText)
+                    return labelText;
+            }
+            return el.textContent?.trim() || '<unnamed>';
+        }
+        function readChecked(el) {
+            return el instanceof HTMLInputElement ? el.checked : el.getAttribute('aria-checked') === 'true';
+        }
+        function dispatch(el) {
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+            el.dispatchEvent(new Event('change', { bubbles: true }));
+        }
+        function setInputCheckedReactAware(input, next) {
+            const tracker = input._valueTracker;
+            if (tracker && typeof tracker.setValue === 'function') {
+                try {
+                    tracker.setValue(String(!next));
+                }
+                catch { /* ignore */ }
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'checked');
+            if (descriptor?.set)
+                descriptor.set.call(input, next);
+            else
+                input.checked = next;
+            dispatch(input);
+        }
+        const kind = kindOf(target);
+        const name = nameOf(target);
+        const before = readChecked(target);
+        if (kind === 'radio' && checked === false) {
+            return { success: before === false, reason: 'radio-uncheck', kind, name, before, after: before };
+        }
+        if (before !== checked) {
+            if (target instanceof HTMLInputElement) {
+                setInputCheckedReactAware(target, checked);
+            }
+            else if (target instanceof HTMLElement) {
+                target.click();
+            }
+        }
+        const after = readChecked(target);
+        return { success: after === checked, kind, name, before, after };
+    }, desiredChecked);
+}
+async function collectToggleMatches(page, label, exact, controlType, contextText, sectionText) {
+    const matches = [];
     for (const frame of page.frames()) {
-        const result = await frame.evaluate((payload) => {
+        const candidates = frame.locator(TOGGLE_CONTROL_SELECTOR);
+        const metadata = await candidates.evaluateAll((elements, payload) => {
             function normalize(value) {
-                return value.replace(/\s+/g, ' ').trim().toLowerCase();
-            }
-            function matchesLabel(candidate) {
-                if (!candidate)
-                    return false;
-                const normalizedCandidate = normalize(candidate);
-                const normalizedNeedle = normalize(payload.label);
-                return payload.exact ? normalizedCandidate === normalizedNeedle : normalizedCandidate.includes(normalizedNeedle);
+                return (value ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
             }
             function visible(el) {
-                const rect = el.getBoundingClientRect();
-                if (rect.width <= 0 || rect.height <= 0)
+                if (!(el instanceof HTMLElement))
                     return false;
+                const rect = el.getBoundingClientRect();
                 const style = getComputedStyle(el);
-                return style.display !== 'none' && style.visibility !== 'hidden';
+                return rect.width > 0 && rect.height > 0 && style.display !== 'none' && style.visibility !== 'hidden';
+            }
+            function rootScopedElementById(owner, id) {
+                const root = owner.getRootNode();
+                if (root instanceof ShadowRoot)
+                    return root.getElementById(id);
+                if (root instanceof Document)
+                    return root.getElementById(id);
+                return null;
             }
-            function referencedText(ids, visited) {
+            function referencedText(owner, ids, visited) {
                 if (!ids)
                     return undefined;
                 const seen = visited ?? new Set();
-                const text = ids
-                    .split(/\s+/)
-                    .map(id => {
+                const text = ids.split(/\s+/).map(id => {
                     if (seen.has(id))
                         return '';
                     seen.add(id);
-                    const target = document.getElementById(id);
-                    if (!target)
+                    const node = rootScopedElementById(owner, id);
+                    if (!node)
                         return '';
-                    const chained = target.getAttribute('aria-labelledby');
-                    if (chained)
-                        return referencedText(chained, seen) ?? '';
-                    return target.textContent?.trim() ?? '';
-                })
-                    .filter(Boolean)
-                    .join(' ')
-                    .trim();
+                    return referencedText(node, node.getAttribute('aria-labelledby'), seen) ?? node.textContent?.trim() ?? '';
+                }).filter(Boolean).join(' ').trim();
                 return text || undefined;
             }
-            function controlKind(el) {
+            function kindOf(el) {
                 if (el instanceof HTMLInputElement) {
                     if (el.type === 'checkbox')
                         return 'checkbox';
@@ -5119,120 +6432,141 @@ export async function setCheckedControl(page, label, opts) {
                     return undefined;
                 }
                 const role = el.getAttribute('role');
-                if (role === 'switch' || role === 'checkbox')
-                    return 'checkbox';
                 if (role === 'radio')
                     return 'radio';
+                if (role === 'checkbox' || role === 'switch')
+                    return 'checkbox';
                 return undefined;
             }
-            function controlName(el) {
+            function nameOf(el) {
                 const aria = el.getAttribute('aria-label')?.trim();
                 if (aria)
                     return aria;
-                const labelledBy = referencedText(el.getAttribute('aria-labelledby'));
+                const labelledBy = referencedText(el, el.getAttribute('aria-labelledby'));
                 if (labelledBy)
                     return labelledBy;
                 if (el instanceof HTMLInputElement) {
-                    const labels = el.labels ? Array.from(el.labels) : [];
-                    for (const labelEl of labels) {
-                        const text = labelEl.textContent?.trim();
-                        if (text)
-                            return text;
-                    }
-                    const nameAttr = el.getAttribute('name')?.trim();
-                    if (nameAttr && /[A-Za-z]/.test(nameAttr) && /[\s,./()_-]/.test(nameAttr))
-                        return nameAttr;
+                    const labelText = Array.from(el.labels ?? []).map(label => label.textContent?.trim()).find(Boolean);
+                    if (labelText)
+                        return labelText;
+                    const name = el.getAttribute('name')?.trim();
+                    if (name && /[A-Za-z]/.test(name) && /[\s,./()_-]/.test(name))
+                        return name;
                 }
-                const text = el.textContent?.trim();
-                return text || undefined;
-            }
-            function readChecked(el) {
-                if (el instanceof HTMLInputElement)
-                    return !!el.checked;
-                return el.getAttribute('aria-checked') === 'true';
-            }
-            function clickTarget(el) {
-                if (el instanceof HTMLInputElement) {
-                    const labelEl = el.labels?.[0];
-                    if (labelEl instanceof HTMLElement)
-                        return labelEl;
-                }
-                return el instanceof HTMLElement ? el : null;
-            }
-            function dispatch(target) {
-                target.dispatchEvent(new Event('input', { bubbles: true }));
-                target.dispatchEvent(new Event('change', { bubbles: true }));
+                return el.textContent?.trim() || undefined;
             }
-            function clearReactTracker(target, next) {
-                const tracker = target._valueTracker;
-                if (tracker && typeof tracker.setValue === 'function') {
-                    try {
-                        tracker.setValue(String(!next));
-                        return true;
-                    }
-                    catch { /* ignore */ }
+            function nearestContext(el, name) {
+                const normalizedName = normalize(name);
+                let current = el.parentElement;
+                for (let depth = 0; current && depth < 6; depth++, current = current.parentElement) {
+                    if (current === document.body || current === document.documentElement)
+                        break;
+                    const text = (current.innerText || current.textContent || '').replace(/\s+/g, ' ').trim();
+                    if (text && normalize(text) !== normalizedName)
+                        return text;
                 }
-                return false;
-            }
-            function setInputCheckedReactAware(target, next) {
-                const hadReactTracker = clearReactTracker(target, next);
-                if (!hadReactTracker && target.checked === next)
-                    return true;
-                const descriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'checked');
-                if (descriptor?.set)
-                    descriptor.set.call(target, next);
-                else
-                    target.checked = next;
-                dispatch(target);
-                return target.checked === next;
-            }
-            const selector = 'input[type="checkbox"], input[type="radio"], [role="checkbox"], [role="radio"], [role="switch"]';
-            const candidates = Array.from(document.querySelectorAll(selector)).filter((el) => el instanceof HTMLElement && visible(el));
-            const target = candidates.find((el) => {
-                const kind = controlKind(el);
-                if (!kind)
-                    return false;
-                if (payload.controlType && kind !== payload.controlType)
-                    return false;
-                return matchesLabel(controlName(el));
-            });
-            if (!target) {
-                return { matched: false };
-            }
-            const kind = controlKind(target);
-            const name = controlName(target) ?? payload.label;
-            const before = readChecked(target);
-            if (kind === 'radio' && payload.checked === false) {
-                return { matched: true, success: before === false, reason: 'radio-uncheck', kind, name };
-            }
-            if (before !== payload.checked && !(target instanceof HTMLInputElement)) {
-                clickTarget(target)?.click();
+                return '';
             }
-            let after = readChecked(target);
-            if (target instanceof HTMLInputElement) {
-                setInputCheckedReactAware(target, payload.checked);
-                after = target.checked;
+            function nearestSection(el) {
+                const section = el.closest('fieldset, section, form, dialog, [role="group"], [role="radiogroup"], [role="region"], [role="dialog"]');
+                if (!(section instanceof HTMLElement))
+                    return '';
+                const explicit = section.getAttribute('aria-label')?.trim() ||
+                    referencedText(section, section.getAttribute('aria-labelledby')) ||
+                    section.querySelector('legend, h1, h2, h3, h4, h5, h6')?.textContent?.trim();
+                return (explicit || section.innerText || section.textContent || '').replace(/\s+/g, ' ').trim();
+            }
+            const needle = normalize(payload.label);
+            const contextNeedle = normalize(payload.contextText);
+            const sectionNeedle = normalize(payload.sectionText);
+            const result = [];
+            for (let index = 0; index < elements.length; index++) {
+                const element = elements[index];
+                if (!element)
+                    continue;
+                if (!visible(element))
+                    continue;
+                const kind = kindOf(element);
+                if (!kind || (payload.controlType && kind !== payload.controlType))
+                    continue;
+                const name = nameOf(element);
+                if (!name)
+                    continue;
+                const normalizedName = normalize(name);
+                const exactLabel = normalizedName === needle;
+                if (payload.exact ? !exactLabel : !normalizedName.includes(needle))
+                    continue;
+                const context = nearestContext(element, name);
+                const section = nearestSection(element);
+                if (contextNeedle && !normalize(context).includes(contextNeedle))
+                    continue;
+                if (sectionNeedle && !normalize(section).includes(sectionNeedle))
+                    continue;
+                result.push({ index, kind, name, exactLabel, contextText: context, sectionText: section });
             }
-            return {
-                matched: true,
-                success: after === payload.checked,
-                kind,
-                name,
-                before,
-                after,
-            };
-        }, { label, exact, checked: desiredChecked, controlType: controlType ?? null });
-        if (!result.matched)
-            continue;
-        if (result.success)
-            return;
-        if (result.reason === 'radio-uncheck') {
-            throw new Error(`setChecked: radio "${result.name}" cannot be unchecked directly; choose a different option instead`);
+            return result;
+        }, { label, exact, controlType: controlType ?? null, contextText: contextText ?? '', sectionText: sectionText ?? '' });
+        for (const candidate of metadata) {
+            matches.push({ ...candidate, locator: candidates.nth(candidate.index), frameUrl: frame.url() });
         }
-        throw new Error(`setChecked: matched ${result.kind} "${result.name}" but could not set it to ${String(desiredChecked)}`);
     }
-    const kindLabel = controlType ?? 'checkbox/radio';
-    throw new Error(`setChecked: no visible ${kindLabel} matching "${label}"`);
+    if (!exact) {
+        const exactMatches = matches.filter(match => match.exactLabel);
+        if (exactMatches.length > 0)
+            return exactMatches;
+    }
+    return matches;
+}
+/**
+ * Set a checkbox/radio by accessible label instead of brittle coordinate clicks.
+ * Helps custom form UIs that keep the real control opacity-hidden but still interactive.
+ */
+export async function setCheckedControl(page, label, opts) {
+    if (!label || label !== label.trim()) {
+        throw new Error('setChecked: label must be a trimmed, non-empty string');
+    }
+    if (opts?.contextText !== undefined && (!opts.contextText || opts.contextText !== opts.contextText.trim())) {
+        throw new Error('setChecked: contextText must be a trimmed, non-empty string when provided');
+    }
+    if (opts?.sectionText !== undefined && (!opts.sectionText || opts.sectionText !== opts.sectionText.trim())) {
+        throw new Error('setChecked: sectionText must be a trimmed, non-empty string when provided');
+    }
+    const exact = opts?.exact ?? false;
+    const desiredChecked = opts?.checked ?? true;
+    const controlType = opts?.controlType;
+    let target = null;
+    if (opts?.fieldKey) {
+        target = await findAuthoredFieldByKeyInPage(page, opts.fieldKey, 'toggle');
+        if (!target) {
+            throw new Error(`setChecked: fieldKey "${opts.fieldKey}" did not resolve to a visible checkbox/radio; refresh geometra_form_schema`);
+        }
+    }
+    if (!target) {
+        const matches = await collectToggleMatches(page, label, exact, controlType, opts?.contextText, opts?.sectionText);
+        if (matches.length === 0) {
+            const kindLabel = controlType ?? 'checkbox/radio';
+            const context = [opts?.contextText && `context "${opts.contextText}"`, opts?.sectionText && `section "${opts.sectionText}"`]
+                .filter(Boolean).join(' and ');
+            throw new Error(`setChecked: no visible ${kindLabel} matching "${label}"${context ? ` in ${context}` : ''}`);
+        }
+        if (matches.length > 1) {
+            const details = matches.slice(0, 5).map(match => `"${match.name}"${match.frameUrl ? ` in ${match.frameUrl}` : ''}`).join(', ');
+            throw new Error(`setChecked: ambiguous label "${label}" matched ${matches.length} controls (${details}); provide fieldKey, contextText, or sectionText`);
+        }
+        target = matches[0].locator;
+    }
+    await assertLocatorMutable(target, 'toggle', 'setChecked');
+    const result = await applyToggleState(target, desiredChecked);
+    if (result.success) {
+        await delay(40);
+        const persisted = await target.evaluate((el, desired) => (el instanceof HTMLInputElement ? el.checked : el.getAttribute('aria-checked') === 'true') === desired, desiredChecked).catch(() => false);
+        if (persisted)
+            return;
+    }
+    if (result.reason === 'radio-uncheck') {
+        throw new Error(`setChecked: radio "${result.name}" cannot be unchecked directly; choose a different option instead`);
+    }
+    throw new Error(`setChecked: matched ${result.kind} "${result.name}" but could not set it to ${String(desiredChecked)}`);
 }
 export async function wheelAt(page, deltaX, deltaY, x, y) {
     if (x !== undefined && y !== undefined && Number.isFinite(x) && Number.isFinite(y)) {