URLフラグメントテキストディレクティブ

1. インフラストラクチャ

この仕様はInfra Standardに依存しています。[INFRA]

2. はじめに

2.1. ユースケース

2.1.1. Webテキスト参照

2.1.2. ユーザー共有

2.2. リンクの有効期間

この仕様は、例えば実際のテキスト内容をURLのペイロードとして使用したり、フォールバックとして要素IDのフラグメントを許可することにより、テキストディレクティブリンクの有用な有効期間を最大化しようとしています。しかし、Web上のページはしばしば更新され、内容が変化します。そのため、このようなリンクは参照先のテキスト内容が目的のページから無くなってしまい「リンク切れ」を起こす場合があります。

この問題があってもテキストディレクティブリンクは有用です。ユーザー共有のユースケースでは、リンクは送信してから短期間のみ利用されることが多く、一時的なものです。参照やWebページのリンクのような長期間にわたって利用される場合でも、テキストディレクティブは通常のリンクに緩やかに劣化するので価値があります。また、古くなったテキストディレクティブがあることで、ユーザーがリンク作成者の意図やその後ページ内容が変わったことを理解する助けになります。

強固なテキストディレクティブリンクの作成方法については§ 4 テキストフラグメントディレクティブの生成を参照してください。

3. 説明

3.1. 指示

この仕様はユーザーエージェントがテキストの一致を「指示」する際に取るアクションを意図的に定義しません。ユーザーエージェントにより異なる体験やトレードオフが考えられます。可能なアクション例:

• テキスト部分を視覚的に強調またはハイライトする

• ページ移動時に自動的にその部分までスクロールする

• 該当テキスト部分でUAのページ内検索機能を起動する

• 「クリックしてテキスト部分へスクロール」通知の表示

• 該当テキスト部分がページ内に見つからない場合の通知の表示

3.2. 構文

テキストディレクティブは、フラグメントディレクティブ(§ 3.3 フラグメントディレクティブ参照)で次のフォーマットで指定されます:

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

(角括弧はオプションパラメータを示します)

テキストパラメータは一致前にパーセントデコードされます。テキストパラメータ内のダッシュ(-)、アンパサンド(&)、カンマ(,)はテキストディレクティブ構文の一部と解釈されないようパーセントエンコードされます。

唯一必須のパラメータはstartです。startだけが指定された場合、その正確なテキストが最初に出現する箇所がターゲットテキストとなります。

endパラメータも指定された場合、テキストディレクティブはページ内のテキスト範囲を示します。ターゲット範囲はstartの最初の出現から、その後に現れるendの最初の出現までの範囲です。これはstartに全体のテキスト範囲を指定するのと同じですが、長いテキストディレクティブでURLが肥大化するのを防げます。

3.2.1. コンテキスト用語

他の2つのオプションパラメータはコンテキスト用語です。プレフィックスの後やサフィックスの前にダッシュ(-)を置くことで指定し、startやendパラメータと区別します。任意のオプションパラメータの組み合わせが可能です。

コンテキスト用語はターゲットテキストフラグメントを区別するために使います。コンテキスト用語はフラグメント直前(プレフィックス)や直後(サフィックス)のテキストを指定でき、空白も許容されます。

コンテキスト用語はターゲットテキストフラグメントには含まれず、視覚的にも指示されません。

3.2.2. 双方向（BiDi）の考慮事項

URL文字列はASCIIエンコードなので、双方向テキストを組み込むサポートはありません。ただし、対象とするページ内容はLTR(左から右)、RTL(右から左)、あるいは両方(双方向/BiDi)となり得ます。このセクションは、仕様の規範的セクションで暗黙的に記述された挙動の直感的な説明を提供します。

テキストフラグメント内の各項目の文字は論理順序です。つまり、母語話者が読む順番（かつメモリ上の文字の格納順）です。

同様にprefixやstart用語は論理順で他の用語の前、suffixやendは論理順で後ろにあるテキストを特定します。

注:ユーザーエージェントは、表示時にURL文字列をUnicodeへ変換するなど、母語話者向けに視覚的な表示を工夫できますが、URLの文字列表現は純粋なASCIIのままです。

3.3. フラグメントディレクティブ

既存のURLフラグメントの利用と互換性の問題を避けるため、この仕様ではフラグメントディレクティブという概念を導入します。これはURLフラグメントのうち、フラグメントディレクティブ区切り子の後ろの部分であり、区切り子が現れなければnullになり得ます。

フラグメントディレクティブ区切り子は":~:"という文字列、すなわち3連続するU+003A(:)、U+007E(~)、U+003A(:)のコードポイントです。

フラグメントディレクティブは解析され、ユーザーエージェントに何らかのアクションを実行するよう指示するディレクティブとして個別に処理されます。一つのフラグメントディレクティブ内に複数のディレクティブを記述できます。

ページ動作への影響を避けるため、著者のスクリプトとの相互作用を防ぐ目的でスクリプトからアクセス可能なAPIではこれを削除します。これにより、将来新たなディレクティブを追加してもWeb互換性リスクを回避できます。

3.3.1. フラグメントディレクティブの抽出

このセクションでは、フラグメントディレクティブがスクリプトから隠される仕組みと、それがHTML § 7.4 ナビゲーションとセッション履歴にどのように組み込まれるかについて説明します。

HTML § 7.4.1 セッション履歴でディレクティブ状態を定義します:

HTML § 7.4.1 セッション履歴へのモンキーパッチ:

ディレクティブ状態 は、セッション履歴エントリ作成時のフラグメントディレクティブの値を保持し、エントリを辿るたびにテキストハイライトなどのディレクティブを起動するために使用されます。次の内容を持ちます:

