gpui_core/

platform.rs

mod app_menu;
mod keyboard;
mod keystroke;
/// Wayland layer-shell window configuration.
#[cfg(all(any(target_os = "linux", target_os = "freebsd"), feature = "wayland"))]
pub mod layer_shell;
mod platform_info;
/// Cross-platform single instance enforcement using Unix domain sockets and Windows named mutexes.
pub mod single_instance;
/// Pure Rust utility for computing window bounds from a semantic [`WindowPosition`].
pub mod window_positioner;

#[cfg(all(
    feature = "screen-capture",
    any(target_os = "linux", target_os = "freebsd")
))]
type PlatformScreenCaptureFrame = scap::frame::Frame;
#[cfg(all(
    any(target_os = "linux", target_os = "freebsd"),
    not(feature = "screen-capture")
))]
type PlatformScreenCaptureFrame = ();

#[cfg(target_os = "macos")]
type PlatformScreenCaptureFrame = core_video::image_buffer::CVImageBuffer;

#[cfg(all(target_os = "windows", feature = "screen-capture"))]
type PlatformScreenCaptureFrame = scap::frame::Frame;
#[cfg(all(target_os = "windows", not(feature = "screen-capture")))]
type PlatformScreenCaptureFrame = ();

#[cfg(any(test, feature = "test-support"))]
#[doc(hidden)]
#[allow(missing_docs)]
pub mod render_image;

#[cfg(any(test, feature = "test-support"))]
mod test;
#[cfg(any(test, feature = "test-support"))]
mod threaded_dispatcher;

#[cfg(all(
    feature = "screen-capture",
    any(
        target_os = "windows",
        all(
            any(target_os = "linux", target_os = "freebsd"),
            any(feature = "wayland", feature = "x11"),
        )
    )
))]
/// Shared screen-capture implementation used by desktop backends.
#[doc(hidden)]
pub mod scap_screen_capture;

use crate::{
    Action, AnyWindowHandle, App, AsyncWindowContext, BackgroundExecutor, Bounds, Corners,
    DEFAULT_WINDOW_SIZE, DevicePixels, DispatchEventResult, Font, FontId, FontMetrics, FontRun,
    ForegroundExecutor, GlyphId, GpuResourceBudget, GpuSpecs, Hsla, ImageSource, Keymap,
    LineLayout, MissingGlyphSink, Pixels, PlatformInput, Point, QuitMode, RenderGlyphParams,
    RenderImage, RenderImageParams, RenderSvgParams, Scene, ShapedGlyph, ShapedRun, SharedString,
    Size, SvgRenderer, SystemWindowTab, Task, TaskLabel, Window, WindowControlArea, hash, point,
    px, size,
};

use anyhow::{Context as _, Result};
use async_task::Runnable;
use futures::channel::oneshot;
#[cfg(feature = "image-format-gif")]
use image::AnimationDecoder as _;
#[cfg(feature = "image-format-gif")]
use image::codecs::gif::GifDecoder;
use image::{DynamicImage, Frame};
use parking::Unparker;
pub use platform_info::{OperatingSystem, PlatformInfo, PlatformTarget};
use raw_window_handle::{HasDisplayHandle, HasWindowHandle};
use schemars::JsonSchema;
use seahash::SeaHasher;
use serde::{Deserialize, Serialize};
use smallvec::SmallVec;
use std::borrow::Cow;
use std::hash::{Hash, Hasher};
use std::io::Cursor;
use std::ops;
use std::time::{Duration, Instant};
use std::{
    ffi::OsString,
    fmt::{self, Debug},
    ops::Range,
    path::{Path, PathBuf},
    rc::Rc,
    sync::Arc,
};
use strum::EnumIter;
use uuid::Uuid;

pub use app_menu::*;
pub use keyboard::*;
pub use keystroke::*;

pub use semantic_version::SemanticVersion;
#[cfg(any(test, feature = "test-support"))]
pub(crate) use test::*;

/// Keeps an operating system activity, such as an idle sleep inhibitor, alive until dropped.
pub struct ActivityGuard {
    _release: util::Deferred<Box<dyn FnOnce() + Send>>,
}

impl std::fmt::Debug for ActivityGuard {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ActivityGuard").finish_non_exhaustive()
    }
}

impl ActivityGuard {
    /// Runs `release` when the guard is dropped.
    pub fn new(release: impl FnOnce() + Send + 'static) -> Self {
        Self {
            _release: util::defer(Box::new(release)),
        }
    }

    /// A guard for platforms without a corresponding activity.
    pub fn noop() -> Self {
        Self::new(|| {})
    }
}

#[cfg(any(test, feature = "test-support"))]
pub use test::{
    TestDispatcher, TestScreenCaptureSource, TestScreenCaptureStream, VisualRenderArtifact,
};
#[cfg(any(test, feature = "test-support"))]
pub use threaded_dispatcher::ThreadedDispatcher;

#[cfg(all(
    any(test, feature = "test-support"),
    any(
        target_os = "macos",
        target_os = "linux",
        target_os = "freebsd",
        target_os = "windows"
    )
))]
#[doc(hidden)]
pub use test::VisualTestPlatform;

/// Returns which Linux compositor the environment indicates without connecting to it.
#[cfg(any(target_os = "linux", target_os = "freebsd"))]
#[inline]
pub fn guess_compositor() -> &'static str {
    if std::env::var_os("ZED_HEADLESS").is_some() {
        return "Headless";
    }

    #[cfg(feature = "wayland")]
    let wayland_display = std::env::var_os("WAYLAND_DISPLAY");
    #[cfg(not(feature = "wayland"))]
    let wayland_display: Option<std::ffi::OsString> = None;

    #[cfg(feature = "x11")]
    let x11_display = std::env::var_os("DISPLAY");
    #[cfg(not(feature = "x11"))]
    let x11_display: Option<std::ffi::OsString> = None;

    let use_wayland = wayland_display.is_some_and(|display| !display.is_empty());
    let use_x11 = x11_display.is_some_and(|display| !display.is_empty());

    if use_wayland {
        "Wayland"
    } else if use_x11 {
        "X11"
    } else {
        "Headless"
    }
}

/// Snapshot of the renderer's pooled GPU resource usage.
///
/// Returned by [`App::renderer_cache_stats`]. Use together with
/// [`App::trim_gpu_caches`] to decide whether reclaiming idle GPU memory is
/// worthwhile. This is a best-effort diagnostic snapshot; platforms that do
/// not maintain trimmable GPU pools report zero.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct RendererCacheStats {
    /// Number of idle GPU instance buffers held by the renderer pool.
    pub idle_gpu_buffers: usize,
    /// Configured size in bytes of each pooled GPU instance buffer.
    pub gpu_buffer_size_bytes: usize,
}

impl RendererCacheStats {
    /// Creates a renderer cache snapshot from backend pool counters.
    #[doc(hidden)]
    pub fn new(idle_gpu_buffers: usize, gpu_buffer_size_bytes: usize) -> Self {
        Self {
            idle_gpu_buffers,
            gpu_buffer_size_bytes,
        }
    }
}

/// Low-level operating-system integration contract implemented by GPUI backends.
#[allow(missing_docs)]
pub trait Platform: 'static {
    /// Returns the host operating system and application target.
    fn platform_info(&self) -> PlatformInfo;

    fn background_executor(&self) -> BackgroundExecutor;
    fn foreground_executor(&self) -> ForegroundExecutor;
    fn text_system(&self) -> Arc<dyn PlatformTextSystem>;

    fn run(&self, on_finish_launching: Box<dyn 'static + FnOnce()>);
    fn quit(&self);
    fn restart(&self, binary_path: Option<PathBuf>, arguments: Vec<OsString>);
    fn activate(&self, ignoring_other_apps: bool);
    fn hide(&self);
    fn hide_other_apps(&self);
    fn unhide_other_apps(&self);

    fn displays(&self) -> Vec<Rc<dyn PlatformDisplay>>;
    fn primary_display(&self) -> Option<Rc<dyn PlatformDisplay>>;
    fn active_window(&self) -> Option<AnyWindowHandle>;
    fn window_stack(&self) -> Option<Vec<AnyWindowHandle>> {
        None
    }

    #[cfg(feature = "screen-capture")]
    fn is_screen_capture_supported(&self) -> bool;
    #[cfg(not(feature = "screen-capture"))]
    fn is_screen_capture_supported(&self) -> bool {
        false
    }
    #[cfg(feature = "screen-capture")]
    fn screen_capture_sources(&self)
    -> oneshot::Receiver<Result<Vec<Rc<dyn ScreenCaptureSource>>>>;
    #[cfg(not(feature = "screen-capture"))]
    fn screen_capture_sources(
        &self,
    ) -> oneshot::Receiver<anyhow::Result<Vec<Rc<dyn ScreenCaptureSource>>>> {
        let (sources_tx, sources_rx) = oneshot::channel();
        sources_tx
            .send(Err(anyhow::anyhow!(
                "gpui was compiled without the screen-capture feature"
            )))
            .ok();
        sources_rx
    }

    fn open_window(
        &self,
        handle: AnyWindowHandle,
        options: WindowParams,
    ) -> anyhow::Result<Box<dyn PlatformWindow>>;

    /// Drop any idle GPU buffers held by the renderer's pools, retaining
    /// configuration. Default implementation is a no-op for platforms that do
    /// not maintain such pools.
    fn trim_renderer_caches(&self) {}

    /// Apply renderer GPU resource budgets. Default implementation is a no-op
    /// for platforms that do not expose configurable renderer pools.
    fn configure_gpu_resources(&self, _gpu: &GpuResourceBudget) {}

    /// Snapshot of the renderer's pooled GPU resource usage. Default
    /// implementation reports an empty snapshot for platforms that do not
    /// maintain such pools.
    fn renderer_cache_stats(&self) -> RendererCacheStats {
        RendererCacheStats::default()
    }

    /// Returns the appearance of the application's windows.
    fn window_appearance(&self) -> WindowAppearance;

    /// Overrides the appearance (light/dark) applied to the app's windows, independent
    /// of the OS-wide setting. Pass `None` to clear the override and follow the system
    /// again. The override is reflected by [`Platform::window_appearance`].
    ///
    /// On macOS this sets `NSApplication.appearance` so the native window chrome (the
    /// window border and titlebar) of every window matches a dark app theme even when
    /// the system is in light mode (or vice versa). Other backends store the override
    /// for [`Platform::window_appearance`] without changing native chrome.
    fn set_window_appearance(&self, _appearance: Option<WindowAppearance>) {}

    fn open_url(&self, url: &str);
    fn on_open_urls(&self, callback: Box<dyn FnMut(Vec<String>)>);
    fn register_url_scheme(&self, url: &str) -> Task<Result<()>>;

    fn prompt_for_paths(
        &self,
        options: PathPromptOptions,
    ) -> oneshot::Receiver<Result<Option<Vec<PathBuf>>>>;
    fn prompt_for_new_path(
        &self,
        directory: &Path,
        suggested_name: Option<&str>,
    ) -> oneshot::Receiver<Result<Option<PathBuf>>>;
    fn can_select_mixed_files_and_dirs(&self) -> bool;
    fn reveal_path(&self, path: &Path);
    fn open_with_system(&self, path: &Path);

    fn on_quit(&self, callback: Box<dyn FnMut() -> bool>);
    fn on_reopen(&self, callback: Box<dyn FnMut()>);

    fn set_menus(&self, menus: Vec<Menu>, keymap: &Keymap);
    fn get_menus(&self) -> Option<Vec<OwnedMenu>> {
        None
    }

    fn set_dock_menu(&self, menu: Vec<MenuItem>, keymap: &Keymap);
    fn perform_dock_menu_action(&self, _action: usize) {}
    fn add_recent_document(&self, _path: &Path) {}
    fn update_jump_list(
        &self,
        _menus: Vec<MenuItem>,
        _entries: Vec<SmallVec<[PathBuf; 2]>>,
    ) -> Vec<SmallVec<[PathBuf; 2]>> {
        Vec::new()
    }
    fn on_app_menu_action(&self, callback: Box<dyn FnMut(&dyn Action)>);
    fn on_will_open_app_menu(&self, callback: Box<dyn FnMut()>);
    fn on_validate_app_menu_command(&self, callback: Box<dyn FnMut(&dyn Action) -> bool>);

    fn thermal_state(&self) -> ThermalState {
        ThermalState::Nominal
    }
    fn on_thermal_state_change(&self, _callback: Box<dyn FnMut()>) {}

    /// Returns the operating system's power mode, or [`PowerMode::Unknown`]
    /// when the platform cannot determine it.
    fn power_mode(&self) -> PowerMode {
        PowerMode::Unknown
    }
    /// Registers a callback invoked when the reported power mode changes.
    fn on_power_mode_change(&self, _callback: Box<dyn FnMut()>) {}

    /// Prevents idle sleep while the returned guard is held.
    ///
    /// Dropping the guard restores the previous sleep policy.
    fn prevent_idle_sleep(&self, reason: &str) -> Task<Result<ActivityGuard>>;

    fn compositor_name(&self) -> &'static str {
        ""
    }
    fn app_path(&self) -> Result<PathBuf>;
    fn path_for_auxiliary_executable(&self, name: &str) -> Result<PathBuf>;

    fn set_cursor_style(&self, style: CursorStyle);
    fn should_auto_hide_scrollbars(&self) -> bool;

    #[cfg(any(target_os = "linux", target_os = "freebsd"))]
    fn write_to_primary(&self, item: ClipboardItem);
    fn write_to_clipboard(&self, item: ClipboardItem);
    #[cfg(any(target_os = "linux", target_os = "freebsd"))]
    fn read_from_primary(&self) -> Option<ClipboardItem>;
    fn read_from_clipboard(&self) -> Option<ClipboardItem>;

    fn write_credentials(&self, url: &str, username: &str, password: &[u8]) -> Task<Result<()>>;

    /// Writes credentials only when no item exists for the same URL and username.
    ///
    /// Platforms without atomic credential creation return an error by default.
    #[cfg(target_os = "macos")]
    fn write_credentials_if_not_exists(
        &self,
        _url: &str,
        _username: &str,
        _password: &[u8],
    ) -> Task<Result<bool>> {
        Task::ready(Err(anyhow::anyhow!(
            "this platform does not support atomic credential writes"
        )))
    }

    fn read_credentials(&self, url: &str) -> Task<Result<Option<(String, Vec<u8>)>>>;
    fn delete_credentials(&self, url: &str) -> Task<Result<()>>;

    fn keyboard_layout(&self) -> Box<dyn PlatformKeyboardLayout>;
    fn keyboard_mapper(&self) -> Rc<dyn PlatformKeyboardMapper>;
    fn on_keyboard_layout_change(&self, callback: Box<dyn FnMut()>);

    fn set_tray_icon(&self, _icon: Option<&[u8]>) {}
    fn set_tray_icon_rendering_mode(&self, _rendering_mode: TrayIconRenderingMode) {}
    fn set_tray_menu(&self, _menu: Vec<TrayMenuItem>) {}
    fn set_tray_tooltip(&self, _tooltip: &str) {}
    fn set_tray_panel_mode(&self, _enabled: bool) {}
    fn get_tray_icon_anchor(&self) -> Option<TrayAnchor> {
        None
    }
    fn get_tray_icon_bounds(&self) -> Option<Bounds<Pixels>> {
        None
    }
    fn on_tray_icon_event(&self, mut callback: Box<dyn FnMut(TrayIconEvent)>) {
        self.on_tray_icon_click_event(Box::new(move |event| callback(event.kind)));
    }
    fn on_tray_icon_click_event(&self, _callback: Box<dyn FnMut(TrayIconClickEvent)>) {}
    fn on_tray_menu_action(&self, _callback: Box<dyn FnMut(SharedString)>) {}

    fn register_global_hotkey(&self, _id: u32, _keystroke: &Keystroke) -> Result<()> {
        Err(anyhow::anyhow!(
            "Global hotkeys not supported on this platform"
        ))
    }
    fn unregister_global_hotkey(&self, _id: u32) {}
    fn on_global_hotkey(&self, _callback: Box<dyn FnMut(u32)>) {}

    fn focused_window_info(&self) -> Option<FocusedWindowInfo> {
        None
    }

    fn accessibility_status(&self) -> PermissionStatus {
        PermissionStatus::Unavailable
    }
    fn request_accessibility_permission(&self) -> PermissionRequestStatus {
        PermissionRequestStatus::Unavailable
    }

    fn microphone_status(&self) -> PermissionStatus {
        PermissionStatus::Unavailable
    }
    fn request_microphone_permission(
        &self,
        callback: Box<dyn FnOnce(bool)>,
    ) -> PermissionRequestStatus {
        callback(false);
        PermissionRequestStatus::Unavailable
    }

    fn set_auto_launch(&self, _app_id: &str, _enabled: bool) -> Result<()> {
        Err(anyhow::anyhow!(
            "Auto-launch not supported on this platform"
        ))
    }
    fn is_auto_launch_enabled(&self, _app_id: &str) -> bool {
        false
    }

    fn show_notification(&self, _title: &str, _body: &str) -> Result<()> {
        Err(anyhow::anyhow!(
            "Notifications not supported on this platform"
        ))
    }

    /// Receive the application's configured [`QuitMode`].
    ///
    /// The core application state owns the actual lifecycle decision; platforms
    /// only need this hook when quit mode carries a platform-visible side
    /// effect (for example macOS `ActivationPolicy`). The default
    /// implementation is a no-op.
    fn set_quit_mode(&self, _mode: QuitMode) {}

    fn on_system_power_event(&self, _callback: Box<dyn FnMut(SystemPowerEvent)>) {}
    fn start_power_save_blocker(&self, _kind: PowerSaveBlockerKind) -> Option<u32> {
        None
    }
    fn stop_power_save_blocker(&self, _id: u32) {}
    fn system_idle_time(&self) -> Option<Duration> {
        None
    }
    fn network_status(&self) -> NetworkStatus {
        NetworkStatus::Online
    }
    fn on_network_status_change(&self, _callback: Box<dyn FnMut(NetworkStatus)>) {}
    fn on_media_key_event(&self, _callback: Box<dyn FnMut(MediaKeyEvent)>) {}
    fn request_user_attention(&self, _attention_type: AttentionType) {}
    fn cancel_user_attention(&self) {}
    fn set_dock_badge(&self, _label: Option<&str>) {}
    fn show_context_menu(
        &self,
        _position: Point<Pixels>,
        _items: Vec<TrayMenuItem>,
        _callback: Box<dyn FnMut(SharedString)>,
    ) {
    }
    fn show_dialog(&self, _options: DialogOptions) -> oneshot::Receiver<usize> {
        let (tx, rx) = oneshot::channel();
        tx.send(0).ok();
        rx
    }
    fn os_info(&self) -> OsInfo {
        OsInfo {
            name: std::env::consts::OS.into(),
            arch: std::env::consts::ARCH.into(),
            version: String::new().into(),
            locale: String::new().into(),
            hostname: String::new().into(),
        }
    }
    fn biometric_status(&self) -> BiometricStatus {
        BiometricStatus::Unavailable
    }
    fn authenticate_biometric(&self, _reason: &str, callback: Box<dyn FnOnce(bool) + Send>) {
        callback(false);
    }
}

/// A handle to a platform's display, e.g. a monitor or laptop screen.
pub trait PlatformDisplay: Send + Sync + Debug {
    /// Get the ID for this display
    fn id(&self) -> DisplayId;

    /// Returns a stable identifier for this display that can be persisted and used
    /// across system restarts.
    fn uuid(&self) -> Result<Uuid>;

    /// Get the bounds for this display
    fn bounds(&self) -> Bounds<Pixels>;

    /// Get the visible bounds for this display, excluding taskbar/dock areas.
    /// Defaults to the full display bounds if the platform does not expose a
    /// separate work area.
    fn visible_bounds(&self) -> Bounds<Pixels> {
        self.bounds()
    }

    /// Get the default bounds for this display to place a window
    fn default_bounds(&self) -> Bounds<Pixels> {
        let bounds = self.visible_bounds();
        let center = bounds.center();
        let window_size = DEFAULT_WINDOW_SIZE.min(&bounds.size);
        let offset = window_size / 2.0;
        let origin = point(center.x - offset.width, center.y - offset.height);
        Bounds::new(origin, window_size)
    }
}

/// The operating system's preference for energy use versus performance.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PowerMode {
    /// The platform cannot determine the mode, or cannot distinguish the
    /// active mode from other non-low-power modes.
    Unknown,
    /// The system prioritizes reducing energy use.
    LowPower,
    /// The system balances energy use and performance.
    Balanced,
    /// The system prioritizes performance over energy use.
    HighPower,
}

/// Thermal state of the system.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ThermalState {
    /// System has no thermal constraints.
    Nominal,
    /// System is slightly constrained, reduce discretionary work.
    Fair,
    /// System is moderately constrained, reduce CPU/GPU intensive work.
    Serious,
    /// System is critically constrained, minimize all resource usage.
    Critical,
}

/// Metadata for a given [ScreenCaptureSource]
#[derive(Clone)]
pub struct SourceMetadata {
    /// Opaque identifier of this screen.
    pub id: u64,
    /// Human-readable label for this source.
    pub label: Option<SharedString>,
    /// Whether this source is the main display.
    pub is_main: Option<bool>,
    /// Video resolution of this source.
    pub resolution: Size<DevicePixels>,
}

/// A source of on-screen video content that can be captured.
pub trait ScreenCaptureSource {
    /// Returns metadata for this source.
    fn metadata(&self) -> Result<SourceMetadata>;

    /// Start capture video from this source, invoking the given callback
    /// with each frame.
    fn stream(
        &self,
        foreground_executor: &ForegroundExecutor,
        frame_callback: Box<dyn Fn(ScreenCaptureFrame) + Send>,
    ) -> oneshot::Receiver<Result<Box<dyn ScreenCaptureStream>>>;

    /// Starts capture and reports its terminal state.
    ///
    /// Startup failures are returned through the receiver. Implementations
    /// invoke `termination_callback` exactly once after a started stream ends,
    /// is cancelled, or fails.
    fn stream_with_termination(
        &self,
        _foreground_executor: &ForegroundExecutor,
        _frame_callback: Box<dyn Fn(ScreenCaptureFrame) + Send>,
        _termination_callback: ScreenCaptureTerminationCallback,
    ) -> oneshot::Receiver<Result<Box<dyn ScreenCaptureStream>>> {
        let (mut sender, receiver) = oneshot::channel();
        sender
            .send(Err(anyhow::anyhow!(
                "runtime termination notification is not supported by this screen capture source"
            )))
            .ok();
        receiver
    }
}

/// Receives a single terminal state from a started screen-capture stream.
pub type ScreenCaptureTerminationCallback = Box<dyn FnOnce(ScreenCaptureStreamTermination) + Send>;

/// The terminal state of a started screen-capture stream.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ScreenCaptureStreamTermination {
    /// The stream completed without an error.
    Ended,
    /// The stream was cancelled before completion.
    Cancelled,
    /// The stream ended because capture failed at runtime.
    Failed(SharedString),
}

/// A video stream captured from a screen.
pub trait ScreenCaptureStream {
    /// Returns metadata for this source.
    fn metadata(&self) -> Result<SourceMetadata>;
}

/// A frame of video captured from a screen.
pub struct ScreenCaptureFrame(pub PlatformScreenCaptureFrame);

/// An opaque identifier for a hardware display
#[derive(PartialEq, Eq, Hash, Copy, Clone)]
pub struct DisplayId(pub(crate) u64);

impl DisplayId {
    /// Creates a display identifier from a raw platform display value.
    #[doc(hidden)]
    pub fn new(id: u64) -> Self {
        Self(id)
    }

    /// Returns this identifier as a zero-based platform display index.
    #[doc(hidden)]
    pub fn index(self) -> usize {
        self.0 as usize
    }
}

impl From<u32> for DisplayId {
    fn from(id: u32) -> Self {
        Self(u64::from(id))
    }
}

impl From<DisplayId> for u32 {
    fn from(id: DisplayId) -> Self {
        id.0 as u32
    }
}

impl From<DisplayId> for u64 {
    fn from(id: DisplayId) -> Self {
        id.0
    }
}

impl Debug for DisplayId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "DisplayId({})", self.0)
    }
}

unsafe impl Send for DisplayId {}

/// Which part of the window to resize
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ResizeEdge {
    /// The top edge
    Top,
    /// The top right corner
    TopRight,
    /// The right edge
    Right,
    /// The bottom right corner
    BottomRight,
    /// The bottom edge
    Bottom,
    /// The bottom left corner
    BottomLeft,
    /// The left edge
    Left,
    /// The top left corner
    TopLeft,
}

