コンテナータイミング API

1. はじめに

Container Timing API により、DOM の注釈されたセクションが画面に表示され、 初回ペイントが完了した時点を監視できます。開発者は containerTiming 属性（Element Timing API の elementtiming と同様）を使用して DOM のサブセクションをマークし、そのセクションが 初めてペイントされたときにパフォーマンスエントリを受け取ることができます。

この 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. ライフサイクル

ただし、ある領域が一度描画されると、その同じ領域の以後の描画によって新しいエントリが生成されることはありません。

ユーザーがページをスクロールまたは操作した後は、それ以降の描画は記録されず、新しいエントリも 生成されません。

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('コンテナーが描画されました：', entry.identifier,
                  '時刻', entry.startTime,
                  'サイズ：', entry.size);
    }
  });
  observer.observe({ entryTypes: ["container"] });
</script>

3.1. サブツリーの無視

<div containertiming="foobar">
  <main>...</main>
  <!-- aside の更新はコンテナータイミングイベントを発生させません -->
  <aside containertimingignore>...</aside>
</div>

4. 用語

コンテナ・ルートとは、 HTMLElement であり、containerTiming 属性を持つものです。

無視されるサブツリーとは、 HTMLElement をルートとし、その要素が containerTimingIgnore 属性を持つサブツリーです。

ペイント済み領域とは、 コンテナ・ルートでペイントされたすべての部分を、その要素が最初に 観測されてから累積して表す領域（矩形の集合）であり、CSS ピクセルで表現されます。ペイント済み領域はビューポート座標空間で維持されます。 コンテナ・ルート要素が移動した場合 （たとえば、レイアウトの変更や moveBefore() によって）、 以前に累積された矩形は調整されません — 領域はビューポート座標内で拡大し続けます。

Container Timing 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 HTMLElement? lastPaintedElement;
    readonly attribute HTMLElement? rootElement;

    [Default] object toJSON();
};

PerformanceContainerTiming includes PaintTimingMixin;

注記: intersectionRectの 座標およびsizeは CSS ピクセル（sizeの場合は平方 CSS ピクセル）で表現され、 ペイント済み 領域の座標空間および交差矩形アルゴリズムによって生成される単位と一致する。

注記: ユーザーエージェントは、削除されたコンテンツによって メモリリークが発生しないように、コンテナルートレコードマップを維持する必要がある。特に、エントリーの存続期間を HTMLElement への弱いポインターに 結び付けることで、HTMLElement が 削除された後のいずれかの時点で、それらをクリーンアップできる。このマップはウェブ開発者に公開されないため、 ガベージコレクションのタイミングが公開されることはない。

6. 処理モデル

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

6.1. 文書単位の状態

各 Document について、ユーザーエージェントは、コンテナ・ルート HTMLElement を Container Timing レコード オブジェクトにマップする コンテナ・ルート・レコード・マップを維持しなければなりません。

6.2. DOM 仕様の変更

この節は、[DOM] 仕様が変更されると削除されます。

イベント・ディスパッチ・アルゴリズムを次のように変更します。

ステップ 1 の直後に、次のステップを追加します。

1. target の 関連するグローバルオブジェクトが Window オブジェクトであり、event の isTrusted が true の場合：

   1. event の type が scroll の場合、target の 関連するグローバルオブジェクトの スクロールイベントをディスパッチ済みを true に設定します。

   2. event の type が keydown、mousedown、pointerdown、または click のいずれかの場合、target の 関連するグローバルオブジェクトの 入力イベントをディスパッチ済みを true に設定します。

6.3. HTMLElement インターフェイスの拡張

この節は、[DOM] 仕様が変更されると削除されます。

HTMLElement インターフェイスを次のように拡張します。

partial interface HTMLElement {

    [CEReactions, Reflect] attribute DOMString containerTiming;

    [CEReactions, Reflect] attribute boolean containerTimingIgnore;

};

6.4. Container Timing レコード

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

6.5. コンテナ・ルートの登録

HTMLElement が containerTiming コンテンツ属性を持った状態で文書に接続された場合：

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

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

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

6.6. containertiming 属性の削除

注： containerTiming 属性が後で同じ要素に再び追加された場合、次の描画時に新しい Container Timing レコードが 作成されます。描画済み領域は新しい状態から始まり、以前の描画データは保持されません。

6.7. コンテナ・ルートの切断

注： 要素が containerTiming 属性を引き続き持ったまま文書に再接続された場合、それは新しい コンテナ・ルート登録として扱われます。次の描画時に、新しい Container Timing レコードが、 新しい 描画済み領域とともに作成されます。

6.8. Container Timing 用の要素描画の処理

注： このアルゴリズムは、描画される各画像またはテキスト ノードについて呼び出されます。交差矩形は、要素をターゲット、ビューポートをルートとして 交差矩形アルゴリズムを使用して計算し、 ビジュアル・ビューポートと交差させる必要があります。テキストノードの場合、交差 矩形は、所有されるテキストノードの集合内のすべてのテキストノードのボーダーボックスを含む最小の矩形であり、ビジュアル・ビューポートと交差させたものです。

注： Container Timing は、コンテンツの 初期レンダリングを測定することを目的としています。ユーザーが文書をスクロールまたは操作した後は、描画は 記録されなくなります。これは、それらがページの読み込みではなく、そのスクロールまたは操作の結果（たとえば、 ビュー内にスクロールされたコンテンツやクリックによって表示されたコンテンツ）である可能性が高いためです。現在の フレームですでに保留中のエントリは、引き続き発行されます。

6.9. Container Timing エントリの発行

注： 描画された要素ごとに複数の エントリを発行する場合がある他の一部のペイント・タイミング API とは異なり、Container Timing は各 コンテナ・ルートについて描画済み領域を蓄積し、 フレームごと、コンテナ・ルートごとに最大 1 つの PerformanceContainerTiming エントリを発行します。このバッチ処理方式はより効率的であり、 コンテナの描画状態を包括的に把握できます。

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

6.11. Container Timing への寄与

HTMLElement は、次のすべてが true の場合、コンテナ・ルートの コンテナ・タイミングに 寄与します。

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

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

• それがシャドーツリー内にないこと。

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

6.13. 最後の新しい描画領域を必要に応じて更新

注： lastPaintedElement は、単一のレンダリング・フレーム内で新たに描画された面積が最大となるよう寄与した要素です。これにより、 実装固有の描画順序への依存を回避します。lastPaintedElement は、大規模または複雑な コンテナ・ルート（たとえば テーブル）の更新を何が引き起こしているかを調査する開発者向けのデバッグ支援として意図されており、それ自体が独立したパフォーマンス指標ではありません。lastNewPaintedAreaSize は、 エントリが発行された後にリセットされるため、各フレームの比較は新しい状態から始まります。

注： このアルゴリズムは、サイズに関係なく描画済み 領域へのあらゆる変更を報告します。描画領域に 1 ピクセルだけの変更があった場合でも、新しい PerformanceContainerTiming エントリがキューに入れられます。小さな変更を除外したい開発者は、エントリ間の size 値を比較することで除外できます。

6.14. Container Timing エントリの作成

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

• Bas Schouten