UNIM 도움말

리눅스판 — 이 문서는 docs/user/ 의 마크다운에서 자동 생성된 오프라인 사본이다. 내용이 오래됐거나 링크가 깨졌다면 최신판을 GitHub 문서에서 확인한다.

UNIM 사용자 매뉴얼 (한국어)

UNIM 0.4.0 — Universal Next-generation Input Method 한국어와 영어를 자유롭게 오가며 타이핑하기 위한 Rust 기반 입력기. 이 문서는 처음 쓰는 사람도 5분 안에 한글 한 글자를 칠 수 있게 만드는 것이 목표다.

1. UNIM이 무엇인가 (30초 설명)

IME (Input Method Editor, 입력기): 키보드의 알파벳 키 두드림을 한글 음절로 바꿔서 앱 화면에 보여주는 시스템 컴포넌트. 다른 IME 예시: ibus-hangul, fcitx-hangul, kime, nimf.
🐧 리눅스에서의 차별점: Rust로 작성된 단일 코어를 GTK·Qt·XIM·Wayland·GNOME Shell 다섯 환경 모두에 그대로 꽂는다. 즉 어떤 앱(터미널, 브라우저, 메모장, IDE)에서 한글을 쳐도 같은 조합 규칙·같은 한자 팝업·같은 자동 오타 교정이 동작한다.
30초 요약: "한/영 키로 모드 전환 → 한글 입력 → 한자키로 한자 변환 → ㄱㄴㄷ로 특수문자 변환 → 영타가 한글로 잘못 나가도 자동 복구". 이게 UNIM이 사용자에게 제공하는 가치 전부다.

약어 풀이: IM 모듈 (Input Method Module) — 앱이 키 입력을 IME에 위임할 수 있게 해 주는 툴킷별 어댑터(GTK용, Qt용 등). DBus (Desktop Bus) — 리눅스 데스크톱의 프로세스 간 통신 버스. UNIM은 DBus 위에서 데몬↔프론트엔드 통신을 한다. XIM (X Input Method) — X11 시절부터 쓰인 가장 오래된 IME 프로토콜. Wayland — 차세대 디스플레이 프로토콜로, X11과 IM 처리 방식이 다르다.

2. 빠른 시작 (5분)

2.1 설치

🐧 리눅스 지원 환경: Ubuntu 24.04 (noble) 이상 / 동급 Debian, amd64. 릴리스 .deb 는 noble 기준으로 빌드된다.

방법 1 — 자동 설치 스크립트 (권장)

한 줄이면 GitHub Releases 의 .deb 전체를 내려받아 apt 로 설치한다. 모든 .deb 를 SHA256 체크섬으로 검증하고, mktemp 임시 디렉토리에 격리하며, 외부 런타임 의존성을 자동 해결한다. 검증 실패 시 아무것도 설치하지 않고 중단한다(부분 설치 없음).

curl -fsSL https://raw.githubusercontent.com/from104/unim/main/install.sh | bash

특정 버전을 고정하려면:

UNIM_VERSION=v0.4.0 curl -fsSL https://raw.githubusercontent.com/from104/unim/main/install.sh | bash

curl | bash 를 신뢰하지 않는다면 스크립트를 먼저 받아 읽고 실행할 수 있다:

curl -fsSL https://raw.githubusercontent.com/from104/unim/main/install.sh -o install.sh
less install.sh && bash install.sh

방법 2 — Releases 수동 다운로드

Releases 에서 unim*_<버전>-1_{amd64,all}.deb 전부와 SHA256SUMS 를 같은 디렉토리에 받아 검증 후 설치한다.

# 체크섬 검증 (예: 0.4.0-1 — 11개 패키지)
sha256sum -c SHA256SUMS

# 패키지 설치 (apt 가 의존성을 자동 해결)
sudo apt install ./unim*.deb

# IBus 제거 (GNOME 환경에서 충돌 방지)
sudo apt remove ibus

# 시스템 입력기로 UNIM 등록 (Debian/Ubuntu 표준 도구)
im-config -n unim

설치 직후 한 번 로그아웃하고 다시 로그인하면 환경변수가 새 셸에 적용된다. 재로그인한 첫 세션에서 첫 실행 마법사(unim-settings)가 자동으로 뜨며, 기본 입력기 지정까지 GUI로 안내한다. 마법사를 도중에 닫으면 다음 로그인에 다시 나타나고, 수동으로 다시 열려면 unim-settings --first-run 을 실행한다.

방법 3 — 소스 빌드 (Arch/Fedora/그 외)

git clone https://github.com/from104/unim.git
cd unim
make build           # Rust workspace + GTK3/4·Qt5/6 IM 모듈 한 번에 빌드
sudo make install PREFIX=/usr
sudo make install-systemd PREFIX=/usr
systemctl --user daemon-reload
systemctl --user enable --now unim-daemon.service

소스 빌드는 cargo 1.95 이상, GTK4/libadwaita 헤더, Qt5/Qt6 개발 패키지가 필요하다. 패키지명은 배포판마다 다르니 빌드 실패 시 docs/user/troubleshooting/README-ko.md 참고.

2.2 환경 변수 (GNOME 확장을 안 쓰는 모든 데스크톱)

KDE Plasma·XFCE·Sway·Hyprland 등에서는 ~/.xprofile 혹은 /etc/environment에 다음 세 줄을 직접 추가한다.

export GTK_IM_MODULE=unim
export QT_IM_MODULE=unim
export XMODIFIERS="@im=unim"

추가 후 로그아웃 → 다시 로그인. im-config -n unim 한 줄로도 같은 효과를 본다 (Debian 계열 한정).

2.3 GNOME + Wayland 사용자

GNOME Shell 위에서는 unim-gnome-extension이 키 가로채기·팝업을 책임진다. 환경변수가 아니라 GNOME Extension을 활성화한다.

gnome-extensions enable unim-gnome@from104.github.io

그리고 IBus와 충돌하지 않게 IBus는 비활성화 또는 제거한다.

sudo apt remove ibus

2.4 첫 한글 입력 (60초)

텍스트 에디터(예: GNOME Text Editor, Kate)를 연다.
한/영 키(또는 Shift+Space, 키보드별로 다름)를 누른다 — 트레이 아이콘이 「한」으로 바뀐다.
dkssud 입력 → 화면에 안녕이 뜬다.
한자 키(또는 F9)를 누르면 安寧 후보가 팝업으로 뜬다. 숫자 1~9로 선택.
한 번 더 한/영 키 → 영문 모드.

여기까지 동작하면 설치는 끝났다. 동작이 안 되면 트러블슈팅으로.

2.5 팝업 동작 개요

🐧 리눅스 — UNIM 0.3.0부터 한자·특수문자·이모지 팝업은 unim-popup-service 가 단일 렌더러로 처리한다.

환경	팝업 렌더 주체	비고
GNOME Wayland	GNOME Extension `popup_view.js` (St 위젯)	Mutter가 wlr-layer-shell 미지원이므로 extension 자체 렌더
GNOME X11 / KDE / Xfce / WM (X11)	`unim-popup-service` GTK4 윈도우	D-Bus auto-activation으로 자동 기동
Wayland (KDE Plasma 6 / Sway / Hyprland)	`unim-popup-service` GTK4 윈도우 (wayland-backend)	`libgtk4-layer-shell` 필요

공통 SoT: 환경과 무관하게 daemon의 PopupRender payload(셀·헤더·푸터·탭·하이라이트)가 단일 view-model로 모든 렌더러에 전달된다. 렌더 구현만 다를 뿐 동작은 동일하다.

외부 클릭 dismiss: 팝업 바깥 좌클릭 시 팝업이 닫히며, 클릭 이벤트는 아래 창에 그대로 전달된다. 팝업이 예상치 않게 닫혔다면 의도된 동작이다 — 트러블슈팅 §popup-dismiss 참고.

KDE Plasma 5.x Wayland 미지원: gtk4-layer-shell이 Ubuntu 24.04 표준 저장소에 없어 팝업이 표시되지 않는다. X11 세션 또는 GNOME으로 우회.

KDE Plasma 6 Wayland / Sway / Hyprland / river — 실험적, 검증 미흡: wayland-backend cargo feature + libgtk4-layer-shell 조합으로 빌드 시 이론상 동작하나, 0.3.0 QA 사이클 이후 v0.4.0까지 이 실험적 지위는 변하지 않았다(추가 검증 없음). popup 위치, IME 포커스 전환, layer-shell 좌표 변환에서 미세 회귀가 있을 수 있다. 자세한 환경별 지원 현황은 트러블슈팅 §G 환경 매트릭스 참고.

3. 환경별 설정 가이드

🐧 리눅스 — 데스크톱 환경과 앱 툴킷 조합에 따라 진입 경로가 갈린다.

환경	설치 방법	IM 모듈	팝업 주체	주의점
X11 + GTK 앱	`GTK_IM_MODULE=unim`	gtk3/gtk4 IM 모듈	`unim-popup-service`(GTK4, D-Bus auto-activation)	—
X11 + Qt 앱	`QT_IM_MODULE=unim`	qt5/qt6 IM 플러그인	동상	Plasma는 Qt 모드로 통일 권장
X11 + 레거시 (Emacs, xterm)	`XMODIFIERS=@im=unim`	xim 프론트엔드	XIM 자체 Xft 팝업	over-the-spot 모드
GNOME + Wayland	GNOME Extension 활성화	(앱은 텍스트-인풋-v3 직접)	GNOME Extension	IBus 제거 필수
KDE + Wayland	`QT_IM_MODULE=unim` + Wayland 프론트엔드	wayland	`unim-popup-service`(wayland-backend)	input-method-v2 사용
Sway/Hyprland (Wayland)	환경변수 + Wayland 프론트엔드	wayland	`unim-popup-service`(wayland-backend)	컴포지터의 input-method-v2 지원 필요

환경 판별: echo $XDG_SESSION_TYPE(x11/wayland), echo $XDG_CURRENT_DESKTOP(GNOME/KDE/sway).

3.1 Flatpak/Snap 앱에서 한글이 안 나올 때

GNOME+Wayland에서 Telegram, VS Code 같은 Flatpak/Snap 앱은 샌드박스 안에 UNIM IM 모듈이 없다. 호스트의 GTK_IM_MODULE=unim이 오히려 입력을 막는다.

자동 처리: unim-daemon이 GNOME+Wayland를 감지하면 시작 시 자동으로 Flatpak 전역 override를 설정해 IM 환경변수를 비운다. Flatpak 앱은 Wayland text-input-v3 → GNOME Extension 경로로 동작한다.

수동 설정(자동 설정이 동작하지 않을 때):

flatpak override --user --env=QT_IM_MODULE= --env=GTK_IM_MODULE=

Snap 앱에는 전역 override 메커니즘이 없으니 ~/.profile에 조건부로 환경변수를 비우는 스크립트를 추가한다 — README §1.7 참고.

4. 일상 사용

4.1 한/영 모드 전환

키	동작	비고
한/영 키 (Hangul)	모드 토글	키보드에 따라 키 코드가 다름
`Shift+Space`	모드 토글 (대체)	모든 키보드에서 동작
오른쪽 Alt (RightAlt)	모드 토글 (`toggle_keys`에 추가한 경우)	이제 GTK·Qt·GNOME 포함 모든 환경에서 동작
트레이 아이콘 클릭	모드 토글 (마우스)	`unim-indicator`가 트레이에

모드 공유 방식(mode_sharing 설정, CLI 키 mode-sharing): 「전역 공유」/「앱별 독립」 중 선택. 「전역 공유」가 기본값이다 — 한 모드를 바꾸면 모든 창에 즉시 동기화된다. 터미널은 영어, 텍스트 에디터는 한글처럼 창마다 모드를 따로 유지하고 싶으면 「앱별 독립」으로 바꾼다.

접근성 — 비시각 사용 시 한/영 전환 비프를 켜라: 리눅스에는 화면 낭독기로 모드 전환을 능동 통지하는 기능이 없고, 전환 비프도 기본은 꺼짐이다(오탐지 방지를 위한 의도된 기본값). 화면을 보지 않고 입력한다면 다음 명령으로 켜 두는 것을 권장한다.
unim-cli config set toggle-announce-beep true
켜짐/꺼짐을 서로 다른 음높이로 구분해 알려 준다.

단, 모드 공유 방식에 따라 이 비프가 안 들릴 수 있다: 트레이 아이콘·GNOME 확장에서 모드를 바꿀 때 비프가 울리는 경로는 「전역 공유」에서만 동작한다(unim-dbus/src/engine_worker.rs:1766-1772). 「앱별 독립」으로 바꾸면 트레이 토글로는 현재 포커스 창의 모드가 실제로 안 바뀌므로(의도된 동작 — 잘못된 신호 방지) 이 경로의 비프가 무음 처리된다. 청각 신호에 의존해 한/영 전환을 확인한다면, 「앱별 독립」으로 바꾸는 순간 트레이 조작으로 나는 비프 신호를 잃는다는 점을 감안한다.

오른쪽 Alt로 토글: toggle_keys 설정에 RightAlt를 넣으면 오른쪽 Alt 키로 한/영을 전환할 수 있다. 예전에는 GTK·Qt·GNOME 확장이 오른쪽 Alt를 자체적으로 걸러내 이 환경들에서는 동작하지 않았지만(XIM·순수 Wayland는 원래 동작), 이제 토글 판정이 데몬으로 일원화되어 어디서나 똑같이 동작한다. AltGr(오른쪽 Alt를 AltGr로 쓰는 레이아웃)에는 영향이 없다. 단, 토글하는 순간 앱도 Alt 입력을 함께 받을 수 있어(예: 일부 앱의 메뉴바 포커스) 이 부작용이 싫으면 toggle_keys에서 RightAlt를 빼면 된다.

키 이름 표기: toggle_keys 에는 UNIM 이 아는 키 이름을 단독으로 적는다(기본값 Korean, RightAlt). 오타 교정 단축키(4.4)와 달리 한/영 전환키는 수정자 조합 표기(Ctrl+X)를 받지 않는다. 잘못 적으면 CLI 와 설정 앱이 저장 시 경고를 띄우고, 데몬 로그에도 파싱 실패가 기록된다 — 값 자체는 저장되지만 그 키는 조용히 죽지 않고 눈에 보인다.

4.2 한자 변환 (Hanja)

한자로 바꿀 한글을 입력 (예: 한국).
한자 키(또는 F9)를 누른다.
9칸 그리드 팝업이 뜬다 — 韓國, 漢國 등.
숫자 1~9로 직접 선택, 화살표로 이동, Enter로 확정, ESC로 취소.
후보가 9개 이상이면 마침표(.) 키로 9×9=81칸 확장 그리드로 토글. 화면 우상단에 ⊞/⊟ 아이콘으로 현재 모드 표시.

한자 키 지정: hanja_keys 기본값은 Hanja, F9 다. 한/영 전환키(4.1)와 마찬가지로 단일 키 이름만 받고 수정자 조합 표기는 쓸 수 없다. 잘못 적으면 CLI 와 설정 앱이 저장 시 경고를 띄우고 데몬 로그에도 파싱 실패가 기록된다.

페이지 이동 (마우스/키보드)

후보가 한 페이지(9칸 또는 81칸)를 넘으면 푸터에 ◀ / ▶ 버튼이 나타난다.

[◀]  page 2 / 5  [▶]  ⊞

