//! Resource management types for the application.

//!

//! This module contains the core types for managing application resources:

//! - `AppConfig`: application-level configuration (logging, fonts, routes, components)

//! - `ImageRef` / `ImageRefHash`: reference-counted decoded image handles

//! - `FontKey` / `FontInstanceKey` / `ImageKey`: renderer-scoped resource keys

//! - `RendererResources`: per-window font/image registry with frame-based GC

//! - `RawImage`: CPU-side pixel data with format conversion to BGRA8

//! - `build_add_font_resource_updates` / `build_add_image_resource_updates`:

//!   diff current frame against registered resources and produce WebRender updates

#[cfg(not(feature = "std"))]

use alloc::string::ToString;

use alloc::{boxed::Box, collections::btree_map::BTreeMap, string::String, vec::Vec};

use core::{

    fmt,

    hash::{Hash, Hasher},

    sync::atomic::{AtomicU64, AtomicUsize, Ordering as AtomicOrdering},

};

use azul_css::{

    codegen::format::GetHash,

    props::basic::{

        pixel::DEFAULT_FONT_SIZE, ColorU, FloatValue, FontRef, LayoutRect, LayoutSize,

        StyleFontFamily, StyleFontFamilyVec, StyleFontSize,

    },

    props::style::scrollbar::OptionScrollPhysics,

    system::SystemStyle,

    AzString, F32Vec, LayoutDebugMessage, OptionI32, StringVec, U16Vec, U32Vec, U8Vec,

};

use rust_fontconfig::FcFontCache;

// Re-export Core* callback types for public use

pub use crate::callbacks::{

    CoreImageCallback, CoreRenderImageCallback, CoreRenderImageCallbackType,

};

use crate::{

    callbacks::{LayoutCallback, VirtualViewCallback},

    dom::{DomId, NodeData, NodeType},

    geom::{LogicalPosition, LogicalRect, LogicalSize},

    gl::{OptionGlContextPtr, Texture},

    hit_test::DocumentId,

    id::NodeId,

    prop_cache::CssPropertyCache,

    refany::RefAny,

    styled_dom::{

        NodeHierarchyItemId, StyleFontFamiliesHash, StyleFontFamilyHash, StyledDom, StyledNodeState,

    },

    ui_solver::GlyphInstance,

    window::{AzStringPair, OptionChar, StringPairVec},

    xml::{

        ComponentDef, ComponentDefVec, ComponentId, ComponentLibrary, ComponentLibraryVec,

        ComponentSource, RegisterComponentFn, RegisterComponentLibraryFn,

    },

    FastBTreeSet, OrderedMap,

};

/// Selects which image layer of an element a node-image update applies to.

///

/// Used by `CallbackInfo::change_node_image` to distinguish between replacing an

/// element's CSS `background` image and replacing its main content image (e.g. an

/// animated GL texture re-rendered on resize).

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

#[repr(C)]

pub enum UpdateImageType {

    /// The update targets the element's background.

    Background,

    /// The update targets the element's main content.

    Content,

}

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

#[repr(C)]

pub struct DpiScaleFactor {

    pub inner: FloatValue,

}

impl DpiScaleFactor {

}

/// Determines what happens when all application windows are closed

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

#[repr(C)]

#[derive(Default)]

pub enum AppTerminationBehavior {

    /// Return control to `main()` when all windows are closed (if platform supports it).

    /// On macOS, this exits the `NSApplication` run loop and returns to `main()`.

    /// This is useful if you want to clean up resources or restart the event loop.

    ReturnToMain,

    /// Keep the application running even when all windows are closed.

    /// This is the standard macOS behavior (app stays in dock until explicitly quit).

    RunForever,

    /// Immediately terminate the process when all windows are closed.

    /// Calls `std::process::exit(0)`.

    #[default]

    EndProcess,

}

/// An email address, e.g. a support mailbox problem reports go to.

///

/// Deliberately a thin wrapper (no RFC 5322 validation): the address is

/// app-configured, not user input, and the SMTP layer reports a bad one

/// loudly at send time.

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

#[repr(C)]

pub struct EmailAddress {

    /// The address, e.g. `support@myapp.example`.

    pub address: AzString,

}

impl_option!(

    EmailAddress,

    OptionEmailAddress,

    copy = false,

    [Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]

);

impl EmailAddress {

}

/// Requested update behaviour.

///

/// The EFFECTIVE behaviour is this clamped by what the installation permits:

/// a package-managed binary (dpkg-owned, `/usr`, snap, flatpak,

/// `WindowsApps`) NEVER self-updates — `SelfUpdate` degrades to

/// `NotifyOnly` there ("update via your package manager").

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

#[repr(C)]

pub enum UpdateMode {

