//! Core FFI-safe types used across crate boundaries.

//!

//! This module defines the fundamental types for FFI interop: [`AzString`] (an FFI-safe

//! string backed by [`U8Vec`] with destructor-based memory management), [`EmptyStruct`] (a

//! non-zero-size unit type), and various `Vec`/`Option` wrappers generated by the

//! `impl_vec!` and `impl_option!` macros.

use alloc::{

    string::{String, ToString},

    vec::Vec,

};

use crate::props::basic::ColorU;

// ============================================================================

// EmptyStruct type - FFI-safe replacement for ()

// ============================================================================

/// FFI-safe void type to replace `()` in Result types.

/// 

/// Since `()` (unit type) has zero size, it's not FFI-safe.

/// This type provides a minimal 1-byte representation that can be

/// safely passed across the C ABI boundary.

/// 

/// # Usage

/// Instead of `Result<(), Error>`, use `Result<EmptyStruct, Error>`.

/// 

/// # Example

/// ```ignore

/// fn do_something() -> Result<EmptyStruct, MyError> {

///     // ... do work ...

///     Ok(EmptyStruct::default())

/// }

/// ```

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

#[repr(C)]

#[derive(Default)]

// `_reserved` is a deliberate padding-field name (C-ABI / api.json); cannot rename.

#[allow(clippy::pub_underscore_fields)]

pub struct EmptyStruct {

    /// Reserved byte to ensure the struct has non-zero size.

    /// Always initialized to 0.

    pub _reserved: u8,

}

impl EmptyStruct {

    /// Create a new `EmptyStruct` value (equivalent to `()`)

    #[must_use]

}

impl From<()> for EmptyStruct {

}

impl From<EmptyStruct> for () {

}

// ============================================================================

// Debug message types

// ============================================================================

/// Debug message severity or category for layout diagnostics.

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

#[repr(C)]

#[derive(Default)]

pub enum LayoutDebugMessageType {

    #[default]

    Info,

    Warning,

    Error,

    // Layout-specific categories for filtering

    BoxProps,

    CssGetter,

    /// Block Formatting Context layout

    BfcLayout,

    /// Inline Formatting Context layout

    IfcLayout,

    TableLayout,

    DisplayType,

    PositionCalculation,

}

/// A debug message emitted during layout, with severity, text, and source location.

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

#[repr(C)]

pub struct LayoutDebugMessage {

    pub message_type: LayoutDebugMessageType,

    pub message: AzString,

    pub location: AzString,

}

impl LayoutDebugMessage {

    /// Create a new debug message with automatic caller location tracking

    #[track_caller]

    /// Helper for Info messages

    #[track_caller]

    /// Helper for Warning messages

    #[track_caller]

    /// Helper for Error messages

    #[track_caller]

    /// Helper for `BoxProps` debug messages

    #[track_caller]

    /// Helper for CSS Getter debug messages

    #[track_caller]

    /// Helper for BFC Layout debug messages

    #[track_caller]

    /// Helper for IFC Layout debug messages

    #[track_caller]

    /// Helper for Table Layout debug messages

    #[track_caller]

    /// Helper for Display Type debug messages

    #[track_caller]

}

/// FFI-safe string type backed by [`U8Vec`] with destructor-based memory management.

///

/// Contents are guaranteed to be valid UTF-8 by all safe constructors.

/// Memory ownership is tracked via the inner `U8Vec`'s destructor field.

#[repr(C)]

pub struct AzString {

    pub vec: U8Vec,

}

impl_option!(

    AzString,

    OptionString,

    copy = false,

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

);

static DEFAULT_STR: &str = "";

impl Default for AzString {

}

impl<'a> From<&'a str> for AzString {

}

impl AsRef<str> for AzString {

}

impl core::fmt::Debug for AzString {

}

impl core::fmt::Display for AzString {

}

impl AzString {

    #[inline]

    /// Creates a new `AzString` from a null-terminated C string (const char*).

    /// This copies the string data into a new allocation.

    ///

    /// # Safety

    /// - `ptr` must be a valid pointer to a null-terminated UTF-8 string

    /// - The string must remain valid for the duration of this call

    ///

    /// Note: `ptr` is `*const i8` rather than `*const core::ffi::c_char`

    /// so the auto-generated FFI signature in `dll_api_internal.rs`

    /// (which uses a literal `i8`) matches on every target —

