Text Fragments

Draft Community Group Report,

This version:
https://wicg.github.io/scroll-to-text-fragment/
Issue Tracking:
GitHub
Inline In Spec
Editors:
(Google)
(Google)
Test Suite:
https://wpt.fyi/results/scroll-to-text-fragment/

Abstract

Text Fragments adds 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.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Infrastructure

This specification depends on the Infra Standard. [INFRA]

2. Introduction

This section is non-normative

2.1. Use cases

2.1.1. 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.

2.1.2. User sharing

With text fragments, 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.

3. Description

3.1. Indication

This section is non-normative

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:

The choice of action can have implications for user security and privacy. See the § 3.4 Security and Privacy section for details.

3.2. Syntax

This section is non-normative

A text fragment directive is specified in the fragment directive (see § 3.3 The Fragment Directive) with the following format:

#:~:text=[prefix-,]start[,end][,-suffix]
          context  |--match--|  context

(Square brackets indicate an optional parameter)

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 start. If only start is specified, the first instance of this exact text string is the target text.

#:~:text=an%20example%20text%20fragment indicates that the exact text "an example text fragment" is the target text.

If the end 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 start, until the first instance of end that appears after start. This is equivalent to specifying the entire text range in the start parameter, but allows the URL to avoid being bloated with a long text directive.

#:~:text=an%20example,text%20fragment indicates that the first instance of "an example" until the following first instance of "text fragment" is the target text.

3.2.1. Context Terms

This section is non-normative

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 start and end 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.

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.

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

#:~:text=this%20is-,an%20example,-text%20fragment would match to "an example" in "this is an example text fragment", but not match to "an example" in "here is an example text".

3.2.2. BiDi Considerations

This section is non-normative
See Unicode Bidirectional Algorithm basics for a good overview of how Bidirectional text works.

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 logical order, 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 prefix and start terms identify text coming before another term in logical order, while suffix and end 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.

Suppose we want to select the text مِصر‎ (Egypt, in Arabic), that’s preceeded by البحرين‎ (Bahrain, in Arabic). We would first percent encode each term:

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

البحرين‎ becomes "%D8%A7%D9%84%D8%A8%D8%AD%D8%B1%D9%8A%D9%86"

The text fragment would then become:

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

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

:~:text=البحرين-,مِصر

3.3. The Fragment Directive

To avoid compatibility issues with usage of existing URL fragments, this spec introduces the fragment directive. The fragment directive is a portion of the URL fragment that follows the fragment directive delimiter.

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