    /// Check, notify, and — after the user consents — download and swap the

    /// binary. Staging may happen in the background; INSTALLING never does.

    SelfUpdate,

    /// Check and notify only ("new version available"); installing is the

    /// user's / packager's job. The mode packagers should ship.

    #[default]

    NotifyOnly,

    /// Never check for updates.

    Disabled,

}

/// Update configuration, part of [`AppConfig`]. With `manifest_url` unset

/// every check reports an error naming this field — nothing phones home

/// unless the app points it somewhere.

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

#[repr(C)]

pub struct UpdateSettings {

    /// Requested behaviour; clamped by the detected install kind at runtime.

    pub mode: UpdateMode,

    /// URL of the update manifest (JSON: `{"latest": {"version", "download_url",

    /// "changelog_md", "digest"}}`). None = update checks disabled.

    pub manifest_url: azul_css::OptionString,

    /// The RUNNING version, compared against the manifest's `latest.version`

    /// (dotted-numeric compare). Apps typically pass `env!("CARGO_PKG_VERSION")`.

    pub current_version: AzString,

    /// Directory-safe application name; keys the updater's state directory

    /// (`{data_dir}/{app_name}/update-state.json`) and the staging area.

    pub app_name: AzString,

    /// RESERVED: the build's date, compiled in by the APP (e.g. a build

    /// script stamping `env!("BUILD_DATE")`). The engine only carries it —

    /// into telemetry resources, crash dumps and update checks.

    pub build_date: AzString,

    /// RESERVED: the build's VCS tag (or commit), compiled in by the APP.

    /// Same carriage as `build_date`.

    pub build_tag: AzString,

    /// The RELEASE CHANNEL this binary follows: `stable` (the default when

    /// empty), `beta`, `nightly`, or whatever names the publisher uses.

    /// Compiled in, so a nightly build cannot be talked onto the stable

    /// track by a manifest: the binary decides which channel it reads, the

    /// publisher decides what is in it.

    pub channel: AzString,

    /// Base64 minisign ROOT public key, compiled in by the APP. Non-empty

    /// arms the update SIGNATURE CHAIN: the manifest must then carry a

    /// root-signed signing-key statement and an artifact signature, and an

    /// unsigned release is a hard error instead of a fallback. Empty (the

    /// default) = digest verification only.

    pub root_public_key: AzString,

}

impl Default for UpdateSettings {

}

/// A named font bundled with the application (name + raw bytes).

/// The name is used to reference the font in CSS (e.g. `font-family: "MyFont"`).

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

#[repr(C)]

pub struct NamedFont {

    /// The font family name to use in CSS (e.g. "Roboto", "`MyCustomFont`")

    pub name: AzString,

    /// Raw font file bytes (TTF, OTF, etc.)

    pub bytes: U8Vec,

}

impl_option!(

    NamedFont,

    OptionNamedFont,

    copy = false,

    [Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]

);

impl NamedFont {

}

impl_vec!(NamedFont, NamedFontVec, NamedFontVecDestructor, NamedFontVecDestructorType, NamedFontVecSlice, OptionNamedFont);

impl_vec_mut!(NamedFont, NamedFontVec);

impl_vec_debug!(NamedFont, NamedFontVec);

impl_vec_partialeq!(NamedFont, NamedFontVec);

impl_vec_eq!(NamedFont, NamedFontVec);

impl_vec_partialord!(NamedFont, NamedFontVec);

impl_vec_ord!(NamedFont, NamedFontVec);

impl_vec_hash!(NamedFont, NamedFontVec);

impl_vec_clone!(NamedFont, NamedFontVec, NamedFontVecDestructor);

/// Descriptor for a font that the layout engine currently has loaded in its

/// font cache.

///

/// Returned by `CallbackInfo::get_loaded_fonts()`. The `font_hash` field is

/// the same `u64` carried by `DisplayListItem::Text` glyph runs, so a callback

/// can correlate a loaded font with the text runs that use it and then fetch

/// the raw bytes via `CallbackInfo::get_loaded_font_bytes(font_hash)` (e.g. to

/// embed every font the layout actually used into a generated PDF).

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

#[repr(C)]

pub struct LoadedFont {

    /// Stable hash of the parsed font, identical to the `font_hash` stored on

    /// `DisplayListItem::Text` glyph runs. Use this to look up the bytes with

    /// `CallbackInfo::get_loaded_font_bytes`.

    pub font_hash: u64,

    /// PostScript / family name from the font's `name` table, or an empty

    /// string if the font did not provide one.

    pub family_name: AzString,

    /// Total number of glyphs in the font (from the `maxp` table).

    pub num_glyphs: u32,

    /// `true` if the source font bytes are retained and can be retrieved with

