//! JSON value types for C API (data definitions only, no serde_json dependency)

//!

//! The actual parsing/serialization lives in `azul_layout::json` which adds

//! serde_json-based implementations on top of these types.

use alloc::string::String;

use alloc::vec::Vec;

use core::fmt;

use azul_css::{

    AzString, OptionString, OptionF64, OptionBool,

    impl_vec, impl_vec_clone, impl_vec_debug, impl_vec_partialeq, impl_vec_mut,

    impl_result, impl_result_inner,

    impl_option, impl_option_inner,

};

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

// JSON Value Type

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

/// A generic JSON value that can hold any JSON type

#[derive(Debug, Clone, PartialEq)]

#[repr(C)]

pub struct Json {

    /// The type of this JSON value

    pub value_type: JsonType,

    /// Internal storage - interpretation depends on `value_type`

    /// For objects/arrays, this contains serialized data

    pub internal: JsonInternal,

}

/// Internal storage for JSON values.

///

/// This is a C-FFI-compatible tagged-union-via-struct: all fields always exist,

/// but only the field(s) corresponding to `JsonType` in the parent `Json` are

/// meaningful.  For compound types (`Array`, `Object`) the serialized JSON is

/// stored in `string_value` and re-parsed on each access — this trades repeated

/// parsing cost for a flat, FFI-safe layout with no interior pointers.

#[derive(Debug, Clone, PartialEq)]

#[repr(C)]

pub struct JsonInternal {

    /// For strings and serialized objects/arrays

    pub string_value: AzString,

    /// For numbers

    pub number_value: f64,

    /// For booleans

    pub bool_value: bool,

}

/// `Json::null()`. A default that is JSON null, rather than an empty string

/// masquerading as a value.

impl Default for Json {

}

impl Default for JsonInternal {

}

/// Type of a JSON value

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

#[repr(C)]

pub enum JsonType {

    /// JSON null

    Null,

    /// JSON boolean (true/false)

    Bool,

    /// JSON number (stored as f64)

    Number,

    /// JSON string

    String,

    /// JSON array

    Array,

    /// JSON object

    Object,

}

/// Error when parsing JSON

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

#[repr(C)]

pub struct JsonParseError {

    /// Error message

    pub message: AzString,

    /// Line number (if available)

    pub line: u32,

    /// Column number (if available)

    pub column: u32,

}

impl fmt::Display for JsonParseError {

        } else {

        }

}

#[cfg(feature = "std")]

impl std::error::Error for JsonParseError {}

/// A key-value pair in a JSON object

#[derive(Debug, Clone, PartialEq)]

#[repr(C)]

pub struct JsonKeyValue {

    /// The key

    pub key: AzString,

    /// The value

    pub value: Json,

}

impl JsonKeyValue {

    /// Create a new key-value pair

}

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

// FFI-safe collection types

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

/// Option type for JsonKeyValue

impl_option!(JsonKeyValue, OptionJsonKeyValue, copy = false, [Debug, Clone, PartialEq]);

/// Vec of JsonKeyValue (FFI-safe)

impl_vec!(JsonKeyValue, JsonKeyValueVec, JsonKeyValueVecDestructor, JsonKeyValueVecDestructorType, JsonKeyValueVecSlice, OptionJsonKeyValue);

impl_vec_clone!(JsonKeyValue, JsonKeyValueVec, JsonKeyValueVecDestructor);

impl_vec_debug!(JsonKeyValue, JsonKeyValueVec);

impl JsonKeyValueVec {

    /// Creates a new, heap-allocated `JsonKeyValueVec` by copying elements from a C array

    #[inline]

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

}

// FFI-safe JsonVec using impl_vec! macro

impl_vec!(Json, JsonVec, JsonVecDestructor, JsonVecDestructorType, JsonVecSlice, OptionJson);

impl_vec_clone!(Json, JsonVec, JsonVecDestructor);

impl_vec_debug!(Json, JsonVec);

impl_vec_partialeq!(Json, JsonVec);