The fragment directive is part of the URL fragment. This means it always appears after a U+0023 (#) code point in a URL.
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.

The fragment directive is meant to carry instructions, such as text=, for the UA rather than for the document.

To prevent impacting page operation, it is stripped from a Document's URL so that author scripts can’t directly interact with it. This also ensures future directives could be added without introducing breaking changes to existing content. Potential examples could be: image-fragments, translation-hints.

3.3.1. Processing the fragment directive

The fragment directive is processed and removed from the fragment whenever the UA sets the URL on a Document. This is defined with the following additions and changes.

To the definition of Document, add:

Monkeypatching [DOM]:

Each document has an associated fragment directive which is either null or an ASCII string holding data used by the UA to process the resource. It is initially null.

To split the fragment from the fragment directive, given an ASCII string raw fragment and returning a tuple consisting of a fragment and a fragment directive (both ASCII strings), run these steps:
  1. Let position be the 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.

  2. Let fragment be the code point substring by positions of raw fragment from the start of raw fragment to position.

  3. Let fragmentDirective be an ASCII string, initially empty.

  4. Advance position by the code point length of the fragment directive delimiter.

  5. If position does not point past the end of raw fragment:

    1. Set fragmentDirective to the code point substring to the end of the string raw fragment starting from position

  6. Return the tuple (fragment, fragmentDirective).

Whenever the fragment directive is stripped from the URL, it is set to the Document’s fragment directive.

Add a series of steps that will process a fragment directive on a URL:

Monkeypatching [DOM]:

To process and consume fragment directive from a URL url and Document document, run these steps:

  1. Let raw fragment be equal to url’s fragment.

  2. If raw fragment is non-null and contains the fragment directive delimiter as a substring:

    1. Let components be the result of running split the fragment from the fragment directive on raw fragment.

    2. Set url’s fragment to componentsfragment.

    3. Set document’s fragment directive to componentsfragment directive.

      This is stored on the document but currently not web-exposed
These changes make a URL’s fragment end at the fragment directive delimiter. The fragment directive includes all characters that follow, but not including, the delimiter.
https://example.org/#test:~:text=foo will be parsed such that the fragment is the string "test" and the fragment directive is the string "text=foo".

Amend the create and initialize a Document object steps to parse and remove the fragment directive by inserting the following steps right before the setting document’s URL (currently step 9):

Monkeypatching [HTML]:

  1. Run the process and consume fragment directive steps on creationURL and document.

  2. Set document’s URL to be creationURL.

Amend the traverse the history steps to process the fragment directive during a history navigation by inserting steps before setting the newDocument’s URL (currently step 6).

Monkeypatching [HTML]:

  1. Let processedURL be a copy of entry’s URL.

  2. Run the process and consume fragment directive steps on processedURL and document.

  3. Set newDocument’s URL to processedURL.

The changes in this section imply that a URL is only stripped of its fragment directive when it is set on a Document. Notably, 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.

Some examples are provided to help clarify various edge cases.

window.location = 'https://example.com#foo:~:bar';

The page loads and when the document’s URL is set the fragment directive is stripped out during the "create and initialize a Document object" steps.

console.log(window.location.href); // 'https://example.com#foo'
console.log(window.location.hash); // '#foo'

Since same document navigations are made by adding a new session history entry and using the "traverse the history" steps, the the fragment directive will be stripped here as well.

window.location.hash = 'fizz:~:buzz';
console.log(window.location.href); // 'https://example.com#fizz'
console.log(window.location.hash); // '#fizz'

The hashchange event is dispatched when only the fragment directive changes because the comparison for it is done on the URLs in the session history entries, where the fragment directive hasn’t been removed.

onhashchange = () => {console.log('HASHCHANGE');};
window.location.hash = 'fizz:~:zillch'; // 'HASHCHANGE'
console.log(window.location.href); // 'https://example.com#fizz'
console.log(window.location.hash); // '#fizz'
In other cases where a Document’s URL is not set by the UA, 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>
History pushState will create a session history entry where the URL’s fragment directive isn’t stripped. However, traversing to the entry will cause it to set its URL on the document which will process the fragment directive before setting it on the Document (but the fragment directive remains on the entry).
history.pushState({}, 'title', 'index.html#foo:~:bar');
window.location = 'newpage.html';
// on newpage.html
history.back();

Results in the current document having "bar" as the fragment directive.

3.3.2. Parsing the fragment directive

A text directive is a struct that consists of four strings: start, end, prefix, and suffix. 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 § 3.2 Syntax for the what each of these components means and how they’re used.

To parse a text directive, on an ASCII string text directive input, run these steps:

This algorithm takes a single text directive string as input (e.g. "text=prefix-,foo,bar") and attempts to parse the string into the components of the directive (e.g. ("prefix", "foo", "bar", null)). See § 3.2 Syntax for the what each of these components means and how they’re used.

Returns null if the input is invalid or fails to parse in any way. Otherwise, returns a text directive.

  1. Assert: text directive input matches the production TextDirective.

  2. Let textDirectiveString be the substring of text directive input starting at index 5.

    This is the remainder of the text directive input following, but not including, the "text=" prefix.
  3. Let tokens be a list of strings that is the result of splitting textDirectiveString on commas.

  4. If tokens has size less than 1 or greater than 4, return null.

  5. If any of tokens’s items are the empty string, return null.

  6. Let retVal be a text directive with each of its items initialized to null.

  7. Let potential prefix be the first item of tokens.

  8. If the last character of potential prefix is U+002D (-), then:

    1. Set retVal’s prefix to the percent-decoding of the result of removing the last character from potential prefix.

    2. Remove the first item of the list tokens.

  9. Let potential suffix be the last item of tokens, if one exists, null otherwise.

  10. If potential suffix is non-null and its first character is U+002D (-), then:

    1. Set retVal’s suffix to the percent-decoding of the result of removing the first character from potential suffix.

    2. Remove the last item of the list tokens.

  11. If tokens has size not equal to 1 nor 2 then return null.

  12. Set retVal’s start be the percent-decoding of the first item of tokens.

  13. If tokens has size 2, then set retVal’s end be the percent-decoding of the last item of tokens.

  14. Return retVal.

3.3.3. Fragment directive grammar

A valid fragment directive is a sequence of characters that appears in the fragment directive that matches the production:

FragmentDirective ::=
(TextDirective | UnknownDirective) ("&" FragmentDirective)?
UnknownDirective ::=
CharacterString
CharacterString ::=
(ExplicitChar | PercentEncodedChar)+
ExplicitChar ::=
[a-zA-Z0-9] | "!" | "$" | "'" | "(" | ")" | "*" | "+" | "." | "/" | ":" | ";" | "=" | "?" | "@" | "_" | "~" | "&" | "," | "-"
An ExplicitChar may be any URL code point.
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.

The text fragment directive is one such fragment directive that enables specifying a piece of text on the page, that matches the production:

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

3.4. Security and Privacy

3.4.1. Motivation

This section is non-normative

Care must be taken when implementing text fragment 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 fragment 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 following subsections restrict the feature to mitigate the expected attack vectors. In summary, the text fragment directives are invoked only on full (non-same-page) navigations that are the result of a user activation. Additionally, navigations originating from a different origin than the destination will require the navigation to take place in a "noopener" context, such that the destination page is known to be sufficiently isolated.

3.4.2. 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.

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.
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.
A malicious page embeds a cross-origin victim in an iframe. The victim page contains information sensitive to the user. The malicious page navigates the victim to a text fragment. Since a successful fragment match will cause focus, the malicious page can determine if the text appears in the victim by listening for a blur event in its own document.
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.

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.

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).

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.

