feat: replace tap-hold-press-gap with tap-hold-release-order

Pure event-driven tap-hold disambiguation with zero parameters.
After both keys are down, the first release determines intent:
- Other key releases first (modifier still held) → Hold
- Modifier releases first (other key still held) → Tap

No timers, no thresholds. Decision on the 3rd event only.

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

Author: tompassarelli

keyberon/src/action.rs

@@ -61,11 +61,11 @@ pub enum HoldTapConfig<'a> {
     /// not used in the flow of typing, like escape for example. If
     /// you are annoyed by accidental tap, you can try this behavior.
     HoldOnOtherKeyPress,
-    /// Like HoldOnOtherKeyPress, but requires a minimum gap (in ticks/ms)
-    /// between the tap-hold keydown and the next keydown before activating hold.
-    /// If the next key arrives before the gap, resolves as tap instead.
-    /// This filters fast-typing overlap from intentional modifier holds.
-    HoldOnOtherKeyPressWithGap(u16),
+    /// 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,
     /// If there is a press and release of another key, the hold
     /// action is activated.
     ///
@@ -105,9 +105,7 @@ impl Debug for HoldTapConfig<'_> {
         match self {
             HoldTapConfig::Default => f.write_str("Default"),
             HoldTapConfig::HoldOnOtherKeyPress => f.write_str("HoldOnOtherKeyPress"),
-            HoldTapConfig::HoldOnOtherKeyPressWithGap(gap) => {
-                write!(f, "HoldOnOtherKeyPressWithGap({gap})")
-            }
+            HoldTapConfig::ReleaseOrder => f.write_str("ReleaseOrder"),
             HoldTapConfig::PermissiveHold => f.write_str("PermissiveHold"),
             HoldTapConfig::Custom(_) => f.write_str("Custom"),
         }
@@ -121,10 +119,7 @@ impl PartialEq for HoldTapConfig<'_> {
             (HoldTapConfig::Default, HoldTapConfig::Default)
             | (HoldTapConfig::HoldOnOtherKeyPress, HoldTapConfig::HoldOnOtherKeyPress)
             | (HoldTapConfig::PermissiveHold, HoldTapConfig::PermissiveHold) => true,
-            (
-                HoldTapConfig::HoldOnOtherKeyPressWithGap(a),
-                HoldTapConfig::HoldOnOtherKeyPressWithGap(b),
-            ) => a == b,
+            (HoldTapConfig::ReleaseOrder, HoldTapConfig::ReleaseOrder) => true,
             _ => false,
         }
     }

keyberon/src/layout.rs

@@ -544,12 +544,18 @@ impl<'a, T: std::fmt::Debug> WaitingState<'a, T> {
                     return Some(WaitingAction::Hold);
                 }
             }
