noyalib/

ser.rs

//! YAML serialization.

// SPDX-License-Identifier: MIT OR Apache-2.0
// Copyright (c) 2026 Noyalib. All rights reserved.

use crate::prelude::*;
use core::fmt::Write as _;

use crate::error::{Error, Result};
use crate::value::{Mapping, Number, Sequence, Tag, TaggedValue, Value};

/// Flow style preference for collections.
///
/// Controls whether sequences and mappings should use inline (flow) or
/// multi-line (block) style.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum FlowStyle {
    /// Always use block style (multi-line).
    #[default]
    Block,
    /// Always use flow style (inline, JSON-like).
    Flow,
    /// Automatic: use flow for small collections, block for larger ones.
    Auto,
}

/// Scalar style preference for strings.
///
/// Controls how string values should be quoted.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum ScalarStyle {
    /// Automatic quoting based on content.
    #[default]
    Auto,
    /// Always use double quotes.
    DoubleQuoted,
    /// Always use single quotes.
    SingleQuoted,
    /// Use literal block style (|) for multiline.
    Literal,
    /// Use folded block style (>) for multiline.
    Folded,
    /// Plain (unquoted) style when possible.
    Plain,
}

/// Configuration options for YAML serialization.
///
/// # Examples
///
/// ```rust
/// use noyalib::{FlowStyle, ScalarStyle, SerializerConfig};
///
/// let config = SerializerConfig::new()
///     .indent(4)
///     .flow_style(FlowStyle::Auto)
///     .scalar_style(ScalarStyle::DoubleQuoted)
///     .document_start(true);
/// ```
#[derive(Debug, Clone, Copy)]
#[non_exhaustive]
pub struct SerializerConfig {
    /// Number of spaces per indentation level (default: 2).
    pub indent: usize,
    /// Whether to include document start marker `---` (default: false).
    pub document_start: bool,
    /// Whether to include document end marker `...` (default: false).
    pub document_end: bool,
    /// Whether to use block style for multiline strings (default: true).
    pub block_scalars: bool,
    /// Minimum number of newlines to trigger block scalar style (default: 1).
    pub block_scalar_threshold: usize,
    /// Flow style preference for collections (default: Block).
    pub flow_style: FlowStyle,
    /// Scalar style preference for strings (default: Auto).
    pub scalar_style: ScalarStyle,
    /// Maximum number of items in a collection to use flow style in Auto mode
    /// (default: 4).
    pub flow_threshold: usize,
    /// Force-quote all string scalars regardless of content (default: false).
    pub quote_all: bool,
    /// Prefer single quotes over double quotes when a string scalar needs
    /// quoting at all (default: false).
    ///
    /// A string that contains a character only double-quoted style can
    /// carry -- a control character, a tab, or any other code point that
    /// needs an escape sequence -- still gets double-quoted regardless of
    /// this setting, since single-quoted style has no escape mechanism
    /// beyond doubling an embedded `'`.
    pub prefer_single_quotes: bool,
    /// Compact list indentation under mapping keys (default: false).
    ///
    /// When `true`, sequence items under a mapping key align with the key
    /// instead of being indented an extra level.
    pub compact_list_indent: bool,
    /// Line width for folded block scalars (default: 80).
    pub folded_wrap_chars: usize,
    /// Minimum string length before block scalar style is considered (default: 80).
    pub min_fold_chars: usize,
    /// Maximum nesting depth allowed during serialization (default: 128).
    pub max_depth: usize,
}

impl Default for SerializerConfig {
    fn default() -> Self {
        Self {
            indent: 2,
            document_start: false,
            document_end: false,
            block_scalars: true,
            block_scalar_threshold: 1,
            flow_style: FlowStyle::Block,
            scalar_style: ScalarStyle::Auto,
            flow_threshold: 4,
            quote_all: false,
            prefer_single_quotes: false,
            compact_list_indent: false,
            folded_wrap_chars: 80,
            min_fold_chars: 80,
            max_depth: 128,
        }
    }
}

impl SerializerConfig {
    /// Create a new configuration with default settings.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the indentation width.
    #[must_use]
    pub fn indent(mut self, spaces: usize) -> Self {
        self.indent = spaces;
        self
    }

    /// Enable or disable document start marker `---`.
    #[must_use]
    pub fn document_start(mut self, enabled: bool) -> Self {
        self.document_start = enabled;
        self
    }

    /// Enable or disable document end marker `...`.
    #[must_use]
    pub fn document_end(mut self, enabled: bool) -> Self {
        self.document_end = enabled;
        self
    }

    /// Enable or disable block scalar style for multiline strings.
    #[must_use]
    pub fn block_scalars(mut self, enabled: bool) -> Self {
        self.block_scalars = enabled;
        self
    }

    /// Set minimum newlines to trigger block scalar style.
    #[must_use]
    pub fn block_scalar_threshold(mut self, count: usize) -> Self {
        self.block_scalar_threshold = count;
        self
    }

    /// Set the flow style preference for collections.
    ///
    /// - `FlowStyle::Block`: Always use multi-line block style
    /// - `FlowStyle::Flow`: Always use inline flow style
    /// - `FlowStyle::Auto`: Use flow for small collections
    #[must_use]
    pub fn flow_style(mut self, style: FlowStyle) -> Self {
        self.flow_style = style;
        self
    }

    /// Set the scalar style preference for strings.
    ///
    /// - `ScalarStyle::Auto`: Quote only when necessary
    /// - `ScalarStyle::DoubleQuoted`: Always use double quotes
    /// - `ScalarStyle::SingleQuoted`: Always use single quotes
    /// - `ScalarStyle::Literal`: Use `|` for multiline
    /// - `ScalarStyle::Folded`: Use `>` for multiline
    /// - `ScalarStyle::Plain`: Unquoted when possible
    #[must_use]
    pub fn scalar_style(mut self, style: ScalarStyle) -> Self {
        self.scalar_style = style;
        self
    }

    /// Set the threshold for automatic flow style.
    ///
    /// Collections with this many or fewer items will use flow style
    /// when `flow_style` is set to `Auto`.
    #[must_use]
    pub fn flow_threshold(mut self, threshold: usize) -> Self {
        self.flow_threshold = threshold;
        self
    }

    /// Force-quote all string scalars regardless of content.
    #[must_use]
    pub fn quote_all(mut self, enabled: bool) -> Self {
        self.quote_all = enabled;
        self
    }

    /// Prefer single quotes over double quotes when a string scalar needs
    /// quoting at all.
    ///
    /// A string that needs a character only double-quoted style can carry
    /// (a control character, a tab, or anything else that needs an escape
    /// sequence) still gets double-quoted regardless of this setting.
    /// Output is unchanged when this is left at its default (`false`).
    #[must_use]
    pub fn prefer_single_quotes(mut self, enabled: bool) -> Self {
        self.prefer_single_quotes = enabled;
        self
    }

    /// Enable compact list indentation under mapping keys.
    ///
    /// When enabled, sequence items align with the key rather than
    /// being indented an extra level.
    #[must_use]
    pub fn compact_list_indent(mut self, enabled: bool) -> Self {
        self.compact_list_indent = enabled;
        self
    }

    /// Set the line width for folded block scalars.
    #[must_use]
    pub fn folded_wrap_chars(mut self, chars: usize) -> Self {
        self.folded_wrap_chars = chars;
        self
    }

    /// Set the minimum string length for block scalar style.
    ///
    /// Strings shorter than this threshold will not use block scalar
    /// (`|` / `>`) style, even if they contain newlines.
    #[must_use]
    pub fn min_fold_chars(mut self, chars: usize) -> Self {
        self.min_fold_chars = chars;
        self
    }

    /// Set the maximum nesting depth for serialization.
    #[must_use]
    pub fn max_depth(mut self, depth: usize) -> Self {
        self.max_depth = depth;
        self
    }
}

/// Serialize a Rust value to a YAML `String`.
///
/// Uses [`SerializerConfig::default`]: 2-space indent, no
/// `---` / `...` markers, block style for collections, auto-style
/// scalars, block scalars enabled.
///
/// # Errors
///
/// Returns [`Error`](crate::Error) when:
///
/// - `Error::Serialize` — `T`'s `Serialize` impl returned an
///   error (custom `serde_core::ser::Error`, non-string mapping key
///   that cannot be coerced, …).
/// - `Error::DepthLimit` — the value graph exceeds
///   `SerializerConfig::max_depth` (default 128). Use
///   [`to_string_with_config`] to raise the cap when serialising
///   a deliberately deep structure.
///
/// `to_string` itself does not perform any I/O and never returns
/// `Error::Io`.
///
/// # Examples
///
/// ```rust
/// #[derive(serde::Serialize)]
/// struct Config {
///     name: String,
///     port: u16,
/// }
///
/// let config = Config {
///     name: "myapp".to_string(),
///     port: 8080,
/// };
///
/// let yaml = noyalib::to_string(&config).unwrap();
/// assert!(yaml.contains("name: myapp"));
/// assert!(yaml.contains("port: 8080"));
/// ```
pub fn to_string<T>(value: &T) -> Result<String>
where
    T: ?Sized + serde_core::Serialize,
{
    let v = to_value(value)?;
    value_to_string(&v, &SerializerConfig::default())
}

/// Serialize a Rust value to a YAML `String` with a custom
/// [`SerializerConfig`].
///
/// # Errors
///
/// Same variant set as [`to_string`]. The active `config`
/// controls which limit-related errors can fire — in particular,
/// raising `max_depth` lets deeper graphs through, lowering it
/// surfaces `Error::DepthLimit` sooner.
///
/// # Examples
///
/// ```rust
/// use noyalib::SerializerConfig;
///
/// #[derive(serde::Serialize)]
/// struct Config {
///     name: String,
///     port: u16,
/// }
///
/// let config = Config {
///     name: "myapp".to_string(),
///     port: 8080,
/// };
///
/// let yaml = noyalib::to_string_with_config(
///     &config,
///     &SerializerConfig::new().indent(4).document_start(true),
/// )
/// .unwrap();
/// assert!(yaml.starts_with("---"));
/// ```
pub fn to_string_with_config<T>(value: &T, config: &SerializerConfig) -> Result<String>
where
    T: ?Sized + serde_core::Serialize,
{
    let v = to_value(value)?;
    value_to_string(&v, config)
}

/// Serialize a Rust value to YAML and write to a
/// [`std::io::Write`] sink.
///
/// Internally serialises to a `String` then writes the bytes to
/// `writer` in a single call.
///
/// # Errors
///
/// - `Error::Io` — the underlying writer returned an I/O error.
/// - All variants documented on [`to_string`].
#[cfg(feature = "std")]
pub fn to_writer<W, T>(writer: W, value: &T) -> Result<()>
where
    W: std::io::Write,
    T: ?Sized + serde_core::Serialize,
{
    to_writer_with_config(writer, value, &SerializerConfig::default())
}

