GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing wicg.github.io — Prerendering Revamped

1. Speculation rules

Modify HTML § 7.6.1 Speculation rules as follows to support prerendering.

1.1. Parsing

Extend the speculation rule set struct with two additional items:

prerender rules, a list of speculation rules, initially empty
prerender_until_script rules, a list of speculation rules, initially empty

Extend the speculation rule struct with one additional item:

target navigable name hint, a string or null

Modify parse a speculation rule set string as follows:

Remove the typesToTreatAsPrefetch construct, and instead parse parsed["prerender"] into the prerender rules list, and parsed["prerender_until_script"] into the prerender_until_script rules list, both in an identical manner to what is done for parsed["prefetch"] and the prefetch rules.
Discard rules parsed from parsed["prefetch"] if the target navigable name hint is not null.
Discard rules parsed from parsed["prerender"] and parsed["prerender_until_script"] if the requirements contain "anonymous-client-ip-when-cross-origin".

Implementations will still be allowed to treat prerender candidates as prefetches, per the modifications in § 1.2 Processing model.

Modify parse a speculation rule by adding the following steps:

Let targetHint be null.
If input["target_hint"] exists:
1. If input["target_hint"] is not a valid navigable target name or keyword:
  1. The user agent may report a warning to the console indicating that the supplied target hint was invalid.
  2. Return null.
2. Set targetHint to input["target_hint"].

and then updating the final step which returns a speculation rule to include setting the target navigable name hint to targetHint.

1.2. Processing model

A prerender candidate is a speculative load candidate with the following additional items:

target navigable name hint, a valid navigable target name or keyword or null
should block scripts, a boolean, initially false

Update the consider speculative loads algorithm to bail out early if document’s node navigable is a prerendering navigable, with an explanatory note about how performing speculative loads in a speculatively-loaded page is too wasteful.

Update the inner consider speculative loads steps algorithm by appending the following steps near the beginning, after assembling prefetchCandidates:

Let prerenderCandidates be an empty list.
For each ruleSet of document’s speculation rule sets:
1. For each (rules, shouldBlockScripts) of « (ruleSet’s prerender rules, false), (ruleSet’s prerender_until_script rules, true) »:
  1. For each rule of rules:
    1. For each url of rule’s URLs:
      1. Let referrerPolicy be the result of computing a speculative load referrer policy given rule and null.
      2. Append a new prerender candidate with
        
        URL
        
        url
        
        No-Vary-Search hint
        
        rule’s No-Vary-Search hint
        
        eagerness
        
        rule’s eagerness
        
        referrer policy
        
        referrerPolicy
        
        tags
        
        rule’s tags
        
        target navigable name hint
        
        rule’s target navigable name hint
        
        should block scripts
        
        shouldBlockScripts
        
        to prerenderCandidates.
    2. If rule’s predicate is not null, then:
      1. Let links be the result of finding matching links given document and rule’s predicate.
      2. For each link of links:
        
        Let target be rule’s target navigable name hint.
        
        If target is null, set it to the result of getting an element’s target given link.
        
        Let referrerPolicy be the result of computing a speculative load referrer policy given rule and link.
        
        Append a prerender candidate with
        
        URL
        
        link’s url
        
        No-Vary-Search hint
        
        rule’s No-Vary-Search hint
        
        eagerness
        
        rule’s eagerness
        
        referrer policy
        
        referrerPolicy
        
        tags
        
        rule’s tags
        
        target navigable name hint
        
        target
        
        should block scripts
        
        shouldBlockScripts
        
        to prerenderCandidates.
Let speculativeLoadCandidates be the union of prefetchCandidates and prerenderCandidates.

Update subsequent steps for canceling not-still-being-speculated prefetch records to operate on speculativeLoadCandidates instead of prefetchCandidates.

Create a list prerenderCandidateGroups in an analogous way to prefetchCandidateGroups, but using prerenderCandidates instead of prefetchCandidates.

Replace the step which performs the actual prefetching by looping over prefetchCandidateGroups with the following:

Let speculativeLoadCandidateGroups be the union of prefetchCandidateGroups and prerenderCandidateGroups.
For each group of speculativeLoadCandidateGroups:
1. The user agent may run the following steps:
  1. Let candidate be group[0].
  2. Let tagsToSend be the result of collecting tags from speculative load candidates given group.
  3. Let prefetchRecord be a new prefetch record with
    
    source
    
    "speculation rules"
    
    URL
    
    candidate’s URL
    
    No-Vary-Search hint
    
    candidate’s No-Vary-Search hint
    
    referrer policy
    
    candidate’s referrer policy
    
    tags
    
    tagsToSend
  4. If candidate is a prefetch candidate, then set prefetchRecord’s anonymization policy to candidate’s anonymization policy.
  5. If candidate is a prerender candidate, then the user agent may run the following steps:
    1. Set prefetchRecord’s prerendering traversable to "to be created".
    2. Set prefetchRecord’s prerendering target navigable name hint to candidate’s target navigable name hint.
    3. Start a referrer-initiated navigational prerender given document, prefetchRecord, and candidate’s should block scripts.
  6. If the user agent did not run the previous step, then start a referrer-initiated navigational prefetch given document and prefetchRecord.
  (And keep the subsequent discussion of when to execute this "may" step.)

