//! Generic icon provider system for Azul

//!

//! This module defines a generic, callback-based icon resolution infrastructure.

//! The actual parsing/loading implementations live in `azul-layout`.

//!

//! # Architecture

//!

//! The icon system is fully generic using RefAny:

//!

//! 1. `IconProviderHandle` - stores icons in nested map: pack_name → (icon_name → RefAny)

//! 2. The resolver callback turns (icon_data, original_dom) into a StyledDom

//! 3. Differentiation between Image/Font/SVG/etc. is via RefAny::downcast

//! 4. Supports any icon source: images, fonts, SVGs, animated icons, etc.

//!

//! # Resolution Flow

//!

//! 1. User creates Icon nodes: `Dom::create_icon("home")`

//! 2. Before layout, `resolve_icons_in_styled_dom()` is called

//! 3. Each Icon node is looked up across all packs (first match wins)

//! 4. The resolver callback is invoked with the found RefAny data + original DOM

//! 5. The callback returns a StyledDom subtree that replaces the icon node

//!

//! # Caching

//!

//! Resolution results are CACHED on the [`SharedIconProvider`], keyed by

//! (icon spec, the original icon node's full `NodeData`, its `StyledNode`),

//! and flushed when the `SystemStyle` changes. The engine calls

//! `resolve_icons_in_styled_dom` on EVERY DOM regeneration — during a Wayland

//! drag-resize that is one call per pixel of mouse movement (373 in a measured

//! 5-second drag), and each un-cached resolution runs `StyledDom::create`'s

//! full single-node cascade whose output is then thrown away by the host's

//! own cascade recompute. ~66 ribbon icons × 373 regenerations ≈ 24 600

//! throwaway cascades per drag, all yielding bit-identical results

//! (scripts/RSS_MAP_2026_08_07.md §36c).

//!

//! The cache stores the resolver's output DECONSTRUCTED into exactly the

//! fields the replacement consumes (node type, inline style, accessibility,

//! styled node), so a hit is four field clones — no `Dom`, no `StyledDom`,

//! no cascade, no `CssPropertyCache`, not even the single-node extraction of

//! the original.

//!

//! Correctness notes:

//! - The KEY includes the whole original `NodeData` + `StyledNode`, because a

//!   custom resolver may read anything from `original_icon_dom` (the default

//!   one copies inline styles and accessibility info). Same name with

//!   different inline styles → separate entries; a hover-state flip on the

//!   node → different `StyledNode` → re-resolve.

//! - The icon SET and the resolver are frozen once the provider is shared

//!   (`App::run` consumes the handle; `SharedIconProvider` exposes no

//!   registration), so registration invalidation cannot be needed post-share.

//! - "Animated icons" remain compatible: animation is carried by the DATA the

//!   resolver returns (e.g. an image-callback node that animates per frame),

//!   not by re-resolving per frame — re-resolution only ever happened on DOM

//!   regeneration anyway.

//!

//! # Custom Resolvers

//!

//! Users can provide custom C callbacks for complete control:

//!

//! ```c

//! AzStyledDom my_resolver(

//!     AzRefAny* icon_data,           // NULL if icon not found

//!     AzStyledDom* original_icon_dom, // Contains icon_name, styles, a11y

//!     AzSystemStyle* system_style

//! ) {

//!     // Custom resolution logic - icon_data contains your registered data

//!     return create_my_icon_dom(...);

//! }

//! ```

use alloc::{

    boxed::Box,

    collections::BTreeMap,

    string::{String, ToString},

    sync::Arc,

    vec::Vec,

};

use core::fmt;

use core::mem::ManuallyDrop;

#[cfg(feature = "std")]

use std::sync::Mutex;

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

use self::nostd_lock::Mutex;

/// Minimal `no_std` spinlock that mirrors the slice of the `std::sync::Mutex`

/// API actually used by this module (`new` + `lock` returning a `Result`).

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

mod nostd_lock {

    use core::cell::UnsafeCell;

    use core::ops::{Deref, DerefMut};

    use core::sync::atomic::{AtomicBool, Ordering};

    pub struct Mutex<T> {

        locked: AtomicBool,

        data: UnsafeCell<T>,

    }

    unsafe impl<T: Send> Send for Mutex<T> {}

    unsafe impl<T: Send> Sync for Mutex<T> {}

    pub struct MutexGuard<'a, T> {

        lock: &'a Mutex<T>,

    }

    impl<T> Mutex<T> {

        pub fn new(data: T) -> Self {

            Mutex { locked: AtomicBool::new(false), data: UnsafeCell::new(data) }

        }

        /// Returns `Ok(guard)` to mirror `std::sync::Mutex::lock`. Never poisons.

        pub fn lock(&self) -> Result<MutexGuard<'_, T>, core::convert::Infallible> {

            while self

                .locked

                .compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed)

                .is_err()

            {

                core::hint::spin_loop();

            }

            Ok(MutexGuard { lock: self })

        }

    }

    impl<'a, T> Deref for MutexGuard<'a, T> {

        type Target = T;

        fn deref(&self) -> &T {

            unsafe { &*self.lock.data.get() }

        }

    }

    impl<'a, T> DerefMut for MutexGuard<'a, T> {

        fn deref_mut(&mut self) -> &mut T {

            unsafe { &mut *self.lock.data.get() }

        }

    }

    impl<'a, T> Drop for MutexGuard<'a, T> {

        fn drop(&mut self) {

            self.lock.locked.store(false, Ordering::Release);

        }

    }

    // Mirror `std::sync::Mutex: Debug` so containers can derive Debug. Does not

    // lock (the spinlock has no `try_lock`, and locking in `fmt` could deadlock).

    impl<T> core::fmt::Debug for Mutex<T> {

        fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {

            f.debug_struct("Mutex").finish_non_exhaustive()

        }

    }

}

use azul_css::{AzString, system::SystemStyle};

use crate::{

    dom::{Dom, NodeData, NodeType},

    refany::{OptionRefAny, RefAny},

    styled_dom::StyledDom,

};

// Type name constants for RefAny-based icon type detection in debug output

const IMAGE_ICON_DATA_TYPE_NAME: &str = "ImageIconData";

const FONT_ICON_DATA_TYPE_NAME: &str = "FontIconData";

// Icon Resolver Callback

/// Callback type for resolving icon data to a `StyledDom`.

///

/// Parameters:

/// - `icon_data`: The `RefAny` data from the icon pack (cloned, or None if not found)

/// - `original_icon_dom`: The original icon node's `StyledDom` (contains inline styles, a11y info, `icon_name`)

/// - `system_style`: Current system style (theme, colors, etc.)

///

/// Returns: A `StyledDom` that will replace the icon node.

/// The resolver should copy relevant styles from `original_icon_dom` to the result.

/// Return an empty `StyledDom` to show a placeholder or nothing.

///

/// Note: `icon_name` is accessible via `original_icon_dom.node_data[0].get_node_type()` → `NodeType::Icon(name)`

pub type IconResolverCallbackType = extern "C" fn(

    icon_data: OptionRefAny,

    original_icon_dom: &StyledDom,

    system_style: &SystemStyle,

) -> StyledDom;

/// Default resolver that returns an empty `StyledDom` (shows placeholder)

    // Default: return empty DOM (icon won't be visible)

// Icon Provider Inner (single mutex)

/// Inner data for `IconProviderHandle` - all fields behind single mutex

#[derive(Debug, Clone)]

pub struct IconProviderInner {

    /// Nested map: `pack_name` → (`icon_name` → `RefAny`)

    /// Differentiation between Image/Font/SVG is via `RefAny::downcast`

    pub icons: BTreeMap<String, BTreeMap<String, RefAny>>,

    /// The resolver callback

    pub resolver: IconResolverCallbackType,

}

impl Default for IconProviderInner {

}

// Icon Provider Handle

/// Icon provider stored in `AppConfig`.

///

/// This is a Box<IconProviderInner> for C FFI compatibility.

/// When `App::run()` is called, it gets converted to Arc<Mutex<IconProviderInner>>

/// and cloned to each window.

///

/// Icons are stored in a nested map: `pack_name` → (`icon_name` → `RefAny`)

/// This allows:

/// - Multiple packs with different sources (app-images, material-icons, etc.)

/// - Easy unregistration of entire packs

/// - First-match-wins lookup across all packs

#[repr(C)]

pub struct IconProviderHandle {

