Navigation API

partial interface Window {
  [Replaceable] readonly attribute Navigation navigation;
};

[Exposed=Window]
interface Navigation : EventTarget {
  sequence<NavigationHistoryEntry> entries();
  readonly attribute NavigationHistoryEntry? currentEntry;
  undefined updateCurrentEntry(NavigationUpdateCurrentEntryOptions options);
  readonly attribute NavigationTransition? transition;

  readonly attribute boolean canGoBack;
  readonly attribute boolean canGoForward;

  NavigationResult navigate(USVString url, optional NavigationNavigateOptions options = {});
  NavigationResult reload(optional NavigationReloadOptions options = {});

  NavigationResult traverseTo(DOMString key, optional NavigationOptions options = {});
  NavigationResult back(optional NavigationOptions options = {});
  NavigationResult forward(optional NavigationOptions options = {});

  attribute EventHandler onnavigate;
  attribute EventHandler onnavigatesuccess;
  attribute EventHandler onnavigateerror;
  attribute EventHandler oncurrententrychange;
};

dictionary NavigationUpdateCurrentEntryOptions {
  required any state;
};

dictionary NavigationOptions {
  any info;
};

dictionary NavigationNavigateOptions : NavigationOptions {
  any state;
  NavigationHistoryBehavior history = "auto";
};

dictionary NavigationReloadOptions : NavigationOptions {
  any state;
};

dictionary NavigationResult {
  Promise<NavigationHistoryEntry> committed;
  Promise<NavigationHistoryEntry> finished;
};

enum NavigationHistoryBehavior {
  "auto",
  "push",
  "replace"
};

A Navigation navigation has entries and events disabled if the following steps return true:

1. If navigation’s relevant global object's browsing context is null, then return true.

2. Let document be navigation’s relevant global object's associated Document.

3. If document’s is initial about:blank is true, then return true.

4. If document’s origin is opaque, then return true.

5. Return false.

To update the entries for a same-document navigation given a Navigation instance navigation, a session history entry destinationSHE, and a NavigationType navigationType:

1. If navigation has entries and events disabled, then:

   1. Assert: navigation’s entry list is empty.

   2. Return.

2. Let oldCurrentNHE be the current entry of navigation.

3. Let disposedNHEs be a new empty list.

4. If navigationType is "traverse":

   1. Set navigation’s current entry index to the index of the NavigationHistoryEntry within navigation’s entry list whose session history entry's navigation API key equals destinationSHE’s navigation API key.

   2. Assert: such a NavigationHistoryEntry must exist, because this algorithm is only called for same-document traversals. (Cross-document traversals will instead call either update the entries for reactivation or initialize the entries for a new Navigation.)

5. Otherwise, if navigationType is "push":

   1. Set navigation’s current entry index to navigation’s current entry index + 1.

   2. Let i be navigation’s current entry index.

   3. While i < navigation’s entry list's size:

      1. Append navigation’s entry list[i] to disposedNHEs.

      2. Set i to i + 1.

   4. Remove all items in disposedNHEs from navigation’s entry list.

6. Otherwise, if navigationType is "replace":

   1. Append oldCurrentNHE to disposedNHEs.

7. If navigationType is "push" or "replace":

   1. Let newNHE be a new NavigationHistoryEntry created in the relevant realm of navigation.

   2. Set newNHE’s session history entry to destinationSHE.

   3. Set navigation’s entry list[navigation’s current entry index] to newNHE.

8. Assert: by this point, the current entry of navigation is different from oldCurrentNHE.

9. If navigation’s ongoing navigation is non-null, then notify about the committed-to entry given navigation’s ongoing navigation and the current entry of navigation.

   It is important to do this before firing the dispose or currententrychange events, since event handlers could start another navigation, or otherwise change the value of navigation’s ongoing navigation.

10. Prepare to run script given navigation’s relevant settings object.

    See a similar note elsewhere for other navigation API events to understand why we do this.

11. Fire an event named currententrychange at navigation using NavigationCurrentEntryChangeEvent, with its navigationType attribute initialized to navigationType and its from initialized to oldCurrentNHE.

12. For each disposedNHE of disposedNHEs:

    1. Fire an event named dispose at disposedNHE.

13. Clean up after running script given navigation’s relevant settings object.

To update the entries for reactivation given a Navigation instance navigation, a list of session history entries newSHEs, and a session history entry reactivatedSHE:

1. Let newNHEs be an empty list.

2. Let oldNHEs be a clone of navigation’s entry list.

3. For each newSHE of newSHEs:

   1. Let newNHE be null.

   2. If oldNHEs contains a NavigationHistoryEntry matchingOldNHE whose session history entry is newSHE, then:

      1. Set newNHE to matchingOldNHE.

      2. Remove matchingOldNHE from oldNHEs.

   3. Otherwise:

      1. Set newNHE to a new NavigationHistoryEntry created in the relevant realm of navigation.

      2. Set newNHE’s session history entry to newSHE.

   4. Append newNHE to newNHEs.

4. For each disposedNHE of oldNHEs:

   1. Set disposedNHE’s index to −1.

5. Set navigation’s entry list to newNHEs.

6. Set navigation’s current entry index to the result of getting the navigation API history index of reactivatedSHE within navigation.

7. Queue a global task on the navigation and traversal task source given navigation’s relevant global object to run the following steps:

   1. For each disposedNHE of oldNHEs:

      1. Fire an event named dispose at disposedNHE.

   We delay these events by a task to ensure that dispose events will fire after the pageshow event. (However, the rest of this algorithm runs before the pageshow event fires, to ensure that navigation.entries() and navigation.currentEntry will have correctly-updated values during any pageshow event handlers.) This is motivated by a desire to have pageshow be the first event a page receives upon reactivation.

To initialize the entries for a new Navigation given a Navigation instance navigation, a list of session history entries newSHEs, and a session history entry initialSHE:

1. Assert: navigation’s entry list is empty.

2. Assert: navigation’s current entry index is −1.

3. If navigation has entries and events disabled, then return.

4. For each newSHE of newSHEs:

   1. Let newNHE be a new NavigationHistoryEntry created in the relevant realm of navigation.

   2. Set newNHE’s session history entry to newSHE.

   3. Append newNHE to navigation’s entry list.

5. Set navigation’s current entry index to the result of getting the navigation API history index of initialSHE within navigation.

To get the navigation API history index of a session history entry she within a Navigation navigation:

1. Let index be 0.

