Mobile "moderate" speculation-rules viewport heuristic controls

moderate_heuristics.md

"moderate" speculation rules eagerness proves very useful on desktop, but less so on mobile.

Chromium's current mobile heuristics are based on watching the viewport: when a link scrolls into view and looks like a plausible next click, the browser prefetches or prerenders it. This shipped in Chrome 138; there's more background in the blink-dev PSA.

"Looks like a plausible next click" comes down to three checks the browser runs each time the user stops scrolling. It looks at the links currently on screen and picks at most one of them:

1. Throw out links that are too far from where the user last tapped. Distance here is vertical, measured as a fraction of screen height, and there's a [low, high] band it has to fall inside.
2. Of what's left, take the largest link by visible area, but only if it's clearly bigger than the runner-up. Concretely, (size(largest) - size(second)) / size(second) has to clear a threshold. If the two biggest links are about the same size, the browser doesn't guess.
3. Wait a short delay before acting. If the user scrolls again during that delay, the candidate is dropped, so links that just whip past during a fling don't get prefetched.

We suspect that the current parameters for these heuristics can be improved on, and that providing developer control for those heuristic parameters can help tighten the feedback loop that can help us find improved values.

This document proposes a mechanism that will provide such (temporary and experimental) developer control.

Proposal

We propose that a rule set can carry an optional moderate_viewport_heuristics object at the top level, defining various viewport heuristic parameters:

<script type="speculationrules">
{
  "moderate_viewport_heuristics": {
    "distance_from_pointer_down": [-0.5, 0.2],
    "largest_anchor_threshold": 0.1,
    "delay": 200
  },
  "prefetch": [
    {
      "source": "document",
      "where": { "href_matches": "/*" },
      "eagerness": "moderate"
    }
  ]
}
</script>

Field	Type	What it does	Default	Clamped to
distance_from_pointer_down	[number, number]	The [low, high] band for a link's vertical distance from the last pointerdown, as a fraction of screen height. Links outside the band are dropped.	[-0.3, 0.0]	each end to [-1, 1]; high raised to at least low
largest_anchor_threshold	number	How much bigger (by visible area, as a fraction) the largest link has to be than the second largest before it's picked.	0.25	>= 0
delay	number	Milliseconds to wait after picking a candidate before acting on it.	500	0 to 5000

This rule-set wide configuration will define the heuristic, and will enable developers to experiment with their own heuristics and report back results.