fix: recover held modifiers after missed keyup events

[KevinVandy]

🎯 Changes

Recover held Control, Alt, Shift, and Meta state when a system shortcut or browser tool swallows keyup without blurring the page. Later keyboard events, mouse movement, and mouse button presses remove modifiers whose event flags report that they are no longer active. Active modifiers and both physical modifier keys remain tracked; unchanged mouse events do not notify subscribers.

Related to #143 and #66. Recovery still requires another input event or blur; it does not infer a release from elapsed time. The missing-event sequence is reproduced in tests, but the exact native macOS screenshot and DevTools shortcuts have not been verified. Keep this PR in draft pending that browser validation.

Adds regressions for all four modifiers, dual-key holds, code-less keys, repeated events, listener cleanup and React useKeyHold, plus documentation and a patch changeset. Targeted validation: 616 core tests and 5 React recovery/hint tests passed; core/React types, core lint and core build passed. pnpm test and pnpm run test:pr passed, including all 152 Nx tasks; the package is 10.46 kB against its 12 kB size limit.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested code changes locally with pnpm run test:pr, or these tests do not apply to this pull request.
• I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🚀 Changeset Version Preview

1 package(s) bumped directly, 12 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/hotkeys	0.10.0 → 0.10.1	Changeset
@tanstack/angular-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/hotkeys-devtools	1.1.0 → 1.1.1	Dependent
@tanstack/lit-hotkeys	0.13.0 → 0.13.1	Dependent
@tanstack/preact-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/preact-hotkeys-devtools	0.9.0 → 0.9.1	Dependent
@tanstack/react-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/react-hotkeys-devtools	0.9.0 → 0.9.1	Dependent
@tanstack/solid-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/solid-hotkeys-devtools	0.9.0 → 0.9.1	Dependent
@tanstack/svelte-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/vue-hotkeys	0.12.0 → 0.12.1	Dependent
@tanstack/vue-hotkeys-devtools	0.9.0 → 0.9.1	Dependent

[pkg-pr-new]

Open in StackBlitz

@tanstack/angular-hotkeys

npm i https://pkg.pr.new/@tanstack/angular-hotkeys@161

@tanstack/hotkeys

npm i https://pkg.pr.new/@tanstack/hotkeys@161

@tanstack/hotkeys-devtools

npm i https://pkg.pr.new/@tanstack/hotkeys-devtools@161

@tanstack/lit-hotkeys

npm i https://pkg.pr.new/@tanstack/lit-hotkeys@161

@tanstack/preact-hotkeys

npm i https://pkg.pr.new/@tanstack/preact-hotkeys@161

@tanstack/preact-hotkeys-devtools

npm i https://pkg.pr.new/@tanstack/preact-hotkeys-devtools@161

@tanstack/react-hotkeys

npm i https://pkg.pr.new/@tanstack/react-hotkeys@161

@tanstack/react-hotkeys-devtools

npm i https://pkg.pr.new/@tanstack/react-hotkeys-devtools@161

@tanstack/solid-hotkeys

npm i https://pkg.pr.new/@tanstack/solid-hotkeys@161

@tanstack/solid-hotkeys-devtools

npm i https://pkg.pr.new/@tanstack/solid-hotkeys-devtools@161

@tanstack/svelte-hotkeys

npm i https://pkg.pr.new/@tanstack/svelte-hotkeys@161

@tanstack/vue-hotkeys

npm i https://pkg.pr.new/@tanstack/vue-hotkeys@161

@tanstack/vue-hotkeys-devtools

npm i https://pkg.pr.new/@tanstack/vue-hotkeys-devtools@161

commit: 89cc98d