VieLotusIM (Sen Việt)

A lightweight, memory-safe Vietnamese input method built natively for the Apple ecosystem (macOS, iOS, and iPadOS). Designed to replace legacy IME cores with a modern, zero-privilege, and crash-resilient architecture.

┌────────────────────────────────────────────────────────────────────────┐
│                        Apple Host Environment                          │
│   macOS (IMKInputController / IMKServer)   │   iOS (UIInputViewController)  │
└───────────────────▲────────────────────────────────────▲───────────────┘
                    │                                    │
┌───────────────────┴────────────────────────────────────┴───────────────┐
│                      VieLotusCore (Pure Swift 6)                       │
│  ┌────────────────────────┐  ┌──────────────────────────────────────┐  │
│  │  InputSessionManager   │  │        SmartBilingualDetector        │  │
│  │  - Composing state     │  │  - Heuristic tone rules              │  │
│  │  - Caret stepping      │  │  - NSSpellChecker / UITextChecker    │  │
│  │  - Telex / VNI engines │  │    via SpellCheckerProvider          │  │
│  └────────────────────────┘  └──────────────────────────────────────┘  │
│  ┌────────────────────────┐  ┌──────────────────────────────────────┐  │
│  │     ClientAdapter      │  │          PresentationRules           │  │
│  │  - App categorization  │  │  - typing-modes.yml (zero-dep)       │  │
│  │  - UTF-16 sync         │  │  - User/App preference overrides     │  │
│  └────────────────────────┘  └──────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────┘

• Core Engine (VieLotusCore): Pure Swift 6 with complete memory safety, zero C/C++ dependencies, and zero raw pointers. Built solely on Apple's Foundation.
• macOS Integration (VieLotusIM): Apple's official InputMethodKit (IMKInputController, IMKServer, IMKTextInput). Operates as a native input method bundle.
• iOS / iPadOS Integration: UIKit (UIInputViewController, UITextDocumentProxy) sharing the identical underlying core state machine.
• Bilingual & Lexical Intelligence: Hybrid rule-based parser paired with NLLanguageRecognizer and system spell-checking via the SpellCheckerProvider protocol (macOS injects NSSpellChecker with a 64K LRU cache).
• Client Configuration Engine: PresentationRules parses typing-modes.yml with a custom zero-dependency parser, resolving application-specific typing behaviors in sub-millisecond time.
• Diagnostics & Benchmarking: VieLotusCLI and VieLotusTrace running a 9,091-case regression suite, latency gates, and continuous ratchet floors.

• The Problem: Legacy Vietnamese input methods rely on synthetic backspaces (via CGEventTap or Carbon key-up hacks) to delete raw keys and replace them with composed syllables. In modern frameworks with virtual DOMs or asynchronous input queues (Google Docs, Notion, Slack, VS Code Monaco Editor, React/Electron), these artificial backspaces race with user input, causing dropped characters, duplicated words, or cursor jumping.
• Solution: VieLotusIM strictly implements Apple's native composition protocol (setMarkedText:selectionRange:replacementRange:). Syllables are composed in-flight under an uncommitted underline and committed atomically upon space or punctuation (insertText:replacementRange:).

• The Problem: Common English words and programming syntax (git, commit, test, restrict, toast, blood, floor, door, width, const) collide with Telex transformation keys (s, f, r, x, j, w, aa, ee, oo). Eagerly transforming them breaks English typing, while overly broad whitelisting degrades Vietnamese typing.
• Solution: SmartBilingualDetector enforces linguistic constraints (e.g. stop-coda tone validation where -c, -ch, -p, -t strictly require Sắc/Nặng tones) and evaluates lexical context.

• The Problem: Firing bursts of backspaces corrupts the host application's undo stack, causing Cmd + Z to erase full paragraphs rather than stepping back keystroke by keystroke.
• Solution: Atomic buffer replacement preserves the text input client's undo manager integrity.

• The Problem: Modern GPU-accelerated terminal emulators (Ghostty, Alacritty, Kitty) manage raw cursor positions and require strict UTF-16 code unit offset synchronization rather than loose Unicode grapheme cluster guesses.
• Solution: Direct replacement mode synchronizes UTF-16 code units with the terminal cursor to prevent trailing artifacts.

Measured on 2026-10-11 release build using the bundled 9,091-case regression suite:

brew install stevedat/tap/vielotus

1. Download VieLotusIM.pkg from the Latest Release.
2. Run the installer (auto-registers the input method).
3. Open System Settings $\rightarrow$ Keyboard $\rightarrow$ Text Input $\rightarrow$ Edit...
4. Add Vietnamese $\rightarrow$ Sen Việt (VieLotusIM).
5. Remove the legacy Apple Vietnamese keyboard to prevent input conflicts.

# Clone the repository
git clone https://github.com/stevedat/VieLotus-IM.git
cd VieLotus-IM

# Build all targets (Core, App, CLI, Lab, Trace)
swift build -c release

# Run the full unit test suite (102 tests)
swift test

# Run the 9,091-case regression benchmark
swift run VieLotusCLI --benchmark

# Run the ratchet check against benchmark floors
./scripts/benchmark_ratchet.sh

# Build release universal macOS application bundle
./scripts/build_imk.sh

# Build auto-registering installer package (VieLotusIM.pkg)
./scripts/build_pkg.sh

VieLotusIM is licensed under the MIT License. Created and maintained by Steve Dat (@stevedat).