/// Serialize a Rust value to YAML and write to a
/// [`std::io::Write`] sink, using a custom [`SerializerConfig`].
///
/// # Errors
///
/// - `Error::Io` — the underlying writer returned an I/O error.
/// - All variants documented on [`to_string_with_config`].
#[cfg(feature = "std")]
pub fn to_writer_with_config<W, T>(writer: W, value: &T, config: &SerializerConfig) -> Result<()>
where
    W: std::io::Write,
    T: ?Sized + serde_core::Serialize,
{
    let s = to_string_with_config(value, config)?;
    let mut writer = writer;
    writer.write_all(s.as_bytes())?;
    Ok(())
}

/// Serialize a Rust type to a YAML string with automatic anchor/alias emission
/// for shared `Rc` and `Arc` pointers wrapped in `RcAnchor` / `ArcAnchor`.
///
/// During this call, every `RcAnchor` / `ArcAnchor` whose pointer is seen for
/// the first time emits a YAML anchor (`&idNNN`); every subsequent sighting of
/// the same pointer emits an alias (`*idNNN`). This preserves true DAG
/// structure in the emitted document — `Rc::clone` siblings become alias
/// references instead of duplicated subtrees.
///
/// Pointer identity is tracked via a thread-local scratchpad that is installed
/// for the duration of the call and cleared on return. Plain `to_string`
/// behaviour is unaffected.
///
/// # Errors
///
/// Returns an error if the type cannot be serialized to YAML.
///
/// # Examples
///
/// ```rust
/// use noyalib::{to_string_tracking_shared, RcAnchor};
/// use std::rc::Rc;
///
/// let shared: RcAnchor<String> = RcAnchor::from("hello".to_string());
/// let doc = vec![shared.clone(), shared.clone(), shared];
/// let yaml = to_string_tracking_shared(&doc).unwrap();
/// assert!(yaml.contains("&id001"));
/// assert!(yaml.contains("*id001"));
/// ```
#[cfg(feature = "std")]
pub fn to_string_tracking_shared<T>(value: &T) -> Result<String>
where
    T: ?Sized + serde_core::Serialize,
{
    to_string_tracking_shared_with_config(value, &SerializerConfig::default())
}

/// Serialize with automatic anchor/alias emission and a custom configuration.
///
/// See [`to_string_tracking_shared`] for behaviour.
///
/// # Errors
///
/// Returns an error if the type cannot be serialized to YAML.
#[cfg(feature = "std")]
pub fn to_string_tracking_shared_with_config<T>(
    value: &T,
    config: &SerializerConfig,
) -> Result<String>
where
    T: ?Sized + serde_core::Serialize,
{
    let _scope = crate::anchors::shared_tracking::AnchorScope::enter();
    to_string_with_config(value, config)
}

/// Write YAML to a writer with automatic anchor/alias emission for shared
/// `Rc` / `Arc` pointers.
///
/// See [`to_string_tracking_shared`] for behaviour.
///
/// # Errors
///
/// Returns an error if the type cannot be serialized or writing fails.
#[cfg(feature = "std")]
pub fn to_writer_tracking_shared<W, T>(writer: W, value: &T) -> Result<()>
where
    W: std::io::Write,
    T: ?Sized + serde_core::Serialize,
{
    to_writer_tracking_shared_with_config(writer, value, &SerializerConfig::default())
}

/// Write YAML to a writer with automatic anchor/alias emission and a custom
/// configuration.
///
/// See [`to_string_tracking_shared`] for behaviour.
///
/// # Errors
///
/// Returns an error if the type cannot be serialized or writing fails.
#[cfg(feature = "std")]
pub fn to_writer_tracking_shared_with_config<W, T>(
    writer: W,
    value: &T,
    config: &SerializerConfig,
) -> Result<()>
where
    W: std::io::Write,
    T: ?Sized + serde_core::Serialize,
{
    let s = to_string_tracking_shared_with_config(value, config)?;
    let mut writer = writer;
    writer.write_all(s.as_bytes())?;
    Ok(())
}

/// Serialize a Rust value to YAML and write into a [`core::fmt::Write`]
/// sink — the no_std-friendly counterpart to [`to_writer`].
///
/// # Errors
///
/// - `Error::Serialize` — the destination's `write_str` returned
///   `fmt::Error`, propagated through `Error::Serialize`.
/// - All variants documented on [`to_string`].
pub fn to_fmt_writer<W, T>(writer: &mut W, value: &T) -> Result<()>
where
    W: fmt::Write,
    T: ?Sized + serde_core::Serialize,
{
    to_fmt_writer_with_config(writer, value, &SerializerConfig::default())
}

/// Serialize a Rust value to YAML and write into a [`core::fmt::Write`]
/// sink, using a custom [`SerializerConfig`].
///
/// # Errors
///
/// - `Error::Serialize` — the destination's `write_str` returned
///   `fmt::Error`.
/// - All variants documented on [`to_string_with_config`].
pub fn to_fmt_writer_with_config<W, T>(
    writer: &mut W,
    value: &T,
    config: &SerializerConfig,
) -> Result<()>
where
    W: fmt::Write,
    T: ?Sized + serde_core::Serialize,
{
    let s = to_string_with_config(value, config)?;
    writer
        .write_str(&s)
        .map_err(|e| Error::Serialize(e.to_string()))
}

/// Serialize a Rust value into a dynamic [`Value`] tree via the
/// Serde data model.
///
/// Use this when the typed serialise output should land in
/// noyalib's [`Value`] for further programmatic editing
/// (`Value::merge`, `Value::interpolate_properties`, …) before a
/// final emit.
///
/// **Note**: [`TaggedValue`]'s `Serialize` impl (which `Value::Tagged`
/// delegates to) routes through `serialize_map` with a single entry keyed
/// by the tag string — the right shape for interop with a generic
/// serializer that has no YAML-tag concept, `serde_json` and friends
/// included — wrapped in a newtype struct carrying a private marker name.
/// This crate's own [`Serializer`] *does* have a tag concept: it
/// recognises the marker (never the map's shape) when it builds the
/// resulting [`Value`] and reconstructs [`Value::Tagged`], so
/// `to_value`/`to_string` on a `Value` containing `Tagged` round-trips the
/// tag rather than losing it to a degenerate one-entry mapping, while a
/// genuine one-entry mapping keyed by a `!`-string stays a mapping. Refs
/// #350, #377. For direct emission of a `Value` you already hold, without going
/// through the `Serialize` pipeline at all, see [`to_string_value`] /
/// [`to_writer_value`].
///
/// # Errors
///
/// - `Error::Serialize` — `T`'s `Serialize` impl returned an
///   error.
/// - `Error::Custom` — surfaces upstream `serde_core::ser::Error`
///   conversions that don't fit the structured variants.
pub fn to_value<T>(value: &T) -> Result<Value>
where
    T: ?Sized + serde_core::Serialize,
{
    // The public `to_value` / `to_string` family keeps
    // `T: ?Sized + serde_core::Serialize` so callers can serialise structs
    // holding borrowed references. `Value::Tagged`'s tag survives this path
    // via `SerializeMap::end`'s single-entry-map reconstruction (see its
    // doc comment); users who already hold a `Value` and want to skip the
    // `Serialize` pipeline entirely can still call [`to_string_value`] /
    // [`to_string_value_with_config`] / [`to_writer_value`].
    value.serialize(Serializer)
}

/// Serialize a [`Value`] directly to a YAML `String`, preserving
/// [`Value::Tagged`] shape losslessly.
///
/// This function bypasses the `Serialize` pipeline entirely and writes
/// the YAML-tag prefix directly. [`to_string`]/[`to_value`] also preserve
/// `Value::Tagged` when `T` is (or contains) a `Value` — see the note on
/// [`to_value`] — but this one skips the round trip through `Serializer`
/// altogether.
///
/// Use this whenever you hold a `Value` that may contain
/// `Value::Tagged` and want the emitted YAML to round-trip back
/// into an equivalent `Value::Tagged`.
///
/// # Errors
///
/// All variants documented on [`to_string`].
///
/// # Examples
///
/// ```
/// use noyalib::{from_str, to_string_value, Value};
/// let v: Value = from_str("!Color '#ff8800'\n").unwrap();
/// assert!(matches!(v, Value::Tagged(_)));
/// let s = to_string_value(&v).unwrap();
/// // Re-parsing yields an equivalent `Value::Tagged`.
/// let back: Value = from_str(&s).unwrap();
/// assert!(matches!(back, Value::Tagged(_)));
/// ```
pub fn to_string_value(value: &Value) -> Result<String> {
    value_to_string(value, &SerializerConfig::default())
}

/// Serialize a [`Value`] to a YAML `String` with a custom
/// [`SerializerConfig`], preserving [`Value::Tagged`] shape
/// losslessly. See [`to_string_value`] for the rationale.
///
/// # Errors
///
/// All variants documented on [`to_string_with_config`].
pub fn to_string_value_with_config(value: &Value, config: &SerializerConfig) -> Result<String> {
    value_to_string(value, config)
}

/// Write a [`Value`] to an [`std::io::Write`] sink, preserving
/// [`Value::Tagged`] shape losslessly. See [`to_string_value`]
/// for the rationale.
///
/// # Errors
///
/// - `Error::Io` — the underlying writer returned an I/O error.
/// - All variants documented on [`to_string`].
#[cfg(feature = "std")]
pub fn to_writer_value<W>(writer: W, value: &Value) -> Result<()>
where
    W: std::io::Write,
{
    to_writer_value_with_config(writer, value, &SerializerConfig::default())
}

/// Write a [`Value`] to an [`std::io::Write`] sink with a custom
/// [`SerializerConfig`], preserving [`Value::Tagged`] shape
/// losslessly. See [`to_string_value`] for the rationale.
///
/// # Errors
///
/// - `Error::Io` — the underlying writer returned an I/O error.
/// - All variants documented on [`to_string_with_config`].
#[cfg(feature = "std")]
pub fn to_writer_value_with_config<W>(
    writer: W,
    value: &Value,
    config: &SerializerConfig,
) -> Result<()>
where
    W: std::io::Write,
{
    let s = to_string_value_with_config(value, config)?;
    let mut writer = writer;
    writer.write_all(s.as_bytes())?;
    Ok(())
}

fn value_to_string(value: &Value, config: &SerializerConfig) -> Result<String> {
    let mut output = String::with_capacity(estimate_yaml_size(value));
    if config.document_start {
        output.push_str("---\n");
    }
    write_value(&mut output, value, 0, true, &Cx::new(config), 0)?;
    if config.document_end {
        // A block scalar ends its own last line; a second break before
        // `...` would be read as one more kept line under `|+`.
        if !output.ends_with('\n') {
            output.push('\n');
        }
        output.push_str("...");
    }
    Ok(output)
}

