Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,38 @@ Notes:
- Firmware repo: `../qmk_firmware_zsa` (keyboard `zsa/voyager`, keymap `sm`); `modules/stasmarkin/sm_td/` there is symlinked to this repo's `sm_td/`, so builds pick up local changes directly.
- Build/flash: `cd ../qmk_firmware_zsa && just build` / `just flash` (DFU). That keymap enables CAPS_WORD, COMBO, REPEAT_KEY, UNICODE - a good integration stress test.

## Chordal Hold (SMTD_CHORDAL_HOLD)
- NEW FEATURE (2026-06-16): Chordal hold, like QMK's chordal hold. Deferred decision — no immediate settle on press, only cancels timeout. TAP/HOLD decided at the last moment before HOLD delivery by scanning all active unresolved states.
- Configuration: define `SMTD_CHORDAL_HOLD 1` in your `config.h`, and define the layout matrix:
```c
const char chordal_hold_layout[MATRIX_ROWS][MATRIX_COLS] PROGMEM =
LAYOUT_split_3x6_3_ex2(
'L', 'L', 'L', 'L', 'L', 'L','L', 'R','R', 'R', 'R', 'R', 'R', 'R',
'L', 'L', 'L', 'L', 'L', 'L','L', 'R','R', 'R', 'R', 'R', 'R', 'R',
'L', 'L', 'L', 'L', 'L', 'L', 'R', 'R', 'R', 'R', 'R', 'R',
'*', '*', '*', '*', '*', '*'
);
```
where `'L'` = left hand, `'R'` = right hand, `'*'` = thumb (neutral).
- Behavior:
1. **Same-hand key PRESSED** while a state is in TOUCH: cancel the hold timeout (prevents accidental HOLD from timeout expiry). The state stays in TOUCH pending further keys.
2. **ANY key RELEASED** (following key in STAGE_TOUCH or STAGE_TOUCH_RELEASE): before sending HOLD, scan all active states via `smtd_chordal_all_same_hand()`:
- If the current state's hand differs from any other active state → HOLD (cross-hand combo)
- If all active states share the same hand (or current is the only one) → TAP (typing within one hand)
3. **Opposite-hand key PRESSED**: timeout NOT cancelled → timeout fires → HOLD. Or the following-key release path decides HOLD (cross-hand check in step 2).
- This means:
- Same-hand typing (e.g., `MT(J,LSFT)` + `K` on same hand) → TAP for both (no accidental mod)
- Cross-hand combo (e.g., `MT(J,LSFT)` on left + `V` on right) → HOLD (Shift+V)
- Same-hand mod-taps + cross-hand key (e.g., `MT(J,LSFT,255)` + `MT(K,LGUI,255)` on left + `V` on right) → HOLD for both mods, TAP for V
- Same-hand mod-taps only (no cross-hand key) → TAP for all (both resolve as taps when released)
- Implementation in `sm_td.c`:
- `smtd_chordal_hand(keypos_t)` — reads hand from PROGMEM layout
- `smtd_chordal_same_hand(a, b)` — true if both keys are on same hand (thumbs match each other but not hands)
- `smtd_chordal_all_same_hand(pos)` — true if all active states (excluding self, NONE, SEQUENCE) have the same hand as pos; thumb pos returns false (neutral)
- Hooked into `SMTD_STAGE_TOUCH` (press + release) and `SMTD_STAGE_TOUCH_RELEASE` (release) in `smtd_apply_event` via `#if SMTD_CHORDAL_HOLD` guards
- Default: `SMTD_CHORDAL_HOLD 0` — completely compiled out, zero code/bloat impact when disabled.
- Not tested via Python mocks (no chordal_hold_layout in mock); needs QMK-native test suite or manual hardware test.

## Known Issues & Backlog
- Divergence from QMK (intentional, YAGNI): real QMK turns Caps Word off when a non-shift mod-tap is held; sm_td's MT hold (`register_mods`) stays invisible to Caps Word.
- `fixme-sm` in `smtd_emulate_key`: emulating keycodes absent from the keymap could use combo-style records (`record->keycode`, requires `COMBO_ENABLE`/`REPEAT_KEY_ENABLE`).
Expand Down
89 changes: 79 additions & 10 deletions sm_td/sm_td.c
Original file line number Diff line number Diff line change
Expand Up @@ -376,6 +376,11 @@ bool is_following_key(smtd_state *state, uint16_t pressed_keycode, keyrecord_t *
return false;
}

#if SMTD_CHORDAL_HOLD
static bool smtd_chordal_same_hand(keypos_t a, keypos_t b);
static bool smtd_chordal_all_same_hand(keypos_t current_pos);
#endif

