add macos forward-to-ime-modifier-mask

shiena · shiena · commit 1034e3befd57 · 2026-05-03T06:10:25.000+09:00
- gate interpretKeyEvents: forwarding by a configurable modifier mask
- handle IME direct commits without preedit (e.g. SKK kana mode)
- swallow keys consumed via IMKTextInput.selectMode (SKK Ctrl+J, q)
diff --git a/frontends/rioterm/src/bindings/mod.rs b/frontends/rioterm/src/bindings/mod.rs
@@ -731,7 +731,7 @@ pub fn default_key_bindings(config: &rio_backend::config::Config) -> Vec<KeyBind
     bindings.extend(platform_key_bindings(
         config.navigation.has_navigation_key_bindings(),
         config.navigation.use_split,
-        config.keyboard,
+        config.keyboard.clone(),
     ));
 
     // Add hint bindings
diff --git a/frontends/rioterm/src/router/window.rs b/frontends/rioterm/src/router/window.rs
@@ -187,6 +187,7 @@ pub fn configure_window(winit_window: &Window, config: &Config) {
         // OnlyRight - The right `Option` key is treated as `Alt`.
         // Both - Both `Option` keys are treated as `Alt`.
         // None - No special handling is applied for `Option` key.
+        use rio_window::keyboard::ModifiersState;
         use rio_window::platform::macos::{OptionAsAlt, WindowExtMacOS};
 
         match config.option_as_alt.to_lowercase().as_str() {
@@ -195,6 +196,20 @@ pub fn configure_window(winit_window: &Window, config: &Config) {
             "right" => winit_window.set_option_as_alt(OptionAsAlt::OnlyRight),
             _ => {}
         }
+
+        let mut mask = ModifiersState::empty();
+        for name in &config.keyboard.forward_to_ime_modifier_mask {
+            match name.to_lowercase().as_str() {
+                "shift" => mask |= ModifiersState::SHIFT,
+                "ctrl" | "control" => mask |= ModifiersState::CONTROL,
+                "alt" | "option" => mask |= ModifiersState::ALT,
+                "super" | "cmd" | "command" => mask |= ModifiersState::SUPER,
+                other => tracing::warn!(
+                    "ignoring unknown forward-to-ime-modifier-mask value: {other:?}"
+                ),
+            }
+        }
+        winit_window.set_forward_to_ime_modifier_mask(mask);
     }
 
     let is_transparent = config.window.opacity < 1.;
diff --git a/frontends/rioterm/src/screen/mod.rs b/frontends/rioterm/src/screen/mod.rs
@@ -226,7 +226,7 @@ impl Screen<'_> {
             split_active_color: config.colors.split_active,
             panel: config.panel,
             title: config.title.clone(),
-            keyboard: config.keyboard,
+            keyboard: config.keyboard.clone(),
             scrollback_history_limit: config.scrollback_history_limit,
         };
 
@@ -528,7 +528,7 @@ impl Screen<'_> {
             .set_multiplier_and_divider(config.scroll.multiplier, config.scroll.divider);
 
         // Update keyboard config in context manager
-        self.context_manager.config.keyboard = config.keyboard;
+        self.context_manager.config.keyboard = config.keyboard.clone();
 
         // Re-evaluate the opaque flag — toggling `window.opacity` /
         // `window.blur` at runtime should flip the compositor mode.
diff --git a/rio-backend/src/config/defaults.rs b/rio-backend/src/config/defaults.rs
@@ -148,6 +148,16 @@ pub fn default_ime_cursor_positioning() -> bool {
     true
 }
 
