//! Discovers system-native styling for colors, fonts, and other metrics.

//!

//! This module provides a best-effort attempt to query the host operating system

//! for its UI theme information. This is gated behind the **`io`** feature flag.

//!

//! **End-user customization (`AZ_RICING`):**

//! By default (if the `io` feature is enabled), Azul looks for an

//! application-specific stylesheet at `~/.config/azul/styles/<app_name>.css`

//! (or `%APPDATA%\azul\styles\<app_name>.css` on Windows) and applies it as

//! the last layer of the cascade, letting end-users "rice" any Azul app.

//!

//! The `AZ_RICING` env var has three modes (case-insensitive):

//!

//! - unset (default): load the user CSS if present; on Linux, the

//!   detection chain is `KDE > GNOME > riced > defaults`.

//! - `AZ_RICING=off` (aliases: `disabled`, `none`, `0`): skip the user

//!   CSS file and the riced-desktop sources (Hyprland config, pywal

//!   cache). Use for kiosk builds or CI runs that mustn't pick up local

//!   customization.

//! - `AZ_RICING=force` (aliases: `prefer`, `aggressive`, `1`): on Linux,

//!   reorder the detection chain so riced-desktop sources win over

//!   GNOME/KDE — useful for tiling-WM users whose `XDG_CURRENT_DESKTOP`

//!   still says `gnome`. The user CSS file still loads.

#![cfg(feature = "parser")]

use alloc::{

    boxed::Box,

    string::{String, ToString},

    vec::Vec,

};

use crate::{

    corety::{AzString, OptionF32, OptionString, OptionU16},

    css::Css,

    parser2::{new_from_str, CssParseWarnMsg},

    props::{

        basic::{

            color::{parse_css_color, ColorU, OptionColorU},

            pixel::{PixelValue, OptionPixelValue},

        },

        style::scrollbar::{ComputedScrollbarStyle, OverscrollBehavior, ScrollBehavior, ScrollPhysics},

    },

};

use crate::dynamic_selector::{BoolCondition, OsVersion};

use core::fmt::Write;

// --- End-user customization mode ---

/// User-customization mode controlled by the `AZ_RICING` env var.

///

/// See the module-level documentation for the full description.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

#[derive(Default)]

pub enum RicingMode {

    /// `AZ_RICING=off` (or `disabled` / `none` / `0`). Skip the user

    /// CSS file *and* the riced-desktop sources. Vanilla detection.

    Off,

    /// Unset. Load the user CSS if present; standard detection chain

    /// (`KDE > GNOME > riced > defaults` on Linux).

    #[default]

    Default,

    /// `AZ_RICING=force` (or `prefer` / `aggressive` / `1`). Reorder

    /// the Linux detection chain so riced-desktop sources win over

    /// GNOME/KDE. The user CSS file still loads.

    Force,

}

/// Read the `AZ_RICING` env var and classify it. Case-insensitive.

/// Anything we don't recognise falls through to `Default` so a typo

/// degrades gracefully instead of disabling the feature silently.

    };

    }

/// True when the user CSS file at `~/.config/azul/styles/<app>.css`

/// should be read. False only when `AZ_RICING=off` is set.

// --- Public Data Structures ---

#[allow(variant_size_differences)] // repr(C,u8) FFI enum: boxing the large variant would change the C ABI (api.json bindings); size disparity accepted

/// Represents the detected platform.

#[derive(Debug, Default, Clone, PartialEq, Eq)]

#[repr(C, u8)]

pub enum Platform {

    Windows,

    MacOs,

    Linux(DesktopEnvironment),

    Android,

    Ios,

    #[default]

    Unknown,

}

impl Platform {

    /// Get the current platform at compile time.

    #[inline]

        #[cfg(target_os = "macos")]

        { Self::MacOs }

        #[cfg(target_os = "windows")]

        { Self::Windows }

        #[cfg(target_os = "linux")]

        #[cfg(target_os = "android")]

        { Self::Android }

        #[cfg(target_os = "ios")]

        { Self::Ios }

        #[cfg(not(any(target_os = "macos", target_os = "windows", target_os = "linux", target_os = "android", target_os = "ios")))]

        { Self::Unknown }

}

#[allow(variant_size_differences)] // repr(C,u8) FFI enum: boxing the large variant would change the C ABI (api.json bindings); size disparity accepted

/// Represents the detected Linux Desktop Environment.

#[derive(Debug, Clone, PartialEq, Eq)]

#[repr(C, u8)]

pub enum DesktopEnvironment {

    Gnome,

    Kde,

    Other(AzString),

}

/// The overall theme type.

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub enum Theme {

    #[default]

    Light,

    Dark,

}

/// A unified collection of discovered system style properties.

