@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/fe/sources/perf/01-core-web-vitals.md

@@ -0,0 +1,58 @@
+---
+title: Core Web Vitals 2024 — 전체 개요 (LCP, INP, CLS)
+source: https://web.dev/articles/vitals
+fetched: 2026-05-18
+category: web-vitals
+---
+
+## 개요
+
+Google Web Vitals는 사용자 경험의 핵심 신호를 로딩·인터랙션·시각 안정성의 세 축으로 측정한다.
+측정 기준: **75번째 백분위수** (모바일+데스크톱 세그먼트 기준).
+
+---
+
+## 세 가지 Core Web Vitals
+
+### 1. LCP — Largest Contentful Paint (로딩)
+- **Good**: ≤ 2.5초
+- **Needs Improvement**: 2.5 ~ 4.0초
+- **Poor**: > 4.0초
+
+### 2. INP — Interaction to Next Paint (인터랙션)
+- **Good**: ≤ 200ms
+- **Needs Improvement**: 201 ~ 500ms
+- **Poor**: > 500ms
+- 2024년 3월 FID 대체로 Core Web Vital 공식 승격
+
+### 3. CLS — Cumulative Layout Shift (시각 안정성)
+- **Good**: ≤ 0.1
+- **Needs Improvement**: 0.1 ~ 0.25
+- **Poor**: > 0.25
+
+---
+
+## 측정 도구
+
+**필드(실사용자) 도구**: Chrome UX Report, PageSpeed Insights, Search Console, Chrome DevTools
+
+**랩 도구**: Lighthouse, Chrome DevTools, WebPageTest
+> Lighthouse는 INP 직접 측정 불가 → Total Blocking Time을 proxy로 사용
+
+---
+
+## JavaScript 구현
+
+```javascript
+import {onCLS, onINP, onLCP} from 'web-vitals';
+
+function sendToAnalytics(metric) {
+  const body = JSON.stringify(metric);
+  (navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
+    fetch('/analytics', {body, method: 'POST', keepalive: true});
+}
+
+onCLS(sendToAnalytics);
+onINP(sendToAnalytics);
+onLCP(sendToAnalytics);
+```

package/assets/dev-guide/fe/sources/perf/02-inp.md

@@ -0,0 +1,83 @@
+---
+title: INP (Interaction to Next Paint) — FID 대체 신 지표
+source: https://web.dev/articles/inp
+fetched: 2026-05-18
+category: web-vitals
+---
+
+## 왜 INP인가?
+
+FID(First Input Delay)는 첫 번째 입력의 지연만 측정했다. INP는 페이지 전체 생애주기에 걸친 **모든 인터랙션**을 관찰하고, 최댓값(outlier 제외)을 최종 점수로 사용한다.
+2024년 3월 Core Web Vital로 공식 승격, FID 은퇴.
+
+---
+
+## 임계값
+
+| 등급 | 값 |
+|------|-----|
+| **Good** | ≤ 200ms |
+| **Needs Improvement** | 201 ~ 500ms |
+| **Poor** | > 500ms |
+
+기준: 모바일+데스크톱 75번째 백분위수
+
+---
+
+## 측정 대상 인터랙션
+
+포함:
+- 마우스 클릭
+- 터치스크린 탭
+- 키보드 키 입력
+
+제외 (INP 미반영):
+- 스크롤
+- 호버(hover)
+- 확대/축소
+
+---
+
+## 인터랙션 구성 3단계
+
+```
+[ 입력 이벤트 ]
+    ↓
+1. Input Delay       — 이벤트 핸들러 실행 전까지의 대기 시간
+    ↓
+2. Processing Time   — 이벤트 핸들러 콜백 실행 시간
+    ↓
+3. Presentation Delay — 다음 프레임 렌더링까지의 시간
+```
+
+**총 INP = Input Delay + Processing Time + Presentation Delay**
+
+---
+
+## JavaScript 측정
+
+```javascript
+import {onINP} from 'web-vitals';
+
+onINP(console.log);
+// metric.value: 밀리초 단위 INP 점수
+// metric.attribution: 어떤 인터랙션이 원인인지 상세 정보
+```
+
+`web-vitals` 라이브러리가 백분위수 계산, BFCache 리셋, visibility-change 추적을 자동 처리한다.
+
+---
+
+## 최적화 방향
+
+1. **Input Delay 줄이기**: 긴 태스크(Long Task) 분할, `scheduler.yield()` 활용
+2. **Processing Time 줄이기**: 이벤트 핸들러 경량화, 메인 스레드 외부(Web Worker) 이동
+3. **Presentation Delay 줄이기**: DOM 크기 최소화, Layout Thrashing 방지, `requestAnimationFrame` 적절 사용
+
+---
+
+## INP가 0으로 보고되지 않는 경우
+
+- 적격 인터랙션 없음 (스크롤·호버만 발생)
+- 봇 접근 (스크립트 인터랙션 없음)
+- 페이지 진입 후 즉시 이탈

