Text directive user activation

Author: domfarolino

images/text-directive-user-activation-flag.png

@@ -2748,6 +2748,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
        <li><dfn data-x-href="https://fetch.spec.whatwg.org/#request-top-level-navigation-initiator-origin">top-level navigation initiator origin</dfn></li>
        <li><dfn data-x-href="https://fetch.spec.whatwg.org/#concept-request-add-range-header">add a range header</dfn></li>
        <li><dfn data-x-href="https://fetch.spec.whatwg.org/#destination-type">destination type</dfn></li>
+       <li><dfn data-x="concept-request-text-directive-user-activation" data-x-href="https://fetch.spec.whatwg.org/#concept-request-text-directive-user-activation">text directive user activation</dfn></li>
       </ul>
      </li>
      <li>
@@ -107170,6 +107171,9 @@ location.href = '#foo';</code></pre>
     care of scrolling.</p>
    </li>
 
+   <li><p>Set <var>navigable</var>'s <span data-x="nav-document">active document</span>'s
+   <span>pending text directives</span> to null.</p></li>
+
    <li><p>Let <var>traversable</var> be <var>navigable</var>'s <span
    data-x="nav-traversable">traversable navigable</span>.</p></li>
 
@@ -115143,12 +115147,60 @@ console.log(document.url.hash); // '#foo:~:bar'
   <span>list</span> of <span data-x="text directive">text directives</span> or null, initially
   null.</p>
 
+  <p>Each <code>Document</code> has a <dfn>text directive user activation</dfn> which is a boolean,
+  initially false.</p>
+
+  <div class="note">
+    <p>The <span>text directive user activation</span> provides the necessary user gesture signal to
+    <!-- TODO(domfarolino): Probably clarify, by adding a link to the specific load steps -->
+    <!-- TODO(domfarolino): Maybe say when it is also set to false / "used" -->
+    allow a single activation of a <span>text directive</span>. It is set to true during document
+    loading only if the navigation occurred as a result of a user activation and is propagated
+    across client-side redirects.</p>
+
+    <p>If a <code>Document</code>'s <span>text directive user activation</span> isn't used to
+    activate a <span>text directive</span>, rather it is used to set a <span
+    data-x="navigation-request">navigation request</span>'s <span
+    data-x="concept-request-text-directive-user-activation">text directive user activation</span> to
+    true, so than an "unused" <span>text directive user activation</span> can be propagated from one
+    <code>Document</code> to another across a navigation.</p>
+
+    <!-- TODO(bokan): What does it mean for a request's boolean to be set to false when it is "used"? How does that work? -->
+    <p>Both <code>Document</code>'s <span>text directive user activation</span> and <span
+    data-x="concept-request">request</span>'s <span
+    data-x="concept-request-text-directive-user-activation">text directive user activation</span>
+    are always set to false when used, such that a single user activation cannot be reused to
+    activate more than one text fragment.</p>
+  </div>
+
+  <div class="note">
+   <p>This mechanism allows text fragments to activate through a common redirect technique used by
+   many popular web sites. Such sites "redirect" users to their intended destination by responding
+   with a "<code data-x="">200</code>" status code containing script that triggers a navigation.</p>
+
+   <p>Unlike real HTTP redirects, these "client-side" redirects cannot propagate the fact that the
+   navigation is the result of a user gesture. The <span>text directive user activation</span>
+   mechanism allows passing through this specifically scoped user-activation through such
+   navigations. This means a page is able to programmatically navigate to a text fragment a single
+   time, as if it has a user gesture. However, since this resets the <span>text directive user
+   activation</span>, further text fragment navigations cannot activate without a new user
+   gesture.</p>
+
+   <p>The following diagram demonstrates how the flag is used to activate a text fragment through
+   this mechanism:</p>
+
+   <img style="margin-left:auto;margin-right:auto;display:block" width="745" height="671"
+   src="/images/text-directive-user-activation-flag.png" alt="Diagram showing how the text directive
+   user activation flag is set and used">
+  </div>
+
 
   <h4>Syntax</h4>
 
   <!-- TODO(domfarolino): Is this non-normative? -->
 
-  <p>A <span>text directive</span> is specified in the <span>fragment directive</span> with the following format:</p>
+  <p>A <span>text directive</span> is specified in the <span>fragment directive</span> with the
+  following format:</p>
 
   <pre>
 #:~:text=[prefix-,]start[,end][,-suffix]
@@ -116241,6 +116293,10 @@ Add a helper algorithm for removing and returning a fragment directive string fr
 
   <h4 id="text-directive-security-and-privacy">Security and privacy considerations</h4>
 
+  <h5>Motivation</h5>
+
+  <!-- NON-NORMATIVE SECTION -->
+
   <p>Care must be taken when implementing <span data-x="text directive">text directives</span> so
   that it cannot be used to exfiltrate information across origins. Scripts can navigate a page to a
   cross-origin URL with a <span>text directive</span>. If a malicious actor can determine that the
@@ -116263,7 +116319,7 @@ Add a helper algorithm for removing and returning a fragment directive string fr
    <li><p>navigations that are the result of a user action.</p></li>
 
    <li><p>in cases where the navigation has a cross-origin initiator, the destination must be opener
-   isolated (i.e. no references to its global objects in other documents)</p></li>
+   isolated (i.e., no references to its global objects in other documents)</p></li>
   </ul>
 
   <h5>Scroll on navigation</h5>