프론트엔드 키트

with-canvas

캔버스 작업은 두 가지 방식으로 실패합니다: 예쁘지만 버벅거리는 시각적 코드와 유지보수 불가능하거나 접근성이 떨어지는 최적화 코드입니다. 모든 작업을 그리기 호출을 작성하기 전에 렌더링 아키텍처 결정으로 취급하세요. 현재 단계에서 명명된 참조만 로드하고, 모든 참조를 미리 로드하지 마세요.

1단계 - 캔버스 작업 분류

API를 선택하기 전에 지배적인 작업 부하를 식별하세요:

• 캔버스 거부: 장면이 주로 텍스트, 접근 가능한 컨트롤, 문서 레이아웃, 단순 아이콘, CSS 애니메이션, 미디어 재생, 또는 소수의 확장 가능한 벡터 모양인 경우 DOM/CSS/SVG/비디오를 선호합니다.
• 장식용 애니메이션: 비대화형 분위기, 배경 입자, 별, 새, 절차적 루프.
• 데이터 렌더링: 차트, 지도, 히트맵, 대규모 점군, 자주 업데이트되는 측정값.
• 생성 예술: 시드/랜덤 드로잉, 창의적인 스케치, 절차적 시스템, 내보내기 가능 이미지.
• 대화형 도구: 포인터/키보드 입력, 선택, 드래그, 편집 가능한 객체, 히트 테스팅.
• 게임/시뮬레이션: 고정 업데이트 루프, 동적 엔티티, 충돌/물리, 레이어드 씬.
• WebGL/엔진 캔버스: GPU 리소스를 소유하는 Three.js/Babylon.js/기타 렌더러.

필독: 작업 부하가 장식용 애니메이션 또는 생성 예술인 경우 references/visual-quality.md를 읽으세요. 이 두 작업의 경우 멋지게 보이는 것이 작업이며, 성능/접근성 위생만으로는 일반적인 결과물이 나옵니다. 데이터 렌더링, 도구, 게임 또는 엔진 캔버스에는 로드하지 마세요.

종료 조건: 작업 부하, 캔버스가 올바른 기본 요소인 이유, 목표 프레임 속도, 예상 객체 수, 상호작용 모델, 캔버스가 장식용인지 의미론적으로 중요한지 명시하세요.

2단계 - 렌더링 모델 선택

장면이 주로 즉시 모드 드로잉, 픽셀 작업, 스프라이트, 간단한 애니메이션 또는 번들 크기가 중요한 경우 원시 Canvas 2D를 사용하세요.

앱에 편집 가능한 객체, 선택, 드래그/드롭, 레이어드 씬 그래프, 이벤트 위임 또는 직렬화가 필요한 경우 보존 모드 라이브러리를 사용하세요.

setup/draw 인체공학이 프레임워크 통합보다 더 중요한 스케치, 생성 예술, 교육/프로토타이핑 또는 창의적 코딩에는 p5.js를 사용하세요.

벡터 편집 워크플로우(경로, 세그먼트, 베지어 지오메트리, 히트 테스팅, SVG 가져오기/내보내기, 레이어드 벡터 문서)에는 Paper.js를 사용하세요.

React/Vue/Svelte 통합, 드래그 가능한 모양, 레이어, 캐시된 모양, 이벤트 수신 컨트롤이 있는 앱 UI 캔버스에는 Konva를 사용하세요.

구성 요소 모델이 프로젝트에 적합하고 종속성 최신성이 허용 가능한 경우 가벼운 씬/컴포넌트 추상화에는 Pencil.js를 사용하세요.

지배적인 비용이 3D/GPU 렌더링, 셰이더, 카메라, 재질 또는 대규모 메시/스프라이트 작업 부하인 경우 Three.js/Babylon.js 또는 WebGL을 직접 사용하세요.

필독: 라이브러리를 선택하거나 라이브러리 선택을 검토하는 경우 references/library-selection.md를 읽으세요. 작업이 해당 단계에 도달하지 않는 한 성능 또는 검토 참조를 로드하지 마세요.

캔버스 라이브러리를 설치하거나 중요하지 않은 라이브러리 API 코드를 작성하기 전에 사용 가능한 경우 Context7로 최신 문서를 확인하고, 그렇지 않으면 공식 문서를 사용하세요. p5.js, Paper.js, Pencil.js, Konva, ZIM, Three.js 또는 Babylon.js에 대해 기억된 API에 의존하지 마세요.