impl_vec_mut!(Json, JsonVec);

impl JsonVec {

    /// Creates a new, heap-allocated `JsonVec` by copying elements from a C array

    #[inline]

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

}

// FFI-safe Result type for JSON parsing

impl_result!(

    Json,

    JsonParseError,

    ResultJsonJsonParseError,

    copy = false,

    [Debug, Clone, PartialEq]

);

// FFI-safe Option types for JSON

impl_option!(Json, OptionJson, copy = false, [Clone, Debug, PartialEq]);

impl_option!(JsonVec, OptionJsonVec, copy = false, [Clone, Debug]);

impl_option!(JsonKeyValueVec, OptionJsonKeyValueVec, copy = false, [Clone, Debug]);

// FFI-safe Option types for JSON value extraction

// Note: OptionBool and OptionF64 are already exported from azul_css

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

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

// Helpers

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

/// Try to losslessly convert an `f64` to `i64`.

///

/// Returns `Some` only when `n` is an integer that fits in `i64` without

/// overflow.  The upper bound uses `< 2^63` (not `<= i64::MAX as f64`)

/// because `i64::MAX` cannot be represented exactly in `f64` — the cast

/// rounds up to `2^63`, which would cause overflow on `n as i64`.

#[allow(clippy::cast_possible_truncation)] // bounded DPI/dimension/number conversion

    } else {

    }

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

// Non-serde methods on Json (pure data, no parsing)

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

impl Json {

    /// Create a null JSON value

    /// Create a boolean JSON value

    /// Create a number JSON value (floating-point)

    /// Create an integer JSON value.

    ///

    /// **Note:** the value is stored as `f64` internally, so `i64` values with

    /// magnitude greater than 2^53 will lose precision silently.

    #[allow(clippy::cast_precision_loss)] // bounded DPI/dimension/number conversion

    /// Create a string JSON value

    /// Check if this is null

    /// Check if this is a boolean

    /// Check if this is a number

    /// Check if this is a string

    /// Check if this is an array

    /// Check if this is an object

    /// Get as boolean (returns None if not a bool)

        } else {

        }

    /// Get as number (returns None if not a number)

        } else {

        }

    /// Get as integer (returns None if not a number or not an integer)

        } else {

        }

    /// Get as string (returns None if not a string)

        } else {

        }

    /// Get the raw internal string value (for arrays/objects this is the serialized JSON)

}

/// Note: the `Display` output is meant for human-readable / debug display.

/// String values are quoted but **not** JSON-escaped (no backslash escaping

/// of embedded quotes, newlines, etc.).  Use `to_json_string()` (requires

/// the `serde-json` feature) when valid JSON output is needed.

impl fmt::Display for Json {

            JsonType::Number => {

                } else {

                }

            }

            JsonType::Array | JsonType::Object => {

            }

        }

}

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

// serde_json-dependent methods (gated behind "serde-json" feature)

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

#[cfg(feature = "serde-json")]

impl serde::Serialize for Json {

    /// Serialize as the JSON value this represents, not as its repr(C) fields.

    ///

    /// Without this, a struct holding a `Json` field cannot derive

    /// `Serialize` at all — and the obvious workaround, storing the payload

    /// as a `String` of JSON, produces escaped JSON-inside-JSON that every

    /// consumer has to parse twice and nothing validates.

}

#[cfg(feature = "serde-json")]

impl<'de> serde::Deserialize<'de> for Json {

}

#[cfg(feature = "serde-json")]

impl Json {

    /// Parse JSON from a string.

    ///

    /// # Errors

    ///

    /// Returns [`JsonParseError`] (message plus line/column) if `s` is not

    /// well-formed JSON.

    /// Parse JSON from bytes (UTF-8).

    ///

    /// # Errors

    ///

    /// Returns [`JsonParseError`] (message plus line/column) if `bytes` is not

    /// well-formed UTF-8 JSON.

