Speculation Rules - moderate viewport heuristics controls

at a glance

why it exists

The moderate eagerness level of the Speculation Rules API has proved valuable on desktop — Shopify measured faster storefront navigations with it (Shopify engineering blog) — but less so on mobile, where “moderate” is driven by viewport heuristics that shipped in Chrome 138 (background in the blink-dev PSA). Those heuristics have fixed internal parameters, and the Chrome team suspects they “can be improved on”; giving developers temporary control over the parameters is meant to “tighten the feedback loop” that finds better values (explainer). The intent’s stated experimentation goal: “Allow developers to find and report back mobile-viewport heuristic values that work well for them and enable performance benefits from ‘moderate’ speculation rules” — Shopify is on the record as interested in experimenting (Intent to Experiment).

how it works: the viewport candidate-selection heuristic

On Android, when a document has document-source speculation rules with "eagerness": "moderate", Chrome watches the viewport and, each time the user stops scrolling, runs three checks against the links currently on screen and picks at most one candidate to prefetch or prerender:

1. Distance filter. Discard links whose vertical distance from the position of the user’s last pointerdown falls outside a [low, high] band, measured as a fraction of screen height. The compiled-in default band is [-0.3, 0.0] — the P12.5/P87.5 bounds of the middle 75% of distances observed for clicked anchors.
2. Dominance test. Of the remaining links, take the largest by visible area — but only if it is clearly bigger than the runner-up: (size(largest) − size(second)) / size(second) must exceed a threshold (default 0.25). If the two biggest links are about the same size, the browser does not guess.
3. Dwell delay. Wait a short delay (default 500 ms) before acting. If the user scrolls again during that window the candidate is dropped, so links that whip past during a fling never trigger speculation.

The moderate_viewport_heuristics object overrides exactly these three numbers for its document. Two gating layers sit between the JSON and the behavior: the heuristic runs only where the base mobile-heuristics feature (kPreloadingModerateViewportHeuristics) is active, and the author overrides are applied only when the SpeculationRulesModerateViewportHeuristicsControl origin trial is enabled for the document — checked in AnchorElementInteractionTracker::AnchorPositionsUpdated at the moment anchor positions update. The compiled defaults are themselves Finch feature parameters (distance_from_ptr_down_low/hi, largest_anchor_threshold, delay), so the effective default configuration can be adjusted server-side; the values above are the compiled defaults cited by the explainer.

lifecycle and application semantics

syntax

An optional top-level key of a speculation-rules rule set, alongside prefetch/prerender (the host grammar is defined by the Speculation Rules specification; this key is an experiment-only extension with no spec text):

{
  "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"
    }
  ]
}

All three fields are optional; unspecified fields keep the (Finch-adjustable) defaults. Malformed values and unknown sub-keys are ignored and never fail the rule set. Full per-field contracts: moderate_viewport_heuristics object reference.

examples

Opting a document into wider experimentation: allow links slightly above and further below the last tap, demand less size dominance, and act sooner:

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

A partial override — only the dwell delay changes; the other two parameters keep their defaults:

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

browser compatibility

Interim table. There is no BCD entry for this feature — BCD api/ has no SpeculationRules.json and no moderate_viewport_heuristics key anywhere (checked 2026-07-29) — and the webstatus.dev register covers only the host speculation-rules feature (Baseline limited). Rows below are compiled from the linked primary sources, not from BCD.

Non-supporting browsers degrade silently: unknown speculation-rules keys are ignored by design, so a rule set carrying moderate_viewport_heuristics still works everywhere the Speculation Rules API itself works — the controls simply have no effect outside the trial.

security and privacy

• Dwell-delay floor (privacy review). The author-specifiable delay is clamped to a minimum of 10 ms — the implementation comment records that “a nonzero floor is enforced (per privacy review) so that authors cannot configure the heuristic to fire essentially immediately” (anchor_element_interaction_tracker.cc). The explainer’s 0–5000 range predates or omits this floor; the implementation is authoritative.
• No new data leaves the device. The parameters only retune when and whether the browser issues its own speculative loads for links already present in the page; the destination of a speculative fetch is unchanged. The privacy-relevant surface remains the underlying prefetch/prerender behavior of the Speculation Rules API, not the controls.
• Third-party tokens are deliberate, not an accident. The flag record allows third-party origin-trial tokens “so that scripts injecting speculation rules cross-origin (e.g. performance libraries) can opt in”; parse-time gating was rejected precisely because a third-party token can arrive after parsing (speculation_rule_set.cc).
• Abuse ceiling is bounded. Even the most aggressive legal values cannot exceed the existing moderate-eagerness behavior class — at most one viewport candidate, only after a scroll stop, subject to the normal speculation-rules eligibility and user-preference constraints — and the experiment gathers parameter data, it does not relax any fetch-credential or cross-origin rules.
• Measurement caveat. Because the parameters change prefetch/prerender timing, experiments should be evaluated against the site’s own privacy policy for any resulting change in speculative-request volume; no storage, identifiers, or cross-session state are added by this feature itself.

specifications

see also

• moderate_viewport_heuristics object reference — per-field contracts (this site)
• Chrome Platform Status — Speculation Rules - moderate viewport heuristics controls (API record; tracking bug 529423512)
• blink-dev — Intent to Experiment (mail-archive mirror) and the API-owner LGTM (M152–M157)
• blink-dev PSA — Speculation rules: mobile “moderate” eagerness improvements (the Chrome 138 behavior this feature tunes)
• MDN — Speculation Rules API (the host API; MDN does not cover this controls object — zero matches for moderate_viewport_heuristics on the page and in MDN search, 2026-07-29)
• Chrome Platform Showcase — interactive demos for this feature
• Shopify engineering — Faster storefront navigations with moderate speculation rules
• Chrome origin trials console (trial SpeculationRulesModerateViewportHeuristicsControl)