`getHeldKeys()` returns stale state during `HotkeySequenceRecorder` / `HotkeyRecorder` recording

[buhodev]

TanStack Hotkeys version

@tanstack/hotkeys v0.8.0

Framework/Library version

@tanstack/svelte-hotkeys v0.10.0

Describe the bug and the steps to reproduce it

Summary

When a recorder (HotkeySequenceRecorder or HotkeyRecorder) is actively recording, getHeldKeys() (and the underlying KeyStateTracker.store) does not update for keys that are pressed while recording. Released keys are still removed (because the keyup listener fires after the recorder), but newly pressed keys never appear in heldKeys until recording stops.

This makes it impossible to build a "live held-modifier preview" UI on top of the recorder, which is the documented use case for getHeldKeys() ("Custom shortcut recording for rebinding").

Root cause

Both recorders attach their keydown listener in capture phase and call stopPropagation() on every event:

dist/hotkey-sequence-recorder.js:174 — document.addEventListener("keydown", this.#keydownListener, true);
dist/hotkey-sequence-recorder.js:82-83 — event.preventDefault(); event.stopPropagation();

The same pattern exists in HotkeyRecorder.

KeyStateTracker, however, attaches its keydown/keyup listeners in bubble phase:

dist/key-state-tracker.js:109-110

document.addEventListener("keydown", this.#keydownListener);
document.addEventListener("keyup", this.#keyupListener);

Because the recorder runs first (capture) and stops propagation, the tracker's bubble-phase keydown listener never fires while recording. keyup events are not stopped by the recorder, so releases still propagate, leaving the tracker permanently behind.

Repro

Minimal Svelte 5 example:

<script>
  import { createHotkeySequenceRecorder, getHeldKeys } from '@tanstack/svelte-hotkeys';

  const recorder = createHotkeySequenceRecorder(() => ({ commitKeys: 'enter' }));
  const held = getHeldKeys();
</script>

<button onclick={() => recorder.startRecording()}>Start</button>
<button onclick={() => recorder.commitRecording()}>Stop</button>

<p>Held: {held.keys.join(' + ') || '(empty)'}</p>

1. Click Start.
2. Press and hold Ctrl (or any modifier) alone.
3. Observe: held.keys stays [].
4. Click Stop, press Ctrl again — now held.keys correctly shows ['Control'].

Proposed fix

Make KeyStateTracker listen in capture phase, matching the recorders:

-document.addEventListener("keydown", this.#keydownListener);
-document.addEventListener("keyup", this.#keyupListener);
+document.addEventListener("keydown", this.#keydownListener, true);
+document.addEventListener("keyup", this.#keyupListener, true);

…with the matching change in #removeListeners(). The tracker only reads event.key / event.code and never calls preventDefault or stopPropagation, so moving it to capture phase has no effect on application behaviour — it just means the tracker observes events before any listener can stop them.

Your Minimal, Reproducible Example - (Sandbox Highly Recommended)

https://svelte.dev/playground/hello-world?version=5.55.5#H4sIAAAAAAAAA51XTW_bRhD9K1O6gCVUokzHShqGVj-CAEFTtEHcW5TDkjsUF1ruMrtD26proJfee-ipLZB7z_1F_QX9CcXyW19JUB0EejTz9s17s7v0nadYjl7orZCeo-QvcGPBEpMIvDRCrcBgog0XauVNvFRItF74-s6jTeGqXMCbtBhfFYVvr1GSi8XM4qF4ohWhIuuFXmQTIwoCydTqcumRXXqLpVqSyAttCO7c85ISg4zwuaY1bq7wbYkqwVcVKTSTOmVA3gXuITU6h9MviSlLLFnP6tWnWQViT58slctLtLIEWdv2JQxwRuMmSSI1GiCHS_jUEiOMLDlxXr-Bn0CVUi5G7nu8hdsUGbiE97UwGo3hcgGjtlud54IcgxBOURGa06ZJreqSEEYW31ZFTc2SBgQtvn1Sh-8rLcYtq7RUCQmtnL2GRuO2elDrmniyFTV-lf2qHYJalgp6G1IXPaJIYTSox8L6EtWKMljA2bgTxq973cVeEkqLgyymEpQHGESzen7czKgoZ0JV0xNlwWLLSIhLN8aF0dEsCxY19chiTT2RzNrLpbcygjfzt6SIi-uFQwA3LzCS4hrHYTRz4SYj0RwXd99cff-dXw-DSDejdpZ8Vza-j2ZVVr1ig9r6DtUgHcLsOhe26xq-gNN_3_32d78dTyGE039-_wsEl3h6cKkrJz1YDSkzH0F-27LD7L9l_WTz95Dn8AUchufjivjPvw05UzRr_Gjt4eK6s4ZVv9jenbgk0gq0SqRI1pd31YzeAxeWxRL55UEJ7xdXLq1XMJrVOMdRdTEE_eQYqi62oDpVqmE0MOuezxev3BhCJXA0y87rfC1bClIs2i39NabaIFRc3ABEmO83gPliApmWHKJ1zBdPycho5p5Amzp0lYmU6pjfQrvTS6vV4tltgQlVPjaRapVu7it8sJm-sVDb-3rpPdWKjJZL701jnw___PkL3Gizts0K0azrw3X01LVwlL8PP2T9bocYE52jBef5Nfo7UG0Hzz-yZWBSK4SR0kBGrFZoXGPj_6lEWXBGaPeqv0qoZPIDKhLbdCr20v377tc_DorWrvHSoLW7rX5W_f2i6ZE01CcpMEgybXgtafUIrCiQGQtCdawrI_qToXHhAGfhXgWElIB5QZvD5h7g-czdWr0nycB-t1McMmlIhWJS_Ii7sNGs3g7thtGaIGGlxX6_FFtHzgvcXLmj9AfDkrVbuIqCwZWwhFXr0DoVl3EssTeqyJhF0GqIx3VS5qio82hrPg_CJqyg0uzhMsUhYVLaITxeoyLfnS0vjS7YirmzbTRuVpvATSaSrLpQLVCGUOVDXJ8Gwu0elmRooW6lXqnR8EpXFVQLATFmQvFm5rZuxFYjhdfuIkK0znWub9RsjZuycCQk9hvVr41xukez9qJVkaWNrI_vcCV1zOQoNFpT9x6QaKnN1CYZ5hiCFKuMgDOzbq756TReNeGpC49O0uozgZOzNAiC-bhLTHcSgyD4_PzRBE5wjo8w7hPzkpDv4z5IL9KHEzgJ0vPHDx7tpVfWbpfwgM95PIGTB48ugnnQl6zjffyaxbHk96FfxPP5wwd9QWY-Avl-KHms-aZTPGbJemV0qXgI18yMnMQteOVGG067cM7MSqgQznpo53CLmGpF05TlQm5CsBtLmE9LMQHLlJ1aNCLtcG6nN4JTFsLDi7Pidgf-3GAOrCTdxAvG3WSFcAaBwbyJSqFwmqETIITAn_ecfPd-1pLiwhaSbUJwwabUPU4J80IywmmiZZkrG4Kj1fzLAUFq2mRWhHDmzx2pwfItWRcaCuJ2y3GJ25n7gNB9x36N71_0K9dDMjWMi9KGcNHpV-lvxY_o6h43-RWpdcyPc6qn9AOM2skMiluwWgo-LK5-286cxppI563N5x3Jo-wHPZ_N95re6u3z-Xa8nblSTHOttC1YghPoHgeT0bwe7g1HKvF23---sHnfu9ujelEzfXyE6eP5Mdse7iiyL-3wwOnE_b8TlZTGunihhbtydzsL21fXtkVdsETQplJiB0JpmjIp9Q3yHiYz3YA17Zxt90262G8xM7tHS1BvtG5DuXuyvjm8iUd4S15IpsT7NxOPmJA3QnEvTJm0eP8fAWgfcqAQAAA

Screenshots or Videos (Optional)

No response

Do you intend to try to help solve this bug with your own PR?

Yes, I am also opening a PR that solves the problem along side this issue

Terms & Code of Conduct

• I agree to follow this project's Code of Conduct
• I understand that if my bug cannot be reliable reproduced in a debuggable environment, it will probably not be fixed and this issue may even be closed.