    /// Convert from `serde_json::Value`

            }

            }

        }

    /// Convert this Json to a `serde_json::Value`

    #[must_use]

            JsonType::Number => {

                )

            }

            JsonType::Array | JsonType::Object => {

            }

        }

    /// Create a JSON array from a vector of JSON values

    // By-value is the C-ABI shape: the generated bindings hand ownership in.

    #[allow(clippy::needless_pass_by_value)]

    /// Create a JSON object from key-value pairs

    // By-value is the C-ABI shape: the generated bindings hand ownership in.

    #[allow(clippy::needless_pass_by_value)]

    /// Get the number of elements (for arrays) or keys (for objects)

            JsonType::Array => {

                } else {

                }

            }

            JsonType::Object => {

                } else {

                }

            }

        }

    /// Check if empty (for arrays/objects)

    /// Get array element by index

        } else {

        }

    /// Get object value by key

        } else {

        }

    /// Get all keys of an object

        };

        } else {

        }

    /// Convert array to Vec<Json>

        } else {

        }

    /// Convert object to Vec<JsonKeyValue>

        } else {

        }

    /// Serialize to JSON string (returns `AzString`)

            JsonType::Number => {

                )

            }

            JsonType::String => {

            }

            JsonType::Array | JsonType::Object => {

            }

        }

    /// Serialize to pretty-printed JSON string

            JsonType::Null | JsonType::Bool | JsonType::Number | JsonType::String => {

            }

            JsonType::Array | JsonType::Object => {

                            )

                    )

            }

        }

    /// Access a nested value using a JSON Pointer (RFC 6901).

            JsonType::Null | JsonType::Bool | JsonType::Number | JsonType::String => {

            }

            JsonType::Array | JsonType::Object => {

                };

            }

        }

    /// Access nested values using a JSON Pointer with wildcard support.

            JsonType::Null | JsonType::Bool | JsonType::Number | JsonType::String => {

            }

            JsonType::Array | JsonType::Object => {

                };

            }

        };

    /// Maximum JSON-Pointer component depth for [`jq_all`](Self::jq_all).

    ///

    /// AUDIT 2026-07-08: `jq_all_recursive` recursed once per pointer component,

    /// so an attacker-supplied pointer with tens of thousands of `/` segments

    /// (e.g. `"/a".repeat(100_000)`) overflowed the stack. The single-child

    /// descent is now iterative (unbounded, allocation-free); only the wildcard

    /// (`*`) fan-out still recurses, and that recursion is capped here. 512 is far

    /// deeper than any real document nesting while staying well inside the stack.

    const JQ_MAX_WILDCARD_DEPTH: usize = 512;

    /// Recursive helper for `jq_all` that handles wildcards.

    ///

    /// Non-wildcard components are walked in a loop so a long linear pointer can

    /// never overflow the stack; only `*` fan-out recurses, bounded by

    /// [`JQ_MAX_WILDCARD_DEPTH`](Self::JQ_MAX_WILDCARD_DEPTH).

        // Guard the wildcard recursion; exceeding the cap yields no match rather

        // than crashing.

        // Walk non-wildcard components iteratively.

        loop {

                    }

                    }

                }

            // Single-child descent: advance the cursor instead of recursing.

                }

            };

            }

        }

}

#[cfg(test)]

mod jq_recursion_tests {

    use super::*;

    /// AUDIT 2026-07-08: a pointer with a very large number of components used to

    /// overflow the stack via per-component recursion. Linear (non-wildcard)

    /// descent is now iterative, so an over-long pointer against a shallow

    /// document returns empty promptly with zero recursion instead of a deep call

    /// chain. `serde_json`'s own 128-level parse cap keeps documents shallow, but

    /// this guarantees the jq walk itself never blows the stack on a huge pointer.

    #[test]

    #[cfg(feature = "serde-json")]

    /// A moderately deep linear pointer (within serde's parse limit) resolves to

    /// its single leaf via the iterative descent.

    #[test]

    #[cfg(feature = "serde-json")]

        const DEPTH: usize = 100; // below serde_json's 128-level parse cap

