fix: 브라우저 게이트를 초록으로(Studio mock·화면 도착 처리·부팅 실패 청크·visual 기준·WebKit 경합) #8

Merged
donghyeon.kang merged 16 commits from fix/browser-gates-green-v2 into main 2026-11-12 11:28:36 +00:00
Owner

제목: fix: 브라우저 게이트를 막던 제품 결함과 시험 경합을 고치고 visual 기준을 다시 만든다
브랜치: tech-log-frontend fix/browser-gates-green-v2, head bf03c28(main 032ba319 위, 커밋 16개)
(먼저 push한 fix/browser-gates-green은 쓰지 않는다. 홈 포커스 수정을 관리 mock 앞에 두려고 다시 쌓았고, force push를 피하려고 이름을 바꿨다.)

무엇을, 왜

PR #7 뒤에도 main의 브라우저 게이트(FE-GATE-008/009)는 빨갰다. 남은 원인 A~E를 고친다(총괄 결정, 2026-11-12). 고치는 동안 같은 경로에서 결함 둘과 시험 경합 몇 개가 더 나왔다. 모두 원인마다 커밋 하나로 나눴다.

원인 커밋 무엇을
A를 막던 결함: 홈 포커스 편집기 무한 초기화 fcc35c7 fix(studio) 「지금 집중하는 것」이 defaultValues를 렌더마다 새로 만들어, 포커스를 읽으면 reset→렌더→reset이 끝없이 돌았다. 관리 mock을 넣자 Studio smoke 시험이 멈춰서 드러났다. 브라우저에서 대시보드를 3초 가만히 두면 수정 전 main thread 2.97초 사용, 수정 후 0초(chromium, CDP TaskDuration). 운영(HTTP)도 포커스가 있으면 같은 코드 경로다. 모듈 상수로 둔다
A. MOCK Studio의 관리 기능이 실제 HTTP로 나감 03ac641 fix(studio) mock 관리 gateway를 둔다. 주제·프로젝트·릴리즈·홈 포커스·작업본 삭제를 메모리에서 처리하고, 실패는 백엔드와 같은 코드를 쓴다. 문서 gateway와 Studio state 하나를 나눠 쓴다
A가 드러낸 시험 어긋남 baece79 test(e2e) 이탈 확인 시험이 지금 Studio 탐색의 「게시」를 누른다(「게시 기록」 링크는 없어졌다)
C. 부팅 실패 화면이 앱 그래프 청크에 묶임 9e20d47 fix(build) manualChunks를 템플릿과 같은 codeSplitting.groups(includeDependenciesRecursively: false)로 바꾼다. route-not-found가 React·i18n·메시지 카탈로그를 끌고 가던 것을 없앤다
B. 공개 화면 도착 처리 없음 8ca90db test(e2e), f78ce58 fix(public) Public shell의 useRouteArrival: 새 경로에서 h1(또는 해시 대상)에 초점을 주고 해시 대상으로 스크롤한다. 뒤로 가기는 저장한 위치로 돌린다. 시험은 sticky가 아닌 머리말 때문에 0에서 떠나던 것을 고쳤다
E. WebKit capability 흔들림 84afff4, c524a21 test(browser) (1) 500 ms짜리 BLOCKED 상태를 폴링으로 놓치던 것은 상태 이력으로 본다. (2) 다운로드 직후 dispose가 blob URL을 해제해 WebKit 다운로드가 시작되지 않던 것은 파일을 받은 뒤 dispose한다
새로 드러남: 편집기 가로 넘침 abe4ec9 fix(studio) 블록 편집기의 손잡이 여백(-38px)이 935px 이하에서 화면 밖으로 나가 페이지가 가로로 스크롤됐다(761~935px 14px, 760px 이하 4px). 여백을 그 폭의 옆 여백에 맞춘다
새로 드러남: 시험 경합 0dc1179, 9095c63, 40075c9, 4a39300 오래된 탭 시험이 홈의 h2 「프로젝트」에 걸리던 것, WebKit에서 첫 화면이 5초를 넘기던 것, WebKit의 preload 추측 경고, Studio 데이터 로딩 전에 찍던 것
D. visual 기준 f3a4e83, 75eea39, bf03c28 test(visual) 모르는 slug는 SPA 안의 not-found를 찍는다. 편집기에서 빠진 즉시 미리보기 visual은 지운다. 기준 129장을 다시 만든다(아래 표)