/// A type to describe the appearance of a window
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Default)]
pub enum WindowDecorations {
    #[default]
    /// Server side decorations
    Server,
    /// Client side decorations
    Client,
}

/// A type to describe how this window is currently configured
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Default)]
pub enum Decorations {
    /// The window is configured to use server side decorations
    #[default]
    Server,
    /// The window is configured to use client side decorations
    Client {
        /// The edge tiling state
        tiling: Tiling,
    },
}

/// What window controls this platform supports
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
pub struct WindowControls {
    /// Whether this platform supports fullscreen
    pub fullscreen: bool,
    /// Whether this platform supports maximize
    pub maximize: bool,
    /// Whether this platform supports minimize
    pub minimize: bool,
    /// Whether this platform supports a window menu
    pub window_menu: bool,
}

impl Default for WindowControls {
    fn default() -> Self {
        // Assume that we can do anything, unless told otherwise
        Self {
            fullscreen: true,
            maximize: true,
            minimize: true,
            window_menu: true,
        }
    }
}

/// A type to describe which sides of the window are currently tiled in some way
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Default)]
pub struct Tiling {
    /// Whether the top edge is tiled
    pub top: bool,
    /// Whether the left edge is tiled
    pub left: bool,
    /// Whether the right edge is tiled
    pub right: bool,
    /// Whether the bottom edge is tiled
    pub bottom: bool,
}

impl Tiling {
    /// Initializes a [`Tiling`] type with all sides tiled
    pub fn tiled() -> Self {
        Self {
            top: true,
            left: true,
            right: true,
            bottom: true,
        }
    }

    /// Whether any edge is tiled
    pub fn is_tiled(&self) -> bool {
        self.top || self.left || self.right || self.bottom
    }
}

#[derive(Debug, Copy, Clone, Eq, PartialEq, Default)]
#[allow(missing_docs)]
pub struct RequestFrameOptions {
    pub require_presentation: bool,
    /// Force refresh of all rendering states when true
    pub force_render: bool,
}

/// Callbacks for the accessibility adapter.
pub struct A11yCallbacks {
    /// Called when the adapter is activated.
    pub activation: Box<dyn Fn() -> Option<accesskit::TreeUpdate> + Send + 'static>,
    /// Called when an action is requested by the screen reader.
    pub action: Box<dyn Fn(accesskit::ActionRequest) + Send + 'static>,
    /// Called when the adapter is deactivated.
    pub deactivation: Box<dyn Fn() + Send + 'static>,
}

/// Whether the platform is presenting a window's frames.
///
/// This is about presentation, not the window's shown/hidden state: a shown
/// window that is fully covered by other windows, minimized, on another
/// Space or virtual desktop, or on a display that is asleep is `Hidden`. A
/// window only partly covered by other windows is `Visible`.
///
/// Each platform reports from a single source, and what that source can see
/// differs:
///
/// * macOS: `NSWindow.occlusionState`. Covers all of the cases above.
/// * Windows: `WS_VISIBLE` and the minimized state. Windows keeps compositing
///   covered windows for thumbnails and Alt-Tab and offers no occlusion
///   notification, so a fully covered window stays `Visible`. Display sleep is
///   not reported either.
/// * Wayland: the `xdg_toplevel` `suspended` state (xdg-shell v6). Compositors
///   that don't support it never report `Hidden`.
/// * X11: mapped state plus `VisibilityNotify`. Compositing window managers
///   generally never report a window as fully obscured, so covering is only
///   detected without compositing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WindowVisibility {
    /// At least part of the window is being presented; frames drawn for it
    /// will be shown.
    Visible,
    /// No part of the window is being presented. The platform will not
    /// request frames for it until it becomes visible again.
    Hidden,
}

impl WindowVisibility {
    /// Whether frames drawn for the window will be shown.
    pub fn is_visible(self) -> bool {
        self == Self::Visible
    }
}

#[allow(missing_docs)]
pub trait PlatformWindow: HasWindowHandle + HasDisplayHandle {
    fn bounds(&self) -> Bounds<Pixels>;
    fn is_maximized(&self) -> bool;
    fn window_bounds(&self) -> WindowBounds;
    fn content_size(&self) -> Size<Pixels>;
    fn resize(&mut self, size: Size<Pixels>);
    /// Resizes the window to the given content size while keeping `anchor`
    /// fixed on screen.
    ///
    /// Unlike [`Self::resize`], which keeps the window origin fixed (growing
    /// right and down) and may animate the change, implementations must not
    /// animate and must keep the anchored corner or edge at its on-screen
    /// position. Useful for popup panels that grow away from the edge they
    /// are attached to (e.g. a tray popup anchored under the menu bar).
    ///
    /// The default falls back to [`Self::resize`], ignoring the anchor.
    fn resize_anchored(&mut self, size: Size<Pixels>, _anchor: ResizeAnchor) {
        self.resize(size);
    }
    fn scale_factor(&self) -> f32;
    fn appearance(&self) -> WindowAppearance;
    fn display(&self) -> Option<Rc<dyn PlatformDisplay>>;
    fn mouse_position(&self) -> Point<Pixels>;
    fn modifiers(&self) -> Modifiers;
    fn capslock(&self) -> Capslock;
    fn set_input_handler(&mut self, input_handler: PlatformInputHandler);
    fn take_input_handler(&mut self) -> Option<PlatformInputHandler>;
    fn prompt(
        &self,
        level: PromptLevel,
        msg: &str,
        detail: Option<&str>,
        answers: &[PromptButton],
    ) -> Option<oneshot::Receiver<usize>>;
    fn activate(&self);
    /// Requests that the operating system draw attention to this window.
    fn request_attention(&self) {}
    fn is_active(&self) -> bool;
    /// The current [`WindowVisibility`]. Read once when the window is created;
    /// afterwards changes arrive through [`Self::on_visibility_change`].
    fn visibility(&self) -> WindowVisibility;
    fn is_hovered(&self) -> bool;
    fn set_title(&mut self, title: &str);
    fn set_background_appearance(&self, background_appearance: WindowBackgroundAppearance);
    fn minimize(&self);
    fn zoom(&self);
    fn toggle_fullscreen(&self);
    fn is_fullscreen(&self) -> bool;
    fn on_request_frame(&self, callback: Box<dyn FnMut(RequestFrameOptions)>);
    fn on_input(&self, callback: Box<dyn FnMut(PlatformInput) -> DispatchEventResult>);
    fn on_active_status_change(&self, callback: Box<dyn FnMut(bool)>);
    /// Registers the callback invoked when [`Self::visibility`] changes. Only
    /// transitions are reported; the callback runs on the main thread outside
    /// of any window update.
    fn on_visibility_change(&self, callback: Box<dyn FnMut(WindowVisibility)>);
    fn on_hover_status_change(&self, callback: Box<dyn FnMut(bool)>);
    fn on_resize(&self, callback: Box<dyn FnMut(Size<Pixels>, f32)>);
    fn on_moved(&self, callback: Box<dyn FnMut()>);
    fn on_should_close(&self, callback: Box<dyn FnMut() -> bool>);
    fn on_hit_test_window_control(&self, callback: Box<dyn FnMut() -> Option<WindowControlArea>>);
    fn on_close(&self, callback: Box<dyn FnOnce()>);
    fn on_appearance_changed(&self, callback: Box<dyn FnMut()>);
    fn draw(&self, scene: &Scene);
    #[cfg(any(test, feature = "test-support"))]
    fn render_to_image(&self, _scene: &Scene) -> anyhow::Result<image::RgbaImage> {
        anyhow::bail!("render_to_image not implemented for this platform")
    }
    fn schedule_frame(&self) {}
    fn sprite_atlas(&self) -> Arc<dyn PlatformAtlas>;

    // macOS specific methods
    fn get_title(&self) -> String {
        String::new()
    }
    fn tabbed_windows(&self) -> Option<Vec<SystemWindowTab>> {
        None
    }
    fn tab_bar_visible(&self) -> bool {
        false
    }
    fn set_edited(&mut self, _edited: bool) {}
    fn toggle_simple_fullscreen(&self) {}
    fn is_simple_fullscreen(&self) -> bool {
        false
    }
    fn show_character_palette(&self) {}
    fn titlebar_double_click(&self) {}
    fn on_move_tab_to_new_window(&self, _callback: Box<dyn FnMut()>) {}
    fn on_merge_all_windows(&self, _callback: Box<dyn FnMut()>) {}
    fn on_select_previous_tab(&self, _callback: Box<dyn FnMut()>) {}
    fn on_select_next_tab(&self, _callback: Box<dyn FnMut()>) {}
    fn on_toggle_tab_bar(&self, _callback: Box<dyn FnMut()>) {}
    fn merge_all_windows(&self) {}
    fn move_tab_to_new_window(&self) {}
    fn toggle_window_tab_overview(&self) {}
    fn set_tabbing_identifier(&self, _identifier: Option<String>) {}

    fn native_window_state(&self) -> Option<Vec<u8>> {
        None
    }
    fn restore_native_window_state(&self, _state: &[u8]) {}

    #[cfg(target_os = "windows")]
    fn get_raw_handle(&self) -> windows::Win32::Foundation::HWND;

    // Linux specific methods
    fn inner_window_bounds(&self) -> WindowBounds {
        self.window_bounds()
    }
    fn request_decorations(&self, _decorations: WindowDecorations) {}
    fn show_window_menu(&self, _position: Point<Pixels>) {}
    fn start_window_move(&self) {}
    fn start_window_resize(&self, _edge: ResizeEdge) {}
    fn set_exclusive_zone(&self, _zone: Pixels) {}
    #[cfg(all(any(target_os = "linux", target_os = "freebsd"), feature = "wayland"))]
    fn set_exclusive_edge(&self, _edge: layer_shell::Anchor) {}
    fn set_input_region(&self, _region: Option<&[Bounds<Pixels>]>) {}
    fn window_decorations(&self) -> Decorations {
        Decorations::Server
    }
    fn set_app_id(&mut self, _app_id: &str) {}
    fn map_window(&mut self) -> anyhow::Result<()> {
        Ok(())
    }
    fn window_controls(&self) -> WindowControls {
        WindowControls::default()
    }
    fn set_client_inset(&self, _inset: Pixels) {}
    fn set_client_corner_radii(&self, _radii: Corners<Pixels>) {}
    fn gpu_specs(&self) -> Option<GpuSpecs>;

    /// Drops idle pooled GPU resources owned by this window's renderer,
    /// where supported. Called by [`crate::App::trim_gpu_caches`] in
    /// addition to [`Platform::trim_renderer_caches`], which covers
    /// renderers whose caches are shared across windows.
    fn trim_renderer_caches(&self) {}

    fn update_ime_position(&self, _bounds: Bounds<Pixels>);

    fn play_system_bell(&self) {}

    /// Initialize the accessibility adapter with callbacks.
    fn a11y_init(&self, _callbacks: A11yCallbacks) {}

    /// Provide a tree update to the accessibility adapter.
    fn a11y_tree_update(&self, _tree_update: accesskit::TreeUpdate) {}

    /// Inform the adapter of updated window bounds.
    fn a11y_update_window_bounds(&self) {}

    fn show(&self) {}
    fn hide(&self) {}
    fn is_visible(&self) -> bool {
        true
    }
    fn set_mouse_passthrough(&self, _passthrough: bool) {}
    fn set_progress_bar(&self, _state: ProgressBarState) {}
    #[allow(dead_code)]
    fn set_window_icon(&self, _icon: Option<image::RgbaImage>) {}

    fn set_cursor_style(&self, _style: CursorStyle) {}

    #[cfg(any(test, feature = "test-support"))]
    fn as_test(&mut self) -> Option<&mut TestWindow> {
        None
    }
}

/// This type is public so that our test macro can generate and use it, but it should not
/// be considered part of our public API.
#[doc(hidden)]
pub trait PlatformDispatcher: Send + Sync {
    fn is_main_thread(&self) -> bool;
    fn dispatch(&self, runnable: Runnable, label: Option<TaskLabel>);
    fn dispatch_on_main_thread(&self, runnable: Runnable);
    fn dispatch_after(&self, duration: Duration, runnable: Runnable);
    fn park(&self, timeout: Option<Duration>) -> bool;
    fn unparker(&self) -> Unparker;
    fn now(&self) -> Instant {
        Instant::now()
    }

    /// Prevents App Nap-style throttling while the returned guard is held.
    ///
    /// This does not prevent the system from entering idle sleep.
    fn prevent_app_nap(&self, _reason: &str) -> ActivityGuard {
        ActivityGuard::noop()
    }