    /// `CallbackInfo::get_loaded_font_bytes(font_hash)`. Fonts loaded on the

    /// production (lazy mmap) path retain their bytes; some test-only fonts do

    /// not.

    pub has_bytes: bool,

}

impl_option!(

    LoadedFont,

    OptionLoadedFont,

    copy = false,

    [Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]

);

impl LoadedFont {

}

impl_vec!(LoadedFont, LoadedFontVec, LoadedFontVecDestructor, LoadedFontVecDestructorType, LoadedFontVecSlice, OptionLoadedFont);

impl_vec_mut!(LoadedFont, LoadedFontVec);

impl_vec_debug!(LoadedFont, LoadedFontVec);

impl_vec_partialeq!(LoadedFont, LoadedFontVec);

impl_vec_eq!(LoadedFont, LoadedFontVec);

impl_vec_partialord!(LoadedFont, LoadedFontVec);

impl_vec_ord!(LoadedFont, LoadedFontVec);

impl_vec_hash!(LoadedFont, LoadedFontVec);

impl_vec_clone!(LoadedFont, LoadedFontVec, LoadedFontVecDestructor);

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

/// Configuration for how fonts should be loaded at app startup.

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

#[repr(C, u8)]

#[derive(Default)]

pub enum FontLoadingConfig {

    /// Load all system fonts (default behavior, can be slow on systems with many fonts)

    #[default]

    LoadAllSystemFonts,

    /// Only load fonts for specific families (faster startup).

    /// Generic families like "sans-serif" are automatically expanded to OS-specific fonts.

    LoadOnlyFamilies(StringVec),

    /// Don't load any system fonts, only use bundled fonts

    BundledFontsOnly,

}

/// Mock environment for CSS evaluation.

/// 

/// Allows overriding auto-detected system properties for testing and development.

/// Any field set to `None` will use the auto-detected value.

/// Any field set to `Some(...)` will override the auto-detected value.

/// 

/// # Example

/// ```rust

/// # use azul_core::resources::CssMockEnvironment;

/// use azul_css::dynamic_selector::{

///     OsCondition, ThemeCondition, OsVersion,

///     OptionOsCondition, OptionThemeCondition, OptionOsVersion,

/// };

/// 

/// // Mock a Linux dark theme environment on any platform

/// let mock = CssMockEnvironment {

///     os: OptionOsCondition::Some(OsCondition::Linux),

///     theme: OptionThemeCondition::Some(ThemeCondition::Dark),

///     ..Default::default()

/// };

/// 

/// // Mock Windows XP for retro testing

/// let mock = CssMockEnvironment {

///     os: OptionOsCondition::Some(OsCondition::Windows),

///     os_version: OptionOsVersion::Some(OsVersion::WIN_XP),

///     ..Default::default()

/// };

/// ```

#[derive(Debug, Clone, Default)]

#[repr(C)]

pub struct CssMockEnvironment {

    /// Override the current theme (light/dark)

    pub theme: azul_css::dynamic_selector::OptionThemeCondition,

    /// Override the current language (BCP 47 tag, e.g., "de-DE", "en-US")

    pub language: azul_css::OptionString,

    /// Override the detected OS version

    pub os_version: azul_css::dynamic_selector::OptionOsVersion,

    /// Override the detected operating system

    pub os: azul_css::dynamic_selector::OptionOsCondition,

    /// Override the Linux desktop environment (only applies when os = Linux)

    pub desktop_env: azul_css::dynamic_selector::OptionLinuxDesktopEnv,

    /// Override viewport dimensions (for @media queries)

    /// Only use for testing - normally set by window size

    pub viewport_width: azul_css::OptionF32,

    pub viewport_height: azul_css::OptionF32,

    /// Override the reduced motion preference

    pub prefers_reduced_motion: azul_css::OptionBool,

    /// Override the high contrast preference

    pub prefers_high_contrast: azul_css::OptionBool,

}

impl CssMockEnvironment {

    /// Create a mock for Linux environment

    /// Create a mock for Windows environment

    /// Create a mock for macOS environment

    /// Create a mock for dark theme

    /// Create a mock for light theme

    /// Apply this mock to a `DynamicSelectorContext`

            } else {

            };

            } else {

            };

}

impl_option!(

    CssMockEnvironment,

    OptionCssMockEnvironment,

    copy = false,

    [Debug, Clone]

);

/// A route mapping a URL pattern to a layout callback.

///

/// Routes are cross-platform: on desktop, switching routes swaps the

/// active layout callback and triggers `RefreshDom`. On web, it also

/// calls `history.pushState()` for browser navigation.

///

/// # Pattern syntax

///

/// - `"/"` — exact root

/// - `"/about"` — exact path