• value：フラグメントディレクティブまたはnullのASCII文字列。初期値はnull。

ディレクティブ状態は、複数のセッション履歴エントリで共有される場合があります。

フラグメントディレクティブはURLから削除され、セッション履歴エントリにセットされる前にディレクティブ状態に格納されます。これにより、スクリプトAPIから見えなくなり、ページ動作に影響を与えずにディレクティブを指定できます。

ディレクティブは生の文字列ではなくディレクティブ状態オブジェクト内に格納されます。これは、同一のディレクティブ状態が複数の連続した履歴エントリで共有できるようにするためです。トラバース時、2つのエントリ間でディレクティブ状態が変化した場合のみ（＝新規ハイライト等が必要な時）ディレクティブが処理されます。

セッション履歴エントリの定義に、次を追加します:

HTML § 7.4.1.1 セッション履歴エントリへのモンキーパッチ:

セッション履歴エントリは以下の項目を持つ構造体です:

• ...

• 永続化ユーザー状態（実装依存・初期値null）

• ディレクティブ状態：ディレクティブ状態。初期値は新規ディレクティブ状態

URLからフラグメントディレクティブ文字列を削除・返却するヘルパーアルゴリズムを追加します:

[HTML]へのモンキーパッチ:

このアルゴリズムはURLのフラグメントをフラグメントディレクティブ区切り子手前までにします。戻り値のフラグメントディレクティブは区切り子以降すべての文字を含み、区切り子自体は含みません。

TODO: フラグメントが':~:'で終わる（空ディレクティブ）の場合、nullを返します。これは明示的ディレクティブ未指定扱い（既存を上書きしない）ですが、空文字列を返すべき？ '#:~:'へのnavigate/pushStateで明示的にディレクティブやハイライトを解除できるよう配慮する案。

フラグメントディレクティブを除去するには、URL url から、次の手順を実行する：

1. raw fragment に url のフラグメントを代入

2. fragment directive をnullにする

3. raw fragmentが非nullかつフラグメントディレクティブ区切り子を含む場合:

   1. position に、raw fragment内で区切り子が最初に現れるコードポイントの位置変数を代入。なければ末尾＋1。

   2. new fragment に、raw fragmentの先頭からposition直前までの部分文字列を代入。

   3. position を区切り子のコードポイント長だけ進める。

   4. positionがraw fragment末尾を超えていなければ:

      1. fragment directiveに、raw fragmentのposition以降の部分文字列をセット

   5. urlのフラグメントをnew fragmentにする

4. fragment directive を返す

https://example.org/#test:~:text=foo はフラグメントが"test"、フラグメントディレクティブが"text=foo"になるようにパースされます。

以降の4つのモンキーパッチは、フラグメントディレクティブが含まれる可能性があるURLでセッション履歴エントリ作成時に、フラグメントディレクティブを除去してディレクティブ状態へ保存する点を修正します。

navigateの定義では:

HTML § 7.4.2.2 ナビゲーション開始へのモンキーパッチ:

ナビゲーブルなnavigableをURLurlにナビゲートするには...:

1. ...

14. navigableのongoing navigationをnavigationIdに設定

15. urlのスキームが"javascript"なら...

16. 並列で次の手順を実行:

    1. ...

    5. urlがabout:blankならdocumentStateのoriginにinitiator originを設定

    6. そうでなくabout:srcdocならdocumentStateのoriginにnavigableの親のアクティブドキュメントoriginを設定

    7. historyEntryを新規セッション履歴エントリにし、そのURLをurl、document stateをdocumentStateに設定。
    7. fragment directiveにフラグメントディレクティブを削除をurlで実行した結果を代入。

    8. directive stateを新しいディレクティブ状態（valueにfragment directiveセット）として作成

    9. historyEntryを新規セッション履歴エントリ（URLはurl、document stateはdocumentState、ディレクティブ状態はdirective state）に設定

    10. navigationParamsをnullに設定

    11. ...

navigate to a fragmentの定義では:

HTML § 7.4.2.3.3 フラグメントナビゲーションへのモンキーパッチ:

ナビゲーブルnavigableでフラグメントにナビゲートするには...:

1. directive stateにnavigableのアクティブセッション履歴エントリのディレクティブ状態を代入

2. fragment directiveにフラグメントディレクティブを削除をurlで実行した結果を代入

3. fragment directiveがnullでなければ：

   フラグメントのみ変更かつディレクティブ未指定なら、アクティブエントリのディレクティブ状態を再利用（＝ハイライト維持）。

   1. directive stateに新規ディレクティブ状態（valueはfragment directive）を設定

4. historyEntryを新規セッション履歴エントリとして:

   • URL: url

   • document state: navigableのアクティブセッション履歴エントリのdocument state

   • scroll restoration mode: navigableのアクティブセッション履歴エントリのscroll restoration mode

   • ディレクティブ状態: directive state

5. historyHandlingが"replace"ならentryToReplaceをnavigableのアクティブセッション履歴エントリに、そうでなければnullに設定

6. ...

URLと履歴更新手順の定義では:

HTML § 7.4.4 非フラグメント同期ナビゲーションへのモンキーパッチ:

Document documentでのURLと履歴更新手順は...:

1. navigableにdocumentのノードナビゲーブルを代入

2. activeEntryにnavigableのアクティブセッション履歴エントリを代入

3. fragment directiveにフラグメントディレクティブを削除をnewUrlで実行した結果を代入

4. historyEntryを新規セッション履歴エントリ（

   • URL: newUrl

   • ...

   • ディレクティブ状態: activeEntryのディレクティブ状態

5. documentのis initial about:blankがtrueならhistoryHandlingを"replace"にセット

6. historyHandlingが"push"なら:

   1. documentのhistory objectのindexをインクリメント

   2. history objectのlengthをindex+1に

   3. newUrl≠activeEntryのURL（fragment除去）またはfragment directiveがnullでなければ:

      フラグメントのみ変更＆ディレクティブ未指定ならアクティブエントリのディレクティブ状態再利用、ハイライト維持

      1. historyEntryのディレクティブ状態を新規ディレクティブ状態（valueはfragment directive）に設定

7. そうでなく、fragment directiveがnullでなければ、historyEntryのディレクティブ状態のvalueにfragment directiveをセット

8. serializedDataがnullでなければ、history object stateをdocumentとnewEntryで復元

create navigation params by fetchingの定義では:

HTML § 7.4.5 セッション履歴エントリの充填へのモンキーパッチ:

session history entry entryでcreate navigation params by fetchingを行うには...:

1. これは並列実行であるassert

2. ...

17. currentURLにrequestのcurrent URLをセット

18. commitEarlyHintsをnullに

19. while (true):

    1. requestのreserved clientがnullでなく、currentURLのorigin≠reserved clientの生成URLのoriginなら:

    2. ...

    21. currentURL = locationURL

    22. fragment directiveにフラグメントディレクティブを削除をlocationURLで実行した結果を代入

    23. entryのURLをcurrentURLに

    24. entryのURLをlocationURLに

    25. entryのディレクティブ状態のvalueにfragment directiveをセット

    26. locationURLのスキームがfetch schemeでなければ、initiator originをrequestのcurrent URLのoriginとした新規non-fetch scheme navigation paramsを返す

    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. ドキュメントへのディレクティブ適用

上記のセクションでは、フラグメントディレクティブがURLから分離され、セッション履歴エントリに保存される仕組みについて説明しました。

このセクションでは、ナビゲーションおよびトラバーサル時に履歴エントリのディレクティブ状態を利用し、セッション履歴エントリに関連付けられたディレクティブをDocumentへ適用するタイミングと方法を定義します。

DOM § 4.5 Interface Documentへのモンキーパッチ:

各ドキュメントは関連付けられた保留中テキストディレクティブを持ちます。これはnullまたはリスト（テキストディレクティブのリスト）で、初期値はnullです。

履歴ステップ適用のためのドキュメント更新の定義にて:

HTML § 7.4.6.2 ドキュメントの更新へのモンキーパッチ:

Document documentとセッション履歴エントリ entry ... を与えて履歴ステップ適用のためのドキュメントを更新する:

1. ...

4. document の history object の length を scriptHistoryLength に設定

5. documentsEntryChanged が true の場合:

   1. oldURL に document の latest entry の URL を代入

   2. document の latest entry のディレクティブ状態が entry のディレクティブ状態と異なる場合:

      1. fragment directive を entry の ディレクティブ状態のvalueとする。

      2. document の保留中テキストディレクティブに、フラグメントディレクティブのパースの結果をセット。

6. document の latest entry を entry に設定

7. ...

3.3.3. フラグメントディレクティブの文法

注: このセクションは規範的ではありません。

注: この文法は便宜のためのリファレンスです。厳密な構文解析手順は§ 3.4 テキストディレクティブセクションの手続きで命令的に規定されています。この文法とそちらの手順が異なる場合は、手順のほうが正となります。

FragmentDirectiveは"&"文字で分割された複数のディレクティブを含めることができます。現時点では複数のテキストディレクティブによってページ内で複数のテキストを指示できますが、将来他種類のディレクティブの拡張や併用も可能です。この拡張性のため、不明なディレクティブが含まれていてもパースに失敗しません。

文字列が有効なフラグメントディレクティブであるのは、次のEBNF（拡張バッカス・ナウア記法）生成規則に合致する場合です：

FragmentDirective ::=

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

TextDirective ::=

"text="CharacterString

UnknownDirective ::=

CharacterString - TextDirective

CharacterString ::=

(ExplicitChar | PercentEncodedByte)*

ExplicitChar ::=

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

ExplicitCharは"&"以外の任意のURL code pointです。

TextDirectiveは次の生成規則を満たすとき有効と見なします:

ValidTextDirective ::=

"text=" TextDirectiveParameters

TextDirectiveParameters ::=

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

TextDirectivePrefix ::=

TextDirectiveString"-"

TextDirectiveSuffix ::=

"-"TextDirectiveString

TextDirectiveString ::=

(TextDirectiveExplicitChar | PercentEncodedByte)+

TextDirectiveExplicitChar ::=

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

TextDirectiveExplicitCharは"&""-""、","で使われている以外の全てのURL code point。テキストフラグメントが"&"や"-"や","を参照する場合はパーセントエンコードする必要があります。

PercentEncodedByte ::=

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

3.4. テキストディレクティブ

テキストディレクティブは、ユーザーに指示するためのテキスト範囲を示すディレクティブの一種です。構造体で、四つの文字列： start, end, prefix, suffix を持ちます。startはnull不可。他3つはnullでもよく、未指定時を示します。空文字列はどれにも許可されません。

各構成要素の意味や使い方は§ 3.2 構文を参照してください。

3.4.1. テキストディレクティブの呼び出し

このセクションでは、ドキュメントの保留中テキストディレクティブ内のテキストディレクティブがどのように処理・呼び出され、該当テキスト部分の指示が行われるかを説明します。

indicated partにおいて、フラグメントでrangeを指示できるようにします。以下のように修正：

HTML § 7.4.6.3 フラグメントへのスクロールへのモンキーパッチ：

HTML文書documentについて、その指示部分を決定するための処理モデルは次の通り：

1. text directivesをdocumentの保留中テキストディレクティブとする。