package/assets/dev-guide/fe/sources/perf/03-lcp-cls.md

@@ -0,0 +1,130 @@
+---
+title: LCP · CLS 최신 가이드라인
+source: https://web.dev/articles/lcp, https://web.dev/articles/cls
+fetched: 2026-05-18
+category: web-vitals
+---
+
+## LCP — Largest Contentful Paint
+
+### 임계값
+
+| 등급 | 값 |
+|------|-----|
+| **Good** | ≤ 2.5초 |
+| **Needs Improvement** | 2.5 ~ 4.0초 |
+| **Poor** | > 4.0초 |
+
+### 측정 대상 요소
+- `<img>` (애니메이션: 첫 프레임 기준)
+- SVG 내 `<image>`
+- `<video>` (poster 이미지 또는 첫 프레임 중 먼저 로드된 것)
+- CSS `background-image: url(...)` 배경 요소
+- 텍스트를 포함한 블록 레벨 요소
+
+제외: `opacity: 0` 요소, 뷰포트 전체를 채우는 배경 처리 요소, 낮은 엔트로피 플레이스홀더 이미지
+
+### 측정 특이사항
+사용자가 탭·스크롤·키 입력 시 측정 **중단** (이미 인터랙션한 뒤 로드되는 요소는 무관).
+
+---
+
+## LCP의 4가지 하위 구성 요소 (최적화 우선순위 순)
+
+```
+LCP = TTFB + Resource Load Delay + Resource Load Duration + Element Render Delay
+```
+
+| 구성 요소 | 목표 비중 | 설명 |
+|-----------|-----------|------|
+| TTFB | ~40% | 서버 응답 시간 |
+| Resource Load Delay | <10% | TTFB ~ LCP 리소스 로딩 시작까지 |
+| Resource Load Duration | ~40% | 실제 리소스 전송 시간 |
+| Element Render Delay | <10% | 리소스 완료 ~ 화면 렌더까지 |
+
+**핵심**: Resource Load Delay + Element Render Delay는 합쳐서 <10%가 이상적.
+어느 구간도 리소스가 로딩되지 않는 시간 = 낭비.
+
+---
+
+## LCP 최적화 기법
+
+### 1. Resource Load Delay 제거
+```html
+<!-- HTML에 직접 src/srcset 포함 (preload scanner 활성화) -->
+<img fetchpriority="high" src="/hero.webp" alt="hero">
+
+<!-- CSS/JS에서만 참조되는 경우 preload 추가 -->
+<link rel="preload" fetchpriority="high" as="image"
+  href="/hero.webp" type="image/webp">
+```
+- LCP 이미지에 `loading="lazy"` 절대 금지
+
+### 2. Element Render Delay 제거
+- Critical CSS 인라인화 또는 CSS 파일 크기 최소화
+- `<head>` 내 동기 스크립트 제거
+- 서버사이드 렌더링으로 HTML에 이미지 포함
+
+### 3. Resource Load Duration 단축
+- WebP/AVIF 포맷 사용
+- 반응형 `srcset` 적용
+- CDN/Image CDN 활용
+- 공격적 캐싱 정책
+
+### 4. TTFB 단축
+- 서버 처리 시간 최소화
+- 불필요한 리다이렉트 제거
+- CDN 엣지 캐싱
+
+---
+
+## CLS — Cumulative Layout Shift
+
+### 임계값
+
+| 등급 | 값 |
+|------|-----|
+| **Good** | ≤ 0.1 |
+| **Needs Improvement** | 0.1 ~ 0.25 |
+| **Poor** | > 0.25 |
+
+기준: 페이지 전체 생애주기 중 최대 레이아웃 이동 버스트 점수의 75번째 백분위수
+
+### 주요 원인
+- 크기 미지정 이미지/비디오
+- 폴백 폰트보다 크거나 작은 웹폰트
+- 동적으로 리사이즈되는 광고·위젯
+- 비동기 리소스 삽입
+- 기존 콘텐츠 앞에 동적 DOM 삽입
+
+### 최적화 기법
+
+```css
+/* 1. CSS transform 사용 (레이아웃 재계산 없음) */
+.moving-element {
+  transform: translate(0, 10px);  /* top/left 변경 대신 */
+  transform: scale(1.1);          /* width/height 변경 대신 */
+}
+
+/* 2. 동적 콘텐츠 공간 미리 확보 */
+.ad-slot {
+  min-height: 250px;
+}
+
+/* 3. 폰트 로딩 중 레이아웃 변화 방지 */
+@font-face {
+  font-display: optional; /* 또는 swap + size-adjust */
+}
+```
+
+```javascript
+// 사용자 인터랙션 후 이동은 CLS 제외 (hadRecentInput 확인)
+new PerformanceObserver((list) => {
+  for (const entry of list.getEntries()) {
+    if (!entry.hadRecentInput) {
+      // 이 shift만 CLS에 카운트됨
+      console.log('CLS shift:', entry.value);
+    }
+  }
+}).observe({type: 'layout-shift', buffered: true});
+```