+#[inline]
+pub fn default_forward_to_ime_modifier_mask() -> Vec<String> {
+    vec![
+        String::from("shift"),
+        String::from("ctrl"),
+        String::from("alt"),
+        String::from("super"),
+    ]
+}
+
 pub fn default_config_file_content() -> String {
     String::from(
         "# See the full configuration reference: https://rioterm.com/docs/config\n",
diff --git a/rio-backend/src/config/keyboard.rs b/rio-backend/src/config/keyboard.rs
@@ -1,8 +1,11 @@
 use serde::{Deserialize, Serialize};
 
-use super::defaults::{default_disable_ctlseqs_alt, default_ime_cursor_positioning};
+use super::defaults::{
+    default_disable_ctlseqs_alt, default_forward_to_ime_modifier_mask,
+    default_ime_cursor_positioning,
+};
 
-#[derive(Debug, Serialize, Deserialize, PartialEq, Clone, Copy)]
+#[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
 pub struct Keyboard {
     // Disable ctlseqs with ALT keys
     // For example: Terminal.app does not deal with ctlseqs with ALT keys
@@ -19,6 +22,20 @@ pub struct Keyboard {
         rename = "ime-cursor-positioning"
     )]
     pub ime_cursor_positioning: bool,
+
+    // Modifier mask deciding when a key event is forwarded to the macOS IME.
+    // A key event is forwarded when no modifier is pressed, or when the
+    // pressed modifiers intersect this mask. Otherwise the event is handled
+    // directly by the application without going through the IME.
+    //
+    // Accepted values (case-insensitive): "shift", "ctrl", "alt", "super".
+    // Useful for input methods like SKK that need to receive Ctrl+key
+    // combinations directly.
+    #[serde(
+        default = "default_forward_to_ime_modifier_mask",
+        rename = "forward-to-ime-modifier-mask"
+    )]
+    pub forward_to_ime_modifier_mask: Vec<String>,
 }
 
 #[allow(clippy::derivable_impls)]
@@ -30,6 +47,7 @@ impl Default for Keyboard {
             #[cfg(not(target_os = "macos"))]
             disable_ctlseqs_alt: false,
             ime_cursor_positioning: default_ime_cursor_positioning(),
+            forward_to_ime_modifier_mask: default_forward_to_ime_modifier_mask(),
         }
     }
 }
diff --git a/rio-window/src/platform/macos.rs b/rio-window/src/platform/macos.rs
@@ -17,6 +17,7 @@
 use std::os::raw::c_void;
 
 use crate::event_loop::{ActiveEventLoop, EventLoopBuilder};
+use crate::keyboard::ModifiersState;
 use crate::monitor::MonitorHandle;
 use crate::window::{Window, WindowAttributes};
 
