コンテナータイミング API

1. はじめに

Container Timing API は、DOM の注釈付けされたセクションが画面に表示され、その初回描画が 完了した時点を監視できるようにします。開発者は、containertiming 属性（Element Timing API の elementtiming と同様）で DOM のサブセクションをマークし、そのセクションが 初めて描画されたときに performance entry を受け取ることができます。

この API により、開発者はページ内のさまざまなコンポーネントのタイミングを測定できます。開発者が アプリケーションをコンポーネントとして構成することが増えるにつれ、アプリケーションまたは Web ページの サブセクションにおけるパフォーマンスを測定したいという需要が高まっています。

Element Timing とは異なり、DOM のセクションが描画を完了した時点をレンダラーが知ることはできません （将来の変更、新しい画像に対する非同期リクエスト、読み込みの遅いボタンなどが存在し得るため）。 そのため、この API は、更新があったときに PerformanceEntry オブジェクトの形式で候補を発行します。

2. 動機

開発者は、テーブル、ウィジェット、その他のコンポーネントなど、DOM のサブセクションがいつ描画されたかを 測定し、描画時間を追跡して分析に送信できるようにしたいと考えています。現在の Web API はこれを十分には サポートしていません:

• Element Timing はサポートできる対象に制限があり、セクション全体には使用できません。

• Largest Contentful Paint (LCP) は、ページの特定部分が読み込まれた時点を測定するには 十分に有用ではありません。

• ユーザー空間の polyfill には、次のような大きな欠点があります:

  • 描画前に要素をマークする必要がある（サーバー側の変更またはレンダリングのブロックが必要）

  • 新たに挿入された要素を捕捉するために MutationObserver が必要

  • document head 内で実行する必要があり、初回描画までの時間が増加する

  • ブラウザー組み込みの 2D エンジンと比較して、矩形追跡の効率が低い場合がある

Web 作者は自分のドメインを誰よりもよく理解しており、自分たちのコンテンツブロックのパフォーマンスを、 ユーザーや組織が理解できる方法で伝えたいと考えています（例: "time to first tweet"）。

2.1. ライフサイクル

ただし、いったん領域が描画されると、その同じ領域の後続の描画によって新しい entry は生成されません。

3. 使用例

次の例は、コンテナールートを登録し、その描画タイミングを監視する方法を示します。

<div containertiming="foobar">
  <main>...</main>
  <aside>...</aside>
</div>

<script>
  const observer = new PerformanceObserver((list) => {
    let perfEntries = list.getEntries();
    for (const entry of perfEntries) {
      console.log('Container painted:', entry.identifier,
                  'at', entry.startTime,
                  'size:', entry.size);
    }
  });
  observer.observe({ entryTypes: ["container"] });
</script>

3.1. サブツリーの無視

<div containertiming="foobar">
  <main>...</main>
  <!-- Aside updates won't trigger container timing events -->
  <aside containertiming-ignore>...</aside>
</div>

4. 用語

コンテナールートとは、 Element のうち、containertiming 属性を持つものです。

無視されるサブツリーとは、 Element をルートとするサブツリーで、その要素が containertiming-ignore> 属性を持つものです。

描画済み領域とは、 最初に観測されて以降に蓄積された、コンテナールートの描画済み部分すべてを表す 領域（矩形の集合）です。

コンテナータイミング API は、コンテナールートが画面に描画される時点に関するタイミング情報を提供します。

5. PerformanceContainerTiming インターフェイス

[Exposed=Window]
interface PerformanceContainerTiming : PerformanceEntry {
    readonly attribute DOMString identifier;
    readonly attribute DOMRectReadOnly intersectionRect;
    readonly attribute unsigned long long size;
    readonly attribute DOMHighResTimeStamp firstRenderTime;
    readonly attribute Element? lastPaintedElement;
    readonly attribute Element? rootElement;
};

PerformanceContainerTiming includes PaintTimingMixin;

注: ユーザーエージェントは、削除されたコンテンツが メモリリークを引き起こさないように、container root records map を維持する必要があります。 特に、entry の寿命を Element への 弱ポインターに結び付けることができ、Element が 削除された後のある時点でそれらをクリーンアップできます。この map は Web 開発者に公開されないため、 これはガベージコレクションのタイミングを公開しません。

6. 処理モデル

