quadraui 0.1.0

//! macOS implementation of [`quadraui::PlatformServices`].
//!
//! - **Clipboard** → `arboard` (NSPasteboard under the hood; the sync
//!   API matches the [`Clipboard`] trait exactly, and shares one
//!   implementation with the TUI and GTK backends).
//! - **File dialogs** → `NSOpenPanel` / `NSSavePanel`, sync
//!   `runModal`. Apps must invoke these from event handlers running
//!   on the main thread (the `MacBackend` run loop guarantees this).
//! - **Notifications** → `osascript -e 'display notification ...'`.
//!   `UNUserNotificationCenter` requires a bundled `.app` with
//!   `CFBundleIdentifier` and user authorization, neither of which
//!   suit an unbundled CLI host. The osascript route works for both
//!   bundled and unbundled hosts.
//!
//!   Issue #955 extended [`Notification`] with `icon`/`actions`/`silent`/
//!   `tag`. Only `silent` has anywhere to go on the `osascript` path —
//!   [`Notification::is_silent`] maps to whether the `display
//!   notification` command's `sound name` clause is present at all (see
//!   [`Self::send_notification`]'s own doc; counterintuitively, *no*
//!   clause means *no* sound, so `silent: false`, the default, is what
//!   adds one). `icon`, `actions`, and `tag` are silently dropped:
//!   `display notification` has no icon parameter (it's always
//!   Script Editor's), no button/action parameter, and no click-through
//!   channel to report an activation back through at all — GTK is the
//!   only backend [`crate::UiEvent::NotificationActivated`] fires on
//!   today (see that variant's own doc). A real fix needs
//!   `UNUserNotificationCenter` (`objc2-user-notifications`) behind the
//!   bundled-`.app` check this module doesn't have a way to perform
//!   without a live macOS host to build/verify it against — tracked as
//!   follow-up, not silently faked; `osascript` stays the fallback for
//!   whichever host lands it, matching this issue's own "keep osascript
//!   as the unbundled fallback" note. The AppleScript-building helpers
//!   ([`crate::desktop::display_notification_script`]/
//!   `crate::desktop::applescript_escape`) moved into `crate::desktop`
//!   by issue #1092, which gave `tui::services` a second `osascript`
//!   call site (TUI's own macOS notification fallback leg) needing the
//!   identical logic.
//! - **`open_url`/`open_url_result`** → `open <url>` via
//!   [`crate::desktop::open_with_default`] (issue #1087) — the
//!   crate-wide opener shared with `tui::services`/`win::services`.
//!   Equivalent to `NSWorkspace.open(_:)` without needing AppKit
//!   initialisation. `open_url_result` overrides the trait's `Ok(())`
//!   default and reports whether `open` genuinely spawned instead of
//!   `open_url`'s discarded outcome.
//! - **`shell.*` parity (issue #956)** → `reveal_in_file_manager` uses
//!   `NSWorkspace::activateFileViewerSelectingURLs`; `open_path` reuses
//!   the same `open_with_default` call `open_url_result` makes; `move_to_trash`
//!   delegates to [`crate::desktop::move_to_trash`] — the cross-platform
//!   `trash` crate, not a hand-rolled `NSFileManager
//!   -trashItemAtURL:resultingItemURL:error:` — see that function's doc
//!   for why every backend shares it; `beep` is the bare `NSBeep` C
//!   function.
//! - **Displays (issue #959)** → `displays` reads `NSScreen::screens()`;
//!   `cursor_screen_point` reads `NSEvent::mouseLocation()`. See each
//!   method's own doc for the exact field mapping and coordinate-system
//!   note.

use std::cell::RefCell;
use std::path::{Path, PathBuf};
use std::process::Command;

use objc2_app_kit::{
    NSAlert, NSAlertFirstButtonReturn, NSAlertStyle, NSApplication, NSBeep, NSColor, NSColorSpace,
    NSEvent, NSOpenPanel, NSSavePanel, NSScreen, NSWorkspace,
};
use objc2_foundation::{MainThreadMarker, NSArray, NSRect, NSString, NSURL};

use crate::backend::{
    BackendError, Clipboard, Display, FileDialogOptions, MessageDialogButton, MessageDialogChoice,
    MessageDialogOptions, Notification, RgbaImage, ServiceResult, SystemTheme,
};
use crate::event::{Point, Rect};
use crate::primitives::dialog::DialogSeverity;
use crate::types::Color;
use crate::PlatformServices;

/// `NSModalResponseOK` — the user clicked Open / Save.
const NS_MODAL_RESPONSE_OK: isize = 1;

/// macOS platform services backed by AppKit + `arboard` + shell-out
/// helpers. Constructed by [`crate::macos::MacBackend::new`] and
/// exposed through [`crate::Backend::services`].
pub struct MacPlatformServices {
    clipboard: MacClipboard,
}

impl MacPlatformServices {
    pub fn new() -> Self {
        Self {
            clipboard: MacClipboard::new(),
        }
    }
}

impl Default for MacPlatformServices {
    fn default() -> Self {
        Self::new()
    }
}

impl PlatformServices for MacPlatformServices {
    fn clipboard(&self) -> &dyn Clipboard {
        &self.clipboard
    }

    fn show_file_open_dialog(&self, opts: FileDialogOptions) -> Option<PathBuf> {
        let mtm = MainThreadMarker::new()
            .expect("show_file_open_dialog must be called from the main thread");
        // SAFETY: AppKit panels are constructed and driven exclusively
        // on the main thread; MainThreadMarker enforces that.
        unsafe {
            let panel = NSOpenPanel::openPanel(mtm);
            panel.setCanChooseFiles(true);
            panel.setCanChooseDirectories(false);
            configure_panel(&panel, &opts);
            if panel.runModal() != NS_MODAL_RESPONSE_OK {
                return None;
            }
            url_to_path(panel.URL().as_deref())
        }
    }

