How to sync eye-tracking data with DOM events?

WHY IT EXISTS: Eye-tracking research needs to correlate what users look at with what they do. Latency from fixation to interaction is a key metric; longer latency suggests the element is hard to find or parse. But gaze trackers and browsers timestamp events independently, often on different clocks.

THE MENTAL MODEL: Two asynchronous streams: (a) gaze points (x, y, timestamp) at 30-60 Hz from the tracker, (b) DOM events (click, focus, etc.) from the browser. Both need a shared clock and spatial mapping. When a gaze point lands on a button's bounding box, start a timer. When the click fires, record the elapsed time.

HOW IT WORKS: Instrument the page: instrument() each interactive element (button, link, form input) to expose its bounding box and fire custom events (e.g., onGazeEnter, onGazeExit) when gaze enters/exits. Receive gaze data from the tracker via WebSocket or a callback; each point includes (x, y, timestamp, confidence). On each gaze point, look up its DOM element via elementFromPoint or a spatial index. If the element differs from the last one, emit onGazeExit from the old element and onGazeEnter from the new. Simultaneously, listen for native click events. When a click fires and the element matches a recent gaze target, compute the time delta and log the record. Synchronization: use the tracker's system time as the source of truth. If the tracker and browser clocks drift, estimate drift by correlating a few manual calibration events (user clicks a target while looking at it) and applying a linear correction to gaze timestamps.

WHEN IT MATTERS: UX research, usability studies, and accessibility testing all rely on this correlation. Long fixation-to-click times can indicate cognition overhead (user confused) or motor delay (accessibility issue). Eye-tracking dashboards often surface these metrics.

ONE CONCRETE EXAMPLE: A form with a "Submit" button. Gaze tracker logs fixations on the button starting at t=5000ms. Click event fires at t=5300ms. Time from first fixation to click: 300ms. If baseline is 200ms (other buttons), this suggests the button is slightly harder to locate or understand, warranting A/B testing of its label or position.