Add speculation rules prefetch #11426

domenic · 2025-07-03T06:58:50Z

Other spec PRs that should be merged shortly after this one:

CSP integration pull request: Integrate with speculation rules w3c/webappsec-csp#776
Fetch integration pull request: Add the "speculationrules" destination fetch#1841
WICG/nav-speculation pull request to rebase on top of this: Rebase on top of HTML WICG/nav-speculation#398

This ports the relevant text from https://wicg.github.io/nav-speculation/speculation-rules.html, with minor improvements and additions. It does not port the actual navigational prefetching algorithms, which are left in https://wicg.github.io/nav-speculation/prefetch.html for now.

Part of #11123.

Notable changes from that document:

Allows treating prerender rules as prefetch rules.
Allows the presence of target_hint (a prerender-specific speculation rule key), but ignores it.
Follows the precedent set by import maps a bit more closely in how it integrates with the script processing model. Normatively, it fires error events on the script element for the few things that cause complete parsing failures. (Chromium recently changed to do this.)
Adds conformance requirements for speculation rules JSON documents, following the precedent set by import maps.
Adds explicit callouts for when the implementation may report warnings for parsing failures, following the precedent set by import maps.
Fixes a few minor bugs in the parsing algorithms. E.g., the previous text did not correctly deal with how CSS selector parsing returned a list, or called the slightly wrong algorithm for parsing URL patterns.
Simplified the processing model for the Speculation-Rules HTTP header. The previous text added various concepts around pending fetches and periodic implementation-defined processing of those fetches, all designed to allow the implementation to de-prioritize these fetches in favor of other things that happen during loading. This version instead explicitly allows an implementation-defined wait time and uses a separate task source which user agents can deprioritize.
Be explicit about when to consider speculative loads, instead of using vague language about "whenever something relevant changes".
Add re-parsing of <script type=speculationrules> on base URL changes, to match the Chromium implementation.
Slightly shorten some of the security and privacy considerations, e.g., by not mentioning mixed content concerns.

At least two implementers are interested (and none opposed):
- Chromium
- Gecko
- WebKit is in support of a subset of the functionality here
Tests are written and can be reviewed and commented upon at:
- https://wpt.fyi/results/speculation-rules (includes updates to error behavior mentioned above)
Implementation bugs are filed:
- Chromium: N/A
- Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=1969396
- WebKit: https://bugs.webkit.org/show_bug.cgi?id=295193
- Deno (only for timers, structured clone, base64 utils, channel messaging, module resolution, web workers, and web storage): N/A
- Node.js (only for timers, structured clone, base64 utils, channel messaging, and module resolution): N/A
Corresponding HTML AAM & ARIA in HTML issues & PRs: N/A
MDN issue is filed: N/A, MDN already documents this well
The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

/acknowledgements.html ( diff )
/browsers.html ( diff )
/browsing-the-web.html ( diff )
/document-lifecycle.html ( diff )
/document-sequences.html ( diff )
/iana.html ( diff )
/images.html ( diff )
/index.html ( diff )
/indices.html ( diff )
/infrastructure.html ( diff )
/interaction.html ( diff )
/links.html ( diff )
/nav-history-apis.html ( diff )
/references.html ( diff )
/scripting.html ( diff )
/semantics.html ( diff )
/urls-and-fetching.html ( diff )
/webappapis.html ( diff )
/speculative-loading.html ( diff )

domenic · 2025-07-09T06:58:22Z

The spec text here is done and ready for review!

Marking "do not merge yet" until I get the other prerequisites listed in the OP done (mostly PRs against other specs).

Part of whatwg/html#11426, for requests initiated by the `Speculation-Rules` HTTP header.

whatwg/html#11426 upstreams most of the speculation rules specification to HTML. Remove the upstreamed portions, and add references to the PR and PR preview.

domenic · 2025-07-18T04:12:23Z

This is now fully ready for review, including all prerequisites. I'll keep "do not merge yet" to reflect that we need to get #11442 reviewed and merged first, but that's a pretty small change...