    fn show_file_save_dialog(&self, opts: FileDialogOptions) -> Option<PathBuf> {
        let mtm = MainThreadMarker::new()
            .expect("show_file_save_dialog must be called from the main thread");
        // SAFETY: same as `show_file_open_dialog` above.
        unsafe {
            let panel = NSSavePanel::savePanel(mtm);
            configure_panel(&panel, &opts);
            if let Some(ref name) = opts.initial_filename {
                panel.setNameFieldStringValue(&NSString::from_str(name));
            }
            if panel.runModal() != NS_MODAL_RESPONSE_OK {
                return None;
            }
            url_to_path(panel.URL().as_deref())
        }
    }

    /// quadraui#935: a two-line variant of `show_file_open_dialog` above —
    /// the same `NSOpenPanel`, with the choose-directories/choose-files
    /// pair flipped.
    fn show_folder_open_dialog(&self, opts: FileDialogOptions) -> Option<PathBuf> {
        let mtm = MainThreadMarker::new()
            .expect("show_folder_open_dialog must be called from the main thread");
        // SAFETY: same as `show_file_open_dialog` above.
        unsafe {
            let panel = NSOpenPanel::openPanel(mtm);
            panel.setCanChooseFiles(false);
            panel.setCanChooseDirectories(true);
            configure_panel(&panel, &opts);
            if panel.runModal() != NS_MODAL_RESPONSE_OK {
                return None;
            }
            url_to_path(panel.URL().as_deref())
        }
    }

    /// `NSAlert` (quadraui#936) — the macOS half of the native-dialog gap
    /// #666 left unfiled after shipping the GTK4 `AlertDialog`
    /// implementation (`gtk::services::GtkPlatformServices::show_message_dialog`,
    /// this method's closest sibling). `native_button_order` picks which
    /// order to add buttons in (macOS convention: most-prominent /
    /// default button added first, since `NSAlert` lays out the
    /// first-added button trailing/rightmost — see `addButtonWithTitle:`'s
    /// docs); `severity_to_alert_style` maps `DialogSeverity` onto
    /// `NSAlertStyle`. Both are free functions below so the mapping is
    /// unit-testable without presenting anything (this issue's
    /// acceptance bar) — the modal `runModal()` call itself still needs a
    /// human on a real Mac.
    fn show_message_dialog(&self, opts: MessageDialogOptions) -> Option<MessageDialogChoice> {
        // Graceful degrade rather than `expect`'s hard panic (unlike the
        // file dialogs above): quadraui#926's `install_menu_bar` twin.
        // Rust's default test harness spawns a fresh OS thread per
        // `#[test]` fn, so a test that reaches this method off the main
        // thread must see `None` — the same "no native alert facility"
        // shape callers already get from `BackendCaps::native_dialogs ==
        // false` — instead of aborting the whole test process.
        // `NSAlert`'s methods below (unlike `NSOpenPanel`/`NSSavePanel`'s
        // `URL()` and this module's own `url_to_path`) are all safe
        // AppKit wrappers — `MainThreadMarker` still gates *construction*
        // (`NSAlert::new` takes it by value), which is what actually
        // enforces the main-thread requirement here.
        let mtm = MainThreadMarker::new()?;
        let order = native_button_order(&opts.buttons);
        let alert = NSAlert::new(mtm);
        alert.setMessageText(&NSString::from_str(&opts.title));
        alert.setInformativeText(&NSString::from_str(&opts.body));
        alert.setAlertStyle(severity_to_alert_style(opts.severity));
        for &i in &order {
            let button = &opts.buttons[i];
            let ns_button = alert.addButtonWithTitle(&NSString::from_str(&button.label));
            if let Some(key) = key_equivalent_for_button(button) {
                ns_button.setKeyEquivalent(&NSString::from_str(key));
            }
        }
        let response = alert.runModal();
        let idx = usize::try_from(response - NSAlertFirstButtonReturn).ok()?;
        let orig = *order.get(idx)?;
        Some(opts.buttons[orig].id.clone())
    }

    /// See the module doc's "Notifications" section for why only
    /// `n.is_silent()` (of #955's four new `Notification` fields) has
    /// anywhere to go here. [`crate::desktop::display_notification_script`]
    /// is the pure half, split out the same way `hig_button_order`/
    /// `system_theme_from_gtk_settings` are in their own backends' sibling
    /// modules — so the AppleScript text itself is unit-testable without
    /// a live mac; only the `Command::spawn` below needs one. Shared with
    /// `tui::services` since issue #1092, which needed the identical
    /// `osascript` call for its own macOS notification fallback leg.
    fn send_notification(&self, n: Notification) {
        let script = crate::desktop::display_notification_script(&n.title, &n.body, n.is_silent());
        let _ = Command::new("osascript").arg("-e").arg(&script).spawn();
    }

    fn open_url(&self, url: &str) {
        let _ = self.open_url_result(url);
    }

    /// Fallible twin of [`Self::open_url`] (issue #1087), via
    /// [`crate::desktop::open_with_default`] — reports whether `open`
    /// genuinely spawned instead of `open_url`'s discarded outcome.
    /// Before this override, `open_url_result` fell to
    /// [`crate::backend::PlatformServices::open_url_result`]'s default
    /// (`open_url` then always `Ok(())`), so a `Command::spawn` failure
    /// (e.g. `open` missing from `$PATH`) was silently reported as
    /// success.
    fn open_url_result(&self, url: &str) -> ServiceResult<()> {
        crate::desktop::open_with_default(std::ffi::OsStr::new(url))
    }