1.3. Triggering

Update the attribute change steps for a and area elements to also monitor the target attribute and consider speculative loads if it changes.

2. Prerendering infrastructure

2.1. Extensions to the `Document` interface

We’d modify [HTML]’s centralized definition of Document as follows:

partial interface Document {
    readonly attribute boolean prerendering;

    // Under "special event handler IDL attributes that only apply to Document objects"
    attribute EventHandler onprerenderingchange;
};

The onprerenderingchange attribute is an event handler IDL attribute corresponding to the prerenderingchange event handler event type. (We would update the corresponding table in [HTML], which currently only contains onreadystatechange.)

As is customary for [HTML], the definition of prerendering would be located in another section of the spec; we’d place it in the new section introduced below:

2.2. Prerendering navigables

The following section would be added as a new sub-section of [HTML]’s Navigables section.

Every navigable has a loading mode, which is one of the following:

"default": No special considerations are applied to content loaded in this navigable
"prerender": This navigable is displaying prerendered content

By default, a navigable’s loading mode is "default". A navigable whose loading mode is "prerender" is known as a prerendering navigable. A prerendering navigable that is also a top-level traversable is known as a prerendering traversable.

Prerendering navigables’s active browsing contexts are never auxiliary browsing contexts.

Although there are only two values for the loading mode, we use a flexible structure in anticipation of other future loading modes, such as those provided by fenced frames, portals, and uncredentialed (cross-site) prerendering. It’s not yet clear whether that anticipation is correct; if, as those features gain full specifications, it turns out not to be, we will instead convert this into a boolean.

Every navigable has a scripting mode, which is one of the following:

"enabled": Scripts are executed as normal.
"blocked-until-activation": Scripts are blocked until the navigable is activated.

By default, a navigable’s scripting mode is "enabled".

The scripting mode is a property of the navigable, instead of the document, so that it can persist across navigations within the same navigable. This is important for cases like the initial about:blank document, or for client-side redirects that occur before activation.

Every prerendering traversable has a prerender initial response search variance, which is a URL search variance or null, and is initially null.

document.prerendering

Returns true if the page is being presented in a non-interactive prerendering context.

The value can change from true to false, which will be accompanied by the Document firing a prerenderingchange event. (It can never then change back to true.)

The prerendering getter steps are to return true if this has a non-null node navigable that is a prerendering navigable; otherwise, false.

Every Document has a post-prerendering activation steps list, which is a list where each item is a series of algorithm steps. For convenience, we define the post-prerendering activation steps list for any platform object platformObject as:

If platformObject is a node

Return platformObject’s node document’s post-prerendering activation steps list.

Otherwise

Assert: platformObject’s relevant global object is a Window object.

Return platformObject’s relevant global object’s associated Document’s post-prerendering activation steps list.

Every Document has an activation start time, which is initially a DOMHighResTimeStamp with a time value of zero.

Every Document has an allow cross origin iframes navigation while prerendering, which is a boolean, and is initially false.

2.3. Prerender algorithms

User agents may choose to initiate prerendering without a referrer document, for example as a result of the address bar or other browser user interactions.

To start user-agent initiated prerendering given a URL startingURL:

Assert: startingURL’s scheme is an HTTP(S) scheme.
Let prerenderingTraversable be the result of creating a new top-level traversable given null and the empty string.
Set prerenderingTraversable’s loading mode to "prerender".
Let prefetchRecord be a new prefetch record whose URL is startingURL, anonymization policy is null, referrer policy is the empty string, No-Vary-Search hint is the default URL search variance, source is "browser UI", and prerendering traversable is prerenderingTraversable.
Start a referrer-initiated navigational prefetch given prerenderingTraversable’s active document and prefetchRecord.
Navigate prerenderingTraversable to startingURL using prerenderingTraversable’s active document.

We treat this initial navigation as prerenderingTraversable navigating itself, which will ensure all relevant security checks pass.
When the user indicates they wish to commit a navigation to an activationURL which is a URL such that prefetchRecord matches a URL given activationURL:
1. If the user indicates they wish to create a new user-visible top-level traversable while doing so (e.g., by pressing Shift+Enter after typing in the address bar):
  1. Update the successor for activation given prerenderingTraversable, startingURL, and activationURL.
  2. Update the user agent’s user interface to present prerenderingTraversable, e.g., by creating a new tab/window.
  3. Finalize activation for prerenderingTraversable given startingURL’s origin.
2. Alternately, if the user indicates they wish to commit the navigation into an existing top-level traversable predecessorTraversable (e.g., by pressing Enter after typing in the address bar):
  1. Activate prerenderingTraversable in place of predecessorTraversable given "push", startingURL, and activationURL.

The user might never indicate such a commitment, or might take long enough to do so that the user agent needs to reclaim the resources used by the prerender for some more immediate task. In that case the user agent can destroy prerenderingTraversable.

To start a referrer-initiated navigational prerender given a Document referrerDoc, a prefetch record prefetchRecord, and a boolean blockScripts:

Assert: prefetchRecord’s URL’s scheme is an HTTP(S) scheme.
If referrerDoc’s node navigable is not a top-level traversable, then return.

