@geometra/proxy 1.64.0 → 1.65.1

package/dist/dom-actions.js

@@ -1,5 +1,5 @@
-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));
@@ -436,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;
@@ -576,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();
@@ -586,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)
@@ -603,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) &&
@@ -612,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;
@@ -769,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
@@ -811,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();
@@ -835,17 +945,88 @@ 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
         ? 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;
@@ -915,6 +1096,7 @@ function displayedValueMatchesSelection(candidate, expected, exact, selectedOpti
 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);
@@ -1015,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;
@@ -1655,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 });
         }
@@ -1839,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.
@@ -2546,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.
@@ -2576,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;
@@ -2611,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);
     }
@@ -2648,143 +2859,224 @@ 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 normalize(value) {
-            return value.replace(/\s+/g, ' ').trim().toLowerCase();
+        function referencedText(owner, ids) {
+            if (!ids)
+                return '';
+            return ids
+                .split(/\s+/)
+                .map(id => rootScopedElementById(owner, id)?.textContent?.trim() ?? '')
+                .filter(Boolean)
+                .join(' ')
+                .trim();
         }
-        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);
+        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();
+        }
+        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')
+        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 true;
+    }, { contextText: contextText ?? '', sectionText: sectionText ?? '' }).catch(() => false);
+}
+async function findScopedFileInputsInPage(page, fieldLabel, exact, contextText, sectionText) {
+    const exactMatches = [];
+    const fuzzyMatches = [];
+    const expected = normalizedOptionLabel(fieldLabel);
+    for (const frame of page.frames()) {
+        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;
-            if (matches(explicitLabelText(el)))
-                return i;
+            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 -1;
-    }, { fieldLabel, exact });
-    return bestIndex >= 0 ? loc.nth(bestIndex) : null;
+    }
+    return exactMatches.length > 0 ? exactMatches : fuzzyMatches;
 }
-async function findLabeledFileInputInPage(page, fieldLabel, exact, cache, fieldId, fieldKey) {
-    const cached = await readCachedLocator(cache, 'file', fieldLabel, exact, fieldId, fieldKey);
-    if (cached !== undefined)
+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) {
-            writeCachedLocator(cache, 'file', fieldLabel, exact, fieldId, fieldKey, 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}"`);
+                }
+            }
+            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`);
     }
+    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) {
-        for (const frame of page.frames()) {
-            const locator = await findLabeledFileInput(frame, fieldLabel, exact);
-            if (!locator)
-                continue;
+        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;
         }
@@ -2792,58 +3084,364 @@ async function findLabeledFileInputInPage(page, fieldLabel, exact, cache, fieldI
     writeCachedLocator(cache, 'file', fieldLabel, exact, fieldId, undefined, null);
     return null;
 }
-async function attachHiddenInAllFrames(page, paths, opts) {
-    if (opts?.fieldLabel || opts?.fieldKey) {
-        const labeled = await findLabeledFileInputInPage(page, opts.fieldLabel ?? '', opts.exact ?? false, opts.cache, opts.fieldId, opts.fieldKey);
-        if (labeled) {
+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 {
-                /* fall through to uncached scan */
+            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;
             }
+            return false;
         }
-    }
-    for (const frame of page.frames()) {
-        if (opts?.fieldLabel) {
-            const labeled = await findLabeledFileInput(frame, opts.fieldLabel, opts.exact ?? false);
-            if (!labeled)
-                continue;
-            try {
-                await labeled.setInputFiles(paths);
-                return true;
+        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})`);
             }
