Magic Analysis

When analyzing keyboard layouts with magic keys, we face a unique challenge: the same text can be typed in multiple ways, each creating different patterns that affect typing comfort. Consider typing the word “boat” on a layout with the magic rule o★ → oa:

• Normal typing: b → o → a → t (4 keystrokes)
• Magic typing: b → o → ★ → t (4 keystrokes, but different key sequence)

Both produce the text “boat”, but they create completely different n-gram patterns for analysis. The normal sequence creates bigrams “bo”, “oa”, “at”, while the magic sequence creates “bo”, “o★”, “★t”. Since we analyze typing keystrokes pressed rather than characters output, these represent different typing experiences.

Resolution

The current analysis pipeline uses keymaxx’s resolver instead of maintaining a separate magic-specific corpus rewrite. The generated analysis layout lists every key behavior—plain grapheme output, multi-grapheme output, magic, skip-magic, repeat, and skip-repeat—and binds those behaviors against the canonical .corpus.protobuf artifact.

During analysis, the resolver chooses keystroke paths that produce the corpus text while minimizing a layouts-wiki cost model. That cost model gives each key press a base cost and adds costs for movement patterns such as Same-Finger Bigrams, Scissors, Lateral Stretch, and redirects. Magic and repeat keys are therefore selected only when their reduced keystroke count or improved movement pattern outweighs the cost of pressing those keys.

This means magic decisions are not optimized separately per metric. The same resolved keystroke stream feeds every metric, so a magic choice that improves one statistic but worsens another is handled through the configured cost tradeoff before stats are counted.

Corpus Artifacts

The canonical corpus artifact stores graphemes, word sequences, n-gram counts, and sequence-edge data in one protobuf. Analysis uses that artifact directly. Older separate .ngrams.protobuf, .magic.protobuf, and .sequences.protobuf files are no longer part of the active build path.

The corpus processor keeps exact denominator semantics for the statistics:

1. Disallowed graphemes create hard sequence breaks.
2. Consecutive, leading, and trailing separators collapse.
3. Separator-crossing n-grams are reconstructed from committed word sequences with one separator grapheme between adjacent words.

Top Contributors

Stats are emitted as exact ratios. Top contributors are formatted at the Rust/protobuf boundary with readable grapheme and special-key labels, so frontend tables and charts do not need to understand resolver-internal key IDs.

Metrics

Once the optimal keystroke sequences are calculated, the final n-gram counts (after applying magic optimizations) feed into the same Same-Finger Bigram, Lateral Stretch, and Rhythm calculators used for traditional layouts.

Additionally, magic layouts get a Speedup metric that measures typing efficiency gains:

$\text{Speedup}\% = 1 - \frac{\text{Adjusted Keystrokes}}{\text{Original Keystrokes}}$

A 5% speedup means magic keys reduce total keystrokes by 5% compared to normal typing.