Currently, prerendering from inside a child navigable is not specified or implemented. Doing so would involve tricky considerations around how the prerendered navigable appears in the navigable tree.
If referrerDoc’s browsing context is an auxiliary browsing context, then return.

This avoids having to deal with any potential opener relationship between the prerendering traversable and referrerDoc’s browsing context’s opener browsing context.
If referrerDoc’s origin is not same site with prefetchRecord’s URL’s origin, then return.

Currently, cross-site prerendering is not specified or implemented, although we have various ideas about how it could work in this repository’s explainers.
If referrerDoc has a matching prefetch record given prefetchRecord with checkPrerender set to true, then return.
Assert: prefetchRecord’s prerendering traversable is "to be created".
Let prerenderingTraversable be the result of creating a new top-level traversable.

The user agent can use prefetchRecord’s prerendering target navigable name hint as a hint to their implementation of create a new top-level traversable. This hint indicates that the web developer expects the eventual activation of the created prerendering traversable to be in place of a particular predecessor traversable: the one that would be chosen by the invoking the rules for choosing a navigable given prefetchRecord’s prerendering target navigable name hint and referrerDoc’s node navigable.

This is just a hint. The value has no normative implications. It would still be perfectly fine in the future to activate in place of a different predecessor traversable that was not hinted at.
Set prerenderingTraversable’s loading mode to "prerender".
If blockScripts is true, set prerenderingTraversable’s scripting mode to "blocked-until-activation".
Set prefetchRecord’s prerendering traversable to prerenderingTraversable.
Set prerenderingTraversable’s remove from referrer to be an algorithm which sets prefetchRecord’s prerendering traversable to null.

As with all top-level traversables, the prerendering traversable can be destroyed for any reason, for example if it becomes unresponsive, performs a restricted operation, or if the user agent believes prerendering takes too many resources. In such cases, the prefetch record will remain, so it can be used to fulfill future navigations, even if the prerendering traversable has been destroyed.
Start a referrer-initiated navigational prefetch given referrerDoc and prefetchRecord.
Navigate prerenderingTraversable to prefetchRecord’s URL using referrerDoc, with referrerPolicy set to prefetchRecord’s referrer policy.

To update the successor for activation given a prerendering traversable successorTraversable, a URL startingURL, and a URL activationURL:

Let successorDocument be successorTraversable’s active document.
If startingURL equals successorDocument’s URL and startingURL does not equal activationURL:
1. Assert: successorDocument can have its URL rewritten to activationURL.
2. Let navigation be successorDocument’s relevant global object’s navigation API.
3. Let continue be the result of firing a push/replace/reload navigate event at navigation given "replace", activationURL, and true.
4. If continue is true, run the URL and history update steps given successorDocument and activationURL.
This allows for the URL of the prerender to match the URL actually navigated to, in the case of inexact matching based on `No-Vary-Search`.

To activate a prerendering traversable successorTraversable in place of a top-level traversable predecessorTraversable given a history handling behavior historyHandling, a URL startingURL, a URL activationURL, an optional navigation ID navigationId:

Assert: successorTraversable’s active document’s is initial about:blank is false.
If navigationId is not given, then let navigationId be the result of generating a random UUID.
Let referrerOrigin be predecessorTraversable’s active document’s origin.
Set predecessorTraversable’s ongoing navigation to navigationId.

This will have the effect of aborting any other ongoing navigations of predecessorTraversable.
In parallel, run these steps:
1. Let unloadPromptCanceled be the result of checking if unloading is user-canceled for predecessorTraversable’s active document’s inclusive descendant navigables.
2. If unloadPromptCanceled is true, or predecessorTraversable’s ongoing navigation is no longer navigationId, then abort these steps.
3. Queue a global task on the navigation and traversal task source given predecessorTraversable’s active window to abort predecessorTraversable’s active document.
4. Update the successor for activation given successorTraversable, startingURL, and activationURL.
5. Append session history traversal steps to predecessorTraversable to perform the following steps:
  1. Assert: successorTraversable’s current session history step is 0.
  2. Assert: successorTraversable’s session history entries’s size is 1.
  3. Let successorEntry be successorTraversable’s session history entries[0].
  4. Remove successorEntry from successorTraversable’s session history entries.
    
    At this point, successorTraversable is empty and can be unobservably destroyed. (As long as the implementation takes care to keep successorEntry, including its document and that Document’s browsing context, alive for the next step.)
  5. Finalize a cross-document navigation given predecessorTraversable, historyHandling, and successorEntry.
    
    Because we have moved the entire session history entry, including the contained document’s browsing context, this means traversing across the associated history entries will cause a browsing context group switch, similar to what happens with the `Cross-Origin-Opener-Policy` header. Importantly, this will sever any opener relationships, in the same way as COOP. Such traversal includes both the actual activation process here, where we make successorEntry active, but also e.g. the user pressing the back button (or the page using history.back()) after activation, which will switch in the other direction.
  6. Update the user agent’s user interface to reflect this change, e.g., by updating the tab/window contents and the browser chrome.
  7. Finalize activation for successorTraversable given referrerOrigin.
  8. Perhaps we should do something with WebDriver BiDi here? See w3c/webdriver-bidi#321. Right now the pre-in parallel part of the navigate algorithm will send WebDriver BiDi navigation started as if it were a normal navigation, but then nothing will happen to indicate the navigation finishes.

