Skip to content

Vim Input islands and block entry

github-actions[bot] edited this page Sep 14, 2026 · 1 revision

Vim Input islands and block entry

vim 이 키를 쥐지 않는 구간과, 그 구간에 들어가고 나오는 규칙이다. 코드블록·수식·mermaid 안에서 vim 이 이상하게 구는 증상은 대부분 이 페이지의 내용이다.

입력 섬이란

NodeView 안의 입력 요소(textarea · input · CodeMirror)는 포커스를 쥐면 키를 소유한다. 그 구간이 입력 섬이고, 그동안 vim 은 명령 해석을 멈춘다. 멈추지 않으면 사용자가 수식을 타이핑할 때 d 가 줄을 지운다.

판정은 마커 두 개로 한다 — 하나는 섬을, 하나는 PM 본문을 표시한다. keydown 의 composedPath() 를 target 에서 바깥으로 걸어 먼저 만나는 마커가 이긴다. 중첩된 구조에서 가장 안쪽 주장이 이기고, 마커 이름은 Code map 의 leaf 모듈에 있다.

해제는 focusout 이 아니라 microtask 재평가다

섬에서 나왔는지를 focusout 에 동기로 물으면, 섬 내부의 input → 버튼 이동이 순간 resume 을 만든다. 그 찰나에 도착한 키를 vim 이 명령으로 훔친다. 그래서 해제는 microtask 로 미뤄 다시 평가한다 — "지금 포커스가 어디 있나" 는 이동이 끝난 뒤에 물어야 답이 맞다.

라벨은 상태와 같은 트랜잭션에 실린다

자체 vim 이 없는 섬(수식 · mermaid · SVG · HTML · query)이 키를 쥐는 동안 모드 라인이 -- NORMAL -- 이라고 말하면 거짓말이다. 그래서 섬 판정에 라벨을 함께 실어 -- INSERT (math) -- 로 표시한다. 불리언만 비교하면 섬에서 섬으로 옮길 때 라벨이 굳으므로, 라벨 변화도 dispatch 조건이다.

코드블록은 의도적으로 라벨이 없다. CM 자체 vim 이 island 레이어로 표시를 소유하므로, 라벨을 달면 그 표시가 서기 전에 잘못된 INSERT 가 한 번 깜빡인다. 모르는 host(캡션 등)는 표면 표시를 유지한다 — 보증하지 못하는 insert 를 주장하지 않는다.

마커는 문서가 아니라 앱의 권한이다

이것이 보안 불변식이다. DOMPurify 는 data-* 와 tabindex 를 기본 허용하므로, 공유받은 문서가 자기를 섬이라고 주장하거나 반대로 진짜 섬에서 섬이 아니라고 우겨 사용자의 타이핑을 vim 명령으로 실행시킬 수 있다. 그래서 sanitizer 세 곳(HTML 블록 · SVG · AI 마크다운)이 이 마커들을 제거한다.

새 sanitizer 를 만들면 반드시 이 목록을 넣을 것. 마커 이름이 의존성 없는 leaf 모듈에 사는 이유가 이것이다 — 항상 도는 보안 코드가 vim 기능 모듈을 역참조하면 계층이 뒤집힌다.

블록 진입 모델

편집 UI 는 selection 이 아니라 진입을 따른다

원래 렌더는 "선택됐으면 편집, 아니면 미리보기" 였다. churn 억제로 착지가 살아남자 j 로 훑기만 해도 편집 박스가 열리는 것이 드러났다. 지금의 규칙:

  • 순회(j/k)와 normal 모드 클릭 = 착지만. 블록에 아웃라인이 서고 편집기는 열리지 않는다.
  • 진입 = i. 또는 insert 모드의 클릭, 또는 vim 이 꺼져 있을 때의 클릭.

normal 모드의 클릭이 탐색이라는 것은 UX 결정이다 — 근거는 Decisions and history 에 있다.

렌더 경로는 하나여야 한다. 두 개의 return 으로 갈리면 flip 할 때 textarea 엘리먼트가 교체되고, 진입 직전에 걸어 둔 포커스가 무효가 된다. 슬롯 하나가 위치를 지켜 엘리먼트 아이덴티티를 보존한다.

standby textarea — 진입할 곳이 먼저 있어야 한다

