# strans

An input method daemon for CJK text entry on X11 and Wayland.

Inspired by 9front's ktrans. Threads communicate via CSP channels.

## Dependencies

- plan9port
- Python 3 (for generated-map checks)
- dbus-1
- wayland-client, libxkbcommon (for Wayland support)
- gtk+-3.0 (optional, for GTK IM module)

## Build

	make
	cd xim && make                          # XIM adapter
	cd gtk && make docker && make install   # GTK IM module

Unit tests use the sibling `cutest` Git repository as a submodule and do not
require the Wayland, D-Bus, GTK, or X11 development packages. Repository
mirrors must provide the same sibling; initialize it after cloning with
`git submodule update --init`:

	make check                               # generated map + unit tests
	make test TESTARGS=hangul                # filtered unit tests only
	make verify-map                          # generated-map check only

The suite covers the fixed-size UTF-8 string, hash table, trie fixtures,
Japanese/Hangul/Telex state transitions, dictionary candidates, engine
selection state, IPC request fields, and production map loading. Tests use
explicit case tables, boundary values, and small regressions for repaired core
contracts. Full IPC and GUI protocol stacks require separate integration checks.

## Run

	./strans map font &

For XIM apps:

	./xim/strans-xim &
	XMODIFIERS=@im=strans xterm

For GTK apps:

	GTK_IM_MODULE=strans gedit

For IBus apps (kitty, foot, etc.):

	GLFW_IM_MODULE=ibus kitty

For Wayland apps (text-input-v3 clients on wlroots compositors):

	# nothing to set; the compositor relays text-input-v3 to strans

Strans itself is the IBus endpoint and the Wayland input-method-v2 client;
no ibus-daemon or fcitx5 needed. Start strans after the compositor.

## Usage

Switch input modes with Ctrl + key:

	N  Hiragana
	K  Katakana
	S  Hangul
	T  English
	V  Vietnamese (Telex)
	P  Toggle preedit echo

Type romanized input. Select candidates with 1-9 or arrow keys.
Outside one-shot search, Tab or Enter commits.

### Emoji and symbols

Ctrl+E starts a one-shot symbol search; it is not a mode. Any current preedit
is committed, then the previous language is kept for the next input. Type an
English alias or the phonetic keys of the current layout (Korean aliases work,
for example). The candidate list is shown even when Ctrl+P has hidden normal
preedit echo.

	안녕 → Ctrl+E → smile → Enter → 😀

There is no auto-insert. Enter commits the first candidate (or the current
one); arrows and Tab move, and Esc cancels. Bare 1 through 9 select an existing
numbered row; a bare digit with no such row and 0 remain query text. Digit
aliases are kept in matching slots, so `^1`, `_2`, and `<3` produce `¹`, `₂`,
and `♥`.

`map/emoji.src` is the source of truth: each UTF-8 TSV row is a result followed
by one or more tab-separated aliases. Aliases may be multilingual and ASCII
letters are case-insensitive. Results and aliases are limited to 64 Unicode
code points; results cannot contain whitespace. Run `map/mkemoji > map/emoji.dict`
after editing it; `make verify-map` checks the generated dictionary and the
Telex map.

	😀	웃음	웃다	스마일	smile	grin

## Architecture

Threads communicate via CSP channels:

- [imthread](strans.c): keystroke processing, transliteration
- [dictthread](dict.c): dictionary lookup
- [drawthread](win.c): preedit window rendering
- [srvthread](srv.c): IPC via unix socket
- [ibusthread](ibus.c): IBus D-Bus endpoint for GLFW/kitty
- [waylandthread](wayland.c): Wayland input-method-v2 + virtual-keyboard-v1

Adapters (strans-xim, im-strans.so) bridge X11/GTK events.

## Files

	strans.c    input method engine
	dict.c      dictionary queries
	win.c       xcb window management
	font.c      truetype rendering (stb_truetype)
	wayland.c   wayland input-method-v2 adapter
	map/        transliteration tables
	font/       bundled CJK fonts

	input-method-unstable-v2-*.{c,h}   wayland-scanner output, vendored
	virtual-keyboard-unstable-v1-*.{c,h}

The two Wayland protocols (input-method-v2, virtual-keyboard-v1) are
wlroots-only and not in the upstream wayland-protocols package, so the
generated client code is vendored. Regenerate with wayland-scanner if
the XML upstream ever changes (it hasn't in years).

## References

- https://git.9front.org/plan9front/plan9front/HEAD/info.html
- https://np.mkv.li/kor/9front-ktrans-%ED%95%9C%EA%B8%80-%EB%98%91%EB%B0%94%EB%A1%9C-%EB%A7%8C%EB%93%A4%EA%B8%B0/
- https://en.wikipedia.org/wiki/Telex_(input_method)
- https://gist.github.com/hieuthi/0f5adb7d3f79e7fb67e0e499004bf558