---
slug: speculative-navigation-pipeline
type: concept
summary: "Chromium's browser-managed path for preparing a future document navigation before user commitment, through Speculation Rules prefetch, prerender, activation, cancellation, and diagnostic status."
created: 2026-06-20
updated: 2026-06-20
last_link_verified: 2026-06-20
related:
  navigation-commit-pipeline:
    relation: complements
    note: "A prerender activation enters the navigation state machine at a different point from an ordinary network load, so speculative navigation is a distinct path into commit."
  bfcache-gate:
    relation: contrasts-with
    note: "BFCache restores a past document from history; speculative navigation prepares a future document before the user chooses it."
  rail-performance-model:
    relation: supports
    note: "The user-visible payoff is lower response and load latency for likely next navigations, especially when activation replaces network and rendering work."
  url-loader-factory:
    relation: uses
    note: "Prefetch and prerender requests still carry browser-owned network authority, isolation state, cookies, and request headers through the URLLoaderFactory boundary."
  feature-flag-guarding:
    relation: supports
    note: "New speculation-rule behaviors reach users through flags, origin trials, and staged rollout because cancellation and side-effect behavior affect real sites."
  intent-ship-pipeline:
    relation: informed-by
    note: "Speculation Rules prerendering and related extensions have public Intent records that describe compatibility risk, delayed side effects, and activation semantics."
---

# Speculative Navigation Pipeline

> **Concept**
>
> Vocabulary that names a phenomenon.

*Chromium's browser-managed path for preparing a future document navigation before the user commits to it, then activating, cancelling, or diagnosing the prepared load when the prediction meets reality.*

The fastest navigation is the one the browser has already prepared. Speculative navigation is the name for Chromium's path that makes that possible: a future document is fetched, or fetched and rendered in a hidden renderer, before the click, tap, or address-bar choice. It isn't BFCache, because it prepares the future rather than restoring the past. It isn't ordinary HTTP cache prefetch, because prerender can run a full hidden document that later becomes visible by activation.

## What It Is

Speculative navigation is Chromium's pipeline for acting on a likely next document navigation before the user commits to it. The project exposes the author-facing trigger as the **Speculation Rules API**: a page may include a JSON rule set in `<script type="speculationrules">` that names candidate document URLs and asks the browser to prefetch or prerender them. Chromium may also start browser-initiated prerenders, such as predictions from the address bar, when browser-side signals say a destination is likely.

The pipeline has two main modes. **Prefetch** requests the destination document and places the response where a later navigation can use it. **Prerender** goes further: Chromium creates a hidden page, loads the document, runs much of its rendering work, and holds it for activation. Activation swaps that prepared document into view when the user's real navigation matches.

That hidden state is not an active page in the ordinary sense. A prerendered document reports `document.prerendering`, records its activation timing through `PerformanceNavigationTiming.activationStart`, and fires `prerenderingchange` when it becomes visible. APIs whose effects would surprise the user, leak state, or interact with the outside world may be delayed, denied, or treated as cancellation reasons. A page may load early, but it must not behave as though the user has already arrived.

At the browser layer, the path runs through preloading and prerender infrastructure rather than through the ordinary navigation path from the start. The `PrerenderHostRegistry` tracks prerender hosts, matches a real navigation to a prepared host, activates the match, or records why the attempt failed.

Request metadata is part of the contract. Chrome sends `Sec-Purpose: prefetch` for Speculation Rules prefetch and `Sec-Purpose: prefetch;prerender` for prerender, so servers can distinguish a speculative request from a user-committed one. The header does not make an unsafe endpoint safe. It makes the early request visible, which is why speculative navigation depends on idempotent document loads and careful side-effect discipline.

## Why It Matters

Speculative navigation changes where the latency is paid. In an ordinary navigation, the user commits first and then waits for DNS, connection setup, request handling, response bytes, parsing, script, layout, paint, and commit. In a successful prerender activation, much of that work has already happened. The visible navigation can feel nearly instant because activation replaces a fresh load with a prepared document.