    /// `c_char` is `i8` on x86/ARM Apple/Windows/Linux but `u8` on

    /// Android, which would otherwise produce a `*const u8 vs *const i8`

    /// mismatch at codegen-call sites. We cast internally before

    /// handing the pointer to `CStr::from_ptr`.

    #[inline]

    /// Copies bytes from a pointer into a new `AzString`.

    /// This is useful for C FFI where you have a char* buffer.

    ///

    /// Invalid UTF-8 sequences are replaced with U+FFFD to maintain

    /// the UTF-8 invariant required by [`as_str()`](Self::as_str).

    ///

    /// `#[inline]` (2026-06-03 web-lift FIX): forces inlining into the

    /// `extern "C" AzString_copyFromBytes` wrapper so there is NO separate

    /// C-ABI(X8-sret) → Rust-ABI(X0-sret) boundary call. The lift mis-threads

    /// %state across that sret-in-X0 shift (X1/ptr 0x13f80→garbage, X3/len 5→0,

    /// empty `AzString`); inlining lets the wrapper do the alloc/memcpy directly

    /// with the standard X8-sret ABI the cascade proves works.

    #[inline]

        // web-lift FIX (2026-06-03): FAST PATH for already-valid UTF-8 (the common case, incl. all

        // ASCII like "Hello") — wrap the U8Vec directly, avoiding the `String::from_utf8_lossy()

        // .into_owned()` std sret-in-X0 call that the lift mis-threads (the returned String comes

        // back with len=0 → empty AzString). `core::str::from_utf8` returns a `Result<&str,_>` (a

        // slice, NOT a by-value struct) so it has no sret to mis-thread. Also a real perf win (no

        // 2nd alloc+copy for valid input). Slow path (rare, invalid UTF-8) keeps the lossy replace.

    #[inline] // web-lift: inline through the sret-in-X0 chain (see copy_from_bytes)

    #[inline]

    /// NOTE: CLONES the memory if the memory is external or &'static

    /// Moves the memory out if the memory is library-allocated

    #[inline]

    #[inline]

            U8VecDestructor::NoDestructor | U8VecDestructor::External(_) | U8VecDestructor::AlreadyDestroyed => {

            }

            U8VecDestructor::DefaultRust => {

            }

        }

    #[inline]

    #[inline]

    /// Returns the length of the string in bytes (not including null terminator)

    #[inline]

    /// Returns true if the string is empty

    #[inline]

    /// Creates a null-terminated copy of the string for C FFI usage.

    /// Returns a new `U8Vec` that contains the string data followed by a null byte.

    /// The caller is responsible for freeing this memory.

    ///

    /// Use this when you need to pass a string to C code that expects `const char*`.

    #[inline]

    /// Shared implementation for UTF-16 decoding with a caller-supplied byte-order function.

    ///

    /// # Safety

    /// - `ptr` must be valid for reading `len` bytes

    /// - `len` must be even (UTF-16 uses 2 bytes per code unit)

        // UTF-16 requires pairs of bytes

    /// Creates a new `AzString` from UTF-16 encoded bytes (little-endian).

    /// Returns an empty string if the input is invalid UTF-16 or has odd length.

    ///

    /// # Arguments

    /// * `ptr` - Pointer to UTF-16 encoded bytes

    /// * `len` - Length in bytes (not code units) - must be even

    ///

    /// # Safety

    /// - `ptr` must be valid for reading `len` bytes

    /// - `len` must be even (UTF-16 uses 2 bytes per code unit)

    #[inline]

    /// Creates a new `AzString` from UTF-16 encoded bytes (big-endian).

    /// Returns an empty string if the input is invalid UTF-16 or has odd length.

    ///

    /// # Arguments

    /// * `ptr` - Pointer to UTF-16 encoded bytes

    /// * `len` - Length in bytes (not code units) - must be even

    ///

    /// # Safety

    /// - `ptr` must be valid for reading `len` bytes

    /// - `len` must be even (UTF-16 uses 2 bytes per code unit)

    #[inline]

    /// Creates a new `AzString` from UTF-8 bytes with lossy conversion.

    /// Invalid UTF-8 sequences are replaced with the Unicode replacement character (U+FFFD).

    ///

    /// # Safety

    /// - `ptr` must be valid for reading `len` bytes

    #[inline]

    /// Creates a new `AzString` from UTF-8 bytes.

    /// Returns an empty string if the input is not valid UTF-8.

    ///

    /// # Safety

    /// - `ptr` must be valid for reading `len` bytes

    #[inline]

}