종료 조건: 모델 이름과 거부된 대안을 한 줄 이유와 함께 명시하세요.

3단계 - 루프와 상태 설계

캔버스 코드를 수명 주기, 상태 업데이트, 렌더링, 입력, 크기 조정, 해체로 분리하세요. 프레임워크 컴포넌트의 경우 명령형 캔버스 엔진을 하나의 마운트/초기화 경계 뒤에 유지하세요.

보이는 애니메이션에는 requestAnimationFrame을 사용하세요. 새로 고침 빈도에 관계없이 시뮬레이션 속도가 안정적이어야 하는 경우 RAF 타임스탬프에서 delta를 추적하세요. 해체 시 RAF를 취소하고, 숨겨졌을 때 작업을 일시 중지하거나 줄이고, prefers-reduced-motion을 존중하세요.

다음 다시 그리기 전략 중 하나를 선택하세요:

• 전체 다시 그리기: 단순함이 중요한 소규모/장식용 장면에 허용 가능.
• 더티 직사각형: 경계가 작고 배경이 안정적인 이동 객체.
• 레이어드 캔버스: 정적/느린 배경, 동적 엔티티, UI/상호작용 오버레이.
• 스프라이트/캐시 블릿: 반복되는 비용이 많이 드는 모양, 텍스트, 마커, 크기 조정된 이미지, 입자.
• 워커 OffscreenCanvas: 입력/메인 스레드와 경쟁하는 무거운 드로잉 또는 시뮬레이션.

필독: 애니메이션, 대규모 장면, 입자, 차트, 이미지 크기 조정, 고해상도 출력 또는 워커 렌더링을 최적화하기 전에 references/performance.md를 읽으세요. 라이브러리를 추가/교체하지 않는 한 라이브러리 선택을 로드하지 마세요.

종료 조건: 프레임 파이프라인을 순서대로 작성하세요: 입력 샘플링 -> 업데이트 -> 지우기/다시 그리기 전략 -> 그리기 -> 다음 프레임 예약.

4단계 - 캔버스 위생 구현

CSS만이 아닌 백킹 스토어로 캔버스 크기를 조정하세요. 선명한 출력을 위해 CSS 크기를 별도로 설정하고 canvas.width/height = cssSize * devicePixelRatio를 설정한 다음 ctx.setTransform(dpr, 0, 0, dpr, 0, 0)으로 변환을 정규화하세요. 성능이 중요한 장면에서는 의도적으로 DPR을 낮추세요.

장면에 맞는 옵션으로 컨텍스트를 초기화하세요. 불투명 캔버스에는 { alpha: false }를 사용하세요. willReadFrequently: true는 빈번한 getImageData 읽기에만 사용하세요. 백킹 전략을 변경할 수 있기 때문입니다.

입력의 경우 getBoundingClientRect()와 캔버스 스케일을 통해 포인터 좌표를 변환하세요. clientX/clientY를 캔버스 좌표로 신뢰하지 마세요.

접근성을 위해 장식용 캔버스에는 aria-hidden="true"를 설정하고 대화형 핸들러를 배치하지 마세요. 의미 있는 캔버스 상호작용에는 DOM 컨트롤, 키보드 경로, 포커스 관리, 레이블 또는 이에 상응하는 비캔버스 표현이 필요합니다.

종료 조건: 크기 조정, DPR, 컨텍스트 옵션, 이벤트 좌표 매핑, 모션 환경설정 및 해체가 모두 명시적이어야 합니다.

5단계 - 검토 및 확인

캔버스 코드를 핫 루프와 리소스 수명 주기로 검토하세요. 시각적 정확성에서 멈추지 마세요.

필독: 기존 캔버스 코드를 검토하거나 새 구현을 마무리하기 전에 references/review-checklist.md를 읽으세요. 검토에 종속성 적합성이 포함되지 않는 한 라이브러리 선택을 로드하지 마세요.

작업에 적합한 최소한 하나의 런타임 신호로 확인하세요: Chrome 성능 패널, FPS 측정기, 메모리 스냅샷, 상호작용 지연 시간, 축소 모션 경로, 숨겨진 탭 동작 또는 저사양/모바일 스로틀링.