    /// `NSWorkspace::activateFileViewerSelectingURLs` on `path`'s
    /// `file://` URL (issue #956) — "Reveal in Finder." `path.is_dir()`
    /// decides `fileURLWithPath:isDirectory:`'s bool the same way
    /// `configure_panel`'s directory-URL construction would need to, were
    /// it not always `true` there (a directory *chooser*'s initial
    /// folder); here `path` can be either a file or a directory, so this
    /// checks rather than assuming.
    fn reveal_in_file_manager(&self, path: &Path) -> ServiceResult<()> {
        let Some(path_str) = path.to_str() else {
            return Err(BackendError::PlatformFailure {
                context: "reveal_in_file_manager: path is not valid UTF-8".to_string(),
            });
        };
        let url = NSURL::fileURLWithPath_isDirectory(&NSString::from_str(path_str), path.is_dir());
        let urls = NSArray::from_retained_slice(&[url]);
        NSWorkspace::sharedWorkspace().activateFileViewerSelectingURLs(&urls);
        Ok(())
    }

    /// `open <path>` (issue #956) via [`crate::desktop::open_with_default`]
    /// (issue #1087) — the same call [`Self::open_url_result`] makes;
    /// macOS's `open(1)` already accepts a filesystem path exactly as
    /// readily as a URL (it's the command-line front end to
    /// `NSWorkspace.open(_:)`), so there is nothing path-specific to add
    /// beyond handing it a path instead of a URL string.
    fn open_path(&self, path: &Path) -> ServiceResult<()> {
        crate::desktop::open_with_default(path.as_os_str())
    }

    /// [`crate::desktop::move_to_trash`] (issue #956) — see that
    /// function's doc for why every backend, macOS included, shares this
    /// one `trash`-crate-backed implementation rather than hand-rolling
    /// `NSFileManager::trashItemAtURL_resultingItemURL_error` here.
    fn move_to_trash(&self, path: &Path) -> ServiceResult<()> {
        crate::desktop::move_to_trash(path)
    }

    /// `NSBeep` (issue #956) — a bare AppKit C function, not a method on
    /// any object, so unlike every other AppKit call in this module it
    /// needs no `MainThreadMarker`/receiver of its own.
    fn beep(&self) -> ServiceResult<()> {
        NSBeep();
        Ok(())
    }

    /// `NSApp.effectiveAppearance` for light/dark,
    /// `NSWorkspace::accessibilityDisplayShouldIncreaseContrast` for high
    /// contrast, `NSColor::controlAccentColor` for the accent colour
    /// (quadraui#952). Reads `effectiveAppearance().name()` and checks it
    /// for `"Dark"` rather than building an `NSArray` and calling
    /// `NSAppearance::bestMatchFromAppearancesWithNames` (the issue's
    /// suggested API, and the one apps *drawing* per-appearance content
    /// should reach for) — for a one-shot query like this, the name
    /// itself already carries the answer, and every system appearance
    /// name (`NSAppearanceNameDarkAqua`, and both
    /// `NSAppearanceNameAccessibilityHighContrast*Dark*` variants)
    /// contains the substring unambiguously.
    fn system_theme(&self) -> ServiceResult<SystemTheme> {
        let mtm = MainThreadMarker::new().ok_or(BackendError::Unsupported)?;
        let appearance_name = NSApplication::sharedApplication(mtm)
            .effectiveAppearance()
            .name()
            .to_string();
        let high_contrast =
            NSWorkspace::sharedWorkspace().accessibilityDisplayShouldIncreaseContrast();
        Ok(system_theme_from_mac_appearance(
            &appearance_name,
            high_contrast,
            mac_accent_color(),
        ))
    }

    /// `NSScreen::screens()` (issue #959) — `frame()`/`visibleFrame()` map
    /// straight to [`Display::bounds`]/[`Display::work_area`], and
    /// `backingScaleFactor()` to [`Display::scale`]. `screens()[0]` is
    /// always the screen containing the menu bar (documented AppKit
    /// behaviour) — used as [`Display::primary`], distinct from
    /// `NSScreen::mainScreen()`, which tracks the *key window*'s screen,
    /// not the platform's primary one.
    ///
    /// `Err(BackendError::Unsupported)` only off the main thread (no
    /// `MainThreadMarker`) — same guard [`Self::system_theme`] uses.
    fn displays(&self) -> ServiceResult<Vec<Display>> {
        let mtm = MainThreadMarker::new().ok_or(BackendError::Unsupported)?;
        let screens = NSScreen::screens(mtm);
        let count = screens.count();
        let mut out = Vec::with_capacity(count);
        for i in 0..count {
            let screen = screens.objectAtIndex(i);
            out.push(Display {
                bounds: rect_from_ns_rect(screen.frame()),
                work_area: rect_from_ns_rect(screen.visibleFrame()),
                scale: screen.backingScaleFactor() as f32,
                primary: i == 0,
            });
        }
        Ok(out)
    }

    /// `NSEvent::mouseLocation()` (issue #959) — a bare AppKit class
    /// method, like [`Self::beep`]'s `NSBeep`, needing no
    /// `MainThreadMarker`/receiver of its own. Returns coordinates in the
    /// same bottom-left-origin, y-up screen space [`Self::displays`]'s
    /// `bounds`/`work_area` do — both come from the same `NSScreen`/
    /// `NSEvent` global-coordinate system, so the two stay directly
    /// comparable (testing which [`Display`] contains the cursor is a
    /// plain point-in-rect check, no coordinate flip needed).
    fn cursor_screen_point(&self) -> ServiceResult<Point> {
        let p = NSEvent::mouseLocation();
        Ok(Point::new(p.x as f32, p.y as f32))
    }

