diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index 16394c4e..f2a861a7 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -91,6 +91,11 @@ lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build lazy chunk 다운로드(200 KB/s 제한)는 들어간다. 클릭의 Event Timing entry 길이(INP의 입력값)는 `context.sampling.clickEventDurationMs`에 따로 남는다. - CPU 모델, 논리 CPU 수, 측정 전후 loadavg를 `context.runner`에 남긴다. +- Chromium은 스크롤바를 보이게 띄운다(`--hide-scrollbars` 제외, 1105/15-05). + Playwright 기본값은 스크롤바를 숨겨서, 첫 화면에 세로 스크롤바가 생기며 + header가 밀리는 shift를 lab이 보지 못했다. 화면 쪽은 `:root`의 + `scrollbar-gutter: stable`이 그 자리를 처음부터 잡는다. 다른 Playwright 게이트 + (시각 골든 포함)는 여전히 스크롤바를 숨긴다. - preview 서버는 자기 프로세스 그룹으로 띄우고 끝날 때 그룹 전체를 멈춘다. `corepack`에만 신호를 보내던 때는 vite가 포트를 계속 잡고 있었다. diff --git a/scripts/lib/lab-performance.ts b/scripts/lib/lab-performance.ts index 0c01699d..cfbd353b 100644 --- a/scripts/lib/lab-performance.ts +++ b/scripts/lib/lab-performance.ts @@ -23,6 +23,17 @@ export function previewArguments(port: number): readonly string[] { ]; } +/** + * 1105/15-05. Playwright starts Chromium with `--hide-scrollbars`, so the lab + * measured layout shift in a browser without the classic scrollbar most + * Windows and Linux desktops draw. A first render that made one appear + * moved the header 15 px and the lab reported CLS 0. The lab runs with + * scrollbars, as those users see the page. + */ +export function labBrowserLaunchOptions(): { ignoreDefaultArgs: string[] } { + return { ignoreDefaultArgs: ["--hide-scrollbars"] }; +} + export type SampleSummary = Readonly<{ median: number; min: number; diff --git a/scripts/test-performance.ts b/scripts/test-performance.ts index 4c82ebdb..5a96be2d 100644 --- a/scripts/test-performance.ts +++ b/scripts/test-performance.ts @@ -10,6 +10,7 @@ import { assertServedRelease, DEFAULT_LAB_PORT, DEFAULT_LAB_RUNS, + labBrowserLaunchOptions, previewArguments, summarizeSamples, } from "./lib/lab-performance.ts"; @@ -183,7 +184,7 @@ try { const thresholds = JSON.parse( await readFile("config/performance/budgets.json", "utf8"), ).lab; - const browser = await chromium.launch(); + const browser = await chromium.launch(labBrowserLaunchOptions()); try { const loadBefore = load(); const samples: RunMetrics[] = []; @@ -208,7 +209,12 @@ try { logicalCpus: cpus().length, loadAverage: { before: loadBefore, after: loadAfter }, }, - browser: { name: "chromium", version: await browser.version() }, + // 1105/15-05. Classic scrollbars, not Playwright's hidden ones. + browser: { + name: "chromium", + version: await browser.version(), + scrollbars: "visible", + }, viewport: { width: 1280, height: 720 }, network: { profile: "contract-fast-4g", diff --git a/src/presentation/styles/theme/base.css b/src/presentation/styles/theme/base.css index b0ecc0e6..71ccec31 100644 --- a/src/presentation/styles/theme/base.css +++ b/src/presentation/styles/theme/base.css @@ -3,6 +3,12 @@ color: var(--color-content); background: var(--color-surface); font-family: var(--font-sans); + /* 1105/15-05. The route loading surface fits a 720 px window and the + home page does not, so the first render added a classic (non-overlay) + scrollbar and pushed the header's right side 15 px left (CLS 0.0002 at + 1280x720 and 1366x657). The gutter is reserved from the first frame; + overlay scrollbars take no space either way. */ + scrollbar-gutter: stable; } body { diff --git a/tests/unit/lab-performance.test.ts b/tests/unit/lab-performance.test.ts index c3ea9d82..ea291ff8 100644 --- a/tests/unit/lab-performance.test.ts +++ b/tests/unit/lab-performance.test.ts @@ -1,4 +1,5 @@ import { spawn } from "node:child_process"; +import { readFile } from "node:fs/promises"; import { createServer, type Server } from "node:http"; import type { AddressInfo } from "node:net"; import path from "node:path"; @@ -8,6 +9,7 @@ import { afterEach, describe, expect, it } from "vitest"; import { assertPortUnused, assertServedRelease, + labBrowserLaunchOptions, previewArguments, summarizeSamples, } from "../../scripts/lib/lab-performance.ts"; @@ -104,3 +106,23 @@ describe("lab performance gate (11-07)", () => { expect(stderr).toMatch(/another server holds the port/u); }, 30_000); }); + +/** + * 1105/15-05. The home page's first render added a vertical scrollbar and + * pushed the header's right side 15 px (CLS 0.0002 at 1280x720 and + * 1366x657). Every gate's Chromium hid scrollbars, the lab included, so no + * gate could see it. The page reserves the gutter, and the lab measures with + * the scrollbar a Windows or Linux desktop draws. + */ +describe("lab performance with real scrollbars (1105/15-05)", () => { + it("starts Chromium without Playwright's --hide-scrollbars", () => { + expect(labBrowserLaunchOptions().ignoreDefaultArgs).toContain("--hide-scrollbars"); + }); + + it("reserves the root scrollbar gutter before the first route renders", async () => { + const base = await readFile("src/presentation/styles/theme/base.css", "utf8"); + const root = base.match(/:root\s*\{([^}]*)\}/u)?.[1] ?? ""; + + expect(root).toMatch(/scrollbar-gutter:\s*stable\s*;/u); + }); +}); diff --git a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png index 03f375b5..5fc74252 100644 Binary files a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png and b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png differ diff --git a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-wide-light-chromium-visual-linux.png b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-wide-light-chromium-visual-linux.png index 866717e6..eef93379 100644 Binary files a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-wide-light-chromium-visual-linux.png and b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-wide-light-chromium-visual-linux.png differ diff --git a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/design-system-gallery-dark-chromium-visual-linux.png b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/design-system-gallery-dark-chromium-visual-linux.png index ba71b3c7..b5f4a480 100644 Binary files a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/design-system-gallery-dark-chromium-visual-linux.png and b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/design-system-gallery-dark-chromium-visual-linux.png differ diff --git a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/platform-overview-light-chromium-visual-linux.png b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/platform-overview-light-chromium-visual-linux.png index ff0a7948..8487c073 100644 Binary files a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/platform-overview-light-chromium-visual-linux.png and b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/platform-overview-light-chromium-visual-linux.png differ diff --git a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/state-surfaces-light-chromium-visual-linux.png b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/state-surfaces-light-chromium-visual-linux.png index 41181671..fae126f6 100644 Binary files a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/state-surfaces-light-chromium-visual-linux.png and b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/state-surfaces-light-chromium-visual-linux.png differ