feat: add StickyMod (SM) action for Alt+Tab-style modifier cycling

docs/docs/main/docs/configuration/behavior.md

@@ -24,46 +24,38 @@ adjust = 3
 
 In this example, when both layers 1 (`upper`) and 2 (`lower`) are active, layer 3 (`adjust`) will also be enabled.
 
-## One-Shot
+## Sticky Keys
 
-The `one_shot` sub-table contains common one-shot configuration (for both OSM and OSL)
+Sticky Keys unify one-shot modifiers, one-shot layers, and repeated modified keys. Use `SK(LShift)` for a modifier, `SK(MO(1))` for a layer, or `SK(Tab, [LAlt])` for an Alt-Tab-style key. `OSM(...)` and `OSL(...)` remain compatibility aliases for the first two forms.
 
-Currently, there are only `timeout` field that specifies how long the one-shot modifier/layer remains active. When no key is pressed within this time, the one-shot modifier/layer will be canceled. `timeout` value is a string suffixed with `s` or `ms` (default: `1s`).
-
-## One-Shot Modifiers
-
-The `one_shot_modifiers` sub-table configures one-shot modifiers (OSM).
-
-By default, one-shot modifiers do not activate on keypress and will be sent only when other key is pressed. You can change this behavior by setting `activate_on_keypress` to `true`. This behavior is also known as One-Shot Sticky Modifiers (OSSM).
-
-If you press One-Shot Modifier again, it will be sent as a normal modifier key press and, therefore, released.
-
-The `quick_release` option controls when the one-shot modifier is released:
-
-- `false` (default): the modifier is released when the next key is **released** (chain mode, equivalent to ZMK `&skn`). The modifier stays active for the entire duration of the next keypress, including key repeat.
-- `true`: the modifier is released when the next key is **pressed** (equivalent to ZMK `&skq`). Only the initial press of the next key is modified; key repeat will not include the modifier.
+```toml
+[behavior.sticky_key]
+timeout = "1s"
+activate_on_keypress = true
+release_after_hold = "500ms"
+max_repeat = 0
+release_mode = "other_key_release"
 
-Default values:
+[behavior.sticky_key.profiles.quick]
+release_mode = "other_key_press | double_tap"
 
-```toml
-[behavior.one_shot_modifiers]
-activate_on_keypress = false
-quick_release = false
+[behavior.sticky_key.profiles.alt_tab]
+timeout = "5s"
+max_repeat = 8
+release_mode = "other_key_press | layer_exit"
 ```
 
-OSSM example:
+Each field may be omitted. Named profiles inherit omitted fields from `[behavior.sticky_key]` and are selected with `@name`, for example `SK(LShift, @quick)` or `SK(Tab, [LAlt], @alt_tab)`.
 
-```toml
-[behavior.one_shot_modifiers]
-activate_on_keypress = true
-```
+- `timeout`: releases an unused latch after this duration; the default is `1s`.
+- `activate_on_keypress`: reports a pure modifier immediately instead of waiting for the next key.
+- `release_after_hold`: for modifiers or layers held for at least this duration, releases the modifier or layer when the Sticky Key is physically released instead of latching it. A shorter tap receives the full `timeout` starting from key-up. This hold threshold is independent of `timeout` and may be shorter or longer. Pure modifiers must also set `activate_on_keypress = true` to be reported while physically held. Modified tap keys are unaffected. The default is disabled.
+- `max_repeat`: limits tap-key repetitions; `0` means unlimited.
+- `release_mode`: a `|`-separated set of `other_key_press`, `other_key_release`, `layer_enter`, `layer_exit`, and `double_tap`.
 
-Quick-release example:
+The legacy `[behavior.one_shot] timeout` and `[behavior.one_shot_modifiers]` settings are still accepted and feed the default Sticky profile. `quick_release = true` maps to `other_key_press` for pure-modifier aliases.
 
-```toml
-[behavior.one_shot_modifiers]
-quick_release = true
-```
+Sticky layers use RMK's normal boolean layer state: when multiple actions target the same layer, the latest activate or deactivate command determines its state.
 
 ## Combo
 

docs/docs/main/docs/configuration/layout.md

@@ -270,16 +270,16 @@ The `layer.keys` string follows several rules:
 
 4. RMK supports many advanced layer operations:
    1. `DF(n)` — switch the default layer to layer `n`.
-   2. `PDF(n)` — switch the default layer to layer `n` and persist it to storage, so it survives reboots.
-   3. `MO(n)` — momentarily activate layer `n`.
-   4. `LM(n, modifier)` — activate layer `n` with a modifier held. The modifier chains like `WM`.
-   5. `LT(n, key, <profile_name>)` — activate layer `n` on hold, or tap `key` (tap/hold). `key` is an RMK [`KeyCode`](./keymap_configuration/keycodes); the optional `profile_name` sets the key's [profile](./behavior#per-key-profiles-for-morse-tapdance-tap-hold-fine-tuning).
-   6. `OSL(n)` — one-shot layer `n`.
-   7. `OSM(modifier)` — one-shot modifier. The modifier chains like `WM`.
-   8. `TT(n)` — activate layer `n`, or tap-toggle it.
-   9. `TG(n)` — toggle layer `n`.
-   10. `TO(n)` — activate layer `n` and deactivate all other layers.
-
+   2. `MO(n)` — momentarily activate layer `n`.
+   3. `LM(n, modifier)` — activate layer `n` with a modifier held. The modifier chains like `WM`.
+   4. `LT(n, key, <profile_name>)` — activate layer `n` on hold, or tap `key` (tap/hold). `key` is an RMK [`KeyCode`](./keymap_configuration/keycodes); the optional `profile_name` sets the key's [profile](./behavior#per-key-profiles-for-morse-tapdance-tap-hold-fine-tuning).
+   5. `OSL(n)` — compatibility alias for the sticky layer `SK(MO(n))`.
+   6. `OSM(modifier)` — compatibility alias for the sticky modifier `SK(modifier)`. The modifier chains like `WM`.
+   7. `TT(n)` — activate layer `n`, or tap-toggle it.
+   8. `TG(n)` — toggle layer `n`.
+   9. `TO(n)` — activate layer `n` and deactivate all other layers.
+   11. `PDF(n)` — switch the default layer to layer `n` and persist it to storage, so it survives reboots.
+   
    These match QMK's definitions; see the [QMK layer docs](https://docs.qmk.fm/#/feature_layers). If you need another action, please [file an issue](https://github.com/rmk-rs/rmk/issues/new).
 
 5. For modifier-tap-hold, use `MT(key, modifier, <profile_name>)`, where the modifier can be a chain as in rule 1. The optional `profile_name` sets the key's [profile](./behavior#per-key-profiles-for-morse-tapdance-tap-hold-fine-tuning).
@@ -295,6 +295,8 @@ The `layer.keys` string follows several rules:
 
 9. For keyboard macros, use `Macro(n)`.
 
+10. For a configurable Sticky Key, use `SK(modifier)`, `SK(MO(n))`, or `SK(key, [modifiers])`. An optional named profile is written as the final `@profile` argument: `SK(LShift, @quick)` or `SK(Tab, [LAlt], @alt_tab)`. See [Sticky Keys](./behavior#sticky-keys).
+
 ## Aliases
 
 The `[aliases]` section maps user-defined names to replacement strings, which you can then use in `layer.keys`:

docs/docs/main/docs/configuration/rmk_config.md

@@ -20,6 +20,8 @@ fork_max_num = 8
 morse_max_num = 8
 # Maximum number of named morse profiles, shared by morse and tap-hold keys (max 255)
 morse_profile_max_num = 16
+# Maximum number of named Sticky Key profiles (max 255). If omitted, RMK derives it.
+# sticky_key_profile_max_num = 4
 # Maximum number of patterns a morse key can handle (default: 8, min: 4, max 65536)
 max_patterns_per_key = 8
 # Macro space size in bytes for storing sequences. The maximum number of Macros depends on the size of each sequence: All sequences combined need to fit into macro_space_size, the number of macro sequences doesn't matter.
@@ -66,7 +68,8 @@ Increasing the number of combos, forks, morses (tap dances), and macros will inc
 - `fork_max_num`: Maximum number of forks for conditional key actions, default value is 8. This value must be between 0 and 255.
 - `morse_max_num`: Maximum number of morses that can be stored, default value is 8. This value must be between 0 and 255.
 - `morse_profile_max_num`: Capacity of the morse profile table (the named profiles in `[behavior.morse.profiles]`, referenced by morse and tap-hold keys), default value is 16. This value must be between 0 and 255.
-- `max_patterns_per_key` : Maximum number of tap/hold patterns a morse key can handle, default value is 8. This value must be between 4 and 65536. (Automatically raised to fit the largest `tap_actions` + `hold_actions` + `morse_actions` count among the configured morse keys.)
+- `sticky_key_profile_max_num`: Capacity of the named Sticky Key profile table. If omitted, RMK derives a sufficient value from the configured profiles with a small Rust-API fallback; an explicit value must be between 0 and 255.
+- `max_patterns_per_key` : Maximum number of tap/hold patterns a morse key can handle, default value is 8. This value must be between 4 and 65536. (Will be automatically set to the maximum length of `tap_actions` + `hold_actions` or `morse_actions`.)
 - `macro_space_size`: Space size in bytes for storing macro sequences, default value is 256.
 
 ### Matrix Configuration

docs/docs/main/docs/development/rynk_protocol.md

@@ -4,7 +4,7 @@
 
 # Rynk Protocol Reference
 
-Current protocol version: **0.1**.
+Current protocol version: **1.0**.
 
 Every transport (USB CDC, BLE GATT, BLE HID) carries the same frame — a 3-byte header plus a [postcard](https://docs.rs/postcard)-encoded payload:
 

rmk-config/src/keymap.pest

@@ -15,6 +15,7 @@ keycode_name = @{ loose_identifier }
 // contexts where it won't conflict with argument separators.
 symbol_keycode = @{ "," }
 profile_name = { strict_identifier }
+alias_ref = @{ "@" ~ strict_identifier }
 
 // Number (for layer indices)
 number = @{ ASCII_DIGIT+ }
@@ -55,7 +56,8 @@ wm_action = { ^"WM" ~ "(" ~ keycode_name ~ "," ~ modifier_combination ~ ")" }
 mod_action = { ^"MOD" ~ "(" ~ modifier_combination ~ ")" }
 
 // Rule 4.6: OSM(modifier) - One-Shot Modifier (requires quotes)
-osm_action = { ^"OSM" ~ "(" ~ modifier_combination ~ ")" }
+sticky_profile_ref = { "@" ~ profile_name }
+osm_action = { ^"OSM" ~ "(" ~ modifier_combination ~ ("," ~ sticky_profile_ref)? ~ ")" }
 
 // Rule 4.1: DF(n) - Switch Default Layer
 df_action = { ^"DF" ~ "(" ~ layer_reference ~ ")" }
@@ -73,7 +75,7 @@ lm_action = { ^"LM" ~ "(" ~ layer_reference ~ "," ~ modifier_combination ~ ")" }
 lt_action = { ^"LT" ~ "(" ~ layer_reference ~ "," ~ nestable_action ~ ("," ~ profile_name)? ~ ")" }
 
 // Rule 4.5: OSL(n) - One-Shot Layer
-osl_action = { ^"OSL" ~ "(" ~ layer_reference ~ ")" }
+osl_action = { ^"OSL" ~ "(" ~ layer_reference ~ ("," ~ sticky_profile_ref)? ~ ")" }
 
 // Rule 4.7: TT(n) - Layer Activate or Tap Toggle
 tt_action = { ^"TT" ~ "(" ~ layer_reference ~ ")" }
@@ -96,9 +98,9 @@ layer_action = _{
 // `keycode_name` fallback (not `simple_keycode`) keeps a lone `,` from being
 // accepted as a slot argument.
 nestable_action = _{
-    wm_action | mod_action | osm_action | shifted_action | trigger_macro_action |
+    wm_action | mod_action | osm_action | shifted_action | trigger_macro_action | alias_ref |
     df_action | pdf_action | mo_action | lm_action | osl_action | tg_action | to_action |
-    stn_action | keycode_name
+    stn_action | sk_action | keycode_name
 }
 
 // Rule 5: MT(key, modifier) - Modifier Tap-Hold
@@ -116,6 +118,17 @@ morse_action = { (^"TD" | ^"MORSE") ~ "(" ~ number ~ ")" }
 // Rule 9: Macro(n) - Trigger Macro
 trigger_macro_action = { ^"MACRO" ~ "(" ~ number ~ ")" }
 
+modifier_keep_list = { "[" ~ modifier_combination ~ "]" | "[" ~ "]" }
+
+// SK(key, [mods], @profile) | SK(modifier, @profile) | SK(MO(n), @profile)
+sk_action = {
+    ^"SK" ~ "(" ~ (
+        mo_action ~ ("," ~ sticky_profile_ref)?
+      | (keycode_name ~ "," ~ modifier_keep_list ~ ("," ~ sticky_profile_ref)?)
+      | modifier_combination ~ ("," ~ sticky_profile_ref)?
+    ) ~ ")"
+}
+
 // Rule 10: STN(key) - Plover HID steno key, named by its position in the chart
 stn_action = { ^"STN" ~ "(" ~ keycode_name ~ ")" }
 
@@ -124,7 +137,7 @@ stn_action = { ^"STN" ~ "(" ~ keycode_name ~ ")" }
 // A single key action entry in the map
 // Order is important: more specific function-like rules first, then aliases/specials, then simple keycodes.
 key_action = _{ // Consume surrounding whitespace/comments implicitly
-    wm_action | mod_action | osm_action | layer_action | mt_action | th_action | shifted_action | morse_action | trigger_macro_action | stn_action | no_action | transparent_action | simple_keycode
+    wm_action | mod_action | osm_action | layer_action | mt_action | th_action | shifted_action | morse_action | trigger_macro_action | stn_action | sk_action | alias_ref | no_action | transparent_action | simple_keycode
 }
 
 // The entire key map string: Start, zero or more key actions, End.

rmk-config/src/keymap.rs

@@ -205,63 +205,77 @@ impl KeyboardTomlConfig {
     fn alias_resolver(keys: &str, aliases: &HashMap<String, String>) -> Result<String, String> {
         let mut current_keys = keys.to_string();
 
-        let mut iterations = 0;
-
-        loop {
-            let mut next_keys = String::with_capacity(current_keys.capacity());
-            let mut made_replacement = false;
-            let mut last_index = 0;
-
-            while let Some(at_index) = current_keys[last_index..].find('@') {
-                let start_index = last_index + at_index;
-
-                next_keys.push_str(&current_keys[last_index..start_index]);
-
-                // The name ends at the grammar's delimiters, so `LM(1, @mods)`
-                // resolves `mods` — not a bogus `mods)`.
-                let mut end_index = start_index + 1;
-                while let Some(&c) = current_keys.as_bytes().get(end_index) {
-                    if c.is_ascii_whitespace() || matches!(c, b'(' | b')' | b',' | b'@') {
+        for _ in 0..MAX_ALIAS_RESOLUTION_DEPTH {
+            let mut next = String::with_capacity(current_keys.len());
+            let mut replaced = false;
+            let mut cursor = 0;
+            while let Some(offset) = current_keys[cursor..].find('@') {
+                let start = cursor + offset;
+                next.push_str(&current_keys[cursor..start]);
+                let mut end = start + 1;
+                while let Some(&byte) = current_keys.as_bytes().get(end) {
+                    if byte.is_ascii_whitespace() || matches!(byte, b'(' | b')' | b',' | b'@') {
                         break;
                     }
-                    end_index += 1;
+                    end += 1;
                 }
-
-                let alias_key = &current_keys[start_index + 1..end_index];
-                if alias_key.is_empty() {
-                    // A bare `@` (trailing, or right before a delimiter) is literal.
-                    next_keys.push('@');
-                    last_index = start_index + 1;
+                if end == start + 1 {
+                    next.push('@');
+                    cursor = end;
                     continue;
                 }
-                match aliases.get(alias_key) {
-                    Some(value) => {
-                        next_keys.push_str(value);
-                        made_replacement = true;
-                    }
-                    None => return Err(format!("Undefined alias: {}", alias_key)),
+                let name = &current_keys[start + 1..end];
+                if Self::is_sticky_profile_reference(&current_keys, start) {
+                    next.push_str(&current_keys[start..end]);
+                } else if let Some(value) = aliases.get(name) {
+                    next.push_str(value);
+                    replaced = true;
+                } else {
+                    return Err(format!("Undefined alias: {name}"));
                 }
-                last_index = end_index;
+                cursor = end;
             }
-
-            next_keys.push_str(&current_keys[last_index..]);
-
-            iterations += 1;
-            if iterations >= MAX_ALIAS_RESOLUTION_DEPTH {
-                return Err(format!(
-                    "Alias resolution exceeded maximum depth ({}), potential infinite loop detected in '{}'",
-                    MAX_ALIAS_RESOLUTION_DEPTH, keys
-                ));
+            next.push_str(&current_keys[cursor..]);
+            if !replaced {
+                return Ok(current_keys);
             }
+            current_keys = next;
+        }
 
-            if !made_replacement {
-                break;
-            }
+        Err(format!(
+            "Alias resolution exceeded maximum depth ({}), potential infinite loop detected in '{}'",
+            MAX_ALIAS_RESOLUTION_DEPTH, keys
+        ))
+    }
 
-            current_keys = next_keys;
+    fn is_sticky_profile_reference(input: &str, at: usize) -> bool {
+        let Some(previous) = input[..at].bytes().rev().find(|byte| !byte.is_ascii_whitespace()) else {
+            return false;
+        };
+        if previous != b',' {
+            return false;
         }
 
-        Ok(current_keys)
+        let bytes = input.as_bytes();
+        let mut depth = 0usize;
+        for index in (0..at).rev() {
+            match bytes[index] {
+                b')' => depth += 1,
+                b'(' if depth > 0 => depth -= 1,
+                b'(' => {
+                    let mut name_start = index;
+                    while name_start > 0 && bytes[name_start - 1].is_ascii_alphabetic() {
+                        name_start -= 1;
+                    }
+                    return matches!(
+                        input[name_start..index].to_ascii_lowercase().as_str(),
+                        "sk" | "osm" | "osl"
+                    );
+                }
+                _ => {}
+            }
+        }
+        false
     }
 
     /// Reconstruct an action string from a parsed pair, resolving every named