-            catch {
-                /* try next frame */
+        };
+        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})`);
             }
-            continue;
+            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, setFiles = async (selectedPaths) => handle.setInputFiles(selectedPaths)) {
+    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 setFiles(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();
+    try {
+        await commitFilesToExactInput(input, paths, 'chooser input', async (selectedPaths) => {
+            await chooser.setFiles(selectedPaths);
+        });
+    }
+    finally {
+        // Playwright transfers ownership of this ElementHandle to the file-chooser
+        // listener. Release it on success and every preflight/error path.
+        await input.dispose().catch(() => { });
+    }
 }
 /**
  * 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() ?? '';
@@ -2851,7 +3449,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':
@@ -2859,9 +3470,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.
  *
@@ -2879,91 +3557,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');
         }
-    }, { bufs: buffers.map(b => Array.from(b)), ns: names, ms: mimes, x: dropX, y: dropY });
+        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');
+        }
+    }
+    finally {
+        await dropFileInput?.dispose().catch(() => { });
+    }
 }
 /**
  * `strategy`:
@@ -2977,7 +3824,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"]');
@@ -3001,15 +3849,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';
@@ -3019,6 +3870,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');
@@ -3032,6 +3928,8 @@ export async function attachFiles(page, paths, opts) {
             fieldKey: opts?.fieldKey,
             fieldLabel,
             exact,
+            contextText: opts?.contextText,
+            sectionText: opts?.sectionText,
             cache: opts?.cache,
         }))
             return;
@@ -3043,9 +3941,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) {
@@ -3059,6 +3958,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) {
@@ -3067,15 +3972,7 @@ 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, fieldKey) {
     const cached = await readCachedLocator(cache, 'editable', fieldLabel, exact, fieldId, fieldKey);
@@ -3197,20 +4094,75 @@ async function locatorCurrentValue(locator) {
 function normalizedFieldValue(value) {
     return value.replace(/\s+/g, ' ').trim().toLowerCase();
 }
-function fieldValueMatches(actual, expected) {
+function fieldValueMatches(actual, expected, inputType) {
     if (!actual)
         return false;
     const normalizedActual = normalizedFieldValue(actual);
     const normalizedExpected = normalizedFieldValue(expected);
     if (!normalizedActual || !normalizedExpected)
         return false;
-    return normalizedActual === normalizedExpected || normalizedActual.includes(normalizedExpected);
+    if (inputType?.toLowerCase() === 'tel') {
+        const actualDigits = normalizedActual.replace(/\D/g, '');
+        const expectedDigits = normalizedExpected.replace(/\D/g, '');
+        return actualDigits.length > 0 && actualDigits === expectedDigits;
+    }
+    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
@@ -3416,7 +4368,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();
@@ -3426,12 +4428,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)
@@ -3443,7 +4445,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) &&
@@ -3452,7 +4454,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;
@@ -3505,6 +4510,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;
@@ -3664,6 +4671,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);
@@ -3671,7 +4680,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))
@@ -3680,7 +4689,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;
@@ -3692,8 +4701,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);
@@ -3702,7 +4715,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;
             }
@@ -3762,13 +4775,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');
@@ -3785,6 +4802,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)
@@ -3803,6 +4822,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;
@@ -3818,6 +4839,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;
@@ -4105,6 +5128,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,
@@ -4310,6 +5336,7 @@ export async function setFieldText(page, fieldLabel, value, opts) {
     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)
@@ -4321,6 +5348,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);
         }
@@ -4331,19 +5359,66 @@ export async function setFieldText(page, fieldLabel, value, opts) {
             });
         }
     }
+    await delay(40);
     const current = await locatorCurrentValue(locator);
-    if (fieldValueMatches(current, normalized))
+    if (fieldValueMatches(current, normalized, inputType))
         return;
     const displayed = await locatorDisplayedValues(locator);
-    if (displayed.some(candidate => fieldValueMatches(candidate, normalized)))
+    if (displayed.some(candidate => fieldValueMatches(candidate, normalized, inputType)))
         return;
     throw new Error(`setFieldText: set "${fieldLabel}" but could not confirm value ${JSON.stringify(value)}`);
 }
 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);
             const enabled = (candidate) => !candidate.disabled && !(candidate.parentElement instanceof HTMLOptGroupElement && candidate.parentElement.disabled);
@@ -4372,7 +5447,8 @@ async function setNativeSelectByLabel(locator, value, exact, optionIndex) {
             el.selectedIndex = option.index;
             el.dispatchEvent(new Event('input', { bubbles: true }));
             el.dispatchEvent(new Event('change', { bubbles: true }));
-            return true;
+            await new Promise(resolveTimer => setTimeout(resolveTimer, 40));
+            return el.selectedIndex === option.index && el.selectedOptions[0] === option;
         }, { value, exact, optionIndex });
     }
     catch {
@@ -4394,6 +5470,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);
@@ -4408,7 +5524,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();
@@ -4418,12 +5542,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)
@@ -4435,7 +5559,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) {
@@ -4469,7 +5593,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;
@@ -4547,6 +5671,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;
@@ -4573,6 +5699,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.
@@ -4580,6 +5708,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';
                     }
@@ -4589,6 +5719,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) {
@@ -4710,6 +5842,7 @@ export async function setFieldChoice(page, fieldLabel, value, opts) {
         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, opts?.optionIndex)) {
@@ -4848,6 +5981,8 @@ export async function fillFields(page, fields, cache = createFillLookupCache())
                     fieldId: field.fieldId,
                     fieldKey: field.fieldKey,
                     fieldLabel: field.fieldLabel,
+                    contextText: field.contextText,
+                    sectionText: field.sectionText,
                     exact: field.exact,
                     cache,
                 });
@@ -4885,71 +6020,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) => {
+            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;
-                const indexed = sel.options[i];
-                if (indexed.disabled || (indexed.parentElement instanceof HTMLOptGroupElement && indexed.parentElement.disabled))
-                    return false;
-                if (payload.value !== null && normalize(indexed.value) !== normalize(payload.value))
-                    return false;
-                if (payload.label !== null && !normalize(indexed.textContent).includes(normalize(payload.label)))
-                    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 &&
-                    !(selected.parentElement instanceof HTMLOptGroupElement && selected.parentElement.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.selectedIndex = found.index;
-                }
-            }
-            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.selectedIndex = optEl.index;
-            }
-            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,
@@ -4966,6 +6076,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;
@@ -4991,16 +6118,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, opts.fieldKey);
+            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,
             }));
@@ -5020,6 +6147,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);
@@ -5036,19 +6167,20 @@ export async function pickListboxOption(page, label, opts) {
         // 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;
@@ -5145,10 +6277,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;
             }
@@ -5183,7 +6317,15 @@ export async function pickListboxOption(page, label, opts) {
 }
 async function applyToggleState(locator, desiredChecked) {
     return await locator.evaluate((target, checked) => {
-        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();
@@ -5191,10 +6333,10 @@ async function applyToggleState(locator, desiredChecked) {
                 if (seen.has(id))
                     return '';
                 seen.add(id);
-                const node = document.getElementById(id);
+                const node = rootScopedElementById(owner, id);
                 if (!node)
                     return '';
-                return referencedText(node.getAttribute('aria-labelledby'), seen) ?? node.textContent?.trim() ?? '';
+                return referencedText(node, node.getAttribute('aria-labelledby'), seen) ?? node.textContent?.trim() ?? '';
             }).filter(Boolean).join(' ').trim();
             return text || undefined;
         }
@@ -5207,7 +6349,7 @@ async function applyToggleState(locator, desiredChecked) {
             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) {
@@ -5272,7 +6414,15 @@ async function collectToggleMatches(page, label, exact, controlType, contextText
                 const style = getComputedStyle(el);
                 return rect.width > 0 && rect.height > 0 && style.display !== 'none' && style.visibility !== 'hidden';
             }
-            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();
@@ -5280,10 +6430,10 @@ async function collectToggleMatches(page, label, exact, controlType, contextText
                     if (seen.has(id))
                         return '';
                     seen.add(id);
-                    const node = document.getElementById(id);
+                    const node = rootScopedElementById(owner, id);
                     if (!node)
                         return '';
-                    return referencedText(node.getAttribute('aria-labelledby'), seen) ?? node.textContent?.trim() ?? '';
+                    return referencedText(node, node.getAttribute('aria-labelledby'), seen) ?? node.textContent?.trim() ?? '';
                 }).filter(Boolean).join(' ').trim();
                 return text || undefined;
             }
@@ -5306,7 +6456,7 @@ async function collectToggleMatches(page, label, exact, controlType, contextText
                 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) {
@@ -5336,7 +6486,7 @@ async function collectToggleMatches(page, label, exact, controlType, contextText
                 if (!(section instanceof HTMLElement))
                     return '';
                 const explicit = section.getAttribute('aria-label')?.trim() ||
-                    referencedText(section.getAttribute('aria-labelledby')) ||
+                    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();
             }
@@ -5419,9 +6569,14 @@ export async function setCheckedControl(page, label, opts) {
         }
         target = matches[0].locator;
     }
+    await assertLocatorMutable(target, 'toggle', 'setChecked');
     const result = await applyToggleState(target, desiredChecked);
-    if (result.success)
-        return;
+    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`);
     }