注: Container Timing API を実装するユーザーエージェントは、 "container" を supportedEntryTypes に含める必要があります。これは Window コンテキスト向けです。 これにより、開発者は container timing のサポートを検出できます。

6.1. 文書ごとの状態

各 Document について、ユーザーエージェントは container root records map を維持しなければなりません。これは コンテナールート Element から Container Timing Record オブジェクトへの対応付けです。

6.2. Element インターフェイスへの拡張

このセクションは、[DOM] 仕様が変更された後に削除されます。

ここでは、Element インターフェイスを次のように拡張します:

partial interface Element {
    [CEReactions] attribute DOMString containertiming;
    [CEReactions] attribute DOMString? containertimingIgnore;
};

6.3. Container Timing Record

この仕様は、処理モデルで使用される内部データ構造を定義します:

6.4. コンテナールートの登録

[^containertiming^] content attribute を持つ Element が文書に接続されたとき:

1. ユーザーエージェントは、その要素を コンテナールートとして登録しなければなりません。

2. ユーザーエージェントは、コンテナールートのために、空の 描画済み領域を初期化しなければなりません。

3. ユーザーエージェントは、コンテナールートのサブツリー内の すべての paint operation を追跡しなければなりません。ただし、無視されるサブツリーは除外します。

6.5. Container Timing のための要素描画の処理

注: このアルゴリズムは、描画される各画像またはテキスト ノードに対して呼び出されます。intersection rectangle は、要素を target、viewport を root として intersection rect algorithm を使用し、visual viewport と交差させて 計算するべきです。テキストノードの場合、intersection rectangle は、所有されるテキストノードの集合内のすべてのテキストノードの border box を含む最小矩形を、visual viewport と交差させたものです。

6.6. Container Timing Entry の発行

注: 描画された要素ごとに複数の entry を発行する場合がある 他の一部の paint timing API とは異なり、Container Timing は各 コンテナールートについて 描画済み領域を蓄積し、コンテナールートごと、フレームごとに最大 1 つの PerformanceContainerTiming entry を発行します。このバッチ化のアプローチはより効率的であり、コンテナーの描画状態を全体的に把握できます。

6.7. 親コンテナールート Element の取得

6.8. Container Timing への寄与

Element は、次のすべてが true である場合、コンテナールートの container timing に寄与します:

• それが コンテナールートの子孫である。

• それが 無視されるサブツリー内にない。

• それが shadow tree 内にない。

6.9. コンテナールート Element の取得

6.10. 最後の新規描画領域を更新する可能性

注: このアルゴリズムは、サイズにかかわらず、描画済み領域への あらゆる変更を報告します。描画領域の 1 ピクセルの変更であっても、新しい PerformanceContainerTiming entry がキューに入れられます。小さな変更を除外したい開発者は、entry 間の size 値を比較することで、それを行うことができます。

6.11. Container Timing Entry の作成

7. セキュリティとプライバシーに関する考慮事項

7.1. クロスオリジン制限

この API はクロスオリジン境界を尊重します:

• クロスオリジン iframe に属する要素は、親フレームに公開されません。

• 開発者が postMessage によって明示的に渡さない限り、タイミング情報は フレーム境界を越えません。

7.2. 情報の露出

この API によって提供される情報の大部分は、既存の API によってすでに推定できます:

• Element Timing は、画像およびテキストの初回レンダリング時刻を返します。

• Paint Timing API は関連するタイムスタンプを提供します。

• これらの API の組み合わせにより、効率は劣るものの、container timing 情報を近似できます。

この API は次のものを公開しません:

• レンダリングエンジンの内部実装の詳細

• 開発者がまだアクセス権を持っていない要素に関する情報

• 既存の Performance API を通じてすでに利用可能なものよりも細かいタイミング情報

7.3. タイミング攻撃

この API は DOMHighResTimeStamp を使用します。これは他の Performance API と同様に、セキュリティ目的で分解能の制限を受ける場合があります。

7.4. プライバシーに関する考慮事項

この API は次のことを行いません:

• サイトをまたいでユーザーを追跡できるようにすること

• 閲覧履歴を公開すること

• スクリプト実行を通じてサイトがすでにアクセスできるものを超える、ユーザー行動に関する情報を提供すること

8. 謝辞

貴重なフィードバックと助言をくださった以下の方々に深く感謝します:

• Barry Pollard

• Michael Mocny

• Scott Haseley

• Sergey Chernyshev