That performance win creates a different risk. Code that treats document load as user intent is wrong on a prerender path. Analytics beacons, shopping-cart mutation, permission prompts, media playback, login side effects, and other "arrival" behavior may run too early unless the page or platform defers them until activation. Server code has the same issue: a state-changing GET can fire before the user chose the page.

The concept also prevents three common conflations. Speculative navigation is not [Back/Forward Cache Eligibility Gate](bfcache-gate.md): BFCache keeps a previously committed document alive for history traversal, while speculative navigation prepares a document the user has not reached yet. It is not subresource prefetch: Speculation Rules target document navigations, not arbitrary scripts or images. It is not a single-page-app route transition: browser-managed speculation follows document navigation rules, so a client-side router cannot treat it as a substitute for preloading its internal route data.

For Chromium-based products, the pipeline is both a performance surface and a governance surface. New rules, new actions, and new cancellation behavior affect live sites, origin-trial policy, DevTools diagnostics, and the [Navigation Commit Pipeline](navigation-commit-pipeline.md). A downstream browser or Electron shell that modifies navigation or network policy needs to know whether it is changing user-committed navigations, speculative attempts, or activation from a prepared host.

## How to Recognize It

The author-facing signal is a Speculation Rules block. A page contains JSON rules that name `prefetch` or `prerender`, list candidate URLs directly or by document rules, and let the browser decide whether current limits, eligibility checks, memory pressure, and policy allow the attempt. Speculation Rules are a hint channel, not a command channel.

The network signal is a document request with speculative-purpose metadata. Server logs may show `Sec-Purpose: prefetch;prerender`, or the prefetch-only `Sec-Purpose: prefetch`, depending on the action. A server that sees these requests before a click is not seeing a crawler. It is seeing the browser prepare a likely navigation on behalf of an already-open page or browser prediction.

The runtime signal is the prerendering state. In a prerendered document, `document.prerendering` is true until activation, and activation timing is visible through `PerformanceNavigationTiming.activationStart`. Code that needs to run only after the user arrives branches on those signals rather than inventing a new navigation type or relying on load-event timing.

The diagnostic signal is in DevTools and the Chrome DevTools Protocol. Chrome DevTools exposes a Preloading view that shows rule sets, attempts, and final status reasons. The DevTools Protocol's `Preload` domain exposes the same model programmatically. When a speculation does not activate, start with the final status the preloading pipeline recorded.

In the source tree, the signal is `content/browser/preloading/prerender/`, where `PrerenderHostRegistry` and its neighbors own browser-side bookkeeping for starting, matching, activating, cancelling, and destroying prerender hosts.

## How It Plays Out

A documentation site adds Speculation Rules for the "next page" link in a tutorial. Chromium prerenders the next document while the reader is still on the current page. When the reader clicks Next, activation replaces a network-and-render path, and the transition lands inside the [RAIL Performance Model](rail-performance-model.md)'s response window. The site's analytics waits for activation, so it doesn't count pages the reader never opened.

An enterprise application tries the same pattern on a checkout confirmation page. The candidate URL increments a server-side counter on GET. Prefetch makes the counter move before the user chooses the page. The bug is not that Chromium speculated; the bug is that the endpoint encoded a mutation in a document load that might now be issued early. The fix is to make the GET idempotent, move the mutation behind explicit user action, or exclude the URL from speculation.

A downstream browser fork changes a navigation policy hook and sees speculation attempts disappear on managed devices. The page's rules are valid, but DevTools reports a final status tied to policy cancellation. The policy allows user-committed navigations while blocking speculative attempts. Treating both as "navigation" hides the bug.

## Consequences

Speculative navigation makes perceived performance less dependent on the user's final click. When prediction is right, the browser shifts network, parsing, layout, and rendering work into earlier idle time. That helps likely next-page flows, documentation sequences, search results, and product pages where the next document is probable and safe to prepare.

The benefit is probabilistic. The browser may decline a rule because page state, policy, memory, battery, origin constraints, or current limits make the attempt unsafe or too expensive. A prerender may be cancelled after it starts. A prefetched response may not be reusable. Code that treats speculation as guaranteed has already made a lifecycle mistake.

