웹 애니메이션 최적화
핵심 규칙
실제 페이지를 먼저 측정하고 편집하세요. 목표는 모션을 제거하는 것이 아니라, 오프스크린 작업을 중지하고, 가시적인 모션이 올바르게 재개되며, 라우트/언마운트 정리가 오래 실행되는 리소스를 해제하도록 하는 것입니다.
가능하면 Codex Browser를 사용하세요. 특히 localhost 페이지에서 사용하세요. 사용자가 명시적으로 요청하지 않는 한 Chrome을 사용하지 마세요.
워크플로우
-
리포지토리 컨텍스트 검사.
AGENTS.md또는 로컬 지침을 읽습니다.- 초기에
git status --short를 실행합니다. - 페이지 컴포넌트, 애니메이션 훅, CSS
@keyframes,requestAnimationFrame,setInterval,setTimeout, 캔버스/WebGL/물리학 컴포넌트, 미디어 요소, GSAP 타임라인/트윈, 기존 가시성 유틸리티를 찾습니다. - 효과 정리(cleanup)에서 이벤트 리스너, 옵저버, RAF 루프, 인터벌, 타이머, 외부 스크립트, 미디어 스트림, WebGL 텍스처/재질/형상/렌더러, 언마운트 후 완료될 수 있는 비동기 작업을 검색합니다.
- 작업 트리가 더티(dirty)하면 처음부터 좁은 스테이징을 계획합니다.
-
브라우저에서 기준선 캡처.
- 사용자가 명명한 정확한 라우트를 엽니다.
- 레이아웃이 다를 수 있는 경우 상단, 중간, 하단/하단 콘텐츠, 모바일 뷰포트 한 곳에서 프로파일링합니다.
- 계산된
animationName,animationPlayState및 가시성별로 CSS 애니메이션을 계산합니다.::before및::after를 포함합니다. - 캔버스/WebGL 요소를 별도로 검사합니다. CSS 프로파일링만으로는 RAF 루프가 중지되었음을 증명할 수 없습니다.
- 어떤 애니메이션 이름이 오프스크린에서 실행 중이며 이를 담당하는 DOM 소유자를 기록합니다.
- 메모리/누수 요청의 경우, 요소/캔버스/이미지/iframe 개수, 노출된 JS 힙 메트릭(가능한 경우), 10-30초 후의 유휴 샘플, 짧은 라우트 사이클 샘플도 기록합니다. 힙 API가
null을 반환하거나 Browser 샌드박스가 몽키 패칭을 차단하는 경우, 그렇게 명시하고 안정적인 관찰 가능한 개수와 소스 감사에 의존합니다. - 스트레스 테스트를 제한합니다. 프로파일링 중 브라우저 탭 충돌은 과부하의 증거이지만, 최소 테스트로 재현되지 않는 한 원인을 과도하게 귀속시키지 마세요.
- 재사용 가능한 Codex Browser 평가자를 위해
references/browser-profiling.md를 참조하세요.
-
모션을 제어하는 가장 작은 소유자를 패치합니다.
- 앱에 기존 페이지 공개/가시성 훅이 있다면 선호합니다.
- 그렇지 않으면
IntersectionObserver를 추가하여 섹션과 애니메이션된 자식 요소에is-offscreen과 같은 안정적인 클래스를 토글합니다. - 대상이 지정된 규칙으로 CSS 애니메이션을 일시 중지합니다:
main > section.is-offscreen .expensive-animation,
.expensive-animation.is-offscreen {
animation-play-state: paused !important;
}
- 반복되는 카드 또는 플레이스홀더의 경우, 전체 문서가 아닌 카드 셸과 애니메이션된 자식을 관찰합니다.
- 마키/티커 트랙의 경우, 해당 섹션이 오프스크린일 때 트랙을 일시 중지합니다.
- 스켈레톤 로더 및 의사 요소 글리머의 경우, 필요한 곳에 `::before` 및 `::after` 일시 중지 선택기를 포함합니다.
- 캔버스/WebGL/물리학 루프의 경우, RAF 루프를 직접 게이트합니다:
- 캔버스/컨테이너가 교차할 때 시작합니다.
- 오프스크린이면 `requestAnimationFrame`을 취소합니다.
- 재진입 시 재개합니다.
- 정리 시 옵저버를 연결 해제하고 프레임을 취소합니다.
- 브라우저 확인에 도움이 될 때 `data-animation-active`와 같은 비시각적 디버그 마커를 추가합니다.
- 컴포넌트가 이미 그렇게 한다면 `prefers-reduced-motion`을 존중하고, 스크롤/애니메이션 상태에 대한 React 렌더 루프를 도입하지 마세요.
- 누수 방지를 위해:
- 효과에 의해 생성된 모든 타임아웃/인터벌을 지웁니다.
- 언마운트 전과 루프 재시작 전에 RAF를 취소합니다.
- `IntersectionObserver`, `ResizeObserver`, `MutationObserver` 및 사용자 정의 구독을 연결 해제합니다.
- 동일한 핸들러 참조로 전역/윈도우/문서 리스너를 제거합니다.
- Three/WebGL 텍스처, 재질, 형상, 렌더러를 폐기하고 렌더러 DOM 노드를 제거합니다.
- DOM 노드 및 셰이더 유니폼과 같은 변경 가능한 객체에 대한 GSAP 트윈/타임라인을 중지합니다.
- 미디어 스트림을 중지하고 분리된 비디오/오디오 소스를 일시 중지합니다.
- 비동기 로더를 `isDisposed` 플래그로 보호하고 언마운트 후 해결되면 로드된 리소스를 폐기합니다.
- React 정리에서, 린트가 ref가 변경될 수 있다고 경고하는 경우 효과 내부의 `ref.current` 값을 캡처한 후 정리 함수를 반환합니다.
- 가시성 일시 중지 후 물리학 또는 시뮬레이션 프레임 델타를 제한하여 지연된 프레임이 과도하게 큰 업데이트를 실행하지 않도록 합니다.
4. 빌드뿐만 아니라 동작을 확인합니다.
- 라우트를 다시 로드하고 동일한 상단/중간/하단/모바일 프로파일을 다시 실행합니다.
- 목표 결과: 테스트 중인 페이지 섹션에 대해 offscreenRunningCount: 0.
- 가시적인 애니메이션이 여전히 실행되거나 뷰로 스크롤될 때 재개되는지 확인합니다.
- RAF/캔버스 루프가 오프스크린에서는 비활성이고 뷰 내에서는 활성 상태이거나, 그렇지 않으면 소스/런타임 상태에서 취소를 증명하는지 확인합니다.
- 누수 감사의 경우, 이전/이후 라우트 사이클 및 유휴 샘플을 비교합니다. 예상되는 작은 비동기 콘텐츠 변경을 허용하면서, 반복 탐색 후 DOM/캔버스/이미지 개수가 동일한 기준선으로 돌아와야 합니다.
- 검색/필터/탐색과 같은 정상적인 페이지 상호 작용을 실행하여 옵저버가 동적 콘텐츠를 깨뜨리지 않는지 확인합니다.
- 새 탭의 콘솔 경고/오류를 확인합니다.
- 로컬 검사를 실행합니다.
- 리포지토리의 일반 게이트를 사용합니다. React/Vite 앱의 경우 종종 다음과 같습니다:
git diff --check
npm run lint
npm run build
- 알려진 비치명적 경고를 실패와 별도로 언급합니다.
6. 리포지토리 또는 사용자 지침에서 요청할 때 좁게 커밋합니다. - 관련 없는 더티 변경 사항이 있는 경우 격리된 인덱스를 사용합니다:
rm -f /tmp/<task>-index
GIT_INDEX_FILE=/tmp/<task>-index git read-tree HEAD
# 의도된 헌크만 임시 인덱스에 적용합니다.
GIT_INDEX_FILE=/tmp/<task>-index git diff --cached --check
GIT_INDEX_FILE=/tmp/<task>-index git commit -m "오프스크린 <page> 애니메이션 일시 중지"
git restore --staged <files> 2>/dev/null || true
- 모든 헌크가 작업에 속하지 않는 한 더티 작업 트리에서 광범위한 파일을 스테이징하지 마세요.
7. 증거와 함께 보고합니다. - 발견 사항을 먼저 제시합니다: 여전히 실행 중인 것, 누수 위험이 있는 것, 측정할 수 없었던 것. - 소스 감사 위험을 라이브 브라우저 측정과 분리합니다. - 정확한 샘플링된 라우트, 오프스크린 애니메이션 개수, DOM/캔버스 개수 안정성, 라우트 사이클 결과, 로컬 검사를 포함합니다. - 제한 사항, 특히 사용할 수 없는 힙 카운터 또는 차단된 브라우저 계측을 명확히 명시합니다.
좋은 수정 패턴
- 긴 섹션의 경우 아래쪽 화면 밖의 자식 애니메이션이 여전히 실행될 수 있으므로 Section 수준의
is-offscreen과 요소 수준의is-offscreen을 함께 사용합니다. COURSES_PAGE_ANIMATION_VISIBILITY_SELECTOR와 같이 라우트당 공유 가시성 선택자 상수.- 애니메이션 게이팅을 위한 약
0.01임계값의IntersectionObserver. - WebGL/캔버스 효과를 위한 직접 RAF 루프 제어; CSS
animation-play-state는 JavaScript 렌더 루프를 일시 중지할 수 없습니다. - 일시 중지 또는 지연된 프레임 후 재개되는 물리학 루프를 위한 프레임 델타 캡.
- GSAP/WebGL 효과에 사용되는 React ref를 위한 캡처된 정리 노드.
- 언마운트 후 해결될 수 있는 이미지/비디오/텍스처/데이터 로더를 위한
isDisposed가드. - 누적되는 DOM 노드, 캔버스, iframe 또는 해제되지 않은 미디어를 포착하기 위한 짧은 유휴 및 라우트 사이클 프로브.
피해야 할 것
- 프로파일을 통과시키기 위해 모든 애니메이션을 제거하는 것.
- 상위 선택기가 너무 광범위하기 때문에 가시적인 히어로 모션을 일시 중지하는 것.
animation-play-state가 의사 요소 또는 JavaScript RAF 루프를 포함한다고 가정하는 것.- 긴 페이지에서 단일 페이지 상단 측정을 신뢰하는 것.
- 사용할 수 없는 힙 카운터를 메모리 누수가 없다는 증거로 취급하는 것.
- 브라우저에서 무제한 스트레스 루프를 실행하는 것; 제한된 사이클을 사용하고 인과 관계를 과장하지 않고 충돌을 기록합니다.
- 성능 증거로 스크린샷만 사용하는 것.
- 관련 없는 로컬 헌크가 커밋에 포함되도록 허용하는 것.