Skip to content

C7: add semantic native select command #206

Description

@SarthakWade

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 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.
  • Reject non-native controls, multiple selects, disabled selects, disabled options, and options inside disabled optgroups.
  • 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.
  • Regenerate TypeScript and Python SDK contracts.
  • Update command docs, phase docs, skill references, and the C7 backlog entry without closing C7 — Design review for deferred command ideas (hover, drag, select, isolation) #35 while hover and drag remain open.

Tests

  • 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:cliCLI parser, help, capabilitiesarea:core-protocolHeadlessProtocol: wire protocol, validation, transportbacklogTracked in docs/roadmap/improvements-backlog.mdpriority:lowNice to havestatus:needs-designRequires an architecture-decision entry firsttype:featureNew capability or command

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions