From e018a742a335faf989a94d72c75d6e36696a564d Mon Sep 17 00:00:00 2001 From: Tyler Hallada Date: Tue, 19 May 2026 17:07:40 -0400 Subject: [PATCH] Add README.md --- README.md | 209 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..7157f9f --- /dev/null +++ b/README.md @@ -0,0 +1,209 @@ +# keydr + +A terminal typing tutor with adaptive learning, a skill-tree progression +system, and live statistics — built in Rust on [ratatui]. Heavily inspired by +[keybr.com], extended for code practice and the terminal. + +Warning: still very much a WIP and is heavily vibe-coded so there may be bugs. +Backwards compatibility is not guaranteed in this phase of development. + +## What makes it different + +Most TUI typing apps either drop you on a fixed word list or randomize from a +dictionary. keydr keeps a model of _your_ typing: per-key timing, per-bigram +error rates, and a confidence score for every key on the keyboard. The text it +generates for you is shaped by that model — words bias toward the keys you're +slowest at, new keys unlock only when the keys you already have are solid, and +the difficulty grows with you. + +## Features + +### Adaptive engine + +- **Per-key confidence model.** Every keystroke updates an exponential moving + average of your per-key time. Your `confidence` for a key is your target + speed divided by that filtered time — a key with `confidence >= 1.0` is at + or above your target speed. +- **Gradual letter unlocking.** You start with 6 letters in English-frequency + order (`e t a o i n …`). A new letter unlocks only when every letter you + already have is confident, so you're never thrown into the full alphabet at + once. +- **Focused-key biasing.** Whichever included key has the lowest confidence + becomes your "focused" key. The generator searches its Markov chain for + states containing the focused letter and starts pseudo-words from there, so + drills naturally pile up practice on your weak spots. +- **Phonetic pseudo-word generation.** Words are generated from a Markov + transition table (the same approach as keybr) so they're pronounceable and + language-shaped, not random consonant noise. +- **N-gram error tracking.** Beyond single keys, keydr tracks bigrams and + trigrams with Laplace-smoothed error rates and a redundancy formula that + separates _genuine_ transition difficulties (e.g. awkward same-finger + bigrams) from errors that are just proxies for a single weak key. Hard + bigrams get folded into drill selection. + +### Skill tree + +Once you've mastered the lowercase alphabet, you don't just keep grinding +prose — five sibling branches unlock at once and you pick what to drill next: + +- **Capitals** (A–Z, 3 levels) — sentence-start and proper-noun rules +- **Numbers** (0–9, 2 levels) +- **Prose punctuation** (`. , ' " ? !` …, 3 levels) +- **Whitespace** (Tab, Enter, …, 2 levels) +- **Code symbols** (`{ } [ ] ( ) ; : = + - * /` …, 4 levels) + +Each branch tracks its own current level and its own focused key. You can have +multiple branches "in progress" at once, and drills can be scoped globally +(everything you've unlocked) or to a single branch. + +### Three drill modes + +- **Adaptive** — the default. Generated text from the phonetic model, biased + by your skill-tree scope and focused key. +- **Code** — language-specific syntax practice. Bundled snippets for Rust, + Python, JavaScript, and Go, with optional opt-in downloads of real code + samples from GitHub for more variety. Configurable per-language, with an + onboarding screen on first use and a download progress screen. +- **Passage** — type real prose from public-domain books (Project + Gutenberg). Opt-in downloads, configurable paragraphs-per-book limit, falls + back to bundled content when offline. + +### Statistics dashboard + +A multi-tab dashboard with everything the engine has learned about you: + +- **Dashboard** — current WPM, accuracy, confident-key count, level/streak +- **History** — recent drills with WPM/accuracy +- **Activity** — a GitHub-style heatmap of drilling activity over time +- **Accuracy** — per-key accuracy heatmap laid out on the keyboard +- **Timing** — per-key timing heatmap +- **N-grams** — your worst bigrams/trigrams, redundancy scores, watchlist of + emerging weak transitions, and what's currently driving drill focus + +### Visual keyboard + +A live keyboard diagram colors each key by the finger that should press it, +highlights your focused key, and (in terminals that support the Kitty keyboard +protocol) lights up modifier keys as you press them. A separate **Keyboard +Explorer** screen lets you click around the layout to inspect any key's +stats. + +### Theming + +14 built-in themes: Catppuccin (Mocha/Latte), Dracula, Gruvbox (Dark/Darkest), +Kanagawa (Wave/Dragon/Lotus), Nord, One Dark, Solarized Dark, Tokyo Night, +Farout, plus an ANSI-safe `terminal-default` that respects your terminal's +own colors. + +### Internationalization + +- **UI translated into 21 languages** (`en`, `de`, `es`, `fr`, `it`, `pt`, + `nl`, `sv`, `da`, `nb`, `fi`, `pl`, `cs`, `ro`, `hr`, `hu`, `lt`, `lv`, + `sl`, `et`, `tr`). +- **Dictionaries for the same 21 languages**, sourced from + [keybr-content-words](https://github.com/aradzie/keybr.com). +- **Keyboard layout profiles**: QWERTY, Dvorak, Colemak, German QWERTZ, + French AZERTY — with per-layout finger maps so the diagram stays accurate. +- Unicode-normalized (NFC) input matching, so composed and decomposed forms + of accented characters compare equal. + +### Import / export + +Back up everything — config, profile, key stats, ranked stats, drill history +— to a single timestamped JSON file from the Settings page, and restore it on +another machine. Machine-local paths (download directories) are preserved +from the target machine on import. Versioned format with a clear error if +schemas don't match. + +### Other niceties + +- Atomic JSON writes (temp file → fsync → rename) so a crash mid-save can't + corrupt your stats. +- Auto-continue between drills with a brief input lock so a trailing + keystroke doesn't start the next drill prematurely. +- Mouse support for menus, tabs, and the keyboard explorer. + +## Build and run + +keydr is a regular Cargo project. You need a recent Rust toolchain (Rust +edition 2024, i.e. a 2026-era stable compiler). + +```sh +git clone keydr +cd keydr +cargo run --release +``` + +Or build once and run the binary: + +```sh +cargo build --release +./target/release/keydr +``` + +### CLI flags + +```sh +keydr [--theme ] [--layout ] [--words ] +``` + +- `--theme, -t` — pick a theme by name for this run (e.g. `dracula`, + `nord`, `catppuccin-mocha`) +- `--layout, -l` — pick a keyboard layout: `qwerty`, `dvorak`, `colemak`, + `de_qwertz`, `fr_azerty` +- `--words, -w` — number of words per drill + +Everything else is set from inside the app, on the Settings screen. + +### Features + +The `network` Cargo feature (on by default) pulls in `reqwest` and enables the +optional GitHub code download and Project Gutenberg passage download flows. To +build a fully offline binary: + +```sh +cargo build --release --no-default-features +``` + +### Files on disk + +- Config: `~/.config/keydr/config.toml` +- Profile, key stats, drill history: `~/.local/share/keydr/*.json` +- Downloaded passages: `~/.local/share/keydr/passages/` +- Downloaded code samples: `~/.local/share/keydr/code/` + +(`dirs` is used to resolve these, so the exact paths follow XDG/macOS/Windows +conventions on your platform.) + +### Tests and benchmarks + +```sh +cargo test +cargo bench # n-gram benchmarks in benches/ +``` + +## Terminal requirements + +keydr works in any reasonably modern terminal. For the best experience — +modifier-key highlighting on the keyboard diagram, unambiguous key +disambiguation, and per-key release events — use a terminal that supports the +[Kitty keyboard protocol] (Kitty, WezTerm, foot, recent Ghostty, recent +Alacritty). keydr falls back gracefully on terminals that don't (tmux, mosh, +SSH to older hosts) using timer-based heuristics. + +A true-color terminal is recommended so the bundled themes render as +intended; the `terminal-default` theme is provided for ANSI-only setups. + +## License and attribution + +keydr is licensed under the GNU Affero General Public License v3.0 only +(AGPL-3.0-only) — see [LICENSE](LICENSE). + +It incorporates content and ideas from [keybr.com] (dictionaries, the core +adaptive algorithm). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for +attribution and [docs/license-compliance.md](docs/license-compliance.md) for +the compliance process. + +[ratatui]: https://ratatui.rs/ +[keybr.com]: https://www.keybr.com/ +[Kitty keyboard protocol]: https://sw.kovidgoyal.net/kitty/keyboard-protocol/