From 4b8e0b694ebe337ad446ffa2a92c9a74376495d2 Mon Sep 17 00:00:00 2001
From: Dominic Farolino Node interfaceNode interface, and its length conceptNodeList interfaceProcessingInstruction interfaceShadowRoot interface
directive state, which is a directive + state-or-null, initially a new directive state.
A directive state is a struct that holds the value of a fragment + directive at the time a session history entry is created. It is used to invoke + directives, such as text highlighting, whenever the entry is traversed. It has:
+ +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.
+Let fragment directive be the result of running remove the fragment + directive on url.
Let directive state be a new directive state with its value set to fragment directive.
Let historyEntry be a new session history entry, with its URL set to url and its document state set to - documentState.
Let navigationParams be null.
Let directive state be navigable's active session history entry's directive state.
Let fragment directive be the result of running remove the fragment + directive on url.
If fragment directive is not null, then set directive state to a new + directive state whose value is set to + fragment directive.
+ +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.
+Let navigation be navigable's active window's navigation API.
Let activeEntry be navigable's active session history entry.
Let fragment directive be the result of running remove the fragment + directive on newUrl.
Let newEntry be a new session history entry, with
@@ -107820,6 +107889,9 @@ location.href = '#foo';Increment document's history object's index.
Set document's history object's length to its index + 1.
Set document's history object's length to its index + 1.
+ +These are temporary best-guess values for immediate synchronous access.
+These are temporary best-guess values for immediate synchronous access.
+If newURL does not equal + activeEntry's URL with exclude fragments set to true, or if fragment directive is not null, + then set newEntry's directive state be a + new directive state whose value is + fragment directive.
+ +We limit diverging newEntry's directive state from that of activeEntry's to + these conditions, so that simple fragment changes to activeEntry's URL that don't specify a fragment directive continue to + reuse the existing one, as to not clobber existing highlights or other user interface + indications.
+Otherwise, if fragment directive is not null, then set newEntry's + directive state's value to fragment directive.
If serializedData is not null, then restore the history object state given document and newEntry.
Set currentURL to locationURL.
Let fragment directive be the result of running remove the fragment + directive on locationURL.
Set entry's URL to currentURL.
Set entry's directive state's value to fragment directive.
Let oldURL be document's latest entry's URL.
If document's latest entry's directive state is not entry's directive state, then set document's + pending text directives to the result of parsing entry's directive + state's value.
Set document's latest entry to entry.
Restore the history object state given document and @@ -110911,6 +111024,37 @@ location.href = '#foo'; url with exclude fragments set to true, then return null.
Let text directives be document's pending text directives.
If text directives is non-null:
+ +Let ranges be the result of running the invoke text directives + steps, given text directives and document.
If ranges is not empty:
+ +Let firstRange by ranges[0].
Visually indicate each range in ranges in an + implementation-defined way. The indication must not be observable from author + script. See Text directive security and + privacy considerations.
+ +Only the first range in ranges gets scrolled into + view, but all ranges will be visually indicated to the user.
+Return firstRange.
Let fragment be url's fragment.
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.
+ +With text directives, browsers may implement an option to 'Copy URL to here' when the user opens the context menu on a text selection. The browser can then generate a URL with the text selection appropriately specified, and the recipient of the URL will have the specified text conveniently indicated. Without text fragments, if a user wants to share a passage of text from a page, they would likely just copy and paste the passage, in which case the receiver loses the context of the page.
+ +This specification attempts to maximize the useful lifetime of text directive links, for example, by + using the actual text content as the URL payload, and allowing a fallback element-id fragment. + However, pages on the web often update and change their content. As such, links like this may "rot" + in that the text content they point to no longer exists on the destination page.
+ +Text directive links can be useful despite this problem. In user sharing use cases, the link is + often transient, intended to be used only within a short time of sending. For longer duration use + cases, such as references and web page links, text directives are still valuable since they degrade + gracefully into an ordinary link. Additionally, the presence of a stale text directive can be useful + information to surface to a user, to help them understand the link creator's original intent and + that the page content may have changed since the link was created.
+ + + See [[#generating-text-fragment-directives]] for best practices on how to create robust text + directive links. + +This section describes the mechanism by which the fragment directive is hidden from script and how it fits into [[HTML#navigation-and-session-history]].
+ +Session history entries now include a new "directive state" item.
All new entries are created with a directive state with an empty value. If the new URL + includes a fragment directive it will be written to the state's value (otherwise it remains + null).
Any time a URL potentially including a fragment directive is written to a session history + entry, extract the fragment directive from the URL and store it in a directive state item of the + entry. There are four such points where a URL can potentially include a directive:
+ +In the "navigate" steps for typical cross-document navigations.
In the "navigate to a fragment" steps for fragment based same-document + navigations.
In the "URL and history update steps" for synchronous updates such as + pushState/replaceState.
In the "create navigation params by fetching" steps for URLs coming from a + redirect.
Same-document navigations that change only the fragment, and the new URL doesn't specify a + directive, will create an entry whose directive state refers to the previous entry's directive + state.
Since a Document is populated from a session history entry, its URL will not include the fragment directive. Similarly,
+ since the Location object is a representation of the active document's
+ URL, all getters on it will produce a
+ fragment-directive-stripped version of the URL.
Additionally, since the HashChangeEvent is fired
+ in response to a changed fragment between URLs of session history entries,
+ hashchange will not be fired if a navigation or traversal
+ changes only the fragment directive.
Consider the below examples, which help clarify various edge cases.
+ +
+window.location = "https://example.com#page1:~:hello";
+console.log(window.location.href); // 'https://example.com#page1'
+console.log(window.location.hash); // '#page1'
+
+
+ The initial navigation created a new session history entry. The entry's URL is stripped of the + fragment directive: "https://example.com#page1". The entry's directive state value is set to + "hello". Since the document is populated from the entry, web APIs don't include the fragment + directive in URLs.
+ +
+location.hash = "page2";
+console.log(location.href); // 'https://example.com#page2'
+
+
+ A same document navigation changed only the fragment. This adds a new session history entry in the + navigate to + a fragment steps. However, since only the fragment changed, the new entry's directive state + points to the same state as the first entry, with a value of "bar".
+ +
+ onhashchange = () => console.assert(false, "hashchange doesn't fire.");
+ location.hash = "page2:~:world";
+ console.log(location.href); // 'https://example.com#page2'
+ onhashchange = null;
+
+
+ A same document navigation changes only the fragment but includes a fragment directive. Since an + explicit directive was provided, the new entry includes its own directive state with a value of + "fizz".
+ +The hashchange event is not fired since the page-visible fragment is unchanged; only the fragment + directive changed. This is because the comparison for hashchange is done on the URLs in the + session history entries, where the fragment directive has been removed.
+ +
+ history.pushState("", "", "page3");
+ console.log(location.href); // 'https://example.com/page3'
+
+
+ pushState creates a new session history entry for the same document. However, since the + non-fragment URL has changed, this entry has its own directive state with value currently null.
+In other cases where a URL is not set to a session history entry, there is no fragment directive stripping.
+ +For URL objects:
+ +
+let url = new URL('https://example.com#foo:~:bar');
+console.log(url.href); // 'https://example.com#foo:~:bar'
+console.log(url.hash); // '#foo:~:bar'
+
+document.url = url;
+console.log(document.url.href); // 'https://example.com#foo:~:bar'
+console.log(document.url.hash); // '#foo:~:bar'
+
+
+ The a or area elements:
+<a id='anchor' href="https://example.com#foo:~:bar">Anchor</a>
+<script>
+ console.log(anchor.href); // 'https://example.com#foo:~:bar'
+ console.log(anchor.hash); // '#foo:~:bar'
+</script>
+
+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 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 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.
+ +The only directive introduced in this spec is the text directive but others could be added in the future.
+ +"https://example.com#:~:text=foo&text=bar&unknownDirective" Contains 2 text directives and one unknown 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.
+ +A text directive is a kind of directive representing a range of text to + be indicated to the user. It is a struct consisting of four strings:
+ +a non-empty string
null or a non-empty string
null or a non-empty string
null or a non-empty string
Each Document has a pending text directives which is either a
+ list of text directives or null, initially
+ null.
A text directive is specified in 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, then 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.
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".
To parse a text directive, on a string text directive value, + perform the following steps. They return a text directive-or-null.
+ +This algorithm takes a single text directive value string as input (e.g., + "prefix-,foo,bar") and attempts to parse the string into the components of the directive (e.g., + ("prefix", "foo", "bar", null)). See [[#syntax]] for the what each of these components means and + how they're used.
+ +Let prefix, suffix, start, and end each be + null.
Assert: text directive value is an ASCII string + with no code points in the fragment percent-encode set and no instances of U+0026 + AMPERSAND character (&).
Let tokens be a list of strings that + result from strictly splitting text directive + value on U+002C (,).
If tokens has size less than 1 or greater than 4, then return null.
If the first item of tokens ends with U+002D (-):
+ +Set prefix to the substring of + tokens[0] from 0 with length tokens[0]'s length - 1.
Remove the first item of tokens.
If prefix is the empty string or contains any instances of U+002D (-), then return null.
If tokens is empty, then return null.
If the last item of tokens starts with U+002D (-):
+ +Set suffix to the substring of the last item of tokens from 1 to the end of the string.
Remove the last item of tokens.
If suffix is the empty string or contains any instances of U+002D (-), then return null.
If tokens is empty, then return null.
If tokens has size greater than 2, then return null.
Assert: tokens has size 1 or 2.
Set start to the first item in tokens.
Remove the first item of tokens.
If start is the empty string or contains any instances of U+002D (-), then return null.
If tokens is not empty:
+ +Set end to the first item in tokens.
If end is the empty string or contains any instances of U+002D (-), return null.
Return a new text directive, with
+ +To percent-decode a text directive term given an ASCII string-or-null term, perform the following steps. They return a string-or-null.
+ +If term is null, then return null.
Let decoded bytes be the result of percent-decoding term.
Return the result of running UTF-8 decode without BOM on decoded bytes.
To parse the fragment directive, given an ASCII string fragment directive, perform the following steps. They return a list of text directives parsed from fragment directive.
+ +Let directives be the result of strictly splitting fragment directive on U+0026 AMPERSAND character (&).
Let output be an empty list.
For each directive in directives:
+ +If directive does not start with "text=", then continue
Let text directive value be the code point substring from 5 to the end of directive.
+ +Note: this might be the empty string.
+Let parsed text directive be the result of parsing text directive value.
If parsed text directive is non-null, append it to output.
Return output.
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:
+ +Let raw fragment be equal to url's fragment.
Let fragment directive be null.
If raw fragment is non-null and contains the fragment directive delimiter as a substring:
+ +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.
Let new fragment be the code point substring by positions of raw fragment from the start of raw fragment to position.
Advance position by the code point length of the fragment directive delimiter.
If position does not point past the end of raw fragment, then set fragment directive to the code point substring to the end of the string raw fragment starting from position.
Set url's fragment to new fragment.
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".
This section outlines several algorithms and definitions that specify how to turn a full fragment directive string into a list of Range objects.
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 the match in the document. The invoke text directives + 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 invoke text directives, given a list of text directives text directives and a Document
+ document, perform these steps:
Let ranges be a list of Range objects, initially
+ empty.
For each directive of text + directives, if the result of running find a range from a text directive given + directive and document is non-null, then append directive to ranges.
Return ranges.
Maybe describe what this next set of algorithms and primitives do.
+ +This algorithm takes as input a successfully parsed text directive and a + document in which to search. It returns a [=range=] that points to the first + text passage within the document that matches the searched-for text and + satisfies the surrounding context. Returns null if no such passage exists.
+ + + [=text directive/end=] can be null. If omitted, this is an "exact" + search and the returned [=range=] will contain a string exactly matching + [=text directive/start=]. If [=text directive/end=] is + provided, this is a "range" search; the returned [=range=] will start with + [=text directive/start=] and end with + [=text directive/end=]. In the normative text below, we'll call a + text passage that matches the provided [=text directive/start=] and + [=text directive/end=], regardless of which mode we're in, the + "matching text". + + Either or both of [=text directive/prefix=] and + [=text directive/suffix=] can be null, in which case context on that + side of a match is not checked. E.g. If [=text directive/prefix=] is + null, text is matched without any requirement on what text precedes it. +:~:text=The quick,lazy dogwill fail to match in + + ``` +
To find a range from a text directive, given a text directive parsedValues and Document document, run the following steps:
+
+
Let searchRange be a range with start + (document, 0) and end (document, document's length).
While searchRange is not collapsed:
+ +Let potentialMatch be null.
If parsedValues's prefix is not null:
+ +Let prefixMatch be the result of running the find a string in + range steps with parsedValues's prefix, searchRange, true, false, and false.
If prefixMatch is null, then return null.
Set searchRange's start to the + first boundary point after prefixMatch's start.
Let matchRange be a range whose start is + prefixMatch's end and end is + searchRange's end.
Advance matchRange's start to the next + non-whitespace position.
If matchRange is collapsed return null.
+ +Assert: matchRange's start node is a Text node.
Let mustEndAtWordBoundary be true if parsedValues's end is non-null or parsedValues's suffix is null, false otherwise.
Set potentialMatch to the result of running the find a string in + range steps with parsedValues's start, matchRange, false, mustEndAtWordBoundary, and true.
If potentialMatch is null, then continue.
+ +Otherwise:
+ +Let mustEndAtWordBoundary be true if parsedValues's end is non-null or parsedValues's suffix is null, false otherwise.
Set potentialMatch to the result of running the find a string in + range steps with parsedValues's start, searchRange, + true, mustEndAtWordBoundary, and false.
If potentialMatch is null, return null.
Set searchRange's start to the + first boundary point after + potentialMatch's start.
Let rangeEndSearchRange be a range whose start + is potentialMatch's end and whose end is + searchRange's end.
While rangeEndSearchRange is not collapsed:
+ +If parsedValues's end item is non-null, then:
+ +Let mustEndAtWordBoundary be true if parsedValues's suffix is null, false otherwise.
Let endMatch be the result of running the find a string in + range steps with parsedValues's end, rangeEndSearchRange, + true, mustEndAtWordBoundary, and false.
If endMatch is null then return null.
Set potentialMatch's end to endMatch's + end.
Assert: potentialMatch is non-null, not + collapsed and represents a range exactly containing an instance of matching + text.
If parsedValues's suffix is null, return + potentialMatch.
Let suffixRange be a range with start equal + to potentialMatch's end and end equal to + searchRange's end.
Advance suffixRange's start to the next + non-whitespace position.
Let suffixMatch be result of running the find a string in range + steps with parsedValues's suffix, + suffixRange, false, true, and true.
If suffixMatch is non-null, return potentialMatch.
If parsedValues's end is null and suffixMatch is null, then break.
+ +Set rangeEndSearchRange's start to + potentialMatch's end.
+ +If rangeEndSearchRange is collapsed:
+ +Assert: parsedValues's end item is + non-null.
Return null.
+ +Return null.
To advance a range range's start to the next non-whitespace position, run these steps:
+ +While range is not collapsed:
+ +Let node be range's start node.
Let offset be range's start offset.
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:
+ +Set range's start node to the next node, in shadow-including tree order.
Set range's start offset to 0.
Continue.
If the Text/substring data of node at offset offset and count 6 is equal to the string " " then:
Add 6 to range's start offset.
Otherwise, if the Text/substring data of node at offset offset and count 5 is equal to the string " " then:
+ +Add 5 to range's start offset.
Otherwise:
+ +Let cp be the code point at the offset index in node's CharacterData/data.
If cp does not have the White_Space property set, then return.
Add 1 to range's start offset.
To find a string in range given a string query, a + range searchRange, and three booleans wordStartBounded, + wordEndBounded and matchMustBeAtBeginning, 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 or end at word boundaries (see [[#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:
+
+ abcde
+
+
+ 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.
+While searchRange is not collapsed:
+ +Let curNode be searchRange's start node.
If curNode is part of a non-searchable subtree:
+ +Set searchRange's start node to the next node, in shadow-including tree order, that isn't a shadow-including descendant of curNode.
Set searchRange's start offset to 0.
Continue.
If curNode is not a visible text node:
+ +Set searchRange's start node to the next node, in shadow-including tree order, that is not a doctype.
Set searchRange's start offset to 0.
Continue.
Let blockAncestor be the nearest block ancestor of curNode.
Let textNodeList be a list of Text nodes, initially empty.
While curNode is a shadow-including descendant of + blockAncestor and the position of the boundary point + (curNode, 0) is not after + searchRange's end:
+ +If curNode has block-level display, then break.
If curNode is search invisible:
+ +Set curNode to the next node, in shadow-including tree order, that isn't a shadow-including descendant of curNode.
Continue.
If curNode is a visible text node then append it to textNodeList.
Set curNode to the next node in shadow-including tree order.
Run the find a range from a node list steps given query, + searchRange, textNodeList, wordStartBounded, + wordEndBounded and matchMustBeAtBeginning as input. If the resulting + range is not null, then return it.
If matchMustBeAtBeginning is true, return null.
If curNode is null, then break.
Assert: curNode follows searchRange's start node.
Set searchRange's start to the boundary point (curNode, 0).
Return null.
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.
The choice of action can have implications for user security and privacy. See the security and privacy sectionfor details.
+ +Care must be taken when implementing text directives 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.
+ +This section describes some of the attacks that could be executed with the help of text directives, and the navigation processing model changes that + restrict this feature to mitigate said attacks. In summary, text directives are restricted to:
+ +top-level traversables.
+ +This isn't strictly true, Chrome allows this for same-origin initiators. Need to + update the spec on this point. See 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)
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 might be able to infer the success or failure of the fragment search based on the order of requests for DNS lookup.
+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.
+ +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.
+ +The restrictions in [[#restricting-the-text-fragment]] prevent this specific case; in particular, the no-same-document-navigation restriction. However, these restrictions are provided as multiple layers of defence.
+For this reason, the implementation must ensure the runtime of [[#navigating-to-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.
+ + TODO: Consider another section describing the normative, algorithmic changes made elsewhere that support the security and privacy considerations discussed here, but do not include those changes here obviously. + + + + + + +Refresh` headerThe `Refresh` HTTP response header is the HTTP-equivalent
From ae6e6b056915b9a6dcc57da290e5fe92a4fdf7b4 Mon Sep 17 00:00:00 2001
From: Dominic Farolino CharacterData node and its
- replace data algorithm
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.
+With text directives, browsers may implement an option to 'Copy URL to here' when the user opens the context menu on a text selection. The browser can then generate a URL with the text selection appropriately specified, and the recipient of the URL will have the specified text conveniently indicated. Without text fragments, if a user wants to share a passage of text from a page, they would likely just copy and paste the passage, in which case the receiver loses the context of the page.
+ + +Text directives add support for specifying a text snippet + in a URL fragment. When navigating to a URL whose fragment contains a text directive, the user + agent can quickly emphasize the captured text on the page, bringing it to the user's + attention.
+ +The core use case for text directives is to allow URLs to + serve as an exact text reference across the web. For example, Wikipedia URLs might link to the + exact text they are quoting from a page. Similarly, search engines can serve URLs that embed text directives that direct the user to the content they are + looking for in the page, rather than just linking to the top of the page.
+ +This section defines how text directives are parsed, constructed, and "invoked", which is the process of finding the text encapsulated + by the directive, in a document.
+ +With text directives, browsers may implement an option to + "Copy URL to this text" when the user engages with various UI components, such as a context menu + referring to 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 directives, 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 recipient loses the context of the page.
This specification attempts to maximize the useful lifetime of text directive links, for example, by - using the actual text content as the URL payload, and allowing a fallback element-id fragment. - However, pages on the web often update and change their content. As such, links like this may "rot" - in that the text content they point to no longer exists on the destination page.
+ -Text directive links can be useful despite this problem. In user sharing use cases, the link is - often transient, intended to be used only within a short time of sending. For longer duration use - cases, such as references and web page links, text directives are still valuable since they degrade - gracefully into an ordinary link. Additionally, the presence of a stale text directive can be useful +
However, pages on the web often update and change their content. As such, text + directive links may "rot" in that the text content they point to no longer exists on the + destination page. This specification attempts to maximize the useful lifetime of text + directive links by using the actual text content as the URL payload, and allowing a + fallback element-id fragment.
+ +In user sharing use cases, the link is often transient, intended to be used only within a short + time of sending. For longer duration use cases, such as references and web page links, text directives are still valuable since they degrade gracefully + into an ordinary link. Additionally, the presence of a stale text directive can be useful information to surface to a user, to help them understand the link creator's original intent and that the page content may have changed since the link was created.
- - See [[#generating-text-fragment-directives]] for best practices on how to create robust text - directive links. +See the Generating text fragment directives + section for best practices on how to create robust text directive links.
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.
The choice of action can have implications for user security and privacy. See the security and privacy section for details.
+ +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.
- TODO: Should this contain content about "indicating a match"? +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.
+ +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.
+ +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, then the URL should reflect this by removing 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 in the subsections 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.
+ +The location bar's URL should include a text fragment while it is visually + indicated. The fragment directiveshould 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.
+ +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.
+ +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.
@@ -114987,12 +115114,12 @@ console.log(document.url.hash); // '#foo:~:bar'"#:~: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.
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.
To parse a text directive, on a string text directive value, perform the following steps. They return a text directive-or-null.
@@ -115109,7 +115239,9 @@ console.log(document.url.hash); // '#foo:~:bar' +To percent-decode a text directive term given an ASCII string-or-null term, perform the following steps. They return a string-or-null.
Return the result of running UTF-8 decode without BOM on decoded bytes.
To parse the fragment directive, given an ASCII string fragment directive, perform the following steps. They return a list of text directives parsed from fragment directive.
Return output.
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:
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".
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".
This section outlines several algorithms and definitions that specify how to turn a full fragment directive string into a list of Range objects.
If a directive was not matched, it does not add an item to the returned list.
+To invoke text directives, given a list of text directives text directives and a Document
document, perform these steps:
Return ranges.
To find a range from a text directive, given a text directive parsedValues and Document document, run the following steps:
Return null.
To advance a range range's start to the next non-whitespace position, run these steps:
If the Text/substring data of node at offset offset and count 6 is equal to the string " " then:
If the substring data of node at offset offset and count 6 is equal to the string " " then:
Add 6 to range's start offset.
Otherwise, if the Text/substring data of node at offset offset and count 5 is equal to the string " " then:
+Otherwise, if the substring data of node at offset offset and count 5 is equal to the string " " then:
Add 5 to range's start offset.
Otherwise:
Let cp be the code point at the offset index in node's CharacterData/data.
Let cp be the code point at the offset index in node's data.
If cp does not have the White_Space property set, then return.
To find a string in range given a string query, a range searchRange, and three booleans wordStartBounded, wordEndBounded and matchMustBeAtBeginning, run these steps:
@@ -115576,7 +115717,7 @@ Add a helper algorithm for removing and returning a fragment directive string frIf curNode is not a visible text node:
Set searchRange's start node to the next node, in shadow-including tree order, that is not a doctype.
Set searchRange's start node to the next node, in shadow-including tree order, that is not a DocumentType node.
Set searchRange's start offset to 0.
If curNode is null, then break.
Assert: curNode follows searchRange's start node.
Assert: curNode is following searchRange's start node.
Set searchRange's start to the boundary point (curNode, 0).
Return null.
A node is search invisible if it is an element in the HTML namespace and meets any of the following conditions:
- domfarolino FROM HERE +the computed value of its 'display' property is 'none';
if the node serializes as void;
if the node is any of the following types: HTMLIFrameElement, HTMLImageElement, HTMLMeterElement, HTMLObjectElement, HTMLProgressElement, HTMLStyleElement, HTMLScriptElement, HTMLVideoElement, HTMLAudioElement; or
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:
+if the node 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:
Providing visual emphasis or highlight of the text passage.
Let curNode be node.
Automatically scrolling the passage into view when the page is navigated.
While curNode is non-null.
-Activating a UA's find-in-page feature on the text passage.
If curNode is not a Text node and it has block-level display then return curNode.
Providing a "Click to scroll to text passage" notification.
Otherwise, set curNode to curNode's parent.
Providing a notification when the text passage isn't found in the page.
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, wordEndBounded and matchMustBeAtBeginning, follow these steps:
+
+
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). See this issue.
+Let searchStart be 0.
If the first item in nodes is searchRange's start node, then set searchStart to searchRange's start offset.
Let start and end be boundary points, initially null.
Let matchIndex be null.
The choice of action can have implications for user security and privacy. See the security and privacy sectionfor details.
+While matchIndex is null.
+ +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]].
+ +Note: Intuitively, this is a case-insensitive search also ignoring accents, umlauts, and other marks.
+If matchIndex is null, return null.
If matchMustBeAtBeginning is true and matchIndex is not 0, return null.
Let endIx be matchIndex + queryString's length.
+ +Note: endIx is the index of the last character in the match + 1.
+Set start to the boundary point result of get boundary point at index matchIndex run over nodes with isEnd false.
Set end to the boundary point result of get boundary point at index endIx run over nodes with isEnd true.
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 boundary point/node as the locale:
+ +Set searchStart to matchIndex + 1.
Set matchIndex to null.
Let endInset be 0.
If the last item in nodes is searchRange's end node then set endInset to (searchRange's end node's length − searchRange'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.
+If matchIndex + queryString's length is greater than searchBuffer's length − endInset return null.
+ +Assert: start and end are non-null, valid boundary points in searchRange.
Return a range with start start and end end.
Optionally, this will only return a match if the matched text begins or ends on a word boundary. For example, the query string "range" will always match in "mountain range", but:
+ +When requiring a word boundary at the beginning, it will not match in "color orange".
When requiring a word boundary at the end, it will not match in "forest ranger".
See [[#word-boundaries]] for details and more examples.
+Optionally, this will only return a match if the matched text is at the beginning of the node list.
+ +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.
+Let counted be 0.
For each curNode of nodes:
+ +Let nodeEnd be counted + curNode's length.
If isEnd is true, add 1 to nodeEnd.
If nodeEnd is greater than index, then return the boundary point (curNode, index − counted).
Increment counted by curNode's length.
Return null.
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 [[UAX29#Word_Boundaries]]. + [[UAX29#Default_Word_Boundaries]] defines a default set of what constitutes a word boundary, but + as the specification mentions, a more sophisticated algorithm should be used based on the + locale.
+ +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.
+An impressive mountain range" but not within "An impressive
+ mountain ranger".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.
+ +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. ++ + 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?
+ +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.
+ +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 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:
+ +The UA determines the quoted text is ambiguous.
The quoted text contains 3 or fewer words.
TODO: Determine the numeric limit above in less arbitrary way.
+ +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.
+ +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 +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.
- TODO: Consider another section describing the normative, algorithmic changes made elsewhere that support the security and privacy considerations discussed here, but do not include those changes here obviously. +However, pages on the web often update and change their content. As such, text - directive links may "rot" in that the text content they point to no longer exists on the - destination page. This specification attempts to maximize the useful lifetime of text - directive links by using the actual text content as the URL payload, and allowing a - fallback element-id fragment.
+Page on the web often update and change their content. As such, text directive + links may "rot" in that the text content they point to no longer exists on the destination page. + This specification attempts to maximize the useful lifetime of text directive links + by using the actual text content as the URL payload, and allowing a fallback element-id + fragment.
In user sharing use cases, the link is often transient, intended to be used only within a short time of sending. For longer duration use cases, such as references and web page links, See the Generating text fragment directives section for best practices on how to create robust text directive links.
-This section describes the mechanism by which the fragment directive is hidden from script and how it fits into [[HTML#navigation-and-session-history]].
- -Session history entries now include a new "directive state" item.
All new entries are created with a directive state with an empty value. If the new URL - includes a fragment directive it will be written to the state's value (otherwise it remains - null).
Any time a URL potentially including a fragment directive is written to a session history - entry, extract the fragment directive from the URL and store it in a directive state item of the - entry. There are four such points where a URL can potentially include a directive:
- -In the "navigate" steps for typical cross-document navigations.
In the "navigate to a fragment" steps for fragment based same-document - navigations.
In the "URL and history update steps" for synchronous updates such as - pushState/replaceState.
This section describes how fragment directives are + exposed to script and updated across navigations.
-In the "create navigation params by fetching" steps for URLs coming from a - redirect.
When a URL including a fragment directive is written to a session history
+ entry, the directive is extracted from the URL and stored in the entry's directive state member. Importantly, since a
+ Document is populated from a session history entry, its URL will not include fragment directives. Similarly, since the Location
+ object is a representation of the active document's URL, all getters on it will produce a fragment
+ directive-stripped version of the URL.
Same-document navigations that change only the fragment, and the new URL doesn't specify a - directive, will create an entry whose directive state refers to the previous entry's directive - state.
Since a Document is populated from a session history entry, its URL will not include the fragment directive. Similarly,
- since the Location object is a representation of the active document's
- URL, all getters on it will produce a
- fragment-directive-stripped version of the URL.
In short, this ensures that fragment directives are + not exposed to script, and are rather tracked by internal mechanisms alongside script-exposed + URLs.
Additionally, since the HashChangeEvent is fired
@@ -114867,7 +114848,13 @@ new PaymentRequest(…); // Allowed to use
hashchange will not be fired if a navigation or traversal
changes only the fragment directive.
Consider the below examples, which help clarify various edge cases.
+Furthermore, same-document navigations that only change a URL's fragment without specifying a + new directive, create new session history entries + whose directive state refers to the previous entry's + directive state.
+ +Consider the below examples, which help clarify various edge cases of the above + implications.
From 5dfcccb790f7a16a1013a508bc820a9a798089cf Mon Sep 17 00:00:00 2001
From: Dominic Farolino
Date: Sun, 9 Nov 2025 12:24:00 +0900
Subject: [PATCH 4/7] Two more monkeypatches and supporting algorithms
---
source | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 102 insertions(+), 12 deletions(-)
diff --git a/source b/source
index 17a09e710aa..b841898406a 100644
--- a/source
+++ b/source
@@ -110734,15 +110734,34 @@ location.href = '#foo';
given document's relevant global object to run these steps:
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.
If the user agent has reason to believe the user is no longer interested in scrolling to + the fragment, then set document's + pending text directives to null and abort these steps.
If document has no parser, or its parser has stopped + parsing, then.
+ +If document's pending text directives is not null, then.
+ +Set document's pending text directives to null.
Scroll to the fragment given document.
Abort these steps.
Scroll to the fragment given document.
If document's indicated part is still null, then try to - scroll to the fragment for document.
Otherwise:
Assert: document's indicated part is an - element.
Assert: document's indicated part is an element or + a range.
Let scrollTarget be document's indicated part.
Let target be scrollTarget.
If target is a range, then:
+ +Set target to the first common ancestor of target's + start node and target's end node.
While target is not null and is not an element, set + target to target's parent.
+ +What should this do if target is inside a shadow tree? See WICG/scroll-to-text-fragment#190 + for discussion.
+Let target be document's indicated part.
Assert: target is an element.
Set document's target element to target.
Run the ancestor revealing algorithm on target.
Run the ancestor revealing algorithm on target.
+ +This currently won't work well with text
+ directives, since target could be an ancestor or even the root document
+ node. WICG/scroll-to-text-fragment#89
+ proposes restricting matches to "contain:style layout" blocks which
+ would resolve this problem.
Scroll target into view, - with behavior set to "auto", block set to "start", and inline - set to "nearest". CSSOMVIEW
Let blockPosition be "center" if scrollTarget
+ is a range, and "start" otherwise.
Scrolling to a text directive centers it in the block flow + direction.
+Scroll scrollTarget into + view, with behavior set to "auto", block set to blockPosition, + and inline set to "nearest". CSSOMVIEW
+ +Implementations may avoid scrolling to the target if it is produced from a text + directive.
+Run the focusing steps for target, with the
Document's viewport as the fallback target.
To find the first common ancestor of two nodes nodeA and + nodeB, follow these steps:
+ +Let commonAncestor be nodeA.
While commonAncestor is non-null and is not a + shadow-including inclusive ancestor of nodeB, let + commonAncestor be commonAncestor's + shadow-including parent.
Return commonAncestor.
To find the shadow-including parent of node follow these steps:
+ +If node is a shadow root, then return node's host.
Otherwise, return node's parent.
To find a range from a node list given a search string queryString, a range searchRange, a list of 8r!p@unc<;5|Gh>$rrI5agiZ_VZa
zSglXw%7MQW5YkWNcK?ZA^tv=036~B6nXhv|M@2;i1z-*2imbH5+*fMAt(YB__$_U0
zx<*IQ+vCZLK-`AnzI+XV5VBkPj|x2yD=RA(XxGpwq;o?-3N*@}K~`2e0&{Bt-gsU9
ztQu7dsiC0A=K35Q{G|2a{tXT;?&^As(CaeeI-40Z2=m)}pTrX{FE7jK5(4X~f`EmE
zg{RsY`3f1av9bRB{nClMZx2N0YVCADCM0Wn$jBh_dK^T81WG{q{dO9dg6jEm 2q+VNTia+(pTPr<19mC^bSV;f=I?+?Ds?tmh>ksD~ADXDLK>s;keND>rc4MX7
zax#yD=)+$eT0aTYzEyK)3N+H$)6Su#p~eWkk2A*oeS!C1bwOJd;5Dc%1_qU*qoY#B
z#@U0_mzS3_(|AD7aeJNQocI7d!RPlp(rI!4gtmZnx&f4b&~m()n2AqJJQr=Nz2+B(
z1^ME)x(TRmFsS`mfPAFzxIAB8LD>Z>a-gxZvnxT;d%ycRM*Qd8Text nodes nodes, and booleans wordStartBounded, wordEndBounded and matchMustBeAtBeginning, follow these steps:
From 5e2ec9d9a8e7ea1a14f2c478940251445b9ec1c9 Mon Sep 17 00:00:00 2001
From: Dominic Farolino }a74GpWw27UoaNqFcApk`4}41W983yKRS9$v^xL`3NpFKiB*X>m{&
zG4b&c6ctB3PTYV{zy(YYA1nzD{aGY1a<=cyZ_DLY0musI6Fs^UXv082e9Rg^WUYbv
zRqwb8z4yHs9v$ba~
zu%NxLOs>0YQU-)u~#3#*Q
z&|J1<7*r*3u0asblf0D)M}45ZK#rMPmNXNKB|KsYz0{^MK3b4_c}YI*Q40S~flUGX
zD+zrZcF1JGwjr6;!Opp3_zC(WU_f5gWR26%jS6bu^W(6~YgSHOLD58p3EVMOg8(6^8VM~3eA|Jn(}^S247Vq8G`Ye;=5EoM
zzWcU7