i 는 블록의 DOM 에서 포커스 가능한 것을 찾아 포커스한다. 편집 렌더가 진입한 뒤에야 생기면 찾을 것이 없으므로, 선택 중에는 보이지 않는 standby 입력을 유지한다.

  • tabIndex={-1} 과 aria-hidden — 탭 정지도 아니고 보조 기술에도 노출되지 않는다. 진입하면 해제한다. 프로그램적 focus() 는 -1 에서도 동작한다.
  • standby 의 focus 이벤트가 곧 진입 신호다.
  • auto-resize 는 편집 중일 때만 잰다 — 1px 폭 standby 에서 잰 높이가 인라인으로 굳는 버그가 있었다.
  • query 블록만 다르다. 편집기가 builder 패널이라 standby 가 input 이고, 포커스가 세션을 연 뒤 layout effect 에서 첫 컨트롤로 전달한다. setTimeout 으로 전달하면 그 틈에 포커스가 body 로 떨어진다.

Esc 계단은 원자적이어야 한다

섬 안에서 Esc → 저장 → 한 트랜잭션으로 normal 모드와 블록 NodeSelection → 에디터 포커스 복귀. 원자성이 필수인 이유는 구체적이다: 표면이 insert 인 상태에서 클릭으로 열린 세션은 vim 이 insert 에 남아 있고, 래치만 닫으면 editable 한 뷰 + 살아 있는 NodeSelection 이 된다. 다음 타이핑이 블록을 통째로 교체한다 — 실제 문서에서 수식이 그렇게 파괴됐다.

vim 이 꺼져 있으면 기존 이탈 동작을 유지한다. 계단은 vim 계약이다.

계약 셋의 멤버십이 다르다

"atom 블록" 이 한 덩어리처럼 보이지만, 세 계약의 참여자가 서로 다르다. 한 곳을 고쳐 전부 커버된다고 가정하면 틀린다.

계약 참여하는 블록
standby 진입 모델 수식 · mermaid · SVG · HTML · query
경계 탈출 공유 훅 (화살표 · 빈 블록 Backspace) 수식 · mermaid · SVG · HTML · block-embed
편집 세션 공유 훅 수식 · mermaid · SVG

query 는 진입 모델에 있으나 경계 탈출 훅에는 없고, block-embed 는 그 반대다. 파일 위치는 Code map 에 있다.

경계 탈출 훅이 포커스를 되돌릴 때 맨 view.focus() 를 쓰면 안 된다 — non-editable 뷰에서 조용히 no-op 이고, 섬이 unmount 되면 포커스가 body 로 떨어져 vim 이 죽는다. 공유 폴백을 쓴다.

코드블록 진입이 "됐다 안 됐다" 했던 이유

머지 뒤 보고: j/k 로 코드블록에 들어가는 것이 파일을 처음 열면 되고, 소스 모드를 왕복하면 안 되고, 마우스로 클릭한 뒤에는 한동안 됐다.

원인은 착지가 아니라 그다음 단계였다. 착지는 매번 성공했다. ProseMirror 가 NodeView 에 setSelection 을 내려보내는 것은 자기 게이트를 통과할 때뿐인데 — DOM selection 의 양 끝이 뷰 안에 있고 activeElement 가 뷰를 품어야 한다 — vim modal 에서는 그 조건이 대개 깨져 있다 (WebKit selection churn 의 방어가 범위 selection 을 지우고, 소스 왕복은 selection 을 통째로 옮긴다). 낡은 DOM range 가 우연히 남았을 때만 성공했다. 비결정성의 정체가 그것이다.

처치는 PM 게이트에 기대지 않는 명시적 핸드오프 채널이다. NodeView 가 자기 핸드오프를 등록·해제하고, 프로그램적 착지 경로들이 공유 판정을 거쳐 직접 부른다.

핵심은 그 핸드오프가 성공 여부를 boolean 으로 보고한다는 것이다. 아직 마운트되지 않은 블록은 selection 을 기억만 하고 false 를 돌려주며, 호출자는 포커스 폴백을 유지해 키보드를 살린다. CM 이 마운트될 때 그 기억을 소비하며 포커스를 인계받는다. 여기서 true 를 돌려주면 검색과 소스 복귀가 폴백을 건너뛰어 키보드가 죽는다.

기억한 selection 을 그대로 쓰지 않고 현재 문서에서 오프셋을 다시 계산하는 것도 같은 이유다 — 비동기 초기화 중에 편집이 끼면 그 기억은 범위 안에 있으면서 낡아 있다.

baram

Vim

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

CLI

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

Clone this wiki locally