    fn platform_name(&self) -> &'static str {
        "macos"
    }
}

/// Convert an AppKit `NSRect` (`CGRect`: `f64` origin + size) to
/// [`Rect`]'s `f32` shape — shared by every [`Display`] field
/// [`MacPlatformServices::displays`] reads off `NSScreen`.
fn rect_from_ns_rect(r: NSRect) -> Rect {
    Rect::new(
        r.origin.x as f32,
        r.origin.y as f32,
        r.size.width as f32,
        r.size.height as f32,
    )
}

/// Pure mapping from an `NSAppearance` name plus the two other
/// already-read signals to [`SystemTheme`] — split out from
/// `system_theme` so the name-matching logic is unit-testable without a
/// live `NSApplication` (mirrors this module's `native_button_order`/
/// `severity_to_alert_style`-style helpers).
fn system_theme_from_mac_appearance(
    appearance_name: &str,
    high_contrast: bool,
    accent: Option<Color>,
) -> SystemTheme {
    SystemTheme {
        dark: appearance_name.contains("Dark"),
        accent,
        high_contrast,
    }
}

/// `NSColor::controlAccentColor`'s RGB components, converted to
/// [`Color`]. `getRed:green:blue:alpha:` raises `NSInvalidArgumentException`
/// if the receiver isn't already in an RGB-compatible colour space, and an
/// ObjC exception unwinding across this Rust/FFI boundary is UB (likely an
/// abort) — Apple's docs don't guarantee `controlAccentColor` (a dynamic,
/// catalog-backed system colour) is pre-resolved to RGB in every runtime
/// context, so this defensively runs it through `colorUsingColorSpace:`
/// first rather than assuming it. `colorUsingColorSpace:` returns `None`
/// only when the conversion itself is impossible (no live colour-management
/// pipeline), which — like the rest of this crate's platform-services
/// layer — is treated as "feature unavailable" rather than an error.
fn mac_accent_color() -> Option<Color> {
    let color = NSColor::controlAccentColor();
    let rgb_color = color.colorUsingColorSpace(&NSColorSpace::sRGBColorSpace())?;
    let (mut r, mut g, mut b, mut a) = (0.0_f64, 0.0_f64, 0.0_f64, 0.0_f64);
    // SAFETY: four valid, non-null `f64` out-pointers, matching
    // `getRed:green:blue:alpha:`'s documented safety requirement. Calling
    // it on `rgb_color` rather than `color` is what makes this safe from
    // the ObjC-exception hazard described above: `colorUsingColorSpace:`
    // above already guarantees an RGB-compatible receiver.
    unsafe {
        rgb_color.getRed_green_blue_alpha(&mut r, &mut g, &mut b, &mut a);
    }
    Some(Color::rgba(
        unit_to_u8(r),
        unit_to_u8(g),
        unit_to_u8(b),
        unit_to_u8(a),
    ))
}

/// Convert a `0.0..=1.0` colour component to a `0..=255` byte, clamping
/// out-of-range input rather than wrapping/panicking (`as u8` on a
/// negative or `NaN` float is technically defined since Rust 1.45's
/// saturating float casts, but `clamp` here makes the intent explicit
/// rather than relying on that cast behaviour).
fn unit_to_u8(component: f64) -> u8 {
    (component.clamp(0.0, 1.0) * 255.0).round() as u8
}

/// Apply common options (message, initial directory, file-type filters)
/// to an `NSSavePanel` — also covers `NSOpenPanel`, which inherits all
/// of these setters from `NSSavePanel`.
///
/// # Safety
///
/// Must be called from the main thread; `panel` must be a valid panel
/// retrieved on this same thread via `openPanel:` / `savePanel:`.
unsafe fn configure_panel(panel: &NSSavePanel, opts: &FileDialogOptions) {
    if let Some(ref title) = opts.title {
        panel.setMessage(Some(&NSString::from_str(title)));
    }
    if let Some(ref dir) = opts.initial_dir {
        if let Some(dir_str) = dir.to_str() {
            let url = NSURL::fileURLWithPath_isDirectory(&NSString::from_str(dir_str), true);
            panel.setDirectoryURL(Some(&url));
        }
    }
    let exts: Vec<_> = opts
        .filters
        .iter()
        .flat_map(|(_, e)| e.iter())
        .map(|ext| NSString::from_str(ext))
        .collect();
    if !exts.is_empty() {
        // `NSArray::from_slice` requires `T: IsRetainable`, which
        // NSString doesn't satisfy (it has an `NSMutableString`
        // subclass). `from_retained_slice` takes already-`Retained`
        // handles and sidesteps that bound — replaces objc2-foundation
        // 0.2's `from_vec` (renamed/reshaped in 0.3, #796; same "already
        // retained" semantics, slice instead of by-value `Vec`).
        let arr = NSArray::from_retained_slice(&exts);
        // `setAllowedFileTypes:` is deprecated in favour of
        // `setAllowedContentTypes:` (UTType), but that requires the
        // UniformTypeIdentifiers framework which objc2 doesn't yet
        // wrap. The legacy API still works on macOS 11–15.
        #[allow(deprecated)]
        panel.setAllowedFileTypes(Some(&arr));
    }
}

/// Convert an `NSURL` back to a Rust `PathBuf`. Returns `None` if the
/// URL is missing or non-file-scheme.
///
/// # Safety
///
/// `url` must be a valid `NSURL` retrieved on the main thread.
unsafe fn url_to_path(url: Option<&NSURL>) -> Option<PathBuf> {
    let path = url?.path()?;
    Some(PathBuf::from(path.to_string()))
}