@@ -106,6 +107,21 @@ pub trait WindowExtMacOS {
     /// Getter for the [`WindowExtMacOS::set_option_as_alt`].
     fn option_as_alt(&self) -> OptionAsAlt;
 
+    /// Set which modifier keys cause a key event to be forwarded to the macOS
+    /// IME (`interpretKeyEvents:`).
+    ///
+    /// A key event is forwarded to the IME when no modifier is pressed, OR
+    /// when the pressed modifiers intersect this mask. Otherwise the event is
+    /// handled directly by the application without going through the IME.
+    ///
+    /// This is useful for input methods (e.g. SKK) that need to receive
+    /// `Ctrl`/`Shift` combinations directly instead of having them processed
+    /// as terminal control sequences.
+    fn set_forward_to_ime_modifier_mask(&self, mask: ModifiersState);
+
+    /// Getter for the [`WindowExtMacOS::set_forward_to_ime_modifier_mask`].
+    fn forward_to_ime_modifier_mask(&self) -> ModifiersState;
+
     /// Makes the titlebar bigger, effectively adding more space around the
     /// window controls if the titlebar is invisible.
     fn set_unified_titlebar(&self, unified_titlebar: bool);
@@ -220,6 +236,18 @@ impl WindowExtMacOS for Window {
         self.window.maybe_wait_on_main(|w| w.option_as_alt())
     }
 
+    #[inline]
+    fn set_forward_to_ime_modifier_mask(&self, mask: ModifiersState) {
+        self.window
+            .maybe_queue_on_main(move |w| w.set_forward_to_ime_modifier_mask(mask))
+    }
+
+    #[inline]
+    fn forward_to_ime_modifier_mask(&self) -> ModifiersState {
+        self.window
+            .maybe_wait_on_main(|w| w.forward_to_ime_modifier_mask())
+    }
+
     #[inline]
     fn set_unified_titlebar(&self, unified_titlebar: bool) {
         self.window
diff --git a/rio-window/src/platform_impl/macos/view.rs b/rio-window/src/platform_impl/macos/view.rs
@@ -138,6 +138,13 @@ pub struct ViewState {
     /// True if we're currently processing a key event
     in_key_event: Cell<bool>,
 
+    /// Characters of the currently-processed key event, as reported by
+    /// `NSEvent`. Tuple of (characters, charactersIgnoringModifiers).
+    /// Used by `insertText:` to distinguish IME direct commits (e.g. SKK
+    /// hiragana mode) from raw keyboard pass-through (where the IME echoes
+    /// the same characters).
+    current_key_event_chars: RefCell<Option<(String, String)>>,
+
     marked_text: RefCell<Retained<NSMutableAttributedString>>,
     accepts_first_mouse: bool,
 
@@ -146,6 +153,11 @@ pub struct ViewState {
 
     /// The state of the `Option` as `Alt`.
     option_as_alt: Cell<OptionAsAlt>,
+
+    /// Modifier mask deciding when a key event is forwarded to the IME.
+    /// A key event is forwarded when no modifier is pressed, or when the
+    /// pressed modifiers intersect this mask.
+    forward_to_ime_modifier_mask: Cell<ModifiersState>,
 }
 
 declare_class!(
@@ -421,23 +433,55 @@ declare_class!(
             let has_marked_text = unsafe { self.hasMarkedText() };
             let is_in_key_event = self.ivars().in_key_event.get();
 
+            // Detect IME direct commits (e.g. SKK hiragana mode) that bypass
+            // preedit: an `insertText:` whose payload differs from the raw
+            // NSEvent characters is something the IME synthesised, not a
+            // pass-through of the pressed key.
+            let is_ime_direct_commit = is_in_key_event
+                && self
+                    .ivars()
+                    .current_key_event_chars
+                    .borrow()
+                    .as_ref()
+                    .is_some_and(|(chars, chars_unmod)| {
+                        string != chars.as_str() && string != chars_unmod.as_str()
+                    });
+
             if self.is_ime_enabled() {
                 if has_marked_text && !is_control {
                     // Clear preedit and commit the text (normal IME flow)
                     self.queue_event(WindowEvent::Ime(Ime::Preedit(String::new(), None)));
                     self.queue_event(WindowEvent::Ime(Ime::Commit(string)));
                     self.ivars().ime_state.set(ImeState::Committed);
-                } else if !is_control && !string.is_empty() && !is_in_key_event {
-                    // Direct input not from keyboard (e.g., emoji picker)
+                } else if !is_control
+                    && !string.is_empty()
+                    && (!is_in_key_event || is_ime_direct_commit)
+                {
+                    // Direct input not from keyboard (e.g., emoji picker) or
+                    // an IME committing without preedit (e.g., SKK).
                     self.queue_event(WindowEvent::Ime(Ime::Commit(string)));
                     self.ivars().ime_state.set(ImeState::Committed);
+                } else if is_in_key_event && !is_ime_direct_commit {
+                    // The IME passed the raw key through unchanged (typical
+                    // when the active input source is ASCII-only or the IME
+                    // is in a passthrough mode, e.g. SKK ASCII/eisuu mode).
+                    // Treat this as "IME did not consume the key" so the key
+                    // event is forwarded to the application.
+                    self.ivars().forward_key_to_app.set(true);
                 }
-            } else if !is_control && !string.is_empty() && !is_in_key_event {
+            } else if !is_control
+                && !string.is_empty()
+                && (!is_in_key_event || is_ime_direct_commit)
+            {
                 // IME is disabled but we got non-keyboard input (e.g., emoji picker)
-                // Temporarily enable IME for this input
+                // or an IME-style direct commit. Temporarily enable IME for
+                // this input.
                 self.queue_event(WindowEvent::Ime(Ime::Enabled));
                 self.queue_event(WindowEvent::Ime(Ime::Commit(string)));
                 self.ivars().ime_state.set(ImeState::Committed);
+            } else if is_in_key_event && !is_ime_direct_commit {
+                // IME disabled and the IME echoed the raw key — forward it.
+                self.ivars().forward_key_to_app.set(true);
             }
         }
 
@@ -490,13 +534,32 @@ declare_class!(
             self.ivars().forward_key_to_app.set(false);
             let event = replace_event(event, self.option_as_alt());
 
+            // Snapshot the NSEvent characters so `insertText:` can tell IME
+            // direct commits (e.g. SKK hiragana mode) from raw key pass-through.
+            let chars = unsafe { event.characters() }
+                .map(|s| s.to_string())
+                .unwrap_or_default();
+            let chars_unmod = unsafe { event.charactersIgnoringModifiers() }
+                .map(|s| s.to_string())
+                .unwrap_or_default();
+            *self.ivars().current_key_event_chars.borrow_mut() =
+                Some((chars, chars_unmod));
+
             // The `interpretKeyEvents` function might call
             // `setMarkedText`, `insertText`, and `doCommandBySelector`.
             // It's important that we call this before queuing the KeyboardInput, because
             // we must send the `KeyboardInput` event during IME if it triggered
             // `doCommandBySelector`. (doCommandBySelector means that the keyboard input
             // is not handled by IME and should be handled by the application)
-            if self.ivars().ime_allowed.get() {
+            //
+            // The IME is bypassed when modifiers are pressed that do not intersect the
+            // configured `forward_to_ime_modifier_mask`. Events with no modifiers are
+            // always forwarded.
+            let mods = event_mods(&event).state();
+            let mask = self.ivars().forward_to_ime_modifier_mask.get();
+            let forward_to_ime = mods.is_empty() || mods.intersects(mask);
+            let routed_to_ime = self.ivars().ime_allowed.get() && forward_to_ime;
+            if routed_to_ime {
                 let events_for_nsview = NSArray::from_slice(&[&*event]);
                 unsafe { self.interpretKeyEvents(&events_for_nsview) };
 
@@ -520,7 +583,20 @@ declare_class!(
                 _ => old_ime_state != self.ivars().ime_state.get(),
             };
 
-            if !had_ime_input || self.ivars().forward_key_to_app.get() {
+            // When the event was routed through the IME, only forward it to
+            // the application if `doCommandBySelector:` explicitly asked us to
+            // (`forward_key_to_app`). Otherwise the IME is assumed to have
+            // consumed the key — even when it produced no NSTextInputClient
+            // callbacks (e.g. SKK switching input mode via
+            // `IMKTextInput.selectMode()` on Ctrl+J or `q`). When the event
+            // was *not* routed to the IME, fall back to the historical
+            // behavior of forwarding it as long as no preedit/commit happened.
+            let should_forward_key = if routed_to_ime {
+                self.ivars().forward_key_to_app.get()
+            } else {
+                !had_ime_input
+            };
+            if should_forward_key {
                 let key_event = create_key_event(&event, true, unsafe { event.isARepeat() }, None);
                 self.queue_event(WindowEvent::KeyboardInput {
                     device_id: DEVICE_ID,
@@ -531,6 +607,7 @@ declare_class!(
 
             // Clear the flag after processing
             self.ivars().in_key_event.set(false);
+            *self.ivars().current_key_event_chars.borrow_mut() = None;
         }
 
         #[method(keyUp:)]
@@ -855,6 +932,8 @@ impl WinitView {
             accepts_first_mouse,
             _ns_window: WeakId::new(&window.retain()),
             option_as_alt: Cell::new(option_as_alt),
+            forward_to_ime_modifier_mask: Cell::new(ModifiersState::all()),
+            current_key_event_chars: RefCell::new(None),
         });
         let this: Retained<Self> = unsafe { msg_send_id![super(this), init] };
 
@@ -1022,6 +1101,14 @@ impl WinitView {
         self.ivars().option_as_alt.get()
     }
 
+    pub(super) fn set_forward_to_ime_modifier_mask(&self, value: ModifiersState) {
+        self.ivars().forward_to_ime_modifier_mask.set(value)
+    }
+
+    pub(super) fn forward_to_ime_modifier_mask(&self) -> ModifiersState {
+        self.ivars().forward_to_ime_modifier_mask.get()
+    }
+
     /// Update modifiers if `event` has something different
     fn update_modifiers(&self, ns_event: &NSEvent, is_flags_changed_event: bool) {
         use ElementState::{Pressed, Released};
diff --git a/rio-window/src/platform_impl/macos/window_delegate.rs b/rio-window/src/platform_impl/macos/window_delegate.rs
@@ -2214,6 +2214,14 @@ impl WindowExtMacOS for WindowDelegate {
         self.view().option_as_alt()
     }
 
+    fn set_forward_to_ime_modifier_mask(&self, mask: crate::keyboard::ModifiersState) {
+        self.view().set_forward_to_ime_modifier_mask(mask);
+    }
+
+    fn forward_to_ime_modifier_mask(&self) -> crate::keyboard::ModifiersState {
+        self.view().forward_to_ime_modifier_mask()
+    }
+
     fn set_unified_titlebar(&self, unified_titlebar: bool) {
         let window = self.window();
         if unified_titlebar {
