1// Package notification provides desktop notification support for the UI.
 2//
 3// This package supports multiple notification backends:
 4//   - NativeBackend: Uses the native OS notification system (macOS, Windows, Linux)
 5//   - OSCBackend: Uses OSC escape sequences with automatic protocol detection.
 6//     Prefers OSC 99 (modern standard with rich notifications) if supported,
 7//     falling back to OSC 777 (urxvt extension, widely supported). Used for SSH sessions.
 8//   - BellBackend: Triggers the terminal bell character (\x07), causing an audible
 9//     beep or visual flash. Works in virtually all terminals but provides no message text.
10//   - NoopBackend: A no-op backend that silently discards notifications. Used when
11//     notifications are disabled or no suitable backend is available.
12//
13// Backend selection is based on terminal capabilities, environment, and user config:
14//   - Users can explicitly set notification_style in crush.json (auto/native/osc/bell/disabled)
15//   - Auto mode: SSH sessions use OSC backend (auto-detects OSC 99 vs 777)
16//   - Auto mode: Local sessions use native OS notifications
17//   - If focus events are not supported in local sessions, notifications are disabled (NoopBackend)
18package notification
19
20import tea "charm.land/bubbletea/v2"
21
22// Notification represents a desktop notification request.
23type Notification struct {
24	Title   string
25	Message string
26}
27
28// Backend defines the interface for sending desktop notifications.
29// Implementations return a tea.Cmd that performs the notification, allowing
30// each backend to choose between synchronous (native OS) and asynchronous
31// (terminal escape sequences) delivery. Policy decisions (config checks,
32// focus state) are handled by the caller.
33type Backend interface {
34	Send(n Notification) tea.Cmd
35}