#[derive(Debug, Clone, PartialEq)]

#[repr(C)]

pub struct SystemStyle {

    pub fonts: SystemFonts,

    pub metrics: SystemMetrics,

    /// Linux-specific customisation (icon theme, cursor theme, GTK theme, ...)

    pub linux: LinuxCustomization,

    pub platform: Platform,

    /// Focus ring / indicator visual style

    pub focus_visuals: FocusVisuals,

    /// System language/locale in BCP 47 format (e.g., "en-US", "de-DE")

    /// Detected from OS settings at startup

    pub language: AzString,

    /// An optional, user-provided stylesheet loaded from a conventional

    /// location (`~/.config/azul/styles/<app_name>.css`), allowing for

    /// application-specific "ricing". Only loaded when the "io" feature

    /// is enabled and `AZ_RICING` is not set to `off`.

    pub app_specific_stylesheet: Option<Box<Css>>,

    /// Scrollbar style information (boxed to ensure stable FFI size)

    pub scrollbar: Option<Box<ComputedScrollbarStyle>>,

    /// Global scroll physics configuration (momentum, friction, rubber-banding).

    /// Platform-specific defaults are applied during system style discovery.

    /// Applications can override this to change the "feel" of scrolling globally.

    pub scroll_physics: ScrollPhysics,

    pub theme: Theme,

    /// Detected OS version (e.g., Windows 11 22H2, macOS Sonoma, etc.)

    pub os_version: OsVersion,

    /// User prefers reduced motion (accessibility setting)

    pub prefers_reduced_motion: BoolCondition,

    /// User prefers high contrast (accessibility setting)

    pub prefers_high_contrast: BoolCondition,

    /// Detailed accessibility settings (superset of `prefers_reduced_motion` / `prefers_high_contrast`)

    pub accessibility: AccessibilitySettings,

    /// Which hand the user operates the device with. Touch UIs put their

    /// primary controls on that side so the thumb reaches them.

    ///

    /// This is INDEPENDENT of text direction: an Arabic left-hander reads

    /// right-to-left but still reaches with the left hand, and a

    /// left-handed English user reads left-to-right. Deriving one from the

    /// other is a bug, so they are separate settings.

    pub handedness: Handedness,

    /// Input interaction timing / distance thresholds from the OS

    pub input: InputMetrics,

    /// Text rendering / anti-aliasing hints from the OS

    pub text_rendering: TextRenderingHints,

    /// OS-level scrollbar visibility / click-behaviour preferences

    pub scrollbar_preferences: ScrollbarPreferences,

    /// Visual hints: icons in menus/buttons, toolbar style, tooltips

    pub visual_hints: VisualHints,

    /// Animation enable/disable, speed factor, focus indicator behaviour

    pub animation: AnimationMetrics,

    pub colors: SystemColors,

    /// Icon-specific styling options (grayscale, tinting, etc.)

    pub icon_style: IconStyleOptions,

    /// Audio feedback preferences (event sounds, input sounds)

    pub audio: AudioMetrics,

    /// FFI double-drop guard. `SystemStyle` owns two heap pointers

    /// (`app_specific_stylesheet`, `scrollbar`). The codegen Az wrapper

    /// (`AzSystemStyle`) gets an `impl Drop` -> `AzSystemStyle_delete` ->

    /// `drop_in_place::<SystemStyle>`, and is nested by value as

    /// `AzAppConfig.system_style`. Dropping an `AzAppConfig` by value

    /// therefore drops the real `SystemStyle` once (freeing both Boxes) and

    /// then re-runs `_delete` on the SAME bytes via drop-glue -> double free.

    /// Same class as `GlContextPtr` / `IconProviderHandle` (see core/src/icon.rs).

    /// The first `Drop` disarms this flag; the second sees it cleared and

    /// neutralizes itself (takes + forgets the already-freed Boxes) so the

    /// redundant drop-glue is a no-op. Defaults to `true` (own + free once).

    pub run_destructor: bool,

}

impl Default for SystemStyle {

}

impl Drop for SystemStyle {

        // Gate the heap frees on `run_destructor` to defuse the codegen

        // double-drop (see the `run_destructor` field docs). drop_in_place

        // runs THIS method, then the field drop-glue; so:

        //  * FIRST drop (flag set): disarm the flag, then let the field

        //    drop-glue free the two Boxes exactly once.

        //  * SECOND drop on the same bytes (flag cleared by the first): the

        //    Boxes are already freed but the fields still hold dangling

        //    `Some(ptr)`. Take them out (-> None) and forget the dangling

        //    values so the trailing drop-glue is a no-op (never derefs/frees).

}

/// Icon-specific styling options for accessibility and theming.

///

/// These settings affect how icons are rendered, supporting accessibility

