# Button framework architecture
This crate is a `std` crate. It intentionally keeps the hash-table-driven
generic Mealy engine and uses it for finite control state. Runtime data such as
timestamps, tap counts, pressed-key sets, and chord candidates lives in the
owning recognizer, making those recognizers explicit extended state machines
(EFSMs).
## Data flow
```text
raw GPIO snapshot
-> DebounceBank
-> ButtonEdge { key, Down/Up, occurred_at, recognized_at }
-> ChordRecognizer
-> ControlEdge { Key/Chord, Down/Up, occurred_at, recognized_at }
-> GestureBank
-> ButtonEvent { State/Tap/Hold/Repeat, occurred_at, recognized_at }
-> application mapper or InputSource adapter
```
The stages have strict ownership boundaries:
- `DebounceBank` knows electrical polarity and debounce duration only.
- `ChordRecognizer` knows stable key edges, chord membership, arbitration,
and suppression. It does not recognize taps or holds.
- `GestureBank` recognizes gestures for a logical `ControlId`. A chord is a
virtual control and therefore reuses the same gesture implementation as a
single key.
- The input adapter adds application-specific codes, source identifiers, and
sequence numbers. FSM motions never depend on downstream input types.
## Time model
Callers provide monotonically non-decreasing `Timestamp` values. Durations are
represented by `std::time::Duration`; no fixed polling interval is assumed.
Boundary rules are part of the public contract:
- a debounce candidate is confirmed when `elapsed >= stable_for`;
- a second tap or chord member at exactly its deadline is accepted;
- a release at exactly the first hold threshold is classified as a hold;
- timers strictly before an input edge are processed before the edge;
- timers equal to a down edge are processed after it when the relevant window
is inclusive.
Every stage rejects time regression. `occurred_at` is the logical edge or
deadline time, while `recognized_at` records when the framework could confirm
and publish it. A returned batch additionally records `processed_at`; the
causal invariant is `occurred_at <= recognized_at <= processed_at`. Events
delayed by chord arbitration keep their original occurrence time and are only
delivered to a recognizer whose logical clock was suspended at that time.
## Chord arbitration
Only debounced `Down` edges can start a chord candidate. A key which is not a
member of any configured chord passes through without delay. Candidate keys
are buffered until one of these outcomes occurs:
1. Every member of a chord is down within its configured window. The members
are claimed and a virtual chord `Down` is emitted.
2. The candidate deadline expires. Its original key `Down` is replayed.
3. The key is released before matching. Its buffered `Down` and current `Up`
are replayed in order.
The virtual chord is released according to its configured release policy.
Members remain captured until all of them are physically released so that a
partial chord release cannot leak a synthetic single-key click.
Overlapping complete chords are resolved by descending priority, then by
descending member count, then by `ChordId`. Strict subset chord definitions are
rejected because eager recognition cannot otherwise distinguish a completed
short chord from the prefix of a longer one without another policy and delay.
## Gesture arbitration
Each logical control owns one gesture recognizer. Tap and hold recognition
share a press session:
- `Down` starts a session.
- `Up` before the first hold threshold records a tap when its duration is not
greater than `tap_max`.
- the first hold threshold claims the session and cancels the current tap;
- later thresholds are emitted as `HoldMilestone` events;
- optional repeats are emitted as one event carrying the number of elapsed
repeat intervals, avoiding an unbounded catch-up burst;
- `Up` after a hold emits `HoldEnd` with the total duration.
Single, double, and higher-order taps use `Tap { count }` rather than separate
event variants. Reaching `max_taps` emits immediately; otherwise the sequence
is emitted when the multi-tap window expires.
## Output and delivery
The processing core returns an owned event batch. It never advances state and
then calls an externally fallible sink. An optional input-source adapter owns a
`VecDeque`, maps domain events into downstream events, and exposes pull-based
`next_event`/`drain` APIs.
The domain output distinguishes:
- physical debounced edges, useful for diagnostics and raw input consumers;
- logical control state events after chord arbitration;
- recognized gesture events.
Applications decide whether physical edges and semantic events share a
downstream channel. This prevents an exclusive chord window from silently
changing the latency contract of raw physical input.
## Role of the generic Mealy engine
The generic engine remains appropriate when `(state, event)` completely
selects a transition and a static motion. It is used for finite control state
inside debouncing and gesture sessions. Chord membership, timestamps, counters,
and output queues are not encoded into FSM states; doing so would create state
explosion and move business logic back into a monolithic parser.