--- title: Typing Tutor --- # Typing Tutor ## What it is A **plugin** for learning and improving touch typing. It teaches proper technique from the home row up, adapts to the exact keys you struggle with, and wraps it all in a light game layer (XP, levels, streaks, achievements). Everything runs locally on your machine — no AI, no internet, no cost, and nothing about your typing leaves the device. > Typing Tutor was formerly a built-in feature; it is now a self-contained **marketplace plugin** > (the Foundry / RepoGuard model). Nothing about the practice experience changed — it just ships > as an installable plugin instead of baked-in code. ## Where to find it Install **Typing Tutor** from the plugin marketplace like any other plugin. Once installed + enabled it appears as a row in the sidebar; click it to open. Its screens run in the plugin's own window: a left sidebar holds the controls (modes, Practice/Progress, settings, reset) and the practice area fills the panel beside it. It is **desktop-oriented** — touch typing needs a physical keyboard, so on a touch-only device it shows a short "open this on desktop" note instead of the practice UI. If you used the old built-in version, your progress carries over automatically: a one-time migration copies your saved profile + history into the plugin's own storage the first time the plugin is installed (see *Under the hood*). ## How it behaves ### The three modes The sidebar switches between: - **Learn** — for beginners. You start on the home row (`a s d f j k l ;`). An on-screen keyboard highlights the next key to press and tells you which finger to use. New keys are introduced **only once you've mastered the ones you have**, following a standard touch-typing order (home row → top row → bottom row). The very first time a new user opens Learn, a one-time **"New to touch typing?"** card offers three quick tips; it disappears after the first round or a **"Got it"** click and never returns. - **Drill** — for people who already type and want to get faster. It uses real words drawn from a common-word list and quietly biases them toward the specific keys you're slowest or least accurate on. - **Challenge** — a timed 60-second run. It scores you and tracks your personal best per mode. A **Practice / Progress** switch (also in the sidebar) — "Progress" opens the stats view (below). ### The typing experience The practice text is shown character by character: dim for not-yet-typed, solid once typed correctly, red where you made a mistake, with a caret on the current character. A live readout shows your **WPM**, **accuracy**, and progress (and a countdown in Challenge). There's an optional on-screen keyboard and optional keypress/level-up sounds (both are toggles in the sidebar's **Settings**; sounds are off by default, generated on the fly — no downloaded audio). When a round finishes you get a results card: WPM, accuracy, XP earned, any new keys you unlocked, a level-up banner, and any achievements — then **Retry** (same text) or **Next** (a fresh round). #### The "intelligent" part The tutor keeps a per-key model of how fast and accurately you type each character. A key is "mastered" once you've typed it enough times, quickly enough, with a low enough error rate. Practice text is weighted toward your weak keys, and in Learn mode the next key unlocks only when your current set is mastered. This is a purely local, deterministic algorithm — the same idea sites like keybr use — so it's instant, private, and works offline. ### The game layer - **XP + levels** — every round earns XP scaled by correct characters, accuracy, speed, and mode difficulty. Levels follow a smooth increasing curve (a small XP bar shows progress to the next). - **Daily streak** — practice on consecutive calendar days to build a streak; miss a day and it resets. - **Achievements** — unlockable badges like "First Steps", "Home Row Hero", the "30/50/80/100 WPM" club, "Flawless", streak milestones, "Full Keyboard", and "Marathon" (50 rounds). - **Personal bests** — your best WPM and accuracy, per mode. ### The Progress view A read-only summary: a **WPM-over-time** line chart of recent rounds, a color-coded keyboard **heatmap** (greener keys are ones you type fast and accurately), your **personal bests** per mode, and the **achievements** grid (earned vs. locked). A **Reset progress** button at the bottom of the sidebar (with a confirm step) clears all progress; it can't be undone. ### Privacy & cost 100% local. Your progress is saved in the plugin's own storage on your machine; nothing is sent anywhere and no AI/network calls are made, so it costs nothing to use. ### Limitations (this version) QWERTY only; a single local profile; no online/multiplayer leaderboards; no AI-generated practice; desktop-oriented. ## For agents ### Under the hood (for agents) - **Self-contained webview plugin** — [src/plugins/typing-tutor/](../../src/plugins/typing-tutor/). UI-only (no worker backend). The manifest declares two storage collections (`typing_profile` — a single JSON blob; `typing_sessions` — one row per round) and the `storage` permission only. - **Engine** — [webview/src/engine/](../../src/plugins/typing-tutor/webview/src/engine/): the pure, deterministic model (`lesson-model`, `text-generator`, `scoring`, `gamification`, `profile` / `applyRound`, `rng`, `constants`), copied from the old shared engine. It now runs IN the webview, so scoring is local — the plugin owns its own data; there is no separate main-process authority (and none is needed, since it is the user's own practice data). Pinned by `engine.test.ts`. - **Data + reset** — [webview/src/lib/persistence.ts](../../src/plugins/typing-tutor/webview/src/lib/persistence.ts) reads/writes the plugin's collections through the bridge (`window.AgentMC.db`); the keystroke loop is [useTypingSession.ts](../../src/plugins/typing-tutor/webview/src/useTypingSession.ts). Reset is a confirm-gated button in the plugin UI (the old agent-callable `POST /typing-tutor/reset` route was intentionally not carried over). - **Migration (continuity)** — [typing-tutor-collection-migration.ts](../../src/main/services/marketplace/typing-tutor-collection-migration.ts) carries a prior built-in user's host data into the plugin collections (verified by content), triggered by leftover host data and run post-install; wired by `migrateTypingTutorBuiltin` in [plugin-update-service.ts](../../src/main/services/marketplace/plugin-update-service.ts). The plugin is marketplace-only (loader-excluded from the builtin tier). Publishing to the live marketplace is a separate operator step ([SUBMISSION.md](../../src/plugins/typing-tutor/SUBMISSION.md)). - **Invariants** — [.claude/memory/contracts/typing-tutor-contract.md](../../.claude/memory/contracts/typing-tutor-contract.md). ## Related Typing Tutor installs and updates like any other add-on, which [Plugin Marketplace](plugin-marketplace.md) explains, and what a plugin is allowed to ask the host for is set out in [Plugin Bridge Capabilities](plugin-bridge-capabilities.md). If you are drilling keyboard skills for the app itself rather than for raw typing speed, [Hotkey Training Mode](hotkey-training-mode.md) is the sibling practice surface.