package/assets/dev-guide/fe/sources/perf/04-speculation-rules.md

@@ -0,0 +1,148 @@
+---
+title: Speculation Rules API — 즉시 페이지 전환(Prerender/Prefetch)
+source: https://developer.chrome.com/docs/web-platform/prerender-pages
+fetched: 2026-05-18
+category: navigation
+---
+
+## 개요
+
+Chrome이 재도입한 완전한 페이지 프리렌더링 API. 구식 `<link rel="prerender">` 대체.
+사용자 탐색 전에 페이지를 비가시 백그라운드 탭으로 로드 → 활성화 시 즉시 전환.
+LCP 사실상 0, CLS 대폭 개선 효과.
+
+**브라우저 지원**: Chrome 109+, Edge 109+ | Firefox 미지원 | Safari 실험적
+
+---
+
+## 기본 문법
+
+```html
+<script type="speculationrules">
+{
+  "prerender": [{
+    "urls": ["/next-page.html", "/about.html"]
+  }]
+}
+</script>
+```
+
+---
+
+## URL 목록 vs 문서 규칙
+
+### URL 목록 (정적)
+```json
+{
+  "prerender": [{ "urls": ["/page1.html", "/page2.html"] }]
+}
+```
+
+### 문서 규칙 (동적 — CSS/URL 패턴 매칭)
+```json
+{
+  "prerender": [{
+    "where": {
+      "and": [
+        { "href_matches": "/*" },
+        { "not": { "href_matches": "/admin/*" } },
+        { "not": { "selector_matches": ".no-prerender" } }
+      ]
+    },
+    "eagerness": "moderate"
+  }]
+}
+```
+
+---
+
+## Eagerness 레벨 (Chrome 121+)
+
+| 레벨 | 데스크톱 | 모바일 |
+|------|---------|--------|
+| `immediate` | 즉시 | 즉시 |
+| `eager` | 10ms 호버 | 뷰포트 진입 50ms 후 |
+| `moderate` | 200ms 호버 또는 pointerdown | 스크롤 후 500ms |
+| `conservative` | pointer/touch down만 | pointer/touch down만 |
+
+**권장 구현** (대부분 사이트에 적합):
+```html
+<script type="speculationrules">
+{
+  "prerender": [{
+    "where": { "href_matches": "/*" },
+    "eagerness": "moderate"
+  }]
+}
+</script>
+```
+
+---
+
+## 브라우저 할당량 (리소스 낭비 방지)
+
+| Eagerness | Prefetch 한도 | Prerender 한도 |
+|-----------|--------------|----------------|
+| `immediate` | 50 | 10 |
+| `eager` / `moderate` / `conservative` | 2 (FIFO) | 2 (FIFO) |
+
+한도 초과 시 가장 오래된 speculation이 취소되고 새 것으로 교체.
+
+---
+
+## Prefetch (경량 대안)
+
+```json
+{
+  "prefetch": [{
+    "urls": ["/next.html"],
+    "eagerness": "moderate"
+  }]
+}
+```
+
+기존 `<link rel="prefetch">`와 달리, 탐색으로서의 문서를 prefetch하여 non-cacheable 콘텐츠도 처리.
+
+---
+
+## HTTP 헤더로 전달
+
+```http
+Speculation-Rules: "/speculationrules.json"
+```
+JSON 파일 MIME 타입: `application/speculationrules+json`
+
+---
+
+## 동적 삽입 (JavaScript)
+
+```javascript
+const rules = document.createElement('script');
+rules.type = 'speculationrules';
+rules.textContent = JSON.stringify({
+  prerender: [{ urls: [getNextPageUrl()] }]
+});
+document.head.appendChild(rules);
+```
+
+---
+
+## 주요 제약
+
+- 서브프레임(iframe) 내 규칙 무시
+- 활성화 전까지 알림·권한 팝업 등 "침습적" API 불가
+- 크로스 오리진 iframe은 페이지 활성화 전까지 렌더링 안 됨
+- Save-Data, 에너지 절약 모드, 사용자 "페이지 프리로드" 설정 자동 준수
+
+---
+
+## 고급 기능
+
+### Tags (Chrome 136+)
+```json
+{ "tag": "my-rules", "prerender": [{ "urls": ["/next.html"] }] }
+```
+서버사이드 필터링을 위한 레이블링.
+
+### Target Hint (Chrome 138+)
+투기 대상 컨텍스트 지정으로 정확도 향상.