    #[cfg(any(test, feature = "test-support"))]
    fn as_test(&self) -> Option<&TestDispatcher> {
        None
    }

    #[cfg(any(test, feature = "test-support"))]
    fn as_threaded(&self) -> Option<&ThreadedDispatcher> {
        None
    }
}

#[allow(missing_docs)]
pub trait PlatformTextSystem: Send + Sync {
    fn add_fonts(&self, fonts: Vec<Cow<'static, [u8]>>) -> Result<()>;
    fn all_font_names(&self) -> Vec<String>;
    fn font_id(&self, descriptor: &Font) -> Result<FontId>;
    /// Drop platform-side glyph rasterization data associated with the core raster-bounds cache.
    fn clear_glyph_raster_cache(&self) {}
    /// Prewarm any system font caches needed to shape text.
    fn prewarm_fonts(&self, _font_ids: &[FontId]) {}
    fn font_metrics(&self, font_id: FontId) -> FontMetrics;
    fn typographic_bounds(&self, font_id: FontId, glyph_id: GlyphId) -> Result<Bounds<f32>>;
    fn advance(&self, font_id: FontId, glyph_id: GlyphId) -> Result<Size<f32>>;
    fn glyph_for_char(&self, font_id: FontId, ch: char) -> Option<GlyphId>;
    fn glyph_raster_bounds(&self, params: &RenderGlyphParams) -> Result<Bounds<DevicePixels>>;
    fn rasterize_glyph(
        &self,
        params: &RenderGlyphParams,
        raster_bounds: Bounds<DevicePixels>,
    ) -> Result<(Size<DevicePixels>, Vec<u8>)>;
    fn layout_line(&self, text: &str, font_size: Pixels, runs: &[FontRun]) -> LineLayout;

    /// Installs the sink for grapheme clusters that exhaust font fallback during
    /// [`Self::layout_line`]. The core text system installs its reporter when it is
    /// created. Platforms that do not detect missing glyphs keep the default no-op.
    fn set_missing_glyph_sink(&self, _sink: Arc<dyn MissingGlyphSink>) {}

    fn glyph_dilation_for_color(&self, _color: Hsla) -> u8 {
        0
    }
}

#[allow(missing_docs)]
pub struct NoopTextSystem;

#[allow(missing_docs)]
impl NoopTextSystem {
    #[allow(dead_code)]
    pub fn new() -> Self {
        Self
    }
}

impl PlatformTextSystem for NoopTextSystem {
    fn add_fonts(&self, _fonts: Vec<Cow<'static, [u8]>>) -> Result<()> {
        Ok(())
    }

    fn all_font_names(&self) -> Vec<String> {
        Vec::new()
    }

    fn font_id(&self, _descriptor: &Font) -> Result<FontId> {
        Ok(FontId(1))
    }

    fn font_metrics(&self, _font_id: FontId) -> FontMetrics {
        FontMetrics {
            units_per_em: 1000,
            ascent: 1025.0,
            descent: -275.0,
            line_gap: 0.0,
            underline_position: -95.0,
            underline_thickness: 60.0,
            cap_height: 698.0,
            x_height: 516.0,
            bounding_box: Bounds {
                origin: Point {
                    x: -260.0,
                    y: -245.0,
                },
                size: Size {
                    width: 1501.0,
                    height: 1364.0,
                },
            },
        }
    }

    fn typographic_bounds(&self, _font_id: FontId, _glyph_id: GlyphId) -> Result<Bounds<f32>> {
        Ok(Bounds {
            origin: Point { x: 54.0, y: 0.0 },
            size: size(392.0, 528.0),
        })
    }

    fn advance(&self, _font_id: FontId, glyph_id: GlyphId) -> Result<Size<f32>> {
        Ok(size(600.0 * glyph_id.0 as f32, 0.0))
    }

    fn glyph_for_char(&self, _font_id: FontId, ch: char) -> Option<GlyphId> {
        Some(GlyphId(ch.len_utf16() as u32))
    }

    fn glyph_raster_bounds(&self, _params: &RenderGlyphParams) -> Result<Bounds<DevicePixels>> {
        Ok(Default::default())
    }

    fn rasterize_glyph(
        &self,
        _params: &RenderGlyphParams,
        raster_bounds: Bounds<DevicePixels>,
    ) -> Result<(Size<DevicePixels>, Vec<u8>)> {
        Ok((raster_bounds.size, Vec::new()))
    }

    fn layout_line(&self, text: &str, font_size: Pixels, _runs: &[FontRun]) -> LineLayout {
        let mut position = px(0.);
        let metrics = self.font_metrics(FontId(0));
        let em_width = font_size
            * self
                .advance(FontId(0), self.glyph_for_char(FontId(0), 'm').unwrap())
                .unwrap()
                .width
            / metrics.units_per_em as f32;
        let mut glyphs = Vec::new();
        for (ix, c) in text.char_indices() {
            if let Some(glyph) = self.glyph_for_char(FontId(0), c) {
                glyphs.push(ShapedGlyph {
                    id: glyph,
                    position: point(position, px(0.)),
                    index: ix,
                    is_emoji: glyph.0 == 2,
                });
                if glyph.0 == 2 {
                    position += em_width * 2.0;
                } else {
                    position += em_width;
                }
            } else {
                position += em_width
            }
        }
        let mut runs = Vec::default();
        if !glyphs.is_empty() {
            runs.push(ShapedRun {
                font_id: FontId(0),
                glyphs,
            });
        } else {
            position = px(0.);
        }

        LineLayout {
            font_size,
            width: position,
            ascent: font_size * (metrics.ascent / metrics.units_per_em as f32),
            descent: font_size * (metrics.descent / metrics.units_per_em as f32),
            runs,
            len: text.len(),
        }
    }
}

#[derive(PartialEq, Eq, Hash, Clone)]
#[allow(missing_docs)]
pub enum AtlasKey {
    Glyph(RenderGlyphParams),
    Svg(RenderSvgParams),
    Image(RenderImageParams),
}

#[allow(missing_docs)]
impl AtlasKey {
    #[cfg_attr(
        all(
            any(target_os = "linux", target_os = "freebsd"),
            not(any(feature = "x11", feature = "wayland"))
        ),
        allow(dead_code)
    )]
    pub fn texture_kind(&self) -> AtlasTextureKind {
        match self {
            AtlasKey::Glyph(params) => {
                if params.is_emoji {
                    AtlasTextureKind::Polychrome
                } else {
                    AtlasTextureKind::Monochrome
                }
            }
            AtlasKey::Svg(_) => AtlasTextureKind::Monochrome,
            AtlasKey::Image(_) => AtlasTextureKind::Polychrome,
        }
    }
}

impl From<RenderGlyphParams> for AtlasKey {
    fn from(params: RenderGlyphParams) -> Self {
        Self::Glyph(params)
    }
}

impl From<RenderSvgParams> for AtlasKey {
    fn from(params: RenderSvgParams) -> Self {
        Self::Svg(params)
    }
}

impl From<RenderImageParams> for AtlasKey {
    fn from(params: RenderImageParams) -> Self {
        Self::Image(params)
    }
}

#[allow(missing_docs)]
pub trait PlatformAtlas: Send + Sync {
    fn get_or_insert_with<'a>(
        &self,
        key: &AtlasKey,
        build: &mut dyn FnMut() -> Result<Option<(Size<DevicePixels>, Cow<'a, [u8]>)>>,
    ) -> Result<Option<AtlasTile>>;
    fn remove(&self, key: &AtlasKey);
}

#[doc(hidden)]
pub struct AtlasTextureList<T> {
    pub textures: Vec<Option<T>>,
    pub free_list: Vec<usize>,
}

impl<T> Default for AtlasTextureList<T> {
    fn default() -> Self {
        Self {
            textures: Vec::default(),
            free_list: Vec::default(),
        }
    }
}

impl<T> ops::Index<usize> for AtlasTextureList<T> {
    type Output = Option<T>;

    fn index(&self, index: usize) -> &Self::Output {
        &self.textures[index]
    }
}

#[allow(missing_docs)]
impl<T> AtlasTextureList<T> {
    #[allow(unused)]
    pub fn drain(&mut self) -> std::vec::Drain<'_, Option<T>> {
        self.free_list.clear();
        self.textures.drain(..)
    }

    #[allow(dead_code)]
    pub fn iter_mut(&mut self) -> impl DoubleEndedIterator<Item = &mut T> {
        self.textures.iter_mut().flatten()
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(C)]
#[allow(missing_docs)]
pub struct AtlasTile {
    pub texture_id: AtlasTextureId,
    pub tile_id: TileId,
    pub padding: u32,
    pub bounds: Bounds<DevicePixels>,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[repr(C)]
#[allow(missing_docs)]
pub struct AtlasTextureId {
    // We use u32 instead of usize for Metal Shader Language compatibility
    pub index: u32,
    pub kind: AtlasTextureKind,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[repr(C)]
#[cfg_attr(
    all(
        any(target_os = "linux", target_os = "freebsd"),
        not(any(feature = "x11", feature = "wayland"))
    ),
    allow(dead_code)
)]
#[allow(missing_docs)]
pub enum AtlasTextureKind {
    Monochrome = 0,
    Polychrome = 1,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
#[repr(C)]
#[allow(missing_docs)]
pub struct TileId(pub u32);

impl From<etagere::AllocId> for TileId {
    fn from(id: etagere::AllocId) -> Self {
        Self(id.serialize())
    }
}

impl From<TileId> for etagere::AllocId {
    fn from(id: TileId) -> Self {
        Self::deserialize(id.0)
    }
}

#[allow(missing_docs)]
pub struct PlatformInputHandler {
    cx: AsyncWindowContext,
    handler: Box<dyn InputHandler>,
}

#[cfg_attr(
    all(
        any(target_os = "linux", target_os = "freebsd"),
        not(any(feature = "x11", feature = "wayland"))
    ),
    allow(dead_code)
)]
#[allow(missing_docs)]
impl PlatformInputHandler {
    pub fn new(cx: AsyncWindowContext, handler: Box<dyn InputHandler>) -> Self {
        Self { cx, handler }
    }

    fn mark_keyboard_input(window: &Window) {
        window.input_rate_tracker.borrow_mut().record_input();
        window.last_input_was_keyboard.set(true);
    }

    pub fn selected_text_range(&mut self, ignore_disabled_input: bool) -> Option<UTF16Selection> {
        self.cx
            .update(|window, cx| {
                self.handler
                    .selected_text_range(ignore_disabled_input, window, cx)
            })
            .ok()
            .flatten()
    }

    #[cfg_attr(target_os = "windows", allow(dead_code))]
    pub fn marked_text_range(&mut self) -> Option<Range<usize>> {
        self.cx
            .update(|window, cx| self.handler.marked_text_range(window, cx))
            .ok()
            .flatten()
    }

