You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Headless can inspect native <select> controls but does not advertise or execute a selection action. Agents must fall back to fragile key presses, and the current inspection contract deliberately omits a nonexistent select hint.
Contract
Add a portable select command for native, single-selection HTML <select> elements:
headless --session qa select@e4 --label "Canada"
headless --session qa select--role combobox --name Country --value CA
Reuse the existing target grammar: exactly one element ref or semantic role/name target.
Require exactly one option matcher: --label or --value.
Match option labels after the runtime's existing whitespace normalization; match option values exactly.
Require exactly one matching option. Missing or ambiguous matches fail without changing selection.
Dispatch input followed by change only after validation and mutation succeed.
Return bounded target metadata and selected option index, but do not echo page option labels or values.
Mark page-derived output untrusted.
Do not add select to recorded flows in this change.
Custom ARIA comboboxes, listboxes, multi-select, hover, drag, and arbitrary evaluation remain out of scope.
Engine behavior
Both engines use the fixed isolated-world runtime operation because there is no portable native menu API with equivalent behavior. Add a separate selectDispatch: synthetic-dom capability so Chromium's existing inputDispatch: trusted-cdp claim remains accurate for click, fill, and press.
Required changes
Record the contract in docs/roadmap/architecture-decisions.md before changing behavior.
Add command enum, validator, CLI parser/help, protocol schema/result, HostCore dispatch, and both engine adapters.
Add the isolated runtime operation and advertise select only for eligible native single-select controls.
Parser and protocol tests for target conflicts, matcher exclusivity, bounds, and generated-schema drift.
Runtime tests for ref and semantic targeting, label/value selection, event order, stale refs, and every no-mutation rejection path.
macOS and Linux E2E tests using a real native select, including one happy path and representative disabled, ambiguous, multi-select, and custom-combobox failures.
Capability tests proving both engines declare synthetic select dispatch.
Definition of done
All protocol, runtime, SDK, web, macOS, and Linux E2E gates pass; docs and generated contracts are current; no unsupported control is advertised as selectable.
Parent: #35
Problem
Headless can inspect native
<select>controls but does not advertise or execute a selection action. Agents must fall back to fragile key presses, and the current inspection contract deliberately omits a nonexistentselecthint.Contract
Add a portable
selectcommand for native, single-selection HTML<select>elements:--labelor--value.multipleselects, disabled selects, disabled options, and options inside disabled optgroups.inputfollowed bychangeonly after validation and mutation succeed.selectto recorded flows in this change.Custom ARIA comboboxes, listboxes, multi-select, hover, drag, and arbitrary evaluation remain out of scope.
Engine behavior
Both engines use the fixed isolated-world runtime operation because there is no portable native menu API with equivalent behavior. Add a separate
selectDispatch: synthetic-domcapability so Chromium's existinginputDispatch: trusted-cdpclaim remains accurate for click, fill, and press.Required changes
docs/roadmap/architecture-decisions.mdbefore changing behavior.selectonly for eligible native single-select controls.Tests
Definition of done
All protocol, runtime, SDK, web, macOS, and Linux E2E gates pass; docs and generated contracts are current; no unsupported control is advertised as selectable.