The cost is early work. Prerender consumes memory and CPU for a page the user may never open. Prefetch consumes network and server capacity before the user commits. Those costs can be worth paying when prediction accuracy is high and side effects are controlled. They are wasteful when rules are broad, candidate pages are heavy, or server endpoints are unsafe for early document requests.

The architecture adds one more lifecycle to web-platform review. A new API that behaves correctly in an active document and in BFCache may still need a prerender answer: whether calls are delayed, denied, allowed with restrictions, or treated as cancellation. That answer is the difference between a future page prepared safely and a hidden document doing active-page work before arrival.

## Notes for Agent Context

When generating Speculation Rules, target document navigations only and treat every rule as a hint the browser may ignore. Do not use Speculation Rules to preload subresources, fake a single-page-app route transition, or force a navigation path the browser has declined for policy, memory, eligibility, or safety reasons.

When writing page code that may run during prerender, guard user-visible and irreversible side effects until activation. Check `document.prerendering`, listen for `prerenderingchange`, and use `PerformanceNavigationTiming.activationStart` for timing analysis; don't infer prerender activation from ordinary load events or invent a custom navigation type.

When debugging a missed speculation, inspect Chrome DevTools' Preloading view or the Chrome DevTools Protocol `Preload` domain before changing rules. Read the final status reason, then decide whether the blocker is rule syntax, eligibility, memory pressure, policy, cross-origin limits, or cancellation during activation.

## Sources

Chrome's *Prerender pages in Chrome for instant page navigations* documentation is the primary source for the author-facing model: Speculation Rules, browser-initiated prerender, request headers, activation state, side-effect restrictions, Chrome limits, and the distinction from older `link rel=prerender` behavior. Chrome's complex-rules guide documents candidate selection, eagerness, and document rules. The DevTools guide and Chrome DevTools Protocol `Preload` domain describe diagnostics. The blink-dev Intent to Ship thread records compatibility risk, delayed side effects, `document.prerendering`, activation events, and `activationStart`. The WICG prerendering patches record the specification shape. Chromium's `PrerenderHostRegistry` source shows browser-side activation and cancellation. Chrome Platform Status records the `prerender_until_script` origin-trial extension.

## Technical Drill-Down

- [Chrome for Developers — *Prerender pages in Chrome for instant page navigations*](https://developer.chrome.com/docs/web-platform/prerender-pages) — current author-facing semantics for prerendering, activation, request headers, limits, and side-effect restrictions.
- [Chrome for Developers — *Guide to implementing speculation rules for more complex sites*](https://developer.chrome.com/docs/web-platform/implementing-speculation-rules) — rule syntax, eagerness, document rules, and practical deployment constraints for multi-page sites.
- [Chrome DevTools — *Debug speculation rules with Chrome DevTools*](https://developer.chrome.com/docs/devtools/application/debugging-speculation-rules) — the Preloading diagnostic panels and final-status workflow.
- [blink-dev — *Intent to Ship: Same-origin prerendering triggered by the speculation rules API*](https://groups.google.com/a/chromium.org/g/blink-dev/c/EdW7O8yG7Jc) — launch record for same-origin Speculation Rules prerendering and its compatibility constraints.
- [WICG — *Prerendering Revamped specification patches*](https://wicg.github.io/nav-speculation/prerendering.html) — specification-level changes for prerender activation and page-visible state.
- [Chrome DevTools Protocol — `Preload` domain](https://chromedevtools.github.io/devtools-protocol/tot/Preload/) — machine-readable rule-set, attempt-source, and final-status diagnostics.
- [`content/browser/preloading/prerender/prerender_host_registry.cc` (pinned `6e82c3b`)](https://chromium.googlesource.com/chromium/src/+/6e82c3b28aa9d9ce9440668ae5217136b8809573/content/browser/preloading/prerender/prerender_host_registry.cc) — browser-side registry for prerender hosts, activation matching, cancellation, and destruction.
- [Chrome Platform Status — *Speculation Rules: prerender-until-script Action*](https://chromestatus.com/feature/6324676351623168) — current feature-status record for the 2026 `prerender_until_script` origin-trial extension.

---

- [Next: Coordination at Scale](coordination-scale.md)
- [Previous: Back/Forward Cache Eligibility Gate](bfcache-gate.md)