impl From<String> for AzString {

}

impl PartialOrd for AzString {

}

impl Ord for AzString {

}

impl Clone for AzString {

}

impl PartialEq for AzString {

}

impl Eq for AzString {}

impl core::hash::Hash for AzString {

    {

}

impl core::ops::Deref for AzString {

    type Target = str;

}

impl_option!(

    u8,

    OptionU8,

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

);

impl_vec!(u8, U8Vec, U8VecDestructor, U8VecDestructorType, U8VecSlice, OptionU8);

impl_vec_mut!(u8, U8Vec);

impl_vec_debug!(u8, U8Vec);

impl_vec_partialord!(u8, U8Vec);

impl_vec_ord!(u8, U8Vec);

impl_vec_clone!(u8, U8Vec, U8VecDestructor);

impl_vec_partialeq!(u8, U8Vec);

impl_vec_eq!(u8, U8Vec);

impl_vec_hash!(u8, U8Vec);

impl U8Vec {

    /// Copies bytes from a pointer into a new Vec.

    /// This is useful for C FFI where you have a `uint8_t`* buffer.

    ///

    /// # Safety contract (caller must ensure)

    /// - `ptr` must be valid for reading `start + len` bytes

    /// - `start + len` must not overflow

    #[inline] // web-lift: inline through the sret-in-X0 chain (see AzString::copy_from_bytes)

    #[allow(clippy::not_unsafe_ptr_arg_deref)] // SAFETY/FFI: `*const T` is the C-ABI signature; the fn null-checks then derefs under the documented caller contract (C guarantees a valid ptr/len). Marking it `unsafe fn` would force unsafe blocks into the generated dll bindings.

        );

}

impl_option!(

    U8Vec,

    OptionU8Vec,

    copy = false,

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

);

impl_vec!(u16, U16Vec, U16VecDestructor, U16VecDestructorType, U16VecSlice, OptionU16);

impl_vec_debug!(u16, U16Vec);

impl_vec_partialord!(u16, U16Vec);

impl_vec_ord!(u16, U16Vec);

impl_vec_clone!(u16, U16Vec, U16VecDestructor);

impl_vec_partialeq!(u16, U16Vec);

impl_vec_eq!(u16, U16Vec);

impl_vec_hash!(u16, U16Vec);

impl_vec!(f32, F32Vec, F32VecDestructor, F32VecDestructorType, F32VecSlice, OptionF32);

impl_vec_debug!(f32, F32Vec);

impl_vec_partialord!(f32, F32Vec);

impl_vec_clone!(f32, F32Vec, F32VecDestructor);

impl_vec_partialeq!(f32, F32Vec);

// Vec<char>

impl_vec!(u32, U32Vec, U32VecDestructor, U32VecDestructorType, U32VecSlice, OptionU32);

impl_vec_mut!(u32, U32Vec);

impl_vec_debug!(u32, U32Vec);

impl_vec_partialord!(u32, U32Vec);

impl_vec_ord!(u32, U32Vec);

impl_vec_clone!(u32, U32Vec, U32VecDestructor);

impl_vec_partialeq!(u32, U32Vec);

impl_vec_eq!(u32, U32Vec);

impl_vec_hash!(u32, U32Vec);

impl_vec!(AzString, StringVec, StringVecDestructor, StringVecDestructorType, StringVecSlice, OptionString);

impl_vec_debug!(AzString, StringVec);

impl_vec_partialord!(AzString, StringVec);

impl_vec_ord!(AzString, StringVec);

impl_vec_clone!(AzString, StringVec, StringVecDestructor);

impl_vec_partialeq!(AzString, StringVec);

impl_vec_eq!(AzString, StringVec);

impl_vec_hash!(AzString, StringVec);

impl From<Vec<String>> for StringVec {

}

impl_option!(

    StringVec,

    OptionStringVec,

    copy = false,

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

);

impl_option!(

    u16,

    OptionU16,

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

);

impl_option!(

    u32,

    OptionU32,

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

);

impl_option!(

    u64,

    OptionU64,

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

);

impl_option!(

    usize,

    OptionUsize,

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

);

impl_option!(

    i16,

    OptionI16,

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

);

impl_option!(

    i32,

    OptionI32,

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

);

impl_option!(bool, OptionBool, [Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]);