/// needs like reduced colors and high contrast modes.

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub struct IconStyleOptions {

    /// If true, icons should be rendered in grayscale (for color-blind users

    /// or reduced color preference). Applies a CSS grayscale filter.

    pub prefer_grayscale: bool,

    /// Optional tint color to apply to icons. Useful for matching icons

    /// to the current theme or for high contrast modes.

    pub tint_color: OptionColorU,

    /// If true, icons should inherit the current text color instead of

    /// using their original colors. Works well with font-based icons.

    pub inherit_text_color: bool,

}

/// System font types that can be resolved at runtime based on OS settings.

/// 

/// This enum allows specifying semantic font roles that get resolved to

/// actual font families based on the current platform and user preferences.

/// For example, `Monospace` resolves to:

/// - macOS: SF Mono or Menlo

/// - Windows: Cascadia Mono or Consolas

/// - Linux: Ubuntu Mono or `DejaVu` Sans Mono

/// 

/// Font variants (bold, italic) can be combined with the base type.

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]

#[repr(C)]

pub enum SystemFontType {

    /// UI font for buttons, labels, menus (SF Pro, Segoe UI, Cantarell)

    #[default]

    Ui,

    /// Bold variant of UI font

    UiBold,

    /// Monospace font for code (SF Mono, Consolas, Ubuntu Mono)

    Monospace,

    /// Bold variant of monospace font

    MonospaceBold,

    /// Italic variant of monospace font

    MonospaceItalic,

    /// Font for window titles

    Title,

    /// Bold variant of title font

    TitleBold,

    /// Font for menu items

    Menu,

    /// Small/caption font

    Small,

    /// Serif font for reading content (New York on macOS, Georgia on Windows)

    Serif,

    /// Bold variant of serif font

    SerifBold,

}

impl SystemFontType {

    /// Parse a `SystemFontType` from a CSS string.

    /// 

    /// Supported formats:

    /// - `system:ui`, `system:ui:bold`

    /// - `system:monospace`, `system:monospace:bold`, `system:monospace:italic`

    /// - `system:title`, `system:title:bold`

    /// - `system:menu`

    /// - `system:small`

    /// - `system:serif`, `system:serif:bold`

        }

    /// Get the CSS syntax for this system font type.

        }

    /// Returns true if this system font type implies bold weight.

    /// Used when resolving system fonts to pass the correct weight to fontconfig.

            Self::UiBold

                | Self::MonospaceBold

                | Self::TitleBold

                | Self::SerifBold

        )

    /// Returns true if this system font type implies italic style.

}

/// Accessibility settings detected from the operating system.

/// 

/// These settings allow apps to adapt their UI for users with accessibility needs.

/// Detection methods:

/// - macOS: `UIAccessibility` APIs (isBoldTextEnabled, isReduceMotionEnabled, etc.)

/// - Windows: `SystemParametersInfo` (`SPI_GETHIGHCONTRAST`, `SPI_GETCLIENTAREAANIMATION`)

/// - Linux: gsettings (org.gnome.desktop.interface, org.gnome.desktop.a11y)

#[derive(Debug, Default, Clone, Copy, PartialEq)]

#[repr(C)]

pub struct AccessibilitySettings {

    /// Text scaling factor (1.0 = normal, 1.5 = 150%, etc.)

    pub text_scale_factor: f32,

    /// User prefers bold text for better readability

    /// macOS: UIAccessibility.isBoldTextEnabled

    /// Windows: N/A (font scaling)

    /// Linux: org.gnome.desktop.interface text-scaling-factor

    pub prefers_bold_text: bool,

    /// User prefers larger text

    /// macOS: preferredContentSizeCategory

    /// Windows: `SystemParametersInfo` text scale factor

    /// Linux: org.gnome.desktop.interface text-scaling-factor

    pub prefers_larger_text: bool,

    /// User prefers high contrast colors

    /// macOS: UIAccessibility.isDarkerSystemColorsEnabled

    /// Windows: `SPI_GETHIGHCONTRAST`

    /// Linux: org.gnome.desktop.a11y.interface high-contrast

    pub prefers_high_contrast: bool,

    /// User prefers reduced motion/animations

    /// macOS: UIAccessibility.isReduceMotionEnabled

    /// Windows: `SPI_GETCLIENTAREAANIMATION` (inverted)

    /// Linux: org.gnome.desktop.interface enable-animations (inverted)

    pub prefers_reduced_motion: bool,

    /// User prefers reduced transparency

    /// macOS: UIAccessibility.isReduceTransparencyEnabled

    /// Windows: N/A

    /// Linux: N/A

    pub prefers_reduced_transparency: bool,

    /// Screen reader is active (`VoiceOver`, Narrator, Orca)