고른 방법과 버린 대안

  • A: e2e에서 /api/v1/studio/**를 가로채는 안을 버렸다. 로컬 개발 빌드가 깨진 채 남는다. 프로젝트와 릴리즈는 공개 화면의 정적 콘텐츠에서 시작해서, 공개 화면과 이름·slug가 같다.
  • B: 라우터(템플릿 소유 app-router.tsx)에 넣는 안을 버렸다. Studio 화면은 자기 초점 처리를 따로 갖고 있다. 화면마다 PageHeader를 씌우는 안도 버렸다(14곳). 위치 저장은 sessionStorage 대신 메모리 Map이다. 저장소 API는 adapter 소유라 lint가 막는다. 새로고침은 브라우저 복원을 그대로 쓴다.
  • B의 초점 테두리: 초점을 받는 h1에 data-route-heading을 단다. 3374f28의 규칙대로 초점은 주되 테두리는 그리지 않는다. 처음에는 이것을 빠뜨렸고, visual 검토에서 h1마다 파란 테두리가 찍힌 것을 보고 고쳤다.
  • C: overflow나 별도 entry로 실패 화면을 떼는 안을 버렸다. 원인이 manualChunks의 재귀 의존 포함이라 템플릿과 같은 groups 형식이 맞다.
  • E: 재시도나 timeout 증가로 덮지 않았다. 두 경합 모두 원인을 고쳤고, WebKit 20회 반복으로 확인했다.
  • 편집기 여백: overflow-x: clip 안을 버렸다. 스크롤은 없어지지만 손잡이가 잘린 채 남는다.
  • WebKit preload 경고: 템플릿(1103/11-09)과 같이 이 추측 경고만 받아들인다. 템플릿이 대신 두는 직접 검사(preload-use.ts)는 CSP·SW 시험의 응답 가로채기까지 고쳐야 해서 이번에 옮기지 않았다(남은 일).
  • quarantine은 쓰지 않았다.

visual 기준 129장 (옛 기준 2026-08-18 cf45bcc)

화면 장수 무엇이 바뀌었나 원인
공개 화면(case, explore, explore-kind, home, profile, project·records·decisions·activity, projects, reference, release, releases, search, topic) × 360·1440 30 9월 공개 화면 개편: 홈의 소개 문구와 NOW·프로젝트 구역, 기록 머리의 조사 위치, 읽기 폭과 제목 크기, 조사 상태 표시, 주제 목록 b9d0585, 0b0c5cb, fe1f235, d3bf392, e88ed5e, 5399e19, aca4f18, de4cb8b, eedc90b 외
question × 360·1440 2 위 개편, 「다음 검증」 라벨 대비 4.46→5.85:1 위, cd4fa8c(PR #7)
홈 breakpoint 12폭 12 홈 개편 위
알려진 공개 fixture 18곳 18 위 개편(질문 2곳은 대비 포함) 위
Studio 화면과 상태 45장 45 로그인한 Studio를 찍는다(8월 기준 뒤 로그인 관문이 생겼다). Studio 재설계(머리말 탐색 묶음, 다음 한 걸음), v4 블록 편집기, Public Preview 상태 패널 스타일, 대시보드의 「지금 집중하는 것」(관리 mock 데이터), 편집기 360px 손잡이 여백 5e2b1a5, 500dbc6(PR #7), 9545860, d72eae2, 805d400, 03ac641, abe4ec9 외
모르는 slug 10경로 × 360·1440 20 평문 「Not Found」 → SPA 안의 「페이지를 찾을 수 없습니다.」 6784eb1, f3a4e83
검색 대화상자 390, Studio 모바일 메뉴 390 2 위 개편 위

검토한 방법:

  • visual이 찍는 56개 화면을 같은 조건(고정 시계, Studio 로그인)으로 열어, 오류 화면·aria-busy·로그인 관문·콘솔 오류를 셌다. 의도한 not-found 말고는 없었다.
  • 옛 기준과 새 기준을 범주마다 나란히 봤다. 의도와 다른 차이는 h1 초점 테두리 하나였고, 코드에서 고쳤다.
  • 관찰(이번에 바꾸지 않음): 편집기의 제목 입력칸이 긴 제목을 한 줄로 두어, 1440·360에서 제목 끝이 칸 안에서 잘려 보인다. 9월 v4 편집기부터의 동작이다.

위험과 영향

  • 운영 동작이 바뀌는 것:
    • 공개 화면 이동 뒤 초점과 스크롤.
    • 청크 구성. Case 화면이 받는 JS 파일이 14개에서 36개로 늘었다. 화면이 뜨는 시간은 같다(chromium 0.920.96초, webkit 3.84.1초). 초기 JS gzip은 336,296B에서 300,178B로 줄었다. 예산(204,800B)은 main부터 넘는다(아래 표).
    • Studio 편집기 935px 이하 손잡이 여백.
  • MOCK 관리 mock은 로컬·시험 빌드에서만 쓰인다(운영은 HTTP).
  • visual 기준은 desktop 호스트에서 만들었다. 8월 기준도 같은 곳에서 만들었고, 바뀌지 않은 평문 NOT_FOUND 2장이 바이트까지 같다. CI 컨테이너에서 픽셀까지 같은지는 확인하지 못했다.

검증

desktop 호스트, node 24.14.0, CI env(CI=true, VITE_BUILD_ID, RELEASE_ID, VITE_COMMIT_SHA, CI_RUNNER_IMAGE), heavy lock 아래에서 돌렸다. push한 head의 새 clone이다.

게이트·명령 rc 내용
FE-GATE-001 lockfile 0
FE-GATE-002 lint 0
FE-GATE-003 typecheck 0
FE-GATE-004 runtime schema 0
FE-GATE-005 unit·coverage 0 176파일 2,388건, coverage 348파일 3,615건
FE-GATE-011 build·storybook build 0
FE-GATE-009 a11y 0 90건 통과, a11y manual format 통과
FE-GATE-008 (1회차) 1 firefox 3건이 30초 시간 초과(홈 networkidle 2, SW 이벤트 1). 같은 시각 Gitea runner의 Gradle job으로 load average 22(12코어)
FE-GATE-008 (2회차) 0 test:e2e 592 통과·3 skip, capability 63, storybook 1, visual 132, 증거 검사 둘
test:visual 단독 0, 0 기준 갱신 뒤 두 번 연속 132건
FE-GATE-012 번들 예산(머지 게이트 아님) 1 초기 JS gzip 300,866B > 예산 204,800B. main부터 초과: main 334,022B, 청크 수정 전 336,296B → 수정 뒤 300,178B(36KB 줄었다). 이 PR로 생긴 실패가 아니고, 예산까지는 남은 일

흔들렸던 것의 연속 실행:

대상 결과
e2e: scroll-restoration, old-tab, app-shell, production-csp, boot-module-failure, tech-log-responsive (chromium·firefox·webkit·compact) 3회 연속 115건 통과, 이어서 FE-GATE-008 2회차 통과
capability webkit 전체 1회차 1건 실패(BroadcastChannel, load 22 중), 2·3회차와 FE-GATE-008 2회차 통과(3회 연속)
capability webkit BroadcastChannel 시험 20회 반복 두 번 40건 통과(load 35~41 포함). 재현되지 않았다
capability webkit IndexedDB blocked·다운로드 시험 고친 뒤 20회 반복 40건 통과
firefox responsive·SW 갱신(1회차 시간 초과 셋) load 3.5~3.7에서 3회 연속 60건 통과, FE-GATE-008 2회차도 통과

남은 일

  • FE-GATE-012 번들 예산: 초기 JS가 main부터 예산을 넘는다(이 PR 뒤 300,866B / 204,800B).
  • 템플릿의 preload 사용 직접 검사(preload-use.ts) 옮기기. 지금은 쓰이지 않는 preload를 어느 엔진에서도 잡지 않는다.
  • desktop 호스트의 WebKit은 화면 하나에 약 4초가 걸린다(Chromium 0.9초). 청크 수와는 상관없다. playwright install-deps가 설치하는 시스템 패키지 64개가 없지만, 그것이 원인인지는 확인하지 못했다(sudo 필요).

관련

제목: fix: 브라우저 게이트를 막던 제품 결함과 시험 경합을 고치고 visual 기준을 다시 만든다 브랜치: tech-log-frontend `fix/browser-gates-green-v2`, head `bf03c28`(main `032ba319` 위, 커밋 16개) (먼저 push한 `fix/browser-gates-green`은 쓰지 않는다. 홈 포커스 수정을 관리 mock 앞에 두려고 다시 쌓았고, force push를 피하려고 이름을 바꿨다.) ## 무엇을, 왜 PR #7 뒤에도 main의 브라우저 게이트(FE-GATE-008/009)는 빨갰다. 남은 원인 A~E를 고친다(총괄 결정, 2026-11-12). 고치는 동안 같은 경로에서 결함 둘과 시험 경합 몇 개가 더 나왔다. 모두 원인마다 커밋 하나로 나눴다. | 원인 | 커밋 | 무엇을 | | --- | --- | --- | | A를 막던 결함: 홈 포커스 편집기 무한 초기화 | `fcc35c7` fix(studio) | 「지금 집중하는 것」이 defaultValues를 렌더마다 새로 만들어, 포커스를 읽으면 reset→렌더→reset이 끝없이 돌았다. 관리 mock을 넣자 Studio smoke 시험이 멈춰서 드러났다. 브라우저에서 대시보드를 3초 가만히 두면 수정 전 main thread 2.97초 사용, 수정 후 0초(chromium, CDP TaskDuration). 운영(HTTP)도 포커스가 있으면 같은 코드 경로다. 모듈 상수로 둔다 | | A. MOCK Studio의 관리 기능이 실제 HTTP로 나감 | `03ac641` fix(studio) | mock 관리 gateway를 둔다. 주제·프로젝트·릴리즈·홈 포커스·작업본 삭제를 메모리에서 처리하고, 실패는 백엔드와 같은 코드를 쓴다. 문서 gateway와 Studio state 하나를 나눠 쓴다 | | A가 드러낸 시험 어긋남 | `baece79` test(e2e) | 이탈 확인 시험이 지금 Studio 탐색의 「게시」를 누른다(「게시 기록」 링크는 없어졌다) | | C. 부팅 실패 화면이 앱 그래프 청크에 묶임 | `9e20d47` fix(build) | `manualChunks`를 템플릿과 같은 `codeSplitting.groups`(`includeDependenciesRecursively: false`)로 바꾼다. route-not-found가 React·i18n·메시지 카탈로그를 끌고 가던 것을 없앤다 | | B. 공개 화면 도착 처리 없음 | `8ca90db` test(e2e), `f78ce58` fix(public) | Public shell의 `useRouteArrival`: 새 경로에서 h1(또는 해시 대상)에 초점을 주고 해시 대상으로 스크롤한다. 뒤로 가기는 저장한 위치로 돌린다. 시험은 sticky가 아닌 머리말 때문에 0에서 떠나던 것을 고쳤다 | | E. WebKit capability 흔들림 | `84afff4`, `c524a21` test(browser) | (1) 500 ms짜리 BLOCKED 상태를 폴링으로 놓치던 것은 상태 이력으로 본다. (2) 다운로드 직후 dispose가 blob URL을 해제해 WebKit 다운로드가 시작되지 않던 것은 파일을 받은 뒤 dispose한다 | | 새로 드러남: 편집기 가로 넘침 | `abe4ec9` fix(studio) | 블록 편집기의 손잡이 여백(-38px)이 935px 이하에서 화면 밖으로 나가 페이지가 가로로 스크롤됐다(761~935px 14px, 760px 이하 4px). 여백을 그 폭의 옆 여백에 맞춘다 | | 새로 드러남: 시험 경합 | `0dc1179`, `9095c63`, `40075c9`, `4a39300` | 오래된 탭 시험이 홈의 h2 「프로젝트」에 걸리던 것, WebKit에서 첫 화면이 5초를 넘기던 것, WebKit의 preload 추측 경고, Studio 데이터 로딩 전에 찍던 것 | | D. visual 기준 | `f3a4e83`, `75eea39`, `bf03c28` test(visual) | 모르는 slug는 SPA 안의 not-found를 찍는다. 편집기에서 빠진 즉시 미리보기 visual은 지운다. 기준 129장을 다시 만든다(아래 표) | ## 고른 방법과 버린 대안 - **A: e2e에서 `/api/v1/studio/**`를 가로채는 안을 버렸다.** 로컬 개발 빌드가 깨진 채 남는다. 프로젝트와 릴리즈는 공개 화면의 정적 콘텐츠에서 시작해서, 공개 화면과 이름·slug가 같다. - **B: 라우터(템플릿 소유 `app-router.tsx`)에 넣는 안을 버렸다.** Studio 화면은 자기 초점 처리를 따로 갖고 있다. 화면마다 PageHeader를 씌우는 안도 버렸다(14곳). 위치 저장은 sessionStorage 대신 메모리 Map이다. 저장소 API는 adapter 소유라 lint가 막는다. 새로고침은 브라우저 복원을 그대로 쓴다. - **B의 초점 테두리:** 초점을 받는 h1에 `data-route-heading`을 단다. 3374f28의 규칙대로 초점은 주되 테두리는 그리지 않는다. 처음에는 이것을 빠뜨렸고, visual 검토에서 h1마다 파란 테두리가 찍힌 것을 보고 고쳤다. - **C: `overflow`나 별도 entry로 실패 화면을 떼는 안을 버렸다.** 원인이 manualChunks의 재귀 의존 포함이라 템플릿과 같은 groups 형식이 맞다. - **E: 재시도나 timeout 증가로 덮지 않았다.** 두 경합 모두 원인을 고쳤고, WebKit 20회 반복으로 확인했다. - **편집기 여백: `overflow-x: clip` 안을 버렸다.** 스크롤은 없어지지만 손잡이가 잘린 채 남는다. - **WebKit preload 경고:** 템플릿(1103/11-09)과 같이 이 추측 경고만 받아들인다. 템플릿이 대신 두는 직접 검사(`preload-use.ts`)는 CSP·SW 시험의 응답 가로채기까지 고쳐야 해서 이번에 옮기지 않았다(남은 일). - quarantine은 쓰지 않았다. ## visual 기준 129장 (옛 기준 2026-08-18 `cf45bcc`) | 화면 | 장수 | 무엇이 바뀌었나 | 원인 | | --- | --- | --- | --- | | 공개 화면(case, explore, explore-kind, home, profile, project·records·decisions·activity, projects, reference, release, releases, search, topic) × 360·1440 | 30 | 9월 공개 화면 개편: 홈의 소개 문구와 NOW·프로젝트 구역, 기록 머리의 조사 위치, 읽기 폭과 제목 크기, 조사 상태 표시, 주제 목록 | `b9d0585`, `0b0c5cb`, `fe1f235`, `d3bf392`, `e88ed5e`, `5399e19`, `aca4f18`, `de4cb8b`, `eedc90b` 외 | | question × 360·1440 | 2 | 위 개편, 「다음 검증」 라벨 대비 4.46→5.85:1 | 위, `cd4fa8c`(PR #7) | | 홈 breakpoint 12폭 | 12 | 홈 개편 | 위 | | 알려진 공개 fixture 18곳 | 18 | 위 개편(질문 2곳은 대비 포함) | 위 | | Studio 화면과 상태 45장 | 45 | 로그인한 Studio를 찍는다(8월 기준 뒤 로그인 관문이 생겼다). Studio 재설계(머리말 탐색 묶음, 다음 한 걸음), v4 블록 편집기, Public Preview 상태 패널 스타일, 대시보드의 「지금 집중하는 것」(관리 mock 데이터), 편집기 360px 손잡이 여백 | `5e2b1a5`, `500dbc6`(PR #7), `9545860`, `d72eae2`, `805d400`, `03ac641`, `abe4ec9` 외 | | 모르는 slug 10경로 × 360·1440 | 20 | 평문 「Not Found」 → SPA 안의 「페이지를 찾을 수 없습니다.」 | `6784eb1`, `f3a4e83` | | 검색 대화상자 390, Studio 모바일 메뉴 390 | 2 | 위 개편 | 위 | 검토한 방법: - visual이 찍는 56개 화면을 같은 조건(고정 시계, Studio 로그인)으로 열어, 오류 화면·aria-busy·로그인 관문·콘솔 오류를 셌다. 의도한 not-found 말고는 없었다. - 옛 기준과 새 기준을 범주마다 나란히 봤다. 의도와 다른 차이는 h1 초점 테두리 하나였고, 코드에서 고쳤다. - 관찰(이번에 바꾸지 않음): 편집기의 제목 입력칸이 긴 제목을 한 줄로 두어, 1440·360에서 제목 끝이 칸 안에서 잘려 보인다. 9월 v4 편집기부터의 동작이다. ## 위험과 영향 - 운영 동작이 바뀌는 것: - 공개 화면 이동 뒤 초점과 스크롤. - 청크 구성. Case 화면이 받는 JS 파일이 14개에서 36개로 늘었다. 화면이 뜨는 시간은 같다(chromium 0.92~0.96초, webkit 3.8~4.1초). 초기 JS gzip은 336,296B에서 300,178B로 줄었다. 예산(204,800B)은 main부터 넘는다(아래 표). - Studio 편집기 935px 이하 손잡이 여백. - MOCK 관리 mock은 로컬·시험 빌드에서만 쓰인다(운영은 HTTP). - visual 기준은 desktop 호스트에서 만들었다. 8월 기준도 같은 곳에서 만들었고, 바뀌지 않은 평문 NOT_FOUND 2장이 바이트까지 같다. CI 컨테이너에서 픽셀까지 같은지는 확인하지 못했다. ## 검증 desktop 호스트, node 24.14.0, CI env(`CI=true`, `VITE_BUILD_ID`, `RELEASE_ID`, `VITE_COMMIT_SHA`, `CI_RUNNER_IMAGE`), heavy lock 아래에서 돌렸다. push한 head의 새 clone이다. | 게이트·명령 | rc | 내용 | | --- | --- | --- | | FE-GATE-001 lockfile | 0 | | | FE-GATE-002 lint | 0 | | | FE-GATE-003 typecheck | 0 | | | FE-GATE-004 runtime schema | 0 | | | FE-GATE-005 unit·coverage | 0 | 176파일 2,388건, coverage 348파일 3,615건 | | FE-GATE-011 build·storybook build | 0 | | | FE-GATE-009 a11y | 0 | 90건 통과, a11y manual format 통과 | | FE-GATE-008 (1회차) | 1 | firefox 3건이 30초 시간 초과(홈 networkidle 2, SW 이벤트 1). 같은 시각 Gitea runner의 Gradle job으로 load average 22(12코어) | | FE-GATE-008 (2회차) | 0 | test:e2e 592 통과·3 skip, capability 63, storybook 1, visual 132, 증거 검사 둘 | | test:visual 단독 | 0, 0 | 기준 갱신 뒤 두 번 연속 132건 | | FE-GATE-012 번들 예산(머지 게이트 아님) | 1 | 초기 JS gzip 300,866B > 예산 204,800B. **main부터 초과**: main 334,022B, 청크 수정 전 336,296B → 수정 뒤 300,178B(36KB 줄었다). 이 PR로 생긴 실패가 아니고, 예산까지는 남은 일 | 흔들렸던 것의 연속 실행: | 대상 | 결과 | | --- | --- | | e2e: scroll-restoration, old-tab, app-shell, production-csp, boot-module-failure, tech-log-responsive (chromium·firefox·webkit·compact) | 3회 연속 115건 통과, 이어서 FE-GATE-008 2회차 통과 | | capability webkit 전체 | 1회차 1건 실패(BroadcastChannel, load 22 중), 2·3회차와 FE-GATE-008 2회차 통과(3회 연속) | | capability webkit BroadcastChannel 시험 | 20회 반복 두 번 40건 통과(load 35~41 포함). 재현되지 않았다 | | capability webkit IndexedDB blocked·다운로드 시험 | 고친 뒤 20회 반복 40건 통과 | | firefox responsive·SW 갱신(1회차 시간 초과 셋) | load 3.5~3.7에서 3회 연속 60건 통과, FE-GATE-008 2회차도 통과 | ## 남은 일 - FE-GATE-012 번들 예산: 초기 JS가 main부터 예산을 넘는다(이 PR 뒤 300,866B / 204,800B). - 템플릿의 preload 사용 직접 검사(`preload-use.ts`) 옮기기. 지금은 쓰이지 않는 preload를 어느 엔진에서도 잡지 않는다. - desktop 호스트의 WebKit은 화면 하나에 약 4초가 걸린다(Chromium 0.9초). 청크 수와는 상관없다. `playwright install-deps`가 설치하는 시스템 패키지 64개가 없지만, 그것이 원인인지는 확인하지 못했다(sudo 필요). ## 관련 - PR #6, #7 - 템플릿: `1103/11-09`(WebKit preload), `15-01`·`09-03`(청크 groups와 부팅 실패 화면)
donghyeon.kang added 16 commits 2026-11-12 11:28:35 +00:00
Studio 대시보드의 「지금 집중하는 것」(HomeFocusEditor)은 홈 포커스를
읽으면 effect에서 form.reset으로 값을 채운다. effect는 [focus,
form.reset]에 걸려 있다. 그런데 useAppForm의 reset은 defaultValues에
의존하고, 이 편집기는 defaultValues를 렌더마다 새 객체 리터럴로 넘긴다.
그래서 포커스가 한 번 읽히면 reset → 상태 갱신 → 다시 렌더 → 새 reset →
effect가 끝없이 돈다. 운영(HTTP)에서는 포커스가 있으면 대시보드가 계속
다시 그려진다. 시험 환경에서는 act가 끝나지 않아 시험이 멈춘다.

MOCK Studio에서는 지금까지 관리 기능이 HTTP로 나가 실패했기 때문에
포커스가 비어 있었고, 이 경로가 돌지 않았다. 관리 mock(다음 커밋)을 넣자
studio-shell-smoke.test.tsx의 첫 시험이 멈췄다(vitest worker CPU 100%로
19분, FE-GATE-005가 끝나지 않음).

defaultValues를 모듈 상수로 둔다. release-editor.tsx가 같은 이유로
EMPTY_RELEASE_DRAFT를 쓰는 방식과 같다.

검증: 관리 mock을 넣은 상태에서 이 수정 전에는 studio-shell-smoke의 첫
시험이 60초 timeout으로 끝나지 않는다. 수정 후 studio-shell-smoke·
studio-screens-smoke 8건이 5초에 통과한다. check:types, eslint rc=0.
create-tech-log-feature-input.ts는 Studio 문서와 Asset은
studioSource에 따라 mock과 HTTP를 고르는데, 관리 표면(주제·프로젝트·
릴리즈·홈 포커스·작업본 삭제)만 언제나 HTTP gateway를 썼다. 그래서
MOCK 빌드(로컬 개발, e2e·visual 빌드)에서 로그인한 Studio의 대시보드와
편집기가 주제·프로젝트를 읽으려고 API_BASE_URL의
/api/v1/studio/session으로 나가고, 연결이 거부된다. 브라우저 시험에서는
Studio 편집기 반응형 40건, Studio 접근성 7건, 경로별 axe의 Studio 두
경로 6건이 이것으로 떨어진다.

mock 문서 gateway와 같은 방식으로 mock 관리 gateway를 둔다.
- 메모리 안에만 있고, Studio 애플리케이션 하나가 사는 동안 유지된다.
- 주제는 MOCK_CATALOG, 프로젝트와 릴리즈는 공개 화면의 정적 콘텐츠
  (public-content.ts)에서 시작한다. 같은 이름과 slug를 쓴다.
- 실패는 백엔드와 같은 코드로 낸다(VERSION_CONFLICT, *_NOT_FOUND,
  게시된 것을 지울 때 CONFLICT).
- 같은 idempotency 키는 첫 결과를 돌려준다.
- 문서 gateway와 Studio state 하나를 나눠 써서, 관리 쪽에서 작업본을
  지우면 문서 목록에서도 빠진다. 그래서 createMockStudioGateway가
  state를 받을 수 있게 했다(주지 않으면 지금처럼 새로 만든다).

버린 대안: e2e에서 /api/v1/studio/**를 page.route로 가로채기. 로컬
개발 빌드는 그대로 깨진 채 남고, 시험만 초록이 된다.

한계: 결정(decision)과 프로젝트 활동은 빈 목록으로 시작한다. 공개
화면의 결정·활동 fixture는 관리 계약의 모양과 달라, 옮겨 담지 않았다.

검증:
- 새 단위 시험 mock-management-gateway.test.ts. 연결 전에는 첫 시험이
  「HTTP executor에 닿았다」로 실패했고, 연결 뒤 5건 모두 통과한다.
  mock-studio-gateway·Studio 화면 smoke·게시 흐름 시험(27건)도 통과한다.
- check:types, lint rc=0.
- chromium에서 Studio 편집기 반응형 10건, Studio 작업 흐름, 경로별 axe의
  Studio 경로가 통과한다(전에는 연결 거부로 실패).
이탈 확인(저장하지 않은 변경) 시험 셋은 작업본을 고친 뒤 「게시 기록」
링크를 누른다. Studio 머리말의 주 탐색은 지금 「작업·구조·자료·게시」로
묶여 있어 그 이름의 링크가 없다. 그래서 로그인과 관리 mock이 갖춰진
뒤에도 링크를 기다리다 30초 제한으로 떨어진다.

같은 곳(/studio/publications)으로 가는 「Studio 주 탐색」의 「게시」
링크를 누른다. visual의 같은 장면도 같이 바꾼다.

검증: tech-log-accessibility.spec.ts와 accessibility.spec.ts가
chromium·firefox·webkit에서 102건 모두 통과한다.
앱 모듈 하나가 평가 중에 예외를 던지면 main.tsx는 부팅 실패 화면
(render-boot-failure.tsx)을 그린다. 그런데 그 청크가 route-not-found
청크에서 값 둘을 import하고, route-not-found에는 React, i18n 카탈로그,
installed-feature-messages.ts가 같이 들어 있다. 그래서 예외를 던진
청크에 실패 화면도 같이 걸려 그리지 못하고, 정적 「불러오는 중」
화면이 계속 남는다(boot-module-failure e2e, 세 엔진 모두).

원인은 vite.config.ts의 manualChunks다. Rolldown은 manualChunks를
includeDependenciesRecursively가 기본값(true)인 group으로 바꾼다. 그래서
route-not-found로 지정한 Public not-found 화면이 자기 정적 의존을 전부
그 청크로 끌고 간다. PR #6 전(27e342d) 빌드도 같은 import가 있었다.

템플릿과 같은 output.codeSplitting.groups 형식으로 바꾼다. react-dom과
route 화면 group은 includeDependenciesRecursively: false로 둬서, 화면
모듈만 그 이름의 청크에 들어가게 한다. 공유 모듈은 Rolldown이 쓰는
쪽에 따라 나눈다. preload-helper·react-dom·route 청크 이름은 그대로다.

검증:
- build-environment-bundle.test.ts에 시험 하나를 더했다. 실패 화면
  청크에서 정적 import로 닿는 청크 가운데 installed-feature-messages의
  오류 문구가 든 것이 없어야 한다. 고치기 전에는
  route-not-found-*.js가 잡혀 실패했고, 고친 뒤 통과한다.
- vite-route-chunks, bundle-*, chunk-recovery*, performance-budgets 단위
  시험(29건) 통과.
- e2e: boot-module-failure, old-tab-chunk-recovery,
  service-worker-update·recovery, production-csp가 chromium·firefox·
  webkit에서 통과한다.
scroll-restoration 시험은 Case를 900px 내린 뒤 주요 탐색의 「프로젝트」를
누르고, 뒤로 가서 900px로 돌아오는지 본다. TechLog 머리말은 sticky가
아니어서, Playwright는 링크를 누르기 전에 머리말까지 페이지를 올린다.
그래서 화면을 떠나는 위치가 0이 되고, 900을 기대한 시험은 복원이 되든
안 되든 떨어진다. 템플릿의 머리말은 sticky라서 이 문제가 없었다.

링크를 스크롤 없이 누른다(dispatchEvent). 실제 사용자가 머리말까지 올려
누르면 떠나는 위치는 맨 위이고, 그것이 복원할 위치다.

검증: 이 수정만 넣고(복원 처리 없음) 돌리면 chromium은 브라우저 기본
복원으로 통과한다. firefox는 두 번 모두 실패하고, webkit은 두 번 중 한 번
실패한다. 다음 커밋이 그 복원을 맡는다.
TechLog 공개 화면은 화면에 도착했을 때 할 일을 아무도 하지 않는다.
- 초점: 템플릿은 라우터가 #main-content에, PageHeader가 h1에 초점을
  준다. 이 제품은 9월 동기화 때 라우터의 초점 이동을 빼며 「shell이
  맡는다」고 적었지만, Public shell에는 그 처리가 없다. TechLog 화면은
  PageHeader를 쓰지 않는다. 그래서 이동 뒤에도 초점이 누른 링크(모바일
  메뉴에서는 닫힌 details 안의 링크)에 남는다.
- 해시: /cases/...#section으로 열면 맨 위에 머문다. 본문은 데이터를
  받은 뒤에 그려져, 브라우저의 기본 앵커 이동이 일어날 때 대상이 없다.
- 뒤로 가기: 브라우저 기본 복원은 돌아갈 화면이 그려지기 전에 일어난다.
  firefox는 0으로, webkit은 가끔 0으로 돌아간다.

Public shell에 useRouteArrival을 둔다. 템플릿의 PageHeader 방식을 따른다.
- 새 경로에 도착하면, 화면이 그려진 뒤(#main-content의 h1이 있고
  aria-busy가 없을 때, 최대 5초) 해시 대상을 보이게 스크롤한다. 그다음
  초점을 받을 수 있는 해시 대상, 아니면 h1(tabindex -1)에 초점을
  준다(preventScroll). 첫 로드에서는 아무것도 초점을 갖지 않았을 때만
  옮긴다.
- 뒤로·앞으로 가기: history entry(location.key)마다 떠날 때의 위치를
  기억하고, 화면이 그만큼 길어지면 그 위치로 돌린다. Public shell이 떠
  있는 동안 history.scrollRestoration을 manual로 둔다. 새로고침은 mount
  전이라 브라우저 복원을 그대로 쓴다. 떠나는 위치는 새 entry를 렌더할 때
  기록한다. 짧은 화면이 commit되면 window.scrollY가 그 순간 줄어들기
  때문이다.
- 쿼리만 바뀌거나 같은 화면의 # 링크는 도착이 아니다.
- jsdom에서는 라우터의 스크롤 처리와 같이 아무것도 하지 않는다.

버린 대안:
- 라우터(템플릿 소유 app-router.tsx)에 되살리기. Studio 화면들은 자기
  초점 처리를 따로 갖고 있어 영향이 넓다. 이번 결함은 Public 화면이다.
- 공개 화면 14개의 h1마다 PageHeader 같은 컴포넌트를 씌우기. 같은 일을
  화면마다 반복하게 된다.
- 위치를 sessionStorage에 두기. 저장소 API는 adapter 소유라 lint가
  막는다. 메모리 Map으로 충분하다(새로고침은 브라우저가 복원한다).

위험: 화면이 5초 안에 그려지지 않으면 그때의 h1이나 대상에 맞춘다.
Studio 경로는 바뀌지 않는다.

검증:
- 이 커밋 전에는 app-shell drawer 초점, scroll-restoration 해시가
  chromium에서 실패한다. 뒤로 가기는 firefox·webkit에서 실패한다.
- 이 커밋 뒤에는 app-shell, scroll-restoration, production-csp가
  chromium·firefox·webkit에서 통과한다. webkit scroll-restoration은 3회
  연속 통과했다.
- 공개 화면 단위 시험 5파일과 router 시험(합쳐 86건) 통과. check:types,
  lint rc=0.
이 시험은 다른 탭이 v1을 연 채로 v2를 열게 하고, 런타임 상태가
BLOCKED가 되는지 본다. BLOCKED는 blockedTimeoutMs(500 ms) 동안만
있다가 CLOSED/NOT_OPENED로 바뀐다. 시험은 getStatus()를 바깥에서
expect.poll로 묻는데, poll 간격이 100·250·500·1000 ms로 벌어진다.
blocked 이벤트가 늦게 오면 그 500 ms가 두 번의 물음 사이에 지나가고,
시험은 뒤따른 CLOSED만 보다가 5초 뒤 떨어진다. WebKit에서 이 시험
하나가 10회 중 1회 이렇게 떨어졌다.

런타임의 subscribeStatus로 페이지 안에서 상태가 바뀔 때마다 기록하고,
그 기록에 BLOCKED가 있는지 본다. 재시도나 timeout을 늘려 덮지 않는다.
나머지 검증(열기 실패의 BLOCKED 오류, 막은 탭이 닫힌 뒤 늦은 연결을
닫음, 삭제)은 그대로다.

검증: WebKit에서 --repeat-each로 고치기 전 10회 중 1회 실패. 고친 뒤
20회 모두 통과(같은 실행의 다운로드 시험 20회 포함 40건).
이 시험은 BOUNDED_OBJECT_URL 다운로드로 Blob을 앵커에 넘기고, 브라우저의
download 이벤트를 기다린다. 그런데 deliver()가 handoff를 마치자마자
.finally(() => runtime.dispose())가 돈다. dispose()는 살아 있는 object URL을
즉시 해제한다(평소에는 30초 유예를 두지만 dispose는 정리라서 예외다).
WebKit은 앵커 클릭 뒤 다운로드를 비동기로 시작하므로, URL이 먼저 해제되면
다운로드가 시작되지 않는다. 그러면 download 이벤트 없이 30초 시험 제한으로
떨어진다. 2026-11-12 capability 실행 4번 중 1번 WebKit에서 이렇게 떨어졌다.

런타임을 전역에 두고, 다운로드 내용을 다 읽은 뒤 페이지에서 dispose한다.
제품의 해제 규칙(30초 유예, dispose 즉시 해제)은 바꾸지 않는다. 실제
화면에서 런타임은 다운로드 직후 버려지지 않는다.

검증: WebKit에서 --repeat-each=20으로 20회 모두 통과. 고치기 전 같은
조건 10회에서는 이 시험이 실패하지 않아 재현율은 낮다. 근거는 위 실패
로그와 dispose의 즉시 해제 코드(download-delivery-adapter.ts)다.
오래된 탭 시험은 A 빌드 탭에서 「프로젝트」를 누른 뒤
getByRole("heading", { name: "프로젝트" })가 보이면 다시 불러오기가 한 번
있었는지 센다. 그런데 탭이 아직 머물러 있는 홈 화면에도 h2 「프로젝트」가
있다. 그래서 A의 프로젝트 청크가 404가 나고 다시 불러오기가 시작되기 전에
조건이 맞고, 다시 불러오기 0번으로 떨어진다. 청크가 잘게 나뉜 뒤(부팅
실패 청크 수정) 다시 불러오기가 조금 늦어지면서 firefox·webkit에서
드러났다. PR #7에서 이 화면을 고를 때 이 h2를 보지 못했다.

새 화면의 h1을 기다린다.

검증: firefox trace에서 A의 route-tech-log-projects 청크가 404였고 그
뒤 release-manifest를 다시 받는 중이었다(다시 불러오기 직전). 고친 뒤
chromium·firefox·webkit에서 통과.
visual의 「unknown Public …」 20건은 /projects/missing-project 같은 경로가
서버의 평문 「Not Found」를 받는다고 기대하고, 그것을 찍는다. 6784eb1
(08-20)부터 서버는 등록된 Public 경로 패턴이면 SPA를 내고, 게시되지 않은
slug는 화면 안의 not-found(「페이지를 찾을 수 없습니다.」)가 된다. 그래서
글자를 찾지 못해 스크린샷 전에 떨어진다.

화면 안의 not-found h1과 site-frame을 확인하고 찍는다. 경로가 없는
NOT_FOUND의 평문 응답 visual은 그대로다. 기준 이미지는 visual 기준 갱신
커밋에서 새로 만든다.
「Studio immediate preview」 visual은 편집기의 「즉시 미리보기」 영역을
찍는다. d72eae2(09-16)가 편집기의 편집/미리보기 모드를 없애며 이 영역을
뺐고, 단위 시험은 그때부터 「없음」을 확인한다. visual만 남아 영역을 찾지
못하고 떨어진다.

시험과 기준 이미지를 지운다. 공개 렌더는 Public Preview 화면의 visual
(current-preview 등)이 계속 본다.
본문 블록 편집기(d72eae2, 09-16)는 드래그 손잡이와 블록 동작 칸을 읽기
단 바깥에 둔다. 그래서 section.studio-block-editor에 margin 0 -38px를 준다.
그런데 편집 화면의 옆 여백은 936px 이상에서만 38px 이상이다. 그 아래로는
24px(single-surface .studio-main이 100% - 48px), 760px 이하에서는 14px다.
그래서 761~935px에서는 14px, 760px 이하에서는 4px만큼 페이지 전체가
가로로 스크롤된다(760px 이하 규칙의 -18px도 14px 여백보다 넓다).

e2e의 「Studio editor has no overflow」는 이것을 잡지 못했다. 블록
편집기는 폼의 나머지보다 늦게 그려지는데, 시험은 그 전에 폭을 쟀다.
WebKit에서만 가끔 늦게 재서 900·820·768px이 떨어졌다.

손잡이 여백을 그 폭의 옆 여백에 맞춘다. 935px 이하는 24px(손잡이 칸
20px), 760px 이하는 14px(손잡이 칸 14px)이다. 936px 이상은 그대로다.
시험은 블록 편집기가 그려진 뒤에 잰다.

버린 대안: 상위 요소에 overflow-x: clip. 스크롤은 없어지지만 손잡이가
화면 밖에서 잘린 채 남는다.

검증:
- 폭별 측정(chromium): 고치기 전 935px 1, 930px 3, 920px 8, 900~761px 14,
  760px 이하 4px 넘침. 936px 이상은 0.
- 시험만 고친 상태에서 chromium·chromium-compact의 Studio editor 20건 중
  14건(935px 이하 일곱 폭 × 2) 실패. 고친 뒤 tech-log-responsive.spec.ts가
  chromium·firefox·webkit·chromium-compact에서 88건 모두 통과.
scroll-restoration, production-csp, old-tab-chunk-recovery,
boot-module-failure는 템플릿처럼 page.goto 뒤 첫 expect(5초) 안에 첫
화면이 그려지기를 기다린다. desktop 호스트의 WebKit은 화면 하나를 여는
데 혼자 돌 때도 3.8~4.6초가 걸린다(Case 화면, Chromium 0.93초). 그래서
다른 worker와 함께 돌면 5초를 넘겨 「불러오는 중」에서 떨어진다. 전체
test:e2e와 3회 반복에서 webkit만 이렇게 떨어졌다.

이 제품의 다른 브라우저 시험처럼 앱이 그려진 것(.site-frame, 부팅 실패면
alert)을 먼저 기다린다. scroll-restoration은 gotoTechLog로 연다. 시험하는
것(스크롤 위치, CSP, 다시 불러오기 횟수, 실패 화면 내용)은 그대로다.

부팅 실패 청크 수정 전후 WebKit 시간이 같아서(JS 14개일 때 3.8~4.6초,
36개일 때 3.8~4.1초) 청크 수가 원인은 아니다.

검증: 네 시험과 app-shell을 chromium·firefox·webkit에서 --repeat-each=3으로
81건 모두 통과.
WebKit은 load 이벤트 3초 뒤, 아직 쓰이지 않은 link preload마다 경고를
한 번 낸다. 공용 fixture는 경고를 실패로 센다. 그런데 desktop 호스트의
WebKit은 화면 하나를 여는 데 4초 안팎이 걸려, 곧 쓰일 청크에도 이 경고가
나온다. app-shell 시험이 3회 반복 중 한 번 이것으로 떨어졌다
(document-kind-labels-*.js).

템플릿(1103/11-09)과 같은 문장 정규식으로 이 경고만 무시한다.

한계: 템플릿은 이 추측 대신 「preload한 스크립트가 실제로 실행됐는지」를
모든 엔진에서 직접 검사한다(preload-use.ts, 시험 서버가 빌드 스크립트에
표시를 넣는다). 그 장치는 CSP·SW 시험의 응답 가로채기까지 같이 고쳐야
해서 옮기지 않았다. 그래서 쓰이지 않는 preload는 지금 어느 엔진에서도
잡히지 않는다. 다음 템플릿 동기화 때 옮길 일이다.

검증: app-shell을 포함한 다섯 시험을 세 엔진에서 3회 반복해 81건 통과.
signInToStudio는 로그인 뒤 Studio 머리말과 networkidle까지 기다린다. 그런데
mock Studio는 네트워크를 쓰지 않아 networkidle이 바로 오고, 화면은 그 뒤
약 0.3초 동안 aria-busy(데이터 로딩)였다가 본문을 그린다. 그래서 visual
「TECH_LOG_STUDIO_DOCUMENT_EDIT 360px」가 두 번 연속 로딩 상태(1000px)를
찍어, 다시 만든 기준(2077px)과 달라 떨어졌다.

main 안에 aria-busy가 없어질 때까지 기다린다.

검증: 로그인 뒤 100 ms마다 잰 값(chromium, 360px)에서 /studio,
/studio/documents, 편집 화면 모두 처음 세 번은 busy 1, 높이 1000이었고
네 번째부터 busy 0과 본문 높이가 됐다. 고친 뒤 test:visual 두 번 연속
132건 통과(PR 표).
visual 기준 이미지는 2026-08-18(cf45bcc)이 마지막이다. 그 뒤로 화면을
바꾼 커밋이 130개 들어왔고, 기준은 한 번도 갱신되지 않았다. 그래서
test:visual 133건 가운데 2건(평문 NOT_FOUND)만 통과했다.

달라진 이유는 아래와 같다(이미지별 표는 PR 본문).
- 공개 화면: 9월 개편(b9d0585 바탕화면 디자인 수정본, 0b0c5cb 홈의 길,
  fe1f235·d3bf392 기록 머리와 읽기 품질, e88ed5e·5399e19 조사 상태,
  aca4f18·de4cb8b 주제 목록과 탭 등), 질문 라벨 대비(cd4fa8c).
- Studio 화면: 로그인한 Studio를 찍는다(500dbc6). Studio 재설계와 v4 블록
  편집기(9545860, d72eae2 등), MOCK 관리 데이터(이 브랜치의 관리 mock:
  대시보드 「지금 집중하는 것」).
- 모르는 slug 20장: SPA 안의 not-found(6784eb1, 이 브랜치의 visual 수정).
- 편집기 360px: 블록 손잡이 여백(이 브랜치의 935px 이하 수정).

검토한 방법:
- visual이 찍는 56개 화면을 같은 조건(고정 시계, Studio 로그인)으로 열어
  오류 화면, aria-busy, 로그인 관문, 콘솔 오류를 셌다. 의도한 not-found
  화면 말고는 없었다.
- 옛 기준과 새 기준을 나란히 놓고 범주마다 봤다. 의도와 다른 차이가 하나
  있었다. 공개 화면 h1에 파란 초점 테두리가 생긴 것이다(이 브랜치의 도착
  초점 처리가 h1에 data-route-heading을 달지 않았다). 그것은 기준을
  바꾸지 않고 코드에서 고쳤다(f78ce58에 합침).
- desktop 호스트(chromium, CI env)에서 test:visual:update. 그 뒤
  test:visual 두 번 연속 132건 통과(즉시 미리보기 1건은 지웠다).

한계: 이 호스트에서 만든 기준이다. 8월 기준도 같은 호스트에서 만든 것이고
평문 NOT_FOUND 2장이 이번에도 바이트까지 같다. CI 컨테이너
(playwright --with-deps)에서 픽셀까지 같은지는 확인하지 못했다.
donghyeon.kang merged commit e5fe335e5a into main 2026-11-12 11:28:36 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/tech-log-frontend#8