From 225c89e94f30c5b949fbb815e35b1253a8fc2642 Mon Sep 17 00:00:00 2001
From: James Graham <james@hoppipolla.co.uk>
Date: Fri, 9 Feb 2024 13:48:40 +0000
Subject: [PATCH] Rewrite the user prompt handler configuration to allow
 overrides

The idea is that for BiDi we'll accept objects like:

{
  "alert": "dismiss",
  "beforeUnload": "ignore"
}

to allow different handling per prompt type, whilst falling back to
the appropiate defaults to maintain the current behaviour for
implementations that don't support BiDi.
---
 index.html | 352 +++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 245 insertions(+), 107 deletions(-)

diff --git a/index.html b/index.html
index 8c798ea7..25076902 100644
--- a/index.html
+++ b/index.html
@@ -1571,7 +1571,7 @@ <h2>Capabilities</h2>
   <td>"<code>unhandledPromptBehavior</code>"
   <td>string
   <td>Describes the <a>session</a>&apos;s <a>user prompt handler</a>.
-   Defaults to the <a>dismiss and notify state</a>.
+   Defaults to "<code>dismiss and notify</code>".
  </tr>
 </table>
 
@@ -2124,6 +2124,11 @@ <h3>Processing capabilities</h3>
        used. The intent is that if this is not possible a new session
        will not be established.
 
+     <dt>"<code>userPromptHandler</code>"
+     <dd><p>If <a>check user prompt handler matches</a>
+     with <var>value</var> is false, return <a>success</a> with
+     data <a><code>null</code></a>.
+
      <dt><strong>Otherwise</strong>
        <dd>
          <ul>
@@ -2218,9 +2223,6 @@ <h2>Sessions</h2>
 <p>An <a>HTTP session</a> has an associated <a>strict file
  interactability</a> state which is a boolean.
 
-<p>A <a>HTTP session</a> has an associated <a>user prompt handler</a>.
-Unless stated otherwise it is in the <a>dismiss and notify state</a>.
-
 <p>A <a>session</a> has an associated <dfn>browsing context input
 state map</dfn>, which is a Weak Map with <a>top-level browsing
 contexts</a> as keys, and <a>input state</a> objects as values. This
@@ -2358,6 +2360,7 @@ <h3>Global State</h3>
      <li><p>If the list of <a>active sessions</a> is empty:
       <ol>
         <li><p>Set the <a>webdriver-active flag</a> to false
+        <li><p>Set the <a>user prompt handler</a> to null.
         <li><p>Unset the <a>accept insecure TLS</a> flag.
         <li><p>Reset the <a>has proxy configuration</a> flag to its
         default value.
@@ -10198,127 +10201,229 @@ <h2>User prompts</h2>
  If the subsequent requested <a>command</a> is not one listed in this chapter,
  an <a>unexpected alert open</a> <a>error</a> will be returned.
 
-<p><a>User prompts</a> that are spawned
- from <a><code>beforeunload</code></a> event handlers,
- are <a>accepted</a> implicitly upon <a>navigation</a>
- or <a>close window</a>,
- regardless of the defined <a>user prompt handler</a>.
+<p>Whenever <a>active sessions</a> is a list containing exactly one
+item, and that item is a <a>HTTP session</a>, then in the <a>steps to
+fire beforeunload</a>, implementations must act as if showing an
+unload prompt is likely to be annoying, deceptive, or pointless.
+
+<p class=note>This means that beforeunload prompts are never shown
+when there&apos;s an active HTTP session.
 
 <p>A <a>user prompt</a> has an associated <dfn>user prompt message</dfn>
  that is the string message shown to the user,
  or <a><code>null</code></a> if the message length is <code>0</code>.
 
-<p>The following <dfn>table of simple dialogs</dfn>
- enumerates all supported <a>simple dialogs</a>,
- along with the <a>commands</a> that are allowed to interact with it
- as a non-normative reference:
+<p>The <dfn>current user prompt</dfn> is the <a>user prompt</a> which
+has invoked the <a>pause</a> algorithm, if any, or null otherwise.
 
