feat(blog-web-svelte): 블로그를 SvelteKit으로 병행 재구현해 React와 나란히 잰다

[Han5991]

배경

apps/blog/web은 Next.js 16 + React 19로 굳어 있습니다. 소스 191개, 글 70편, React 전용 런타임 의존만 8종(@ssgoi/react·@giscus/react·react-markdown·recharts·@tanstack/react-query·react-medium-image-zoom·react-syntax-highlighter·lucide-react)입니다.

여기서 궁금한 것이 넷입니다.

1. 같은 사이트를 컴파일 기반 프레임워크로 지으면 번들이 실제로 얼마나 줄어드는가
2. 이 블로그의 저작 문법(커스텀 태그 15종)이 React 없이도 같은 모양으로 서는가
3. @blog/content·check-seo·Panda blog-preset이 정말 프레임워크 중립인가 — 지금까지 소비자가 React 하나뿐이라 검증된 적이 없습니다
4. 이 저장소의 저작 스킬(blog-design-system·blog-components·blog-diagrams·tech-blog-writer)이 React를 전제하고 있는가

넷 다 읽어서는 답이 안 나오고, 지어 봐야 나옵니다. 그래서 운영 블로그는 그대로 두고 SvelteKit으로 같은 사이트를 한 벌 더 짓습니다.

무엇을 만드는가

apps/blog/web-svelte(@blog/web-svelte) 워크스페이스를 새로 만들어, apps/blog/web과 같은 콘텐츠·같은 토큰·같은 URL 계약으로 블로그 전체를 SvelteKit + adapter-static으로 재구현합니다. 기존 React 앱은 지우지 않고 그대로 운영합니다.

결정 요약

축	결정	근거
프레임워크	SvelteKit + adapter-static	선정 기준은 문법 직관성 + 번들 최소. Solid 스파이크 없이 Svelte로 확정
대상 범위	공개 6개 라우트 + Admin 4개 = 전체	부분만 지으면 번들 비교가 사과와 오렌지가 됨
React 앱	유지	3중 비교가 아니라 2중 비교(React vs Svelte). 되돌리기가 항상 가능
워크스페이스	apps/blog/web-svelte / @blog/web-svelte	나중에 진짜 교체할 때 web으로 개명하는 경로가 자연스럽다
콘텐츠 소스	apps/blog/posts 공유	원고를 복제하면 두 사이트가 조용히 갈라진다
콘텐츠 파이프라인	@blog/content 그대로 재사용	자체 content.config.mts + content.values.mts만 새로 둔다
스타일	Panda CSS + blog-preset 그대로	색 토큰의 단일 출처가 blog-preset.ts라는 금지선을 유지. @design-system/ui의 React 컴포넌트만 재구현
Supabase	로컬 인스턴스만	프로덕션 post_views·post_view_logs에 쓰지 않는다 → 운영 조회수·Analytics 오염이 구조적으로 불가능
배포	별도 Worker, wrangler versions upload 프리뷰 URL만	custom_domain 없음. 최종 배포 전환은 이 이슈 범위 밖
기능 플래그	해당 없음	별도 워크스페이스라 기존 블로그 사용자에게 노출되는 경로가 없다. 워크스페이스의 존재 여부가 곧 스위치
마감	없음	실험·학습이 목적. 스택 PR을 틈날 때 쌓는다

목적 (성공 기준의 출처)

• 학습·비교 실험 — 반응성 모델·컴파일 전략·DX 차이를 직접 겪는다
• 번들 크기·성능 개선 여지 확인
• 블로그 글 소재 확보
• 저작 스킬 4종의 사용성·성능 점검 — React 전제가 얼마나 박혀 있는지

---

대시보드 (2026-09-13 3차 갱신)

구현은 전부 릴리즈 브랜치(claude/react-svelte-solid-migration-dkj247)에 머지됐습니다. main에는 아직 아무것도 들어가지 않았습니다.

무엇	PR	릴리즈 브랜치 머지 커밋
구현 스택 14개	#393~#406, #408	9a2082b (맨 위 #408)
프리뷰를 앱별로 조건부 빌드	#409	286b603
mermaid 글 본문 소실 수정	#413	f3340b2
main 승격	#412 (초안)	미결정 — 9월 말까지 판단을 보류합니다

머지 기록

순서	PR	브랜치	내용
1	#393	svelte-1-baseline	기준선 측정 + 워크스페이스 뼈대
2	#394	svelte-2-site-values	사이트 값을 @blog/site-values로
3	#395	svelte-3-routing	공개 라우트 5개 + check-seo 통과
4	#396	svelte-4-markdown-components	커스텀 태그 9종을 HAST 변환으로
5	#398	svelte-5-diagrams	레이아웃 엔진을 @blog/diagram으로
6	#399	svelte-6-code-blocks	check-bundle에서 경로 관례 제거
7	#400	svelte-7-code-blocks	코드 블록 빌드 타임 강조
8	#401	svelte-8-client-runtime	읽기 경로 클라이언트 조각
9	#402	svelte-9-search-comments	⌘K 검색 + Giscus
10	#403	svelte-10-admin	조회수·대시보드를 @blog/analytics로
11	#404	svelte-11-admin-ui	Admin 대시보드 + 조회수
12	#405	svelte-12-ci-deploy	CI 게이트 + 프리뷰 배포
13	#406	svelte-13-home-parity	화면 파리티 + check-parity + 주석 규칙
14	#408	svelte-14-admin-charts	차트 반응형·곡선 파리티 + 기하 스냅샷

• 머지 커밋으로 내렸습니다. 스쿼시하면 PR마다 새 SHA로 들어가 다음 PR의 merge-base가 옛 커밋에 남고, 그 PR의 diff가 앞 PR의 내용까지 끌어안습니다(실측 10 → 29파일)
• 머지 경로. REST 머지 엔드포인트는 스택 PR을 403(Merging stacked PRs via this endpoint is not supported)으로 거절합니다. gh stack merge <스택 번호> --yes --merge로 내렸습니다 — 메서드를 빼면 마지막에 쓴 방식을 따르므로 --merge를 명시해야 합니다
• base는 미리 못 돌립니다. GitHub이 스택 멤버의 base 변경을 막습니다(Cannot change the base branch because the pull request is part of a stack)
• #408은 GitHub 스택 UI에 묶여 있지 않았습니다. 생성 시점에 REST API가 POST /pulls를 500/502로 거절해 웹 UI로 만들었고, base가 올바라 머지 순서에는 영향이 없었습니다

#409 — 프리뷰를 앱별로 조건부 빌드

preview-blog.yml 매트릭스의 두 줄(preview = Next.js, preview-svelte = SvelteKit)이 자기 앱 경로나 두 앱이 함께 읽는 경로(원고·packages/@blog·이 워크플로)가 바뀐 PR에서만 빌드·업로드합니다. 잡 if에서는 matrix를 쓸 수 없어 첫 스텝이 pulls/{n}/files로 판정하고 뒤 13스텝을 건너뜁니다. 옮긴 파일은 옛 경로도 보고, API 실패나 3000개 상한에서는 건너뛰지 않습니다.

• React 판만 고친 PR에서 preview-svelte 잡이 70초 → 6초
• 테스트: workflowPreviewGate.test.ts(구조) + workflowPreviewGateScript.test.ts(워크플로의 run: 블록을 꺼내 가짜 gh로 실행, 27개)

스벨트를 몰라도 리뷰하는 법

코드 구조는 알지만 Svelte 문법이 처음일 때를 위한 안내입니다.

문법 대응표 — 이 스택에 실제로 나오는 것만