/// - `"/user/:id"` — parameterized segment, `/user/42` yields `id = "42"`

///

/// # C API

/// ```c

/// AzAppConfig_addRoute(&config, AzString_fromConstStr("/user/:id"), layout_user);

/// ```

#[repr(C)]

pub struct Route {

    /// URL pattern (e.g. `"/"`, `"/about"`, `"/user/:id"`)

    pub pattern: AzString,

    /// Layout callback invoked when this route is active

    pub layout_callback: LayoutCallback,

}

impl Clone for Route {

}

impl fmt::Debug for Route {

}

impl Eq for Route {}

impl_option!(Route, OptionRoute, copy = false, [Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]);

impl_vec!(Route, RouteVec, RouteVecDestructor, RouteVecDestructorType, RouteVecSlice, OptionRoute);

impl_vec_mut!(Route, RouteVec);

impl_vec_debug!(Route, RouteVec);

impl_vec_clone!(Route, RouteVec, RouteVecDestructor);

impl_vec_partialeq!(Route, RouteVec);

impl_vec_eq!(Route, RouteVec);

impl_vec_partialord!(Route, RouteVec);

impl_vec_ord!(Route, RouteVec);

impl_vec_hash!(Route, RouteVec);

/// Result of matching a URL against a route pattern.

///

/// Stores the matched pattern and any extracted parameters.

/// Available to layout callbacks via `LayoutCallbackInfo::get_route_param()`.

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

#[repr(C)]

pub struct RouteMatch {

    /// The matched route pattern (e.g. `"/user/:id"`)

    pub pattern: AzString,

    /// Extracted parameters (e.g. `[("id", "42")]`)

    pub params: StringPairVec,

}

impl RouteMatch {

    /// Get a route parameter by key.

}

impl_option!(RouteMatch, OptionRouteMatch, copy = false, [Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]);

/// Match a URL path against a route pattern, extracting parameters.

///

/// Returns `Some(RouteMatch)` with extracted params on match, `None` otherwise.

///

/// # Examples

/// - pattern `"/user/:id"`, path `"/user/42"` → `Some(RouteMatch { params: [("id","42")] })`

/// - pattern `"/"`, path `"/"` → `Some(RouteMatch { params: [] })`

/// - pattern `"/about"`, path `"/settings"` → `None`

#[allow(clippy::similar_names)] // domain-standard coordinate/control-point names

    }

/// The ZOMBIE-SPECIFIC half of what a native animation function receives.

///

/// The other half is a full [`TimerCallbackInfo`] (USER ruling 2026-08-17),

/// so a callback can also reach the LIVE dom, queue changes, read momentum,

/// measure any node… full customizability, not a keyhole.

///

/// The pointers here are BORROWED for the duration of the call — a function

/// may walk the retained tree (e.g. measure its own component's text

/// mid-exit) but must not store them: for an exit the tree is the retained

/// zombie frame, freed when the animation completes.

#[derive(Debug)]

#[repr(C)]

pub struct ZombieAnimInfo {

    /// The `StyledDom` the ANIMATED node lives in — the retained tree for

    /// exits, the live tree for enters. Never null during a call. (The live

    /// dom is separately reachable through the `TimerCallbackInfo`.)

    pub styled_dom: *const crate::styled_dom::StyledDom,

    /// The animated node's index in THAT tree.

    pub node_id: u64,

    /// The node's rect in logical px: the retained rect for exits, the

    /// solved rect for enters.

    pub rect: LogicalRect,

    /// The viewport the tree was laid out in.

    pub viewport: LogicalRect,

    pub dpi_factor: f32,

    /// RAW LINEAR progress 0..=1. The engine does NOT pre-apply easing for

    /// native functions: the DECLARED timing arrives in `timing` below, and

    /// the callback owns the math — apply it via `AnimationTiming::evaluate`

    /// or substitute its own curve entirely.

    pub t: f32,

    /// The timing the CSS requested (`ease`, `spring`, a

    /// `cubic-bezier(...)` point list, …).

    pub timing: azul_css::props::basic::animation::AnimationTiming,

    /// The animation's velocity ENTERING this frame, logical px/s — the

    /// derivative of the previous two samples (one-frame lag; zero on the

    /// first frame and for enter/live tracks today). The read half of the

    /// momentum API for native functions: reversing with continuity means

    /// producing frames that start at this speed.

    pub velocity_x: f32,

    pub velocity_y: f32,

}

/// One frame of a native presence animation, returned by a

/// the zombie animation callback. Absolute values, not deltas.

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

#[repr(C)]

pub struct ZombieFrame {

    /// Translation in logical px, applied about the node's origin.

    pub translate_x: f32,

    pub translate_y: f32,

