# The Upload Button Was in Another Document

*2026-08-26*

The file input was plainly visible in Chrome. Our async browser could not find
it.

This is an easy failure to misread during an async migration. The locator call
looks familiar, the selector is correct, and the old browser uploads the file.
It is tempting to blame a missing `await`. The actual problem was spatial: the
editor lived in an iframe, so the control belonged to another document.

The synchronous browser had already learned this lesson. It filtered the page's
frames by URL or name, counted matching controls across those frames, and treated
the caller's index as a position in that combined list. A quick async port that
searched only the main page would keep the same method name while quietly
changing which pages it could operate.

## The chooser made the race visible

Direct file inputs are forgiving. Playwright can set files on a hidden input
without opening the operating-system picker. Upload buttons are less forgiving:
the browser emits a file-chooser event only as a consequence of the click. The
listener must exist before the click, the event must be awaited afterward, and
only then can the selected files be set.

That sequence forced the real design into view. Frame selection was not a detail
inside one upload method; it was the routing boundary shared by scripts, direct
inputs, and chooser-trigger controls. We introduced one frame enumeration path
that preserves the old filters and global match order. Each async operation then
awaits its own locator, evaluation, chooser, post-upload wait, and context save.

We also stopped at an important edge. Selector clicking in the supported browser
is humanized. Porting it as a raw locator click would have made the checklist look
more complete while changing observable behavior. That work remains with the
humanized-input boundary.

## Make the browser prove where the file went

Mocks can prove that methods were awaited and error strings stayed stable. They
cannot prove that Chrome delivered a chooser event from a child frame.

The native acceptance page therefore contains a named iframe with two upload
paths. The test runs a local script inside that frame, sets one file input
directly, then clicks a button wired to a second hidden input. It reads both
selected filenames back from the frame's DOM. We run the same scenario once from
the source tree and once from an installed wheel.

The lesson is broader than uploads: async parity is not a count of converted
methods. It is preservation of time and place—when a listener begins waiting,
which document receives an operation, and when success is safe to report.