마우스 좌클릭 ◀ : 이전 페이지, ▶ : 다음 페이지. 마지막에서 ▶을 누르면 첫 페이지로 wrap, 첫에서 ◀ 누르면 마지막으로 wrap.
키보드 ← / Page Up : 이전 페이지, → / Page Down : 다음 페이지. 동일하게 wrap-around.
후보가 한 페이지 안에 다 들어가면 ◀/▶ 버튼은 숨겨진다 (한 페이지짜리에 페이지 컨트롤이 보이는 혼란 방지).
페이지를 옮겨도 cursor의 행/열 위치는 유지된다 — 예: 81칸 grid에서 (3, 4) 셀을 보다가 ▶ 누르면 다음 페이지의 (3, 4) 셀이 선택된 상태로 표시.

약어 풀이: cursor란 현재 키보드 포커스가 가 있는 셀을 가리키는 시각 표시 (배경 하이라이트로 보인다).

우클릭 동작 — 환경별 차이

페이지 이동 ◀/▶ 버튼은 모든 프런트엔드에서 동일하게 동작하지만, **그리드 영역 위에서의 우클릭(마우스 오른쪽 버튼)**은 프런트엔드마다 의미가 다르다. 시각적 단축으로 활용하려면 자기 환경의 매핑을 알아 둬야 한다.

GNOME Shell 확장 (Wayland/X11 모두): ★ 즐겨찾기 토글 — 키보드 Space와 동일.
GTK IM 모듈 (gtk3 / gtk4): 다음 페이지 (wrap-around) — → / Page Down과 동일.
Qt IM 모듈 (qt5 / qt6): 다음 페이지 (wrap-around).
XIM (한자 / 특수문자 / 이모지 팝업 공통): 다음 페이지 (wrap-around).
그 외 (unim-popup-service Standalone, 순수 Wayland): 동작 없음 (정의되지 않음).

왜 GNOME만 다른가? GNOME Shell 확장은 후보 셀이 곧 Clutter.Actor라 셀 단위 우클릭 hit-test가 자연스럽다. 그래서 우클릭에 즐겨찾기를 매핑한 게 손이 덜 가는 단축이 된다. 반면 GTK/Qt IM 모듈과 XIM은 X11/Wayland override-redirect 윈도우라 셀 hit-test가 제한적이고, 우클릭으로 페이지를 넘기는 기존 관습(고전 IME 패턴)을 따른다.

정리: 어느 환경이든 ◀/▶ 마우스 버튼·키보드 ←/→·Space는 의미가 같다. 환경에 따라 달라지는 건 오직 그리드 본문에서의 우클릭뿐이다. 헷갈리면 키보드 단축키만 써도 모든 동작을 할 수 있다.

즐겨찾기 ☆/★

자주 쓰는 한자를 즐겨찾기에 등록할 수 있다. 후보에 포커스를 둔 상태에서 Space 키 → ☆(미등록) ↔ ★(등록) 토글.

등록된 한자는 HanjaCandidatesReordered DBus 시그널로 모든 열린 팝업이 즉시 갱신된다.

토글하면 한자가 자동으로 재정렬되며 cursor가 그 한자를 따라간다.