To finalize activation of a top-level traversable traversable given an origin origin:

For each navigable of traversable’s active document’s inclusive descendant navigables, queue a global task on the navigation and traversal task source, given navigable’s active window, to perform the following steps:
1. For each origin → hintSet in navigable’s prerender-scoped Accept-CH cache:
  1. Set Accept-CH cache[origin] to hintSet.
2. If navigable’s scripting mode is "blocked-until-activation":
  1. Set navigable’s scripting mode to "enabled".
  2. Unblock script execution in navigable’s active document.
  The precise mechanism for how script execution is resumed, especially how previously-queued tasks are processed, needs to be specified in more detail.
3. Let doc be navigable’s active document.
4. We should really propagate the loading mode change here, in the posted task. This is where implementations would update what is returned by document.prerendering. However, right now it lives on the traversable, so it gets magically updated when we move over the session history entry. Probably we need to move it to the Document.
5. If doc’s origin is the same as origin, then set doc’s activation start time to the current high resolution time for doc’s relevant global object.
6. Fire an event named prerenderingchange at doc.
7. For each steps in doc’s post-prerendering activation steps list:
  1. Run steps.
    
    These steps might return something, like a Promise. That is just an artifact of how the spec is modified; such return values can always be ignored.
  2. Assert: running steps did not throw an exception.
  The order here is observable for Documents that share an event loop, but not for those in separate event loops.

A prerendering traversable has an associated remove from referrer, which is null or an algorithm with no arguments, initially set to null.

To ensure that the references for a prerendering traversable are cleared once it is destroyed, modify destroy a top-level traversable by appending the following step:

If traversable is a prerendering traversable and traversable’s remove from referrer is not null, then call traversable’s remove from referrer.

2.4. Modifications to creating navigables

To ensure that any child navigables inherit their parent’s loading mode, modify create a new child navigable by appending the following step:

Set navigable’s loading mode to element’s node navigable’s loading mode.

3. Navigation and session history

3.1. Allowing activation in place of navigation

To find a matching prerendered prefetch record given a Document predecessorDocument and URL url:

Let recordToUse be null.
For each record of predecessorDocument’s prefetch records:
1. If record’s prerendering traversable is not a prerendering traversable, then continue.
2. If record’s prerendering traversable’s active document’s is initial about:blank is true, then continue.
3. If record’s URL is equal to url:
  1. Set recordToUse to record.
  2. Break.
4. If recordToUse is null and record matches a URL given url:
  1. Set recordToUse to record.
If recordToUse is not null:
1. Remove recordToUse from predecessorDocument’s prefetch records.
Return recordToUse.

To wait for a matching prerendered prefetch record given a navigable navigable, a URL url, a string cspNavigationType, and a POST resource, string, or null documentResource:

Assert: this is running in parallel.
If any of the following conditions hold:
- navigable is not a top-level traversable;
- navigable is a prerendering traversable;
- navigable is a fenced frame;
  
  The concept of a fenced frame navigable is not yet defined but we need to link to it once it exists.
- cspNavigationType is not "other"; or
- documentResource is not null
then return null.
Let predecessorDocument be navigable’s active document.
Let cutoffTime be null.
While true:
1. Let completeRecord be the result of finding a matching prerendered prefetch record given predecessorDocument and url.
2. If completeRecord is not null, return completeRecord.
3. Let potentialRecords be an empty list.
4. For each record of predecessorDocument’s prefetch records:
  1. If all of the following are true, then append record to potentialRecords:
    - record’s prerendering traversable is a prerendering traversable;
    - record’s prerendering traversable’s active document’s is initial about:blank is true;
    - record is expected to match a URL given url; and
    - cutoffTime is null or record’s start time is less than cutoffTime.
5. If potentialRecords is empty, return null.
6. Wait until the ongoing navigation of the prerendering traversable of any element of predecessorDocument’s prefetch records changes.
7. If cutoffTime is null and any element of potentialRecords has a prerendering traversable whose active document’s is initial about:blank is false, set cutoffTime to the current high resolution time for the relevant global object of predecessorDocument.

Patch the navigate algorithm to allow the activation of a prerendering traversable in place of a normal navigation as follows:

In navigate, insert the following steps as the first ones after we go in parallel:

Let record be the result of waiting for a matching prerendered prefetch record given navigable, url, cspNavigationType, and documentResource.
If record is not null, then:
1. Let matchingPrerenderedNavigable be record’s prerendering traversable.
2. Let startingURL be record’s URL.
3. Activate matchingPrerenderedNavigable in place of navigable given historyHandling, startingURL, url, and navigationId.
4. Abort these steps.

3.2. Navigation fetch changes

In create navigation params by fetching, add the following step near the top of the algorithm:

Let initiatorOrigin be entry’s document state’s initiator origin.

Append the following steps after the first sub-step under "While true:":

If navigable is a prerendering navigable and currentURL’s origin is not same site with initiatorOrigin, then:
1. If navigable is a top-level traversable, then return null.
2. Otherwise, if navigable’s top-level traversable’s active document’s allow cross origin iframes navigation while prerendering is false, the user agent must wait to continue this algorithm until navigable’s loading mode becomes "normal". At any point during this wait (including immediately), it may instead choose to destroy navigable’s top-level traversable and return null from this algorithm.

