Skip to content

Vim Architecture

github-actions[bot] edited this page Oct 6, 2026 · 2 revisions

Vim Architecture

WYSIWYG 표면의 vim 은 자체 엔진이다 (Overview 가 왜인지 설명한다). 그 엔진은 네 층이고, 이 페이지는 각 층이 무엇을 하는지보다 경계가 왜 거기 그어졌는지 를 다룬다. 경계가 흔들리면 되돌아올 곳이 여기다.

층 흐름

KeyboardEvent
   │
   ▼
toKeyToken            물리키 / raw 분리 — 한글 입력 소스 대응
   │  KeyToken
   ▼
core 상태기계          순수. ProseMirror import 0 (purity 핀이 고정)
   │  StepResult { state, command, handled }
   ▼
plugin                PM Plugin — 진입점 · selection 경로 · 상태 reduce
   │  CoreCommand
   ▼
adapters              intent 를 실제 문서 위에서 실행
   │                  모션 · d/c/y · 검색 · grapheme 경계 · 스크롤 · 입력 섬 판정
   ▼
EditorState

각 층의 파일은 Code map 에 있다 — 키 정규화는 흐름에서 core 앞에 서지만 파일은 core 안의 별도 모듈이다.

층별 책임

층 하는 일 하지 않는 일
toKeyToken KeyboardEvent 를 KeyToken 으로 정규화 의미 판단
core 모드 · pending · count · 라인 입력의 상태 위치 해석, 트랜잭션 생성
plugin 키 진입, selection 쓰기, 상태 reduce 모션이 어디로 가는지 계산
adapters 문서를 걷고 읽고 바꾸기 모드나 pending 을 기억

경계 1: 키 정규화 — 물리키와 raw

한글 입력 소스가 켜진 채 j 를 누르면 event.key 는 ㅓ 다. 명령 판단이 event.key 를 보면 모달 편집은 한국어 사용자에게 통째로 죽는다.

toKeyToken 이 vim 의 langmap 아이디어를 안전하게 판정할 수 있는 한 경우로 좁혀 적용한다: 생성된 문자가 한글이고 물리키가 평범한 글자키일 때만, 물리키의 글자를 명령으로 읽는다. 그 밖의 모든 경우(어떤 레이아웃의 라틴 글자, 기호, 숫자, 제어키)는 event.key 를 그대로 둔다 — dvorak 류 리매핑과 shift 기호가 다치지 않는다.

원래 문자를 잃지 않는다. 다르면 raw 에 함께 실어 보내고, 문자를 리터럴로 받아야 하는 소비자만 raw 를 읽는다 — f/F/t/T 의 find 타겟(한글 타겟은 한글을 찾아야 한다)과 라인 입력의 문자 누적이 그렇다.

이 분리가 가장 아래 층에 있는 이유: 위의 세 층 전부가 "명령은 물리키, 문자는 raw" 라는 한 규칙을 공유하게 된다. 각 소비자가 알아서 판단하면 한국어 지원이 경로마다 갈리고, 새 명령을 추가할 때마다 같은 실수를 다시 할 자리가 생긴다.

경계 2: core 순수성 계약

core 는 ProseMirror 를 모른다. 정적 import 문에 PM 이 없고, purity 핀이 core 디렉터리의 .ts 를 훑어 그것을 고정한다 — 게이트 없는 경계는 첫 번째 편리한 import 에서 무너지기 때문이다. (핀이 보는 것은 from "…" 형태다. 동적 await import() 나 leaf 를 거친 전이 의존은 그 검사가 못 본다.)

구체적으로 core 는 위치를 해석하지 않고 트랜잭션을 만들지 않는다. 대가는 core 가 "커서를 아래로" 라고만 말할 수 있다는 것이고, 얻는 것은 모달 층을 DOM 없이 단위 테스트할 수 있다는 것이다. 모드 전이·pending 시퀀스·count 접두·라인 입력은 평범한 객체 리터럴로 상태기계를 구동해 검증된다.