    pub screen_reader_active: bool,

    /// User prefers differentiate without color

    /// macOS: UIAccessibility.shouldDifferentiateWithoutColor

    pub differentiate_without_color: bool,

}

/// Common system colors used for UI elements.

/// 

/// These colors are queried from the operating system and automatically adapt

/// to the current theme (light/dark mode) and accent color settings.

/// 

/// On macOS, these correspond to `NSColor` semantic colors.

/// On Windows, these come from `UISettings`.

/// On Linux/GTK, these come from the GTK theme.

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub struct SystemColors {

    // === Primary semantic colors ===

    /// Primary text color (NSColor.textColor on macOS)

    pub text: OptionColorU,

    /// Secondary text color for less prominent text (NSColor.secondaryLabelColor)

    pub secondary_text: OptionColorU,

    /// Tertiary text color for disabled/placeholder text (NSColor.tertiaryLabelColor)

    pub tertiary_text: OptionColorU,

    /// Background color for content areas (NSColor.textBackgroundColor)

    pub background: OptionColorU,

    // === Accent colors ===

    /// System accent color chosen by user (NSColor.controlAccentColor on macOS)

    pub accent: OptionColorU,

    /// Text color on accent backgrounds

    pub accent_text: OptionColorU,

    // === Control colors ===

    /// Button/control background (NSColor.controlColor)

    pub button_face: OptionColorU,

    /// Button/control text color (NSColor.controlTextColor)

    pub button_text: OptionColorU,

    /// Disabled control text color (NSColor.disabledControlTextColor)

    pub disabled_text: OptionColorU,

    // === Window colors ===

    /// Window background color (NSColor.windowBackgroundColor)

    pub window_background: OptionColorU,

    /// Under-page background color (NSColor.underPageBackgroundColor)

    pub under_page_background: OptionColorU,

    // === Selection colors ===

    /// Selection background when window is focused (NSColor.selectedContentBackgroundColor)

    pub selection_background: OptionColorU,

    /// Selection text color when window is focused

    pub selection_text: OptionColorU,

    /// Selection background when window is NOT focused (NSColor.unemphasizedSelectedContentBackgroundColor)

    /// This is used for :backdrop state styling

    pub selection_background_inactive: OptionColorU,

    /// Selection text color when window is NOT focused

    pub selection_text_inactive: OptionColorU,

    // === Additional semantic colors ===

    /// Link color (NSColor.linkColor)

    pub link: OptionColorU,

    /// Separator/divider color (NSColor.separatorColor)

    pub separator: OptionColorU,

    /// Grid/table line color (NSColor.gridColor)

    pub grid: OptionColorU,

    /// Find/search highlight color (NSColor.findHighlightColor)

    pub find_highlight: OptionColorU,

    // === Sidebar colors (macOS-specific) ===

    /// Sidebar background color

    pub sidebar_background: OptionColorU,

    /// Selected row in sidebar

    pub sidebar_selection: OptionColorU,

}

/// Common system font settings.

/// 

/// On macOS, these are queried from `NSFont`.

/// On Windows, these come from `SystemParametersInfo`.

/// On Linux, these come from GTK/gsettings.

#[derive(Debug, Default, Clone, PartialEq, Eq)]

#[repr(C)]

pub struct SystemFonts {

    /// The primary font used for UI elements like buttons and labels.

    /// On macOS: SF Pro (system font)

    /// On Windows: Segoe UI

    /// On Linux: Cantarell, Ubuntu, or system default

    pub ui_font: OptionString,

    /// The default font size for UI elements, in points.

    pub ui_font_size: OptionF32,

    /// The font used for code or other monospaced text.

    /// On macOS: SF Mono or Menlo

    /// On Windows: Cascadia Mono or Consolas

    /// On Linux: Ubuntu Mono or `DejaVu` Sans Mono

    pub monospace_font: OptionString,

    /// Monospace font size in points

    pub monospace_font_size: OptionF32,

    /// Bold variant of the UI font (if different)

    pub ui_font_bold: OptionString,

    /// Font for window titles

    pub title_font: OptionString,

    /// Title font size in points

    pub title_font_size: OptionF32,

    /// Font for menu items

    pub menu_font: OptionString,

    /// Menu font size in points

    pub menu_font_size: OptionF32,

    /// Small/caption font for less prominent text

    pub small_font: OptionString,

    /// Small font size in points

    pub small_font_size: OptionF32,

}

/// Common system metrics for UI element sizing and spacing.

#[derive(Debug, Default, Clone, PartialEq, Eq)]

#[repr(C)]

pub struct SystemMetrics {

    /// The corner radius for standard elements like buttons.

    pub corner_radius: OptionPixelValue,

    /// The width of standard borders.