-            HoldTapConfig::HoldOnOtherKeyPressWithGap(min_gap) => {
-                if queued.iter().any(|s| s.event.is_press()) {
-                    if self.ticks >= min_gap {
-                        return Some(WaitingAction::Hold);
-                    } else {
-                        return Some(WaitingAction::Tap);
+            HoldTapConfig::ReleaseOrder => {
+                // 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.
+                let mut queued = queued.iter();
+                while let Some(q) = queued.next() {
+                    if q.event.is_press() {
+                        let (i, j) = q.event.coord();
+                        let target = Event::Release(i, j);
+                        if queued.clone().any(|q| q.event == target) {
+                            return Some(WaitingAction::Hold);
+                        }
                     }
                 }
             }
@@ -2520,28 +2526,25 @@ mod test {
     }
 
     #[test]
-    fn hold_on_press_with_gap_clean_tap() {
-        // Clean tap: press and release the tap-hold key with no other keys.
-        // Should emit the tap action (Space).
+    fn release_order_clean_tap() {
+        // Press and release modifier with no other keys → Tap.
         static LAYERS: Layers<2, 1> = &[[[
             HoldTap(&HoldTapAction {
                 on_press_reset_timeout_to: None,
                 timeout: u16::MAX,
                 hold: k(LAlt),
                 timeout_action: k(Space),
                 tap: k(Space),
-                config: HoldTapConfig::HoldOnOtherKeyPressWithGap(100),
+                config: HoldTapConfig::ReleaseOrder,
                 tap_hold_interval: 0,
             }),
             k(Enter),
         ]]];
         let mut layout = Layout::new(LAYERS);
 
-        // Press the tap-hold key
         layout.event(Press(0, 0));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
-        // Wait a bit, then release (no other key pressed)
         for _ in 0..50 {
             assert_eq!(CustomEvent::NoEvent, layout.tick());
             assert_keys(&[], layout.keycodes());
@@ -2554,116 +2557,71 @@ mod test {
     }
 
     #[test]
-    fn hold_on_press_with_gap_fast_typing_overlap() {
-        // Fast typing overlap: another key pressed within min_gap (100ms).
-        // Should resolve as tap: emit Space then Enter.
+    fn release_order_hold() {
+        // Modifier down → other down → other up first → Hold.
         static LAYERS: Layers<2, 1> = &[[[
             HoldTap(&HoldTapAction {
                 on_press_reset_timeout_to: None,
                 timeout: u16::MAX,
                 hold: k(LAlt),
                 timeout_action: k(Space),
                 tap: k(Space),
-                config: HoldTapConfig::HoldOnOtherKeyPressWithGap(100),
+                config: HoldTapConfig::ReleaseOrder,
                 tap_hold_interval: 0,
             }),
             k(Enter),
         ]]];
         let mut layout = Layout::new(LAYERS);
 
-        // Press the tap-hold key
         layout.event(Press(0, 0));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
-        // Wait only 30ms, then press another key (within the 100ms gap)
-        for _ in 0..29 {
-            assert_eq!(CustomEvent::NoEvent, layout.tick());
-            assert_keys(&[], layout.keycodes());
-        }
         layout.event(Press(0, 1));
-        // Next tick: gap is 30 ticks < 100 min_gap, so resolves as Tap
-        assert_eq!(CustomEvent::NoEvent, layout.tick());
-        assert_keys(&[Space], layout.keycodes());
-        // Buffered Enter gets dequeued
-        assert_eq!(CustomEvent::NoEvent, layout.tick());
-        assert_keys(&[Space, Enter], layout.keycodes());
-    }
-
-    #[test]
-    fn hold_on_press_with_gap_intentional_hold() {
-        // Intentional hold: another key pressed after min_gap (100ms).
-        // Should resolve as hold: activate LAlt, then Enter is processed with LAlt active.
-        static LAYERS: Layers<2, 1> = &[[[
-            HoldTap(&HoldTapAction {
-                on_press_reset_timeout_to: None,
-                timeout: u16::MAX,
-                hold: k(LAlt),
-                timeout_action: k(Space),
-                tap: k(Space),
-                config: HoldTapConfig::HoldOnOtherKeyPressWithGap(100),
-                tap_hold_interval: 0,
-            }),
-            k(Enter),
-        ]]];
-        let mut layout = Layout::new(LAYERS);
-
-        // Press the tap-hold key
-        layout.event(Press(0, 0));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
-        // Wait 150ms (past the 100ms gap threshold)
-        for _ in 0..149 {
-            assert_eq!(CustomEvent::NoEvent, layout.tick());
-            assert_keys(&[], layout.keycodes());
-        }
-        layout.event(Press(0, 1));
-        // Next tick: gap is 150 ticks >= 100 min_gap, so resolves as Hold
+        // Other key releases first → Hold
+        layout.event(Release(0, 1));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[LAlt], layout.keycodes());
-        // Buffered Enter gets dequeued
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[LAlt, Enter], layout.keycodes());
-        // Release both
-        layout.event(Release(0, 1));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[LAlt], layout.keycodes());
+        // Release modifier
         layout.event(Release(0, 0));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
     }
 
     #[test]
-    fn hold_on_press_with_gap_exact_boundary() {
-        // Exactly at min_gap: should resolve as hold (>= check).
+    fn release_order_tap() {
+        // Modifier down → other down → modifier up first → Tap.
         static LAYERS: Layers<2, 1> = &[[[
             HoldTap(&HoldTapAction {
                 on_press_reset_timeout_to: None,
                 timeout: u16::MAX,
                 hold: k(LAlt),
                 timeout_action: k(Space),
                 tap: k(Space),
-                config: HoldTapConfig::HoldOnOtherKeyPressWithGap(100),
+                config: HoldTapConfig::ReleaseOrder,
                 tap_hold_interval: 0,
             }),
             k(Enter),
         ]]];
         let mut layout = Layout::new(LAYERS);
 
-        // Press the tap-hold key
         layout.event(Press(0, 0));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
         assert_keys(&[], layout.keycodes());
-        // Wait exactly 100 ticks
-        for _ in 0..99 {
-            assert_eq!(CustomEvent::NoEvent, layout.tick());
-            assert_keys(&[], layout.keycodes());
-        }
         layout.event(Press(0, 1));
-        // Next tick: gap is exactly 100 ticks == 100 min_gap, resolves as Hold
         assert_eq!(CustomEvent::NoEvent, layout.tick());
-        assert_keys(&[LAlt], layout.keycodes());
+        assert_keys(&[], layout.keycodes());
+        // Modifier releases first → Tap
+        layout.event(Release(0, 0));
         assert_eq!(CustomEvent::NoEvent, layout.tick());
-        assert_keys(&[LAlt, Enter], layout.keycodes());
+        assert_keys(&[Space], layout.keycodes());
+        assert_eq!(CustomEvent::NoEvent, layout.tick());
+        assert_keys(&[Space, Enter], layout.keycodes());
     }
 
     #[test]

parser/src/cfg/list_actions.rs

@@ -136,7 +136,7 @@ pub const CLIPBOARD_RESTORE: &str = "clipboard-restore";
 pub const CLIPBOARD_SAVE_SET: &str = "clipboard-save-set";
 pub const CLIPBOARD_SAVE_CMD_SET: &str = "clipboard-save-cmd-set";
 pub const CLIPBOARD_SAVE_SWAP: &str = "clipboard-save-swap";
-pub const TAP_HOLD_PRESS_GAP: &str = "tap-hold-press-gap";
+pub const TAP_HOLD_RELEASE_ORDER: &str = "tap-hold-release-order";
 pub const TAP_HOLD_OPPOSITE_HAND: &str = "tap-hold-opposite-hand";
 
 pub fn is_list_action(ac: &str) -> bool {
@@ -273,7 +273,7 @@ pub fn is_list_action(ac: &str) -> bool {
         CLIPBOARD_SAVE_SET,
         CLIPBOARD_SAVE_CMD_SET,
         CLIPBOARD_SAVE_SWAP,
-        TAP_HOLD_PRESS_GAP,
+        TAP_HOLD_RELEASE_ORDER,
         TAP_HOLD_OPPOSITE_HAND,
     ];
     LIST_ACTIONS.contains(&ac)

parser/src/cfg/mod.rs

@@ -1508,7 +1508,7 @@ fn parse_action_list(ac: &[SExpr], s: &ParserState) -> Result<&'static KanataAct
         TAP_HOLD_PRESS | TAP_HOLD_PRESS_A => {
             parse_tap_hold(&ac[1..], s, HoldTapConfig::HoldOnOtherKeyPress)
         }
-        TAP_HOLD_PRESS_GAP => parse_tap_hold_press_gap(&ac[1..], s),
+        TAP_HOLD_RELEASE_ORDER => parse_tap_hold_release_order(&ac[1..], s),
         TAP_HOLD_RELEASE | TAP_HOLD_RELEASE_A => {
             parse_tap_hold(&ac[1..], s, HoldTapConfig::PermissiveHold)
         }

parser/src/cfg/tap_hold.rs

@@ -94,26 +94,25 @@ pub(crate) fn parse_tap_hold_timeout(
     }))))
 }
 
-pub(crate) fn parse_tap_hold_press_gap(
+pub(crate) fn parse_tap_hold_release_order(
     ac_params: &[SExpr],
     s: &ParserState,
 ) -> Result<&'static KanataAction> {
-    if ac_params.len() != 3 {
+    if ac_params.len() != 2 {
         bail!(
-            r"tap-hold-press-gap expects 3 items after it, got {}.
+            r"tap-hold-release-order expects 2 items after it, got {}.
 Params in order:
-<min-gap-ms> <tap-action> <hold-action>",
+<tap-action> <hold-action>",
             ac_params.len(),
         )
     }
-    let min_gap = parse_non_zero_u16(&ac_params[0], s, "min gap threshold")?;
-    let tap_action = parse_action(&ac_params[1], s)?;
-    let hold_action = parse_action(&ac_params[2], s)?;
+    let tap_action = parse_action(&ac_params[0], s)?;
+    let hold_action = parse_action(&ac_params[1], 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::HoldOnOtherKeyPressWithGap(min_gap),
+        config: HoldTapConfig::ReleaseOrder,
         tap_hold_interval: 0,
         timeout: u16::MAX,
         tap: *tap_action,