From b99f1ed4b79b1ffe0af53c2119695da4479e0ad0 Mon Sep 17 00:00:00 2001
From: James Graham <james@hoppipolla.co.uk>
Date: Fri, 4 Jun 2021 15:15:29 +0100
Subject: [PATCH] Add a browsingContext.traverseHistory command

This traverses the history by a specified `delta` (e.g. +1 for forward,
or -1 for back). Like other navigation commands the `wait` parameter
controls whether to return as soon as the history traversal starts, or
wait for a specified level of completeness.

Mush like other navigation commands, history traversal is tracked with
a unique navigation id.

Typically history traversal results in a navigation, but in the case
of the history entry being in the bfcache, no navigation is
necessary. In this case any non-"none" value for wait will return once
the `pageshow` event is fired, and the `persisted` attribute of the
return value is set to `true`.

This model differs somewhat from the CDP model where one navigates to
an explicit history entry and failure is only possible if the entry id
is invalid. But back/forwward only seems closer to the use cases we
have, and allowing events to be traced to a specific traversal seems
consistent with the way we handle other navigation-related events.
---
 index.bs | 116 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 114 insertions(+), 2 deletions(-)

diff --git a/index.bs b/index.bs
index 6b5bc2f5..41110be6 100644
--- a/index.bs
+++ b/index.bs
@@ -1560,7 +1560,8 @@ is a set that is initially empty.
 BrowsingContextCommand = (
     BrowsingContextGetTreeCommand //
     BrowsingContextNavigateCommand //
-    BrowsingContextReloadCommand
+    BrowsingContextReloadCommand //
+    BrowsingContextTraverseHistoryCommand
 )
 </pre>
 
@@ -1570,7 +1571,8 @@ BrowsingContextCommand = (
 
 BrowsingContextResult = (
     BrowsingContextGetTreeResult //
-    BrowsingContextNavigateResult
+    BrowsingContextNavigateResult //
+    BrowsingContextTraverseHistoryResult
 )
 
 BrowsingContextEvent = (
@@ -1993,6 +1995,116 @@ 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">
+      BrowsingContextTraverseHistoryCommand = {
+        method: "browsingContext.traverseHistory",
+        params: BrowsingContextTraverseHistoryParameters
+      }
+
+      BrowsingContextReloadParameters = {
+        context: BrowsingContext,
+        delta: int,
+        ?wait: ReadinessState,
+      }
+      </pre>
+   </dd>
+   <dt>Return Type</dt>
+   <dd>
+    <pre class="cddl local-cddl">
+        BrowsingContextTraverseHistoryResult = {
+            navigation: 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 |context id| be the value of the <code>context</code> field of
+     |command parameters|.
+
+  1. Let |context| be the result of [=trying=] to [=get a browsing context=]
+     with |context id|.
+
+  1. Assert: |context| is not null.
+
+  1. Let |delta| be the value of the <code>delta</code> field of |command
+     parameters|.
+
+  1. Let |wait condition| be the value of the <code>wait</code> field of |command
+     parameters| if present, or "<code>none</code>" otherwise.
+
+  1. Let |navigate status| be the result of running the [=traverse the history
+     by a delta steps=] given |delta|, and |context|.
+
+  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>BrowsingContextNavigateResult</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 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>BrowsingContextTraverseHistoryResult</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. If the [=current session=] is null, return.
+
+ 1. Let |navigation id| be |navigation status|'s id.
+
+ 1. [=Resume=] with "<code>page show</code>", |navigation id|, and
+    |navigation status|.
+
+</div>
+
+
 ### Events ### {#module-contexts-events}
 
 #### The browsingContext.contextCreated Event #### {#event-browsingContext-contextCreated}