예시

• 사용자가 "입자 배경 만들어 줘"라고 요청: 장식용 애니메이션으로 분류하고, 입자 수 또는 절차적 드로잉이 캔버스를 정당화하는 경우에만 DOM/SVG를 거부한 다음, 외관을 위해 references/visual-quality.md를, 루프를 위해 references/performance.md를 읽습니다.
• 사용자가 "선택 기능이 있는 드래그 가능한 모양 만들어 줘"라고 요청: 대화형 도구로 분류하고, references/library-selection.md를 읽은 다음, 객체 모델에 따라 Konva/Paper.js/원시 Canvas 2D를 선택할 가능성이 높습니다.
• 사용자가 "이 캔버스 루프 검토해 줘"라고 요청: 기존 작업 부하를 분류하고, references/review-checklist.md를 읽고, 버벅거림, 높은 객체 수 또는 핫 경로 문제가 나타나는 경우에만 references/performance.md를 읽습니다.
• 사용자가 "p5 스케치 추가해 줘"라고 요청: references/library-selection.md를 읽고, API 코드 전에 최신 p5 문서를 확인한 다음, 프레임워크 수명 주기 경계를 명시적으로 유지합니다.

절대 하지 말 것

• 절대 그려진 캔버스에 CSS로만 크기 조정하지 마세요 대신: 백킹 스토어 크기와 CSS 크기를 의도적으로 설정하고, 크기 조정 후 DPR 변환을 한 번 적용하세요. 이유: CSS 전용 스케일링은 출력을 흐리게 하고 레티나 디스플레이에서 더 악화되는 백킹 스토어 불일치를 숨깁니다.

• 절대 해체 경로 없이 RAF 루프를 시작하지 마세요 대신: 프레임 ID를 저장하고, 마운트 해제/해제 시 취소하고, 가시성 또는 미디어 쿼리 변경 후 이중 시작을 방지하세요. 이유: 고아 루프는 분리된 캔버스를 계속 그리고 메모리/CPU 누수를 생성하며, 스냅샷이 종종 브라우저 내부의 잘못된 원인으로 돌립니다.

• 절대 시각적으로 장면의 일부이기 때문에 비용이 많이 드는 정적 콘텐츠를 매 프레임 다시 그리지 마세요 대신: 오프스크린 캔버스, 이미지 비트맵, 레이어 캔버스, Path2D 또는 라이브러리 모양 캐시에 캐시하세요. 이유: 캔버스는 즉시 모드입니다. 변경되지 않은 비주얼은 명시적으로 캐시하거나 레이어링하지 않는 한 여전히 전체 그리기 시간이 소요됩니다.

• 절대 캔버스 전용 상호작용을 유일한 접근 가능한 컨트롤로 사용하지 마세요 대신: DOM 컨트롤/시맨틱 또는 키보드 조작 가능한 보존 객체 모델과 레이블 및 포커스 동작을 제공하세요. 이유: 캔버스 픽셀은 보조 기술에 역할, 이름, 상태 또는 히트 대상을 노출하지 않습니다.

• 절대 성능이 나쁘다고 OffscreenCanvas로 캔버스 작업을 옮기지 마세요 대신: 먼저 병목 현상이 그리기 호출, 상태 변경, 오버드로우, 이미지 크기 조정, 픽셀 읽기 또는 시뮬레이션인지 식별하고, 메인 스레드 경합이 문제일 때만 워커를 사용하세요. 이유: 워커는 전송, 번들링 및 DOM 액세스 제약 조건을 추가합니다. 잘못된 그리기 아키텍처를 수정하지 않습니다.

• 절대 보존 모드 라이브러리 성능 규칙을 선택 사항으로 취급하지 마세요 대신: 비활성 레이어에서 수신을 비활성화하고, 비용이 많이 드는 모양을 캐시하고, 레이어 수를 최소화하고, 라이브러리 수명 주기를 통해 노드/스테이지를 파괴하세요. 이유: 라이브러리는 씬 그래프와 이벤트 메커니즘을 추가합니다. 해당 스위치를 무시하면 원시 캔버스보다 느릴 수 있습니다.