컨테이너 타이밍 API

1. 소개

Container Timing API는 주석이 지정된 DOM 섹션이 화면에 표시되고 초기 페인트가 완료되는 시점을 모니터링할 수 있도록 합니다. 개발자는 containerTiming 속성(Element Timing API의 elementtiming과 유사함)을 사용하여 DOM의 하위 섹션을 표시하고, 해당 섹션이 처음으로 페인트되었을 때 성능 엔트리를 받을 수 있습니다.

이 API를 통해 개발자는 페이지 안의 여러 컴포넌트 타이밍을 측정할 수 있다. 개발자가 애플리케이션을 점점 더 컴포넌트 단위로 구성함에 따라, 애플리케이션이나 웹 페이지의 하위 섹션에 대한 성능을 측정하려는 수요가 커지고 있다.

Element Timing과 달리, DOM의 한 섹션이 언제 페인트를 완료했는지 렌더러가 알 수는 없다(향후 변경, 새 이미지에 대한 비동기 요청, 느리게 로드되는 버튼 등이 있을 수 있음). 따라서 이 API는 업데이트가 있었을 때 PerformanceEntry 객체 형식의 후보를 내보낸다.

2. 동기

개발자는 테이블, 위젯 또는 기타 컴포넌트와 같은 DOM의 하위 섹션이 언제 페인트되었는지 측정하여 페인트 시간을 추적하고 분석 시스템에 제출하려 한다. 현재 웹 API는 이를 충분히 지원하지 않는다.

• Element Timing은 지원할 수 있는 범위가 제한되어 있으며 전체 섹션에는 사용할 수 없다.

• Largest Contentful Paint(LCP)는 페이지의 특정 부분이 언제 로드되었는지 측정하는 데 충분히 유용하지 않다.

• 사용자 공간 폴리필에는 다음과 같은 상당한 단점이 있다.

  • 페인트 전에 요소를 표시해야 함(서버 측 변경 또는 렌더링 차단이 필요함)

  • 새로 삽입된 요소를 포착하기 위해 MutationObserver가 필요함

  • 문서 head에서 실행되어야 하므로 첫 페인트까지의 시간이 증가함

  • 브라우저 내장 2D 엔진과 비교해 사각형 추적 효율이 낮을 수 있음

웹 작성자는 자신의 도메인을 누구보다 잘 알고 있으며, 사용자나 조직이 이해할 수 있는 방식으로 자신들의 콘텐츠 블록 성능을 전달하려 한다(예: "첫 트윗까지의 시간").

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()로 인해), 이전에 누적된 사각형은 조정되지 않으며 — 영역은 뷰포트 좌표에서 계속 확장됩니다.

컨테이너 타이밍 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. 처리 모델

참고: 컨테이너 타이밍 API를 구현하는 사용자 에이전트는 supportedEntryTypes에 "container"를 포함해야 한다. 이는 Window 컨텍스트에 적용된다. 이를 통해 개발자는 컨테이너 타이밍 지원 여부를 감지할 수 있다.

6.1. 문서별 상태

각 Document에 대해, 사용자 에이전트는 컨테이너 루트 레코드 맵을 유지해야 하며, 이 맵은 컨테이너 루트 HTMLElement를 컨테이너 타이밍 레코드 객체에 매핑합니다.

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. 컨테이너 타이밍 레코드

이 명세는 처리 모델에서 사용하는 내부 데이터 구조를 정의합니다:

6.5. 컨테이너 루트 등록

다음 HTMLElement 요소에 containerTiming 콘텐츠 속성이 있고 문서에 연결되면:

1. 사용자 에이전트는 요소를 컨테이너 루트로 등록해야 합니다.

2. 사용자 에이전트는 컨테이너 루트에 대해 빈 페인트된 영역을 초기화해야 합니다.

3. 사용자 에이전트는 컨테이너 루트의 서브트리 내 모든 페인트 작업을 추적해야 하며, 모든 무시되는 서브트리는 제외합니다.

6.6. containertiming 속성 제거

참고: containerTiming 속성이 나중에 동일한 요소에 다시 추가되면, 새로운 컨테이너 타이밍 레코드가 다음 페인트 시 생성됩니다. 페인트된 영역은 새로 시작하며 — 이전 페인트 데이터는 보존되지 않습니다.

6.7. 컨테이너 루트 연결 해제

참고: 요소가 문서에 다시 연결되고 여전히 containerTiming 속성을 가지고 있으면, 새로운 컨테이너 루트 등록으로 취급됩니다. 새로운 컨테이너 타이밍 레코드가 새로운 페인트된 영역과 함께 다음 페인트 시 생성됩니다.

6.8. 컨테이너 타이밍을 위해 페인트된 요소 처리

