Add navigation hooks for WebDriver BiDi history traversal

WebDriver BiDi wants to invoke the 'traverse the history by a delta`
algorithm, and get a callback whenever the algoritihm has run to
completion, either by failing or by the navigation or state
restoration completing.

w3c/webdriver-bidi#109 is the WebDriver BiDi
side of this change.

Author: jgraham

source

@@ -4147,6 +4147,8 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
      <li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-fragment-navigated">WebDriver BiDi fragment navigated</dfn></li>
      <li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-dom-content-loaded">WebDriver BiDi DOM content loaded</dfn></li>
      <li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-load-complete">WebDriver BiDi load complete</dfn></li>
+     <li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-page-show">WebDriver BiDi page show</dfn></li>
+     <li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-pop-state">WebDriver BiDi pop state</dfn></li>
     </ul>
    </dd>
 
@@ -84908,16 +84910,23 @@ interface <dfn interface>History</dfn> {
 
   <hr>
 
-  <p>To <dfn>traverse the history by a delta</dfn> given <var>delta</var> and <span>browsing
-  context</span> <var>source browsing context</var>, the user agent must append a <span
-  data-x="concept-task">task</span> to this <span>top-level browsing context</span>'s <span>session
-  history traversal queue</span>, the <span data-x="concept-task">task</span> consisting of running
-  the following steps:</p>
+  <p>To <dfn>traverse the history by a delta</dfn> given <var>delta</var>, <span>browsing
+  context</span> <var>source browsing context</var>, and an optional <span
+  data-x="navigation-id">navigation id</span> <var>navigationId</var> (default null),
+  the user agent must append a <span data-x="concept-task">task</span> to this <span>top-level
+  browsing context</span>'s <span>session history traversal queue</span>, the <span
+  data-x="concept-task">task</span> consisting of running the following steps:</p>
 
   <ol>
    <li><p>If the index of the <span>current entry of the joint session history</span> plus
    <var>delta</var> is less than zero or greater than or equal to the number of items in the
-   <span>joint session history</span>, then return.</p>
+   <span>joint session history</span>, invoke <span>WebDriver BiDi navigation failed</span>
+   with <var>source browsing context</var>, and a <span>WebDriver BiDi navigation status</span> whose <span
+   data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
+   data-x="navigation-status-status">status</span> is "<code
+   data-x="navigation-status-canceled">canceled</code>", and <span
+   data-x="navigation-status-url">url</span> is <var>resource</var>'s <span
+   data-x="concept-request-url">url</span>, then return.</p></li>
 
    <li><p>Let <var>specified entry</var> be the entry in the <span>joint session
    history</span> whose index is the sum of <var>delta</var> and the index of the
@@ -84927,17 +84936,32 @@ interface <dfn interface>History</dfn> {
    the <var>specified entry</var>.</p></li>
 
    <li><p>If <var>source browsing context</var> is not <span>allowed to navigate</span>
-   <var>specified browsing context</var>, then return.</p></li>
+   <var>specified browsing context</var>, then invoke <span>WebDriver BiDi navigation failed</span> with
+   with <var>source browsing context</var>, and a <span>WebDriver BiDi navigation status</span> whose <span
+   data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
+   data-x="navigation-status-status">status</span> is "<code
+   data-x="navigation-status-canceled">canceled</code>", and <span
+   data-x="navigation-status-url">url</span> is <var>resource</var>'s <span
+   data-x="concept-request-url">url</span>, then return.</p></li>
 
    <li><p>If the <var>specified browsing context</var>'s <span>active document</span>'s <span>unload
-   counter</span> is greater than 0, then return.</p></li>
+   counter</span> is greater than 0, then invoke <span>WebDriver BiDi navigation failed</span> with
+   with <var>source browsing context</var>, and a <span>WebDriver BiDi navigation status</span> whose <span
+   data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
+   data-x="navigation-status-status">status</span> is "<code
+   data-x="navigation-status-canceled">canceled</code>", and <span
+   data-x="navigation-status-url">url</span> is <var>resource</var>'s <span
+   data-x="concept-request-url">url</span>, then return.</p></li>
 
    <li>
     <p><span>Queue a global task</span> on the <span>history traversal task source</span> given
     <var>specified browsing context</var>'s <span>active window</span> to perform the following
     steps:</p>
 
     <ol>
+     <li><p>If <var>navigationId</var> is null, let <var>navigation id</var> be the result of
+     <span>generating a random UUID</span>. <ref spec=UUID></p></li>
+
      <li><p>If there is an ongoing attempt to navigate <var>specified browsing context</var>
      that has not yet <span data-x="concept-navigate-mature">matured</span> (i.e. it has not passed the
      point of making its <code>Document</code> the <span>active document</span>), then cancel that
@@ -84951,7 +84975,13 @@ interface <dfn interface>History</dfn> {
       <ol>
        <li><p><span>Prompt to unload</span> the <span>active document</span> of the <var>specified
        browsing context</var>. If the user <span>refused to allow the document to be
-       unloaded</span>, then return.</p></li>
+       unloaded</span>, then invoke <span>WebDriver BiDi navigation failed</span> with
+       with <var>source browsing context</var>, and a <span>WebDriver BiDi navigation status</span>
+       whose <span data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
+       data-x="navigation-status-status">status</span> is "<code
+       data-x="navigation-status-canceled">canceled</code>", and <span
+       data-x="navigation-status-url">url</span> is <var>resource</var>'s <span
+       data-x="concept-request-url">url</span>, then return.</p></li>
 
        <li><p><span data-x="unload a document">Unload</span> the <span>active document</span> of the
        <var>specified browsing context</var>.</p></li>
@@ -84960,7 +84990,8 @@ interface <dfn interface>History</dfn> {
 
      <li><p><span>Traverse the history</span> of the <var>specified browsing context</var> to
      the <var>specified entry</var> with <var><span>explicitHistoryNavigation</span></var> set to
-     true.</p>
+     true, and <span data-x="traverse-history-navigationid">navigation id</span> set to
+     <var>navigationId</var>.</p>
     </ol>
    </li>
   </ol>
@@ -86539,8 +86570,6 @@ interface <dfn interface>Location</dfn> { // but see also <a href="#the-location
    context</span>'s <span>active window</span> has <span>transient activation</span>; otherwise
    false.</p></li>
 
-   <li><p>Let <var>navigationStatus</var> be </li>
-
    <li><p>Invoke <span>WebDriver BiDi navigation started</span> with <var>browsingContext</var>, and
    a new <span>WebDriver BiDi navigation status</span> whose <span
    data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
@@ -87659,7 +87688,8 @@ new PaymentRequest(&hellip;); // Allowed to use
        <li><p><span>Traverse the history</span> to <var>sessionHistory</var>'s <span>current
        entry</span> with <var data-x="traverse-history-hh">historyHandling</var> set to
        <var>navigationParams</var>'s <span data-x="navigation-params-hh">history
-       handling</span>.</p></li>
+       handling</span>, and <span data-x="traverse-history-navigationid">navigation id</span>
+       set to <var>navigationId</var>.</p></li>
       </ol>
      </dd>
 
@@ -87689,7 +87719,9 @@ new PaymentRequest(&hellip;); // Allowed to use
 
        <li><p><span>Traverse the history</span> to <var>newEntry</var> with
        <var data-x="traverse-history-hh">historyHandling</var> set to "<code
-       data-x="hh-replace">replace</code>".</p></li>
+       data-x="hh-replace">replace</code>", and <span
+       data-x="traverse-history-navigationid">navigation id</span> set to <var>navigationId</var>.
+       </p></li>
       </ol>
      </dd>
 
@@ -87718,7 +87750,9 @@ new PaymentRequest(&hellip;); // Allowed to use
        <li><p><span data-x="list append">Append</span> <var>newEntry</var> to
        <var>sessionHistory</var>.</p></li>
 
-       <li><p><span>Traverse the history</span> to <var>newEntry</var>.</p></li>
+       <li><p><span>Traverse the history</span> to <var>newEntry</var> with <span
+       data-x="traverse-history-navigationid">navigation id</span> set to <var>navigationId</var>.
+       </p></li>
       </ol>
      </dd>
     </dl>
@@ -88111,18 +88145,11 @@ new PaymentRequest(&hellip;); // Allowed to use
    mode</span>.</p></li>
 
    <li><p><span>Traverse the history</span> to the new entry, with <var
-   data-x="traverse-history-hh">historyHandling</var> set to <var>historyHandling</var> and with
-   <var><span>nonBlockingEvents</span></var> set to true. This will <span>scroll to the
-   fragment</span> given in what is now the document's <span
+   data-x="traverse-history-hh">historyHandling</var> set to <var>historyHandling</var>,
+   <var><span>nonBlockingEvents</span></var> set to true, and <span
+   data-x="traverse-history-navigationid">navigation id</span> set to <var>navigationId</var>.
+   This will <span>scroll to the fragment</span> given in what is now the document's <span
    data-x="concept-document-url">URL</span>.</p></li>
-
-   <li><p><p>Invoke <span>WebDriver BiDi fragment navigated</span> with <var>browsingContext</var>,
-   and a new <span>WebDriver BiDi navigation status</span> whose <span
-   data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
-   data-x="navigation-status-url">url</span> is <var>resource</var>'s <span
-   data-x="concept-request-url">url</span>, and <span
-   data-x="navigation-status-status">status</span> is "<code
-   data-x="navigation-status-complete">complete</code>".</p></li>
   </ol>
 
   <p class="note">If the scrolling fails because the relevant <span data-x="concept-id">ID</span> has
@@ -88253,8 +88280,9 @@ new PaymentRequest(&hellip;); // Allowed to use
   with an optional <span>history handling behavior</span> <dfn
   data-x="traverse-history-hh"><var>historyHandling</var></dfn> (default "<code
   data-x="hh-default">default</code>"), an optional boolean <dfn><var>nonBlockingEvents</var></dfn>
-  (default false), and an optional boolean <dfn><var>explicitHistoryNavigation</var></dfn> (default
-  false):</p>
+  (default false), an optional boolean <dfn><var>explicitHistoryNavigation</var></dfn> (default
+  false), optional <span data-x="navigation-id">navigation id</span>
+  <dfn data-x="traverse-history-navigationid"><var>navigationId</var></dfn> (default null):</p>
 
   <p class="note">This algorithm is not just invoked when <span data-x="traverse the history by a
   delta">explicitly going back or forwards in the session history</span> &mdash; it is also invoked
@@ -88280,11 +88308,12 @@ new PaymentRequest(&hellip;); // Allowed to use
      <li>
       <p><span>Navigate</span><!--DONAV history traversal after eviction--> the <span>browsing
       context</span> to <var>request</var> with <var data-x="navigation-hh">historyHandling</var>
-      set to "<code data-x="hh-entry-update">entry update</code>" and with <var
+      set to "<code data-x="hh-entry-update">entry update</code>", with <var
       data-x="navigation-historypolicycontainer">historyPolicyContainer</var> set to
-      <var>entry</var>'s <span data-x="she-policy-container">policy container</span>. The navigation
-      must be done using the same <span>source browsing context</span> as was used the first time
-      <var>entry</var> was created.</p>
+      <var>entry</var>'s <span data-x="she-policy-container">policy container</span>, and with
+      <span data-x="navigation-navigationid">navigation id</span> set to <var>navigationId</var>.
+      The navigation must be done using the same <span>source browsing context</span> as was
+      used the first time <var>entry</var> was created.</p>
 
       <p class="note">The "<span>navigate</span>" algorithm reinvokes this "traverse" algorithm to
       complete the traversal, at which point <var>entry</var>'s <span
@@ -88306,6 +88335,20 @@ new PaymentRequest(&hellip;); // Allowed to use
    <li><p>Let <var>newDocument</var> be <var>entry</var>'s <span
    data-x="she-document">document</span>.</p></li>
 
+   <li><p>If <var>navigationId</var> is null:</p>
+    <!-- In practice I think the only case that we use the navigation id in subsequent steps is
+    when we have a page loaded from the bfcache, in which case document's navigation id is always null.
+    We could just use null as the navigation id in that case, but it would mean a difference between
+    a WebDriver-initiated history traversal from the bfcache and a UA initated history traversal. -->
+    <ol>
+     <li><p>If <var>newDocument</var>'s <span data-x="concept-document-navigation-id">navigation
+     id</span> is not null, let <var>navigationId</var> be <var>newDocument</var>'s <span
+     data-x="concept-document-navigation-id">navigation id</span>. Otherwise let
+     <var>navigationId</var> be the result of <span>generating a random UUID</span>.
+     <ref spec=UUID></p></li>
+    </ol>
+   </li>
+
    <li><p>If <var>newDocument</var> is different than the <span>current entry</span>'s <span
    data-x="she-document">document</span>, or <var>historyHandling</var> is "<code
    data-x="hh-entry-update">entry update</code>" or "<code data-x="hh-reload">reload</code>",
@@ -88395,6 +88438,14 @@ new PaymentRequest(&hellip;); // Allowed to use
        <li><p><span>Fire a page transition event</span> named <code
        data-x="event-pageshow">pageshow</code> at <var>newDocument</var>'s <span>relevant global
        object</span> with true.</p></li>
+
+       <li><p>Invoke <span>WebDriver BiDi page show</span> with <var>newDocument</var>'s
+       <span data-x="concept-document-bc">browsing context</span>, and a new <span>WebDriver BiDi
+       navigation status</span> whose <span data-x="navigation-status-id">id</span> is the
+       <var>navigationId</var>, <span data-x="navigation-status-status">status</span> is
+       "<code data-x="navigation-status-complete">complete</code>", and <span
+       data-x="navigation-status-url">url</span> is the <var>newDocument</var>'s <span
+       data-x="concept-document-url">URL</span>.</p></li>
       </ol>
 
       <!-- an interesting thing to test would be to traverse back during onload, before the first
@@ -88467,19 +88518,44 @@ new PaymentRequest(&hellip;); // Allowed to use
     object</span> to run the following steps instead.</p>
 
     <ol>
-     <li><p>If <var>stateChanged</var> is true, then <span data-x="concept-event-fire">fire an
-     event</span> named <code data-x="event-popstate">popstate</code> at <var>newDocument</var>'s
-     <span>relevant global object</span>, using <code>PopStateEvent</code>, with the <code
-     data-x="dom-PopStateEvent-state">state</code> attribute initialized to <var>state</var>.</p></li>
+     <li><p>If <var>stateChanged</var> is true:</p>
+      <ol>
+        <li><p><span data-x="concept-event-fire">Fire an event</span> named <code
+        data-x="event-popstate">popstate</code> at <var>newDocument</var>'s
+        <span>relevant global object</span>, using <code>PopStateEvent</code>, with the <code
+        data-x="dom-PopStateEvent-state">state</code> attribute initialized to <var>state</var>.
+        </p></li>
+
+        <li><p>Invoke <span>WebDriver BiDi pop state</span> with with <var>newDocument</var>'s
+        <span data-x="concept-document-bc">browsing context</span>, and a new <span>WebDriver
+        BiDi navigation status</span> whose <span data-x="navigation-status-id">id</span> is
+        <var>navigationId</var>, <span data-x="navigation-status-url">url</span> is
+        <var>resource</var>'s <span data-x="concept-request-url">url</span>, and <span
+        data-x="navigation-status-status">status</span> is "<code
+        data-x="navigation-status-complete">complete</code>".</p></li>
+      </ol>
+     </li>
 
      <li><p><span>Restore persisted state</span> from <var>entry</var>.</p></li>
 
-     <li><p>If <var>hashChanged</var> is true, then <span data-x="concept-event-fire">fire an
-     event</span> named <code data-x="event-hashchange">hashchange</code> at the <span>browsing
-     context</span>'s <span>active window</span>, using <code>HashChangeEvent</code>, with the <code
-     data-x="dom-HashChangeEvent-oldURL">oldURL</code> attribute initialized to <var>oldURL</var>
-     and the <code data-x="dom-HashChangeEvent-newURL">newURL</code> attribute initialized to
-     <var>newURL</var>.</p></li>
+     <li><p>If <var>hashChanged</var> is true:</p>
+      <ol>
+       <li><p><span data-x="concept-event-fire">Fire an event</span> named
+       <code data-x="event-hashchange">hashchange</code> at the <span>browsing context</span>'s
+       <span>active window</span>, using <code>HashChangeEvent</code>, with the <code
+       data-x="dom-HashChangeEvent-oldURL">oldURL</code> attribute initialized to <var>oldURL</var>
+       and the <code data-x="dom-HashChangeEvent-newURL">newURL</code> attribute initialized to
+       <var>newURL</var>.</p></li>
+
+       <li><p>Invoke <span>WebDriver BiDi fragment navigated</span> with <var>newDocument</var>'s
+       <span data-x="concept-document-bc">browsing context</span>, and a new <span>WebDriver
+       BiDi navigation status</span> whose <span data-x="navigation-status-id">id</span> is
+       <var>navigationId</var>, <span data-x="navigation-status-url">url</span> is
+       <var>resource</var>'s <span data-x="concept-request-url">url</span>, and <span
+       data-x="navigation-status-status">status</span> is "<code
+       data-x="navigation-status-complete">complete</code>".</p></li>
+      </ol>
+     </li>
     </ol>
    </li>
   </ol>