Wiki · Concept · Last reviewed June 25, 2026

Speculation Rules API

The Speculation Rules API lets a page tell the browser which future document navigations may be worth prefetching or prerendering before the user chooses them.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: browser API, prefetch, prerender, agents, prediction, privacy

Definition

The Speculation Rules API is a browser mechanism for declaring likely future document navigations. Instead of waiting until the user clicks a link, a page can supply JSON rules that let the browser prefetch or prerender candidate pages. MDN describes it as an API for future-navigation performance, aimed at document URLs rather than subresource files.

The normative core now sits in the HTML Standard's speculative-loading chapter. That chapter defines a speculation rule set as a JSON object with top-level prefetch and prerender rule arrays, plus optional metadata. A rule can name explicit urls, use document predicates such as href_matches or selector_matches, set eagerness, set a Referrer Policy, and include hints such as expects_no_vary_search.

How It Works

Rules can be embedded in an inline <script type="speculationrules"> block or delivered through a Speculation-Rules response header that points to a JSON resource served as application/speculationrules+json. MDN notes that content-security policy must explicitly allow inline speculation rules when a site uses the script form.

Prefetch and prerender are different bets. Prefetch obtains a future document response so navigation can be faster later; it does not fetch the page's subresources. Prerender is a deeper speculative act: the browser may prepare the future page in advance so activation can feel immediate. Chrome's implementation documentation describes restrictions around same-tab use, same-origin prerendering, cross-origin prefetching, credentialed prerender opt-in headers, and anonymous cross-origin prefetch conditions. Those details are implementation-specific and should not be treated as universal web behavior.

Agent Context

Speculation rules matter for AI browsers because they turn prediction into infrastructure. A normal site might speculate that the user will open a product page, next article, checkout step, or help page. An agentic browser may also predict likely task paths: the next form, the next search result, the next account page, or the next vendor portal. That can make a task feel smoother, but it also changes what the browser contacts before the user has chosen.

The governance problem is not that prefetching is inherently abusive. The problem is ambiguity. Did the user navigate, did the page speculate, did the browser infer, or did an agent steer? Those are different events, and they need different records.

Governance Use

A browser-agent runtime should treat speculative loading as an auditable pre-action. If an agent suggests or injects speculation rules, it should record the task purpose, candidate URLs, rule source, eagerness level, credential mode where observable, referrer behavior, and whether a prefetched or prerendered page was eventually activated.

This also connects to Clear-Site-Data. Browser documentation now recognizes cleanup directives for prefetch and prerender cache state. That matters because speculative pages can create traces that users may not understand as ordinary visits.

Limits

Speculation rules are not a consent system, privacy guarantee, or authorization boundary. They do not decide whether a predicted page should be loaded for a particular user, account, workplace, or legal context. They also do not make unsafe pages safe to prerender. Pages with state-changing side effects, sensitive session behavior, confusing analytics, or fragile bot defenses need careful exclusion.

Support is uneven. MDN marks the API as limited availability and experimental, so production claims should identify the browser, version, rule form, action, target origin, and test date.

Minimum Evidence Record

For agent-mediated browsing, record the page origin, rule source, rule action, candidate URL pattern or list, eagerness, referrer policy, requirements, target origin class, whether credentials or cookies were involved according to browser policy, activation status, agent task identifier, and cleanup event. Do not store full page contents or personal account data just because a speculative request occurred.

Source Discipline

Use the HTML Standard for rule syntax and data-model claims, MDN for browser-facing interface summaries and availability warnings, and Chrome documentation only for Chromium implementation behavior. Do not generalize Chrome prerender restrictions or DevTools behavior into all browsers.

Spiralist Reading

Spiralism reads speculation rules as the web learning to move one step ahead of the user. That can be generous: fewer waits, less friction, faster return to thought. It can also become a quiet rehearsal of desire, where the system prepares a path before the person has chosen it.

The discipline is to name prediction as prediction. A page that was prepared in advance is not the same as a page the user visited. In agentic systems, that distinction protects both memory and agency.

Sources

Return to Wiki