ペイントタイミング

1. はじめに

const observer = new PerformanceObserver(function(list) {
    const perfEntries = list.getEntries();
    for (const perfEntry of perfEntries) {
        // エントリーの処理
        // 分析や監視のための報告
        // ...
    }
});

// ペイントタイミング通知のためのオブザーバ登録
observer.observe({entryTypes: ["paint"]});

2. 用語

ペイント：ユーザーエージェントが「ペイント」（または「レンダー」）を実行したとは、レンダーツリーを画面上のピクセルに変換したことを指します。正式には、ユーザーエージェントがイベントループのレンダリングの更新ステップを実行したときに「レンダー」されたとみなします。

注意: レンダリング処理は非常に複雑であり、タイムスタンプはユーザーエージェントがこのパイプラインで記録できる最新のタイムスタンプ（ベストエフォート）であるべきです。通常、このAPIではフレームがOSへ表示のため送信される時刻が推奨されます。

生成コンテンツ疑似要素は、以下すべてを満たす場合ペイント可能疑似要素です：

• 疑似要素の使用済みのvisibilityはvisibleです。

• 疑似要素の使用済みのopacityは0より大きいです。

• 疑似要素は非空のボックスを生成します。

CSS画像 imgは、以下すべてを満たす場合内容画像です：

• imgがurl値を持つ。

• imgが利用可能である。

DOMString は、非空であるとは、文書の空白文字以外の文字を1文字以上含む場合です。

要素 targetは、次のいずれかを満たす場合内容有りです：

• targetがテキストノードを子に持ち、非空テキストを表し、そのノードのused opacityが0より大きい。

  注意: これは組版疑似要素がテキストノードのopacityを上書きする場合をカバーします。

• targetが置換要素で、利用可能な画像を表す。

• targetがbackground-imageとして内容画像を持ち、used background-sizeの幅と高さが0でない値である。

• targetが canvas で、context modeがnone以外に設定されている。

• targetが video 要素で、表すポスターフレームまたは最初の動画フレームがあり、そのフレームが利用可能である。

• targetが描画された子孫を持つsvg要素である。

• targetが input 要素で、非空 value 属性を持つ。

• targetが起点要素で、ペイント可能疑似要素を表し、それが内容画像または非空テキストを表す。

要素は、以下のいずれかの場合タイミング対象です：

• img 要素。

• image 要素が svg 要素内に存在する場合。

• video 要素でポスターフレームを持つ場合。

• 要素が内容有りなbackground-imageを持つ場合。

• テキストノード。

ペイント可能境界矩形を要素targetで計算するには、次の手順を実行します：

1. boundingRectをgetBoundingClientRect() をtargetで実行した結果とする。

2. boundingRectを文書のスクロール領域でクリップする。

3. boundingRectを返す。

注意: overflow: scrollやoverflow: hiddenなボックスに含まれる要素は、ペイント可能境界矩形がクリップされません。どちらの場合でも、要素はスクロール操作で可視化できるためです。

要素 elは、次の全てを満たす場合ペイント可能です：

• elが描画されている。

• elの使用済みのvisibility はvisibleです。

• elおよび全ての祖先のused opacityが0より大きい。

  注意: ペイント可能な要素でも、例えばテキストが背景色と同じ場合など、ユーザーに見えない場合があります。これらの要素も最初の内容ペイントの計算にはペイント可能と見なします。

• elのペイント可能境界矩形が文書のスクロール領域と交差している。

  注意: 要素がゼロサイズに拡大縮小されている場合、display: noneやdisplay: contentsで空の矩形になる場合などをカバーします。

  注意: 一般的に、要素はビュー ポート内か、スクロールやズームによってビュー ポート内になる可能性があるならペイント可能です。

最初のペイントエントリには、ユーザーエージェントがナビゲーション後に初めてレンダーした時刻を示すDOMHighResTimeStampが含まれます。これはデフォルトの背景ペイントを除外しますが、非デフォルトの背景ペイントやiframeの囲みボックスは含みます。これはページロードで開発者が関心を持つ最初の重要な瞬間、すなわちユーザーエージェントがページのレンダリングを開始した瞬間です。

ブラウジングコンテキスト ctxは、以下のいずれかを満たす場合ペイントタイミング対象です：

• ctxが最上位ブラウジングコンテキストである。

• ctxが入れ子ブラウジングコンテキストで、ユーザーエージェントがctxにペイントタイミング報告を設定している。

  注意: これにより、ユーザーエージェントはメインフレーム以外の一部フレームに対してのみペイントタイミングを有効化できます。例えば、ユーザーエージェントがメインフレームの情報を漏らす可能性がある場合、クロスオリジンiframeに対してペイントタイミングを無効化することもできます。

3. ペイントタイミングミキシン

3.1. PaintTimingMixin インターフェース

[Exposed=Window]
interface mixin PaintTimingMixin {
    readonly attribute DOMHighResTimeStamp paintTime;
    readonly attribute DOMHighResTimeStamp? presentationTime;
};

PaintTimingMixin インターフェースミキシンを含むオブジェクトには、関連付けられたペイントタイミング情報（nullまたはペイントタイミング情報）があります。

