On the design and behaviour of a forgiving typing-tutor cursor — followed by an apparatus for stepping through it, one keystroke at a time.
A typing tutor compares what the user types, character by character, against a reference passage. The simple version is straightforward: if the pressed key equals text[cursor], advance the cursor; otherwise, mark an error. This is the strict mode found in most typing software — keybr's only mode, Monkeytype's letter-mode. It is pedagogically defensible: every wrong key is felt. But it has a brittle failure case, and that failure case is what the apparatus below is built to study.
Suppose the reference is thinking words and the user types rgoinking words. They meant to type the right thing — their fingers were misplaced for the first three letters, then they recovered and typed the rest correctly. In strict mode the cursor freezes at position 0 (the t). The user keeps pressing keys, none of which match t. Each is logged as an error. They notice something is wrong only when they look up and see the cursor hasn't moved — by which time they've typed half a word into the void.
What we want, instead, is some way to recognise that the user is back on track — that their recent keystrokes line up with the reference, just at a different cursor position than we currently believe.
The first thing to try is lookahead-1: after a mismatch at cursor, peek at text[cursor+1]. If the user's keystroke matches that, infer they skipped one character, charge the skipped character as a key error, and advance the cursor by two. This handles a clean single-letter deletion (world typed as wrld) well, and stays safe with two cheap checks: refuse to skip across whitespace — so a typo doesn't fly past a word boundary — and refuse to skip when text[cursor] equals text[cursor+1], the doubled-letter trap, where typing one l at ll looks like a skip but is just a missed second letter.
Lookahead-1 stops there. It cannot recover from rgoinking: three keystrokes happened before the user came back into phase, and by the time they type i we would need to peek at least two positions ahead. Even then, a single i matching text[2] is a coin flip's worth of evidence. Reasonably long English text has i's scattered everywhere; matching one in isolation tells us almost nothing about whether the user has actually recovered.
A different approach: full edit-distance. Run a Wagner-Fischer dynamic program that aligns the user's entire input against the reference and find the true minimum-cost alignment. This is mathematically clean. But it's slow to do per-keystroke, and the alignments it produces flicker — the cursor jumps backward and forward as the optimal alignment evolves with each new character. For an authoring tool, fine. For a real-time typing tutor, distracting.
The middle path is what the apparatus below implements: forward scan with N-character confirmation.
The user's recent keystrokes form a short signal. When they are typing correctly, that signal is identical to the corresponding window of the reference. When they are typing incorrectly, the signal diverges. When they recover, the signal re-converges — but to a different position in the reference than where the cursor currently sits.
We don't need to do anything sophisticated with the signal. We need to ask, after each keystroke: do my last N keystrokes appear contiguously in the next few characters of the reference? If yes, that is overwhelming evidence the user has resumed correct typing at that offset, and the cursor should snap there.
The choice of N is the entire game. N = 1 means "is the latest keystroke any character that appears within the next several positions?" — almost always true, gives garbage. N = 2 means "do my last two keystrokes match a 2-char window?" — coincidence rate roughly one-in-several-hundred for random letters and far better for English, where bigram frequencies are highly non-uniform. N = 3 is more conservative still, but it rarely fires; by the time the user types three correct letters past the reference position, they often realise something is off and stop. In practice, N = 2 is the sweet spot for natural-text typing tutors, and it is the default below. Try sliding it to 1 in the apparatus and watch the false positives accumulate.
Each keystroke runs through four branches, in order, stopping at the first one that fires:
{`branch 1 — exact match
pressed === text[cursor] ?
→ advance cursor by 1.
branch 2 — lookahead-1 (single-char skip)
pressed === text[cursor+1],
and not whitespace, and not a doubled letter ?
→ advance cursor by 2;
charge text[cursor] as a key error.
branch 3 — forward scan with N-confirmation
buffer[-N:] === text[cursor+k : cursor+k+N]
for some k in 1..MAX_SKIP,
with no whitespace in the skipped slice ?
→ advance cursor by k+N;
charge text[cursor : cursor+k] as key errors;
retroactively absolve the previous N-1 keystrokes.
branch 4 — real error
none of the above matched.
→ stay; mark errorAtCursor;
count this keystroke as a session error.`}
Branch 1 is the fast path: most keystrokes are correct. Branch 2 is essentially a special case of Branch 3 with N = 1, but it carries stricter safety conditions — particularly the doubled-letter check — and we keep it as a separate test because that single-skip case is common enough to deserve dedicated logic. Branch 3 is the heart of the algorithm. Branch 4 is the fallback for genuine errors, where the user really has typed the wrong key and needs to correct it before continuing.
Once we accept that some wrong-at-the-time keystrokes were retroactively part of correct typing, we have to be careful about what "errors" means. There are two distinct quantities, and they should not be conflated.
The session error count drives the live accuracy display. It should reflect how often the user actually typed the wrong key. When they type r,g,o,i,n against thinking, three of those keystrokes (r, g, o) were genuinely wrong, and two (i, n) turned out to be the right keystrokes for positions 2 and 3 — they were just typed before the cursor reached them. An honest count is 3, not 5.
The per-key error count is what feeds the adaptive practice generator. It is keyed by the expected character: which keys did the user fumble? Here the answer is different. The user should have typed t and h to advance through positions 0 and 1, and they didn't. So t and h each get +1 error. This is what makes the adaptive generator surface practice text rich in t and h for a while — until the user demonstrates they can hit those keys reliably.
The algorithm tracks both. On a successful resync of distance k, the k skipped reference characters each get +1 in keyStatErrors, and the previous N−1 keystrokes flip from wrong to absolved, with sessionErrors decremented by the same count. The current keystroke that triggered the resync — being itself part of the matching tail — also doesn't add to the session count. This dual accounting is the algorithm's pedagogical contribution: strict mode collapses both quantities into one number, while forward-scan separates what the user did wrong from what their fingers missed. Adaptive practice uses the latter; live feedback uses the former. Neither is forced to lie about the other.
Three constraints prevent the scan from doing dumb things, and watching them reject candidate matches in the trace is a good way to internalise them.
No whitespace in the skip. A spurious match across a space — the buffer go matching the start of a future word good, when the user actually skipped over a space and into a word they shouldn't be in — would feel violating. Refusing any resync whose skipped slice or matched window contains whitespace keeps the cursor inside word boundaries. Within-word slips are common; across-word slips usually mean the user is genuinely lost and should look up.
No doubled letters in lookahead-1. When the reference is all and the user types one l at position 1, lookahead-1 would compare l against text[2] = l and conclude the first l was skipped. They didn't skip it; they just typed too few. The check text[cursor] !== text[cursor+1] blocks this. Forward-scan with N ≥ 2 is naturally immune, since a 2-char tail cannot form a false match against a single doubled character.
Bounded max-skip. Without a cap, a user typing complete garbage for 30 seconds could eventually trigger a spurious resync against some random window of the reference. Capping the maximum skip at 5 or 6 keeps the algorithm anchored. If recovery does not happen within a handful of keystrokes, the cursor refuses to leap and the user is forced to look up and recover deliberately. That is the right outcome — the algorithm's job is to forgive small slips, not to rescue the lost.
The algorithm captures deletions — the user dropped a character — cleanly. It does not handle two related cases.
Insertions: the user typed an extra letter that isn't in the reference. Reference the, input thhe. Forward-scan finds no useful resync target because the cursor is already roughly where the alignment expects it to be — the problem is on the input side, not the reference side. To handle insertions, you would need a different motion: instead of skipping forward in the reference, skip backward in the input. Recognise that the latest keystroke is the extra one and the user is still on track at the current cursor position. This requires a small alignment buffer rather than single-keystroke lookahead.
Transpositions: the typed as hte. The algorithm handles single transpositions accidentally, by way of lookahead-1: when the user types h at position 0, lookahead-1 fires (text[1] = h), the cursor skips to 2, and the user's next t lands at position 2 expecting e — which is a real error. Net result: t is charged as the skipped key error, the typed t is wasted, and the user has to correct it. Not perfect (the user "typed all the right letters in the wrong order" gets recorded as one error and one wasted keystroke), but acceptable for a practice tool.
For genuinely tricky cases — long transposed runs, mixed insertions and deletions, repeated phonetic substitutions — the right tool is a small banded edit-distance computation (Damerau-Levenshtein over a 4-6 character window) or the bitap algorithm with errors. Those handle all four edit operations uniformly. They are more complex to implement and produce alignments rather than discrete branch decisions, but for high-end typing software they are worth the complexity. Forward-scan trades that capability for simplicity, predictability, and a trace you can read.
A natural question, given the keyword "matching": doesn't this look like a string-matching problem? Why not the standard fast algorithms?
Aho–Corasick is for finding any of many patterns in a stream. Its win is the failure-function machinery that keeps partial matches active across all patterns simultaneously. We have one pattern — the upcoming reference text — so AC degenerates into KMP, whose failure function we don't need either: our scan window is at most ~6 characters and our buffer tail is at most N characters, both tiny constants. The total work per keystroke is bounded by perhaps 30 character comparisons. Fancy preprocessing buys us nothing.
There is a deeper reason the analogy is wrong. Aho–Corasick and KMP answer "where in the text does the pattern appear?" We are asking the dual question — "where in the reference should the cursor be, given streaming user input?" That dual is online approximate string matching, and the textbook tool there is bitap (Wu & Manber, 1992), which encodes the match state as bitmasks updated in O(1) per keystroke. Bitap is genuinely beautiful, and it is the right answer if you want to handle insertions, transpositions, and substitutions all at once. But for skip-only behaviour, it is overkill. Forward-scan with N-confirmation gets the same recovery for ~30 lines of straightforward code instead of a bitmask DP.
The lesson is that algorithmic muscle should be calibrated to the problem. We have one short pattern, a tight scan window, and only one edit type to handle. The right algorithm is the smallest one that fits.
Below: the apparatus. Step through any input one keystroke at a time, watch each branch test and outcome, see absolution in action.