-<table class=simple>
- <tr>
-  <th>Definition
-  <th>Dialog
-  <th>Interactions
- </tr>
+<p>To <dfn data-lt="dismissed|dismisses">dismiss</dfn> the <a>current
+ user prompt</a>, act as if the user clicked the <b>Cancel</b> button
+ prompt on that prompt, if present, or otherwise <a>accept</a> the
+ prompt.
 
- <tr>
-  <td><dfn>Alert</dfn>
-  <td><a>window.<code>alert</code></a>
-  <td>
-   <a>Accept Alert</a><br>
-   <a>Dismiss Alert</a><br>
-   <a>Get Alert Text</a>
- </tr>
+<p>To <dfn data-lt="accepting|accepted|accepts">accept</dfn>
+ the <a>current user prompt</a>, act if the user clicked
+ the <b>OK</b> button on that prompt.
 
- <tr>
-  <td><dfn>Confirm</dfn>
-  <td><a>window.<code>confirm</code></a>
-  <td>
-   <a>Dismiss Alert</a><br>
-   <a>Accept Alert</a><br>
-   <a>Get Alert Text</a>
- </tr>
+<h3>User Prompt Handler</h3>
 
- <tr>
-  <td><dfn>Prompt</dfn>
-  <td><a>window.<code>prompt</code></a>
-  <td>
-   <a>Dismiss Alert</a><br>
-   <a>Accept Alert</a><br>
-   <a>Get Alert Text</a><br>
-   <a>Send Alert Text</a>
- </tr>
-</table>
+<p>A <a>remote end</a> has a <dfn>user prompt handler</dfn> which
+defines how a WebDriver session will react when a user prompt is
+displayed. It is either null or a <a data-cite=infra>map</a> between strings
+and <a>prompt handler configuration</a> values. Initially it is null.
+
+<p>A <dfn>prompt handler configuration</dfn> is a <a>struct</a> with two
+items; a <dfn data-dfn-for="prompt handler configuration">handler</dfn>, which is a
+string, and a <dfn data-dfn-for="prompt handler configuration">notify</dfn>,
+which is a boolean.
 
-<p>The <dfn>current user prompt</dfn> is said to be the active <a>user prompt</a>,
- which can be one of the entries on the <a>table of simple dialogs</a>.
+<p>To <dfn>serialize a prompt handler configuration</dfn>
+given <var>configuration</var>:
 
-<p>To <dfn data-lt="dismissed|dismisses">dismiss</dfn>
- the <a>current user prompt</a>,
- do so as if the user would click the <b>Cancel</b> or <b>OK</b> button,
- whichever is present, in that order.
+<ol class=algorithm>
 
-<p>To <dfn data-lt="accepting|accepted|accepts">accept</dfn> the <a>current user prompt</a>,
- do so as if the user would click the <b>OK</b> button.
+ <li><p>Let <var>serialized</var>
+ be <var>configuration</var>&apos;s [=prompt handler
+ configuration/handler=].
 
-<p>
-The <dfn>user prompt handler</dfn> defines what action
-the <a>remote end</a> must take when a <a>user prompt</a> is encountered.
-This is defined by the <a>unhandled prompt behavior</a> capability.
-The following <dfn>known prompt handling approaches table</dfn>
-lists the keywords and states for the attribute:
+ <li><p>If «"<code>dismiss</code>", "<code>accept</code>"»
+ [=list/contains=] <var>serialized</var>,
+ and <var>configuration</var>&apos;s [=prompt handler
+ configuration/notify=] is true, append "<code> and notify</code>"
+ to <var>serialized</var>.
+
+ <li><p>Return <var>serialized</var>.
+
+</ol>
 
+The <dfn>known prompt handlers</dfn> are:
 <table class=simple>
  <tr>
