Files
archived-camoufox/docs/input-dispatch.md
T
Jake WriterandClaude Opus 5.5 4421005130 Let a late drag answer decide the drag; test both waits' bounds for real
The drag-finalize bound gave up after one deadline and called it no drag,
so a page busy for 10 to 30 s after dragstart lost its drop: the page saw
dragstart, mouseup and click instead of dragstart, drop and dragend. Main
dropped correctly, only late. The mousemove that starts a drag now keeps
its watcher, and the next mouse event waits a deadline for the answer
again; mouseup ends the gesture.

The APZ flush bound has a real trigger: killing the GPU process during a
burst of wheels stalls main until the 30 s slot backstop, every time. The
timed-out listener is removed, so a later flush cannot resume a dispatch
the chain has moved past, and the target's box is still measured after
the wait.

input-ack-backstop.py appends both scenarios to the existing one instead
of re-indenting it, and the preventDefault drag scenario, which could not
see the lost drop, is replaced.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 19:17:39 -06:00

5.2 KiB

Synthesized input dispatch

Every synthesized mouse and wheel event in the parent process goes through browser/additions/juggler/input/MouseDispatch.js. browser/scripts/check-input-dispatch.py fails the build if anything else dispatches input or does browser-relative coordinate arithmetic, and it runs on every pull request.

The invariant

A synthesized input event whose ack we await must reach the content renderer — and when it does not, we must stop waiting.

Why it is worth a module and a lint

Four deadlocks shipped between 2026-04 and 2026-09, all the same failure:

Date Commit Trigger
2026-06-04 9270618 x == width / y == height — the far edges
2026-07-18 541ffca trajectory points, which bypassed the endpoint's guard (#225, #677)
2026-07-24 16e5a13 a zero-displacement move
2026-09-03 014cc65 y == 0 — the near edge (#751, #752)

Each was fixed by adding one more coordinate guard at one more call site. That does not converge, for two reasons.

The trigger set is not enumerable. Whether relative y == 0 reaches the renderer is decided by Math.round(boundingBox.top) < boundingBox.top — a rounding accident in the fractional height of browser chrome, which varies with the spoofed OS: windows 51.4 → 51 deadlocks, macos 53.1 → 53 deadlocks, linux 56.5 → 57 is fine. No review catches that, and no hand-written list of coordinates contains it.

Every miss costs the whole process. activateAndRun() (TargetRegistry.js) serializes input on a promise chain shared by every tab in the process. It swallows errors to keep the chain running, but it cannot swallow a callback that never returns. One unbounded await for an ack that will never arrive wedges every later input event, in every tab, permanently — at 0% CPU, with nothing in flight and no diagnostic.

#677 is why review is not enough: restoring the humanize trajectory meant writing a bounds check, and the one written was a copy of the pre-#225 form, reintroducing a fixed deadlock one day before it was re-fixed.

How it is enforced

One chokepoint. MouseDispatch owns the relative→absolute conversion (with the boundary snap), the in-viewport predicate, and the ack wait. Callers pass relative coordinates and never see a bounding box.

A fresh rect. The browser rect is measured after the last await before the dispatch (apz-repaints-flushed), never before it. The chrome can change height during that wait — measured 2026-09-14: the nav-bar grew from 40 to 41 px about a second after startup when the (then forced) built-in theme was applied — and a rect taken before it put a relative y == 0 one row above the content: the event reached the renderer as an exit event at client y == -1, produced no ack, and the page saw no mousemove (~1 in 25 runs of near-edge-mouse-deadlock.py). Both dispatch sites (Page.dispatchMouseEvent, Page.dispatchWheelEvent) measure synchronously before dispatching.

Bounded waits. sendAcked() waits at most kAckDeadlineMs (5s) and then drops the event with a warning naming the type, coordinate and browser rect. The deadline is sized above the slowest legitimate ack, not near the typical one: acks are p99 1ms on an idle page, but they are delivered from the content main thread and inherit any block on it — a 3s synchronous script delayed one by 2849ms. sendTrajectoryAcked() abandons the rest of a curve after the first undelivered point, so the ~90 bounded waits a curve can hold — the 1.5s default humanize ceiling at 60Hz — cannot add up to an unbounded slot. It also refuses to dispatch a point on the pixel the previous dispatch left the cursor on: a zero-displacement move produces no eMouseMove, so it is never acked, and that is the same deadlock reached from inside a curve rather than from Page.dispatchMouseEvent. apz-repaints-flushed waits at most kAckDeadlineMs too: a flush sent to a GPU process that dies never comes back, and stalled every such dispatch until the backstop. So does the drag path's juggler-drag-finalized, per input event: an answer a busy page gives later still decides the next event, so the drag drops, and mouseup ends the wait. activateAndRun() carries a 30s backstop for the waits still unbounded in the same slot (TabSwitchDone, the drag path's dragover and cross-process sends), none of which has failed yet.

The static check. browser/scripts/check-input-dispatch.py, wired into the static job of .github/workflows/tests.yml. Two exemptions, both content-process: PageAgent.js (drag events, already content-relative, no ack) and FrameTree.js (the ack producer).

Boundary coverage. browser/tests/playwright/patches/mouse-boundary-sweep.py sweeps the whole viewport ring across every spoofed OS with humanize on and off, asserting each point is acked and observed by the page. Hand-picked coordinate lists are what let each of the four bugs through: humanize-edge-deadlock.py probed only the far edges, and humanize-mouse-trajectory.py pins os="linux" — the one fingerprint immune to #751. browser/tests/playwright/patches/input-ack-backstop.py covers the bounded waits themselves: a late renderer ack, and a drag whose page answers late.