    pub border_width: OptionPixelValue,

    /// The horizontal (left/right) padding for buttons and similar controls.

    pub button_padding_horizontal: OptionPixelValue,

    /// The vertical (top/bottom) padding for buttons and similar controls.

    pub button_padding_vertical: OptionPixelValue,

    /// Titlebar layout information (button positions, safe areas, etc.)

    pub titlebar: TitlebarMetrics,

}

/// Which side of the titlebar the window control buttons are on.

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]

#[repr(C)]

pub enum TitlebarButtonSide {

    /// Buttons are on the left (macOS default)

    Left,

    /// Buttons are on the right (Windows, most Linux DEs)

    #[default]

    Right,

}

/// Which window control buttons are available in the titlebar.

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct TitlebarButtons {

    /// Close button is available

    pub has_close: bool,

    /// Minimize button is available

    pub has_minimize: bool,

    /// Maximize/zoom button is available

    pub has_maximize: bool,

    /// Fullscreen button is available (macOS green button behavior)

    pub has_fullscreen: bool,

}

impl Default for TitlebarButtons {

}

/// Safe area insets for devices with notches, rounded corners, or sensor housings.

/// 

/// On devices like iPhones with notches or Dynamic Island, the safe area

/// indicates regions where content should not be placed to avoid being

/// obscured by hardware features.

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub struct SafeAreaInsets {

    /// Inset from the top edge (notch, camera housing, etc.)

    pub top: OptionPixelValue,

    /// Inset from the bottom edge (home indicator on iPhone)

    pub bottom: OptionPixelValue,

    /// Inset from the left edge (rounded corners)

    pub left: OptionPixelValue,

    /// Inset from the right edge (rounded corners)

    pub right: OptionPixelValue,

}

/// Metrics for titlebar layout and window chrome.

/// 

/// This provides information needed to correctly position custom titlebar

/// content when using `WindowDecorations::NoTitle` (expanded title mode).

#[derive(Debug, Clone, PartialEq, Eq)]

#[repr(C)]

pub struct TitlebarMetrics {

    /// Which side the window control buttons are on

    pub button_side: TitlebarButtonSide,

    /// Which buttons are available

    pub buttons: TitlebarButtons,

    /// Height of the titlebar in pixels

    pub height: OptionPixelValue,

    /// Width reserved for window control buttons (close/min/max)

    /// This is the space to avoid when drawing custom title text

    pub button_area_width: OptionPixelValue,

    /// Horizontal padding inside the titlebar

    pub padding_horizontal: OptionPixelValue,

    /// Safe area insets for notched/rounded displays

    pub safe_area: SafeAreaInsets,

    /// Title text font (from `SystemFonts::title_font`)

    pub title_font: OptionString,

    /// Title text font size

    pub title_font_size: OptionF32,

    /// Title text font weight (400 = normal, 600 = semibold, 700 = bold)

    pub title_font_weight: OptionU16,

}

impl Default for TitlebarMetrics {

}

impl TitlebarMetrics {

    /// Windows-style titlebar (buttons on right)

    /// macOS-style titlebar (buttons on left, "traffic lights")

    /// Linux GNOME-style titlebar (buttons on right by default)

    /// iOS-style safe area (for notched devices)

    /// Android-style titlebar (action bar)

}

// ── Input interaction metrics ────────────────────────────────────────────

/// Input interaction timing and distance thresholds from the OS.

///

/// These values are queried from the operating system to match the user's

/// configured double-click speed, drag sensitivity, caret blink rate, etc.

///

/// # Platform APIs

/// - **macOS:** `NSEvent.doubleClickInterval`

/// - **Windows:** `GetDoubleClickTime()`, `GetSystemMetrics(SM_CXDOUBLECLK)`,

///   `GetCaretBlinkTime()`, `SystemParametersInfo(SPI_GETWHEELSCROLLLINES)`

/// - **Linux:** XDG Desktop Portal / gsettings

#[derive(Debug, Clone, Copy, PartialEq)]

#[repr(C)]

pub struct InputMetrics {

    /// Max milliseconds between clicks to register a double-click.

    pub double_click_time_ms: u32,

    /// Max pixels the mouse can move between clicks and still count.

    pub double_click_distance_px: f32,

    /// Pixels the mouse must move while held down before a drag starts.

    pub drag_threshold_px: f32,

    /// Caret blink rate in milliseconds (0 = no blink).

    pub caret_blink_rate_ms: u32,

    /// Width of the text caret/cursor in pixels (typically 1–2).

    pub caret_width_px: f32,

    /// Lines to scroll per mouse wheel notch.

    pub wheel_scroll_lines: u32,

    /// Milliseconds to wait before a hover triggers (e.g. tooltip delay).

    /// Windows: `SystemParametersInfo(SPI_GETMOUSEHOVERTIME)` — default 400.

    pub hover_time_ms: u32,

}

impl Default for InputMetrics {

}

// ── Text rendering hints ─────────────────────────────────────────────────

/// Subpixel rendering layout for font smoothing.

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub enum SubpixelType {

    /// No subpixel rendering (grayscale anti-aliasing only).

    #[default]

    None,

    /// Horizontal RGB subpixel layout (most common for LCD monitors).

    Rgb,

    /// Horizontal BGR subpixel layout.

    Bgr,

    /// Vertical RGB subpixel layout.

    VRgb,

    /// Vertical BGR subpixel layout.

    VBgr,

}

/// Text rendering configuration from the OS.

///

/// These hints allow the framework to match the host's font smoothing

/// settings for crisp, consistent text rendering.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub struct TextRenderingHints {

    /// Subpixel rendering type.

    pub subpixel_type: SubpixelType,

    /// Font smoothing gamma (1000 = default, higher = more contrast).

    pub font_smoothing_gamma: u32,

    /// Whether font smoothing (anti-aliasing) is enabled.

    pub font_smoothing_enabled: bool,

    /// User prefers increased text contrast.

    pub increased_contrast: bool,

}

impl Default for TextRenderingHints {

}

// ── Focus ring visuals ───────────────────────────────────────────────────

/// Focus ring / indicator visual style.

///

/// When an element receives keyboard focus the OS typically draws a visible

/// ring or border.  These values come from the OS preferences.

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub struct FocusVisuals {

    /// Focus ring / indicator colour.

    /// macOS: `NSColor.keyboardFocusIndicatorColor`

    pub focus_ring_color: OptionColorU,

    /// Width of focus border / ring.

    /// Windows: `SystemParametersInfo(SPI_GETFOCUSBORDERWIDTH)`

    pub focus_border_width: OptionPixelValue,

    /// Height of focus border / ring.

    pub focus_border_height: OptionPixelValue,

}

// ── Scrollbar preferences ────────────────────────────────────────────────

/// When scrollbars should be shown (OS-level preference).

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub enum ScrollbarVisibility {

    /// Always show scrollbars.

    Always,

    /// Show only while scrolling, then fade out.

    #[default]

    WhenScrolling,

    /// Automatic: depends on input device (trackpad → overlay, mouse → always).

    Automatic,

}

/// What happens when clicking the scrollbar track area.

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub enum ScrollbarTrackClick {

    /// Jump to the clicked position.

    JumpToPosition,

    /// Scroll by one page.

    #[default]

    PageUpDown,

}

/// OS-level scrollbar behaviour preferences.

///

/// These are separate from the CSS scrollbar *appearance* (`ComputedScrollbarStyle`).

/// They control *when* scrollbars appear and *how* clicking the track behaves.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub struct ScrollbarPreferences {

    /// How scrollbars should be shown.

    /// macOS: `NSScroller.preferredScrollerStyle`

    pub visibility: ScrollbarVisibility,

    /// What happens when clicking the scrollbar track.

    pub track_click: ScrollbarTrackClick,

}

impl Default for ScrollbarPreferences {

}

// ── Linux-specific customisation ─────────────────────────────────────────

/// Linux-specific customisation settings.

///

/// Read from GTK / KDE / XDG settings on Linux; `Default` (all `None` / 0)

/// on other platforms.

#[derive(Debug, Default, Clone, PartialEq, Eq)]

#[repr(C)]

pub struct LinuxCustomization {

    /// GTK theme name (e.g. "Adwaita", "Breeze", "Numix").

    pub gtk_theme: OptionString,

    /// Icon theme name (e.g. "Papirus", "Numix", "Breeze").

    pub icon_theme: OptionString,

    /// Cursor theme name (e.g. "`Breeze_Snow`", "DMZ-Black").

    pub cursor_theme: OptionString,

    /// Cursor size in pixels (0 = unset / use OS default).

    pub cursor_size: u32,

    /// GTK button layout string (e.g. "close,minimize,maximize:menu").

    /// Determines button side and order for CSD titlebars on Linux.

    pub titlebar_button_layout: OptionString,

}

// ── Visual hints (icons in menus / buttons / toolbar style) ──────────────

/// Toolbar display style (icons, text, or both).

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub enum ToolbarStyle {

    /// Show only icons in toolbars.

    #[default]

    IconsOnly,

    /// Show only text labels in toolbars.

    TextOnly,

    /// Show text beside the icon (horizontal).

    TextBesideIcon,

    /// Show text below the icon (vertical).

    TextBelowIcon,

}

/// Visual hints from the OS about how icons and decorations should be shown.