3.4.3. 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 fragment directive-invoking URL, they would be able to determine the existence of a text snippet by measuring how long the navigation call takes.

The restrictions in § 3.4.4 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.

For this reason, the implementation must ensure the runtime of § 3.5 Navigating to a Text Fragment steps does not differ based on whether a match has been successfully found.

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

3.4.4. Restricting the Text Fragment

Amend the definition of a request and of a Document to include a new boolean text fragment user activation field:

Monkeypatching [FETCH]:

A request has an associated boolean text fragment user activation, initially false.

Monkeypatching [HTML]:

Each Document has a text fragment user activation, which is a boolean, initially false.

text fragment 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 text fragment user activation isn’t used to activate a text fragment, it is instead used to set a new navigation request's text fragment user activation to true. In this way, a text fragment user activation can be propagated from one Document to another across a navigation.

Both Document's text fragment user activation and request's text fragment 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.

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 window.location .

Unlike real HTTP ( status 3xx ) redirects, these "client-side" redirects cannot propagate the fact that the navigation is the result of a user gesture. The text fragment 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 text fragment user activation, further text fragment navigations will not activation without a new user gesture.

The following diagram demonstrates how the flag is used to activate a text fragment through a client-side redirect service:

Diagram showing how a text fragment flag is set and used

See redirects.md for a more in-depth discussion.

Monkeypatching [HTML]:

Each Document has an allow text fragment scroll, which is a boolean, initially false.

allow text fragment scroll is used to determine whether a text fragment will perform scrolling when the document is loaded. If it is false, the text fragment can be visually indicated but will not be scrolled to. This implements the mitigations discussed in § 3.4.2 Scroll On Navigation.

The reason we compute and store allow text fragment scroll, rather than performing these checks at the time of use, is that it relies on the properties of the navigation while the invocation will occur as part of the scroll to the fragment steps which can happen outside the context of a navigation.

TODO: This should really only prevent potentially observable side-effects like automatic scrolling. Unobservable effects like a highlight could be safely allowed in all cases.

Amend the create and initialize a Document object steps by adding the following steps before returning document:

Monkeypatching [HTML]:

  1. Set document’s text fragment user activation by following these sub-steps:

    1. Let is user activated be true if the current navigation was initiated from a window that had a transient activation at the time the navigation was initiated, or the UA has reason to believe it comes from a direct user gesture (e.g. user typed into the address bar).

      TODO: it’d be better to refer to the user-activation flag.
    2. If browsing context is a top-level browsing context and if either of is user activated or the text fragment user activation of navigationParam’s request object is true, set the document’s text fragment user activation to true. Otherwise, set it to false.

      It’s important that the flag not be copyable so that only one text fragment can be activated per user-activated navigation.
  2. Set document’s allow text fragment scroll by following these sub-steps:

    1. If document’s fragment directive field is null or empty, set allow text fragment scroll to false and abort these sub-steps.

    2. Let text fragment user activation be the value of document’s text fragment user activation and set document’s text fragment user activation to false.

    3. If the navigationParam’s request has a sec-fetch-site header and its value is "none" set allow text fragment scroll to true and abort these sub-steps.

      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.

      Note: Depending on the UA, there can be cases where the incumbentNavigationOrigin parameter is null but it’s not clear that the navigation is to be considered as initiated from browser UI. E.g. an "open in new window" context menu item when right clicking on a link. The intent in this item is to distinguish cases where the app/page is able to set the URL from those that are fully under the user’s control. In the former we want to prevent activation 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).

      See sec-fetch-site in [FETCH-METADATA] for a more detailed discussion of how this applies.

    4. If text fragment user activation is false, set allow text fragment scroll to false and abort these sub-steps.

    5. If the navigationParam’s request has a sec-fetch-site header and its value is "same-origin" set allow text fragment scroll to true and abort these sub-steps.

    6. If document’s browsing context is a top-level browsing context and its group’s browsing context set has length 1, set allow text fragment scroll to true and abort these sub-steps.

      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.
    7. Otherwise, set allow text fragment scroll to false.