2. text directivesがnullでない場合：

   1. rangesリストをテキストディレクティブ呼び出し手順でdocumentとtext directivesから生成。

   2. rangesが空でなければ：

      1. firstRangeをrangesの最初の要素とする。

      2. ranges内の各rangeを 実装依存の方法で視覚的に指示する。指示は著者スクリプトから観測不可でなければならない。§ 3.7 テキスト一致の指示を参照。

         rangesの最初のrangeがスクロールされますが、全て指示は視覚的にユーザーに見せる必要があります。

      3. firstRangeをdocumentの指示部分としてセットし、return。

3. fragmentをdocumentのURLフラグメントとする。

4. fragmentが空文字列なら、特殊値「ドキュメント先頭」を返す。

5. potentialIndicatedElementをdocumentとfragmentをもとに求める。

6. ...

フラグメント識別子へのスクロールにおいて、指示部分がrangeの場合や、force-load-at-topポリシー時のスクロール制御を記述。次のように修正：

HTML § 7.4.6.3 フラグメントへのスクロールへのモンキーパッチ：

1. documentの指示部分がnullなら、documentのtarget要素をnullに。

2. documentの指示部分が「ドキュメント先頭」なら：

   1. documentのtarget要素をnullに。

   2. documentでドキュメント先頭へスクロール。

   3. return。

3. その他の場合：

   1. アサーション: documentの指示部分はelementまたはrange。

   2. scrollTargetをdocumentの指示部分とする。

   3. targetをscrollTargetとする。

   4. targetがrangeの場合：

      1. targetをstart node、end nodeの最小共通祖先にセット。

      2. targetがnullでなくelementでない間、targetをtargetの親に辿る。

         shadow tree内の場合のtarget設定はどうするか？ #190

   5. アサート：targetはelement。

   6. documentのtarget要素にtargetをセット。

   7. ancestor details revealingアルゴリズムをtargetで実行。

   8. ancestor hidden-until-found revealingアルゴリズムをtargetで実行。

      revealingアルゴリズムの現状だとtargetが祖先またはドキュメントルートノードの場合うまくいかない場合がある。 #89 でcontain:style layoutブロックへの制限提案あり。

   9. blockPositionはscrollTargetがrangeなら"center"、それ以外は"start"。

      テキストディレクティブへのスクロールはブロック方向で中央寄せスクロールとなる。
   10. targetを自動・start・nearestでスクロール。
   10. scroll a target into viewのtargetは scrollTarget、behaviorは"auto"、blockはblockPosition、inlineは"nearest"で実行。

       実装はテキストディレクティブから生成されたtargetの場合スクロールしないことも可能。

   11. targetのfocusing stepsを実行（fallbackはDocumentのビューポート）。

       Blinkは現状テキストフラグメントでfocusを設定しない。対応要検討。

   12. 逐次focusナビゲーションの開始点をtargetに移動。

次の2つのモンキーパッチは、ユーザーエージェントがフラグメント検索完了時に保留中テキストディレクティブをクリアすること、およびテキストディレクティブ検索パース終了時は非テキストディレクティブのフラグメントもサーチすることを保証します。

try to scroll to the fragmentの定義にて：

HTML § 7.4.6.3 フラグメントへのスクロールへのモンキーパッチ：

Document documentについて、try to scroll to the fragmentのパラレル手順は以下：

1. 実装依存の時間だけwait（パフォーマンス配慮のためのUX最適化）。

2. documentのrelevant global objectでnavigation/traversal task sourceのグローバルタスクとして以下をキュー：

   1. documentにparserが存在しないか、パース完了か、スクロール不要ならabort
   1. ユーザーエージェントがスクロール不要と判断した場合

      1. 保留中テキストディレクティブをnullにセット

      2. abort

   2. documentにparserが存在しないかparserがstopなら：

      1. 保留中テキストディレクティブがnullでなければ：

         1. 保留中テキストディレクティブをnullに

         2. フラグメント識別子へのスクロールをdocumentで実行

      2. abort

   3. documentでフラグメントへスクロールを実行。

   4. ドキュメントの indicated part がまだ null の場合、ドキュメントのフラグメントへスクロールを試みる。それ以外の場合は、保留中のテキストディレクティブ を null に設定する。

navigate to a fragmentの定義では：

HTML § 7.4.2.3.3 フラグメントナビゲーションへのモンキーパッチ：

navigable navigableでフラグメントにナビゲートするには...:

1. ...

8. navigableのactive document, historyEntry, true, scriptHistoryIndex, scriptHistoryLengthで履歴ステップ適用のためのドキュメント更新を行う。

9. navigableのactive documentでフラグメントにスクロールする。

10. navigableのactive documentの保留中テキストディレクティブをnullに

11. traversableをnavigableのtraversable navigableとする。

12. ...

指示部分へのスクロールは「scroll to the fragment」から行われるものの1つにすぎない。名称と関連定義を「indicating a fragment」にリネーム：

HTML § 7.4.2.3.3 フラグメントナビゲーションへのモンキーパッチ：

HTML § 7.4.2.3.3 Fragment navigations およびその関連手順の名称を「indicating a fragment」（フラグメントの指示）にリネーム。

3.5. セキュリティとプライバシー

3.5.1. 動機

テキストディレクティブを実装する際は、オリジン間で情報漏えいに使われないよう注意が必要です。スクリプトはクロスオリジンのテキストディレクティブ付きURLにナビゲートできます。悪意のある者が、被害者ページでテキストフラグメントが発見されたかを検出できれば、ページ内テキストの有無を推測できてしまいます。

次節以降の処理モデルでは、この攻撃ベクトルを軽減できるように制限を設けています。要点をまとめると、テキストディレクティブは次の条件下でのみ許可されます：