This CL introduces error handling for <script type=speculationrules>, mirroring the behavior of <script type=importmap>. Specifically, it adds error events for two cases: - Inline speculation rules with unparsable JSON. - External speculation rules, which are not yet supported. This is verified by new web platform tests. This follows the spec change at whatwg/html#11426. Change-Id: I9b0776b86059f6c8734d57c17f50ed26e89215da Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6758353 Reviewed-by: Hiroki Nakagawa <[email protected]> Commit-Queue: Domenic Denicola <[email protected]> Cr-Commit-Position: refs/heads/main@{#1488632}

This CL introduces error handling for <script type=speculationrules> with invalid ruleset-level tags. This changes the behavior: previously we would ignore such tags and preload with the null tag. But now, we error the entire <script type=speculationrules>, since it is better to avoid preloading if the web developer is expecting it to get a certain tag and we cannot fulfill that request. This matches the spec update at whatwg/html#11426. Bug: None Change-Id: I5d2211510bd4e3a3ecce15010325b411f18fde3a Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6746174 Commit-Queue: Domenic Denicola <[email protected]> Reviewed-by: Danil Somsikov <[email protected]> Reviewed-by: Hiroki Nakagawa <[email protected]> Cr-Commit-Position: refs/heads/main@{#1488633}

This CL introduces error handling for <script type=speculationrules>, mirroring the behavior of <script type=importmap>. Specifically, it adds error events for two cases: - Inline speculation rules with unparsable JSON. - External speculation rules, which are not yet supported. This is verified by new web platform tests. This follows the spec change at whatwg/html#11426. Change-Id: I9b0776b86059f6c8734d57c17f50ed26e89215da Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6758353 Reviewed-by: Hiroki Nakagawa <[email protected]> Commit-Queue: Domenic Denicola <[email protected]> Cr-Commit-Position: refs/heads/main@{#1488632}

This CL introduces error handling for <script type=speculationrules> with invalid ruleset-level tags. This changes the behavior: previously we would ignore such tags and preload with the null tag. But now, we error the entire <script type=speculationrules>, since it is better to avoid preloading if the web developer is expecting it to get a certain tag and we cannot fulfill that request. This matches the spec update at whatwg/html#11426. Bug: None Change-Id: I5d2211510bd4e3a3ecce15010325b411f18fde3a Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6746174 Commit-Queue: Domenic Denicola <[email protected]> Reviewed-by: Danil Somsikov <[email protected]> Reviewed-by: Hiroki Nakagawa <[email protected]> Cr-Commit-Position: refs/heads/main@{#1488633}

This CL introduces error handling for <script type=speculationrules>, mirroring the behavior of <script type=importmap>. Specifically, it adds error events for two cases: - Inline speculation rules with unparsable JSON. - External speculation rules, which are not yet supported. This is verified by new web platform tests. This follows the spec change at whatwg/html#11426. Change-Id: I9b0776b86059f6c8734d57c17f50ed26e89215da Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6758353 Reviewed-by: Hiroki Nakagawa <[email protected]> Commit-Queue: Domenic Denicola <[email protected]> Cr-Commit-Position: refs/heads/main@{#1488632}

This CL introduces error handling for <script type=speculationrules> with invalid ruleset-level tags. This changes the behavior: previously we would ignore such tags and preload with the null tag. But now, we error the entire <script type=speculationrules>, since it is better to avoid preloading if the web developer is expecting it to get a certain tag and we cannot fulfill that request. This matches the spec update at whatwg/html#11426. Bug: None Change-Id: I5d2211510bd4e3a3ecce15010325b411f18fde3a Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6746174 Commit-Queue: Domenic Denicola <[email protected]> Reviewed-by: Danil Somsikov <[email protected]> Reviewed-by: Hiroki Nakagawa <[email protected]> Cr-Commit-Position: refs/heads/main@{#1488633} Co-authored-by: Domenic Denicola <[email protected]>

