index.bs

<pre class='metadata'>
Status: CG-DRAFT
Title: URL Fragment Text Directives
ED: https://wicg.github.io/scroll-to-text-fragment/
Shortname: text-directive
Level: 1
Editor: Nick Burris, Google https://www.google.com, nburris@chromium.org
Editor: David Bokan, Google https://www.google.com, bokan@chromium.org
Abstract: Text directives add support for specifying a text snippet in the URL
    fragment. When navigating to a URL with such a fragment, the user agent
    can quickly emphasise and/or bring it to the user's attention.
Group: wicg
Repository: wicg/scroll-to-text-fragment
Markup Shorthands: markdown yes
WPT Display: inline
</pre>

<pre class='link-defaults'>
spec:css-cascade-5; type:dfn; text:computed value
spec:css-display-3; type:value; for:display; text:flex
spec:css-display-3; type:value; for:display; text:grid
spec:css-display-4; type:property; text:display
spec:css-display-4; type:property; text:visibility
spec:dom; type:dfn; for:/; text:element
spec:dom; type:dfn; for:range; text:end
spec:dom; type:dfn; for:range; text:start
spec:dom; type:dfn; text:parent element
spec:dom; type:dfn; text:range
spec:html; type:element; text:link
spec:html; type:element; text:script
spec:html; type:element; text:style
spec:url; type:dfn; text:fragment
</pre>

<pre class="anchors">
spec:html; type:dfn; for:browsing context; text:group; url: https://html.spec.whatwg.org/multipage/browsers.html#tlbc-group
spec:html; type:dfn; for:/; text:navigable; url: https://html.spec.whatwg.org/multipage/document-sequences.html#navigable
spec:html; type:dfn; for:/; text:origin; url: https://html.spec.whatwg.org/multipage/browsers.html#concept-origin
spec:html; type:dfn; text:user navigation involvement; url: https://html.spec.whatwg.org/multipage/browsing-the-web.html#user-navigation-involvement
spec:html; type:dfn; for:document state; text:initiator origin; url: https://html.spec.whatwg.org/multipage/browsing-the-web.html#document-state-initiator-origin
spec:html; type:dfn; for:/; text:document state; url: https://html.spec.whatwg.org/multipage/browsing-the-web.html#she-document-state
spec:html; type:dfn; for:she; text:document; url: https://html.spec.whatwg.org/multipage/browsing-the-web.html#she-document
</pre>

<pre class="biblio">
  {
    "document-policy": {
      "authors": [
        "Ian Clelland"
      ],
      "href": "https://wicg.github.io/document-policy",
      "title": "Document Policy",
      "status": "ED",
      "publisher": "W3C",
      "deliveredBy": [
        "https://www.w3.org/2011/webappsec/"
      ]
    },
    "fetch-metadata": {
      "authors": [
        "Mike West"
      ],
      "href": "https://w3c.github.io/webappsec-fetch-metadata/",
      "title": "Fetch Metadata Request Headers",
      "status": "WD",
      "publisher": "W3C",
      "deliveredBy": [
        "https://www.w3.org/TR/fetch-metadata/"
      ]
    }
  }
</pre>

<style>
  .monkeypatch {
    color: grey;
  }

  .monkeypatch .diff {
    color: var(--text);
  }
</style>

<h2 id=infrastructure>Infrastructure</h2>

<p>This specification depends on the Infra Standard. [[!INFRA]]

# Introduction # {#introduction}

<div class='note'>This section is non-normative</div>

## Use cases ## {#use-cases}

### Web text references ### {#web-text-references}
The core use case for text fragments is to allow URLs to serve as an exact text
reference across the web. For example, Wikipedia references could link to the
exact text they are quoting from a page. Similarly, search engines can serve
URLs that direct the user to the answer they are looking for in the page rather
than linking to the top of the page.

### User sharing ### {#user-sharing}
With text directives, browsers may implement an option to 'Copy URL to here'
when the user opens the context menu on a text selection. The browser can then
generate a URL with the text selection appropriately specified, and the
recipient of the URL will have the specified text conveniently indicated.
Without text fragments, if a user wants to share a passage of text from a page,
they would likely just copy and paste the passage, in which case the receiver
loses the context of the page.

## Link Lifetime ## {#link-lifetime}

This specification attempts to maximize the useful lifetime of text directive links, for example, by
using the actual text content as the URL payload, and allowing a fallback element-id fragment.
However, pages on the web often update and change their content. As such, links like this may "rot"
in that the text content they point to no longer exists on the destination page.

Text directive links can be useful despite this problem. In user sharing use cases, the link is
often transient, intended to be used only within a short time of sending. For longer duration use
cases, such as references and web page links, text directives are still valuable since they degrade
gracefully into an ordinary link. Additionally, the presence of a stale text directive can be useful
information to surface to a user, to help them understand the link creator's original intent and
that the page content may have changed since the link was created.