-  <th>Keyword
-  <th>State
-  <th>Description
+  <th>Handler key
+  <th>Description (non-normative).
  </tr>
 
  <tr>
   <td>"<code>dismiss</code>"
-  <td><dfn>Dismiss state</dfn>
   <td>All <a>simple dialogs</a> encountered should be <a>dismissed</a>.
  </tr>
 
  <tr>
   <td>"<code>accept</code>"
-  <td><dfn>Accept state</dfn>
   <td>All <a>simple dialogs</a> encountered should be <a>accepted</a>.
  </tr>
 
  <tr>
   <td>"<code>dismiss and notify</code>"
-  <td><dfn>Dismiss and notify state</dfn>
   <td>All <a>simple dialogs</a> encountered should be <a>dismissed</a>,
       and an error returned that the dialog was handled.
  </tr>
 
  <tr>
   <td>"<code>accept and notify</code>"
-  <td><dfn>Accept and notify state</dfn>
   <td>All <a>simple dialogs</a> encountered should be <a>accepted</a>,
       and an error returned that the dialog was handled.
  </tr>
 
  <tr>
   <td>"<code>ignore</code>"
-  <td><dfn>Ignore state</dfn>
   <td>All <a>simple dialogs</a> encountered should be left to the user to handle.
  </tr>
 </table>
 
-<p>When required to <dfn>deserialize as an unhandled prompt behavior</dfn> an
+<p>The <dfn>valid prompt types</dfn> are «"<code>alert</code>",
+"<code>beforeUnload</code>", "<code>confirm</code>",
+"<code>default</code>", "<code>prompt</code>"».
+
+<p>To <dfn>deserialize as an unhandled prompt behavior</dfn> an
 argument <var>value</var>:
 
-<ol>
- <li><p>If <var>value</var> is not a <a>string</a> return
-  an <a>error</a> with <a>error code</a> <a>invalid argument</a>.
+<ol class=algorithm>
 
- <li><p>If <var>value</var> is not present as a <code>keyword</code>
-  in the <a>known prompt handling approaches table</a>
-  return an <a>error</a> with <a>error code</a> <a>invalid argument</a>.
+ <!-- TODO - We should hoist this conversion into the capabilities processing, or even the
+      main request handling, but do it explicitly here for now to avoid a large refactor -->
+ <li><p>Set <var>value</far> to the result of <a>converting a
+ JSON-derived JavaScript value to an Infra value</a>
+ with <var>value</var>.
 