///

/// These preferences differ heavily between Linux desktops (KDE vs GNOME)

/// and are less configurable on macOS / Windows where HIG rules apply.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub struct VisualHints {

    /// Toolbar display style.

    /// Linux: `org.gnome.desktop.interface toolbar-style`, KDE `ToolButtonStyle`.

    pub toolbar_style: ToolbarStyle,

    /// Show icons on push buttons?  (Common in KDE, rare in Win/Mac.)

    /// Linux: `org.gnome.desktop.interface buttons-have-icons`, KDE `ShowIconsOnPushButtons`.

    pub show_button_images: bool,

    /// Show icons in context menus?  (GNOME defaults off since 3.x; Win/Mac/KDE usually on.)

    /// Linux: `org.gnome.desktop.interface menus-have-icons`.

    pub show_menu_images: bool,

    /// Should tooltips be shown on hover?

    pub show_tooltips: bool,

    /// Flash the window taskbar entry on alert?

    pub flash_on_alert: bool,

}

impl Default for VisualHints {

}

// ── Animation metrics ────────────────────────────────────────────────────

/// Focus indicator behaviour (always visible vs keyboard-only).

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub enum FocusBehavior {

    /// Focus indicators are always visible when an element has focus.

    #[default]

    AlwaysVisible,

    /// Focus indicators are hidden until the user presses a keyboard key

    /// (Alt, Tab, arrow keys, etc.).  Windows: `SPI_GETKEYBOARDCUES`.

    KeyboardOnly,

}

/// Animation-related preferences from the OS.

///

/// These control whether UI animations (transitions, fades, slides) should

/// play and at what speed.

///

/// # Platform APIs

/// - **Windows:** `SystemParametersInfo(SPI_GETCLIENTAREAANIMATION)`,

///   `SPI_GETKEYBOARDCUES`

/// - **macOS:** `NSWorkspace.accessibilityDisplayShouldReduceMotion`

/// - **Linux:** `org.gnome.desktop.interface enable-animations`,

///   KDE `AnimationDurationFactor`

#[derive(Debug, Clone, Copy, PartialEq)]

#[repr(C)]

pub struct AnimationMetrics {

    /// Global enable/disable for UI animations.

    pub animations_enabled: bool,

    /// Animation speed factor (1.0 = normal, 0.5 = 2× faster, 2.0 = 2× slower).

    /// Primarily used in KDE.

    pub animation_duration_factor: f32,

    /// When to show focus rectangles / rings.

    pub focus_indicator_behavior: FocusBehavior,

}

impl Default for AnimationMetrics {

}

// ── Audio metrics ────────────────────────────────────────────────────────

/// Audio-feedback preferences from the OS.

///

/// Controls whether the app should make sounds on events (error pings,

/// notifications) or on input (clicks, key presses).

///

/// # Platform APIs

/// - **Windows:** `SystemParametersInfo(SPI_GETBEEP)`

/// - **macOS:** `NSSound.soundEffectAudioVolume`

/// - **Linux:** `org.gnome.desktop.sound event-sounds`,

///   `org.gnome.desktop.sound input-feedback-sounds`

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub struct AudioMetrics {

    /// Should the app make sounds on events?  (Error ping, notification, etc.)

    pub event_sounds_enabled: bool,

    /// Should the app make sounds on input?  (Clicks, typing feedback.)

    pub input_feedback_sounds_enabled: bool,

}

impl Default for AudioMetrics {

}

/// Apple system font family names for font fallback chains.

/// 

/// These are the canonical names for Apple's system fonts, which should

/// be used in font fallback chains for proper rendering on Apple platforms.

/// Note: The names here must match what rust-fontconfig indexes from the font metadata.

pub mod apple_fonts {

    /// System Font - Primary system font for macOS

    /// This is how rust-fontconfig indexes the SF Pro font family

    pub const SYSTEM_FONT: &str = "System Font";

    /// SF NS variants as indexed by rust-fontconfig

    pub const SF_NS_ROUNDED: &str = "SF NS Rounded";

    /// SF Compact - System font optimized for watchOS

    /// Optimized for small sizes and narrow columns

    pub const SF_COMPACT: &str = "SF Compact";

    /// SF Mono - Monospaced font used in Xcode

    /// Enables alignment between rows and columns of text

    pub const SF_MONO: &str = "SF NS Mono Light";

    /// New York - Serif font for reading

    /// Performs as traditional reading face at small sizes

    pub const NEW_YORK: &str = "New York";

    /// SF Arabic - Arabic system font

    pub const SF_ARABIC: &str = "SF Arabic";

    /// SF Armenian - Armenian system font

    pub const SF_ARMENIAN: &str = "SF Armenian";

    /// SF Georgian - Georgian system font