• トップレベルのnavigable（＝iframe不可）

  • これは正確ではなく、Chromeではsame-originイニシエーターでは許可。仕様更新要。

• ユーザーアクションによるナビゲーション

• ナビゲーションがクロスオリジンイニシエータの場合は、行き先がopener isolatedである必要がある（他のドキュメントからグローバルオブジェクト参照不可）

3.5.2. ナビゲーション時のスクロール

UAは一致したテキスト部分を自動スクロール表示できる場合があります。これはユーザーにとって便利ですが、実装UAはリスクに注意が必要です。

ナビゲーション時スクロールが通常のユーザースクロールと区別できる既知・未知の検出方法があります。

このような漏洩方法は、ターゲットページ特有の状況に依存し一般化は難しいです。テキストフラグメントの発動に更なる制限をつけることで、攻撃者の行動範囲はさらに狭くなります。ただし、UAごとにリスク受容性判断が異なる可能性があります。UAはこうしたリスクを考慮し、テキストフラグメントでの自動スクロール実施可否を判断して下さい。

準拠UAはナビゲーション時の自動スクロールをしない選択もできます。その場合はUIでユーザーがスクロール開始できる仕組み（「クリックしてスクロール」など）や、指示部分が下部ページに存在する旨の通知をすることも可能です。

上記例は状況次第でページ内容1ビット漏洩可能となることを示していますが、攻撃を繰り返して任意のページ内容抽出が行えないよう、ユーザーアクティベーション制限やブラウジングコンテキスト分離などが重要かつ必須です。

UAが自動スクロール実施を選ぶ場合、ドキュメントがバックグラウンド（非アクティブタブ等）では一切スクロールしない必要があります。これにより、不正利用がユーザー可視となり、バックグラウンド自動化攻撃を防止します。

UAが自動スクロールを実施しない場合、テキストフラグメント有無に関わらず要素ID指定部分は必ずスクロールしてください。そうしないと要素IDがスクロールされたか否かで一致判別ができてしまいます。

3.5.3. 検索タイミング

ナイーブなテキスト検索アルゴリズムでは、一致／不一致時の実行時間差で情報漏えいの可能性があります。攻撃者がテキストディレクティブ呼び出しURLへ同期ナビゲートできれば、その実行時間からテキスト片の存在を推測可能です。

そのため、§ 3.6 テキストフラグメントへのナビゲーション手順の実行時間が一致の有無で変化しないように実装しなければなりません。

この仕様では、UAが達成する手法は問わず、多様な解法とトレードオフが存在します。例：UAはテキストディレクティブから範囲検索で一致が見つかってもツリー走査を継続したり、非同期タスクでドキュメント指示部分を設定するなど。

3.5.4. テキストフラグメントの制限

requestおよびDocumentの定義を修正し、新たなboolean型text directive user activationフィールドを含めます：

Monkeypatching [FETCH]:

requestには関連付けられたboolean型text directive user activation があり、初期値はfalse。

Monkeypatching [HTML]:

各Documentはtext directive user activation（boolean型、初期値はfalse）を持つ。

text directive user activationは、テキストフラグメントを一度だけアクティベート可能にするためのユーザー操作シグナルです。ドキュメント読み込み中、ユーザーアクティベーションによるナビゲート時のみtrueになり、クライアントサイドリダイレクトでも伝搬します。

Documentのtext directive user activationがテキストフラグメントのアクティベートに使われなかった場合は、新しいナビゲーションrequestのtext directive user activationにもtrueがセットされます。これにより、一つのtext directive user activationがナビゲーションをまたいで引き継がれます。

どちらのDocumentのtext directive user activationも、requestのtext directive user activationも、使用された時点で常にfalseになる。これにより、一度のユーザーアクティベーションで複数のテキストフラグメントをアクティベートできなくなる。

create navigation params by fetching手順では、active documentのtext directive user activation値をrequestのtext directive user activationに伝搬します。

Monkeypatching [HTML]:

1. これは並列実行である

2. documentResourceをentryのdocument stateのresourceとする。

3. requestを新規requestとして作成：

   url

   entryのURL

   ...

   ...

   referrer policy

   entryのdocument stateのrequest referrer policy

   text directive user activation

   navigableのactive documentのtext directive user activation

4. navigableのactive documentのtext directive user activationをfalseに設定。

5. documentResourceがPOST resourceであれば：

   1. ...

navigation params定義にも新しいフィールドを含める：

Monkeypatching [HTML]:

user involvement

user navigation involvement値。

user involvement値をナビゲーションparams作成時にセット。特にcreate navigation params by fetchingのケースでは初期値true：

Monkeypatching [HTML]:

To create navigation params by fetching given ... user navigation involvement user involvement, ...

1. アサート：これは並列で実行されている。

2. ...

23. resultPolicyContainer を、response の URL、entry の document state の history policy container、sourceSnapshotParams の source policy container、null、および responsePolicyContainer からナビゲーションパラメータポリシーコンテナを決定した結果とする。

24. navigable の container が iframe であり、かつ response の timing allow passed フラグが立っている場合、container の pending resource-timing start time を null に設定する。

25. 次の内容を持つ新しいナビゲーションパラメータを返す：

    id

    navigationId

    ...

    ...

    about base URL

    entry の document state の about base URL

    ユーザー関与

    user involvement

Documentオブジェクトの生成と初期化手順にてtext directive user activationフラグの計算と保存を行う：

Monkeypatching [HTML]:

18. link headersをdocument, navigationParamsのresponse, "pre-media"で処理。