    /// 0.0 skips the node entirely this frame.

    pub opacity: f32,

    /// Absolute painted width in logical px (left-anchored narrowing for

    /// exits; the live layout already owns the vacated space). `None` keeps

    /// the full width. Ignored for enters (live width is layout's job).

    pub width: azul_css::OptionF32,

    /// Clip the exit to its frozen rect so the motion cannot paint over

    /// neighbouring components. Ignored for enters.

    pub clip_to_frozen_rect: bool,

}

impl Default for ZombieFrame {

}

// TYPE-ERASED `extern "C"` entry point of a native presence animation:

// stored as `usize` for the same reason as `crate::callbacks::CoreCallback` —

// the REAL signature takes a `&mut TimerCallbackInfo` (full live-dom access,

// USER ruling 2026-08-17), and that type lives in `azul-layout`, above this

// crate. azul-layout defines the typed alias and casts on invocation:

// `extern "C" fn(&mut RefAny, &mut TimerCallbackInfo, &ZombieAnimInfo) -> ZombieFrame`

// (Erased alias removed: the PUBLIC `ZombieAnimCallbackType` name now

// belongs to the GENERATED typed fn-pointer emitted from `ZombieAnimCallback`'s

// callback_typedef in api.json — two same-name exports collided in codegen.

// Internally the erasure is just `usize`.)

/// The type-erased component animation callback (a fn pointer as `usize`).

#[repr(C)]

#[derive(Clone, Copy)]

pub struct ZombieAnimCallback {

    pub cb: usize,

}

impl fmt::Debug for ZombieAnimCallback {

}

impl Hash for ZombieAnimCallback {

}

impl PartialEq for ZombieAnimCallback {

}

impl Eq for ZombieAnimCallback {}

impl PartialOrd for ZombieAnimCallback {

}

impl Ord for ZombieAnimCallback {

}

/// A COMPONENT-ATTACHED native animation function.

///

/// Lives on the node's own `NodeData` (USER ruling 2026-08-17 — a sidebar

/// widget ships its fly-out next to its own DOM, not in app-global state;

/// the global `AppConfig` registry this replaced was "a bit unclean").

/// Resolvable by NAME from that node's `-azul-animation-in` /

/// `-azul-animation-out`, AFTER stylesheet `@keyframes` — the web mechanism

/// stays the only default name source.

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

#[repr(C)]

pub struct AnimationFunction {

    pub name: AzString,

    pub callback: ZombieAnimCallback,

    /// Passed to `callback` on every invocation.

    pub data: RefAny,

}

/// Configuration of the SYSTEM-driven animations: physics-based scrolling

/// and the caret / selection tweens. Lives on [`AppConfig`] so a platform or

/// application can tune the feel without rebuilding azul.

///

/// The scroll physics override is applied ON TOP of the platform-discovered

/// [`SystemStyle`] at `App::create` time (`None` keeps the per-platform

/// preset). The tween slots always apply; set a duration to `0` to disable

/// that tween (the caret / selection then jumps, the classic behavior).

#[derive(Debug, Clone)]

#[repr(C)]

pub struct SystemAnimations {

    // Field order: decreasing alignment (8-aligned callbacks/RefAny first,

    // then the 4-aligned option/durations, bool last) — the autofix padding

    // lint enforces this, and the api.json struct_fields order must match

    // (the field-order lint enforces THAT).

    /// The caret tween MATH: called every animation frame with the past /

    /// current caret rectangles and linear progress `t`; returns the

    /// rectangle to render. Default: ease-out cubic lerp.

    pub caret_tween: crate::callbacks::CaretTweenCallback,

    /// The selection tween MATH: called every animation frame with the

    /// past / current selection band rectangles and linear progress `t`;

    /// returns the rectangles to render (must match the current count).

    /// Default: ease-out cubic lerp, rectangles paired by index.

    pub selection_tween: crate::callbacks::SelectionTweenCallback,

    /// User data passed to `caret_tween` on every invocation.

    pub caret_tween_data: RefAny,

    /// User data passed to `selection_tween` on every invocation.

    pub selection_tween_data: RefAny,

    /// Overrides `SystemStyle.scroll_physics` (momentum, overscroll /

    /// rubber-band, wheel-vs-trackpad curves). `None` = platform default.

    pub scroll_physics: OptionScrollPhysics,

    /// Duration of the caret-move tween in ms. `0` disables the tween.

    /// While the tween runs, caret blinking is suppressed (caret stays

    /// solid while it moves).

    pub caret_tween_duration_ms: u32,

    /// Duration of the selection tween in ms. `0` disables the tween.

    pub selection_tween_duration_ms: u32,

    /// Focus-ring glide duration in ms (ledger #29). `0` (the DEFAULT)