2. For each ahe of navigation’s entry list:

   1. If ahe’s session history entry is equal to she, then return index.

   2. Increment index by 1.

3. Assert: this step is never reached.

The entries() method steps are:

1. If this has entries and events disabled, then return the empty list.

2. Return this's entries list.

The canGoBack getter steps are:

1. If this has entries and events disabled, then return false.

2. Assert: this's current entry index is not −1.

3. If this's current entry index is 0, then return false.

4. Return true.

The canGoForward getter steps are:

1. If this has entries and events disabled, then return false.

2. Assert: this's current entry index is not −1.

3. If this's current entry index is equal to this's entry list's size − 1, then return false.

4. Return true.

[Exposed=Window]
interface NavigationCurrentEntryChangeEvent : Event {
  constructor(DOMString type, NavigationCurrentEntryChangeEventInit eventInit);

  readonly attribute NavigationType? navigationType;
  readonly attribute NavigationHistoryEntry from;
};

dictionary NavigationCurrentEntryChangeEventInit : EventInit {
  NavigationType? navigationType = null;
  required NavigationHistoryEntry destination;
};

The current entry for a Navigation navigation is the result running of the following algorithm:

1. If navigation has entries and events disabled, then return null.

2. Assert: navigation’s current entry index is not −1.

3. Return navigation’s entry list[navigation’s current entry index].

The updateCurrentEntry(options) method steps are:

1. Let current be the current entry for this.

2. If current is null, then throw an "InvalidStateError" DOMException.

3. Let serializedState be StructuredSerializeForStorage(options["state"]), rethrowing any exceptions.

4. Set current’s session history entry's navigation API state to serializedState.

5. Fire an event named currententrychange at this using NavigationCurrentEntryChangeEvent, with its navigationType attribute initialized to null and its from initialized to current.

[Exposed=Window]
interface NavigationTransition {
  readonly attribute NavigationType navigationType;
  readonly attribute NavigationHistoryEntry from;
  readonly attribute Promise<undefined> finished;
};

const key1 = navigation.entries()[navigation.currentEntry.index - 1].key;
const key2 = navigation.entries()[navigation.currentEntry.index + 1].key;

navigation.traverseTo(key1); // intentionally no await
navigation.traverseTo(key2);

const p1 = navigation.navigate(url1).finished;
const p2 = navigation.navigate(url2).finished;

To set the upcoming non-traverse navigation given a Navigation navigation, a JavaScript value info, and a serialized state-or-null serializedState:

1. Let committedPromise and finishedPromise be new promises created in navigation’s relevant realm.

2. Mark as handled finishedPromise.

   The web developer doesn’t necessarily care about finishedPromise being rejected:

   • They might only care about committedPromise.

   • They could be doing multiple synchronous navigations within the same task, in which case all but the last will be aborted (causing their finishedPromise to reject). This could be an application bug, but also could just be an emergent feature of disparate parts of the application overriding each others' actions.

   • They might prefer to listen to other transition-failure signals instead of finishedPromise, e.g., the navigateerror event, or the navigation.transition.finished promise.

   As such, we mark it as handled to ensure that it never triggers unhandledrejection events.

3. Let ongoingNavigation be a navigation API method navigation whose navigation object is navigation, key is null, info is info, serialized state is serializedState, committed-to entry is null, committed promise is committedPromise, and finished promise is finishedPromise.

4. Assert: navigation’s upcoming non-traverse navigation is null.

5. Set navigation’s upcoming non-traverse navigation to ongoingNavigation.

6. Return ongoingNavigation.

To set an upcoming traverse navigation given a Navigation navigation, a string key, and a JavaScript value info:

1. Let committedPromise and finishedPromise be new promises created in navigation’s relevant realm.

2. Mark as handled finishedPromise.

   See the previous discussion as to why this is done.

3. Let traversal be a navigation API method navigation whose whose navigation object is navigation, key is key, info is info, serialized state is null, committed-to entry is null, committed promise is committedPromise, and finished promise is finishedPromise.

4. Set navigation’s upcoming traverse navigations[key] to traversal.

5. Return traversal.

To promote the upcoming navigation to ongoing given a Navigation navigation and a string-or-null destinationKey:

1. Assert: navigation’s ongoing navigation is null.

2. If destinationKey is not null, then:

   1. Assert: navigation’s upcoming non-traverse navigation is null.

   2. If navigation’s upcoming traverse navigations[destinationKey] exists, then:

      1. Set navigation’s ongoing navigation to navigation’s upcoming traverse navigations[destinationKey].

      2. Remove navigation’s upcoming traverse navigations[destinationKey].

3. Otherwise,

   1. Set navigation’s ongoing navigation to navigation’s upcoming non-traverse navigation.

   2. Set navigation’s upcoming non-traverse navigation to null.

To clean up a navigation API method navigation navigation:

1. Let navigation be navigation’s navigation object.

2. If navigation’s ongoing navigation is navigation, then set navigation’s ongoing navigation to null.

3. Otherwise,

   1. Assert: navigation’s key is not null.

   2. Assert: navigation’s upcoming traverse navigations[navigation’s key] exists.

   3. Remove navigation’s upcoming traverse navigations[navigation’s key].

To notify about the committed-to entry given a navigation API method navigation navigation and a NavigationHistoryEntry entry:

1. Set navigation’s committed-to entry to entry.

2. If navigation’s serialized state is not null, then set entry’s session history entry's navigation API state to navigation’s serialized state.

   If it’s null, then we’re traversing to entry via traverseTo(), which does not allow changing the state.

   After this point, navigation’s serialized state is no longer needed. Implementations might want to clear it out to avoid keeping it alive for the lifetime of the navigation API method navigation.

3. Resolve navigation’s committed promise with entry.

   After this point, navigation’s committed promise is only needed in cases where it has not yet been returned to author code. Implementations might want to clear it out to avoid keeping it alive for the lifetime of the navigation API method navigation.

To resolve the finished promise for a navigation API method navigation navigation:

1. If navigation’s finished promise is null, then return.

2. Resolve navigation’s finished promise with its committed-to entry.

3. Clean up navigation.

To reject the finished promise for a navigation API method navigation navigation with a JavaScript value exception:

1. If navigation’s finished promise is null, then return.

2. If navigation’s committed promise is not null, then reject navigation’s committed promise with exception.

3. Reject navigation’s finished promise with exception.

4. Clean up navigation.

The navigate(url, options) method steps are:

1. Let document be this's relevant global object's associated document.

