URL Fragment Text Directives

1. Infrastructure

This specification depends on the Infra Standard. [INFRA]

2. Introduction

2.1. Use cases

2.1.1. Web text references

2.1.2. User sharing

3. Description

3.1. Indication

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

3.2. Syntax

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

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.

3.2.1. Context Terms

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.

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

3.2.2. BiDi Considerations

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.

3.3. The Fragment Directive

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

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

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

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.

3.3.1. Extracting the fragment directive

This section describes the mechanism by which the fragment directive is hidden from script and how it fits into HTML § 7.4 Navigation and session history.

In HTML § 7.4.1 Session history, define directive state:

Monkeypatching HTML § 7.4.1 Session history:

directive state 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:

• value, the fragment directive ASCII string or null, initially null.

A directive state may be shared by multiple session history entries.

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.

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.

To the definition of session history entry, add:

Monkeypatching HTML § 7.4.1.1 Session history entries:

A session history entry is a struct with the following items:

• ...

• persisted user state, which is implementation-defined, initially null

• directive state, a directive state, initially a new directive state

Add a helper algorithm for removing and returning a fragment directive string from a URL:

Monkeypatching [HTML]:

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.

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 '#:~:'.

To remove the fragment directive from a URL url, run these steps:

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

2. Let fragment directive be null.

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

   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 new fragment be the code point substring by positions of raw fragment from the start of raw fragment to position.

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

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

   5. Set url’s fragment to new fragment.

4. Return fragment directive.

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

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:

Monkeypatching HTML § 7.4.2.2 Beginning navigation:

To navigate a navigable navigable to a URL url...:

1. ...

14. Set navigable’s ongoing navigation to navigationId.

15. If url’s scheme is "javascript", then...

16. In parallel, run these steps:

    1. ...

    5. If url is about:blank, then set documentState’s origin to documentState’s initiator origin.

    6. Otherwise, if url is about:srcdoc, then set documentState’s origin to navigable’s parent’s active document’s origin.

    7. Let historyEntry be a new session history entry, with its URL set to url and its document state set to documentState.
    7. Let fragment directive be the result of running remove the fragment directive on url.

    8. Let directive state be a new directive state with value set to fragment directive.

    9. Let historyEntry be a new session history entry, with its URL set to url, its document state set to documentState, and its directive state set to directive state.

    10. Let navigationParams be null.

    11. ...

In the definition of navigate to a fragment:

Monkeypatching HTML § 7.4.2.3.3 Fragment navigations:

To navigate to a fragment given navigable navigable, ...:

1. Let directive state be navigable’s active session history entry’s directive state.

2. Let fragment directive be the result of running remove the fragment directive on url.

3. If fragment directive is not null:

   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.

   1. Let directive state be a new directive state with value set to fragment directive.

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

   • directive state directive state

5. Let entryToReplace be navigable’s active session history entry if historyHandling is "replace", otherwise null.

6. ...

In the definition of URL and history update steps:

Monkeypatching HTML § 7.4.4 Non-fragment synchronous "navigations":

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. Let fragment directive be the result of running remove the fragment directive on newUrl.

4. Let historyEntry be a new session history entry, with

   • URL newUrl

   • ...

   • directive state activeEntry’s directive state

5. If document’s is initial about:blank is true, then set historyHandling to "replace".

6. 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. If newUrl does not equal activeEntry’s URL with exclude fragments set to true OR fragment directive is not null, then:

      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.

      1. Let historyEntry’s directive state be a new directive state with value set to fragment directive.

7. Otherwise, if fragment directive is not null, set historyEntry’s directive state's value to fragment directive.

8. If serializedData is not null, then restore the history object state given document and newEntry.

In the definition of create navigation params by fetching:

Monkeypatching HTML § 7.4.5 Populating a session history entry:

To create navigation params by fetching given a session history entry entry, ...:

1. Assert: this is running in parallel.

2. ...

17. Let currentURL be request’s current URL.

18. Let commitEarlyHints be null.

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

    2. ...

    21. Set currentURL to locationURL.

    22. Let fragment directive be the result of running remove the fragment directive on locationURL.

    23. Set entry’s URL to currentURL.

    24. Set entry’s URL to locationURL.

    25. Set entry’s directive state's value to fragment directive.

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

    27. ...

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

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

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

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

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'

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

3.3.2. 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 directive state to apply the directives associated with a session history entry to a Document.

