コンテナータイミング 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. ライフサイクル

ただし、いったん領域が描画されると、その同じ領域の後続の描画によって新しい 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('コンテナーが描画されました：', entry.identifier,
                  '時刻', entry.startTime,
                  'サイズ：', entry.size);
    }
  });
  observer.observe({ entryTypes: ["container"] });
</script>

3.1. サブツリーの無視

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

4. 用語

コンテナルートとは、 [^containertiming^] 属性を持つ HTMLElement である。

無視されるサブツリーとは、 [^containertimingignore^] 属性を持つ HTMLElement を根とするサブツリーである。

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

コンテナタイミング 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;
};

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 Record オブジェクトに対応付ける、コンテナルートレコードマップを維持しなければならない。

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

この節は、[DOM] 仕様が修正され次第、削除される。

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

partial interface HTMLElement {
    [CEReactions, Reflect] attribute DOMString containerTiming;
    [CEReactions, Reflect] attribute boolean containerTimingIgnore;
};

6.3. Container Timing Record

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

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

[^containertiming^] コンテンツ属性を持つ HTMLElement が文書に接続されたとき：

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

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

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

6.5. containertiming 属性の削除

注： [^containertiming^] 属性が後で同じ要素に 再度追加された場合、次の描画時に新しい コンテナータイミングレコードが 作成されます。描画領域は新たに開始され、以前の描画データは保持されません。

6.6. コンテナールートの切断

注： 要素が [^containertiming^] 属性を引き続き 持ったまま文書に再接続された場合、新しい コンテナールートの登録として扱われます。次の描画時に、新しい コンテナータイミングレコードが、新しい 描画領域とともに作成されます。

6.7. コンテナータイミングのために描画された要素を処理する

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

6.8. コンテナータイミングエントリーを発行する

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

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

6.10. コンテナータイミングへの寄与

HTMLElement は、以下のすべてが真である場合、コンテナルートのコンテナタイミングに寄与する。

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

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

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

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

6.12. 最後の新規描画領域を必要に応じて更新する

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

注： このアルゴリズムは、サイズにかかわらず描画 領域に対するすべての変更を報告します。描画領域が 1 ピクセルだけ変更された場合でも、新しい PerformanceContainerTiming エントリーがキューに追加されます。小さな変更を除外したい開発者は、エントリー間の size の値を比較することで除外できます。

6.13. コンテナータイミングエントリーの作成

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