// `applescript_escape`/`display_notification_script` used to live here as
// this module's own private helpers (issue #955). Issue #1092 gave
// `tui::services` a second `osascript` call site — the TUI degrade's
// macOS notification fallback leg — that needed byte-for-byte the same
// AppleScript-building logic, so both are now shared out of
// `crate::desktop` (see that module's "display_notification_script"
// section) instead of `tui::services` growing its own copy.

/// Order `buttons` for `NSAlert::addButtonWithTitle:` (quadraui#936):
/// `NSAlert` lays out the first-added button trailing/rightmost (its own
/// docs: "arranged from trailing-to-leading edge... Buttons should be
/// added from most-to-least prominent"), so the default/primary button
/// goes first, any cancel button goes second, and everything else keeps
/// its declared relative order after that. Returns indices into
/// `buttons` — `show_message_dialog` maps `runModal`'s chosen index back
/// through this same slice to recover the original
/// [`MessageDialogButton::id`], mirroring
/// `gtk::services::hig_button_order`'s job for the GTK4 `AlertDialog`.
///
/// A button with both `is_default` and `is_cancel` set (a single-button
/// "OK" alert) lands in the default slot here — `show_message_dialog`
/// also binds it to Return, not Escape, when assigning the key
/// equivalent (see that method's doc comment), so which bucket this
/// function sorts it into only affects visual position, not behaviour.
fn native_button_order(buttons: &[MessageDialogButton]) -> Vec<usize> {
    let mut default_idx = None;
    let mut cancel_idx = None;
    let mut rest = Vec::new();
    for (i, b) in buttons.iter().enumerate() {
        if b.is_default && default_idx.is_none() {
            default_idx = Some(i);
        } else if b.is_cancel && cancel_idx.is_none() {
            cancel_idx = Some(i);
        } else {
            rest.push(i);
        }
    }
    let mut order = Vec::with_capacity(buttons.len());
    order.extend(default_idx);
    order.extend(cancel_idx);
    order.extend(rest);
    order
}

/// Pick the `NSButton::setKeyEquivalent` string for `button`, or `None`
/// to leave `NSAlert`'s own default untouched (quadraui#936).
///
/// `setKeyEquivalent` only ever holds one string, so a button that is
/// both `is_default` and `is_cancel` (a single-button "OK" alert — the
/// most common message-dialog shape in this codebase) can only be bound
/// to one of Return/Escape here. `is_default` wins: `NSAlert`'s own
/// native default (its docs: "By default, the first button has a key
/// equivalent of Return...") already gives such a button Return for
/// free when `setKeyEquivalent` is never called, and both sibling
/// backends bind *both* keys to this button —
/// `gtk::services::hig_button_order`'s doc points `set_cancel_button`
/// *and* `set_default_button` at it, and
/// `win::services::assign_button_ids` gives it `TASKDIALOG_IDCANCEL`
/// *and* looks it up as `pszDefaultButton` — so Return is the one to
/// keep when only one of the two can survive on this platform.
fn key_equivalent_for_button(button: &MessageDialogButton) -> Option<&'static str> {
    if button.is_default {
        Some("\r")
    } else if button.is_cancel {
        Some("\u{1b}")
    } else {
        None
    }
}

/// Map [`DialogSeverity`] onto `NSAlertStyle` (quadraui#936) — shares
/// `win::services::win_show_message_dialog`'s `icon` match's "`Question`
/// has no dedicated native icon" gap: `NSAlertStyle` (like
/// `TaskDialogIndirect`'s icon set) has no question-mark style, so
/// `Question` degrades to a neutral style, matching [`DialogSeverity`]'s
/// own "`None` = neutral" doc. Unlike the Windows arm, though,
/// `NSAlertStyle` also has no dedicated "no icon" state the way
/// `PCWSTR::null()` gives Windows one, so `Info` is folded into the same
/// `Informational` bucket as `Question`/`None` here rather than getting
/// its own arm the way `TD_INFORMATION_ICON` does on Windows.
fn severity_to_alert_style(severity: Option<DialogSeverity>) -> NSAlertStyle {
    match severity {
        Some(DialogSeverity::Error) => NSAlertStyle::Critical,
        Some(DialogSeverity::Warning) => NSAlertStyle::Warning,
        Some(DialogSeverity::Info) | Some(DialogSeverity::Question) | None => {
            NSAlertStyle::Informational
        }
    }
}

/// System clipboard via `arboard` (NSPasteboard under the hood on
/// macOS). Held for the lifetime of `MacPlatformServices` so the
/// pasteboard handle outlives any cached connection state.
pub struct MacClipboard {
    inner: RefCell<Option<arboard::Clipboard>>,
}

impl MacClipboard {
    fn new() -> Self {
        Self {
            inner: RefCell::new(arboard::Clipboard::new().ok()),
        }
    }
}

/// Context string used when there is no live `arboard::Clipboard` handle
/// at all (construction failed — e.g. no `WindowServer` session) rather
/// than a native call on a real handle failing. Shared by
/// [`MacClipboard`]'s `Clipboard` methods below.
const NO_PASTEBOARD_CONTEXT: &str = "arboard::Clipboard::new (no NSPasteboard session)";

/// Map an `arboard::Error` from a named native call into a
/// [`BackendError::PlatformFailure`] (issue #954) — the one
/// implementation shared with `gtk::services` (issue #1087); see
/// [`crate::desktop::map_arboard_error`]'s own doc for the full
/// rationale.
use crate::desktop::map_arboard_error;