fn estimate_yaml_size(value: &Value) -> usize {
    match value {
        Value::Null => 4,
        Value::Bool(_) => 5,
        Value::Number(_) => 12,
        Value::String(s) => s.len() + 4,
        Value::Sequence(seq) => 4 + seq.iter().map(|v| estimate_yaml_size(v) + 4).sum::<usize>(),
        Value::Mapping(map) => {
            4 + map
                .iter()
                .map(|(k, v)| k.len() + estimate_yaml_size(v) + 6)
                .sum::<usize>()
        }
        Value::Tagged(t) => 20 + estimate_yaml_size(t.value()),
    }
}

/// Write `total_spaces` space characters to `output` without heap allocation.
#[inline]
fn write_indent(output: &mut String, total_spaces: usize) {
    const SPACES: &str = "                                                                ";
    // 64 spaces - covers indent up to depth 32 with indent=2
    let mut remaining = total_spaces;
    while remaining > 0 {
        let n = remaining.min(SPACES.len());
        output.push_str(&SPACES[..n]);
        remaining -= n;
    }
}

/// The emitter's context: the caller's configuration, and whether the
/// writer is inside a flow collection. Inside one, every nested
/// collection is written in flow form too (block layout does not parse
/// there), a string never takes a block scalar, and a plain scalar must
/// not contain a flow indicator. Dereferences to the configuration.
#[derive(Debug, Clone, Copy)]
struct Cx<'a> {
    cfg: &'a SerializerConfig,
    in_flow: bool,
}

impl<'a> Cx<'a> {
    fn new(cfg: &'a SerializerConfig) -> Self {
        Self {
            cfg,
            in_flow: false,
        }
    }

    /// The context for the contents of a flow collection.
    fn flow(self) -> Self {
        Self {
            in_flow: true,
            ..self
        }
    }
}

impl core::ops::Deref for Cx<'_> {
    type Target = SerializerConfig;

    fn deref(&self) -> &SerializerConfig {
        self.cfg
    }
}

fn write_value(
    output: &mut String,
    value: &Value,
    indent: usize,
    is_root: bool,
    config: &Cx<'_>,
    depth: usize,
) -> Result<()> {
    if crate::parser::budget::depth_exceeded(depth, config.max_depth) {
        return Err(Error::RecursionLimitExceeded { depth });
    }
    match value {
        Value::Null => output.push_str("null"),
        Value::Bool(b) => output.push_str(if *b { "true" } else { "false" }),
        Value::Number(n) => write_number(output, n),
        Value::String(s) => write_string(output, s, indent, config),
        Value::Sequence(seq) => write_sequence(output, seq, indent, is_root, config, depth)?,
        Value::Mapping(map) => write_mapping(output, map, indent, is_root, config, depth)?,
        // Only the serializer's own wrapper types create a directive
        // (`Tag::directive`); a tag read from a document or built with
        // `Tag::new` is written back as the tag it is, whatever its name.
        Value::Tagged(tagged) if tagged.tag().is_directive() => {
            let tag_str = tagged.tag().as_str();
            write_internal_tag(
                output,
                tag_str,
                tagged.value(),
                indent,
                is_root,
                config,
                depth,
            )?;
        }
        Value::Tagged(tagged) => write_user_tag(output, tagged, indent, config, depth)?,
    }
    Ok(())
}

fn write_number(output: &mut String, n: &Number) {
    match n {
        Number::Integer(n) => {
            #[cfg(feature = "fast-int")]
            {
                let mut buf = itoa::Buffer::new();
                output.push_str(buf.format(*n));
            }
            #[cfg(not(feature = "fast-int"))]
            {
                let _ = write!(output, "{n}");
            }
        }
        #[cfg(feature = "lossless-u64")]
        Number::Unsigned(n) => {
            #[cfg(feature = "fast-int")]
            {
                let mut buf = itoa::Buffer::new();
                output.push_str(buf.format(*n));
            }
            #[cfg(not(feature = "fast-int"))]
            {
                let _ = write!(output, "{n}");
            }
        }
        // Shared with `Number`'s `Display` impl (see #348) so the
        // two never disagree on how a float prints.
        Number::Float(n) => {
            let _ = crate::value::write_float(output, *n);
        }
    }
}

/// Write the tag, then its payload. A scalar payload sits on this same
/// line after a space (`!tag value`); a non-empty mapping/sequence
/// payload starts block layout on the next line instead, with no
/// trailing space after the tag (that space would never be followed by
/// anything, so it would survive only as trailing whitespace). `indent`
/// here is already the slot this caller computed for the *whole* tagged
/// value via `needs_block_layout`/`indicator_takes_a_space` (see
/// `write_mapping`/`write_sequence`), so the payload is written at that
/// same `indent`, not one deeper.
fn write_user_tag(
    output: &mut String,
    tagged: &TaggedValue,
    indent: usize,
    config: &Cx<'_>,
    depth: usize,
) -> Result<()> {
    let tag_str = tagged.tag().as_str();
    let inner = tagged.value();
    // A tag body NO spelling can carry -- a control character (the
    // scanner rejects those in shorthand and verbatim forms alike; a tab
    // is one) or a `>` (verbatim's terminator, rejected in shorthand as
    // a non-URI char) -- resolves the serde-model ambiguity the other
    // way: in the serde data model a tagged value is indistinguishable
    // from the single-entry mapping keyed by its `!`-leading spelling,
    // so emit that mapping with a quoted key and let it re-parse as what
    // it is (found by fuzz_roundtrip on the key `"!\t"`).
    let as_mapping = tag_str.bytes().any(|b| b < 0x20 || b == 0x7f || b == b'>');
    // Inside a flow collection that mapping needs its own braces.
    let braced = as_mapping && config.in_flow;
    if braced {
        output.push('{');
    }
    if as_mapping {
        write_key_string(output, tag_str, indent, config);
        output.push(':');
    } else {
        write_tag_spelling(output, tag_str);
    }
    if indicator_takes_a_space(inner, config) {
        output.push(' ');
    }
    write_value(output, inner, indent, false, config, depth + 1)?;
    if braced {
        output.push('}');
    }
    Ok(())
}

/// Write a tag in the shortest spelling that re-parses to exactly the
/// stored tag.
///
/// A tag whose body holds characters the shorthand spelling cannot
/// carry -- flow indicators, blanks, or an interior `!` (a handle
/// separator there) -- is emitted in the verbatim form `!<...>`, which
/// re-parses to exactly the stored tag (`!<!!str>` is `!!str`). Emitting
/// it raw produced YAML that split at the first such byte:
/// `!<tag:example.com,2026:x>` re-emitted as shorthand died at the comma
/// (found by fuzz_roundtrip).
fn write_tag_spelling(output: &mut String, tag_str: &str) {
    let shorthand_body = tag_str
        .strip_prefix("!!")
        .or_else(|| tag_str.strip_prefix('!'));
    // A body starting with `<` would turn the shorthand into the
    // verbatim opener `!<` itself.
    let needs_verbatim = shorthand_body.is_some_and(|body| {
        body.starts_with('<')
            || body
                .bytes()
                .any(|b| matches!(b, b',' | b'[' | b']' | b'{' | b'}' | b'!' | b' ' | b'\t'))
    });
    match shorthand_body {
        // A tag a `%TAG` directive resolved is held as a bare URI with
        // no `!`. Written as it stands it is not a tag at all, and the
        // document reads back as a plain scalar, so the value is lost.
        // The verbatim form carries it without needing the directive.
        None => {
            output.push_str("!<");
            output.push_str(tag_str);
            output.push('>');
        }
        Some(_) if needs_verbatim => {
            output.push_str("!<");
            output.push_str(tag_str);
            output.push('>');
        }
        Some(_) => output.push_str(tag_str),
    }
}

/// Fast check whether a plain scalar would be interpreted as a number by a YAML
/// parser.  This is intentionally over-inclusive to ensure roundtrip safety —
/// it's cheaper to quote a few extra strings than to lose data.
fn looks_like_number(s: &str) -> bool {
    let bytes = s.as_bytes();
    if bytes.is_empty() {
        return false;
    }

    // YAML special float literals (case variants)
    if matches!(
        s,
        ".inf"
            | ".Inf"
            | ".INF"
            | "+.inf"
            | "+.Inf"
            | "+.INF"
            | "-.inf"
            | "-.Inf"
            | "-.INF"
            | ".nan"
            | ".NaN"
            | ".NAN"
    ) {
        return true;
    }

    // Skip any leading signs (yaml-rust2 is permissive with e.g. "++1")
    let mut i = 0;
    while i < bytes.len() && (bytes[i] == b'+' || bytes[i] == b'-') {
        i += 1;
    }
    if i >= bytes.len() {
        return false;
    }

    let rest = &bytes[i..];

    // A digit, or "." and a digit (floats like .5), can open a number.
    // That is the cheap filter; the parser's own resolver has the last
    // word, so digit-leading text it keeps as a string (`2026-12-31`,
    // `1.2.3`, `3rd`, `1/2`) is written plain, as the author wrote it.
    // The resolver sees the text after the signs: a permissive reader
    // (yaml-rust2 accepts `++1`) may take stacked signs as one, so what
    // follows them decides.
    let candidate =
        rest[0].is_ascii_digit() || (rest[0] == b'.' && rest.len() > 1 && rest[1].is_ascii_digit());
    candidate && resolves_as_non_string(&s[i..])
}

/// The parser's verdict on a plain scalar: would it read back as a
/// number, a boolean, or null rather than a string?
///
/// Runs the resolver the loaders and the streaming path share, with the
/// YAML 1.1 legacy forms enabled (`0`-prefixed octals, sexagesimals) so a
/// string is quoted whenever any reader configuration would turn it into
/// something else.
fn resolves_as_non_string(s: &str) -> bool {
    !matches!(
        crate::streaming::resolve_plain_ext(s, false, true, false, true, true, false),
        crate::streaming::Scalar::Str(_)
    )
}

/// A `:` ends a plain scalar only when a space, a tab, a flow indicator,
/// or the end of the text follows it (YAML 1.2 plain scalars), so
/// `word:count`, `10:00:00Z`, and `http://` stay plain.
fn colon_ends_plain(bytes: &[u8], i: usize) -> bool {
    match bytes.get(i + 1) {
        None => true,
        Some(&next) => matches!(next, b' ' | b'\t' | b',' | b'[' | b']' | b'{' | b'}'),
    }
}

/// A `#` starts a comment only at the start of the text or after
/// whitespace, so `a#b` stays plain.
fn hash_starts_comment(bytes: &[u8], i: usize) -> bool {
    i == 0 || matches!(bytes[i - 1], b' ' | b'\t')
}