impl_option!(f32, OptionF32, [Debug, Copy, Clone, PartialEq]);

impl_option!(f64, OptionF64, [Debug, Copy, Clone, PartialEq, PartialOrd]);

// Manual implementations for Hash and Ord on OptionF32 (since f32 doesn't implement these traits)

impl core::hash::Hash for OptionF32 {

        }

}

impl Eq for OptionF32 {}

// Manual PartialOrd delegating to Ord keeps the two consistent (the derived

// PartialOrd would diverge from the manual Ord — see derive_ord_xor_partial_ord).

impl PartialOrd for OptionF32 {

}

impl Ord for OptionF32 {

            }

        }

}

// ============================================================================

// StringArena — bump allocator for AzString bytes

// ============================================================================

//

// Consolidates thousands of small AzString allocations (tag names,

// attribute values, text content) into a handful of 64 KiB chunks.

// Each arena-backed AzString uses `U8VecDestructor::External` and stashes

// a cloned `Arc<StringArenaInner>` pointer in the `cap` field — dropping

// the AzString decrements the refcount, and the backing bytes are freed

// only when the last reference goes away. This works across FFI without

// changing any public struct layout.

use alloc::sync::Arc;

use core::cell::UnsafeCell;

/// Shared interior of a [`StringArena`]. Refcounted via `Arc<Self>`;

/// never accessed through its `Arc` for mutation — only the owning

/// `StringArena` (with `&mut self`) mutates the chunks.

struct StringArenaInner {

    /// Pre-allocated byte chunks. Pointers into a chunk stay valid

    /// because we never push past `Vec::capacity()` — no reallocation.

    chunks: UnsafeCell<Vec<Vec<u8>>>,

    /// Remaining unused bytes in the last chunk; `0` when a fresh

    /// chunk is needed.

    current_remaining: UnsafeCell<usize>,

}

// Safety:

// - Mutation through `UnsafeCell` only happens via `&mut StringArena`,

//   which owns the sole external reference to `Arc<StringArenaInner>`

//   held in a `StringArena`. Other `Arc` references live inside AzString

//   destructors and never touch chunks — they only drop the Arc.

// - `Arc<T>` itself needs `T: Send + Sync` to cross threads; since the

//   destructor can run on any thread, we claim Send+Sync and rely on the

//   single-writer invariant for mutation safety.

unsafe impl Send for StringArenaInner {}

unsafe impl Sync for StringArenaInner {}

/// Bump allocator backing arena-owned `AzString` instances.

///

/// Every `AzString` returned by [`StringArena::intern`] holds a cloned

/// `Arc` to this arena; the backing bytes stay alive until the last

/// such `AzString` (and the arena handle itself) is dropped.

///

/// Intended use: create one arena per XML/HTML parse pass, intern all

/// tag names / attribute values / text content through it, then drop the

/// handle. The `AzStrings` embedded in the resulting `StyledDom` keep the

/// arena alive for as long as they need the bytes.

pub struct StringArena {

    inner: Arc<StringArenaInner>,

}

impl core::fmt::Debug for StringArena {

    // StringArenaInner holds UnsafeCell chunks (not Debug) — opaque by design.

}

impl StringArena {

    /// Size of a freshly allocated chunk. Large enough that a typical

    /// DOM parse fits in 1-2 chunks, small enough to not over-allocate

    /// for small documents.

    pub const CHUNK_SIZE: usize = 64 * 1024;

    /// Returns `(chunk_count, total_bytes_used)` for metrics.

        // Safety: metrics is read-only; the caller holds &self so no

        // concurrent mutation via &mut self is possible.

        unsafe {

        }

    /// Intern `s` into the arena and return an `AzString` whose backing

    /// bytes live inside the arena. The returned `AzString` owns a cloned

    /// `Arc` reference; dropping it decrements the refcount, and the

    /// arena frees its chunks when the final reference is released.

    ///

    /// # Panics

    ///

    /// Panics if the arena's internal chunk list is unexpectedly empty when

    /// appending a non-oversized string (an invariant violation that cannot

    /// occur through the public API, since a chunk is allocated on demand).

            // Empty strings don't need arena storage; a non-null dangling