Append the following steps toward the end of the algorithm, after the steps which check locationURL:

If navigable is a prerendering navigable, and responseOrigin is not same origin with initiatorOrigin, then:
1. Let loadingModes be the result of getting the supported loading modes for response.
2. If loadingModes does not contain `credentialed-prerender`, then return null.
  
  In the future we could possibly also allow the uncredentialed-prerender token to work here. However, since that is primarily intended for the cross site case, which isn’t specified or implemented yet, we don’t want to encourage its use in the wild, so for now we specify that prerendering fails if only the uncredentialed-prerender token is found.

In create and initialize a Document object, add the following step after "If navigationParams’s response has a Refresh header, then:":

If navigationParams’s navigable is a prerendering navigable, then:
1. Let loadingModes be the result of getting the supported loading modes for response.
2. If loadingModes contains `prerender-cross-origin-frames`, set document’s allow cross origin iframes navigation while prerendering to true.

In attempt to populate the history entry’s document, append the following after the steps which establish the value of failure, but before the other steps which act on it:

If navigable is a prerendering navigable, and any of the following hold:
- failure is true;
- navigationParams’s request is null;
- navigationParams’s request’s current URL’s scheme is not a HTTP(S) scheme;
- navigationParams’s request’s current URL is not potentially trustworthy;
- navigationParams’s response does not support prefetch;
  
  Responses which are ineligible for prefetch, e.g. because they have an error status, are not eligible for prerender either. A future version of this specification might allow responses to more clearly delineate the two.
- navigationParams’s response has a `Content-Disposition` header specifying the attachment disposition type; or
- navigationParams’s response’s status is 204 or 205,
then:
1. Destroy navigable’s top-level traversable.
2. Return.
If navigable is a prerendering traversable and navigable’s prerender initial response search variance is null:
1. Set navigable’s prerender initial response search variance to the result of obtaining a URL search variance given navigationParams’s response.

In hand-off to external software, prepend the following step:

If navigable is a prerendering navigable, then return without invoking the external software package.

We could also allow prerendering activations in place of redirects, not just in place of navigations. We’ve omitted that for now as it adds complexity and is not yet implemented anywhere to our knowledge.

3.3. Maintaining a trivial session history

Patch the navigate algorithm to ensure the session history of a prerendering navigable stays trivial by prepending the following step before all others:

If navigable is a prerendering navigable, then set historyHandling to "replace".

Patch the URL and history update steps by adding the following step after step 1:

If navigable is a prerendering navigable, then set historyHandling to "replace".

3.4. Interaction with worker lifetime

In The worker’s lifetime, modify the definition of active needed worker, to count workers with a prerendering navigable owner as not active:

A worker is said to be an active needed worker if any of its owners are either Document objects that are fully active and their node navigable is not a prerendering navigable, or active needed workers.

This means that the worker’s script would load, but the execution would be suspended until the document is activated.

3.5. Cleanup upon discarding a `Document`

Modify the destroy algorithm for Documents by appending the following step:

Empty document’s post-prerendering activation steps list.

4. Interaction with other specifications and concepts

4.1. Interaction with Page Visibility

Documents in prerendering navigables always have a visibility state of "hidden".

We should probably explicitly update this, similar to how we need to update document.prerendering.

4.2. Interaction with system focus

Prerendering traversables never have system focus.

4.3. Extensions to the `PerformanceNavigationTiming` interface

Extend the PerformanceNavigationTiming interface as follows:

partial interface PerformanceNavigationTiming {
    readonly attribute DOMHighResTimeStamp activationStart;
};

The activationStart getter steps are:

Return this’s relevant global object’s associated Document’s activation start time.

4.4. Interaction with Client Hint Cache

We need to ensure that the Accept-CH cache, which is owned by user agent as a global storage, is not modified while prerendering, but is properly updated after activation. The following modifications ensure this.

Each prerendering navigable has a prerender-scoped Accept-CH cache, which is an ordered map of origin to client hints sets.

This stores which client hints each origin has opted into receiving, until it can be copied to the global Accept-CH cache when activation is finalized.

Modify the update the client hints set from cache algorithm, by replacing the second step with the following steps.

Let navigable be settingsObject’s global object’s navigable.
Let originMatchingEntries be the entries in the Accept-CH cache whose origin is same origin with settingsObject’s origin.
If navigable is a prerendering navigable, then:
1. Let prerenderAcceptClientHintsCache be navigable’s prerender-scoped Accept-CH cache.
2. Let origin be settingsObject’s origin.
3. If prerenderAcceptClientHintsCache[origin] exists, then let originMatchingEntries be the entries in the prerenderAcceptClientHintsCache whose origin is same origin with origin.

Modify the create or override the cached client hints set algorithm, by updating the last step.

Let navigable be settingsObject’s global object’s navigable.
If navigable is a prerendering navigable, set navigable’s prerender-scoped Accept-CH cache[origin] to hintSet.
Otherwise, set Accept-CH cache[origin] to hintSet.

4.5. Interaction with Clear Site Data

Add an additional header value description in Clear Site Data § 3.1 The Clear-Site-Data HTTP Response Header Field:

