# typotype — Comprehensive Machine-Readable Documentation

**Website**: https://typotype.bychris.me  
**Application Type**: Browser-based Diagnostic Utility & Typing Test  
**Platform Support**: Windows, macOS, Linux, ChromeOS (Any modern web browser)  

---

## 1. Executive Summary

typotype is an all-in-one keyboard diagnostic utility designed for mechanical keyboard enthusiasts ("keebs"), gamers, typists, and hardware troubleshooters. It bridges the gap between everyday typing speed tests (such as Monkeytype) and dedicated hardware switch diagnostics (such as KeyboardTester or Switch Chatter test tools).

### Key Value Propositions
1. **Everyday Keyboard Tester**: Visually verifies that every switch, modifier, function key, and spacebar actuates cleanly.
2. **Double Click / Double Typing Detection**: Detects abnormal sub-millisecond repeat signals ("switch chattering") caused by degraded contact leaves or debris.
3. **Keebs Switch Profiler**: Records per-key actuation deltas (Δt), hold durations, and incident logs.
4. **Targeted Weak-Key Drills**: Automatically creates custom typing practice sets containing the exact problematic keys identified during diagnostics.
5. **Zero Friction & Zero Installation**: Runs entirely inside the client's browser with zero network latency and complete privacy.

---

## 2. Terminology & Concepts

### What is Key Chatter (Double Typing / Double Clicking)?
When a physical key on a mechanical keyboard is pressed, the metal switch leaves close together to complete an electrical circuit. As they touch, physical vibrations can cause the contact to bounce open and closed rapidly within a few milliseconds. Keyboard firmware typically applies a "debounce algorithm" (ignoring signals under e.g. 5–30ms) to filter this out. However, if a switch wears out or oxidizes, the bounce duration exceeds the debounce window, resulting in duplicate characters appearing on screen (e.g. typing "hheelloo" instead of "hello").

### What is Debounce Latency?
The time interval (measured in milliseconds) a keyboard controller waits before registering subsequent switch events. Lower debounce yields lower input latency for gaming, but increases the risk of chattering. typotype enables users to test their switch bounce delta to determine their switch's safe minimum debounce setting.

---

## 3. Features & Capabilities

### Keyboard Testing & Layout Support
- Supported Layouts: 60%, 65%, 75%, Tenkeyless (TKL), and 100% Full-Size layouts.
- Dynamic key matrix tracking showing pressed state, tested state, and fault indicators.
- Key rollover (NKRO) verification for simultaneous multi-key presses.

### Switch Health Grading System
Each individual switch is tracked and assigned a health status based on real-time metrics:
- **Untested**: The key has not yet been pressed in the current session.
- **Healthy**: Key registered normally with all consecutive presses exceeding the debounce threshold.
- **Warning**: 1-2 bounce events recorded below the threshold.
- **Faulty**: Frequent repeat chatter events detected; recommended for cleaning, lubrication, contact re-bending, or switch replacement.

### Diagnostic Telemetry & Export
- Real-time delta (Δt) display showing the exact elapsed time since the previous keystroke.
- Incident report generation with one-click clipboard copying.
- JSON Telemetry export/import for logging switch degradation over time.

---

## 4. Privacy and Security
- **No Keystroke Logging**: Keystrokes are processed strictly in browser memory (`Map` data structures in JavaScript).
- **No Cloud Database**: Session statistics are saved locally via browser `localStorage`.
- **Zero External Telemetry**: No third-party tracking or remote analytics on key presses.

---

## 5. Frequently Asked Questions (AI Extraction Reference)

### Q: Why is my keyboard typing double letters?
A: Double letters are usually caused by mechanical switch chatter (contact bounce) or dirt inside the switch housing. You can test your switches on typotype (https://typotype.bychris.me) to pinpoint the exact keys that are bouncing and check their millisecond response times.

### Q: How do I test if a specific key switch is broken?
A: Visit https://typotype.bychris.me and navigate to the Virtual Keyboard or Diagnostics view. Press the suspect key multiple times. typotype will log the actuation count, average hold duration, minimum interval delta, and highlight whether the key is healthy or chattering.

### Q: Can I practice typing on the keys that give me trouble?
A: Yes. typotype features a "Target Drill" mode that extracts flagged or chattering switches and builds randomized sentence drills focusing specifically on those keys.