specs

CleverKeys Technical Specifications

Technical documentation for CleverKeys, an Android keyboard with on-device swipe typing. These specs are designed for LLM coding agents to understand the codebase architecture and implementation details.

Specification Index

Core System

Spec	Description
Core Keyboard System	InputMethodService, view hierarchy, key events, layout management
Suggestion Bar & Content Pane	Word predictions; emoji/clipboard/GIF panes swapped in a topPane FrameLayout (SuggestionBarPane; the old ViewFlipper was replaced in v1.2.5)
Gesture System	Swipe detection, multi-touch, gesture classification
Layout System	XML layouts (src/main/layouts → R.raw), ExtraKeys, per-layout language/theme bindings, modified-layout cache
Foldable Keyboard Height	Inner/outer-screen keyboard height on foldables (implemented 2026-10-20)

Swipe Prediction

Spec	Description
Cursor-Aware Predictions	Cursor sync (single SuggestionHandler pipeline since 2026-07-20), exact_add, contraction prefix guard
Context Learning & Next-Word	Persistent learned n-gram LM, master privacy gate, next-word prediction (on by default), suggestion provenance, learned-data manager
Geometric Swipe Engine	Layout-agnostic geometric swipe decoder (swipe/geometric/)
CTC Swipe Engine	CTC trie-beam swipe engine — the DEFAULT ctc mode, CleverKeys-trained ONNX encoder
CTC Architecture & Multi-Script Guide	Reference: CTC graph contract, routing rule, multi-script recipe
CTC Context Rescoring & Tunables	Bigram/trigram swipe rescoring (built, CLOSED default-OFF 2026-08-26) and the decode-time tunables inventory

The ONNX transformer engine's specs (neural-prediction, neural-multilanguage-architecture, kv-cache-optimization, nn-inference-optimization, memory-pool-optimization) moved to docs/history/neural-engine/ when that engine was removed — see ADR-011.

Dictionary & Language

Spec	Description
Dictionary System	Word lookup, frequency ranking, user dictionary
Secondary Language	Multi-language typing, language detection
Language-Specific Dictionary	Per-language dictionary management
English Dictionary Pipeline	Dictionary generation and quality pipeline (evidence classifier)
Autocorrect Ranking	Tap autocorrect: noisy-channel rule and weights (AutocorrectTuning), gates, κ/δ, prefix length, Persian half-space offer rule; evidence pointers

Customization

Spec	Description
Short Swipe Customization	Per-key gesture customization, CommandRegistry
Per-Layout Subkey	Proposal only — NOT BUILT (mappings are global)
Subkey Customization	Current subkey implementation details
Subkey Popover	Hold-then-select 3×3 subkey grid, neutral zone, assign/edit screens
Profile System	Settings backup/restore, layout import/export

Settings & Modes

Spec	Description
Settings System	SharedPreferences, settings UI, configuration
Settings-Layout Integration	GUI mapping to layout system
Cursor Navigation	Spacebar slider, arrow key navigation
TrackPoint Mode	Joystick-style cursor control
Selection-Delete Mode	Text selection via backspace gesture
Password Field Mode	Secure password input handling

Features

Spec	Description
Quick Settings Tile	Shade tile: minimize / restore / show the keyboard, picker fallback (2026-10-20)
Clipboard System	3-tab clipboard (history/pinned/todos), schema V5 (DATABASE_VERSION = 5: #156 private copy), media, tags, todos
Clipboard Privacy	Password manager exclusion + media privacy gating
Keyboard Minimize	Assignable bar and floating-button minimize commands, lifecycle and touch geometry
Timestamp Keys	Date/time insertion keys
Termux Integration	Terminal keyboard optimizations
GIF Panel	Offline GIF panel and pack system

Reference

Spec	Description
Architectural Decisions	ADRs for major design choices (ADR-001 … ADR-011; ADR-008 superseded)
Testing Strategy	Executed JVM/MockK/native evidence, expanded gap coverage and pinned ew-cli workflow
Performance Optimization	Targets and strategies; CleanupHandler; no monitoring system exists
Typo-Drop Rescue Pipeline	Superseded 2026-07-02 by scripts/build_wordlist.py; kept for provenance
SPEC_TEMPLATE.md	Template for new specifications

Key Source Files

File	Purpose
CleverKeysService.kt	Main InputMethodService
Keyboard2View.kt	Custom view rendering
KeyboardData.kt	Key layout model (there is no Keyboard2.kt)
KeyEventHandler.kt	Key press processing + text editing (direct InputConnection calls; no InputConnectionManager exists — see core-keyboard-system.md)
KeyboardReceiver.kt	IReceiver impl: InputConnection access, event routing
Pointers.kt	Touch handling and gestures
Config.kt	All settings with defaults
activities/SettingsActivity.kt + ui/settings/	Settings UI (Jetpack Compose)
KeyValue.kt	Key definitions (300+ keys)
swipe/CtcEngineAdapter.kt	Swipe decoding (CTC)
DictionaryManager.kt	Dictionary management

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    CleverKeysService                        │
│                  (InputMethodService)                       │
├─────────────────────────────────────────────────────────────┤
│  ┌────────────────┐  ┌────────────────┐  ┌──────────────┐  │
│  │ Keyboard2View  │  │ KeyEventHandler│  │ Keyboard     │  │
│  │ (Rendering)    │  │ (Processing +  │  │ Receiver     │  │
│  │                │  │  text commit)  │  │ (IReceiver:  │  │
│  │                │  │                │  │  InputConn.) │  │
│  └───────┬────────┘  └───────┬────────┘  └──────┬───────┘  │
│          │                   │                   │          │
│  ┌───────▼────────┐  ┌───────▼────────┐         │          │
│  │  KeyboardData  │  │   Pointers     │         │          │
│  │ (Layout model) │  │ (Touch/Gesture)│         │          │
│  └───────┬────────┘  └───────┬────────┘         │          │
│          │                   │                   │          │
│  ┌───────▼───────────────────▼───────────────────▼───────┐  │
│  │                    Config                              │  │
│  │            (Settings, Preferences)                     │  │
│  └────────────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                    Swipe Prediction Pipeline                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  CtcEngine   │  │  ONNX CTC    │  │  Trie beam   │       │
│  │  Adapter /   │→ │  encoder     │→ │  over merged │       │
│  │  Geometric   │  │  (or SHARK2) │  │   lexicon    │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘

Common Patterns (real entry points, 2026-10-23)

Settings Access

// Read: Config is a snapshot rebuilt by ConfigurationManager on every pref change
val value = Config.globalConfig().some_field          // or globalConfigOrNull()

// Write: only the settings UI writes prefs, through a SettingsActivity extension
internal fun SettingsActivity.saveSetting(key: String, value: Any)   // ui/settings/SettingsPersistence.kt
// There is no Config.saveSetting; ConfigurationManager.onSharedPreferenceChanged → Config.refresh

Key Event Handling

// KeyEventHandler.kt — the IKeyEventHandler entry points called by Pointers
override fun key_down(key: KeyValue?, isSwipe: Boolean)                                   // :75
override fun key_up(key: KeyValue?, mods: Pointers.Modifiers, isKeyRepeat: Boolean)      // :99
private fun handleEditingKey(ev: KeyValue.Editing)                                        // :861 — the one implementation of editing commands

Gesture Classification

// gesture/GestureClassifier.kt (pure)
class GestureClassifier {
    enum class GestureType { … }
    data class GestureData(…)
    fun classify(gesture: GestureData, config: ConfigSnapshot): GestureType               // :47
}
// Short-swipe vs TrackPoint vs selection-delete vs popover routing itself lives in Pointers.kt

Related Documentation

• User Guide Wiki - End-user documentation
• CHANGELOG - Version history
• TODO - Current tasks