    #[cfg_attr(
        any(target_os = "linux", target_os = "freebsd", target_os = "windows"),
        allow(dead_code)
    )]
    pub fn text_for_range(
        &mut self,
        range_utf16: Range<usize>,
        adjusted: &mut Option<Range<usize>>,
    ) -> Option<String> {
        self.cx
            .update(|window, cx| {
                self.handler
                    .text_for_range(range_utf16, adjusted, window, cx)
            })
            .ok()
            .flatten()
    }

    pub fn replace_text_in_range(&mut self, replacement_range: Option<Range<usize>>, text: &str) {
        self.cx
            .update(|window, cx| {
                Self::mark_keyboard_input(window);
                self.handler
                    .replace_text_in_range(replacement_range, text, window, cx);
            })
            .ok();
    }

    pub fn replace_and_mark_text_in_range(
        &mut self,
        range_utf16: Option<Range<usize>>,
        new_text: &str,
        new_selected_range: Option<Range<usize>>,
    ) {
        self.cx
            .update(|window, cx| {
                Self::mark_keyboard_input(window);
                self.handler.replace_and_mark_text_in_range(
                    range_utf16,
                    new_text,
                    new_selected_range,
                    window,
                    cx,
                )
            })
            .ok();
    }

    #[cfg_attr(target_os = "windows", allow(dead_code))]
    pub fn unmark_text(&mut self) {
        self.cx
            .update(|window, cx| {
                Self::mark_keyboard_input(window);
                self.handler.unmark_text(window, cx)
            })
            .ok();
    }

    pub fn bounds_for_range(&mut self, range_utf16: Range<usize>) -> Option<Bounds<Pixels>> {
        self.cx
            .update(|window, cx| self.handler.bounds_for_range(range_utf16, window, cx))
            .ok()
            .flatten()
    }

    #[allow(dead_code)]
    pub fn apple_press_and_hold_enabled(&mut self) -> bool {
        self.handler.apple_press_and_hold_enabled()
    }

    pub(crate) fn dispatch_input(&mut self, input: &str, window: &mut Window, cx: &mut App) {
        // Note: record_input() is already called by dispatch_event for the key event
        // that triggered this text insertion, so we only update last_input_was_keyboard here.
        window.last_input_was_keyboard.set(true);
        self.handler.replace_text_in_range(None, input, window, cx);
    }

    pub fn compute_ime_candidate_bounds(
        marked_range: Option<Range<usize>>,
        selection: &UTF16Selection,
        mut bounds_for_range: impl FnMut(Range<usize>) -> Option<Bounds<Pixels>>,
    ) -> Option<Bounds<Pixels>> {
        if let Some(marked_range) = marked_range {
            let mut line_start = marked_range.start;
            let caret = selection.range.end;
            if let Some(caret_bounds) = bounds_for_range(caret..caret) {
                for i in (marked_range.start..caret).rev() {
                    if let Some(bounds) = bounds_for_range(i..i)
                        && (bounds.origin.y - caret_bounds.origin.y).abs() > px(0.1)
                    {
                        line_start = i + 1;
                        break;
                    }
                }
            }
            bounds_for_range(line_start..line_start)
        } else {
            let offset = if selection.reversed {
                selection.range.start
            } else {
                selection.range.end
            };
            bounds_for_range(offset..offset)
        }
    }

    pub fn selected_bounds(&mut self, window: &mut Window, cx: &mut App) -> Option<Bounds<Pixels>> {
        let marked_range = self.handler.marked_text_range(window, cx);
        let selection = self.handler.selected_text_range(true, window, cx)?;
        Self::compute_ime_candidate_bounds(marked_range, &selection, |range| {
            self.handler.bounds_for_range(range, window, cx)
        })
    }

    #[allow(dead_code)]
    pub fn ime_candidate_bounds(&mut self) -> Option<Bounds<Pixels>> {
        let marked_range = self.marked_text_range();
        let selection = self.selected_text_range(true)?;
        Self::compute_ime_candidate_bounds(marked_range, &selection, |range| {
            self.bounds_for_range(range)
        })
    }

    #[allow(unused)]
    pub fn character_index_for_point(&mut self, point: Point<Pixels>) -> Option<usize> {
        self.cx
            .update(|window, cx| self.handler.character_index_for_point(point, window, cx))
            .ok()
            .flatten()
    }

    #[allow(dead_code)]
    pub fn accepts_text_input(&mut self, window: &mut Window, cx: &mut App) -> bool {
        self.handler.accepts_text_input(window, cx)
    }

    #[allow(dead_code)]
    pub fn query_accepts_text_input(&mut self) -> bool {
        self.cx
            .update(|window, cx| self.handler.accepts_text_input(window, cx))
            .unwrap_or(true)
    }
}

/// A struct representing a selection in a text buffer, in UTF16 characters.
/// This is different from a range because the head may be before the tail.
#[derive(Debug)]
pub struct UTF16Selection {
    /// The range of text in the document this selection corresponds to
    /// in UTF16 characters.
    pub range: Range<usize>,
    /// Whether the head of this selection is at the start (true), or end (false)
    /// of the range
    pub reversed: bool,
}

/// Zed's interface for handling text input from the platform's IME system
/// This is currently a 1:1 exposure of the NSTextInputClient API:
///
/// <https://developer.apple.com/documentation/appkit/nstextinputclient>
pub trait InputHandler: 'static {
    /// Get the range of the user's currently selected text, if any
    /// Corresponds to [selectedRange()](https://developer.apple.com/documentation/appkit/nstextinputclient/1438242-selectedrange)
    ///
    /// Return value is in terms of UTF-16 characters, from 0 to the length of the document
    fn selected_text_range(
        &mut self,
        ignore_disabled_input: bool,
        window: &mut Window,
        cx: &mut App,
    ) -> Option<UTF16Selection>;

    /// Get the range of the currently marked text, if any
    /// Corresponds to [markedRange()](https://developer.apple.com/documentation/appkit/nstextinputclient/1438250-markedrange)
    ///
    /// Return value is in terms of UTF-16 characters, from 0 to the length of the document
    fn marked_text_range(&mut self, window: &mut Window, cx: &mut App) -> Option<Range<usize>>;

    /// Get the text for the given document range in UTF-16 characters
    /// Corresponds to [attributedSubstring(forProposedRange: actualRange:)](https://developer.apple.com/documentation/appkit/nstextinputclient/1438238-attributedsubstring)
    ///
    /// range_utf16 is in terms of UTF-16 characters
    fn text_for_range(
        &mut self,
        range_utf16: Range<usize>,
        adjusted_range: &mut Option<Range<usize>>,
        window: &mut Window,
        cx: &mut App,
    ) -> Option<String>;

    /// Replace the text in the given document range with the given text
    /// Corresponds to [insertText(_:replacementRange:)](https://developer.apple.com/documentation/appkit/nstextinputclient/1438258-inserttext)
    ///
    /// replacement_range is in terms of UTF-16 characters
    fn replace_text_in_range(
        &mut self,
        replacement_range: Option<Range<usize>>,
        text: &str,
        window: &mut Window,
        cx: &mut App,
    );

    /// Replace the text in the given document range with the given text,
    /// and mark the given text as part of an IME 'composing' state
    /// Corresponds to [setMarkedText(_:selectedRange:replacementRange:)](https://developer.apple.com/documentation/appkit/nstextinputclient/1438246-setmarkedtext)
    ///
    /// range_utf16 is in terms of UTF-16 characters
    /// new_selected_range is in terms of UTF-16 characters
    fn replace_and_mark_text_in_range(
        &mut self,
        range_utf16: Option<Range<usize>>,
        new_text: &str,
        new_selected_range: Option<Range<usize>>,
        window: &mut Window,
        cx: &mut App,
    );

    /// Remove the IME 'composing' state from the document
    /// Corresponds to [unmarkText()](https://developer.apple.com/documentation/appkit/nstextinputclient/1438239-unmarktext)
    fn unmark_text(&mut self, window: &mut Window, cx: &mut App);

    /// Get the bounds of the given document range in screen coordinates
    /// Corresponds to [firstRect(forCharacterRange:actualRange:)](https://developer.apple.com/documentation/appkit/nstextinputclient/1438240-firstrect)
    ///
    /// This is used for positioning the IME candidate window
    fn bounds_for_range(
        &mut self,
        range_utf16: Range<usize>,
        window: &mut Window,
        cx: &mut App,
    ) -> Option<Bounds<Pixels>>;

    /// Get the character offset for the given point in terms of UTF16 characters
    ///
    /// Corresponds to [characterIndexForPoint:](https://developer.apple.com/documentation/appkit/nstextinputclient/characterindex(for:))
    fn character_index_for_point(
        &mut self,
        point: Point<Pixels>,
        window: &mut Window,
        cx: &mut App,
    ) -> Option<usize>;

    /// Allows a given input context to opt into getting raw key repeats instead of
    /// sending these to the platform.
    /// TODO: Ideally we should be able to set ApplePressAndHoldEnabled in NSUserDefaults
    /// (which is how iTerm does it) but it doesn't seem to work for me.
    #[allow(dead_code)]
    fn apple_press_and_hold_enabled(&mut self) -> bool {
        true
    }

    /// Returns whether this handler is accepting text input to be inserted.
    fn accepts_text_input(&mut self, _window: &mut Window, _cx: &mut App) -> bool {
        true
    }
}

/// The variables that can be configured when creating a new window
#[derive(Debug)]
pub struct WindowOptions {
    /// Specifies the state and bounds of the window in screen coordinates.
    /// - `None`: Inherit the bounds.
    /// - `Some(WindowBounds)`: Open a window with corresponding state and its restore size.
    pub window_bounds: Option<WindowBounds>,

    /// The titlebar configuration of the window
    pub titlebar: Option<TitlebarOptions>,

    /// Whether the window should be focused when created
    pub focus: bool,

    /// Whether the window should be shown when created
    pub show: bool,

    /// The kind of window to create
    pub kind: WindowKind,

    /// Whether the window should be movable by the user.
    pub is_movable: bool,

    /// Whether the application owns dragging of its custom titlebar on macOS.
    ///
    /// This prevents AppKit from claiming the titlebar region or delaying clicks,
    /// while leaving `is_movable` enabled for application-driven window moves.
    pub app_owns_titlebar_drag: bool,

    /// The minimum interval between animation frames while the window is inactive.
    ///
    /// Set to `None` to disable inactive-window animation frame throttling.
    /// Overlay, HUD, and daemon windows that keep animating while unfocused
    /// can set a shorter interval (or `None`) here.
    pub inactive_frame_interval: Option<Duration>,

    /// Whether the window should be resizable by the user
    pub is_resizable: bool,

    /// Whether the window should be minimized by the user
    pub is_minimizable: bool,

    /// The display to create the window on, if this is None,
    /// the window will be created on the main display
    pub display_id: Option<DisplayId>,

    /// The appearance of the window background.
    pub window_background: WindowBackgroundAppearance,

    /// Application identifier of the window. Can by used by desktop environments to group applications together.
    pub app_id: Option<String>,

    /// Window minimum size
    pub window_min_size: Option<Size<Pixels>>,

    /// Whether to use client or server side decorations. Wayland only
    /// Note that this may be ignored.
    pub window_decorations: Option<WindowDecorations>,

    /// Tab group name, allows opening the window as a native tab on macOS 10.12+. Windows with the same tabbing identifier will be grouped together.
    pub tabbing_identifier: Option<String>,

    /// Whether the window should allow mouse events to pass through to windows behind it
    pub mouse_passthrough: bool,

    /// Optional window icon (currently consumed only on X11; ignored elsewhere)
    pub icon: Option<image::RgbaImage>,
}

/// The variables that can be configured when creating a new window
#[derive(Debug)]
#[cfg_attr(
    all(
        any(target_os = "linux", target_os = "freebsd"),
        not(any(feature = "x11", feature = "wayland"))
    ),
    allow(dead_code)
)]
#[allow(missing_docs)]
pub struct WindowParams {
    pub bounds: Bounds<Pixels>,

    /// The titlebar configuration of the window
    #[cfg_attr(feature = "wayland", allow(dead_code))]
    pub titlebar: Option<TitlebarOptions>,

    /// The kind of window to create
    #[cfg_attr(any(target_os = "linux", target_os = "freebsd"), allow(dead_code))]
    pub kind: WindowKind,

    /// Whether the window should be movable by the user
    #[cfg_attr(any(target_os = "linux", target_os = "freebsd"), allow(dead_code))]
    pub is_movable: bool,

    /// Whether the application owns custom-titlebar dragging on macOS.
    #[cfg_attr(
        any(target_os = "linux", target_os = "freebsd", target_os = "windows"),
        allow(dead_code)
    )]
    pub app_owns_titlebar_drag: bool,

    /// Whether the window should be resizable by the user
    #[cfg_attr(any(target_os = "linux", target_os = "freebsd"), allow(dead_code))]
    pub is_resizable: bool,

    /// Whether the window should be minimized by the user
    #[cfg_attr(any(target_os = "linux", target_os = "freebsd"), allow(dead_code))]
    pub is_minimizable: bool,

    #[cfg_attr(
        any(target_os = "linux", target_os = "freebsd", target_os = "windows"),
        allow(dead_code)
    )]
    pub focus: bool,

    #[cfg_attr(
        any(target_os = "linux", target_os = "freebsd", target_os = "windows"),
        allow(dead_code)
    )]
    pub app_id: Option<String>,

    #[cfg_attr(any(target_os = "linux", target_os = "freebsd"), allow(dead_code))]
    pub show: bool,

    #[cfg_attr(feature = "wayland", allow(dead_code))]
    pub display_id: Option<DisplayId>,

    pub window_min_size: Option<Size<Pixels>>,
    #[cfg(target_os = "macos")]
    pub tabbing_identifier: Option<String>,

    #[allow(dead_code)]
    pub mouse_passthrough: bool,

    /// Optional window icon (primarily for X11)
    #[cfg_attr(not(any(target_os = "linux", target_os = "freebsd")), allow(dead_code))]
    pub icon: Option<image::RgbaImage>,
}