    /// Boxed inner data - Box<T> is repr(C) compatible (single pointer).

    /// `ManuallyDrop` so the Box is freed ONLY by our `Drop` (gated on

    /// `run_destructor`), never by drop-glue. The codegen Az wrapper nests an

    /// `AzIconProviderHandle` field (in `AzAppConfig`) whose own `Drop` re-runs

    /// `_delete` -> `drop_in_place::<IconProviderHandle>` on the SAME bytes; with

    /// a bare `Box` the glue freed it a second time -> double free. Same

    /// convention as `GlContextPtr` / `CssPropertyCachePtr`.

    pub inner: ManuallyDrop<Box<IconProviderInner>>,

    pub run_destructor: bool,

}

impl Clone for IconProviderHandle {

}

impl Drop for IconProviderHandle {

        // First drop (run_destructor still true) frees the Box and clears the flag

        // in the shared bytes; the codegen's redundant second drop sees false -> no-op.

}

impl fmt::Debug for IconProviderHandle {

}

impl Default for IconProviderHandle {

}

impl IconProviderInner {

    /// Resolves an icon SPEC to registered icon data.

    ///

    /// A spec is a comma-separated fallback list of entries, each either a

    /// bare icon name (`"content_copy"`, searched across all packs in

    /// registration order, first match wins) or a pack-qualified name

    /// (`"material-icons:save"`, searched only in that pack). The first

    /// entry that resolves wins, so markup can express per-platform

    /// fallbacks: `<icon>ios:open_menu,kde:three-lines,menu</icon>`.

    /// Icon names are case-insensitive; pack names are case-sensitive.

        // Verbatim first: a registered name is always found as-is (names may

        // legally contain ':', ',' or whitespace). The spec syntax below only

        // applies when nothing is registered under the literal name.

            };

            );

        }

}

impl IconProviderHandle {

    /// Create a new empty icon provider with the default (no-op) resolver.

    /// 

    /// Note: The default resolver in core crate returns an empty `StyledDom`.

    /// Use `set_resolver()` to set a proper resolver from the layout crate,

    /// or use `with_resolver()` to create with a custom resolver.

    /// Create with a custom resolver callback

    /// Convert this handle into an Arc<Mutex<IconProviderInner>> for use in windows.

    ///

    /// This consumes the Box and creates an Arc. Called by `App::run()` to create

    /// the shared icon provider that gets cloned to each window.

        // Take the Box out and disarm our Drop so it doesn't free the moved-out

        // allocation (ManuallyDrop::take leaves `inner` logically uninitialized).

    /// Set the resolver callback

    /// Register a single icon in a pack (creates pack if needed).

    ///

    /// Note: `pack_name` is case-sensitive, while `icon_name` is normalized to lowercase.

    /// Unregister a single icon from a pack

    /// Unregister an entire icon pack

    /// Look up an icon across all packs, returning the pack name and data reference (first match wins)

        }

    /// Look up an icon by spec (bare name, `pack:name`, or a comma-separated

    /// fallback list of either form; first match wins).

    /// Check if an icon spec resolves in any pack

    /// List all pack names

    /// List all icon names in a specific pack

    /// Debug lookup: returns detailed info about an icon's `RefAny` contents

    #[allow(clippy::used_underscore_binding)] // intentional `_`-prefix (FFI/api.json pub field, or cfg-gated binding); access is deliberate

        use core::fmt::Write;

        // Report registered packs

        }

        // Find the icon using shared lookup helper

            }

        }

}

/// Thread-safe icon provider for use in windows.

/// 

/// This is created from `IconProviderHandle::into_shared()` in `App::run()`

/// and cloned to each window.

#[derive(Debug, Clone)]

pub struct SharedIconProvider {

    inner: Arc<Mutex<IconProviderInner>>,

    /// Resolution cache — see the module-level `# Caching` section. Shared by

    /// every clone of this provider (all windows), like `inner`.

    cache: Arc<Mutex<IconResolutionCache>>,

}

/// Hard cap on cached resolutions. A frame's live icon set is typically a few

/// dozen; the cap only matters when specs vary without bound (adversarial or

/// generated names). Policy on overflow is FLUSH-ALL: the next frame re-fills

/// with the live set, so a pathological producer degrades to today's uncached

/// behaviour instead of growing without limit.

const ICON_CACHE_CAP: usize = 512;

/// A resolver result, stored DECONSTRUCTED into exactly what

/// [`apply_cached_resolution`] consumes. See the module `# Caching` docs for

/// why this is not a `StyledDom`.

#[derive(Debug, Clone)]

enum CachedIconResolution {

    /// Resolver returned a zero-node `StyledDom` → the icon becomes an empty

    /// `Div` placeholder (same as the uncached empty arm).

    Empty,

    /// The dominant case: a single-node replacement.

    SingleNode {

        node_type: NodeType,

        style: azul_css::css::Css,

        accessibility: Option<Box<crate::a11y::AccessibilityInfo>>,

        /// `None` = the replacement carried no styled node; keep the host's

        /// (exact parity with the uncached path, which only overwrites when

        /// the replacement's `styled_nodes` is non-empty).

        styled_node: Option<Box<crate::styled_dom::StyledNode>>,

    },

    /// Multi-node subtree, cloned wholesale on hit. Rare — and today's

    /// splicing uses only its root (see `apply_multi_node_replacement`) — but

    /// stored complete so implementing real splicing later cannot be silently

    /// truncated by this cache.

    Subtree(Box<StyledDom>),

}

/// One cached resolution. `original`/`original_styled` are the KEY (together

/// with the spec, the map key one level up); `resolution` is the value.

#[derive(Debug)]

struct IconCacheEntry {

    original: NodeData,

    original_styled: crate::styled_dom::StyledNode,

    resolution: CachedIconResolution,

}

/// See the module-level `# Caching` section.

#[derive(Debug, Default)]

struct IconResolutionCache {

    /// The `SystemStyle` every entry was resolved under. A mismatch flushes:

    /// resolvers read the style (theme, tint, grayscale), so entries from

    /// another style are wrong, not merely stale.

    system_style: Option<SystemStyle>,

    /// spec → entries with that spec (usually exactly one; more when the same

    /// icon name appears with different inline styles).

    entries: BTreeMap<String, Vec<IconCacheEntry>>,

    /// Total entry count across all specs (the map holds vecs, so `len()` of

    /// the map alone cannot enforce [`ICON_CACHE_CAP`]).

    total: usize,

}

impl SharedIconProvider {

    /// Create from an `IconProviderHandle` (consumes the handle)

    /// Flush the cache if `system_style` differs from the one its entries

    /// were resolved under. Called ONCE per `resolve_icons_in_styled_dom`

    /// batch, not per icon, so the `SystemStyle` comparison is per-frame.

        }

    /// Cache hit test. `None` = miss (resolve for real, then

    /// [`Self::store_resolution`]).

    /// Insert a freshly-resolved entry, flushing everything first if the cap

    /// is reached (see [`ICON_CACHE_CAP`]).

    /// Resolve an icon to a `StyledDom` using the registered callback

            };

        };

    /// Look up an icon by spec (bare name, `pack:name`, or a comma-separated

    /// fallback list of either form; first match wins)

    /// Check if an icon spec resolves

}

// Icon Resolution in StyledDom

/// Collected icon node info for replacement

struct CollectedIcon {

    /// Index in the `node_data` array

    node_idx: usize,

    /// The icon spec (explicit name, or derived from the node's text children)

    icon_name: AzString,

    /// Text children that supplied the spec (`<icon>name</icon>` markup form);

    /// their text is cleared once the icon node is replaced so the raw spec

    /// never renders next to the resolved icon.

    text_children: Vec<usize>,

}

/// Replacement result after resolving an icon

struct IconReplacement {

    /// Index of the icon node to replace

    node_idx: usize,

    /// The resolved replacement, already normalized for both the apply step

    /// and the cache (empty / single node / subtree)

    replacement: CachedIconResolution,

    /// Spec-supplying text children to clear after the swap

    text_children: Vec<usize>,

}

/// Collect all Icon nodes from the `StyledDom`.

///

/// An Icon node with an explicit non-empty name (`Dom::create_icon("x")`)

/// uses that name directly. An Icon node with an EMPTY name — the markup

/// form `<icon>content_copy</icon>`, where the tag itself carries no name —

/// derives its spec from its direct text children, exactly like a ligature

/// icon font turns glyph text into an icon. The arena is in DFS order, so a