- <li><p>Return <a>success</a> with data <var>value</var>.
+ <li><p>If <var>value</var> is not a string, an implementation that
+ does not also support [[WebDriver-BiDi]] may return <a>error</a>
+ with <a>error code</a> <a>invalid argument</a>.
+
+ <p class="note">This is to avoid [[WebDriver-BiDi]] monkey-patching
+ the current spec.
+
+ <li><p>If <var>value</var> is a <a>string</a> set <var>value</var> to
+ the <a data-cite=infra>map</a> «["<code>default</code>" → <var>value</var>]».
+
+ <li>Let <var>user prompt handler</var> be an empty <a data-cite=infra>map</a>.
+
+ <li><p>For each <var>prompt type</var> → <var>handler</var> in <var>value</var>:
+
+  <ol>
+   <li><p>If <a>valid prompt types</a> does
+   not [=map/contains=] <var>prompt type</var> return <a>error</a>
+   with <a>error code</a> <a>invalid argument</a>.
+
+   <li><p>If <a>known prompt handlers</a> does not contain an entry
+   with handler key <var>handler</var> return <a>error</a>
+   with <a>error code</a> <a>invalid argument</a>.
+
+   <li><p>Let <var>notify</var> be false.
+
+   <li><p>If <var>handler</var> is "<code>accept and notify</code>",
+   set <var>handler<var> to "<code>accept</code>"
+   and <var>notify</var> to true.
+
+   <li><p>If <var>handler</var> is "<code>dismiss and notify</code>",
+   set <var>handler<var> to "<code>dismiss</code>"
+   and <var>notify</var> to true.
+
+   <li><p>Let <var>configuration</var> be a <a>prompt handler
+   configuration</a> with [=prompt handler
+   configuration/handler=] <var>handler</var> and [=prompt handler
+   configuration/notify=] <var>notify</var>.
+
+   <li><p>[=map/Set=] <var>user prompt
+   handler</var>[<var>handler</var>] to <var>configuration</var>.
+
+  </ol>
+ </li>
+
+ <li><p>Return <a>success</a> with data <var>user prompt handler</var>.
+</ol>
+
+<p>To <dfn>check user prompt handler matches</dfn>
+given <var>requested prompt handler</var>:
+
+<ol class="algorithm">
+ <li><p>If the <a>user prompt handler</a> is null, return true.
+
+ <li><p>For each <var>request key</var> → <var>request handler</var>
+ in <var>requested prompt handler</var>:
+
+  <ol>
+   <li><p>If the <a>user prompt
+   handler</a> [=map/contains=] <var>key</var>:
+
+    <ol>
+
+     <li><p>If the <var>requested prompt handler</var>&apos;s [=prompt
+     handler configuration/handler=] is not equal to the <a>user
+     prompt handler</a>&apos;s [=prompt handler
+     configuration/handler=], or the <var>requested prompt
+     handler</var>&apos;s [=prompt handler configuration/notify=]
+     is not equal to the <a>user prompt
+     handler</a>&apos;s [=prompt handler configuration/handler=],
+     return false.
+
+    </ol>
+   </li>
+ </ol>
+
+ <li>Return true</li>
+</ol>
+
+<p>To <dfn>update the user prompt handler</dfn> given <var>requested handler</var>:
+
+<ol class=algorithm>
+
+ <li><p>If the <a>user prompt handler</a> is null, set the <a>user prompt
+ handler</a> to an empty map.
+
+ <li><p>For each <var>request key</var> → <var>request handler</var>
+ in <var>requested prompt handler</var>:
+
+  <ol>
+   <li><p>Set <a>user prompt handler</a>[<var>key</var>] to <var>value</var>:
+
+  </ol>
+
+</ol>
+
+<p>To <dfn>serialize the current user prompt handler</dfn>:
+
+<ol class=algorithm>
+ <li><p>If the <a>user prompt handler</a> is null, return null.
+
+ <li><p>If the <a>user prompt handler</a> has [=map/size=] 1,
+ and <a>user prompt handler</a> [=list/contains=]
+ "<code>default</code>", return the result of <a>serialize a prompt
+ handler configuration</a> with <a>user prompt
+ handler</a>["<code>default</code>"].
+
+ <li><p>Let <var>serialized</var> be an empty <a data-cite=infra>map</a>.
+
+ <li><p>For each <var>key</var> → <code>value</code> of <a>user prompt
+ handler</a>:
+
+ <ol>
+  <li><p>Set <var>serialized</var>[<var>key</var>] to <a>serialize a prompt
+  handler configuration</a> with <var>value</var>.
+ </ol>
+
+ <li><p>Return <a>convert an Infra value to a JSON-compatible
+ JavaScript value</a> with <var>serialized</var>.
 </ol>
 
 <p>An <dfn>annotated unexpected alert open error</dfn>
@@ -10328,47 +10433,72 @@ <h2>User prompts</h2>
 
  <dl>
   <dt>"<code>text</code>"
-  <dd>The <a>current user prompt</a>’s
+  <dd>The <a>current user prompt</a>&apos;s
    <a data-lt="user prompt message">message</a>.
  </dl>
 
-<p>To <dfn>handle any user prompts</dfn>
- given <var>session</var>, <a>remote end</a> must:
+<p>To <dfn>get the prompt handler</dfn> <var>type</var>:
 