            // pointer is fine because `len == 0` means nobody will deref.

        } else {

            // Safety: `&mut self` ⇒ exclusive access to inner chunks.

            unsafe {

                // Oversized strings get their own dedicated chunk so we

                // don't waste the tail of the current chunk.

                    // This dedicated chunk is FULL (len == cap). `remaining` must not

                    // keep describing the previous chunk, or the next small intern

                    // below would see a stale positive `remaining`, skip allocating,

                    // and `extend_from_slice` into THIS chunk — reallocating it and

                    // dangling the `p` we just handed out.

                } else {

                    // Safety: chunk was allocated with capacity ≥ len and

                    // `remaining` tracks unused capacity — no realloc.

                }

            }

        };

        // Each AzString carries its own Arc reference count. Stash the

        // raw Arc pointer in `cap` so the External destructor can decrement.

}

impl Default for StringArena {

}

/// Destructor installed on every arena-backed `AzString`. Reads the Arc

/// pointer out of `cap` and drops one Arc reference; when the count

/// reaches zero the `StringArenaInner` is freed.

    // Safety: called at most once per AzString drop. `cap` was set by

    // `StringArena::intern` to `Arc::into_raw(Arc<StringArenaInner>)`.

    unsafe {

    }

#[cfg(test)]

mod string_arena_tests {

    use super::*;

    #[test]

    #[test]

        };

    #[test]

    #[test]

        }

    #[test]

        // Cloning an External AzString deep-copies into DefaultRust, so

        // the clone doesn't depend on the arena at all.

        };

}

#[cfg(test)]

#[allow(clippy::all, clippy::pedantic, clippy::nursery)]

mod autotest_generated {

    use super::*;

    // ------------------------------------------------------------------

    // helpers

    // ------------------------------------------------------------------

    /// Minimal FNV-1a hasher so the Hash-consistency tests don't depend on

    /// `std` being linked (the crate keeps a `#![no_std]` line commented out).

    struct Fnv(u64);

    impl core::hash::Hasher for Fnv {

        fn finish(&self) -> u64 {

            self.0

        }

        fn write(&mut self, bytes: &[u8]) {

            for b in bytes {

                self.0 ^= u64::from(*b);

                self.0 = self.0.wrapping_mul(0x0100_0000_01b3);

            }

        }

    }

    fn hash_of<T: core::hash::Hash>(t: &T) -> u64 {

        use core::hash::{Hash, Hasher};

        let mut h = Fnv(0xcbf2_9ce4_8422_2325);

        Hash::hash(t, &mut h);

        h.finish()

    }

    /// UTF-16 code units of `s`, serialized to bytes with the given byte order.

    fn utf16_bytes(s: &str, little_endian: bool) -> Vec<u8> {

        s.encode_utf16()

            .flat_map(|u| {

                let b = if little_endian {

                    u.to_le_bytes()

                } else {

                    u.to_be_bytes()

                };

                [b[0], b[1]]

            })

            .collect()

    }

    // ==================================================================

    // EmptyStruct

    // ==================================================================

    #[test]

    fn empty_struct_new_invariants() {

        let e = EmptyStruct::new();

        assert_eq!(e._reserved, 0, "_reserved must always be initialized to 0");

        assert_eq!(e, EmptyStruct::default(), "new() must equal default()");

    }

    #[test]

    fn empty_struct_is_ffi_safe_non_zero_size() {

        // The whole point of the type: `()` is zero-sized and not FFI-safe.

        assert_eq!(size_of::<EmptyStruct>(), 1);

        assert_eq!(align_of::<EmptyStruct>(), 1);

    }

    #[test]

    fn empty_struct_unit_conversions_round_trip() {

        let from_unit = EmptyStruct::from(());

        assert_eq!(from_unit, EmptyStruct::new());

        let back: () = EmptyStruct::new().into();

        assert_eq!(back, ());

    }

    #[test]

    fn empty_struct_total_order_is_trivial() {

        // Every EmptyStruct is equal to every other one, so Ord/Hash must agree.

        let a = EmptyStruct::new();

        let b = EmptyStruct::default();

        assert_eq!(a.cmp(&b), core::cmp::Ordering::Equal);

        assert_eq!(hash_of(&a), hash_of(&b));

    }

    // ==================================================================

    // LayoutDebugMessage

    // ==================================================================

    #[test]

