Module scroll 

Scroll verification and the AX scroll-bar fallback. Pure: no events are posted, no Accessibility call is made, and no clock is read from here.

A scroll-wheel CGEvent posted with CGEventPostToPid is not delivered to the views of a non-frontmost app, so a posted event is not proof of a scroll. The event tier reads the AXScrollArea scroll bar before and after the post, and this module turns that measurement into a decision: the wheel event worked, the AX scroll-bar fallback should run, the bar is already at its limit, or nothing could be verified at all.

The per-line step size is computed from the ratio between the content height (the document child of the AXScrollArea) and the visible height (the scroll area itself, minus the orthogonal scroll bar). One wheel notch is roughly three text lines, so a notch is LINE_POINTS points; the math in content_step divides that by the content-overflow (content - visible) and clamps to 0..=1 so a wheel line never jumps the whole bar.

Every function here is pure so the same tests run on macOS, Windows, and Linux. The macOS backend owns the Accessibility calls (src/backend/macos/scroll_ax.rs); Windows and Linux scroll through their own foreground or portal paths and do not use this module.

Structs

Outcome

What a scroll actually did, in the shape the response carries.

Step

The per-line fraction (and the warnings from sizing it) the AX scroll-bar fallback uses.

Enums

AxCause

Why the AX scroll-bar path is running.

AxFailure

Why an AX scroll-bar fallback could not finish.

Axis

One axis of a scroll bar.

Decision

What comparing the bar before and after the wheel event means.

Via

Which mechanism produced the scroll.

Constants

APPROXIMATED_WARNING

Warning text when the scroll area has no measured AXSize for either the scroll area itself or its document child, so the per-line step falls back to the legacy five-percent approximation.

AX_FALLBACK_WARNING

Warning text when the wheel event did nothing and AXValue was written.

CONTENT_FITS_WARNING

Warning text when the document’s content fits inside the visible viewport, so a scroll is not possible and the per-line step is 0.0.

DEFAULT_STEP

Value step per wheel line when the content sizing data could not be read.

EPSILON

Two scroll-bar values closer than this are the same value.

LINE_POINTS

One wheel-line in points.

MAX_STEP

Largest step per wheel line. One wheel line never jumps the whole bar.

MIN_STEP

Smallest step per wheel line. Below this a write would not visibly move.

ROUNDING_TOLERANCE

How far a read-back value may sit from the requested value before the outcome notes that the app landed somewhere else. An app that snaps to its own page is still a scroll; it just did not land where we asked.

Functions

at_limit

True when a bar at value cannot scroll steps further.

ax_delta

Signed value delta for steps wheel lines using step. Positive is down or right.

ax_result

The outcome of writing AXValue, or the reason it failed.

content_step

The per-line scroll step computed from the document content’s size along the scroll axis and the visible viewport’s size along the same axis.

decide

Decide what the measurement means.

moved

True when the two readings differ by more than EPSILON.

next_value

The clamped value to write for steps wheel lines from before.