-<ol>
-<li><p>
-If there is no <a>current user prompt</a>,
-abort these steps and return <a>success</a>.
+<ol class=algorithm>
+ <li><p>If the <a>user prompt handler</a> is null,
+ let <var>handlers</var> be an empty map. Otherwise
+ let <var>handlers</var> be <a>user prompt handler</a>.
 
-<li><p>
-Perform the following substeps
-based on the <a>session</a>’s <a>user prompt handler</a>:
+ <li><p>If <var>handlers</var> contains <var>type</var>
+ return <var>handlers</var>[<var>type</var>].
 
-<dl class=switch>
-<dt><a>dismiss state</a>
-<dd><p><a>Dismiss</a> the <a>current user prompt</a>.
+ <li><p>If <var>type</var> is "<code>beforeUnload</code>", return a
+   <a>prompt handler configuration</a> with [=prompt
+   handler configuration/handler=] "<code>accept</code>"
+   and [=prompt handler configuration/notify=] false.
 
-<dt><a>accept state</a>
-<dd><p><a>Accept</a> the <a>current user prompt</a>.
+ <li><p>If <var>handlers</var> contains "<code>default</code>
+ return <var>handlers</var>["<code>default</code>"].
 
-<dt><a>dismiss and notify state</a>
-<dd>
-<ol>
-<li><p><a>Dismiss</a> the <a>current user prompt</a>.
-<li><p>Return an <a>annotated unexpected alert open error</a>.
+ <li><p>Return a a>prompt handler
+   configuration</a> with [=prompt handler
+   configuration/handler=] "<code>dismiss</code>" and [=prompt handler
+   configuration/notify=] true.
 </ol>
 
-<dt><a>accept and notify state</a>
-<dd>
-<ol>
-<li><p><a>Accept</a> the <a>current user prompt</a>.
-<li><p>Return an <a>annotated unexpected alert open error</a>.
-</ol>
+<p>To <dfn>handle any user prompts</dfn>:
+
+<ol class=algorithm>
+ <li><p>If the <a>current browsing context</a>&apos; is not blocked by
+ a dialog return <a>success</a>.
 
-<dt><a>ignore state</a>
-<dd><p>Return an <a>annotated unexpected alert open error</a>.
+ <li><p>Let <var>type</var> be "<code>default</code>".
+
+ <li><p>If the <a>current user prompt</a> is an alert dialog,
+ set <var>type</var> to "<code>alert</code>". Otheriwse, if
+ the <a>current user prompt</a> is a confirm dialog,
+ set <var>type</var> to "<code>confirm</code>". Otherwise, if
+ the <a>current user prompt</a> is a confirm dialog,
+ set <var>type</var> to "<code>prompt</code>".
+
+ <li><p>TODO: other types
+
+ <li><p>Let <var>handler</var> be <a>get the prompt handler</a>
+ with <var>type</var>.
+
+ <li><p> Perform the following substeps based
+ on <var>handler</var>&apos;s [=prompt handler configuration/handler=]:
+
+<dl class=switch>
+<dt>"<code>dismiss</code>"
+<dd><p><a>Dismiss</a> the <a>current user prompt</a>.
+
+<dt>"<code>accept</code>"
+<dd><p><a>Accept</a> the <a>current user prompt</a>.
+
+<dt>"<code>ignore state</code>
+<dd><p>Do nothing.
 </dl>
 
+<li><p>If <var>handler</var>&apos;s [=prompt handler
+   configuration/notify=] is true, return <a>annotated unexpected
+   alert open error</a>.
+
 <li><p>Return <a>success</a>.
 </ol>
 
@@ -10421,7 +10551,7 @@ <h3><dfn>Dismiss Alert</dfn></h3>
   context</a> is <a>no longer open</a>, return <a>error</a>
   with <a>error code</a> <a>no such window</a>.
 
