# 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, and production map loading. Tests use explicit case tables,
boundary values, and small regressions for repaired core contracts. IPC and GUI
protocol stacks are outside this suite and 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)
	E  Emoji
	P  Toggle preedit/candidate popup window

Type romanized input. Select candidates with 1-9 or arrow keys.
Tab or Enter to commit.

## 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