Skip to content

feat(macos): add opt-in physical-only key events - #198

Draft
LuisJann wants to merge 1 commit into
Narsil:mainfrom
LuisJann:feat/macos-physical-key-events
Draft

feat(macos): add opt-in physical-only key events#198
LuisJann wants to merge 1 commit into
Narsil:mainfrom
LuisJann:feat/macos-physical-key-events

Conversation

@LuisJann

Copy link
Copy Markdown

Summary

Recent macOS versions can abort a process when TIS/TSM input-source operations
run from an inappropriate queue. An rdev listen() callback can encounter this
while resolving layout-dependent key names.

This change adds the opt-in macos_physical_key_events feature. When enabled,
macOS key events are mapped exclusively from their physical keycodes and
Event::name is left unset. The default behavior remains unchanged.

Motivation

Consumers such as keyboard-sound applications do not need Unicode or current
keyboard-layout resolution; they need stable physical key identities. For those
applications, dispatching TIS work to the main queue adds latency and potential
re-entrancy/deadlock risk, while moving the complete event tap to the
application's main run loop changes callback scheduling.

An explicit physical-only mode avoids TIS entirely without changing callback
threading or affecting existing consumers. This complements the main-thread
initialization work in #147 and is
motivated by the crash class reported in
#146.

Changes

  • add the macos_physical_key_events Cargo feature;
  • map key down/up events directly with key_from_code when enabled;
  • avoid TIS-backed name lookup in both key classification and Event::name;
  • preserve the existing conversion path when the feature is disabled;
  • suppress feature-specific dead-code warnings in the unused TIS helpers.

Behavioral impact

With macos_physical_key_events enabled:

  • physical key press/release and modifier events remain available;
  • mouse events are unchanged;
  • Event::name is None for macOS key events;
  • layout-dependent fallback recognition for otherwise unknown extended keys is
    unavailable.

Without the feature, behavior and API output are unchanged.

Validation

  • cargo fmt --all --check: passed;
  • cargo test --lib: 4 passed with the default configuration;
  • cargo test --lib --features macos_physical_key_events: 4 passed;
  • an equivalent physical-only rdev 0.5.3 path was validated in MechvibesDX on
    Apple Silicon/macOS with global keyboard and mouse input, both audio paths,
    more than five minutes of stability, and close/reopen;
  • no SIGTRAP, dispatch_assert_queue, or
    TSMGetInputSourceProperty crash recurred in that consumer validation.

Compatibility

The feature is opt-in and does not alter the default configuration. A consumer
can enable it while retaining other features such as unstable_grab.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant