제한 사항과 고려 사항

Vanilla Disintegrate는 브라우저 API 위에서 동작하므로 모든 DOM 콘텐츠, 브라우저, 기기에서 완전히 동일한 결과를 보장할 수 없습니다. 효과를 선택하고 성능을 조정할 때는 다음 제한 사항을 고려해야 합니다.

스냅샷은 DOM의 픽셀 단위 복사본이 아닙니다

내장 파티클 효과는 실제 DOM 노드가 아니라 요소의 Canvas 스냅샷을 애니메이션합니다. 2026년 현재 웹 플랫폼에는 개별 DOM 요소에서 이미 렌더링된 픽셀을 직접 복사할 수 있는 안정적이고 폭넓게 지원되는 API가 없습니다. 따라서 캡처 엔진은 요소의 외형을 다시 재현해야 합니다.

vanilla-disintegrate/snapdom 진입점은 SnapDOM을 사용합니다. 요소의 콘텐츠와 스타일을 SVG로 옮긴 다음 브라우저가 이를 Canvas로 변환합니다. 이 재래스터화 결과는 다음과 같은 부분에서 원본 DOM과 다를 수 있습니다.

• 텍스트 안티앨리어싱과 굵기
• 경계의 서브픽셀 위치
• 그림자, 필터, 마스크, 변환
• 기본값이 아닌 페이지 확대/축소 비율이나 소수점 devicePixelRatio에서의 결과
• 브라우저 엔진별 동작

카드, 이미지, 기타 큰 요소를 애니메이션할 때는 차이가 거의 눈에 띄지 않지만, 픽셀 단위 정확도가 중요한 개별 글리프나 가는 선에서는 차이가 보일 수 있습니다.

renderQuality: 'exact'의 역할

exact 모드는 파티클 렌더러 내부의 적응형 해상도 축소를 비활성화합니다. 이미 얻은 스냅샷의 세부 표현은 유지하지만 DOM 스냅샷 자체를 더 정확하게 만들지는 않으며, 텍스트 래스터화 차이도 보정하지 않습니다.

즉, exact는 원본 캡처의 정확도가 아니라 이후 렌더링 품질을 제어합니다.

캡처 엔진 교체

IIFE 번들은 SnapDOM을 기본 캡처 어댑터로 사용합니다. 성능은 이를 선택할 때 고려한 요소 중 하나입니다. 2026년 현재 프로젝트가 공개한 비교 벤치마크는 다양한 복잡도의 DOM 요소를 캡처할 때 지연 시간이 짧다는 결과를 보여 줍니다. 실제 속도는 콘텐츠, 브라우저, 기기에 따라 달라지며 캡처 방식이 브라우저 래스터화의 한계를 없애 주지는 않습니다.

capture 옵션은 <canvas>를 반환할 수 있는 모든 어댑터를 허용하므로 프로젝트에서 다른 엔진이나 자체 구현을 사용할 수 있습니다. 전체 어댑터 계약은 캡처 API를 참고하세요.

그렇지만 SnapDOM을 포함해 당시 사용할 수 있는 어떤 DOM-to-Canvas 솔루션도 모든 콘텐츠에 픽셀 단위 정확도를 보장하지는 않습니다. 엔진마다 텍스트, 이미지, SVG, 폼 컨트롤, 의사 요소, 브라우저 효과를 처리하는 방식이 다릅니다.

동적 콘텐츠

스냅샷은 특정 시점의 요소 상태를 기록합니다. 캡처 이후의 DOM, 스타일, 크기 또는 로드된 리소스 변경 사항은 해당 스냅샷에 반영되지 않습니다.

요소를 캡처하기 전에는 다음 작업이 끝날 때까지 기다리는 것이 좋습니다.

• 사용 중인 글꼴 로드
• 이미지 디코딩
• 전환과 일시적인 애니메이션
• 요소의 최종 크기 계산

미리 준비한 스냅샷은 첫 효과를 더 빠르게 시작하지만 요소가 변경되면 오래된 상태가 될 수 있습니다. 기본적으로 라이브러리는 크기가 변경될 때 캐시를 무효화하지만 전체 DOM 하위 트리를 관찰하지는 않습니다. 콘텐츠가 크게 바뀐 뒤에는 invalidate()를 호출하거나 추가 관찰 비용이 적절한 경우 observeMutations를 활성화하세요.

WebGL2 제한

WebGL2는 내장 파티클 효과에만 필요합니다. 라이브러리 코어와 사용자 효과는 Web Animations API, Canvas 2D, CSS 또는 자체 렌더러를 사용할 수 있습니다.

WebGL2를 사용할 수 없거나 브라우저가 컨텍스트를 만들지 못해도 DOM 작업은 그대로 실행됩니다. 다만 시각 효과는 skipped 상태로 끝나고 원인은 onError로 전달됩니다.

동시에 실행되는 각 내장 효과는 WebGL2 컨텍스트 하나를 사용합니다. 라이브러리는 효과가 끝난 컨텍스트를 재사용하고 공유 풀의 크기를 제한하지만, 브라우저, GPU 또는 드라이버가 더 엄격한 한도를 적용할 수 있습니다.

성능 비용

일반적인 인터페이스 요소와 소수의 동시 효과에서는 최신 기기에 가해지는 부하가 일시적이며 대부분 체감되지 않습니다. CPU는 스냅샷 생성에 관여하고 내장 파티클 애니메이션은 WebGL2를 통해 GPU에서 실행됩니다. 작업이 끝나면 임시 텍스처를 삭제하고 WebGL2 컨텍스트를 크기가 제한된 풀로 반환해 재사용합니다.

큰 요소, 높은 픽셀 밀도, 많은 동시 효과 또는 exact 모드를 사용할 때는 비용이 더 눈에 띌 수 있습니다. auto 모드는 저사양 기기를 포함한 대부분의 인터페이스에 적합합니다. 작업 해상도를 제한하기 때문입니다. 추가 선명도가 실제로 눈에 띄는 작은 요소에만 exact를 선택적으로 사용하세요.

브라우저 지원

런타임은 ES2020 형식으로 출력되며 Canvas, Web Animations API(Animation.finished 및 Element.getAnimations()), AbortController, requestAnimationFrame에 의존합니다. 내장 프리셋에는 WebGL2도 필요합니다.

폴리필은 포함되지 않습니다. 이 버전은 API 호환성의 최소 기준이며 모든 GPU, 드라이버 또는 브라우저 설정에서 WebGL2 컨텍스트를 만들 수 있음을 보장하지는 않습니다.

브라우저 지원 여부가 렌더링 엔진, 페이지 확대/축소 비율, 기기에 관계없이 동일한 DOM 스냅샷 래스터화를 보장하는 것은 아닙니다.

Disintegrator는 서버 렌더링 중이 아니라 브라우저에서만 생성하세요. 교차 출처 이미지, 글꼴, 스타일시트는 CORS를 허용하거나 캡처 어댑터의 프록시 옵션을 사용해야 하며, 그렇지 않으면 Canvas 스냅샷에서 빠질 수 있습니다.

권장 사항

가장 자연스러운 전환을 얻으려면 다음을 권장합니다.

• 개별 글리프보다 완전한 요소와 블록을 애니메이션합니다.
• 지원하는 모든 브라우저에서 결과를 확인합니다.
• 타당한 경우에만 exact를 사용합니다.
• 캡처하는 동안 요소의 콘텐츠를 변경하지 않습니다.
• 동영상, <iframe>, Canvas, WebGL, 교차 출처 리소스는 별도로 테스트합니다.
• 필요한 경우 용도에 맞는 capture 어댑터를 제공합니다.