2. Let navigable be navigation’s relevant global object's navigable.

3. Assert: navigable is not null.

4. Parse url relative to this's relevant settings object. If that returns failure, then return an early error result for a "SyntaxError" DOMException. Otherwise, let urlRecord be the resulting URL record.

5. If options["history"] is "push", and any of the following are true:

   • document’s is initial about:blank is true;

   • document is not completely loaded;

   • url equals document’s URL; or

   • url’s scheme is "javascript"

   then return an early error result for a "NotSupportedError" DOMException.

   These are the conditions under which a push navigation will be converted into a replace navigation by the navigate algorithm or by the below step. If the developer explicitly requested a push, we fail to let them know it won’t happen.

   In the future, we could consider loosening some of these conditions, e.g., allowing explicitly-requested push navigations to the current URL or before the document is completely loaded.

6. Let state be options["state"] if it exists; otherwise, undefined.

7. Let serializedState be StructuredSerializeForStorage(state). If this throws an exception, then return an early error result for that exception.

   It is important to perform this step early, since serialization can invoke web developer code, which in turn might change the state checked in later steps.

8. Let info be options["info"] if it exists; otherwise, undefined.

9. Let historyHandling be "replace" if options["history"] is "replace" or if document is not completely loaded; otherwise, "push".

10. If document is not fully active, then return an early error result for an "InvalidStateError" DOMException.

11. If document’s unload counter is greater than 0, then return an early error result for an "InvalidStateError" DOMException.

12. Let ongoingNavigation be the result of setting the upcoming non-traverse navigation for navigation given info.

13. Navigate navigable to urlRecord using document, with historyHandling set to historyHandling and navigationAPIState set to serializedState.

    Unlike location.assign() and friends, which are exposed across origin-domain boundaries, navigation.navigate() can only be accessed by code with direct synchronous access to the navigation property. Thus, we avoid the complications around tracking the source document, and we don’t need to deal with the allowed by sandboxing to navigate check and its accompanying exceptionsEnabled flag. We just treat all navigations as being initiated by the Navigation object itself.

14. If navigation’s upcoming non-traverse navigation is ongoingNavigation, then:

    This means the navigate algorithm bailed out before ever getting to the inner navigate event firing algorithm which would promote the upcoming navigation to ongoing.

    1. Set navigation’s upcoming non-traverse navigation to null.

    2. Return an early error result for an "AbortError" DOMException.

15. Return «[ "committed" → ongoingNavigation’s committed promise, "finished" → ongoingNavigation’s finished promise ]».

The reload(options) method steps are:

1. Let document be this's relevant global object's associated document.

2. Let navigable be navigation’s relevant global object's navigable.

3. Assert: navigable is not null.

4. Let serializedState be null.

5. If options["state"] exists, then set serializedState to StructuredSerializeForStorage(options["state"]). If this throws an exception, then return an early error result for that exception.

   It is important to perform this step early, since serialization can invoke web developer code, which in turn might change the state checked in later steps.

6. Otherwise,

   1. Let current be the current entry of this.

   2. If current is not null, then set serializedState to current’s navigation API state.

   3. Otherwise, set serializedState to StructuredSerializeForStorage(undefined).

7. Let info be options["info"] if it exists; otherwise, undefined.

8. If document is not fully active, then return an early error result for an "InvalidStateError" DOMException.

9. If document’s unload counter is greater than 0, then return an early error result for an "InvalidStateError" DOMException.

10. Let ongoingNavigation be the result of setting the upcoming non-traverse navigation for navigation given info.

11. Reload navigable with navigationAPIState set to serializedState.

12. If navigation’s upcoming non-traverse navigation is ongoingNavigation, then:

    This means the reload algorithm bailed out before ever getting to the inner navigate event firing algorithm which would promote the upcoming navigation to ongoing.

    1. Set navigation’s upcoming non-traverse navigation to null.

    2. Return an early error result for an "AbortError" DOMException.

13. Return «[ "committed" → ongoingNavigation’s committed promise, "finished" → ongoingNavigation’s finished promise ]».

The traverseTo(key, options) method steps are:

1. If this's current entry index is −1, then return an early error result for an "InvalidStateError" DOMException.

2. If this's entry list does not contain any NavigationHistoryEntry whose session history entry's navigation API key equals key, then return an early error result for an "InvalidStateError" DOMException.

3. Return the result of performing a navigation API traversal given this, key, and options.

The back(options) method steps are:

1. If this's current entry index is −1 or 0, then return an early error result for an "InvalidStateError" DOMException.

2. Let key be this's entry list[this's current entry index − 1]'s session history entry's navigation API key.

3. Return the result of performing a navigation API traversal given this, key, and options.

The forward(options) method steps are:

1. If this's current entry index is −1 or is equal to this's entry list's size − 1, then return an early error result for an "InvalidStateError" DOMException.

2. Let key be this's entry list[this's current entry index + 1]'s session history entry's navigation API key.

3. Return the result of performing a navigation API traversal given this, key, and options.

To perform a navigation API traversal given a Navigation object navigation, a string key, and a NavigationOptions options:

1. Let sourceDocument be navigation’s relevant global object's associated Document.

2. If sourceDocument is not fully active, then return an early error result for an "InvalidStateError" DOMException.

3. If sourceDocument’s unload counter is greater than 0, then return an early error result for an "InvalidStateError" DOMException.

4. If navigation’s current entry's session history entry's navigation API key equals key, then return «[ "committed" → a promise resolved with navigation’s current entry, "finished" → a promise resolved with navigation’s current entry ]»

5. If navigation’s upcoming traverse navigations[key] exists, then:

   1. Let navigation be navigation’s upcoming traverse navigations[key].

   2. Return «[ "committed" → navigation’s committed promise, "finished" → navigation’s finished promise ]».

6. Let info be options["info"] if it exists, or undefined otherwise.

7. Let ongoingNavigation be the result of setting an upcoming traverse navigation for navigation given key and info.

8. Let navigable be sourceDocument’s node navigable.

9. Let traversable be navigable’s traversable navigable.

10. Let sourceSnapshotParams be the result of snapshotting source snapshot params given sourceDocument.