    /// disables the ring entirely — no visual change for existing apps;

    /// an app that opts in gets a focus outline that GLIDES between

    /// focused elements using the `caret_tween` interpolator (the ring is

    /// suppressed while a text-editing session owns focus — there the

    /// caret is the indicator).

    pub focus_ring_duration_ms: u32,

    /// Whether "scroll the caret into view" glides via the scroll-physics

    /// spring (true, the Word feel) or jumps instantly (false — also what

    /// [`Self::disabled`] sets, keeping e2e screenshots deterministic).

    pub caret_scroll_glide: bool,

}

impl SystemAnimations {

    /// All system animations disabled: no scroll-physics override, tween

    /// durations 0 (caret / selection jump). Test drivers and deterministic

    /// harnesses use this so screenshots never catch geometry mid-glide.

}

impl Default for SystemAnimations {

}

/// Configuration for optional features, such as whether to enable logging or panic hooks

#[derive(Debug, Clone)]

#[repr(C)]

pub struct AppConfig {

    /// If enabled, logs error and info messages.

    ///

    /// Default is `LevelFilter::Error` to log all errors by default

    pub log_level: AppLogLevel,

    /// If the app crashes / panics, a window with a message box pops up.

    /// Setting this to `false` disables the popup box.

    pub enable_visual_panic_hook: bool,

    /// If this is set to `true` (the default), a backtrace + error information

    /// gets logged to stdout and the logging file (only if logging is enabled).

    pub enable_logging_on_panic: bool,

    /// Determines what happens when all windows are closed.

    /// Default: `EndProcess` (terminate when last window closes).

    pub termination_behavior: AppTerminationBehavior,

    /// Icon provider for the application.

    /// Register icons here before calling `App::run()`.

    /// Each window will clone this provider (cheap, Arc-based).

    pub icon_provider: crate::icon::IconProviderHandle,

    /// Fonts bundled with the application.

    /// These fonts are loaded into memory and take priority over system fonts.

    pub bundled_fonts: NamedFontVec,

    /// Configuration for how system fonts should be loaded.

    /// Default: `LoadAllSystemFonts` (scan all system fonts at startup)

    pub font_loading: FontLoadingConfig,

    /// Optional mock environment for CSS evaluation.

    /// 

    /// When set, this overrides the auto-detected system properties (OS, theme, etc.)

    /// for CSS @-rules and dynamic selectors. This is useful for:

    /// - Testing OS-specific styles on a different platform

    /// - Screenshot testing with consistent environment

    /// - Previewing how the app looks on different systems

    /// 

    /// Default: None (use auto-detected system properties)

    pub mock_css_environment: OptionCssMockEnvironment,

    /// System style detected at startup (theme, colors, fonts, etc.)

    /// 

    /// This is detected once at `AppConfig::create()` and passed to all windows.

    /// You can override this after creation to use a custom system style,

    /// for example to test how your app looks on a different platform.

    pub system_style: SystemStyle,

    /// Component libraries registered at startup.

    ///

    /// Use `add_component()` to register individual components, or

    /// `add_component_library()` to register entire libraries.

    /// User-registered (and built-in) component libraries.

    ///

    /// The 52 built-in HTML elements are automatically registered by

    /// `AppConfig::create()` via `register_builtin_components`.

    /// Additional libraries can be added with `add_component_library`.

    pub component_libraries: ComponentLibraryVec,

    /// Registered routes mapping URL patterns to layout callbacks.

    ///

    /// Cross-platform: on desktop, the active route determines which layout

    /// callback runs. On web, routes map to HTTP endpoints and browser URLs.

    ///

    /// The first route (or `"/"`) is the default. Use `add_route()` to register.

    pub routes: RouteVec,

    /// System-animation configuration (scroll physics override, caret /

    /// selection tween hooks). See [`SystemAnimations`].

    pub system_animations: SystemAnimations,

    /// Handler for E2E ops the engine does not implement, letting a scenario

    /// drive application-level actions ("now load the document") that the

    /// engine cannot express on the app's behalf.

    ///

    /// The default recognises nothing, so a scenario naming a custom op fails

    /// unless the app installed a handler.

    pub custom_e2e_op: crate::events::CustomE2eOpCallback,

    /// Update configuration: manifest URL, requested mode, the running

    /// version. Drives `CallbackInfo::check_for_updates` and the

    /// `SysDialogType::UpdateVersion` dialog. Default: no manifest (checks

    /// disabled), `NotifyOnly`.

    pub updates: UpdateSettings,

    /// URL of the app's changelog in Markdown. The `UpdateVersion` dialog

    /// shows it before installing when a release carries no changelog link

    /// of its own.

    pub changelog_md: azul_css::OptionString,

