btn-recognizer 0.2.0

Timestamp-driven button debouncing with multi-tap, hold, repeat, and multi-key chord gesture recognition
Documentation
# 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.