/// node's children always appear after the node itself.

    use alloc::collections::BTreeMap;

    // node_idx of un-named icon → position in `icons`

            }

                else {

                };

                };

            }

        }

    }

    }

/// Extract a single-node `StyledDom` from a parent `StyledDom` at the given index.

/// This creates a minimal `StyledDom` containing just that node for the resolver.

    use crate::dom::{NodeDataVec, DomId};

    use crate::id::NodeId;

    use crate::styled_dom::{

        StyledNodeVec, NodeHierarchyItemIdVec, TagIdToNodeIdMappingVec,

        NodeHierarchyItemVec, NodeHierarchyItem, NodeHierarchyItemId,

        ParentWithNodeDepthVec, ParentWithNodeDepth,

    };

    use crate::style::{CascadeInfoVec, CascadeInfo};

    use crate::prop_cache::{CssPropertyCachePtr, CssPropertyCache};

    // Clone the single node

    } else {

    };

/// Resolve all collected icons, consulting the provider's cache first.

///

/// On a HIT nothing is built at all: no single-node extraction (which clones

/// the node's inline `Css` and allocates a throwaway `CssPropertyCache`), no

/// pack lookup, no resolver call, no cascade. The 66-icon ribbon that

/// motivated this (`RSS_MAP` §36c) turns from 66 resolver round-trips per DOM

/// regeneration into 66 key comparisons.

        // The key mirrors what `extract_single_node_styled_dom` would hand the

        // resolver: this node's data + styled state (default when absent,

        // matching the extraction's own fallback).

        // MISS: the uncached path, exactly as before — extract, resolve —

        // followed by normalize + store.

/// Deconstruct a resolver-returned `StyledDom` into [`CachedIconResolution`].

///

/// The single-node arm takes the SAME fields, by move, that

/// `apply_single_node_replacement` takes — everything else in the returned

/// `StyledDom` (notably the `CssPropertyCache` its cascade just built) was

/// always discarded, which is precisely why the result is cacheable in this

/// reduced form.

        1 => {

            } else {

            };

        }

    }

/// Apply a normalized resolution to the icon node at `node_idx`. Semantics

/// are bit-for-bit those of the pre-cache code: `Empty` → placeholder `Div`

/// (old `apply_single_node_replacement` empty arm), `SingleNode` → move the

/// four fields in (old non-empty arm), `Subtree` → root-only splice via

/// `apply_multi_node_replacement`.

        CachedIconResolution::Empty => {

        }

        }

    }

/// Check if a replacement is a single-node replacement (fast path)

/// Apply a single-node replacement (fast path: swap `NodeType` and MOVE properties).

///

/// Takes the replacement BY VALUE. It was previously borrowed and every field

/// deep-copied out of it — `NodeType`, the inline `Css`, the accessibility

/// box, and the `StyledNode` — even though the caller already owns each

/// replacement (`replacements.into_iter()`) and drops it immediately after.

///

/// Cloning a `Css` is not cheap: it is a `CssRuleBlockVec`, each block holding

/// a `CssDeclarationVec`, and `Css::from(CssPropertyWithConditionsVec)`

/// (`css/src/css.rs:171`) builds ONE rule block with a ONE-ELEMENT declaration

/// vec per property — so a widget with N inline properties is N separate heap

/// allocations, and cloning it re-allocates all N. Measured on an icon-dense

/// ribbon: 304 style clones cascading into **14 690** `CssDeclarationVec`

/// clones, ~2 MB of transient churn that glibc never returns to the OS.

///

/// Moving costs nothing and cannot fail. This is a memory AND a latency fix.

        // Empty replacement - convert to empty div

    // Consume the replacement so its root's fields can be MOVED rather than

    // cloned. `swap_remove(0)` is fine: only index 0 is read, and the vec is

    // dropped immediately after.

    // Also update the styled_nodes to reflect the new styling.

/// Apply multi-node replacement using subtree splicing

    // Read the length BEFORE moving — it is used again after the call.

    // For now, just apply the root node (same as single-node). Ownership is

    // threaded through so the root's fields MOVE rather than being cloned;

    // see apply_single_node_replacement.

/// Resolve all Icon nodes in a `StyledDom` to their actual content.

///

/// This function:

/// 1. Collects all Icon nodes from the `StyledDom`

/// 2. Resolves each icon via the provider's callback (passing original icon DOM)

/// 3. Applies replacements (single-node fast path or multi-node splicing)

///

/// This should be called after `StyledDom` creation but before layout.

    // Step 1: Collect all icon nodes

    // Step 1.5: A SystemStyle change (theme flip, tint, grayscale) invalidates

    // every cached resolution. Checked once per batch, not once per icon.

    // Step 2: Resolve all icons (cache-first; see resolve_collected_icons)

    // Step 3: Apply replacements (reverse order to preserve indices)

        );

        // `<icon>name</icon>`: the spec text was consumed by the resolution —

        // clear the contributing text children so the raw name never renders

        // next to (or instead of) the resolved icon.

        }

    }

// FFI Option Types

impl_option!(

    IconProviderHandle,

    OptionIconProviderHandle,

    [Clone]

);

#[cfg(test)]

#[allow(clippy::float_cmp, clippy::too_many_lines)]

mod autotest_generated {

    use core::sync::atomic::{AtomicBool, AtomicUsize, Ordering as AtomicOrdering};

    use super::*;

    use crate::{dom::NodeDataVec, styled_dom::StyledNodeVec};

    // Test payloads. The names `ImageIconData` / `FontIconData` are load-bearing:

    // `debug_lookup` sniffs `RefAny::get_type_name()` (i.e. `core::any::type_name`)

    // for those substrings.

    #[derive(Debug, Clone, PartialEq)]

    struct TestIconData {

        id: u32,

    }

    #[derive(Debug)]

    struct ImageIconData {

        _w: u32,

    }

    #[derive(Debug)]

    struct FontIconData {

        _codepoint: u32,

    }

    /// Empty / control / unicode / huge names, all of which are legal icon names

    /// (the API places no constraints on them).

    fn adversarial_names() -> Vec<String> {

        vec![

            String::new(),

            String::from(" "),

            String::from("   "),

            String::from("\t\n\r"),

            String::from("\0"),

            String::from("a\0b"),

            String::from("\u{1b}[0m"),

            String::from("../../etc/passwd"),

            String::from("home;garbage"),

            String::from("{\"json\":true}"),

            String::from("-0"),

            String::from("NaN"),

            String::from("inf"),

            String::from("9223372036854775807"),

            String::from("\u{1F600}"),               // emoji

            String::from("e\u{0301}\u{0301}"),       // combining marks

            String::from("\u{202e}RTL\u{202d}"),     // bidi override

            String::from("\u{130}"),                 // LATIN CAPITAL I WITH DOT ABOVE

            String::from("\u{FFFD}\u{10FFFF}"),      // replacement + max scalar

            "[".repeat(10_000),                      // deeply "nested" junk

            "x".repeat(100_000),                     // huge

        ]

    }

    fn styled_dom_with_icons(names: &[&str]) -> StyledDom {

        let mut body = Dom::create_body();

        for n in names {

            body.add_child(Dom::create_icon(*n));

        }

        StyledDom::create_from_dom(body)

    }

    /// A `StyledDom` with *zero* nodes — `StyledDom::default()` has one (a Body),

    /// so the truly-empty case has to be built by hand.

    fn zero_node_styled_dom() -> StyledDom {

        StyledDom {

            node_data: NodeDataVec::from_vec(Vec::new()),

            styled_nodes: StyledNodeVec::from_vec(Vec::new()),

            ..StyledDom::default()

        }

    }

    fn node_type_at(sd: &StyledDom, idx: usize) -> NodeType {

        sd.node_data.as_ref()[idx].get_node_type().clone()

    }

    fn icon_indices(sd: &StyledDom) -> Vec<usize> {

        collect_icon_nodes(sd).iter().map(|i| i.node_idx).collect()

    }

    // Resolvers

    extern "C" fn div_resolver(

        _icon_data: OptionRefAny,

        _original_icon_dom: &StyledDom,

        _system_style: &SystemStyle,

    ) -> StyledDom {

        StyledDom::create_from_dom(Dom::create_div())

    }

    extern "C" fn zero_node_resolver(

        _icon_data: OptionRefAny,

        _original_icon_dom: &StyledDom,

        _system_style: &SystemStyle,

    ) -> StyledDom {

        zero_node_styled_dom()

    }