Monkeypatching DOM § 4.5 Interface Document:

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

In the definition of update document for history step application:

Monkeypatching HTML § 7.4.6.2 Updating the document:

To update document for history step application given a Document document, a session history entry entry,...

1. ...

4. Set document’s history object’s length to scriptHistoryLength

5. If documentsEntryChanged is true, then:

   1. Let oldURL be document’s latest entry’s URL.

   2. If document’s latest entry’s directive state is not entry’s directive state then set document’s uninvoked directives to entry’s directive state's value.

   3. Set document’s latest entry to entry

   4. ...

3.3.3. Parsing the fragment directive

3.3.4. Fragment directive grammar

An ASCII string is a valid fragment directive if it matches the production:

FragmentDirective ::=

(TextDirective | UnknownDirective) ("&" FragmentDirective)?

UnknownDirective ::=

CharacterString

CharacterString ::=

(ExplicitChar | PercentEncodedByte)+

ExplicitChar ::=

[a-zA-Z0-9] | "!" | "$" | "'" | "(" | ")" | "*" | "+" | "." | "/" | ":" | ";" | "=" | "?" | "@" | "_" | "~" | "," | "-"

An ExplicitChar may be any URL code point other than "&".

TextDirective ::=

"text=" TextDirectiveParameters

TextDirectiveParameters ::=

(TextDirectivePrefix ",")? TextDirectiveString ("," TextDirectiveString)? ("," TextDirectiveSuffix)?

TextDirectivePrefix ::=

TextDirectiveString"-"

TextDirectiveSuffix ::=

"-"TextDirectiveString

TextDirectiveString ::=

(TextDirectiveExplicitChar | PercentEncodedByte)+

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.

PercentEncodedByte ::=

"%" [a-zA-Z0-9][a-zA-Z0-9]

3.4. Text Directives

A text directive is a kind of directive representing a range of text to be indicated to the user. It 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.

3.4.1. Invoking Text Directives

This section describes how text directives in a document’s uninvoked directives are processed and invoked to cause indication of the relevant text passages.

In indicated part, enable a fragment to indicate a range. Make the following changes:

Monkeypatching HTML § 7.4.6.3 Scrolling to a fragment:

For an HTML document document, the following processing model must be followed to determine its indicated part:

1. Let directives be the document’s uninvoked directives.

2. If directives is non-null and document’s allow text fragment scroll is true then:

   1. Let ranges be a list that is the result of running the invoke text directives steps with directives and the document.

   2. If ranges is non-empty, then:

      1. Let firstRange be the first item of ranges.

      2. Visually indicate each range in ranges in an implementation-defined way. The indication must not be observable from author script. See § 3.7 Indicating The Text Match.

         The first range in ranges is the one that gets scrolled into view but all ranges should be visually indicated to the user.

      3. Set firstRange as document’s indicated part, return.

3. Let fragment be document’s URL’s fragment.

4. If fragment is the empty string, then return the special value top of the document.

5. Let potentialIndicatedElement be the result of finding a potential indicated element given document and fragment.

6. ...

In scroll to the fragment, handle a indicated part that is a range and also prevent fragment scrolling if the force-load-at-top policy is enabled. Make the following changes:

Monkeypatching HTML § 7.4.6.3 Scrolling to a fragment:

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 or it is a range.

   2. Let scrollTarget be document’s indicated part.

   3. Let target be scrollTarget.

   4. If target is a range, then:

      1. Set target to be the first common ancestor of target’s start node and end node.

      2. 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. Assert: target is an element.

   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.

      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.

   9. Let blockPosition be "center" if scrollTarget is a range, "start" otherwise.

      Scrolling to a text directive centers it in the block flow direction.
   10. Scroll target into view, with behavior set to "auto", block set to "start", and inline set to "nearest".
   10. scroll a target into view, with target set to scrollTarget, behavior set to "auto", block set to blockPosition, and inline set to "nearest".

       Implementations MAY avoid scrolling to the target if it is produced from a text directive.

   11. Run the focusing steps for target, 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.

   12. Move the sequential focus navigation starting point to target.

The next two monkeypatches ensure the user agent clears uninvoked 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 try to scroll to the fragment:

Monkeypatching HTML § 7.4.6.3 Scrolling to a fragment:

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. 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.
   1. If the user agent has reason to believe the user is no longer interested in scrolling to the fragment, then:

      1. Set uninvoked directives to null.

      2. Abort these steps.

   2. If the document has no parser, or its parser has stopped parsing, then:

      1. If uninvoked directives is not null, then:

         1. Set uninvoked directives to null.

         2. Scroll to the fragment given document.

      2. Abort these steps.

   3. Scroll to the fragment given document.

   4. If document’s indicated part is still null, then try to scroll to the fragment for document. Otherwise, set uninvoked directives to null.

In the definition of navigate to a fragment:

Monkeypatching HTML § 7.4.2.3.3 Fragment navigations:

To navigate to a fragment given navigable navigable, ...:

1. ...

8. Update document for history step application given navigable’s active document, historyEntry, true, scriptHistoryIndex, and scriptHistoryLength.

9. Scroll to the fragment given navigable’s active document.

10. Set navigable’s active document’s uninvoked directives to null.

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:

Monkeypatching HTML § 7.4.2.3.3 Fragment navigations:

Rename HTML § 7.4.2.3.3 Fragment navigations and related steps to "indicating a fragment" to reflect its broader effects.

3.5. Security and Privacy

3.5.1. Motivation

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

  • This isn’t strictly true, Chrome allows this for same-origin initiators. Need to update the spec on this point. [Issue #WICG/scroll-to-text-fragment#240]

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

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

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.

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

For this reason, the implementation must ensure the runtime of § 3.6 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.5.4. Restricting the Text Fragment

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

Monkeypatching [FETCH]:

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

Monkeypatching [HTML]:

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

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

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

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

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

Monkeypatching [HTML]:

15. Set document’s text directive 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 directive user activation of navigationParam’s request object is true, set the document’s text directive 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.

16. Set document’s allow text fragment scroll by following these sub-steps:

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

    2. Let text directive user activation be the value of document’s text directive user activation and set document’s text directive 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 directive 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 directive user activation to the value of the active document's text directive user activation and set the active document's value to false.

Monkeypatching [HTML]:

2. 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 directive user activation to sourceBrowsingContext’s active document’s text directive user activation. Set sourceBrowsingContext’s active document’s text directive 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.

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

Need to decide how force-load-at-top interacts with the Navigation API. [Issue #WICG/scroll-to-text-fragment#242]

Amend the restore persisted state steps to take a new boolean parameter which suppresses scroll restoration:

Monkeypatching [HTML]:

To restore persisted state from a session history entry entry , and boolean suppressScrolling:

1. If entry’s scroll restoration mode is "auto", suppressScrolling is false, 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 update document for history step application steps to check the force-load-at-top policy and avoid scrolling in a new document if it’s set.

Monkeypatching [HTML]:

1. ...

4. Set document’s history object’s length to scriptHistoryLength.

5. Let scrollingBlockedInNewDocument be the result of getting the policy value for force-load-at-top for document.

6. If documentsEntryChanged is true, then:

   1. Let oldURL be document’s latest entry’s URL.

   2. ...

   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 and suppressScrolling set to false.

      4. If oldURL’s fragment is not equal to...

   6. Otherwise,

      1. Assert: entriesForNavigationAPI is given.

      2. Restore persisted state given entry and scrollingBlockedInNewDocument.

      3. Initialize the navigation API entries for a new document given navigation, entriesForNavigationAPI, and entry.

7. If documentIsNew is true, then:

   1. If scrollingBlockedInNewDocument is false, try to scroll to the fragment for document.

   2. At this point scripts may run for the newly-created document document.

8. Otherwise, if documentsEntryChanged is false and doNotReactivate is false, then:

   1. ...

3.6. Navigating to a Text Fragment

3.6.1. Finding Ranges in a Document

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

text=prefix-,foo
text=bar,baz

:~:text=The quick,lazy dog

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

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

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

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.

3.6.2. Word Boundaries

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.

3.7. 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 any methods observable by author script, such as the Document’s selection, 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.

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

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 few common examples are provided below.

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

Document-Policy: force-load-at-top

Fragment-based scroll blocking from this policy is specified in an amendment to the scroll to the fragment algorithm in the § 3.6 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:

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

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.

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.

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.

4.2. 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="section">HEADER</div>
<div class="content">Text to quote</div>

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

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:

• The UA determines the quoted text is ambiguous
• The quoted text contains 3 or fewer words

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

The earliest known tool for use in computation is the Sumerian abacus

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

By the late 1960s, computer systems could perform symbolic algebraic
manipulations