/// The window corner or edge that stays fixed on screen when the window is
/// resized via [`PlatformWindow::resize_anchored`] / [`crate::Window::resize_anchored`].
///
/// Named from the viewer's perspective: `TopLeft` pins the visually top-left
/// corner, so a tray popup below the menu bar grows down and to the right.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ResizeAnchor {
    /// Keep the visually top-left corner fixed; the window grows down-right.
    TopLeft,
    /// Keep the top edge's midpoint fixed; the window grows downward.
    Top,
    /// Keep the visually top-right corner fixed; the window grows down-left.
    TopRight,
    /// Keep the left edge's midpoint fixed; the window grows rightward.
    Left,
    /// Keep the center fixed; the window grows outward.
    Center,
    /// Keep the right edge's midpoint fixed; the window grows leftward.
    Right,
    /// Keep the visually bottom-left corner fixed; the window grows up-right.
    BottomLeft,
    /// Keep the bottom edge's midpoint fixed; the window grows upward.
    Bottom,
    /// Keep the visually bottom-right corner fixed; the window grows up-left.
    BottomRight,
}

/// Represents the status of how a window should be opened.
#[derive(Debug, Copy, Clone, PartialEq)]
pub enum WindowBounds {
    /// Indicates that the window should open in a windowed state with the given bounds.
    Windowed(Bounds<Pixels>),
    /// Indicates that the window should open in a maximized state.
    /// The bounds provided here represent the restore size of the window.
    Maximized(Bounds<Pixels>),
    /// Indicates that the window should open in fullscreen mode.
    /// The bounds provided here represent the restore size of the window.
    Fullscreen(Bounds<Pixels>),
}

impl Default for WindowBounds {
    fn default() -> Self {
        WindowBounds::Windowed(Bounds::default())
    }
}

impl WindowBounds {
    /// Retrieve the inner bounds
    pub fn get_bounds(&self) -> Bounds<Pixels> {
        match self {
            WindowBounds::Windowed(bounds) => *bounds,
            WindowBounds::Maximized(bounds) => *bounds,
            WindowBounds::Fullscreen(bounds) => *bounds,
        }
    }

    /// Creates windowed bounds centered in the primary display's work area.
    ///
    /// Delegates to [`Bounds::centered`], so the size is clamped with [`Size::min`]
    /// and the origin uses `visible_bounds` rather than the full display.
    pub fn centered(size: Size<Pixels>, cx: &App) -> Self {
        WindowBounds::Windowed(Bounds::centered(None, size, cx))
    }
}

impl Default for WindowOptions {
    fn default() -> Self {
        Self {
            window_bounds: None,
            titlebar: Some(TitlebarOptions {
                title: Default::default(),
                appears_transparent: Default::default(),
                traffic_light_position: Default::default(),
            }),
            focus: true,
            show: true,
            kind: WindowKind::Normal,
            is_movable: true,
            app_owns_titlebar_drag: false,
            inactive_frame_interval: Some(Duration::from_micros(33_333)),
            is_resizable: true,
            is_minimizable: true,
            display_id: None,
            window_background: WindowBackgroundAppearance::default(),
            app_id: None,
            window_min_size: None,
            window_decorations: None,
            tabbing_identifier: None,
            mouse_passthrough: false,
            icon: None,
        }
    }
}

#[cfg(test)]
mod platform_input_handler_tests {
    use super::*;
    use crate::{
        AppContext, Context, ElementInputHandler, Empty, EntityInputHandler, TestAppContext,
    };

    struct RejectingEntityInputHandler;

    impl EntityInputHandler for RejectingEntityInputHandler {
        fn text_for_range(
            &mut self,
            _range: Range<usize>,
            _adjusted_range: &mut Option<Range<usize>>,
            _window: &mut Window,
            _cx: &mut Context<Self>,
        ) -> Option<String> {
            None
        }

        fn selected_text_range(
            &mut self,
            _ignore_disabled_input: bool,
            _window: &mut Window,
            _cx: &mut Context<Self>,
        ) -> Option<UTF16Selection> {
            None
        }

        fn marked_text_range(
            &self,
            _window: &mut Window,
            _cx: &mut Context<Self>,
        ) -> Option<Range<usize>> {
            None
        }

        fn unmark_text(&mut self, _window: &mut Window, _cx: &mut Context<Self>) {}

        fn replace_text_in_range(
            &mut self,
            _range: Option<Range<usize>>,
            _text: &str,
            _window: &mut Window,
            _cx: &mut Context<Self>,
        ) {
        }

        fn replace_and_mark_text_in_range(
            &mut self,
            _range: Option<Range<usize>>,
            _new_text: &str,
            _new_selected_range: Option<Range<usize>>,
            _window: &mut Window,
            _cx: &mut Context<Self>,
        ) {
        }

        fn bounds_for_range(
            &mut self,
            _range_utf16: Range<usize>,
            _element_bounds: Bounds<Pixels>,
            _window: &mut Window,
            _cx: &mut Context<Self>,
        ) -> Option<Bounds<Pixels>> {
            None
        }

        fn character_index_for_point(
            &mut self,
            _point: Point<Pixels>,
            _window: &mut Window,
            _cx: &mut Context<Self>,
        ) -> Option<usize> {
            None
        }

        fn accepts_text_input(&self, _window: &mut Window, _cx: &mut Context<Self>) -> bool {
            false
        }
    }

    #[gpui_macros::test]
    fn element_input_handler_forwards_text_input_rejection(cx: &mut TestAppContext) {
        let entity = cx.new(|_| RejectingEntityInputHandler);
        let window = cx.add_window(|_, _| Empty);

        cx.update_window(window.into(), |_, window, cx| {
            let mut handler = ElementInputHandler::new(Bounds::default(), entity);
            assert!(!handler.accepts_text_input(window, cx));
        })
        .unwrap();
    }

    #[gpui_macros::test]
    fn platform_input_handler_accepts_text_when_window_update_fails(cx: &mut TestAppContext) {
        let entity = cx.new(|_| RejectingEntityInputHandler);
        let window = cx.add_window(|_, _| Empty);
        let window = AnyWindowHandle::from(window);
        let async_cx = cx
            .update_window(window, |_, window, cx| window.to_async(cx))
            .unwrap();

        cx.update_window(window, |_, window, _| window.remove_window())
            .unwrap();
        assert!(cx.update_window(window, |_, _, _| ()).is_err());

        let mut handler = PlatformInputHandler::new(
            async_cx,
            Box::new(ElementInputHandler::new(Bounds::default(), entity)),
        );
        assert!(handler.query_accepts_text_input());
    }

    fn bounds_at(offset: usize, y: f32) -> Bounds<Pixels> {
        Bounds::new(
            point(px(offset as f32 * 10.0), px(y)),
            size(px(1.0), px(20.0)),
        )
    }

    #[test]
    fn ime_candidate_bounds_uses_selection_endpoint_without_marked_range() {
        let selection = UTF16Selection {
            range: 3..5,
            reversed: false,
        };
        let mut requests = Vec::new();
        let bounds =
            PlatformInputHandler::compute_ime_candidate_bounds(None, &selection, |range| {
                requests.push(range.clone());
                Some(bounds_at(range.start, 0.0))
            })
            .unwrap();

        assert_eq!(bounds.origin.x, px(50.0));
        assert_eq!(requests, vec![5..5]);

        let selection = UTF16Selection {
            range: 3..5,
            reversed: true,
        };
        let bounds =
            PlatformInputHandler::compute_ime_candidate_bounds(None, &selection, |range| {
                Some(bounds_at(range.start, 0.0))
            })
            .unwrap();

        assert_eq!(bounds.origin.x, px(30.0));
    }

    #[test]
    fn ime_candidate_bounds_anchors_marked_text_to_visual_line_start() {
        let selection = UTF16Selection {
            range: 15..15,
            reversed: false,
        };
        let mut requests = Vec::new();
        let bounds =
            PlatformInputHandler::compute_ime_candidate_bounds(Some(10..15), &selection, |range| {
                requests.push(range.clone());
                let y = if range.start >= 13 { 20.0 } else { 0.0 };
                Some(bounds_at(range.start, y))
            })
            .unwrap();

        assert_eq!(bounds.origin.x, px(130.0));
        assert_eq!(requests.last(), Some(&(13..13)));
    }
}

/// The options that can be configured for a window's titlebar
#[derive(Debug, Default)]
pub struct TitlebarOptions {
    /// The initial title of the window
    pub title: Option<SharedString>,

    /// Should the default system titlebar be hidden to allow for a custom-drawn titlebar? (macOS and Windows only)
    /// Refer to [`WindowOptions::window_decorations`] on Linux
    pub appears_transparent: bool,

    /// The position of the macOS traffic light buttons
    pub traffic_light_position: Option<Point<Pixels>>,
}

/// The kind of window to create
#[derive(Clone, Debug, PartialEq)]
pub enum WindowKind {
    /// A normal application window
    Normal,

    /// A window that appears above all other windows, usually used for alerts or popups
    /// use sparingly!
    PopUp,

    /// A floating window that appears on top of its parent window
    Floating,

    /// An overlay window that appears above all other windows, including fullscreen apps
    Overlay,

    /// A Wayland layer-shell window, used for overlays or backgrounds such as docks,
    /// notifications, and wallpapers.
    #[cfg(all(any(target_os = "linux", target_os = "freebsd"), feature = "wayland"))]
    LayerShell(layer_shell::LayerShellOptions),
}

/// The appearance of the window, as defined by the operating system.
///
/// On macOS, this corresponds to named [`NSAppearance`](https://developer.apple.com/documentation/appkit/nsappearance)
/// values.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
pub enum WindowAppearance {
    /// A light appearance.
    ///
    /// On macOS, this corresponds to the `aqua` appearance.
    #[default]
    Light,

    /// A light appearance with vibrant colors.
    ///
    /// On macOS, this corresponds to the `NSAppearanceNameVibrantLight` appearance.
    VibrantLight,

    /// A dark appearance.
    ///
    /// On macOS, this corresponds to the `darkAqua` appearance.
    Dark,

    /// A dark appearance with vibrant colors.
    ///
    /// On macOS, this corresponds to the `NSAppearanceNameVibrantDark` appearance.
    VibrantDark,
}

/// The appearance of the background of the window itself, when there is
/// no content or the content is transparent.
#[derive(Copy, Clone, Debug, Default, PartialEq)]
pub enum WindowBackgroundAppearance {
    /// Opaque.
    ///
    /// This lets the window manager know that content behind this
    /// window does not need to be drawn.
    ///
    /// Actual color depends on the system and themes should define a fully
    /// opaque background color instead.
    #[default]
    Opaque,
    /// Plain alpha transparency.
    Transparent,
    /// Transparency, but the contents behind the window are blurred.
    ///
    /// Not always supported.
    Blurred,
}

/// Controls how a system tray icon should be rendered.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub enum TrayIconRenderingMode {
    /// Render using the platform's default status icon appearance.
    ///
    /// On macOS, this uses template rendering so the icon adapts to the menu bar appearance.
    #[default]
    Adaptive,
    /// Render the icon with its original colors when supported by the platform.
    ///
    /// On macOS, this disables template rendering.
    Original,
}

/// Events that can occur on a system tray icon.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum TrayIconEvent {
    /// The user left-clicked the tray icon.
    LeftClick,
    /// The user right-clicked the tray icon.
    RightClick,
    /// The user double-clicked the tray icon.
    DoubleClick,
}

/// A tray icon click event with optional screen position information.
#[derive(Debug, Clone, PartialEq)]
pub struct TrayIconClickEvent {
    /// The kind of click that occurred.
    pub kind: TrayIconEvent,
    /// The click position in GPUI logical screen coordinates, if the platform provides it.
    ///
    /// Linux StatusNotifierItem provides a raw screen-coordinate hint; GPUI
    /// converts that hint through the active display scale before exposing it.
    /// On Wayland fractional scaling, the hint has no surface association, so
    /// conversion uses the integer output scale and may remain approximate.
    pub position: Option<Point<Pixels>>,
}

impl TrayIconClickEvent {
    /// Create a tray click event without position information.
    pub fn new(kind: TrayIconEvent) -> Self {
        Self {
            kind,
            position: None,
        }
    }

    /// Create a tray click event with a logical screen-coordinate hint.
    pub fn with_position(kind: TrayIconEvent, position: Point<Pixels>) -> Self {
        Self {
            kind,
            position: Some(position),
        }
    }
}