이 이득이 특히 큰 이유는 이 엔진이 다루는 DOM 이 정직하지 않기 때문이다 — WebKit selection churn 이 그 기록이다. 모달 의미론의 회귀를 그 위에서 잡으려 하면 무엇이 깨졌는지 구별할 수 없다.

경계 3: CoreCommand 는 intent 어휘다

core 가 plugin 에게 넘기는 것은 "무엇을 하라" 이고, "어떻게" 는 adapters 가 정한다. 이 어휘가 지키는 규칙:

  • 한 키 입력이 만드는 명령은 최대 하나다. dd·gg·df{c} 처럼 여러 키로 완성되는 시퀀스는 pending 상태로 누적되고, 완성될 때만 방출된다. 중간 키는 상태만 바꾼다.
  • handled: false 는 "앱에 넘겨라" 다. normal 모드에서 Cmd+S 나 메뉴 액셀러레이터를 삼키면 안 된다. 소비 여부를 core 가 말해 주므로, plugin 은 handled 일 때만 이벤트를 소비한다 — 키 하나에 소비자가 하나라는 원칙이 여기서 나온다.
  • 라인 입력 두 개(exLine·searchLine)는 같은 틀이다. 열림 → printable 누적(raw 우선 — 한글 자모) → Enter 에서 방출 / Esc 에서 닫힘. 열려 있는 동안 모든 키를 삼킨다(앱으로 새면 :w 를 타이핑하다 메뉴가 열린다). core 에서 상호 배타이므로 상태 피드의 슬롯도 하나다.

plugin 층이 키를 받는 자리도 경계가 만든 결과다. normal/visual 키는 PM 의 handleKeyDown 이 아니라 custom DOM keydown 핸들러로 들어온다. prosemirror-view 가 custom 핸들러를 자신의 editable 게이트보다 먼저 실행하기 때문이고, 그래서 그 경로가 non-editable 뷰에서도 살아 있는 유일한 키 경로다. 이건 현재 prosemirror-view 의 입력 배선(initInput — custom 핸들러 먼저, editable 게이트 나중)에 기댄 것이라 업그레이드 때 확인할 계약이다.