/// Lookup table: true if the byte can require the string to be quoted.
/// Covers: control chars (except tab), colon, hash, newline, etc. A colon
/// or a hash is then judged in context by `colon_ends_plain` and
/// `hash_starts_comment`.
static NEEDS_QUOTE_BYTE: [bool; 128] = {
    let mut t = [false; 128];
    // Control characters (except tab 0x09)
    let mut i = 0u8;
    while i < 0x20 {
        if i != b'\t' {
            t[i as usize] = true;
        }
        i += 1;
    }
    // YAML structural characters
    t[b':' as usize] = true;
    t[b'#' as usize] = true;
    t[b'\n' as usize] = true;
    t[b'\r' as usize] = true;
    t[b'\0' as usize] = true;
    t
};

/// Characters that require quoting when they appear as the first character.
static FIRST_CHAR_QUOTE: [bool; 128] = {
    let mut t = [false; 128];
    t[b' ' as usize] = true;
    t[b'-' as usize] = true;
    t[b'&' as usize] = true;
    t[b'*' as usize] = true;
    t[b'!' as usize] = true;
    t[b'|' as usize] = true;
    t[b'>' as usize] = true;
    t[b'%' as usize] = true;
    t[b'@' as usize] = true;
    t[b'`' as usize] = true;
    t[b'{' as usize] = true;
    t[b'}' as usize] = true;
    t[b'[' as usize] = true;
    t[b']' as usize] = true;
    t[b',' as usize] = true;
    t[b'?' as usize] = true;
    t[b'\'' as usize] = true;
    t[b'"' as usize] = true;
    t
};

/// A character only double-quoted style can carry faithfully: CR, NEL
/// (U+0085), LS (U+2028), PS (U+2029) — and a BOM (U+FEFF). A literal
/// block scalar normalises `\r` into the block's own line breaks, and
/// the three Unicode separators pass through plain and single-quoted
/// styles as raw bytes that 1.1-era parsers (and this crate's own
/// reader) fold as line breaks, so a round trip changes the string
/// (#335). A raw BOM is worse: the reader must not accept one inside
/// a document at all (§5.2), and a string-leading BOM emitted plain
/// is stream-skipped on re-parse, reinterpreting the rest of the
/// scalar as markup (found by fuzz_roundtrip).
///
/// The C1 block (U+0080 to U+009F, NEL included) and the non-characters
/// U+FFFE and U+FFFF sit outside `c-printable` (§5.1): this crate's
/// reader takes them raw, but libyaml-based tools reject the document,
/// so they force the same style with a hex escape (#379).
fn needs_double_quoted_escape(s: &str) -> bool {
    s.chars().any(|c| {
        matches!(
            c,
            '\r' | '\u{2028}' | '\u{2029}' | '\u{feff}' | '\u{fffe}' | '\u{ffff}'
        ) || ('\u{7f}'..='\u{9f}').contains(&c)
            || (c < '\u{20}' && c != '\t' && c != '\n')
    })
}

/// Write a mapping key. Keys are implicit (`key: value`) in every
/// form this serializer emits, and an implicit key must fit on one
/// line — the block scalar styles are not grammar there at all — so
/// a string the value writer would render as a `|`/`>` block (any
/// string holding a line break) is written double-quoted with
/// escapes instead. Found by fuzz_roundtrip: a multi-line key
/// emitted as a `|-` block produced YAML that no longer parsed
/// ("expected block mapping key or end").
///
/// A plain `<<` key is the merge key: on reload its value is merged into
/// the mapping instead of kept under the key, so the string `<<` is
/// always quoted as a key.
fn write_key_string(output: &mut String, s: &str, indent: usize, config: &Cx<'_>) {
    if s.contains('\n') {
        write_double_quoted(output, s);
    } else if s == "<<" {
        match quoted_style(s, config.prefer_single_quotes) {
            StrStyle::Single => write_single_quoted(output, s),
            _ => write_double_quoted(output, s),
        }
    } else {
        write_string(output, s, indent, config);
    }
}

/// The style [`write_string`] gives a string scalar.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum StrStyle {
    Plain,
    Single,
    Double,
    Block,
}

fn write_string(output: &mut String, s: &str, indent: usize, config: &Cx<'_>) {
    match string_style(s, config) {
        StrStyle::Plain => output.push_str(s),
        StrStyle::Single => write_single_quoted(output, s),
        StrStyle::Double => write_double_quoted(output, s),
        StrStyle::Block => write_block_scalar(output, s, indent, config),
    }
}

/// Choose the style for a string scalar in the writer's context. Every
/// choice must read back as exactly `s`.
fn string_style(s: &str, config: &Cx<'_>) -> StrStyle {
    // Empty string must be quoted
    if s.is_empty() {
        return if config.prefer_single_quotes {
            StrStyle::Single
        } else {
            StrStyle::Double
        };
    }

    // Force-quote all strings when configured. A scalar starting with
    // `...` emitted at the start of a line reads back as the
    // document-end marker (explicit-key emission places keys at column
    // 0), so it can never go plain either -- same family as the `-`
    // first-byte rule, which already covers `---` (found by
    // fuzz_roundtrip on a `? ...` explicit key). Single-quoted style has
    // no escapes, and a line break inside it folds to a space on
    // re-parse, so a string it cannot carry verbatim falls back to
    // double quotes regardless of the setting.
    if config.quote_all || s.starts_with("...") {
        return quoted_style(s, true);
    }

    // Fast path: short ASCII strings that are clearly safe as plain
    // scalars, in every context (no flow indicator can pass the byte
    // filter). Avoids the full scan for the majority of mapping keys.
    if is_simple_plain(s) {
        return StrStyle::Plain;
    }

    // Block scalar for multiline strings -- unless the string carries a
    // character a block scalar cannot represent: `str::lines` and the
    // block's own line breaks erase a `\r` (#335). A flow collection
    // cannot hold a block scalar at all.
    if config.block_scalars && !config.in_flow && !needs_double_quoted_escape(s) {
        let newlines = s.bytes().filter(|&b| b == b'\n').count();
        if newlines >= config.block_scalar_threshold {
            return StrStyle::Block;
        }
    }

    // CR and the Unicode line separators are representable only with
    // double-quoted escapes (#335).
    if needs_double_quoted_escape(s) {
        return StrStyle::Double;
    }
    if is_plain_safe(s, config.in_flow) {
        return StrStyle::Plain;
    }
    quoted_style(s, config.prefer_single_quotes)
}

/// Single quotes when they are preferred and can carry `s` verbatim,
/// double quotes otherwise. Single quotes cannot carry a control
/// character (a line break folds to a space on re-parse) nor any
/// character only a double-quoted escape spells faithfully.
fn quoted_style(s: &str, prefer_single: bool) -> StrStyle {
    if prefer_single && single_quote_safe(s) && !needs_double_quoted_escape(s) {
        StrStyle::Single
    } else {
        StrStyle::Double
    }
}

/// Short, alnum-bounded, built only from bytes that never need quoting,
/// and not a word or number the resolver would turn into another type.
///
/// The conditions are all ANDed. An earlier version of this guard read
/// `a && b && c && !config.block_scalars || no_newline`, which let
/// *every* newline-free string take the fast path regardless of its
/// first byte (`"-"` slipped through unquoted and re-parsed as a block
/// sequence entry, not a scalar). The alnum bounds already exclude every
/// `FIRST_CHAR_QUOTE` member and tab.
fn is_simple_plain(s: &str) -> bool {
    let bytes = s.as_bytes();
    bytes.len() <= 64
        && bytes.first().is_some_and(u8::is_ascii_alphanumeric)
        && bytes.last().is_some_and(u8::is_ascii_alphanumeric)
        && bytes
            .iter()
            .all(|&b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b'-' | b'.' | b'/'))
        && !is_reserved_word(s)
        && !looks_like_number(s)
}

/// The plain spellings that resolve to a boolean or null.
fn is_reserved_word(s: &str) -> bool {
    matches!(
        s,
        "true" | "false" | "null" | "~" | "True" | "False" | "TRUE" | "FALSE" | "Null" | "NULL"
    )
}

/// A flow indicator: inside `[...]` / `{...}` it ends or nests a
/// collection wherever it appears in a plain scalar (YAML 1.2 §7.3.3,
/// `ns-plain-safe(c)`), not only at the first byte. Shared with the CST
/// editor's plain-scalar check for flow leaves.
pub(crate) fn has_flow_indicator(s: &str) -> bool {
    s.bytes()
        .any(|b| matches!(b, b',' | b'[' | b']' | b'{' | b'}'))
}

/// Whether `s` can be written as a plain scalar and read back unchanged,
/// in block context or (`in_flow`) inside a flow collection, where
/// `[viewer, admin]` written for the one string `viewer, admin` reads
/// back as two items.
fn is_plain_safe(s: &str, in_flow: bool) -> bool {
    let bytes = s.as_bytes();
    let (first, last) = (bytes[0], bytes[bytes.len() - 1]);
    // A leading or trailing tab must quote. `NEEDS_QUOTE_BYTE`
    // deliberately excludes tab so an *interior* tab stays unescaped in
    // a plain scalar, but YAML 1.2 still requires quoting when a plain
    // scalar's content starts or ends in white space (tab included), or
    // the boundary is lost on re-parse. A trailing space likewise.
    if (first < 128 && FIRST_CHAR_QUOTE[first as usize])
        || first == b'\t'
        || matches!(last, b'\t' | b' ')
        || is_reserved_word(s)
        || looks_like_number(s)
        || (in_flow && has_flow_indicator(s))
    {
        return false;
    }
    !(0..bytes.len()).any(|i| byte_forces_quotes(bytes, i))
}

/// Whether the byte at `i` keeps a string from being plain. A colon or a
/// hash counts only where YAML gives it meaning; see `colon_ends_plain`
/// and `hash_starts_comment`.
fn byte_forces_quotes(bytes: &[u8], i: usize) -> bool {
    match bytes[i] {
        b':' => colon_ends_plain(bytes, i),
        b'#' => hash_starts_comment(bytes, i),
        b => b < 128 && NEEDS_QUOTE_BYTE[b as usize],
    }
}

/// Whether `s` can be represented as a YAML single-quoted scalar with no
/// escapes beyond doubling an embedded `'`.
///
/// Single-quoted style has no escape mechanism at all besides doubling the
/// quote character itself — a literal backslash, double quote, `#`, `:`,
/// and so on all pass straight through unescaped. What it *cannot* carry is
/// a control character (tab, newline, carriage return, and the rest of the
/// C0/C1 ranges) or any other non-printable code point: those need one of
/// double-quoted style's escape sequences, so a string containing one must
/// fall back to double-quoted even when `prefer_single_quotes` is set.
fn single_quote_safe(s: &str) -> bool {
    !s.chars()
        .any(|c| c.is_control() || matches!(c, '\u{fffe}' | '\u{ffff}'))
}