    /// Ordinary wildcard + index access still works after the iterative rewrite.

    #[test]

    #[cfg(feature = "serde-json")]

}

#[cfg(test)]

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

mod autotest_generated {

    use super::*;

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

    // helpers

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

    fn az(s: &str) -> AzString {

        AzString::from(String::from(s))

    }

    /// Build a `Json` by hand, bypassing the constructors. Used to feed the

    /// accessors a *corrupt* value (e.g. `value_type: Array` whose internal

    /// string is not parseable JSON) — reachable over FFI because every field

    /// of `Json` / `JsonInternal` is `pub`.

    fn raw(value_type: JsonType, string_value: &str) -> Json {

        Json {

            value_type,

            internal: JsonInternal {

                string_value: az(string_value),

                number_value: 0.0,

                bool_value: false,

            },

        }

    }

    fn two_pow_63() -> f64 {

        2_f64.powi(63)

    }

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

    // f64_as_i64  (numeric: zero / min_max / negative / overflow / nan_inf)

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

    #[test]

    fn f64_as_i64_zero_and_negative_zero() {

        assert_eq!(f64_as_i64(0.0), Some(0));

        // -0.0 is an integer and in range: the sign is silently dropped.

        assert_eq!(f64_as_i64(-0.0), Some(0));

    }

    #[test]

    fn f64_as_i64_min_max_boundaries() {

        // -2^63 is exactly representable and is exactly i64::MIN.

        assert_eq!(f64_as_i64(-two_pow_63()), Some(i64::MIN));

        // +2^63 is NOT a valid i64 — must be rejected rather than wrapping.

        assert_eq!(f64_as_i64(two_pow_63()), None);

        // i64::MAX rounds *up* to 2^63 when cast to f64, so it is rejected too.

        // This is the documented reason the bound is `< 2^63` and not `<= MAX`.

        #[allow(clippy::cast_precision_loss)]

        let max_as_f64 = i64::MAX as f64;

        assert_eq!(max_as_f64, two_pow_63());

        assert_eq!(f64_as_i64(max_as_f64), None);

        // The largest f64 that is a valid i64: 2^63 - 1024.

        let just_below = two_pow_63() - 1024.0;

        assert_eq!(f64_as_i64(just_below), Some(9_223_372_036_854_774_784));

    }

    #[test]

    fn f64_as_i64_negatives_are_deterministic() {

        assert_eq!(f64_as_i64(-1.0), Some(-1));

        assert_eq!(f64_as_i64(-42.0), Some(-42));

        assert_eq!(f64_as_i64(-0.5), None);

        assert_eq!(f64_as_i64(-1.0 - f64::EPSILON), None);

        // One ULP below -2^63 is out of range.

        assert_eq!(f64_as_i64(-two_pow_63() * (1.0 + f64::EPSILON)), None);

    }

    #[test]

    fn f64_as_i64_overflow_inputs_return_none_not_a_wrapped_cast() {

        for n in [

            1e19_f64,

            1e300_f64,

            -1e300_f64,

            f64::MAX,

            f64::MIN,

            two_pow_63() * 2.0,

        ] {

            assert_eq!(f64_as_i64(n), None, "{n} must not be cast to i64");

        }

    }

    #[test]

    fn f64_as_i64_nan_and_infinity_do_not_panic() {

        // NaN.fract() is NaN, and NaN == 0.0 is false, so all three fall through

        // to `None` without ever reaching the (UB-adjacent) `as i64` cast.

        assert_eq!(f64_as_i64(f64::NAN), None);

        assert_eq!(f64_as_i64(f64::INFINITY), None);

        assert_eq!(f64_as_i64(f64::NEG_INFINITY), None);

    }

    #[test]

    fn f64_as_i64_fractional_and_subnormal_return_none() {

        assert_eq!(f64_as_i64(0.5), None);

        assert_eq!(f64_as_i64(f64::EPSILON), None);

        assert_eq!(f64_as_i64(f64::MIN_POSITIVE), None);

        // Smallest subnormal.

        assert_eq!(f64_as_i64(f64::from_bits(1)), None);

    }

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