19. documentのtext directive user activationを、次条件のいずれかでtrue、そうでなければfalseに設定：

    • navigationParamsのuser involvementが"activation"

    • navigationParamsのuser involvementが"browser UI"

    • navigationParamsのrequestのtext directive user activationがtrue

      text directive user activationはコピーできないことが重要であり、ユーザーアクティベートされたナビゲートごとに1回のみテキストフラグメントがアクティベートできる。

20. documentを返す。

text directive allowing MIME typeは、MIME typeのessenceが"text/html"または"text/plain"であるもの。

注: scrolling to a fragmentで述べられているように、フラグメント処理は各MIME Typeごとに定義されています。したがってscroll to the fragmentでのテキストディレクティブスクロールはtext/htmlメディアタイプのみが対象。ただし実際にはブラウザはtext/plainにもHTML方式のフラグメント処理を適用することがあり、そのためtext/plainへのテキストディレクティブ適用許可が有用です。text/css, application/json, application/javascript等は明示的に除外され、XS-Search攻撃等への配慮です。

この記述はHTML仕様として妥当か？

§ 3.4.1 テキストディレクティブの呼び出しですでに修正済みのscroll to the fragment手順にboolean型allow text directive scroll引数を追加：

Monkeypatching HTML § 7.4.6.3 フラグメントへのスクロール:

Document document、boolean allow text directive scroll引数で scroll to the fragmentを実行：

1. ドキュメントの indicated part が null の場合、ドキュメントの target element を null に設定する。

2. ...

3. それ以外の場合：

   1. アサート：ドキュメントの indicated part は要素、または range である。

   2. ...

   4. target が range の場合：

      1. allow text directive scroll が false なら、return。

      2. target を target の 最初の共通祖先（target の start node と end node）にする。

      3. ...

try to scroll to the fragmentを修正、boolean型allow text directive scrollを引数に持ち、手順2のタスク内容を差し替え：

Monkeypatching [HTML]:

Document documentとboolean allow text directive scroll でtry to scroll to the fragmentを並列実行：

1. 実装依存の時間wait。

2. documentのrelevant global objectでnavigation/traversal task sourceのグローバルタスクとして以下：

   1. documentにparserがない/停止済/ユーザーがスクロール希望でないならabort。

   2. documentとallow text directive scrollでscroll to the fragmentを実行。

   3. documentの指示部分がnullなら再度try to scroll to the fragment(allow text directive scroll)。

update document for history step application手順でもboolean allow text directive scrollを引数に持ち、scroll to a fragment時に利用：

Monkeypatching [HTML]:

Document document, session history entry entry, boolean doNotReactivate, 数値scriptHistoryLengthとIndex、entriesForNavigationAPI（任意）、boolean allow text directive scroll引数でupdate document for history step application手順：

1. documentIsNewはdocumentのlatest entryがnullならtrue。

2. ...

5. documentsEntryChangedがtrueの場合：

   1. oldURL = documentのlatest entryのURL

   2. ...

6. documentIsNewがtrueなら：

   1. documentとallow text directive scrollでtry to scroll to the fragment実行

apply the history stepアルゴリズムもboolean allow text directive scroll引数を持ち、update document for history step application へ渡す：

Monkeypatching [HTML]:

apply the history step handoff... boolean allow text directive scroll（デフォルトfalse）で呼び出し

14. completedChangeJobs が totalChangeJobs と等しくない間：

    1. ...

    11. navigation and traversal task source で、navigable の active window に対し次のステップを実行するグローバルタスクをキューする：

        1. changingNavigableContinuation の update-only が false の場合：

           1. ...

           2. navigable の targetEntry の履歴エントリをアクティブ化する。

        2. updateDocument を次のアルゴリズムステップとする：targetEntry の document、targetEntry、changingNavigableContinuation の update-only、scriptHistoryLength、scriptHistoryIndex、entriesForNavigationAPI、および allow text directive scroll を指定して履歴ステップ適用のためのドキュメント更新を実行する。

        3. targetEntry の document が displayedDocument と等しければ、updateDocument を実行する。

15. totalNonchangingJobs を nonchangingNavigablesThatStillNeedUpdates のサイズとする。

apply the push/replace history stepでもallow text directive scrollingをapply the history stepへ渡す：

Monkeypatching [HTML]:

apply the push/replace history step handoff... boolean allow text directive scroll（デフォルトfalse）で呼び出し

apply the history step内でfalse, null, null, null, allow text directive scrollを渡し実行。

注: allow text directive scrollはトラバースやリロード時には意図的にセットされません。イニシエーターオリジンやユーザー関与のチェック回避や履歴スクロール状態優先のためです。テキストディレクティブはドキュメントの指示部分として使われるため、ハイライトは復元される。

finalize a cross-document navigationにuser involvement引数を渡し、allow text directive scrollingも計算・伝搬：

Monkeypatching [HTML]:

finalize a cross-document navigation handoff...user navigation involvement user involvement、...

1. ...

10. allow text directive scrollをテキストディレクティブがスクロール可能か判定で計算し、historyEntryのdocument, entryのdocument state, initiator origin, user involvement引数で渡す

11. apply the push/replace history step targetStep to traversable, with allow text directive scroll

navigateアルゴリズムにてuser involvementをfinalize a cross-document navigationへ伝播：

Monkeypatching [HTML]:

1. ...

20. . 並列で次の手順を実行する：

    1. ...

    9. . allowPOST を true、completionSteps を次の手順とし、navigable、"navigate"、sourceSnapshotParams、targetSnapshotParams、navigationId、navigationParams、cspNavigationType を指定して historyEntry のための履歴エントリの document を生成しようとする：

       1. navigable、historyHandling、historyEntry、および userInvolvement を指定して、セッションクロスドキュメントナビゲーションを完了するためのセッション履歴トラバーサル手順を navigable の traversable に追加する。