/// Write a single-quoted string, escaping embedded single quotes.
fn write_single_quoted(output: &mut String, s: &str) {
    output.push('\'');
    for c in s.chars() {
        if c == '\'' {
            output.push_str("''");
        } else {
            output.push(c);
        }
    }
    output.push('\'');
}

/// Write a double-quoted string with bulk-copy between escape points.
fn write_double_quoted(output: &mut String, s: &str) {
    output.push('"');
    let mut start = 0;
    for (i, c) in s.char_indices() {
        let esc = match c {
            '"' => "\\\"",
            '\\' => "\\\\",
            '\n' => "\\n",
            '\r' => "\\r",
            '\t' => "\\t",
            '\0' => "\\0",
            // Named escapes for the non-ASCII line-break characters
            // (YAML 1.2 section 5.7): emitted raw they read back as
            // line breaks in 1.1-era parsers and in this crate's own
            // reader (#335).
            '\u{0085}' => "\\N",
            '\u{2028}' => "\\L",
            '\u{2029}' => "\\P",
            // A raw BOM must never reach the output stream — the
            // reader rejects one inside a document (§5.2).
            '\u{feff}' => "\\uFEFF",
            // The two non-characters sit outside `c-printable` (§5.1)
            // and have no named escape (#379).
            '\u{fffe}' | '\u{ffff}' => {
                output.push_str(&s[start..i]);
                let _ = write!(output, "\\u{:04X}", c as u32);
                start = i + c.len_utf8();
                continue;
            }
            c if (c as u32) < 0x20 || ('\u{7f}'..='\u{9f}').contains(&c) => {
                // Other control characters -- C0, DEL and the C1 block
                // (#379; NEL is matched above): flush and write the
                // two-digit hex escape. A C1 character is two bytes in
                // UTF-8, so advance by its width, not by one.
                output.push_str(&s[start..i]);
                let _ = write!(output, "\\x{:02X}", c as u32);
                start = i + c.len_utf8();
                continue;
            }
            _ => continue,
        };
        output.push_str(&s[start..i]);
        output.push_str(esc);
        start = i + c.len_utf8();
    }
    output.push_str(&s[start..]);
    output.push('"');
}

/// Write a string using YAML literal block scalar style (|).
/// Write a block scalar's content lines at `indent + 1`.
///
/// An empty line gets **no** indentation. The block's indent is detected from
/// its first non-empty line, so an empty one has nothing to say; writing the
/// indent anyway leaves it standing as trailing whitespace on a line that
/// holds nothing, which `git diff --check` and `yamllint` reject.
///
/// This must stay one function. It had three identical copies — `|` auto, `|`
/// explicit and `>` — and the empty-line rule was missing from all three, so
/// fixing any one of them would have left the other two writing it.
fn write_block_scalar_body(output: &mut String, s: &str, indent: usize, config: &SerializerConfig) {
    for line in s.lines() {
        output.push('\n');
        if !line.is_empty() {
            write_indent(output, config.indent * (indent + 1));
            output.push_str(line);
        }
    }
}

/// The explicit indentation indicator digit(s), if the block needs one.
///
/// YAML 1.2.2 §8.1.1.1: a literal/folded block scalar's indentation is
/// normally *auto-detected* from its first non-empty content line. That
/// detection breaks when the first content line itself starts with a
/// space or a tab — the leading whitespace gets folded into the detected
/// indentation, inflating it past what later, less-indented lines carry,
/// which a parser then rejects as inconsistent indentation. The fix is an
/// explicit indentation indicator between the block style character
/// (`|`/`>`) and the chomping indicator, stating the indentation as a
/// number of columns *beyond the parent node's own indentation*.
///
/// [`write_block_scalar_body`] always places content `config.indent`
/// columns beyond the indentation this function's caller was handed for
/// this value's slot (the parent node's own indentation) — so whenever an
/// indicator is needed, its value is exactly `config.indent`, independent
/// of nesting depth.
fn block_scalar_indent_indicator(s: &str, config: &SerializerConfig) -> String {
    let first_content_line = s.lines().find(|line| !line.is_empty());
    match first_content_line {
        Some(line) if line.starts_with(' ') || line.starts_with('\t') => config.indent.to_string(),
        _ => String::new(),
    }
}

/// The chomping indicator for a block scalar holding `s` (YAML 1.2.2
/// §8.1.1.2): strip when the text has no trailing line break, keep when
/// it has more than one, clip otherwise -- except that a text with **no
/// content line at all** (`"\n"`) also takes keep.
///
/// Clip preserves the final break of the last content line, and a block
/// with no content line has none, so `k: |` followed by one empty line
/// read back as the empty string and the value was lost on the first
/// round trip (#383). Under keep the empty line is the value.
///
/// One function for the three block writers: the rule had three copies
/// and the no-content case was missing from all of them.
fn block_chomping(s: &str) -> &'static str {
    if !s.ends_with('\n') {
        "-"
    } else if s.ends_with("\n\n") || s.lines().all(str::is_empty) {
        "+"
    } else {
        ""
    }
}

/// Begin an entry's line: a line break, unless the output already ends
/// with one, then the indentation.
///
/// A block scalar closes its own last line, so a break written blindly
/// after one opens a blank line. Under clip chomping that was cosmetic;
/// under keep chomping (`|+`) the parser keeps the blank line, and a
/// keep-chomped value grew by one newline per round trip whenever a
/// sibling entry followed it (#385).
fn start_line(output: &mut String, indent_spaces: usize) {
    if !output.ends_with('\n') {
        output.push('\n');
    }
    write_indent(output, indent_spaces);
}

fn write_block_scalar(output: &mut String, s: &str, indent: usize, config: &SerializerConfig) {
    let chomping = block_chomping(s);

    output.push('|');
    output.push_str(&block_scalar_indent_indicator(s, config));
    output.push_str(chomping);

    write_block_scalar_body(output, s, indent, config);

    // `str::lines()` never yields an extra empty element for the string's
    // *final* line terminator, but every other trailing blank line DOES
    // get its own element (and so its own newline from the loop above).
    // That means the body loop always emits exactly one newline fewer
    // than `s` actually ends with, regardless of how many trailing
    // newlines there are: for `"text\n"` the loop emits none after
    // "text" (`.lines()` is just `["text"]`), for `"text\n\n"` it emits
    // one (`["text", ""]`), for `"text\n\n\n"` it emits two
    // (`["text", "", ""]`), and so on -- one behind `s`'s own count every
    // time. So exactly one more newline (never a count derived from `s`)
    // closes the gap.
    //
    // The previous version pushed `s.len() - s.trim_end_matches('\n').len()`
    // newlines here -- the *full* trailing-newline count -- which double
    // counted every trailing newline past the first and grew the string by
    // one extra `\n` on every serialize/parse round trip.
    if s.ends_with('\n') {
        output.push('\n');
    }
}

/// Whether a value can be safely rendered inside an `Auto`-mode flow
/// collection. A flow collection may only contain scalars and other flow
/// collections — a nested *block* collection would produce invalid YAML
/// (`[a, - x]`). So in `Auto` mode the whole subtree must stay within the
/// flow threshold for any ancestor to flow; otherwise we fall back to block.
///
/// `Tagged` values are conservatively treated as block-only: they carry
/// anchors, custom tags, and the internal block-scalar/anchor magic tags that
/// have no valid flow representation here.
fn auto_flow_eligible(value: &Value, config: &Cx<'_>) -> bool {
    match value {
        Value::Sequence(s) => {
            s.len() <= config.flow_threshold && s.iter().all(|v| auto_flow_eligible(v, config))
        }
        Value::Mapping(m) => {
            m.len() <= config.flow_threshold && m.iter().all(|(_, v)| auto_flow_eligible(v, config))
        }
        Value::Tagged(_) => false,
        _ => true,
    }
}

/// Decide whether a collection of `len` items holding `values` should render
/// in flow style under the active `config`.
fn use_flow<'a, I>(len: usize, values: impl Fn() -> I, config: &Cx<'_>) -> bool
where
    I: Iterator<Item = &'a Value>,
{
    if config.in_flow {
        return true;
    }
    match config.flow_style {
        FlowStyle::Block => false,
        FlowStyle::Flow => true,
        FlowStyle::Auto => {
            len <= config.flow_threshold && values().all(|v| auto_flow_eligible(v, config))
        }
    }
}

fn write_sequence(
    output: &mut String,
    seq: &Sequence,
    indent: usize,
    is_root: bool,
    config: &Cx<'_>,
    depth: usize,
) -> Result<()> {
    if seq.is_empty() {
        output.push_str("[]");
        return Ok(());
    }

    if use_flow(seq.len(), || seq.iter(), config) {
        return write_flow_sequence(output, seq, config, depth);
    }

    for (i, value) in seq.iter().enumerate() {
        if i > 0 || !is_root {
            start_line(output, config.indent * indent);
        }
        output.push('-');

        match value {
            Value::Mapping(m) if !m.is_empty() => {
                // The item's first key shares the dash's line, so the dash
                // always takes its space here whatever the *value* looks
                // like — `- key: 1` and `- key:` alike.
                output.push(' ');
                for (j, (k, v)) in m.iter().enumerate() {
                    if j > 0 {
                        start_line(output, config.indent * (indent + 1));
                    }
                    write_key_string(output, k, indent + 1, config);
                    output.push(':');
                    if indicator_takes_a_space(v, config) {
                        output.push(' ');
                    }
                    // `compact_list_indent`: a sequence value starts at its
                    // own key's indentation (`indent + 1`, matching `k`'s
                    // own column) rather than one level deeper — the same
                    // rule `write_mapping` applies, extended to a mapping
                    // that is itself a sequence item. Every other
                    // block-layout value (a mapping, or a sequence with the
                    // option off) still gets the extra level.
                    let next_indent = if needs_block_layout(v, config) {
                        if config.compact_list_indent && matches!(v, Value::Sequence(_)) {
                            indent + 1
                        } else {
                            indent + 2
                        }
                    } else {
                        indent + 1
                    };
                    write_value(output, v, next_indent, false, config, depth + 1)?;
                }
            }
            Value::Sequence(inner) if config.compact_list_indent && !inner.is_empty() => {
                // `compact_list_indent`: a sequence item that is itself a
                // sequence is written inline (`- - a`), with the nested
                // dash sharing this item's own dash's line the same way a
                // nested mapping's first key does above. Continuation
                // elements align with that nested dash (`indent + 1`).
                output.push(' ');
                write_sequence(output, inner, indent + 1, true, config, depth + 1)?;
            }
            _ => {
                if indicator_takes_a_space(value, config) {
                    output.push(' ');
                }
                // A block collection item nests one level under the dash.
                // A scalar item uses the indent for one thing, a block
                // scalar's body, which belongs `config.indent` columns past
                // the dash -- the parent node's indentation the block's
                // indentation indicator counts from -- so it takes this
                // sequence's own level. One level deeper put the body four
                // columns past the dash under a `|2` indicator, and the
                // surplus read back as content (#387).
                let item_indent = if needs_block_layout(value, config) {
                    indent + 1
                } else {
                    indent
                };
                write_value(output, value, item_indent, false, config, depth + 1)?;
            }
        }
    }
    Ok(())
}

