ADR-0026: 글꼴을 번들해 텍스트 폭을 글꼴 메트릭으로 계산하고, 저장되는 SVG에는 서브셋 글꼴을 임베드한다
이후 변경
- 2026-11-03: 문서 설정 “텍스트를 외곽선으로 저장”(R-FMT-10)을 켜면 텍스트를 번들 TTF의 글리프 외곽선으로 적고, 서브셋 글꼴에는 번들 글꼴에 없는 문자가 든 줄의 문자만 넣는다. PDF는 늘 외곽선으로 그린다 → ADR-0045
- 2026-11-03: 웹은 화면 글꼴(woff2)을 문자 범위의 조각 38개로 나눠, 화면에 나온 글자의 조각만 받는다. 폭은 지금처럼 폭 테이블로 센다 → ADR-0040
- 2026-11-02: 번들 글꼴의 이름을
AriadneNSD Block에서AriadneNSD Mono로 바꿨다(고정폭 글꼴의 관례, 비례폭은AriadneNSD Sans) → DR-0019- 2026-11-01: MVP 코드에서 D2Coding 1.4.0으로 번들 글꼴과 폭 테이블을 만들었다(반각 1,259자 · 전각 11,565자). 글꼴 파일 안의 이름은
AriadneNSD Block이다(“D2Coding”은 OFL의 예약 글꼴 이름이라 고친 글꼴에 쓰지 못함). 서브셋에는 이름 레코드(저작권 · OFL 고지)를 모두 남긴다 → 2. 텍스트 폭 측정, 2. 문서 구조- 2026-11-01: 저장 파일에 넣는 서브셋 글꼴의 형식을 WOFF로 정했다(압축은 판을 고정한 JS zlib 라이브러리) → ADR-0039
- 2026-10-25: D2Coding으로 다시 쟀다. 글자 폭은 반각 500 · 전각 1000 두 가지뿐이고, 폭 테이블은 구간 50개(약 0.8 KB)다. 굵게의 폭은 보통과 같다. 테이블에 없는 글자는 전각으로 센다(ADR-0037). 서브셋은 한글 800자에 114 KB(TTF) · 46 KB(woff2)로, 아래 Pretendard의 숫자(895종에 179 KB)보다 작다 → 2. 텍스트 폭 측정
- 2026-10-25: 아래 “남은 물음”의 셋(어느 글꼴, 고정폭을 쓰는지, 한글을 모두 싣는지)에 답했다. 기본 블록 글꼴은 D2Coding 보통 굵기 하나이고, 한자를 뺀 나머지 문자(라틴 · 유럽 확장, 한글 11,172자, 그리스, 키릴, 가나)를 싣는다. 사용자를 한국어 사용자로 국한하지 않는다는 기준이 더해졌다 → ADR-0034
- 2026-10-22: 용어를 SW 엔지니어의 말로 고쳤다(뜻은 그대로). “글자 폭 표”는 advance 폭 테이블, “글꼴 조각”은 서브셋 글꼴, “글꼴 추리기”는 서브세팅이다. → 01-architecture
- 2026-10-17: 글꼴 파일, advance 폭 테이블, 서브세팅 wasm을 따로 된 패키지
packages/fonts에 둔다.core는 advance 폭 테이블만 쓴다(메인테이너: “A1 · 1번”) → 4. 구성 요소- 2026-10-13: 아래 “남은 물음” 가운데 서브셋 글꼴을 만드는 방법을 스파이크로 확인했다(
journal/assets/2026-10-13-font-subset-spike.mjs). harfbuzz의 서브세팅 라이브러리(hb-subset wasm, 652 KB)를 Node에서 돌렸다. 한 번에 10ms쯤 걸리고, 두 번 돌려도 글자의 순서를 바꿔도 같은 바이트가 나온다(결정적). 서브셋의 크기는 글자 41종에 8.7 KB(파일에 들어갈 때는 11.6 KB), 895종에 179 KB(239 KB)다. 압축하지 않은 TTF이고, 더 줄이려면 압축기를 따로 실어야 한다. 브라우저 안에서는 돌려 보지 않았다(같은 wasm 파일이다)
누가 무엇을 정했나
“글꼴 번들”과 “저장되는 그림에도 쓰인 글자만 추려 넣는다”(F1 · 2번)는 메인테이너가 정했다. 폭을 브라우저에 측정시키지 않고 글꼴 메트릭으로 계산한다, 커닝을 끈다, 정수 px로 올린다는 Claude가 제안했고, 메인테이너가 스파이크의 결과를 보고 승인했다(2026-10-13: “승인”). 어느 글꼴을 실을지는 이 ADR이 정하지 않는다.
배경
블록의 폭은 글자의 폭으로 정해진다. 글자의 폭은 실행 환경(브라우저, OS에 깔린 글꼴)마다 조금씩 다르다. 그러면 같은 모델이 환경마다 다른 그림으로 저장되어 R-NFR-02와 R-FMT-03을 지키지 못한다. 8. 위험과 검증이 필요한 사항에 위험으로 적어 두었던 것이다.
아키텍처를 짜기 전에 정할 것으로 Claude가 물었고, 메인테이너가 답했다.
3: 글꼴 번들 3번 스파이크 합시다
스파이크에서 물음이 하나 더 나왔다. 저장된 그림은 Obsidian의 노트나 GitHub처럼 우리 글꼴이 없는 곳에서 열리고, 거기서는 다른 글꼴로 그려져 글자가 칸을 넘거나 못 미친다(F1). 메인테이너는 처음에 이렇게 답했다.
Obsidian 노트나 GitHub에서는 번들을 해도 소용이 없다면 번들하려는 의미가 없습니다. 번들은 하지 맙시다
Claude가 바로잡았다. 글꼴을 그림에 넣거나 외곽선으로 바꾸려면 글꼴 파일이 손에 있어야 하고, 브라우저는 기기에 깔린 글꼴의 파일을 읽을 수 없다. 번들은 그 문제를 푸는 길의 전제다. 번들하지 않아도 다른 곳에서 글자가 어긋나는 것은 그대로다. 메인테이너가 스파이크 페이지의 그림을 보고 정했다.
F1 · 2번 채택
결정 기준
- 같은 모델은 어느 배포 대상에서 저장해도 같은 SVG가 된다
core는 DOM과 브라우저 API에 기대지 않는다 (4.3 의존 규칙)- 설치 파일과 첫 내려받기가 지나치게 커지지 않는다
- 저장된 그림은 글꼴이 없는 곳에서 열어도 글자가 칸에 맞는다 (R-FMT-01)
검토한 대안
대안 A. 글꼴을 번들한다
- 장점: 기기에 무슨 글꼴이 깔려 있든 같은 글꼴로 그린다. 글꼴 파일에 글리프마다의 advance 폭이 있어, 브라우저의 측정 API 없이 폭을 계산할 수 있다
- 단점: 글꼴 파일만큼 커진다. 글꼴에 없는 글자는 여전히 기기의 글꼴로 그려진다. 저장된 그림을 글꼴이 없는 곳에서 열면 다른 글꼴로 보인다
대안 B. 기기의 글꼴로 재고 값을 반올림한다
- 장점: 더 실을 것이 없다
- 단점: 기기마다 깔린 글꼴이 다르면 폭이 몇 px씩 달라 반올림으로 가려지지 않는다
대안 C. 요구사항을 “같은 환경에서 같은 SVG”로 낮춘다
- 장점: 할 일이 없다
- 단점: Obsidian에서 만든 파일을 웹에서 저장하면 그림 전체가 바뀌어 git에 큰 변경으로 남는다
저장되는 그림에 글꼴을 넣는 법 (F1)
- 1번. 넣지 않는다: 파일이 작고 git에서 바뀐 곳이 읽힌다. 글꼴이 없는 곳에서 글자가 칸을 넘거나 못 미친다
- 2번. 쓰인 글자만 추려 넣는다: 어디서 열어도 칸에 맞는다. 파일마다 서브셋 글꼴이 임베드되고(스파이크의 세 줄짜리 그림이 1.3 KB에서 18 KB로), 글자를 하나 더 쓰면 그 base64 덩어리가 통째로 바뀐다. 일부 문서 도구는 SVG 안의 글꼴을 읽지 않는다
- 3번. 글자를 외곽선으로 바꿔 넣는다: 어디서나 똑같이 보인다. 그림에서 글자를 고르거나 찾을 수 없고 파일이 가장 크다
결정
글꼴을 번들한다(대안 A). 저장되는 SVG에는 쓰인 글자만 남긴 서브셋 글꼴을 임베드한다(F1 · 2번). 그리고 텍스트 폭은 번들한 글꼴 파일의 advance 폭 테이블로 core가 직접 계산한다. 셸이 텍스트 측정 함수를 주입하지 않아도 된다.
스파이크(2026-10-13, 바로 가기의 “글자 폭 스파이크”)에서 이 컴퓨터의 Chrome 155와 Edge 155로 견본 14줄을 쟀다.
| 견준 것 | 가장 큰 차이 |
|---|---|
| 번들 글꼴(커닝 끔)을 브라우저가 측정한 값과 글꼴 메트릭으로 계산한 값 | 0.015px (Chrome이 폭을 1/64px 단위로 맞추는 만큼) |
| 위 두 값을 위로 올림한 값 | 다른 줄 없음 |
| 커닝을 켠 값과 끈 값 | 줄에 따라 0~8px (AVATAR To WAVE 같은 낱말) |
| 기기의 글꼴(맑은 고딕)로 측정한 값과 번들 글꼴로 측정한 값 | 줄에 따라 2~32px |
같은 날 메인테이너가 휴대폰(Chrome 154 / Android, 화면 배율 2.8125)에서 같은 페이지를 열어 값을 보냈다(journal/assets/2026-10-13-text-width-spike-android.json).
| 견준 것 (번들 글꼴에 없는 글자가 든 줄은 뺌) | 가장 큰 차이 |
|---|---|
| 휴대폰의 브라우저가 측정한 값과 글꼴 메트릭으로 계산한 값 | 0.083px (모든 줄에서 휴대폰 쪽이 조금 작다) |
| 휴대폰의 브라우저가 측정한 값과 Windows의 Chrome이 측정한 값 | 0.090px |
| 위로 올림한 값 | 다른 줄 없음 |
| 기기의 글꼴로 측정한 값, 휴대폰과 Windows | 32.8px |
▾ 나누기(글꼴에 없는 글자), 휴대폰과 Windows | 6.4px |
같은 엔진(Blink)에 같은 글꼴인데도 브라우저가 측정한 값은 기기마다 0.1px쯤 다르다. 폭을 맞추는 단위가 화면 배율을 따르기 때문이다(Windows는 1/64px, 이 휴대폰은 1/180px). 견본에서는 올림한 값이 같았지만, 폭이 정수에 아주 가까운 글자에서는 기기에 따라 1px이 갈릴 수 있다. 브라우저가 측정한 값을 쓰면 번들해도 “같은 모델이면 같은 SVG”(결정적 출력)가 보장되지 않고, 글꼴 메트릭으로 계산한 값을 쓰면 보장된다.
여기서 정해지는 것:
- 그릴 때 커닝과 합자를 끈다(
font-kerning: none). 켜 두면 advance 폭의 합과 브라우저가 렌더링한 폭이 어긋난다. 커닝까지 계산하려면 글꼴의 커닝 테이블(kern/ GPOS)을 읽는 코드가 더 든다 - 계산한 폭은 정수 px로 올림(ceil)해 쓴다. 브라우저마다의 소수점 아래 차이가 그림에 들어가지 않는다
- 번들 글꼴에 없는 글자(견본에서는
▾)는 편집기가 그림에 적지 않는다. 사용자가 적은 글자가 글꼴에 없을 때의 폭은 따로 정한다
결과
- 좋아지는 점: 레이아웃이 순수 함수가 되어 Node에서 그대로 테스트할 수 있다. 텍스트 측정 함수를 주입하는 인터페이스가 없어진다
- 감수하는 점: 저장되는 파일마다 서브셋 글꼴이 임베드되어 커지고, git에서 그 부분의 변경은 읽을 수 없다. Pretendard Regular를 통째로 실으면 woff2로 762 KB, 자주 쓰는 한글 2,350자로 추리면 187 KB가 는다. 굵은 글자나 고정폭 글꼴을 더 실으면 그만큼 더해진다
- 확인하지 못한 것: Firefox(Gecko)와 Safari(WebKit)에서 번들 글꼴을 측정한 값. 폭을 글꼴 메트릭으로 계산하므로 저장되는 파일은 이 값과 상관없이 같다. 남는 것은 그 브라우저가 렌더링한 폭이 계산한 폭에서 얼마나 벗어나는가이고, Blink에서는 0.1px 안이었다
- 남은 물음
- 어느 글꼴을 싣는가. 스파이크는 Pretendard Regular(OFL 1.1)를 임시로 썼다. 코드를 적는 블록에 고정폭 글꼴을 쓸지도 함께 정한다
- 서브세팅은 같은 글자 집합에서 늘 같은 바이트가 나와야 한다(결정적)(R-FMT-03). 브라우저 안에서 서브세팅하는 방법(라이브러리, 크기, 속도)은 확인하지 못했다. 스파이크의 서브셋은 Python의 fonttools로 미리 만든 것이다
- 임베드된 글꼴을 읽지 않는 도구를 위한 외곽선 옵션(R-FMT-10)을 그대로 둘지
- 사용자가 테마에서 글꼴을 바꾸는 것(R-LAY-08)을 어디까지 허용하는가. 번들하지 않은 글꼴은 폭을 계산할 수 없다
- 한글을 모두(11,172자) 싣는가, 추려 싣는가
- 후속 작업: 2. 텍스트 폭 측정, 01-architecture의 의존 규칙과 4.1의 시퀀스 다이어그램(측정 함수 주입)을 고친다