Navigate to a fragmentアルゴリズムもinitiator originを引数にとり、 allow text directive scrollをフラグメントスクロール時に渡す：

Monkeypatching [HTML]:

navigate to a fragment handoff... navigable, URL, ..., userInvolvement, navigationAPIState, navigationId, origin initiator origin...

1. ...

14. navigableのactive document, historyEntry, true, ...などでupdate document for history step application

15. ...

16. allow text directive scrollをcheck if a text directive can be scrolledで計算（active document, initiator origin, userInvolvement）

17. active document, allow text directive scrollでscroll to the fragment呼び出し

navigateアルゴリズムでfragment navigationする際にinitiator originを渡す：

Monkeypatching [HTML]:

10. navigation must be a replaceの判定（...）

11. 次4条件がすべてtrueの場合：

    • documentResourceがnull

    • responseがnull

    • urlがnavigableのactive session history entryのURL(fragment除去)と等しい

    • urlのfragmentがnon-null

    なら：

    1. navigate to a fragment(navigable, url, historyHandling, userInvolvement, navigationAPIState, navigationId, initiatorOriginSnapshot)

    2. navigation = navigableのactive windowのnavigation API

3.5.5. ロード時のスクロール制限

このセクションでは、新しいドキュメントの読み込み時に、テキストディレクティブなどを含むすべての種類のスクロールを防ぐために、force-load-at-top ポリシーがどのように使用されるかを定義します。