This CL introduces error handling for <script type=speculationrules>, mirroring the behavior of <script type=importmap>. Specifically, it adds error events for two cases: - Inline speculation rules with unparsable JSON. - External speculation rules, which are not yet supported. This is verified by new web platform tests. This follows the spec change at whatwg/html#11426. Change-Id: I9b0776b86059f6c8734d57c17f50ed26e89215da Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6758353 Reviewed-by: Hiroki Nakagawa <[email protected]> Commit-Queue: Domenic Denicola <[email protected]> Cr-Commit-Position: refs/heads/main@{#1488632}

…sts#53822) This CL introduces error handling for <script type=speculationrules> with invalid ruleset-level tags. This changes the behavior: previously we would ignore such tags and preload with the null tag. But now, we error the entire <script type=speculationrules>, since it is better to avoid preloading if the web developer is expecting it to get a certain tag and we cannot fulfill that request. This matches the spec update at whatwg/html#11426. Bug: None Change-Id: I5d2211510bd4e3a3ecce15010325b411f18fde3a Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6746174 Commit-Queue: Domenic Denicola <[email protected]> Reviewed-by: Danil Somsikov <[email protected]> Reviewed-by: Hiroki Nakagawa <[email protected]> Cr-Commit-Position: refs/heads/main@{#1488633} Co-authored-by: Domenic Denicola <[email protected]>

…sts#53822) This CL introduces error handling for <script type=speculationrules> with invalid ruleset-level tags. This changes the behavior: previously we would ignore such tags and preload with the null tag. But now, we error the entire <script type=speculationrules>, since it is better to avoid preloading if the web developer is expecting it to get a certain tag and we cannot fulfill that request. This matches the spec update at whatwg/html#11426. Bug: None Change-Id: I5d2211510bd4e3a3ecce15010325b411f18fde3a Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6746174 Commit-Queue: Domenic Denicola <[email protected]> Reviewed-by: Danil Somsikov <[email protected]> Reviewed-by: Hiroki Nakagawa <[email protected]> Cr-Commit-Position: refs/heads/main@{#1488633}

This CL introduces error handling for <script type=speculationrules> with invalid ruleset-level tags. This changes the behavior: previously we would ignore such tags and preload with the null tag. But now, we error the entire <script type=speculationrules>, since it is better to avoid preloading if the web developer is expecting it to get a certain tag and we cannot fulfill that request. This matches the spec update at whatwg/html#11426. Bug: None Change-Id: I5d2211510bd4e3a3ecce15010325b411f18fde3a Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6746174 Commit-Queue: Domenic Denicola <[email protected]> Reviewed-by: Danil Somsikov <[email protected]> Reviewed-by: Hiroki Nakagawa <[email protected]> Cr-Commit-Position: refs/heads/main@{#1488633}

This ports the relevant text from https://wicg.github.io/nav-speculation/speculation-rules.html, with minor improvements and additions. It does *not* port the actual navigational prefetching algorithms, which are left in https://wicg.github.io/nav-speculation/prefetch.html for now. Notable changes from that document: * Allows treating prerender rules as prefetch rules. * Allows the presence of target_hint (a prerender-specific speculation rule key), but ignores it. * Follows the precedent set by import maps a bit more closely in how it integrates with the script processing model. Normatively, it fires error events on the script element for the few things that cause complete parsing failures. * Adds conformance requirements for speculation rules JSON documents, following the precedent set by import maps. * Adds explicit callouts for when the implementation may report warnings for parsing failures, following the precedent set by import maps. * Fixes a few minor bugs in the parsing algorithms. E.g., the previous text did not correctly deal with how CSS selector parsing returned a list, or called the slightly wrong algorithm for parsing URL patterns. * Simplified the processing model for the Speculation-Rules HTTP header. The previous text added various concepts around pending fetches and periodic implementation-defined processing of those fetches, all designed to allow the implementation to de-prioritize these fetches in favor of other things that happen during loading. This version instead explicitly allows an implementation-defined wait time and uses a separate task source which user agents can deprioritize. * Be explicit about when to consider speculative loads, instead of using vague language about "whenever something relevant changes". * Add re-parsing of <script type=speculationrules> on base URL changes, to match the Chromium implementation. * Slightly shorten some of the security and privacy considerations, e.g., by not mentioning mixed content concerns.