    fn debug_message_new_records_fields_and_caller_location() {

        let m = LayoutDebugMessage::new(LayoutDebugMessageType::Warning, "disk on fire");

        assert_eq!(m.message_type, LayoutDebugMessageType::Warning);

        assert_eq!(m.message.as_str(), "disk on fire");

        assert!(

            m.location.as_str().contains("corety.rs"),

            "#[track_caller] must record THIS file, got {:?}",

            m.location.as_str()

        );

        // location is "file:line:column" — the last two segments must be numbers.

        let parts: Vec<&str> = m.location.as_str().rsplitn(3, ':').collect();

        assert_eq!(parts.len(), 3, "location must be file:line:column");

        assert!(parts[0].parse::<u32>().is_ok(), "column must parse as u32");

        assert!(parts[1].parse::<u32>().is_ok(), "line must parse as u32");

    }

    #[test]

    fn debug_message_track_caller_propagates_through_helpers() {

        // If #[track_caller] were missing on the helpers, both locations would

        // collapse to the same line inside LayoutDebugMessage::new().

        let a = LayoutDebugMessage::info("a");

        let b = LayoutDebugMessage::info("b");

        assert_ne!(

            a.location.as_str(),

            b.location.as_str(),

            "two call sites on different lines must record different locations"

        );

        assert!(a.location.as_str().contains("corety.rs"));

    }

    #[test]

    fn debug_message_helpers_set_the_right_type() {

        assert_eq!(

            LayoutDebugMessage::info("x").message_type,

            LayoutDebugMessageType::Info

        );

        assert_eq!(

            LayoutDebugMessage::warning("x").message_type,

            LayoutDebugMessageType::Warning

        );

        assert_eq!(

            LayoutDebugMessage::error("x").message_type,

            LayoutDebugMessageType::Error

        );

        assert_eq!(

            LayoutDebugMessage::box_props("x").message_type,

            LayoutDebugMessageType::BoxProps

        );

        assert_eq!(

            LayoutDebugMessage::css_getter("x").message_type,

            LayoutDebugMessageType::CssGetter

        );

        assert_eq!(

            LayoutDebugMessage::bfc_layout("x").message_type,

            LayoutDebugMessageType::BfcLayout

        );

        assert_eq!(

            LayoutDebugMessage::ifc_layout("x").message_type,

            LayoutDebugMessageType::IfcLayout

        );

        assert_eq!(

            LayoutDebugMessage::table_layout("x").message_type,

            LayoutDebugMessageType::TableLayout

        );

        assert_eq!(

            LayoutDebugMessage::display_type("x").message_type,

            LayoutDebugMessageType::DisplayType

        );

    }

    #[test]

    fn debug_message_helpers_preserve_the_message_verbatim() {

        // Every helper must forward the payload untouched, including empty

        // and unicode payloads.

        for m in [

            LayoutDebugMessage::info(""),

            LayoutDebugMessage::warning(""),

            LayoutDebugMessage::error(""),

            LayoutDebugMessage::box_props(""),

            LayoutDebugMessage::css_getter(""),

            LayoutDebugMessage::bfc_layout(""),

            LayoutDebugMessage::ifc_layout(""),

            LayoutDebugMessage::table_layout(""),

            LayoutDebugMessage::display_type(""),

        ] {

            assert!(m.message.is_empty());

            assert!(!m.location.is_empty(), "location is always filled in");

        }

        let weird = "ünïcødé \u{1F600}\n\t\"quoted\" \u{0}nul";

        assert_eq!(LayoutDebugMessage::error(weird).message.as_str(), weird);

    }

    #[test]

    fn debug_message_handles_huge_message_without_panicking() {

        let huge = "m".repeat(1_000_000);

        let m = LayoutDebugMessage::new(LayoutDebugMessageType::PositionCalculation, huge.clone());

        assert_eq!(m.message.len(), 1_000_000);

        assert_eq!(m.message.as_str(), huge.as_str());

        assert_eq!(

            m.message_type,

            LayoutDebugMessageType::PositionCalculation,

            "the variant with no helper must still be constructible via new()"

        );

    }

    #[test]

    fn debug_message_default_is_empty_info() {

        let m = LayoutDebugMessage::default();

        assert_eq!(m.message_type, LayoutDebugMessageType::Info);

        assert!(m.message.is_empty());

        assert!(m.location.is_empty(), "default() does not track a caller");

        assert_eq!(LayoutDebugMessageType::default(), LayoutDebugMessageType::Info);

    }

    #[test]