#[allow(missing_docs)]
#[derive(Debug, Clone, PartialEq)]
pub struct TrayAnchor {
    pub display_id: DisplayId,
    pub bounds: Bounds<Pixels>,
}

/// A menu item for a system tray context menu.
#[derive(Debug, Clone)]
pub enum TrayMenuItem {
    /// A clickable action item.
    Action {
        /// The display label.
        label: SharedString,
        /// A unique identifier for this action.
        id: SharedString,
    },
    /// A visual separator between menu items.
    Separator,
    /// A submenu containing nested items.
    Submenu {
        /// The display label.
        label: SharedString,
        /// The nested menu items.
        items: Vec<TrayMenuItem>,
    },
    /// A toggleable menu item with a checkmark.
    Toggle {
        /// The display label.
        label: SharedString,
        /// Whether the item is currently checked.
        checked: bool,
        /// A unique identifier for this toggle.
        id: SharedString,
    },
}

/// Information about the currently focused window from any application.
#[derive(Debug, Clone)]
pub struct FocusedWindowInfo {
    /// The name of the application that owns the focused window.
    pub app_name: String,
    /// The title of the focused window.
    pub window_title: String,
    /// The bundle identifier of the application (macOS only).
    pub bundle_id: Option<String>,
    /// The process ID of the application.
    pub pid: Option<u32>,
}

/// The status of a system permission.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PermissionStatus {
    /// Permission has been granted.
    Granted,
    /// Permission has been denied.
    Denied,
    /// Permission has not yet been requested.
    NotDetermined,
    /// The platform does not expose this permission capability.
    Unavailable,
}

/// Whether the platform accepted a permission request.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PermissionRequestStatus {
    /// The platform accepted the request and will resolve it through its normal flow.
    Requested,
    /// The platform does not expose this permission request.
    Unavailable,
}

/// System power state change events.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SystemPowerEvent {
    /// The system is about to suspend/sleep.
    Suspend,
    /// The system has resumed from suspend/sleep.
    Resume,
    /// The screen has been locked.
    LockScreen,
    /// The screen has been unlocked.
    UnlockScreen,
    /// The system is shutting down.
    Shutdown,
}

/// The kind of power save blocker to create.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PowerSaveBlockerKind {
    /// Prevent the application from being suspended.
    PreventAppSuspension,
    /// Prevent the display from sleeping.
    PreventDisplaySleep,
}

/// The current network connectivity status.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NetworkStatus {
    /// The system has network connectivity.
    Online,
    /// The system has no network connectivity.
    Offline,
}

/// Media key events from hardware media keys or OS media controls.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MediaKeyEvent {
    /// Play media.
    Play,
    /// Pause media.
    Pause,
    /// Toggle play/pause.
    PlayPause,
    /// Stop media playback.
    Stop,
    /// Skip to the next track.
    NextTrack,
    /// Skip to the previous track.
    PreviousTrack,
}

/// The type of user attention to request from the OS.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AttentionType {
    /// An informational attention request (e.g. bounce dock icon once).
    Informational,
    /// A critical attention request (e.g. bounce dock icon continuously).
    Critical,
}

/// The state of a taskbar/dock progress bar for a window.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum ProgressBarState {
    /// No progress bar is shown.
    None,
    /// An indeterminate progress bar is shown.
    Indeterminate,
    /// A normal progress bar with the given fraction (0.0 to 1.0).
    Normal(f64),
    /// An error progress bar with the given fraction (0.0 to 1.0).
    Error(f64),
    /// A paused progress bar with the given fraction (0.0 to 1.0).
    Paused(f64),
}

/// The kind of a native dialog.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DialogKind {
    /// An informational dialog.
    Info,
    /// A warning dialog.
    Warning,
    /// An error dialog.
    Error,
}

/// Options for displaying a native dialog.
#[derive(Debug, Clone)]
pub struct DialogOptions {
    /// The kind of dialog to display.
    pub kind: DialogKind,
    /// The title of the dialog.
    pub title: SharedString,
    /// The primary message of the dialog.
    pub message: SharedString,
    /// Optional detail text shown below the message.
    pub detail: Option<SharedString>,
    /// The button labels for the dialog.
    pub buttons: Vec<SharedString>,
}

/// Information about the operating system.
#[derive(Debug, Clone)]
pub struct OsInfo {
    /// The name of the operating system (e.g. "macos", "linux", "windows").
    pub name: SharedString,
    /// The version of the operating system.
    pub version: SharedString,
    /// The CPU architecture (e.g. "x86_64", "aarch64").
    pub arch: SharedString,
    /// The system locale (e.g. "en-US").
    pub locale: SharedString,
    /// The hostname of the system.
    pub hostname: SharedString,
}

/// The kind of biometric authentication available.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BiometricKind {
    /// macOS Touch ID.
    TouchId,
    /// Windows Hello.
    WindowsHello,
    /// Generic fingerprint reader.
    Fingerprint,
}

/// The availability status of biometric authentication.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BiometricStatus {
    /// Biometric authentication is available with the given kind.
    Available(BiometricKind),
    /// Biometric authentication is not available.
    Unavailable,
}

/// A snapshot of a window's state for save/restore.
#[derive(Debug, Clone, PartialEq)]
pub struct WindowState {
    /// The window bounds.
    pub bounds: WindowBounds,
    /// The display the window is on.
    pub display_id: Option<DisplayId>,
    /// Whether the window is fullscreen.
    pub fullscreen: bool,
}

/// A semantic window position for positioning windows relative to the screen.
#[derive(Debug, Clone, PartialEq)]
pub enum WindowPosition {
    /// Center the window on the primary display.
    Center,
    /// Center the window on the given display.
    CenterOnDisplay(DisplayId),
    /// Center the window above the tray icon area.
    ///
    /// Deprecated: this variant only carries the tray icon bounds and does
    /// not know which display the tray is on, which causes window placement
    /// to be off on multi-monitor setups. Prefer [`WindowPosition::TrayAnchored`],
    /// which carries a full [`TrayAnchor`] (including `display_id`).
    #[deprecated(
        since = "0.5.3",
        note = "Use `WindowPosition::TrayAnchored(TrayAnchor)` instead; the new variant carries `display_id` and fixes multi-monitor placement. This variant will be removed in a future release."
    )]
    TrayCenter(Bounds<Pixels>),
    /// Center the window above the tray icon area, using a full [`TrayAnchor`].
    ///
    /// The `TrayAnchor` carries both the tray icon `bounds` (display-local,
    /// top-left origin) and the `display_id` it resides on. Callers should
    /// also propagate `display_id` to `WindowOptions.display_id` so the
    /// window is opened on the correct screen in multi-monitor setups.
    TrayAnchored(TrayAnchor),
    /// Position the window in the top-right corner.
    TopRight {
        /// The margin from the screen edge.
        margin: Pixels,
    },
    /// Position the window in the bottom-right corner.
    BottomRight {
        /// The margin from the screen edge.
        margin: Pixels,
    },
    /// Position the window in the top-left corner.
    TopLeft {
        /// The margin from the screen edge.
        margin: Pixels,
    },
    /// Position the window in the bottom-left corner.
    BottomLeft {
        /// The margin from the screen edge.
        margin: Pixels,
    },
}

/// Information collected for a crash report.
#[derive(Debug, Clone)]
pub struct CrashReport {
    /// The error message.
    pub message: String,
    /// The backtrace at the time of the crash.
    pub backtrace: String,
    /// Information about the operating system.
    pub os_info: OsInfo,
    /// The application version, if available.
    pub app_version: Option<String>,
}

/// The options that can be configured for a file dialog prompt
#[derive(Clone, Debug)]
pub struct PathPromptOptions {
    /// Should the prompt allow files to be selected?
    pub files: bool,
    /// Should the prompt allow directories to be selected?
    pub directories: bool,
    /// Should the prompt allow multiple files to be selected?
    pub multiple: bool,
    /// The prompt to show to a user when selecting a path
    pub prompt: Option<SharedString>,
}

/// What kind of prompt styling to show
#[derive(Copy, Clone, Debug, PartialEq)]
pub enum PromptLevel {
    /// A prompt that is shown when the user should be notified of something
    Info,

    /// A prompt that is shown when the user needs to be warned of a potential problem
    Warning,

    /// A prompt that is shown when a critical problem has occurred
    Critical,
}

/// Prompt Button
#[derive(Clone, Debug, PartialEq)]
pub enum PromptButton {
    /// Ok button
    Ok(SharedString),
    /// Cancel button
    Cancel(SharedString),
    /// Other button
    Other(SharedString),
}

impl PromptButton {
    /// Create a button with label
    pub fn new(label: impl Into<SharedString>) -> Self {
        PromptButton::Other(label.into())
    }

    /// Create an Ok button
    pub fn ok(label: impl Into<SharedString>) -> Self {
        PromptButton::Ok(label.into())
    }

    /// Create a Cancel button
    pub fn cancel(label: impl Into<SharedString>) -> Self {
        PromptButton::Cancel(label.into())
    }

    #[allow(dead_code)]
    #[doc(hidden)]
    pub fn is_cancel(&self) -> bool {
        matches!(self, PromptButton::Cancel(_))
    }

    /// Returns the label of the button
    pub fn label(&self) -> &SharedString {
        match self {
            PromptButton::Ok(label) => label,
            PromptButton::Cancel(label) => label,
            PromptButton::Other(label) => label,
        }
    }
}

impl From<&str> for PromptButton {
    fn from(value: &str) -> Self {
        match value.to_lowercase().as_str() {
            "ok" => PromptButton::Ok("Ok".into()),
            "cancel" => PromptButton::Cancel("Cancel".into()),
            _ => PromptButton::Other(SharedString::from(value.to_owned())),
        }
    }
}

/// The style of the cursor (pointer)
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
pub enum CursorStyle {
    /// The default cursor
    #[default]
    Arrow,

    /// A text input cursor
    /// corresponds to the CSS cursor value `text`
    IBeam,

    /// A crosshair cursor
    /// corresponds to the CSS cursor value `crosshair`
    Crosshair,

    /// A closed hand cursor
    /// corresponds to the CSS cursor value `grabbing`
    ClosedHand,

    /// An open hand cursor
    /// corresponds to the CSS cursor value `grab`
    OpenHand,

    /// A pointing hand cursor
    /// corresponds to the CSS cursor value `pointer`
    PointingHand,

    /// A resize left cursor
    /// corresponds to the CSS cursor value `w-resize`
    ResizeLeft,

    /// A resize right cursor
    /// corresponds to the CSS cursor value `e-resize`
    ResizeRight,

    /// A resize cursor to the left and right
    /// corresponds to the CSS cursor value `ew-resize`
    ResizeLeftRight,

    /// A resize up cursor
    /// corresponds to the CSS cursor value `n-resize`
    ResizeUp,

    /// A resize down cursor
    /// corresponds to the CSS cursor value `s-resize`
    ResizeDown,

    /// A resize cursor directing up and down
    /// corresponds to the CSS cursor value `ns-resize`
    ResizeUpDown,

    /// A resize cursor directing up-left and down-right
    /// corresponds to the CSS cursor value `nesw-resize`
    ResizeUpLeftDownRight,

    /// A resize cursor directing up-right and down-left
    /// corresponds to the CSS cursor value `nwse-resize`
    ResizeUpRightDownLeft,

    /// A cursor indicating that the item/column can be resized horizontally.
    /// corresponds to the CSS cursor value `col-resize`
    ResizeColumn,

    /// A cursor indicating that the item/row can be resized vertically.
    /// corresponds to the CSS cursor value `row-resize`
    ResizeRow,

    /// A text input cursor for vertical layout
    /// corresponds to the CSS cursor value `vertical-text`
    IBeamCursorForVerticalLayout,

    /// A cursor indicating that the operation is not allowed
    /// corresponds to the CSS cursor value `not-allowed`
    OperationNotAllowed,

    /// A cursor indicating that the operation will result in a link
    /// corresponds to the CSS cursor value `alias`
    DragLink,

    /// A cursor indicating that the operation will result in a copy
    /// corresponds to the CSS cursor value `copy`
    DragCopy,

    /// A cursor indicating that the operation will result in a context menu
    /// corresponds to the CSS cursor value `context-menu`
    ContextualMenu,

    /// Hide the cursor
    None,
}

/// A clipboard item that should be copied to the clipboard
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ClipboardItem {
    entries: Vec<ClipboardEntry>,
}

/// Either a ClipboardString or a ClipboardImage
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum ClipboardEntry {
    /// A string entry
    String(ClipboardString),
    /// An image entry
    Image(Image),
}