    pub const SF_GEORGIAN: &str = "SF Georgian";

    /// SF Hebrew - Hebrew system font with niqqud support

    pub const SF_HEBREW: &str = "SF Hebrew";

    /// Legacy macOS fonts for fallback

    pub const MENLO: &str = "Menlo";

    pub const MENLO_REGULAR: &str = "Menlo Regular";

    pub const MENLO_BOLD: &str = "Menlo Bold";

    pub const MONACO: &str = "Monaco";

    pub const LUCIDA_GRANDE: &str = "Lucida Grande";

    pub const LUCIDA_GRANDE_BOLD: &str = "Lucida Grande Bold";

    pub const HELVETICA_NEUE: &str = "Helvetica Neue";

    pub const HELVETICA_NEUE_BOLD: &str = "Helvetica Neue Bold";

}

/// Windows system font family names.

pub mod windows_fonts {

    /// Modern Windows 11 fonts

    pub const SEGOE_UI_VARIABLE: &str = "Segoe UI Variable";

    pub const SEGOE_UI_VARIABLE_TEXT: &str = "Segoe UI Variable Text";

    pub const SEGOE_UI_VARIABLE_DISPLAY: &str = "Segoe UI Variable Display";

    /// Standard Windows fonts

    pub const SEGOE_UI: &str = "Segoe UI";

    pub const CONSOLAS: &str = "Consolas";

    pub const CASCADIA_CODE: &str = "Cascadia Code";

    pub const CASCADIA_MONO: &str = "Cascadia Mono";

    /// Legacy Windows fonts

    pub const TAHOMA: &str = "Tahoma";

    pub const MS_SANS_SERIF: &str = "MS Sans Serif";

    pub const LUCIDA_CONSOLE: &str = "Lucida Console";

    pub const COURIER_NEW: &str = "Courier New";

}

/// Linux/GTK common font family names.

pub mod linux_fonts {

    /// GNOME default fonts

    pub const CANTARELL: &str = "Cantarell";

    pub const ADWAITA: &str = "Adwaita";

    /// Ubuntu fonts

    pub const UBUNTU: &str = "Ubuntu";

    pub const UBUNTU_MONO: &str = "Ubuntu Mono";

    /// `DejaVu` fonts (widely available)

    pub const DEJAVU_SANS: &str = "DejaVu Sans";

    pub const DEJAVU_SANS_MONO: &str = "DejaVu Sans Mono";

    pub const DEJAVU_SERIF: &str = "DejaVu Serif";

    /// Liberation fonts (metrically compatible with Windows fonts)

    pub const LIBERATION_SANS: &str = "Liberation Sans";

    pub const LIBERATION_MONO: &str = "Liberation Mono";

    pub const LIBERATION_SERIF: &str = "Liberation Serif";

    /// Noto fonts (broad Unicode coverage)

    pub const NOTO_SANS: &str = "Noto Sans";

    pub const NOTO_MONO: &str = "Noto Sans Mono";

    pub const NOTO_SERIF: &str = "Noto Serif";

    /// KDE default fonts

    pub const HACK: &str = "Hack";

    /// Generic fallback names

    pub const MONOSPACE: &str = "Monospace";

    pub const SANS_SERIF: &str = "Sans";

    pub const SERIF: &str = "Serif";

}

impl SystemFontType {

    /// Returns the font fallback chain for this font type on the given platform.

    /// 

    /// The returned list contains font family names in order of preference.

    /// The first available font should be used.

        }

            // Normal weight: System Font first, then Helvetica Neue.

            ],

            // Bold weights: Helvetica Neue first (System Font has no Bold variant in fontconfig).

            ],

            // Monospace: Menlo (has a Bold variant), then Monaco.

            ],

            // Title / Menu / Small: System Font then Helvetica Neue.

            ],

            // Serif fonts - Georgia has bold variant

            ],

            ],

        }

            ],

            ],

            ],

            ],

            ],

            ],

        }

            ],

            ],

            ],

            ],

        }

            Self::Monospace | Self::MonospaceBold | Self::MonospaceItalic => {

            }

        }

            Self::Ui | Self::UiBold | Self::Title | Self::TitleBold | Self::Menu | Self::Small => {

            }

            Self::Monospace | Self::MonospaceBold | Self::MonospaceItalic => {

            }

        }

}

impl SystemStyle {

    /// Format the `SystemStyle` as a human-readable JSON string for debugging.

    ///

    /// This does NOT use serde — it manually formats the most important fields

    /// so that they can be verified against OS-reported values in a test script.

    #[allow(clippy::too_many_lines)] // large but cohesive: single-purpose CSS parser/formatter/dispatch table (one branch per property/variant)

        use alloc::format;

            )