package/assets/dev-guide/fe/sources/perf/05-view-transitions.md

@@ -0,0 +1,153 @@
+---
+title: View Transitions API — 페이지 전환 애니메이션 (Chrome 111+)
+source: https://developer.chrome.com/docs/web-platform/view-transitions
+fetched: 2026-05-18
+category: navigation
+---
+
+## 개요
+
+DOM 업데이트(SPA) 또는 페이지 간 이동(MPA) 시 부드러운 시각적 전환을 제공하는 API.
+브라우저가 전환 전후 스냅샷을 찍고 CSS 애니메이션으로 보간한다.
+
+---
+
+## 두 가지 구현 유형
+
+### 1. 동일 문서 전환 (Same-Document / SPA)
+**지원**: Chrome 111+, Edge 111+, Firefox 144+, Safari 18+
+
+JavaScript API로 트리거:
+```javascript
+// DOM 업데이트를 감싸기만 하면 됨
+document.startViewTransition(() => updateTheDOMSomehow());
+
+// 비동기 업데이트도 지원
+document.startViewTransition(async () => {
+  await fetchNewContent();
+  updateTheDOMSomehow();
+});
+```
+
+### 2. 크로스 문서 전환 (Cross-Document / MPA)
+**지원**: Chrome 126+, Edge 126+, Safari 18.2+ | Firefox 미지원
+
+CSS만으로 opt-in (JS 불필요):
+```css
+/* 양쪽 페이지 모두에 추가 */
+@view-transition {
+  navigation: auto;
+}
+```
+같은 오리진 페이지 간 탐색 시 자동으로 전환 효과 적용.
+
+---
+
+## 핵심 CSS: view-transition-name
+
+개별 요소를 캡처하여 독립 애니메이션 처리:
+```css
+.hero-image {
+  view-transition-name: hero;
+}
+
+.page-title {
+  view-transition-name: page-title;
+}
+```
+
+**주의**: `view-transition-name` 값은 페이지 전체에서 고유해야 함.
+
+---
+
+## 생성되는 Pseudo-Elements
+
+```
+::view-transition                          /* 루트 오버레이 */
+  └── ::view-transition-group(name)        /* 개별 요소 래퍼 */
+        ├── ::view-transition-old(name)    /* 이전 상태 스냅샷 */
+        └── ::view-transition-new(name)    /* 새 상태 스냅샷 */
+```
+
+기본 전환은 cross-fade. 커스터마이즈:
+```css
+/* 슬라이드 전환 예시 */
+::view-transition-old(root) {
+  animation: 300ms ease-out both slide-to-left;
+}
+::view-transition-new(root) {
+  animation: 300ms ease-out both slide-from-right;
+}
+
+@keyframes slide-to-left {
+  to { transform: translateX(-100%); }
+}
+@keyframes slide-from-right {
+  from { transform: translateX(100%); }
+}
+```
+
+---
+
+## View Transition Types (Chrome 125+)
+
+네비게이션 방향에 따라 다른 애니메이션:
+```javascript
+document.startViewTransition({
+  update: updateTheDOMSomehow,
+  types: ['forwards']  // 'backwards', 'reload' 등
+});
+```
+
+CSS에서 타입별 스타일:
+```css
+:active-view-transition-type(forwards) ::view-transition-old(root) {
+  animation-name: slide-to-left;
+}
+:active-view-transition-type(backwards) ::view-transition-old(root) {
+  animation-name: slide-to-right;
+}
+```
+
+---
+
+## JavaScript 애니메이션 (Web Animations API)
+
+```javascript
+const transition = document.startViewTransition(() => updateDOM());
+
+// pseudo-element가 생성된 후 JS 애니메이션 적용
+transition.ready.then(() => {
+  document.documentElement.animate(
+    { transform: ['translateY(-100%)', 'translateY(0)'] },
+    {
+      duration: 300,
+      easing: 'ease-out',
+      pseudoElement: '::view-transition-new(root)'
+    }
+  );
+});
+```
+
+---
+
+## 주요 활용 사례
+- 썸네일 → 상세 이미지 확대
+- 네비게이션 persistent 요소 (헤더, 탭바)
+- 필터링 시 그리드 재정렬
+- 페이지 간 영웅 이미지 공유 트랜지션
+
+---
+
+## 접근성 고려
+
+```css
+/* 모션 감소 선호 사용자 대응 */
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation-duration: 0.01ms !important;
+  }
+}
+```