Address review comments.

index.html

@@ -452,7 +452,7 @@ <h2>
           </li>
         </ol>
         <div class="issue">
-          Implementations may wish to show a prompt if and only if the site
+          Implementations may wish to show a prompt if, and only if, the site
           explicitly requests it via
           <a><code>BeforeInstallPromptEvent.prompt()</code></a>, but not
           automatically without the site's approval. Is this something we want
@@ -561,9 +561,9 @@ <h3>
           <a
           data-cite="DOM#dom-event-preventdefault"><code>preventDefault</code></a>)
           prevents the user agent from <a data-lt="presents an install
-          prompt">presenting an automated install prompt</a> until a later time
-          (see the <a for="BeforeInstallPromptEvent"><code>prompt()</code></a>
-          method).
+          prompt">presenting an automated install prompt</a>. The user agent is
+          free to run <a>steps to notify before an automated install prompt</a>
+          again at a later time.
         </div>
         <p>
           The <dfn>PromptResponseObject</dfn> contains the result of calling <a
@@ -580,8 +580,8 @@ <h3>
             <dfn>[[\didPrompt]]</dfn>
           </dt>
           <dd>
-            A boolean, initially <code>false</code>. Represents if this event
-            was used to <a>present an install prompt</a> to the end-user.
+            A boolean, initially <code>false</code>. Represents whether this
+            event was used to <a>present an install prompt</a> to the end-user.
           </dd>
           <dt>
             <dfn>[[\userResponsePromise]]</dfn>
@@ -629,14 +629,11 @@ <h4>
               <a>Present an install prompt</a> and let <var>outcome</var> be
               the result.
             </li>
-            <li>Let <var>responseObj</var> be a newly created
-            <a>PromptResponseObject</a> whose <a
+            <li>Resolve <var>event</var>.<a>[[\userResponsePromise]]</a> with
+            a newly created <a>PromptResponseObject</a> whose <a
             for="PromptResponseObject">userChoice</a> member is the value of
             <var>outcome</var>.
             </li>
-            <li>Resolve <var>event</var>.<a>[[\userResponsePromise]]</a> with
-            <var>responseObj</var>.
-            </li>
           </ol>
         </section>
         <section class="informative">
@@ -646,11 +643,13 @@ <h4>
           <p>
             This example shows how one might prevent an automated install
             prompt from showing until the user clicks a button to install the
-            app. In this way, the site can control the installation experience.
+            app. In this way, the site can leave installation at the user's
+            discretion (rather than prompting at an arbitrary time), whilst
+            still providing a prominent UI to do so.
           </p>
           <pre class="example"
                title="Using beforeinstallprompt to present an install button">
-            window.addEventListener("beforeinstallprompt", async (event) =&gt; {
+            window.addEventListener("beforeinstallprompt", event =&gt; {
               // Suppress automatic prompting.
               event.preventDefault();
 
@@ -659,14 +658,14 @@ <h4>
               installButton.disabled = false;
 
               // Wait for the user to click the button.
-              await installButtonClicked;
-
-              // The prompt() method can only be used once.
-              installButton.disabled = true;
+              installButton.addEventListener("click", async e =&gt; {
+                // The prompt() method can only be used once.
+                installButton.disabled = true;
 
-              // Show the prompt.
-              const { userChoice } = await event.prompt();
-              console.info(`user choice was: ${userChoice}`);
+                // Show the prompt.
+                const { userChoice } = await event.prompt();
+                console.info(`user choice was: ${userChoice}`);
+              });
             });
           </pre>
         </section>