//! 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)]

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, 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(always)]` (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(always)]

        // 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(always)] // 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(always)] // web-lift: inline through the sret-in-X0 chain (see AzString::copy_from_bytes)

        );

}

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, PartialOrd]);

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 {}

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 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.

            // 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.

                } 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.

        };

}