    fn debug_message_accepts_string_and_str_via_into() {

        // `impl Into<String>` must work for both &str and String.

        let from_str = LayoutDebugMessage::info("borrowed");

        let from_string = LayoutDebugMessage::info(String::from("owned"));

        assert_eq!(from_str.message.as_str(), "borrowed");

        assert_eq!(from_string.message.as_str(), "owned");

    }

    #[test]

    fn debug_message_clone_is_a_deep_equal_copy() {

        let m = LayoutDebugMessage::error("clone me \u{1F600}");

        let c = m.clone();

        assert_eq!(c, m);

        assert_ne!(

            c.message.as_bytes().as_ptr(),

            m.message.as_bytes().as_ptr(),

            "clone must deep-copy the library-owned message bytes"

        );

    }

    // ==================================================================

    // AzString — constructors

    // ==================================================================

    #[test]

    fn azstring_default_is_empty_and_readable() {

        let s = AzString::default();

        assert_eq!(s.as_str(), "");

        assert_eq!(s.len(), 0);

        assert!(s.is_empty());

        assert_eq!(s.as_bytes(), b"");

    }

    #[test]

    fn azstring_from_const_str_borrows_the_static_and_never_frees_it() {

        // One binding, used for both the construction and the pointer check —

        // rustc is not obliged to dedupe two identical string literals.

        const TEXT: &str = "static text";

        let s = AzString::from_const_str(TEXT);

        assert_eq!(s.as_str(), TEXT);

        assert_eq!(s.len(), 11);

        assert!(

            matches!(s.vec.destructor, U8VecDestructor::NoDestructor),

            "a &'static str must not get a freeing destructor"

        );

        assert_eq!(

            s.vec.ptr,

            TEXT.as_bytes().as_ptr(),

            "from_const_str must alias the static, not copy it"

        );

    }

    #[test]

    fn azstring_from_const_str_empty_and_unicode() {

        let empty = AzString::from_const_str("");

        assert!(empty.is_empty());

        assert_eq!(empty.as_str(), "");

        assert_eq!(empty.len(), 0);

        let uni = AzString::from_const_str("héllo \u{1F600}");

        assert_eq!(uni.as_str(), "héllo \u{1F600}");

        // len() is BYTES, not chars: 5 ASCII-ish + 1 extra for é + space + 4 for the emoji

        assert_eq!(uni.len(), "héllo \u{1F600}".len());

        assert_ne!(

            uni.len(),

            uni.as_str().chars().count(),

            "len() must be a byte length, not a char count"

        );

    }

    #[test]

    fn azstring_from_string_round_trips_edge_values() {

        for input in [

            String::new(),

            String::from(" "),

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

            String::from("0"),

            String::from("-0"),

            String::from("9223372036854775807"), // i64::MAX

            String::from("NaN"),

            String::from("inf"),

            String::from("  valid  "),

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

            String::from("\u{1F600}\u{0301}\u{0}"), // emoji + combining mark + NUL

            "{".repeat(10_000),                     // deeply "nested" junk: no parser, no overflow

        ] {

            let s = AzString::from_string(input.clone());

            assert_eq!(s.as_str(), input.as_str(), "from_string must be verbatim");

            assert_eq!(s.len(), input.len());

            assert_eq!(s.is_empty(), input.is_empty());

            // round-trip back out

            assert_eq!(s.into_library_owned_string(), input);

        }

    }

    #[test]

    fn azstring_from_string_handles_a_megabyte() {

        let huge = "x".repeat(1_000_000);

        let s = AzString::from_string(huge.clone());

        assert_eq!(s.len(), 1_000_000);

        assert_eq!(s.as_str().len(), huge.len());

        assert!(s.as_str().bytes().all(|b| b == b'x'));

    }

    #[test]

    fn azstring_from_string_preserves_the_original_capacity() {

        // into_library_owned_string rebuilds the String via from_raw_parts(ptr, len, cap).

        // If `cap` were not carried through faithfully, this would corrupt the heap.

        let mut owned = String::with_capacity(4096);

        owned.push_str("hi");

        let s = AzString::from_string(owned);

        assert!(matches!(s.vec.destructor, U8VecDestructor::DefaultRust));

        let back = s.into_library_owned_string();

        assert_eq!(back, "hi");

        assert!(

            back.capacity() >= 4096,

            "capacity must survive the AzString round-trip, got {}",

            back.capacity()

        );

    }

    // ==================================================================

    // AzString::copy_from_bytes  (numeric / pointer edge cases)

