커스텀 Ink 렌더링 엔진

Claude Code의 터미널 UI는 브라우저 DOM 대신 터미널 셀 그리드에 그려집니다. Ink 렌더러는 React Reconciler가 만든 호스트 트리를 받아 Yoga로 레이아웃을 계산하고, 그 결과를 화면 버퍼에 적재한 뒤, 이전 프레임과 비교해 필요한 ANSI 출력만 내보냅니다.

• Reconciler: React 커밋을 Ink 호스트 노드로 바꿉니다
• Yoga: Flexbox 레이아웃을 숫자 좌표로 계산합니다
• Output 단계: 노드를 쓰기 명령과 스타일 정보로 평탄화합니다
• Screen Buffer: 셀 단위 상태를 패킹해 diff 친화적으로 만듭니다
• Terminal Flush: 이전 프레임과 비교해 변경분만 출력합니다

renderer.ts는 단순한 "마지막 출력기"가 아닙니다. Reconciler에서 받은 변경 신호를 수집하고, 언제 레이아웃을 다시 계산할지, 언제 전체 프레임을 다시 그릴지, 언제 이전 버퍼를 무효화할지를 결정하는 프레임 조정자 역할을 합니다.

주요 책임

• dirty 상태 수집: 변경이 생긴 서브트리를 표시합니다
• 렌더 스케줄링: 여러 커밋을 한 프레임으로 모읍니다
• 버퍼 수명 관리: 현재 프레임과 이전 프레임의 비교 기준을 유지합니다
• 터미널 불변식 유지: alt-screen, contamination, resize 이후 재그리기를 통제합니다

// renderer.ts의 개념적 흐름
commit from reconciler
  -> mark dirty subtrees
  -> schedule frame
  -> compute layout if needed
  -> build output commands
  -> write into packed screen buffer
  -> diff with previous frame
  -> flush terminal escapes

React Reconciler는 DOM 대신 Ink의 호스트 노드를 만듭니다. 텍스트 노드, 박스 노드, 스타일 노드가 여기에 속하며, 커밋 단계에서 변경된 노드를 dirty로 표시해 후속 렌더를 예약합니다.

커밋의 핵심

• 호스트 노드 생성: JSX를 Ink 전용 노드 트리로 변환
• 속성 반영: 스타일과 텍스트, 정렬 옵션을 갱신
• dirty 전파: 변경된 노드와 관련 조상에게 재계산 필요를 알림

// 커밋 후 dirty 전파 예시
function commitUpdate(node, nextProps) {
  node.props = nextProps
  markDirty(node)
}

function markDirty(node) {
  node.isDirty = true
  let current = node.parentNode
  while (current) {
    current.hasDirtyDescendant = true
    current = current.parentNode
  }
}

호스트 트리가 준비되면 Yoga가 각 노드의 사각형을 계산합니다. 터미널 렌더러는 CSS 전체를 구현하지 않지만, Flexbox 축과 패딩, 정렬, 폭 계산 같은 핵심 규칙은 Yoga에 맡겨 일관성을 얻습니다.

왜 별도 레이아웃 단계가 필요한가

• 텍스트 폭 계산: 문자열 길이와 실제 터미널 셀 폭은 다를 수 있습니다
• 박스 중첩: 부모와 자식의 패딩, 정렬, wrapping을 한 번에 계산해야 합니다
• 후속 단계 단순화: 출력 단계는 계산된 좌표만 믿고 그리면 됩니다

// Yoga 계산 결과는 숫자 좌표로 내려옵니다
layout = {
  x: 0,
  y: 3,
  width: 64,
  height: 5,
}

renderNodeToOutput 단계는 레이아웃이 끝난 노드를 실제 쓰기 명령으로 평탄화합니다. 여기서 중요한 점은 blit 최적화가 "터미널로 바로 쓰는 지름길"이 아니라, 같은 화면 버퍼 모델 안에서 일부 영역만 빠르게 갱신하는 경로라는 점입니다.

일반 경로