    /// Support mailbox that problem reports (`SysDialogType::ReportProblem`)

    /// and manual crash reports go to. None = the `ReportProblem` dialog saves

    /// reports to disk instead of mailing them.

    pub report_problem: OptionEmailAddress,

}

impl AppConfig {

        // Dogfood: register the 52 built-in HTML elements via the

        // same `add_component_library` API that users call.

        // Annotated binding coerces the fn item to the fn-pointer type that

        // `Into<RegisterComponentLibraryFn>` is implemented for (no `as` cast).

        );

    /// Create config with a mock CSS environment for testing

    /// 

    /// This allows you to simulate how your app would look on a different OS,

    /// with a different theme, language, or accessibility settings.

    /// 

    /// # Example

    /// ```rust

    /// # use azul_core::resources::{AppConfig, CssMockEnvironment};

    /// # use azul_css::dynamic_selector::{OsCondition, OptionOsCondition, ThemeCondition, OptionThemeCondition};

    /// let config = AppConfig::create()

    ///     .with_mock_environment(CssMockEnvironment {

    ///         os: OptionOsCondition::Some(OsCondition::Linux),

    ///         theme: OptionThemeCondition::Some(ThemeCondition::Dark),

    ///         ..Default::default()

    ///     });

    /// ```

    /// Register a single component into a named library.

    ///

    /// Calls `register_fn` immediately and adds the returned `ComponentDef`

    /// to the library named `library`. If no library with that name exists,

    /// a new one is created. If a component with the same `id.name` already

    /// exists in the library, it is replaced.

    ///

    /// # C API

    /// ```c

    /// AzAppConfig_addComponent(&config, AzString_fromConstStr("mylib"), my_register_fn);

    /// ```

    /// Register an entire component library.

    ///

    /// Calls `register_fn` immediately and adds the returned

    /// `ComponentLibrary` to the config. Uses `name` as the library name

    /// (overriding whatever the function sets). If a library with the same

    /// name already exists, it is replaced wholesale.

    ///

    /// # C API

    /// ```c

    /// AzAppConfig_addComponentLibrary(&config, AzString_fromConstStr("vendor"), my_lib_fn);

    /// ```

    /// Register a route mapping a URL pattern to a layout callback.

    ///

    /// On web: each route becomes an HTTP endpoint. On desktop: the first

    /// route (or `"/"`) is the initial layout, and `CallbackInfo::switch_route()`

    /// swaps the active callback.

    ///

    /// # C API

    /// ```c

    /// AzAppConfig_addRoute(&config, AzString_fromConstStr("/user/:id"), layout_user);

    /// ```

        // Replace existing route with the same pattern

    /// Find the route matching a given URL path.

    ///

    /// Returns the matched `Route` and a `RouteMatch` with extracted parameters.

        }

}

impl Default for AppConfig {

}

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

#[repr(C)]

pub enum AppLogLevel {

    Off,

    Error,

    Warn,

    Info,

    Debug,

    Trace,

}

/// Metadata (but not storage) describing an image In `WebRender`.

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

#[repr(C)]

pub struct ImageDescriptor {

    /// Format of the image data.

    pub format: RawImageFormat,

    /// Width and height of the image data, in pixels.

    pub width: usize,

    pub height: usize,

    /// The number of bytes from the start of one row to the next. If non-None,

    /// `compute_stride` will return this value, otherwise it returns

    /// `width * bpp`. Different source of images have different alignment

    /// constraints for rows, so the stride isn't always equal to width * bpp.

    pub stride: OptionI32,

    /// Offset in bytes of the first pixel of this image in its backing buffer.

    /// This is used for tiling, wherein `WebRender` extracts chunks of input images

    /// in order to cache, manipulate, and render them individually. This offset

    /// tells the texture upload machinery where to find the bytes to upload for

    /// this tile. Non-tiled images generally set this to zero.

    pub offset: i32,

    /// Various bool flags related to this descriptor.

    pub flags: ImageDescriptorFlags,

}

/// Various flags that are part of an image descriptor.

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

#[repr(C)]

pub struct ImageDescriptorFlags {

    /// Whether this image is opaque, or has an alpha channel. Avoiding blending

    /// for opaque surfaces is an important optimization.

    pub is_opaque: bool,

    /// Whether to allow the driver to automatically generate mipmaps. If images

    /// are already downscaled appropriately, mipmap generation can be wasted

    /// work, and cause performance problems on some cards/drivers.

    ///

    /// See <https://github.com/servo/webrender/pull/2555>/

    pub allow_mipmaps: bool,

}

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

pub struct IdNamespace(pub u32);

impl ::core::fmt::Display for IdNamespace {

}

impl ::core::fmt::Debug for IdNamespace {

}

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

