tap-hold-release-order: add buffer parameter for fast typing grace period

Key presses within the buffer (ms) after the hold-tap key press are
ignored by release-order logic, resolving as Tap regardless of release
order.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: tompassarelli

keyberon/src/action.rs

@@ -64,8 +64,10 @@ pub enum HoldTapConfig<'a> {
     /// Resolves based on release order after both keys are down.
     /// If the other key releases first (modifier still held) → Hold.
     /// If the modifier releases first (other key still held) → Tap.
-    /// No timers, no thresholds — purely event-driven.
-    ReleaseOrder,
+    /// The buffer field specifies a grace period in ticks (ms) after the
+    /// initial press during which release-order logic is ignored and fast
+    /// typing will resolve as Tap.
+    ReleaseOrder { buffer: u16 },
     /// If there is a press and release of another key, the hold
     /// action is activated.
     ///
@@ -105,7 +107,7 @@ impl Debug for HoldTapConfig<'_> {
         match self {
             HoldTapConfig::Default => f.write_str("Default"),
             HoldTapConfig::HoldOnOtherKeyPress => f.write_str("HoldOnOtherKeyPress"),
-            HoldTapConfig::ReleaseOrder => f.write_str("ReleaseOrder"),
+            HoldTapConfig::ReleaseOrder { .. } => f.write_str("ReleaseOrder"),
             HoldTapConfig::PermissiveHold => f.write_str("PermissiveHold"),
             HoldTapConfig::Custom(_) => f.write_str("Custom"),
         }
@@ -119,7 +121,7 @@ impl PartialEq for HoldTapConfig<'_> {
             (HoldTapConfig::Default, HoldTapConfig::Default)
             | (HoldTapConfig::HoldOnOtherKeyPress, HoldTapConfig::HoldOnOtherKeyPress)
             | (HoldTapConfig::PermissiveHold, HoldTapConfig::PermissiveHold) => true,
-            (HoldTapConfig::ReleaseOrder, HoldTapConfig::ReleaseOrder) => true,
+            (HoldTapConfig::ReleaseOrder { .. }, HoldTapConfig::ReleaseOrder { .. }) => true,
             _ => false,
         }
     }

keyberon/src/layout.rs

@@ -544,13 +544,21 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                     return Some(WaitingAction::Hold);
                 }
             }
-            HoldTapConfig::ReleaseOrder => {
+            HoldTapConfig::ReleaseOrder { buffer } => {
                 // Like PermissiveHold: if another key was pressed AND released
                 // (while modifier is still held), resolve as Hold.
                 // If modifier is released first, the fallthrough below handles Tap.
+                //
+                // Buffer: key presses that occurred within `buffer` ticks of the
+                // hold-tap key press are ignored by release-order logic, allowing
+                // fast typing to resolve as Tap regardless of release order.
                 let mut queued = queued.iter();
                 while let Some(q) = queued.next() {
                     if q.event.is_press() {
+                        let press_tick = self.ticks.saturating_sub(q.since);
+                        if press_tick < buffer {
+                            continue;
+                        }
                         let (i, j) = q.event.coord();
                         let target = Event::Release(i, j);
                         if queued.clone().any(|q| q.event == target) {
@@ -2535,7 +2543,7 @@ mod test {
                 hold: k(LAlt),
                 timeout_action: k(Space),
                 tap: k(Space),
-                config: HoldTapConfig::ReleaseOrder,
+                config: HoldTapConfig::ReleaseOrder { buffer: 0 },
                 tap_hold_interval: 0,
             }),
             k(Enter),
@@ -2566,7 +2574,7 @@ mod test {
                 hold: k(LAlt),
                 timeout_action: k(Space),
                 tap: k(Space),
-                config: HoldTapConfig::ReleaseOrder,
+                config: HoldTapConfig::ReleaseOrder { buffer: 0 },
                 tap_hold_interval: 0,
             }),
             k(Enter),
@@ -2603,7 +2611,7 @@ mod test {
                 hold: k(LAlt),
                 timeout_action: k(Space),
                 tap: k(Space),
-                config: HoldTapConfig::ReleaseOrder,
+                config: HoldTapConfig::ReleaseOrder { buffer: 0 },
                 tap_hold_interval: 0,
             }),
             k(Enter),

parser/src/cfg/tap_hold.rs

@@ -98,21 +98,22 @@ pub(crate) fn parse_tap_hold_release_order(
     ac_params: &[SExpr],
     s: &ParserState,
 ) -> Result<&'static KanataAction> {
-    if ac_params.len() != 2 {
+    if ac_params.len() != 3 {
         bail!(
-            r"tap-hold-release-order expects 2 items after it, got {}.
+            r"tap-hold-release-order expects 3 items after it, got {}.
 Params in order:
-<tap-action> <hold-action>",
+<buffer-ms> <tap-action> <hold-action>",
             ac_params.len(),
         )
     }
-    let tap_action = parse_action(&ac_params[0], s)?;
-    let hold_action = parse_action(&ac_params[1], s)?;
+    let buffer = parse_u16(&ac_params[0], s, "buffer")?;
+    let tap_action = parse_action(&ac_params[1], s)?;
+    let hold_action = parse_action(&ac_params[2], s)?;
     if matches!(tap_action, Action::HoldTap { .. }) {
         bail!("tap-hold does not work in the tap-action of tap-hold")
     }
     Ok(s.a.sref(Action::HoldTap(s.a.sref(HoldTapAction {
-        config: HoldTapConfig::ReleaseOrder,
+        config: HoldTapConfig::ReleaseOrder { buffer },
         tap_hold_interval: 0,
         timeout: u16::MAX,
         tap: *tap_action,