pretext 딥다이브
— DOM을 그리지 않고 텍스트 레이아웃을 계산하는 15KB 라이브러리

1프로젝트 한줄 요약

pretext는 DOM에 실제로 텍스트를 그리지 않고도 "그렸을 때의 줄 수와 높이"를 계산하는 멀티라인 텍스트 측정·배치 라이브러리다. 브라우저의 Canvas measureText API로 글자 폭을 재고, 그 폭들을 산술 계산해서 레이아웃을 결정한다. 채팅 말풍선 크기, 가상 스크롤 행 높이, 텍스트 에디터 줄바꿈처럼 "측정이 수백 번 반복되는" 상황을 위해 만들어졌다.

2왜 주목받는가

제작자가 Cheng Lou — React Motion(React 애니메이션의 고전)을 만든 개발자다. 이름값에 더해, "DOM 측정은 느리다"는 웹 개발의 오래된 통증을 정면으로 푼 점이 화제가 됐다. 게다가 레포 안에 RESEARCH.md·CLAUDE.md·AGENTS.md로 "왜 이렇게 만들었는가"를 솔직하게 공개해, 라이브러리 설계 노하우 교과서로도 읽힌다.

경쟁/대안 비교

3기술 스택 전체 지도

언어 구성 (GitHub Linguist 기준)

※ 단 두 언어. 빌드 도구·예제까지 거의 전부 TypeScript로 통일돼 있다.

런타임 의존성 — 0개

개발/빌드 도구 (devDependencies)

스크립트는 accuracy-check, benchmark-check, corpus-check, build:package, site:build 등 20개 이상 — "정확도 검증·벤치마크·말뭉치 검증"을 자동화한 점이 이 레포의 특징이다.

4아키텍처 심화 분석

전체 데이터 흐름

핵심 설계 패턴 ①: 측정/배치 2단계 분리

핵심 설계 패턴 ②: 병렬 배열 (Structure of Arrays)

핵심 설계 패턴 ③: 제로 할당 핫패스

핵심 설계 패턴 ④: 브라우저별 보정값을 "측정해서 캐시"

Chrome·Firefox는 macOS에서 작은 크기 이모지를 Canvas상에서 DOM보다 2~3픽셀 더 넓게 잰다. pretext는 룩업 테이블을 박아두는 대신 폰트별 보정 계수를 런타임에 감지해 캐시한다. 환경이 바뀌어도 견디는 설계다.

핵심 설계 패턴 ⑤: 전처리 우선(preprocessing over heuristics)

아랍어·미얀마어 같은 복잡한 스크립트는 복잡한 폭 모델 대신 의미 단위 전처리(구두점 클러스터 병합, 반복 기호 표시 등)로 푼다. RESEARCH.md의 결론: "알고리즘적 정교함보다 브라우저에 근거를 두는 단순함이 더 가치 있었다."

5디렉토리 구조 해부

읽는 순서 추천: README.md(무엇을) → src/layout.ts(공개 API의 형태) → src/measurement.ts(폭을 어떻게 재는가) → src/bidi.ts(가장 어려운 함정) → RESEARCH.md(왜 이렇게 했는가). 함정 하나당 파일 하나로 나뉜 구조라, 관심 있는 주제만 골라 읽기 좋다.

6학습 포인트 (기술별)

A. Canvas measureText — 숨은 측정 API

배울 것: DOM 리플로우 없이 글자 폭을 얻는 법. ctx.measureText(str).width 한 줄이 어떻게 "그리기"를 우회하는지, 그리고 그 결과가 실제 렌더링과 왜/얼마나 다른지(서브픽셀, 폰트별 보정).

B. 성능 설계 — 핫패스/콜드패스 분리

배울 것: "비싼 일은 한 번, 싼 일은 N번"이라는 보편 패턴. 어떤 일을 prepare로 밀어내고 layout은 산술만 남기는지를 보면, 자기 코드의 병목도 같은 눈으로 보게 된다.

C. 데이터 지향 설계 (SoA)

배울 것: 객체 배열 대신 병렬 배열로 CPU 캐시를 챙기는 법, 제로 할당으로 GC 부담을 없애는 법. JS에서도 이런 저수준 최적화가 의미 있다는 실증.

D. 국제화(i18n)의 실제 난이도

배울 것: 공백으로 단어를 나누면 왜 망하는지(CJK는 공백이 없음), Intl.Segmenter로 언어별 분절을 어떻게 위임하는지, 그래핌(이모지 결합)·금칙처리·RTL이 각각 무슨 문제인지. bidi.ts는 UAX #9 알고리즘의 실전 구현 예제다.

E. "정확도"를 코드로 보증하는 법

배울 것: accuracy/ + corpora/ + CI로 "계산값이 실제 DOM 측정과 일치하는가"를 자동 검증하는 구조. 측정 라이브러리답게 "맞다는 걸 어떻게 증명하나"가 코드에 박혀 있다.

F. 라이브러리 공개 설계 — 문서로 의사결정 남기기

배울 것: RESEARCH.md가 "무엇을 시도했고 왜 버렸는가"를 솔직히 기록한 사례. 좋은 오픈소스가 코드뿐 아니라 맥락(why)을 어떻게 남기는지 배울 수 있다.

7하드웨어 / 시스템 요구사항

pretext는 무거운 라이브러리가 아니라 브라우저 내장 API에 얹히는 15KB 코드다. 따라서 RAM·CPU 같은 하드웨어 사양보다 실행 환경이 특정 API를 지원하는가가 핵심 요구사항이다.

8직접 해볼 수 있는 실습 과제

// 브라우저 콘솔에 그대로 입력
const ctx = document.createElement('canvas').getContext('2d');
ctx.font = '16px sans-serif';
ctx.measureText('테스트 Hello 👨‍👩‍👧‍👦').width;
// → 숫자 폭이 즉시 출력. DOM에는 아무 흔적도 없다.

// 개념 코드 (API 형태 예시)
import { prepare, layout } from '@chenglou/pretext';

const prepared = prepare(message, { font: '14px Pretendard' });
const { height, lineCount } = layout(prepared, 360, 22);
// 리사이즈 시: 같은 prepared로 layout()만 다시 호출

9관련 기술 심화 학습 로드맵

1주차: 텍스트 측정의 기초

2주차: 레이아웃 알고리즘

3주차: 국제화(i18n)

4주차: 성능 & 검증

10핵심 키워드 사전

11참고 링크

• GitHub 레포 — chenglou/pretext
• README — API 전체 목록과 사용법
• RESEARCH.md — 설계 의사결정 기록
• src/ — layout.ts · bidi.ts · measurement.ts 등 소스
• npm — @chenglou/pretext
• MDN — Canvas measureText
• MDN — Intl.Segmenter
• Unicode UAX #9 — Bidirectional Algorithm
• 강제 동기 레이아웃(리플로우) 유발 속성 목록 — Paul Irish