# Performance evidence contract Performance evidence is deliberately split by measurement context: - `bundle.json` records production build output and enforces initial JavaScript at 200 KiB gzip and every lazy chunk at 120 KiB gzip. - `lab.json` records Chromium/runner/viewport/network/CPU/cache/build context and enforces LCP 2.5 s, CLS 0.10, and the named route interaction at 200 ms. - `field-web-vitals.json` records consent-filtered, route-ID aggregated, release-specific production samples over 28 days and evaluates p75 LCP, CLS, and INP against 2.5 s, 0.10, and 200 ms. ## 번들 예산의 기준선과 여유 리뷰 0925/13-14, 1101/15-02. 예산은 `config/performance/budgets.json`에 있고 `scripts/check-bundle.ts`(FE-GATE-012, merge 단계)가 강제한다. 템플릿 기본 화면만으로 초기 JS 예산의 98.9%를 쓴다. 첫 기능을 추가하기 전에 아래 숫자를 보고 예산을 정한다. | 항목 | 값 | |---|---| | 초기 JS 예산 | 204,800 gzip bytes(200 KiB) | | 템플릿 기준선(2026-11-01, 커밋 `298201f`) | 202,509~202,522 gzip bytes, 16개 파일. local 프로필, `VITE_BUILD_ID`가 `local-build`일 때와 CI 모양(`gitea--`)일 때다. 빌드 ID가 번들에 들어가므로 빌드마다 수십~수백 바이트 다르다 | | 여유 | 약 2,280 bytes(1.1%) | | 기능 하나를 더할 때 | 참조 기능 모양 복사본 하나에 약 +650~750 bytes(`298201f` 측정, 상한은 `tests/unit/feature-shape-growth.test.ts`의 1 KiB). 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다 | | lazy chunk 예산 | 파일마다 122,880 gzip bytes(120 KiB). 기준선의 lazy JS는 17개, 합계 28,204 bytes이고 가장 큰 것은 `use-reference-feature` 8,386 bytes다 | 청크 이름으로 크기를 판단하지 않는다. rolldown은 공용 청크에 안에 든 모듈 하나의 이름을 붙인다. 예를 들어 `render-boot-failure` 청크(58.6 KB)의 대부분은 react-dom이고, `design-system` 청크(48.2 KB)에는 react-router가 들어 있다. 아래는 출처별 크기다. sourcemap 빌드에서 minify된 바이트를 원래 모듈에 나눠 붙이고 묶음마다 따로 gzip했다. 따로 압축하므로 합은 실제 합계와 조금 다르다. | 출처 | minify bytes | 단독 gzip bytes | |---|---:|---:| | react-dom + scheduler | 181,673 | 56,545 | | react-router | 94,271 | 30,697 | | zod | 70,512 | 18,607 | | @tanstack/* | 24,751 | 7,286 | | react | 7,869 | 2,961 | | 그 밖의 npm(lucide-react) | 2,329 | 1,142 | | 템플릿 `src` | 265,529 | 78,883 | 템플릿 `src` 중 큰 것은 `src/contracts` 17.8 KB, `src/adapters/http` 8.0 KB, `src/presentation/i18n`(문구 카탈로그) 7.6 KB, `src/bootstrap` 7.4 KB, `src/presentation/design-system` 5.1 KB다. 측정 조건: - 초기 파일은 Vite manifest의 entry, 그 static import, entry가 직접 dynamic import하는 chunk(`boot`, `render-boot-failure`)와 그 static import다 (`scripts/lib/classify-vite-bundle.ts`). entry는 앱 그래프의 평가 실패를 보고하려고 그 둘을 dynamic import로 읽을 뿐이고, 첫 화면에 항상 필요하다 (0925/09-03). 그 밖의 dynamic import chunk는 lazy다. - 합계는 JavaScript만 센다. CSS(`index-*.css`, 8.6 KB gzip)는 예산에 들어가지 않는다. - gzip은 Node `zlib.gzipSync` 기본 수준(6)으로 잰다 (`scripts/lib/release-candidate.ts`). 호스팅이 brotli로 보내면 전송 크기는 더 작다. 예산은 gzip 기준 그대로 둔다. - Node·pnpm·runner 이미지는 `artifacts/performance/bundle.json`의 `context`에 기록된다. 예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다. lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build를 `vite preview --strictPort`로 띄워 잰다(리뷰 11-07). - 포트는 `LAB_PERFORMANCE_PORT`(기본 4173)다. 서버를 띄우기 전에 그 포트가 이미 응답하면 실패하고, 응답하는 `/release-manifest.json`의 build·release가 로컬 `dist/release-manifest.json`과 다르면 실패한다 (`scripts/lib/lab-performance.ts`, `tests/unit/lab-performance.test.ts`). - 새 브라우저 context에서 `--runs=N`(기본 5)번 재고, 예산은 중앙값으로 판정한다. 모든 측정값과 최소·최대는 `lab.json`의 `context.sampling`에 남는다. - named interaction은 페이지 안의 시계로 잰다. 클릭 이벤트의 `timeStamp`부터 대상 heading이 DOM에 들어온 시각까지다. Playwright 왕복 시간은 들어가지 않고, lazy chunk 다운로드(200 KB/s 제한)는 들어간다. 클릭의 Event Timing entry 길이(INP의 입력값)는 `context.sampling.clickEventDurationMs`에 따로 남는다. - CPU 모델, 논리 CPU 수, 측정 전후 loadavg를 `context.runner`에 남긴다. - preview 서버는 자기 프로세스 그룹으로 띄우고 끝날 때 그룹 전체를 멈춘다. `corepack`에만 신호를 보내던 때는 vite가 포트를 계속 잡고 있었다. 2026-09-27 한 빌드를 10회 잰 결과(i5-10400F 12 CPU, loadavg 11~17): 중앙값 LCP 2,386ms, interaction 184.5ms로 통과했다. 한 번씩 판정했다면 interaction 10회 중 4회(최대 274ms), LCP 10회 중 2회(최대 2,644ms)가 실패였다. 같은 빌드를 loadavg 7~9에서 다시 10회 재면 interaction 120~148ms, LCP 1,968~2,072ms로 모두 통과했다. 한 번 측정한 판정은 호스트 부하에 따라 뒤집히고, 중앙값 판정은 두 번 모두 통과였다. The field minimum eligible-sample threshold is intentionally unresolved until a privacy-approved telemetry baseline exists. Therefore the field command fails closed with `FAIL_UNVERIFIED` when run against the example input. Provide `FIELD_WEB_VITALS_INPUT` and `MIN_ELIGIBLE_SAMPLES` only after that decision is recorded. The external input must identify a production release and an exact 28-day export window, name the source/export, carry privacy-approval and threshold-decision references, and contain only non-negative route-ID samples. The environment threshold must be a positive integer equal to the approved decision embedded in the input. Invalid metadata fails as `FAIL_UNVERIFIED`; the example can never serve as production evidence. ## 초기 청크 수와 HTTP/1.1 리뷰 1101/14.4. 08-08은 초기 JS 바이트를 줄이는 대신 초기 파일 수를 늘렸다 (`vite.config.ts`의 `moduleSideEffects` 주석). HTTP/1.1에서 브라우저는 한 호스트에 연결을 6개까지만 연다. 파일이 많으면 요청이 줄을 서서 왕복이 는다. 그래서 지금 빌드와 작은 초기 청크를 하나로 묶은 빌드를 쟀다(2026-11-03, 커밋 `ec7435c`). | 빌드 | 초기 JS 파일(entry 포함) | 초기 JS gzip(B) | 첫 화면까지 JS 요청 | Fast 3G 첫 화면 | Fast 4G 첫 화면 | |---|---:|---:|---:|---:|---:| | 지금 | 26 | 202,782 | 27 | 5,887 ms | 1,874 ms | | (가) 08-08이 나눈 초기 primitive 청크 4개(`field`·`button`·`select`·`page-templates`)를 하나로 | 23 | 201,818 | 24 | 5,426 ms | 1,764 ms | | (나) 묶을 수 있는 초기 청크 14개를 하나로 | 13 | 198,673 | 14 | 4,930 ms | 1,535 ms | 같은 빌드를 HTTP/2로 서빙하면(`node:http2`, 자체 서명 인증서, gzip) 차이가 거의 없다. | 빌드 | Fast 3G 첫 화면 | Fast 4G 첫 화면 | |---|---:|---:| | 지금 | 4,793 ms | 1,444 ms | | (가) | 4,769 ms | 1,440 ms | | (나) | 4,708 ms | 1,422 ms | 측정 조건: - `vite preview`(HTTP/1.1, gzip 응답)로 띄우고 Chromium으로 잰다. 네트워크는 CDP `Network.emulateNetworkConditions`에 DevTools 프리셋 값을 넣었다. Fast 3G는 지연 562.5 ms·내려받기 180,000 B/s, Fast 4G는 165 ms·1,012,500 B/s다. - 매번 새 browser context에서 캐시 없이 `/`를 연다. 첫 화면은 boot 셸이 사라지고 `#main-content h1[data-route-heading]`가 DOM에 들어온 시각이다 (`performance.now()`). - 세 빌드를 번갈아 7번씩 재고 중앙값을 적었다. 7번의 범위는 지금 5,866~6,077 ms, (가) 5,384~5,652 ms, (나) 4,891~5,032 ms다(Fast 3G). loadavg는 HTTP/1.1 측정 때 6~20, HTTP/2 측정 때 3~6이었다. 그래서 두 표끼리는 비교하지 않는다. - CDP 지연은 요청마다 붙는다. 연결 수립(TCP·TLS) 비용은 따로 재지 않았다. - (나)에서 묶지 않은 것: entry·`preload-helper`·`boot`, 부트 실패 화면이 쓰는 모듈(`render-boot-failure`·react·react-dom·`jsx-runtime`·`operation-id`· `diagnostics`·`boot-messages`, 09-03), 15-01의 `feature-declarations`· `feature-platform`. 판단: 지금은 묶지 않는다. - HTTP/1.1에서는 묶는 편이 빠르다. Fast 3G에서 (가) 0.46초, (나) 0.96초 빨라지고 초기 JS도 조금 준다. - 그러나 (가)·(나)는 이 빌드의 청크 안 모듈 목록을 그대로 적어 만들었다. 규칙으로 고르는 방법은 찾지 못했다. - 모듈 그래프로 boot의 정적 closure를 따라가면 design-system 배럴을 지나 갤러리 전용 primitive까지 잡힌다. 그 primitive가 다시 초기 청크로 간다. - rolldown의 `$initial` 태그는 entry가 앱을 dynamic import로 읽어서(09-03) 아무것도 잡지 않는다. - `boot.tsx`를 entry로 더하면 manifest 분류가 lazy 화면까지 초기로 센다 (28개, 216,820 B로 예산 초과). - 고정 목록은 셸이 쓰는 primitive가 바뀔 때마다 다시 맞춰야 한다. 목록이 낡아도 실패하는 검사가 없다. 08-08이 같은 이유로 `manualChunks` 이름 고정을 버렸다. - HTTP/2에서는 (나)도 Fast 3G 85 ms, Fast 4G 22 ms 차이다(위 둘째 표). 그래서 템플릿은 HTTP/2 이상으로 서빙한다고 본다. HTTP/1.1로만 서빙해야 하는 제품은 (나)처럼 초기 청크를 묶는 그룹을 `vite.config.ts`에 넣는다. 그 목록은 셸을 바꿀 때마다 위 방법으로 다시 잰다.