void smtd_apply_event(bool is_state_key, smtd_state *state, uint16_t pressed_keycode, keyrecord_t *record) {
SMTD_DEBUG("--%s apply_event with %s, is_state_key=%d",
smtd_state_to_str(state),
Expand All @@ -398,41 +403,61 @@ void smtd_apply_event(bool is_state_key, smtd_state *state, uint16_t pressed_key
// -----------------------------------------------------------------------------------------
case SMTD_STAGE_TOUCH: {
if (state->idx + 1 == smtd_active_states_size) {
// last state in stack
if (is_state_key && !record->event.pressed) {
smtd_apply_stage(state, SMTD_STAGE_SEQUENCE);
if (!smtd_feature_enabled_or_default(state, SMTD_FEATURE_AGGREGATE_TAPS)) {
smtd_handle_action(state, SMTD_ACTION_TAP);
}

smtd_apply_stage(state, SMTD_STAGE_SEQUENCE);
break;
}

#if SMTD_CHORDAL_HOLD
if (!is_state_key && record->event.pressed) {
if (smtd_chordal_same_hand(state->pressed_keyposition, record->event.key)) {
cancel_deferred_exec(state->timeout);
state->timeout = INVALID_DEFERRED_TOKEN;
}
break;
}
#endif
break;
}

if (is_state_key && !record->event.pressed) {
// Macro key is released, moving to the next stage
smtd_apply_stage(state, SMTD_STAGE_TOUCH_RELEASE);
break;
}

#if SMTD_CHORDAL_HOLD
if (!is_state_key && record->event.pressed) {
if (smtd_chordal_same_hand(state->pressed_keyposition, record->event.key)) {
cancel_deferred_exec(state->timeout);
state->timeout = INVALID_DEFERRED_TOKEN;
}
break;
}
#endif

if (!is_following_key(state, pressed_keycode, record)) {
// Some previously pressed key has been released
// We don't need to do anything here
break;
}

if (!is_state_key && !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 let following state handle the key release
#if SMTD_CHORDAL_HOLD
if (smtd_chordal_all_same_hand(state->pressed_keyposition)) {
smtd_apply_stage(state, SMTD_STAGE_SEQUENCE);
if (!smtd_feature_enabled_or_default(state, SMTD_FEATURE_AGGREGATE_TAPS)) {
smtd_handle_action(state, SMTD_ACTION_TAP);
}
break;
}
#endif
smtd_apply_stage(state, SMTD_STAGE_HOLD);
smtd_handle_action(state, SMTD_ACTION_HOLD);
break;
}

break;
} // case SMTD_STAGE_TOUCH
}

// -----------------------------------------------------------------------------------------
case SMTD_STAGE_SEQUENCE: {
Expand Down Expand Up @@ -504,6 +529,15 @@ void smtd_apply_event(bool is_state_key, smtd_state *state, uint16_t pressed_key

// Following key is released. Now we definitely know that macro key is held
// we need to execute hold the macro key
#if SMTD_CHORDAL_HOLD
if (smtd_chordal_all_same_hand(state->pressed_keyposition)) {
if (!smtd_feature_enabled_or_default(state, SMTD_FEATURE_AGGREGATE_TAPS)) {
smtd_handle_action(state, SMTD_ACTION_TAP);
}
smtd_apply_stage(state, SMTD_STAGE_SEQUENCE);
break;
}
#endif
smtd_apply_stage(state, SMTD_STAGE_HOLD_RELEASE);
smtd_handle_action(state, SMTD_ACTION_HOLD);

Expand Down Expand Up @@ -1014,6 +1048,41 @@ bool smtd_feature_enabled_default(uint16_t keycode, smtd_feature feature) {
return false;
}

/* ************************************* *
* CHORDAL HOLD *
* ************************************* */

#if SMTD_CHORDAL_HOLD

static char smtd_chordal_hand(keypos_t key) {
return (char)pgm_read_byte(&chordal_hold_layout[key.row][key.col]);
}

static bool smtd_chordal_same_hand(keypos_t a, keypos_t b) {
char hand_a = smtd_chordal_hand(a);
char hand_b = smtd_chordal_hand(b);
if (hand_a == '*' && hand_b == '*') return true;
if (hand_a == '*' || hand_b == '*') return false;
return hand_a == hand_b;
}

static bool smtd_chordal_all_same_hand(keypos_t current_pos) {
char current_hand = smtd_chordal_hand(current_pos);
if (current_hand == '*') return false;
for (uint8_t i = 0; i < smtd_active_states_size; i++) {
smtd_state *other = smtd_active_states[i];
if (other->stage == SMTD_STAGE_NONE) continue;
if (other->stage == SMTD_STAGE_SEQUENCE) continue;
if (other->pressed_keyposition.row == current_pos.row && other->pressed_keyposition.col == current_pos.col) continue;
char other_hand = smtd_chordal_hand(other->pressed_keyposition);
if (other_hand == '*') continue;
if (other_hand != current_hand) return false;
}
return true;
}

#endif

/* ************************************* *
* TEST FRAMEWORK ACCESSORS *
* ************************************* */
Expand Down
12 changes: 12 additions & 0 deletions sm_td/sm_td.h
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,18 @@
#define SMTD_QMK_TAPHOLD_USE_CAPS_WORD true
#endif

/* ************************************* *
* CHORDAL HOLD CONFIGURATION *
* ************************************* */

#ifndef SMTD_CHORDAL_HOLD
#define SMTD_CHORDAL_HOLD 0
#endif

#if SMTD_CHORDAL_HOLD
extern const char chordal_hold_layout[MATRIX_ROWS][MATRIX_COLS];
#endif

#include <stdint.h>


Expand Down