Add a browsingContext.traverseHistory command

index.bs

@@ -186,6 +186,7 @@ spec: HTML; urlPrefix: https://html.spec.whatwg.org/multipage/
     text: set up a worker environment settings object; url: workers.html#set-up-a-worker-environment-settings-object
     text: set up a worklet environment settings object; url: worklets.html#set-up-a-worklet-environment-settings-object
     text: shared worker; url: workers.html#shared-workers
+    text: traverse the history by a delta; url: browsing-the-web.html#traverse-the-history-by-a-delta
     text: window open steps; url: window-object.html#window-open-steps
     text: worker event loop; url: webappapis.html#worker-event-loop-2
     text: worklet global scopes; url:worklets.html#concept-document-worklet-global-scopes
@@ -1852,6 +1853,7 @@ BrowsingContextCommand = (
   browsingContext.Print //
   browsingContext.Reload //
   browsingContext.SetViewport
+  browsingContext.TraverseHistory
 )
 </pre>
 
@@ -1864,6 +1866,7 @@ BrowsingContextResult = (
   browsingContext.GetTreeResult //
   browsingContext.NavigateResult //
   browsingContext.PrintResult
+  browsingContext.TraverseHistoryResult
 )
 
 BrowsingContextEvent = (
@@ -3062,6 +3065,146 @@ The [=remote end steps=] with |command parameters| are:
 
 </div>
 
+#### The browsingContext.traverseHistory Command ####  {#command-browsingContext-traverseHistory}
+
+The <dfn export for=commands>browsingContext.traverseHistory</dfn> command
+traverses the history of a given context by a delta.
+
+<dl>
+   <dt>Command Type</dt>
+   <dd>
+      <pre class="cddl remote-cddl">
+      BrowsingContext.TraverseHistory = {
+        method: "browsingContext.traverseHistory",
+        params: browsingContext.TraverseHistoryParameters
+      }
+
+      browsingContext.TraverseHistoryParameters = {
+        context: browsingContext.BrowsingContext,
+        delta: int,
+        ? wait: browsingContext.ReadinessState,
+      }
+      </pre>
+   </dd>
+   <dt>Return Type</dt>
+   <dd>
+    <pre class="cddl local-cddl">
+        browsingContext.TraverseHistoryResult = {
+            navigation: browsingContext.Navigation / null,
+            ?persisted: bool
+            url: text,
+        }
+    </pre>
+   </dd>
+</dl>
+
+<div algorithm="remote end steps for browsingContext.traverseHistory">
+The [=remote end steps=] with |command parameters| are:
+
+1. Let |browsing context| be the result of [=trying=] to [=get a browsing context=]
+   with |command parameters|["<code>context</code>"]|.
+
+1. Assert: |browsing context| is not null.
+
+1. Let |navigable| be the [=/navigable=] whose [=navigable/active
+   document=] is |browsing context|'s [=browsing context/active document=].
+
+1. Let |delta| be |command parameters|["<code>delta</code>"].
+
+1. If |command parameters| [=map/contains=] "<code>wait</code>, let |wait
+   condition| be |command parameters|["<code>wait</code>"]. Otherwise let |wait
+   condition| be "<code>none</code>".
+
+1. Let |navigation id| be the string representation of a
+   [[!RFC4122|UUID]] based on truly random, or pseudo-random numbers.
+
+1. [=Traverse the history by a delta=] given |delta|, |navigable|, and
+   |navigation id|.
+
+1.  Let (|event received|, |navigate status|) be [=await=] given
+    «"<code>navigation started</code>", "<code>navigation failed</code>",
+    "<code>fragment navigated</code>", "<code>pop state</code>"», and
+    |navigation id|.
+
+1. Assert: |navigate status|'s id is |navigation id|.
+
+1. If |navigate status|'s status is "<code>complete</code>":
+
+  1. Let |body| be a [=/map=] matching the
+     <code>browsingContext.TraverseHistoryResult</code> production, with the
+     <code>navigation</code> field set to |navigation id|, and the
+     <code>url</code> field set to the result of the [=URL serializer=] given
+     |navigate status|'s url.
+
+  1. Return [=success=] with data |body|.
+
+1. If |navigate status|'s status is "<code>canceled</code>" return [=error=]
+   with [=error code=] [=unknown error=].
+
+1. Assert: |navigate status|'s status is "<code>pending</code>" and
+   |navigation id| is not null.
+
+1. If |wait condition| is "<code>none</code>":
+
+  1. Let |body| be a [=/map=] matching the
+     <code>browsingContext.TraverseHistoryResult</code> production, with the
+     <code>navigation</code> field set to |navigation id|, and the
+     <code>url</code> field set to the result of the [=URL serializer=] given
+     |navigate status|'s url.
+
+1. If |wait condition| is "<code>interactive</code>", let |event name| be
+   "<code>domContentLoaded</code>", otherwise let |event name| be
+   "<code>load</code>".
+
+1. Let (|event received|, |status|) be [=await=] given «|event name|,
+    "<code>download started</code>", "<code>navigation aborted</code>",
+    "<code>navigation failed</code>", "<code>page show</code>"», and |navigation
+    id|.
+
+1. If |event received| is "<code>navigation failed</code>"
+   return [=error=] with [=error code=] [=unknown error=].
+
+1. If event received is "<code>page show</code>", let |persisted| be true,
+   otherwise let |persisted| be false.
+
+1. Let |body| be a [=/map=] matching the
+   <code>browsingContext.TraverseHistoryResult</code> production, with the
+   <code>navigation</code> field set to |status|'s id, the
+   <code>persisted</code> field set to |persisted|, and the <code>url</code>
+   field set to the result of the [=URL serializer=] given |status|'s url.
+
+1. Return [=success=] with data |body|.
+
+</div>
+
+<div algorithm>
+
+The <dfn export>WebDriver BiDi page show</dfn> steps given <var
+ignore>context</var> and |navigation status| are:
+
+Issue: Do we want to expose a `browsingContext.pageShow event? In that case we'd
+need to call this whenever `pageshow` is going to be emitted, not just on
+bfcache restore, and also add the persisted status to the data.
+
+ 1. Let |navigation id| be |navigation status|'s id.
+
+ 1. [=Resume=] with "<code>page show</code>", |navigation id|, and
+    |navigation status|.
+
+</div>
+
+<div algorithm>
+
+The <dfn export>WebDriver BiDi pop state</dfn> steps given <var
+ignore>context</var> and |navigation status| are:
+
+ 1. Let |navigation id| be |navigation status|'s id.
+
+ 1. [=Resume=] with "<code>pop state</code>", |navigation id|, and
+    |navigation status|.
+
+</div>
+
 
 ### Events ### {#module-contexts-events}