11. Append the following session history traversal steps to traversable:

    1. Let navigableEntries be the result of getting session history entries given navigable.

    2. Let targetEntry be the session history entry in navigableEntries whose navigation API key equals key. If no such entry exists, then:

       1. Queue a global task on the navigation and traversal task source given sourceDocument’s relevant global object to reject the finished promise for ongoingNavigation with an "InvalidStateError" DOMException.

       2. Abort these steps.

       This can occur if the navigation object’s view of session history is outdated, which can happen for brief periods while all the relevant threads and processes are being synchronized in reaction to a history change (such as the user clearing their history).

    3. If targetEntry is navigable’s active session history entry, then abort these steps.

       This can occur if a previously-queued-up traversal already took us to this session history entry. In that case that previous traversal will have dealt with ongoingNavigation already.

    4. Apply the history step given by targetEntry’s step to traversable, with checkForUserCancellation set to true, sourceSnapshotParams set to sourceSnapshotParams, and initiatorToCheck set to navigable.

       • If this aborts due to user-canceled unloading or due to the navigate event being canceled, then queue a global task on the navigation and traversal task source given sourceDocument’s relevant global object to finalize with an aborted navigation error given navigation and ongoingNavigation.

       • If this aborts due to the initiator allowed-to-navigate check, then queue a global task on the navigation and traversal task source given sourceDocument’s relevant global object to finalize with an aborted navigation error given navigation, ongoingNavigation, and a new "SecurityError" DOMException created in navigation’s relevant realm.

       As part of merging this spec into HTML, we would modify apply the history step to have well-specified hooks for communicating these conditions back to its caller.

12. Return «[ "committed" → ongoingNavigation’s committed promise, "finished" → ongoingNavigation’s finished promise ]».

[Exposed=Window]
interface NavigateEvent : Event {
  constructor(DOMString type, NavigateEventInit eventInit);

  readonly attribute NavigationType navigationType;
  readonly attribute NavigationDestination destination;
  readonly attribute boolean canIntercept;
  readonly attribute boolean userInitiated;
  readonly attribute boolean hashChange;
  readonly attribute AbortSignal signal;
  readonly attribute FormData? formData;
  readonly attribute DOMString? downloadRequest;
  readonly attribute any info;

  undefined intercept(optional NavigationInterceptOptions options = {});
  undefined scroll();
};

dictionary NavigateEventInit : EventInit {
  NavigationType navigationType = "push";
  required NavigationDestination destination;
  boolean canIntercept = false;
  boolean userInitiated = false;
  boolean hashChange = false;
  required AbortSignal signal;
  FormData? formData = null;
  DOMString? downloadRequest = null;
  any info;
};

dictionary NavigationInterceptOptions {
  NavigationInterceptHandler handler;
  NavigationFocusReset focusReset;
  NavigationScrollBehavior scroll;
};

enum NavigationFocusReset {
  "after-transition",
  "manual"
};

enum NavigationScrollBehavior {
  "after-transition",
  "manual"
};

callback NavigationInterceptHandler = Promise<undefined> ();

enum NavigationType {
  "reload",
  "push",
  "replace",
  "traverse"
};

The intercept(options) method steps are:

1. If this's relevant global object's associated Document is not fully active, then throw an "InvalidStateError" DOMException.

2. If this's isTrusted attribute was initialized to false, then throw a "SecurityError" DOMException.

3. If this's canIntercept attribute was initialized to false, then throw a "SecurityError" DOMException.

4. If this's dispatch flag is unset, then throw an "InvalidStateError" DOMException.

5. If this's canceled flag is set, then throw an "InvalidStateError" DOMException.

6. If options["handler"] exists, then append it to this's navigation handler list.

7. Set this's was intercepted to true.

8. If options["focusReset"] exists, then:

   1. If this's focus reset behavior is not null, and it is not equal to options["focusReset"], then the user agent may report a warning to the console indicating that the focusReset option for a previous call to intercept() was overridden by this new value, and the previous value will be ignored.

   2. Set this's focus reset behavior to options["focusReset"].

9. If options["scroll"] exists, then:

   1. If this's scroll behavior is not null, and it is not equal to options["scroll"], then the user agent may report a warning to the console indicating that the scroll option for a previous call to intercept() was overridden by this new value, and the previous value will be ignored.

   2. Set this's scroll behavior to options["scroll"].

The scroll() method steps are:

1. If this's did process scroll behavior is true, then throw an "InvalidStateError" DOMException.

2. If this's was intercepted is false, then throw an "InvalidStateError" DOMException.

3. If this's relevant global object's associated Document is not fully active, then throw an "InvalidStateError" DOMException.

4. Definitely process scroll behavior given this.

[Exposed=Window]
interface NavigationDestination {
  readonly attribute USVString url;
  readonly attribute DOMString? key;
  readonly attribute DOMString? id;
  readonly attribute long long index;
  readonly attribute boolean sameDocument;

  any getState();
};

The getState() method steps are:

1. If this's state is null, then return undefined.