    // Json::number / Json::integer  (numeric)

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

    #[test]

    fn number_stores_nan_and_infinity_without_panicking() {

        for n in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {

            let j = Json::number(n);

            assert!(j.is_number());

            assert_eq!(j.as_i64(), OptionI64::None);

            match j.as_number() {

                OptionF64::Some(v) => assert_eq!(v.is_nan(), n.is_nan()),

                OptionF64::None => panic!("as_number() must be Some for a Number"),

            }

            // Display must not panic on non-finite floats.

            let s = alloc::format!("{j}");

            assert!(!s.is_empty());

        }

    }

    #[test]

    fn number_min_max_and_zero() {

        assert_eq!(Json::number(0.0).as_i64(), OptionI64::Some(0));

        assert_eq!(Json::number(-0.0).as_i64(), OptionI64::Some(0));

        assert_eq!(Json::number(f64::MAX).as_number(), OptionF64::Some(f64::MAX));

        assert_eq!(Json::number(f64::MIN).as_number(), OptionF64::Some(f64::MIN));

        // Huge-but-finite values are numbers, but not integers.

        assert_eq!(Json::number(f64::MAX).as_i64(), OptionI64::None);

    }

    #[test]

    fn integer_min_round_trips_but_max_does_not() {

        // i64::MIN == -2^63 is exactly representable in f64.

        assert_eq!(Json::integer(i64::MIN).as_i64(), OptionI64::Some(i64::MIN));

        // i64::MAX is NOT: `value as f64` rounds it up to 2^63, which is out of

        // i64 range, so the value cannot be read back. Documented on the fn as

        // "silent precision loss" for |value| > 2^53.

        assert_eq!(Json::integer(i64::MAX).as_i64(), OptionI64::None);

        assert_eq!(

            Json::integer(i64::MAX).as_number(),

            OptionF64::Some(two_pow_63())

        );

    }

    #[test]

    fn integer_silently_loses_precision_above_2_pow_53() {

        let boundary = 1_i64 << 53; // 9_007_199_254_740_992

        assert_eq!(Json::integer(boundary).as_i64(), OptionI64::Some(boundary));

        // 2^53 + 1 is not representable: it rounds *down* to 2^53.

        assert_eq!(

            Json::integer(boundary + 1).as_i64(),

            OptionI64::Some(boundary)

        );

        assert_eq!(Json::integer(0).as_i64(), OptionI64::Some(0));

        assert_eq!(Json::integer(-1).as_i64(), OptionI64::Some(-1));

    }

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

    // constructors + predicates  (predicate: basic_true_false / edge_inputs)

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

    #[test]

    fn predicates_are_mutually_exclusive_for_every_type() {

        let cases = [

            (Json::null(), JsonType::Null),

            (Json::bool(false), JsonType::Bool),

            (Json::number(f64::NAN), JsonType::Number),

            (Json::integer(0), JsonType::Number),

            (Json::string(""), JsonType::String),

            (raw(JsonType::Array, "[]"), JsonType::Array),

            (raw(JsonType::Object, "{}"), JsonType::Object),

        ];

        for (j, ty) in &cases {

            let flags = [

                j.is_null(),

                j.is_bool(),

                j.is_number(),

                j.is_string(),

                j.is_array(),

                j.is_object(),

            ];

            assert_eq!(

                flags.iter().filter(|b| **b).count(),

                1,

                "exactly one predicate must hold for {ty:?}"

            );

            assert_eq!(j.value_type, *ty);

        }

    }

    #[test]

    fn predicates_on_a_default_internal_do_not_panic() {

        // A hand-rolled Json with a default (empty) payload — the FFI worst case.

        for ty in [

            JsonType::Null,

            JsonType::Bool,

            JsonType::Number,

            JsonType::String,

            JsonType::Array,

            JsonType::Object,

        ] {

            let j = Json {

                value_type: ty,

                internal: JsonInternal::default(),

            };

            assert_eq!(j.is_null(), ty == JsonType::Null);

            assert_eq!(j.is_object(), ty == JsonType::Object);

            assert_eq!(j.raw_string(), "");

        }

    }

