Prerendering Revamped

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

1. Assert: startingURL’s scheme is an HTTP(S) scheme.

2. Let prerenderingTraversable be the result of creating a new top-level traversable given null and the empty string.

3. Set prerenderingTraversable’s loading mode to "prerender".

4. Navigate prerenderingTraversable to startingURL using prerenderingTraversable’s active document.

   We treat this initial navigations as prerenderingTraversable navigating itself, which will ensure all relevant security checks pass.

5. When the user indicates they wish to commit the navigation and 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 user agent’s user interface to present prerenderingTraversable, e.g., by creating a new tab/window.

   2. Finalize activation for prerenderingTraversable given startingURL’s origin.

6. Alternately, when they use 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".

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.

1. Assert: successorTraversable’s active document's is initial about:blank is false.

2. If navigationId is not given, then let navigationId be the result of generating a random UUID.

3. Let referrerOrigin be predecessorTraversable’s active document's origin.

4. Set predecessorTraversable’s ongoing navigation to navigationId.

   This will have the effect of aborting any other ongoing navigations of predecessorTraversable.

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

1. 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. Let doc be navigable’s active document.

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

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

   5. Fire an event named prerenderingchange at doc.

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

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:

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

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

1. Let matchingPrerenderedNavigable be the result of getting the matching prerendering navigable given navigable, url, cspNavigationType, and documentResource.

2. If matchingPrerenderedNavigable is not null, then:

   1. Wait until either matchingPrerenderedNavigable’s active document's is initial about:blank is false, or matchingPrerenderedNavigable is destroyed.

   2. If matchingPrerenderedNavigable was not destroyed, then:

      1. Activate matchingPrerenderedNavigable in place of navigable given historyHandling and navigationId.

      2. Abort these steps.

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

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

1. 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, 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:

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

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

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

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

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

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.

1. Empty document’s post-prerendering activation steps list.

1. Let navigable be settingsObject’s global object's navigable.

2. Let originMatchingEntries be the entries in the Accept-CH cache whose origin is same origin with settingsObject’s origin.

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

1. Let navigable be settingsObject’s global object's navigable.

2. If navigable is a prerendering navigable, set navigable’s prerender-scoped Accept-CH cache[origin] to hintSet.

3. Otherwise, set Accept-CH cache[origin] to hintSet.

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

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

1. If this's navigable is a prerendering navigable, then return.

1. Let realm be the current realm.

2. If the operation in question is a regular operation, then set realm to the relevant realm of this.

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

4. Otherwise, return the result of running the originally-specified steps for this operation, with the same this and arguments.

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

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

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

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

2. If document is null, then return a promise rejected with a "SecurityError" DOMException.

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

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

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

2. Otherwise, get the notifications permission state and return it.

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

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

3. Assert: this.[[state]] is "activating".

1. 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]].

1. Let promise be a new promise.

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

3. If the user agent does not support locking the screen orientation, then reject promise with a "NotSupportedError" DOMException and return promise.

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

5. Set the document's [[orientationPendingPromise]] to promise.

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

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

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

1. Let (normalizedScheme, normalizedURLString) be the result of running normalize protocol handler parameters with scheme, url, and this's relevant settings object.

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

1. Let (normalizedScheme, normalizedURLString) be the result of running normalize protocol handler parameters with scheme, url, and this's relevant settings object.

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