libxml_rs/xml/encoding/

mod.rs

//! Character encoding handling (§22, §85 Phase 4).
//!
//! Encoding detection, XML declaration encoding, BOM behavior, UTF-8/UTF-16
//! validity, legacy encodings, conversion errors, output conversion,
//! serializer fallback, custom encoding handlers.
//!
//! # Architecture
//!
//! ```text
//! ABI exports (exports_xml2.rs)  ←  pub(crate) functions in this module
//!                                           ↕
//!                           Encoding handler registry (global RwLock)
//!                                           ↕
//!              Built-in handlers: UTF-8, UTF-16LE, UTF-16BE, Latin-1, ASCII
//! ```
//!
//! The internal encoding is always UTF-8. All conversions go to/from UTF-8.
//! The handler registry stores `_xmlCharEncodingHandler` structs that contain
//! function pointers for input (→UTF-8) and output (UTF-8→) conversion.
//!
//! # Upstream contract
//!
//! Mirrors upstream `encoding.c` / `encoding.h`
//! (`SRC-LIBXML2-2.15.0-ENCODING-C`, parity target libxml2 2.15.3 oracle).
//! ABI surface: `xmlLookupCharEncodingHandler`, `xmlGetCharEncodingHandler`,
//! `xmlOpenCharEncodingHandler`, `xmlCreateCharEncodingHandler`,
//! `xmlCharEncInput`/`xmlCharEncOutput` and the `_xmlCharEncodingHandler`
//! C-layout struct (R-000129 fixed the Rust mirror from 48 to the upstream
//! 56 bytes).
//!
//! # Conceptual behavior
//!
//! Detection runs BOM first, then the XML declaration, then registry lookup.
//! The registry mirrors upstream `defaultHandlers[32]` plus the extra-handler
//! table (`globalHandlers`, encoding.c): named handlers are registered under
//! their canonical lowercased alias and found by `xmlFindCharEncodingHandler`
//! via `find_encoding_handler`.
//!
//! # Ownership & safety invariants
//!
//! Handlers are allocated with xmlMalloc and owned by the registry; `xmlFree` releases
//! them at teardown. Registry access is serialized by an RwLock; that
//! serialization is exactly what makes the raw `HandlerPtr` Send+Sync
//! SAFETY sound (documented on the wrapper). Names from
//! `xmlGetCharEncodingName`/alias tables are borrowed statics — the caller
//! never frees them.
//!
//! # Historical quirks & epochs
//!
//! R-000157 (OPEN, UNRESOLVED): the crate ships no
//! iconv/ICU backend, so the iconv/ICU-only encodings (UCS-4LE/BE, EBCDIC,
//! UCS-2, ISO-8859-2..16, ISO-2022-JP, Shift_JIS, EUC-JP, windows-1252)
//! report XML_ERR_UNSUPPORTED_ENCODING (32) where the 2.15.3 oracle (built
//! with Iconv+ICU enabled) returns
//! a converter, while the native set (UTF-8, UTF-16LE/BE, UTF-16,
//! ISO-8859-1, US-ASCII) and all error paths are byte-identical. This is a
//! REAL current executed-platform difference, so the residual is UNRESOLVED
//! (11.1-Z.1) — closure requires implementing an iconv/ICU backend, a future
//! implementation work item, not a waiver. Upstream
//! itself removed the libiconv dependence where possible in the 2.10+ era
//! (HISTORY.md §1.8), which is the epoch this module targets.
//!
//! # Deliberate oddities
//!
//! The bounded native set is a deliberate divergence, not a stub: the
//! missing encodings are absent because no converter exists, and every
//! error path matches the oracle. `xmlLookupCharEncodingHandler` returns
//! XML_ERR_OK with a NULL handler for UTF-8/NONE exactly like upstream
//! encoding.c (`/* Return NULL handler for UTF-8 */`). R-000157 is tracked
//! UNRESOLVED: adding an iconv/ICU backend would close the gap for the
//! encodings the executed oracle serves.
//!
//! # Proving courts
//!
//! ENCODING-001 (`courts/suites/data-abi/encoding-family-probe.c`) compiles
//! one C probe against the oracle DSO and the candidate and requires
//! byte-identical stdout across the native set and all error paths.
//!
//! # Tempting simplifications that would break parity
//!
//! Do not collapse the registry to a fixed match statement: custom handlers
//! added through `xmlAddCharEncodingHandler` must stay discoverable by later
//! lookups. Do not fabricate handlers for the iconv-only encodings — that
//! would fake a converter that does not exist and break the R-000157
//! UNRESOLVED record (the honest path is a real iconv/ICU backend). Do not
//! touch the struct layout: R-000129
//! proved a 48-byte mirror breaks the C ABI.

#![allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]

use std::ffi::CStr;
use std::os::raw::{c_char, c_int, c_uchar, c_uint, c_void};
use std::ptr;
use std::sync::atomic::{AtomicBool, Ordering};

use once_cell::sync::Lazy;
use parking_lot::RwLock;

use crate::abi::allocator::{xmlFreeImpl, xmlMallocImpl, xmlReallocImpl};
use crate::abi::callbacks::{
    xmlCharEncConvCtxtDtor, xmlCharEncConvFunc, xmlCharEncConvImpl, xmlCharEncodingInputFunc,
    xmlCharEncodingOutputFunc,
};
use crate::abi::structs::{
    _xmlBuffer, _xmlCharEncodingHandler, EncodingInputUnion, EncodingOutputUnion,
};
use crate::abi::types::{xmlChar, xmlCharEncoding};

// ── Constants ──────────────────────────────────────────────────────────────

/// Maximum bytes needed per character for any supported encoding.
#[allow(dead_code)]
const MAX_CHAR_BYTES: usize = 6;

/// UTF-8 BOM bytes.
#[allow(dead_code)]
const UTF8_BOM: [u8; 3] = [0xEF, 0xBB, 0xBF];

/// UTF-16LE BOM bytes.
const UTF16LE_BOM: [u8; 2] = [0xFF, 0xFE];

/// UTF-16BE BOM bytes.
const UTF16BE_BOM: [u8; 2] = [0xFE, 0xFF];

// ── Global handler registry ────────────────────────────────────────────────

/// A raw pointer wrapper that implements `Send` and `Sync`.
///
/// This is safe because all access to the global handler registry is
/// serialized through the `RwLock`, and handlers are only accessed from
/// trusted internal code.
#[derive(Clone, Copy)]
struct HandlerPtr(*mut _xmlCharEncodingHandler);

unsafe impl Send for HandlerPtr {}
unsafe impl Sync for HandlerPtr {}

/// Global list of registered encoding handlers, protected by a read-write lock.
///
/// UPSTREAM-PARITY: this is the Rust mirror of encoding.c `globalHandlers`
/// (the table behind `xmlFindExtraHandler`); `xmlAddCharEncodingHandler`
/// appends here and lookups scan it after the built-in `defaultHandlers[32]`
/// set (R-000157: only the native subset is backed by real converters).
static ENCODING_HANDLERS: Lazy<RwLock<Vec<HandlerPtr>>> = Lazy::new(|| RwLock::new(Vec::new()));

/// Whether the built-in encoding handlers have been initialized.
static ENCODING_INITIALIZED: AtomicBool = AtomicBool::new(false);

/// Serializes first-time handler registration (see init_encodings).
static ENCODING_INIT_MUTEX: parking_lot::Mutex<()> = parking_lot::Mutex::new(());

// ═══════════════════════════════════════════════════════════════════════════════
// 1. Encoding detection
// ═══════════════════════════════════════════════════════════════════════════════

/// Determine encoding from BOM bytes.
///
/// Returns `XML_CHAR_ENCODING_NONE` if no BOM is present, or if `data` is empty.
/// Otherwise returns the matching encoding enum value.
#[allow(dead_code)]
pub(crate) fn detect_encoding_from_bom(data: &[u8]) -> xmlCharEncoding {
    if data.len() >= 3 && data[0..3] == UTF8_BOM {
        xmlCharEncoding::XML_CHAR_ENCODING_UTF8
    } else if data.len() >= 2 && data[0..2] == UTF16LE_BOM {
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE
    } else if data.len() >= 2 && data[0..2] == UTF16BE_BOM {
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16BE
    } else {
        xmlCharEncoding::XML_CHAR_ENCODING_NONE
    }
}

/// Determine encoding from an XML declaration's `encoding` attribute.
///
/// Scans for `<?xml ... encoding="..." ?>` and returns the encoding name
/// as a byte vector (lowercased), or `None` if not found.
#[allow(dead_code)]
pub(crate) fn detect_encoding_from_declaration(data: &[u8]) -> Option<Vec<u8>> {
    // Look for "<?xml" at the start (possibly after BOM)
    let start = if data.len() >= 3 && data[0..3] == UTF8_BOM {
        3
    } else if data.len() >= 2 && (data[0..2] == UTF16LE_BOM || data[0..2] == UTF16BE_BOM) {
        // For UTF-16, we can't easily scan the bytes; skip
        return None;
    } else {
        0
    };

    let remaining = &data[start..];

    // Must start with "<?xml"
    if remaining.len() < 5 || !remaining[0..5].eq_ignore_ascii_case(b"<?xml") {
        return None;
    }

    // Find the end of the PI: "?>"
    let pi_end = remaining.windows(2).position(|w| w == b"?>")?;
    let decl_content = &remaining[5..pi_end];

    // Look for "encoding" attribute
    let decl_str = core::str::from_utf8(decl_content).ok()?;
    let lower = decl_str.to_ascii_lowercase();

    // Find "encoding" keyword
    let enc_pos = lower.find("encoding")?;

    // After "encoding", expect optional whitespace and '='
    let after_enc = &decl_content[enc_pos + 8..];
    let after_enc_str = core::str::from_utf8(after_enc).ok()?;
    let after_enc_trimmed = after_enc_str.trim_start();

    if !after_enc_trimmed.starts_with('=') {
        return None;
    }

    let after_eq = after_enc_trimmed[1..].trim_start();

    // Expect quote character
    let quote = after_eq.chars().next()?;
    if quote != '"' && quote != '\'' {
        return None;
    }

    // Find matching closing quote
    let value_end = after_eq[1..].find(quote)?;
    let encoding_value = &after_eq[1..=value_end];

    Some(encoding_value.to_ascii_lowercase().as_bytes().to_vec())
}

/// Parse an encoding name string to an `xmlCharEncoding` enum value.
///
/// Matching is case-insensitive. Common aliases are recognized.
/// Returns `XML_CHAR_ENCODING_ERROR` if the name is not recognized.
pub(crate) fn encoding_from_name(name: &[u8]) -> xmlCharEncoding {
    let s = core::str::from_utf8(name).unwrap_or("");
    let s = s.trim().to_ascii_lowercase();

    match s.as_str() {
        // UTF-8
        "utf-8" | "utf8" => xmlCharEncoding::XML_CHAR_ENCODING_UTF8,

        // UTF-16
        "utf-16" | "utf-16le" | "utf16le" => xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE,
        "utf-16be" | "utf16be" => xmlCharEncoding::XML_CHAR_ENCODING_UTF16BE,

        // ISO-8859 variants
        "iso-8859-1" | "iso_8859-1" | "latin1" | "latin-1" | "l1" | "cp819" | "ibm819"
        | "iso-ir-100" | "iso_8859-1:1987" => xmlCharEncoding::XML_CHAR_ENCODING_8859_1,
        "iso-8859-2" | "iso_8859-2" | "latin2" | "latin-2" | "l2" => {
            xmlCharEncoding::XML_CHAR_ENCODING_8859_2
        }
        "iso-8859-3" | "iso_8859-3" | "latin3" | "latin-3" | "l3" => {
            xmlCharEncoding::XML_CHAR_ENCODING_8859_3
        }
        "iso-8859-4" | "iso_8859-4" | "latin4" | "latin-4" | "l4" => {
            xmlCharEncoding::XML_CHAR_ENCODING_8859_4
        }
        "iso-8859-5" | "iso_8859-5" | "cyrillic" => xmlCharEncoding::XML_CHAR_ENCODING_8859_5,
        "iso-8859-6" | "iso_8859-6" | "arabic" => xmlCharEncoding::XML_CHAR_ENCODING_8859_6,
        "iso-8859-7" | "iso_8859-7" | "greek" => xmlCharEncoding::XML_CHAR_ENCODING_8859_7,
        "iso-8859-8" | "iso_8859-8" | "hebrew" => xmlCharEncoding::XML_CHAR_ENCODING_8859_8,
        "iso-8859-9" | "iso_8859-9" | "latin5" | "latin-5" | "l5" | "turkish" => {
            xmlCharEncoding::XML_CHAR_ENCODING_8859_9
        }

        // ASCII
        "ascii" | "us-ascii" | "us" | "ansi_x3.4-1968" | "ansi_x3.4-1986" | "iso-ir-6"
        | "iso_646.irv:1991" | "cp367" | "ibm367" => xmlCharEncoding::XML_CHAR_ENCODING_ASCII,

        // East Asian
        "iso-2022-jp" | "iso2022-jp" => xmlCharEncoding::XML_CHAR_ENCODING_2022_JP,
        "shift_jis" | "shift-jis" | "sjis" | "cp932" => {
            xmlCharEncoding::XML_CHAR_ENCODING_SHIFT_JIS
        }
        "euc-jp" | "eucjp" => xmlCharEncoding::XML_CHAR_ENCODING_EUC_JP,

        // UCS/Unicode variants
        "ucs-4" | "ucs4" => xmlCharEncoding::XML_CHAR_ENCODING_UCS4LE,
        "ucs-4le" | "ucs4le" => xmlCharEncoding::XML_CHAR_ENCODING_UCS4LE,
        "ucs-4be" | "ucs4be" => xmlCharEncoding::XML_CHAR_ENCODING_UCS4BE,
        "ucs-2" | "ucs2" => xmlCharEncoding::XML_CHAR_ENCODING_UCS2,

        // EBCDIC
        "ebcdic" | "cp037" | "ibm037" => xmlCharEncoding::XML_CHAR_ENCODING_EBCDIC,

        _ => xmlCharEncoding::XML_CHAR_ENCODING_ERROR,
    }
}