React에서 아는 것	이 스택의 Svelte	비고
useState	let x = $state(0)	그냥 변수. 대입하면 다시 그린다
useMemo / 파생값	const y = $derived(...), 여러 줄이면 $derived.by(() => ...)	의존성 배열이 없다 — 읽은 것을 컴파일러가 안다
useEffect	$effect(() => { ...; return () => 정리 })	정리 함수는 React와 같은 자리
function C({ a, b })	const { a, b } = $props()	타입은 그 자리에 붙인다
children	{@render children()}, 타입은 Snippet
onClick={fn}	onclick={fn}	소문자다. DOM 속성 이름 그대로
{cond && <X/>}	{#if cond}<X/>{/if}
xs.map(x => <Row key={x.id}/>)	{#each xs as x (x.id)}<Row/>{/each}	괄호 안이 key
ref={el}	bind:this={el}
useRef + ResizeObserver	bind:clientWidth={w}	Svelte가 ResizeObserver로 구현한다. #408에서 <ResponsiveContainer> 자리에 씀

파일 배치도 대응됩니다.

Next.js	SvelteKit
app/posts/page.tsx	routes/posts/+page.svelte
서버 컴포넌트의 데이터 로드	routes/posts/+page.server.ts의 load()
generateStaticParams	+page.server.ts의 entries()
app/layout.tsx	routes/+layout.svelte
'use client'	없다. 대신 src/lib/server/ 아래 모듈을 화면이 import하면 빌드가 실패한다

마지막 줄이 실제로 도움이 된 차이입니다. React 판은 "이 모듈은 서버 전용"을 주석과 리뷰로 지키는데(src/content.ts), 여기서는 도구가 강제합니다.

문법을 몰라도 볼 수 있는 것 — 체크리스트 여섯

Svelte 코드 한 줄도 읽지 않고 이것만 확인해도 위험은 거의 덮입니다.

1. 화면이 @blog/content 배럴을 여는 곳이 있는가 — 있으면 안 됩니다. 배럴은 node:fs를 함께 열어서, 클라이언트 그래프에 들어가면 Vite가 빈 스텁으로 바꿉니다(빌드는 성공하고 런타임에만 깨집니다). 화면은 @blog/content/client만 씁니다
   → grep -rn "from '@blog/content'" apps/blog/web-svelte/src/lib/components apps/blog/web-svelte/src/lib/client
2. 값의 단일 출처를 건너뛴 곳이 있는가 — 사이트 값은 @blog/site-values, 앱 경로는 src/lib/shared/routes.ts, 글 URL은 postPath
3. 색 hex 리터럴이 컴포넌트에 있는가 — 0건이어야 합니다
   → grep -rn "#[0-9a-fA-F]\{6\}" apps/blog/web-svelte/src
4. 레일 폭(maxW·px)을 페이지가 직접 쓴 곳이 있는가 — Rail.svelte만 압니다
5. 인라인 eslint-disable이 있는가 — 0건이어야 합니다(noInlineConfig로 애초에 안 먹습니다)
6. 화면 문자열이 React 판과 같은가 — 라벨·placeholder·aria-label. Svelte를 몰라도 두 파일을 나란히 놓으면 보입니다

결정이 든 파일 일곱

나머지는 기계적인 이식입니다. 논쟁할 값이 있는 것은 이 일곱입니다.

파일	무엇을 정하나
apps/blog/web-svelte/content.config.mts	경로 앵커와 배선. __CONTENT_ROOT__로 앵커를 덮는 이유가 주석에
apps/blog/web-svelte/content.values.mts	이 앱의 번들 규칙 12개. 마커를 왜 React 판과 다르게 골랐는지가 핵심
apps/blog/web-svelte/panda.config.ts	구문 강조 토큰 매핑. React는 서드파티 테마의 hex를 치환하고, 여기는 Prism 클래스에 역할을 직접 잇습니다
src/lib/server/markdown/index.ts + 형제들	커스텀 태그를 빌드 타임 HAST 변환으로. React는 런타임 컴포넌트 맵입니다
src/lib/client/archiveParams.ts	/posts URL 계약. nuqs를 안 쓰고 순수 함수 둘로
src/lib/shared/tocRail.ts	차례 레일 좌표 + 활성 구간 판정. 데스크톱·모바일이 같은 함수를 씁니다
src/lib/admin/charts/geometry.ts	차트 좌표. 영역 차트는 0→max, 스파크라인은 min→max로 스케일이 다르고, 그 이유가 주석에 있습니다(React 판이 그렇게 나뉘어 있습니다)

게이트가 대신 봐 주는 것

• check-seo — 산출물 HTML의 SEO 계약 99페이지. React 판과 같은 검사기를 수정 없이 통과합니다
• check-bundle — 청크 마커 규칙 12개. admin 코드·mermaid·구문 강조 파서·차트 곡선 계산이 공개 페이지 첫 로드에 없다는 것
• check-parity — 두 산출물의 클래스 어휘·헤딩·링크·요소 수·아이콘 선언 대조
• 계약 테스트 116개 / 파일 15개 — URL 계약, 공개 판정, 커스텀 태그 구조, 좌표 계산, 차트 기하 스냅샷
• lint --max-warnings=0, check-types

게이트는 전부 JS가 돌기 전의 산출물만 봅니다. 브라우저에서 JS가 DOM을 바꾸거나 읽는 조각(mermaid·이미지 줌·코드 복사·차례)은 어느 게이트에도 걸리지 않습니다. mermaid 글 5편의 본문이 사라진 채로 #401부터 #412까지 통과한 이유입니다 — 아래 「배포 뒤 발견한 결함」

---

측정 결과 (2026-09-13 재측정, 양쪽 새로 빌드)

blog-content measure-bundle — gzip 첫 로드 전송량(HTML + CSS + JS), 프로덕션 빌드.

페이지	React	Svelte	비율	차이
/	313.6 KB	87.4 KB	27.9%	−226.2 KB
/about/	313.0 KB	86.9 KB	27.8%	−226.1 KB
/posts/ (중앙값)	339.7 KB	114.8 KB	33.8%	−224.9 KB
/series/	255.1 KB	87.5 KB	34.3%	−167.6 KB
/privacy/	249.9 KB	85.2 KB	34.1%	−164.7 KB
/404/	248.1 KB	82.4 KB	33.2%	−165.7 KB
/admin/ (중앙값)	447.9 KB	146.1 KB	32.6%	−301.8 KB

산출물 전체: 921개 파일 96.5 MB → 529개 파일 64.0 MB

어디서 갈리는가 — 분해

페이지		HTML	CSS	JS
/	React	9.3 KB	30.3 KB	274.0 KB (13개)
	Svelte	5.8 KB	29.5 KB	52.1 KB (19개)
/404/	React	5.2 KB	30.3 KB	212.7 KB (9개)
	Svelte	3.3 KB	29.5 KB	49.6 KB (18개)
/admin/	React	5.6 KB	30.3 KB	412.1 KB (17개)
	Svelte	3.4 KB	29.5 KB	113.2 KB (25개)

CSS가 30.3 대 29.5로 사실상 같습니다. 파리티 전에는 30.3 대 10.3이었습니다. 그 격차는 프레임워크가 아니라 기능 수였다는 것이 이걸로 확인됩니다 — 같은 Panda 프리셋이라 화면이 같아지면 유틸리티도 같아집니다. 이 결론은 라이브러리 선택과 무관합니다.

JS 수치를 어디까지 믿을 수 있나

JS는 페이지마다 오염 정도가 다릅니다. 가장 깨끗한 것은 /404/ 입니다 — 차트도 쿼리도 URL 파라미터도 애니메이션도 없어서, 논쟁 중인 라이브러리가 하나도 걸리지 않습니다.

/404/ JS	React	Svelte
	212.7 KB	49.6 KB (23.3%)

차이 163.1 KB 중 확실하게 귀속되는 것:

크기	식별된 내용
69.5 KB	react-dom + unstable_scheduleCallback + createRoot
41.5 KB	React 내부(Minified React error)
나머지	확실하게 귀속하지 못함

/posts/·/admin/은 여전히 라이브러리 선택이 섞여 있습니다 — 아래 절을 보세요.

라이브러리 비용 — 실측 (2026-09-13)

「손으로 만들기 전에 대안을 찾지 않았다」는 지적에 대한 조사 결과입니다. Vite + Svelte 5.57 프로브를 만들어 실제로 번들했습니다(gzip, Svelte 런타임 베이스라인 16.1 KB 제외).

후보	추가	렌더	Panda 토큰	비고
d3-shape (곡선만)	+2.3 KB	SVG	✅	채택 — #408에서 들어감
@tanstack/svelte-query	+6.8 KB	—	—	미적용
d3-shape + d3-scale	+10.6 KB	SVG	✅
layercake 8.4	+20.9 KB	SVG(마크는 직접)	✅	유일한 진지한 대안
uPlot 1.x	+22.5 KB	Canvas	❌	구조적 탈락
chart.js (tree-shaken)	+58.4 KB	Canvas	❌	구조적 탈락
@observablehq/plot	+130.0 KB	SVG	△
layerchart 2.5 (/svg 서브패스)	+148 KB	SVG	❌ Tailwind	recharts보다 큼
recharts (React 판 현재)	~129 KB	SVG	✅	마커를 가진 청크 3개의 합(상한)

두 가지가 뒤집혔습니다.

• layerchart는 배럴 탓이 아니었습니다. 처음 +132.5 KB가 나왔을 때 export * 트리셰이킹 실패로 보고 넘겼는데, layerchart/svg 서브패스로 좁혀도 오히려 더 큽니다(148 KB, 정적 클로저 32청크). 게다가 스타일이 @layerstack/tailwind에 묶여 Panda strictTokens 위에 얹을 수 없습니다
• Canvas 계열은 크기와 무관하게 탈락입니다. 색을 css()로 못 주니 CSS 변수를 읽어 주입하고 테마 전환마다 다시 그려야 하는데, 이 저장소는 다이어그램 SVG까지 전부 토큰에 연결하는 금지선이 있습니다. check-seo·check-bundle도 canvas 내용은 못 봅니다

recharts 129 KB가 이 대시보드에서 실제로 하는 계산은 2.3 KB입니다. recharts의 victory-vendor가 d3-shape/d3-scale을 벤더링한 것이고, type="monotone"은 curveMonotoneX 그 자체입니다.

라이브러리 교체 비용의 분해

recharts를 쪼개면 셋으로 갈립니다. 이 축이 「무엇이 비쌌는가」를 설명합니다.

조각	프레임워크 종속?	이 화면의 비용
계산 (d3-shape·d3-scale)	무관	2.3 KB — 그대로 가져옴
DOM 측정 (ResponsiveContainer)	무관 (브라우저 API)	0 KB — bind:clientWidth
컴포넌트 조립 (<XAxis/>·<Area/>)	React 전용	나머지 전부

셋째가 가치는 가장 작고 번들은 가장 큽니다. 같은 분해를 nuqs에 대면 셋째가 거의 0이라 73줄로 끝났고, motion은 셋째가 아예 없어서 패키지가 그대로 갈 수 있었습니다. 분해가 곧 비용 예측입니다. 전문은 이 코멘트.

남은 오염 — 무엇이 정리됐고 무엇이 아닌가

라이브러리	상태
recharts ↔ 직접 그린 SVG	정리됨(다른 방식으로). 대안 8종을 실측했고 공정한 교체 대상이 없음을 확인했습니다(위 표). 동시에 Svelte 판이 빠뜨리고 있던 반응형 사이징과 곡선 보간을 #408에서 채워 기능이 동등해졌습니다. 「같은 라이브러리」는 아니지만 「같은 기능, 근거 있는 선택」입니다
@tanstack/react-query ↔ 69줄 스토어	미정리. svelte-query 비용만 쟀습니다(+6.8 KB). 넣어서 재지는 않았습니다
nuqs ↔ 73줄 순수 함수	미정리. sveltekit-search-params 4.0.0을 재지 않았습니다
motion ↔ svelte/transition	미정리. motion은 프레임워크 중립이라 같은 패키지를 쓸 수 있는데 쓰지 않았습니다. 현재 svelte/transition의 fly·fade·scale을 씁니다 — 스프링과 다른 움직임입니다

HTML에서도 갈립니다 — 하이드레이션 페이로드

글 상세 HTML을 페이로드와 마크업으로 갈라 재면:

	전체(gzip)	페이로드 제외	페이로드 원문
React	34.4 KB	13.2 KB	153.5 KB
Svelte	20.1 KB	12.0 KB	49.3 KB

마크업 자체는 13.2 대 12.0으로 거의 같습니다 — 픽셀 파리티가 다른 각도에서 한 번 더 확인됩니다. 차이 14 KB는 전부 RSC flight 페이로드입니다.

#406 시점 대비 변화

	#406 기록	지금	변화
/	86.6 KB	87.4 KB	+0.8
/posts/	114.0 KB	114.8 KB	+0.8
/404/	81.6 KB	82.4 KB	+0.8
/admin/	142.8 KB	146.1 KB	+3.3

#408이 d3-shape(+2.3 KB)와 스파크라인 채움 경로를 넣은 결과입니다. admin의 +3.3 KB가 그 실제 비용이고, 공개 페이지도 0.8 KB씩 늘었습니다 — d3-shape가 샌 것은 아닙니다(check-bundle 규칙 12번이 curveMonotoneX가 어느 페이지 첫 로드에도 없음을 강제하고 통과합니다). 청크가 하나 늘면서 SvelteKit 매니페스트가 커진 것으로 보이나 확인하지 않은 추정입니다.

아직 못 잰 것

• query·url-params·motion의 라이브러리 비용 분리 — 위 표의 미정리 셋
• LCP · 하이드레이션 시간 — 측정 항목에 있지만 재지 못했습니다. 번들 크기만 있습니다
• 빌드 시간 — React 49초는 기록돼 있으나 같은 조건의 Svelte 수치가 없습니다

---

프레임워크 중립성 — 가정이 어떻게 판명됐나

자산	가정	판명
@blog/content 로더·공개 판정·URL 계약	중립	참. 다만 배럴이 node:fs를 함께 열어, 클라이언트 그래프에서 빈 스텁으로 externalize됐습니다(빌드는 성공하고 런타임에만 깨집니다). 클라이언트 문 @blog/content/client를 새로 냈습니다
@blog/content 빌드 스크립트	중립	참. 진입점을 blog-content 하나로 모았습니다
check-seo	중립	참 — 수정 없이 통과합니다. 이 실험에서 가장 강한 중립성 증거
check-bundle	반쯤 중립	거짓이었습니다. /_next/static/chunks/가 경로에 박혀 있어 SvelteKit 산출물에서 청크를 하나도 못 찾았습니다. 음성 검사만 있었다면 규칙 전부가 "누수 없음"으로 통과했겠지만, 양성 대조(requiredIn)가 #328(2026-08-27)부터 규칙마다 필수라 전 규칙이 marker-dead로 실패하며 드러났습니다. 경로 관례를 걷어냈습니다(#399). 정정: 이전 기록의 "규칙마다 양성 대조를 필수로 만들었다"는 틀렸습니다 — 필수화는 이 실험 전의 일입니다
Panda blog-preset	중립	참. jsxFramework 없이 css() 함수만 씁니다
@design-system/ui 컴포넌트	비중립	예상대로. Svelte로 재구현
React 전용 런타임 의존 8종	전부 다시 만들어야 한다	거짓. 셋(react-markdown·react-syntax-highlighter·@giscus/react)은 React 바인딩일 뿐이라 벗겨 내면 같은 엔진(unified·refractor·giscus 스크립트)을 그대로 씁니다. 넷(react-query·recharts·nuqs·motion)은 Svelte 대안이 있는데 찾아보지 않고 손으로 만들었습니다 — 뒤늦게 전부 실측했고(위 표), 그중 recharts만 "대안이 더 나쁘다"가 확인됐습니다

예상 밖의 결과

• 사이트 값이 중립이 아니었습니다. React 앱의 content.values.mts에 묶여 있어 @blog/site-values 패키지로 뺐습니다
• 조회수·대시보드 도메인 2,560줄에 react·next/ import가 0이었습니다. 원래 중립이었고 앱에 묶여 있던 것은 env를 읽어 클라이언트를 만드는 일 하나였습니다 → @blog/analytics
• 다이어그램 좌표 계산기도 중립이었습니다 → @blog/diagram. 두 앱이 같은 좌표를 쓰므로 같은 원고가 픽셀 단위로 같은 그림이 됩니다
• "React 전용 의존"의 절반은 React 전용이 아니었습니다. 위 표의 마지막 줄
• Svelte 앱 11,093줄 중 3,053줄이 프레임워크 import가 0입니다(lib/server 2,248 + lib/shared 654 + lib/domain·platform 151). boundaries 린트가 강제한 결과고, 그만큼은 다음 프레임워크로 그대로 갑니다

이 실험이 실제로 가르쳐 준 것

계획에 없던 발견들입니다. 깨진 가정 자체가 산출물이라는 방침에 따라 남깁니다.

1. 기계가 세는 게이트는 화면을 보지 않습니다. check-seo·check-bundle·테스트가 전부 초록인 채로 여섯 페이지가 자리만 잡은 화면이었습니다. 12개 PR 동안 드러나지 않았습니다
2. 완료 기준에 없는 것은 만들어지지 않습니다. 원장의 18개 기준 중 "화면이 같다"고 말하는 줄이 없었고, 그래서 화면이 같아지지 않았습니다
3. "계약·회귀 테스트만 이식"이 시각 계약 테스트를 정확히 제외했습니다. React 판 Rail.test.tsx의 test('기본 폭은 text다')를 이식했다면 레일 폭 버그는 없었을 것입니다
4. 웹폰트 누락은 박스로는 안 잡힙니다. JetBrains Mono를 안 싣고 있었는데 모노는 0.6em 고정폭이라 글자 상자가 픽셀 단위로 같았습니다. 크롬의 실제 렌더 폰트 조회(CSS.getPlatformFontsForNode)로만 드러났습니다. Pretendard 때는 한글 폴백의 폭이 달라 줄바꿈이 어긋나며 드러났습니다
5. 번들 수치에는 유효성 전제가 필요합니다. 기능이 다른 두 산출물의 크기 비교는 아무것도 말해 주지 않습니다
6. 대체물을 만들기 전에 대안을 찾아야 합니다. 라이브러리 넷을 손으로 만들면서 Svelte 대안을 찾아보지 않았고, 그 선택이 주 지표를 오염시켰습니다. 「찾아봤는데 없어서」와 「안 찾아봐서」는 글로 적으면 똑같이 읽힙니다 — 전자였는지 확인할 방법이 기록에 없으면 후자로 보는 편이 안전합니다
7. 애니메이션은 정지 마크업 대조로 못 잡습니다. motion의 스프링을 svelte/transition의 280ms fly로 바꿔 놓고 픽셀 파리티를 달성했다고 적었습니다. 다른 움직임입니다
8. 게이트에 사각지대가 있으면 거기에 결함이 고입니다. /admin은 로그인 게이트 뒤라 배포된 프리뷰에서 열리지 않고, check-parity의 PARITY_PAGES 5개에도 없습니다 — 두 검증 장치 어느 쪽도 보지 않는 화면입니다. 그 틈에서 AreaChart가 preserveAspectRatio="none"으로 viewBox를 가로로만 늘려 축 글자가 뭉개지고 커서 점이 타원인 채로 살아남았습니다. 빌드도 check-seo도 check-bundle도 전부 통과하고 있었습니다(#408에서 수정 + 좌표 스냅샷으로 잠금)
9. 손으로 만든 코드가 실패한 자리는 계산이 아니라 렌더링 환경 대응이었습니다. 차트 428줄을 쪼개면 geometry.ts 101줄(순수 함수 + 테스트)에서도, 마크업 250줄에서도 버그가 안 났습니다. 난 곳은 실제 폭 측정·곡선 보간·라벨 겹침 — 전부 브라우저에서만 드러나고 순수 함수로 안 떨어지는 축입니다. 라이브러리가 파는 것의 상당 부분이 사실 이쪽이고, 직접 만들면 이 축이 구조적으로 빕니다
10. 라이브러리 교체 비용은 "대응 패키지가 있나"가 아니라 "렌더 트리에 얼마나 붙어 있나"로 결정됩니다. 위 「라이브러리 교체 비용의 분해」 절
11. 본문을 빌드 타임 HTML로 구우면, 상호작용은 "마운트 뒤 DOM 고치기"가 되고 그 코드는 게이트 밖에 놓입니다. React 판은 react-markdown이 렌더할 때 코드 블록 노드를 컴포넌트로 바꿔(CodeBlock.tsx — language === 'mermaid'면 <MermaidLazy>) 그림이 트리의 제자리에 들어갑니다. 무엇을 바꿀지 고르는 코드가 없습니다. Svelte 판은 본문을 {@html} 문자열로 넣어 그 안에 컴포넌트를 둘 수 없으므로, Mermaid.svelte가 마운트 뒤 DOM을 찾아 replaceWith로 바꿉니다. 바꿀 대상은 다른 파일(codeBlock.ts)이 정한 마크업 모양에 대한 가정이었고, 그 가정이 틀려 본문 전체가 그림 하나로 대체됐습니다(fix(blog-web-svelte): mermaid 그림이 글 본문 전체를 대신하지 않게 한다 #413). 그림 그리기는 두 판 모두 같은 mermaid.render입니다 — 라이브러리의 문제가 아니라 10번 분해의 컴포넌트 조립 조각을 손으로 대신한 자리입니다. 빌드 타임 굽기를 택한 이유(load 데이터가 하이드레이션용으로 HTML에 한 번 더 직렬화된다)는 apps/blog/web-svelte/README.md에 있습니다

배포 뒤 발견한 결함

mermaid가 있는 글의 본문이 사라졌다 — #413에서 수정

발견	2026-09-13, 프리뷰의 /posts/payment-system-architecture/가 헤더와 썸네일만 보인다는 제보
증상	서버 HTML(curl)에는 본문이 전부 있다(h2 6 · p 33). 브라우저에서 JS가 돈 뒤에는 #post-content가 없고, 그 자리에 mermaid 그림 상자 하나만 남는다
원인	codeBlock.ts는 mermaid 펜스를 상자로 감싸지 않는다(<pre><code class="language-mermaid">가 본문 바로 아래). Mermaid.svelte는 <div><pre><code> 모양을 가정하고 closest('pre')?.parentElement를 바꿨다 → 그 부모가 #post-content
기간	Mermaid.svelte가 들어온 #401(4bf2cae)부터 #413 머지(f3340b2)까지
영향	mermaid 펜스가 있는 글 5편 — payment-system-architecture · next-js-ecs-deploy · 번들러 2·3·4편. React 판은 무관
수정	<pre> 하나만 바꾼다. 서버 쪽 테스트에 "mermaid 펜스는 상자 없이 <pre>로 나간다"를 잠갔다 — 이 단언은 수정 전에도 통과한다. 클라이언트 버그는 이 앱의 node 테스트 환경에서 재현되지 않는다
검증	JS가 돈 뒤 #post-content의 h2·p 수를 서버 HTML과 대조 — 로컬 빌드에서 글 44편 전부, PR 프리뷰 배포본에서 mermaid 글 5편. 그림 8개가 서버의 mermaid <pre> 수와 같다

마운트 뒤 DOM을 만지거나 읽는 다른 조각은 동작을 확인하지 않았습니다. 이번 대조는 "본문이 남는가"만 봤습니다.

• src/lib/client/CopyCode.svelte — closest('figure')로 코드를 찾는다
• src/lib/client/ImageZoom.svelte
• src/lib/client/Toc.svelte · MobileToc.svelte — 헤딩 id로 요소를 찾는다

스택 PR 계획 → 실제 진행

원래 6단계를 계획했으나 14개로 쪼개졌습니다.

계획 #	내용	상태
1	기준선 측정 + 워크스페이스 뼈대	✅
2	라우팅 + 정적 페이지	✅
3	마크다운 렌더 + 커스텀 태그	✅ 13종(원고가 실제로 쓰는 전부)
4	Mermaid · 구문 강조 · 이미지 줌 + check-bundle 규칙	✅ 규칙 12개
5	런타임 기능	✅ 페이지 전환 애니메이션만 제외
6	Admin + 배포 + CI + 문서 + 글 초안	✅ 스킬 점검 보고서 완료 · 비교 글 초안은 보류
—	화면 파리티 (계획에 없던 단계)	✅
—	라이브러리 대안 실측 (계획에 없던 단계)	✅ 8종 측정 완료
—	라이브러리 비용 분리 (계획에 없던 단계)	🔄 차트 축만 정리됨. query·url-params·motion 남음

---

성공 기준

목표 수치는 지금 정하지 않습니다. 1번 PR에서 React 쪽 기준선을 먼저 재고, 그 숫자를 본 뒤 목표를 정해 이 이슈에 추가합니다. 지금 지어낸 숫자보다 정직합니다.

측정 항목(양쪽 동일 조건, 프로덕션 빌드 기준):

• 글 상세 페이지 초기 JS gzip 크기 — 주 지표 → 273.2 KB → 64.4 KB (⚠️ query·url-params 오염 잔존)
• 홈 초기 JS gzip 크기 → 274.0 KB → 52.1 KB (⚠️ 같은 오염)
• /404/ 초기 JS gzip 크기 — 오염이 가장 적은 지표 → 212.7 KB → 49.6 KB (23.3%)
• 총 산출물 크기 → 96.5 MB → 64.0 MB
• LCP · hydration 시간(로컬 측정, 반복 후 중앙값) → 미측정
• 빌드 시간 → 미측정(같은 조건의 Svelte 수치 없음)

완료 기준

• apps/blog/web-svelte가 pnpm build --filter=@blog/web-svelte로 정적 export 된다
• 공개 6개 + Admin 4개 라우트가 전부 서고, URL 계약(후행 슬래시 포함)이 React 판과 같다
• apps/blog/posts의 글 70편이 원고 수정 없이 그대로 렌더된다
• 커스텀 태그가 전부 동작하고, React 판과 같은 시맨틱 구조를 낸다 — 13종(원고가 실제로 쓰는 전부). code-tabs는 상호작용이 필요해 제외
• Mermaid · 구문 강조 · 이미지 줌이 글 상세에서만 지연 로드된다 — 다만 mermaid 글 5편에서 본문을 지우고 있었습니다(feat(blog-web-svelte): 읽기 경로의 클라이언트 조각과 check-bundle의 initial 스코프 #401~Claude/react svelte solid migration dkj247 #412, #413에서 수정)
• 조회수 · Giscus · 검색 · 테마가 로컬 환경에서 동작한다 — 페이지 전환 애니메이션은 미구현
• blog-content check-seo가 수정 없이 통과한다
• check-bundle이 이 앱의 BUNDLE_GUARDS 선언으로 통과한다 — 규칙 12개
• pnpm lint --filter=@blog/web-svelte가 --max-warnings=0으로 통과하고 인라인 disable이 0건이다
• 레이어 경계 위반이 0건이다 — SvelteKit의 $lib/server 강제가 eslint-plugin-boundaries를 대신합니다(도구가 막으므로 빌드가 실패합니다)
• 색 hex 리터럴이 컴포넌트에 0건이다(전부 blog-preset 토큰 경유)
• 계약·회귀 테스트가 통과한다 — 116개 / 파일 15개
• 별도 Worker 프리뷰 URL로 배포되고 PR에 링크가 달린다
• turbo lint·check-types·test에 편입돼 PR CI가 두 앱을 함께 검사한다
• 기준선/비교 수치가 이 이슈에 기록된다
• 스킬 4종 사용성 점검 보고서 — 보고서. 규칙·문법은 중립, 경로·절차는 React 전제
• README.md·CLAUDE.md·AGENTS.md에 새 워크스페이스가 반영된다
• 비교 글 초안 — 보류(2026-09-13)
• apps/blog/web은 한 줄도 바뀌지 않는다 — 예외 조항대로 중립화 수정만 들어갔고(@blog/site-values·@blog/analytics·@blog/diagram 추출), React 앱 테스트 전량이 통과합니다

나중에 추가한 기준 (이번 실험이 가르쳐 준 것)

• 페이지별 화면 대조 — 문서 높이·링크 수·버튼 수·DOM 기하를 양쪽에서 재서 일치를 확인한다. 「계약이 통과한다」로는 화면이 같은지 알 수 없다
• 시각 계약 대조를 도구로 남긴다 — blog-content check-parity. 클래스 어휘·헤딩·링크·요소 수·아이콘 선언 다섯 축을 HTML만 읽고 대조한다
• 번들 수치에 유효성 전제를 단다 — "두 산출물의 기능이 같을 때만 비교 가능"
• 라이브러리를 손으로 대체하기 전에 대안을 찾고, 찾은 결과를 기록한다. 없어서 만든 것과 안 찾아보고 만든 것은 결과물이 같아 구분되지 않는다 — 소급해서 8종을 실측하고 위 표에 남겼습니다. 앞으로는 만들기 전에 합니다
• 번들 비교는 라이브러리 선택을 통제한 뒤에 한다. 차트 축은 정리됐으나(대안이 더 나쁨을 실측 + 기능 동등화) query·url-params·motion 셋이 남았습니다
• 디자인 결정을 어느 쪽에 맞출지 미리 못 박는다 — 글꼴·토큰 색·애니메이션 곡선처럼 두 판이 갈릴 수 있는 축
• 게이트가 보지 않는 화면을 찾아 덮는다. /admin이 로그인 게이트와 PARITY_PAGES 양쪽의 사각지대였습니다. 차트 좌표를 인라인 스냅샷으로 잠가(snapshot.test.ts) 회귀가 조용히 지나가지 않게 했습니다
• JS가 돈 뒤의 화면을 검사한다. 게이트는 전부 JS 실행 전 산출물만 봐서, mermaid 글의 본문 소실(fix(blog-web-svelte): mermaid 그림이 글 본문 전체를 대신하지 않게 한다 #413)이 #401부터 #412까지 통과했습니다. 한 번은 손으로 대조했지만(글 44편) 반복 가능한 검사는 아직 없습니다

테스트 시나리오

계약·회귀 테스트만 이식합니다. 유닛 테스트 전량 이식은 하지 않습니다.

이 방침이 시각 계약 테스트를 함께 제외했습니다. 위 「나중에 추가한 기준」이 그 수정입니다.

• 글 70편 스모크 — 전부 200으로 서고 빌드가 통과한다
• 커스텀 태그 각각의 렌더 계약 — 필수 속성, 자식 구조, 누락 속성 시 동작
• check-seo 규칙 전부 통과 — h1 1개, description 중복·길이, <title> 60자, canonical 자기참조, og 태그, img alt, 산출물↔발행 글 정합성
• URL 계약 — 후행 슬래시, .이 든 slug(turborepo-next.js-docker·vue-3.0) 처리
• 공개 판정 회귀 — draft·scheduled 글이 프로덕션 빌드에서 빠지고 dev에서는 배지와 함께 보인다
• 지연 로드 경계 — Mermaid·구문 강조·차트 곡선 계산이 글 상세 외 라우트 청크에 없다
• 테마 — pre-paint 스크립트가 FOUC 없이 html[data-theme]를 세팅한다
• 조회수 — 6시간 쿠키 쿨다운이 지켜지고 두 탭 레이스에서 중복 카운트가 없다
• 차트 기하 — 좌표 문자열 스냅샷(720·1152 두 폭, 스파크라인 80×32·96×24). /admin이 시각 검증 경로가 없으므로 계산을 대신 잠근다
• 비회귀: apps/blog/web의 기존 테스트 전량이 계속 통과한다. pnpm build --filter=@blog/web이 계속 통과한다

범위 밖

• apps/blog/web 교체·제거 — 최종 배포 전환은 비교 결과를 보고 별도로 판단합니다. 이 이슈는 비교 재료를 만드는 데까지입니다
• 프로덕션 Supabase 연결 — 로컬 인스턴스만. 배포된 프리뷰는 동적 기능이 빈 상태입니다
• 커스텀 도메인 · 색인 허용 — 프리뷰 URL만 냅니다. 중복 콘텐츠 판단은 최종 배포 결정 때 함께 봅니다
• Solid 구현 — Svelte 하나로 갑니다
• 기능 플래그 — 별도 워크스페이스라 필요 없습니다
• 스킬 파일 자체 수정 — 점검 보고서까지만. 스킬을 고치는 것은 보고서를 보고 별도로 판단합니다
• apps/react·apps/next.js 등 다른 실험 앱 — 손대지 않습니다
• 두 앱의 admin 라우트 구조 정렬 — React는 /admin이 글 관리 화면(509줄)이고 대시보드가 /admin/analytics인데, Svelte는 /admin이 대시보드입니다. 그래서 React TopPostsTable의 행별 스파크라인에 대응하는 자리가 Svelte에 없습니다. 컴포넌트 문제가 아니라 구조 문제라 별도 판단입니다

[Han5991]

기준선 측정 (2026-09-07) — PR 1 완료

PR #393. blog-content measure-bundle로 같은 도구·같은 방식으로 잰 gzip 첫 로드 전송량(HTML + CSS + JS, zlib.gzipSync).

React 판 (apps/blog/web) — 100 페이지

그룹	페이지	중앙값	최대	대표 페이지
/admin/	49	447.4 KB	494.3 KB	/admin/analytics/design-system-start/
/posts/	45	339.7 KB	407.3 KB	/posts/reduce-server-dependency-clean-architecture/
/	1	313.5 KB	313.5 KB	/
/about/	1	313.0 KB	313.0 KB	/about/
/series/	1	255.1 KB	255.1 KB	/series/
/privacy/	1	249.9 KB	249.9 KB	/privacy/

대표 페이지 분해:

페이지	HTML	CSS	JS	JS 파일
/posts/reduce-server-dependency-clean-architecture/	35.6 KB	30.9 KB	273.2 KB	13
/	9.3 KB	30.3 KB	274.0 KB	13
/admin/analytics/design-system-start/	5.5 KB	30.3 KB	411.5 KB	16
/series/	12.1 KB	30.3 KB	212.7 KB	9

• 산출물 전체: 파일 921개 / 96.5 MB (raw)
• 빌드 시간: 49초 (prebuild → next build → check-seo → check-bundle)

Svelte 판 — 뼈대 1 페이지

페이지	HTML	CSS	JS	JS 파일	합계
/	0.9 KB	6.0 KB	32.3 KB	7	39.2 KB

이 39.2 KB는 바닥값이다 — 프레임워크 런타임 + 라우터 + Panda preflight. 화면도 마크다운 렌더도 런타임 기능도 아직 없으므로 313.5 KB와 나란히 읽으면 안 된다. 비교는 같은 화면이 양쪽에 서는 PR 3 이후에 성립한다.

주 지표는 글 상세의 JS 273.2 KB다. 목표 수치는 같은 화면이 선 뒤에 정하고 여기에 추가한다.

---

가정 대조 — 첫 결과

이슈 본문의 "프레임워크 중립성" 표를 실측으로 갱신한다.

자산	가정	실제
@blog/content 로더·설정	중립	✅ SvelteKit 앱에서 그대로 로드된다
Panda blog-preset	중립	✅ css()가 Svelte에서 그대로 돈다 (c_ink.950 클래스 생성 확인)
check-bundle	반쯤 중립	❌ 깨졌다. collectChunkRefs가 /_next/static/chunks/를 정규식에 박아 두어 SvelteKit 산출물에서 청크를 하나도 못 찾는다. "누수 0건"이 아니라 검사 무력화 — 일반화는 PR 4
check-seo	중립	미검증 — 라우트가 서는 PR 2에서

측정기가 먼저 거짓말을 했다

첫 판이 Svelte 산출물에서 0 KB를 보고했다. SvelteKit이 기본값으로 ./_app/… 상대 경로를 내는데 수집기가 /로 시작하는 참조만 셌기 때문이다. 정확히 "Svelte가 공짜로 보이는" 종류의 버그이고, 이 실험 전체가 이런 실패에 취약하다는 신호다. 양쪽을 고치고(사이트는 paths.relative: false, 측정기는 URL 해석 + missing 보고) 회귀 테스트를 붙였다.

새로 열린 결정

content.values.mts 중복. 뼈대는 React 판 값 모듈의 부분 사본을 들고 있다. 사이트 정체성이 두 곳에 살아 있어 한쪽만 고치면 두 산출물이 조용히 갈라진다 — 이 저장소가 published 필드 이중화에서 이미 겪은 실패 모양이다. 해소책 셋이 전부 apps/blog/web이나 워크스페이스 구조를 건드려서 PR 1의 완료 기준("React 앱은 한 줄도 바뀌지 않는다")과 충돌했다. PR 2에서 셋 중 하나를 고른다:

1. 공유 패키지 @blog/site-values로 추출 (React 앱의 import 한 줄이 바뀐다)
2. 상대 경로 교차 import (../web/content.values.mts — 워크스페이스 캡슐화를 깬다)
3. 계약 테스트로 두 파일을 글자 단위 대조 (중복은 남고 드리프트만 막는다)

---

Generated by Claude Code

[Han5991]

정정 — 커스텀 태그는 15종이 아니라 13종이다

이슈 본문과 PR #393·#394·#395 에 "15종"으로 적었다. PostBody.tsx의 컴포넌트 맵을 세면 13종이다:

callout · code-tabs · file-tree · figure · dialogue · msg · metrics · metric · timeline · step · diagram · diagram-node · diagram-edge

PR #396 이 9종을 옮겼고, 남은 4종은 code-tabs(상호작용) + diagram 계열 3종(배치 계산)이다.

---

원고 전수 조사 — 범위 판단이 바뀌는 사실

70편에서 커스텀 태그가 실제로 쓰인 횟수:

태그	사용
diagram-node	11
diagram-edge	5
diagram · file-tree	3
figure	2
callout · code-tabs · dialogue · msg · metrics · metric · timeline · step	0

8종은 한 번도 쓰이지 않았다. 리뉴얼 때 만든 시그니처 컴포넌트(dialogue·metrics·timeline)가 통째로 여기 들어간다.

두 가지 함의가 있다.

1. 검증 방법이 갈린다. 쓰이지 않는 8종은 실제 글로 동등성을 확인할 수 없어 픽스처 테스트로 계약을 잠갔다. 쓰이는 태그는 두 산출물을 문자 단위로 대조한다(file-tree는 지금 동일함을 확인했다).
2. 남은 4종이 실제로 가장 중요하다. diagram 계열이 19회로 압도적이다. PR 5의 무게가 여기 있다.

---

가정 대조 — PR 4 기준 갱신

자산	상태
@blog/content 로더·설정	✅ 중립
Panda blog-preset	✅ 중립. strictTokens가 지어낸 토큰 넷을 컴파일에서 막았다(success.*는 없다 — moss.600/moss.700)
check-seo	✅ 중립 확인 — SvelteKit 산출물 49페이지를 수정 없이 통과
check-bundle	❌ /_next/ 하드코딩 — PR 5
경로 앵커(root: import.meta.url)	❌ 번들러 의존이었다. Vite가 설정을 서버 번들로 옮기면 앵커가 출력 파일을 가리킨다
catch-all 파라미터	❌ 라우터마다 모양이 다르다. [...slug]가 후행 슬래시를 삼킨다
배럴의 클라이언트 안전성	❌ Next 전용 optimizePackageImports가 막고 있었다
react-markdown 컴포넌트 맵	❌ 등가물이 없다. SvelteKit은 load 데이터를 HTML에 직렬화하므로 HAST를 화면에 넘기면 문서가 부푼다 — 빌드 타임 HAST 변환으로 우회

---

측정 — PR 4 기준

	HTML	CSS	JS	합계
React 글 상세	35.6 KB	30.9 KB	273.2 KB	339.7 KB
Svelte 글 상세	9.4 KB	7.5 KB	38.8 KB	55.6 KB

여전히 같은 조건이 아니다(Svelte 쪽에 코드 블록 테마·Mermaid·이미지 줌·런타임 기능·Admin이 없다). 다만 태그 9종을 더하는 동안 JS가 +0.1 KB였다는 것은 의미가 있다 — 변환이 빌드 타임에 끝나기 때문이다.

---

Generated by Claude Code

[Han5991]

진행 현황 — UI 패리티 감사 (2026-09-11)

두 빌드를 같은 뷰포트로 띄워 화면을 대조했습니다. 원장에 없던 문제가 나왔습니다.

원장의 빈 곳

완료 기준 18개가 전부 기계 검사이거나 문서 산출물입니다. "화면이 같다"는 항목이 하나도 없습니다. 시각에 가장 가까운 색 hex 리터럴 0건은 부정 검사라, 색을 하드코딩하지 않았다는 것만 증명하고 맞는 토큰을 골랐는지는 말하지 않습니다.

스택 계획 2번(라우팅 + 정적 페이지 — 레일 그리드, 레이아웃)의 완료 신호가 check-seo가 통과한다였습니다. check-seo는 h1 개수·canonical·og를 봅니다 — 자리만 잡은 화면도 통과합니다. 실제로 통과했고 그 위에 PR이 쌓였습니다. 3번(마크다운)의 React 판과 같은 **구조**를 낸다도 같은 모양입니다(구조지 모양이 아님).

그리고 계약·회귀 테스트만 이식합니다가 하필 화면 계약을 담은 테스트를 잘랐습니다. Rail.test.tsx에 이 테스트가 있습니다.

test('기본 폭은 text다', () => {
  const { inner } = shell(<Rail>본문</Rail>);
  expect(hasAll(inner, railColumn({ width: 'text' }))).toBe(true);
});

이식했다면 아래 1번 버그가 첫날 빨간불이었습니다.

찾은 버그

	증상
Rail 기본 폭 역전	React text(680px) ↔ Svelte wide(1200px). <Rail>을 그냥 쓴 화면이 전부 두 배 폭으로 퍼졌다
웹폰트 미로딩	pretendard/…/pretendardvariable-dynamic-subset.css import가 없어 폰트 요청 0건. 사이트 전체가 시스템 폴백으로 렌더. 같은 문자열 폭 244.3px ↔ 281px
인라인 코드 무스타일	codeBlocks가 <pre><code>만 봐서 문단 안 <code>에 클래스가 0개
브랜드 표기	헤더에 Frontend Lab. React는 로고만 sangwook.dev로 두는 것이 의도
내비 활성 표시	없음. 라벨도 소개 ↔ About
테마 토글	☾ 글자. 값을 읽기 전까지 자리가 비어 첫 페인트에 빈 칸

화면별 상태

화면	상태
헤더·푸터	✅ 좌표·브랜드·토글 일치
/	✅ scrollHeight 1274 ↔ 1275px
/posts/[...slug]	🟡 헤더·히어로·본문·차례·이전다음 완료. 복사 버튼·읽기 진행바·맨 위로·모바일 차례·공유 버튼 남음
/privacy	✅ 1560px / 링크 13개 일치
/about	✅ 1391px / 링크 22개 일치
/series	✅ 2606px / 링크 51개 일치
/posts 아카이브	❌ 필터 사이드바·카드 그리드 없음. 버튼 31개 ↔ 2개
/admin	❌ 미확인(로그인 필요)

기준선 — 패리티 이전이라 비교 결과로 쓸 수 없습니다

첫 로드 gzip(HTML+CSS+JS), 문서가 직접 가리킨 것만.

그룹	React	Svelte(현재)
/	313.6 KB	81.3 KB
/posts/ 중앙값	339.7 KB	104.5 KB
/series/	255.1 KB	81.4 KB
/about/	313.0 KB	80.7 KB
/privacy/	249.9 KB	79.3 KB
/admin/ 중앙값	447.9 KB	137.6 KB

이 비율을 결론으로 쓰면 안 됩니다. Svelte 쪽이 아직 덜 그립니다. 패리티 작업을 시작한 뒤 이미 홈이 66.0 → 81.3 KB로 올랐습니다(+15.3 KB). CSS는 Panda가 쓰인 선언만 내므로 컴포넌트가 늘수록 React 쪽(30.3 KB)으로 수렴합니다.

분해에서 확실히 말할 수 있는 것은 하나입니다 — React /404/의 첫 로드 JS 212.7 KB 중 69.7 KB가 react-dom + 스케줄러로 확인됐고 Svelte에는 대응물이 없습니다. 나머지 청크 8개는 마커가 안 잡혀 grep으로는 더 못 가릅니다(제대로 하려면 bundle analyzer / rollup-plugin-visualizer).

한편 Svelte /404/의 JS 47.9 KB는 청크 18개 전부가 앱 코드이고 식별되는 서드파티가 0개입니다. 뒤집어 보면 Svelte의 앱 코드(47.9 KB)가 React의 가장 큰 비런타임 청크(41.7 KB)보다 큽니다 — 이득은 "앱 코드가 작다"가 아니라 **"그 밑에 깔리는 런타임 층이 없다"**입니다.

원장에 더할 것 (제안)

완료 기준에 다음을 추가하는 것이 맞다고 봅니다.

• 기준 화면 목록을 두 빌드 스크린샷으로 대조해 불일치 0 — 화면 × (라이트·다크) × (1280·390)
• 화면 계약 테스트를 이식 대상에 포함(Rail.test.tsx부터)
• 번들 수치는 패리티 확인 뒤에만 비교 결과로 쓴다
• Rail 기본 폭 같은 디자인 결정은 주석이 아니라 공유 모듈·테스트로 잠근다

마지막 항목은 제가 Rail.svelte에 "React 판과 같은 계약이다"라고 적어 두고 값은 다르게 둔 데서 나왔습니다. 주석은 계약이 아닙니다.

---

Generated by Claude Code

[Han5991]

회고 (KPT)

스택 13개를 쌓고 화면 파리티까지 끝낸 시점의 회고입니다. 잘된 것보다 막힌 것에 무게를 뒀습니다.

---

Keep — 실제로 값을 한 것

게이트를 pnpm build 안에 넣은 것

check-seo·check-bundle이 빌드의 마지막 두 단계라 로컬·PR·배포가 같은 검사를 지납니다. 워크플로에 별도 스텝으로 두었다면 build에서 이미 실패해 도달하지 못하는 죽은 게이트가 됐을 것입니다. 이 판단은 그대로 두는 게 맞습니다.

규칙마다 양성 대조(requiredIn)를 필수로 만든 것

이게 이번 실험에서 가장 값을 한 설계입니다. check-bundle이 /_next/static/chunks/를 경로에 박고 있어서 SvelteKit 산출물에서 청크를 하나도 못 찾았는데, 음성 검사만 있었다면 규칙 9개 전부가 "누수 없음"으로 통과했을 것입니다. 양성 대조가 있어서 "검사가 무력화됐다"가 드러났습니다.

isCliEntry의 무음 no-op 사고에서 배운 fail-closed가 다른 자리에서 한 번 더 증명됐습니다.

레이어 경계 린트

SvelteKit 앱 11,093줄 중 3,053줄이 Svelte를 한 줄도 import하지 않습니다. 우연이 아니라 경계 규칙이 지킨 결과입니다.

층	줄 수	프레임워크를 아는 파일
lib/server (마크다운 파이프라인)	2,248	13개 중 0개
lib/shared	654	11개 중 0개
lib/domain + lib/platform	151	5개 중 0개

@blog/analytics가 2,560줄에 React import 0으로 떨어져 나온 것도 같은 이유입니다.

주석에 "왜"를 남긴 규율

이번에 코드를 다시 읽을 때 결정의 이유를 되짚을 필요가 없었습니다. preview_urls 기본값 함정, registerOnce의 refractor 중복 등록, code-tabs를 왜 뺐는지가 전부 주석에 있었습니다. 이게 없었다면 같은 함정을 다시 밟았을 것입니다.

값의 단일 출처

blog-preset 하나가 두 앱의 토큰을 대므로 생성된 원자 클래스가 공통 어휘가 됩니다. 그래서 "클래스 집합의 차집합 = 한쪽에만 있는 시각 결정"이라는 비교 축이 생겼습니다. 토큰 출처가 갈려 있었다면 이 축이 없습니다.

Supabase 로컬 한정

실험 앱이 운영 조회수를 오염시키는 경로가 구조적으로 없습니다. 배포된 프리뷰에서 조회수가 안 도는 것이 그 결정의 값입니다.

---

Problem — 막힌 것

완료 기준에 화면이 없었다

기준 18개 중 "화면이 같다"고 말하는 줄이 0개였습니다. 그 결과 12개 PR 동안 홈·글 상세·/posts·/series·/about·/privacy가 전부 자리만 잡은 화면인 채로 모든 게이트를 통과했습니다.

레이아웃 PR의 완료 신호가 check-seo였습니다. h1 개수를 세는 검사가 "이 페이지에 내용이 있는가"를 대신할 수 없습니다.

도구가 있는데 안 썼다

실행 환경에 Chromium이 있었는데 12개 PR 동안 한 번도 띄우지 않았습니다. "결과물을 보니 기존과 너무 다르다"는 지적을 받고서야 열었습니다. 기계가 세는 것이 전부 초록이면 확인이 끝났다고 여긴 것이 원인입니다.

측정이 세션 안에만 남았다

DOM 기하 대조, 토큰 색 대조, 렌더 폰트 조회를 전부 일회성 스크립트로 했습니다. 재현되지 않고 회귀도 못 잡습니다. 지금 check-parity로 모듈화하는 중입니다.

번들 수치를 유효성 전제 없이 발표했다

기능이 다른 두 산출물을 비교해 "CSS가 3배 작다"고 적었습니다. 파리티 후에 다시 재니 30.3 대 29.3으로 거의 같았습니다. 그 격차는 프레임워크가 아니라 기능 수였습니다. 틀린 결론이 이슈에 남을 뻔했습니다.

"계약·회귀 테스트만 이식" 방침의 부작용

이 방침이 하필 시각 계약을 담은 테스트를 정확히 제외했습니다. React 판 Rail.test.tsx에 test('기본 폭은 text다')가 있는데, 그걸 이식했다면 모든 페이지가 1200px로 퍼지는 버그는 없었습니다.

웹폰트를 두 번 빠뜨렸다

Pretendard와 JetBrains Mono를 각각 놓쳤습니다. 두 번째는 첫 번째를 고친 뒤에도 안 보였습니다 — 모노는 0.6em 고정폭이라 글자 상자가 픽셀 단위로 같아서 DOM 기하 대조를 통과했습니다. 크롬의 실제 렌더 폰트 조회로만 드러났습니다.

선언된 값과 실제 값을 구분하지 않고 말했다

코드 블록 글꼴을 "React는 Menlo, Svelte는 JetBrains Mono"라고 설명했는데, 그건 CSS에 선언된 스택이지 실제로 그려진 얼굴이 아니었습니다. 재측정하니 둘 다 시스템 모노였고, 진짜 문제는 다른 데(웹폰트 미탑재) 있었습니다.

스택 PR 13개는 리뷰가 불가능했다

브랜치 열세 개로 흩어져 있는데다 리뷰어가 Svelte를 모르는 상태였습니다. 원래 계획은 6단계였는데 13개가 됐습니다.

그 과정에서 "하나로 몰아 달라"를 확인 없이 12개 PR을 닫는 것으로 실행했습니다. 의도는 각 PR이 릴리즈 브랜치에 하나씩 머지되는 그림이었습니다.

GitHub 스택 기능의 제약을 모르고 시작했다

되돌리려 할 때야 알았습니다.

Cannot change the base branch because the pull request is part of a stack.

스택으로 등록된 PR은 base를 API로 바꿀 수 없습니다. 13개를 다시 열고 나서도 마찬가지였습니다.

대시보드를 갱신하지 않았다

이 이슈의 완료 기준이 12개 PR 동안 하나도 체크되지 않은 채 있었습니다. "이슈 대시보드 업데이트 하면서 하는 거지?"라는 질문에 "아니요"라고 답해야 했습니다.

---

Try — 다음에 할 것

1. check-parity 서브커맨드 (진행 중)

두 산출물을 HTML만 읽어 대조합니다. 브라우저를 안 쓰므로 CI에서 그대로 돕니다.

비교 축 다섯: 클래스 어휘 · 헤딩 순서 · <a> 링크 · 요소 수 · <head> 메타와 아이콘.

프로토타입이 이미 제 기하 대조가 놓친 둘을 잡았습니다.

무엇	React	Svelte
헤더	pos_sticky top_0 bkdp-blur_[12px]	보더만
아이콘 선언	5줄	favicon.ico 1줄
apple-touch-icon·android-chrome-*·site.webmanifest	있음	없음

2. boundaries/external로 중립성을 규칙으로

지금 쓰는 boundaries/element-types는 방향만 강제합니다. "이 층이 react를 import할 수 있는가"는 아무도 안 봅니다(boundaries/external 설정 0건).

그래서 중립성이 규칙이 아니라 결과였습니다. 누가 lib/shared에 svelte를 하나 import해도 lint는 통과합니다. 이 규칙을 걸면 "패키지로 뺄 수 있는가"를 grep이 아니라 CI가 답합니다.

3. 큰 재구현은 중립화를 먼저 하고 시작한다

이번엔 두 번째 앱을 지으면서 중립화를 해서, 무엇이 중립인지 매번 그 자리에서 발견했습니다. 앱이 하나일 때 grep으로 판정하고 패키지로 먼저 빼면 재발견이 없습니다.

4. 완료 기준에 "사람이 눈으로 확인할 것"을 항목으로 둔다

기계가 세는 항목만 모으면 그 목록이 완성돼도 화면은 비어 있을 수 있습니다. 이번이 그 증명입니다.

5. 스택 PR은 3~4개까지

13개는 리뷰 대상이 아니라 관리 대상이 됩니다. 쪼개기 어려우면 쪼개지 말고, 대신 읽는 순서와 결정이 든 파일을 본문에 적습니다.

6. 되돌리기 어려운 작업은 먼저 확인한다

PR 다수 닫기, 브랜치 구조 변경 같은 것. 이번에 12개를 닫았다가 되살렸습니다.

7. "선언된 값"과 "실제 값"을 구분해서 말한다

computed style은 선언이고, CSS.getPlatformFontsForNode가 실제입니다. 둘을 섞어 말하면 진단이 엉뚱한 데로 갑니다.

---

Generated by Claude Code

[Han5991]

⚠️ 번들 비교가 오염돼 있습니다 — 대시보드의 JS 수치를 신뢰하지 마세요

위 대시보드의 「JS 222 KB가 격차의 전부입니다」는 틀린 결론입니다. 제 실수라 기록해 둡니다.

무엇을 잘못했나

SvelteKit 판에서 React 라이브러리 넷을 손으로 만든 것으로 대체했습니다. 그러면서 Svelte 대안이 있는지 찾아보지 않았습니다. 지금 확인하니 넷 다 있습니다.

React 판	Svelte 대안	Svelte 5 지원
@tanstack/react-query	@tanstack/svelte-query 6.1.48	peer svelte: ^5.25.0
recharts	layerchart 2.5.0	peer svelte: ^5.0.0
nuqs	sveltekit-search-params 4.0.0	지원
motion	같은 패키지	루트 export가 프레임워크 중립

마지막 줄이 가장 나쁩니다. motion ^13.2.0은 이미 이 모노레포에 있고 motion/react가 아니라 루트 export는 프레임워크를 가리지 않습니다. 같은 패키지를 그대로 쓸 수 있었습니다.

왜 수치가 오염되나

측정하려던 것은 프레임워크 비용인데, 실제로 잰 것은 이것입니다.

React  + recharts + react-query + nuqs + motion
  대
Svelte + 손으로 만든 차트 428줄 + 스토어 69줄 + URL 함수 73줄 + 내장 transition

/admin/ 447.9 KB 대 142.8 KB의 격차에 라이브러리 선택이 섞여 있습니다. 얼마가 프레임워크고 얼마가 라이브러리인지 저는 모릅니다.

CSS에서 지적했던 것과 정확히 같은 오류입니다. 「기능이 다른 두 산출물의 크기 비교는 아무것도 말해 주지 않는다」를 적어 놓고 JS에서 같은 실수를 했습니다. 그리고 이쪽이 더 큽니다 — CSS는 기능 수 차이였지만 JS는 같은 기능을 다른 방식으로 구현한 차이입니다.

파리티 주장도 하나 깨집니다

motion의 스프링(damping: 25, stiffness: 200)을 svelte/transition의 fly 280ms로 바꿨습니다. 다른 움직임입니다. 그래 놓고 픽셀 파리티를 달성했다고 적었습니다. check-parity가 정지 상태의 마크업만 봐서 못 잡습니다.

React 쪽 상한선 (참고)

청크에서 라이브러리 마커를 찾아 재면 이렇습니다. 상한선입니다 — Turbopack이 청크 하나에 앱 코드와 라이브러리를 함께 넣으므로 "이 라이브러리가 N KB"가 아니라 "이 라이브러리가 들어 있는 청크의 합이 N KB"입니다.

페이지	초기 JS	라이브러리 마커가 있는 청크
/admin/analytics/…	410.6 KB	221.2 KB (54%)
/posts/ · /	273.0 KB	143.9 KB (53%)

가장 큰 단일 청크는 recharts + react-query가 함께 든 97.5 KB입니다.

어떻게 할 것인가

양쪽을 다 잽니다. SvelteKit 판에 같은 라이브러리를 넣어 빌드하고, 손으로 만든 판과의 차분으로 라이브러리 비용을 분리합니다. 그래야 프레임워크 비용이 남습니다.

측정이 끝나면 이 대시보드의 수치를 그 결과로 갈아 끼우겠습니다. 그때까지 위 JS 수치는 비교용으로 쓰지 마세요.

---

Generated by Claude Code

[Han5991]

라이브러리 비용 측정 — 1차 결과

오염을 걷어내려고 실제로 라이브러리를 넣어 재 봤습니다. 측정 전용 브랜치에서 하고 폐기했으므로 코드는 남아 있지 않습니다.

기준선은 현재 claude/svelte-13-home-parity의 빌드입니다(/admin/ 143.4 KB · /404/ 82.2 KB · / 87.2 KB).

@tanstack/svelte-query — 답이 나왔습니다

손으로 만든 69줄 스토어를 QueryClient.fetchQuery + removeQueries로 바꿨습니다. 공개 API는 그대로라 소비자 네 곳은 손대지 않았습니다.

페이지	손으로 만든 판	svelte-query 판	차이
/admin/	143.4 KB	150.2 KB	+6.8 KB
/404/ · / · /posts/	—	변화 없음	0

라이브러리를 썼어도 7 KB였습니다. /admin/의 React 대 Svelte 격차 305 KB 중 react-query 선택이 설명하는 몫은 그 정도입니다. 이 항목의 오염은 작습니다.

덤으로 하나 바로잡습니다. 앞서 「비-admin 페이지도 +0.6 KB」라고 읽었는데, 다시 재니 그건 svelte-query가 아니라 같은 PR의 파리티 수정(sticky 헤더·아이콘 선언·페이지 셸)이었습니다. 기준선을 옛 커밋의 수치로 잡아서 생긴 착각입니다.

layerchart — 숫자를 못 냈습니다

최소 사용(면적 차트 하나 + 축 둘)을 admin 페이지에 넣고 쟀습니다.

페이지	기준선	layerchart 프로브	차이
/admin/analytics/	143.4 KB	275.9 KB	+132.5 KB
공개 페이지 전부	82.2 KB	85.7 KB	+3.5 KB

이 수치를 라이브러리 비용으로 쓰면 안 됩니다. 제가 패키지 루트에서 임포트했는데(import { Chart, Area, Axis, Svg } from 'layerchart'), layerchart의 진입점이 export * from './components/index.js' 배럴이고 의존에 @dagrejs/dagre·d3-geo·d3-contour·d3-delaunay 같은 것이 줄줄이 달려 있습니다. 132 KB는 배럴 임포트의 트리셰이킹 실패가 만든 천장이지 제대로 포팅했을 때의 비용이 아닙니다.

@blog/content 배럴이 node:fs를 함께 열던 것과 같은 모양의 함정입니다. 이번엔 남의 패키지에서 겪었습니다.

공개 페이지가 +3.5 KB 오른 것도 원인을 특정하지 못했습니다. 마커를 훑으면 공개 청크에 layerchart·d3·LayerCake 문자열이 0바이트입니다(누수는 아닙니다). SvelteKit이 모든 라우트 청크 이름을 매니페스트로 싣는 성질 때문으로 보이지만 확인하지 않았습니다.

지금까지의 결론

항목	오염 규모	상태
react-query ↔ svelte-query	+6.8 KB	해결
nuqs ↔ sveltekit-search-params	미측정	작을 것으로 예상(73줄 대체)
motion	미측정	같은 패키지라 양쪽 동일하게 만들 수 있음
recharts ↔ 차트 라이브러리	불명	지배적 항목. 실제 포팅 없이는 답이 안 나옴

차트가 남은 전부입니다. /admin/ 격차 305 KB에서 react-query 7 KB를 빼도 298 KB가 남고, 그 대부분이 recharts와 프레임워크 중 어느 쪽인지 아직 모릅니다.

다음

차트는 프로브로 못 잽니다. 세 갈래가 있습니다.

1. 실제로 포팅한다 — AreaChart·BarChart·Sparkline 셋을 layerchart로 다시 써서 잰다. 정직하지만 작업량이 크고, 그 코드를 유지할지도 결정해야 한다
2. React 쪽에서 뺀다 — recharts를 제거한 React 빌드를 한 번 만들어 차분을 본다. 운영 앱을 건드리므로 측정 전용 브랜치에서만
3. 차트를 비교에서 제외한다 — /admin/을 주 지표에서 빼고 공개 페이지만 비교한다. 공개 페이지에는 차트가 없으므로 이 오염이 애초에 없다

3번이 가장 싸고 정직합니다. 원래 주 지표도 「글 상세 초기 JS」였고 거기엔 차트가 없습니다. 다만 「전체를 지어야 비교가 성립한다」는 원래 결정과는 어긋납니다.

---

Generated by Claude Code

[Han5991]

회고 보강 — 라이브러리 교체 비용은 왜 균일하지 않았나

앞선 KPT에는 "라이브러리 대응을 확인하지 않았다"만 적혀 있다. 정작 쓸모 있는 것은 왜 어떤 건 공짜였고 어떤 건 비쌌는가인데, 그걸 재고 나서야 축이 잡혔다.

이번 포팅에서 건드린 라이브러리 4개

라이브러리	실제로 벌어진 일	비용
motion	패키지가 그대로 간다 — 프레임워크 중립이고 이미 모노레포에 있었다	0 (못 보고 직접 만들었다)
@tanstack/react-query	같은 팀의 svelte-query로 1:1. 코어가 같다	+6.8 KB
nuqs	대응이 없지만 옮길 것이 없었다 — URL 계약은 순수 함수 73줄	73줄 + 테스트 7개
recharts	대응이 없고, 있는 것이 더 나쁘다	이것만 진짜 문제

4개 중 1개만 어려웠고, 그 1개가 어려운 이유는 "Svelte 버전이 없어서"가 아니었다.

축은 "대응 패키지가 있나"가 아니라 "렌더 트리에 얼마나 붙어 있나"다

recharts를 쪼개면 셋으로 갈린다.

조각	프레임워크 종속?	이 화면의 비용
계산 (d3-shape·d3-scale)	무관	2.3 KB — 그대로 가져옴
DOM 측정 (ResponsiveContainer)	무관 (브라우저 API)	0 KB — bind:clientWidth
컴포넌트 조립 (<XAxis/>·<Area/>)	React 전용	나머지 전부

셋째가 가치는 가장 작고 번들은 가장 크다. React 판에서 recharts 마커를 가진 청크 셋의 합이 gzip 129 KB인데, 이 대시보드가 그중 실제로 쓰는 계산은 2.3 KB다.

같은 분해를 nuqs에 대면 셋째가 거의 0이라 73줄로 끝났고, motion은 셋째가 아예 없어서 패키지가 그대로 갔다. 분해가 곧 비용 예측이다.

대안 라이브러리는 실제로 다 재 봤다 (Vite + Svelte 5.57 프로브, gzip, Svelte 런타임 16.1 KB 제외)

후보	추가	렌더	Panda 토큰
ResizeObserver + d3-shape	+2.3 KB	SVG	✅
d3-shape + d3-scale	+10.6 KB	SVG	✅
layercake 8.4	+20.9 KB	SVG (마크는 직접)	✅
uPlot 1.x	+22.5 KB	Canvas	❌
chart.js (tree-shaken)	+58.4 KB	Canvas	❌
recharts (React 판 현재)	~129 KB	SVG	✅
@observablehq/plot	+130.0 KB	SVG	△
layerchart 2.5 (/svg 서브패스)	+148 KB	SVG	❌ Tailwind

두 가지가 뒤집혔다.

• layerchart는 배럴 탓이 아니었다. 이전에 +132.5 KB가 나왔을 때 export * 트리셰이킹 실패로 보고 넘겼는데, layerchart/svg 서브패스로 좁혀도 오히려 더 크다(148 KB, 정적 클로저 32청크). recharts보다 무겁다. 게다가 스타일이 @layerstack/tailwind에 묶여 있어 Panda strictTokens 위에 얹을 수 없다.
• layercake가 유일하게 진지한 대안이었다. 컨테이너 폭을 재서 스케일을 주되 마크는 직접 그리게 둔다 — 지금 구조를 유지한 채 빠진 것을 정확히 메운다. 채택하지 않은 이유는 geometry.ts가 이미 그 계산을 테스트까지 붙여 갖고 있어서, 20.9 KB로 되사는 것이 실질적으로 폭 측정 하나뿐이기 때문이다.

Canvas 계열(uPlot·Chart.js)은 크기와 무관하게 탈락이다. 색을 css()로 못 주니 CSS 변수를 읽어 주입하고 테마 전환마다 다시 그려야 하는데, 이 저장소는 다이어그램 SVG까지 전부 토큰에 연결하는 규칙이다. check-seo·check-bundle도 canvas 내용은 못 본다.

손으로 만든 것의 유지보수 비용은 줄 수가 아니었다

차트 코드 428줄을 쪼개면:

• geometry.ts 101줄 (순수 함수 6개 + 테스트) — 여기서는 버그가 안 났다
• 마크업 250줄 — 여기도 안 났다
• 렌더링 환경 대응 0줄 — 여기서 났다

AreaChart가 720 폭 viewBox를 preserveAspectRatio="none"으로 늘리고 있었다. x만 약 1.5배 스케일되고 y는 1배라 SVG 안의 모든 것이 가로로 늘어났다 — 축 라벨 글자가 뭉개지고 커서 점(<circle r="4">)이 타원이 됐다. 정확히 ResponsiveContainer가 막아 주던 것이다.

교훈은 줄 수가 아니라 어느 축이 테스트에서 새는가다. 순수 함수로 떨어지는 것(좌표·눈금·솎아내기)은 테스트가 지켰고, 브라우저에서만 드러나는 것(실제 폭, 곡선 모양, 라벨 겹침)은 직접 만들면 그 축이 구조적으로 빈다. 라이브러리가 파는 것의 상당 부분이 사실 이쪽이다.

여기에 이 저장소만의 사각이 겹쳤다 — /admin은 로그인 게이트 뒤라 프리뷰에서 안 열리고, check-parity의 PARITY_PAGES 5개에도 없다. 두 검증 장치 어느 쪽도 안 보는 화면이다.

이 구조가 이미 하던 일과 맞물리는 지점

측정해 보니 Svelte 앱 11,093줄 중 3,053줄이 프레임워크 import가 0이다(lib/server 2,248 + lib/shared 654 + lib/domain·platform 151). boundaries 린트가 강제한 결과고, 그 3,053줄은 다음 프레임워크로 그대로 간다.

라이브러리에도 같은 자를 댄다. @blog/diagram이 선례다 — 좌표 계산기가 프레임워크를 모르니 같은 원고가 두 사이트에서 픽셀 단위로 같은 그림이 된다. 다시 쓴 것은 그리는 일뿐이다.

그래서 라이브러리 교체는 피할 수 없지만 미리 낼 수는 있다. 포팅할 때가 아니라 처음 쓸 때, 라이브러리의 가치를 (계산 | 렌더)로 갈라 계산 쪽을 자기 코드로 빼두는 것이다. geometry.ts·archiveParams.ts·tocRail.ts가 전부 그렇게 나왔는데, 전부 포팅 중에 나왔다. React 판에는 그 분리가 없어서 recharts를 뺄 때 무엇을 잃는지 세는 데만 시간이 걸렸다.

한계도 분명하다. 이 방법은 라이브러리 가치의 대부분이 계산일 때만 통한다. Giscus·Supabase Auth처럼 가치가 전부 "외부 시스템과의 프로토콜"인 것, 가상 스크롤·드래그처럼 전부 DOM 상호작용인 것에는 안 통한다. 후자는 다시 쓰는 수밖에 없다.

조치

• preserveAspectRatio="none" 제거, viewBox 폭을 bind:clientWidth가 잰 실제 폭으로 (1152px·372px 두 폭에서 렌더 확인 — viewBox가 렌더 폭과 같고 커서 점 bbox 8×8 정원)
• 곡선을 d3-shape의 curveMonotoneX로 — Recharts type="monotone"과 같은 함수. 스파크라인은 React 판이 <polyline>이라 직선 유지
• 라벨 밀도를 폭에서 유도(1152px에서 6개 → 10개), 마지막 라벨 오른쪽 정렬(09/30이 09/3으로 잘리던 것)
• 번들 규칙 추가 — curveMonotoneX가 어느 페이지 첫 로드에도 오지 않는지(차트는 AdminGuard 뒤다). React 판 recharts 규칙에 대응하는 것이 그동안 없었다
• 테스트 3개 추가 — 곡선/직선 구분, 폭이 계산의 입력임, 한 점짜리 계열의 NaN

남는 것

• /admin 시각 검증 경로가 없다. 이 결함이 오래 안 보인 근본 원인이다. check-parity는 로그인 게이트를 못 넘으므로, 차트 SVG의 d 문자열을 스냅샷으로 잠그는 쪽이 현실적이다(geometry.test.ts가 하는 일의 확장)
• Sparkline은 아직 안 맞는다. React 판은 min→max로 스케일하고((v-min)/range) 이 앱은 0→max다(scaleMax). 크기도 100×24 대 96×28이다. 같은 데이터에서 선 모양이 다르게 나온다 — 이번 커밋 범위 밖이라 남겨 둔다
• /admin/ 번들 비교는 이제 다시 잴 수 있다. 이전 305 KB 격차는 반응형 사이징과 곡선 보간이 빠진 상태의 값이라 비교 가능한 숫자가 아니었다. 이번 변경의 실측 증가분은 첫 로드 기준 0(공개 페이지 변화 없음, 차트는 지연 로드)

---

Generated by Claude Code

[Han5991]

저작 스킬 4종 중립성 점검 보고서

배경의 넷째 질문 —「이 저장소의 저작 스킬이 React를 전제하고 있는가」— 에 대한 답입니다. 완료 기준의 스킬 4종 사용성 점검 보고서 항목입니다.

범위는 보고서까지입니다. 스킬 파일은 한 줄도 고치지 않았습니다(원장 「범위 밖」 조항).

방법

1. 정적 감사 — 4종 SKILL.md 전체(1,131줄)에서 React계 어휘를 훑고 각 건을 네 갈래로 분류
2. 실사용 1건 — blog-diagrams의 「새 다이어그램 등록」 절차를 실제로 따라가서 두 앱에서 무엇이 갈리는지 측정. 작업 트리에서만 하고 되돌렸습니다

2단계를 한 건으로 좁힌 이유는 실행할 절차가 있는 스킬이 그것 하나이기 때문입니다. tech-blog-writer는 산문 코칭이라 실행할 게 없고, blog-design-system의 토큰 지침은 Panda 프리셋이 공유라 그대로 통하며, blog-components의 13종 렌더 계약은 이미 계약 테스트와 check-parity가 덮고 있습니다.

---

요약

스킬	줄 수	React 어휘	판정
tech-blog-writer	410	2	중립
blog-design-system	160	2	거의 중립 — 경로 참조뿐
blog-components	283	3	문법 중립 / 메커니즘 서술이 한쪽만 참
blog-diagrams	278	9	절차가 깨져 있음 — 두 가지 이유로

패턴이 하나입니다: 규칙과 문법은 중립인데 경로와 절차가 아닙니다. 스킬의 "무엇을·왜"는 프레임워크를 모르고, "어디에·어떻게"만 React입니다. 라이브러리 비용을 (계산 | DOM 측정 | 컴포넌트 조립)으로 쪼갠 것과 같은 축입니다.

---

분류별 상세

중립 — 고칠 것 없음

tech-blog-writer (2건). 둘 다 스킬이 React를 전제하는 게 아니라 글 내용의 예시 문자열입니다.

305: - [ ] 버전 호환성 명시했는가? (React 18+, Node.js 20+ 등)
358: - 변경 이력 관리: "2024.08 수정: React 19 호환성 추가"

구조·톤·금지 어휘 표 전체가 프레임워크를 모릅니다.

React 명시 — 경로만 어긋남 (3건)

규칙 자체는 중립인데 가리키는 파일이 React 앱 것입니다. 읽는 사람이 SvelteKit 판에서 작업 중이면 그 파일이 없습니다.

위치	내용	대응물
blog-design-system:104	src/components/Rail.tsx가 레일의 단일 출처	Rail.svelte
blog-design-system:157	codeMeta.test.tsx가 대조군을 고정	Svelte는 codeBlock 테스트
blog-components:94	컴포넌트 매핑은 apps/blog/web/src/components/diagram/registry.ts	Svelte는 lib/server/markdown/diagram.ts

React 암묵 — 설명이 한쪽에서만 참 (1건)

blog-components:8-9

HTML 태그를 그대로 쓰면 React 컴포넌트로 치환된다.
MDX가 아니라 react-markdown + rehype-raw다.

저작 문법은 두 앱에서 같습니다 — 글 쓰는 데 지장이 없습니다. 그런데 "왜 되는가"의 설명이 SvelteKit 판에서 거짓입니다. 거기는 런타임 컴포넌트 맵이 아니라 빌드 타임 HAST 변환입니다. 문법은 맞고 메커니즘만 틀린 종류라, 이 문장을 근거로 뭔가 추론하면(예: "런타임이니 props를 동적으로 넘길 수 있겠다") 틀립니다.

절차가 깨져 있음 — blog-diagrams §5

두 가지가 독립적으로 틀렸습니다.

(a) 2단계가 존재하지 않는 배열을 가리킨다

스킬 226~228줄:

2. 앱 루트 apps/blog/web/content.values.mts 의 DIAGRAM_NAMES 에 이름 한 줄을 넣는다

그 파일에 DIAGRAM_NAMES 배열이 없습니다. 확인:

$ grep -n "DIAGRAM_NAMES" apps/blog/web/content.values.mts
  (없음)
$ grep -n "site-values" apps/blog/web/content.values.mts
20: export * from '@blog/site-values';

정의는 packages/@blog/site-values/src/index.ts:134 로 옮겨졌습니다. 이 스택(#394)이 옮긴 것입니다.

더 흥미로운 건 스킬 232~235줄이 그 이동을 반대하는 근거를 적어 두고 있다는 점입니다:

목록을 패키지가 아니라 앱이 소유하는 이유는 그 반대다 — 어떤 그림이 있는지는 사이트마다 다르고, 패키지에 기본값을 두면 그 값이 곧 특정 사이트의 하드코딩이다.

이 실험이 그 결정을 뒤집었는데 스킬은 아직 옛 근거를 들고 있습니다. 지금 @blog/site-values는 "패키지의 기본값"이 아니라 "이 사이트의 값을 담은 패키지"라 원래 우려와 상황이 다릅니다만, 어느 쪽이든 스킬과 코드가 어긋나 있습니다.

(b) 타입 가드가 한쪽에만 있다 — 실측

스킬 231줄의 핵심 안전 장치:

레지스트리 타입이 Record<DiagramName, …> 이라 2·3 중 하나만 하면 컴파일이 막는다.

실제로 해봤습니다. 공유 목록에 이름 하나(skill-audit-probe)를 더하고 구현은 어느 쪽에도 만들지 않은 채 양쪽 타입 검사를 돌렸습니다.

앱	결과
React	❌ 컴파일 에러 — registry.ts(33,14): error TS2741: Property '"skill-audit-probe"' is missing in type … but required in type 'Record<"deploy-pipeline" | "skill-audit-probe", ComponentType<NamedDiagramProps>>'
SvelteKit	✅ 1,125파일 0 에러

스킬이 약속한 안전 장치는 React에만 있습니다.

SvelteKit 판에는 이름→컴포넌트 레지스트리가 없고, PostHero.svelte가 {#if name === 'deploy-pipeline'}{:else if thumbnailUrl} 분기로 직접 처리합니다. 그래서 등록됐지만 구현되지 않은 이름은:

1. lint:posts의 unknown-hero-diagram을 통과합니다(목록에 있으니까)
2. check-types를 통과합니다
3. 렌더 시 조용히 썸네일로 폴백합니다

즉 절차를 그대로 따르면 그림이 한 사이트에만 생기고, 어느 게이트도 그걸 말해 주지 않습니다.

아이러니한 건 좌표 계산은 이미 @blog/diagram으로 빼서 중립이고 두 앱이 같은 좌표를 공유한다는 점입니다. 「같은 원고가 두 사이트에서 픽셀 단위로 같은 그림이 된다」가 성립하는데, 그 그림을 새로 만드는 절차만 한쪽을 모릅니다.

---

부수 발견 — 코드 주석도 같은 병에 걸려 있다

스킬을 검증하다 PostHero.svelte(26~28줄)에서 없는 보장을 주장하는 주석을 찾았습니다.

여기서 좁히면 아래 분기가 등록된 이름만 다룬다는 것이 타입으로 보장된다 — 새 이름을 목록에 더하고 분기를 빠뜨리면 never 분기에서 걸린다.

위 실험이 정확히 그 상황입니다(이름 추가 + 분기 없음). 0 에러였습니다. {#if}{:else if} 체인에는 exhaustiveness 검사가 없고 never 분기도 없습니다. 앞쪽 절반(DiagramName으로 좁히면 분기가 등록된 이름만 다룬다)은 참이지만, 뒤쪽 절반은 거짓입니다.

스킬의 (b)와 정확히 같은 병입니다 — 문서가 약속한 컴파일 타임 보장이 실제로는 한쪽에만 있는 것. 스킬에서 찾은 문제가 코드 주석에도 있었습니다.

---

권고 (결정은 별도)

「범위 밖」 조항대로 고치지 않았습니다. 선택지는 셋으로 갈리고, 건마다 답이 다를 수 있습니다.

선택지	어디에 맞나
경로를 중립으로 고친다	「React 명시」 3건. Rail.tsx → "레일 컴포넌트" 식으로 앱 중립 표현 + 두 경로 병기
두 앱 절차를 모두 적는다	blog-diagrams §5. 다만 스킬이 두 배로 길어지고, 앱이 셋이 되면 또 늘어납니다
앱별 절차를 스킬에서 빼고 앱 README로 내린다	같은 곳. 스킬은 "무엇을·왜"(문법·색 2색 규칙·부제 5단어)만 갖고, "어디에·어떻게"는 각 앱이 소유

셋째가 이 저장소의 다른 결정들과 결이 맞습니다 — 값의 단일 출처를 소유자에게 돌려주는 패턴(@blog/site-values·content.values.mts·BUNDLE_GUARDS)과 같은 모양입니다. 다만 스킬이 "그림 추가하려면 어디를 봐야 하나"에 답을 못 하게 되므로, 앱 README로 가는 포인터는 남겨야 합니다.

blog-diagrams (a)는 선택지와 무관하게 지금 틀린 사실이라 어느 쪽으로 가든 고쳐야 합니다.

PostHero.svelte의 주석은 스킬이 아니라 코드라 범위 밖 조항에 걸리지 않습니다 — 주석을 사실에 맞게 줄이거나, 주장대로 exhaustiveness 검사를 실제로 넣는({:else if name} 뒤 never 소진) 선택이 있습니다.

---

검증 범위

• 정적 감사: 4종 SKILL.md 전체를 읽었습니다(1,131줄)
• 실사용: blog-diagrams §5 절차 1건. 프로브는 작업 트리에서만 돌리고 되돌렸습니다 — 되돌린 뒤 React check-types가 다시 통과하는 것을 확인했습니다. 커밋된 변경은 없습니다
• 하지 않은 것: 실제로 새 다이어그램을 두 앱에 구현해 화면으로 대조하지는 않았습니다. 타입 검사 층에서 이미 갈렸으므로 렌더까지 갈 필요가 없다고 판단했습니다

---

Generated by Claude Code