try sm_td

1 files changed, 834 insertions, 0 deletions

diff --git a/common/sm_td.h b/common/sm_td.h
new file mode 100644
index 0000000..185fa9a
--- /dev/null
+++ b/common/sm_td.h
@@ -0,0 +1,834 @@
+/* Copyright 2024 Stanislav Markin (https://github.com/stasmarkin)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ *
+ * Version: 0.4.0
+ * Date: 2024-03-07
+ */
+#pragma once
+
+#include QMK_KEYBOARD_H
+#include "deferred_exec.h"
+
+#ifdef SMTD_DEBUG_ENABLED
+#include "print.h"
+#endif
+
+#ifdef SMTD_GLOBAL_SIMULTANEOUS_PRESSES_DELAY_MS
+#include "timer.h"
+#endif
+
+/* ************************************* *
+ *         GLOBAL CONFIGURATION          *
+ * ************************************* */
+
+#ifndef SMTD_GLOBAL_SIMULTANEOUS_PRESSES_DELAY_MS
+#define SMTD_GLOBAL_SIMULTANEOUS_PRESSES_DELAY_MS 0
+#endif
+
+#if SMTD_GLOBAL_SIMULTANEOUS_PRESSES_DELAY_MS > 0
+#define SMTD_SIMULTANEOUS_PRESSES_DELAY wait_ms(SMTD_GLOBAL_SIMULTANEOUS_PRESSES_DELAY_MS);
+#else
+#define SMTD_SIMULTANEOUS_PRESSES_DELAY
+#endif
+
+#ifndef SMTD_GLOBAL_TAP_TERM
+#define SMTD_GLOBAL_TAP_TERM TAPPING_TERM
+#endif
+
+#ifndef SMTD_GLOBAL_SEQUENCE_TERM
+#define SMTD_GLOBAL_SEQUENCE_TERM TAPPING_TERM / 2
+#endif
+
+#ifndef SMTD_GLOBAL_FOLLOWING_TAP_TERM
+#define SMTD_GLOBAL_FOLLOWING_TAP_TERM TAPPING_TERM
+#endif
+
+#ifndef SMTD_GLOBAL_RELEASE_TERM
+#define SMTD_GLOBAL_RELEASE_TERM TAPPING_TERM / 4
+#endif
+
+#ifndef SMTD_GLOBAL_MODS_RECALL
+#define SMTD_GLOBAL_MODS_RECALL true
+#endif
+
+#ifndef SMTD_GLOBAL_AGGREGATE_TAPS
+#define SMTD_GLOBAL_AGGREGATE_TAPS false
+#endif
+
+/* ************************************* *
+ *          DEBUG CONFIGURATION          *
+ * ************************************* */
+
+#ifdef SMTD_DEBUG_ENABLED
+__attribute__((weak)) char* keycode_to_string_user(uint16_t keycode);
+
+char* keycode_to_string(uint16_t keycode) {
+    if (keycode_to_string_user) {
+        char* result = keycode_to_string_user(keycode);
+        if (result) {
+            return result;
+        }
+    }
+
+    static char buffer[16];
+    snprintf(buffer, sizeof(buffer), "KC_%d", keycode);
+    return buffer;
+}
+#endif
+
+/* ************************************* *
+ *       USER TIMEOUT DEFINITIONS        *
+ * ************************************* */
+
+typedef enum {
+    SMTD_TIMEOUT_TAP,
+    SMTD_TIMEOUT_SEQUENCE,
+    SMTD_TIMEOUT_FOLLOWING_TAP,
+    SMTD_TIMEOUT_RELEASE,
+} smtd_timeout;
+
+__attribute__((weak)) uint32_t get_smtd_timeout(uint16_t keycode, smtd_timeout timeout);
+
+uint32_t get_smtd_timeout_default(smtd_timeout timeout) {
+    switch (timeout) {
+        case SMTD_TIMEOUT_TAP:
+            return SMTD_GLOBAL_TAP_TERM;
+        case SMTD_TIMEOUT_SEQUENCE:
+            return SMTD_GLOBAL_SEQUENCE_TERM;
+        case SMTD_TIMEOUT_FOLLOWING_TAP:
+            return SMTD_GLOBAL_FOLLOWING_TAP_TERM;
+        case SMTD_TIMEOUT_RELEASE:
+            return SMTD_GLOBAL_RELEASE_TERM;
+    }
+    return 0;
+}
+
+uint32_t get_smtd_timeout_or_default(uint16_t keycode, smtd_timeout timeout) {
+    if (get_smtd_timeout) {
+        return get_smtd_timeout(keycode, timeout);
+    }
+    return get_smtd_timeout_default(timeout);
+}
+
+/* ************************************* *
+ *    USER FEATURE FLAGS DEFINITIONS     *
+ * ************************************* */
+
+typedef enum {
+    SMTD_FEATURE_MODS_RECALL,
+    SMTD_FEATURE_AGGREGATE_TAPS,
+} smtd_feature;
+
+__attribute__((weak)) bool smtd_feature_enabled(uint16_t keycode, smtd_feature feature);
+
+bool smtd_feature_enabled_default(smtd_feature feature) {
+    switch (feature) {
+        case SMTD_FEATURE_MODS_RECALL:
+            return SMTD_GLOBAL_MODS_RECALL;
+        case SMTD_FEATURE_AGGREGATE_TAPS:
+            return SMTD_GLOBAL_AGGREGATE_TAPS;
+    }
+    return false;
+}
+
+bool smtd_feature_enabled_or_default(uint16_t keycode, smtd_feature feature) {
+    if (smtd_feature_enabled) {
+        return smtd_feature_enabled(keycode, feature);
+    }
+    return smtd_feature_enabled_default(feature);
+}
+
+/* ************************************* *
+ *       USER ACTION DEFINITIONS         *
+ * ************************************* */
+
+typedef enum {
+    SMTD_ACTION_TOUCH,
+    SMTD_ACTION_TAP,
+    SMTD_ACTION_HOLD,
+    SMTD_ACTION_RELEASE,
+} smtd_action;
+
+#ifdef SMTD_DEBUG_ENABLED
+char *smtd_action_to_string(smtd_action action) {
+    switch (action) {
+        case SMTD_ACTION_TOUCH:
+            return "ACT_TOUCH";
+        case SMTD_ACTION_TAP:
+            return "ACT_TAP";
+        case SMTD_ACTION_HOLD:
+            return "ACT_HOLD";
+        case SMTD_ACTION_RELEASE:
+            return "ACT_RELEASE";
+    }
+    return "ACT_UNKNOWN";
+}
+#endif
+
+void on_smtd_action(uint16_t keycode, smtd_action action, uint8_t sequence_len);
+
+#ifdef SMTD_DEBUG_ENABLED
+#define SMTD_ACTION(action, state) printf("%s by %s in %s\n", \
+    smtd_action_to_string(action), keycode_to_string(state->macro_keycode), smtd_stage_to_string(state->stage)); \
+    on_smtd_action(state->macro_keycode, action, state->sequence_len);
+#else
+#define SMTD_ACTION(action, state) on_smtd_action(state->macro_keycode, action, state->sequence_len);
+#endif
+
+/* ************************************* *
+ *       USER STATES DEFINITIONS         *
+ * ************************************* */
+
+typedef enum {
+    SMTD_STAGE_NONE,
+    SMTD_STAGE_TOUCH,
+    SMTD_STAGE_SEQUENCE,
+    SMTD_STAGE_FOLLOWING_TOUCH,
+    SMTD_STAGE_HOLD,
+    SMTD_STAGE_RELEASE,
+} smtd_stage;
+
+#ifdef SMTD_DEBUG_ENABLED
+char *smtd_stage_to_string(smtd_stage stage) {
+    switch (stage) {
+        case SMTD_STAGE_NONE:
+            return "STAGE_NONE";
+        case SMTD_STAGE_TOUCH:
+            return "STAGE_TOUCH";
+        case SMTD_STAGE_SEQUENCE:
+            return "STAGE_SEQUENCE";
+        case SMTD_STAGE_FOLLOWING_TOUCH:
+            return "STAGE_FOL_TOUCH";
+        case SMTD_STAGE_HOLD:
+            return "STAGE_HOLD";
+        case SMTD_STAGE_RELEASE:
+            return "STAGE_RELEASE";
+    }
+    return "STAGE_UNKNOWN";
+}
+#endif
+
+typedef struct {
+    /** The keycode of the macro key */
+    uint16_t macro_keycode;
+
+    /** The mods before the touch action performed. Required for mod_recall feature */
+    uint8_t modes_before_touch;
+
+    /** Since touch can modify global mods, we need to save them separately to correctly restore a state before touch */
+    uint8_t modes_with_touch;
+
+    /** The length of the sequence of same key taps */
+    uint8_t sequence_len;
+
+    /** The position of key that was pressed after macro was pressed */
+    keypos_t following_key;
+
+    /** The keycode of the key that was pressed after macro was pressed */
+    uint16_t following_keycode;
+
+    /** The timeout of current stage */
+    deferred_token timeout;
+
+    /** The current stage of the state */
+    smtd_stage stage;
+
+    /** The flag that indicates that the state is frozen, so it won't handle any events */
+    bool freeze;
+} smtd_state;
+
+#define EMPTY_STATE {                       \
+        .macro_keycode = 0,                 \
+        .modes_before_touch = 0,            \
+        .modes_with_touch = 0,              \
+        .sequence_len = 0,                  \
+        .following_key = MAKE_KEYPOS(0, 0), \
+        .following_keycode = 0,             \
+        .timeout = INVALID_DEFERRED_TOKEN,  \
+        .stage = SMTD_STAGE_NONE,           \
+        .freeze = false                     \
+}
+
+/* ************************************* *
+ *             LAYER UTILS               *
+ * ************************************* */
+
+#define RETURN_LAYER_NOT_SET 15
+
+static uint8_t return_layer = RETURN_LAYER_NOT_SET;
+static uint8_t return_layer_cnt = 0;
+
+void avoid_unused_variable_on_compile(void* ptr) {
+    // just touch them, so compiler won't throw "defined but not used" error
+    // that variables are used in macros that user may not use
+    if (return_layer == RETURN_LAYER_NOT_SET) return_layer = RETURN_LAYER_NOT_SET;
+    if (return_layer_cnt == 0) return_layer_cnt = 0;
+}
+
+#define LAYER_PUSH(layer)                              \
+    return_layer_cnt++;                                \
+    if (return_layer == RETURN_LAYER_NOT_SET) {        \
+        return_layer = get_highest_layer(layer_state); \
+    }                                                  \
+    layer_move(layer);
+
+#define LAYER_RESTORE()                          \
+    if (return_layer_cnt > 0) {                  \
+        return_layer_cnt--;                      \
+        if (return_layer_cnt == 0) {             \
+            layer_move(return_layer);            \
+            return_layer = RETURN_LAYER_NOT_SET; \
+        }                                        \
+    }
+
+/* ************************************* *
+ *      CORE LOGIC IMPLEMENTATION        *
+ * ************************************* */
+
+smtd_state smtd_active_states[10] = {EMPTY_STATE, EMPTY_STATE, EMPTY_STATE, EMPTY_STATE, EMPTY_STATE,
+                                     EMPTY_STATE, EMPTY_STATE, EMPTY_STATE, EMPTY_STATE, EMPTY_STATE};
+uint8_t smtd_active_states_size = 0;
+
+
+#define DO_ACTION_TAP(state)                                                                 \
+    uint8_t current_mods = get_mods();                                                       \
+    if (                                                                                     \
+            smtd_feature_enabled_or_default(state->macro_keycode, SMTD_FEATURE_MODS_RECALL)  \
+            && state->modes_before_touch != current_mods                                     \
+            ) {                                                                              \
+        set_mods(state->modes_before_touch);                                                 \
+        send_keyboard_report();                                                              \
+                                                                                             \
+        SMTD_SIMULTANEOUS_PRESSES_DELAY                                                      \
+        SMTD_ACTION(SMTD_ACTION_TAP, state)                                                  \
+        uint8_t mods_diff = get_mods() ^ state->modes_before_touch;                          \
+                                                                                             \
+        SMTD_SIMULTANEOUS_PRESSES_DELAY                                                      \
+        set_mods(current_mods ^ mods_diff);                                                  \
+        del_mods(state->modes_with_touch);                                                   \
+        send_keyboard_report();                                                              \
+                                                                                             \
+        state->modes_before_touch = 0;                                                       \
+        state->modes_with_touch = 0;                                                         \
+    } else {                                                                                 \
+        SMTD_ACTION(SMTD_ACTION_TAP, state)                                                  \
+    }
+
+void smtd_press_following_key(smtd_state *state, bool release) {
+    state->freeze = true;
+    keyevent_t event_press = MAKE_KEYEVENT(state->following_key.row, state->following_key.col, true);
+    keyrecord_t record_press = {.event = event_press};
+    #ifdef SMTD_DEBUG_ENABLED
+    if (release) {
+        printf("FOLLOWING_TAP(%s) by %s in %s\n", keycode_to_string(state->following_keycode),
+               keycode_to_string(state->macro_keycode), smtd_stage_to_string(state->stage));
+    } else {
+        printf("FOLLOWING_PRESS(%s) by %s in %s\n", keycode_to_string(state->following_keycode),
+               keycode_to_string(state->macro_keycode), smtd_stage_to_string(state->stage));
+    }
+    #endif
+    process_record(&record_press);
+    if (release) {
+        keyevent_t event_release = MAKE_KEYEVENT(state->following_key.row, state->following_key.col, false);
+        keyrecord_t record_release = {.event = event_release};
+        SMTD_SIMULTANEOUS_PRESSES_DELAY
+        process_record(&record_release);
+    }
+    state->freeze = false;
+}
+
+void smtd_next_stage(smtd_state *state, smtd_stage next_stage);
+
+uint32_t timeout_reset_seq(uint32_t trigger_time, void *cb_arg) {
+    smtd_state *state = (smtd_state *) cb_arg;
+    state->sequence_len = 0;
+
+    return 0;
+}
+
+uint32_t timeout_touch(uint32_t trigger_time, void *cb_arg) {
+    smtd_state *state = (smtd_state *) cb_arg;
+    smtd_next_stage(state, SMTD_STAGE_HOLD);
+    return 0;
+}
+
+uint32_t timeout_sequence(uint32_t trigger_time, void *cb_arg) {
+    smtd_state *state = (smtd_state *) cb_arg;
+
+    if (smtd_feature_enabled_or_default(state->macro_keycode, SMTD_FEATURE_AGGREGATE_TAPS)) {
+        DO_ACTION_TAP(state);
+    }
+
+    smtd_next_stage(state, SMTD_STAGE_NONE);
+    return 0;
+}
+
+uint32_t timeout_following_touch(uint32_t trigger_time, void *cb_arg) {
+    smtd_state *state = (smtd_state *) cb_arg;
+    smtd_next_stage(state, SMTD_STAGE_HOLD);
+
+    SMTD_SIMULTANEOUS_PRESSES_DELAY
+    smtd_press_following_key(state, false);
+    return 0;
+}
+
+uint32_t timeout_release(uint32_t trigger_time, void *cb_arg) {
+    smtd_state *state = (smtd_state *) cb_arg;
+
+    DO_ACTION_TAP(state);
+
+    SMTD_SIMULTANEOUS_PRESSES_DELAY
+    smtd_press_following_key(state, false);
+
+    smtd_next_stage(state, SMTD_STAGE_NONE);
+    return 0;
+}
+
+void smtd_next_stage(smtd_state *state, smtd_stage next_stage) {
+    #ifdef SMTD_DEBUG_ENABLED
+    printf("STAGE by %s, %s -> %s\n", keycode_to_string(state->macro_keycode),
+           smtd_stage_to_string(state->stage),smtd_stage_to_string(next_stage));
+    #endif
+
+    deferred_token prev_token = state->timeout;
+    state->timeout = INVALID_DEFERRED_TOKEN;
+    state->stage = next_stage;
+
+    switch (state->stage) {
+        case SMTD_STAGE_NONE:
+            for (uint8_t i = 0; i < smtd_active_states_size; i++) {
+                if (&smtd_active_states[i] != state) continue;
+
+                for (uint8_t j = i; j < smtd_active_states_size - 1; j++) {
+                    smtd_active_states[j].macro_keycode = smtd_active_states[j + 1].macro_keycode;
+                    smtd_active_states[j].modes_before_touch = smtd_active_states[j + 1].modes_before_touch;
+                    smtd_active_states[j].modes_with_touch = smtd_active_states[j + 1].modes_with_touch;
+                    smtd_active_states[j].sequence_len = smtd_active_states[j + 1].sequence_len;
+                    smtd_active_states[j].following_key = smtd_active_states[j + 1].following_key;
+                    smtd_active_states[j].following_keycode = smtd_active_states[j + 1].following_keycode;
+                    smtd_active_states[j].timeout = smtd_active_states[j + 1].timeout;
+                    smtd_active_states[j].stage = smtd_active_states[j + 1].stage;
+                    smtd_active_states[j].freeze = smtd_active_states[j + 1].freeze;
+                }
+
+                smtd_active_states_size--;
+                smtd_state *last_state = &smtd_active_states[smtd_active_states_size];
+                last_state->macro_keycode = 0;
+                last_state->modes_before_touch = 0;
+                last_state->modes_with_touch = 0;
+                last_state->sequence_len = 0;
+                last_state->following_key = MAKE_KEYPOS(0, 0);
+                last_state->following_keycode = 0;
+                last_state->timeout = INVALID_DEFERRED_TOKEN;
+                last_state->stage = SMTD_STAGE_NONE;
+                last_state->freeze = false;
+
+                break;
+            }
+            break;
+
+        case SMTD_STAGE_TOUCH:
+            state->modes_before_touch = get_mods();
+            SMTD_ACTION(SMTD_ACTION_TOUCH, state)
+            state->modes_with_touch = get_mods() & ~state->modes_before_touch;
+            state->timeout = defer_exec(get_smtd_timeout_or_default(state->macro_keycode, SMTD_TIMEOUT_TAP),
+                                        timeout_touch, state);
+            break;
+
+        case SMTD_STAGE_SEQUENCE:
+            state->timeout = defer_exec(get_smtd_timeout_or_default(state->macro_keycode, SMTD_TIMEOUT_SEQUENCE),
+                                        timeout_sequence, state);
+            break;
+
+        case SMTD_STAGE_HOLD:
+            SMTD_ACTION(SMTD_ACTION_HOLD, state)
+            break;
+
+        case SMTD_STAGE_FOLLOWING_TOUCH:
+            state->timeout = defer_exec(get_smtd_timeout_or_default(state->macro_keycode, SMTD_TIMEOUT_FOLLOWING_TAP),
+                                        timeout_following_touch, state);
+            break;
+
+        case SMTD_STAGE_RELEASE:
+            state->timeout = defer_exec(get_smtd_timeout_or_default(state->macro_keycode, SMTD_TIMEOUT_RELEASE),
+                                        timeout_release, state);
+            break;
+    }
+
+    // need to cancel after creating new timeout. There is a bug in QMK scheduling
+    cancel_deferred_exec(prev_token);
+}
+
+bool process_smtd_state(uint16_t keycode, keyrecord_t *record, smtd_state *state) {
+    if (state->freeze) {
+        return true;
+    }
+
+    switch (state->stage) {
+        case SMTD_STAGE_NONE:
+            if (keycode == state->macro_keycode && record->event.pressed) {
+                smtd_next_stage(state, SMTD_STAGE_TOUCH);
+                return false;
+            }
+            return true;
+
+        case SMTD_STAGE_TOUCH:
+            if (keycode == state->macro_keycode && !record->event.pressed) {
+                smtd_next_stage(state, SMTD_STAGE_SEQUENCE);
+
+                if (!smtd_feature_enabled_or_default(state->macro_keycode, SMTD_FEATURE_AGGREGATE_TAPS)) {
+                    DO_ACTION_TAP(state);
+                }
+
+                return false;
+            }
+            if (keycode != state->macro_keycode && record->event.pressed) {
+                state->following_key = record->event.key;
+                state->following_keycode = keycode;
+                smtd_next_stage(state, SMTD_STAGE_FOLLOWING_TOUCH);
+                return false;
+            }
+            return true;
+
+        case SMTD_STAGE_SEQUENCE:
+            if (keycode == state->macro_keycode && record->event.pressed) {
+                state->sequence_len++;
+                smtd_next_stage(state, SMTD_STAGE_TOUCH);
+                return false;
+            }
+            if (record->event.pressed) {
+                if (smtd_feature_enabled_or_default(state->macro_keycode, SMTD_FEATURE_AGGREGATE_TAPS)) {
+                    DO_ACTION_TAP(state);
+                }
+
+                smtd_next_stage(state, SMTD_STAGE_NONE);
+
+                return true;
+            }
+            return true;
+
+        case SMTD_STAGE_FOLLOWING_TOUCH:
+            // At this stage, we have already pressed the macro key and the following key
+            // none of them is assumed to be held yet
+
+            if (keycode == state->macro_keycode && !record->event.pressed) {
+                // Macro key is released, moving to the next stage
+                smtd_next_stage(state, SMTD_STAGE_RELEASE);
+                return false;
+            }
+
+            if (
+                    keycode != state->macro_keycode
+                    && (state->following_key.row == record->event.key.row &&
+                        state->following_key.col == record->event.key.col)
+                    && !record->event.pressed
+                    ) {
+                // Following key is released. Now we definitely know that macro key is held
+                // we need to execute hold the macro key and execute hold the following key
+                // and then press move to next stage
+                smtd_next_stage(state, SMTD_STAGE_HOLD);
+
+                SMTD_SIMULTANEOUS_PRESSES_DELAY
+                smtd_press_following_key(state, true);
+
+                return false;
+            }
+            if (
+                    keycode != state->macro_keycode
+                    && !(state->following_key.row == record->event.key.row &&
+                         state->following_key.col == record->event.key.col)
+                    && record->event.pressed
+                    ) {
+                // so, now we have 3rd key pressed
+                // we assume this to be hold macro key, hold following key and press the 3rd key
+
+                // need to put first key state into HOLD stage
+                smtd_next_stage(state, SMTD_STAGE_HOLD);
+
+                // then press and hold (without releasing) the following key
+                SMTD_SIMULTANEOUS_PRESSES_DELAY
+                smtd_press_following_key(state, false);
+
+                // then rerun the 3rd key press
+                // since we have just started hold stage, we need to simulate the press of the 3rd key again
+                // because by holding first two keys we might have changed a layer, so current keycode might be not actual
+                // if we don't do this, we might continue processing the wrong key
+                SMTD_SIMULTANEOUS_PRESSES_DELAY
+                state->freeze = true;
+                keyevent_t event_press = MAKE_KEYEVENT(record->event.key.row, record->event.key.col, true);
+                keyrecord_t record_press = {.event = event_press};
+                process_record(&record_press);
+                state->freeze = false;
+
+                // we have processed the 3rd key, so we intentionally return false to stop further processing
+                return false;
+            }
+            return true;
+
+        case SMTD_STAGE_HOLD:
+            if (keycode == state->macro_keycode && !record->event.pressed) {
+                SMTD_ACTION(SMTD_ACTION_RELEASE, state)
+
+                smtd_next_stage(state, SMTD_STAGE_NONE);
+
+                return false;
+            }
+            return true;
+
+        case SMTD_STAGE_RELEASE:
+            // At this stage we have just released the macro key and still holding the following key
+
+            if (keycode == state->macro_keycode && record->event.pressed) {
+                DO_ACTION_TAP(state);
+
+                SMTD_SIMULTANEOUS_PRESSES_DELAY
+                smtd_press_following_key(state, false);
+
+                //todo need to go to NONE stage and from NONE jump to TOUCH stage
+                SMTD_SIMULTANEOUS_PRESSES_DELAY
+                smtd_next_stage(state, SMTD_STAGE_TOUCH);
+
+                state->sequence_len = 0;
+
+                return false;
+            }
+            if (
+                    keycode != state->macro_keycode
+                    && (state->following_key.row == record->event.key.row &&
+                        state->following_key.col == record->event.key.col)
+                    && !record->event.pressed
+                    ) {
+                // Following key is released. Now we definitely know that macro key is held
+                // we need to execute hold the macro key and execute tap the following key
+                // then close the state
+
+                SMTD_ACTION(SMTD_ACTION_HOLD, state)
+
+                SMTD_SIMULTANEOUS_PRESSES_DELAY
+                smtd_press_following_key(state, true);
+
+                SMTD_SIMULTANEOUS_PRESSES_DELAY
+                SMTD_ACTION(SMTD_ACTION_RELEASE, state)
+
+                smtd_next_stage(state, SMTD_STAGE_NONE);
+
+                return false;
+            }
+            if (
+                    keycode != state->macro_keycode
+                    && (state->following_key.row != record->event.key.row ||
+                        state->following_key.col != record->event.key.col)
+                    && record->event.pressed
+                    ) {
+                // at this point we have already released the macro key and still holding the following key
+                // and we get 3rd key pressed
+                // we assume this to be tap macro key, press (w/o release) following key and press (w/o release) the 3rd key
+
+                // so we need to tap the macro key first
+                DO_ACTION_TAP(state)
+
+                // then press and hold (without releasing) the following key
+                SMTD_SIMULTANEOUS_PRESSES_DELAY
+                smtd_press_following_key(state, false);
+
+                // release current state, because the first key is already processed
+                smtd_next_stage(state, SMTD_STAGE_NONE);
+
+                // then rerun the 3rd key press
+                // since we have just press following state, we need to simulate the press of the 3rd key again
+                // because by pressing second key we might have changed a layer, so current keycode might be not actual
+                // if we don't do this, we might continue processing the wrong key
+                SMTD_SIMULTANEOUS_PRESSES_DELAY
+
+                // we also don't need to freeze the state here, because we are already put in NONE stage
+                keyevent_t event_press = MAKE_KEYEVENT(record->event.key.row, record->event.key.col, true);
+                keyrecord_t record_press = {.event = event_press};
+                process_record(&record_press);
+
+                // we have processed the 3rd key, so we intentionally return false to stop further processing
+                return false;
+            }
+            return true;
+    }
+
+    return true;
+}
+
+/* ************************************* *
+ *      ENTRY POINT IMPLEMENTATION       *
+ * ************************************* */
+
+bool process_smtd(uint16_t keycode, keyrecord_t *record) {
+    #ifdef SMTD_DEBUG_ENABLED
+    printf("\n>> GOT KEY %s %s\n", keycode_to_string(keycode), record->event.pressed ? "PRESSED" : "RELEASED");
+    #endif
+
+    // check if any active state may process an event
+    for (uint8_t i = 0; i < smtd_active_states_size; i++) {
+        smtd_state *state = &smtd_active_states[i];
+        if (!process_smtd_state(keycode, record, state)) {
+            #ifdef SMTD_DEBUG_ENABLED
+            printf("<< HANDLE KEY %s %s by %s\n", keycode_to_string(keycode),
+                   record->event.pressed ? "PRESSED" : "RELEASED", keycode_to_string(state->macro_keycode));
+            #endif
+            return false;
+        }
+    }
+
+    // may be start a new state? A key must be just pressed
+    if (!record->event.pressed) {
+        #ifdef SMTD_DEBUG_ENABLED
+        printf("<< BYPASS KEY %s %s\n", keycode_to_string(keycode), record->event.pressed ? "PRESSED" : "RELEASED");
+        #endif
+        return true;
+    }
+
+    // check if the key is a macro key
+    if (keycode <= SMTD_KEYCODES_BEGIN || SMTD_KEYCODES_END <= keycode) {
+        #ifdef SMTD_DEBUG_ENABLED
+        printf("<< BYPASS KEY %s %s\n", keycode_to_string(keycode), record->event.pressed ? "PRESSED" : "RELEASED");
+        #endif
+        return true;
+    }
+
+    // check if the key is already handled
+    for (uint8_t i = 0; i < smtd_active_states_size; i++) {
+        if (smtd_active_states[i].macro_keycode == keycode) {
+            #ifdef SMTD_DEBUG_ENABLED
+            printf("<< ALREADY HANDELED KEY %s %s\n", keycode_to_string(keycode), record->event.pressed ? "PRESSED" : "RELEASED");
+            #endif
+            return true;
+        }
+    }
+
+    // create a new state and process the event
+    smtd_state *state = &smtd_active_states[smtd_active_states_size];
+    state->macro_keycode = keycode;
+    smtd_active_states_size++;
+
+    #ifdef SMTD_DEBUG_ENABLED
+    printf("<< CREATE STATE %s %s\n", keycode_to_string(keycode), record->event.pressed ? "PRESSED" : "RELEASED");
+    #endif
+    return process_smtd_state(keycode, record, state);
+}
+
+/* ************************************* *
+ *         CUSTOMIZATION MACROS          *
+ * ************************************* */
+
+#ifdef CAPS_WORD_ENABLE
+#define SMTD_TAP_16(use_cl, key) tap_code16(use_cl && is_caps_word_on() ? LSFT(key) : key)
+#define SMTD_REGISTER_16(use_cl, key) register_code16(use_cl && is_caps_word_on() ? LSFT(key) : key)
+#define SMTD_UNREGISTER_16(use_cl, key) unregister_code16(use_cl && is_caps_word_on() ? LSFT(key) : key)
+#else
+#define SMTD_TAP_16(use_cl, key) tap_code16(key)
+#define SMTD_REGISTER_16(use_cl, key) register_code16(key)
+#define SMTD_UNREGISTER_16(use_cl, key) unregister_code16(key)
+#endif
+
+#define SMTD_GET_MACRO(_1, _2, _3, _4, _5, NAME, ...) NAME
+#define SMTD_MT(...) SMTD_GET_MACRO(__VA_ARGS__, SMTD_MT5, SMTD_MT4, SMTD_MT3)(__VA_ARGS__)
+#define SMTD_MTE(...) SMTD_GET_MACRO(__VA_ARGS__, SMTD_MTE5, SMTD_MTE4, SMTD_MTE3)(__VA_ARGS__)
+#define SMTD_LT(...) SMTD_GET_MACRO(__VA_ARGS__, SMTD_LT5, SMTD_LT4, SMTD_LT3)(__VA_ARGS__)
+
+#define SMTD_MT3(macro_key, tap_key, mod) SMTD_MT4(macro_key, tap_key, mod, 1000)
+#define SMTD_MTE3(macro_key, tap_key, mod) SMTD_MTE4(macro_key, tap_key, mod, 1000)
+#define SMTD_LT3(macro_key, tap_key, layer) SMTD_LT4(macro_key, tap_key, layer, 1000)
+
+#define SMTD_MT4(macro_key, tap_key, mod, threshold) SMTD_MT5(macro_key, tap_key, mod, threshold, true)
+#define SMTD_MTE4(macro_key, tap_key, mod, threshold) SMTD_MTE5(macro_key, tap_key, mod, threshold, true)
+#define SMTD_LT4(macro_key, tap_key, layer, threshold) SMTD_LT5(macro_key, tap_key, layer, threshold, true)
+
+#define SMTD_MT5(macro_key, tap_key, mod, threshold, use_cl)  \
+    case macro_key: {                                         \
+        switch (action) {                                     \
+            case SMTD_ACTION_TOUCH:                           \
+                break;                                        \
+            case SMTD_ACTION_TAP:                             \
+                SMTD_TAP_16(use_cl, tap_key);                 \
+                break;                                        \
+            case SMTD_ACTION_HOLD:                            \
+                if (tap_count < threshold) {                  \
+                    register_mods(MOD_BIT(mod));              \
+                } else {                                      \
+                    SMTD_REGISTER_16(use_cl, tap_key);        \
+                }                                             \
+                break;                                        \
+            case SMTD_ACTION_RELEASE:                         \
+                if (tap_count < threshold) {                  \
+                    unregister_mods(MOD_BIT(mod));            \
+                } else {                                      \
+                    SMTD_UNREGISTER_16(use_cl, tap_key);      \
+                    send_keyboard_report();                   \
+                }                                             \
+                break;                                        \
+        }                                                     \
+        break;                                                \
+    }
+
+#define SMTD_MTE5(macro_key, tap_key, mod, threshold, use_cl) \
+    case macro_key: {                                         \
+        switch (action) {                                     \
+            case SMTD_ACTION_TOUCH:                           \
+                register_mods(MOD_BIT(mod));                  \
+                break;                                        \
+            case SMTD_ACTION_TAP:                             \
+                unregister_mods(MOD_BIT(mod));                \
+                SMTD_TAP_16(use_cl, tap_key);                 \
+                break;                                        \
+            case SMTD_ACTION_HOLD:                            \
+                if (!(tap_count < threshold)) {               \
+                    unregister_mods(MOD_BIT(mod));            \
+                    SMTD_REGISTER_16(use_cl, tap_key);        \
+                }                                             \
+                break;                                        \
+            case SMTD_ACTION_RELEASE:                         \
+                if (tap_count < threshold) {                  \
+                    unregister_mods(MOD_BIT(mod));            \
+                    send_keyboard_report();                   \
+                } else {                                      \
+                    SMTD_UNREGISTER_16(use_cl, tap_key);      \
+                }                                             \
+                break;                                        \
+        }                                                     \
+        break;                                                \
+    }
+
+#define SMTD_LT5(macro_key, tap_key, layer, threshold, use_cl)\
+    case macro_key: {                                         \
+        switch (action) {                                     \
+            case SMTD_ACTION_TOUCH:                           \
+                break;                                        \
+            case SMTD_ACTION_TAP:                             \
+                SMTD_TAP_16(use_cl, tap_key);                 \
+                break;                                        \
+            case SMTD_ACTION_HOLD:                            \
+                if (tap_count < threshold) {                  \
+                    LAYER_PUSH(layer);                        \
+                } else {                                      \
+                    SMTD_REGISTER_16(use_cl, tap_key);        \
+                }                                             \
+                break;                                        \
+            case SMTD_ACTION_RELEASE:                         \
+                if (tap_count < threshold) {                  \
+                    LAYER_RESTORE();                          \
+                }                                             \
+                SMTD_UNREGISTER_16(use_cl, tap_key);          \
+                break;                                        \
+        }                                                     \
+        break;                                                \
+    }
+