Amend step 2 of the process a navigate fetch steps to additionally set request’s text fragment user activation to the value of the active document's text fragment user activation and set the active document's value to false.

Monkeypatching [HTML]:

  1. Set request’s client to sourceBrowsingContext’s active document’s relevant settings object, destination to "document", mode to "navigate", credentials mode to "include", use-URL-credentials flag, redirect mode to "manual", replaces client id to browsingContext’s active document’s relevant settings object’s id, and text fragment user activation to sourceBrowsingContext’s active document’s text fragment user activation. Set sourceBrowsingContext’s active document’s text fragment user activation to false.

Amend the try to scroll to the fragment steps by replacing the steps of the task queued in step 2:

Monkeypatching [HTML]:

  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 set document’s allow text fragment scroll to false and abort these steps.

  2. Scroll to the fragment given in document’s URL. If this does not find an indicated part, then try to scroll to the fragment for document.

  3. Set document’s allow text fragment scroll to false.

The text fragment specification proposes an amendment to HTML § 7.4.2.3.3 Fragment navigations. In summary, if a text fragment 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.

To enable the scroll to the fragment algorithm to operate on a range indicated part, replace step 3 of this algorithm as follows:

Monkeypatching [HTML]:

Replace:

  1. Assert: document’s indicated part is an element.
  2. Let target be document’s indicated part.
  3. Set document’s target element to target.
  4. Run the ancestor details revealing algorithm on target.
  5. Run the ancestor hidden-until-found revealing algorithm on target.
  6. Scroll target into view, with behavior set to "auto", block set to "start", and inline set to "nearest".
  7. Run the focusing steps for target, with the Document’s viewport as the fallback target.
  8. Move the sequential focus navigation starting point to target.

With:

  1. Assert: document’s indicated part is a range.

  2. Let range be the range that is document’s indicated part.

  3. Let target be the first common ancestor of range’s start node and end node.

  4. While target is non-null and is not an element, set target to target’s parent.

    What should be set as target if inside a shadow tree? #190
  5. Set document’s target element to target.

  6. Run the ancestor details revealing algorithm on target.

  7. Run the ancestor hidden-until-found revealing algorithm on target.

    These revealing algorithms currently wont work well since target could be an ancestor or even the root document node. Issue #89 proposes restricting matches to contain:style layout blocks which would resolve this problem.
  8. Get the policy value for force-load-at-top in the Document. If the result is false:

    1. If range wasn’t produced as a result of a text fragment, or if the UA supports scrolling of text fragments on navigation, invoke scroll a target into view, with target set to range, containingElement target, behavior set to "auto", block set to "center", and inline set to "nearest".

    force-load-at-top should be checked only when a new document is being loaded. #186
  9. Let start node be range’s start node.

  10. Run the focusing steps for start node, with the Document’s viewport as the fallback target.

    Implementation note: Blink doesn’t currently set focus for text fragments, it probably should? TODO: file crbug.
  11. Move the sequential focus navigation starting point to start node.

To enable a fragment to indicate a range of text, add the following steps to the beginning of the processing model for the HTML Document's indicated part so that the indicated part is a range:

Monkeypatching [HTML]:

  1. Let fragment directive string be the document’s fragment directive.

  2. If the document’s allow text fragment scroll is true then:

    1. Let ranges be a list that is the result of running the process a fragment directive steps with fragment directive string and the document.

    2. If ranges is non-empty, then:

      1. Let range be the first item of ranges.

        The first range in ranges is specifically scrolled into view. This range, along with the remaining ranges should be visually indicated in a way that is not revealed to script, which is left as UA-defined behavior.
      2. Set range as document’s indicated part, return.

