first version for notifications (closes #1470)

raphamorim · raphamorim · commit 12953e0e9b45 · 2026-03-29T17:37:38.000+02:00
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -7,6 +7,7 @@ members = [
     "rio-proc-macros",
     "rio-backend",
     "rio-window",
+    "rio-notifier",
     "frontends/rioterm",
 ]
 resolver = "2"
@@ -31,6 +32,7 @@ readme = "README.md"
 teletypewriter = { path = "teletypewriter", version = "0.3.0" }
 rio-backend = { path = "rio-backend", version = "0.3.0" }
 rio-window = { path = "rio-window", version = "0.3.0", default-features = false }
+rio-notifier = { path = "rio-notifier", version = "0.3.0" }
 sugarloaf = { path = "sugarloaf", version = "0.3.0" }
 
 # Own dependencies
diff --git a/docs/docs/escape-sequence-support.md b/docs/docs/escape-sequence-support.md
@@ -98,6 +98,7 @@ brevity.
 | `OSC 2`   | IMPLEMENTED |                                                |
 | `OSC 4`   | IMPLEMENTED |                                                |
 | `OSC 8`   | IMPLEMENTED |                                                |
+| `OSC 9`   | IMPLEMENTED | Desktop notifications and progress bar (9;4)   |
 | `OSC 10`  | IMPLEMENTED |                                                |
 | `OSC 11`  | IMPLEMENTED |                                                |
 | `OSC 12`  | IMPLEMENTED |                                                |
@@ -107,6 +108,7 @@ brevity.
 | `OSC 110` | IMPLEMENTED |                                                |
 | `OSC 111` | IMPLEMENTED |                                                |
 | `OSC 112` | IMPLEMENTED |                                                |
+| `OSC 777` | IMPLEMENTED | Desktop notifications (rxvt notify extension)  |
 
 ### DCS (Device Control String) - `ESC P`
 
diff --git a/docs/src/pages/changelog.mdx b/docs/src/pages/changelog.mdx
@@ -29,6 +29,7 @@ language: 'en'
 - **Toggle Appearance Theme**: Switch between dark and light themes at runtime via key binding (`ToggleAppearanceTheme`) or command palette (only available when adaptive theme is configured)
 - **Custom Mouse Cursor**: Configurable mouse cursor effects via `effects.custom-mouse-cursor`
 - **Trail Cursor**: Smooth spring-animated cursor trail using neovide-style physics (enabled by default via `effects.trail-cursor`)
+- **Desktop Notifications**: Support for OSC 9 (iTerm2) and OSC 777 (rxvt) terminal notifications using native platform APIs (macOS `UNUserNotificationCenter`, Linux D-Bus, Windows Toast)
 - **Force Theme**: New `force-theme` configuration property to override the system theme when using adaptive themes
 - **Quake Window Mode**: Drop-down terminal from top of screen
 - **macOS Traffic Light Positioning**: Customize position of window control buttons
diff --git a/frontends/rioterm/Cargo.toml b/frontends/rioterm/Cargo.toml
@@ -48,6 +48,7 @@ url = { workspace = true }
 smallvec = { workspace = true }
 rio-window = { workspace = true }
 lru = "0.16.0"
+rio-notifier = { workspace = true }
 
 [target.'cfg(all(not(target_os = "macos"), not(target_os = "windows")))'.dependencies]
 cpal = { version = "0.15", optional = true }
diff --git a/frontends/rioterm/src/application.rs b/frontends/rioterm/src/application.rs
@@ -138,6 +138,10 @@ impl Application<'_> {
         }
     }
 
+    fn handle_desktop_notification(&self, title: &str, body: &str) {
+        rio_notifier::send_notification(title, body);
+    }
+
     pub fn run(
         &mut self,
         event_loop: EventLoop<EventPayload>,
@@ -524,6 +528,9 @@ impl ApplicationHandler<EventPayload> for Application<'_> {
                     self.handle_audio_bell();
                 }
             }
