# WO-03: Expose real, actionable browser controls

Status: complete — integrated and verified offline

## Anchors

- `packages/execution/src/tools/dom-summary.ts`: live DOM collection and legacy
  HTML downsampling fallback.
- `packages/execution/src/tools/playwright-browser.ts`: `dom_summary`,
  `query_all`, strict selector handling and runtime browser observations.

## Acceptance

- [x] Browser summaries describe actual DOM controls and exclude script/template
  markup, including the observed literal `${downloadButton}` false control.
- [x] Icon controls expose accessible labels, role, useful target attributes,
  visibility/state, and bounded parent/item context.
- [x] Observations provide usable scoped selectors or explicit selector/index
  pairs; repeated Download controls remain distinguishable.
- [x] Preserve strict interaction targeting instead of guessing among matches.
- [x] Observation results stay bounded and do not require a vision-model call.
- [x] Tests include icon buttons, script templates, duplicate controls, hidden
  controls, and escaped target identifiers.

## Implementation and verification

Playwright `dom_summary`, `query_all`, and lifecycle bundles now inspect real
locator matches in one browser evaluation. They return bounded accessible-name
hints, roles, state, target attributes, item context, and exact selector/index
pairs. Names use ARIA references/labels, HTML labels, alt/title and SVG title;
this is a compact observation, not a replacement for the full accessibility tree.

`scope` must identify one container. `offset`/`limit` bound observations, with an
additional 20 KB element-data budget. Hidden controls are excluded by default;
`include_hidden` opts in. Indices always refer to the original complete locator,
so filtering hidden controls cannot redirect an action. Strict actions continue
to reject ambiguity. An explicit index no longer waits on a hidden first match.

The legacy HTML transport used by `browser_action` removes script, style,
noscript, template and comment bodies before downsampling, and improves icon
labels and attribute-selector escaping. Playwright no longer uses that fallback.

Validation: 23 tests passed across `dom-summary`, `playwright-browser-observation`,
`playwright-browser-contract`, and `playwright-browser-cancellation`; execution
TypeScript build passed. Tests use synthetic DOM and mocked Playwright sessions;
no active browser, live model, GPU workload, or Telegram transport was touched.

Final integrated execution validation passes 76 checks, including these
observations, native downloads and desktop input. The download commit also
keeps an out-of-range index from waiting unnecessarily while preserving the
hidden-first-match repair.
