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//   - OSC99Backend: Uses the OSC 99 Desktop Notification protocol, supported by
 6//     modern terminals like kitty, wezterm, and ghostty. Supports rich notifications
 7//     with title, body, icons, and actions.
 8//   - OSC777Backend: Uses the OSC 777 urxvt notification extension, widely supported
 9//     but less capable (title and body only). Used as a fallback for SSH sessions.
10//   - NoopBackend: A no-op backend that silently discards notifications.
11//
12// Backend selection is based on terminal capabilities and environment:
13//   - SSH sessions prefer OSC 99 if available, falling back to OSC 777
14//   - Local sessions use native OS notifications
15//   - If focus events are not supported, notifications are disabled (NoopBackend)
16package notification
17
18import tea "charm.land/bubbletea/v2"
19
20// Notification represents a desktop notification request.
21type Notification struct {
22	Title   string
23	Message string
24}
25
26// Backend defines the interface for sending desktop notifications.
27// Implementations return a tea.Cmd that performs the notification, allowing
28// each backend to choose between synchronous (native OS) and asynchronous
29// (terminal escape sequences) delivery. Policy decisions (config checks,
30// focus state) are handled by the caller.
31type Backend interface {
32	Send(n Notification) tea.Cmd
33}