    #[test]

    fn bool_constructor_keeps_both_values() {

        assert_eq!(Json::bool(true).as_bool(), OptionBool::Some(true));

        assert_eq!(Json::bool(false).as_bool(), OptionBool::Some(false));

        // The unused payload fields are zeroed, which the derived PartialEq relies on.

        assert_eq!(Json::bool(true).raw_string(), "");

        assert_eq!(Json::bool(true).as_number(), OptionF64::None);

    }

    #[test]

    fn string_constructor_handles_empty_unicode_and_huge_inputs() {

        assert_eq!(Json::string("").as_string(), OptionString::Some(az("")));

        let unicode = "😀 náïve \u{0301}\u{202e}\0 中文";

        assert_eq!(

            Json::string(unicode).as_string(),

            OptionString::Some(az(unicode))

        );

        assert_eq!(Json::string(unicode).raw_string(), unicode);

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

        let j = Json::string(huge.clone());

        assert_eq!(j.raw_string().len(), 1_000_000);

        assert_eq!(j.as_string(), OptionString::Some(AzString::from(huge)));

    }

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

    // getters  (getter: basic_access / edge_access)

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

    #[test]

    fn getters_return_none_on_type_mismatch() {

        let null = Json::null();

        assert_eq!(null.as_bool(), OptionBool::None);

        assert_eq!(null.as_number(), OptionF64::None);

        assert_eq!(null.as_i64(), OptionI64::None);

        assert_eq!(null.as_string(), OptionString::None);

        // A Bool whose *number* payload happens to be set must still not be

        // readable as a number (the tag, not the payload, decides).

        let mut liar = Json::bool(true);

        liar.internal.number_value = 7.0;

        liar.internal.string_value = az("7");

        assert_eq!(liar.as_number(), OptionF64::None);

        assert_eq!(liar.as_i64(), OptionI64::None);

        assert_eq!(liar.as_string(), OptionString::None);

        assert_eq!(liar.as_bool(), OptionBool::Some(true));

        // ...but raw_string() is the *unchecked* accessor and does hand it back.

        assert_eq!(liar.raw_string(), "7");

    }

    #[test]

    fn raw_string_is_empty_for_scalars_and_serialized_for_containers() {

        assert_eq!(Json::null().raw_string(), "");

        assert_eq!(Json::bool(true).raw_string(), "");

        assert_eq!(Json::number(1.5).raw_string(), "");

        assert_eq!(Json::string("hi").raw_string(), "hi");

        assert_eq!(raw(JsonType::Array, "[1,2]").raw_string(), "[1,2]");

        // Corrupt payloads are handed back verbatim, never panic.

        assert_eq!(raw(JsonType::Object, "{not json").raw_string(), "{not json");

    }

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

    // Display for Json  (round_trip / serializer)

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

    #[test]

    fn display_scalar_values() {

        assert_eq!(alloc::format!("{}", Json::null()), "null");

        assert_eq!(alloc::format!("{}", Json::bool(true)), "true");

        assert_eq!(alloc::format!("{}", Json::bool(false)), "false");

        // Integral floats print without a fractional part (via f64_as_i64).

        assert_eq!(alloc::format!("{}", Json::number(3.0)), "3");

        assert_eq!(alloc::format!("{}", Json::integer(-42)), "-42");

        assert_eq!(alloc::format!("{}", Json::number(1.5)), "1.5");

        assert_eq!(alloc::format!("{}", Json::string("x")), "\"x\"");

    }

    #[test]

    fn display_of_non_finite_numbers_is_not_json() {

        // Characterization: Display is documented as human-readable, NOT JSON.

        assert_eq!(alloc::format!("{}", Json::number(f64::NAN)), "NaN");

        assert_eq!(alloc::format!("{}", Json::number(f64::INFINITY)), "inf");

        assert_eq!(alloc::format!("{}", Json::number(f64::NEG_INFINITY)), "-inf");

        // -0.0 loses its sign because f64_as_i64(-0.0) == Some(0).

        assert_eq!(alloc::format!("{}", Json::number(-0.0)), "0");

    }