/// Whether the indicator introducing `value` — the `:` after a key, or a
/// sequence item's `-` — must be followed by a space.
///
/// An inline scalar needs one (`key: 1`, `- 1`). A block collection does not:
/// it begins on the *next* line, so the space would be left dangling at the
/// end of this one. That is invisible, it re-parses identically, and it is
/// exactly what `git diff --check` and `yamllint`'s `trailing-spaces` reject.
///
/// The exception is an anchor-wrapped block value, which renders as
/// `&idNNN\n  ...`: the `&` is on *this* line, so the space is real
/// separation rather than leftovers. A regular (user) tag is the same
/// story: `!tag\n  ...` also has visible text — the tag name — on this
/// line, so the space is real separation there too.
///
/// [`write_mapping`] has always applied this rule; [`write_sequence`] carried
/// its own copy of the key-writing and did not, which is the whole of the bug
/// this function exists to stop recurring. One rule, one place, both callers.
fn indicator_takes_a_space(value: &Value, config: &Cx<'_>) -> bool {
    !needs_block_layout(value, config)
        || matches!(
            value,
            Value::Tagged(t) if !t.tag().is_directive()
                || t.tag().as_str() == crate::fmt::MAGIC_ANCHOR_DEF
        )
}

/// Whether a value needs block-style layout (indented on the line after `:`)
/// rather than inline scalar layout. Anchor-wrapped block collections must be
/// treated like the inner collection; a regular (user) tag likewise needs
/// block layout exactly when *its* payload does (a tagged mapping/sequence
/// under a key must be indented one level deeper, the same as an untagged
/// one — see [`write_value`]'s `Value::Tagged` arm).
///
/// Every `__noya_` arm below must predict what [`write_internal_tag`] will
/// actually emit for that tag. When the two disagree and the writer emits a
/// block *mapping* while this says inline, the mapping's keys are written at
/// the parent's column and YAML reads them as siblings of the key they were
/// meant to be under — the value silently becomes null and its contents move
/// up a level. `SpaceAfter`/`Commented` around a struct did exactly that
/// until this function learned to look through them.
/// A non-empty collection the writer will lay out in block form, not
/// in flow form (`[...]` / `{...}` on the current line).
fn is_block_collection(v: &Value, config: &Cx<'_>) -> bool {
    match v {
        Value::Mapping(m) => {
            !m.is_empty() && !use_flow(m.len(), || m.iter().map(|(_, v)| v), config)
        }
        Value::Sequence(s) => !s.is_empty() && !use_flow(s.len(), || s.iter(), config),
        _ => false,
    }
}

fn needs_block_layout(v: &Value, config: &Cx<'_>) -> bool {
    let Value::Tagged(t) = v else {
        return is_block_collection(v, config);
    };
    let inner = t.value();
    if !t.tag().is_directive() {
        return needs_block_layout(inner, config);
    }
    match t.tag().as_str() {
        // `[id, inner]` — `&id` goes on the key's line, the inner value
        // lays itself out from there.
        crate::fmt::MAGIC_ANCHOR_DEF => match inner {
            Value::Sequence(seq) if seq.len() == 2 => needs_block_layout(&seq[1], config),
            _ => false,
        },
        // `*id` is always inline.
        crate::fmt::MAGIC_ANCHOR_REF => false,
        // A flow wrapper holding the shape it names emits one line. Holding
        // anything else, the writer falls back to plain output, and the
        // layout has to follow the fallback rather than the wrapper's name.
        crate::fmt::MAGIC_FLOW_SEQ => {
            !matches!(inner, Value::Sequence(_)) && needs_block_layout(inner, config)
        }
        crate::fmt::MAGIC_FLOW_MAP => {
            !matches!(inner, Value::Mapping(_)) && needs_block_layout(inner, config)
        }
        // A block-scalar wrapper around a string writes its own `|`/`>`
        // header; around anything else it falls back the same way.
        crate::fmt::MAGIC_LIT_STR | crate::fmt::MAGIC_FOLD_STR => {
            !matches!(inner, Value::String(_)) && needs_block_layout(inner, config)
        }
        // `[inner, comment]` — the comment is appended to whatever `inner`
        // emits, so the layout is entirely `inner`'s.
        crate::fmt::MAGIC_COMMENTED => match inner {
            Value::Sequence(seq) if seq.len() == 2 => needs_block_layout(&seq[0], config),
            other => needs_block_layout(other, config),
        },
        // A trailing blank line does not change how the value itself lays out.
        crate::fmt::MAGIC_SPACE_AFTER => needs_block_layout(inner, config),
        // Any other directive falls through to plain output.
        _ => needs_block_layout(inner, config),
    }
}

fn write_mapping(
    output: &mut String,
    map: &Mapping,
    indent: usize,
    is_root: bool,
    config: &Cx<'_>,
    depth: usize,
) -> Result<()> {
    if map.is_empty() {
        output.push_str("{}");
        return Ok(());
    }

    if use_flow(map.len(), || map.iter().map(|(_, v)| v), config) {
        return write_flow_mapping(output, map, config, depth);
    }

    for (i, (key, value)) in map.iter().enumerate() {
        if i > 0 || !is_root {
            start_line(output, config.indent * indent);
        }
        write_key_string(output, key, indent, config);

        output.push(':');
        if indicator_takes_a_space(value, config) {
            output.push(' ');
        }
        let next_indent = if needs_block_layout(value, config) {
            // `compact_list_indent`: when on, sequence values
            // under a mapping key align with the key column
            // instead of being bumped one indent level deeper.
            // This is the visual style preferred by some style
            // guides (Kubernetes manifests, GitHub Actions
            // workflows). Mappings and other non-sequence block
            // values keep the standard indent.
            if config.compact_list_indent && matches!(value, Value::Sequence(_)) {
                indent
            } else {
                indent + 1
            }
        } else {
            indent
        };
        write_value(output, value, next_indent, false, config, depth + 1)?;
    }
    Ok(())
}

fn write_internal_tag(
    output: &mut String,
    tag: &str,
    value: &Value,
    indent: usize,
    is_root: bool,
    config: &Cx<'_>,
    depth: usize,
) -> Result<()> {
    match (tag, value) {
        (crate::fmt::MAGIC_FLOW_SEQ, Value::Sequence(seq)) => {
            write_flow_sequence(output, seq, config, depth)
        }
        (crate::fmt::MAGIC_FLOW_MAP, Value::Mapping(map)) => {
            write_flow_mapping(output, map, config, depth)
        }
        // Inside a flow collection a block scalar cannot appear, a
        // comment would swallow the rest of the line, and a blank line
        // has no meaning: the value is written on its own.
        (
            crate::fmt::MAGIC_LIT_STR
            | crate::fmt::MAGIC_FOLD_STR
            | crate::fmt::MAGIC_COMMENTED
            | crate::fmt::MAGIC_SPACE_AFTER,
            _,
        ) if config.in_flow => write_flow_hinted(output, tag, value, config, depth),
        (crate::fmt::MAGIC_LIT_STR, Value::String(s)) => {
            write_literal_block(output, s, indent, config);
            Ok(())
        }
        (crate::fmt::MAGIC_FOLD_STR, Value::String(s)) => {
            write_folded_block(output, s, indent, config);
            Ok(())
        }
        // value is a sequence [inner_value, comment_string]
        (crate::fmt::MAGIC_COMMENTED, Value::Sequence(seq)) if seq.len() == 2 => {
            let start = output.len();
            write_value(output, &seq[0], indent, is_root, config, depth)?;
            if let Value::String(comment) = &seq[1] {
                // A value that spans lines may end inside a block scalar,
                // where `# ...` is content: its comment goes below it.
                let inline = !output[start..].contains('\n');
                write_comment(output, comment, inline, config.indent * indent);
            }
            Ok(())
        }
        (crate::fmt::MAGIC_SPACE_AFTER, _) => {
            write_value(output, value, indent, is_root, config, depth)?;
            output.push('\n');
            // `start_line` opens the next entry with a newline only when the
            // output does not already end in one, so a single `\n` here is
            // absorbed and the blank line never appears. Nested values need a
            // second one to survive that. At the root there is no next entry
            // to separate from, and one `\n` is simply the terminator.
            if !is_root {
                output.push('\n');
            }
            Ok(())
        }
        // value is a sequence [String(id), inner_value]
        (crate::fmt::MAGIC_ANCHOR_DEF, Value::Sequence(seq)) => {
            if let [Value::String(id), inner] = seq.as_slice() {
                write_anchor_def(output, id, inner, indent, config, depth)?;
            }
            Ok(())
        }
        // value is String(id). Emit "*id".
        (crate::fmt::MAGIC_ANCHOR_REF, Value::String(id)) => {
            output.push('*');
            output.push_str(id);
            Ok(())
        }
        (crate::fmt::MAGIC_ANCHOR_DEF | crate::fmt::MAGIC_ANCHOR_REF, _) => Ok(()),
        // A directive holding a shape it does not apply to falls through
        // to regular output.
        _ => write_value(output, value, indent, is_root, config, depth),
    }
}

/// Write `comment` after a value: its first line on the value's line when
/// `inline`, every other line as a `# ` line of its own at `column`.
///
/// Comment text is never written raw. A line break in it (LF, CR, NEL,
/// LS, PS, all of which the reader treats as one) would end the comment
/// and turn the rest into YAML, so `x\nrole: admin` used to add a key; it
/// starts a new comment line instead. A character no YAML stream may
/// carry (other C0/C1 controls, a BOM, U+FFFE/U+FFFF) is replaced with
/// U+FFFD so the document stays loadable. The column only has to sit
/// left of any block scalar body in the value, which a trailing comment
/// line then cleanly ends.
fn write_comment(output: &mut String, comment: &str, inline: bool, column: usize) {
    let is_break = |c: char| matches!(c, '\n' | '\r' | '\u{85}' | '\u{2028}' | '\u{2029}');
    for (i, line) in comment.split(is_break).enumerate() {
        if i == 0 && inline {
            output.push_str(" #");
        } else {
            start_line(output, column);
            output.push('#');
        }
        if !line.is_empty() {
            output.push(' ');
        }
        output.extend(line.chars().map(|c| {
            if needs_double_quoted_escape(&c.to_string()) {
                '\u{fffd}'
            } else {
                c
            }
        }));
    }
}