    // Statics for `shared_resolve_receives_icon_data_and_original_dom` ONLY.

    // (`extern "C" fn` cannot capture, and tests run in parallel — never share

    // one recording resolver between two tests.)

    static REC_CALLS: AtomicUsize = AtomicUsize::new(0);

    static REC_SAW_DATA: AtomicBool = AtomicBool::new(false);

    static REC_SAW_ICON_NODE: AtomicBool = AtomicBool::new(false);

    static REC_NAME_LEN: AtomicUsize = AtomicUsize::new(0);

    extern "C" fn recording_resolver(

        icon_data: OptionRefAny,

        original_icon_dom: &StyledDom,

        _system_style: &SystemStyle,

    ) -> StyledDom {

        REC_CALLS.fetch_add(1, AtomicOrdering::SeqCst);

        if matches!(icon_data, OptionRefAny::Some(_)) {

            REC_SAW_DATA.store(true, AtomicOrdering::SeqCst);

        }

        if let Some(node) = original_icon_dom.node_data.as_ref().first() {

            if let NodeType::Icon(name) = node.get_node_type() {

                REC_SAW_ICON_NODE.store(true, AtomicOrdering::SeqCst);

                REC_NAME_LEN.store(name.as_ref().as_str().len(), AtomicOrdering::SeqCst);

            }

        }

        StyledDom::create_from_dom(Dom::create_div())

    }

    // Mutex (the no_std spinlock under `no_std`, `std::sync::Mutex` otherwise)

    #[test]

    fn mutex_new_then_lock_roundtrips_the_value() {

        let m = Mutex::new(42u32);

        assert_eq!(*m.lock().unwrap(), 42);

        *m.lock().unwrap() = u32::MAX;

        assert_eq!(*m.lock().unwrap(), u32::MAX);

    }

    #[test]

    fn mutex_lock_on_empty_and_large_payloads() {

        let empty: Mutex<Vec<u8>> = Mutex::new(Vec::new());

        assert!(empty.lock().unwrap().is_empty());

        let big = Mutex::new(vec![0u8; 1_000_000]);

        assert_eq!(big.lock().unwrap().len(), 1_000_000);

        // Sequential re-lock must not deadlock (guard dropped at end of statement).

        for _ in 0..1_000 {

            assert!(big.lock().is_ok());

        }

    }

    // default_icon_resolver

    #[test]

    fn default_resolver_returns_one_body_node_for_none_and_some() {

        let orig = StyledDom::default();

        let style = SystemStyle::default();

        let none = default_icon_resolver(OptionRefAny::None, &orig, &style);

        // NOTE: the doc calls this an "empty StyledDom", but `StyledDom::default()`

        // carries exactly one node (a Body), so the result is single-node, NOT empty.

        assert_eq!(none.node_data.as_ref().len(), 1);

        assert!(is_single_node_replacement(&none));

        let some = default_icon_resolver(

            OptionRefAny::Some(RefAny::new(TestIconData { id: 1 })),

            &orig,

            &style,

        );

        assert_eq!(some.node_data.as_ref().len(), 1);

    }

    #[test]

    fn default_resolver_no_panic_on_zero_node_original_dom() {

        let orig = zero_node_styled_dom();

        let style = SystemStyle::default();

        let out = default_icon_resolver(OptionRefAny::None, &orig, &style);

        assert_eq!(out.node_data.as_ref().len(), 1);

    }

    // IconProviderHandle: construction / invariants

    #[test]

    fn new_handle_is_empty_and_all_queries_are_negative() {

        let h = IconProviderHandle::new();

        assert!(h.list_packs().is_empty());

        assert!(h.list_icons_in_pack("anything").is_empty());

        assert!(!h.has_icon("home"));

        assert!(h.lookup("home").is_none());

        assert!(h.lookup_with_pack("home").is_none());

        assert!(h.debug_lookup("home").as_str().contains("Total packs: 0"));

    }

    #[test]

    fn default_handle_matches_new_handle() {

        let a = IconProviderHandle::default();

        let b = IconProviderHandle::new();

        assert_eq!(a.list_packs(), b.list_packs());

        assert_eq!(a.has_icon(""), b.has_icon(""));

    }

    #[test]