    #[test]

    fn display_does_not_escape_strings() {

        // Documented caveat on the Display impl: embedded quotes/newlines are

        // NOT escaped, so the output is deliberately not valid JSON.

        let j = Json::string("a\"b\nc");

        assert_eq!(alloc::format!("{j}"), "\"a\"b\nc\"");

    }

    #[test]

    fn display_of_container_emits_the_raw_payload_even_when_corrupt() {

        assert_eq!(

            alloc::format!("{}", raw(JsonType::Array, "[1, 2]")),

            "[1, 2]"

        );

        assert_eq!(

            alloc::format!("{}", raw(JsonType::Object, "<<garbage>>")),

            "<<garbage>>"

        );

        assert_eq!(alloc::format!("{}", raw(JsonType::Array, "")), "");

    }

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

    // JsonParseError::fmt  (serializer)

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

    #[test]

    fn parse_error_display_with_and_without_position() {

        let with_pos = JsonParseError {

            message: az("expected value"),

            line: 3,

            column: 7,

        };

        assert_eq!(alloc::format!("{with_pos}"), "3:7: expected value");

        let no_pos = JsonParseError {

            message: az("expected value"),

            line: 0,

            column: 99,

        };

        assert_eq!(alloc::format!("{no_pos}"), "expected value");

    }

    #[test]

    fn parse_error_display_edge_values_do_not_panic() {

        let empty = JsonParseError {

            message: az(""),

            line: 0,

            column: 0,

        };

        assert_eq!(alloc::format!("{empty}"), "");

        let maxed = JsonParseError {

            message: az("😀"),

            line: u32::MAX,

            column: u32::MAX,

        };

        assert_eq!(

            alloc::format!("{maxed}"),

            alloc::format!("{}:{}: 😀", u32::MAX, u32::MAX)

        );

    }

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

    // JsonKeyValue::create  (other: no_panic_smoke)

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

    #[test]

    fn key_value_create_preserves_key_and_value() {

        let kv = JsonKeyValue::create(az(""), Json::null());

        assert_eq!(kv.key.as_str(), "");

        assert!(kv.value.is_null());

        let big_key = "k".repeat(100_000);

        let kv = JsonKeyValue::create(

            AzString::from(big_key.clone()),

            Json::number(f64::NEG_INFINITY),

        );

        assert_eq!(kv.key.as_str().len(), big_key.len());

        assert!(kv.value.is_number());

        let kv = JsonKeyValue::create(az("😀/\u{0}"), Json::string("v"));

        assert_eq!(kv.key.as_str(), "😀/\u{0}");

        assert_eq!(kv.value.as_string(), OptionString::Some(az("v")));

    }

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

    // copy_from_array  (numeric: zero / min_max / overflow)

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

    #[test]

    fn json_vec_copy_from_array_null_ptr_is_empty_even_at_usize_max_len() {

        // The null check runs first, so a bogus (null, huge) pair from C must

        // yield an empty vec rather than constructing a wild slice.

        let v = JsonVec::copy_from_array(core::ptr::null(), 0);

        assert!(v.is_empty());

        let v = JsonVec::copy_from_array(core::ptr::null(), usize::MAX);

        assert!(v.is_empty());

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

    }

    #[test]

    fn json_vec_copy_from_array_zero_len_with_valid_ptr_is_empty() {

        let items = [Json::null(), Json::bool(true)];

        let v = JsonVec::copy_from_array(items.as_ptr(), 0);

        assert!(v.is_empty());

    }

    #[test]