"prerenderCache"

The "prerenderCache" type indicates that the server wishes to remove any prerenders initiated by the origin of a particular response’s URL.

This type is a subset of the "cache" type.

Implementation details are below.

Modify parse response’s Clear-Site-Data header’s parsing step such that:

encountering `"cache"` or `"*"` appends "prerenderCache" to types (in addition to the values already appended in those branches); and
encountering `"prerenderCache"` appends "prerenderCache" to types.

Modify clear site data for response’s switch to add a case that handles "prerenderCache" and calls clear prerender cache for origin.

To clear prerender cache given an origin origin:

For each top-level traversable traversable of the user agent’s top-level traversable set:
1. Let navigables be the inclusive descendant navigables of traversable’s active document.
2. For each navigable in navigables:
  1. Let activeDocument be the navigable’s active document.
  2. If activeDocument’s origin is not same origin with origin, then continue.
  3. For each prefetchRecord in activeDocument’s prefetch records:
    1. If prefetchRecord’s prerendering traversable is null, then continue.
    2. Cancel and discard prefetchRecord given activeDocument.

4.6. Interaction with Fetch

Modify HTTP-network-or-cache fetch by adding the following step after the existing step that sets `Sec-Purpose`:

Otherwise, if httpRequest’s client is an environment settings object whose global object is a Window, and that Window’s navigable is a prerendering navigable:
1. Let purpose be a List containing the Token prefetch.
2. Add a parameter whose key is "prerender" and whose value is true to the prefetch token in purpose.
3. Set a structured field value given (`Sec-Purpose`, purpose) in httpRequest’s header list.
This includes both subresources within the prerendering navigable, and cases where the prerendering navigable is navigating itself.

5. The ``Supports-Loading-Mode`` HTTP response header

The following section would be added as a sub-section of [HTML]’s Loading web pages section.

In some cases, cross-origin web pages might not be prepared to be loaded in a novel context. To allow them to opt in to being loaded in such ways, the `Supports-Loading-Mode` HTTP response header can be used. This header is a structured header; if present its value must be one or more of the tokens listed below.

The parsing is actually done as a list of tokens, and unknown tokens will be ignored.

The `credentialed-prerender` token indicates that the response can be used to create a prerendering navigable, despite the prerendering being initiated by a cross-origin same-site referrer. Without this opt-in, such prerenders will fail, as outlined in § 3.2 Navigation fetch changes.

The `prerender-cross-origin-frames` token indicates that the response can be used to prerender all cross-origin iframes. Without this opt-in, such prerenders will be deferred, as outlined in § 3.2 Navigation fetch changes.

To get the supported loading modes for a response response:

If response is a network error, then return an empty list.
Let slmHeader be the result of getting a structured field value given `Supports-Loading-Mode` and "list" from response’s header list.
Return a list containing all elements of slmHeader that are tokens.

6. Preventing intrusive behaviors

Various behaviors are disallowed in prerendering navigables because they would be intrusive to the user, since the prerendered content is not being actively interacted with.

6.1. Pausing script execution

If a navigable’s scripting mode is "blocked-until-activation", the user agent must not execute script in the navigable’s active document. This includes, but is not limited to executing <script> elements.

The precise mechanism for how script execution is blocked, and how various script-related tasks are queued instead of being processed, needs to be specified in more detail.

This effectively pauses all JavaScript execution until the page is activated. For inline event handlers, the expected behavior is under discussion.

6.2. Downloading resources

Modify the download the hyperlink algorithm to ensure that downloads inside prerendering navigable are delayed until activation, by inserting the following before the step which goes in parallel:

If subject’s node navigable is a prerendering navigable, then append the following step to subject’s post-prerendering activation steps list and return.

6.3. User prompts

Modify the cannot show simple dialogs algorithm, given a Window window, by prepending the following step:

If window’s navigable is a prerendering navigable, then return true.

Modify the print() method steps by prepending the following step:

If this’s navigable is a prerendering navigable, then return.

6.4. Delaying async API results

Many specifications need to be patched so that, if a given algorithm invoked in a prerendering navigable, most of its work is deferred until the navigable’s top-level traversable is activated. This is tricky to do uniformly, as many of these specifications do not have great hygeine around using the event loop. Nevertheless, the following sections give our best attempt.

Note that if the scripting mode is "blocked-until-activation", the scripts that would invoke these algorithms are not executed in the first place until activation.

6.4.1. The `[DelayWhilePrerendering]` extended attribute

To abstract away some of the boilerplate involved in delaying the action of asynchronous methods until activation, we introduce the [DelayWhilePrerendering] Web IDL extended attribute. It indicates that when a given method is called in a prerendering navigable, it will immediately return a pending promise and do nothing else. Only upon activation will the usual method steps take place, with their result being used to resolve or reject the previously-returned promise.

The [DelayWhilePrerendering] extended attribute must take no arguments, and must only appear on a regular or static operation whose return type is a promise type or undefined, and whose exposure set contains only Window.

The method steps for any operation annotated with the [DelayWhilePrerendering] extended attribute are replaced with the following:

Let realm be the current realm.
If the operation in question is a regular operation, then set realm to the relevant realm of this.
If realm’s global object’s navigable is a prerendering navigable, then:
1. Let promise be a new promise, created in realm.
2. Append the following steps to this’s post-prerendering activation steps list:
  1. Let result be the result of running the originally-specified steps for this operation, with the same this and arguments.
  2. Resolve promise with result.
3. If this operation’s return type is a promise type, then return promise.
Otherwise, return the result of running the originally-specified steps for this operation, with the same this and arguments.

6.4.2. Service Workers

Add [DelayWhilePrerendering] to update(), unregister(), register(scriptURL, options), postMessage(message, transfer), and postMessage(message, options).

This allows prerendered page to take advantage of existing service workers, but not have any effect on the state of service worker registrations.

6.4.3. BroadcastChannel

Add [DelayWhilePrerendering] to postMessage().

6.4.4. Geolocation API

Modify the getCurrentPosition() method steps by prepending the following step:

If this’s relevant global object’s navigable is a prerendering navigable, then append the following steps to this’s post-prerendering activation steps list and return.

Modify the watchPosition() method steps by prepending the following step:

If this’s relevant global object’s navigable is a prerendering navigable, then:
1. Let watchId be an implementation-defined unsigned long, and note it as a post-prerendering activation geolocation watch process ID.
2. Append the following steps to this’s post-prerendering activation steps list, with the modification that the watchId generated must use watchId as its ID, and return watchId.

Modify the clearWatch(watchId) method steps by prepending the following step:

If this’s relevant global object’s navigable is a prerendering navigable, then:
1. If watchId is a post-prerendering activation geolocation watch process ID, then remove its corresponding steps from this’s post-prerendering activation steps list.
2. Return.

6.4.5. Web Serial API

Add [DelayWhilePrerendering] to requestPort().

TODO: the below could probably be done by generalizing [DelayWhilePrerendering] to use owner document while in dedicated workers.

Modify the getPorts() method steps by inserting the following steps after the initial creation of promise:

Let document be this’s relevant global object’s associated Document, if this’s relevant global object is a Window, or this’s relevant global object’s owner document, if this’s relevant global object is a DedicatedWorkerGlobalScope.
If document is null, then return a promise rejected with a "SecurityError" DOMException.
If document’s node navigable is a prerendering navigable, then append the following steps to document’s post-prerendering activation steps list and return promise.

6.4.6. Notifications API

Add [DelayWhilePrerendering] to requestPermission().

Modify the Notification() constructor steps by replacing the step which goes in parallel with the following:

If this’s relevant global object’s navigable is a prerendering navigable, then append these steps to this’s post-prerendering activation steps list. Otherwise, run these steps in parallel.

Modify the permission static getter steps by replacing them with the following:

If the current global object’s navigable is a prerendering navigable, then return "default".

This allows implementations to avoid looking up the actual permission state, which might not be synchronously accessible especially in the case of prerendering navigables. Web developers can then call Notification.requestPermission(), which per the above modifications will only actually do anything after activation. At that time we might discover that the permission is "granted" or "denied", so the browser might not actually ask the user like would normally be the case with "default". But that’s OK: it’s not observable to web developer code.
Otherwise, get the notifications permission state and return it.

6.4.7. Web MIDI API

Add [DelayWhilePrerendering] to requestMIDIAccess().

6.4.8. Idle Detection API

Add [DelayWhilePrerendering] to start().

The other interesting method, IdleDetector.requestPermission(), is gated on transient activation. However, even if permission was previously granted for the origin in question, we delay starting any idle detectors while prerendering.

6.4.9. Generic Sensor API

Modify the start() method steps by inserting the following steps after the state is set to "activating":

If this’s relevant global object’s navigable is a prerendering navigable, then append the following steps to this’s post-prerendering activation steps list and return.
If this.[[state]] is "idle", then return.

This ensures that if this portion of the algorithm was delayed due to prerendering, and in the meantime stop() was called, we do nothing upon activating the prerender.
Assert: this.[[state]] is "activating".

6.4.10. Web NFC

Add [DelayWhilePrerendering] to write() and scan().

6.4.11. Battery Status API

Modify the getBattery() method steps by prepending the following step:

If this’s relevant global object’s navigable is a prerendering navigable, then append the following steps to this’s post-prerendering activation steps list and return this.[[BatteryPromise]].

6.4.12. Screen Orientation API

Modify the apply orientation lock algorithm steps by overwriting the first few steps, before it goes in parallel, as follows:

Let promise be a new promise.
If this’s relevant global object’s navigable is a prerendering navigable, then append the following steps to this’s post-prerendering activation steps list and return promise.
If the user agent does not support locking the screen orientation, then reject promise with a "NotSupportedError" DOMException and return promise.
If the document’s active sandboxing flag set has the sandboxed orientation lock browsing context flag set, or the user agent doesn’t meet the pre-lock conditions to perform an orientation change, then reject promise with a "SecurityError" DOMException and return promise.
Set the document’s [[orientationPendingPromise]] to promise.

Add [DelayWhilePrerendering] to unlock().

This latter modification is necessary to ensure that code that calls screen.orientation.lock() followed by screen.orientation.unlock() produces the expected results.

6.4.13. Gamepad

Modify the getGamepads() method steps by prepending the following step:

If this’s relevant global object’s navigable is a prerendering navigable, then return an empty sequence.