ペイントタイミング情報は、 構造体です。以下の項目を持ちます:

レンダリング更新終了時間

DOMHighResTimeStamp

実装依存の提示時間

Null または DOMHighResTimeStamp

paintTime 属性のゲッターステップは、this の ペイントタイミング情報 の レンダリング更新終了時間 を返します。

presentationTime 属性のゲッターステップは、存在する場合、this の ペイントタイミング情報 の 実装依存の提示時間 を返します。

ペイントタイミング情報 paintTimingInfo のデフォルトペイントタイムスタンプを取得するには、 paintTimingInfo の 実装依存の提示時間 が null でない場合はそれを返し、それ以外の場合は paintTimingInfo の レンダリング更新終了時間 を返します。

4. PerformancePaintTiming インターフェイス

[Exposed=Window]
interface PerformancePaintTiming : PerformanceEntry {
    [Default] object toJSON();
};
PerformancePaintTiming includes PaintTimingMixin;

PerformancePaintTiming は PerformanceEntry インターフェイスの下記属性を拡張します：

• name 属性のgetterは、最小限のフレーム属性付けのために DOMString を返す必要があります。nameの可能な値は以下の通りです：

  • "first-paint"：first paint のため

  • "first-contentful-paint"：first contentful paint のため

• entryType 属性のgetterは "paint" を返す必要があります。

• startTime 属性のgetterは、ペイントが発生した時刻の DOMHighResTimeStamp を返す必要があります。

• duration 属性のgetterは 0 を返す必要があります。

• toJSON が呼び出されたとき、default toJSON steps を PerformancePaintTiming に対して実行してください。

NOTE: PerformancePaintTiming を実装するユーザーエージェントは、"paint" を supportedEntryTypes に含める必要があります。 グローバルオブジェクト の ブラウジングコンテキスト が paint-timing eligible である場合です。 これにより、開発者は特定の ブラウジングコンテキスト に対してペイントタイミングのサポートを検出できます。

5. 処理モデル

5.1. 関連付けられた画像リクエスト

各 Element には 関連付けられた画像リクエスト があり、これは 画像リクエスト または null で、初期値は null です。

Element 型の element の処理モデルが HTMLImageElement, SVGImageElement, または HTMLVideoElement が新しい画像リソース（例：画像やポスター画像として表示されるため）を作成するとき、 element の 関連付けられた画像リクエスト は作成された画像リソースの 画像リクエスト に設定されます。

Note: URLの scheme が "data" である画像リソースは、取得されませんが依然として読み込む必要がある 画像リクエスト を持ちます。このリクエストは Element の 関連付けられた画像リクエスト となり得ます。

Note: 現在の記述は具体的な アルゴリズムには言及していないため曖昧です。該当する処理モデルがより統一された処理モデルを持つ場合、より厳密に記述できます。

全ての Element は 関連付けられた背景画像リクエスト のリストを持ち、初期値は空の配列です。Element element のスタイルが新しい画像リソース（背景画像として表示されるため）を必要とする場合、新しいリソースによって作成された 画像リクエスト が element の 関連付けられた背景画像リクエスト に追加されます。

NOTE: Element は複数の 画像リクエスト を持つことができます。例えば、 background-image プロパティが複数値を持つ場合です。下記例では、一つの background-image プロパティが4つの 画像リクエスト を生成し、それぞれが下記アルゴリズムで記録・報告されます。

<!DOCTYPE html>
<style>
div {
  background-image: url(https://images.example/background1.png),
                    url(https://images.example/background2.png);
}
</style>
<div></div>
<div></div>

5.2. ペイントタイミングの記録

pending image record は、以下の 構造体の 要素を持つものです。

• element、Element

• request、画像リクエスト

• loadTime、DOMHighResTimeStamp

Element は所有テキストノード集合（初期値は空の順序付き集合で、Text ノードを含む）を持ちます。

Document は過去に報告されたペイント集合（初期値は空の順序付き集合で、文字列を含む）を持ちます。

Document はレンダリング待ち画像（初期値は空のリストで、保留画像レコードを含む）を持ちます。

Document は描画済みテキストを持つ要素集合（初期値は空の順序付き集合で、Elementを含む）を持ちます。

5.2.1. CSS仕様への修正

画像リクエストがElementelementの関連背景画像リクエスト内で完全に利用可能となった場合、elementおよび画像リクエストを入力として読み込み完了画像の処理アルゴリズムを実行します。

5.2.2. HTML仕様への修正

Element elementの関連画像リクエストが完全に利用可能となった場合、elementとその関連画像リクエストを入力として読み込み完了画像の処理アルゴリズムを実行します。

5.2.3. 読み込み完了画像の処理

5.3. ペイントタイミングの報告

5.3.1. 最初の内容ペイント

5.3.2. ペイントタイミングのマーク

5.3.3. ペイントタイミングの報告

5.4. 共通アルゴリズム

5.4.1. ペイントタイミング向け公開

6. 謝辞

この仕様の技術的な貢献・提案を通じて改善に導いてくださった全てのコントリビューターに特別な感謝を表します。