참고: 이 알고리즘은 페인트되는 각 이미지 또는 텍스트 노드에 대해 호출됩니다. 교차 사각형은 요소를 대상으로 하고 뷰포트를 루트로 하여 교차 사각형 알고리즘을 사용해 계산한 뒤 시각적 뷰포트와 교차시켜야 합니다. 텍스트 노드의 경우, 교차 사각형은 소유된 텍스트 노드 집합에 있는 모든 텍스트 노드의 테두리 상자를 포함하는 최소 사각형이며, 시각적 뷰포트와 교차됩니다.

참고: 컨테이너 타이밍은 콘텐츠의 초기 렌더링을 측정하기 위한 것입니다. 사용자가 문서를 스크롤하거나 상호작용한 후에는 페인트가 더 이상 기록되지 않습니다. 해당 페인트는 페이지 로딩이 아니라 그 스크롤 또는 상호작용의 결과(예를 들어, 콘텐츠가 스크롤되어 보이게 되거나 클릭으로 표시됨)일 가능성이 높기 때문입니다. 이미 보류 중인 항목은 현재 프레임에 대해서는 계속 내보냅니다.

6.9. 컨테이너 타이밍 항목 내보내기

참고: 페인트된 요소당 여러 항목을 내보낼 수 있는 일부 다른 페인트 타이밍 API와 달리, 컨테이너 타이밍은 각 컨테이너 루트의 페인트된 영역을 누적하고 프레임당 컨테이너 루트마다 최대 하나의 PerformanceContainerTiming 항목을 내보냅니다. 이 일괄 처리 방식은 더 효율적이며 컨테이너의 페인트 상태에 대한 전체적인 관점을 제공합니다.

6.10. 부모 컨테이너 루트 Element 가져오기

6.11. 컨테이너 타이밍에 기여

HTMLElement가 다음 조건을 모두 충족하면 컨테이너 루트의 컨테이너 타이밍에 기여합니다:

• 컨테이너 루트의 자손입니다.

• 무시되는 서브트리 내에 있지 않습니다.

• 섀도 트리에 있지 않습니다.

6.12. 컨테이너 루트 Element 가져오기

6.13. 마지막 새 페인트 영역을 필요에 따라 업데이트

참고: lastPaintedElement 는 단일 렌더링 프레임 내에서 가장 큰 새 페인트 영역에 기여한 요소입니다. 이를 통해 구현별 페인트 순서에 대한 의존성을 피할 수 있습니다. lastPaintedElement 는 크거나 복잡한 컨테이너 루트(예: 테이블)의 업데이트를 무엇이 유발하는지 조사하는 개발자를 위한 디버깅 보조 수단이며, 그 자체로 독립적인 성능 지표는 아닙니다. lastNewPaintedAreaSize는 항목을 내보낸 후 재설정되므로 각 프레임의 비교가 새로 시작됩니다.

참고: 이 알고리즘은 페인트된 영역의 크기와 관계없이 모든 변경을 보고합니다. 페인트된 영역이 1픽셀만 변경되어도 새로운 PerformanceContainerTiming 항목이 큐에 추가됩니다. 작은 변경을 필터링하려는 개발자는 size 값을 항목 간에 비교하여 필터링할 수 있습니다.

6.14. 컨테이너 타이밍 항목 생성

7. 보안 및 개인정보 보호 고려사항

7.1. 교차 출처 제한

이 API는 교차 출처 경계를 존중한다.

• 교차 출처 iframe에 속한 요소는 부모 프레임에 노출되지 않는다.

• 개발자가 postMessage를 통해 명시적으로 전달하지 않는 한, 타이밍 정보는 프레임 경계를 넘지 않는다.

7.2. 정보 노출

이 API가 제공하는 대부분의 정보는 기존 API를 통해 이미 추정할 수 있다.

• Element Timing은 이미지와 텍스트의 최초 렌더링 시간을 반환한다.

• Paint Timing API는 관련 타임스탬프를 제공한다.

• 이러한 API들의 조합은 컨테이너 타이밍 정보를 근사할 수 있지만, 효율성은 더 낮다.

이 API는 다음을 노출하지 않는다.

• 렌더링 엔진의 내부 구현 세부사항

• 개발자가 이미 접근 권한을 갖고 있지 않은 요소에 대한 정보

• 기존 Performance API를 통해 이미 사용할 수 있는 것보다 더 세밀한 타이밍 정보

7.3. 타이밍 공격

이 API는 DOMHighResTimeStamp를 사용하며, 이는 다른 Performance API와 일관되게 보안 목적의 해상도 제한을 받을 수 있다.

7.4. 개인정보 보호 고려사항

이 API는 다음을 하지 않는다.

• 사이트 간 사용자 추적을 가능하게 하지 않는다

• 브라우징 기록을 노출하지 않는다

• 사이트가 스크립트 실행을 통해 이미 접근할 수 있는 범위를 넘어서는 사용자 행동 정보를 제공하지 않는다

8. 감사의 말

소중한 피드백과 조언을 주신 다음 분들께 깊이 감사한다.

• Barry Pollard

• Michael Mocny

• Scott Haseley

• Sergey Chernyshev

• Bas Schouten