# Clave

Read `About this Folder.txt` for what the types are. This file is for what's easy to get wrong.

## A chord fires unless something more specific claims the keys

A plain `Chord.Press(Z)` matches on Alt+Z, Ctrl+Shift+Z and AltGr+Z. That is intended. A chord is hidden only when an
enabled chord that is strictly more specific (`Supersedes`) matches too, such as Ctrl+Z over Z. Nothing more specific
means every chord that matches fires.

- **Don't add exclusions to "fix" it.** A `noAlt` guard on every chord is the wrong answer. Register the more specific
  chord, and the plain one steps aside by itself.
- **`WithNoneHeld` is for a chord that must not fire** even when nothing else claims the keys, such as a paste chord
  that should ignore AltGr. It is the exception.
- **Priority ranks equivalent chords.** Between chords that match the same snapshots, the higher priority wins and
  equal priorities both fire. Specificity decides between chords that differ.
- **Edge terms count.** A chord with a press, release or repeat term (`RequiresEdge`) fires on that event only. A
  chord that only reads held keys matches on every snapshot while the keys are down.

## Ask an arbiter, not the chord

`Chord.Matches(snapshot)` says whether the keys fit and knows nothing about other chords. Code that acts on a key
should ask a `ChordArbiter` (`ShouldFire`), which applies hiding, priority and enabled state. A client that matches the
raw input skips all of that and fires when it shouldn't.

- `ChordSet` is immutable. `ChordSetBuilder` is its mutable form. `ChordArbiter` holds many sets at once, each on a
  `ChordMount`, and ranks them against each other.
- A chord or set never knows what uses it. The mount is what tells two uses of the same chord apart.
- `ChordSetBuilder.ShouldFire` ranks only the chords in that builder. It is for a standalone group, not for a game that
  has an arbiter.

## Chords are distinct objects

Chords compare by reference, so two `Chord.Press(KeyCode.A)` calls are two bindings, and a set can hold both. A test
that looks a chord up again must keep the variable it made, not rebuild it.

## Key spaces

A chord reads physical keys or layout keys (`KeySpace`), and the default is physical. Layout chords are folded to the
physical keys when an arbiter analyses them, which costs about twice as much as a physical chord. Mixing spaces in one
arbiter is fine.

## Building and mounting cost

Making a chord builds a diagram, and adding it to an arbiter analyses it and ranks it against the others. Do both once
and keep the result.

- **Strongly prefer not to build chords or mount sets per frame.** Mounting a set costs more the more chords are in
  play. `SetPriority`, `SetEnabled` and `Clear` change an arbiter in place.
- **Chords that pin no key** (`PressAny` over several keys) are the costly kind to add, since each is ranked against
  more of the arbiter.
- **Measure with the control.** `Bin\Release\Clave.PerformanceTests.exe --quick "<filter>"` runs a control row beside
  every row. Read the ratio over the control and not the microseconds, because the machine's speed drifts.