1. 노드 트리를 순회합니다
2. 텍스트와 스타일을 출력 조각으로 바꿉니다
3. 조각을 화면 버퍼에 기록합니다
4. 최종 diff를 계산해 터미널에 flush합니다

blit 경로의 실제 의미

blit은 이미 계산된 출력 조각이나 버퍼 조각을 대상 영역에 복사하는 빠른 경로입니다. 하지만 alt-screen 관리, 이전 프레임 비교, 오염 감지는 여전히 같은 파이프라인이 담당합니다. 즉, blit이 diff와 버퍼 불변식을 건너뛰는 것은 아닙니다.

// blit은 버퍼 일부를 같은 프레임 모델 안에서 복사합니다
function blitRegion(screen, fragment, x, y) {
  // fragment -> packed screen buffer의 일부 영역으로 복사
  // 이후 flush 단계는 여전히 prev frame과 비교합니다
}

화면 버퍼는 문자열 배열이 아니라 셀 상태를 정수 중심으로 패킹한 구조입니다. 문자, 스타일, 가시성 플래그, 와이드 문자 연속 상태 같은 값이 버퍼에 담겨 있으므로, diff 단계는 먼저 값 비교를 빠르게 수행하고 필요할 때만 ANSI 시퀀스를 만듭니다.

왜 패킹하는가

• 빠른 비교: 셀 단위 정수 비교가 문자열 비교보다 싸기 때문입니다
• 스타일 중복 제거: 스타일 상태를 셀과 함께 저장해 flush 단계가 단순해집니다
• 공백도 상태화: 공백 문자인지와 별개로 배경색, 가시성 여부를 구분할 수 있습니다

// 화면 버퍼는 문자 자체보다 셀 상태 비교에 최적화됩니다
cell = {
  codePoint,
  styleBits,
  visibleOnSpace,
  continuation,
}

터미널 텍스트는 단순히 "문자 1개 = 셀 1칸"이 아닙니다. 한글, CJK 문자는 2칸을 차지할 수 있고, 결합 문자나 variation selector는 새 셀을 차지하지 않을 수 있습니다. 렌더러는 이 폭 정보를 알고 버퍼를 채워야 셀 경계가 깨지지 않습니다.

와이드 문자

• 리드 셀: 실제 문자와 스타일이 들어갑니다
• 연속 셀: 오른쪽 절반이라는 표시가 들어갑니다
• 덮어쓰기 규칙: 와이드 문자 위에 일반 문자를 쓰면 연속 셀도 함께 정리해야 합니다

결합 문자와 0폭 문자

결합 문자는 독립 셀을 하나 더 차지하기보다 앞선 글리프에 붙습니다. 그래서 렌더러는 단순한 string.length가 아니라 실제 셀 폭 규칙을 기준으로 버퍼 오프셋을 계산해야 합니다.

// 폭 계산은 코드 유닛 수가 아니라 셀 폭 기준입니다
const width = getCellWidth(grapheme)

if (width === 2) {
  // lead cell + continuation cell
}

if (width === 0) {
  // 이전 셀 글리프에 결합
}

전체 화면 지우기와 풀 프레임 재렌더는 아무 때나 해도 되는 동작이 아닙니다. alt-screen에 들어간 상태에서만 기존 셸 화면을 건드리지 않고 안전하게 전체 프레임을 다시 그릴 수 있습니다. 이게 렌더러의 중요한 불변식입니다.

핵심 불변식

• alt-screen 안에서만 파괴적 clear: 일반 셸 화면을 실수로 지우지 않아야 합니다
• contamination 이후 full redraw: 외부 출력이나 resize로 기준 버퍼가 어긋나면 전체 재그리기가 필요합니다
• shouldClearScreen의 범위 제한: 단순히 "첫 프레임이니까 clear"가 아니라, alt-screen 진입이나 버퍼 무효화 같은 상태 전환과 함께 봐야 합니다

// 전체 clear는 alt-screen과 버퍼 무효화가 맞물릴 때만 안전합니다
if (isInAltScreen && shouldClearScreen) {
  clearScreen()
  previousFrame = null
}