whatwg/html#11426 upstreams most of the speculation rules specification to HTML. Remove the upstreamed portions, and add references to the PR and PR preview.

domenic added addition/proposal New features or enhancements topic: navigation labels Jul 3, 2025

domenic marked this pull request as draft July 3, 2025 06:59

domenic mentioned this pull request Jul 9, 2025

Patch HTML's base URL stuff to be in terms of DOM whatwg/dom#61

Closed

domenic force-pushed the speculation-rules branch from 7ff9848 to c23dcae Compare July 9, 2025 06:51

domenic marked this pull request as ready for review July 9, 2025 06:54

domenic added the do not merge yet Pull request must not be merged per rationale in comment label Jul 9, 2025

domenic force-pushed the speculation-rules branch from c23dcae to 6ea2451 Compare July 9, 2025 06:58

domenic added a commit to whatwg/fetch that referenced this pull request Jul 10, 2025

Add the "speculationrules" destination

c649784

Part of whatwg/html#11426, for requests initiated by the `Speculation-Rules` HTTP header.

This was referenced Jul 10, 2025

Add the "speculationrules" destination whatwg/fetch#1841

Open

"speculationrules" request destination missing mdn/content#40289

Closed

Integrate with speculation rules w3c/webappsec-csp#776

Open

domenic force-pushed the speculation-rules branch 4 times, most recently from 33f0b13 to 647afa5 Compare July 11, 2025 02:42

domenic added a commit to WICG/nav-speculation that referenced this pull request Jul 11, 2025

Rebase on top of HTML

0ce01bb

whatwg/html#11426 upstreams most of the speculation rules specification to HTML. Remove the upstreamed portions, and add references to the PR and PR preview.

domenic mentioned this pull request Jul 11, 2025

Rebase on top of HTML WICG/nav-speculation#398

Merged

chromium-wpt-export-bot mentioned this pull request Jul 18, 2025

[speculation-rules] Fire error events for invalid speculation rules web-platform-tests/wpt#53821

Merged

chromium-wpt-export-bot mentioned this pull request Jul 18, 2025

Fire error events for invalid speculation rules tags web-platform-tests/wpt#53822

Merged

jonathan-j-lee mentioned this pull request Jul 22, 2025

Reland "Fire error events for invalid speculation rules tags" web-platform-tests/wpt#53905

Merged

domenic force-pushed the speculation-rules branch from 647afa5 to d56b452 Compare July 23, 2025 02:10

domenic removed the do not merge yet Pull request must not be merged per rationale in comment label Jul 23, 2025

domenic added a commit to WICG/nav-speculation that referenced this pull request Jul 23, 2025

Rebase on top of HTML

b75b9f7

whatwg/html#11426 upstreams most of the speculation rules specification to HTML. Remove the upstreamed portions, and add references to the PR and PR preview.

domenic requested a review from domfarolino July 24, 2025 05:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add speculation rules prefetch #11426

Add speculation rules prefetch #11426

domenic commented Jul 3, 2025 •

edited by pr-preview bot

Loading

Uh oh!

domenic commented Jul 9, 2025

Uh oh!

domenic commented Jul 18, 2025

Uh oh!

Uh oh!

Add speculation rules prefetch #11426

Are you sure you want to change the base?

Add speculation rules prefetch #11426

Conversation

domenic commented Jul 3, 2025 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

domenic commented Jul 9, 2025

Uh oh!

domenic commented Jul 18, 2025

Uh oh!

Uh oh!

domenic commented Jul 3, 2025 •

edited by pr-preview bot

Loading