/// A block-only directive met inside a flow collection: write the value
/// it wraps (for a comment, the first element of `[value, comment]`).
fn write_flow_hinted(
    output: &mut String,
    tag: &str,
    value: &Value,
    config: &Cx<'_>,
    depth: usize,
) -> Result<()> {
    let inner = match (tag, value) {
        (crate::fmt::MAGIC_COMMENTED, Value::Sequence(seq)) if seq.len() == 2 => &seq[0],
        _ => value,
    };
    write_value(output, inner, 0, false, config, depth)
}

/// Emit `&id` before the inner value. For block collections the inner
/// starts on a new line; for scalars it follows on the same line.
fn write_anchor_def(
    output: &mut String,
    id: &str,
    inner: &Value,
    indent: usize,
    config: &Cx<'_>,
    depth: usize,
) -> Result<()> {
    output.push('&');
    output.push_str(id);
    match inner {
        Value::Mapping(m) if is_block_collection(inner, config) => {
            output.push('\n');
            write_indent(output, config.indent * indent);
            // `is_root = true` suppresses the leading newline
            // inside write_mapping so the anchor line and
            // the first key are correctly adjacent.
            write_mapping(output, m, indent, true, config, depth + 1)
        }
        Value::Sequence(s) if is_block_collection(inner, config) => {
            output.push('\n');
            write_indent(output, config.indent * indent);
            write_sequence(output, s, indent, true, config, depth + 1)
        }
        _ => {
            output.push(' ');
            write_value(output, inner, indent, false, config, depth + 1)
        }
    }
}

fn write_flow_sequence(
    output: &mut String,
    seq: &Sequence,
    config: &Cx<'_>,
    depth: usize,
) -> Result<()> {
    let config = &config.flow();
    output.push('[');
    for (i, value) in seq.iter().enumerate() {
        if i > 0 {
            output.push_str(", ");
        }
        write_value(output, value, 0, false, config, depth + 1)?;
    }
    output.push(']');
    Ok(())
}

fn write_flow_mapping(
    output: &mut String,
    map: &Mapping,
    config: &Cx<'_>,
    depth: usize,
) -> Result<()> {
    let config = &config.flow();
    output.push('{');
    for (i, (key, value)) in map.iter().enumerate() {
        if i > 0 {
            output.push_str(", ");
        }
        write_key_string(output, key, 0, config);
        output.push_str(": ");
        write_value(output, value, 0, false, config, depth + 1)?;
    }
    output.push('}');
    Ok(())
}

fn write_literal_block(output: &mut String, s: &str, indent: usize, config: &SerializerConfig) {
    let chomping = block_chomping(s);

    output.push('|');
    output.push_str(&block_scalar_indent_indicator(s, config));
    output.push_str(chomping);

    write_block_scalar_body(output, s, indent, config);
}

fn write_folded_block(output: &mut String, s: &str, indent: usize, config: &SerializerConfig) {
    let chomping = block_chomping(s);

    output.push('>');
    output.push_str(&block_scalar_indent_indicator(s, config));
    output.push_str(chomping);

    write_block_scalar_body(output, s, indent, config);
}

/// Serialize an iterable of values as a multi-document YAML
/// string with `---` document-start markers between each.
///
/// # Errors
///
/// All variants documented on [`to_string`]; the first failing
/// document short-circuits and returns its error — earlier
/// documents are not emitted.
///
/// # Examples
///
/// ```rust
/// let docs = vec![1, 2, 3];
/// let yaml = noyalib::to_string_multi(&docs).unwrap();
/// assert!(yaml.contains("---"));
/// ```
pub fn to_string_multi<T: serde_core::Serialize>(values: &[T]) -> Result<String> {
    to_string_multi_with_config(values, &SerializerConfig::default())
}

/// Serialize an iterable of values as a multi-document YAML
/// string with a custom [`SerializerConfig`].
///
/// # Errors
///
/// All variants documented on [`to_string_with_config`].
pub fn to_string_multi_with_config<T: serde_core::Serialize>(
    values: &[T],
    config: &SerializerConfig,
) -> Result<String> {
    let mut output = String::new();
    for (i, value) in values.iter().enumerate() {
        if i > 0 {
            output.push('\n');
        }
        output.push_str("---\n");
        let v = to_value(value)?;
        write_value(&mut output, &v, 0, true, &Cx::new(config), 0)?;
        output.push('\n');
    }
    Ok(output)
}

/// Serialize multiple values as multi-document YAML to a writer.
///
/// # Errors
///
/// Returns an error if any value cannot be serialized or writing fails.
#[cfg(feature = "std")]
pub fn to_writer_multi<W, T>(writer: W, values: &[T]) -> Result<()>
where
    W: std::io::Write,
    T: serde_core::Serialize,
{
    to_writer_multi_with_config(writer, values, &SerializerConfig::default())
}

/// Serialize multiple values as multi-document YAML to a writer with custom
/// configuration.
///
/// # Errors
///
/// Returns an error if any value cannot be serialized or writing fails.
#[cfg(feature = "std")]
pub fn to_writer_multi_with_config<W, T>(
    writer: W,
    values: &[T],
    config: &SerializerConfig,
) -> Result<()>
where
    W: std::io::Write,
    T: serde_core::Serialize,
{
    let s = to_string_multi_with_config(values, config)?;
    let mut writer = writer;
    writer.write_all(s.as_bytes())?;
    Ok(())
}

/// A YAML serializer.
#[derive(Debug, Copy, Clone)]
pub struct Serializer;

impl serde_core::ser::Serializer for Serializer {
    type Ok = Value;
    type Error = Error;

    type SerializeSeq = SerializeSeq;
    type SerializeTuple = SerializeSeq;
    type SerializeTupleStruct = SerializeSeq;
    type SerializeTupleVariant = SerializeTupleVariant;
    type SerializeMap = SerializeMap;
    type SerializeStruct = SerializeMap;
    type SerializeStructVariant = SerializeStructVariant;

    fn serialize_bool(self, v: bool) -> Result<Value> {
        Ok(Value::Bool(v))
    }

    fn serialize_i8(self, v: i8) -> Result<Value> {
        self.serialize_i64(i64::from(v))
    }

    fn serialize_i16(self, v: i16) -> Result<Value> {
        self.serialize_i64(i64::from(v))
    }

    fn serialize_i32(self, v: i32) -> Result<Value> {
        self.serialize_i64(i64::from(v))
    }

    fn serialize_i64(self, v: i64) -> Result<Value> {
        Ok(Value::Number(Number::Integer(v)))
    }

    fn serialize_u8(self, v: u8) -> Result<Value> {
        self.serialize_i64(i64::from(v))
    }

    fn serialize_u16(self, v: u16) -> Result<Value> {
        self.serialize_i64(i64::from(v))
    }

    fn serialize_u32(self, v: u32) -> Result<Value> {
        self.serialize_i64(i64::from(v))
    }

    fn serialize_u64(self, v: u64) -> Result<Value> {
        if let Ok(v) = i64::try_from(v) {
            return Ok(Value::Number(Number::Integer(v)));
        }
        // Values above `i64::MAX` require the `lossless-u64` feature.
        // Without it the `Number::Unsigned` variant does not exist and
        // there is no lossless representation to fall back to — return
        // an explicit serialise-time error so callers can surface the
        // limit to their users.
        #[cfg(feature = "lossless-u64")]
        {
            Ok(Value::Number(Number::Unsigned(v)))
        }
        #[cfg(not(feature = "lossless-u64"))]
        {
            Err(Error::Serialize(format!(
                "u64 value {v} exceeds i64::MAX and cannot be represented losslessly; \
                 enable the `lossless-u64` Cargo feature to opt in to unsigned integer support"
            )))
        }
    }

    fn serialize_f32(self, v: f32) -> Result<Value> {
        self.serialize_f64(f64::from(v))
    }

    fn serialize_f64(self, v: f64) -> Result<Value> {
        Ok(Value::Number(Number::Float(v)))
    }

    fn serialize_char(self, v: char) -> Result<Value> {
        self.serialize_str(&v.to_string())
    }

    fn serialize_str(self, v: &str) -> Result<Value> {
        Ok(Value::String(v.to_owned()))
    }

    fn serialize_bytes(self, v: &[u8]) -> Result<Value> {
        // YAML 1.2.2 §10.4: byte buffers serialise as a `!!binary`
        // tagged scalar carrying the RFC 4648 base64 encoding of
        // the payload. This is the round-trip partner of the
        // `deserialize_bytes` path that recognises `!!binary` and
        // base64-decodes on demand. Holds for any `serde_bytes`
        // wrapper (`ByteBuf`, `Bytes`) and any `&[u8]` /
        // `Vec<u8>`-shaped target the caller annotates with
        // `#[serde(with = "serde_bytes")]`.
        let encoded = crate::base64::encode(v);
        Ok(Value::Tagged(Box::new(TaggedValue::new(
            Tag::new("!!binary"),
            Value::String(encoded),
        ))))
    }

    fn serialize_none(self) -> Result<Value> {
        Ok(Value::Null)
    }

    fn serialize_some<T>(self, value: &T) -> Result<Value>
    where
        T: ?Sized + serde_core::Serialize,
    {
        value.serialize(self)
    }

    fn serialize_unit(self) -> Result<Value> {
        Ok(Value::Null)
    }

    fn serialize_unit_struct(self, _name: &'static str) -> Result<Value> {
        self.serialize_unit()
    }

    fn serialize_unit_variant(
        self,
        _name: &'static str,
        _variant_index: u32,
        variant: &'static str,
    ) -> Result<Value> {
        self.serialize_str(variant)
    }

