fix(theme): 스크롤바 자리를 첫 화면부터 잡고 lab을 스크롤바와 함께 잰다

문제: 라우트 로딩 화면(280 px)은 720 px 창에 들고 홈 화면(732 px 문서)은
넘친다. 일반(overlay가 아닌) 스크롤바를 쓰는 브라우저에서 홈이 그려지는
프레임에 세로 스크롤바가 생겨 너비가 15 px 줄고 header 오른쪽(세션 영역)이
15 px 밀린다(1280x720·1366x657에서 CLS 0.0002, 리뷰 15-R2 12회). lab과 모든
게이트의 Playwright Chromium은 --hide-scrollbars로 떠서 이 shift를 못 본다.

고른 방법:
- base.css의 :root에 scrollbar-gutter: stable을 둔다. 스크롤바 자리가
  첫 프레임부터 있어 내용이 길어져도 너비가 바뀌지 않는다. overlay
  스크롤바(macOS 기본)는 어느 쪽이든 자리를 쓰지 않는다.
- lab(scripts/test-performance.ts)은 labBrowserLaunchOptions()로
  --hide-scrollbars를 빼고 띄운다. lab.json context.browser에
  scrollbars: "visible"을 남긴다. 이제 lab의 `/` CLS가 같은 회귀를 본다.
- 단위 테스트: 실행 옵션이 --hide-scrollbars를 빼는지, :root에
  scrollbar-gutter: stable이 있는지.
- 시각 골든 5장을 새 gutter에 맞춰 desktop에서 다시 찍는다
  (test:visual:update).
버린 대안: html { overflow-y: scroll } — 짧은 화면에도 빈 스크롤바를
그린다.

위험·한계: 스크롤바 폭만큼 오른쪽 여백이 짧은 화면에서도 늘 생긴다.
--hide-scrollbars로 뜬 Chromium도 gutter 자리를 잡는다. 그래서 시각 골든
5장이 모두 바뀌었다. 바뀐 것은 내용 폭 15 px다(main 1040 → 1025 px).
compact(390 px) 골든은 줄바꿈이 늘어 1297 → 1377 px로 길어졌다. 실제
휴대폰은 overlay 스크롤바라 자리를 쓰지 않으므로, compact 골든은 휴대폰
화면보다 15 px 좁게 그린다. 열린 drawer의 가림막은 gutter를 덮지 않는다
(일반 스크롤바 브라우저에서는 그 자리에 스크롤바가 그려진다). lab의 CLS 예산
0.1은 그대로라 0.0002 shift가 다시 생겨도 lab은 통과한다(값만 남는다).
Firefox·Windows 스크롤바 폭은 재지 않았다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/lab-performance.test.ts
corepack pnpm test:visual (부모 d5b6aeba에서 6건 통과, 이 변경은 옛
골든과 5건이 달라 실패, 다시 찍은 골든에서 통과)
corepack pnpm build && corepack pnpm test:performance -- --runs=5

Refs: 1105/15-05
This commit is contained in:
DongHyeonka
2026-11-06 01:23:48 +09:00
parent 46359a1c79
commit e02f252d57
10 changed files with 52 additions and 2 deletions
+5
View File
@@ -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가 포트를 계속 잡고 있었다.
+11
View File
@@ -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;
+8 -2
View File
@@ -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",
+6
View File
@@ -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 {
+22
View File
@@ -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);
});
});
Binary file not shown.

Before

Width:  |  Height:  |  Size: 67 KiB

After

Width:  |  Height:  |  Size: 68 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 90 KiB

After

Width:  |  Height:  |  Size: 90 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 189 KiB

After

Width:  |  Height:  |  Size: 190 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 183 KiB

After

Width:  |  Height:  |  Size: 190 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 119 KiB

After

Width:  |  Height:  |  Size: 119 KiB