2. Return StructuredDeserialize(this's state).

To fire a traversal navigate event at a Navigation navigation given a session history entry destinationEntry, and an optional user navigation involvement userInvolvement (default "none"):

1. Let event be the result of creating an event given NavigateEvent, in navigation’s relevant realm.

2. Set event’s classic history API serialized data to null.

3. Let destination be a new NavigationDestination created in navigation’s relevant realm.

4. Set destination’s URL to destinationEntry’s URL.

5. If destinationEntry’s document state's origin is same origin with navigation’s relevant settings object's origin, then:

   1. Set destination’s key to destinationEntry’s navigation API key.

   2. Set destination’s id to destinationEntry’s navigation API ID.

   3. Set destination’s index to the result of getting the navigation API history index of destinationEntry within navigation.

   4. Set destination’s state to destinationEntry’s navigation API state.

6. Otherwise,

   1. Set destination’s key to null.

   2. Set destination’s id to null.

   3. Set destination’s index to −1.

   4. Set destination’s state to null.

7. Set destination’s is same document to true if destinationEntry’s document is equal to navigation’s relevant global object's associated Document; otherwise false.

8. Return the result of performing the inner navigate event firing algorithm given navigation, "traverse", event, destination, userInvolvement, null, and null.

To fire a non-traversal navigate event at a Navigation navigation given a NavigationType navigationType, a URL destinationURL, a boolean isSameDocument, an optional user navigation involvement userInvolvement (default "none"), an optional serialized state-or-null state (default null), an optional entry list or null formDataEntryList (default null), and an optional serialized state-or-null classicHistoryAPISerializedData (default null):

1. Let event be the result of creating an event given NavigateEvent, in navigation’s relevant realm.

2. Set event’s classic history API serialized data to classicHistoryAPISerializedData.

3. Let destination be a new NavigationDestination created in navigation’s relevant realm.

4. Set destination’s URL to destinationURL.

5. Set destination’s key to null.

6. Set destination’s id to null.

7. Set destination’s index to −1.

8. Set destination’s state to state.

9. Set destination’s is same document to isSameDocument.

10. Return the result of performing the inner navigate event firing algorithm given navigation, navigationType, event, destination, userInvolvement, formDataEntryList, and null.

To fire a download-requested navigate event at a Navigation navigation given a URL destinationURL, a user navigation involvement userInvolvement, and a string filename:

1. Let event be the result of creating an event given NavigateEvent, in navigation’s relevant realm.

2. Set event’s classic history API serialized data to null.

3. Let destination be a new NavigationDestination created in navigation’s relevant realm.

4. Set destination’s URL to destinationURL.

5. Set destination’s key to null.

6. Set destination’s id to null.

7. Set destination’s index to −1.

8. Set destination’s state to null.

9. Set destination’s is same document to false.

10. Return the result of performing the inner navigate event firing algorithm given navigation, "push", event, destination, userInvolvement, null, and filename.

The inner navigate event firing algorithm is the following steps, given a Navigation navigation, a NavigationType navigationType, a NavigateEvent event, a NavigationDestination destination, a user navigation involvement userInvolvement, an entry list or null formDataEntryList, and a string or null downloadRequestFilename:

1. Promote the upcoming navigation to ongoing given navigation and destination’s key.

2. Let ongoingNavigation be navigation’s ongoing navigation.

3. If navigation has entries and events disabled, then:

   1. If ongoingNavigation is not null, then clean up ongoingNavigation.

      In this case the committed promise and finished promise will never fulfill, since we never create NavigationHistoryEntrys for the initial about:blank Document so we have nothing to resolve them with.

   2. Return true.

4. Let navigable be navigation’s relevant global object's navigable.

5. Let document be navigation’s relevant global object's associated document.

6. If document can have its URL rewritten to destination’s URL, and either destination’s is same document is true or navigationType is not "traverse", then initialize event’s canIntercept to true. Otherwise, initialize it to false.

7. Let traverseCanBeCanceled be true if userInvolvement is not "browser UI" or navigation’s relevant global object has transient activation; otherwise, false.

   We are exploring the possibility of introducing the concept of a "consumable user activation" (i.e., a user activation that can be consumed like a transient user activation, but does not have the timeout of a transient user activation) instead of using transient activation here. This does not have a spec yet.

8. If any of the following are true:

   • navigationType is not "traverse"; or

   • navigable is a top-level traversable and traverseCanBeCanceled is true

   then initialize event’s cancelable to true. Otherwise, initialize it to false.

9. Initialize event’s type to "navigate".

10. Initialize event’s navigationType to navigationType.

11. Initialize event’s destination to destination.

12. Initialize event’s downloadRequest to downloadRequestFilename.

13. If ongoingNavigation is not null, then initialize event’s info to ongoingNavigation’s info. Otherwise, initialize it to undefined.

    At this point ongoingNavigation’s info is no longer needed and can be nulled out instead of keeping it alive for the lifetime of the navigation API method navigation.

14. Initialize event’s signal to a new AbortSignal created in navigation’s relevant realm.

15. Let currentURL be document’s URL.

16. If all of the following are true:

    • destination’s is same document is true;

    • destination’s URL equals currentURL with exclude fragments set to true; and

    • destination’s URL's fragment is not identical to currentURL’s fragment

    then initialize event’s hashChange to true. Otherwise, initialize it to false.

17. If userInvolvement is not "none", then initialize event’s userInitiated to true. Otherwise, initialize it to false.

18. If formDataEntryList is not null, then initialize event’s formData to a new FormData created in navigation’s relevant realm, associated to formDataEntryList. Otherwise, initialize it to null.

19. Assert: navigation’s ongoing navigate event is null.

20. Set navigation’s ongoing navigate event to event.

21. Assert: navigation’s ongoing navigation signal is null.

22. Set navigation’s ongoing navigation signal to event’s signal.

23. Set navigation’s focus changed during ongoing navigation to false.

24. Set navigation’s suppress normal scroll restoration during ongoing navigation to false.

25. Let dispatchResult be the result of dispatching event at navigation.

26. If dispatchResult is false:

    1. If navigationType is not "traverse" and event’s signal is not aborted, then finalize with an aborted navigation error given navigation and ongoingNavigation.

       If navigationType is "traverse", then we will finalize with an aborted navigation error in perform a navigation API traversal.

    2. Return false.

27. If destination’s is same document is true and navigationType is "traverse":

    1. Set event’s needs continue to true.

    2. Return true.

28. Return the result of reacting to navigate event result given navigation and event.

To react to navigate event result, given a Navigation navigation and a NavigateEvent event:

1. Let document be navigation’s relevant global object's associated document.

2. Let destination be event’s destination.

3. Let ongoingNavigation be navigation’s ongoing navigation.

4. Let navigationType be event’s navigationType.

5. Let endResultIsSameDocument be true if event’s was intercepted is true or destination’s is same document is true.

6. Prepare to run script given event’s relevant settings object.

   This is done to avoid the JavaScript execution context stack becoming empty right after any currententrychange event handlers run as a result of the URL and history update steps that could soon happen. If the stack were to become empty at that time, then it would immediately perform a microtask checkpoint, causing various promise fulfillment handlers to run interleaved with the event handlers and before any handlers passed to navigateEvent.intercept(). This is undesirable since it means promise handler ordering vs. currententrychange event handler ordering vs. intercept() handler ordering is dependent on whether the navigation is happening with an empty JavaScript execution context stack (e.g., because the navigation was user-initiated) or with a nonempty one (e.g., because the navigation was caused by a JavaScript API call).

   By inserting an otherwise-unnecessary JavaScript execution context onto the stack in this step, we essentially suppress the perform a microtask checkpoint algorithm until later, thus ensuring that the sequence is always: currententrychange event handlers, then intercept() handlers, then promise handlers.

7. If event’s was intercepted is true:

   1. Let fromEntry be the current entry for navigation.

   2. Assert: fromEntry is not null.

   3. Set navigation’s transition to a new NavigationTransition created in navigation’s relevant realm, whose navigation type is navigationType, from entry is fromEntry, and whose finished promise is a new promise created in navigation’s relevant realm.

   4. Mark as handled navigation’s transition's finished promise.

      See the discussion about other finished promises as to why this is done.

   5. If navigationType is "traverse", then set navigation’s suppress normal scroll restoration during ongoing navigation to true.

      If event’s scroll behavior was set to "after-transition", then we will potentially perform scroll restoration below. Otherwise, there will be no scroll restoration. That is, no navigation which is intercepted by intercept() goes through the normal scroll restoration process; scroll restoration for such navigations is either done manually, by the web developer, or is done after the transition.

   6. If navigationType is "push" or "replace", then run the URL and history update steps given document and event’s destination's URL, with serializedData set to event’s classic history API serialized data and historyHandling set to navigationType.

      If navigationType is "reload", then we are converting a reload into a "same-document reload", for which the URL and history update steps are not appropriate. Navigation API-related stuff still happens, such as updating the active session history entry's navigation API state if this was caused by a call to navigation.reload(), and all the ongoing navigation tracking.

8. If endResultIsSameDocument is true:

   1. Let promisesList be an empty list.

   2. For each handler of event’s navigation handler list:

      1. Append the result of invoking handler to promisesList with an empty arguments list.

   3. If promisesList’s size is 0, then set promisesList to « a promise resolved with undefined ».

      There is a subtle timing difference between how waiting for all schedules its success and failure steps when given zero promises versus ≥1 promises. For most uses of waiting for all, this does not matter. However, with this API, there are so many events and promise handlers which could fire around the same time that the difference is pretty easily observable: it can cause the event/promise handler sequence to vary. (Some of the events and promises involved include: navigatesuccess / navigateerror, currententrychange, dispose, ongoingNavigation’s promises, and the navigation.transition.finished promise.)

   4. Wait for all of promisesList, with the following success steps:

      1. If event’s signal is aborted, then abort these steps.

      2. If event equals navigation’s ongoing navigate event, set navigation’s ongoing navigate event to null.

      3. Fire an event named navigatesuccess at navigation.

      4. If navigation’s transition is not null, then resolve navigation’s transition's finished promise with undefined.

      5. Set navigation’s transition to null.

      6. If ongoingNavigation is non-null, then resolve the finished promise for ongoingNavigation.

      7. Potentially reset the focus given navigation and event.

      8. Potentially process scroll behavior given event.

      and the following failure steps given reason rejectionReason:

      1. If event’s signal is aborted, then abort these steps.

      2. Fire an event named navigateerror at navigation using ErrorEvent, with error initialized to rejectionReason, and message, filename, lineno, and colno initialized to appropriate values that can be extracted from rejectionReason in the same underspecified way the user agent typically does for the report an exception algorithm.

      3. If navigation’s transition is not null, then reject navigation’s transition's finished promise with rejectionReason.

      4. Set navigation’s transition to null.

      5. If ongoingNavigation is non-null, then reject the finished promise for ongoingNavigation with rejectionReason.

      6. Potentially reset the focus given navigation and event.

         Although we still potentially reset the focus for such failed transitions, we do not potentially process scroll behavior for them.

9. Otherwise, if ongoingNavigation is non-null, then clean up ongoingNavigation.

10. Clean up after running script given event’s relevant settings object.

    Per the previous note, this stops suppressing any potential promise handler microtasks, causing them to run at this point or later.

11. If event’s was intercepted is true, then return false.

12. Return true.

To maybe continue the navigate event, given a Navigation navigation:

1. If navigation’s ongoing navigate event is null, or navigation’s ongoing navigate event's needs continue is false, then return.

2. React to navigate event result given navigation and navigation’s ongoing navigate event.

To finalize with an aborted navigation error given a Navigation navigation, a navigation API method navigation or null ongoingNavigation, and an optional DOMException error:

1. Set navigation’s focus changed during ongoing navigation to false.

2. Set navigation’s suppress normal scroll restoration during ongoing navigation to false.

3. If error was not given, then set error to a new "AbortError" DOMException, created in navigation’s relevant realm.

4. If navigation’s ongoing navigate event is non-null, then:

   1. Set navigation’s ongoing navigate event's canceled flag to true.

   2. Set navigation’s ongoing navigate event to null.

5. If navigation’s ongoing navigation signal is non-null, then:

   1. Signal abort on navigation’s ongoing navigation signal given error.

   2. Set navigation’s ongoing navigation signal to null.

6. Fire an event named navigateerror at navigation using ErrorEvent, with error initialized to error, and message, filename, lineno, and colno initialized to appropriate values that can be extracted from error and the current JavaScript stack in the same underspecified way the user agent typically does for the report an exception algorithm.

   Thus, for example, if this algorithm is reached because of a call to window.stop(), these properties would probably end up initialized based on the line of script that called window.stop(). But if it’s because the user clicked the stop button, these properties would probably end up with default values like the empty string or 0.

7. If ongoingNavigation is non-null, then reject the finished promise for ongoingNavigation with error.

8. If navigation’s transition is not null, then:

   1. Reject navigation’s transition's finished promise with error.

   2. Set navigation’s transition to null.

To inform the navigation API about canceling navigation in a navigable navigable:

1. Let navigation be navigable’s active window's navigation API.

2. If navigation’s ongoing navigation signal is null, then return.

3. Finalize with an aborted navigation error given navigation and navigation’s ongoing navigation.

To inform the navigation API about nested navigable destruction given a navigable navigable:

1. Inform the navigation API about canceling navigation in navigable.

2. Let navigation be navigable’s active window's navigation API.

3. Let traversals be a clone of navigation’s upcoming traverse navigations.

4. For each traversal of traversals: finalize with an aborted navigation error given navigation and traversal.

To potentially reset the focus given a Navigation object navigation and an NavigateEvent event:

1. Let focusChanged be navigation’s focus changed during ongoing navigation.

2. Set navigation’s focus changed during ongoing navigation to false.

3. If focusChanged is true, then return.

4. If event’s was intercepted is false, then return.

5. If event’s focus reset behavior is "manual", then return.

   If it was left as null, then we treat that as "after-transition", and continue onward.

6. Let document be navigation’s relevant global object's associated Document.

7. Let focusTarget be the autofocus delegate for document.

8. If focusTarget is null, then set focusTarget to document’s body element.

9. If focusTarget is null, then set focusTarget to document’s document element.

10. Run the focusing steps for focusTarget, with document’s viewport as the fallback target.

11. Move the sequential focus navigation starting point to focusTarget.

To potentially process scroll behavior given a NavigateEvent event:

1. If event’s was intercepted is false, then return.

2. If event’s scroll behavior is "manual", then return.

   If it was left as null, then we treat that as "after-transition", and continue onward.

3. If event’s did process scroll behavior is true, then return.

4. Definitely process scroll behavior given event.

To definitely process scroll behavior given a NavigateEvent event:

1. Set event’s did process scroll behavior to true.

2. If event’s navigationType was initialized to "traverse" or "reload", then restore scroll position data given event’s relevant global object's navigable's active session history entry.

3. Otherwise,

   1. Let document be event’s relevant global object's associated Document.

   2. If document’s indicated part is null, then scroll to the beginning of the document given document.

   3. Otherwise, scroll to the fragment given document.

[Exposed=Window]
interface NavigationHistoryEntry : EventTarget {
  readonly attribute USVString? url;
  readonly attribute DOMString key;
  readonly attribute DOMString id;
  readonly attribute long long index;
  readonly attribute boolean sameDocument;

  any getState();

  attribute EventHandler ondispose;
};

The key getter steps are:

1. If this's relevant global object's associated Document is not fully active, then return the empty string.

2. Return this's session history entry's navigation API key.

The id getter steps are:

1. If this's relevant global object's associated Document is not fully active, then return the empty string.

2. Return this's session history entry's navigation API ID.

The url getter steps are:

1. If this's relevant global object's associated Document is not fully active, then return null.

2. Let she be this's session history entry.

3. If she’s document does not equal this's relevant global object's associated Document, and she’s document state's request referrer policy is "no-referrer" or "origin", then return null.

4. Return she’s URL, serialized.

The index getter steps are:

1. If this's relevant global object's associated Document is not fully active, then return −1.

2. Return this's index.

The sameDocument getter steps are:

1. If this's relevant global object's associated Document is not fully active, then return false.

2. Return true if this's session history entry's document equals this's relevant global object's associated Document, and false otherwise.

The getState() method steps are:

1. If this's relevant global object's associated Document is not fully active, then return undefined.

2. If this's session history entry's navigation API state is null, then return undefined.

3. Return StructuredDeserialize(this's session history entry's navigation API state).

Unlike history.state, this will deserialize upon each access.

This can in theory throw an exception, if attempting to deserialize a large ArrayBuffer when not enough memory is available.

Modify the navigate algorithms parameter list as follows:

• Add an optional entry list or null entryList (default null)

• Add an optional user navigation involvement userInvolvement (default "none")

• Add an optional serialized state or null navigationAPIState (default null)

• Remove cspNavigationType

Add the following step early in the algorithm:

1. Let cspNavigationType be "form-submission" if entryList is non-null; otherwise, "other".

Add the following steps right before we go in parallel:

1. Let navigation be navigable’s active window's navigation API.

2. If all of the following are false:

   • userInvolvement is "browser UI"

   • navigable’s active document's origin is not same origin-domain with sourceDocument’s origin

   • navigable’s active document's is initial about:blank is true

   • url’s scheme is not a fetch scheme

   then:

   1. Let continue be the result of firing a non-traversal navigate event at navigation with navigationType set to historyHandling, isSameDocument set to false, userInvolvement set to userInvolvement, formDataEntryList set to entryList, destinationURL set to url, and state set to navigationAPIState.

   2. If continue is false, return.

   "browser UI" or cross origin-domain navigations that cause fragment navigations do fire the navigate event; those are handled as part of the navigate to a fragment algorithm called earlier in navigate, which is not guarded by this condition.

Modify the navigate to a fragment algorithm to take a new userInvolvement argument. Then prepend the following steps:

1. Let navigation be navigable’s active window's navigation API.

2. Let continue be the result of firing a non-traversal navigate event at navigation given with navigationType set to historyHandling, isSameDocument set to true, userInvolvement set to userInvolvement, and destinationURL set to url.

3. If continue is false, then return.

Modify the step which creates the new historyEntry to also copy over the navigation API state from the active session history entry.

Insert the following step after the call to update document for history step application:

1. Update the entries for a same-document navigation given navigable’s active window's navigation API, navigable’s active session history entry, and historyHandling.

Modify the shared history push/replace state steps by inserting the following steps right before the step that runs the URL and history update steps.

1. Let navigation be history’s relevant global object's navigation API.

2. Let continue be the result of firing a non-traversal navigate event at navigation with navigationType set to historyHandling, isSameDocument set to true, destinationURL set to newURL, and classicHistoryAPISerializedData set to serializedData.

3. If continue is false, then return.

Update the URL and history update steps by appending the following step right after setting the active session history entry:

1. Update the entries for a same-document navigation given document’s relevant global object's navigation API, navigable’s active session history entry, and historyHandling.

Update the update document for history step application algorithm as follows:

Prepend the following step:

1. Let navigation be document’s relevant global object's navigation API.

Inside the "documentsEntryChanged is true" block, after restore the history state object:

1. If documentIsNew is false, then update the entries for a same-document navigation given navigation, entry, and "traverse".

2. Otherwise, initialize the entries for a new Navigation given navigation, sessionHistoryEntries TODO pass this in, and entry.

This means any currententrychange event and dispose events will fire before the popstate and hashchange events, and those event handlers will see an updated Navigation object.

Insert the following step into finalize a cross-document navigation's "Otherwise" branch (where entryToReplace is non-null):

1. If historyEntry’s document state's origin is the same as entryToReplace’s document state's origin, then set historyEntry’s navigation API key to entryToReplace’s navigation API key.

Update the reactivate algorithm by adding the following step before the final top-level step which checks the current document readiness:

1. Update the entries for reactivation given document’s relevant global object's navigation API, sessionHistoryEntries TODO pass this in (harder), and entry TODO pass this in (easier).

Modify the reload algorithm to take an optional navigationAPIState (default null) and an optional userInvolvement (default "none"). Then, prepend the following steps:

1. Let navigation be navigable’s active window's navigation API.

2. If both of the following are true:

   • userInvolvement is not "browser UI"

   • navigable’s active document's is initial about:blank is false

   then:

   1. Let continue be the result of firing a non-traversal navigate event at navigation with navigationType set to "reload", isSameDocument set to false, userInvolvement set to userInvolvement, destinationURL set to navigable’s active document's URL, and state set to navigationAPIState.

   2. If continue is false, return.

• Ensure that the algorithm gets an appropriate user navigation involvement value, userInvolvement, passed to it. This is similar to the modifications for the follow the hyperlink algorithm described in § 4.15.1 User navigation involvement. One key difference is that, for the case where the user indicates a preference for downloading, userInvolvement must be "browser UI", even if it is triggered as part of activation behavior.

• Separate out the sandboxing checks in allowed to download from the user-safeguarding checks. If the sandboxing checks fail, then the user agent must not fire a navigate event. Whereas, the user-safeguarding checks generally happen later, probably in parallel.

• Before we reach the point at which it’s time to actually go in parallel and fetch content from the server, and after the cannot navigate check, the synchronously-possible part of the allowed to download check, the URL parsing step, and the hyperlink suffix appending step, run the equivalent of the following:

  1. If userInvolvement is not "browser UI", then:

     1. Let navigation be subject’s relevant global object's navigation API.

     2. Let filename be the value of subject’s download attribute.

     3. Let continue be the result of firing a download-requested navigate event at navigation with destinationURL set to URL, userInvolvement set to userInvolvement, and filename set to filename.

     4. If continue is false, then return.

  Here the variables subject and URL refer to the same things they currently do in the download the hyperlink algorithm, i.e. the a or area element in question, and the parsed URL.

  If we end up triggering the navigate algorithm from the download the hyperlink algorithm, then these steps won’t be directly incorporated into the download the hyperlink algorithm. Instead, the modifications in § 4.2 Navigate will get a bit more complicated, so as to use fire a download-requested navigate event with the above arguments, instead of fire a non-traversal navigate event, for downloads.

navigation.addEventListener("navigate", e => {
  e.intercept({
    handler() {
      return new Promise(r => setTimeout(r, 1_000));
    }
  });
  e.signal.addEventListener("abort", () => { ... });
});

const p = navigation.navigate("#1");

setTimeout(() => window.stop(), 500);

Modify the check if unloading is user-canceled algorithm as follows:

To check if unloading is user-canceled given a list of navigables navigablesCrossingDocuments, an optional navigable traversable, an optional integer targetStep (default null), and an optional user navigation involvement userInvolvement (default "none"):

1. Let unloadPromptShown be false.

2. Let unloadPromptCanceled be false.

3. Let changingNavigables be a list of navigables, initially empty.

4. If traversable is not null and targetStep is not null, append the result of get all navigables whose current session history entry will change or reload given traversable and targetStep to changingNavigables.

5. Otherwise, append navigablesCrossingDocuments to changingNavigables.

6. Let totalTasks be the size of changingNavigables.

7. Let completedTasks be 0.

8. If traversable is not null and changingNavigables contains traversable:

   1. Let targetEntry be the result of getting the target history entry given traversable and targetStep.

   2. Let isSameOrigin be true if targetEntry’s document state's origin is the same as traversable’s current session history entry's document state's origin; otherwise, false.

   3. Queue a global task on the navigation and traversal task source given traversable’s active window to run the following steps:

      1. If isSameOrigin is true:

         1. Let navigateEventResult be the result of firing a traversal navigate event at traversable’s active window's navigation API with destinationEntry set to targetEntry and userInvolvement set to userInvolvement.

         2. If navigateEventResult is false, then set unloadPromptCanceled to true.

      2. If unloadPromptCanceled is false and navigablesCrossingDocuments contains traversable:

         1. Run the steps to fire a beforeunload event (currently steps 6.1 thru 6.8 in the check if unloading is user-canceled steps).

      3. Increment completedTasks.

   4. Wait for completedTasks to be 1.

   5. If unloadPromptCanceled is true, then return "refuse";

9. For each navigable of changingNavigables:

   1. If navigable equals traversable, then continue.

   2. Let targetEntry be the result of getting the target history entry given traversable and targetStep.

   3. Let isSameOrigin be true if targetEntry’s document state's origin is the same as navigable’s current session history entry's document state's origin; otherwise, false.

   4. Queue a global task on the navigation and traversal task source given navigable’s active window to run the following steps:

      1. If isSameOrigin is true:

         1. Let navigateEventResult be the result of firing a traversal navigate event at navigable’s active window's navigation API with destinationEntry set to targetEntry and userInvolvement set to userInvolvement.

         2. Assert: navigateEventResult is true.

      2. If navigablesCrossingDocuments contains navigable:

         1. Run the steps to fire a beforeunload event (currently steps 6.1 thru 6.8 in the check if unloading is user-canceled steps).

      3. Increment completedTasks.

10. Wait for completedTasks to be totalTasks.

11. Return unloadPromptCanceled.

Modify the apply the history step algorithm as follows:

Change step 5 (which runs the check if unloading is user-canceled steps) to:

1. If checkForUserCancelation is true, and the result of checking if unloading is user-canceled given navigablesCrossingDocuments, traversable, targetStep and userInvolvement is "refuse", then return.

(Recall that we introduced the userInvolvement parameter as part of § 4.10 Traversal.)

Before the update document for history step application (currently step 14.10.3), add the following step:

1. If changingNavigableContinuation’s update-only is true, maybe continue the navigate event given displayedDocument’s relevant global object's navigation API.

Modify the activation behavior of area elements by introducing the event argument and replacing the follow the hyperlink step with the following:

1. Otherwise, follow the hyperlink created by element with the user navigation involvement for event.

Modify the activation behavior of a elements by replacing its follow the hyperlink step with the following:

1. Otherwise, follow the hyperlink created by element with the user navigation involvement for event.

Define the process of restoring scroll position data given a session history entry entry as follows:

1. Let document be entry’s document.

2. If document’s has been scrolled by the user is true, then the user agent should return.

3. The user agent should attempt to use entry’s scroll position data to restore the scroll positions of document’s restorable scrollable regions. The user agent may continue to attempt to do so periodically, until document’s has been scrolled by the user becomes true.

   This is formulated as an attempt, which is potentially repeated until success or until the user scrolls, due to the fact that relevant content indicated by the scroll position data might take some time to load from the network.

   Scroll restoration might be affected by scroll anchoring. [CSS-SCROLL-ANCHORING-1]

With this in place, modify the restore persisted state algorithm’s first step to read as follows:

1. If entry’s scroll restoration mode is "auto", and entry’s document's relevant global object's navigation API's suppress normal scroll restoration during ongoing navigation is false, then restore scroll position data given entry.

In addition to the existing note, add the following one:

If the suppress normal scroll restoration during ongoing navigation boolean is true, then restoring scroll position data might still happen at a later point, as part of potentially processing scroll behavior for the relevant Navigation object, or via a navigateEvent.scroll() method call.