force-load-at-top がナビゲーションAPIとどのように連携するかを決定する必要があります。[Issue #WICG/scroll-to-text-fragment#242]

保存状態の復元ステップを修正し、スクロールの復元を抑制する新しいブールパラメーターを受け取るようにします：

Monkeypatching [HTML]:

セッション履歴エントリ entry , およびブール値 suppressScrolling から保存状態を復元するには：

1. entryのスクロール復元モードが "auto"、 suppressScrolling がfalse、かつentryのドキュメントの関連グローバルオブジェクトのナビゲーションAPIの ongoing navigation中の通常のスクロール復元抑制がfalseであれば、entryを指定してスクロール位置データを復元する。

2. ...

履歴ステップ適用のためのドキュメント更新ステップを修正し、 force-load-at-top ポリシーを確認することで、新しいドキュメントで設定されていればスクロールを回避します。

Monkeypatching [HTML]:

1. ...

4. documentの履歴オブジェクトのlengthを scriptHistoryLength に設定する。

5. scrollingBlockedInNewDocument を ポリシー値の取得 を使って force-load-at-top を document に対して取得した結果とする。

6. documentsEntryChanged が true の場合、次を行う：

   1. oldURL を document の latest entry の URL とする。

   2. ...

   5. documentIsNew が false の場合：

      1. ナビゲーション、entry、"traverse" を指定して、同一ドキュメントナビゲーション用のナビゲーションAPIエントリを更新する。

      2. popstate という名前のイベントを発火する...

      3. entry および suppressScrolling をfalseにして保存状態を復元する。

      4. oldURLのフラグメントが...でなければ

   6. それ以外の場合、

      1. Assert: entriesForNavigationAPI が与えられている。

      2. entry および scrollingBlockedInNewDocument で保存状態を復元する。

      3. ナビゲーション、entriesForNavigationAPI、entry を指定して新しいドキュメント用のナビゲーションAPIエントリを初期化する。

7. documentIsNew が true の場合、

   1. scrollingBlockedInNewDocument がfalseであれば、ドキュメントのフラグメントへスクロールを試みる。

   2. この時点でスクリプトが新たに生成された document 用に実行される場合がある。

8. それ以外で、documentsEntryChanged が false かつ doNotReactivate が false なら：

   1. ...

3.6. テキストフラグメントへのナビゲーション

3.6.1. ドキュメント内の範囲の特定

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>

ノードは、検索不可 である条件： 要素であり、HTML名前空間内にあり、以下いずれかを満たすとき：

1. computed value（算出値）の display プロパティが none である。

2. そのノードが voidとしてシリアライズされるとき。

3. 次の型のいずれかである場合：HTMLIFrameElement、 HTMLImageElement、 HTMLMeterElement、 HTMLObjectElement、 HTMLProgressElement、 HTMLStyleElement、 HTMLScriptElement、 HTMLVideoElement、 HTMLAudioElement

4. select 要素で multiple 属性がない場合

ノードが 検索不可部分木 の一部となる条件は、自身または shadow-including ancestor が 検索不可 である場合です。

ノードが 可視テキストノード と判定される条件は、Text ノードであり、親要素の算出値による親要素の visibility プロパティが visible であり、描画されていることです。

ノードがブロックレベル表示を持つとは、 要素であり、 算出値による display プロパティが block、table、flow-root、grid、flex、list-item のいずれかであることです。

3.6.2. 単語境界

単語境界は、[UAX29]およびUnicode Text Segmentation § Word_Boundariesで定義されます。Unicode Text Segmentation § Default_Word_Boundariesでは デフォルトの単語境界規則セットを規定していますが、仕様でも述べている通り、より高度なアルゴリズムをロケールに応じて使うべきです。

辞書ベースの単語境界判定は、単語区切り文字のないロケールでは特に注意が必要です。英語ではスペース(' ')で単語区切りですが、日本語には単語間を区切る文字がありません。そのような場合、かつアルファベットが100文字未満の場合、辞書には有効な1文字単語をアルファベットの20%以内に抑える必要があります。

ロケールとは、有効な文字列（[BCP47]言語タグ）または空文字列です。空文字列は主言語が不明であることを示します。

部分文字列が単語境界で区切られているとは、文字列 text、ロケール startLocale と endLocale が与えられたとき、その最初の文字の位置が 単語境界であるかつ、末尾（最後の文字の直後の位置）が 単語境界である場合を指します。

数値 position が 単語境界であるのは、文字列 text、および ロケール locale が与えられたとき、localeに従い 単語境界が直前にある、または text の長さが0より大きく、positionが0 または text長と等しい場合を指します。

3.7. 一致したテキストの指示

UAは、try to scroll to the fragment の手順や他のメカニズムの一環として、テキストフラグメントをインビューにスクロールしても構いませんが、必ずしも一致箇所を表示する義務はありません。

UAはユーザに一致箇所を認識させるため、ハイコントラストなハイライトなど視覚的に強調して示すべきです。

UAはユーザーの操作で一致表示状態を解除し、強調を消す手段も提示すべきです。

その見た目やUI動作はUA依存です。ただし、オーサスクリプトで観測可能な手法（例：Documentのselection）によって表示してはなりません。そうするとコンテント抽出の攻撃ベクトルとなります。

UAは提供されたコンテキスト語句には視覚的強調を表示してはいけません。

強調はドキュメントの内容の一部ではないため、UAはユーザがページ内容と区別できる工夫も推奨されます。

3.7.1. UA機能のURL表示

UAは、ドキュメントURLを消費する様々な場所を提供します（window.locationのようなAPIを除く）。例としては、ロケーションバーで現在表示中ドキュメントのURLを見せたり、ブックマーク作成時のURLなどがあります。

ユーザの混乱を避けるため、こうしたURLにフラグメントディレクティブを含めるかどうかは統一すべきです。本節で推奨する標準動作例を示します。

原則として、URLはビジュアル指示（マーカー）が表示中のみフラグメントディレクティブを含めるべきです。マーカーが解除されたらURLからも同ディレクティブを除外すべきです。

URLがテキストフラグメントを含むが実際には一致しなかった場合、UAは公開URLからそれを省くこともできます。

よくある具体例は以下のとおりです。

3.7.1.1. ロケーションバー

ロケーションバーのURLには、マーカー表示中はテキストフラグメントを含めるべきです。マーカー解除時はロケーションバーのURLから同ディレクティブを消してください。

たとえ一致しなくても、ロケーションバーにはフラグメント情報を含めることが推奨されます。

3.7.1.2. ブックマーク

多くのUAは「ブックマーク」機能で現在ページへのリンクを保存できます。

新たに作成されたブックマークURLは、デフォルトで一致がありかつマーカー表示中であればフラグメントディレクティブを含めるべきです。

ブックマークからの遷移時は通常と同様、同ディレクティブを処理します。

3.7.1.3. 共有

一部UAはURL共有（他アプリ・メッセージ転送）機能を提供します。

この場合も、一致がありマーカーが未解除ならフラグメントディレクティブをURLに含めるべきです。

3.8. Document Policyとの統合

本仕様は Document Policy の設定点として "force-load-at-top" という名前で定義します。型は boolean で、初期値 は falseです。

Document-Policy: force-load-at-top

このポリシーによるフラグメント由来のスクロール抑制は、本書scroll to the fragmentアルゴリズム修正として§ 3.6 テキストフラグメントへのナビゲート内で規定されています。

履歴スクロール復元の抑制は、restore persisted state ステップの2の直後に下記処理を挿入することで規定します：

3. "force-load-at-top" 機能のDocument policy値を取得し、Documentについて trueなら、ユーザエージェントは Documentやそのスクロール可能領域のスクロール位置を復元してはならない。

3.9. 機能検出について

機能検出のため、新しいFragmentDirectiveインターフェイスを追加し、UAが対応していればdocument.fragmentDirectiveで公開する提案です。

[Exposed=Window]
interface FragmentDirective {
};

このため Document インターフェイスに fragmentDirective プロパティを追加します：

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

このオブジェクトは将来テキストフラグメントやその他ディレクティブに関する追加情報を提供する目的にも使えるでしょう。

4. テキストフラグメントディレクティブ生成

本節ではUAがテキストディレクティブ付きURLを自動生成する際の推奨を示します。必須仕様ではありませんが、生成URLの安定性・利便性を高める観点でまとめています。

4.1. 範囲一致より完全一致を優先

一致テキストは exact型（例: "text=foo%20bar%20baz"）または range型（例: "text=foo,bar"）いずれでも指定できます。

可能なら全体を1つの文字列として指定するほうが望ましいです。これにより遷移先ページが削除・変動しても意図したリンク先がURLから分かります。

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.

範囲一致は引用テキストが非常に長く、全体をエンコードするとURLが極端に長大になる場合は有用です。

300文字未満のテキスト断片は完全一致を推奨、超える場合はrange型も可。

4.2. 文脈指定は必要時のみ

文脈指定はテキストディレクティブによるページ内断片の曖昧性解消に使えますが、構造変化などで 脆くなりやすいです。多くの場合、断片テキストは要素境界で始まったり終わることが多いので文脈側が隣接別要素に現れます。そのためページ構造の変更で文脈と一致断片が隣接しなくなりURLが無効になりがちです。

<div class="section">HEADER</div>
<div class="content">Text to quote</div>

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

断片テキストが十分長くユニークな場合、UAは無用な文脈語追加を避けるべきです。

文脈指定が必要な条件：

• UAが引用テキストが曖昧だと判定した場合
• 引用テキストが3語以下

4.3. フラグメントIDの要否判定

UAがテキストディレクティブ付きURLへ遷移時、テキストフラグメントが見つからなければ通常の要素IDフラグメントにフォールバックしてスクロールします。

これは、ページテキストが変化してテキストディレクティブが無効化された場合の保険として有用です。

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

ただし、フォールバック先の要素IDが適切かどうか注意が必要です：

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