impl Clipboard for MacClipboard {
    fn read_text(&self) -> Option<String> {
        self.inner.borrow_mut().as_mut()?.get_text().ok()
    }

    fn write_text(&self, text: &str) {
        if let Some(cb) = self.inner.borrow_mut().as_mut() {
            let _ = cb.set_text(text);
        }
    }

    /// Decoded RGBA pixels via `arboard::Clipboard::get_image` (issue
    /// #954) — the `image-data`-featured leg of the same `arboard`
    /// handle `read_text`/`write_text` already share.
    fn read_image(&self) -> ServiceResult<RgbaImage> {
        let mut inner = self.inner.borrow_mut();
        let cb = inner.as_mut().ok_or(BackendError::PlatformFailure {
            context: NO_PASTEBOARD_CONTEXT.to_string(),
        })?;
        let img = cb
            .get_image()
            .map_err(|e| map_arboard_error("arboard::get_image", e))?;
        Ok(RgbaImage {
            width: img.width as u32,
            height: img.height as u32,
            pixels: img.bytes.into_owned(),
        })
    }

    fn write_image(&self, image: &RgbaImage) -> ServiceResult<()> {
        let mut inner = self.inner.borrow_mut();
        let cb = inner.as_mut().ok_or(BackendError::PlatformFailure {
            context: NO_PASTEBOARD_CONTEXT.to_string(),
        })?;
        let data = arboard::ImageData {
            width: image.width as usize,
            height: image.height as usize,
            bytes: std::borrow::Cow::Borrowed(&image.pixels),
        };
        cb.set_image(data)
            .map_err(|e| map_arboard_error("arboard::set_image", e))
    }

    fn write_html(&self, html: &str, alt_text: &str) -> ServiceResult<()> {
        let mut inner = self.inner.borrow_mut();
        let cb = inner.as_mut().ok_or(BackendError::PlatformFailure {
            context: NO_PASTEBOARD_CONTEXT.to_string(),
        })?;
        cb.set_html(html, Some(alt_text))
            .map_err(|e| map_arboard_error("arboard::set_html", e))
    }

    fn read_file_list(&self) -> ServiceResult<Vec<PathBuf>> {
        let mut inner = self.inner.borrow_mut();
        let cb = inner.as_mut().ok_or(BackendError::PlatformFailure {
            context: NO_PASTEBOARD_CONTEXT.to_string(),
        })?;
        cb.get()
            .file_list()
            .map_err(|e| map_arboard_error("arboard::get().file_list()", e))
    }