    // ==================================================================

    #[test]

    fn azstring_copy_from_bytes_zero_len_is_empty() {

        let buf = b"hello";

        let s = AzString::copy_from_bytes(buf.as_ptr(), 0, 0);

        assert!(s.is_empty());

        assert_eq!(s.as_str(), "");

    }

    #[test]

    fn azstring_copy_from_bytes_null_ptr_is_empty() {

        let s = AzString::copy_from_bytes(core::ptr::null(), 0, 16);

        assert!(s.is_empty());

        assert_eq!(s.as_str(), "");

    }

    #[test]

    fn azstring_copy_from_bytes_honours_the_start_offset() {

        let buf = b"0123456789";

        let s = AzString::copy_from_bytes(buf.as_ptr(), 3, 4);

        assert_eq!(s.as_str(), "3456");

        assert_eq!(s.len(), 4);

    }

    #[test]

    fn azstring_copy_from_bytes_start_at_end_with_zero_len_is_empty() {

        // start == buf.len() is only legal because len == 0 short-circuits

        // before the pointer is ever offset.

        let buf = b"abc";

        let s = AzString::copy_from_bytes(buf.as_ptr(), buf.len(), 0);

        assert!(s.is_empty());

    }

    #[test]

    fn azstring_copy_from_bytes_zero_len_wins_over_start_overflow() {

        // start + len overflows usize, but len == 0 must short-circuit BEFORE

        // the debug_assert / ptr.add() — no panic, no UB.

        let buf = b"abc";

        let s = AzString::copy_from_bytes(buf.as_ptr(), usize::MAX, 0);

        assert!(s.is_empty());

    }

    #[test]

    fn azstring_copy_from_bytes_null_wins_over_max_len() {

        // The null check must precede everything, even for absurd start/len.

        let s = AzString::copy_from_bytes(core::ptr::null(), usize::MAX, usize::MAX);

        assert!(s.is_empty());

        assert_eq!(s.as_str(), "");

    }

    #[test]

    fn azstring_copy_from_bytes_replaces_invalid_utf8_lossily() {

        // Slicing "héllo" mid-codepoint leaves a stray continuation byte (0xA9),

        // which must become U+FFFD so the as_str() UTF-8 invariant still holds.

        let buf = "héllo".as_bytes();

        assert_eq!(buf[1], 0xC3);

        assert_eq!(buf[2], 0xA9);

        let s = AzString::copy_from_bytes(buf.as_ptr(), 2, 2);

        assert_eq!(s.as_str(), "\u{FFFD}l");

        // The UTF-8 invariant as_str() relies on must actually hold:

        assert!(core::str::from_utf8(s.as_bytes()).is_ok());

    }

    #[test]

    fn azstring_copy_from_bytes_keeps_valid_utf8_byte_for_byte() {

        let buf = "héllo \u{1F600}".as_bytes();

        let s = AzString::copy_from_bytes(buf.as_ptr(), 0, buf.len());

        assert_eq!(s.as_str(), "héllo \u{1F600}");

        assert_eq!(s.as_bytes(), buf);

    }

    #[test]

    fn azstring_copy_from_bytes_preserves_interior_nul() {

        let buf = b"a\0b";

        let s = AzString::copy_from_bytes(buf.as_ptr(), 0, 3);

        assert_eq!(s.len(), 3, "an interior NUL is data, not a terminator");

        assert_eq!(s.as_bytes(), b"a\0b");

    }

    // ==================================================================

    // U8Vec::copy_from_bytes  (numeric / pointer edge cases)

    // ==================================================================

    #[test]

    fn u8vec_copy_from_bytes_zero_len_is_empty() {

        let buf = b"hello";

        let v = U8Vec::copy_from_bytes(buf.as_ptr(), 0, 0);

        assert!(v.is_empty());

        assert_eq!(v.as_ref(), b"");

    }

    #[test]

    fn u8vec_copy_from_bytes_null_ptr_is_empty() {

        let v = U8Vec::copy_from_bytes(core::ptr::null(), 0, 8);

        assert!(v.is_empty());

        assert_eq!(v.len(), 0);

    }

    #[test]

    fn u8vec_copy_from_bytes_null_wins_over_max_start_and_len() {

        // Neither the debug_assert nor ptr.add() may be reached for a null ptr.

        let v = U8Vec::copy_from_bytes(core::ptr::null(), usize::MAX, usize::MAX);