    fn json_vec_copy_from_array_deep_copies_the_elements() {

        let items = vec![

            Json::null(),

            Json::bool(true),

            Json::number(f64::NAN),

            Json::string("😀"),

        ];

        let v = JsonVec::copy_from_array(items.as_ptr(), items.len());

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

        assert_eq!(v.as_slice()[3].as_string(), OptionString::Some(az("😀")));

        // The copy is independent: dropping the source must not invalidate it.

        drop(items);

        assert!(v.as_slice()[0].is_null());

        assert_eq!(v.as_slice()[1].as_bool(), OptionBool::Some(true));

        assert_eq!(v.as_slice()[3].raw_string(), "😀");

    }

    #[test]

    fn key_value_vec_copy_from_array_null_ptr_is_empty_even_at_usize_max_len() {

        let v = JsonKeyValueVec::copy_from_array(core::ptr::null(), 0);

        assert!(v.is_empty());

        let v = JsonKeyValueVec::copy_from_array(core::ptr::null(), usize::MAX);

        assert!(v.is_empty());

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

    }

    #[test]

    fn key_value_vec_copy_from_array_deep_copies_the_elements() {

        let items = vec![

            JsonKeyValue::create(az("a"), Json::integer(1)),

            JsonKeyValue::create(az(""), Json::null()),

        ];

        let v = JsonKeyValueVec::copy_from_array(items.as_ptr(), items.len());

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

        let zero_len = JsonKeyValueVec::copy_from_array(items.as_ptr(), 0);

        assert!(zero_len.is_empty());

        drop(items);

        assert_eq!(v.as_slice()[0].key.as_str(), "a");

        assert_eq!(v.as_slice()[0].value.as_i64(), OptionI64::Some(1));

        assert_eq!(v.as_slice()[1].key.as_str(), "");

    }

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

    // Json::parse / parse_bytes — malformed input

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

    #[test]

    #[cfg(feature = "serde-json")]

    fn parse_empty_and_whitespace_only_input_is_an_error() {

        for s in ["", " ", "   ", "\t\n\r", "\u{feff}"] {

            let err = Json::parse(s).expect_err("empty/blank input must not parse");

            assert!(!err.message.as_str().is_empty());

            assert!(Json::parse_bytes(s.as_bytes()).is_err());

        }

        assert!(Json::parse_bytes(b"").is_err());

    }

    #[test]

    #[cfg(feature = "serde-json")]

    fn parse_garbage_returns_err_and_never_panics() {

        for s in [

            "{", "}", "[", "]", ",", ":", "nul", "tru", "'a'", "{,}", "[,]", "{\"a\"}", "{\"a\":}",

            "[1,]", "{\"a\":1,}", "\"unterminated", "\\", "\u{0}", "01", "+1", ".5", "1.", "-",

            "0x10", "--1", "1e", "{'a':1}", "undefined",

        ] {

            assert!(Json::parse(s).is_err(), "{s:?} must be rejected");

            assert!(Json::parse_bytes(s.as_bytes()).is_err(), "{s:?} (bytes)");

        }

    }

    #[test]

    #[cfg(feature = "serde-json")]

    fn parse_leading_and_trailing_junk() {

        // Surrounding whitespace is allowed and trimmed...

        assert_eq!(Json::parse("  1  ").expect("padded"), Json::integer(1));

        assert_eq!(Json::parse("\n\t{}\r\n").expect("padded"), Json::parse("{}").expect("{}"));

        // ...but trailing non-whitespace is not.

        for s in ["1;garbage", "{} {}", "null null", "1 2", "[1] x"] {

            assert!(Json::parse(s).is_err(), "{s:?} must be rejected");

        }

    }

    #[test]

    #[cfg(feature = "serde-json")]

    fn parse_bytes_rejects_invalid_utf8_without_panicking() {

        assert!(Json::parse_bytes(&[0xFF, 0xFE, 0x00]).is_err());

        // Structurally valid JSON, but the string body is not UTF-8.

        assert!(Json::parse_bytes(&[b'"', 0xFF, b'"']).is_err());

        // Lone continuation byte inside an otherwise fine document.

        assert!(Json::parse_bytes(&[b'[', 0x80, b']']).is_err());

    }