In order for the indicated part to return a range for regular element fragments, modify the find a potential indicated element steps as follows:

Monkeypatching [HTML]:

Replace:

  1. If there is an element in the document tree whose root is document and that has an ID equal to fragment, then return the first such element in tree order.
  2. If there is an a element in the document tree whose root is document that has a name attribute whose value is equal to fragment, then return the first such element in tree order.
  3. Return null.

With:

  1. Let element be an Element, initially null.

  2. If there is an element in the document tree whose root is document and that has an ID equal to fragment, set element to the first such element in tree order.

  3. Otherwise, if there is an element in the document tree whose root is document that has a name attribute whose value is equal to fragment, then set element to the first such element in tree order.

  4. If element is null, return null.

  5. Otherwise, return a range with start (element, 0) and end (element, element’s length).

And rename this algorithm and the returned variables.

To find the first common ancestor of two nodes nodeA and nodeB, follow these steps:
  1. Let commonAncestor be nodeA.

  2. While commonAncestor is non-null and is not a shadow-including inclusive ancestor of nodeB, let commonAncestor be commonAncestor’s shadow-including parent.

  3. Return commonAncestor.

To find the shadow-including parent of node follow these steps:
  1. If node is a shadow root, return node’s host.

  2. Otherwise, return node’s parent.

3.5.1. Finding Ranges in a Document

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:

text=prefix-,foo&unknown&text=bar,baz

We break this up into the individual text directives:

text=prefix-,foo
text=bar,baz

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 process a fragment directive steps are the high level API provided by this section. These return a list 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.

To process a fragment directive, given as input an ASCII string fragment directive input and a Document document, run these steps:
This algorithm takes as input a fragment directive input, that is the raw text of the fragment directive and the document over which it operates. It returns a list of ranges that are to be visually indicated, the first of which will be scrolled into view (if the UA scrolls automatically).
  1. If fragment directive input is not a valid fragment directive, then return an empty list.

  2. Let directives be a list of ASCII strings that is the result of strictly splitting the string fragment directive input on "&".

  3. Let ranges be a list of ranges, initially empty.

  4. For each ASCII string directive of directives:

    1. If directive does not match the production TextDirective, then continue.

    2. Let parsedValues be the result of running the parse a text directive steps on directive.

    3. If parsedValues is null then continue.

    4. If the result of running find a range from a text directive given parsedValues and document is non-null, then append it to ranges.

  5. Return ranges.

To find a range from a text directive, given a text directive parsedValues and Document document, run the following steps:
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.

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

Either or both of prefix and suffix can be null, in which case context on that side of a match is not checked. E.g. If prefix is null, text is matched without any requirement on what text precedes it.