insert 모드만 handleKeyDown 을 쓴다 — PM 의 composition 전처리를 물려받아야 하기 때문이다. 거기로 들어오는 것은 Esc(그리고 그 Esc 를 transient 에게 양보하는 중재)와 코드블록 경계의 화살표 진입(#477)이다.

경계 4: 행 모델 — "줄" 을 정의하는 층

vim 의 세로 이동과 줄 오퍼레이션은 "줄" 을 전제한다. PM 문서는 트리이고 줄이 없다. 그 전제를 공급하는 것이 행 모델이다.

collectLines 가 문서를 "커서 줄" 의 배열로 본다:

문서 구조 줄로는 어떻게 보이나
텍스트블록 hardBreak 로 쪼갠 세그먼트들 (splitSegments)
atom 블록 (수식 · mermaid · 이미지 · hr) 한 줄
테이블 행 한 줄 (첫 셀의 첫 텍스트블록이 대표)
코드블록 한 줄 — 단 아래의 특례

코드블록 특례가 이 층에서 가장 미끄러운 곳이다. 코드블록은 content: "text*" 라 textblock 으로 읽히는데 내부 개행이 리터럴 문자다. 세로 이동의 칼럼 보존이 그 개행을 모르면 칼럼을 소스 오프셋으로 흘려보내므로, 코드블록 착지는 일반 칼럼 산술에서 떼어 낸다. normal 모드의 기본은 방향성 착지다 — 진입 방향의 소스 줄(위에서 오면 첫 줄, 아래에서 오면 마지막 줄)에 goal 칼럼 그대로 내려놓는다. 콘텐츠 시작으로 떨어지는 것은 visual 모드와 CM 섬이 없는 journal-* 블록뿐이다.

그 판정은 노드 이름 매칭이다 — spec.code 로 판정하면 frontmatter 도 true 라서 회귀를 만들었다.

블록 안에서의 이동은 행 모델이 아니라 CM island 소관이다.

goal 칼럼은 vim 의 curswant 다. j/k 는 출발한 칼럼을 기억하고, 각 줄에서는 그 줄 길이로 clamp 할 뿐 기억을 줄이지 않는다 — 짧은 줄 · 빈 줄 · atom 블록 · 표 행을 지나도 칼럼이 돌아온다. 어떤 명령이 그 기억을 유지하고 어떤 명령이 잊게 하는지는 core 의 한 switch 가 명령마다 정하고 (default 가 없어 새 명령은 답하기 전까지 컴파일되지 않는다. find 는 성공했을 때만 잊는데, 성공 여부는 문서를 보는 adapter 가 넣는다), 칼럼 값은 다음 j/k 가 필요할 때만 adapter 가 잰다. 상태줄 검색 제출도 goalAfter(...) 를 호출해 같은 규칙을 쓴다. 그 switch 밖에서 기억을 지우는 자리는 core 의 insert 모드 Esc, plugin state 의 우선순위 사다리(외부 명령과 외부 선택은 항상, 편집은 forgetsGoal(tr) 에 따라 syntax reveal 태그가 없을 때), 모드 재설정(섬 경계, 변경 거부 복구, 섬 진입·이탈), vim 을 켤 때의 초기화, 커서를 실제로 옮긴 포인터 누름을 감시하는 경로(누를 때 걸고, 다음 키에 푼다), 문서 활성화 리셋이다. 오퍼레이터는 실행되면 goal 을 잊는데, 모션이 실패해 취소된 것(매치 없는 find, 줄을 떠나지 못하는 j/k)은 실행되지 않았으므로 키 입력 전의 goal 을 돌려받는다 — adapter 가 취소를 알리고, core 의 goalAfterOperator 가 정하고, plugin 이 변경 명령의 normal 복귀(goal 을 지운다) 뒤에 적용한다. 파일 위치는 Vim Code map.

gg · G · :N 의 첫 non-blank 착지는 Vim 의 기본 startofline 을 따른다. Neovim 의 기본 nostartofline 은 가능한 한 칼럼을 유지한다.

frontmatter 는 두 줄 모델이 겹친다. 코드블록처럼 리터럴 개행을 가진 textblock 이지만 CM 섬이 없어 PM 이 캐럿을 관리한다. j/k · 0/$ · linewise 오퍼레이터 · 줄 끝 clamp 에게는 블록 전체가 한 줄이고, 첫 non-blank 탐색(^ · I · z. · gg/G · :N)과 insert Esc 의 후퇴는 개행으로 자른 YAML 줄을 줄로 본다 — 앞쪽 규칙이 YAML 줄을 넘으면 빈 첫 줄을 건너뛰거나 윗줄 개행 위로 물러나기 때문이다. 개행 문자는 폭이 없어 normal 커서가 그 위에서는 빈 줄 caret 으로 그려진다.

h/l 이 셀 경계를 넘는 것(cellHop)도 이 모델의 귀결이다. 테이블 한 행이 한 줄이므로, 한 줄 안에서 좌우로 움직이면 셀을 건너게 된다.

baram

Vim

링크 없는 항목은 아직 쓰지 않았다. 그 주제의 현재 출처는 해당 모듈의 헤더 주석이고, 어느 파일인지는 Code map 이, 구현 현황은 #298 · #372 가 답한다.

CLI

링크 없는 항목은 아직 쓰지 않았다. 쓰는 법은 사용자 문서 가, 구현 현황과 다음 단계는 추적 이슈 가, 계약은 src-tauri/src/cli/ 의 모듈 헤더와 함수 · 타입의 문서 주석이 답한다.

Clone this wiki locally