impl ClipboardItem {
    /// Create a new ClipboardItem::String with no associated metadata
    pub fn new_string(text: String) -> Self {
        Self {
            entries: vec![ClipboardEntry::String(ClipboardString::new(text))],
        }
    }

    /// Create a new ClipboardItem::String with the given text and associated metadata
    pub fn new_string_with_metadata(text: String, metadata: String) -> Self {
        Self {
            entries: vec![ClipboardEntry::String(ClipboardString {
                text,
                metadata: Some(metadata),
            })],
        }
    }

    /// Create a new ClipboardItem::String with the given text and associated metadata
    pub fn new_string_with_json_metadata<T: Serialize>(text: String, metadata: T) -> Self {
        Self {
            entries: vec![ClipboardEntry::String(
                ClipboardString::new(text).with_json_metadata(metadata),
            )],
        }
    }

    /// Create a new ClipboardItem::Image with the given image with no associated metadata
    pub fn new_image(image: &Image) -> Self {
        Self {
            entries: vec![ClipboardEntry::Image(image.clone())],
        }
    }

    /// Concatenates together all the ClipboardString entries in the item.
    /// Returns None if there were no ClipboardString entries.
    pub fn text(&self) -> Option<String> {
        let mut answer = String::new();
        let mut any_entries = false;

        for entry in self.entries.iter() {
            if let ClipboardEntry::String(ClipboardString { text, metadata: _ }) = entry {
                answer.push_str(text);
                any_entries = true;
            }
        }

        if any_entries { Some(answer) } else { None }
    }

    /// If this item is one ClipboardEntry::String, returns its metadata.
    #[cfg_attr(not(target_os = "windows"), allow(dead_code))]
    pub fn metadata(&self) -> Option<&String> {
        match self.entries().first() {
            Some(ClipboardEntry::String(clipboard_string)) if self.entries.len() == 1 => {
                clipboard_string.metadata.as_ref()
            }
            _ => None,
        }
    }

    /// Get the item's entries
    pub fn entries(&self) -> &[ClipboardEntry] {
        &self.entries
    }

    /// Get owned versions of the item's entries
    pub fn into_entries(self) -> impl Iterator<Item = ClipboardEntry> {
        self.entries.into_iter()
    }
}

impl From<ClipboardString> for ClipboardEntry {
    fn from(value: ClipboardString) -> Self {
        Self::String(value)
    }
}

impl From<String> for ClipboardEntry {
    fn from(value: String) -> Self {
        Self::from(ClipboardString::from(value))
    }
}

impl From<Image> for ClipboardEntry {
    fn from(value: Image) -> Self {
        Self::Image(value)
    }
}

impl From<ClipboardEntry> for ClipboardItem {
    fn from(value: ClipboardEntry) -> Self {
        Self {
            entries: vec![value],
        }
    }
}

impl From<String> for ClipboardItem {
    fn from(value: String) -> Self {
        Self::from(ClipboardEntry::from(value))
    }
}

impl From<Image> for ClipboardItem {
    fn from(value: Image) -> Self {
        Self::from(ClipboardEntry::from(value))
    }
}

/// One of the editor's supported image formats (e.g. PNG, JPEG) - used when dealing with images in the clipboard
#[derive(Clone, Copy, Debug, Eq, PartialEq, EnumIter, Hash)]
pub enum ImageFormat {
    // Sorted from most to least likely to be pasted into an editor,
    // which matters when we iterate through them trying to see if
    // clipboard content matches them.
    /// .png
    Png,
    /// .jpeg or .jpg
    Jpeg,
    /// .webp
    Webp,
    /// .gif
    Gif,
    /// .svg
    Svg,
    /// .bmp
    Bmp,
    /// .tif or .tiff
    Tiff,
}

impl ImageFormat {
    /// Returns the mime type for the ImageFormat
    pub const fn mime_type(self) -> &'static str {
        match self {
            ImageFormat::Png => "image/png",
            ImageFormat::Jpeg => "image/jpeg",
            ImageFormat::Webp => "image/webp",
            ImageFormat::Gif => "image/gif",
            ImageFormat::Svg => "image/svg+xml",
            ImageFormat::Bmp => "image/bmp",
            ImageFormat::Tiff => "image/tiff",
        }
    }

    /// Returns the ImageFormat for the given mime type
    pub fn from_mime_type(mime_type: &str) -> Option<Self> {
        match mime_type {
            "image/png" => Some(Self::Png),
            "image/jpeg" | "image/jpg" => Some(Self::Jpeg),
            "image/webp" => Some(Self::Webp),
            "image/gif" => Some(Self::Gif),
            "image/svg+xml" => Some(Self::Svg),
            "image/bmp" => Some(Self::Bmp),
            "image/tiff" | "image/tif" => Some(Self::Tiff),
            _ => None,
        }
    }
}

/// An image, with a format and certain bytes
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Image {
    /// The image format the bytes represent (e.g. PNG)
    pub format: ImageFormat,
    /// The raw image bytes
    pub bytes: Vec<u8>,
    /// The unique ID for the image
    id: u64,
}

impl Image {
    /// Creates an image from encoded bytes and derives its stable clipboard identifier.
    pub fn new(format: ImageFormat, bytes: Vec<u8>) -> Self {
        let id = crate::hash(&bytes);
        Self { format, bytes, id }
    }
}

impl Hash for Image {
    fn hash<H: Hasher>(&self, state: &mut H) {
        state.write_u64(self.id);
    }
}

pub(crate) fn decode_static_image(
    bytes: &[u8],
    format: image::ImageFormat,
) -> Result<SmallVec<[Frame; 1]>> {
    let decoder = image::ImageReader::with_format(Cursor::new(bytes), format)
        .into_decoder()
        .context("creating image decoder")?;
    decode_static_image_from_decoder(decoder)
}

pub(crate) fn decode_static_image_from_decoder(
    mut decoder: impl image::ImageDecoder,
) -> Result<SmallVec<[Frame; 1]>> {
    let orientation = decoder.orientation().context("reading image orientation")?;
    let mut image = DynamicImage::from_decoder(decoder).context("decoding static image")?;
    image.apply_orientation(orientation);

    let mut data = image.into_rgba8();
    for pixel in data.chunks_exact_mut(4) {
        pixel.swap(0, 2);
    }

    Ok(SmallVec::from_elem(Frame::new(data), 1))
}

impl Image {
    /// An empty image containing no data
    pub fn empty() -> Self {
        Self::from_bytes(ImageFormat::Png, Vec::new())
    }

    /// Create an image from a format and bytes
    pub fn from_bytes(format: ImageFormat, bytes: Vec<u8>) -> Self {
        Self {
            id: hash(&bytes),
            format,
            bytes,
        }
    }

    /// Get this image's ID
    pub fn id(&self) -> u64 {
        self.id
    }

    /// Use the GPUI `use_asset` API to make this image renderable
    pub fn use_render_image(
        self: Arc<Self>,
        window: &mut Window,
        cx: &mut App,
    ) -> Option<Arc<RenderImage>> {
        ImageSource::Image(self)
            .use_data(None, window, cx)
            .and_then(|result| result.ok())
    }

    /// Use the GPUI `get_asset` API to make this image renderable
    pub fn get_render_image(
        self: Arc<Self>,
        window: &mut Window,
        cx: &mut App,
    ) -> Option<Arc<RenderImage>> {
        ImageSource::Image(self)
            .get_data(None, window, cx)
            .and_then(|result| result.ok())
    }

    /// Use the GPUI `remove_asset` API to drop this image, if possible.
    pub fn remove_asset(self: Arc<Self>, cx: &mut App) {
        ImageSource::Image(self).remove_asset(cx);
    }

    /// Convert the clipboard image to an `ImageData` object.
    pub fn to_image_data(&self, svg_renderer: SvgRenderer) -> Result<Arc<RenderImage>> {
        let frames = match self.format {
            #[cfg(feature = "image-format-gif")]
            ImageFormat::Gif => {
                let decoder = GifDecoder::new(Cursor::new(&self.bytes))?;
                let mut frames = SmallVec::new();

                for frame in decoder.into_frames() {
                    let mut frame = frame?;
                    // Convert from RGBA to BGRA.
                    for pixel in frame.buffer_mut().chunks_exact_mut(4) {
                        pixel.swap(0, 2);
                    }
                    frames.push(frame);
                }

                frames
            }
            #[cfg(not(feature = "image-format-gif"))]
            ImageFormat::Gif => decode_static_image(&self.bytes, image::ImageFormat::Gif)?,
            ImageFormat::Png => decode_static_image(&self.bytes, image::ImageFormat::Png)?,
            ImageFormat::Jpeg => decode_static_image(&self.bytes, image::ImageFormat::Jpeg)?,
            ImageFormat::Webp => decode_static_image(&self.bytes, image::ImageFormat::WebP)?,
            ImageFormat::Bmp => decode_static_image(&self.bytes, image::ImageFormat::Bmp)?,
            ImageFormat::Tiff => decode_static_image(&self.bytes, image::ImageFormat::Tiff)?,
            ImageFormat::Svg => {
                return svg_renderer
                    .render_single_frame(&self.bytes, 1.0)
                    .map_err(Into::into);
            }
        };

        Ok(Arc::new(RenderImage::new(frames)))
    }

    /// Get the format of the clipboard image
    pub fn format(&self) -> ImageFormat {
        self.format
    }

    /// Get the raw bytes of the clipboard image
    pub fn bytes(&self) -> &[u8] {
        self.bytes.as_slice()
    }
}

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

    #[test]
    fn image_to_image_data_applies_exif_orientation() {
        let image = Image::from_bytes(
            ImageFormat::Jpeg,
            include_bytes!("../test_data/exif-orientation-rotate-180.jpg").to_vec(),
        );

        let render_image = image.to_image_data(SvgRenderer::new(Arc::new(()))).unwrap();

        assert_eq!(render_image.size(0), size(16.into(), 32.into()));
        let bytes = render_image.as_bytes(0).unwrap();
        assert_eq!(&bytes[..4], &[255, 255, 255, 255]);
        assert_eq!(&bytes[(16 * 32 - 1) * 4..], &[0, 0, 0, 255]);
    }
}

/// A clipboard item that should be copied to the clipboard
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ClipboardString {
    pub(crate) text: String,
    pub(crate) metadata: Option<String>,
}

impl ClipboardString {
    /// Create a new clipboard string with the given text
    pub fn new(text: String) -> Self {
        Self {
            text,
            metadata: None,
        }
    }

    /// Replace the associated metadata with an opaque string.
    #[doc(hidden)]
    pub fn with_metadata(mut self, metadata: String) -> Self {
        self.metadata = Some(metadata);
        self
    }

    /// Return a new clipboard item with the metadata replaced by the given metadata,
    /// after serializing it as JSON.
    pub fn with_json_metadata<T: Serialize>(mut self, metadata: T) -> Self {
        self.metadata = Some(serde_json::to_string(&metadata).unwrap());
        self
    }

    /// Get the text of the clipboard string
    pub fn text(&self) -> &String {
        &self.text
    }

    /// Get the owned text of the clipboard string
    pub fn into_text(self) -> String {
        self.text
    }

    /// Get the metadata of the clipboard string, formatted as JSON
    pub fn metadata_json<T>(&self) -> Option<T>
    where
        T: for<'a> Deserialize<'a>,
    {
        self.metadata
            .as_ref()
            .and_then(|m| serde_json::from_str(m).ok())
    }

    /// Returns the raw metadata string associated with this clipboard entry.
    #[doc(hidden)]
    pub fn metadata(&self) -> Option<&str> {
        self.metadata.as_deref()
    }

    #[doc(hidden)]
    pub fn text_hash(text: &str) -> u64 {
        let mut hasher = SeaHasher::new();
        text.hash(&mut hasher);
        hasher.finish()
    }
}

impl From<String> for ClipboardString {
    fn from(value: String) -> Self {
        Self {
            text: value,
            metadata: None,
        }
    }
}

#[cfg(test)]
mod clipboard_string_tests {
    use super::ClipboardString;

    #[test]
    fn raw_metadata_preserves_the_clipboard_text() {
        let clipboard_string = ClipboardString::new("copied text".to_owned())
            .with_metadata("application/x-fc-gpui".to_owned());

        assert_eq!(clipboard_string.text(), "copied text");
        assert_eq!(clipboard_string.metadata(), Some("application/x-fc-gpui"));
    }
}