- <li><p>If there is no <a>current user prompt</a>,
+ <li><p>If the <a>current user prompt</a> is null,
   return <a>error</a> with <a>error code</a> <a>no such alert</a>.
 
  <li><p><a>Dismiss</a> the <a>current user prompt</a>.
@@ -10452,7 +10582,7 @@ <h3><dfn>Accept Alert</dfn></h3>
   context</a> is <a>no longer open</a>, return <a>error</a>
   with <a>error code</a> <a>no such window</a>.
 
- <li><p>If there is no <a>current user prompt</a>,
+ <li><p>If the <a>current user prompt</a> is null,
   return <a>error</a> with <a>error code</a> <a>no such alert</a>.
 
  <li><p><a>Accept</a> the <a>current user prompt</a>.
@@ -10483,7 +10613,7 @@ <h3><dfn>Get Alert Text</dfn></h3>
   context</a> is <a>no longer open</a>, return <a>error</a>
   with <a>error code</a> <a>no such window</a>.
 
- <li><p>If there is no <a>current user prompt</a>,
+ <li><p>If the <a>current user prompt</a> is null,
   return <a>error</a> with <a>error code</a> <a>no such alert</a>.
 
  <li><p>Let <var>message</var> be the text message
@@ -10528,7 +10658,7 @@ <h3><dfn>Send Alert Text</dfn></h3>
   context</a> is <a>no longer open</a>, return <a>error</a>
   with <a>error code</a> <a>no such window</a>.
 
- <li><p>If there is no <a>current user prompt</a>,
+ <li><p>If the <a>current user prompt</a> is null,
   return <a>error</a> with <a>error code</a> <a>no such alert</a>.
 
  <li><p>Run the substeps of the first matching
@@ -11407,6 +11537,7 @@ <h2>Index</h2>
    <!-- Satisfies its constraints --> <li><dfn><a href=https://html.spec.whatwg.org/#concept-fv-valid>Satisfies its constraints</a></dfn>
    <!-- Selectedness --> <li><dfn><a href=https://html.spec.whatwg.org/#concept-option-selectedness>Selectedness</a></dfn>
    <!-- Simple dialogs --> <li><dfn data-lt="simple dialog"><a href=https://html.spec.whatwg.org/#simple-dialogs>Simple dialogs</a></dfn>
+   <!-- Steps to fire beforeunload --> <li><dfn><a href=https://html.spec.whatwg.org/#steps-to-fire-beforeunload>Steps to fire beforeunload</a></dfn>
    <!-- Suffering from bad input --> <li><dfn><a href=https://html.spec.whatwg.org/#suffering-from-bad-input>Suffering from bad input</a></dfn>
    <!-- Traverse the history by a delta --> <li><dfn><a href=https://html.spec.whatwg.org/#traverse-the-history-by-a-delta>Traverse the history by a delta</a></dfn>
    <!-- Unfocusing steps --><li><dfn><a href=https://html.spec.whatwg.org/#unfocusing-steps>unfocusing steps</a></dfn>
@@ -11494,6 +11625,13 @@ <h2>Index</h2>
    <!-- Status code registry --> <li><dfn><a href=https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml>Status code registry</a></dfn>
   </ul>
 
+ <dt>Infra
+ <dd><p>The following terms are defined in the Infra specification: [[INFRA]]
+   <ul>
+    <!-- convert an Infra value to a JSON-compatible JavaScript value --> <li><dfn><a href="https://infra.spec.whatwg.org/#convert-an-infra-value-to-a-json-compatible-javascript-value">convert an Infra value to a JSON-compatible JavaScript value</a></dfn>
+    <!-- converting a JSON-derived JavaScript value to an Infra value --> <li><dfn><a href="https://infra.spec.whatwg.org/#convert-a-json-derived-javascript-value-to-an-infra-value">converting a JSON-derived JavaScript value to an Infra value</a></dfn>
+   </ul>
+
  <dd>The following terms are defined in
   the Netscape Navigator Proxy Auto-Config File Format:
   <ul>