    fn clear(&self) -> ServiceResult<()> {
        let mut inner = self.inner.borrow_mut();
        let cb = inner.as_mut().ok_or(BackendError::PlatformFailure {
            context: NO_PASTEBOARD_CONTEXT.to_string(),
        })?;
        cb.clear()
            .map_err(|e| map_arboard_error("arboard::clear", e))
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn platform_name_is_macos() {
        let svc = MacPlatformServices::new();
        assert_eq!(svc.platform_name(), "macos");
    }

    /// `NSBeep` (issue #956) — a bare AppKit C function with no receiver
    /// and no window/UI object graph to touch, so unlike
    /// `show_message_dialog`'s `NSAlert::runModal` above this is safe to
    /// call from a spawned test thread without a `MainThreadMarker`.
    /// `reveal_in_file_manager`/`open_path` aren't covered by an
    /// automated test here for the same reason `open_url` never has been
    /// in this module: both have a real, visible side effect (a Finder
    /// window opens; the default app for a file launches) that a test
    /// suite shouldn't trigger — manual smoke-testing only, same posture
    /// as `open_url`. `move_to_trash` is covered once, backend-neutrally,
    /// by `crate::desktop`'s own real round-trip test.
    #[test]
    fn beep_reports_success() {
        let svc = MacPlatformServices::new();
        assert_eq!(svc.beep(), Ok(()));
    }

    /// quadraui#959: `displays` needs a `MainThreadMarker` the same way
    /// `system_theme`/`show_message_dialog` above do, so off the spawned
    /// thread `cargo test` runs every `#[test]` fn on, it reports
    /// `Unsupported` rather than panicking — same shape
    /// `show_message_dialog_off_main_thread_returns_none_not_panic`
    /// pins for that method.
    #[test]
    fn displays_off_main_thread_returns_unsupported_not_panic() {
        let svc = MacPlatformServices::new();
        assert_eq!(svc.displays(), Err(BackendError::Unsupported));
    }

    /// `NSEvent::mouseLocation()` (issue #959) — a bare AppKit class
    /// method with no receiver, like `NSBeep` above, so this is safe to
    /// call from a spawned test thread without a `MainThreadMarker` and
    /// always reports a real point.
    #[test]
    fn cursor_screen_point_reports_a_point() {
        let svc = MacPlatformServices::new();
        assert!(svc.cursor_screen_point().is_ok());
    }

    /// #1087 acceptance bar: `open_url_result` reports a real failure
    /// when the platform opener can't even launch, instead of the
    /// pre-#1087 capability lie (`open_url`'s `Command::spawn` discarded
    /// its outcome; `open_url_result` fell to the trait's `Ok(())`
    /// default). `$PATH` is temporarily redirected (guarded by
    /// [`crate::desktop::PATH_OVERRIDE_TEST_LOCK`], and always restored
    /// via a drop guard even on panic) to a directory containing no
    /// `open` binary at all, so the real `Command::new("open").spawn()`
    /// genuinely fails (`ENOENT`) rather than launching anything.
    #[test]
    fn open_url_result_reports_failure_when_the_opener_is_missing() {
        let _guard = crate::desktop::PATH_OVERRIDE_TEST_LOCK
            .lock()
            .unwrap_or_else(|p| p.into_inner());
        let original_path = std::env::var_os("PATH");
        struct RestorePath(Option<std::ffi::OsString>);
        impl Drop for RestorePath {
            fn drop(&mut self) {
                match self.0.take() {
                    Some(path) => std::env::set_var("PATH", path),
                    None => std::env::remove_var("PATH"),
                }
            }
        }
        let _restore = RestorePath(original_path);
        let empty_dir = tempfile::tempdir().expect("tempdir");
        std::env::set_var("PATH", empty_dir.path());

        let svc = MacPlatformServices::new();
        assert!(svc.open_url_result("https://example.com/1087").is_err());
    }

    // ── Clipboard image/html/file-list/clear (#954) ────────────────────

    /// Real `NSPasteboard` round trip through every method #954 added,
    /// in one `#[test]` fn rather than several: `cargo test` runs
    /// `#[test]` fns in parallel by default, and separate fns would fight
    /// over the one real systemwide pasteboard (same reasoning as
    /// `build_file_dialog_behaviors`'s single-fn consolidation elsewhere
    /// in this crate, different shared resource). Skips gracefully — like
    /// `build_file_dialog_behaviors` does for a missing display — on a
    /// runner with no live `NSPasteboard` session at all, rather than
    /// failing the whole crate's test run over an environment gap this
    /// test isn't trying to cover.
    ///
    /// Consolidating into one fn only removes the race while this fn is
    /// the crate's *only* real-pasteboard test, which stopped being true
    /// when `macos::testing`'s Ctrl-C copy test (#803) landed — see
    /// [`crate::macos::lock_real_pasteboard`] for how that pair raced and
    /// why both now take the same lock.
    #[allow(clippy::print_stderr)]
    #[test]
    fn clipboard_image_html_file_list_and_clear_round_trip() {
        let _pasteboard = crate::macos::lock_real_pasteboard();
        let svc = MacPlatformServices::new();
        let cb = svc.clipboard();

        // write_image → read_image: dimensions and pixel-buffer length
        // round-trip even though NSPasteboard may re-encode the bytes
        // internally (TIFF) — this doesn't assert byte-for-byte pixel
        // equality, only shape.
        let image = RgbaImage {
            width: 2,
            height: 2,
            pixels: vec![
                255, 0, 0, 255, // red
                0, 255, 0, 255, // green
                0, 0, 255, 255, // blue
                255, 255, 0, 255, // yellow
            ],
        };
        if let Err(e) = cb.write_image(&image) {
            eprintln!("skipping: no live NSPasteboard session in this environment ({e:?})");
            return;
        }
        let read_back = cb
            .read_image()
            .expect("read_image should see what write_image just wrote");
        assert_eq!(read_back.width, image.width);
        assert_eq!(read_back.height, image.height);
        assert_eq!(
            read_back.pixels.len(),
            (image.width * image.height * 4) as usize
        );

        // write_html: no read-back method exists (see `ClipboardFormat`'s
        // doc for why) — just assert it succeeds.
        cb.write_html("<b>hi</b>", "hi").expect(
            "write_html should succeed once write_image already proved the pasteboard is live",
        );

        // read_file_list: `Clipboard` has no `write_file_list` (only
        // `read_file_list` — again see `ClipboardFormat`'s doc), so seed
        // the pasteboard directly via a second `arboard::Clipboard`
        // handle, then confirm `MacClipboard::read_file_list` reads back
        // what was set.
        let tmp = std::env::temp_dir().join("quadraui-954-clipboard-test-file.txt");
        std::fs::write(&tmp, b"quadraui#954").expect("write temp file");
        arboard::Clipboard::new()
            .expect("a second arboard handle should also see the live pasteboard")
            .set()
            .file_list(&[&tmp])
            .expect("seeding the pasteboard with a file list should succeed");
        let files = cb
            .read_file_list()
            .expect("read_file_list should see the seeded file");
        // Canonicalize before comparing: NSPasteboard round-trips the
        // path through `/private/var/...` even though `std::env::temp_dir()`
        // returns the `/var/...` symlink on macOS — a path-spelling
        // artifact of the OS pasteboard, not something `read_file_list`
        // got wrong.
        assert_eq!(
            files
                .iter()
                .map(|p| p.canonicalize().unwrap_or_else(|_| p.clone()))
                .collect::<Vec<_>>(),
            vec![tmp.canonicalize().expect("temp file should exist")]
        );
        let _ = std::fs::remove_file(&tmp);

        // clear: removes everything, regardless of format.
        cb.write_text("some text #954");
        assert_eq!(cb.read_text(), Some("some text #954".to_string()));
        cb.clear()
            .expect("clear should succeed once the pasteboard has proven live");
        assert_eq!(cb.read_text(), None);
    }

    // `applescript_escape`/`display_notification_script` tests moved to
    // `crate::desktop::display_notification_script_tests` alongside the
    // functions themselves (issue #1092).

    // ── system_theme_from_mac_appearance / unit_to_u8 (quadraui#952) ────

    #[test]
    fn dark_aqua_appearance_reports_dark() {
        let theme = system_theme_from_mac_appearance("NSAppearanceNameDarkAqua", false, None);
        assert!(theme.dark);
        assert!(!theme.high_contrast);
        assert_eq!(theme.accent, None);
    }

    #[test]
    fn aqua_appearance_reports_light() {
        let theme = system_theme_from_mac_appearance("NSAppearanceNameAqua", false, None);
        assert!(!theme.dark);
    }

    #[test]
    fn high_contrast_flag_is_passed_through_not_rederived_from_name() {
        // The appearance name alone already implies high contrast, but
        // `high_contrast` is a caller-supplied signal
        // (`NSWorkspace::accessibilityDisplayShouldIncreaseContrast`),
        // not derived from the name — this pins that the function trusts
        // its caller's flag rather than re-deriving it from the name
        // string.
        let theme = system_theme_from_mac_appearance(
            "NSAppearanceNameAccessibilityHighContrastDarkAqua",
            true,
            None,
        );
        assert!(theme.dark);
        assert!(theme.high_contrast);
    }

    #[test]
    fn accent_color_passes_through_unchanged() {
        let accent = Some(Color::rgb(0, 122, 255));
        let theme = system_theme_from_mac_appearance("NSAppearanceNameAqua", false, accent);
        assert_eq!(theme.accent, accent);
    }

    #[test]
    fn unit_to_u8_maps_the_full_range() {
        assert_eq!(unit_to_u8(0.0), 0);
        assert_eq!(unit_to_u8(1.0), 255);
        assert_eq!(unit_to_u8(0.5), 128);
    }

    #[test]
    fn unit_to_u8_clamps_out_of_range_input() {
        assert_eq!(unit_to_u8(-1.0), 0);
        assert_eq!(unit_to_u8(2.0), 255);
    }

    fn msg_btn(id: &str, is_default: bool, is_cancel: bool) -> MessageDialogButton {
        MessageDialogButton {
            id: crate::types::WidgetId::new(id),
            label: id.to_string(),
            is_default,
            is_cancel,
        }
    }

    #[test]
    fn native_button_order_puts_default_first_and_cancel_second() {
        let buttons = [
            msg_btn("middle", false, false),
            msg_btn("cancel", false, true),
            msg_btn("default", true, false),
        ];
        assert_eq!(native_button_order(&buttons), vec![2, 1, 0]);
    }

    #[test]
    fn native_button_order_preserves_relative_order_of_the_rest() {
        let buttons = [
            msg_btn("a", false, false),
            msg_btn("b", false, false),
            msg_btn("c", false, false),
        ];
        assert_eq!(native_button_order(&buttons), vec![0, 1, 2]);
    }

    #[test]
    fn native_button_order_single_button_both_default_and_cancel() {
        // A single "OK" button often carries both flags. It should still
        // appear exactly once (in the default slot), not twice.
        let buttons = [msg_btn("ok", true, true)];
        assert_eq!(native_button_order(&buttons), vec![0]);
    }

    #[test]
    fn native_button_order_no_default_or_cancel_keeps_declared_order() {
        let buttons = [msg_btn("a", false, false), msg_btn("b", false, false)];
        assert_eq!(native_button_order(&buttons), vec![0, 1]);
    }

    #[test]
    fn key_equivalent_for_button_default_only_binds_return() {
        assert_eq!(
            key_equivalent_for_button(&msg_btn("ok", true, false)),
            Some("\r")
        );
    }

    #[test]
    fn key_equivalent_for_button_cancel_only_binds_escape() {
        assert_eq!(
            key_equivalent_for_button(&msg_btn("cancel", false, true)),
            Some("\u{1b}")
        );
    }

    #[test]
    fn key_equivalent_for_button_neither_binds_nothing() {
        assert_eq!(
            key_equivalent_for_button(&msg_btn("middle", false, false)),
            None
        );
    }

    #[test]
    fn key_equivalent_for_button_both_default_and_cancel_binds_return_not_escape() {
        // Regression test (quadraui#936 review): a single "OK" button
        // that carries both flags — the most common message-dialog
        // shape — MUST get Return, not just Escape, or pressing Enter
        // does nothing and the dialog is keyboard-unresponsive on its
        // most common shape.
        assert_eq!(
            key_equivalent_for_button(&msg_btn("ok", true, true)),
            Some("\r")
        );
    }

    #[test]
    fn severity_to_alert_style_maps_error_and_warning_distinctly() {
        assert_eq!(
            severity_to_alert_style(Some(DialogSeverity::Error)),
            NSAlertStyle::Critical
        );
        assert_eq!(
            severity_to_alert_style(Some(DialogSeverity::Warning)),
            NSAlertStyle::Warning
        );
    }

    #[test]
    fn severity_to_alert_style_defaults_question_and_none_to_informational() {
        assert_eq!(
            severity_to_alert_style(Some(DialogSeverity::Info)),
            NSAlertStyle::Informational
        );
        assert_eq!(
            severity_to_alert_style(Some(DialogSeverity::Question)),
            NSAlertStyle::Informational
        );
        assert_eq!(severity_to_alert_style(None), NSAlertStyle::Informational);
    }

    /// RED-verify companion (quadraui#936's acceptance bar): off the main
    /// thread — which is exactly where Rust's default per-test-fn thread
    /// puts this test — `show_message_dialog` must degrade to `None`
    /// rather than panic, the same contract the doc comment on
    /// `show_message_dialog` describes. Before this issue's fix the
    /// method was an unconditional `None` stub, so this assertion also
    /// held then; what changed is that it now holds for the *documented
    /// reason* (no `MainThreadMarker` here) rather than "not implemented
    /// yet".
    #[test]
    fn show_message_dialog_off_main_thread_returns_none_not_panic() {
        let svc = MacPlatformServices::new();
        let opts = MessageDialogOptions {
            title: "Title".to_string(),
            body: "Body".to_string(),
            buttons: vec![msg_btn("ok", true, true)],
            severity: None,
        };
        assert!(svc.show_message_dialog(opts).is_none());
    }
}