See [[#generating-text-fragment-directives]] for best practices on how to create robust text
directive links.

# Description # {#description}

## Indication ## {#indication}

<div class='note'>This section is non-normative</div>

This specification intentionally doesn't define what actions a user agent takes
to "indicate" a text match. There are different experiences and trade-offs a
user agent could make. Some examples of possible actions:

* Providing visual emphasis or highlight of the text passage
* Automatically scrolling the passage into view when the page is navigated
* Activating a UA's find-in-page feature on the text passage
* Providing a "Click to scroll to text passage" notification
* Providing a notification when the text passage isn't found in the page

<div class='note'>
The choice of action can have implications for user security and privacy.  See
the [[#security-and-privacy]] section for details.
</div>

## Syntax ## {#syntax}

<div class='note'>This section is non-normative</div>

A [=text directive=] is specified in the [=/fragment directive=] (see
[[#the-fragment-directive]]) with the following format:
<pre>
#:~:text=[prefix-,]start[,end][,-suffix]
          context  |--match--|  context
</pre>
<em>(Square brackets indicate an optional parameter)</em>

The text parameters are percent-decoded before matching. Dash (-), ampersand
(&), and comma (,) characters in text parameters are percent-encoded to avoid
being interpreted as part of the text directive syntax.

The only required parameter is <code>start</code>. If only <code>start</code> is specified, the
first instance of this exact text string is the target text.

<div class="example">
<code>#:~:text=an%20example%20text%20fragment</code> indicates that the
exact text "an example text fragment" is the target text.
</div>

If the <code>end</code> parameter is also specified, then the text directive refers to a
range of text in the page. The target text range is the text range starting at
the first instance of <code>start</code>, until the first instance of <code>end</code> that
appears after <code>start</code>. This is equivalent to specifying the entire text range
in the <code>start</code> parameter, but allows the URL to avoid being bloated with a
long text directive.

<div class="example">
<code>#:~:text=an%20example,text%20fragment</code> indicates that the first
instance of "an example" until the following first instance of "text fragment"
is the target text.
</div>

### Context Terms ### {#context-terms}

<div class='note'>This section is non-normative</div>

The other two optional parameters are context terms. They are specified by the
dash (-) character succeeding the prefix and preceding the suffix, to
differentiate them from the <code>start</code> and <code>end</code> parameters, as any
combination of optional parameters can be specified.

Context terms are used to disambiguate the target text fragment. The context
terms can specify the text immediately before (prefix) and immediately after
(suffix) the text fragment, allowing for whitespace.

<div class="note">
While a match succeeds only if the context terms surround the target text
fragment, any amount of whitespace is allowed between context terms and the text
fragment. This allows context terms to cross element boundaries, for example if
the target text fragment is at the beginning of a paragraph and needs
disambiguation by the previous element's text as a prefix.
</div>

The context terms are not part of the targeted text fragment and are not
visually indicated.

<div class="example">
<code>#:~:text=this%20is-,an%20example,-text%20fragment</code> would match
to "an example" in "this is an example text fragment", but not match to "an
example" in "here is an example text".
</div>

### BiDi Considerations ### {#bidi-considerations}

<div class='note'>This section is non-normative</div>

<div class='note'>
  See <a
  href="https://www.w3.org/International/articles/inline-bidi-markup/uba-basics.en">Unicode
  Bidirectional Algorithm basics</a> for a good overview of how Bidirectional
  text works.
</div>

Since URL strings are ASCII encoded, they provide no built-in support for
bi-directional text. However, the content that we wish to target on a page can
be LTR (left-to-right), RTL (right-to-left) or both (Bidirectional/BiDi). This
section provides an intuitive description the behavior implicitly described by
the normative sections further in this spec.

The characters of each term in the text fragment are in <em>logical order</em>,
that is, the order in which a native reader would read them in (and also the
order in which characters are stored in memory).

Similarly, the <code>prefix</code> and <code>start</code> terms identify
text coming before another term in logical order, while <code>suffix</code> and
<code>end</code> follow other terms in logical order.

Note: user agents can visually render URLs in a manner friendlier to a native
reader, for example, by converting the displayed string to Unicode. However, the
string representation of a URL remains plain ASCII characters.

<div class="example">
  Suppose we want to select the text <code lang="ar">مِصر‎</code> (Egypt, in Arabic),
  that's preceeded by <code lang="ar">البحرين‎</code> (Bahrain, in Arabic). We would
  first percent encode each term:

  <code lang="ar">مِصر‎</code> becomes "%D9%85%D8%B5%D8%B1" (Note: UTF-8 character
  [0xD9,0x85] is the first (right-most) character of the Arabic word.)

  <code lang="ar">البحرين‎</code> becomes "%D8%A7%D9%84%D8%A8%D8%AD%D8%B1%D9%8A%D9%86"

  The text fragment would then become:

  <code>
    :~:text=%D8%A7%D9%84%D8%A8%D8%AD%D8%B1%D9%8A%D9%86-,%D9%85%D8%B5%D8%B1
  </code>

  When displayed in a browser's address bar, the browser can visually render the
  text in its natural RTL direction, appearing to the user:

  <code>
    :~:text=<span lang="ar">البحرين</span>-,<span lang="ar">مِصر</span>
  </code>
</div>

## The Fragment Directive ## {#the-fragment-directive}

To avoid compatibility issues with usage of existing URL fragments, this spec
introduces the concept of a <dfn>fragment directive</dfn>. It is the portion of
the URL [=url/fragment=] that follows the [=fragment directive delimiter=] and
may be null if the delimiter does not appear in the fragment.

The <dfn>fragment directive delimiter</dfn> is the string ":~:", that is the
three consecutive code points U+003A (:), U+007E (~), U+003A (:).

<div class="note">
  The [=fragment directive=] is part of the URL fragment. This means it
  always appears after a U+0023 (#) code point in a URL.
</div>

<div class="example">
  To add a [=fragment directive=] to a URL like https://example.com, a fragment
  is first appended to the URL: https://example.com#:~:text=foo.
</div>

The fragment directive is parsed and processed into individual
<dfn>directives</dfn>, which are instructions to the user agent to perform some
action. Multiple directives may appear in the fragment directive.

<div class="note">
  The only directive introduced in this spec is the text directive but others
  could be added in the future.
</div>

<div class="example">
  <code>https://example.com#:~:text=foo&text=bar&unknownDirective</code>
  <p>Contains 2 text directives and one unknown directive.</p>
</div>

To prevent impacting page operation, it is stripped from script-accessible APIs to prevent
interaction with author script. This also ensures future directives can be added without web
compatibility risk.

### Extracting the fragment directive ### {#extracting-the-fragment-directive}

This section describes the mechanism by which the fragment directive is hidden
from script and how it fits into [[HTML#navigation-and-session-history]].

<div class="note">
  The summarized changes in this section:

  * Session history entries now include a new "directive state" item
  * All new entries are created with a directive state with an empty value. If the new URL includes
      a fragment directive it will be written to the state's value (otherwise it remains null).
  * Any time a URL potentially including a fragment directive is written to a session history entry,
      extract the fragment directive from the URL and store it in a directive state item of the
      entry. There are four such points where a URL can potentially include a directive:
      * In the "navigate" steps for typical cross-document navigations
      * In the "navigate to a fragment" steps for fragment based same-document navigations
      * In the "URL and history update steps" for synchronous updates such as
          pushState/replaceState.
      * In the "create navigation params by fetching" steps for URLs coming from a redirect.
  * Same-document navigations that change only the fragment, and the new URL doesn't specify a
      directive, will create an entry whose directive state refers to the previous entry's directive
      state.

</div>

In [[HTML#session-history-infrastructure]], define [=/directive state=]:

>   <strong>Monkeypatching [[HTML#session-history-infrastructure]]:</strong>
>
>   <dfn>directive state</dfn> holds the value of the [=fragment directive=] at the time the session
>   history entry was created and is used to invoke directives, such as text highlighting, whenever
>   the entry is traversed. It has:
>   * <dfn for="directive state">value</dfn>, the [=fragment directive=] [=ASCII string=] or null,
>       initially null.
>
>   A [=/directive state=] may be shared by multiple session history entries.
>
>   <div class="note">
>       <p>The fragment directive is removed from the URL before the URL is set to the session
>       history entry. It is instead stored in the directive state. This prevents it from being
>       visible to script APIs so that a directive can be specified without interfering with a
>       page's operation.</p>
>
>       <p>The fragment directive is stored in the directive state object, rather than a raw string,
>       since the same directive state can be shared across multiple contiguous session history
>       entries. On a traversal, the directive is only processed (i.e. search text and highlight) if
>       the directive state has changed between two entries.</p>
>   </div>

To the definition of <a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#session-history-entry">session history entry</a>, add:

>   <strong>Monkeypatching [[HTML#session-history-entries]]:</strong>
>
>   <div class="monkeypatch">A session history entry is a struct with the following items:
>     * ...
>     * persisted user state, which is implementation-defined, initially null
>     * <span class="diff"><dfn for=she>directive state</dfn>, a [=/directive state=],
>         initially a new [=/directive state=]</span>
>   </div>

Add a helper algorithm for removing and returning a fragment directive string from a [=/URL=]:

>   <strong>Monkeypatching [[HTML]]:</strong>
>
>   <div class="note">
>     This algorithm makes a URL's fragment end at the [=fragment directive
>     delimiter=]. The returned [=/fragment directive=] includes all characters that follow the
>     delimiter but does not include the delimiter.
>   </div>
>
>   <div class="issue">
>     TODO: If a URL's fragment ends with ':~:' (i.e. empty directive), this will return null which
>     is treated as the URL not specifying an explicit directive (and avoids clobbering an existing
>     one. But maybe in this case we should return the empty string? That way a page can explicitly
>     clear directives/highlights by navigating/pushState to '#:~:'.
>   </div>
>
>   To <dfn>remove the fragment directive</dfn> from a [=/URL=] |url|, run these steps:
>   1. Let |raw fragment| be equal to |url|'s [=url/fragment=].
>   1. Let |fragment directive| be null.
>   1. If |raw fragment| is non-null and contains the [=fragment directive delimiter=] as a
>       substring:
>       1. Let |position| be the [=string/position variable=] pointing to the first code
>           point of the first instance, if one exists, of the [=fragment directive delimiter=] in
>           |raw fragment|, or past the end of |raw fragment| otherwise.
>       1. Let |new fragment| be the [=code point substring by positions=] of |raw fragment| from
>           the start of |raw fragment| to |position|.
>       1. Advance |position| by the [=string/code point length=] of the [=fragment directive
>           delimiter=].
>       1. If |position| does not point past the end of |raw fragment|:
>           1. Set |fragment directive| to the [=code point substring to the end of the string=]
>               |raw fragment| starting from |position|
>       1. Set |url|'s [=url/fragment=] to |new fragment|.
>   1. Return |fragment directive|.
>
>   <div class="example">
>      <code>https://example.org/#test:~:text=foo</code> will be parsed such that
>      the fragment is the string "test" and the [=/fragment directive=] is the string
>      "text=foo".
>   </div>

The next four monkeypatches modify the creation of a session history entry, where the URL might
contain a fragment directive, to remove the fragment directive and store it in the [=/directive
state=].

In the definition of [=navigate=]:

>   <strong>Monkeypatching [[HTML#beginning-navigation]]:</strong>
>
>   <div class="monkeypatch">To navigate a navigable navigable to a URL |url|...:
>     1. ...
>         <li value="14">Set navigable's ongoing navigation to navigationId.</li>
>     15. If url's scheme is "javascript", then...
>     16. In parallel, run these steps:
>         1. ...
>             <li value="5">If url is about:blank, then set documentState's origin to documentState's initiator origin.</li>
>         6. Otherwise, if url is about:srcdoc, then set documentState's origin to navigable's parent's active document's origin.
>         7. <strike>Let historyEntry be a new session history entry, with its URL set to url and
>             its document state set to documentState.</strike>
>             <li value="7"><span class="diff">Let |fragment directive| be the result of running [=remove the
>             fragment directive=] on |url|.</span></li>
>         8. <span class="diff">Let |directive state| be a new [=/directive
>             state=] with [=directive state/value=] set to |fragment directive|.</span>
>         9. <span class="diff">Let historyEntry be a new session history entry, with its URL
>             set to |url|, its document state set to documentState, and its [=she/directive state=]
>             set to |directive state|.</span>
>         10. Let navigationParams be null.
>         11. ...
>   </div>

In the definition of <a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#navigate-fragid">navigate to a fragment</a>:

>   <strong>Monkeypatching [[HTML#scroll-to-fragid]]:</strong>
>
>   <div class="monkeypatch">To navigate to a fragment given navigable |navigable|, ...:
>     1. <span class="diff">Let |directive state| be navigable's active session history
>         entry's [=she/directive state=].</span>
>     1. <span class="diff">Let |fragment directive| be the result of running
>         [=remove the fragment directive=] on |url|.</span>
>     1. <span class="diff">If |fragment directive| is not null:</span>
>         <div class="note">Otherwise, when only the fragment has changed and it did not specify
>         a directive, the active entry's directive state is reused. This prevents a fragment
>         change from clobbering highlights.</div>
>         1. <span class="diff">Let |directive state| be a new [=/directive state=] with
>             [=directive state/value=] set to |fragment directive|.
>     2. Let historyEntry be a new session history entry, with
>         * URL url
>         * document state navigable's active session history entry's document state
>         * scroll restoration mode navigable's active session history entry's scroll restoration
>             mode
>         * <span class="diff">[=she/directive state=] |directive state|</span>
>     2. Let entryToReplace be navigable's active session history entry if historyHandling is
>         "replace", otherwise null.
>     3. ...
>   </div>

In the definition of <a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#url-and-history-update-steps">URL and history update steps</a>:

>   <strong>Monkeypatching [[HTML#navigate-non-frag-sync]]:</strong>
>
>   <div class="monkeypatch">The URL and history update steps, given a Document |document|, ...:
>     1. Let |navigable| be |document|'s node navigable.
>     2. Let |activeEntry| be |navigable|'s active session history entry.
>     3. <span class="diff">Let |fragment directive| be the result of running [=remove the
>         fragment directive=] on |newUrl|.</span>
>     5. Let |historyEntry| be a new session history entry, with
>         * URL |newUrl|
>         * ...
>         * <span class="diff">[=she/directive state=] |activeEntry|'s [=she/directive
>             state=]</span>
>     6. If |document|'s is initial about:blank is true, then set historyHandling to "replace".
>     7. If historyHandling is "push", then:
>         1. Increment document's history object's index.
>         2. Set document's history object's length to its index + 1.
>         3. <span class="diff">If |newUrl| does not equal |activeEntry|'s URL with exclude
>             fragments set to true OR |fragment directive| is not null, then:</span>
>             <div class="note">Otherwise, when only the fragment has changed and it did not specify
>             a directive, the active entry's directive state is reused. This prevents a fragment
>             change from clobbering highlights.</div>
>             1. <span class="diff">Let |historyEntry|'s [=she/directive state=] be a new
>                 [=/directive state=] with [=directive state/value=] set to |fragment
>                 directive|.</span>
>     8. <span class="diff">Otherwise, if |fragment directive| is not null, set
>         |historyEntry|'s [=she/directive state=]'s [=directive state/value=] to |fragment
>         directive|.</span>
>     9. If serializedData is not null, then restore the history object state given document and
>         newEntry.
>   </div>

In the definition of <a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#create-navigation-params-by-fetching">
create navigation params by fetching</a>:

>   <strong>Monkeypatching [[HTML#populating-a-session-history-entry]]:</strong>
>
>   <div class="monkeypatch">To create navigation params by fetching given a session history entry
>       |entry|, ...:
>     1. Assert: this is running in parallel.
>     1. ...
>         <li value="17">Let currentURL be request's current URL.</li>
>     1. Let commitEarlyHints be null.
>     1. While true:
>         1. If request's reserved client is not null and currentURL's origin is not the same as request's reserved client's creation URL's origin, then:
>         1. ...
>             <li value="21">Set currentURL to |locationURL|.</li>
>         1. <span class="diff">Let |fragment directive| be the result of running
>             [=remove the fragment directive=] on |locationURL|.</span>
>         1. <strike class="diff">Set |entry|'s URL to currentURL.</strike>
>         1. <span class="diff">Set |entry|'s URL to |locationURL|.</span>
>         1. <span class="diff">Set |entry|'s [=she/directive state=]'s [=directive state/value=] to
>             |fragment directive|.
>         1. If |locationURL| is a URL whose scheme is not a fetch scheme, then return a new non-fetch
>             scheme navigation params, with initiator origin request's current URL's origin
>         1. ...
>   </div>

<div class="note">
  <p>
    Since a Document is populated from a history entry, its [=Document/URL=] will not include the
    fragment directive. Similarly, since a window's {{Location}} object is a representation of the
    [=/URL=] of the [=active document=], all getters on it will show a fragment-directive-stripped
    version of the URL.
  </p>

  <p>
    Additionally, since the {{HashChangeEvent}} is
    <a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#updating-the-document">
    fired in response to a changed fragment</a> between URLs of session history entries,
    <code>hashchange</code> will not be fired if a navigation or traversal changes only the fragment
    directive.
  </p>

  <p>
    Some examples are provided to help clarify various edge cases.
  </p>
</div>

<div class="example">
  ```
  window.location = "https://example.com#page1:~:hello";
  console.log(window.location.href); // 'https://example.com#page1'
  console.log(window.location.hash); // '#page1'
  ```

  The initial navigation created a new session history entry. The entry's URL is stripped of the
  fragment directive: "https://example.com#page1". The entry's directive state value is set to
  "hello". Since the document is populated from the entry, web APIs don't include the fragment
  directive in URLs.

  ```
  location.hash = "page2";
  console.log(location.href); // 'https://example.com#page2'
  ```

  A same document navigation changed only the fragment. This adds a new session history entry in the
  <a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#navigate-fragid">navigate to
  a fragment</a> steps. However, since only the fragment changed, the new entry's directive state
  points to the same state as the first entry, with a value of "bar".

  ```
  onhashchange = () => console.assert(false, "hashchange doesn't fire.");
  location.hash = "page2:~:world";
  console.log(location.href); // 'https://example.com#page2'
  onhashchange = null;
  ```

  A same document navigation changes only the fragment but includes a fragment directive. Since an
  explicit directive was provided, the new entry includes its own directive state with a value of
  "fizz".

  The hashchange event is not fired since the page-visible fragment is unchanged; only the fragment
  directive changed. This is because the comparison for hashchange is done on the URLs in the
  session history entries, where the fragment directive has been removed.

  ```
  history.pushState("", "", "page3");
  console.log(location.href); // 'https://example.com/page3'
  ```

  pushState creates a new session history entry for the same document. However, since the
  non-fragment URL has changed, this entry has its own directive state with value currently null.
</div>

<div class="example">
  In other cases where a URL is not set to a session history entry, there is no
  fragment directive stripping.

  For URL objects:

  ```
  let url = new URL('https://example.com#foo:~:bar');
  console.log(url.href); // 'https://example.com#foo:~:bar'
  console.log(url.hash); // '#foo:~:bar'

  document.url = url;
  console.log(document.url.href); // 'https://example.com#foo:~:bar'
  console.log(document.url.hash); // '#foo:~:bar'

  ```

  The `<a>` or `<area>` elements:

  ```
  <a id='anchor' href="https://example.com#foo:~:bar">Anchor</a>
  <script>
    console.log(anchor.href); // 'https://example.com#foo:~:bar'
    console.log(anchor.hash); // '#foo:~:bar'
  </script>
  ```
</div>

### Applying directives to a document ### {#applying-directives-to-a-document}

The section above described how the [=fragment directive=] is separated from the URL and stored in a
session history entry.

This section defines how and when navigations and traversals make use of history entry's [=she/directive
state=] to apply the directives associated with a session history entry to a [=/Document=].

>   <strong>Monkeypatching [[DOM#interface-document]]:</strong>
>
>   Each document has an associated <dfn for="Document">pending text directives</dfn> which is either
>   null or an <a spec=infra>list</a> of [=text directives=]. It is initially null.

In the definition of <a spec="HTML">update document for history step application</a>:

>   <strong>Monkeypatching [[HTML#updating-the-document]]:</strong>
>
>   <div class="monkeypatch">To update document for history step application given a Document
>   |document|, a session history entry |entry|,...
>     1. ...
>         <li value="4">Set |document|'s history object's length to scriptHistoryLength</li>
>     5. If <var ignore>documentsEntryChanged</var> is true, then:
>         1. Let <var ignore>oldURL</var> be |document|'s latest entry's URL.
>         2. <div class="diff">If |document|'s latest entry's [=she/directive state=] is not
>             |entry|'s [=she/directive state=] then:
>             1. Let |fragment directive| be |entry|'s [=she/directive state=]'s
>                 [=directive state/value=].
>             1. Set |document|'s [=Document/pending text directives=] to the result of [=parse the
>                 fragment directive|parsing=] |fragment directive|.
>                 </div>
>         3. Set |document|'s latest entry to |entry|
>         4. ...
>   </div>

### Fragment directive grammar ### {#fragment-directive-grammar}

Note: This section is non-normative.

Note: This grammar is provided as a convenient reference; however, the rules and steps for parsing
are specified imperatively in the [[#text-directives]] section. Where this grammar differs in
behavior from the steps of that section, the steps there are to be taken as the authoritative source
of truth.

The [=FragmentDirective=] can contain multiple directives split by the "&" character. Currently this
means we allow multiple text directives to enable multiple indicated strings in the page, but this
also allows for future directive types to be added and combined. For extensibility, we do not fail
to parse if an unknown directive is in the &-separated list of directives.

A <a spec=infra>string</a> is a valid fragment directive if it matches the EBNF (Extended
Backus-Naur Form) production:

<dl>
  <dt>
    <dfn id="fragmentdirectiveproduction">`FragmentDirective`</dfn> `::=`
  </dt>
  <dd>
    <code>([=TextDirective=] | [=UnknownDirective=]) ("&" [=FragmentDirective=])?</code>
  </dd>
  <dt>
    <dfn>`TextDirective`</dfn> `::=`
  </dt>
  <dd>
    <code>"text="[=CharacterString=]</code>
  </dd>
  <dt>
    <dfn>`UnknownDirective`</dfn> `::=`
  </dt>
  <dd>
    <code>[=CharacterString=] - [=TextDirective=]</code>
  </dd>
  <dt>
    <dfn>`CharacterString`</dfn> `::=`
  </dt>
  <dd>
    <code>([=ExplicitChar=] | [=PercentEncodedByte=])*</code>
  </dd>
  <dt>
    <dfn>`ExplicitChar`</dfn> `::=`
  </dt>
  <dd>
    <code>[a-zA-Z0-9] | "!" | "$" | "'" | "(" | ")" | "*" | "+" | "." | "/" | ":" |
    ";" | "=" | "?" | "@" | "_" | "~" | "," | "-"</code>
  <div class = "note">
    An [=ExplicitChar=] may be any [=URL code point=] other than "&".
  </div>
  </dd>
</dl>

A [=TextDirective=] is considered valid if it matches the following production:

<dl>
  <dt><dfn>`ValidTextDirective`</dfn> `::=`</dt>
  <dd><code>"text=" [=TextDirectiveParameters=]</code></dd>
  <dt><dfn>`TextDirectiveParameters`</dfn> `::=`</dt>
  <dd>
    <code>
    ([=TextDirectivePrefix=] ",")? [=TextDirectiveString=]
    ("," [=TextDirectiveString=])?  ("," [=TextDirectiveSuffix=])?
    </code>
  </dd>
  <dt><dfn>`TextDirectivePrefix`</dfn> `::=`</dt>
  <dd><code>[=TextDirectiveString=]"-"</code></dd>
  <dt><dfn>`TextDirectiveSuffix`</dfn> `::=`</dt>
  <dd><code>"-"[=TextDirectiveString=]</code></dd>
  <dt><dfn>`TextDirectiveString`</dfn> `::=`</dt>
  <dd><code>([=TextDirectiveExplicitChar=] | [=PercentEncodedByte=])+</code></dd>
  <dt><dfn>`TextDirectiveExplicitChar`</dfn> `::=`</dt>
  <dd>
  <code>
    [a-zA-Z0-9] | "!" | "$" | "'" | "(" | ")" | "*" | "+" | "." | "/" | ":" |
    ";" | "=" | "?" | "@" | "_" | "~"
    </code>
  <div class = "note">
    A [=TextDirectiveExplicitChar=] is any [=URL code point=] that is not explicitly used in the
    [=FragmentDirective=] or [=ValidTextDirective=] syntax, that is "&", "-", and ",".  If a text
    fragment refers to a "&", "-", or "," character in the document, it will be percent-encoded in
    the fragment.
  </div>
  </dd>
  <dt><dfn>`PercentEncodedByte`</dfn> `::=`</dt>
  <dd><code>"%" [a-zA-Z0-9][a-zA-Z0-9]</code></dd>
</dl>

## Text Directives ## {#text-directives}

A <dfn>text directive</dfn> is a kind of [=/directive=] representing a range of
text to be indicated to the user. It is a <a spec=infra>struct</a> that consists of
four strings: <dfn for="text directive">start</dfn>,
<dfn for="text directive">end</dfn>,
<dfn for="text directive">prefix</dfn>, and
<dfn for="text directive">suffix</dfn>. [=text directive/start=]
is required to be non-null. The other three items may be set to null,
indicating they weren't provided. The empty string is not a valid value for any
of these items.

See [[#syntax]] for the what each of these components means and how they're
used.

<div algorithm="percent-decode a text directive term">
  To <dfn>percent-decode a text directive term</dfn> given an input <a spec=infra>string</a> |term|:

  <ol class="algorithm">
    1. If |term| is null, return null.
    1. <a spec=infra>Assert</a>: |term| is an <a spec=infra>ASCII string</a>.
    1. Let |decoded bytes| be the result of <a spec=url for=string
        lt="percent-decode">percent-decoding</a> |term|.
    1. Return the result of running <a spec=encoding>UTF-8 decode without BOM</a> on |decoded
        bytes|.
  </ol>
</div>

<div algorithm="parse a text directive">
  To <dfn>parse a text directive</dfn>, on an <a spec="infra">string</a> |text
  directive value|, run these steps:

  <div class="note">
    <p>
      This algorithm takes a single text directive value string as input (e.g.  "prefix-,foo,bar") and
      attempts to parse the string into the components of the directive (e.g. ("prefix", "foo", "bar",
      null)). See [[#syntax]] for the what each of these components means and how they're used.
    </p>
    <p>
      Returns null if the input is invalid. Otherwise, returns a [=text directive=].
    </p>
  </div>

  <ol class="algorithm">
    1. Let |prefix|, |suffix|, |start|, |end|, each be null.
    1. <a spec="infra">Assert</a>: |text directive value| is an <a spec="infra">ASCII string</a>
        with no code points in the <a spec="URL">fragment percent-encode set</a> and no instances of
        U+0026 (&).
    1. Let |tokens| be a <a for=/>list</a> of <a spec="infra">strings</a> that result from
        <a lt="strictly split a string">strictly splitting</a> |text directive value| on U+002C (,).
    1. If |tokens| has <a for=list>size</a> less than 1 or greater than 4, return null.
    1. If the first item of |tokens| <a spec=infra for=string>ends with</a> U+002D (-):
        1. Set |prefix| to the <a spec=infra lt="code point substring">substring</a> of |tokens|[0]
            from 0 with length |tokens|[0]'s <a spec=infra for=string lt="code point
            length">length</a> - 1.
        1. Remove the first item of |tokens|.
        1. If |prefix| is the empty string or contains any instances of U+002D (-), return null.
        1. If |tokens| is <a spec="infra" for="list">empty</a>, return null.
    1. If the last item of |tokens| <a spec=infra for=string>starts with</a> U+002D (-):
        1. Set |suffix| to the <a spec=infra lt="code point substring to the end of the
            string">substring</a> of the last item of |tokens| from 1 to the end of the string.
        1. Remove the last item of |tokens|.
        1. If |suffix| is the empty string or contains any instances of U+002D (-), return null.
        1. If |tokens| is <a spec="infra" for="list">empty</a>, return null.
    1. If |tokens| has <a spec=infra for=list>size</a> greater than 2, return null.
    1. <a spec=infra>Assert</a>: |tokens| has <a spec=infra for=list>size</a> 1 or 2.
    1. Set |start| to the first item in |tokens|.
    1. Remove the first item in |tokens|.
    1. If |start| is the empty string or contains any instances of U+002D (-), return null.
    1. If |tokens| is not <a spec=infra for=list>empty</a>:
        1. Set |end| to the first item in |tokens|.
        1. If |end| is the empty string or contains any instances of U+002D (-), return null.
    1. Return a new [=text directive=], with
        <dl class="props">
          <dt>[=text directive/prefix=]</dt>
          <dd>The [=percent-decode a text directive term|percent-decoding=] of |prefix|</dd>
          <dt>[=text directive/start=]</dt>
          <dd>The [=percent-decode a text directive term|percent-decoding=] of |start|</dd>
          <dt>[=text directive/end=]</dt>
          <dd>The [=percent-decode a text directive term|percent-decoding=] of |end|</dd>
          <dt>[=text directive/suffix=]</dt>
          <dd>The [=percent-decode a text directive term|percent-decoding=] of |suffix|</dd>
        </dl>
  </ol>
</div>

<div algorithm="parse the fragment directive">

To <dfn>parse the fragment directive</dfn>, an an <a spec="infra">ASCII string</a> |fragment
directive|, run these steps:

<div class="note">
  This algorithm takes the fragment directive string (i.e. the part that follows ":~:") and returns
  a list of [=text directive=] objects parsed from that string. Can return an empty list.
</div>

<ol class="algorithm">
  1. Let |directives| be the result of <a spec="infra" lt="strictly split a string">strictly
      splitting</a> |fragment directive| on U+0026 (&).
  1. Let |output| be an initially empty <a spec="infra">list</a> of [=text directives=].
  1. <a spec="infra" for="list">For each</a> <a spec="infra">string</a> |directive| in |directives|:
      1. If |directive| does not <a spec="infra" lt="starts with" for="string">start with</a>
          "<code>text=</code>", then <a spec="infra" for="iteration">continue</a>.
      1. Let |text directive value| be the <a spec="infra" lt="code point substring to the end of
          the string">code point substring</a> from 5 to the end of |directive|.
          <div class="note">Note: this may be the empty string.</div>
      1. Let |parsed text directive| be the result of [=parse a text directive|parsing=] |text
          directive value|.
      1. If |parsed text directive| is non-null, <a spec="infra" for="list">append</a> it to
          |output|.
  1. Return |output|.

</ol>

</div>

### Invoking Text Directives ### {#invoking-text-directives}

This section describes how text directives in a document's [=Document/pending text directives=] are
processed and invoked to cause indication of the relevant text passages.

<div class="note">
    The summarized changes in this section:

    * Modify the indicated part processing model to try processing [=Document/pending text directives=]
        into a [=range=] that will be returned as the indicated part.
    * Modify "scrolling to a fragment" to correctly scroll and set the Document's target element in the case
        of a [=range=] based indicated part.
    * Ensure [=Document/pending text directives=] is reset to null when the user agent has finished the
        fragment search for the current navigation/traversal.
    * If the user agent finishes searching for a text directive, ensure it tries the regular
        fragment as a fallback.
</div>

In <a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#the-indicated-part-of-the-document">
indicated part</a>, enable a fragment to indicate a [=range=]. Make the following changes:

>   <strong>Monkeypatching [[HTML#scrolling-to-a-fragment]]:</strong>
>
>   <div class="monkeypatch">
>   For an HTML document |document|, the following processing model must be followed to determine
>   its indicated part:
>
>   1. <span class="diff">Let |text directives| be the document's [=Document/pending text directives=].
>       </span>
>   1. <span class="diff">If |text directives| is non-null then:</span>
>       1. <span class="diff">Let |ranges| be a <a spec=infra>list</a> that is the result of running
>           the [=invoke text directives=] steps with |text directives| and the document.</span>
>       1. <span class="diff">If |ranges| is non-empty, then:</span>
>           1. <span class="diff">Let |firstRange| be the first item of |ranges|.</span>
>           1. <span class="diff">Visually indicate each [=range=] in |ranges| in an
>               [=implementation-defined=] way. The indication must not be observable from author
>               script. See [[#indicating-the-text-match]].</span>
>               <div class="note">
>                 The first [=range=] in |ranges| is the one that gets scrolled into view but all
>                 ranges should be visually indicated to the user.
>               </div>
>           1. <span class="diff">Set |firstRange| as |document|'s indicated part, return.</span>
>   1. Let fragment be document's URL's fragment.
>   1. If fragment is the empty string, then return the special value top of the document.
>   1. Let potentialIndicatedElement be the result of finding a potential indicated element given
>       document and fragment.
>   1. ...
>
>   </div>

In <a spec=HTML>scroll to the fragment</a>, handle an indicated part that is a [=range=] and also
prevent fragment scrolling if the force-load-at-top policy is enabled. Make the following changes:

>   <strong>Monkeypatching [[HTML#scrolling-to-a-fragment]]:</strong>
>
>   <div class="monkeypatch">
>   1. If document's indicated part is null, then set document's target element to null.
>   2. Otherwise, if document's indicated part is top of the document, then:
>       1. Set document's target element to null.
>       2. Scroll to the beginning of the document for document.
>       3. Return.
>   3. Otherwise:
>       1. Assert: document's indicated part is an element <span class="diff">or it is a [=range=].</span>
>       2. <span class="diff">Let |scrollTarget| be |document|'s indicated part.</span>
>       3. <span class="diff">Let |target| be |scrollTarget|.</span>
>       4. <span class="diff">If |target| is a [=range=], then:</span>
>           1. <span class="diff">Set |target| to be the [=first common ancestor=] of |target|'s
>               [=range/start node=] and [=range/end node=].</span>
>           2. <span class="diff">While |target| is non-null and is not an [=element=], set |target| to
>               |target|'s [=tree/parent=].</span>
>               <div class="issue">
>                   What should be set as target if inside a shadow tree?
>                   <a href="https://github.com/WICG/scroll-to-text-fragment/issues/190">#190</a>
>               </div>
>       5. <span class="diff">Assert: |target| is an [=element=].</span>
>       6. Set |document|'s target element to |target|.
>       7. Run the ancestor details revealing algorithm on |target|.
>       8. Run the ancestor hidden-until-found revealing algorithm on |target|.
>           <div class="issue">
>               These revealing algorithms currently wont work well since |target| could be an
>               ancestor or even the root document node. Issue
>               <a href="https://github.com/WICG/scroll-to-text-fragment/issues/89">#89</a> proposes
>               restricting matches to `contain:style layout` blocks which would resolve this
>               problem.
>           </div>
>       9. <span class="diff">Let |blockPosition| be "center" if |scrollTarget| is a [=range=],
>           "start" otherwise.</span>
>           <div class="note">
>             Scrolling to a text directive centers it in the block flow direction.
>           </div>
>       10. <strike class="diff">Scroll |target| into view, with behavior set to "auto", block set to
>           "start", and inline set to "nearest".</strike>
>
>           <li value="10"><span class="diff">[=scroll a target into view=],
>           with <em>target</em> set to |scrollTarget|, <em>behavior</em> set to "auto",
>           <em>block</em> set to |blockPosition|, and <em>inline</em> set to "nearest".</span>
>
>           <span class="diff">Implementations MAY avoid scrolling to the target if it is
>           produced from a [=text directive=].</span></li>
>       11. Run the focusing steps for target, with the Document's viewport as the fallback target.
>           <div class="issue">Implementation note: Blink doesn’t currently set focus for text
>           fragments, it probably should? TODO: file crbug.</div>
>       12. Move the sequential focus navigation starting point to target.
>
>   </div>

The next two monkeypatches ensure the user agent clears [=Document/pending text directives=] when
the fragment search is complete. In the case where a text directive search finishes because parsing
has stopped, it tries one more search for a non-text directive fragment.

In the definition of <a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#try-to-scroll-to-the-fragment">
try to scroll to the fragment</a>:

>   <strong>Monkeypatching [[HTML#scrolling-to-a-fragment]]:</strong>
>
>   <div class="monkeypatch">
>   To try to scroll to the fragment for a Document |document|, perform the following steps in
>   parallel:
>   1. Wait for an implementation-defined amount of time. (This is intended to allow the user agent
>       to optimize the user experience in the face of performance concerns.)
>   2. Queue a global task on the navigation and traversal task source given document's relevant
>       global object to run these steps:
>       1. <strike class="diff">If document has no parser, or its parser has stopped parsing, or the user agent
>           has reason to believe the user is no longer interested in scrolling to the fragment, then
>           abort these steps.</strike>
>           <li value="1" class="diff">If the user agent has reason to believe the user is no longer interested in scrolling to
>           the fragment, then:</span>
>           1. <span class="diff">Set [=Document/pending text directives=] to null.</span>
>           1. <span class="diff">Abort these steps.</span>
>       1. <span class="diff">If the document has no parser, or its parser has stopped parsing,
>           then:</li>
>           1. <span class="diff">If [=Document/pending text directives=] is not null, then:</span>
>               1. <span class="diff">Set [=Document/pending text directives=] to null.</span>
>               1. <span class="diff"><a spec=HTML>Scroll to the fragment</a> given |document|.</span>
>           1. <span class="diff">Abort these steps.</span>
>       2. Scroll to the fragment given document.
>       3. If document's indicated part is still null, then try to scroll to the fragment for
>           document. <span class="diff">Otherwise, set [=Document/pending text directives=] to
>           null.</span>

In the definition of
<a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#navigate-fragid">
navigate to a fragment</a>:

>   <strong>Monkeypatching [[HTML#scroll-to-fragid]]:</strong>
>
>   <div class="monkeypatch">To navigate to a fragment given navigable |navigable|, ...:
>     1. ...
>         <li value="8">Update document for history step application given navigable's active
>         document, historyEntry, true, scriptHistoryIndex, and scriptHistoryLength. </li>
>     9. Scroll to the fragment given navigable's active document.
>         <li class="diff">Set |navigable|'s active document's [=Document/pending text directives=] to
>         null.</li>
>     11. Let traversable be navigable's traversable navigable.
>     12. ...

Scrolling to the indicated part is only one of several things that happens from "scroll to the
fragment". Rename it and related definitions:

>   <strong>Monkeypatching [[HTML#scroll-to-fragid]]:</strong>
>
>   Rename [[HTML#scroll-to-fragid]] and related steps to "indicating a fragment" to reflect its
>   broader effects.

## Security and Privacy ## {#security-and-privacy}

### Motivation ### {#motivation}

<div class="note">This section is non-normative</div>

Care must be taken when implementing [=text directive=] so that it
cannot be used to exfiltrate information across origins. Scripts can navigate a
page to a cross-origin URL with a [=text directive=]. If a malicious
actor can determine that the text fragment was successfully found in victim
page as a result of such a navigation, they can infer the existence of any text
on the page.

The processing model in the following subsections restricts the feature to
mitigate the expected attack vectors. In summary, text directives are restricted
to:

* top level navigables (i.e. no iframes).
    * ISSUE(WICG/scroll-to-text-fragment#240): This isn't strictly true, Chrome
        allows this for same-origin initiators. Need to update the spec on this
        point.
* navigations that are the result of a user action
* 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)


### Scroll On Navigation ### {#scroll-on-navigation}

A UA may choose to automatically scroll a matched text passage into view. This
can be a convenient experience for the user but does present some risks that
implementing UAs need to be aware of.

There are known (and potentially unknown) ways a scroll on navigation might be
detectable and distinguished from natural user scrolls.

<div class="example">
  An origin embedded in an iframe in the target page registers an
  IntersectionObserver and determines in the first 500ms of page load whether
  a scroll has occurred. This scroll can be indicative of whether the text
  fragment was successfully found on the page.
</div>

<div class="example">
  Two users share the same network on which traffic is visible between them.
  A malicious user sends the victim a link with a text fragment to a
  page. The searched-for text appears nearby to a resource located on a unique
  (on the page) domain. The attacker may be able to infer the success or failure
  of the fragment search based on the order of requests for DNS lookup.
</div>

<div class="example">
  An attacker sends a link to a victim, sending them to a page that displays
  a private token. The attacker asks the victim to read back the token. Using
  a text fragment, the attacker gets the page to load for the victim such that
  warnings about keeping the token secret are scrolled out of view.
</div>

All known cases like this rely on specific circumstances about the target page
so don't apply generally. With additional restrictions about when the text
fragment can invoke an attacker is further restricted. Nonetheless, different
UAs can come to different conclusions about whether these risks are acceptable.
UAs need to consider these factors when determining whether to scroll as part of
navigating to a text fragment.

Conforming UAs may choose not to scroll automatically on navigation. Such UAs
may, instead, provide UI to initiate the scroll ("click to scroll") or none
at all. In these cases UA should provide some indication to the user that an
indicated passage exists further down on the page.

The examples above illustrate that in specific circumstances, it can be
possible for an attacker to extract 1 bit of information about content on the
page. However, care must be taken so that such opportunities cannot be
exploited to extract arbitrary content from the page by repeating the attack.
For this reason, restrictions based on user activation and browsing context
isolation are very important and must be implemented.

<div class="note">
  Browsing context isolation ensures that no other document can script the
  target document which helps reduce the attack surface.

  However, it also ensures any malicious use is difficult to hide. A browsing
  context that's the only one in a group will be a top level browsing context
  (i.e. a full tab/window).
</div>

If a UA does choose to scroll automatically, it must ensure no scrolling is
performed while the document is in the background (for example, in an inactive
tab). This ensures any malicious usage is visible to the user and prevents
attackers from trying to secretly automate a search in background documents.

If a UA chooses not to scroll automatically, it must scroll a fallback
element-id into view, if provided, regardless of whether a text fragment was
matched. Not doing so would allow detecting the text fragment match based on
whether the element-id was scrolled.

### Search Timing ### {#search-timing}

A naive implementation of the text search algorithm could allow information
exfiltration based on runtime duration differences between a matching and non-
matching query. If an attacker could find a way to synchronously navigate
to a [=text directive=]-invoking URL, they would be able to determine
the existence of a text snippet by measuring how long the navigation call takes.

<div class="note">
  The restrictions in [[#restricting-the-text-fragment]] prevent this
  specific case; in particular, the no-same-document-navigation restriction.
  However, these restrictions are provided as multiple layers of defence.
</div>

For this reason, the implementation <em>must ensure the runtime of
[[#navigating-to-text-fragment]] steps does not differ based on whether a match
has been successfully found</em>.

This specification does not specify exactly how a UA achieves this as there are
multiple solutions with differing tradeoffs. For example, a UA <em>may</em>
continue to walk the tree even after a match is found in [=find a range from a
text directive=].  Alternatively, it <em>may</em> schedule an asynchronous task
to find and set the [=/Document=]'s indicated part.

### Restricting the Text Fragment ### {#restricting-the-text-fragment}

<div class="note">
  This section integrates with HTML navigation to restrict when an indicated text directive will
  be allowed to scroll. In summary:

  * Add a boolean <code>text directive user activation</code> to both Document and Request. This
      flag is set on a document when created from a user activated navigation and consumed if a text
      directive is scrolled. If unconsumed, it can be transfered to an outgoing navigation request.
      This implements the user-activation-through-redirects behavior described in the note below.
  * Define a series of checks, performed on a document and the user involvement and initiator origin
      state of a navigation, to determine whether a text directive should be allowed to perform a
      scroll.
  * Compute the scroll permission from "finalize a cross document navigation" and from "navigate to
      a fragment steps" and plumb it through to the "scroll to the fragment" steps where its used to
      abort a text directive scroll.

</div>

Amend the definition of a [=/request=] and of a [=/Document=] to include a new
boolean [=document/text directive user activation=] field:

>   <strong>Monkeypatching [[FETCH]]:</strong>
>
>   A [=/request=] has an associated boolean <dfn for="request">text directive user activation</dfn>,
>   initially false.

>   <strong>Monkeypatching [[HTML]]:</strong>
>
>   Each [=/Document=] has a <dfn for="document">text directive user activation</dfn>, which is a boolean,
>   initially false.
>
>   <div class="note">
>     [=document/text directive user activation=] provides the necessary user gesture signal to allow
>     a single activation of a text fragment. 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.
>
>     If a [=/Document=]'s [=document/text directive user activation=] isn't used to activate a text
>     fragment, it is instead used to set a new navigation [=/request=]'s [=request/text directive user activation=]
>     to true. In this way, a [=document/text directive user activation=] can be propagated
>     from one [=/Document=] to another across a navigation.
>
>     Both [=/Document=]'s [=document/text directive user activation=] and [=/request=]'s
>     [=request/text directive user activation=] are always set to false when used, such that a
>     single user activation cannot be reused to activate more than one text fragment.
>   </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 200 status code containing
    script to set the <tt>window.location</tt>.
  </p>

  <p>
    Unlike real HTTP (<tt>status 3xx</tt>) redirects, these "client-side"
    redirects cannot propagate the fact that the navigation is the result of a
    user gesture. The [=document/text directive user activation=] 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 <code>text fragment user
    activation</code>, further text fragment navigations will not activation without a new user gesture.
  </p>
  <p>
    The following diagram demonstrates how the flag is used to activate a text
    fragment through a client-side redirect service:
  </p>

  <img style="margin-left:auto;margin-right:auto;display:block" width="745" height="671" src="https://raw.githubusercontent.com/WICG/scroll-to-text-fragment/master/text_fragment_activation_flag.png" alt="Diagram showing how a text fragment flag is set and used">

  <p>
    See [redirects.md](redirects.md) for a more in-depth discussion.
  </p>
</div>

Amend the <a spec=HTML>create navigation params by fetching</a> steps to transfer the [=active
document=]'s [=document/text directive user activation=] value into <var ignore>request</var>'s
[=request/text directive user activation=].

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>   1. Assert: this is running in parallel.
>   2. Let documentResource be entry's document state's resource.
>   3. Let <var ignore>request</var> be a new request, with
>
>      <dl class="props">
>       <dt>url</dt>
>       <dd><var ignore>entry</var>'s URL</dd>
>
>       <dt>...</dt>
>       <dd>...</dd>
>
>       <dt>referrer policy</dt>
>       <dd><var ignore>entry</var>'s document state's request referrer policy</dd>
>
>       <dt><span class="diff">[=request/text directive user activation=]</span></dt>
>       <dd><span class="diff">|navigable|'s [=navigable/active document=]'s [=document/text directive user activation=]</span></dd>
>      </dl>
>     </li>
>   4. <span class="diff">Set |navigable|'s [=navigable/active document=]'s [=document/text directive
>       user activation=] to false.</span>
>   5. If documentResource is a POST resource, then:
>       1. ...
>
> </div>

Amend the definition of <a spec=HTML>navigation params</a> to include a new field:

>   <strong>Monkeypatching [[HTML]]:</strong>
>
>  <dl>
>   <dt><dfn for="navigation params">user involvement</dfn></dt>
>   <dd>A <a spec=HTML>user navigation involvement</a> value.</dd>
>  </dl>
>

Initialize the [=navigation params/user involvement=] value everywhere a navigation params is
created. Specifically: initialize it to true in the <a spec=HTML>create navigation params by
fetching</a> case:

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>   To create navigation params by fetching given a session history entry entry, a navigable
>   navigable, a source snapshot params sourceSnapshotParams, a target snapshot params
>   targetSnapshotParams, a string cspNavigationType, a navigation ID-or-null navigationId, a
>   NavigationTimingType navTimingType, <span class="diff">and a <a spec=HTML>user navigation
>   involvement</a> |user involvement|</span>, perform the following steps. They return a navigation params,
>   a non-fetch scheme navigation params, or null.
>
>   1. Assert: this is running in parallel.
>   2. ...
>       <li value="23">Let resultPolicyContainer be the result of determining navigation params policy container given
>       response's URL, entry's document state's history policy container, sourceSnapshotParams's source
>       policy container, null, and responsePolicyContainer.</li>
>   24. If navigable's container is an iframe, and response's timing allow passed flag is set, then
>       set container's pending resource-timing start time to null.
>   25. Return a new navigation params, with
>
>       <dl>
>        <dt>id</dt>
>        <dd>navigationId</dd>
>        <dt>...</dt>
>        <dd>...</dd>
>        <dt>about base URL</dt>
>        <dd>entry's document state's about base URL</dd>
>        <dt class="diff">[=navigation params/user involvement=]</dt>
>        <dd class="diff">|user involvement|</dd>
>       </dl>
>
> </div>

Amend the
<a href="https://html.spec.whatwg.org/multipage/document-lifecycle.html#initialise-the-document-object">
create and initialize a Document object</a> steps to compute and store the [=document/text directive
user activation=] flag:

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>   18. Process link headers given document, navigationParams's response, and "pre-media".
>   19. <div class="diff">Set |document|'s [=document/text directive user activation=] to true if any of the following
>     conditions hold, false otherwise:
>       * |navigationParams|'s [=user involvement=] is "<code>activation</code>";
>       * |navigationParams|'s [=user involvement=] is "<code>browser UI</code>"; or
>       * |navigationParams|'s
>         <a href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#navigation-params-request">request</a>'s
>         [=request/text directive user activation=] is true.
>         <div class="note">
>           It's important that [=document/text directive user activation=] not be copyable so that
>           only one text fragment can be activated per user-activated navigation.
>         </div></div>
>   20. Return |document|.
>
> </div>

A <dfn>text directive allowing MIME type</dfn> is a [=MIME type=] whose [=MIME type/essence=] is
"<code>text/html</code>" or "<code>text/plain</code>".

Note: As noted in <a
href="https://html.spec.whatwg.org/multipage/browsing-the-web.html#scrolling-to-a-fragment">scrolling
to a fragment, fragment processing is defined individually by each MIME type. As such, the
<a spec=HTML>scroll to the fragment</a> steps where text directives are scrolled should only apply
to text/html media types. However, in practice, web browsers tend to apply HTML fragment processing
to other types, such as text/plain (e.g. add an element with an id to a text/plain document,
navigating to the fragment-id causes scrolling). While this is the case, enabling text directives in
text/plain documents is useful. Other types are explicitly disallowed to prevent the possibility of
XS-Search attacks on potentially sensitive application data (e.g. text/css, application/json,
application/javascript, etc.).

Issue: Is this valid to say in the HTML spec?

<div algorithm="check if a text directive can be scrolled">
  To <dfn>check if a text directive can be scrolled</dfn>; given a [=/Document=] |document|, an
  [=/origin=]-or-null |initiator origin|, and <a spec=HTML>user navigation involvement</a>-or-null
  |user involvement|, follow these steps:

  <ol class="algorithm">
    1. If |document|'s [=Document/pending text directives=] field is null or empty, return false.
    1. Let |is user involved| be true if: |document|'s [=document/text directive user activation=] is
        true, or |user involvement| is one of "<code>activation</code>" or "<code>browser
        UI</code>"; false otherwise.
    1. Set |document|'s [=document/text directive user activation=] to false.
    1. If |document|'s [=Document/content type=] is not a [=text directive allowing MIME type=],
        return false.
    1. If |user involvement| is "<code>browser UI</code>", return true.
        <div class="note">
          <p>
            If a navigation originates from browser UI, it's always ok to allow it since it'll be
            user triggered and the page/script isn't providing the text snippet.
          </p>
          <p>
            Note: The intent in this item is to distinguish cases where the app/page is able to
            control the URL from those that are fully under the user's control. In the former we
            want to prevent scrolling of the text fragment unless the destination is loaded in a
            separate browsing context group (so that the source cannot both control the text snippet
            and observe side-effects in the navigation). There are some cases where "browser UI" may
            be a grey area in this regard. E.g. an "open in new window" context menu item when right
            clicking on a link.
          </p>
          <p>
            See
            <a href="https://w3c.github.io/webappsec-fetch-metadata/#directly-user-initiated">
            sec-fetch-site</a> in [[FETCH-METADATA]] for a related discussion of how this applies.
          </p>
        </div>
    1. If |is user involved| is false, return false.
    1. If |document|'s [=node navigable=] has a [=navigable/parent=], return false.
    1. If |initiator origin| is non-null and |document|'s [=Document/origin=] is [=same origin=]
        with |initiator origin|, return true.
    1. If |document|'s [=Document/browsing context=]'s [=browsing context/group=]'s
        <a spec=HTML>browsing context set</a> has length 1, return true.
        <div class="note">
          i.e. Only allow navigation from a cross-origin element/script if the
          document is loaded in a noopener context. That is, a new top level
          browsing context group to which the navigator does not have script access
          and which can be placed into a separate process.
        </div>
    1. Otherwise, return false.
  </ol>
</div>

Amend (the already amended, in [[#invoking-text-directives]]) <a spec=HTML>scroll to the
fragment</a> steps to add a new parameter, a boolean |allow text directive scroll|:

> <strong>Monkeypatching [[HTML#scrolling-to-a-fragment]]:</strong>
>
> <div class="monkeypatch">
>   To scroll to the fragment given a Document |document| <span class="diff">and boolean |allow text
>   directive scroll|</span>:
>
>   1. If document's indicated part is null, then set document's target element to null.
>   2. ...
>   3. Otherwise:
>       1. Assert: document's indicated part is an element or it is a [=range=].
>       2. ...
>           <li value="4">If |target| is a [=range=], then:</li>
>           1. <span class="diff">If |allow text directive scroll| is false, return.</span>
>           1. Set |target| to be the [=first common ancestor=] of |target|'s [=range/start node=]
>               and [=range/end node=].
>           1. ...
>
> </div>

Amend the <a spec=HTML>try to scroll to the fragment</a> by adding a boolean flag |allow text
directive scroll| and replacing the steps of the task queued in step 2:

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>  To try to scroll to the fragment for a Document |document|, <span class="diff">with boolean
>  |allow text directive scroll|</span>, perform the following steps in parallel:
>
>   1. Wait for an implementation-defined amount of time. (This is intended to allow the user agent
>       to optimize the user experience in the face of performance concerns.)
>   2. Queue a global task on the navigation and traversal task source given document's relevant
>       global object to run these steps:
>       1. If document has no parser, or its parser has stopped parsing, or the user
>           agent has reason to believe the user is no longer interested in scrolling to
>           the fragment, then abort these steps.
>       2. Scroll to the fragment given |document| <span class="diff">and |allow text directive
>           scroll|.</span>
>       3. If document's indicated part is still null, then try to scroll to the fragment for
>           |document|<span class="diff"> and |allow text directive scroll|</span>.
>
>   </div>

Amend the <a spec=HTML>update document for history step application</a> steps to take a boolean
|allow text directive scroll| and use it when scrolling to a fragment:

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>   To update document for history step application given a Document document, a session history
>   entry entry, a boolean doNotReactivate, integers scriptHistoryLength and scriptHistoryIndex,
>   an optional list of session history entries entriesForNavigationAPI, <span class="diff">and a
>   boolean |allow text directive scroll|</span>:
>
>   1. Let documentIsNew be true if |document|'s latest entry is null; otherwise false.
>   1. ...
>       <li value="5">If documentsEntryChanged is true, then:
>       1. Let oldURL be document's latest entry's URL.
>       2. ...
>   6. If documentIsNew is true, then:
>       1. Try to scroll to the fragment with |document| <span class="diff">and |allow text
>           directive scroll|.</span>
>
> </div>

Amend the <a spec=HTML>apply the history step</a> algorithm to take a boolean |allow text directive
scroll| and pass it through when calling <a spec=HTML>update document for history step application
</a>:

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>
> To apply the history step given a non-negative integer step to a traversable navigable
> traversable, with boolean checkForCancelation, source snapshot params-or-null
> sourceSnapshotParams, navigable-or-null initiatorToCheck, user navigation involvement-or-null
> userInvolvementForNavigateEvents, <span class="diff">and boolean |allow text directive scroll|
> (default false)</span> perform the following steps. They
> return "initiator-disallowed", "canceled-by-beforeunload", "canceled-by-navigate", or "applied".
>
> 14. While completedChangeJobs does not equal totalChangeJobs:
>     1. ...
>         <li value="11">Queue a global task on the navigation and traversal task source given
>         navigable's active window to run the steps:
>             1. If changingNavigableContinuation's update-only is false, then:
>                 1. ...
>                 2. Activate history entry |targetEntry| for navigable.
>             2. Let updateDocument be an algorithm step which performs update document for history
>                 step application given |targetEntry|'s document, |targetEntry|,
>                 changingNavigableContinuation's update-only, scriptHistoryLength,
>                 scriptHistoryIndex, entriesForNavigationAPI, <span class="diff">and |allow text
>                 directive scroll|</span>
>             3. If |targetEntry|'s document is equal to displayedDocument, then perform
>                 updateDocument.
> 15. Let totalNonchangingJobs be the size of nonchangingNavigablesThatStillNeedUpdates.
>
> </div>

Amend the <a spec=HTML>apply the push/replace history step</a> to take and pass |allow text
directive scrolling| to apply the history step:

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>  To apply the push/replace history step given a non-negative integer |step| to a traversable
>  navigable |traversable|, <span class="diff">with boolean |allow text directive scroll| (default
>  false)</span>:
>
>  Return the result of applying the history step |step| to |traversable| given false, null, null,
>  null, <span class="diff">|allow text directive scroll|</span>.
> </div>

Note: The |allow text directive scroll| is intentionally not set for traversal and reload cases.
This avoids extensive plumbing and checks for initiator origin and user involvement and history
scroll state should take precedence anyway. The text directive may still be used as the indicated
part of the document so highlights will be restored.

Amend the <a spec=HTML>finalize a cross-document navigation</a> to take a |user involvement|
parameter and compute and pass |allow text directive scrolling| to apply the push/replace history
step:

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>
> To finalize a cross-document navigation given a navigable navigable, history handling behavior
> historyHandling, session history entry historyEntry, <span class="diff"> and <a spec=HTML>user
> navigation involvement</a> |user involvement| (default "none")</span>:
>
> 1. Assert: this is running on navigable's traversable navigable's session history traversal queue.
> 2. ...
>     <li value="10"><span class="diff">Let |allow text directive scroll| be the result of [=check if a text
>     directive can be scrolled|checking if a text directive can be scrolled=], given
>     |historyEntry|'s [=she/document=], |historyEntry|'s <a spec=HTML>document state</a>'s
>     [=document state/initiator origin=], and |user involvement|</span>
> 11. Apply the push/replace history step targetStep to traversable, <span class="diff">with |allow
>     text directive scroll|.</span>

Amend the <a spec=HTML>navigate</a> algorithm to pass |user involvement| to the finalize a
cross-document navigation steps:

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>
> 1. ...
>     <li value="20">. In parallel, run these steps:</li>
>     1. ...
>         <li value="9">. Attempt to populate the history entry's document for historyEntry, given
>         navigable, "navigate", sourceSnapshotParams, targetSnapshotParams, navigationId,
>         navigationParams, cspNavigationType, with allowPOST set to true and completionSteps set to
>         the following step:</li>
>         1. Append session history traversal steps to navigable's traversable to finalize a
>             cross-document navigation given navigable, historyHandling, historyEntry,
>             <span class="diff">and |userInvolvement|</span>.

Amend the <a spec=HTML>Navigate to a fragment</a> algorithm to take an |initiator origin| parameter
and pass the |allow text directive scroll| flag when scrolling to the fragment:

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>
> To navigate to a fragment given a navigable navigable, a URL url, a history handling behavior
> historyHandling, a user navigation involvement |userInvolvement|, a serialized state-or-null
> navigationAPIState, navigation ID navigationId, <span class="diff">an [=/origin=] |initiator
> origin|</span>:
>
> 1. Let navigation be |navigable|'s active window's navigation API.
> 2. ...
>     <li value="14"> Update document for history step application given navigable's active document, historyEntry, true, scriptHistoryIndex, and scriptHistoryLength.
> 15. Update the navigation API entries for a same-document navigation given navigation, historyEntry, and historyHandling.
> 16. <span class="diff">Let |allow text directive scroll| be the result of [=check if a text
>     directive can be scrolled|checking if a text directive can be scrolled=], given
>     |navigable|'s [=active document=], |initiator origin|, and |userInvolvement|</span>
> 17. Scroll to the fragment given |navigable|'s active document<span class="diff">, and |allow text
>     directive scroll|.</span>
>
> </div>

Amend the <a spec=HTML>navigate</a> algorithm to pass the initiator origin when performing a
fragment navigation:

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>
> 10. If the navigation must be a replace given url and navigable's active document, then set historyHandling to "replace".
> 11. If all of the following are true:
>     * documentResource is null;
>     * response is null;
>     * url equals navigable's active session history entry's URL with exclude fragments set to true; and
>     * url's fragment is non-null,
>
>     then:
>
>     1. Navigate to a fragment given navigable, url, historyHandling, userInvolvement,
>         navigationAPIState, navigationId, <span class="diff">and <var ignore>
>         initiatorOriginSnapshot</var></span>
>     1. Let navigation be |navigable|'s active window's navigation API.
>
> </div>

### Restricting Scroll on Load ### {#restricting-scroll-on-load}

This section defines how the `force-load-at-top` policy is used to prevent all
types of scrolling when loading a new document, including but not limited to
text directives.

ISSUE(WICG/scroll-to-text-fragment#242): Need to decide how `force-load-at-top`
interacts with the Navigation API.

Amend the <a spec=HTML>restore persisted state</a> steps to take a new boolean
parameter which suppresses scroll restoration:

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>   To restore persisted state from a session history entry <var ignore>entry</var>
>   <span class="diff">, and boolean |suppressScrolling|</span>:
>
>  1. If entry's scroll restoration mode is "auto", <span class="diff">|suppressScrolling|
>     is false,</span> and entry's document's relevant global object's navigation API's suppress
>     normal scroll restoration during ongoing navigation is false, then restore scroll position
>     data given entry.
>  2. ...


Amend the <a spec=HTML>update document for history step application</a> steps
to check the `force-load-at-top` policy and avoid scrolling in a new document
if it's set.

> <strong>Monkeypatching [[HTML]]:</strong>
>
> <div class="monkeypatch">
>   1. ...
>       <li value="4">Set document's history object's length to scriptHistoryLength.</li>
>   5. <span class="diff">Let |scrollingBlockedInNewDocument| be the result of
>       <a href="https://wicg.github.io/document-policy#algo-get-policy-value">getting the policy
>       value</a> for `force-load-at-top` for |document|.</span>
>   5. If documentsEntryChanged is true, then:
>       1. Let oldURL be document's latest entry's URL.
>       2. ...
>           <li value="5"> If documentIsNew is false, then:
>           1. Update the navigation API entries for a same-document navigation given navigation,
>               entry, and "traverse".
>           2. Fire an event named popstate...
>           3. Restore persisted state given entry <span class="diff">and
>               |suppressScrolling| set to false.</span>
>           4. If oldURL's fragment is not equal to...
>       6. Otherwise,
>           1. Assert: entriesForNavigationAPI is given.
>           2. Restore persisted state given entry <span class="diff">and
>               |scrollingBlockedInNewDocument|.</span>
>           3. Initialize the navigation API entries for a new document given navigation,
>               entriesForNavigationAPI, and entry.
>   6. If documentIsNew is true, then:
>       1. <span class="diff">If |scrollingBlockedInNewDocument| is false,</span> try to scroll to
>           the fragment for document.
>       2. At this point scripts may run for the newly-created document document.
>   7. Otherwise, if documentsEntryChanged is false and doNotReactivate is false, then:
>       1. ...
>
> </div>

## Navigating to a Text Fragment ## {#navigating-to-text-fragment}

<div class="note">
The text fragment specification proposes an amendment to
[[html#scroll-to-fragid]]. In summary, if a [=text directive=] is
present and a match is found in the page, the text fragment takes precedent over
the element fragment as the indicated part. We amend the HTML Document's
indicated part processing model to return a [=range=], rather than an
[=element=], that will be scrolled into view.
</div>

<div algorithm="first common ancestor">
To find the <dfn>first common ancestor</dfn> of two nodes |nodeA| and |nodeB|,
follow these steps:


  <ol class="algorithm">
    1. Let |commonAncestor| be |nodeA|.
    1. While |commonAncestor| is non-null and is not a [=shadow-including inclusive
        ancestor=] of |nodeB|, let |commonAncestor| be |commonAncestor|’s
        [=shadow-including parent=].
    1. Return |commonAncestor|.
  </ol>
</div>

<div algorithm="shadow-including parent">
To find the <dfn>shadow-including parent</dfn> of |node| follow these steps:

  <ol class="algorithm">
    1. If |node| is a [=/shadow root=], return |node|'s [=DocumentFragment/host=].
    1. Otherwise, return |node|'s [=tree/parent=].
  </ol>
</div>

### Finding Ranges in a Document ### {#finding-ranges-in-a-document}

<div class="note">
  This section outlines several algorithms and definitions that specify how to
  turn a full fragment directive string into a list of [=Ranges=] in the
  document.

  At a high level, we take a fragment directive string that looks like this:
  <pre>
    text=prefix-,foo&unknown&text=bar,baz
  </pre>

  We break this up into the individual text directives:

  <pre>
    text=prefix-,foo
    text=bar,baz
  </pre>

  For each text directive, we perform a search in the document for the first
  instance of rendered text that matches the restrictions in the directive.
  Each search is independent of any others; that is, the result is the same
  regardless of how many other directives are provided or their match result.

  If a directive successfully matches to text in the document, it returns a
  [=range=] indicating that match in the document. The
  [=invoke text directives=] steps are the high level API provided by this
  section. These return a <a spec=infra>list</a> of [=ranges=] that were matched
  by the individual directive matching steps, in the order the directives were
  specified in the fragment directive string.

  If a directive was not matched, it does not add an item to the returned
  list.
</div>

<div algorithm="invoke text directives">
  To <dfn>invoke text directives</dfn>, given as input a <a spec=infra>list</a> of [=text
  directives=] |text directives| and a [=/Document=] |document|, run these steps:

  <div class="note">
    This algorithm returns a <a spec=infra>list</a> of [=ranges=] that are to be visually indicated,
    the first of which will be scrolled into view (if the UA scrolls automatically).
  </div>

  <ol class="algorithm">
    1. Let |ranges| be a <a spec=infra>list</a> of [=ranges=], initially empty.
    1. <a spec=infra for=list>For each</a> [=text directive=] |directive| of |text directives|:
        1. If the result of running [=find a range from a text directive=] given |directive| and
            |document| is non-null, then [=list/append=] it to |ranges|.
    1. Return |ranges|.
  </ol>
</div>

<div algorithm="find a range from a text directive">
To <dfn>find a range from a text directive</dfn>, given a
[=text directive=] |parsedValues| and [=/Document=] |document|, run the
following steps:

<div class="note">
  This algorithm takes as input a successfully parsed text directive and a
  document in which to search. It returns a [=range=] that points to the first
  text passage within the document that matches the searched-for text and
  satisfies the surrounding context. Returns null if no such passage exists.

  [=text directive/end=] can be null. If omitted, this is an "exact"
  search and the returned [=range=] will contain a string exactly matching
  [=text directive/start=]. If [=text directive/end=] is
  provided, this is a "range" search; the returned [=range=] will start with
  [=text directive/start=] and end with
  [=text directive/end=]. In the normative text below, we'll call a
  text passage that matches the provided [=text directive/start=] and
  [=text directive/end=], regardless of which mode we're in, the
  "matching text".

  Either or both of [=text directive/prefix=] and
  [=text directive/suffix=] can be null, in which case context on that
  side of a match is not checked. E.g. If [=text directive/prefix=] is
  null, text is matched without any requirement on what text precedes it.
</div>
<div class="note">
  While the matching text and its prefix/suffix can span across
  block-boundaries, the individual parameters to these steps cannot. That is,
  each of [=text directive/prefix=], [=text directive/start=],
  [=text directive/end=], and [=text directive/suffix=] will only
  match text within a single block.

  <div class="example">
    <pre>:~:text=The quick,lazy dog</pre> will fail to match in

    ```
    <div>The<div> </div>quick brown fox</div>
    <div>jumped over the lazy dog</div>
    ```

    because the starting string "The quick" does not appear within a single,
    uninterrupted block. The instance of "The quick" in the document has a
    block element between "The" and "quick".

    It does, however, match in this example:

    ```
    <div>The quick brown fox</div>
    <div>jumped over the lazy dog</div>
    ```

  </div>
</div>
  <ol class="algorithm">
    1. Let |searchRange| be a [=range=] with [=range/start=] (|document|, 0) and
        [=range/end=] (|document|, |document|'s [=Node/length=])
    1. While |searchRange| is not [=range/collapsed=]:
        1. Let |potentialMatch| be null.
        1. If |parsedValues|'s [=text directive/prefix=] is not null:
            1. Let |prefixMatch| be the the result of running the [=find a string
                in range=] steps with |query| |parsedValues|'s
                [=text directive/prefix=], |searchRange| |searchRange|,
                |wordStartBounded| true and |wordEndBounded| false.
            1. If |prefixMatch| is null, return null.
            1. Set |searchRange|'s [=range/start=] to the first [=/boundary point=]
                [=boundary point/after=] |prefixMatch|'s [=range/start=]
            1. Let |matchRange| be a [=range=] whose [=range/start=] is
                |prefixMatch|'s [=range/end=] and [=range/end=] is |searchRange|'s
                [=range/end=].
            1. Advance |matchRange|'s [=range/start=] to the
                [=next non-whitespace position=].
            1. If |matchRange| is [=range/collapsed=] return null.
                <div class="note">
                  This can happen if |prefixMatch|'s [=range/end=] or its subsequent
                  non-whitespace position is at the end of the document.
                </div>
            1. [=/Assert=]: |matchRange|'s [=range/start node=] is a {{Text}} node.
                <div class="note">
                  |matchRange|'s [=range/start=] now points to the next
                  non-whitespace text data following a matched prefix.
                </div>
            1. Let |mustEndAtWordBoundary| be true if |parsedValues|'s
                [=text directive/end=] is non-null or
                |parsedValues|'s [=text directive/suffix=] is null, false
                otherwise.
            1. Set |potentialMatch| to the result of running the [=find a string in
                range=] steps with |query| |parsedValues|'s
                [=text directive/start=], |searchRange| |matchRange|,
                |wordStartBounded| false, and |wordEndBounded|
                |mustEndAtWordBoundary|.
            1. If |potentialMatch| is null, return null.
            1. If |potentialMatch|'s [=range/start=] is not |matchRange|'s
                [=range/start=], then [=iteration/continue=].
                <div class="note">
                  In this case, we found a prefix but it was followed by something
                  other than a matching text so we'll continue searching for the
                  next instance of [=text directive/prefix=].
                </div>
        1. Otherwise:
            1. Let |mustEndAtWordBoundary| be true if |parsedValues|'s
                [=text directive/end=] is non-null or
                |parsedValues|'s [=text directive/suffix=] is null, false
                otherwise.
            1. Set |potentialMatch| to the result of running the [=find a string in
                range=] steps with |query| |parsedValues|'s
                [=text directive/start=], |searchRange| |searchRange|,
                |wordStartBounded| true, and |wordEndBounded|
                |mustEndAtWordBoundary|.
            1. If |potentialMatch| is null, return null.
            1. Set |searchRange|'s [=range/start=] to the first [=/boundary point=]
                [=boundary point/after=] |potentialMatch|'s [=range/start=]
        1. Let |rangeEndSearchRange| be a [=range=] whose [=range/start=] is
            |potentialMatch|'s [=range/end=] and whose [=range/end=] is
            |searchRange|'s [=range/end=].
        1. While |rangeEndSearchRange| is not [=range/collapsed=]:
            1. If |parsedValues|'s [=text directive/end=] item is
                non-null, then:
                1. Let |mustEndAtWordBoundary| be true if |parsedValues|'s
                    [=text directive/suffix=] is null, false otherwise.
                1. Let |endMatch| be the result of running the [=find a string
                    in range=] steps with |query| |parsedValues|'s
                    [=text directive/end=], |searchRange| |rangeEndSearchRange|,
                    |wordStartBounded| true, and |wordEndBounded|
                    |mustEndAtWordBoundary|.
                1. If |endMatch| is null then return null.
                1. Set |potentialMatch|'s [=range/end=] to |endMatch|'s
                    [=range/end=].
            1. [=/Assert=]: |potentialMatch| is non-null, not [=range/collapsed=] and
                represents a range exactly containing an instance of matching text.
            1. If |parsedValues|'s [=text directive/suffix=] is null, return
                |potentialMatch|.
            1. Let |suffixRange| be a [=range=] with [=range/start=] equal to
                |potentialMatch|'s [=range/end=] and [=range/end=] equal to
                |searchRange|'s [=range/end=].
            1. Advance |suffixRange|'s [=range/start=] to the [=next non-whitespace
                position=].
            1. Let |suffixMatch| be result of running the [=find a string in range=]
                steps with |query| |parsedValues|'s [=text directive/suffix=],
                |searchRange| |suffixRange|, |wordStartBounded| false, and
                |wordEndBounded| true.
            1. If |suffixMatch| is null then return null.
                <div class="note">
                  If the suffix doesn't appear in the remaining text of the document,
                  there's no possible way to make a match.
                </div>
            1. If |suffixMatch|'s [=range/start=] is |suffixRange|'s [=range/start=],
                return |potentialMatch|.
            1. If |parsedValues|'s [=text directive/end=] item is null
                then [=iteration/break=];
                <div class="note">
                  If this is an exact match and the suffix doesn't match,
                  start searching for the next range start by breaking out
                  of this loop without |rangeEndSearchRange| being collapsed.
                  If we're looking for a range match, we'll continue iterating
                  this inner loop since the range start will already be correct.
                </div>
            1. Set |rangeEndSearchRange|'s [=range/start=] to |potentialMatch|'s
                [=range/end=].
                <div class="note">
                  Otherwise, it is possible that we found the correct range
                  start, but not the correct range end. Continue the inner
                  loop to keep searching for another matching instance of
                  rangeEnd.
                </div>
        1. If |rangeEndSearchRange| is [=range/collapsed=] then:
            1. [=/Assert=]: |parsedValues|'s [=text directive/end=] item is non-null
            1. Return null
                <div class="note">
                    This can only happen for range matches due to the
                    [=iteration/break=] for exact matches in step 9 of the
                    above loop. If we couldn't find a valid rangeEnd+suffix
                    pair anywhere in the doc then there's no possible way to
                    make a match.
                </div>
    1. Return null
  </ol>

</div>

<wpt>
  /scroll-to-text-fragment/find-range-from-text-directive.html
</wpt>

<div algorithm="advance range start to next non-whitespace position">
To advance a [=range=] |range|'s [=range/start=] to the <dfn>next
non-whitespace position</dfn> follow the steps:

  <ol class="algorithm">
    1. While |range| is not collapsed:
        1. Let |node| be |range|'s [=range/start node=].
        1. Let |offset| be |range|'s [=range/start offset=].
        1. If |node| is part of a [=non-searchable subtree=] or if |node| is
            not a [=visible text node=] or if |offset| is equal to |node|'s [=Node/length=] then:
            1. Set |range|'s [=range/start node=] to the next node, in [=shadow-including tree order=].
            1. Set |range|'s [=range/start offset=] to 0.
            1. [=iteration/Continue=].
        1. If the [=Text/substring data=] of |node| at offset |offset|
            and count 6 is equal to the string "&amp;nbsp;" then:
            1. Add 6 to |range|'s [=range/start offset=].
        1. Otherwise, if the [=Text/substring data=] of |node| at offset |offset|
            and count 5 is equal to the string "&amp;nbsp" then:
            1. Add 5 to |range|'s [=range/start offset=].
        1. Otherwise:
            1. Let |cp| be the [=code point=] at the |offset| index in |node|'s
                [=CharacterData/data=].
            1. If |cp| does not have the <a
                href="http://www.unicode.org/reports/tr44/#White_Space">White_Space</a>
                property set, return.
            1. Add 1 to |range|'s [=range/start offset=].
  </ol>
</div>

<div algorithm="find a string in a range">
To <dfn>find a string in range</dfn> given a <a spec=infra>string</a> |query|, a
[=range=] |searchRange|, and booleans |wordStartBounded| and |wordEndBounded|,
run these steps:

<div class="note">
  This algorithm will return a [=range=] that represents the first instance of
  the |query| text that is fully contained within |searchRange|, optionally
  restricting itself to matches that start and/or end at word boundaries (see
  [[#word-boundaries]]). Returns null if none is found.
</div>

<div class="note">
  <p>
    The basic premise of this algorithm is to walk all searchable text nodes
    within a block, collecting them into a list. The list is then concatenated
    into a single string in which we can search, using the node list to
    determine offsets with a node so we can return a [=range=].
  </p>

  <p>
    Collection breaks when we hit a block node, e.g. searching over this tree:

    ```
      <div>
        a<em>b</em>c<div>d</div>e
      </div>
    ```
  </p>

  Will perform a search on "abc", then on "d", then on "e".

  Thus, |query| will only match text that is continuous (i.e. uninterrupted by
  a block-level container) within a single block-level container.
</div>

  <ol class="algorithm">
    1. While |searchRange| is not [=range/collapsed=]:
        1. Let |curNode| be |searchRange|'s [=range/start node=].
        1. If |curNode| is part of a [=non-searchable subtree=]:
            1. Set |searchRange|'s [=range/start node=] to the next node, in
                [=shadow-including tree order=], that isn't a [=shadow-including
                descendant=] of |curNode|.
            1. Set |searchRange|'s [=range/start offset=] to 0.
            1. [=iteration/Continue=].
        1. If |curNode| is not a [=visible text node=]:
            1. Set |searchRange|'s [=range/start node=] to the next node, in
                [=shadow-including tree order=], that is not a [=doctype=].
            1. Set |searchRange|'s [=range/start offset=] to 0.
            1. [=iteration/Continue=].
        1. Let |blockAncestor| be the [=nearest block ancestor=] of |curNode|.
        1. Let |textNodeList| be a <a spec=infra>list</a> of {{Text}} nodes,
            initially empty.
        1. While |curNode| is a [=shadow-including descendant=] of |blockAncestor|
            and the position of the [=/boundary point=] (|curNode|, 0) is not
            [=boundary point/after=] |searchRange|'s [=range/end=]:
            1. If |curNode| [=has block-level display=] then [=iteration/break=].
            1. If |curNode| is [=search invisible=]:
                1. Set |curNode| to the next node, in [=shadow-including tree
                    order=], that isn't a [=shadow-including descendant=] of
                    |curNode|.
                2. [=iteration/Continue=].
            1. If |curNode| is a [=visible text node=] then append it to
                |textNodeList|.
            1. Set |curNode| to the next node in [=shadow-including tree order=].
        1. Run the [=find a range from a node list=] steps given |query|,
            |searchRange|, |textNodeList|, |wordStartBounded| and |wordEndBounded|
            as input. If the resulting [=range=] is not null, then return it.
        1. If |curNode| is null, then [=iteration/break=].
        1. [=/Assert=]: |curNode| [=tree/following|follows=] |searchRange|'s
            [=range/start node=].
        1. Set |searchRange|'s [=range/start=] to the [=/boundary point=] (|curNode|,
            0).
    1. Return null.
  </ol>
</div>

A node is <dfn>search invisible</dfn> if it is an [=element=] in the [=HTML
namespace=] and meets any of the following conditions:
1. The [=computed value=] of its 'display' property is ''display/none''.
1. If the node <a spec=html>serializes as void</a>.
1. Is any of the following types: {{HTMLIFrameElement}}, {{HTMLImageElement}},
    {{HTMLMeterElement}}, {{HTMLObjectElement}}, {{HTMLProgressElement}},
    {{HTMLStyleElement}}, {{HTMLScriptElement}}, {{HTMLVideoElement}},
    {{HTMLAudioElement}}
1. Is a <{select}> element whose <{select/multiple}> content attribute is absent.

A node is part of a <dfn>non-searchable subtree</dfn> if it is or has a
[=shadow-including ancestor=] that is [=search invisible=].

A node is a <dfn>visible text node</dfn> if it is a {{Text}} node, the
[=computed value=] of its [=parent element=]'s 'visibility' property is
''visibility/visible'', and it is <a spec=html>being rendered</a>.

A node <dfn>has block-level display</dfn> if it is an [=element=] and the [=computed value=] of its
'display' property is any of ''display/block'', ''display/table'',
''display/flow-root'', ''display/grid'', ''display/flex'',
''display/list-item''.

<div algorithm="nearest block ancestor">
To find the <dfn>nearest block ancestor</dfn> of a |node| follow the steps:
  <ol class="algorithm">
    1. Let |curNode| be |node|.
    1. While |curNode| is non-null
        1. If |curNode| is not a {{Text}} node and it [=has block-level display=] then
            return |curNode|.
        1. Otherwise, set |curNode| to |curNode|'s [=tree/parent=].
    1. Return |node|'s [=Node/node document=]'s [=document element=].
  </ol>
</div>

<div algorithm="range from node list">
To <dfn>find a range from a node list</dfn> given a search string |queryString|,
a [=range=] |searchRange|, a [=/list=] of {{Text}} nodes |nodes|, and booleans
|wordStartBounded| and |wordEndBounded|, follow these steps:

<div class="note">
  Optionally, this will only return a match if the matched text begins and/or
  ends on a [=word boundary=]. For example:

  <div class="example">
    The query string “range” will always match in “mountain range”, but
    1. When requiring a word boundary at the beginning, it will not match in “color orange”.
    2. When requiring a word boundary at the end, it will not match in “forest ranger”.
  </div>

  See [[#word-boundaries]] for details and more examples.
</div>

  <ol class="algorithm">
    1. Let |searchBuffer| be the [=string/concatenate|concatenation=] of the
        [=CharacterData/data=] of each item in |nodes|.

        ISSUE(WICG/scroll-to-text-fragment#98): [=CharacterData/data=] is not
        correct here since that's the text data as it exists in the DOM. This
        algorithm means to run over the text as rendered (and then convert back
        to Ranges in the DOM).
    1. Let |searchStart| be 0.
    1. If the first item in |nodes| is |searchRange|'s [=range/start node=] then
        set |searchStart| to |searchRange|'s [=range/start offset=].
    1. Let |start| and |end| be [=/boundary points=], initially null.
    1. Let |matchIndex| be null.
    1. While |matchIndex| is null
        1. Set |matchIndex| to the index of the first instance of |queryString| in
            |searchBuffer|, starting at |searchStart|. The string search must be
            performed using a base character comparison, or the
            <a href="http://www.unicode.org/reports/tr10/#Multi_Level_Comparison">primary
            level</a>, as defined in [[!UTS10]].
            <div class="note">
              Intuitively, this is a case-insensitive search also ignoring accents, umlauts,
              and other marks.
            </div>
        1. If |matchIndex| is null, return null.
        1. Let |endIx| be |matchIndex| + |queryString|'s [=string/length=].
            <div class="note">
               |endIx| is the index of the last character in the match + 1.
            </div>
        1. Set |start| to the [=/boundary point=] result of [=get boundary point at
            index=] |matchIndex| run over |nodes| with |isEnd| false.
        1. Set |end| to the [=/boundary point=] result of [=get boundary point at
            index=] |endIx| run over |nodes| with |isEnd| true.
        1. If |wordStartBounded| is true and |matchIndex| [=is at a word boundary|is
            not at a word boundary=] in |searchBuffer|, given the <a
            spec=html>language</a> from |start|'s [=boundary point/node=] as the
            |locale|; or |wordEndBounded| is true and |matchIndex| + |queryString|'s
            [=string/length=] [=is at a word boundary|is not at a word boundary=] in
            |searchBuffer|, given the <a spec=html>language</a> from |end|'s
            [=boundary point/node=] as the |locale|:
            1. Set |searchStart| to |matchIndex| + 1.
            1. Set |matchIndex| to null.
    1. Let |endInset| be 0.
    1. If the last item in |nodes| is |searchRange|'s [=range/end node=] then set
        |endInset| to (|searchRange|'s [=range/end node=]'s [=Node/length=] &minus;
        |searchRange|'s [=range/end offset=])
        <div class="note">
          |endInset| is the offset from the last position in the last node in the
          reverse direction. Alternatively, it is the length of the node that's not
          included in the range.
        </div>
    1. If |matchIndex| + |queryString|'s [=string/length=] is greater than
        |searchBuffer|'s length &minus; |endInset| return null.
        <div class="note">
          If the match runs past the end of the search range, return null.
        </div>
    1. [=/Assert=]: |start| and |end| are non-null, valid [=/boundary points=] in
        |searchRange|.
    1. Return a [=range=] with [=range/start=] |start| and [=range/end=] |end|.
  </ol>
</div>

<div algorithm="boundary point at index">
To <dfn>get boundary point at index</dfn>, given an integer |index|, [=/list=]
of {{Text}} nodes |nodes|, and a boolean |isEnd|, follow these steps:

<div class="note">
  <p>
    This is a small helper routine used by the steps above to determine which
    node a given index in the concatenated string belongs to.
  </p>
  <p>
    |isEnd| is used to differentiate start and end indices. An end index points
    to the "one-past-last" character of the matching string. If the match ends
    at node boundary, we want the end offset to remain within that node, rather
    than the start of the next node.
  </p>
</div>

  <ol class="algorithm">
    1. Let |counted| be 0.
    1. For each |curNode| of |nodes|:
        1. Let |nodeEnd| be |counted| + |curNode|'s [=Node/length=].
        1. If |isEnd| is true, add 1 to |nodeEnd|.
        1. If |nodeEnd| is greater than |index| then:
            1. Return the [=/boundary point=] (|curNode|, |index| &minus; |counted|).
        1. Increment |counted| by |curNode|'s [=Node/length=].
    1. Return null.
  </ol>
</div>

### Word Boundaries ### {#word-boundaries}
<div class="note">
  Limiting matching to word boundaries is one of the mitigations to limit
  cross-origin information leakage.
</div>
<div class="note">
  See <a
  href="https://github.com/tc39/proposal-intl-segmenter">Intl.Segmenter</a>, a
  proposal to specify unicode segmentation, including word segmentation. Once
  specified, this algorithm can be improved by making use of the Intl.Segmenter
  API for word boundary matching.
</div>

<p>
  A <dfn>word boundary</dfn> is defined in [[!UAX29]] in
  [[UAX29#Word_Boundaries]]. [[UAX29#Default_Word_Boundaries]] defines a
  default set of what constitutes a word boundary, but as the specification
  mentions, a more sophisticated algorithm should be used based on the locale.
</p>
<p>
  Dictionary-based word bounding should take specific care in locales without a
  word-separating character. E.g. In English, words are separated by the space
  character (' '); however, in Japanese there is no character that separates one
  word from the next. In such cases, and where the alphabet contains fewer
  than 100 characters, the dictionary must not contain more than 20% of the
  alphabet as valid, one-letter words.
</p>

A <dfn>locale</dfn> is a <a spec=infra>string</a> containing a valid [[BCP47]]
language tag, or the empty string. An empty string indicates that the primary
language is unknown.

A substring is <dfn>word bounded</dfn> in a <a spec=infra>string</a> |text|,
given [=locales=] |startLocale| and |endLocale|, if both the position of its
first character [=is at a word boundary=] given |startLocale|, and the position
after its last character [=is at a word boundary=] given |endLocale|.

A number |position| <dfn>is at a word boundary</dfn> in a <a spec=infra>string</a>
|text|, given a [=locale=] |locale|, if, using |locale|, either a [=word
boundary=] immediately precedes the |position|th code unit, or |text|'s length
is more than 0 and |position| equals either 0 or |text|'s length.

<div class="note">
  Intuitively, a substring is [=word bounded=] if it neither begins nor ends in
  the middle of a word.

  In languages with a word separator (e.g. " " space) this is (mostly)
  straightforward; though there are details covered by the above technical
  reports such as new lines, hyphenations, quotes, etc.

  Some languages do not have such a separator (notably,
  Chinese/Japanese/Korean). Languages such as these requires dictionaries to
  determine what a valid word in the given locale is.
</div>

<div class="example">
  <p>
    Text fragments are restricted such that match terms, when combined with
    their adjacent context terms, are word bounded. For example, in an
    exact search like <code>prefix,start,suffix</code>,
    <code>"prefix+start+suffix"</code> will match only if the entire result is word bounded. However, in a
    range search like <code>prefix,start,end,suffix</code>, a match is
    found only if both
    <code>"prefix+start"</code> and <code>"end+suffix"</code> are
    word bounded.
  </p>

  <p>
    The goal is that a third-party must already know the full tokens they are
    matching against. A range match like <code>start,end</code> must be
    word bounded on the inside of the two terms; otherwise a third party could
    use this repeatedly to try and reveal a token (e.g. on a page with
    <code>"Balance: 123,456 $"</code>, a third-party could set
    <code>prefix="Balance: ", end="$"</code> and vary <code>start</code>
    to try and guess the numeric token one digit at a time).
  </p>

  <p>
    For more details, refer to the [Security Review Doc](https://docs.google.com/document/d/1YHcl1-vE_ZnZ0kL2almeikAj2gkwCq8_5xwIae7PVik/edit#heading=h.78iny7nejmx2)
  </p>
</div>

<div class="example">
  The substring "mountain range" is word bounded within the string "An impressive
  mountain range" but not within "An impressive mountain ranger".
</div>

<div class="example">
  In the Japanese string "<span lang="ja">ウィキペディアへようこそ</span>" (Welcome to Wikipedia),
  "<span lang="ja">ようこそ</span>" (Welcome) is considered word-bounded but "<span lang="ja">ようこ</span>" is not.
</div>

## Indicating The Text Match ## {#indicating-the-text-match}

The UA may choose to scroll the text fragment into view as part of the <a
spec=HTML>try to scroll to the fragment</a> steps or by some other mechanism;
however, it is not required to scroll the match into view.

The UA should visually indicate the matched text in some way such that the user
is made aware of the text match, such as with a high-contrast highlight.

The UA should provide to the user some method of dismissing the match, such
that the matched text no longer appears visually indicated.

The exact appearance and mechanics of the indication are left as UA-defined.
However, the UA must not use any methods observable by author script, such as
the Document's <a href="https://w3c.github.io/selection-api/#dfn-selection">
selection</a>, to indicate the text match. Doing so could allow attack vectors
for content exfiltration.

The UA must not visually indicate any provided context terms.

Since the indicator is not part of the document's content, UAs should consider
ways to differentiate it from the page's content as perceived by the user.

<div class="example">
  The UA could provide an in-product help prompt the first few times the
  indicator appears to help train the user that it comes from the linking page
  and is provided by the UA.
</div>

### URLs in UA features ### {#urls-in-ua-features}

UAs provide a number of consumers for a document's URL (outside of programmatic
APIs like <code>window.location</code>). Examples include a location bar
indicating the URL of the currently visible document, or the URL used when a
user requests to create a bookmark for the current page.

To avoid user confusion, UAs should be consistent in whether such URLs include
the [=/fragment directive=]. This section provides a default set of
recommendations for how UAs can handle these cases.

<div class='note'>
  <p>
  We provide these as a baseline for consistent behavior; however, as these
  features don't affect cross-UA interoperability, they are not strict
  conformance requirements.
  </p>

  <p>
  Exact behavior is left up to the implementing UA which can have differing
  constraints or reasons for modifying the behavior. e.g. UAs can allow users
  to configure defaults or expose UI options so users can choose whether they
  prefer to include fragment directives in these URLs.

  It's also useful to allow UAs to experiment with providing a better
  experience. E.g. perhaps the UA's displayed URL can elide the text fragment if
  the user scrolls it out of view?
  </p>
</div>

The general principle is that a URL should include the [=/fragment directive=]
only while the visual indicator is visible (i.e. not dismissed). If the user
dismisses the indicator, the URL should reflect that by also removing the the
[=/fragment directive=].

If the URL includes a text fragment but a match wasn't found in the current
page, the UA may choose to omit it from the exposed URL.

<div class='note'>
  <p>
  A text fragment that isn't found on the page can be useful information to
  surface to a user to indicate that the page has changed since the link
  was created.
  </p>

  <p>
  However, it's unlikely to be useful to the user in a bookmark.
  </p>
</div>

A few common examples are provided below.

<div class='note'>
  We use "text fragment" and "fragment directive" interchangeably here as text
  fragments are assumed to be the only kind of directive. If additional
  directives are added in the future, the UX in these cases will have to be
  re-evaluated separately for new directive types.
</div>

#### Location Bar #### {#urls-in-location-bar}

The location bar's URL should include a text fragment while it is visually
indicated. The [=/fragment directive=] should be stripped from the location bar
URL when the user dismisses the indication.

It is recommended that the text fragment be displayed in the location bar's URL
even if a match wasn't located in the document.

#### Bookmarks #### {#urls-in-bookmarks}

Many UAs provide a "bookmark" feature allowing users to store a convenient link
to the current page in the UA's interface.

A newly created bookmark should, by default, include the [=/fragment directive=]
in the URL if, and only if, a match was found and the visual indicator hasn't
been dismissed.

Navigating to a URL from a bookmark should process a [=/fragment directive=] as
if it were navigated to in a typical navigation.

#### Sharing #### {#urls-in-sharing}

Some UAs provide a method for users to share the current page with others,
typically by providing the URL to another app or messaging service.

When providing a URL in these situations, it should include the [=/fragment
directive=] if, and only if, a match was found and the visual indicator hasn't
been dismissed.

## Document Policy Integration ## {#document-policy-integration}

<!-- TODO:Replace manual links with autolinks to document-policy definitions
          once it's referrable.  Also remember to autolink the ref in the
          navigating-to-text-fragment section -->

This specification defines a <a href="https://wicg.github.io/document-policy#configuration-point">configuration point</a>
in [[!document-policy|Document Policy]] with name "force-load-at-top". Its
<a href="https://wicg.github.io/document-policy#configuration-point-type">type</a> is `boolean`
with <a href="https://wicg.github.io/document-policy#configuration-point-default-value">default value</a>
`false`.

<div class="note">
  When enabled, this policy disables all automatic scroll-on-load features:
  text-fragments, element fragments, history scroll restoration.
</div>
<div class='example'>
  Suppose the user navigates to `https://example.com#:~:text=foo`. The
  example.com server response includes the header:

  ```
  Document-Policy: force-load-at-top
  ```

  When the page loads, the element containing "foo" will be marked as the
  indicated part and set as the document's target element. However, "foo"
  will not be scrolled into view.
</div>

Fragment-based scroll blocking from this policy is specified in an amendment to the
<a spec=HTML>scroll to the fragment</a> algorithm in the
[[#navigating-to-text-fragment]] section of this document.

History scroll restoration is blocked by amending the <a spec="HTML">restore
persisted state</a> steps by inserting a new step after 2:

3. <a href="https://wicg.github.io/document-policy#algo-get-policy-value">Get
    the document policy value</a> of the "force-load-at-top" feature for the [=/Document=]. If
    the result is true, then the user agent should not restore the scroll
    position for the [=/Document=] or any of its scrollable regions.


## Feature Detectability ## {#feature-detectability}

For feature detectability, we propose adding a new FragmentDirective interface
that is exposed via <code>document.fragmentDirective</code> if the UA supports
the feature.

<pre class='idl'>
  [Exposed=Window]
  interface FragmentDirective {
  };
</pre>

We amend the {{Document}} interface to include a <code>fragmentDirective</code>
property:

<pre class='idl'>
  partial interface Document {
      [SameObject] readonly attribute FragmentDirective fragmentDirective;
  };
</pre>

This object may be used to expose additional information about the text
fragment or other fragment directives in the future.

# Generating Text Fragment Directives # {#generating-text-fragment-directives}

<div class='note'>
  This section is non-normative.
</div>

This section contains recommendations for UAs automatically generating URLs
with a [=text directive=]. These recommendations aren't normative but
are provided to ensure generated URLs result in maximally stable and usable
URLs.

## Prefer Exact Matching To Range-based ## {#prefer-exact-matching-to-range-based}

The match text can be provided either as an exact string "text=foo%20bar%20baz"
or as a range "text=foo,bar".

Prefer to specify the entire string where practical. This ensures that if the
destination page is removed or changed, the intended destination can still be
derived from the URL itself.

<div class='example'>
  Suppose we wish to craft a URL to
  https://en.wikipedia.org/wiki/History_of_computing quoting the sentence:

  <pre>
    The first recorded idea of using digital electronics for computing was the
    1931 paper "The Use of Thyratrons for High Speed Automatic Counting of
    Physical Phenomena" by C. E. Wynn-Williams.
  </pre>

  We could create a range-based match like so:

  <a href="https://en.wikipedia.org/wiki/History_of_computing#:~:text=The%20first%20recorded,Williams">
  https://en.wikipedia.org/wiki/History_of_computing#:~:text=The%20first%20recorded,Williams</a>

  Or we could encode the entire sentence using an exact match term:

  <a href="https://en.wikipedia.org/wiki/History_of_computing#:~:text=The%20first%20recorded%20idea%20of%20using%20digital%20electronics%20for%20computing%20was%20the%201931%20paper%20%22The%20Use%20of%20Thyratrons%20for%20High%20Speed%20Automatic%20Counting%20of%20Physical%20Phenomena%22%20by%20C.%20E.%20Wynn-Williams">
  https://en.wikipedia.org/wiki/History_of_computing#:~:text=The%20first%20recorded%20idea%20of%20using%20digital%20electronics%20for%20computing%20was%20the%201931%20paper%20%22The%20Use%20of%20Thyratrons%20for%20High%20Speed%20Automatic%20Counting%20of%20Physical%20Phenomena%22%20by%20C.%20E.%20Wynn-Williams</a>

  The range-based match is less stable, meaning that if the page is changed to
  include another instance of "The first recorded" somewhere earlier in the
  page, the link will now target an unintended text snippet.

  The range-based match is also less useful semantically. If the page is
  changed to remove the sentence, the user won't know what the intended
  target was. In the exact match case, the user can read, or the UA can
  surface, the text that was being searched for but not found.
</div>

Range-based matches can be helpful when the quoted text is excessively long
and encoding the entire string would produce an unwieldy URL.

Text snippets shorter than 300 characters are encouraged to be encoded using an
exact match. Above this limit, the UA can encode the string as a range-based
match.

<div class='note'>
  TODO:  Can we determine the above limit in some less arbitrary way?
</div>

## Use Context Only When Necessary ## {#use-context-only-when-necessary}

Context terms allow the [=text directive=] to disambiguate text
snippets on a page. However, their use can make the URL more brittle in some
cases. Often, the desired string will start or end at an element boundary. The
context will therefore exist in an adjacent element. Changes to the page
structure could invalidate the [=text directive=] since the context and
match text will no longer appear to be adjacent.

<div class='example'>
  Suppose we wish to craft a URL for the following text:

  <pre>
    &lt;div class="section"&gt;HEADER&lt;/div&gt;
    &lt;div class="content"&gt;Text to quote&lt;/div&gt;
  </pre>

  We could craft the [=text directive=] as follows:

  <pre>
    text=HEADER-,Text%20to%20quote
  </pre>

  However, suppose the page changes to add a "[edit]" link beside all section
  headers. This would now break the URL.
</div>

Where a text snippet is long enough and unique, a UAs are encouraged to avoid
adding superfluous context terms.

Use context only if one of the following is true:
<ul>
  <li>The UA determines the quoted text is ambiguous</li>
  <li>The quoted text contains 3 or fewer words</li>
</ul>

<div class="note">
  TODO: Determine the numeric limit above in less arbitrary way.
</div>

## Determine If Fragment Id Is Needed ## {#determine-if-fragment-id-is-needed}

When the UA navigates to a URL containing a [=text directive=], it will
fallback to scrolling into view a regular element-id based fragment if it
exists and the text fragment isn't found.

This can be useful to provide a fallback, in case the text in the document
changes, invalidating the [=text directive=].

<div class='example'>
  Suppose we wish to craft a URL to
  https://en.wikipedia.org/wiki/History_of_computing quoting the sentence:

  <pre>
    The earliest known tool for use in computation is the Sumerian abacus
  </pre>

  By specifying the section that the text appears in, we ensure that, if the
  text is changed or removed, the user will still be pointed to the relevant
  section:

  <a href="https://en.wikipedia.org/wiki/History_of_computing#Early_computation:~:text=The%20earliest%20known%20tool%20for%20use%20in%20computation%20is%20the%20Sumerian%20abacus">
  https://en.wikipedia.org/wiki/History_of_computing#Early_computation:~:text=The%20earliest%20known%20tool%20for%20use%20in%20computation%20is%20the%20Sumerian%20abacus</a>
</div>

However, UAs should take care that the fallback element-id fragment is the
correct one:

<div class='example'>
  Suppose the user navigates to
  https://en.wikipedia.org/wiki/History_of_computing#Early_computation. They
  now scroll down to the Symbolic Computations section. There, they select a
  text snippet and choose to create a URL to it:

  <pre>
    By the late 1960s, computer systems could perform symbolic algebraic
    manipulations
  </pre>

  Even though the current URL of the page is:
  https://en.wikipedia.org/wiki/History_of_computing#Early_computation, using
  #Early_computation as a fallback is inappropriate. If the above sentence is
  changed or removed, the page will load in the #Early_computation section
  which could be quite confusing to the user.

  If the UA cannot reliably determine an appropriate fragment to fallback to,
  it should remove the fragment id from the URL:

  <a href="https://en.wikipedia.org/wiki/History_of_computing#:~:text=By%20the%20late%201960s,%20computer%20systems%20could%20perform%20symbolic%20algebraic%20manipulations">
  https://en.wikipedia.org/wiki/History_of_computing#:~:text=By%20the%20late%201960s,%20computer%20systems%20could%20perform%20symbolic%20algebraic%20manipulations</a>
</div>