Modify the discussion of the gamepadconnected and gamepaddisconnected events to specify that the user agent must not dispatch these events if the Window object’s navigable is a prerendering navigable.

Modify the gamepadconnected section to indicate that every Document document’s post-prerendering activation steps list should gain the following steps:

If document is allowed to use the "gamepad" feature, and document’s relevant settings object is a secure context, and any gamepads are connected, then for each connected gamepad, fire an event named gamepadconnected at document’s relevant global object using GamepadEvent, with its gamepad attribute initialized to a new Gamepad object representing the connected gamepad.

6.4.14. Encrypted Media Extensions

Add [DelayWhilePrerendering] to requestMediaKeySystemAccess().

6.4.15. Media Autoplay

Modify the playing the media resource section to indicate that the the current playback position of a HTMLMediaElement must increase monotonically only when the Document is not prerendering.

6.4.16. Media Capture and Streams

Add [DelayWhilePrerendering] to getUserMedia(), getUserMedia() and enumerateDevices().

Modify the MediaDevices section by prepending the following step to the device change notification steps:

If this’s relevant global object’s navigable is a prerendering navigable, then return.

6.4.17. Web Audio API

The concept, allowed to start, is used in the spec, but details are left implementation-defined. To restrict auto playback while prerendering, add the following rule in the AudioContext interface section.

The AudioContext is never allowed to start while prerendering.

Also modify AudioContext() constructor steps to have the following step before returning the constructed object.

Else if context is not allow to start only due to the prerendering, then append the following steps to context’s post-prerendering activation steps list.
1. Set the [[control thread state]] on context to running.
2. Queue a control message to resume context.

Developers might call resume() while prerendering. In that case, the context is not allow to start, and appends a Promise to [[pending resume promises]]. The Promise will be resolved in the activation steps above.

The AudioScheduledSourceNode interface has a start(when) method and the AudioBufferSourceNode interface has a start(when, offset, duration) method that might affect [[control thread state]]. But they don’t as the context is not allowed to start and it prevents the algorithm from setting the [[control thread state]]. This would not matter because the node can automatically start when the context starts.

6.4.30. Custom Scheme Handlers

Modify the registerProtocolHandler(scheme, url) method steps by overwriting the first few steps, before it goes in parallel, as follows:

Let (normalizedScheme, normalizedURLString) be the result of running normalize protocol handler parameters with scheme, url, and this’s relevant settings object.
If this’s relevant global object’s navigable is a prerendering navigable, then append the following steps to this’s post-prerendering activation steps list and return.

Modify the unregisterProtocolHandler(scheme, url) method steps by overwriting the first few steps, before it goes in parallel, as follows:

Let (normalizedScheme, normalizedURLString) be the result of running normalize protocol handler parameters with scheme, url, and this’s relevant settings object.
If this’s relevant global object’s navigable is a prerendering navigable, then append the following steps to this’s post-prerendering activation steps list and return.

6.5. Implicitly restricted APIs

Some APIs do not need modifications because they will automatically fail or no-op without a property that a prerendering navigable, its active window, or its active document will never have. These properties include:

transient activation or sticky activation
system focus
the "visible" visibility state

We list known APIs here for completeness, to show which API surfaces we’ve audited.

APIs that require transient activation or sticky activation:

window.open() [HTML]
The prompt generated by the beforeunload event [HTML]
element.requestFullscreen() [FULLSCREEN]
- navigator.keyboard.lock() [KEYBOARD-LOCK], which requires fullscreen
  
  [KEYBOARD-LOCK] allows browsing contexts to enable keyboard lock easily but it has no effect except in fullscreen, which requires a user gesture. If that changes then this needs to be revisited.
paymentRequest.show() [PAYMENT-REQUEST]
presentationRequest.start() [PRESENTATION-API]
showOpenFilePicker(), showSaveFilePicker(), and showDirectoryPicker() [FILE-SYSTEM-ACCESS]
IdleDetector.requestPermission() [IDLE-DETECTION]
Firing of clipboard events. [CLIPBOARD-APIS]
navigator.share() [WEB-SHARE]
element.requestPointerLock() [POINTERLOCK]
getDisplayMedia() [SCREEN-CAPTURE]

APIs that require system focus:

The Asynchronous Clipboard API: navigator.clipboard.read(), navigator.clipboard.readText(), navigator.clipboard.write(), navigator.clipboard.writeText(). [CLIPBOARD-APIS]

APIs that require the "visible" visibility state:

navigator.wakeLock.request() [SCREEN-WAKE-LOCK]

More complicated cases:

Request Picture-in-Picture as invoked due to video.requestPictureInPicture() requires either transient activation, or the visibility state to have been "visible". [PICTURE-IN-PICTURE]

7. Security considerations

See HTML § 7.6.5 Security considerations.

For the integration of this spec with No-Vary-Search, see No-Vary-Search Security considerations.

Add security considerations that are specific to prerendering. See issue #319.

8. Privacy considerations

See HTML § 7.6.6 Privacy considerations.

For the integration of this spec with No-Vary-Search, see No-Vary-Search Privacy considerations.

Add privacy considerations that are specific to prerendering. See issue #319. One in particular worth calling out is how cross-partition prerendering is just disallowed, due to the privacy complexities.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.