While the matching text and its prefix/suffix can span across block-boundaries, the individual parameters to these steps cannot. That is, each of prefix, start, end, and suffix will only match text within a single block.
:~:text=The quick,lazy dog
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>
  1. Let searchRange be a range with start (document, 0) and end (document, document’s length)

  2. While searchRange is not collapsed:

    1. Let potentialMatch be null.

    2. If parsedValues’s prefix is not null:

      1. Let prefixMatch be the the result of running the find a string in range steps with query parsedValues’s prefix, searchRange searchRange, wordStartBounded true and wordEndBounded false.

      2. If prefixMatch is null, return null.

      3. Set searchRange’s start to the first boundary point after prefixMatch’s start

      4. Let matchRange be a range whose start is prefixMatch’s end and end is searchRange’s end.

      5. Advance matchRange’s start to the next non-whitespace position.

      6. If matchRange is collapsed return null.

        This can happen if prefixMatch’s end or its subsequent non-whitespace position is at the end of the document.
      7. Assert: matchRange’s start node is a Text node.

        matchRange’s start now points to the next non-whitespace text data following a matched prefix.
      8. Let mustEndAtWordBoundary be true if parsedValues’s end is non-null or parsedValues’s suffix is null, false otherwise.

      9. Set potentialMatch to the result of running the find a string in range steps with query parsedValues’s start, searchRange matchRange, wordStartBounded false, and wordEndBounded mustEndAtWordBoundary.

      10. If potentialMatch is null, return null.

      11. If potentialMatch’s start is not matchRange’s start, then continue.

        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 prefix.
    3. Otherwise:

      1. Let mustEndAtWordBoundary be true if parsedValues’s end is non-null or parsedValues’s suffix is null, false otherwise.

      2. Set potentialMatch to the result of running the find a string in range steps with query parsedValues’s start, searchRange searchRange, wordStartBounded true, and wordEndBounded mustEndAtWordBoundary.

      3. If potentialMatch is null, return null.

      4. Set searchRange’s start to the first boundary point after potentialMatch’s start

    4. Let rangeEndSearchRange be a range whose start is potentialMatch’s end and whose end is searchRange’s end.

    5. While rangeEndSearchRange is not collapsed:

      1. If parsedValues’s end item is non-null, then:

        1. Let mustEndAtWordBoundary be true if parsedValues’s suffix is null, false otherwise.

        2. Let endMatch be the result of running the find a string in range steps with query parsedValues’s end, searchRange rangeEndSearchRange, wordStartBounded true, and wordEndBounded mustEndAtWordBoundary.

        3. If endMatch is null then return null.

        4. Set potentialMatch’s end to endMatch’s end.

      2. Assert: potentialMatch is non-null, not collapsed and represents a range exactly containing an instance of matching text.

      3. If parsedValues’s suffix is null, return potentialMatch.

      4. Let suffixRange be a range with start equal to potentialMatch’s end and end equal to searchRange’s end.

      5. Advance suffixRange’s start to the next non-whitespace position.

      6. Let suffixMatch be result of running the find a string in range steps with query parsedValues’s suffix, searchRange suffixRange, wordStartBounded false, and wordEndBounded true.

      7. If suffixMatch is null then return null.

        If the suffix doesn’t appear in the remaining text of the document, there’s no possible way to make a match.
      8. If suffixMatch’s start is suffixRange’s start, return potentialMatch.

      9. If parsedValues’s end item is null then break;

        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.
      10. Set rangeEndSearchRange’s start to potentialMatch’s end.

        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.
    6. If rangeEndSearchRange is collapsed then:

      1. Assert: parsedValues’s end item is non-null

      2. Return null

        This can only happen for range matches due to the 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.
  3. Return null

Tests
To advance a range range’s start to the next non-whitespace position follow the steps:
  1. While range is not collapsed:

    1. Let node be range’s start node.

    2. Let offset be range’s start offset.

    3. 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 length then:

      1. Set range’s start node to the next node, in shadow-including tree order.

      2. Set range’s start offset to 0.

      3. Continue.

    4. If the substring data of node at offset offset and count 6 is equal to the string "&nbsp;" then:

      1. Add 6 to range’s start offset.

    5. Otherwise, if the substring data of node at offset offset and count 5 is equal to the string "&nbsp" then:

      1. Add 5 to range’s start offset.

    6. Otherwise:

      1. Let cp be the code point at the offset index in node’s data.

      2. If cp does not have the White_Space property set, return.

      3. Add 1 to range’s start offset.

To find a string in range given a string query, a range searchRange, and booleans wordStartBounded and wordEndBounded, run these steps:
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 § 3.5.2 Word Boundaries). Returns null if none is found.

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.

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>

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.

  1. While searchRange is not collapsed:

    1. Let curNode be searchRange’s start node.

    2. If curNode is part of a non-searchable subtree:

      1. Set searchRange’s start node to the next node, in shadow-including tree order, that isn’t a shadow-including descendant of curNode.

      2. Set searchRange’s start offset to 0.

      3. Continue.

    3. If curNode is not a visible text node:

      1. Set searchRange’s start node to the next node, in shadow-including tree order, that is not a doctype.

      2. Set searchRange’s start offset to 0.

      3. Continue.

    4. Let blockAncestor be the nearest block ancestor of curNode.

    5. Let textNodeList be a list of Text nodes, initially empty.

    6. While curNode is a shadow-including descendant of blockAncestor and the position of the boundary point (curNode, 0) is not after searchRange’s end:

      1. If curNode has block-level display then break.

      2. 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. Continue.

      3. If curNode is a visible text node then append it to textNodeList.

      4. Set curNode to the next node in shadow-including tree order.

    7. 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.

    8. If curNode is null, then break.

    9. Assert: curNode follows searchRange’s start node.

    10. Set searchRange’s start to the boundary point (curNode, 0).

  2. Return null.

A node is search invisible 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 none.

  2. If the node serializes as void.

  3. Is any of the following types: HTMLIFrameElement, HTMLImageElement, HTMLMeterElement, HTMLObjectElement, HTMLProgressElement, HTMLStyleElement, HTMLScriptElement, HTMLVideoElement, HTMLAudioElement

  4. Is a select element whose multiple content attribute is absent.