#[repr(C)]

pub enum RawImageFormat {

    R8,

    RG8,

    RGB8,

    RGBA8,

    R16,

    RG16,

    RGB16,

    RGBA16,

    BGR8,

    BGRA8,

    RGBF32,

    RGBAF32,

}

// NOTE: starts at 1 (0 = DUMMY)

static IMAGE_KEY: AtomicU64 = AtomicU64::new(1);

static FONT_KEY: AtomicU64 = AtomicU64::new(0);

static FONT_INSTANCE_KEY: AtomicU64 = AtomicU64::new(0);

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

pub struct ImageKey {

    pub namespace: IdNamespace,

    pub key: u64,

}

impl ImageKey {

    pub const DUMMY: Self = Self {

        namespace: IdNamespace(0),

        key: 0,

    };

}

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

pub struct FontKey {

    pub namespace: IdNamespace,

    pub key: u64,

}

impl FontKey {

}

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

pub struct FontInstanceKey {

    pub namespace: IdNamespace,

    pub key: u64,

}

impl FontInstanceKey {

}

// NOTE: This type should NOT be exposed in the API!

// The only public functions are the constructors

#[derive(Debug)]

pub enum DecodedImage {

    /// Image that has a reserved key, but no data, i.e it is not yet rendered

    /// or there was an error during rendering

    NullImage {

        width: usize,

        height: usize,

        format: RawImageFormat,

        /// Sometimes images need to be tagged with extra data

        tag: Vec<u8>,

    },

    // OpenGl texture

    Gl(Texture),

    // Image backed by CPU-rendered pixels

    Raw((ImageDescriptor, ImageData)),

    // Same as `Texture`, but rendered AFTER the layout has been done

    Callback(CoreImageCallback),

    // YUVImage(...)

    // VulkanSurface(...)

    // MetalSurface(...),

    // DirectXSurface(...)

}

#[derive(Debug)]

#[repr(C)]

pub struct ImageRef {

    /// Shared pointer to an opaque implementation of the decoded image

    pub data: *const DecodedImage,

    /// How many copies does this image have (if 0, the font data will be deleted on drop)

    pub copies: *const AtomicUsize,

    /// Process-unique, monotonically-assigned identity of the *decoded image*

    /// (see [`ImageRefHash`]). Shared by shallow clones (they are the same

    /// image), fresh for [`ImageRef::deep_copy`] and every `new_*` (a

    /// different image). Unlike the old `data`-pointer identity this is drawn

    /// from a never-reused counter, so freeing an image and reusing its heap

    /// address can never make a *new* image collide with a stale key — the

    /// prerequisite for image GC (see resources.rs `image_ref_get_hash`).

    pub id: u64,

    pub run_destructor: bool,

}

/// Never-reused source of [`ImageRef::id`]. Starts at 1 so `id == 0` can flag

/// an un-initialised / raw-reconstructed handle.

static IMAGE_REF_ID_COUNTER: AtomicU64 = AtomicU64::new(1);

#[must_use]

impl ImageRef {

}

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

#[repr(C)]

pub struct ImageRefHash {

    pub inner: u64,

}

impl_option!(

    ImageRef,

    OptionImageRef,

    copy = false,

    [Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]

);

impl ImageRef {

    /// If *copies = 1, returns the internal image data

        // SAFETY: `data`/`copies` are non-null heap allocations from `Box::into_raw`

        // in `new()` (never mutated afterwards). When `copies == 1` we are the sole

        // owner, so reclaiming both Boxes and `forget`-ing `self` transfers ownership

        // without a double free / running the destructor twice.

        unsafe {

            } else {

            }

        }

        // SAFETY: `data` is a non-null, live `Box` allocation owned by this handle

        // (and its shallow clones) until the last copy drops; the returned borrow is

        // tied to `&self`, so it cannot outlive the allocation.

        // SAFETY: `copies` is a non-null, live allocation for the lifetime of `&self`.

        // SAFETY: `data` is a non-null, live `Box` allocation; borrow tied to `&self`.

        }

        // SAFETY: `copies` is a non-null, live allocation for the lifetime of `&self`.

        // SAFETY: `copies == 1` proven above, so `&mut self` is the unique owner of

        // the `data` allocation; the exclusive borrow is tied to `&mut self`.

        }

    /// In difference to the default shallow copy, creates a new image ref

            DecodedImage::NullImage {

            // NOTE: textures cannot be deep-copied yet (since the OpenGL calls for that

            // are missing from the trait), so calling clone() on a GL texture will result in an

            // empty image

            // WARNING: the data may still be a U8Vec<'static> - the data may still not be

            // actually cloned. The data only gets cloned on a write operation

            }

        };