★ 등록 시: 그 한자가 1페이지 상단(★ 그룹)으로 promote되고 cursor가 그 위치(page 1, row 1)로 이동.
☆ 해제 시: 그 한자가 사전순 원위치로 demote되며 cursor가 그 자리(다른 페이지일 수 있음)로 점프. 점프해 도착한 셀이 140ms 동안 노란색(#f9e2af)으로 짧게 깜박인다(flash) — "별을 끄니 한자가 여기로 돌아갔구나"를 즉시 인지하게 만드는 시각 단서.

왜 flash가 등록(★ ON) 때는 없고 해제(★ OFF) 때만 있나? 등록은 cursor가 자연스럽게 1페이지 상단으로 따라가므로 시각 단서가 충분. 반면 해제는 다른 페이지로 점프할 때 사용자가 화면 변화를 놓치기 쉬워 flash로 위치를 찍어 준다.

4.3 특수문자 입력

한글 모드에서 자음(초성) 키 → 한자 키. 초성에 따라 카테고리가 달라진다.

초성	카테고리	예시
ㄱ	특수기호	`!`, `@`, `÷`, `≠`, `∞`
ㄴ	괄호류	`「」`, `『』`, `≪≫`
ㄷ	수학기호	`∂`, `∇`, `√`, `∫`
ㄹ	단위기호	`＄`, `％`, `℃`, `Å`
ㅁ	도형기호	`■`, `□`, `●`, `○`
ㅂ	선문자	`─`, `│`, `┌`, `┐`
ㅅ	한글 자모	`ㄱ`, `ㄴ`, `ㅏ`, `ㅑ`
ㅇ	원문자	`①`, `②`, `ⓐ`
ㅈ	괄호한글	`㈀`, `㈁`
ㅊ/ㅋ	괄호숫자	`⑴`, `⑵`
ㅌ	괄호영문	`⒜`, `⒝`
ㅍ	그리스문자	`Α`, `β`, `γ`
ㅎ	기타기호	`●`, `♨`, `☏`

예: ㅁ 입력 → 한자 키 → 도형기호 그리드 → 2 선택 → □ 커밋.

4.4 자동 오타 교정 (AutoTypeFix)

타자가 모드를 잘못 둔 채 친 글을 자동으로 되살리는 기능. 두 방향이 있다.

Forward (영→한): 한글 모드인 줄 알았는데 영문 모드라 gksrmf이 그대로 나가버린 경우 → 단어 경계(스페이스/구두점) 시점에 자동으로 한글로 교체.
Reverse (한→영): 반대로 ㅈㅐㅍㅁ처럼 한글로 영타를 친 경우 → wave로 교체.

억제 사전 (Blacklist) — 사용자 학습

특정 단어가 매번 잘못 교정되면 UNIM이 알아서 학습한다.

교정 결과가 마음에 안 들어 BackSpace로 지우고 모드를 전환한다 → UNIM이 「의심 단어」로 표시(Pending).
같은 단어가 또 교정 시도되면 → 그 시도를 억제하고 동시에 「승인 대기(Tentative)」로 등록.
설정 GUI 「억제 단어」 페이지에서 단어를 고르고 [선택 영구 활성] 을 누르면 Confirmed(영구 억제), 기본 4시간 동안 재트리거가 없으면 Inactive(만료). 만료 시간은 1~12시간 사이로 조절할 수 있다.

저장 위치: ~/.config/unim/typefix-blacklist.yaml. 데몬은 mtime 감시로 자동 리로드한다.

사용자 사전 (역방향 화이트리스트): 0.2.0 신규. 텍스트 선택 후 단축키로 RegisterUserDictFromSelection DBus 메서드 호출 → 영어 사전 항목으로 등록. 설정 GUI 「사용자 사전」 페이지에서 추가/제거/수정.

토글 단축키 — 지정한 키로 즉시 켜고 끄기

키 하나로 자동 오타 교정을 바로 켜고 끌 수 있다. 전체 토글의 기본값은 Shift+F8 이고, 순방향·역방향 전용 단축키는 비어 있다(필요한 사람만 지정). 세 가지를 각각 따로 둔다.

전체 토글: 자동 오타 교정 전체(마스터 스위치)를 켜고 끈다.
순방향(=정방향) 토글: 순방향(영→한) 교정만 켜고 끈다. (일부 GUI 라벨은 "정방향"으로 표기하지만 같은 뜻이다.)
역방향 토글: 역방향(한→영) 교정만 켜고 끈다.

CLI로 지정한다.

# 기본값 (전체 토글 = Shift+F8)
unim-cli config set auto-typefix-toggle-keys "Shift+F8"

# 순방향/역방향을 각각 F10, F11 로
unim-cli config set auto-typefix-forward-toggle-keys F10
unim-cli config set auto-typefix-reverse-toggle-keys F11

# 여러 키를 쉼표로 (그중 아무거나 누르면 토글)
unim-cli config set auto-typefix-toggle-keys "Shift+F8,Ctrl+Left"

# 해제 — 빈 값을 주면 어떤 키도 가로채지 않는다
unim-cli config set auto-typefix-toggle-keys ""

설정 GUI(unim-settings, 5.2) 에서는 세 칸이 오타 교정 페이지의 「토글 단축키」 그룹에 나란히 모여 있다.

레거시 GTK 다이얼로그(unim-settings-gtk, 앱 메뉴에는 숨겨져 있음 — §5 참고)에서는 세 칸이 한 그룹에 모여 있지 않고 각 기능 그룹에 나뉘어 배치돼 있다 — 전체 토글은 「오타 교정」 마스터 그룹(전체 켜기·끄기 스위치 옆), 순방향(정방향) 토글은 「순방향」 그룹, 역방향 토글은 「역방향」 그룹에 각각 놓인다.

수정자 조합을 쓸 수 있다 — Shift+F8, Ctrl+Left, Ctrl+Shift+F7 처럼 적는다(Ctrl/Control, Alt, Super/Win/Meta, Shift. 대소문자·순서 무관). 수정자 없이 F10 처럼 적으면 종전대로 그 키 단독으로만 발동한다. 구분자는 + 가 정식이고, + 가 하나도 없는 표기에서는 - 도 허용한다(Ctrl-F8 = Ctrl+F8). 단, Ctrl+Shift-F8 처럼 혼용하면 무효다.

표기한 수정자가 정확히 눌렸을 때만 발동한다. 그래서 지정하지 않은 조합(예: Shift+F10 컨텍스트 메뉴)은 UNIM 이 가로채지 않고 앱으로 그대로 간다.

기본값은 Shift+F8 이다 — F9~F11 은 미디어 키나 리매핑(잘라내기/복사/붙여넣기 등)으로 OS 에 도달하지 못하는 키보드가 있어 피했다. 한자/이모지 키(맨 F9)와는 키가 달라 충돌이 없고, Shift+F9 처럼 F9 조합을 지정해도 맨 F9 팝업은 그대로다.

키 이름은 F1~F12 처럼 UNIM 이 아는 이름이어야 한다(ScrollLock·Pause·PrintScreen·Menu 는 인식하지 않는다). 잘못 적으면 CLI 와 설정 앱이 저장 시 경고를 띄우고, 데몬 로그에도 파싱 실패가 기록된다 — 조용히 무시되지 않는다.

쓰지 않으려면 목록을 비운다(""). 그러면 그 단축키는 아무 키도 소비하지 않는다.

GNOME(Wayland)에서는 Ctrl+Left 같은 Ctrl/Alt/Super 조합도 동작한다 — UNIM 확장이 토글 조합을 엔진으로 전달한다(확장 업데이트 후 재로그인 필요).

Windows(TSF)에서도 조합 표기가 리눅스와 동일하게 동작한다 — 기본값 Shift+F8 그대로 쓰면 된다.

전체가 꺼진 상태에서 순방향만 토글로 켜도 실제 교정은 전체를 다시 켜야 발동한다(전체가 마스터 스위치). 순방향/역방향 토글은 각 방향의 플래그만 바꾼다.

접근성 참고: toggle-announce-beep 설정을 켜면 이 토글도 한/영 전환과 같은 차등 비프(켜짐=상승음/꺼짐=하강음)로 상태를 알려 준다 — Windows·Linux 공통이다(리눅스는 daemon 이 paplay/pw-cat/aplay 중 PATH 에서 찾은 재생기로 소리를 낸다. 셋 다 없으면 무음 no-op). 기본값은 꺼짐 — 4.1 접근성 안내 참고.

비밀번호 필드 자동 보호

비밀번호·PIN 입력 칸에서는 자동 오타 교정이 자동으로 꺼진다. 앱이 "이 칸은 비밀번호"라고 알려 주면(content_purpose) UNIM 은 그 칸에 머무는 동안 순방향·역방향 교정을 모두 멈추고, 이미 쌓인 키 관측 버퍼·되돌리기 기록도 지운다. 덕분에 dkssud처럼 친 비밀번호가 한글로 자동 교정돼 값이 깨지는 일이 없다.

칸을 벗어나면 즉시 원래대로 돌아온다. 수동으로 토글해 둔 켜짐/꺼짐 상태는 그대로 유지된다 — 비밀번호 보호는 그 위에 잠깐 덮이는 안전장치일 뿐이다.
이 보호는 앱이 비밀번호 칸임을 알려 줄 때 동작한다. 알려 주지 않는 일부 환경(XIM 레거시 앱, content-purpose 를 보내지 않는 일부 Wayland 컴포지터·웹폼)에서는 자동 감지가 안 될 수 있다 → FAQ Q9 참고.
제보 바란다. 어떤 앱이 비밀번호 칸을 제대로 알려 주고 어떤 앱이 안 알려 주는지, 아직 사례가 충분히 모이지 않았다. 리눅스·Windows 양쪽 다 마찬가지라 앱별 대응이 다 들어가 있지 못하다. 비밀번호 칸에서 교정이 발동하는 앱을 만나면 앱 이름·버전과 함께 GitHub Issues 로 알려 주면 그 앱을 대응 목록에 넣을 수 있다.

4.5 자동 영문 모드 전환 (Auto-English-Mode)

vim 명령 모드(Esc), CLI 슬래시 명령(/) 같은 비한글 컨텍스트에 들어갈 때 자동으로 영문으로 전환되게 하는 opt-in 기능. 기본 비활성.

활성화: 설정 GUI → 「일반」 → 「자동 영문 전환」 그룹 → 자동 영문 전환 사용 ON.
트리거 키: 기본은 Escape, Slash. 필요 시 ShiftSemicolon(:), ShiftSlash(?) 같은 가상 이름을 추가.
동작: 한글 모드에서 트리거 키를 누르면 (1) 조합 commit → (2) 영문 모드로 영구 전환 → (3) 트리거 키 자체는 그대로 앱에 전달.

한/영 토글 키와 트리거 키가 겹치면 토글 분기가 우선이라 자동 전환이 발동하지 않는다. 비밀번호 필드는 이미 강제 영문이라 영향 없음.

트리거 표기: key:<키이름> / char:<문자> 형식으로 적는다(예: key:Escape, char:/). 접두사 없는 옛 표기(Escape)도 그대로 인식하고, key:Ctrl+B 같은 수정자 조합도 쓸 수 있다. 잘못 적으면 CLI 와 설정 앱이 저장 시 경고를 띄우고, 데몬 로그에도 파싱 실패가 기록된다 — 조용히 무시되지 않는다.

4.6 단어 단위 입력 (조합 확정 단위)

기본은 음절 단위 확정 — 한 글자가 완성되면 바로 확정된다. 단어 단위로 두면 스페이스·구두점 같은 단어 경계까지 조합을 밑줄(preedit) 로 누적했다가 한 번에 확정한다. 조합 도중 BackSpace 는 자모 단위로 되돌아가고, 자동 오타 교정(4.4)의 역방향 교정과도 더 자연스럽게 맞물린다.

세 가지 값이 있다.

음절 (syllable): 항상 음절 단위 확정. 가장 예측 가능.
단어 (word): 모든 대상 앱에서 단어 단위 누적.
스마트 (smart, 기본): word-mode-apps 목록에 등록된 앱에서만 단어 단위, 그 외에는 음절 단위. 기본 목록은 winword.exe(Windows) 뿐이라 리눅스에서는 아무것도 등록하지 않으면 사실상 음절 단위로 동작한다(무회귀).

영문 입력에는 적용되지 않는다 — 의도된 동작이다. 확정 단위는 한글 조합에만 걸린다. 그래서 한영을 섞어 쓰면 한글 부분에만 밑줄이 생기고 영문은 친 즉시 확정된다. 밑줄이 들쭉날쭉해 보이는 건 그 때문이지 설정이 잘못된 게 아니다.

한글의 밑줄은 ㅎ+ㅏ+ㄴ 이 모여 한 이 되는 조합 과정을 보여주는 표시다. 영문은 키 하나가 곧 글자 하나라 조합할 것이 없어 표시할 것도 없다. 영문까지 밑줄로 묶으면 앱이 그 글자를 "아직 확정되지 않은 것"으로 취급해 자동완성·맞춤법 검사·실시간 검색이 멈추고, 한 글자짜리 단축키(브라우저·편집기의 j·t 같은 키)가 먹히지 않는다. 얻는 것 없이 잃는 것만 커서 적용하지 않는다.

켜는 법

# 전역 단어 단위
unim-cli config set commit-unit word

# 스마트 + 특정 앱만 단어 단위 (예: LibreOffice)
unim-cli config set commit-unit smart
unim-cli config set word-mode-apps "winword.exe,soffice"

설정 GUI 에서는 「일반」 → 「입력 모드」 그룹의 조합 확정 단위 콤보에서 고른다. word-mode-apps 는 CLI/config.yaml 로 편집한다(정확일치, 대소문자 무시). 리눅스 앱 ID 예시: LibreOffice soffice, 앱 ID 는 창별 독립 모드에서 로그로 확인할 수 있다.

적용되지 않는 경우 (안전장치)

터미널 (ghostty·kitty·wezterm·alacritty·foot·gnome-terminal·konsole·xterm 등): preedit 이 취약해 항상 음절 단위.
XIM (xterm 계열 레거시 앱): 구조적으로 단어 단위 불가 — 항상 음절 단위.
순수 Wayland·Flatpak/Snap(ibus): 앱 식별이 안 돼 현재는 제외(음절 단위).
모아치기(동시치기) 를 켠 상태: 단어 단위와 양립하지 않아 항상 음절 단위로 동작한다.

단어 단위에서 자동 오타 교정 역방향(한→영)은 조합만 교체하고 앞선 확정 텍스트는 건드리지 않는다. 위 비대상 경우에는 자동으로 음절 단위로 내려가므로 데이터 손실 걱정 없이 켜 두어도 된다.

5. 설정 GUI 투어

unim-settings(Slint, 리눅스·Windows 공통 단일 코드베이스)가 유일한 설정 진입점이다. 즉 아래 4개 페이지의 구성과 항목은 양쪽 운영체제가 동일하다 — 다른 것은 창을 여는 방법뿐이다.

🐧 리눅스에서 여는 법 — 앱 메뉴의 「UNIM 설정」 항목, 첫 실행 마법사, 트레이 메뉴가 모두 이 실행 파일을 띄운다. 터미널에서 직접 띄워도 된다.

unim-settings &

레거시 GTK 다이얼로그(unim-settings-gtk)에 관해: GTK4+libadwaita로 짠 예전 설정창은 계속 패키지에 포함되지만 앱 메뉴에는 더 이상 노출되지 않는다(.desktop 파일에 NoDisplay=true). 직접 unim-settings-gtk &로 띄울 수는 있으나 신규 설정 항목이 이쪽에는 반영되지 않을 수 있다 — 위 unim-settings를 기준으로 삼는다. Qt 다이얼로그(unim-gui-qt)는 이미 폐기됐고, 트레이 아이콘은 unim-indicator, 한자·특수문자·이모지 팝업은 unim-popup-service가 각각 별도 프로세스로 담당한다(§2.5 참고).

페이지 구성 (좌측 내비게이션 4개):

5.1 페이지 1 — 일반

그룹	항목	비고
자판 옵션	한글 자판 / 영문 자판	`ko_2bulstd`(두벌식 표준) 등 — §7.1 참고. 자판별 동적 옵션(예: 세벌식 390의 순아래받침)도 이 그룹에 나타난다
	한글 확정 단위	`음절`/`단어`/`스마트` — 4.6 참고
입력 모드	시작 입력 모드	데몬 시작 시 한글/영문 중 어느 쪽으로 켤지
	모드 공유	`전역 공유`(기본) / `앱별 독립` — 4.1 참고
	앱별 규칙	특정 앱(창 식별자·클라이언트 이름 부분 일치)에서 항상 지정 모드로 시작하도록 규칙 추가. 「모드 공유=앱별 독립」일 때 효과가 크다
자동 영문 전환	사용 스위치 + 트리거 키	기본 OFF — 4.5 참고
접근성	원클릭 프리셋 (「한 손 사용」/「넉넉한 타이밍」) + 개별 스위치	아래 설명 참고

접근성 프리셋: 「한 손 사용」은 세벌식 순아래 자판 + 비수정자 토글키 + 모아치기 끔 + 자동반복 억제를 한 번에 적용한다. 「넉넉한 타이밍」은 자동반복 억제 + 오타 교정 판정 시간 확대 + (지원 자판이면) 모아치기 조합창을 넉넉하게 잡는다. 프리셋 적용 후에도 개별 스위치로 세부 조정할 수 있다.

조합키 자동반복 억제(접근성): 키를 계속 누르고 있으면 운영체제가 같은 키를 빠르게 반복 입력하는데(자동 반복), 이 옵션을 켜면 데몬이 그 반복을 무시한다. 손 떨림 등으로 키를 오래 누르게 되는 지체장애 사용자를 위한 기능이며, Windows·Linux 공통으로 데몬이 집행한다(과거 리눅스에서는 미집행이었으나 v0.4.0에서 정정). 억제 대상은 한/영 토글 키와 한글 모드의 문자 키이며, 백스페이스·방향키 같은 편집키와 영문 직접 입력의 반복은 그대로 둔다. Wayland·Qt5/6·GNOME 확장에서는 반복 여부를 정확히 가려내고, GTK3/4·XIM·ibus 호환 경로에서는 80ms 시간창으로 근사 판정하므로 첫 반복 1회는 통과될 수 있고 시스템 키 반복 간격을 80ms보다 길게 잡았다면 걸러지지 않을 수 있다(어느 경우든 "덜 막는" 쪽으로 안전하게 동작). 기본값은 꺼짐이며, unim-cli config set ignore-key-repeat true 로도 켤 수 있다. GNOME 확장 사용자는 재로그인 후 적용된다.

이모지 입력은 별도 스위치가 없다 — 한자 팝업과 같은 경로로 항상 켜져 있으며, 키보드 단축키 가이드 의 Super+.(또는 등록한 단축키)로 호출한다.

GNOME 확장 전용 설정(패널 인디케이터 표시 여부, 수동 변환 단축키 등)은 이 앱이 아니라 gnome-extensions prefs unim-gnome@from104.github.io 로 별도로 연다 — 키보드 단축키 가이드 GNOME 절 참고.

5.2 페이지 2 — 오타 교정

그룹	항목	비고
활성화	자동 오타 교정 사용	마스터 스위치. OFF면 순방향·역방향 둘 다 정지
교정 강도	보수적 / 표준 / 적극적 프리셋	임계값·단어 길이·감지창을 한 번에 맞춘다. 세부값은 아래 「고급 설정」에서 직접 조정 가능
교정 방향	정방향 사용 / 역방향 사용	각각 독립적으로 켜고 끌 수 있다 — 4.4 참고
토글 단축키	전체 켜기·끄기 / 정방향 켜기·끄기 / 역방향 켜기·끄기 (세 칸 한 그룹)	지정한 키로 즉시 토글. 비우면 사용 안 함. `Shift+F9`처럼 수정자 조합 가능 — 4.4 참고
고급 설정(펼침)	한글 음절 임계값 / 영문 단어 최소 길이 / 정방향·역방향 감지창(ms) / 임시 항목 만료(시간) / 관찰 타임아웃(초) — 전부 슬라이더	대부분은 위 「교정 강도」 프리셋으로 충분하다
옵션(고급 설정 안)	영어 단어는 교정 건너뛰기 / 완성된 음절은 교정 건너뛰기 / 되돌리기(롤백) 감지 / 사용자 사전 사용	—
—	기본값으로 복원	오타 교정 설정을 초기값으로 되돌린다(5초 안에 취소 가능)

5.3 페이지 3 — 교정 억제 단어

한 개의 목록에 임시(Tentative)·확정(Confirmed)·비활성(Inactive) 세 상태의 억제 단어가 함께 표시된다(상태별 표시로 구분, 예전 GTK 다이얼로그의 3개 섹션 구성과는 다르다). 선택한 항목을 「선택 영구 활성」(확정으로 승격) 또는 「선택 삭제」할 수 있고, 「모두 삭제」로 전체를 비울 수도 있다(5초 안에 되돌리기 가능).

데몬이 파일을 갱신해도 GUI가 즉시 반영한다. 따로 리로드 안 해도 된다.

5.4 페이지 4 — 사용자 사전 (역방향 화이트리스트)

「단어」+「메모(선택)」를 입력해 [추가]하면 영어 단어 ↔ 한글 시퀀스 매핑이 등록된다. 예: wave ↔ ㅈㅐㅍㅁ. 아래 목록에서 선택 후 [선택 삭제]로 제거한다. reverse 교정에서 우선 매칭.

5.6 자판 도구 (Keymap Studio / Typing Practice)

설정 GUI와 별개로, 자판을 눈으로 보고·편집하고·연습하는 두 GTK4 도구가 함께 설치된다. 각자 고유 아이콘으로 앱 목록에 등록된다(io.github.from104.unim.KeymapStudio, io.github.from104.unim.TypingPractice).

unim-keymap-studio &      # 자판 보기·편집
unim-typing-practice &    # 타자 연습

5.6.1 unim-keymap-studio — 자판 보기·편집

한국어/영문 자판이 키마다 어떤 자모·문자를 내는지 시각적으로 확인하고, 사용자 자판을 만든다.

헤더 3단 드롭다운: 「언어 > 출처 > 자판」 순서로 좁혀 선택. 예: 한국어 > 사용자 정의 > my_3bul_variant.
4개 탭: 「기본」(메타 정보) · 「자판」(키별 매핑 그리드) · 「조합」(자모 결합 규칙) · 「확장」(rule_set 토글). 「조합」·「확장」 탭은 한글 자판을 선택했을 때만 나타난다 (영문 자판에는 자모 조합 개념이 없으므로).
헤더 우측 버튼: [도움말] (F1) · [설정] · [메뉴].
저장 정책: 빌트인 자판은 읽기 전용이라 「다른 이름으로 저장」만 가능. 사용자 자판은 「저장」 + 「다른 이름으로 저장」 둘 다 된다. 새로 만든 사용자 자판은 ~/.config/unim/layouts/ 에 JSON으로 떨어지고, 데몬이 자동 스캔해 설정 GUI 자판 목록에 나타난다. 이 JSON 파일을 손으로 고친 경우에는 다음번 설정 저장(어떤 항목이든) 또는 재로그인 때 반영된다 — 데몬이 자판 파일 자체를 감시하지는 않는다.

단축키

키	동작
F1	도움말
Ctrl + N	새 자판
Ctrl + D	현재 자판 복제
Ctrl + S	저장 (사용자 자판)
Ctrl + Shift + S	다른 이름으로 저장
Ctrl + E	내보내기 (export)
Ctrl + I	가져오기 (import)
Ctrl + 1 / 2 / 3 / 4	탭 전환 (기본 / 자판 / 조합 / 확장)

5.6.2 unim-typing-practice — 타자 연습

현재 활성 자판(데몬이 쓰는 자판)으로 타자 연습을 한다. 자판을 바꾸면 자동으로 다시 로드된다.

측정 지표: WPM(분당 단어), CPM(분당 글자), 정확도, 그리고 오타 히트맵 — 어떤 키에서 실수가 잦은지 키보드 위에 색으로 표시.
연습 글감: 내장 단어/문장 외에 파일(Ctrl+O)이나 클립보드(Ctrl+Shift+V)에서 가져올 수 있다.
keymap-studio와 동일한 5행 키보드 위젯을 공유하므로 보이는 자판이 일관된다.

단축키

키	동작
F1	도움말
Ctrl + R	다시 시작 (재시작)
Ctrl + Shift + C	결과 복사
Ctrl + 1	연습 화면
Ctrl + 2	결과 화면
Ctrl + O	파일에서 글감 가져오기
Ctrl + Shift + V	클립보드에서 글감 가져오기

6. 키 매핑 치트시트

🐧 리눅스

상황	키	결과
어디서나	한/영 (또는 Shift+Space)	모드 토글
한글 모드, 글자 입력 후	한자 (F9)	한자 팝업
한자 팝업	숫자 1~9	직접 선택
한자 팝업	화살표	후보 이동
한자 팝업	`←`/`→` 또는 PageUp/PageDown	페이지 이동 (wrap-around)
한자 팝업	마우스 ◀ / ▶	페이지 이동 (wrap-around, 단일 페이지면 숨김)
한자 팝업	마우스 우클릭	환경별 차이: GNOME=★ 즐겨찾기 토글 / GTK·Qt IM·XIM=다음 페이지 / 기타=동작 없음 (§4.2)
한자 팝업	Enter	포커스 항목 확정
한자 팝업	ESC	취소
한자 팝업	`.` (마침표)	9칸 ↔ 81칸 토글
한자 팝업	Space	즐겨찾기 ☆/★ 토글 (해제 시 cursor 셀 140ms flash)
한글 모드, 자음만 입력	한자 (F9)	특수문자 팝업
한글 입력 중	BackSpace	마지막 자모 1개 삭제
forward 교정 후 후회	BS + 한/영	Tentative 학습 트리거
자동 영문 모드 활성 시	`Esc` 또는 `/`	영문 강제 전환 + 키 전달

7. CLI 사용법 (`unim-cli`)

CLI는 두 용도. (1) 한↔영 변환 필터, (2) 설정 관리.

7.1 변환 필터

# 영타를 한글로 (compose, 기본 모드)
echo "dkssudgktpdy" | unim-cli
# → 안녕하세요

# 한글을 영타로 (decompose)
echo "안녕하세요" | unim-cli -d
# → dkssudgktpdy

# 자판 지정
echo "ekswn" | unim-cli -k 2bul       # 두벌식 (기본)
echo "j;ax" | unim-cli -k 390         # 세벌식 390

# 파일 입출력
unim-cli -o out.txt input.txt

지원 자판:

한국어: 2bul, 390, 391, noshift
영어: qwerty, dvorak, colemak, colemak_dh, workman

7.2 설정 관리

# 현재 설정 전체 보기 (grep으로 특정 키만 확인해도 된다)
unim-cli config show

# 값 설정 — 키 이름은 케밥 표기(하이픈)만 받는다
unim-cli config set auto-typefix true
unim-cli config set auto-typefix-tentative-expiry-hours 6
unim-cli config set auto-english true

# 조합 확정 단위 (음절/단어/스마트) — 4.6 참고
unim-cli config set commit-unit word

# 자동 오타 교정 토글 단축키 (쉼표 구분, 수정자 조합 가능) — 4.4 참고
unim-cli config set auto-typefix-toggle-keys "Shift+F8"
unim-cli config set auto-typefix-forward-toggle-keys F10
unim-cli config set auto-typefix-reverse-toggle-keys F11

# 자판 프로필 관리
unim-cli config layout list                    # 내장 + 사용자 프로필 목록
unim-cli config layout describe ko_3bul390     # 프로필 상세
unim-cli config layout validate my.json        # 사용자 정의 자판 검증

설정 변경은 데몬에 즉시 반영된다. config.yaml ↔ unim-cli ↔ 설정 GUI(unim-settings) 3지점이 항상 싱크되도록 설계됐다.

한 가지 예외 — 자판을 바꾸는 순간 글자를 조합 중이라면: 새 자판은 지금 조합 중인 글자가 끝난 뒤부터 적용된다(음절 하나가 아니라 밑줄이 사라질 때까지 = 단어 단위 확정을 쓰면 단어 경계까지). 조합을 중간에 끊어 글자를 망가뜨리지 않으려는 의도된 동작이다. 바로 확인하고 싶으면 스페이스나 Esc로 조합을 끝낸 뒤 입력하면 된다.

8. 설정 파일 위치 / 백업

파일	용도	백업 권장
`~/.config/unim/config.yaml`	일반 설정 (자판·모드·자동 영문 등)	YES
`~/.config/unim/typefix-blacklist.yaml`	학습된 교정 억제 사전	YES
`~/.config/unim/typefix-userdict.yaml`	reverse 사용자 사전	YES
`~/.config/unim/layouts/*.json`	사용자 정의 자판 v1 프로필	YES
`~/.unim-errors.log`	디버그 로그 (`UNIM_DEVELOP=1` 시)	NO (휘발)

# 통째 백업
tar -czf unim-backup-$(date +%F).tar.gz -C ~/.config unim
# 복원
tar -xzf unim-backup-2026-04-26.tar.gz -C ~/.config
systemctl --user restart unim-daemon

9. 다음 단계

동작이 이상하다 → 트러블슈팅
다른 IME와 비교 / 안정성 / 마이그레이션 → FAQ
판별 변경 내역 → 변경 이력
기여하고 싶다 → CONTRIBUTING.md
핵심 동작 명세 → IME_BEHAVIOR.md, docs/dev/specs/POPUP_SPEC.md

문서 버전: 0.4.0 / 작성일: 2026-08-01 / 라이선스: 본문 라이선스는 프로젝트와 동일.

▲ 목차로

키보드 단축키 가이드

🐧 리눅스

UNIM의 단축키는 환경(데스크톱/컴포지터)에 따라 캡처 주체가 달라집니다. 이 문서는 사용자가 환경별로 어떻게 단축키를 활성화해야 하는지 설명합니다.

영문 버전: README.md

GNOME 전용 — 수동 변환 단축키 (기본 활성)

GNOME Shell(unim-gnome-extension)에서는 아래 세 단축키가 별도 설정 없이 기본으로 켜져 있다. 다른 데스크톱/컴포지터(KDE, Sway, Hyprland 등)에는 이 단축키가 없다 — GNOME 확장이 Main.wm.addKeybinding으로 Shell 자체에 등록하는 GNOME 전용 기능이기 때문이다.

단축키	동작	예시
`Super+K`	포커스된 단어를 영어 → 한글로 변환 후 교체	`gksrmf` → `한글`
`Shift+Super+K`	포커스된 단어를 한글 → 영어로 변환 후 교체	`ㅗ디ㅣㅐ` → `hello`
`Super+E`	선택 영역을 읽어 역방향(한→영) AutoTypeFix 사용자 사전에 등록	`ㅎㅑㅅ` 선택 → `git` 으로 등록

이 세 단축키는 4.4 자동 오타 교정의 자동 교정과는 별개로, 사용자가 직접 트리거하는 수동 변환이다. Super 조합을 다른 용도로 쓰고 있거나 충돌이 난다면, 다음 명령으로 확장 설정을 열어 바꾸거나 끌 수 있다.

gnome-extensions prefs unim-gnome@from104.github.io

「변환 단축키」 그룹에서 Super+K/Shift+Super+K, 「사용자 사전 등록」 그룹에서 Super+E 를 각각 재지정하거나 빈 값으로 비워 끌 수 있다.

이모지 팝업 단축키 (`Super+.`)

UNIM은 마지막 활성 입력 위치에 이모지 팝업을 띄우는 기능을 제공합니다. 기본 단축키는 Super+.(Meta+.)입니다. 다만 단축키를 누가 캡처하느냐가 환경별로 다르기 때문에, 일부 환경에서는 사용자가 직접 등록해야 합니다.

환경별 동작 매트릭스

환경	자동 동작?	등록 방법
X11 / XIM	자동	unim 데몬이 X server로부터 redirect 받아 직접 매칭
Wayland + GNOME	자동	UNIM GNOME extension이 `Main.wm.addKeybinding`으로 처리
Wayland + KDE Plasma	직접 등록 필요	KCM Custom Shortcuts
Wayland + Hyprland	직접 등록 필요	`hyprland.conf`
Wayland + Sway	직접 등록 필요	`sway/config`
Wayland + Wayfire	직접 등록 필요	`wayfire.ini`
Wayland + 기타 컴포지터	직접 등록 필요	컴포지터별 단축키 도구

왜 직접 등록이 필요한가?

Wayland 컴포지터(KDE/Hyprland/Sway/Wayfire 등)는 Super 같은 modifier 조합 키를 자체 단축키 시스템에서 우선적으로 가로챕니다. 이 단계에서 컴포지터가 단축키를 소비해 버리면 입력기(IME)에는 키 이벤트 자체가 도달하지 않습니다.

GNOME에서는 UNIM의 GNOME 확장이 Shell 측 단축키 슬롯에 등록되어 자동 동작합니다. 그러나 다른 컴포지터에는 그런 확장이 없으므로, 컴포지터의 단축키 시스템에 unim-cli trigger emoji_popup 명령을 단축키로 직접 등록해야 합니다.

공통 명령

unim-cli trigger emoji_popup

내부적으로 이 명령은 데몬의 DBus 인터페이스 org.atit.unim.InputMethod의 TriggerAction RPC를 호출합니다. 데몬이 이 신호를 받으면, 마지막으로 활성화되어 있던 입력 컨텍스트(가장 최근에 사용한 텍스트 위젯) 위에 이모지 팝업을 띄웁니다.

향후 다른 액션(hanja_popup 등)도 같은 패턴으로 추가될 예정입니다.

환경별 등록 방법

KDE Plasma 6 (Wayland)

System Settings → Shortcuts → Custom Shortcuts 열기
좌하단 Edit → New → Global Shortcut → Command/URL
이름: Trigger UNIM emoji popup (자유롭게 지정)
Trigger 탭 → 단축키 입력란에 Meta+. 입력
Action 탭 → Command/URL: unim-cli trigger emoji_popup
Apply

Plasma 5 계열에서도 메뉴 경로만 다를 뿐 동일하게 동작합니다. (System Settings → Shortcuts → Custom Shortcuts)

Hyprland

~/.config/hypr/hyprland.conf 에 다음 줄을 추가하세요.

bind = SUPER, period, exec, unim-cli trigger emoji_popup

설정 파일은 자동 reload되며, 적용을 강제하려면 hyprctl reload를 실행하세요.

Sway

~/.config/sway/config 에 다음 줄을 추가하세요.

bindsym Mod4+period exec unim-cli trigger emoji_popup

Mod4는 Super(Windows) 키입니다. 적용은 swaymsg reload.

Wayfire

~/.config/wayfire.ini 의 [command] 섹션에 두 줄을 추가하세요.

[command]
binding_emoji = <super> KEY_DOT
command_emoji = unim-cli trigger emoji_popup

설정 변경 시 자동 reload됩니다.

GNOME (확장 없이 사용할 때 fallback)

UNIM GNOME 확장을 설치/활성화한 경우 별도 설정이 필요 없지만, 확장을 쓰지 않는다면 GNOME 자체 단축키 시스템으로 같은 효과를 낼 수 있습니다.

Settings → Keyboard → View and Customize Shortcuts
Custom Shortcuts → Add Shortcut
Name: UNIM Emoji Popup
Command: unim-cli trigger emoji_popup
Set Shortcut: Super+. 누르기 → Add

GNOME에서는 일부 Super 조합이 시스템 예약입니다. 충돌이 나면 다른 키 조합(예: Ctrl+Alt+E)을 시도하세요.

X11 + 임의 WM (xbindkeys)

X11/XIM 환경에서는 데몬이 자동 매칭하므로 보통은 별도 등록이 필요 없습니다. 하지만 데몬이 단축키를 받지 못하는 환경(특정 게임 모드, 일부 화면 전환 도구 등)에서는 xbindkeys로 보강할 수 있습니다.

~/.xbindkeysrc 에 다음을 추가하세요.

"unim-cli trigger emoji_popup"
  Mod4 + period

적용:

xbindkeys -p   # 기존 인스턴스 종료
xbindkeys      # 다시 시작

동작 확인

단축키를 설정한 뒤 정상 동작하는지 확인하려면 데몬 로그를 보세요.

journalctl --user -f | grep unim

또는 systemd 서비스로 실행 중이라면:

journalctl --user -u unim-daemon -f

단축키를 누른 직후 다음과 비슷한 메시지가 보이면 성공입니다.

[DBus] TriggerAction(emoji_popup) 수신

만약 메시지가 보이지 않는다면:

which unim-cli 로 CLI 경로 확인
unim-cli trigger emoji_popup 을 터미널에서 직접 실행했을 때 에러가 없는지 확인
systemctl --user status unim-daemon 으로 데몬이 실행 중인지 확인
컴포지터의 단축키 충돌 확인 (다른 앱이 같은 키를 점유했을 수 있음)

자판 도구 앱 내부 단축키

위 Super+. 는 데스크톱 전역 단축키지만, 함께 설치되는 두 GTK4 자판 도구는 앱 창 안에서만 동작하는 자체 단축키를 가집니다(컴포지터 등록 불필요). 자세한 사용법은 사용자 매뉴얼 §5.6.

unim-keymap-studio (자판 보기·편집)

키	동작
F1	도움말
Ctrl + N	새 자판
Ctrl + D	현재 자판 복제
Ctrl + S	저장 (사용자 자판)
Ctrl + Shift + S	다른 이름으로 저장
Ctrl + E	내보내기
Ctrl + I	가져오기
Ctrl + 1 / 2 / 3 / 4	탭 전환 (기본 / 자판 / 조합 / 확장)

unim-typing-practice (타자 연습)

키	동작
F1	도움말
Ctrl + R	다시 시작
Ctrl + Shift + C	결과 복사
Ctrl + 1	연습 화면
Ctrl + 2	결과 화면
Ctrl + O	파일에서 글감 가져오기
Ctrl + Shift + V	클립보드에서 글감 가져오기

참고

X11/XIM에서는 X server가 modifier 키 조합을 IM에 redirect 해주기 때문에 자동 동작합니다.
Wayland에서는 그런 redirect 메커니즘이 표준화되어 있지 않아 컴포지터 협조가 필요합니다.
향후 추가될 액션은 unim-cli trigger <action> 형태로 동일하게 등록할 수 있습니다.

UNIM FAQ (한국어)

UNIM 0.4.4에 대해 사람들이 정말 자주 묻는 질문 모음. 답에는 항상 「왜 그렇게 동작하는지」를 한 줄 이상 곁들여, 단순 사실 전달이 아니라 다음 결정에 도움이 되도록 했다.

Q1. 다른 한글 IME(ibus-hangul, fcitx-hangul, kime, nimf)와 무엇이 다른가?

항목	UNIM	ibus-hangul	fcitx-hangul	kime	nimf
코어 언어	Rust	C	C	Rust	C
통신 방식	DBus 데몬 + IM 모듈	IBus 데몬	Fcitx 데몬	임베디드	데몬
GTK3/4 지원	✅ 네이티브 IM 모듈	✅	✅	✅	✅
Qt5/6 지원	✅ 네이티브 플러그인	✅	✅	✅	✅
XIM	✅	✅	✅	✅	✅
Wayland (input-method-v2)	✅	✅ (IBus)	✅	△	✅
GNOME Shell 직접 통합	✅ 자체 확장	✅ (IBus)	△	✗	✗
자동 한↔영 오타 교정	✅ AutoTypeFix(forward+reverse+학습)	✗	✗	✗	✗
한자 9칸/81칸 그리드	✅ 통일	△	△	✗	△
한자 즐겨찾기	✅ DBus 시그널로 전체 동기화	✗	✗	✗	✗
사용자 자판 v1 JSON	✅ inherits + rule_sets	✗	△	△	✗
라이선스	(프로젝트 라이선스 참고)	LGPL/GPL	GPL	GPLv3	LGPL

한 줄 요약: UNIM은 "Rust 코어 한 개를 모든 환경에 그대로 꽂는다"는 설계 + AutoTypeFix와 학습형 억제 사전 같은 사용자 경험 기능을 다른 IME가 안 가진 영역으로 차별화한다.

Q2. 시스템 IME와 동시에 설치해도 되나?

🐧 리눅스

가능하긴 하지만 권장하지 않는다. 한 데스크톱에 두 IME가 살아있으면 키 이벤트가 어디로 갈지 OS와 툴킷이 헷갈린다.

GNOME: IBus와 UNIM 동시 사용 시 키 이벤트 유실 빈발 → IBus 제거 필수.
```
sudo apt remove ibus
```
KDE: fcitx5는 자체 데몬을 띄우므로 충돌. 환경변수에서 한쪽만 활성화하라.
테스트 환경: VM/컨테이너로 분리해 비교하는 건 좋다.

결론: "둘 중 하나"가 정답. UNIM 도입 전 기존 IME를 깔끔히 제거하라.

Q3. 어떤 환경이 가장 안정적인가?

🐧 리눅스

UNIM 0.2.0 시점의 안정성 등급:

환경	등급	비고
Ubuntu 24.04 + GNOME(Wayland) + GNOME Extension	🟢 A	권장. 메인 개발/테스트 환경
Ubuntu 24.04 + GNOME(X11)	🟢 A	환경변수 + Standalone 팝업
KDE Plasma 6 (Wayland)	🟢 B+	input-method-v2 잘 동작
KDE Plasma 6 (X11)	🟢 B+	XIM/Qt IM 둘 다 양호
Sway (Wayland)	🟡 B	팝업 위치 약간 미흡, 팝업 명세 §8.4 참고
Hyprland (Wayland)	🟡 B	동상
XFCE/MATE (X11)	🟢 B+	전통적 환경, 잘 동작
Wayland 단독(컴포지터별)	🟡 B/C	컴포지터의 IM 프로토콜 지원도에 의존

A 등급 권장 = "처음 깔아 보는 사람용". 익숙해지면 다른 환경도 충분히 사용 가능.

Q4. AutoTypeFix는 정확히 어떻게 동작?

2단계로 보면 된다.

단계 1 — 관측

엔진은 사용자 키 입력을 모드별로 동시에 두 개의 가상 트랙(한글 트랙, 영어 트랙)으로 시뮬레이션한다. 예: 영문 모드에서 gksrmf이 들어오면 한글 트랙은 동시에 한글을 만든다.

단계 2 — 트리거

단어 경계(스페이스/구두점/Enter)가 들어왔을 때, 현재 모드와 다른 트랙이 「의미 있는 단어」를 만들었으면 교정 제안.

forward: 영문 모드인데 한글 트랙이 글자 만듦 → gksrmf → 한글
reverse: 한글 모드인데 영어 트랙이 단어 만듦 → ㅈㅐㅍㅁ → wave

학습 (억제 사전)

사용자가 교정을 「실수」로 받아들이고 BS+모드전환으로 되돌리면 → Pending 표시. 같은 단어가 또 트리거되면 「그 시도를 억제하면서 동시에 Tentative로 등록」. GUI에서 [확정] 누르면 영구.

이 모델의 핵심은 등록을 롤백 시점이 아니라 재시도 시점에 한다는 것. 모드를 잘못 둔 일회성 오타로는 학습되지 않게 막는 안전장치.

Q5-1. 즐겨찾기를 끄면 popup이 다른 페이지로 휙 넘어가는데 정상인가?

정상 동작이다. 즐겨찾기(★)는 한자를 1페이지 상단으로 promote하고, 해제(☆)는 그 한자를 원래 사전순 위치로 demote한다. 사전순 위치가 현재 페이지가 아니면 popup이 그 페이지로 점프한다.

이 점프 자체를 사용자가 놓치지 않게, 도착한 cursor 셀이 140ms 동안 노란색(#f9e2af)으로 짧게 깜박인다(flash). "내가 별을 끄니 이 한자가 여기로 돌아갔구나"를 시각으로 잡아 주는 신호다.

등록(★ ON)은 cursor가 1페이지 상단으로 따라가는 게 자연스럽고 눈에 띄어서 flash가 없다.
해제(☆ OFF)는 어디로 갈지 예측이 어려워서 flash가 있다.

자세한 동작은 사용자 매뉴얼 §4.2와 팝업 명세 §3.6/§3.7 참고.

Q5. 한자 9칸 vs 81칸 차이는?

항목	9칸 (compact)	81칸 (expanded)
화면 점유	작음	큼
시야 후보 수	9개	81개 (9×9)
적합 상황	자주 쓰는 후보가 상위에 있음	드문 한자, 동음이의어가 많음
토글 키	—	`.` (마침표)
표시	⊟ 아이콘	⊞ 아이콘
키 바인딩	1~9 직선택, 화살표	1~9 + 행 점프, 화살표

한자가 9개를 넘기면 9칸은 PageDown 대신 화살표로 다음 페이지를 보여 주지만, 81칸은 한 번에 9페이지를 펼쳐 시각적으로 바로 비교 가능.

Q6. 설정 파일 위치, 백업과 복원은?

🐧 리눅스

위치

~/.config/unim/
├── config.yaml              # 일반 설정 (소스 오브 트루스)
├── typefix-blacklist.yaml   # 학습된 억제 사전
├── userdict.yaml            # reverse 사용자 사전 (0.2.0 신규)
└── layouts/                 # 사용자 정의 v1 자판
    └── my_3bul_variant.json

백업

tar -czf ~/unim-backup-$(date +%F).tar.gz -C ~/.config unim

복원

# 데몬을 멈추고 복원하면 안전
systemctl --user stop unim-daemon
tar -xzf ~/unim-backup-2026-04-26.tar.gz -C ~/.config
systemctl --user start unim-daemon

데몬은 typefix-blacklist.yaml과 userdict.yaml을 mtime 감시로 자동 리로드하므로 데몬을 멈추지 않고도 복원할 수 있다. 다만 config.yaml은 일부 키가 데몬 시작 시 캐시되므로 재시작이 안전.

Q7. 자판은 어떤 게 있고, 새로 추가할 수 있나?

내장 한국어 자판

ko_2bulstd(두벌식 표준), ko_3bul390(세벌식 390), ko_3bul391(세벌식 391), ko_3bul_noshift(세벌식 순아래), ko_3bul_anmatae(안마태, 모아치기).

참고: 쿼티형 세벌식(ko_3bul_qwerty)은 빌트인이 아닌 연구 자료로만 보존된다. docs/references/keymaps/ko_3bul_qwerty_v2.json을 ~/.config/unim/layouts/ko_3bul_qwerty.json으로 복사하면 사용자 프로필로 활성화된다.

영어

qwerty, dvorak, colemak, colemak_dh, workman.

사용자 정의

🐧 리눅스

~/.config/unim/layouts/<name>.json에 v1 스키마 JSON을 넣으면 데몬이 자동 스캔. inherits: "ko_3bul390" 같이 상속해 일부만 덮어쓸 수도 있음.

# 검증
unim-cli config layout validate ~/.config/unim/layouts/my.json
# 활성화
unim-cli config set korean-layout my

스키마 상세는 docs/archive/plans/LAYOUT_PROFILE_V1.md.

rule_sets로 같은 자판에 옵션 토글을 붙일 수도 있다. 예: ko_3bul390의 sun_arae_batchim(순아래받침). 설정 GUI에서 SwitchRow가 동적으로 나타난다.

Q8. UNIM의 메모리 사용량은 얼마나 되나?

정상 운영 시 unim-daemon RSS는 30~80 MB 수준. UNIM 0.2.0이 사용하는 안정화 장치:

#[global_allocator] tikv_jemallocator::Jemalloc — glibc ptmalloc arena 폭주 차단.
Environment=MALLOC_ARENA_MAX=2 (systemd) — C 라이브러리 경로 이중 차단.
60초 주기 libc::malloc_trim(0) — OS에 메모리 반환 강제.

과거 RSS가 2 GB까지 부풀던 사건(0.1.x) 이후 회귀 금지로 못 박았다. RSS 500 MB+ 관측 시 트러블슈팅 §14로.

Q9. UNIM이 비밀번호 입력을 가로채는가?

아니다. 비밀번호 필드는 content_purpose로 식별되어 자동으로 영문 강제 전환된다. AutoTypeFix(순방향·역방향)·한자 변환·특수문자 팝업 모두 비활성화된다. 이미 쌓인 키 관측 버퍼·되돌리기 기록도 함께 지워져, dkssud 같은 비밀번호가 한글로 자동 교정돼 값이 깨지지 않는다. 입력값은 데몬 메모리에도 남기지 않는다.

단, 자동 검출은 앱이 content_purpose=password(리눅스) 또는 InputScope(Windows)를 정확히 보고할 때만 동작한다. 보고하지 않는 환경 — XIM 레거시 앱, content-purpose 를 보내지 않는 일부 Wayland 컴포지터·웹폼 — 에서는 자동 감지가 안 될 수 있으니, 그런 곳에서는 직접 한/영 키로 영문 모드를 확인하길 권장한다. (정상 감지 환경: GTK3/4·Qt5/6·GNOME 확장·Windows TSF — 64비트·32비트 앱 모두 unim_tsf32.dll TSF TIP 이 동일한 InputScope 방식으로 감지한다. "Windows IMM32 앱은 ES_PASSWORD 표준 컨트롤만 최선노력 감지"라는 서술을 봤다면 실제 배포되지 않는 IMM32 폴백 이야기이니 무시해도 된다 — Q11 참고)

Q9-1. 비밀번호 칸에서는 왜 자동 오타 교정이 안 되나?

의도된 동작이다. 비밀번호·PIN 칸에서는 자동 오타 교정을 일부러 끈다(Q9 참고). 켜 두면 dkssud처럼 친 비밀번호가 단어 경계에서 한글로 바뀌어 로그인이 깨지기 때문이다. 칸을 벗어나면 즉시 원래대로 돌아오고, 수동으로 켜고 꺼 둔 토글 상태도 그대로 유지된다.

반대로 비밀번호가 아닌 일반 칸인데도 교정이 안 되는 경우는 다른 원인이다 → 트러블슈팅 §8. 위에 적은 미감지 환경(XIM·일부 Wayland)에서는 비밀번호 칸이 일반 칸으로 취급돼 오히려 교정이 발동할 수 있는데, 이 한계도 트러블슈팅 §8-1 에 정리돼 있다.

Q9-2. `install.sh`(한 줄 설치)는 안전한가요?

curl -fsSL .../install.sh | bash 는 편리하지만 "정체불명 스크립트를 통째로 실행"하는 것이므로 걱정될 수 있다. UNIM 설치 스크립트에는 다음 4가지 안전장치가 있다.

SHA256 체크섬 검증 — 릴리스에 포함된 SHA256SUMS 를 매니페스트로 삼아 내려받은 모든 .deb 를 검증한다. 하나라도 불일치하면 설치 단계로 넘어가지 않고 중단한다(부분 설치 없음).
임시 디렉토리 격리 — 모든 다운로드는 mktemp 로 만든 임시 디렉토리에 저장되고, 성공/실패/중단 어느 경우든 trap 으로 자동 삭제된다. 시스템에 남는 파일이 없다.
apt 트랜잭션 — 설치는 dpkg -i 가 아니라 apt install 로 하므로, 외부 런타임 의존성까지 apt 의 원자적 트랜잭션으로 해결된다. 실패 시 부분 설치가 남지 않는다.
스크립트 전문 공개 — 스크립트는 main 브랜치에 그대로 공개돼 있다. 실행 전에 curl ... -o install.sh 로 받아 직접 읽어볼 수 있다.

한계: SHA256SUMS 가 .deb 와 **같은 출처(GitHub Releases)**에 있으므로, 전송 무결성은 보장되지만 출처 인증은 GitHub 의 TLS 신뢰에 의존한다. GPG/minisign 서명은 향후 과제다. 최소 권한을 원하면 방법 2(수동 다운로드)로 각 파일을 직접 검증해 설치하면 된다.

Q10. 0.1.x에서 0.2.0으로 업그레이드 시 주의?

대부분 자동. 단 두 군데 자동 정규화가 있다.

config.yaml의 korean.layout이 enum 형식(Dubeolsik)이면 → ko_2bulstd 같은 문자열로 자동 변환.
english.layout이 enum이면 → qwerty 등 문자열로 자동 변환.
typefix-blacklist.yaml의 옛 키도 serde compat 레이어로 자동 정규화.

C-API: UnimEnglishLayout/UnimKoreanLayout enum 제거 → C 문자열 setter/getter로 변경. C/C++ 클라이언트 사용자만 영향.

자세한 마이그레이션은 변경 이력 0.2.0.

Q11. UNIM은 macOS/Windows에서도 되나?

Windows는 된다. macOS는 아직 안 된다.

v0.4.0부터 Windows 10/11(64비트)을 TSF(Text Services Framework) 기반 unim-tsf로 지원한다.

irm https://raw.githubusercontent.com/from104/unim/main/install.ps1 | iex

로 MSI를 내려받아 설치한다(사용자 매뉴얼 §2.1 설치 참고). 32비트 앱은 64비트 TSF 대신 별도의 32비트 TSF TIP(unim_tsf32.dll)이 처리한다. 예전에 검토됐던 IMM32 폴백(unim-imm32 크레이트)은 실제 배포 MSI에는 포함되지 않는 진단·연구용 소스로만 남아 있다 — "IMM32 폴백"을 배포 기능으로 안내하는 문서를 봤다면 오래된 것이다.

Windows 쪽은 개발자 상용 환경에서 매일 쓰이며 다듬어지고 있지만, 리눅스만큼 여러 머신·앱 조합을 거치지는 못했다. 문제를 만나면 GitHub Issues로 앱 이름과 Windows 버전(winver)을 함께 보고해 주길 권한다.

macOS는 여전히 미착수다(로드맵 5단계). Rust 코어와 C-API가 분리돼 있어 이론적으론 macOS의 IMKit에 어댑터를 붙이면 되지만, 착수한 사람이 아직 없다. 자원자가 있다면 환영.

Q12. 빌드에 cargo 1.95가 왜 필요?

Cargo.lock 파일이 v4 포맷이고, 이 포맷은 cargo 1.83+이 안전하게 다룰 수 있다 (1.95에서 안정 사용 검증). 리눅스 배포판에 따라 /usr/bin/cargo가 1.75 같은 구 버전인 경우가 있어 다음과 같이 명시 권장:

rustup update stable
which cargo                  # ~/.cargo/bin/cargo 가 잡혀야 함
cargo --version              # 1.95.0 이상

소스 빌드 실패 메시지에 lock file version 4 requires '-Znext-lockfile-bump'가 보이면 100% 이 문제다.

Q13. 기여하고 싶다 — 어디부터?

CONTRIBUTING.md — 브랜치/PR 워크플로.
AGENTS.md — 아키텍처와 컴포넌트 맵.
IME_BEHAVIOR.md — 동작 명세.
컴포넌트 별 SPEC.md (각 크레이트 안).
빌드 검증: make build 경고 0개 + cargo test --workspace 전체 통과.
커밋 메시지는 영어, 문서는 한국어 (프로젝트 컨벤션).

good-first-issue 라벨 이슈가 출발점으로 가장 좋다.

Q14. 「universal」이라는 이름은 왜?

Universal Next-generation Input Method의 약자. "한글" 입력기지만 한국어/영어를 자유롭게 오가는 양방향 + 모든 툴킷에 한 코어를 그대로 쓴다는 의미. 장기적으로는 macOS/Windows까지 확장(로드맵 5단계).

Q15. 안마태(안마태)와 Moachigi(모아치기)가 뭐가 다른가?

안마태는 구체적인 자판 배열 이름이다. 2003년에 완성된 세벌식 계열 자판으로, 초·중·종성이 키보드 영역별로 고정 배치된다. UNIM에서는 ko_3bul_anmatae 프로필로 내장됐다.

Moachigi(모아치기, "모아서 치기")는 입력 방식이다. 여러 자모를 동시에 또는 짧은 시간 안에 연달아 누르면 하나의 음절로 묶어서 처리한다. 일반 두벌식·세벌식이 한 키씩 순서대로 처리하는 것과 달리, 모아치기는 chord 윈도우(기본 60ms) 안에 들어온 키를 한꺼번에 처리한다.

즉, 안마태 자판으로 모아치기를 하는 것이 UNIM 0.3.0의 첫 모아치기 지원이다. supports_moachigi=true 자판에서만 모아치기 설정 그룹이 설정 앱(unim-settings)에 나타난다.

unim-popup-service가 설치됐는지 먼저 확인한다.

busctl --user introspect org.atit.unim.PopupService /org/atit/unim/popup

응답이 없으면 패키지 미설치 또는 D-Bus 서비스 파일 누락이다. 자세한 진단은 트러블슈팅 §16.

Q17. deb에서 rpm으로 또는 그 반대로 마이그레이션할 때 설정이 유지되나?

예. 사용자 설정과 레이아웃은 ~/.config/unim/ 아래에 저장되며, 패키지 형식과 무관하다.

~/.config/unim/config.yaml — 주 설정 파일
~/.config/unim/layouts/*.json — 사용자 자판 프로필
~/.config/unim/typefix-blacklist.yaml — AutoTypeFix 억제 사전
~/.config/unim/typefix-userdict.yaml — 사용자 사전

패키지를 제거하고 다른 형식으로 재설치해도 위 파일들은 건드리지 않는다. 단, unim-gui-qt 패키지는 0.3.0에서 제거됐다 — 트레이 아이콘·설정창·팝업 렌더러는 지금 unim-desktop(인디케이터+레거시 설정창+unim-popup-service 묶음) 과 unim-settings(Slint 설정 앱) 두 패키지가 나눠 담당한다. 현재 배포되는 11개 패키지 전체 목록은 debian/control 또는 dpkg -l 'unim*' 로 확인.

Q19. 자판을 눈으로 보거나 편집·연습할 도구가 있나?

두 개의 GTK4 보조 도구가 함께 설치된다.

unim-keymap-studio (자판 스튜디오): 한국어/영문 자판을 시각적으로 보고 편집한다. 헤더의 3단 드롭다운(언어 > 출처 > 자판)으로 대상을 고르고, 4개 탭(기본 / 자판 / 조합 / 확장)으로 내용을 본다. 「조합」·「확장」 탭은 한글 자판일 때만 나타난다. 헤더 우측에는 [도움말]·[설정]·[메뉴].
- 빌트인 자판은 읽기 전용이라 「다른 이름으로 저장」만 가능하고, 사용자 자판은 「저장」 + 「다른 이름으로 저장」 둘 다 된다.
- 사용자 자판은 ~/.config/unim/layouts/ 에 JSON으로 저장된다(Q7의 사용자 정의 자판과 동일 위치).
unim-typing-practice (타자 연습): 현재 활성 자판으로 타자 연습을 한다. WPM/CPM, 정확도, 오타 히트맵을 측정해 어떤 키에서 실수가 많은지 보여 준다.

두 도구는 동일한 5행 키보드 위젯을 공유하므로 보이는 자판 모양이 일관된다. 단축키는 사용자 매뉴얼 §5.6 참고.

Q18. chord_window_ms 적정값은 얼마인가?

범위는 10–200ms, 기본값은 60ms다. 60ms는 숙련자 기준으로 설계됐다.

프로필	권장 범위	설명
입문자	100–150ms	키를 동시에 누르는 타이밍이 불안정할 때 넉넉하게
일반	60–100ms	대부분의 사용자에게 편안한 범위
숙련자	10–60ms	오입력 최소화, 반응 속도 우선

chord_window_ms를 0으로 설정하면 모아치기가 완전히 꺼진다.

🐧 리눅스 — 설정창의 슬라이더로 조정하거나 unim-cli config set korean-chord-window-ms 80 명령을 쓴다.

Q20. 키를 오래 누르면 글자가 여러 번 입력돼요.

손 떨림 등으로 키를 오래 누르고 있으면 운영체제가 같은 키를 빠르게 반복 입력한다(자동 반복). UNIM에는 이 반복을 데몬이 무시하는 조합키 자동반복 억제(접근성) 옵션이 있다. 억제 대상은 한/영 토글 키와 한글 모드의 문자 키이며, 백스페이스·방향키 같은 편집키와 영문 직접 입력의 반복은 그대로 둔다. 기본값은 꺼짐이라 켜기 전에는 동작이 바뀌지 않는다.

🐧 리눅스

켜는 법 — 설정 앱의 접근성 → 조합키 자동반복 억제 스위치, 또는 CLI:

unim-cli config set ignore-key-repeat true

폴백의 한계: Wayland·Qt5/6·GNOME 확장은 반복 여부를 정확히 가려낸다. 반면 GTK3/4·XIM·ibus 호환 경로는 80ms 시간창으로 근사 판정하므로 (1) 첫 반복 1회는 통과될 수 있고, (2) 시스템의 키 반복 간격을 80ms보다 길게 설정했다면 걸러지지 않을 수 있다. 어느 경우든 오판 시 항상 "덜 막는" 쪽으로 안전하게 동작한다. GNOME 확장 사용자는 재로그인 후 적용된다.

Q21. Chrome/Chromium의 비밀번호 필드에서 한/영 차단이 안 될 때는?

Chrome은 입력기를 보고하지 않으므로 UNIM이 자동 감지할 수 없습니다.

원인별 진단

1. Wayland Chrome (네이티브, `--enable-wayland-ime` 미활성화)

기본 상태에서는 Wayland 입력 메서드 프로토콜(input-method-v2)을 사용하지 않습니다. 플래그를 명시적으로 켜야 합니다.

해결 방법:

옵션 1 — 명령줄 플래그

google-chrome --enable-wayland-ime
chromium --enable-wayland-ime

옵션 2 — 플래그 파일 (~/.config/chrome-flags.conf)
```
--enable-wayland-ime
```

옵션 3 — .desktop 항목 (모든 사용자, 패키지 재설치해도 유지)

# /usr/share/applications/google-chrome.desktop 또는 ~/.local/share/applications/google-chrome.desktop
# Exec= 라인을 찾아 끝에 --enable-wayland-ime 추가
Exec=/opt/google/chrome/google-chrome --enable-wayland-ime %U

플래그를 켠 후 Chrome을 재시작하면 UNIM이 비밀번호 필드를 감지합니다.

2. X11 Chrome / Chromium

Chromium 엔진은 X11에서도 입력 필드 종류를 DBus 입력기에 보고하지 않습니다. 이는 Chromium의 설계 선택이므로 UNIM 쪽에서 해결할 수 없습니다. 직접 한/영 토글(예: 한영 키)으로 영문 모드를 확인하시기 바랍니다.

대안: Firefox는 입력기에 필드 정보를 보고하므로 필드 감지가 정상 동작합니다.

Q22. XIM 환경에서 비밀번호 필드 자동 감지가 안 될 때는?

XIM 프로토콜 자체에 입력 필드 종류를 전달할 방법이 없습니다.

XIM(X Input Method)은 1994년 설계된 레거시 프로토콜로, 비밀번호 같은 필드의 의미를 전달할 기능이 없습니다. 대신 다음 중 선택하시기 바랍니다:

직접 영문 모드 확인 — 비밀번호 칸에 진입하기 전에 한/영 키를 눌러 영문 모드인지 확인.
앱을 GTK/Qt 기반으로 전환 — XIM만 쓰는 레거시 앱을 최신 GTK/Qt 앱으로 바꾸기 (예: gvim → vim-gtk / nvim-qt).
다른 입력 방식 시도 — 커맨드라인이라면 ibus 호환 경로도 함께 켜서 시도.

Q23. UNIM을 제거했더니 한/영 전환이 아예 안 된다 — 다른 IME로 되돌리려면?

UNIM 제거는 시스템 입력기 지정을 자동으로 원래대로 되돌리지 않는다. Q2 에서 안내한 대로 UNIM 을 설치하며 sudo apt remove ibus 로 IBus 를 지운 경우, im-config -n unim (또는 GNOME+Wayland 확장 활성화)으로 지정해 둔 "현재 입력기 = unim" 설정이 UNIM 패키지를 제거해도 그대로 남는다. 그 상태에서 재로그인하면 run_im unim 만 남고 정작 UNIM 은 없으므로 어떤 IME 도 뜨지 않아 한/영 전환 자체가 안 되는 상태가 된다.

제거 전에 할 일 (권장)

UNIM 을 제거하기 전에 다른 IME 로 먼저 되돌려 둔다.

# 예: ibus-hangul 로 되돌아가려면 먼저 설치
sudo apt install ibus ibus-hangul

# 입력기 지정을 되돌린다
im-config -n ibus
# 또는 사용 가능한 프로파일 중 자동 선택
im-config -n auto

# 그 다음에 UNIM 제거 (전 패키지 일괄 — 셸 glob 확장 사용)
sudo apt remove 'unim*'

이미 제거해서 한글 입력이 전혀 안 되는 경우

im-config -n auto 를 실행해 설치된 IME 중 하나로 자동 재지정한다. 아무 IME 도 안 깔려 있으면 sudo apt install ibus ibus-hangul 로 최소 하나를 설치한 뒤 다시 실행한다.
~/.xinputrc 를 직접 확인해 run_im unim 이 남아 있다면 지우거나 다른 IME 이름으로 바꾼다(GNOME+Wayland 세션에서는 이 파일이 아예 안 쓰일 수도 있다 — 사용자 매뉴얼 §2.2 참고).
로그아웃 후 다시 로그인.

이 제거·롤백 경로는 UNIM 패키지 스크립트가 아니라 데비안/우분투의 im-config 프레임워크가 관리하는 영역이라, UNIM 쪽에서 자동으로 원복해 주지 않는다. 위 수동 절차가 현재의 유일한 복구 방법이다.

더 읽을 거리

▲ 목차로

UNIM 트러블슈팅 (한국어)

UNIM 0.4.0 — 증상 → 1차 진단 → 2차 명령 → 해결 순서로 정리. "한 번도 한글이 안 나간다"부터 "특정 앱에서만 깨진다"까지 자주 마주치는 증상들을 다룬다.

🐧 리눅스

전체 진단의 출발점은 두 가지다. 하나는 데몬이 살아 있는가, 다른 하나는 로그가 무엇이라고 말하는가.

# (1) 데몬 살아있나?
systemctl --user status unim-daemon
# 또는 PID 확인
unim-daemon --check && echo "RUNNING" || echo "STOPPED"

# (2) 디버그 로그 켜고 재현
UNIM_DEVELOP=1 systemctl --user restart unim-daemon
> ~/.unim-errors.log    # 비우고
# … 문제 재현 …
tail -f ~/.unim-errors.log

UNIM_DEVELOP=1은 Engine·DBus·Frontend·Extension 전 컴포넌트의 로그를 한 파일(~/.unim-errors.log)로 모은다. 일반 사용 시에는 OFF가 기본 — 로그 파일이 무한히 커지지 않게 하기 위함.

1. "한글이 아예 안 나옴" — 새로 설치한 직후

🐧 리눅스

1차 진단

echo $GTK_IM_MODULE      # unim 이어야 함
echo $QT_IM_MODULE       # unim 이어야 함
echo $XMODIFIERS         # @im=unim 이어야 함
unim-daemon --check && echo OK || echo MISSING

원인별 처방

증상	원인	해결
환경변수 비어 있음	im-config 설정 누락	`im-config -n unim` 후 로그아웃/로그인
`unim-daemon --check` → MISSING	systemd unit 미등록	`systemctl --user enable --now unim-daemon`
셸에는 보이는데 GUI 앱엔 적용 안 됨	DM이 환경변수를 안 가져감	`~/.xprofile` 또는 `/etc/environment`에 export
GNOME+Wayland	환경변수 경로가 막힘	대신 `gnome-extensions enable unim-gnome@from104.github.io`

🐧 리눅스 — §2~§4는 리눅스 프런트엔드(GTK / Qt / GNOME 확장) 전용이다.

2. "GTK 앱(GNOME Text Editor 등)에서만 안 됨"

진단

# IM 모듈이 설치돼 있나?
ls /usr/lib/x86_64-linux-gnu/gtk-3.0/3.0.0/immodules/im-unim.so 2>/dev/null
ls /usr/lib/x86_64-linux-gnu/gtk-4.0/4.0.0/immodules/libim-unim.so 2>/dev/null

# 모듈 캐시 갱신 필요?
sudo gtk-query-immodules-3.0 --update-cache
sudo gtk-query-immodules-4.0 --update-cache

처방

파일이 없으면 unim-im-gtk 패키지 재설치 또는 sudo make install PREFIX=/usr 재실행.
파일은 있지만 작동 안 하면 캐시 갱신 후 GTK 앱 재시작.
GTK4 모듈 파일명이 libim-unim.so인지 반드시 확인 (GTK3는 im-unim.so, 접두 lib 유무가 다름).

디버깅 팁: GTK_IM_MODULE_FILE=/usr/lib/.../immodules.cache GTK_IM_MODULE=unim gnome-text-editor 식으로 직접 띄워 보면 모듈 로드 단계 에러가 stderr에 보인다.

3. "Qt 앱(Kate, Krita)에서만 안 됨"

진단

ls /usr/lib/x86_64-linux-gnu/qt5/plugins/platforminputcontexts/libunimplatforminputcontextplugin.so
ls /usr/lib/x86_64-linux-gnu/qt6/plugins/platforminputcontexts/libunimplatforminputcontextplugin.so
QT_DEBUG_PLUGINS=1 kate 2>&1 | grep -i unim

처방

플러그인 부재 → unim-im-qt 재설치.
QT_DEBUG_PLUGINS=1 출력에서 Cannot load library 등 메시지가 보이면 의존 라이브러리 누락 → ldd <plugin>.so로 확인.
KDE Plasma 6에서는 Qt6 경로가 우선이니 QT_IM_MODULE=unim만 잘 잡혀 있으면 된다.

4. "GNOME 확장이 메뉴에 안 보임"

진단

gnome-extensions list | grep unim
gnome-extensions info unim-gnome@from104.github.io
journalctl --user -u gnome-shell -b | grep -i unim

처방

디렉토리 확인: ~/.local/share/gnome-shell/extensions/unim-gnome@from104.github.io/ 존재해야 함.
없으면 make dev-extension(소스 빌드) 또는 unim-gnome 패키지 설치.
활성화: gnome-extensions enable unim-gnome@from104.github.io → Alt+F2 → r (X11) 또는 로그아웃/로그인 (Wayland).
GNOME Shell 버전 호환: metadata.json의 shell-version 배열에 현재 버전이 들어 있는지 확인.

5. "한자 팝업이 안 뜸"

🐧 리눅스

진단

# 팝업 렌더러가 떠 있나? (X11/KDE/Xfce, 없으면 §16 참고)
pgrep -a unim-popup
# GNOME Wayland라면 확장이 활성 상태인가?
gnome-extensions list --enabled | grep unim

# DBus 시그널이 발행되고 있나? (별도 터미널에서 monitor)
busctl --user monitor org.atit.unim.InputMethod
# 그 상태에서 한글 입력 + 한자 키 → ShowHanjaPopup 시그널이 보여야 함

처방

환경	팝업 렌더 주체 (0.3.0+)	비고
GNOME+Wayland	GNOME extension `popup_view.js` (St 위젯)	확장이 `PopupRender` 시그널 받아 직접 그림
GNOME X11 / KDE / Xfce / WM (X11)	`unim-popup-service` (GTK4)	D-Bus auto-activation으로 자동 기동
Wayland (KDE Plasma 6 / Sway 등)	`unim-popup-service` (GTK4, wayland-backend)	`libgtk4-layer-shell` 필요, 실험적 — 팝업 명세 §12 참고

0.3.0부터 IM 모듈은 더 이상 자체 팝업을 그리지 않는다. 한자·특수문자·이모지 팝업 렌더링은 전부 unim-popup-service(또는 GNOME extension)로 중앙화됐다. 진단은 (이제는 존재하지 않는 popup_mode 설정이 아니라) 위처럼 렌더러 프로세스가 살아 있는지를 본다.

DBus가 죽었을 때: busctl --user list | grep atit → 비어 있으면 데몬이 서비스 등록을 못 한 것. journalctl --user -u unim-daemon -n 100 로그 확인.

6. "특수문자 팝업이 안 뜸"

원인 거의 동일 (한자 팝업과 같은 코드 경로).

🐧 리눅스 — 현재 입력 모드(한글/영문)는 CLI 로 조회하는 키가 따로 없다 — 트레이 아이콘 또는 GNOME 확장 인디케이터 표시로 확인한다.

한글 모드에서 자음(초성) 1글자만 입력한 상태로 한자 키를 눌러야 특수문자 팝업이 뜬다.

ㄱ~ㅎ 입력 후 한자 키. 한국어 자판이 두벌식이면 잘 동작, 세벌식이면 자음 입력 자체가 다를 수 있음.

7. "한자 팝업이 9칸까지만 보이고 81칸 토글이 안 됨"

🐧 리눅스

진단

# 마침표 키가 한자 팝업에 도달하는지 확인
UNIM_DEVELOP=1 systemctl --user restart unim-daemon
# 한자 팝업 띄우고 . 누른 후
grep -i 'ToggleExpanded\|9x9\|expanded' ~/.unim-errors.log

처방

0.1.x 시절에 빌드된 IM 모듈이 잔류해 있을 가능성 — make build && sudo make install 재실행.
키보드 레이아웃에서 .이 다른 키로 매핑돼 있는지 확인.

🐧 리눅스 — §7-1·§7-2는 리눅스 전용(Wayland 컴포지터 / XIM) 증상이다.

7-1. "Wayland에서 ◀/▶ 페이지 버튼이 보이는데 마우스 클릭이 안 먹음"

증상

unim-frontends/wayland로 동작하는 popup(컴포지터: GNOME mutter, KWin, Sway 등)에서 ◀/▶ 버튼이 시각적으로 분명히 그려지는데 마우스 좌클릭에 반응이 없다.

원인

Wayland popup은 zwp_input_popup_surface_v2 위에 그려진다. 이 surface로 pointer 이벤트가 들어오려면 컴포지터가 IM popup으로 pointer 라우팅을 허용해야 하는데, 일부 컴포지터(특히 GNOME mutter 일부 버전)는 IM popup을 "pass-through" 처리해 클릭이 아래 앱으로 빠진다.

처방

즉시 우회: 키보드 ← / → (또는 Page Up / Page Down)로 페이지 이동. 마우스 ◀/▶와 100% 동일 동작.
GNOME 사용자: GNOME Shell 확장 popup으로 자동 전환되므로 ◀/▶ 클릭이 정상 동작 (unim-gnome-extension이 mutter 외부에서 자체 그린다). 만일 GNOME에서도 안 되면 확장이 비활성 또는 미설치 상태인지 gnome-extensions list --enabled | grep unim으로 확인.
장기 대응: 컴포지터 측 IM popup pointer 라우팅 지원 여부에 의존. 보고는 GitHub Issues에 컴포지터 이름·버전 명시.

키보드 ←/→ 동작은 모든 컴포지터에서 보장된다. 마우스 ◀/▶는 컴포지터 정책상 best-effort.

7-2. "XIM 이모지 popup의 ◀/▶가 카테고리 탭과 겹치게 동작"

증상

XIM(unim-frontends/xim)에서 이모지 popup을 띄우면 카테고리 탭(스마일·동물·음식 …)과 ◀/▶ 페이지 버튼이 같은 영역 근처에 동시에 표시된다. "어느 게 누른 거지?" 헷갈린다.

원인 / 정상 여부

정상 동작이다. XIM 이모지 popup은 (1) 상단에 카테고리 탭(좌클릭으로 카테고리 전환), (2) 하단에 ◀/▶(좌클릭으로 한 페이지 이동) 두 컨트롤을 모두 가진다. 둘 다 좌클릭이지만 영역이 다르다 — 카테고리 탭은 popup 상단, ◀/▶는 footer.

처방

좌클릭 영역을 명확히 인지: 카테고리는 위, 페이지 이동은 아래.
헷갈리면 키보드로 처리:
- 카테고리 전환: Tab (다음) / Shift+Tab (이전).
- 페이지 이동: ← / → (또는 Page Up/Page Down).

정상 동작이지만 시각적 분리가 부족하다는 피드백은 받고 있다 — 향후 footer 색 분리 예정.

8. "AutoTypeFix가 작동 안 함"

진단

🐧 리눅스

unim-cli config show | grep -i typefix         # 전체/순방향/역방향 사용 여부 확인
cat ~/.config/unim/typefix-blacklist.yaml | head -50  # 등록된 억제 단어

처방

마스터 토글 OFF → 설정 GUI에서 ON.
특정 단어가 자꾸 억제 사전에 들어가면 GUI 「교정 억제 단어」 페이지 → 「비활성」 또는 「삭제」.
단어 경계(스페이스/마침표)가 들어와야 비로소 교정이 적용된다. 한 글자 더 친 뒤에 스페이스를 넣어 보면 즉시 교정됨.
영문 모드에서 작동 안 함 → 「영문 모드 시 무시」가 ON이라 그렇다 (의도된 기본값).

8-1. "비밀번호 칸인데 자동 오타 교정이 발동한다"

원인

비밀번호 보호(FAQ Q9)는 앱이 "이 칸은 비밀번호"라고 알려 줄 때(content_purpose)만 동작한다. 아래 환경은 이 신호를 UNIM 에 전달하지 못해, 비밀번호 칸이 일반 칸으로 취급된다.

환경	상태	이유
GTK3/4, Qt5/6, GNOME 확장, Windows TSF(64비트·32비트 `unim_tsf32.dll` 모두)	감지됨	content_purpose / InputScope 정상 전달
XIM 레거시 앱	미감지	XIM 프로토콜에 해당 신호가 없음
일부 Wayland 컴포지터·웹폼	미감지	content-purpose 를 보내지 않음(앱/컴포지터 재량)
포커스 후 목적이 바뀌는 GTK 앱	미감지	GTK IM 은 포커스 시점에만 input-purpose 를 읽고 `notify::input-purpose` 변경은 구독하지 않는다(기존 한계) — 같은 칸이 나중에 비밀번호로 바뀌면 재포커스 전까지 반영 안 됨

이 표는 아직 성긴 편이다 — 제보 바란다. 어떤 앱이 비밀번호 칸을 제대로 알려 주고 어떤 앱이 안 알려 주는지는 실사용 사례가 쌓여야 채워진다. 리눅스·Windows 양쪽 다 사례가 충분치 않아 앱별 대응이 다 들어가 있지 못하다. 비밀번호 칸에서 교정이 발동하는 앱을 만나면 앱 이름·버전을 GitHub Issues 로 알려 주기 바란다. 그게 이 표를 채우는 유일한 경로다.

처방

미감지 환경에서는 비밀번호를 치기 전에 한/영 키로 영문 모드를 직접 확인한다. 영문 모드에서는 순방향(영→한) 교정이 기본으로 억제되므로 사실상 안전하다.
특정 앱에서 자주 겪는다면 자동 오타 교정 자체를 토글 단축키(사용자 매뉴얼 4.4)로 잠깐 꺼 두는 것도 방법이다.
토글 단축키를 지정할 때는 한/영 키·한자 키와 같은 키를 쓰지 않는다 — 역할이 충돌해 한/영 전환이나 한자 변환이 토글에 가려질 수 있다(CLI unim-cli config set 은 중복 지정 시 경고를 낸다).

preedit 노출 관련 별도 이슈: 비밀번호 칸에서는 한글 조합 자체가 차단되므로, 조합 중 글자가 preedit(밑줄)로 화면에 잠깐 비치는 문제는 정상 감지 환경에선 거의 없다. 다만 위 미감지 Wayland 환경에서는 이론상 노출이 성립할 수 있어 별도 이슈로 추적 중이며, 현재 권장 우회는 위 「영문 모드 직접 확인」이다.

9. "AutoTypeFix가 너무 자주 잘못 교정"

처방

🐧 리눅스

케이스	해법
특정 단어 한 개만 문제	BS + 한/영로 롤백 → 다음에 같은 단어 칠 때 자동으로 Tentative 등록됨
자주 후회한다	설정 → 「오타 교정」 → 임시 만료 시간을 늘려 학습 기회 확보
영문 모드에서도 reverse가 동작	`auto_typefix.reverse.skip_incomplete_syllable` ON
직접 단어 추가	`~/.config/unim/typefix-blacklist.yaml`을 텍스트 에디터로 편집 → 데몬이 mtime 자동 리로드

10. "설정이 저장 안 됨 / 변경이 안 먹힘"

🐧 리눅스

진단

ls -la ~/.config/unim/
test -w ~/.config/unim/config.yaml && echo writable || echo BLOCKED
unim-cli config show 2>&1 | head -5
journalctl --user -u unim-daemon -n 50

처방

권한 문제 → chmod 644 ~/.config/unim/*.yaml, chmod 755 ~/.config/unim.
~/.config/unim을 root가 만든 흔적이 있으면 sudo chown -R $USER:$USER ~/.config/unim.
GUI에서 변경했는데 데몬에 반영 안 됨 → 데몬 재시작: systemctl --user restart unim-daemon.

🐧 리눅스 — §11~§14는 리눅스 전용이다. Windows에는 GTK IM 모듈·Flatpak·Snap·상주 데몬이 모두 없다.

11. "키 입력 자체가 잠겼다 (ghostty/터미널)"

증상: 한 키만 친 뒤 화면이 멈춘 듯 키가 안 먹힘.

원인

GTK3/4 IM의 preedit-end 시그널 누락으로 ghostty가 IM 잠금 상태에 빠짐(0.1.x 잔존 이슈, 0.2.0에서 unim_emit_preedit 헬퍼로 해결).

처방

# 0.2.0 빌드인지 확인
dpkg -l | grep unim       # 또는 unim-cli --version
unim-cli --version        # 0.2.0 이상이면 해결됨

0.1.x이면 make build && sudo make install 후 IM 모듈 갱신.

12. "Flatpak 앱(Telegram, VS Code)에서 한글 안 됨"

진단

flatpak list --columns=application,environment | grep -E 'GTK_IM|QT_IM'

처방

GNOME+Wayland인 경우 호스트 환경변수가 Flatpak 샌드박스에 새어들면 입력이 막힌다. 자동 처리가 작동했으면 비어 있어야 한다.

# 자동 처리 확인 — daemon 시작 로그
journalctl --user -u unim-daemon | grep -i flatpak
# 다음 두 줄이 보이면 정상:
#   [Flatpak] GNOME+Wayland 감지 — Flatpak IM 환경변수 설정 시작
#   [Flatpak] IM 환경변수 override 완료

# 수동 적용
flatpak override --user --env=QT_IM_MODULE= --env=GTK_IM_MODULE=
flatpak kill org.telegram.desktop

X11이거나 GNOME이 아닌 경우는 반대로 환경변수를 유지해야 한다 — 자동 처리는 GNOME+Wayland에서만 발동한다.

⚠️ UNIM 제거 후에도 남는다: 이 override는 사용자 전역 ~/.local/share/flatpak/overrides/global에 영구히 기록되며, unim 패키지를 삭제해도 자동으로 원복되지 않는다. 다른 입력기로 옮긴 뒤 Flatpak 앱 입력이 이상하면 아래 명령으로 직접 해제해야 한다.
flatpak override --user --unset-env=QT_IM_MODULE --unset-env=GTK_IM_MODULE

13. "Snap 앱에서 한글 안 됨"

Snap은 호스트 환경변수를 그대로 상속하지만 전역 override 메커니즘이 없다.

처방

~/.profile에 조건부 export:

if [ "$XDG_SESSION_TYPE" = "wayland" ] && echo "$XDG_CURRENT_DESKTOP" | grep -q "GNOME"; then
    export GTK_IM_MODULE=
    export QT_IM_MODULE=
else
    export GTK_IM_MODULE=unim
    export QT_IM_MODULE=unim
fi
export XMODIFIERS="@im=unim"

또는 한 번만 띄울 때:

QT_IM_MODULE= GTK_IM_MODULE= snap run telegram-desktop

14. "데몬이 메모리 너무 많이 먹음 (RSS 500MB↑)"

진단

grep -E 'VmRSS|VmData|Threads' /proc/$(pidof unim-daemon)/status
cat /proc/$(pidof unim-daemon)/smaps_rollup | grep -E 'Rss|Anonymous'

처방

UNIM 0.2.0은 tikv_jemallocator + MALLOC_ARENA_MAX=2 + 60초 주기 malloc_trim(0)로 1MB 단위 안정 운영을 보장한다. 그럼에도 RSS가 500MB를 초과하면:

# 임시 회복
systemctl --user restart unim-daemon

# 진단 데이터 수집 (이슈 보고용)
ps -o pid,rss,vsz,cmd $(pidof unim-daemon)
journalctl --user -u unim-daemon -n 500 > unim-mem.log

AGENTS.md §메모리 관리 규칙이 회귀 금지 항목과 진단 명령을 모두 정리해 둔다. 이슈로 보고하면 도움이 된다.

15. "모아치기(chord)가 제대로 인식 안 됨"

모아치기 관련 문제는 원인이 다양하다. 아래 항목을 순서대로 확인한다.

15-1. 현재 자판이 모아치기를 지원하지 않음

모아치기는 supports_moachigi: true인 자판에서만 동작한다. 빌트인 중에는 안마태 자판 (ko_3bul_anmatae) 만 해당된다. 쿼티형 세벌식 v2 는 빌트인이 아닌 연구 자료(docs/references/keymaps/ko_3bul_qwerty_v2.json)로 보존되며, 사용자 자판 폴더로 복사한 사용자 프로필에서 모아치기 지원을 켤 수 있다.

사용자 자판 폴더는 ~/.config/unim/layouts/ 다 — 위 파일을 ~/.config/unim/layouts/ko_3bul_qwerty.json으로 복사한다.

# 현재 자판 확인
unim-cli config show | grep -E 'layout|keymap'

출력이 모아치기 지원 자판이 아니라면 설정 앱(unim-settings)에서 자판을 변경해야 한다. 모아치기 지원 자판으로 바꾸면 모아치기 그룹이 자동으로 나타난다.

15-2. chord_window_ms가 너무 짧음

chord_window_ms 기본 권장값은 60ms다. 처음 모아치기를 시작하거나 입력 속도가 빠르지 않다면 80~100ms 부터 시작해 익숙해지면 줄여 나가는 것이 좋다.

# 현재 설정값 확인
unim-cli config show | grep chord-window

# 80ms로 변경
unim-cli config set korean-chord-window-ms 80

또는 설정 앱(unim-settings) 「일반」 페이지의 자판 옵션(모아치기 지원 자판에서만 표시)에서 슬라이더로 조정한다.

15-3. bidirectional_combine이 비활성 상태

자모 역순 결합(예: ᆯ+ᆨ → ᆰ, ㅎ+ㄱ → ㅋ)이 안 된다면 양방향 자모 결합 옵션이 꺼져 있는 것이다.

# 현재 상태 확인
unim-cli config show | grep bidirectional-combine

# 활성화
unim-cli config set korean-bidirectional-combine true

또는 설정 앱(unim-settings) 「일반」 페이지 > 자판 옵션 > 양방향 자모 결합 토글을 ON.

15-4. 키보드가 NKRO를 지원하지 않음 (ghosting)

일반 멤브레인 키보드는 2~3 KRO(Key Rollover) 한계로 인해 여러 키를 동시에 눌렀을 때 일부 키가 운영체제에 전달되지 않는다(ghosting). chord가 누락되거나 엉뚱한 자모로 조합된다면 키보드 자체가 동시 입력을 지원하지 못하는 것일 수 있다.

자가 진단:

# X11 환경에서 동시 키 이벤트 확인
xev -event keyboard

Wayland 환경에서는 xev 대신 wev 사용 (apt install wev 또는 동등).

나타나는 창에 포커스를 두고 chord에서 사용하는 키를 모두 동시에 누른다. 터미널에 KeyPress event가 키 수만큼 모두 찍혀야 한다. 또는 브라우저에서 keyboardchecker.com 등 온라인 키 테스터를 사용한다.

해결: 게이밍 키보드 또는 메커니컬 키보드의 NKRO 모드 사용 권장. 자세한 내용은 안마태 자판 가이드 — 키보드 호환성 참고.

15-5. USB 폴링 레이트 낮음 (125Hz = 8ms 분해능)

USB 키보드의 기본 폴링 레이트는 125Hz(= 8ms 간격)다. chord_window_ms를 10~30ms처럼 짧게 설정하면 폴링 주기 자체가 윈도우의 상당 부분을 차지해 일부 키를 놓칠 수 있다.

해결:

chord_window_ms를 60ms 이상으로 올려 폴링 지연 여유분 확보.
1000Hz 폴링 지원 게이밍 키보드 사용, 또는 USB 포트 변경.

빌드 실패

🐧 리눅스

일반 빌드 실패

make clean
make build 2>&1 | tee /tmp/unim-build.log

에러 메시지	원인	처방
`lock file version 4 requires '-Znext-lockfile-bump'`	cargo 1.75 등 구 버전	`rustup update stable`로 cargo 1.95+ 사용
`gtk4/libadwaita not found`	개발 헤더 누락	`sudo apt install libgtk-4-dev libadwaita-1-dev`
`Qt6Core not found`	Qt6 dev 누락	`sudo apt install qt6-base-dev`
`cxx-qt build error`	Qt 헤더 경로 어긋남	`pkg-config --cflags Qt6Core` 확인
경고 발생	UNIM은 zero-warning 정책	경고 메시지 그대로 이슈로 보고

빌드 명령은 make build가 정본. cargo build --workspace만으로는 C/C++ 프론트엔드가 빠진다.

진단 데이터 수집 (이슈 보고 시 필수)

🐧 리눅스

{
  echo "=== version ==="
  unim-cli --version
  echo "=== env ==="
  echo "session=$XDG_SESSION_TYPE"
  echo "desktop=$XDG_CURRENT_DESKTOP"
  env | grep -E 'GTK_IM|QT_IM|XMOD' | sort
  echo "=== daemon ==="
  systemctl --user status unim-daemon --no-pager
  echo "=== config ==="
  unim-cli config show
  echo "=== logs (last 200) ==="
  tail -n 200 ~/.unim-errors.log 2>/dev/null
} > unim-report.txt

이 unim-report.txt를 이슈에 첨부하면 진단이 빨라진다. 비밀번호·토큰이 로그에 들어갔을 가능성은 낮지만, 첨부 전에 한 번 훑어보길 권장.

더 읽을 거리

FAQ — 다른 IME와의 차이, 동시 설치, 백업 복원
사용자 매뉴얼 — 설정 GUI 페이지별 상세
IME_BEHAVIOR.md — 동작 명세 (개발자용)
AGENTS.md — 아키텍처와 메모리 관리 규칙

🐧 리눅스 — 이하 §16과 0.2.0 릴리스 특이 진단은 리눅스 전용이다.

증상: 한자·특수문자·이모지 팝업이 전혀 안 뜸 (GNOME X11 또는 KDE/Xfce)

0.3.0부터 팝업은 unim-popup-service가 단독으로 렌더한다. 데몬은 살아 있어도 popup-service가 없으면 팝업이 나타나지 않는다.

진단 명령

# popup-service 프로세스 확인
pgrep -a unim-popup

# DBus 인터페이스 노출 확인
busctl --user introspect org.atit.unim.PopupService /org/atit/unim/popup

# D-Bus 서비스 파일 설치 확인
ls ~/.local/share/dbus-1/services/org.atit.unim.PopupService.service \
   /usr/share/dbus-1/services/org.atit.unim.PopupService.service 2>/dev/null

해결 방법

서비스 파일이 없으면 unim-popup-service 실행 파일을 담고 있는 unim-desktop 패키지(인디케이터·레거시 설정창과 한 묶음)가 설치되지 않은 것이다. unim-popup-service 는 독립 패키지가 아니다.
```
# deb 설치 (버전은 실제 다운로드한 파일명에 맞게)
sudo apt install ./unim-desktop_<버전>_amd64.deb
# 또는 소스 빌드 후
sudo make install PREFIX=/usr
```
서비스 파일이 있는데도 팝업이 안 뜨면 수동으로 기동해 로그를 확인한다.
```
UNIM_DEVELOP=1 unim-popup-service &
# 이후 한자 팝업 트리거 → 터미널 로그 확인
```
busctl introspect가 실패하면 org.atit.unim.PopupService 자체가 응답하지 않는 것이다. systemctl --user status unim-popup-service 또는 journalctl --user -t unim-popup-service -b --no-pager로 오류 원인을 확인한다.

증상: 팝업이 클릭하자마자 바로 닫힘

팝업 외부 좌클릭 시 팝업이 닫히는 것은 의도된 동작이다. 클릭 이벤트는 아래 창에 그대로 전달된다. 팝업 내부 셀·버튼 영역을 클릭하면 닫히지 않는다. 팝업 내부를 클릭했는데도 닫힌다면 팝업 크기·위치가 잘못 계산된 것이다 — DBus caret 좌표(caret_rect) 값을 확인한다.

증상: GNOME Wayland에서 팝업이 두 번 뜸

Meta.is_wayland_compositor() 감지가 실패해 extension PopupView와 popup-service GTK4 팝업이 동시에 열리는 경우다. GNOME Shell 버전을 확인하고, 확장(unim-gnome@from104.github.io)을 비활성화 후 재활성화해 본다.

증상: XIM commit 직후 다음 글자가 안 보인다 (일부 해결, 일부 미해결)

조합 중이던 음절이 확정된 직후 새로 누른 자모가 화면에 안 나타나는 증상이다. 0.3.0부터 있었고, 경로에 따라 상태가 다르다.

해결된 범위 (2026-08-07) — 자체 XIM 클라이언트와 OVER-THE-SPOT(XTerm·WezTerm 등)에서는 고쳐졌다. 원인은 그동안 이 문서가 지목하던 "xim crate의 commit()이 preedit_started를 갱신하지 않음"이 아니었다(그 우회책을 통째로 제거해도 증상이 그대로였다). 실제로는 ON-THE-SPOT 클라이언트가 한 키를 처리하다 Commit을 만나면 그 뒤에 온 메시지를 버리기 때문이었고, XIM만 preedit을 commit보다 먼저 보내도록 바꿔 해결했다. 계약은 docs/dev/architecture/IME_BEHAVIOR.md §8.1 예외 항목.

아직 미해결 (2026-08-10 확인) — GTK가 XIM 모듈(im-xim)로 붙는 경로에서는 여전히 증상이 남아 있고, 원인도 위와 다르다. 이 경우 확정 직후 입력기가 잠시 멎어 다음 글자가 몇 초 동안 통째로 씹힌다(libX11이 시간이 지나면 스스로 풀린다). 서버가 PreeditDraw를 보내는 순간 그 입력 문맥이 다음 키를 받지 못하는 것이 원인으로, 3/3 재현된다.

누가 겪나: 주로 Flatpak·Snap 앱이다. 샌드박스 안에는 호스트의 im-unim.so가 보이지 않아 GTK가 XIM으로 폴백한다. 옵시디언(Electron)이 대표적이다.
영향 없는 환경: 일반 설치된 GTK/Qt 앱(네이티브 IM 모듈 사용), XTerm·WezTerm 등 OVER-THE-SPOT 클라이언트.
현재 우회책: 없다. 같은 앱을 deb·AppImage 등 샌드박스 밖 배포판으로 설치하면 네이티브 IM 모듈을 타서 증상이 사라진다. IBus 호환 경로는 0.4.0에서 크게 고쳤지만 아직 조합 중 글자가 표시되지 않아 대안이 되지 못한다.

진행 상황은 ROADMAP 3단계 "샌드박스 앱(Flatpak·Snap) 입력 경로" 항목에서 추적한다.

0.2.0 릴리스 특이 진단

0.2.0 릴리스 직전 manual-test-planner가 작성한 추가 진단 시나리오. 위 §1–§14와 중복되는 항목은 사용자 README가 우선이며, 아래는 보조 진단 도구·세부 회귀 케이스 위주로만 남긴다.

A. 진단 공통 도구 (보조)

명령	용도
`journalctl --user -u unim -b --no-pager`	데몬 systemd 로그 (이번 부팅)
`: > ~/.unim-errors.log; UNIM_DEVELOP=1 /usr/libexec/unim-daemon -n --replace &`	로그 초기화 + 개발자 모드 재시작
`pgrep -a unim-`	모든 unim-* 프로세스 목록
`busctl --user introspect org.atit.unim.InputMethod /org/atit/unim/InputMethod`	DBus API 노출 확인

B. 0.2.0에서 회귀 금지 케이스

gedit 이중 commit (늘늘): focus-out 시 CommitText 시그널 broadcasting 회귀가 0.2.0에서 fix됨. 재현 시 ~/.unim-errors.log | grep -i 'commit_text\|focus_out'.
영문 모드 Space 누락 (gedit): 0.2.0에서 consumed=true commit=" " 경로로 수정. 회귀 시 engine_worker.rs Space 처리 분기 점검.
AutoTypeFix 잔존 BS (XIM): 0.2.0 N+1 BS 모델로 수정됨. Chrome preedit edge case는 알려진 SKIP.
tentative_expiry_hours 단위: 0.2.0부터 days→hours로 변경 (1..=12). 기존 config는 자동 마이그레이션.
XIM commit 직후 다음 글자 누락 (부분 해결): 자체 XIM 클라이언트·OVER-THE-SPOT 은 2026-08-07 에 해결했다 — ON-THE-SPOT 클라이언트가 한 키를 처리하다 Commit 을 만나면 그 뒤 메시지를 버리는 것이 원인이었고(오래 적혀 있던 "xim crate 의 commit() 이 preedit_started 를 갱신하지 않음" 은 오진), XIM 만 preedit 을 commit 보다 먼저 보내도록 바꿨다(IME_BEHAVIOR.md §8.1). 그러나 GTK 가 im-xim 으로 붙는 경로는 2026-08-10 확인 결과 여전히 미해결이며 원인도 다르다 — PreeditDraw 를 보내는 순간 그 IC 가 다음 키를 받지 못한다(3/3 재현). 주 피해자는 Flatpak·Snap 앱이다. 회귀 감시: tests/unim-test-xim·tests/unim-test-gtk3(ON-THE-SPOT)와 xterm(OVER-THE-SPOT), 그리고 GTK_IM_MODULE=xim 으로 띄운 tests/unim-test-gtk3.

C. 데몬 다중 인스턴스

pkill -9 -x unim-daemon; sleep 1; systemctl --user start unim
DBus 자동 활성화 + 수동 실행이 겹치는 경우 발생. 수동 실행 시 --replace 플래그 사용.

caret_rect 미수신: cursor_y = 0 fallback. POPUP_SPEC §6.3 좌표 소스 확인.
9칸 ↔ 81칸 토글 안 됨: Period(.) 키가 다른 곳에서 가로채짐. 키맵 확인.
책갈피(★) 동기화: HanjaBookmarkChanged 시그널 미수신. busctl --user monitor org.atit.unim.InputMethod로 시그널 흐름 확인.

E. CLI 한국어 깨짐

locale 미설치: sudo locale-gen ko_KR.UTF-8
gettext mo: ls /usr/share/locale/ko/LC_MESSAGES/unim*.mo

F. `unim-cli config set` 후 GUI 미반영

데몬이 mtime 핫리로드 못함 → pkill -SIGHUP unim-daemon
5지점 sync 깨짐 가능성 → CLI/엔진/GUI/locale/dbus 5점 모두 갱신됐는지 점검.

G. 환경 매트릭스 (0.4.0 재확인 — 최초 작성은 0.3.0)

환경	지원 상태	비고
GNOME Wayland	✅ 검증	GNOME extension `popup_view.js` (St 위젯) 자체 렌더
GNOME X11	✅ 검증	popup-service GTK4 + GNOME extension 보조
X11 + KDE Plasma 5.x	✅ 검증	popup-service GTK4
X11 + XFCE / MATE / Cinnamon / LXDE	✅ 검증	popup-service GTK4
Wayland + KDE Plasma 5.x	❌ 미지원	`gtk4-layer-shell` 미배포 (Ubuntu 24.04 noble 표준 저장소) → X11 세션 / GNOME 우회
Wayland + KDE Plasma 6	⚠️ 실험적	`wayland-backend` feature + `libgtk4-layer-shell` 필요. 0.4.0 QA 미검증(0.3.0 이후 변경 없음)
Sway / Hyprland / river (단독 Wayland)	⚠️ 실험적	동상. popup 위치·IME 포커스 회귀 가능
Weston 등 reference Wayland	⚠️ 실험적	동상

0.4.0 재확인 결과: 위 표는 0.4.0 릴리스 시점에도 여전히 유효하다 — 순수 Wayland(비-GNOME) 환경의 한자/특수문자 팝업은 이 릴리스에서도 미지원이며(설계 제약, 유지), GNOME 을 거치지 않는 Wayland 컴포지터는 여전히 「실험적」 지위다. Windows(TSF, 64비트·32비트 unim_tsf32.dll)는 v0.4.0에서 새로 추가된 실험적 플랫폼이며 이 표에는 포함하지 않는다 — 별도로 FAQ Q11 참고.

⚠️ 실험적 환경에서 문제 발견 시 GitHub Issues 로 제보 부탁드립니다.

H. 로그 분석 슬래시 명령

# Claude Code 사용 시
/unim-log

→ ~/.unim-errors.log 자동 분류·요약·진단.

▲ 목차로

UNIM 사용자 매뉴얼 (한국어)

1. UNIM이 무엇인가 (30초 설명)

2. 빠른 시작 (5분)

2.1 설치

방법 1 — 자동 설치 스크립트 (권장)

방법 2 — Releases 수동 다운로드

방법 3 — 소스 빌드 (Arch/Fedora/그 외)

2.2 환경 변수 (GNOME 확장을 안 쓰는 모든 데스크톱)

2.3 GNOME + Wayland 사용자

2.4 첫 한글 입력 (60초)

2.5 팝업 동작 개요

3. 환경별 설정 가이드

3.1 Flatpak/Snap 앱에서 한글이 안 나올 때

4. 일상 사용

4.1 한/영 모드 전환

4.2 한자 변환 (Hanja)

페이지 이동 (마우스/키보드)

우클릭 동작 — 환경별 차이

즐겨찾기 ☆/★

4.3 특수문자 입력

4.4 자동 오타 교정 (AutoTypeFix)

억제 사전 (Blacklist) — 사용자 학습

토글 단축키 — 지정한 키로 즉시 켜고 끄기

비밀번호 필드 자동 보호

4.5 자동 영문 모드 전환 (Auto-English-Mode)

4.6 단어 단위 입력 (조합 확정 단위)

5. 설정 GUI 투어

5.1 페이지 1 — 일반

5.2 페이지 2 — 오타 교정

5.3 페이지 3 — 교정 억제 단어

5.4 페이지 4 — 사용자 사전 (역방향 화이트리스트)

5.6 자판 도구 (Keymap Studio / Typing Practice)

5.6.1 unim-keymap-studio — 자판 보기·편집

단축키

5.6.2 unim-typing-practice — 타자 연습

단축키

6. 키 매핑 치트시트

7. CLI 사용법 (unim-cli)

7.1 변환 필터

7.2 설정 관리

8. 설정 파일 위치 / 백업

9. 다음 단계

키보드 단축키 가이드

GNOME 전용 — 수동 변환 단축키 (기본 활성)

이모지 팝업 단축키 (Super+.)

환경별 동작 매트릭스

왜 직접 등록이 필요한가?

공통 명령

환경별 등록 방법

KDE Plasma 6 (Wayland)

Hyprland

Sway

Wayfire

GNOME (확장 없이 사용할 때 fallback)

X11 + 임의 WM (xbindkeys)

동작 확인

자판 도구 앱 내부 단축키

unim-keymap-studio (자판 보기·편집)

unim-typing-practice (타자 연습)

참고

UNIM FAQ (한국어)

Q1. 다른 한글 IME(ibus-hangul, fcitx-hangul, kime, nimf)와 무엇이 다른가?

Q2. 시스템 IME와 동시에 설치해도 되나?

Q3. 어떤 환경이 가장 안정적인가?

Q4. AutoTypeFix는 정확히 어떻게 동작?

단계 1 — 관측

단계 2 — 트리거

학습 (억제 사전)

Q5-1. 즐겨찾기를 끄면 popup이 다른 페이지로 휙 넘어가는데 정상인가?

Q5. 한자 9칸 vs 81칸 차이는?

Q6. 설정 파일 위치, 백업과 복원은?

위치

백업

복원

Q7. 자판은 어떤 게 있고, 새로 추가할 수 있나?

내장 한국어 자판

영어

사용자 정의

Q8. UNIM의 메모리 사용량은 얼마나 되나?

Q9. UNIM이 비밀번호 입력을 가로채는가?

7. CLI 사용법 (`unim-cli`)

이모지 팝업 단축키 (`Super+.`)

Q9-2. `install.sh`(한 줄 설치)는 안전한가요?

1. Wayland Chrome (네이티브, `--enable-wayland-ime` 미활성화)