+            RioEventType::Rio(RioEvent::DesktopNotification { title, body }) => {
+                self.handle_desktop_notification(&title, &body);
+            }
             RioEventType::Rio(RioEvent::PrepareRender(millis)) => {
                 if let Some(route) = self.router.routes.get(&window_id) {
                     let timer_id = TimerId::new(
diff --git a/misc/osx/Rio.app/Contents/Info.plist b/misc/osx/Rio.app/Contents/Info.plist
@@ -165,6 +165,51 @@
   <string>A program running inside Rio requires elevated privileges.</string>
   <key>TICapsLockLanguageSwitchCapable</key>
   <true/>
+  <key>NSHighResolutionCapable</key>
+  <true/>
+  <key>MDItemKeywords</key>
+  <string>Terminal</string>
+  <key>NSServices</key>
+  <array>
+    <dict>
+      <key>NSMenuItem</key>
+      <dict>
+        <key>default</key>
+        <string>New Rio Tab Here</string>
+      </dict>
+      <key>NSMessage</key>
+      <string>openTab</string>
+      <key>NSRequiredContext</key>
+      <dict>
+        <key>NSTextContent</key>
+        <string>FilePath</string>
+      </dict>
+      <key>NSSendTypes</key>
+      <array>
+        <string>NSFilenamesPboardType</string>
+        <string>public.plain-text</string>
+      </array>
+    </dict>
+    <dict>
+      <key>NSMenuItem</key>
+      <dict>
+        <key>default</key>
+        <string>New Rio Window Here</string>
+      </dict>
+      <key>NSMessage</key>
+      <string>openWindow</string>
+      <key>NSRequiredContext</key>
+      <dict>
+        <key>NSTextContent</key>
+        <string>FilePath</string>
+      </dict>
+      <key>NSSendTypes</key>
+      <array>
+        <string>NSFilenamesPboardType</string>
+        <string>public.plain-text</string>
+      </array>
+    </dict>
+  </array>
   <key>com.apple.security.automation.apple-events</key>
   <true/>
 </dict>
diff --git a/rio-backend/src/config/effects.rs b/rio-backend/src/config/effects.rs
@@ -1,18 +1,9 @@
 use serde::{Deserialize, Serialize};
 
-#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
+#[derive(Debug, Default, PartialEq, Clone, Serialize, Deserialize)]
 pub struct Effects {
     #[serde(default = "bool::default", rename = "custom-mouse-cursor")]
     pub custom_mouse_cursor: bool,
     #[serde(default = "bool::default", rename = "trail-cursor")]
     pub trail_cursor: bool,
 }
-
-impl Default for Effects {
-    fn default() -> Effects {
-        Effects {
-            custom_mouse_cursor: false,
-            trail_cursor: false,
-        }
-    }
-}
diff --git a/rio-backend/src/crosswords/mod.rs b/rio-backend/src/crosswords/mod.rs
@@ -2580,6 +2580,14 @@ impl<U: EventListener> Handler for Crosswords<U> {
         self.event_proxy.send_event(RioEvent::Bell, self.window_id);
     }
 
+    #[inline]
+    fn desktop_notification(&mut self, title: String, body: String) {
+        self.event_proxy.send_event(
+            RioEvent::DesktopNotification { title, body },
+            self.window_id,
+        );
+    }
+
     #[inline]
     fn substitute(&mut self) {
         warn!("[unimplemented] Substitute");
diff --git a/rio-backend/src/event/mod.rs b/rio-backend/src/event/mod.rs
@@ -144,6 +144,12 @@ pub enum RioEvent {
     /// Terminal bell ring.
     Bell,
 
+    /// Desktop notification from OSC 9 or OSC 777.
+    DesktopNotification {
+        title: String,
+        body: String,
+    },
+
     /// Shutdown request.
     Exit,
 
@@ -209,6 +215,9 @@ impl Debug for RioEvent {
             }
             RioEvent::Scroll(scroll) => write!(f, "Scroll {scroll:?}"),
             RioEvent::Bell => write!(f, "Bell"),
+            RioEvent::DesktopNotification { title, body } => {
+                write!(f, "DesktopNotification({title}, {body})")
+            }
             RioEvent::Exit => write!(f, "Exit"),
             RioEvent::Quit => write!(f, "Quit"),
             RioEvent::CloseTerminal(route) => write!(f, "CloseTerminal {route}"),
diff --git a/rio-backend/src/performer/handler.rs b/rio-backend/src/performer/handler.rs
@@ -233,6 +233,9 @@ pub trait Handler {
     /// Hopefully this is never implemented.
     fn bell(&mut self) {}
 
+    /// Desktop notification (OSC 9 / OSC 777).
+    fn desktop_notification(&mut self, _title: String, _body: String) {}
+
     /// Substitute char under cursor.
     fn substitute(&mut self) {}
 
@@ -1104,7 +1107,29 @@ impl<U: Handler, T: Timeout> copa::Perform for Performer<'_, U, T> {
                         return;
                     }
                 }
-                // OSC 9 can also be used for desktop notifications, but we don't support that yet
+                // OSC 9 desktop notification: ESC ] 9 ; <body> ST
+                if params.len() >= 2 {
+                    let body = std::str::from_utf8(params[1])
+                        .unwrap_or_default()
+                        .to_string();
+                    self.handler.desktop_notification(String::new(), body);
+                    return;
+                }
+                unhandled(params);
+            }
+
+            // OSC 777 - rxvt notification: ESC ] 777 ; notify ; <title> ; <body> ST
+            b"777" => {
+                if params.len() >= 4 && params[1] == b"notify" {
+                    let title = std::str::from_utf8(params[2])
+                        .unwrap_or_default()
+                        .to_string();
+                    let body = std::str::from_utf8(params[3])
+                        .unwrap_or_default()
+                        .to_string();
+                    self.handler.desktop_notification(title, body);
+                    return;
+                }
                 unhandled(params);
             }
 
diff --git a/rio-notifier/Cargo.toml b/rio-notifier/Cargo.toml
@@ -0,0 +1,28 @@
+[package]
+name = "rio-notifier"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+
+[target.'cfg(target_os = "macos")'.dependencies]
+objc = { workspace = true }
+objc2 = "0.5.2"
+objc2-foundation = { version = "0.2.2", features = ["NSString"] }
+objc2-user-notifications = { version = "0.2.2", features = [
+    "UNUserNotificationCenter",
+    "UNNotificationContent",
+    "UNNotificationRequest",
+    "UNNotificationTrigger",
+    "block2",
+] }
+
+[target.'cfg(all(not(target_os = "macos"), not(target_os = "windows")))'.dependencies]
+zbus = { version = "4", default-features = false, features = ["blocking"] }
+
+[target.'cfg(windows)'.dependencies]
+windows = { version = "0.58", features = [
+    "Data_Xml_Dom",
+    "UI_Notifications",
+] }
diff --git a/rio-notifier/src/lib.rs b/rio-notifier/src/lib.rs
@@ -0,0 +1,121 @@
+/// Send a desktop notification using the platform's native API.
+///
+/// - **macOS**: `UNUserNotificationCenter` (requires app bundle with identifier).
+/// - **Linux**: D-Bus `org.freedesktop.Notifications`.
+/// - **Windows**: Toast notifications via `windows` crate.
+///
+/// Spawns a background thread so the caller is never blocked.
+pub fn send_notification(title: &str, body: &str) {
+    let title = if title.is_empty() {
+        "Rio".to_string()
+    } else {
+        title.to_string()
+    };
+    let body = body.to_string();
+
+    std::thread::spawn(move || {
+        platform::notify(&title, &body);
+    });
+}
+
+#[cfg(target_os = "macos")]
+mod platform {
+    use objc::runtime::Object;
+    use objc::{class, msg_send, sel, sel_impl};
+    use objc2_foundation::NSString;
+    use objc2_user_notifications::{
+        UNMutableNotificationContent, UNNotificationRequest, UNUserNotificationCenter,
+    };
+
+    pub fn notify(title: &str, body: &str) {
+        unsafe {
+            // UNUserNotificationCenter crashes if the app has no bundle
+            // identifier (e.g. cargo run). Guard like Kitty does.
+            let bundle: *mut Object = msg_send![class!(NSBundle), mainBundle];
+            if bundle.is_null() {
+                return;
+            }
+            let bundle_id: *mut Object = msg_send![bundle, bundleIdentifier];
+            if bundle_id.is_null() {
+                return;
+            }
+
+            let center = UNUserNotificationCenter::currentNotificationCenter();
+
+            let content = UNMutableNotificationContent::new();
+            content.setTitle(&NSString::from_str(title));
+            content.setBody(&NSString::from_str(body));
+
+            let identifier = NSString::from_str("rio-notification");
+            let request = UNNotificationRequest::requestWithIdentifier_content_trigger(
+                &identifier,
+                &content,
+                None,
+            );
+
+            center.addNotificationRequest_withCompletionHandler(&request, None);
+        }
+    }
+}
+
+#[cfg(all(not(target_os = "macos"), not(target_os = "windows")))]
+mod platform {
+    use std::collections::HashMap;
+
+    pub fn notify(title: &str, body: &str) {
+        let Ok(connection) = zbus::blocking::Connection::session() else {
+            return;
+        };
+        let Ok(proxy) = zbus::blocking::Proxy::new(
+            &connection,
+            "org.freedesktop.Notifications",
+            "/org/freedesktop/Notifications",
+            "org.freedesktop.Notifications",
+        ) else {
+            return;
+        };
+        let hints: HashMap<&str, zbus::zvariant::Value<'_>> = HashMap::new();
+        let _: Result<u32, _> = proxy.call(
+            "Notify",
+            &(
+                "Rio",          // app_name
+                0u32,           // replaces_id
+                "rio",          // app_icon
+                title,          // summary
+                body,           // body
+                &[] as &[&str], // actions
+                &hints,         // hints
+                -1i32,          // expire_timeout
+            ),
+        );
+    }
+}
+
+#[cfg(target_os = "windows")]
+mod platform {
+    pub fn notify(title: &str, body: &str) {
+        use windows::core::HSTRING;
+        use windows::Data::Xml::Dom::XmlDocument;
+        use windows::UI::Notifications::{ToastNotification, ToastNotificationManager};
+
+        let Ok(xml) = XmlDocument::new() else {
+            return;
+        };
+        let toast_xml = format!(
+            r#"<toast><visual><binding template="ToastGeneric"><text>{}</text><text>{}</text></binding></visual></toast>"#,
+            title, body,
+        );
+        if xml.LoadXml(&HSTRING::from(&toast_xml)).is_err() {
+            return;
+        }
+        let Ok(toast) = ToastNotification::CreateToastNotification(&xml) else {
+            return;
+        };
+        let Ok(notifier) =
+            ToastNotificationManager::CreateToastNotifierWithId(&HSTRING::from("Rio"))
+        else {
+            return;
+        };
+        let _ = notifier.Show(&toast);
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -138,6 +138,10 @@ impl Application<'_> {`
`138`	`138`	`}`
`139`	`139`	`}`
`140`	`140`
	`141`	`+ fn handle_desktop_notification(&self, title: &str, body: &str) {`
	`142`	`+ rio_notifier::send_notification(title, body);`
	`143`	`+ }`
	`144`	`+`
`141`	`145`	`pub fn run(`
`142`	`146`	`&mut self,`
`143`	`147`	`event_loop: EventLoop<EventPayload>,`
`@@ -524,6 +528,9 @@ impl ApplicationHandler<EventPayload> for Application<'_> {`
`524`	`528`	`self.handle_audio_bell();`
`525`	`529`	`}`
`526`	`530`	`}`
	`531`	`+ RioEventType::Rio(RioEvent::DesktopNotification { title, body }) => {`
	`532`	`+ self.handle_desktop_notification(&title, &body);`
	`533`	`+ }`
`527`	`534`	`RioEventType::Rio(RioEvent::PrepareRender(millis)) => {`
`528`	`535`	`if let Some(route) = self.router.routes.get(&window_id) {`
`529`	`536`	`let timer_id = TimerId::new(`