/// Get the canonical name for an encoding as a byte slice.
///
/// Returns `None` for `XML_CHAR_ENCODING_ERROR` and `XML_CHAR_ENCODING_NONE`.
pub(crate) const fn encoding_name(enc: xmlCharEncoding) -> Option<&'static [u8]> {
    match enc {
        xmlCharEncoding::XML_CHAR_ENCODING_UTF8 => Some(b"UTF-8" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE => Some(b"UTF-16LE" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16BE => Some(b"UTF-16BE" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_UCS4LE => Some(b"UCS-4LE" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_UCS4BE => Some(b"UCS-4BE" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_EBCDIC => Some(b"EBCDIC" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_UCS4_2143 => Some(b"UCS-4-2143" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_UCS4_3412 => Some(b"UCS-4-3412" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_UCS2 => Some(b"UCS-2" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_1 => Some(b"ISO-8859-1" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_2 => Some(b"ISO-8859-2" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_3 => Some(b"ISO-8859-3" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_4 => Some(b"ISO-8859-4" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_5 => Some(b"ISO-8859-5" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_6 => Some(b"ISO-8859-6" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_7 => Some(b"ISO-8859-7" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_8 => Some(b"ISO-8859-8" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_9 => Some(b"ISO-8859-9" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_2022_JP => Some(b"ISO-2022-JP" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_SHIFT_JIS => Some(b"SHIFT_JIS" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_EUC_JP => Some(b"EUC-JP" as &[u8]),
        xmlCharEncoding::XML_CHAR_ENCODING_ASCII => Some(b"US-ASCII" as &[u8]),
        _ => None,
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// 2. UTF-8 validation
// ═══════════════════════════════════════════════════════════════════════════════

/// Check if a byte sequence is valid UTF-8.
///
/// Returns `true` if the entire slice is valid UTF-8, `false` otherwise.
#[allow(dead_code)]
pub(crate) const fn utf8_valid(data: &[u8]) -> bool {
    core::str::from_utf8(data).is_ok()
}

/// Check if a Unicode codepoint is a valid XML character.
///
/// Per XML 1.0 (Fifth Edition) §2.2, the valid character ranges are:
/// - `#x9` (tab)
/// - `#xA` (LF)
/// - `#xD` (CR)
/// - `#x20` – `#xD7FF`
/// - `#xE000` – `#xFFFD`
/// - `#x10000` – `#x10FFFF`
///
/// Excludes surrogate halves (`#xD800` – `#xDFFF`) and `#xFFFE`/`#xFFFF`.
#[allow(dead_code)]
pub(crate) const fn is_valid_xml_char(cp: u32) -> bool {
    matches!(
        cp,
        0x9 | 0xA | 0xD | 0x20..=0xD7FF | 0xE000..=0xFFFD | 0x10000..=0x10FFFF
    )
}

// ═══════════════════════════════════════════════════════════════════════════════
// 3. UTF-16 handling
// ═══════════════════════════════════════════════════════════════════════════════

/// Decode a single UTF-16LE code unit from two bytes.
#[inline]
const fn read_utf16le_unit(data: &[u8]) -> Option<u16> {
    if data.len() < 2 {
        return None;
    }
    Some(u16::from_le_bytes([data[0], data[1]]))
}

/// Decode a single UTF-16BE code unit from two bytes.
#[inline]
const fn read_utf16be_unit(data: &[u8]) -> Option<u16> {
    if data.len() < 2 {
        return None;
    }
    Some(u16::from_be_bytes([data[0], data[1]]))
}

/// Encode a Unicode codepoint as UTF-8 bytes.
///
/// Returns the number of bytes written (1–4), or 0 if the codepoint is invalid.
const fn encode_codepoint_to_utf8(cp: u32, out: &mut [u8]) -> usize {
    if cp < 0x80 {
        if !out.is_empty() {
            out[0] = cp as u8;
        }
        1
    } else if cp < 0x800 {
        if out.len() < 2 {
            return 0;
        }
        out[0] = 0xC0 | ((cp >> 6) as u8);
        out[1] = 0x80 | (cp as u8 & 0x3F);
        2
    } else if cp < 0x10000 {
        if out.len() < 3 {
            return 0;
        }
        out[0] = 0xE0 | ((cp >> 12) as u8);
        out[1] = 0x80 | ((cp >> 6) as u8 & 0x3F);
        out[2] = 0x80 | (cp as u8 & 0x3F);
        3
    } else if cp < 0x110000 {
        if out.len() < 4 {
            return 0;
        }
        out[0] = 0xF0 | ((cp >> 18) as u8);
        out[1] = 0x80 | ((cp >> 12) as u8 & 0x3F);
        out[2] = 0x80 | ((cp >> 6) as u8 & 0x3F);
        out[3] = 0x80 | (cp as u8 & 0x3F);
        4
    } else {
        0
    }
}

/// Convert UTF-16LE bytes to UTF-8.
///
/// Returns `Ok(converted_bytes)` on success, or `Err(())` on invalid input
/// (e.g., unpaired surrogates, truncated data).
pub(crate) fn utf16le_to_utf8(data: &[u8]) -> Result<Vec<u8>, ()> {
    if data.is_empty() {
        return Ok(Vec::new());
    }

    // Skip BOM if present
    let offset = if data.len() >= 2 && data[0..2] == UTF16LE_BOM {
        2
    } else {
        0
    };

    let mut result = Vec::with_capacity(data.len() / 2 + data.len() / 4);
    let mut i = offset;

    while i < data.len() {
        let unit = read_utf16le_unit(&data[i..]).ok_or(())?;
        i += 2;

        if (0xD800..=0xDBFF).contains(&unit) {
            // High surrogate: expect a low surrogate
            let low = read_utf16le_unit(&data[i..]).ok_or(())?;
            i += 2;

            if !(0xDC00..=0xDFFF).contains(&low) {
                return Err(());
            }

            let cp = 0x10000 + ((unit as u32 - 0xD800) << 10) + (low as u32 - 0xDC00);
            let mut buf = [0u8; 4];
            let n = encode_codepoint_to_utf8(cp, &mut buf);
            if n == 0 {
                return Err(());
            }
            result.extend_from_slice(&buf[..n]);
        } else if (0xDC00..=0xDFFF).contains(&unit) {
            // Unexpected low surrogate
            return Err(());
        } else {
            let cp = unit as u32;
            let mut buf = [0u8; 4];
            let n = encode_codepoint_to_utf8(cp, &mut buf);
            result.extend_from_slice(&buf[..n]);
        }
    }

    Ok(result)
}

/// Convert UTF-16BE bytes to UTF-8.
///
/// Returns `Ok(converted_bytes)` on success, or `Err(())` on invalid input.
pub(crate) fn utf16be_to_utf8(data: &[u8]) -> Result<Vec<u8>, ()> {
    if data.is_empty() {
        return Ok(Vec::new());
    }

    // Skip BOM if present
    let offset = if data.len() >= 2 && data[0..2] == UTF16BE_BOM {
        2
    } else {
        0
    };

    let mut result = Vec::with_capacity(data.len() / 2 + data.len() / 4);
    let mut i = offset;

    while i < data.len() {
        let unit = read_utf16be_unit(&data[i..]).ok_or(())?;
        i += 2;

        if (0xD800..=0xDBFF).contains(&unit) {
            // High surrogate: expect a low surrogate
            let low = read_utf16be_unit(&data[i..]).ok_or(())?;
            i += 2;

            if !(0xDC00..=0xDFFF).contains(&low) {
                return Err(());
            }

            let cp = 0x10000 + ((unit as u32 - 0xD800) << 10) + (low as u32 - 0xDC00);
            let mut buf = [0u8; 4];
            let n = encode_codepoint_to_utf8(cp, &mut buf);
            if n == 0 {
                return Err(());
            }
            result.extend_from_slice(&buf[..n]);
        } else if (0xDC00..=0xDFFF).contains(&unit) {
            // Unexpected low surrogate
            return Err(());
        } else {
            let cp = unit as u32;
            let mut buf = [0u8; 4];
            let n = encode_codepoint_to_utf8(cp, &mut buf);
            result.extend_from_slice(&buf[..n]);
        }
    }

    Ok(result)
}

/// Encode a Unicode codepoint as UTF-16LE bytes.
///
/// Returns the number of bytes written (2 or 4), or 0 if the codepoint is invalid.
fn encode_codepoint_to_utf16le(cp: u32, out: &mut [u8]) -> usize {
    if cp < 0x10000 {
        if out.len() < 2 {
            return 0;
        }
        let u = cp as u16;
        out[..2].copy_from_slice(&u.to_le_bytes());
        2
    } else if cp < 0x110000 {
        if out.len() < 4 {
            return 0;
        }
        let cp = cp - 0x10000;
        let high = 0xD800 | ((cp >> 10) as u16);
        let low = 0xDC00 | (cp as u16 & 0x3FF);
        out[..2].copy_from_slice(&high.to_le_bytes());
        out[2..4].copy_from_slice(&low.to_le_bytes());
        4
    } else {
        0
    }
}

/// Convert UTF-8 bytes to UTF-16LE.
///
/// Returns `Ok(converted_bytes)` on success, or `Err(())` on invalid UTF-8 input.
pub(crate) fn utf8_to_utf16le(data: &[u8]) -> Result<Vec<u8>, ()> {
    let s = core::str::from_utf8(data).map_err(|_| ())?;
    let mut result = Vec::with_capacity(data.len() * 2);

    for ch in s.chars() {
        let cp = ch as u32;
        let mut buf = [0u8; 4];
        let n = encode_codepoint_to_utf16le(cp, &mut buf);
        if n == 0 {
            return Err(());
        }
        result.extend_from_slice(&buf[..n]);
    }

    Ok(result)
}

// ═══════════════════════════════════════════════════════════════════════════════
// 4. ISO-8859-1 (Latin-1) handling
// ═══════════════════════════════════════════════════════════════════════════════

/// Convert Latin-1 (ISO-8859-1) bytes to UTF-8.
///
/// Latin-1 maps codepoints 0x00–0xFF directly to Unicode codepoints U+0000–U+00FF.
/// Each input byte produces either 1 or 2 UTF-8 bytes.
#[allow(dead_code)]
pub(crate) fn latin1_to_utf8(data: &[u8]) -> Vec<u8> {
    let mut result = Vec::with_capacity(data.len() * 2);

    for &byte in data {
        let cp = byte as u32;
        let mut buf = [0u8; 2];
        let n = encode_codepoint_to_utf8(cp, &mut buf);
        result.extend_from_slice(&buf[..n]);
    }

    result
}

/// Convert UTF-8 bytes to Latin-1 (ISO-8859-1).
///
/// Returns `Err(())` if the input is not valid UTF-8 or contains codepoints
/// outside the Latin-1 range (U+0000–U+00FF).
pub(crate) fn utf8_to_latin1(data: &[u8]) -> Result<Vec<u8>, ()> {
    let s = core::str::from_utf8(data).map_err(|_| ())?;
    let mut result = Vec::with_capacity(data.len());

    for ch in s.chars() {
        let cp = ch as u32;
        if cp > 0xFF {
            return Err(());
        }
        result.push(cp as u8);
    }

    Ok(result)
}

// ═══════════════════════════════════════════════════════════════════════════════
// 5. Encoding handler registry
// ═══════════════════════════════════════════════════════════════════════════════

/// Initialize the built-in encoding handlers.
///
/// This function registers handlers for:
/// - UTF-8 (identity/no conversion)
/// - UTF-16LE
/// - UTF-16BE
/// - ISO-8859-1 (Latin-1)
/// - ASCII
///
/// Safe to call multiple times — only the first call has an effect.
pub(crate) fn init_encodings() {
    if ENCODING_INITIALIZED.load(Ordering::SeqCst) {
        return;
    }
    // Serialize first-time registration: without the mutex, a second thread
    // can observe ENCODING_INITIALIZED == true and look up handlers while
    // the first thread is still registering them (race found by the parallel
    // test suite: xml::io test_output_buffer_with_encoding intermittently
    // failed to find the Latin-1 handler).
    let _guard = ENCODING_INIT_MUTEX.lock();
    if ENCODING_INITIALIZED.load(Ordering::SeqCst) {
        return;
    }
    register_builtin_handlers();
    ENCODING_INITIALIZED.store(true, Ordering::SeqCst);
}

/// Register all built-in encoding handlers.
fn register_builtin_handlers() {
    // UTF-8 (identity handler — no conversion needed)
    register_handler(
        b"UTF-8\0",
        xmlCharEncoding::XML_CHAR_ENCODING_UTF8,
        xmlCharEncoding::XML_CHAR_ENCODING_UTF8,
        Some(utf8_input_func as xmlCharEncodingInputFunc),
        Some(utf8_output_func as xmlCharEncodingOutputFunc),
    );

    // UTF-16LE
    register_handler(
        b"UTF-16LE\0",
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE,
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE,
        Some(utf16le_input_func as xmlCharEncodingInputFunc),
        Some(utf16le_output_func as xmlCharEncodingOutputFunc),
    );

    // UTF-16BE
    register_handler(
        b"UTF-16BE\0",
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16BE,
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16BE,
        Some(utf16be_input_func as xmlCharEncodingInputFunc),
        Some(utf16be_output_func as xmlCharEncodingOutputFunc),
    );

    // ISO-8859-1 (Latin-1)
    register_handler(
        b"ISO-8859-1\0",
        xmlCharEncoding::XML_CHAR_ENCODING_8859_1,
        xmlCharEncoding::XML_CHAR_ENCODING_8859_1,
        Some(latin1_input_func as xmlCharEncodingInputFunc),
        Some(latin1_output_func as xmlCharEncodingOutputFunc),
    );

    // Windows-1252 (CP1252): served by iconv on the oracle; native converter
    // here (R-000157 partial closure). Registered under both the canonical
    // spelling and the cp1252 alias; lookup is case-insensitive so
    // "Windows-1252" (the Dom\XMLDocument overrideEncoding the PHP court
    // passes verbatim) resolves to the same entry.
    register_handler(
        b"windows-1252\0",
        xmlCharEncoding::XML_CHAR_ENCODING_ERROR,
        xmlCharEncoding::XML_CHAR_ENCODING_ERROR,
        Some(cp1252_input_func as xmlCharEncodingInputFunc),
        Some(cp1252_output_func as xmlCharEncodingOutputFunc),
    );
    register_handler(
        b"cp1252\0",
        xmlCharEncoding::XML_CHAR_ENCODING_ERROR,
        xmlCharEncoding::XML_CHAR_ENCODING_ERROR,
        Some(cp1252_input_func as xmlCharEncodingInputFunc),
        Some(cp1252_output_func as xmlCharEncodingOutputFunc),
    );

    // ASCII — upstream's static default handler (defaultHandlers[22]) is named
    // "US-ASCII"; the name "ASCII" is registered as a second entry so name-based
    // lookups (xmlFindCharEncodingHandler, the saver path) accept both spellings
    // exactly like upstream's xmlParseCharEncodingInternal mapping.
    register_handler(
        b"US-ASCII\0",
        xmlCharEncoding::XML_CHAR_ENCODING_ASCII,
        xmlCharEncoding::XML_CHAR_ENCODING_ASCII,
        Some(ascii_input_func as xmlCharEncodingInputFunc),
        Some(ascii_output_func as xmlCharEncodingOutputFunc),
    );
    register_handler(
        b"ASCII\0",
        xmlCharEncoding::XML_CHAR_ENCODING_ASCII,
        xmlCharEncoding::XML_CHAR_ENCODING_ASCII,
        Some(ascii_input_func as xmlCharEncodingInputFunc),
        Some(ascii_output_func as xmlCharEncodingOutputFunc),
    );

    // UTF-16 (default handler for enc == XML_CHAR_ENCODING_UTF16 == 23): the
    // upstream converter is UTF16LEToUTF8/UTF8ToUTF16 (the latter emits the LE
    // BOM on its init call). Our converter pair is the UTF-16LE pair; the BOM
    // init protocol is not emitted (documented divergence, conversion only).
    register_handler(
        b"UTF-16\0",
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE,
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE,
        Some(utf16le_input_func as xmlCharEncodingInputFunc),
        Some(utf16le_output_func as xmlCharEncodingOutputFunc),
    );

    // Shift_JIS + EUC-JP — encoding_rs-backed converters (R-000157 closure
    // slice, Phase 14.27). Upstream serves these through iconv on the
    // executed oracle (2.15.3, Iconv+ICU); the crate ships no iconv/ICU
    // backend, so the converters are implemented natively over WHATWG
    // Shift_JIS (a CP932-compatible superset) / EUC-JP, which byte-match
    // glibc iconv on the shared JIS X 0208 repertoire the php suite and
    // byte-parity probes exercise (the WHATWG/CP932 extension differences
    // are residualized in R-000157). Registered under the canonical
    // spellings + the aliases upstream's name path accepts (registry lookup
    // is case-insensitive).
    register_handler(
        b"SHIFT_JIS\0",
        xmlCharEncoding::XML_CHAR_ENCODING_SHIFT_JIS,
        xmlCharEncoding::XML_CHAR_ENCODING_SHIFT_JIS,
        Some(shift_jis_input_func as xmlCharEncodingInputFunc),
        Some(shift_jis_output_func as xmlCharEncodingOutputFunc),
    );
    register_handler(
        b"SJIS\0",
        xmlCharEncoding::XML_CHAR_ENCODING_SHIFT_JIS,
        xmlCharEncoding::XML_CHAR_ENCODING_SHIFT_JIS,
        Some(shift_jis_input_func as xmlCharEncodingInputFunc),
        Some(shift_jis_output_func as xmlCharEncodingOutputFunc),
    );
    register_handler(
        b"CP932\0",
        xmlCharEncoding::XML_CHAR_ENCODING_SHIFT_JIS,
        xmlCharEncoding::XML_CHAR_ENCODING_SHIFT_JIS,
        Some(shift_jis_input_func as xmlCharEncodingInputFunc),
        Some(shift_jis_output_func as xmlCharEncodingOutputFunc),
    );
    register_handler(
        b"EUC-JP\0",
        xmlCharEncoding::XML_CHAR_ENCODING_EUC_JP,
        xmlCharEncoding::XML_CHAR_ENCODING_EUC_JP,
        Some(euc_jp_input_func as xmlCharEncodingInputFunc),
        Some(euc_jp_output_func as xmlCharEncodingOutputFunc),
    );
    register_handler(
        b"EUCJP\0",
        xmlCharEncoding::XML_CHAR_ENCODING_EUC_JP,
        xmlCharEncoding::XML_CHAR_ENCODING_EUC_JP,
        Some(euc_jp_input_func as xmlCharEncodingInputFunc),
        Some(euc_jp_output_func as xmlCharEncodingOutputFunc),
    );
}

/// Helper to create and register an encoding handler.
///
/// # Safety
///
/// - `name_bytes` must be a valid byte slice containing a NUL terminator;
///   `xmlMemStrdupImpl` scans it as a C string.
/// - The `xmlMallocImpl` result is NULL-checked before `ptr::write`
///   initializes the handler; the written handler is inserted into the
///   global registry, which keeps it alive for the process lifetime.
fn register_handler(
    name_bytes: &[u8],
    _input_enc: xmlCharEncoding,
    _output_enc: xmlCharEncoding,
    input_func: Option<xmlCharEncodingInputFunc>,
    output_func: Option<xmlCharEncodingOutputFunc>,
) {
    let name_raw =
        unsafe { crate::abi::allocator::xmlMemStrdupImpl(name_bytes.as_ptr() as *const c_char) };
    if name_raw.is_null() {
        return;
    }

    let handler = unsafe { xmlMallocImpl(size_of::<_xmlCharEncodingHandler>()) }
        as *mut _xmlCharEncodingHandler;

    if handler.is_null() {
        unsafe { xmlFreeImpl(name_raw) };
        return;
    }

    unsafe {
        ptr::write(
            handler,
            _xmlCharEncodingHandler {
                name: name_raw as *mut c_char,
                input: EncodingInputUnion {
                    legacyFunc: input_func,
                },
                output: EncodingOutputUnion {
                    legacyFunc: output_func,
                },
                inputCtxt: ptr::null_mut(),
                outputCtxt: ptr::null_mut(),
                ctxtDtor: None,
                flags: 0,
            },
        );
    }

    add_encoding_handler(handler);
}

/// Clean up encoding handlers.
///
/// Frees all registered handlers and resets the registry.
///
/// # Safety
///
/// - Every registered handler pointer must be NULL or a valid
///   heap-allocated `_xmlCharEncodingHandler` whose `name` is NULL or a
///   heap-allocated NUL-terminated string; each allocation is freed exactly
///   once and must not be freed elsewhere.
pub(crate) fn cleanup_encodings() {
    let mut handlers = ENCODING_HANDLERS.write();
    for &handler in handlers.iter() {
        let ptr = handler.0;
        if !ptr.is_null() {
            unsafe {
                if !(*ptr).name.is_null() {
                    xmlFreeImpl((*ptr).name as *mut c_void);
                }
                xmlFreeImpl(ptr as *mut c_void);
            }
        }
    }
    handlers.clear();
    // Re-allow registration on the next init_encodings()/cleanup round-trip so
    // a caller that cleans up and then (re)initializes in another thread does
    // not observe a stale "already initialized" registry that stays empty.
    // (ENCODING_INITIALIZED/ENCODING_INIT_MUTEX are separate statics.)
    drop(handlers);
    ENCODING_INITIALIZED.store(false, Ordering::SeqCst);
}

/// Find an encoding handler by name.
///
/// Searches the global handler registry for a handler whose name matches
/// (case-insensitive). Returns a pointer to the handler, or `ptr::null_mut()`
/// if not found.
///
/// # Safety
///
/// - `name` must be NULL or a valid pointer to a NUL-terminated string.
/// - Each registry entry must be NULL or a valid `_xmlCharEncodingHandler`
///   whose `name` is NULL or a valid NUL-terminated string.
pub(crate) fn find_encoding_handler(name: *const xmlChar) -> *mut _xmlCharEncodingHandler {
    if name.is_null() {
        return ptr::null_mut();
    }

    /* The upstream default-handler table is static and always present; the
     * candidate's registry is populated lazily, so ensure it is initialized
     * before any name-based lookup. Idempotent. */
    init_encodings();

    let name_str = unsafe {
        match CStr::from_ptr(name as *const c_char).to_bytes() {
            b"" => return ptr::null_mut(),
            s => s,
        }
    };

    let handlers = ENCODING_HANDLERS.read();
    for &handler in handlers.iter() {
        let ptr = handler.0;
        if ptr.is_null() {
            continue;
        }
        let h_name = unsafe {
            if (*ptr).name.is_null() {
                continue;
            }
            CStr::from_ptr((*ptr).name).to_bytes()
        };

        if name_str.eq_ignore_ascii_case(h_name) {
            return ptr;
        }
    }

    ptr::null_mut()
}

/// Build an owned, caller-freed copy of a registered encoding handler.
///
/// Upstream's `xmlFindCharEncodingHandler` hands the caller a handler it owns
/// and is expected to release with `xmlCharEncCloseFunc` after use (Phase 14
/// PHP court: `dom_document_encoding_write` finds a handler then closes it for
/// every write). Returning the persistent registry pointer directly would let
/// the exported close free the registry entry out from under later lookups
/// (a use-after-free seen as `DOMDocument::$encoding = 'UTF-16'` corrupting the
/// handler registry and crashing the next `find_encoding_handler`).
///
/// The copy duplicates the name with `xmlMemStrdupImpl` so the caller may free
/// it; the conversion unions and context pointers are shared with the original
/// registry entry. All built-in registry handlers the find path serves are
/// stateless (`ctxtDtor` is None, contexts NULL), so `xmlCharEncCloseFunc` on
/// the copy only releases the duplicated name and the struct.
///
/// Returns the new handler or `ptr::null_mut()` when `src` is NULL/alloc fails.
pub(crate) fn clone_encoding_handler_for_find(
    src: *mut _xmlCharEncodingHandler,
) -> *mut _xmlCharEncodingHandler {
    if src.is_null() {
        return ptr::null_mut();
    }
    let name_raw = unsafe {
        let nm = (*src).name;
        if nm.is_null() {
            ptr::null_mut()
        } else {
            crate::abi::allocator::xmlMemStrdupImpl(nm)
        }
    };
    let handler = unsafe { xmlMallocImpl(size_of::<_xmlCharEncodingHandler>()) }
        as *mut _xmlCharEncodingHandler;
    if handler.is_null() {
        if !name_raw.is_null() {
            unsafe { crate::abi::allocator::xmlFreeImpl(name_raw) };
        }
        return ptr::null_mut();
    }
    unsafe {
        ptr::write(
            handler,
            _xmlCharEncodingHandler {
                name: name_raw as *mut c_char,
                input: ptr::read(&(*src).input),
                output: ptr::read(&(*src).output),
                inputCtxt: (*src).inputCtxt,
                outputCtxt: (*src).outputCtxt,
                ctxtDtor: (*src).ctxtDtor,
                flags: (*src).flags,
            },
        );
    }
    handler
}

/// Upstream handler `flags` marker: the handler lives for the process lifetime
/// (upstream `encoding.c` `{"UTF-8", ... , XML_HANDLER_STATIC}`) and
/// `xmlCharEncCloseFunc` must therefore not release it.
pub(crate) const XML_HANDLER_STATIC: c_int = 0x01;

/// ABI `xmlFindCharEncodingHandler` mirror (upstream libxml2 2.15 encoding.c
/// `xmlFindCharEncodingHandler`).
///
/// Upstream returns an OWNED handler the caller releases with
/// `xmlCharEncCloseFunc`, except for UTF-8/UTF8 where it returns the static
/// `defaultHandlers[XML_CHAR_ENCODING_UTF8]` (has `XML_HANDLER_STATIC`, so
/// `xmlCharEncCloseFunc` is a no-op). Phase 14 PHP court:
/// `dom_document_encoding_write` finds a handler for every `$dom->encoding=
/// write and closes it — so returning the persistent registry pointer for a
/// non-UTF-8 encoding let the caller's close free the registry entry (the
/// use-after-free behind `DOMDocument::$encoding = 'UTF-16'` crashing the next
/// `find_encoding_handler`).
///
/// Returns an owned heap copy for non-UTF-8 encodings, the flagged-static
/// registry UTF-8 handler for UTF-8, or `ptr::null_mut()` when `name` is NULL
/// or no handler is registered.
pub(crate) fn xmlFindCharEncodingHandler_owned(
    name: *const xmlChar,
) -> *mut _xmlCharEncodingHandler {
    if name.is_null() {
        return ptr::null_mut();
    }
    let name_bytes = unsafe {
        let len = libc::strlen(name as *const c_char);
        core::slice::from_raw_parts(name as *const u8, len)
    };

    // UTF-8 / UTF8 special case (upstream returns the static handler).
    if encoding_from_name(name_bytes) == xmlCharEncoding::XML_CHAR_ENCODING_UTF8 {
        let utf8 = find_encoding_handler(c"UTF-8".as_ptr() as *const xmlChar);
        if utf8.is_null() {
            return ptr::null_mut();
        }
        // Flag it static so xmlCharEncCloseFunc does not free the registry entry.
        unsafe {
            (*utf8).flags |= XML_HANDLER_STATIC;
        }
        return utf8;
    }

    // Non-UTF-8: resolve the registry entry, preferring a canonical lookup when
    // the raw spelling is not itself a registered key (mirrors the canonical
    // re-lookup upstream performs in xmlCreateCharEncodingHandler).
    let mut entry = find_encoding_handler(name as *const xmlChar);
    if entry.is_null() {
        if let Some(canon) = encoding_name(encoding_from_name(name_bytes)) {
            entry = find_encoding_handler(canon.as_ptr() as *const xmlChar);
        }
    }
    // Return an OWNED copy of the registry entry (never the entry itself), so
    // the caller's xmlCharEncCloseFunc releases only the copy.
    clone_encoding_handler_for_find(entry)
}

/// Add an encoding handler to the registry.
///
/// Returns 0 on success, -1 on failure (e.g., null pointer).
pub(crate) fn add_encoding_handler(handler: *mut _xmlCharEncodingHandler) -> c_int {
    if handler.is_null() {
        return -1;
    }

    let mut handlers = ENCODING_HANDLERS.write();
    handlers.push(HandlerPtr(handler));
    0
}

// ═══════════════════════════════════════════════════════════════════════════════
// 6. Encoding conversion functions
// ═══════════════════════════════════════════════════════════════════════════════

/// Input conversion: convert from handler's input encoding to UTF-8.
///
/// Calls the handler's `input.legacyFunc` callback. Returns bytes written or -1 on error.
///
/// # Safety
///
/// - `handler` must be NULL or a valid pointer to an initialized
///   `_xmlCharEncodingHandler`; the stored `input.legacyFunc` callback, when
///   present, must be a valid function pointer.
/// - `out` must be a valid mutable byte slice and `in_data` a valid byte
///   slice; both stay valid for the duration of the callback.
#[allow(dead_code)]
pub(crate) fn char_enc_in_func(
    handler: *mut _xmlCharEncodingHandler,
    out: &mut [u8],
    in_data: &[u8],
) -> c_int {
    if handler.is_null() {
        return -1;
    }

    let h = unsafe { &*handler };
    let input_func = unsafe { h.input.legacyFunc };
    let input_func = match input_func {
        Some(f) => f,
        None => return -1,
    };

    let mut outlen = out.len() as c_int;
    let mut inlen = in_data.len() as c_int;

    unsafe { input_func(out.as_mut_ptr(), &mut outlen, in_data.as_ptr(), &mut inlen) }
}

/// Output conversion: convert from UTF-8 to handler's output encoding.
///
/// Calls the handler's `output.legacyFunc` callback. Returns bytes written or -1 on error.
///
/// # Safety
///
/// - `handler` must be NULL or a valid pointer to an initialized
///   `_xmlCharEncodingHandler`; the stored `output.legacyFunc` callback,
///   when present, must be a valid function pointer.
/// - `out` must be a valid mutable byte slice and `in_data` a valid byte
///   slice; both stay valid for the duration of the callback.
#[allow(dead_code)]
pub(crate) fn char_enc_out_func(
    handler: *mut _xmlCharEncodingHandler,
    out: &mut [u8],
    in_data: &[u8],
) -> c_int {
    if handler.is_null() {
        return -1;
    }

    let h = unsafe { &*handler };
    let output_func = unsafe { h.output.legacyFunc };
    let output_func = match output_func {
        Some(f) => f,
        None => return -1,
    };

    let mut outlen = out.len() as c_int;
    let mut inlen = in_data.len() as c_int;

    unsafe { output_func(out.as_mut_ptr(), &mut outlen, in_data.as_ptr(), &mut inlen) }
}

/// Full input conversion (`xmlCharEncInFunc` equivalent).
///
/// Reads from the input `_xmlBuffer`, converts via the handler's `input.legacyFunc`,
/// and appends the result to the output `_xmlBuffer`.
///
/// Returns the number of bytes written to the output buffer, or -1 on error.
///
/// # Safety
///
/// - `handler` must be NULL or a valid `_xmlCharEncodingHandler` whose
///   `input.legacyFunc` callback is a valid function pointer.
/// - `in_` and `out` must be NULL or valid `_xmlBuffer` pointers; `in_`'s
///   `content` must be NULL or point to `use_` readable bytes, and `out`
///   must stay valid while `append_to_xml_buffer` may reallocate its
///   `content`.
pub(crate) fn char_enc_in(
    handler: *mut _xmlCharEncodingHandler,
    out: *mut _xmlBuffer,
    in_: *mut _xmlBuffer,
) -> c_int {
    if handler.is_null() || out.is_null() || in_.is_null() {
        return -1;
    }

    let h = unsafe { &*handler };
    let input_func = unsafe { h.input.legacyFunc };
    let input_func = match input_func {
        Some(f) => f,
        None => return -1,
    };

    let in_buf = unsafe { &*in_ };
    let out_buf = unsafe { &mut *out };

    if in_buf.content.is_null() || in_buf.use_ == 0 {
        return 0;
    }

    let in_data = unsafe { core::slice::from_raw_parts(in_buf.content, in_buf.use_ as usize) };

    // Allocate an output buffer. A good heuristic is 2x input for UTF-16→UTF-8.
    let out_capacity = (in_buf.use_ as usize).saturating_mul(3).max(256);
    let mut out_vec = vec![0u8; out_capacity];
    let mut out_len = out_capacity as c_int;
    let mut in_len = in_buf.use_ as c_int;

    let ret = unsafe {
        input_func(
            out_vec.as_mut_ptr(),
            &mut out_len,
            in_data.as_ptr(),
            &mut in_len,
        )
    };

    if ret < 0 {
        return -1;
    }

    let written = ret as usize;

    // Append to output buffer
    append_to_xml_buffer(out_buf, &out_vec[..written]);

    written as c_int
}

/// Full output conversion (`xmlCharEncOutFunc` equivalent).
///
/// Reads from the input `_xmlBuffer` (UTF-8), converts via the handler's
/// `output.legacyFunc`, and appends the result to the output `_xmlBuffer`.
///
/// Returns the number of bytes written to the output buffer, or -1 on error.
///
/// # Safety
///
/// - `handler` must be NULL or a valid `_xmlCharEncodingHandler` whose
///   `output.legacyFunc` callback is a valid function pointer.
/// - `in_` and `out` must be NULL or valid `_xmlBuffer` pointers; `in_`'s
///   `content` must be NULL or point to `use_` readable bytes, and `out`
///   must stay valid while `append_to_xml_buffer` may reallocate its
///   `content`.
pub(crate) fn char_enc_out(
    handler: *mut _xmlCharEncodingHandler,
    out: *mut _xmlBuffer,
    in_: *mut _xmlBuffer,
) -> c_int {
    if handler.is_null() || out.is_null() || in_.is_null() {
        return -1;
    }

    let h = unsafe { &*handler };
    let output_func = unsafe { h.output.legacyFunc };
    let output_func = match output_func {
        Some(f) => f,
        None => return -1,
    };

    let in_buf = unsafe { &*in_ };
    let out_buf = unsafe { &mut *out };

    if in_buf.content.is_null() || in_buf.use_ == 0 {
        return 0;
    }

    let mut in_data = unsafe { core::slice::from_raw_parts(in_buf.content, in_buf.use_ as usize) };

    // UPSTREAM-PARITY (encoding.c xmlCharEncOutput): the output conversion
    // runs in a loop; when the converter reports an INPUT error (a character
    // not representable in the output encoding — the ASCII handler stops at
    // the first byte >= 0x80), the offending UTF-8 character is decoded and
    // replaced by a DECIMAL character reference (&#NNN;), then conversion
    // continues. This is how libxml2 serializes non-ASCII text into an
    // ASCII output buffer (lxml's default `tostring` encoding, which
    // produces `&#195;&#169;` for the mojibake case).
    const ENC_INPUT_ERROR: c_int = -2;
    let mut total_written: usize = 0;
    loop {
        let out_capacity = (in_data.len().saturating_mul(3)).max(64) + 16;
        let mut out_vec = vec![0u8; out_capacity];
        let mut out_len = out_capacity as c_int;
        let mut in_len = in_data.len() as c_int;
        let ret = unsafe {
            output_func(
                out_vec.as_mut_ptr(),
                &mut out_len,
                in_data.as_ptr(),
                &mut in_len,
            )
        };
        let written = out_len.max(0) as usize;
        if written > 0 {
            append_to_xml_buffer(out_buf, &out_vec[..written]);
            total_written += written;
        }
        let consumed = in_len.max(0) as usize;
        if ret == ENC_INPUT_ERROR && consumed < in_data.len() {
            // Decode the UTF-8 character at the offending position and emit
            // a decimal character reference (upstream xmlSerializeDecCharRef).
            let mut clen: c_int = 4;
            let cp = unsafe {
                crate::abi::exports_misc::xmlGetUTF8Char(in_data[consumed..].as_ptr(), &mut clen)
            };
            if cp <= 0 || clen <= 0 || (consumed + clen as usize) > in_data.len() {
                return -1;
            }
            let ref_str = format!("&#{};", cp);
            append_to_xml_buffer(out_buf, ref_str.as_bytes());
            total_written += ref_str.len();
            in_data = &in_data[consumed + clen as usize..];
            if in_data.is_empty() {
                break;
            }
            continue;
        }
        if ret < 0 {
            return -1;
        }
        break;
    }

    total_written as c_int
}

/// Append bytes to an `_xmlBuffer`, reallocating if needed.
///
/// # Safety
///
/// - `buf` must be a valid `_xmlBuffer` whose `content` is NULL or points to
///   `size` allocated bytes; `buf.content` may be replaced by a fresh
///   `xmlReallocImpl` allocation when it must grow.
/// - `data` must be a valid byte slice; after the call, `buf.content` holds
///   `use_` initialized bytes.
fn append_to_xml_buffer(buf: &mut _xmlBuffer, data: &[u8]) {
    if data.is_empty() {
        return;
    }

    let new_use = (buf.use_ as usize).saturating_add(data.len());
    if new_use > buf.size as usize {
        // Grow buffer: double or fit, whichever is larger
        let new_size = (buf.size as usize).saturating_mul(2).max(new_use).max(256);
        let new_content =
            unsafe { xmlReallocImpl(buf.content as *mut c_void, new_size) as *mut xmlChar };
        if new_content.is_null() {
            return; // Allocation failure — silently skip
        }
        buf.content = new_content;
        // UPSTREAM-PARITY (io/mod.rs buf_add realloc paths): when the buffer
        // grows, contentIO tracks the CURRENT allocation base — buf_free
        // frees contentIO, so a stale contentIO (the pre-realloc block) would
        // cause a double-free on buffers that grew through this conversion
        // path (nokogiri HTML4/HTML5 UTF-8 serialization).
        buf.contentIO = new_content;
        buf.size = new_size as c_uint;
    }

    unsafe {
        ptr::copy_nonoverlapping(
            data.as_ptr(),
            buf.content.add(buf.use_ as usize),
            data.len(),
        );
    }
    buf.use_ = new_use as c_uint;
}

// ═══════════════════════════════════════════════════════════════════════════════
// 7. Built-in encoding handler callbacks (extern "C")
// ═══════════════════════════════════════════════════════════════════════════════

// ── UTF-8 (identity) ──────────────────────────────────────────────────────

/// UTF-8 input function: identity (input is already UTF-8).
///
/// Simply copies bytes from input to output, up to the available space.
unsafe extern "C" fn utf8_input_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    let avail_out = *outlen as usize;
    let avail_in = *inlen as usize;
    let to_copy = avail_out.min(avail_in);

    if to_copy > 0 {
        ptr::copy_nonoverlapping(in_, out, to_copy);
    }

    *outlen = to_copy as c_int;
    *inlen = to_copy as c_int;
    to_copy as c_int
}

/// UTF-8 output function: identity (output is already UTF-8).
unsafe extern "C" fn utf8_output_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    utf8_input_func(out, outlen, in_, inlen)
}

// ── UTF-16LE ──────────────────────────────────────────────────────────────

/// UTF-16LE input function: convert UTF-16LE to UTF-8.
unsafe extern "C" fn utf16le_input_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    if out.is_null() || outlen.is_null() || in_.is_null() || inlen.is_null() {
        return -1;
    }

    let avail_in = *inlen as usize;
    let avail_out = *outlen as usize;

    if avail_in == 0 || avail_out == 0 {
        *outlen = 0;
        *inlen = 0;
        return 0;
    }

    let in_data = core::slice::from_raw_parts(in_, avail_in);
    let _out_slice = core::slice::from_raw_parts_mut(out, avail_out);

    // Use the safe wrapper
    let result = match utf16le_to_utf8(in_data) {
        Ok(v) => v,
        Err(()) => return -1,
    };

    let written = result.len().min(avail_out);
    if written > 0 {
        ptr::copy_nonoverlapping(result.as_ptr(), out, written);
    }

    *outlen = written as c_int;
    *inlen = avail_in as c_int; // All input consumed
    written as c_int
}

/// UTF-16LE output function: convert UTF-8 to UTF-16LE.
unsafe extern "C" fn utf16le_output_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    if out.is_null() || outlen.is_null() || in_.is_null() || inlen.is_null() {
        return -1;
    }

    let avail_in = *inlen as usize;
    let avail_out = *outlen as usize;

    if avail_in == 0 || avail_out == 0 {
        *outlen = 0;
        *inlen = 0;
        return 0;
    }

    let in_data = core::slice::from_raw_parts(in_, avail_in);
    let _out_slice = core::slice::from_raw_parts_mut(out, avail_out);

    let result = match utf8_to_utf16le(in_data) {
        Ok(v) => v,
        Err(()) => return -1,
    };

    let written = result.len().min(avail_out);
    if written > 0 {
        ptr::copy_nonoverlapping(result.as_ptr(), out, written);
    }

    *outlen = written as c_int;
    *inlen = avail_in as c_int;
    written as c_int
}

// ── UTF-16BE ──────────────────────────────────────────────────────────────

/// UTF-16BE input function: convert UTF-16BE to UTF-8.
unsafe extern "C" fn utf16be_input_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    if out.is_null() || outlen.is_null() || in_.is_null() || inlen.is_null() {
        return -1;
    }

    let avail_in = *inlen as usize;
    let avail_out = *outlen as usize;

    if avail_in == 0 || avail_out == 0 {
        *outlen = 0;
        *inlen = 0;
        return 0;
    }

    let in_data = core::slice::from_raw_parts(in_, avail_in);
    let _out_slice = core::slice::from_raw_parts_mut(out, avail_out);

    let result = match utf16be_to_utf8(in_data) {
        Ok(v) => v,
        Err(()) => return -1,
    };

    let written = result.len().min(avail_out);
    if written > 0 {
        ptr::copy_nonoverlapping(result.as_ptr(), out, written);
    }

    *outlen = written as c_int;
    *inlen = avail_in as c_int;
    written as c_int
}

/// UTF-16BE output function: convert UTF-8 to UTF-16BE.
unsafe extern "C" fn utf16be_output_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    if out.is_null() || outlen.is_null() || in_.is_null() || inlen.is_null() {
        return -1;
    }

    let avail_in = *inlen as usize;
    let avail_out = *outlen as usize;

    if avail_in == 0 || avail_out == 0 {
        *outlen = 0;
        *inlen = 0;
        return 0;
    }

    let in_data = core::slice::from_raw_parts(in_, avail_in);

    // First convert to UTF-16LE, then swap bytes
    let le_result = match utf8_to_utf16le(in_data) {
        Ok(v) => v,
        Err(()) => return -1,
    };

    // Swap byte pairs to get UTF-16BE
    let mut result = le_result;
    for chunk in result.as_chunks_mut::<2>().0 {
        chunk.swap(0, 1);
    }

    let written = result.len().min(avail_out);
    if written > 0 {
        ptr::copy_nonoverlapping(result.as_ptr(), out, written);
    }

    *outlen = written as c_int;
    *inlen = avail_in as c_int;
    written as c_int
}

// ── ISO-8859-1 (Latin-1) ─────────────────────────────────────────────────

/// Latin-1 input function: convert ISO-8859-1 to UTF-8.
unsafe extern "C" fn latin1_input_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    if out.is_null() || outlen.is_null() || in_.is_null() || inlen.is_null() {
        return -1;
    }

    let avail_in = *inlen as usize;
    let avail_out = *outlen as usize;

    if avail_in == 0 || avail_out == 0 {
        *outlen = 0;
        *inlen = 0;
        return 0;
    }

    let in_data = core::slice::from_raw_parts(in_, avail_in);
    let out_slice = core::slice::from_raw_parts_mut(out, avail_out);

    let mut in_pos = 0;
    let mut out_pos = 0;

    while in_pos < avail_in && out_pos < avail_out {
        let byte = in_data[in_pos];
        in_pos += 1;

        if byte < 0x80 {
            // Single byte UTF-8
            if out_pos < avail_out {
                out_slice[out_pos] = byte;
                out_pos += 1;
            } else {
                break;
            }
        } else {
            // Two byte UTF-8: 0xC0 | (byte >> 6), 0x80 | (byte & 0x3F)
            // For byte 0x80-0xFF, the encoding is 0xC2-0xC3 followed by continuation
            if out_pos + 1 < avail_out {
                out_slice[out_pos] = 0xC2 | (byte >> 6);
                out_slice[out_pos + 1] = 0x80 | (byte & 0x3F);
                out_pos += 2;
            } else {
                break;
            }
        }
    }

    *outlen = out_pos as c_int;
    *inlen = in_pos as c_int;
    out_pos as c_int
}

/// Latin-1 output function: convert UTF-8 to ISO-8859-1.
unsafe extern "C" fn latin1_output_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    if out.is_null() || outlen.is_null() || in_.is_null() || inlen.is_null() {
        return -1;
    }

    let avail_in = *inlen as usize;
    let avail_out = *outlen as usize;

    if avail_in == 0 || avail_out == 0 {
        *outlen = 0;
        *inlen = 0;
        return 0;
    }

    let in_data = core::slice::from_raw_parts(in_, avail_in);
    let out_slice = core::slice::from_raw_parts_mut(out, avail_out);

    let mut in_pos = 0;
    let mut out_pos = 0;

    while in_pos < avail_in && out_pos < avail_out {
        let byte = in_data[in_pos];
        in_pos += 1;

        if byte < 0x80 {
            // ASCII — direct mapping
            out_slice[out_pos] = byte;
            out_pos += 1;
        } else if (0xC2..=0xC3).contains(&byte) {
            // Two-byte UTF-8 for codepoints U+0080–U+00FF
            if in_pos < avail_in {
                let second = in_data[in_pos];
                in_pos += 1;
                if second & 0xC0 != 0x80 {
                    return -1; // Invalid continuation byte
                }
                let cp = ((byte as u32 & 0x1F) << 6) | (second as u32 & 0x3F);
                if cp > 0xFF {
                    return -1; // Outside Latin-1 range
                }
                out_slice[out_pos] = cp as u8;
                out_pos += 1;
            } else {
                return -1; // Truncated
            }
        } else if (0x80..=0xBF).contains(&byte) {
            // Unexpected continuation byte
            return -1;
        } else {
            // Multi-byte sequence for codepoints > U+00FF
            // Skip the rest of the sequence and return error
            return -1;
        }
    }

    *outlen = out_pos as c_int;
    *inlen = in_pos as c_int;
    out_pos as c_int
}

// ── Windows-1252 (CP1252) ────────────────────────────────────────────────

/// Windows-1252 mapping for bytes 0x80..=0xFF (WHATWG windows-1252 == glibc
/// iconv CP1252). Bytes 0x81, 0x8D, 0x8F, 0x90, 0x9D are UNDEFINED in the
/// encoding (iconv raises EILSEQ on them). 0x00..=0x7F are ASCII and 0xA0..=
/// 0xFF are the Latin-1 supplement, so only 0x80..=0x9F need the table below
/// (indexed by `byte - 0x80`, U+FFFF = undefined).
///
/// R-000157 closure (partial): the oracle serves windows-1252 through iconv;
/// the candidate now ships a native converter for this single-byte set.
const CP1252_C1: [u16; 32] = [
    0x20AC, 0xFFFF, 0x201A, 0x0192, 0x201E, 0x2026, 0x2020, 0x2021, // 80..87
    0x02C6, 0x2030, 0x0160, 0x2039, 0x0152, 0xFFFF, 0x017D, 0xFFFF, // 88..8F
    0xFFFF, 0x2018, 0x2019, 0x201C, 0x201D, 0x2022, 0x2013, 0x2014, // 90..97
    0x02DC, 0x2122, 0x0161, 0x203A, 0x0153, 0xFFFF, 0x017E, 0x0178, // 98..9F
];

/// Map a Windows-1252 byte to its Unicode codepoint; `None` for the five
/// undefined C1 bytes.
#[allow(dead_code)]
pub(crate) const fn cp1252_byte_to_cp(byte: u8) -> Option<u32> {
    match byte {
        0x00..=0x7F => Some(byte as u32),
        0x80..=0x9F => {
            let cp = CP1252_C1[(byte - 0x80) as usize];
            if cp == 0xFFFF {
                None
            } else {
                Some(cp as u32)
            }
        }
        _ => Some(byte as u32), // 0xA0..=0xFF = Latin-1 supplement
    }
}

/// Map a Unicode codepoint back to its Windows-1252 byte; `None` when the
/// codepoint is not representable in windows-1252.
#[allow(dead_code)]
pub(crate) const fn cp_to_cp1252_byte(cp: u32) -> Option<u8> {
    if cp < 0x80 || (cp >= 0xA0 && cp <= 0xFF) {
        Some(cp as u8)
    } else if cp >= 0x80 && cp <= 0x9F {
        // Reverse scan of the C1 table (32 entries; called per character on
        // output conversion only).
        let mut i = 0;
        while i < 32 {
            if CP1252_C1[i] == cp as u16 {
                return Some(0x80 + i as u8);
            }
            i += 1;
        }
        None
    } else {
        None
    }
}

/// Convert a single UTF-8 character starting at `data[in_pos]` to its
/// codepoint. Returns `(cp, bytes_consumed)` or `None` on invalid UTF-8.
fn decode_utf8_char(data: &[u8], in_pos: usize) -> Option<(u32, usize)> {
    let b0 = *data.get(in_pos)?;
    if b0 < 0x80 {
        return Some((u32::from(b0), 1));
    }
    let (len, cp0) = match b0 {
        0xC2..=0xDF => (2, u32::from(b0 & 0x1F)),
        0xE0..=0xEF => (3, u32::from(b0 & 0x0F)),
        0xF0..=0xF4 => (4, u32::from(b0 & 0x07)),
        _ => return None,
    };
    if in_pos + len > data.len() {
        return None;
    }
    let mut cp = cp0;
    for k in 1..len {
        let b = data[in_pos + k];
        if b & 0xC0 != 0x80 {
            return None;
        }
        cp = (cp << 6) | u32::from(b & 0x3F);
    }
    Some((cp, len))
}

/// Convert a whole CP1252 byte slice to UTF-8.
///
/// Returns `Err(())` when a byte has no windows-1252 mapping (the five
/// undefined C1 bytes 0x81/0x8D/0x8F/0x90/0x9D — iconv raises EILSEQ).
pub(crate) fn cp1252_to_utf8(data: &[u8]) -> Result<Vec<u8>, ()> {
    let mut result = Vec::with_capacity(data.len() * 2);
    for &byte in data {
        let cp = match cp1252_byte_to_cp(byte) {
            None => return Err(()),
            Some(cp) => cp,
        };
        let mut buf = [0u8; 4];
        let n = encode_codepoint_to_utf8(cp, &mut buf);
        result.extend_from_slice(&buf[..n]);
    }
    Ok(result)
}

/// Convert UTF-8 bytes to CP1252 (used by whole-buffer output paths).
///
/// Returns `Err(())` on invalid UTF-8 or an unrepresentable codepoint.
#[allow(dead_code)]
pub(crate) fn utf8_to_cp1252(data: &[u8]) -> Result<Vec<u8>, ()> {
    let mut result = Vec::with_capacity(data.len());
    let mut pos = 0;
    while pos < data.len() {
        let (cp, consumed) = match decode_utf8_char(data, pos) {
            None => return Err(()),
            Some(v) => v,
        };
        let byte = match cp_to_cp1252_byte(cp) {
            None => return Err(()),
            Some(b) => b,
        };
        result.push(byte);
        pos += consumed;
    }
    Ok(result)
}

/// Windows-1252 input function: convert CP1252 bytes to UTF-8.
unsafe extern "C" fn cp1252_input_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    if out.is_null() || outlen.is_null() || in_.is_null() || inlen.is_null() {
        return -1;
    }

    let avail_in = *inlen as usize;
    let avail_out = *outlen as usize;

    if avail_in == 0 || avail_out == 0 {
        *outlen = 0;
        *inlen = 0;
        return 0;
    }

    let in_data = core::slice::from_raw_parts(in_, avail_in);
    let out_slice = core::slice::from_raw_parts_mut(out, avail_out);

    let mut in_pos = 0;
    let mut out_pos = 0;

    while in_pos < avail_in && out_pos < avail_out {
        let byte = in_data[in_pos];
        let cp = match cp1252_byte_to_cp(byte) {
            // Undefined byte (0x81/0x8D/0x8F/0x90/0x9D): EILSEQ like iconv.
            None => {
                *outlen = out_pos as c_int;
                *inlen = in_pos as c_int;
                return -1;
            }
            Some(cp) => cp,
        };
        let mut buf = [0u8; 4];
        let n = encode_codepoint_to_utf8(cp, &mut buf);
        if out_pos + n > avail_out {
            break;
        }
        out_slice[out_pos..out_pos + n].copy_from_slice(&buf[..n]);
        out_pos += n;
        in_pos += 1;
    }

    *outlen = out_pos as c_int;
    *inlen = in_pos as c_int;
    out_pos as c_int
}

/// Windows-1252 output function: convert UTF-8 to CP1252 bytes.
unsafe extern "C" fn cp1252_output_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    if out.is_null() || outlen.is_null() || in_.is_null() || inlen.is_null() {
        return -1;
    }

    let avail_in = *inlen as usize;
    let avail_out = *outlen as usize;

    if avail_in == 0 || avail_out == 0 {
        *outlen = 0;
        *inlen = 0;
        return 0;
    }

    let in_data = core::slice::from_raw_parts(in_, avail_in);
    let out_slice = core::slice::from_raw_parts_mut(out, avail_out);

    let mut in_pos = 0;
    let mut out_pos = 0;

    while in_pos < avail_in && out_pos < avail_out {
        let (cp, consumed) = match decode_utf8_char(in_data, in_pos) {
            None => {
                *outlen = out_pos as c_int;
                *inlen = in_pos as c_int;
                return -1;
            }
            Some(v) => v,
        };
        let byte = match cp_to_cp1252_byte(cp) {
            None => {
                // Not representable in windows-1252: EILSEQ like iconv.
                *outlen = out_pos as c_int;
                *inlen = in_pos as c_int;
                return -1;
            }
            Some(b) => b,
        };
        out_slice[out_pos] = byte;
        out_pos += 1;
        in_pos += consumed;
    }

    *outlen = out_pos as c_int;
    *inlen = in_pos as c_int;
    out_pos as c_int
}

// ── ASCII ─────────────────────────────────────────────────────────────────

/// ASCII input function: verify and pass through ASCII data to UTF-8.
///
/// Returns the number of bytes written, `-1` on invalid arguments, or
/// `-2` (the candidate's input-error code) when a byte >= 0x80 is reached
/// — in that case `*inlen`/`*outlen` hold the bytes consumed/written before
/// the offending character, so the output converter (`char_enc_out`) can
/// decode the UTF-8 character and replace it with a decimal character
/// reference (upstream `asciiToAscii` returns XML_ENC_ERR_INPUT).
unsafe extern "C" fn ascii_input_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    if out.is_null() || outlen.is_null() || in_.is_null() || inlen.is_null() {
        return -1;
    }

    let avail_in = *inlen as usize;
    let avail_out = *outlen as usize;

    if avail_in == 0 || avail_out == 0 {
        *outlen = 0;
        *inlen = 0;
        return 0;
    }

    let in_data = core::slice::from_raw_parts(in_, avail_in);
    let out_slice = core::slice::from_raw_parts_mut(out, avail_out);

    let mut pos = 0;
    while pos < avail_in && pos < avail_out {
        let byte = in_data[pos];
        if byte > 0x7F {
            // Not valid ASCII: report how much was consumed so the caller
            // can substitute a character reference and retry.
            *outlen = pos as c_int;
            *inlen = pos as c_int;
            return -2;
        }
        out_slice[pos] = byte;
        pos += 1;
    }

    *outlen = pos as c_int;
    *inlen = pos as c_int;
    pos as c_int
}

/// ASCII output function: verify and pass through UTF-8 data that is ASCII.
unsafe extern "C" fn ascii_output_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    // For output, ASCII handler requires that input is already ASCII
    ascii_input_func(out, outlen, in_, inlen)
}

// ── Shift_JIS / EUC-JP (encoding_rs-backed; R-000157 closure slice) ────────

/// Module-level input-error code: a converter reports the character at
/// `*inlen` as unrepresentable and `char_enc_out` substitutes the upstream
/// decimal character reference (&#NNN;) before retrying (encoding.c
/// xmlCharEncOutput XML_ENC_ERR_INPUT path).
const ENC_INPUT_ERROR: c_int = -2;

/// Shared output conversion for the encoding_rs-backed East-Asian handlers
/// (UTF-8 → `target`). House func contract (see cp1252): complete UTF-8
/// characters are converted while output space lasts; the first character
/// `target` cannot represent stops the conversion and is reported with the
/// -2 input-error convention (so `char_enc_out` emits the decimal character
/// reference and retries); invalid UTF-8 (or an incomplete trailing
/// sequence) reports -1 with the bytes before the error in `*inlen`. No
/// charref expansion happens inside the func, and Shift_JIS/EUC-JP output is
/// at most 1:1 with the UTF-8 input on the representable repertoire, so the
/// caller's >= 3x scratch can never overflow.
unsafe fn enc_rs_output(
    target: &'static encoding_rs::Encoding,
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    if out.is_null() || outlen.is_null() || in_.is_null() || inlen.is_null() {
        return -1;
    }
    let avail_in = *inlen as usize;
    let avail_out = *outlen as usize;

    if avail_in == 0 || avail_out == 0 {
        *outlen = 0;
        *inlen = 0;
        return 0;
    }

    let in_data = core::slice::from_raw_parts(in_, avail_in);
    let out_slice = core::slice::from_raw_parts_mut(out, avail_out);

    // Convert only complete UTF-8 characters. On invalid bytes (or an
    // incomplete trailing sequence) the valid prefix is converted and the
    // error is reported at the first offending byte (upstream iconv EILSEQ;
    // the xmlCharEncOutput error path decodes the UTF-8 character there).
    let (s, error_at) = match core::str::from_utf8(in_data) {
        Ok(s) => (s, None),
        Err(e) => {
            let valid = e.valid_up_to();
            if valid == 0 {
                *outlen = 0;
                *inlen = 0;
                return -1;
            }
            // SAFETY: `valid` is a UTF-8 boundary (from_utf8 guarantees the
            // valid prefix ends on a character boundary).
            (
                unsafe { core::str::from_utf8_unchecked(&in_data[..valid]) },
                Some(valid),
            )
        }
    };

    let mut encoder = target.new_encoder();
    let mut in_pos: usize = 0;
    let mut out_pos: usize = 0;
    while in_pos < s.len() && out_pos < avail_out {
        let dst = &mut out_slice[out_pos..];
        let (res, read, written) =
            encoder.encode_from_utf8_without_replacement(&s[in_pos..], dst, true);
        out_pos += written;
        in_pos += read;
        match res {
            encoding_rs::EncoderResult::InputEmpty => break,
            encoding_rs::EncoderResult::OutputFull => {
                // Output exhausted: report the partial conversion (with the
                // caller's >= 3x scratch this is unreachable for these
                // encodings on complete input).
                break;
            }
            encoding_rs::EncoderResult::Unmappable(c) => {
                // The encoder consumed the unrepresentable character `c`
                // (its UTF-8 bytes are the last len_utf8() bytes of the
                // consumed prefix), so rewind *inlen to point AT it:
                // char_enc_out substitutes the decimal character reference
                // for the character there and retries the remainder.
                *outlen = out_pos as c_int;
                *inlen = (in_pos - c.len_utf8()) as c_int;
                return ENC_INPUT_ERROR;
            }
        }
    }

    if let Some(err) = error_at {
        if in_pos == s.len() {
            // The whole convertible prefix was converted; report the UTF-8
            // error at the offending byte (the trailing partial is not
            // converted).
            *outlen = out_pos as c_int;
            *inlen = err as c_int;
            return -1;
        }
    }
    *outlen = out_pos as c_int;
    *inlen = in_pos as c_int;
    out_pos as c_int
}

/// Shared input conversion for the encoding_rs-backed East-Asian handlers
/// (`source` → UTF-8). Converts complete characters while output space
/// lasts; an undefined byte or an incomplete trailing sequence reports -1
/// with the bytes before the error in `*inlen` (iconv EILSEQ semantics —
/// deterministic and loop-free for the caller).
unsafe fn enc_rs_input(
    source: &'static encoding_rs::Encoding,
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    if out.is_null() || outlen.is_null() || in_.is_null() || inlen.is_null() {
        return -1;
    }
    let avail_in = *inlen as usize;
    let avail_out = *outlen as usize;

    if avail_in == 0 || avail_out == 0 {
        *outlen = 0;
        *inlen = 0;
        return 0;
    }

    let in_data = core::slice::from_raw_parts(in_, avail_in);
    let out_slice = core::slice::from_raw_parts_mut(out, avail_out);

    let mut decoder = source.new_decoder_without_bom_handling();
    let mut in_pos: usize = 0;
    let mut out_pos: usize = 0;
    while in_pos < avail_in && out_pos < avail_out {
        let (res, read, written) = decoder.decode_to_utf8_without_replacement(
            &in_data[in_pos..],
            &mut out_slice[out_pos..],
            true,
        );
        out_pos += written;
        in_pos += read;
        match res {
            encoding_rs::DecoderResult::InputEmpty => break,
            encoding_rs::DecoderResult::OutputFull => break,
            encoding_rs::DecoderResult::Malformed(..) => {
                // Undefined byte or incomplete tail: hard error after the
                // complete prefix (iconv EILSEQ).
                *outlen = out_pos as c_int;
                *inlen = in_pos as c_int;
                return -1;
            }
        }
    }

    *outlen = out_pos as c_int;
    *inlen = in_pos as c_int;
    out_pos as c_int
}

/// Shift_JIS input function (CP932-compatible WHATWG Shift_JIS → UTF-8).
unsafe extern "C" fn shift_jis_input_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    enc_rs_input(encoding_rs::SHIFT_JIS, out, outlen, in_, inlen)
}

/// Shift_JIS output function (UTF-8 → CP932-compatible WHATWG Shift_JIS).
unsafe extern "C" fn shift_jis_output_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    enc_rs_output(encoding_rs::SHIFT_JIS, out, outlen, in_, inlen)
}

/// EUC-JP input function (EUC-JP → UTF-8).
unsafe extern "C" fn euc_jp_input_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    enc_rs_input(encoding_rs::EUC_JP, out, outlen, in_, inlen)
}

/// EUC-JP output function (UTF-8 → EUC-JP).
unsafe extern "C" fn euc_jp_output_func(
    out: *mut c_uchar,
    outlen: *mut c_int,
    in_: *const c_uchar,
    inlen: *mut c_int,
) -> c_int {
    enc_rs_output(encoding_rs::EUC_JP, out, outlen, in_, inlen)
}

// ═══════════════════════════════════════════════════════════════════════════════
// 8. ABI export functions (called from exports_xml2.rs)
// ═══════════════════════════════════════════════════════════════════════════════

/// `xmlFindCharEncodingHandler` implementation.
///
/// Finds an encoding handler by name. Returns a pointer to the handler,
/// or `ptr::null_mut()` if not found.
pub(crate) fn xmlFindCharEncodingHandler(name: *const c_char) -> *mut _xmlCharEncodingHandler {
    if name.is_null() {
        return ptr::null_mut();
    }
    find_encoding_handler(name as *const xmlChar)
}

/// `xmlGetCharEncodingName` implementation.
///
/// Returns the canonical name for an encoding, or `ptr::null()` if unknown.
pub(crate) const fn xmlGetCharEncodingName(enc: xmlCharEncoding) -> *const c_char {
    // Return null-terminated C strings using static CStr literals.
    // Mirrors upstream 2.15 xmlGetCharEncodingName: the UTF-16/UCS-4 pairs
    // return the W3C canonical names before the defaultHandlers table.
    match enc {
        xmlCharEncoding::XML_CHAR_ENCODING_UTF8 => c"UTF-8".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE | xmlCharEncoding::XML_CHAR_ENCODING_UTF16BE => {
            c"UTF-16".as_ptr()
        }
        xmlCharEncoding::XML_CHAR_ENCODING_UCS4LE | xmlCharEncoding::XML_CHAR_ENCODING_UCS4BE => {
            c"UCS-4".as_ptr()
        }
        xmlCharEncoding::XML_CHAR_ENCODING_EBCDIC => c"IBM037".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_UCS2 => c"UCS-2".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_1 => c"ISO-8859-1".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_2 => c"ISO-8859-2".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_3 => c"ISO-8859-3".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_4 => c"ISO-8859-4".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_5 => c"ISO-8859-5".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_6 => c"ISO-8859-6".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_7 => c"ISO-8859-7".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_8 => c"ISO-8859-8".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_8859_9 => c"ISO-8859-9".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_2022_JP => c"ISO-2022-JP".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_SHIFT_JIS => c"Shift_JIS".as_ptr(),
        xmlCharEncoding::XML_CHAR_ENCODING_EUC_JP => c"EUC-JP".as_ptr(),
        // upstream defaultHandlers[22].name
        xmlCharEncoding::XML_CHAR_ENCODING_ASCII => c"US-ASCII".as_ptr(),
        _ => ptr::null(),
    }
}

/// `xmlParseCharEncoding` implementation.
///
/// Parses an encoding name string to an `xmlCharEncoding` enum value,
/// returned as `c_int`.
///
/// # Safety
///
/// - `name` must be NULL or a valid pointer to a NUL-terminated string.
pub(crate) fn xmlParseCharEncoding(name: *const c_char) -> c_int {
    if name.is_null() {
        return xmlCharEncoding::XML_CHAR_ENCODING_NONE as c_int;
    }
    let bytes = unsafe { CStr::from_ptr(name).to_bytes() };
    encoding_from_name(bytes) as c_int
}

// ── Encoding aliases (upstream encoding.c xmlAddEncodingAlias etc.) ──────────
//
// A global alias table maps alias names to canonical encoding names.
// Upstream keeps a static hash of aliases; the candidate uses a
// process-lifetime RwLock<HashMap>. Thread-safe; matches upstream's
// observable contract (add/del/get by name).

static ENCODING_ALIASES: std::sync::OnceLock<
    parking_lot::RwLock<std::collections::HashMap<Vec<u8>, Vec<u8>>>,
> = std::sync::OnceLock::new();

fn encoding_aliases() -> &'static parking_lot::RwLock<std::collections::HashMap<Vec<u8>, Vec<u8>>> {
    ENCODING_ALIASES.get_or_init(|| parking_lot::RwLock::new(std::collections::HashMap::new()))
}

/// `xmlAddEncodingAlias` implementation: register `alias` for `name`.
/// Returns 0 on success, -1 on error (NULL arguments).
///
/// # Safety
///
/// - `name` and `alias` must be NULL or valid pointers to NUL-terminated
///   strings; both are copied before insertion into the alias table.
pub(crate) fn add_encoding_alias(name: *const c_char, alias: *const c_char) -> c_int {
    if name.is_null() || alias.is_null() {
        return -1;
    }
    let n = unsafe { CStr::from_ptr(name).to_bytes().to_vec() };
    let a = unsafe { CStr::from_ptr(alias).to_bytes().to_vec() };
    encoding_aliases().write().insert(a, n);
    0
}

/// `xmlDelEncodingAlias` implementation: remove `alias`.
/// Returns 0 on success, -1 if the alias does not exist.
///
/// # Safety
///
/// - `alias` must be NULL or a valid pointer to a NUL-terminated string.
pub(crate) fn del_encoding_alias(alias: *const c_char) -> c_int {
    if alias.is_null() {
        return -1;
    }
    let a = unsafe { CStr::from_ptr(alias).to_bytes().to_vec() };
    if encoding_aliases().write().remove(&a).is_some() {
        0
    } else {
        -1
    }
}

/// `xmlGetEncodingAlias` implementation: return the canonical name for
/// `alias`, or NULL when not registered.
///
/// # Safety
///
/// - `alias` must be NULL or a valid pointer to a NUL-terminated string.
/// - The returned pointer is a leaked, process-lifetime NUL-terminated
///   string, or NULL; the caller must not free it.
pub(crate) fn get_encoding_alias(alias: *const c_char) -> *const c_char {
    if alias.is_null() {
        return ptr::null();
    }
    let a = unsafe { CStr::from_ptr(alias).to_bytes().to_vec() };
    let guard = encoding_aliases().read();
    match guard.get(&a) {
        Some(v) => {
            // leak the canonical name: upstream returns a pointer valid for
            // the process lifetime (the alias hash owns the strings)
            let leaked: &'static [u8] = Box::leak(v.clone().into_boxed_slice());
            leaked.as_ptr() as *const c_char
        }
        None => ptr::null(),
    }
}

/// `xmlCleanupEncodingAliases` implementation: drop all aliases.
pub(crate) fn cleanup_encoding_aliases() {
    encoding_aliases().write().clear();
}

/// `xmlCharEncInFunc` implementation.
///
/// Converts the input buffer's encoding to UTF-8 using the given handler.
pub(crate) fn xmlCharEncInFunc(
    handler: *mut _xmlCharEncodingHandler,
    out: *mut _xmlBuffer,
    in_: *mut _xmlBuffer,
) -> c_int {
    char_enc_in(handler, out, in_)
}

/// `xmlCharEncOutFunc` implementation.
///
/// Converts the input buffer from UTF-8 to the handler's output encoding.
pub(crate) fn xmlCharEncOutFunc(
    handler: *mut _xmlCharEncodingHandler,
    out: *mut _xmlBuffer,
    in_: *mut _xmlBuffer,
) -> c_int {
    char_enc_out(handler, out, in_)
}

/// `xmlNewCharEncodingHandler` implementation.
///
/// Creates a new encoding handler with the given name and conversion functions.
/// The name string is duplicated. Returns a pointer to the new handler,
/// or `ptr::null_mut()` on allocation failure.
///
/// # Safety
///
/// - `name` must be NULL or a valid pointer to a NUL-terminated string that
///   stays valid until it is duplicated.
/// - `input` and `output` must be valid function pointers matching the
///   callback ABI; on success the returned handler owns a duplicated name
///   and must be released with `xmlDelEncodingHandler`.
pub(crate) fn xmlNewCharEncodingHandler(
    name: *const c_char,
    input: xmlCharEncodingInputFunc,
    output: xmlCharEncodingOutputFunc,
) -> *mut _xmlCharEncodingHandler {
    if name.is_null() {
        return ptr::null_mut();
    }

    let name_raw = unsafe { crate::abi::allocator::xmlMemStrdupImpl(name) };
    if name_raw.is_null() {
        return ptr::null_mut();
    }

    let handler = unsafe { xmlMallocImpl(size_of::<_xmlCharEncodingHandler>()) }
        as *mut _xmlCharEncodingHandler;

    if handler.is_null() {
        unsafe { xmlFreeImpl(name_raw) };
        return ptr::null_mut();
    }

    unsafe {
        ptr::write(
            handler,
            _xmlCharEncodingHandler {
                name: name_raw as *mut c_char,
                input: EncodingInputUnion {
                    legacyFunc: Some(input),
                },
                output: EncodingOutputUnion {
                    legacyFunc: Some(output),
                },
                inputCtxt: ptr::null_mut(),
                outputCtxt: ptr::null_mut(),
                ctxtDtor: None,
                flags: 0,
            },
        );
    }

    handler
}

/// `xmlDelEncodingHandler` implementation.
///
/// Frees an encoding handler previously created with `xmlNewCharEncodingHandler`.
///
/// # Safety
///
/// - `handler` must be NULL or a valid heap-allocated
///   `_xmlCharEncodingHandler` whose `name` is NULL or a heap-allocated
///   NUL-terminated string; both allocations are freed exactly once, and the
///   handler must have been removed from the registry.
#[allow(dead_code)]
pub(crate) fn xmlDelEncodingHandler(handler: *mut _xmlCharEncodingHandler) {
    if handler.is_null() {
        return;
    }

    // Remove from registry if present
    {
        let mut handlers = ENCODING_HANDLERS.write();
        handlers.retain(|&h| h.0 != handler);
    }

    unsafe {
        if !(*handler).name.is_null() {
            xmlFreeImpl((*handler).name as *mut c_void);
        }
        xmlFreeImpl(handler as *mut c_void);
    }
}

/// `xmlInitCharEncodingHandlers` implementation.
pub(crate) fn xmlInitCharEncodingHandlers() {
    init_encodings();
}

/// `xmlCleanupCharEncodingHandlers` implementation.
pub(crate) fn xmlCleanupCharEncodingHandlers() {
    cleanup_encodings();
}

// ═══════════════════════════════════════════════════════════════════════════════
// 7. Handler lookup / creation (upstream 2.13.0+ encoding.c)
// ═══════════════════════════════════════════════════════════════════════════════
//
// Upstream keeps a static `defaultHandlers[32]` table indexed by xmlCharEncoding
// plus iconv/ICU fallbacks. The candidate ships no iconv/ICU, so encodings whose
// upstream default handler carries a real converter (UTF-8, UTF-16LE, UTF-16BE,
// UTF-16, ISO-8859-1, US-ASCII) resolve to the registered built-in handlers;
// every other encoding reports XML_ERR_UNSUPPORTED_ENCODING exactly where
// upstream would fall through to iconv/ICU.

/// `xmlLookupCharEncodingHandler` implementation (upstream encoding.c).
///
/// Mirrors the upstream control flow:
///  - `out == NULL`                     → XML_ERR_ARGUMENT (115)
///  - `enc <= 0 || enc >= 32`           → XML_ERR_UNSUPPORTED_ENCODING (32)
///  - UTF-8                             → XML_ERR_OK, `*out` stays NULL
///  - native built-in encoding          → XML_ERR_OK, `*out` = static handler
///  - iconv/ICU-only encoding           → XML_ERR_UNSUPPORTED_ENCODING
///
/// The returned handler is a static registry entry and must NOT be freed.
///
/// # Safety
///
/// - `out` must be a valid pointer to a `*mut c_void` out-parameter; it is
///   written with NULL or a pointer to a static registry handler that the
///   caller must not free.
pub(crate) fn xmlLookupCharEncodingHandler(enc: c_int, out: *mut *mut c_void) -> c_int {
    if out.is_null() {
        return crate::abi::types::XML_ERR_ARGUMENT;
    }
    unsafe {
        *out = ptr::null_mut();
    }
    if enc <= 0 || enc >= 32 {
        return crate::abi::types::XML_ERR_UNSUPPORTED_ENCODING;
    }
    /* Return NULL handler for UTF-8 */
    if enc == xmlCharEncoding::XML_CHAR_ENCODING_UTF8 as c_int {
        return crate::abi::types::XML_ERR_OK;
    }
    let canonical: &[u8] = match enc {
        /* XML_CHAR_ENCODING_UTF16LE */
        2 => b"UTF-16LE\0",
        /* XML_CHAR_ENCODING_UTF16BE */
        3 => b"UTF-16BE\0",
        /* XML_CHAR_ENCODING_8859_1 */
        10 => b"ISO-8859-1\0",
        /* XML_CHAR_ENCODING_ASCII */
        22 => b"US-ASCII\0",
        /* XML_CHAR_ENCODING_UTF16 (not in the local enum) */
        23 => b"UTF-16\0",
        _ => return crate::abi::types::XML_ERR_UNSUPPORTED_ENCODING,
    };
    let h = find_encoding_handler(canonical.as_ptr() as *const xmlChar);
    if h.is_null() {
        return crate::abi::types::XML_ERR_UNSUPPORTED_ENCODING;
    }
    unsafe {
        *out = h as *mut c_void;
    }
    crate::abi::types::XML_ERR_OK
}

/// `xmlGetCharEncodingHandler` implementation (deprecated upstream wrapper).
pub(crate) fn xmlGetCharEncodingHandler(enc: c_int) -> *mut c_void {
    let mut ret: *mut c_void = ptr::null_mut();
    let _rc = xmlLookupCharEncodingHandler(enc, &mut ret);
    ret
}

/// `xmlCreateCharEncodingHandler` implementation (upstream 2.14.0+ encoding.c).
///
/// Flags: XML_ENC_INPUT = 1, XML_ENC_OUTPUT = 2, XML_ENC_HTML = 4.
/// Unlike upstream, no iconv/ICU backend exists, so encodings without a native
/// converter fall through to `find_extra_handler` (custom impl / deprecated
/// global registry) and otherwise report XML_ERR_UNSUPPORTED_ENCODING.
///
/// # Safety
///
/// - `out` must be a valid pointer to a `*mut c_void` out-parameter; it is
///   written with NULL or a heap-allocated handler copy the caller owns.
/// - `name` must be NULL or a valid pointer to a NUL-terminated string.
/// - `implCtxt` is an opaque context forwarded to `find_extra_handler` and
///   must be valid for the callback that consumes it.
pub(crate) fn xmlCreateCharEncodingHandler(
    name: *const c_char,
    flags: c_int,
    impl_: Option<xmlCharEncConvImpl>,
    implCtxt: *mut c_void,
    out: *mut *mut c_void,
) -> c_int {
    if out.is_null() {
        return crate::abi::types::XML_ERR_ARGUMENT;
    }
    unsafe {
        *out = ptr::null_mut();
    }
    if name.is_null() || flags == 0 {
        return crate::abi::types::XML_ERR_ARGUMENT;
    }
    let norig = unsafe { CStr::from_ptr(name).to_bytes() };

    /* Alias resolution (upstream xmlGetEncodingAlias). */
    let mut eff: &[u8] = norig;
    let alias = get_encoding_alias(name);
    if !alias.is_null() {
        eff = unsafe { CStr::from_ptr(alias).to_bytes() };
    }

    let enc = encoding_from_name(eff);

    /* Return NULL handler for UTF-8 */
    if enc == xmlCharEncoding::XML_CHAR_ENCODING_UTF8 {
        return crate::abi::types::XML_ERR_OK;
    }

    let canonical: &[u8] = match enc {
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE => b"UTF-16LE\0",
        xmlCharEncoding::XML_CHAR_ENCODING_UTF16BE => b"UTF-16BE\0",
        xmlCharEncoding::XML_CHAR_ENCODING_8859_1 => b"ISO-8859-1\0",
        xmlCharEncoding::XML_CHAR_ENCODING_ASCII => b"US-ASCII\0",
        _ => {
            return find_extra_handler(norig, eff, flags, impl_, implCtxt, out);
        }
    };
    let h = find_encoding_handler(canonical.as_ptr() as *const xmlChar);
    if h.is_null() {
        return find_extra_handler(norig, eff, flags, impl_, implCtxt, out);
    }
    unsafe {
        let src = &*h;
        let has_in = (flags & 1) == 0 || !src.input.legacyFunc.is_none();
        let has_out = (flags & 2) == 0 || !src.output.legacyFunc.is_none();
        if !has_in || !has_out {
            return find_extra_handler(norig, eff, flags, impl_, implCtxt, out);
        }
        /*
         * Return a copy of the handler with the original name (upstream
         * "Return a copy of the handler with the original name").
         */
        let copy =
            xmlMallocImpl(size_of::<_xmlCharEncodingHandler>()) as *mut _xmlCharEncodingHandler;
        if copy.is_null() {
            return crate::abi::types::XML_ERR_NO_MEMORY;
        }
        let name_copy = crate::abi::allocator::xmlMemStrdupImpl(name) as *mut c_char;
        if name_copy.is_null() {
            xmlFreeImpl(copy as *mut c_void);
            return crate::abi::types::XML_ERR_NO_MEMORY;
        }
        ptr::write(
            copy,
            _xmlCharEncodingHandler {
                name: name_copy,
                input: EncodingInputUnion {
                    legacyFunc: src.input.legacyFunc,
                },
                output: EncodingOutputUnion {
                    legacyFunc: src.output.legacyFunc,
                },
                inputCtxt: src.inputCtxt,
                outputCtxt: src.outputCtxt,
                ctxtDtor: src.ctxtDtor,
                flags: src.flags,
            },
        );
        *out = copy as *mut c_void;
    }
    crate::abi::types::XML_ERR_OK
}

/// Fallback path of `xmlCreateCharEncodingHandler` (upstream `xmlFindExtraHandler`).
///
/// Tries the caller-supplied custom implementation first, then the deprecated
/// global handler registry. iconv/ICU do not exist in the candidate, so the
/// final result is XML_ERR_UNSUPPORTED_ENCODING.
///
/// # Safety
///
/// - `norig` and `name` must be valid byte slices; NUL-terminated copies are
///   built from them for lookups and callbacks.
/// - `out` must be a valid out-parameter; it is written with NULL or a
///   registry handler pointer that must not be freed.
/// - `implCtxt` must be a valid context for the custom `impl_` callback when
///   one is supplied.
fn find_extra_handler(
    norig: &[u8],
    name: &[u8],
    flags: c_int,
    impl_: Option<xmlCharEncConvImpl>,
    implCtxt: *mut c_void,
    out: *mut *mut c_void,
) -> c_int {
    /* Custom implementation before deprecated global handlers. */
    if let Some(f) = impl_ {
        let mut n = norig.to_vec();
        n.push(0);
        let rc = unsafe {
            f(
                implCtxt,
                n.as_ptr() as *const c_char,
                flags,
                out as *mut *mut crate::abi::structs::_xmlCharEncodingHandler,
            )
        };
        return rc;
    }
    /* Deprecated global handlers registry (xmlRegisterCharEncodingHandler). */
    let mut n = name.to_vec();
    n.push(0);
    let h = find_encoding_handler(n.as_ptr() as *const xmlChar);
    if !h.is_null() {
        unsafe {
            let src = &*h;
            let has_in = (flags & 1) == 0 || !src.input.legacyFunc.is_none();
            let has_out = (flags & 2) == 0 || !src.output.legacyFunc.is_none();
            if has_in && has_out {
                *out = h as *mut c_void;
                return crate::abi::types::XML_ERR_OK;
            }
        }
    }
    crate::abi::types::XML_ERR_UNSUPPORTED_ENCODING
}

/// `xmlOpenCharEncodingHandler` implementation (upstream encoding.c).
pub(crate) fn xmlOpenCharEncodingHandler(
    name: *const c_char,
    output: c_int,
    out: *mut *mut c_void,
) -> c_int {
    /* XML_ENC_OUTPUT if output else XML_ENC_INPUT */
    let flags: c_int = if output != 0 { 2 } else { 1 };
    xmlCreateCharEncodingHandler(name, flags, None, ptr::null_mut(), out)
}

/// `xmlCharEncNewCustomHandler` implementation (upstream 2.15.0+ encoding.c).
///
/// Creates a handler backed by modern `xmlCharEncConvFunc` callbacks (with
/// per-direction contexts and a context destructor). The handler must be
/// released with `xmlCharEncCloseFunc`.
///
/// # Safety
///
/// - `out` must be a valid pointer to a `*mut c_void` out-parameter.
/// - `name` must be NULL or a valid pointer to a NUL-terminated string.
/// - `input` and `output` must be valid `xmlCharEncConvFunc` callbacks;
///   `inputCtxt` and `outputCtxt` are opaque contexts consumed by them and
///   by `ctxtDtor`, which is invoked on each non-NULL context when
///   allocation fails (and later by `xmlCharEncCloseFunc`).
pub(crate) fn xmlCharEncNewCustomHandler(
    name: *const c_char,
    input: xmlCharEncConvFunc,
    output: xmlCharEncConvFunc,
    ctxtDtor: Option<xmlCharEncConvCtxtDtor>,
    inputCtxt: *mut c_void,
    outputCtxt: *mut c_void,
    out: *mut *mut c_void,
) -> c_int {
    if out.is_null() {
        return crate::abi::types::XML_ERR_ARGUMENT;
    }
    let handler = unsafe { xmlMallocImpl(size_of::<_xmlCharEncodingHandler>()) }
        as *mut _xmlCharEncodingHandler;
    if handler.is_null() {
        unsafe {
            if let Some(d) = ctxtDtor {
                if !inputCtxt.is_null() {
                    d(inputCtxt);
                }
                if !outputCtxt.is_null() {
                    d(outputCtxt);
                }
            }
        }
        return crate::abi::types::XML_ERR_NO_MEMORY;
    }
    let name_copy = if name.is_null() {
        ptr::null_mut()
    } else {
        let nc = unsafe { crate::abi::allocator::xmlMemStrdupImpl(name) } as *mut c_char;
        if nc.is_null() {
            unsafe { xmlFreeImpl(handler as *mut c_void) };
            unsafe {
                if let Some(d) = ctxtDtor {
                    if !inputCtxt.is_null() {
                        d(inputCtxt);
                    }
                    if !outputCtxt.is_null() {
                        d(outputCtxt);
                    }
                }
            }
            return crate::abi::types::XML_ERR_NO_MEMORY;
        }
        nc
    };
    unsafe {
        ptr::write(
            handler,
            _xmlCharEncodingHandler {
                name: name_copy,
                input: EncodingInputUnion { func: Some(input) },
                output: EncodingOutputUnion { func: Some(output) },
                inputCtxt,
                outputCtxt,
                ctxtDtor,
                flags: 0,
            },
        );
        *out = handler as *mut c_void;
    }
    crate::abi::types::XML_ERR_OK
}

// ═══════════════════════════════════════════════════════════════════════════════
// Tests
// ═══════════════════════════════════════════════════════════════════════════════

#[cfg(test)]
mod tests {
    use super::*;

    // ── BOM detection ──────────────────────────────────────────────────────

    #[test]
    fn test_detect_bom_utf8() {
        let data = [0xEF, 0xBB, 0xBF, b'<', b'?', b'x', b'm', b'l'];
        assert_eq!(
            detect_encoding_from_bom(&data),
            xmlCharEncoding::XML_CHAR_ENCODING_UTF8
        );
    }

    #[test]
    fn test_detect_bom_utf16le() {
        let data = [0xFF, 0xFE, 0x00, 0x01];
        assert_eq!(
            detect_encoding_from_bom(&data),
            xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE
        );
    }

    #[test]
    fn test_detect_bom_utf16be() {
        let data = [0xFE, 0xFF, 0x00, 0x01];
        assert_eq!(
            detect_encoding_from_bom(&data),
            xmlCharEncoding::XML_CHAR_ENCODING_UTF16BE
        );
    }

    #[test]
    fn test_detect_bom_none() {
        let data = b"<xml>";
        assert_eq!(
            detect_encoding_from_bom(data),
            xmlCharEncoding::XML_CHAR_ENCODING_NONE
        );
    }

    #[test]
    fn test_detect_bom_empty() {
        assert_eq!(
            detect_encoding_from_bom(b""),
            xmlCharEncoding::XML_CHAR_ENCODING_NONE
        );
    }

    // ── Encoding from declaration ──────────────────────────────────────────

    #[test]
    fn test_detect_encoding_declaration_utf8() {
        let data = b"<?xml version=\"1.0\" encoding=\"UTF-8\"?>";
        let result = detect_encoding_from_declaration(data);
        assert_eq!(result, Some(b"utf-8".to_vec()));
    }

    #[test]
    fn test_detect_encoding_declaration_iso() {
        let data = b"<?xml version='1.0' encoding='ISO-8859-1'?>";
        let result = detect_encoding_from_declaration(data);
        assert_eq!(result, Some(b"iso-8859-1".to_vec()));
    }

    #[test]
    fn test_detect_encoding_declaration_none() {
        let data = b"<?xml version=\"1.0\"?>";
        let result = detect_encoding_from_declaration(data);
        assert!(result.is_none());
    }

    #[test]
    fn test_detect_encoding_declaration_no_xml() {
        let data = b"<root>";
        let result = detect_encoding_from_declaration(data);
        assert!(result.is_none());
    }

    #[test]
    fn test_detect_encoding_declaration_with_bom() {
        let mut data = vec![0xEF, 0xBB, 0xBF];
        data.extend_from_slice(b"<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
        let result = detect_encoding_from_declaration(&data);
        assert_eq!(result, Some(b"utf-8".to_vec()));
    }

    // ── Encoding from name ─────────────────────────────────────────────────

    #[test]
    fn test_encoding_from_name_utf8() {
        assert_eq!(
            encoding_from_name(b"UTF-8"),
            xmlCharEncoding::XML_CHAR_ENCODING_UTF8
        );
        assert_eq!(
            encoding_from_name(b"utf8"),
            xmlCharEncoding::XML_CHAR_ENCODING_UTF8
        );
    }

    #[test]
    fn test_encoding_from_name_utf16() {
        assert_eq!(
            encoding_from_name(b"UTF-16LE"),
            xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE
        );
        assert_eq!(
            encoding_from_name(b"UTF-16BE"),
            xmlCharEncoding::XML_CHAR_ENCODING_UTF16BE
        );
        assert_eq!(
            encoding_from_name(b"utf-16"),
            xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE
        );
    }

    #[test]
    fn test_encoding_from_name_latin1() {
        assert_eq!(
            encoding_from_name(b"ISO-8859-1"),
            xmlCharEncoding::XML_CHAR_ENCODING_8859_1
        );
        assert_eq!(
            encoding_from_name(b"Latin1"),
            xmlCharEncoding::XML_CHAR_ENCODING_8859_1
        );
    }

    #[test]
    fn test_encoding_from_name_ascii() {
        assert_eq!(
            encoding_from_name(b"ASCII"),
            xmlCharEncoding::XML_CHAR_ENCODING_ASCII
        );
        assert_eq!(
            encoding_from_name(b"US-ASCII"),
            xmlCharEncoding::XML_CHAR_ENCODING_ASCII
        );
    }

    #[test]
    fn test_encoding_from_name_error() {
        assert_eq!(
            encoding_from_name(b"invalid-encoding"),
            xmlCharEncoding::XML_CHAR_ENCODING_ERROR
        );
    }

    #[test]
    fn test_encoding_from_name_empty() {
        assert_eq!(
            encoding_from_name(b""),
            xmlCharEncoding::XML_CHAR_ENCODING_ERROR
        );
    }

    // ── Encoding name ──────────────────────────────────────────────────────

    #[test]
    fn test_encoding_name_utf8() {
        assert_eq!(
            encoding_name(xmlCharEncoding::XML_CHAR_ENCODING_UTF8),
            Some(b"UTF-8" as &[u8])
        );
    }

    #[test]
    fn test_encoding_name_utf16le() {
        assert_eq!(
            encoding_name(xmlCharEncoding::XML_CHAR_ENCODING_UTF16LE),
            Some(b"UTF-16LE" as &[u8])
        );
    }

    #[test]
    fn test_encoding_name_none() {
        assert!(encoding_name(xmlCharEncoding::XML_CHAR_ENCODING_NONE).is_none());
    }

    #[test]
    fn test_encoding_name_error() {
        assert!(encoding_name(xmlCharEncoding::XML_CHAR_ENCODING_ERROR).is_none());
    }

    // ── UTF-8 validation ───────────────────────────────────────────────────

    #[test]
    fn test_utf8_valid_ascii() {
        assert!(utf8_valid(b"hello world"));
    }

    #[test]
    fn test_utf8_valid_multi_byte() {
        assert!(utf8_valid("héllo wörld 🌍".as_bytes()));
    }

    #[test]
    fn test_utf8_valid_empty() {
        assert!(utf8_valid(b""));
    }

    #[test]
    fn test_utf8_invalid() {
        assert!(!utf8_valid(&[0xFF, 0xFE, 0x00]));
    }

    // ── XML char validation ────────────────────────────────────────────────

    #[test]
    fn test_valid_xml_chars() {
        assert!(is_valid_xml_char(0x9)); // Tab
        assert!(is_valid_xml_char(0xA)); // LF
        assert!(is_valid_xml_char(0xD)); // CR
        assert!(is_valid_xml_char(0x20)); // Space
        assert!(is_valid_xml_char(0x41)); // 'A'
        assert!(is_valid_xml_char(0xD7FF));
        assert!(is_valid_xml_char(0xE000));
        assert!(is_valid_xml_char(0xFFFD));
        assert!(is_valid_xml_char(0x10000));
        assert!(is_valid_xml_char(0x10FFFF));
    }

    #[test]
    fn test_invalid_xml_chars() {
        assert!(!is_valid_xml_char(0x00));
        assert!(!is_valid_xml_char(0x08));
        assert!(!is_valid_xml_char(0x0B));
        assert!(!is_valid_xml_char(0x0C));
        assert!(!is_valid_xml_char(0x0E));
        assert!(!is_valid_xml_char(0x1F));
        assert!(!is_valid_xml_char(0xD800)); // Surrogate
        assert!(!is_valid_xml_char(0xDFFF)); // Surrogate
        assert!(!is_valid_xml_char(0xFFFE));
        assert!(!is_valid_xml_char(0xFFFF));
        assert!(!is_valid_xml_char(0x110000));
    }

    // ── UTF-16LE to UTF-8 ──────────────────────────────────────────────────

    #[test]
    fn test_utf16le_to_utf8_ascii() {
        // "AB" in UTF-16LE
        let data = [b'A', 0x00, b'B', 0x00];
        let result = utf16le_to_utf8(&data).unwrap();
        assert_eq!(result, b"AB");
    }

    #[test]
    fn test_utf16le_to_utf8_bom() {
        let mut data = vec![0xFF, 0xFE]; // BOM
        data.extend_from_slice(&[b'A', 0x00, b'B', 0x00]);
        let result = utf16le_to_utf8(&data).unwrap();
        assert_eq!(result, b"AB");
    }

    #[test]
    fn test_utf16le_to_utf8_bmp() {
        // U+00E9 (é) in UTF-16LE = 0xE9 0x00
        let data = [0xE9, 0x00];
        let result = utf16le_to_utf8(&data).unwrap();
        assert_eq!(result, "é".as_bytes());
    }

    #[test]
    fn test_utf16le_to_utf8_supplementary() {
        // U+1F600 (😀) in UTF-16LE = 0x3D 0xD8 0x00 0xDE
        let data = [0x3D, 0xD8, 0x00, 0xDE];
        let result = utf16le_to_utf8(&data).unwrap();
        assert_eq!(result, "😀".as_bytes());
    }

    #[test]
    fn test_utf16le_to_utf8_unpaired_surrogate() {
        let data = [0x00, 0xD8]; // High surrogate without low
        assert!(utf16le_to_utf8(&data).is_err());
    }

    #[test]
    fn test_utf16le_to_utf8_truncated() {
        let data = [0x00]; // Odd length
        assert!(utf16le_to_utf8(&data).is_err());
    }

    #[test]
    fn test_utf16le_to_utf8_empty() {
        let result = utf16le_to_utf8(b"").unwrap();
        assert!(result.is_empty());
    }

    // ── UTF-16BE to UTF-8 ──────────────────────────────────────────────────

    #[test]
    fn test_utf16be_to_utf8_ascii() {
        let data = [0x00, b'A', 0x00, b'B'];
        let result = utf16be_to_utf8(&data).unwrap();
        assert_eq!(result, b"AB");
    }

    #[test]
    fn test_utf16be_to_utf8_bom() {
        let mut data = vec![0xFE, 0xFF]; // BOM
        data.extend_from_slice(&[0x00, b'A', 0x00, b'B']);
        let result = utf16be_to_utf8(&data).unwrap();
        assert_eq!(result, b"AB");
    }

    #[test]
    fn test_utf16be_to_utf8_supplementary() {
        // U+1F600 (😀) in UTF-16BE = 0xD8 0x3D 0xDE 0x00
        let data = [0xD8, 0x3D, 0xDE, 0x00];
        let result = utf16be_to_utf8(&data).unwrap();
        assert_eq!(result, "😀".as_bytes());
    }

    #[test]
    fn test_utf16be_to_utf8_empty() {
        let result = utf16be_to_utf8(b"").unwrap();
        assert!(result.is_empty());
    }

    // ── UTF-8 to UTF-16LE ──────────────────────────────────────────────────

    #[test]
    fn test_utf8_to_utf16le_ascii() {
        let result = utf8_to_utf16le(b"AB").unwrap();
        assert_eq!(result, [b'A', 0x00, b'B', 0x00]);
    }

    #[test]
    fn test_utf8_to_utf16le_bmp() {
        let result = utf8_to_utf16le("é".as_bytes()).unwrap();
        assert_eq!(result, [0xE9, 0x00]);
    }

    #[test]
    fn test_utf8_to_utf16le_supplementary() {
        let result = utf8_to_utf16le("😀".as_bytes()).unwrap();
        assert_eq!(result, [0x3D, 0xD8, 0x00, 0xDE]);
    }

    #[test]
    fn test_utf8_to_utf16le_invalid_utf8() {
        assert!(utf8_to_utf16le(&[0xFF]).is_err());
    }

    #[test]
    fn test_utf8_to_utf16le_empty() {
        let result = utf8_to_utf16le(b"").unwrap();
        assert!(result.is_empty());
    }

    // ── Latin-1 to UTF-8 ───────────────────────────────────────────────────

    #[test]
    fn test_latin1_to_utf8_ascii() {
        let result = latin1_to_utf8(b"ABC");
        assert_eq!(result, b"ABC");
    }

    #[test]
    fn test_latin1_to_utf8_accented() {
        // 0xE9 = é in Latin-1
        let result = latin1_to_utf8(&[0xE9]);
        assert_eq!(result, "é".as_bytes());
    }

    #[test]
    fn test_latin1_to_utf8_all_255() {
        let result = latin1_to_utf8(&[0xFF]);
        // U+00FF = ÿ, UTF-8: 0xC3 0xBF
        assert_eq!(result, [0xC3, 0xBF]);
    }

    #[test]
    fn test_latin1_to_utf8_empty() {
        let result = latin1_to_utf8(b"");
        assert!(result.is_empty());
    }

    #[test]
    fn test_latin1_to_utf8_mixed() {
        let result = latin1_to_utf8(b"caf\xE9");
        assert_eq!(result, "café".as_bytes());
    }

    // ── UTF-8 to Latin-1 ───────────────────────────────────────────────────

    #[test]
    fn test_utf8_to_latin1_ascii() {
        let result = utf8_to_latin1(b"ABC").unwrap();
        assert_eq!(result, b"ABC");
    }

    #[test]
    fn test_utf8_to_latin1_accented() {
        let result = utf8_to_latin1("é".as_bytes()).unwrap();
        assert_eq!(result, [0xE9]);
    }

    #[test]
    fn test_utf8_to_latin1_out_of_range() {
        assert!(utf8_to_latin1("€".as_bytes()).is_err()); // U+20AC not in Latin-1
    }

    #[test]
    fn test_utf8_to_latin1_invalid_utf8() {
        assert!(utf8_to_latin1(&[0xFF]).is_err());
    }

    #[test]
    fn test_utf8_to_latin1_empty() {
        let result = utf8_to_latin1(b"").unwrap();
        assert!(result.is_empty());
    }

    // ── Encoding handler registry ──────────────────────────────────────────

    #[test]
    fn test_init_and_find_encodings() {
        init_encodings();

        let utf8_name: *const xmlChar = c"UTF-8".as_ptr() as *const xmlChar;
        assert!(!find_encoding_handler(utf8_name).is_null());

        let utf16le_name: *const xmlChar = c"UTF-16LE".as_ptr() as *const xmlChar;
        assert!(!find_encoding_handler(utf16le_name).is_null());

        let utf16be_name: *const xmlChar = c"UTF-16BE".as_ptr() as *const xmlChar;
        assert!(!find_encoding_handler(utf16be_name).is_null());

        let latin1_name: *const xmlChar = c"ISO-8859-1".as_ptr() as *const xmlChar;
        assert!(!find_encoding_handler(latin1_name).is_null());

        let ascii_name: *const xmlChar = c"ASCII".as_ptr() as *const xmlChar;
        assert!(!find_encoding_handler(ascii_name).is_null());

        // Case insensitive
        let lower_name: *const xmlChar = c"utf-8".as_ptr() as *const xmlChar;
        assert!(!find_encoding_handler(lower_name).is_null());
    }

    /// Phase 14 PHP court regression: the ABI `xmlFindCharEncodingHandler`
    /// hands the caller an OWNED handler that it may release with
    /// `xmlCharEncCloseFunc` — except UTF-8, where upstream returns a static
    /// handler that close must not release (so the registry is never freed
    /// out from under subsequent lookups). Closing a returned non-UTF-8
    /// handler must not free the persistent registry entry.
    ///
    /// # Safety
    ///
    /// - The handler returned by `xmlFindCharEncodingHandler_owned` is owned by
    ///   the caller and released here with the allocator, mirroring the export
    ///   `xmlCharEncCloseFunc` (which, for these stateless built-in handlers,
    ///   frees `name` and the struct without invoking any context destructor).
    #[test]
    fn test_find_owned_close_keeps_registry_intact() {
        init_encodings();
        let name: *const xmlChar = c"ISO-8859-1".as_ptr() as *const xmlChar;

        // The registry entry is a long-lived borrow.
        let registry = find_encoding_handler(name);
        assert!(!registry.is_null());
        // First retrieval returns an OWNED copy, distinct from the registry entry.
        let h1 = xmlFindCharEncodingHandler_owned(name);
        assert!(!h1.is_null());
        assert_ne!(h1 as *const c_void, registry as *const c_void);

        // Closing h1 (simulate xmlCharEncCloseFunc on a non-static handler):
        // frees its name + struct but NOT the registry entry.
        unsafe {
            if !(*h1).name.is_null() {
                crate::abi::allocator::xmlFreeImpl((*h1).name as *mut c_void);
            }
            xmlFreeImpl(h1 as *mut c_void);
        }

        // The registry entry must survive the close of a previous result with
        // its name intact (the PHP `$dom->encoding='UTF-16'` crash was the
        // registry entry itself being freed by this very close, so the next
        // lookup returned freed memory).
        let registry2 = find_encoding_handler(name);
        assert_eq!(registry2 as *const c_void, registry as *const c_void);
        assert!(!unsafe { (*registry2).name }.is_null());
        let reg_name = unsafe { CStr::from_ptr((*registry2).name as *const c_char) };
        assert_eq!(reg_name.to_bytes(), b"ISO-8859-1");

        // A second owned retrieval still works and is usable.
        let h2 = xmlFindCharEncodingHandler_owned(name);
        assert!(!h2.is_null());
        assert_ne!(h2 as *const c_void, registry as *const c_void);
        unsafe {
            if !(*h2).name.is_null() {
                crate::abi::allocator::xmlFreeImpl((*h2).name as *mut c_void);
            }
            xmlFreeImpl(h2 as *mut c_void);
        }
    }

    /// Phase 14 PHP court regression (UTF-8 subset): retrieval for UTF-8/UTF8
    /// returns the persistent static handler, and referencing it from a second
    /// caller must yield the same live pointer (the registry entry is never
    /// freed by a close — `xmlCharEncCloseFunc` on XML_HANDLER_STATIC is a
    /// no-op).
    #[test]
    fn test_find_owned_utf8_static_and_persistent() {
        init_encodings();
        let name: *const xmlChar = c"UTF-8".as_ptr() as *const xmlChar;
        let u1 = xmlFindCharEncodingHandler_owned(name);
        assert!(!u1.is_null());
        // Static: close must not release it, so a second find returns the same
        // live registry handler.
        let u2 = xmlFindCharEncodingHandler_owned(c"utf8".as_ptr() as *const xmlChar);
        assert_eq!(u1, u2);
        assert_eq!(
            unsafe { (*u1).flags } & XML_HANDLER_STATIC,
            XML_HANDLER_STATIC
        );
    }

    #[test]
    fn test_find_encoding_handler_not_found() {
        let name: *const xmlChar = c"NONEXISTENT".as_ptr() as *const xmlChar;
        assert!(find_encoding_handler(name).is_null());
    }

    #[test]
    fn test_find_encoding_handler_null() {
        assert!(find_encoding_handler(ptr::null()).is_null());
    }

    /// Verify registering a handler in the global registry and looking it
    /// up.
    ///
    /// # Safety
    ///
    /// - The `xmlMallocImpl` and `xmlMemStrdupImpl` results are NULL-checked
    ///   before `ptr::write` initializes the handler; the handler is removed
    ///   from the registry before its allocations are freed exactly once.
    #[test]
    fn test_add_encoding_handler() {
        let handler = unsafe {
            xmlMallocImpl(size_of::<_xmlCharEncodingHandler>()) as *mut _xmlCharEncodingHandler
        };
        assert!(!handler.is_null());

        let name = unsafe {
            crate::abi::allocator::xmlMemStrdupImpl(c"TEST-ENC".as_ptr() as *const c_char)
        };
        unsafe {
            ptr::write(
                handler,
                _xmlCharEncodingHandler {
                    name: name as *mut c_char,
                    input: EncodingInputUnion { legacyFunc: None },
                    output: EncodingOutputUnion { legacyFunc: None },
                    inputCtxt: ptr::null_mut(),
                    outputCtxt: ptr::null_mut(),
                    ctxtDtor: None,
                    flags: 0,
                },
            );
        }

        assert_eq!(add_encoding_handler(handler), 0);

        let found = find_encoding_handler(c"TEST-ENC".as_ptr() as *const xmlChar);
        assert_eq!(found, handler);

        // Remove from registry before freeing to avoid dangling pointers
        {
            let mut handlers = ENCODING_HANDLERS.write();
            handlers.retain(|&h| h.0 != handler);
        }

        unsafe {
            xmlFreeImpl(name as *mut c_void);
            xmlFreeImpl(handler as *mut c_void);
        }
    }

    // ── Conversion round-trips ─────────────────────────────────────────────

    #[test]
    fn test_utf16le_roundtrip() {
        let original = b"Hello, World! UTF-16LE test: \xC3\xA9\xF0\x9F\x98\x80";
        let utf16 = utf8_to_utf16le(original).unwrap();
        let back = utf16le_to_utf8(&utf16).unwrap();
        assert_eq!(original.to_vec(), back);
    }

    #[test]
    fn test_utf16be_roundtrip() {
        let original = b"Hello, World! UTF-16BE test: \xC3\xA9\xF0\x9F\x98\x80";
        let utf16le = utf8_to_utf16le(original).unwrap();
        // Convert LE to BE by swapping bytes
        let mut utf16be = utf16le.clone();
        for chunk in utf16be.as_chunks_mut::<2>().0 {
            chunk.swap(0, 1);
        }
        let back = utf16be_to_utf8(&utf16be).unwrap();
        assert_eq!(original.to_vec(), back);
    }

    #[test]
    fn test_latin1_roundtrip() {
        let original: Vec<u8> = (0x00..=0xFF).collect();
        let utf8 = latin1_to_utf8(&original);
        let back = utf8_to_latin1(&utf8).unwrap();
        assert_eq!(original, back);
    }

    // ── Built-in handler callbacks ─────────────────────────────────────────

    /// Verify the UTF-8 identity callback copies bytes up to the smaller
    /// length.
    ///
    /// # Safety
    ///
    /// - `output` is a valid mutable 64-byte buffer and `input` a valid byte
    ///   slice; the callback writes at most the minimum of the two lengths.
    #[test]
    fn test_utf8_handler_identity() {
        let input = b"Hello, UTF-8!";
        let mut output = [0u8; 64];
        let mut outlen = output.len() as c_int;
        let mut inlen = input.len() as c_int;

        let ret = unsafe {
            utf8_input_func(output.as_mut_ptr(), &mut outlen, input.as_ptr(), &mut inlen)
        };

        assert_eq!(ret, input.len() as c_int);
        assert_eq!(&output[..ret as usize], input);
        assert_eq!(inlen, input.len() as c_int);
    }

    /// Verify a UTF-16LE output/input callback round-trip.
    ///
    /// # Safety
    ///
    /// - The `utf16_buf` and `decoded` arrays are valid buffers of the given
    ///   lengths, and the input slices are valid; the callbacks write only
    ///   up to the advertised output length.
    #[test]
    fn test_utf16le_handler_roundtrip() {
        init_encodings();

        let original = b"Hello UTF-16LE!";
        let mut utf16_buf = [0u8; 128];
        let mut outlen = utf16_buf.len() as c_int;
        let mut inlen = original.len() as c_int;

        let written = unsafe {
            utf16le_output_func(
                utf16_buf.as_mut_ptr(),
                &mut outlen,
                original.as_ptr(),
                &mut inlen,
            )
        };
        assert!(written > 0);

        // Now decode back
        let mut decoded = [0u8; 128];
        let mut outlen2 = decoded.len() as c_int;
        let mut inlen2 = written;

        let written2 = unsafe {
            utf16le_input_func(
                decoded.as_mut_ptr(),
                &mut outlen2,
                utf16_buf.as_ptr(),
                &mut inlen2,
            )
        };
        assert_eq!(written2 as usize, original.len());
        assert_eq!(&decoded[..written2 as usize], original);
    }

    // ── xmlBuffer operations ───────────────────────────────────────────────

    /// Verify `append_to_xml_buffer` grows the buffer and copies bytes.
    ///
    /// # Safety
    ///
    /// - `content` is a valid 64-byte allocation owned by the test and freed
    ///   exactly once with `xmlFreeImpl`; `buf` keeps consistent `use_` and
    ///   `size` fields while `append_to_xml_buffer` may reallocate `content`.
    #[test]
    fn test_append_to_xml_buffer() {
        unsafe {
            let content = xmlMallocImpl(64) as *mut xmlChar;
            assert!(!content.is_null());

            let mut buf = _xmlBuffer {
                content,
                use_: 0,
                size: 64,
                alloc: 0,
                contentIO: ptr::null_mut(),
            };

            append_to_xml_buffer(&mut buf, b"Hello");
            assert_eq!(buf.use_, 5);
            let slice = core::slice::from_raw_parts(buf.content, 5);
            assert_eq!(slice, b"Hello");

            append_to_xml_buffer(&mut buf, b" World");
            assert_eq!(buf.use_, 11);
            let slice = core::slice::from_raw_parts(buf.content, 11);
            assert_eq!(slice, b"Hello World");

            xmlFreeImpl(buf.content as *mut c_void);
        }
    }

    // ── ABI export functions ───────────────────────────────────────────────

    #[test]
    fn test_xml_parse_char_encoding() {
        let name = c"UTF-8".as_ptr() as *const c_char;
        assert_eq!(
            xmlParseCharEncoding(name),
            xmlCharEncoding::XML_CHAR_ENCODING_UTF8 as c_int
        );

        let name = c"ISO-8859-1".as_ptr() as *const c_char;
        assert_eq!(
            xmlParseCharEncoding(name),
            xmlCharEncoding::XML_CHAR_ENCODING_8859_1 as c_int
        );

        assert_eq!(
            xmlParseCharEncoding(ptr::null()),
            xmlCharEncoding::XML_CHAR_ENCODING_NONE as c_int
        );
    }

    /// Verify `xmlNewCharEncodingHandler` and `xmlDelEncodingHandler`
    /// round-trip.
    ///
    /// # Safety
    ///
    /// - `name` is a valid NUL-terminated string; the returned handler is
    ///   non-NULL, its `name` field is a valid NUL-terminated string, and it
    ///   is freed exactly once by `xmlDelEncodingHandler`.
    #[test]
    fn test_xml_new_and_del_encoding_handler() {
        let name = c"TestEnc".as_ptr() as *const c_char;
        let handler = xmlNewCharEncodingHandler(
            name,
            utf8_input_func as xmlCharEncodingInputFunc,
            utf8_output_func as xmlCharEncodingOutputFunc,
        );
        assert!(!handler.is_null());

        unsafe {
            assert!(!(*handler).name.is_null());
            let cstr = CStr::from_ptr((*handler).name);
            assert_eq!(cstr.to_bytes(), b"TestEnc");
        }

        xmlDelEncodingHandler(handler);
    }

    #[test]
    fn test_xml_init_and_cleanup() {
        xmlInitCharEncodingHandlers();

        let name: *const xmlChar = c"UTF-8".as_ptr() as *const xmlChar;
        assert!(!find_encoding_handler(name).is_null());

        xmlCleanupCharEncodingHandlers();
        // After cleanup, handlers should be empty
    }

    // ── Shift_JIS / EUC-JP (encoding_rs-backed, R-000157 slice) ────────────

    /// Drive a legacy func on whole buffers.
    fn call_func(
        func: unsafe extern "C" fn(*mut c_uchar, *mut c_int, *const c_uchar, *mut c_int) -> c_int,
        input: &[u8],
    ) -> (c_int, Vec<u8>, usize) {
        let mut out = vec![0u8; input.len() * 6 + 64];
        let mut outlen = out.len() as c_int;
        let mut inlen = input.len() as c_int;
        let rc = unsafe { func(out.as_mut_ptr(), &mut outlen, input.as_ptr(), &mut inlen) };
        out.truncate(outlen.max(0) as usize);
        (rc, out, inlen.max(0) as usize)
    }

    #[test]
    fn test_shift_jis_output_roundtrip() {
        // ぁ (U+3041 → 0x82 0x9F), 漢 (U+6F22 → 0x8A 0xBF), half-width ｱ
        // (U+FF71 → 0xB1): byte-exact vs the oracle's iconv output.
        let (rc, out, consumed) = call_func(shift_jis_output_func, "ぁ漢ｱ".as_bytes());
        assert!(rc >= 0);
        assert_eq!(out, [0x82, 0x9F, 0x8A, 0xBF, 0xB1]);
        assert_eq!(consumed, "ぁ漢ｱ".len());

        let (rc, back, _) = call_func(shift_jis_input_func, &out);
        assert!(rc >= 0);
        assert_eq!(back, "ぁ漢ｱ".as_bytes());
    }

    #[test]
    fn test_shift_jis_output_unmappable_reports_input_error() {
        // U+1F600 is outside Shift_JIS: the func stops BEFORE it with the
        // -2 input-error convention (char_enc_out substitutes the decimal
        // character reference, exactly like the oracle iconv EILSEQ path).
        let (rc, out, consumed) = call_func(shift_jis_output_func, "A😀B".as_bytes());
        assert_eq!(rc, ENC_INPUT_ERROR);
        assert_eq!(out, b"A");
        assert_eq!(consumed, 1); // *inlen points AT the emoji

        // Whole-buffer conversion through char_enc_out emits the charref and
        // continues: &#128512; (decimal), matching xmlSerializeDecCharRef.
        let handler = find_encoding_handler(c"SHIFT_JIS".as_ptr() as *const xmlChar);
        assert!(!handler.is_null());
        let in_buf = crate::xml::io::buf_create(64);
        let src = "A\u{1F600}B".as_bytes();
        assert!(
            crate::xml::io::buf_add(in_buf, src.as_ptr() as *const xmlChar, src.len() as c_int)
                >= 0
        );
        let out_buf = crate::xml::io::buf_create(64);
        let n = char_enc_out(handler, out_buf, in_buf);
        assert!(n >= 0);
        let bytes =
            unsafe { core::slice::from_raw_parts((*out_buf).content, (*out_buf).use_ as usize) };
        assert_eq!(bytes, b"A&#128512;B");
        crate::xml::io::buf_free(in_buf);
        crate::xml::io::buf_free(out_buf);
    }

    #[test]
    fn test_euc_jp_output_roundtrip() {
        // ぁ (U+3041 → 0xA4 0xA1), 漢 (U+6F22 → 0xB4 0xC1), ｱ (U+FF71 →
        // 0x8E 0xB1) — oracle iconv byte-exact.
        let (rc, out, consumed) = call_func(euc_jp_output_func, "ぁ漢ｱ".as_bytes());
        assert!(rc >= 0);
        assert_eq!(out, [0xA4, 0xA1, 0xB4, 0xC1, 0x8E, 0xB1]);
        assert_eq!(consumed, "ぁ漢ｱ".len());

        let (rc, back, _) = call_func(euc_jp_input_func, &out);
        assert!(rc >= 0);
        assert_eq!(back, "ぁ漢ｱ".as_bytes());
    }

    #[test]
    fn test_east_asian_handlers_registered_and_findable() {
        for name in [
            c"SHIFT_JIS".as_ptr(),
            c"Shift_JIS".as_ptr(),
            c"SJIS".as_ptr(),
            c"CP932".as_ptr(),
            c"EUC-JP".as_ptr(),
            c"euc-jp".as_ptr(),
        ] {
            assert!(
                !find_encoding_handler(name as *const xmlChar).is_null(),
                "handler not found for {name:?}"
            );
        }
    }

    #[test]
    fn test_shift_jis_output_invalid_utf8_errors() {
        let (rc, out, consumed) = call_func(shift_jis_output_func, b"A\xFFB");
        assert_eq!(rc, -1);
        assert_eq!(out, b"A");
        assert_eq!(consumed, 1);
    }
}