moderate_viewport_heuristics

syntax

Formal position: a top-level member of the rule-set object, a sibling of prefetch, prerender, and tag — not a member of any individual rule:

rule-set = {
  "moderate_viewport_heuristics": {
    "distance_from_pointer_down": [ low, high ],   // optional; two numbers
    "largest_anchor_threshold": number,            // optional
    "delay": milliseconds                          // optional; number
  },                                // ^ the whole object is optional
  "prefetch": [ … ],   // and/or "prerender"
}

The key is valid in inline <script type="speculationrules"> blocks and in external rule sets fetched via Speculation-Rules headers alike — parsing happens in the shared rule-set parser (speculation_rule_set.cc), which makes no inline/external distinction for this key.

distance_from_pointer_down

largest_anchor_threshold

delay

parse and error semantics

The object is parsed unconditionally — including in documents with no origin-trial token — so that a third-party token registered after parsing can still take effect on the next heuristic run without a re-parse; effectiveness is gated separately at application time. Error handling is deliberately forgiving, and the implementation comment states the design rule explicitly: unknown sub-keys and malformed values are ignored; they never cause the whole rule set to fail.

context and exposure

• Where it applies. Documents that contain document-source speculation rules with "eagerness": "moderate", on Android, with the SpeculationRulesModerateViewportHeuristicsControl origin trial enabled. It does not affect desktop hover-based heuristics, other eagerness levels (immediate, eager, conservative), or list rules (explicit urls), none of which use the viewport candidate picker.
• Inline and external rule sets. Parsed by the shared rule-set parser, so the key works in inline <script type="speculationrules"> blocks and external rule-set resources alike.
• Prerequisite base behavior. The viewport heuristic itself must be active on the device (the base kPreloadingModerateViewportHeuristics feature behind the Chrome 138 mobile behavior); the overrides layer onto its configuration, they do not enable it.
• Third-party contexts. First- and third-party origin-trial tokens both enable the override application, by design, so injected rule sets from performance libraries can participate.

lifecycle

1. Parse (page load / rule-set insertion): the object is read into an optional per-rule-set params struct; malformed fields are dropped here, but nothing is clamped or applied yet and no metric is recorded.
2. Selection (document level): when the heuristic needs the configuration, the document consults its rule sets in order and uses the first rule set that carries the object; objects on later rule sets are ignored (no merging), a deliberate simplification for an experiment-only mechanism.
3. Application (each scroll stop): if and only if the origin trial is enabled for the document, the params are clamped and layered onto the default config; the use counter kSpeculationRulesModerateViewportHeuristicsControl is recorded at this point so the metric reflects params that actually took effect.
4. Action: the retuned distance filter, dominance test, and dwell delay govern the next candidate pick; the candidate dies if the user scrolls during the delay, and the delay timer resets on new position updates.
5. Teardown: nothing persists — params live and die with the document’s rule sets; navigating away discards all state.

examples

All three fields set (the explainer’s proposal example):

<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>

Conservative experiment — only admit links nearly level with the tap, require a clear size winner, wait longer:

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

Two rule sets — demonstrating first-wins: the second object is ignored, so delay stays 300, not 900:

<script type="speculationrules">
{
  "moderate_viewport_heuristics": { "delay": 300 },
  "prefetch": [ { "source": "document", "where": { "href_matches": "/*" }, "eagerness": "moderate" } ]
}
</script>
<script type="speculationrules">
{
  "moderate_viewport_heuristics": { "delay": 900 },
  "prerender": [ { "source": "document", "where": { "href_matches": "/checkout/*" }, "eagerness": "moderate" } ]
}
</script>

compatibility

security and privacy

• The delay floor of 10 ms exists “per privacy review” so the heuristic cannot be configured to fire essentially immediately (anchor_element_interaction_tracker.cc).
• The parameters influence only the timing and selectivity of speculative loads the browser would be eligible to perform anyway; they introduce no new request destinations, credentials, storage, or identifiers.
• Third-party trial tokens are an explicit design decision to accommodate cross-origin performance libraries (runtime flag record); the parse-anywhere/apply-under-token split exists so such libraries cannot silently change behavior before their token registers (speculation_rule_set.cc).
• Malformed content fails closed: it is ignored, leaving conservative defaults (speculation_rule_set.cc).