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
Section titled “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, Keymax finds every minimum-cost keystroke path that produces each corpus sequence. Each layout supplies its complete cost expressions. A shadowed default offered as a miss can carry an extra cost to represent waiting out a timeout; the selected adaptive output and ordinary unshadowed defaults do not incur that surcharge. See N-gram Frequency Analysis for the standard model and the distinction between path costs and metric rates.
Magic decisions are not optimized separately per metric. All tied minimum-cost paths contribute equally to every metric. A magic choice can therefore improve one statistic while worsening another, and an equal-cost ordinary typing path remains part of the result.
Corpus Artifacts
Section titled “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 preserves sequence boundaries and records the output grapheme count. N-gram frequencies use the weighted population of resolved event windows for their source width, rather than that grapheme count:
- Disallowed graphemes create hard sequence breaks.
- Consecutive, leading, and trailing separators collapse.
- Separator-crossing n-grams are reconstructed from committed word sequences with one separator grapheme between adjacent words.
Contributors
Section titled “Contributors”Occurrence counts retain exact rational weights. A metric query’s .freq divides its matching mass by the complete original source-window population; filters and endpoint projections preserve that denominator. Contributor lists are queried on demand from the retained analysis report, without redecoding the corpus, and paginated without a top-N cap. Their miniature keycaps use the actual decoded event identities, including chords and held state.
Metrics
Section titled “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.
Speedup can instead compare weighted resolved event counts with corpus graphemes. That explicitly chosen comparison is separate from n-gram .freq; it does not change any n-gram denominator.