    fn serialize_newtype_struct<T>(self, name: &'static str, value: &T) -> Result<Value>
    where
        T: ?Sized + serde_core::Serialize,
    {
        // Intercept formatting hint magic names
        match name {
            crate::fmt::MAGIC_FLOW_SEQ
            | crate::fmt::MAGIC_FLOW_MAP
            | crate::fmt::MAGIC_LIT_STR
            | crate::fmt::MAGIC_FOLD_STR
            | crate::fmt::MAGIC_SPACE_AFTER => {
                let inner = value.serialize(Self)?;
                Ok(Value::Tagged(Box::new(TaggedValue::new(
                    Tag::directive(name),
                    inner,
                ))))
            }
            crate::fmt::MAGIC_COMMENTED => {
                // value is a tuple (inner_value, comment_string)
                let inner = value.serialize(Self)?;
                Ok(Value::Tagged(Box::new(TaggedValue::new(
                    Tag::directive(name),
                    inner,
                ))))
            }
            crate::fmt::MAGIC_ANCHOR_DEF | crate::fmt::MAGIC_ANCHOR_REF => {
                // ANCHOR_DEF: value serializes as Sequence([String(id), inner]).
                // ANCHOR_REF: value serializes as String(id).
                let inner = value.serialize(Self)?;
                Ok(Value::Tagged(Box::new(TaggedValue::new(
                    Tag::directive(name),
                    inner,
                ))))
            }
            crate::fmt::MAGIC_TAGGED => {
                // `TaggedValue::serialize`'s wire form: a single-entry map
                // keyed by the tag string (#350). The marker name, not the
                // map's shape, is what rebuilds `Value::Tagged` here, so a
                // genuine one-entry mapping keyed by a `!`-string reaches
                // `SerializeMap::end` below and stays a mapping (#377).
                match value.serialize(Self)? {
                    Value::Mapping(map) if map.len() == 1 => {
                        let (tag, inner) = map
                            .into_iter()
                            .next()
                            .expect("length checked to be exactly one entry");
                        Ok(Value::Tagged(Box::new(TaggedValue::new(
                            Tag::new(tag),
                            inner,
                        ))))
                    }
                    other => Ok(other),
                }
            }
            _ => value.serialize(self),
        }
    }

    fn serialize_newtype_variant<T>(
        self,
        _name: &'static str,
        _variant_index: u32,
        variant: &'static str,
        value: &T,
    ) -> Result<Value>
    where
        T: ?Sized + serde_core::Serialize,
    {
        let mut map = Mapping::new();
        let _ = map.insert(variant.to_owned(), value.serialize(Self)?);
        Ok(Value::Mapping(map))
    }

    fn serialize_seq(self, len: Option<usize>) -> Result<Self::SerializeSeq> {
        Ok(SerializeSeq {
            vec: Vec::with_capacity(len.unwrap_or(0)),
        })
    }

    fn serialize_tuple(self, len: usize) -> Result<Self::SerializeTuple> {
        self.serialize_seq(Some(len))
    }

    fn serialize_tuple_struct(
        self,
        _name: &'static str,
        len: usize,
    ) -> Result<Self::SerializeTupleStruct> {
        self.serialize_seq(Some(len))
    }

    fn serialize_tuple_variant(
        self,
        _name: &'static str,
        _variant_index: u32,
        variant: &'static str,
        len: usize,
    ) -> Result<Self::SerializeTupleVariant> {
        Ok(SerializeTupleVariant {
            name: variant.to_owned(),
            vec: Vec::with_capacity(len),
        })
    }

    fn serialize_map(self, _len: Option<usize>) -> Result<Self::SerializeMap> {
        Ok(SerializeMap {
            map: Mapping::new(),
            key: None,
        })
    }

    fn serialize_struct(self, _name: &'static str, len: usize) -> Result<Self::SerializeStruct> {
        self.serialize_map(Some(len))
    }

    fn serialize_struct_variant(
        self,
        _name: &'static str,
        _variant_index: u32,
        variant: &'static str,
        _len: usize,
    ) -> Result<Self::SerializeStructVariant> {
        Ok(SerializeStructVariant {
            name: variant.to_owned(),
            map: Mapping::new(),
        })
    }
}

/// Serializer for sequences.
#[derive(Debug)]
pub struct SerializeSeq {
    vec: Vec<Value>,
}

impl serde_core::ser::SerializeSeq for SerializeSeq {
    type Ok = Value;
    type Error = Error;

    fn serialize_element<T>(&mut self, value: &T) -> Result<()>
    where
        T: ?Sized + serde_core::Serialize,
    {
        self.vec.push(value.serialize(Serializer)?);
        Ok(())
    }

    fn end(self) -> Result<Value> {
        Ok(Value::Sequence(self.vec))
    }
}

impl serde_core::ser::SerializeTuple for SerializeSeq {
    type Ok = Value;
    type Error = Error;

    fn serialize_element<T>(&mut self, value: &T) -> Result<()>
    where
        T: ?Sized + serde_core::Serialize,
    {
        serde_core::ser::SerializeSeq::serialize_element(self, value)
    }

    fn end(self) -> Result<Value> {
        serde_core::ser::SerializeSeq::end(self)
    }
}

impl serde_core::ser::SerializeTupleStruct for SerializeSeq {
    type Ok = Value;
    type Error = Error;

    fn serialize_field<T>(&mut self, value: &T) -> Result<()>
    where
        T: ?Sized + serde_core::Serialize,
    {
        serde_core::ser::SerializeSeq::serialize_element(self, value)
    }

    fn end(self) -> Result<Value> {
        serde_core::ser::SerializeSeq::end(self)
    }
}

/// Serializer for tuple variants.
#[derive(Debug)]
pub struct SerializeTupleVariant {
    name: String,
    vec: Vec<Value>,
}

impl serde_core::ser::SerializeTupleVariant for SerializeTupleVariant {
    type Ok = Value;
    type Error = Error;

    fn serialize_field<T>(&mut self, value: &T) -> Result<()>
    where
        T: ?Sized + serde_core::Serialize,
    {
        self.vec.push(value.serialize(Serializer)?);
        Ok(())
    }

    fn end(self) -> Result<Value> {
        let mut map = Mapping::new();
        let _ = map.insert(self.name, Value::Sequence(self.vec));
        Ok(Value::Mapping(map))
    }
}

/// Serializer for maps.
#[derive(Debug)]
pub struct SerializeMap {
    map: Mapping,
    key: Option<String>,
}

impl serde_core::ser::SerializeMap for SerializeMap {
    type Ok = Value;
    type Error = Error;

    fn serialize_key<T>(&mut self, key: &T) -> Result<()>
    where
        T: ?Sized + serde_core::Serialize,
    {
        let key_value = key.serialize(Serializer)?;
        let key_str = match key_value {
            Value::String(s) => s,
            Value::Number(Number::Integer(n)) => n.to_string(),
            #[cfg(feature = "lossless-u64")]
            Value::Number(Number::Unsigned(n)) => n.to_string(),
            Value::Bool(b) => b.to_string(),
            _ => return Err(Error::Serialize("map key must be a string".to_string())),
        };
        self.key = Some(key_str);
        Ok(())
    }

    fn serialize_value<T>(&mut self, value: &T) -> Result<()>
    where
        T: ?Sized + serde_core::Serialize,
    {
        let key = self
            .key
            .take()
            .ok_or_else(|| Error::Serialize("missing key".to_string()))?;
        let _ = self.map.insert(key, value.serialize(Serializer)?);
        Ok(())
    }

    fn end(self) -> Result<Value> {
        Ok(Value::Mapping(self.map))
    }
}

impl serde_core::ser::SerializeStruct for SerializeMap {
    type Ok = Value;
    type Error = Error;

    fn serialize_field<T>(&mut self, key: &'static str, value: &T) -> Result<()>
    where
        T: ?Sized + serde_core::Serialize,
    {
        let _ = self
            .map
            .insert(key.to_owned(), value.serialize(Serializer)?);
        Ok(())
    }

    fn end(self) -> Result<Value> {
        Ok(Value::Mapping(self.map))
    }
}

/// Serializer for struct variants.
#[derive(Debug)]
pub struct SerializeStructVariant {
    name: String,
    map: Mapping,
}

impl serde_core::ser::SerializeStructVariant for SerializeStructVariant {
    type Ok = Value;
    type Error = Error;

    fn serialize_field<T>(&mut self, key: &'static str, value: &T) -> Result<()>
    where
        T: ?Sized + serde_core::Serialize,
    {
        let _ = self
            .map
            .insert(key.to_owned(), value.serialize(Serializer)?);
        Ok(())
    }

    fn end(self) -> Result<Value> {
        let mut map = Mapping::new();
        let _ = map.insert(self.name, Value::Mapping(self.map));
        Ok(Value::Mapping(map))
    }
}

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

    #[test]
    fn test_serialization_recursion_limit() {
        let mut root = Value::Sequence(vec![Value::Null]);
        for _ in 0..200 {
            root = Value::Sequence(vec![root]);
        }

        let config = SerializerConfig::default().max_depth(128);
        let result = to_string_with_config(&root, &config);

        match result {
            Err(Error::RecursionLimitExceeded { depth }) => assert!(depth > 128),
            _ => panic!("Expected RecursionLimitExceeded error, got {result:?}"),
        }
    }

    // Regression for #84: `flow_style` was stored but never consulted by the
    // emit path, so `FlowStyle::Flow` / `Auto` silently produced block output.
    #[test]
    fn test_flow_style_flow_emits_inline_collections() {
        let seq = Value::Sequence(vec![
            Value::from(0),
            Value::from(1),
            Value::from(2),
            Value::from(3),
            Value::from(4),
        ]);
        let mut map = Mapping::new();
        let _ = map.insert("a", Value::from(1));
        let _ = map.insert("b", Value::from(2));
        let _ = map.insert("c", Value::from(3));
        let map = Value::Mapping(map);

        let config = SerializerConfig::new().flow_style(FlowStyle::Flow);
        assert_eq!(
            to_string_with_config(&seq, &config).unwrap().trim_end(),
            "[0, 1, 2, 3, 4]"
        );
        assert_eq!(
            to_string_with_config(&map, &config).unwrap().trim_end(),
            "{a: 1, b: 2, c: 3}"
        );
    }

    #[test]
    fn test_flow_style_auto_respects_threshold() {
        let small = Value::Sequence((0..3).map(Value::from).collect());
        let large = Value::Sequence((0..10).map(Value::from).collect());

        let config = SerializerConfig::new()
            .flow_style(FlowStyle::Auto)
            .flow_threshold(4);

        // Small collection (<= threshold) flows inline.
        assert_eq!(
            to_string_with_config(&small, &config).unwrap().trim_end(),
            "[0, 1, 2]"
        );
        // Large collection (> threshold) stays block.
        assert!(
            to_string_with_config(&large, &config)
                .unwrap()
                .starts_with("- 0")
        );
    }

    #[test]
    fn test_flow_style_auto_falls_back_when_child_exceeds_threshold() {
        // Outer has 2 items (<= threshold) but the inner sequence has 10
        // (> threshold). Flowing the outer would emit an invalid block child
        // inside flow, so Auto must keep the outer in block style.
        let inner = Value::Sequence((0..10).map(Value::from).collect());
        let outer = Value::Sequence(vec![Value::from(0), inner]);

        let config = SerializerConfig::new()
            .flow_style(FlowStyle::Auto)
            .flow_threshold(4);
        let out = to_string_with_config(&outer, &config).unwrap();
        assert!(out.starts_with("- 0"), "outer should stay block: {out:?}");
    }

    #[test]
    fn test_flow_style_block_is_default_unchanged() {
        let seq = Value::Sequence((0..3).map(Value::from).collect());
        // Default config (Block) and the no-config helper both stay block.
        assert!(to_string(&seq).unwrap().starts_with("- 0"));
        assert!(
            to_string_with_config(&seq, &SerializerConfig::new())
                .unwrap()
                .starts_with("- 0")
        );
    }
}