feat: add tap-hold-release-order action

[tompassarelli]

Add tap-hold-release-order: event-driven tap-hold disambiguation

A new tap-hold variant that resolves based on release order rather than timing:

• If another key is pressed and released while the hold-tap key is still held → Hold
• If the hold-tap key is released first → Tap

This is useful for spacebar-as-modifier setups where timeout-based approaches either add latency (high timeout) or misfire during fast typing (low timeout). Release-order makes the decision purely event-driven.

Parameters

(tap-hold-release-order $tap-repress-timeout $buffer-ms $tap-action $hold-action)

Parameter	Description
$tap-repress-timeout	If the key is tapped and pressed again within this window (ms), it bypasses hold-tap logic and immediately fires as tap — allowing double-tap-and-hold to repeat. 0 to disable.
$buffer-ms	Grace period (ms) after the initial press during which release-order logic is ignored. Key presses within this window always resolve as tap regardless of release order, preventing misfires during fast typing. 0 to disable.

Example

(defalias spacesym (tap-hold-release-order 200 50 spc (layer-while-held symbols)))

• Tap space → outputs space
• Hold space, press a, release a (while space still held) → activates symbols layer
• Hold space, press a, release space first → outputs space then a
• Within 50ms of pressing space: fast typing always outputs space (buffer)
• Double-tap space within 200ms and hold → space repeats (tap-repress)

Checklist

• Add documentation to docs/config.adoc
  • Yes
• Add example and basic docs to cfg_samples/kanata.kbd
  • Yes
• Update error messages
  • Yes
• Added tests, or did manual testing
  • Yes — 5 unit tests (clean tap, hold, tap, buffer ignores fast typing, hold after buffer)

[malpern]

Nice work — release-order disambiguation fills a real gap. A couple thoughts:

Naming

My main concern is tap-hold-release-order living right next to tap-hold-release in the docs. They're one word apart but fundamentally different — tap-hold-release cares whether an interrupt key was released at all during hold, while this cares about which key releases first.

For context, the ecosystem is already a bit of a maze here:

Firmware	Name	Behavior
QMK	PERMISSIVE_HOLD	Hold on other key release
Kanata	tap-hold-release	Same as above
ZMK	balanced	Similar, timeout-gated
This PR	tap-hold-release-order	Whichever key releases first wins

Some alternatives that might read more distinctly:

• tap-hold-release-first — "resolve based on which releases first"
• tap-hold-order — shorter, emphasizes the core concept

Not sure what's best though — @jtroo you have much better sense of how users navigate the existing variant names. What do you think?

Implementation

Code is clean — slots into HoldTapConfig naturally. Minor things I noticed:

• Multi-key test: All five tests use two keys. Might be worth one test with hold-tap + two other keys (A down, B down, A released while B still held) to document the iterator behavior in that case.
• Buffer tick math: self.ticks.saturating_sub(q.since) < buffer is correct but the relationship isn't obvious from the variable names alone — a short comment could help future readers.
• timeout: u16::MAX: Makes sense for purely event-driven resolution. A one-line comment noting the intent would clarify it's deliberate.

All minor — overall this looks like a solid addition.

[jtroo]

Thanks for the contribution!

Two main things:

1. please pull from latest main and add handling for the require-prior-idle option
2. agree the naming is potentially confusing when comparing against tap-hold-release

To expand more on naming, I believe tap-hold-order would be a nicer name because the behaviours are quite different; this action doesn't have a timeout where tap-hold-release does.

[tompassarelli]

Updated per feedback:

• Renamed to tap-hold-order
• Added optional require-prior-idle-ms as trailing parameter (defaults to 0/disabled), matching the interface contract across other tap-hold variants
• Added multi-key test (TH + two other keys, documents iterator behavior)
• Added inline comments on the saturating_sub/buffer comparison and the timeout: u16::MAX
• Rebased onto latest main (picks up feat: add tap-hold-require-prior-idle defcfg option #1960)

[jtroo]

Please add some simulation tests to test closer to end-to-end. Also please add a test case for a press within the buffer window; I didn't spot one in the keyberon tests.

https://github.com/jtroo/kanata/blob/main/src/tests/sim_tests/tap_hold_tests.rs

Simulation tests can be run like so:

kanata/justfile

Line 35 in 07bed9e

cargo test --features=simulated_output sim_tests

[tompassarelli]

Please add some simulation tests to test closer to end-to-end. Also please add a test case for a press within the buffer window; I didn't spot one in the keyberon tests.

https://github.com/jtroo/kanata/blob/main/src/tests/sim_tests/tap_hold_tests.rs

Simulation tests can be run like so:

kanata/justfile

Line 35 in 07bed9e

cargo test --features=simulated_output sim_tests

Updated with simulation tests and keyberon buffer test per your feedback. Tests cover: clean tap, hold via release-order, tap via release-order, buffer ignoring fast typing, hold after buffer expires, require-prior-idle short-circuit, and require-prior-idle passthrough. All 184 sim tests pass