A node is part of a non-searchable subtree if it is or has a shadow-including ancestor that is search invisible.

A node is a visible text node if it is a Text node, the computed value of its parent element's visibility property is visible, and it is being rendered.

A node has block-level display if it is an element and the computed value of its display property is any of block, table, flow-root, grid, flex, list-item.

To find the nearest block ancestor of a node follow the steps:
  1. Let curNode be node.

  2. While curNode is non-null

    1. If curNode is not a Text node and it has block-level display then return curNode.

    2. Otherwise, set curNode to curNode’s parent.

  3. Return node’s node document's document element.

To find a range from a node list given a search string queryString, a range searchRange, a list of Text nodes nodes, and booleans wordStartBounded and wordEndBounded, follow these steps:
Optionally, this will only return a match if the matched text begins and/or ends on a word boundary. For 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”.

See § 3.5.2 Word Boundaries for details and more examples.

  1. Let searchBuffer be the concatenation of the data of each item in nodes.

    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). [Issue #WICG/scroll-to-text-fragment#98]

  2. Let searchStart be 0.

  3. If the first item in nodes is searchRange’s start node then set searchStart to searchRange’s start offset.

  4. Let start and end be boundary points, initially null.

  5. Let matchIndex be null.

  6. 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 primary level, as defined in [UTS10].

      Intuitively, this is a case-insensitive search also ignoring accents, umlauts, and other marks.
    2. If matchIndex is null, return null.

    3. Let endIx be matchIndex + queryString’s length.

      endIx is the index of the last character in the match + 1.
    4. Set start to the boundary point result of get boundary point at index matchIndex run over nodes with isEnd false.

    5. Set end to the boundary point result of get boundary point at index endIx run over nodes with isEnd true.

    6. If wordStartBounded is true and matchIndex is not at a word boundary in searchBuffer, given the language from start’s node as the locale; or wordEndBounded is true and matchIndex + queryString’s length is not at a word boundary in searchBuffer, given the language from end’s node as the locale:

      1. Set searchStart to matchIndex + 1.

      2. Set matchIndex to null.

  7. Let endInset be 0.

  8. If the last item in nodes is searchRange’s end node then set endInset to (searchRange’s end node's lengthsearchRange’s end offset)

    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.
  9. If matchIndex + queryString’s length is greater than searchBuffer’s length − endInset return null.

    If the match runs past the end of the search range, return null.
  10. Assert: start and end are non-null, valid boundary points in searchRange.

  11. Return a range with start start and end end.

To get boundary point at index, given an integer index, list of Text nodes nodes, and a boolean isEnd, follow these steps:

This is a small helper routine used by the steps above to determine which node a given index in the concatenated string belongs to.

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.

  1. Let counted be 0.

  2. For each curNode of nodes:

    1. Let nodeEnd be counted + curNode’s length.

    2. If isEnd is true, add 1 to nodeEnd.

    3. If nodeEnd is greater than index then:

      1. Return the boundary point (curNode, indexcounted).

    4. Increment counted by curNode’s length.

  3. Return null.

3.5.2. Word Boundaries

Limiting matching to word boundaries is one of the mitigations to limit cross-origin information leakage.
See Intl.Segmenter, 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.

A word boundary is defined in [UAX29] in Unicode Text Segmentation § Word_Boundaries. Unicode Text Segmentation § 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.

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.

A locale is a string containing a valid [BCP47] language tag, or the empty string. An empty string indicates that the primary language is unknown.

A substring is word bounded in a string 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 is at a word boundary in a string text, given a locale locale, if, using locale, either a word boundary immediately precedes the positionth code unit, or text’s length is more than 0 and position equals either 0 or text’s length.

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.

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 prefix,start,suffix, "prefix+start+suffix" will match only if the entire result is word bounded. However, in a range search like prefix,start,end,suffix, a match is found only if both "prefix+start" and "end+suffix" are word bounded.

The goal is that a third-party must already know the full tokens they are matching against. A range match like start,end 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 "Balance: 123,456 $", a third-party could set prefix="Balance: ", end="$" and vary start to try and guess the numeric token one digit at a time).

For more details, refer to the Security Review Doc

The substring "mountain range" is word bounded within the string "An impressive mountain range" but not within "An impressive mountain ranger".
In the Japanese string "ウィキペディアへようこそ" (Welcome to Wikipedia), "ようこそ" (Welcome) is considered word-bounded but "ようこ" is not.

3.6. Indicating The Text Match

The UA may choose to scroll the text fragment into view as part of the try to scroll to the fragment 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 the Document’s selection to indicate the text match as 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.

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.

3.6.1. URLs in UA features

UAs provide a number of consumers for a document’s URL (outside of programmatic APIs like window.location). 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.

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.

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?

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.

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.

However, it’s unlikely to be useful to the user in a bookmark.

A few common examples are provided below.

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.
3.6.1.1. 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.

3.6.1.2. 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.

3.6.1.3. 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.

3.7. Document Policy Integration

This specification defines a configuration point in Document Policy with name "force-load-at-top". Its type is boolean with default value false.

When enabled, this policy disables all automatic scroll-on-load features: text-fragments, element fragments, history scroll restoration.
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.

Fragment-based scroll blocking from this policy is specified in an amendment to the scroll to the fragment algorithm in the § 3.5 Navigating to a Text Fragment section of this document.

History scroll restoration is blocked by amending the restore persisted state steps by inserting a new step after 2:

  1. Get the document policy value 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.

3.8. Feature Detectability

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

[Exposed=Window]
interface FragmentDirective {
};

We amend the Document interface to include a fragmentDirective property:

partial interface Document {
    [SameObject] readonly attribute FragmentDirective fragmentDirective;
};

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

4. Generating Text Fragment Directives

This section is non-normative.

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

4.1. 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.

Suppose we wish to craft a URL to https://en.wikipedia.org/wiki/History_of_computing quoting the sentence:
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.

We could create a range-based match like so:

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

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

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

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.

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.

TODO: Can we determine the above limit in some less arbitrary way?

4.2. Use Context Only When Necessary

Context terms allow the text fragment 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 fragment directive since the context and match text will no longer appear to be adjacent.

Suppose we wish to craft a URL for the following text:
<div class="section">HEADER</div>
<div class="content">Text to quote</div>

We could craft the text fragment directive as follows:

text=HEADER-,Text%20to%20quote

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

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:

TODO: Determine the numeric limit above in less arbitrary way.

4.3. Determine If Fragment Id Is Needed

When the UA navigates to a URL containing a text fragment 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 fragment directive.

Suppose we wish to craft a URL to https://en.wikipedia.org/wiki/History_of_computing quoting the sentence:
The earliest known tool for use in computation is the Sumerian abacus

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:

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

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

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:
By the late 1960s, computer systems could perform symbolic algebraic
manipulations

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:

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

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Tests

Tests relating to the content of this specification may be documented in “Tests” blocks like this one. Any such block is non-normative.


Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 5. URL: https://drafts.csswg.org/css-cascade-5/
[CSS-DISPLAY-3]
Tab Atkins Jr.; Elika Etemad. CSS Display Module Level 3. URL: https://drafts.csswg.org/css-display/
[CSS-DISPLAY-4]
CSS Display Module Level 4 URL: https://drafts.csswg.org/css-display-4/
[DOCUMENT-POLICY]
Ian Clelland. Document Policy. ED. URL: https://wicg.github.io/document-policy
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[UAX29]
Christopher Chapman. Unicode Text Segmentation. 26 August 2022. Unicode Standard Annex #29. URL: https://www.unicode.org/reports/tr29/tr29-41.html
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[UTS10]
Ken Whistler; Markus Scherer. Unicode Collation Algorithm. 26 August 2022. Unicode Technical Standard #10. URL: https://www.unicode.org/reports/tr10/tr10-47.html
[WEB-ANIMATIONS-1]
Brian Birtles; et al. Web Animations. URL: https://drafts.csswg.org/web-animations-1/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Informative References

[BCP47]
A. Phillips, Ed.; M. Davis, Ed.. Tags for Identifying Languages. September 2009. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc5646
[FETCH-METADATA]
Mike West. Fetch Metadata Request Headers. WD. URL: https://w3c.github.io/webappsec-fetch-metadata/

IDL Index

[Exposed=Window]
interface FragmentDirective {
};

partial interface Document {
    [SameObject] readonly attribute FragmentDirective fragmentDirective;
};

Issues Index

What should be set as target if inside a shadow tree? #190
These revealing algorithms currently wont work well since target could be an ancestor or even the root document node. Issue #89 proposes restricting matches to contain:style layout blocks which would resolve this problem.
force-load-at-top should be checked only when a new document is being loaded. #186
Implementation note: Blink doesn’t currently set focus for text fragments, it probably should? TODO: file crbug.
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). [Issue #WICG/scroll-to-text-fragment#98]