    fn with_resolver_installs_the_callback() {

        let mut h = IconProviderHandle::with_resolver(div_resolver);

        h.register_icon("p", "home", RefAny::new(TestIconData { id: 1 }));

        let shared = SharedIconProvider::from_handle(h);

        let out = shared.resolve(&StyledDom::default(), "home", &SystemStyle::default());

        assert!(matches!(node_type_at(&out, 0), NodeType::Div));

    }

    #[test]

    fn set_resolver_overrides_the_default_resolver() {

        let mut h = IconProviderHandle::new();

        h.set_resolver(div_resolver);

        let shared = SharedIconProvider::from_handle(h);

        // Unregistered icon: resolver still runs, just with `None` data.

        let out = shared.resolve(&StyledDom::default(), "missing", &SystemStyle::default());

        assert!(matches!(node_type_at(&out, 0), NodeType::Div));

    }

    #[test]

    fn clone_of_handle_is_deep() {

        let mut a = IconProviderHandle::new();

        a.register_icon("p", "home", RefAny::new(TestIconData { id: 1 }));

        let mut b = a.clone();

        b.register_icon("p", "settings", RefAny::new(TestIconData { id: 2 }));

        b.unregister_icon("p", "home");

        assert!(a.has_icon("home"));

        assert!(!a.has_icon("settings"));

        assert!(b.has_icon("settings"));

        assert!(!b.has_icon("home"));

    }

    #[test]

    fn drop_of_clones_and_originals_is_safe() {

        // Guards the ManuallyDrop / run_destructor convention (see the type's docs).

        let mut a = IconProviderHandle::new();

        a.register_icon("p", "home", RefAny::new(TestIconData { id: 1 }));

        for _ in 0..100 {

            let c = a.clone();

            drop(c);

        }

        assert!(a.has_icon("home"));

        drop(a);

    }

    // register / unregister

    #[test]

    fn register_icon_lowercases_icon_name_but_not_pack_name() {

        let mut h = IconProviderHandle::new();

        h.register_icon("MyPack", "HoMe", RefAny::new(TestIconData { id: 1 }));

        assert_eq!(h.list_packs(), vec![String::from("MyPack")]);

        assert!(h.list_icons_in_pack("MyPack").contains(&String::from("home")));

        // Pack name is case-sensitive:

        assert!(h.list_icons_in_pack("mypack").is_empty());

        // Icon name is not:

        assert!(h.has_icon("HOME"));

        assert!(h.has_icon("home"));

        assert!(h.has_icon("hOmE"));

    }

    #[test]

    fn registering_the_same_icon_twice_overwrites_instead_of_duplicating() {

        let mut h = IconProviderHandle::new();

        h.register_icon("p", "home", RefAny::new(TestIconData { id: 1 }));

        h.register_icon("p", "HOME", RefAny::new(TestIconData { id: 2 }));

        assert_eq!(h.list_icons_in_pack("p").len(), 1);

        let mut data = h.lookup("home").expect("icon must exist");

        assert_eq!(data.downcast_ref::<TestIconData>().unwrap().id, 2);

    }

    #[test]

    fn unregister_icon_drops_the_pack_once_it_is_empty() {

        let mut h = IconProviderHandle::new();

        h.register_icon("p", "home", RefAny::new(TestIconData { id: 1 }));

        h.register_icon("p", "settings", RefAny::new(TestIconData { id: 2 }));

        h.unregister_icon("p", "HOME"); // case-insensitive on the icon name

        assert_eq!(h.list_packs(), vec![String::from("p")]);

        assert!(!h.has_icon("home"));

        h.unregister_icon("p", "settings");

        assert!(h.list_packs().is_empty(), "pack must be pruned when empty");

    }

    #[test]

    fn unregister_of_unknown_pack_or_icon_is_a_no_op() {

        let mut h = IconProviderHandle::new();

        h.register_icon("p", "home", RefAny::new(TestIconData { id: 1 }));

        h.unregister_icon("nonexistent-pack", "home");

        h.unregister_icon("p", "nonexistent-icon");

        h.unregister_pack("nonexistent-pack");

        h.unregister_pack("");

        h.unregister_icon("", "");

        assert!(h.has_icon("home"));

        assert_eq!(h.list_packs().len(), 1);

    }