mpeg-pes 0.6.0

//! PES packet header parsing (ISO/IEC 13818-1 §2.4.3.6, Table 2-21).

use crate::PACKET_START_CODE_PREFIX;
use crate::error::{Error, Result};
use crate::stream_id::StreamId;
use crate::timestamp::{self, Dts, Pts};

const MIN_LEN: usize = 6; // start_code(3) + stream_id(1) + PES_packet_length(2)
const HEADER_FIXED: usize = 3; // 2 flag bytes + PES_header_data_length

// ── PES header flag bits (ISO/IEC 13818-1 §2.4.3.7, Table 2-21) ──────────────
// First flag byte (`'10' | PES_scrambling_control(2) | PES_priority |
// data_alignment_indicator | copyright | original_or_copy`).
const F1_PRIORITY: u8 = 0x08;
const F1_DATA_ALIGNMENT: u8 = 0x04;
const F1_COPYRIGHT: u8 = 0x02;
const F1_ORIGINAL_OR_COPY: u8 = 0x01;
// Second flag byte (`PTS_DTS_flags(2) | ESCR | ES_rate | DSM_trick_mode |
// additional_copy_info | PES_CRC | PES_extension`).
const F2_ESCR: u8 = 0x20;
const F2_ES_RATE: u8 = 0x10;
const F2_DSM_TRICK_MODE: u8 = 0x08;
const F2_ADDITIONAL_COPY_INFO: u8 = 0x04;
const F2_PES_CRC: u8 = 0x02;
const F2_PES_EXTENSION: u8 = 0x01;
// PES_extension flag byte (`PES_private_data | pack_header_field |
// program_packet_sequence_counter | P-STD_buffer | reserved(3) |
// PES_extension_flag_2`).
const EXT_PES_PRIVATE_DATA: u8 = 0x80;
const EXT_PACK_HEADER: u8 = 0x40;
const EXT_PROGRAM_PACKET_SEQUENCE_COUNTER: u8 = 0x20;
const EXT_P_STD_BUFFER: u8 = 0x10;
const EXT_FLAG_2: u8 = 0x01;
/// The 3 `reserved` bits between `P-STD_buffer_flag` and `PES_extension_flag_2`.
const EXT_RESERVED_MASK: u8 = 0x0E;
const EXT_RESERVED_SHIFT: u32 = 1;
/// Spec-convention value of those reserved bits (`'111'`).
const EXT_RESERVED_VALUE: u8 = 0x07;

/// Table 2-21: `marker_bit` / `stream_id_extension_flag` is the MSB of the
/// byte; the remaining 7 bits carry the length / extension value.
const MSB_FLAG: u8 = 0x80;
/// The two fixed `'10'` marker bits at the top of the first PES header flag
/// byte (Table 2-21).
const F1_MARKER_MASK: u8 = 0xC0;
const F1_MARKER_VALUE: u8 = 0x80;
/// `ES_rate` is `marker_bit(1) | ES_rate(22) | marker_bit(1)`; both markers
/// are `1` per Table 2-21.
const ES_RATE_MARKERS_VALUE: u8 = 0b11;
const ES_RATE_LEADING_MARKER: u8 = 0x80;
const ES_RATE_TRAILING_MARKER: u8 = 0x01;
/// Mask of those low 7 bits (`PES_extension_field_length`, `stream_id_extension`).
const LOW7_MASK: u8 = 0x7F;

// ── ESCR (ISO/IEC 13818-1 §2.4.3.7 Table 2-21) ──────────────────────────────

/// Elementary Stream Clock Reference: 33-bit base (90 kHz) + 9-bit extension
/// (27 MHz) — ISO/IEC 13818-1 §2.4.3.7, Table 2-21.
///
/// Wire layout (6 bytes, 48 bits):
/// `2×reserved(1) | ESCR_base[32:30](3) | marker(1) | ESCR_base[29:15](15) |
///  marker(1) | ESCR_base[14:0](15) | marker(1) | ESCR_ext(9) | marker(1)`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Escr {
    /// 33-bit base (90 kHz units).
    pub base: u64,
    /// 9-bit extension (27 MHz units, 0..=299).
    pub extension: u16,
    /// The leading `reserved(2)` of the field (Table 2-21; spec convention
    /// `0b11`), kept so a real stream's value round-trips. Held here, in the
    /// struct's padding, rather than in `PesHeader` so the header does not grow
    /// (the PS demuxer's allocation budget counts its size).
    pub reserved: u8,
}

/// Spec-convention value of the freeze-frame `reserved(3)` bits (all ones,
/// ISO/IEC 13818-1 "reserved" convention; Table 2-24).
pub const FREEZE_FRAME_RESERVED_VALUE: u8 = 0b111;
/// `marker_bit` of the `additional_copy_info` byte (bit 7, Table 2-21).
const ADDITIONAL_COPY_INFO_MARKER: u8 = 0x80;
/// Spec-convention value of the ESCR leading `reserved(2)` (`0b11`).
const ESCR_RESERVED_VALUE: u8 = 0b11;
/// Bit position of the ESCR leading `reserved(2)` in the field's first byte.
const ESCR_RESERVED_SHIFT: u32 = 6;

/// ESCR 33-bit base mask (ISO/IEC 13818-1 §2.4.3.7 `ESCR_base`).
const ESCR_BASE_MASK: u64 = (1 << 33) - 1;
/// ESCR 9-bit extension mask (`ESCR_extension`).
const ESCR_EXT_MASK: u16 = (1 << 9) - 1;
/// ESCR `marker_bit` that sits in bit 2 of bytes 0, 2 and 4.
const ESCR_MARKER_MID: u8 = 0x04;
/// ESCR trailing `marker_bit` (bit 0 of byte 5).
const ESCR_MARKER_LAST: u8 = 0x01;

impl Escr {
    /// Full ESCR value on the 27 MHz clock: `base * 300 + extension`.
    #[must_use]
    pub fn as_27mhz(self) -> u64 {
        broadcast_common::clock33::pcr_from_parts(self.base, self.extension)
    }

    /// Construct from an absolute 27 MHz clock value.
    #[must_use]
    pub fn from_27mhz(ticks: u64) -> Self {
        let (base, extension) = broadcast_common::clock33::pcr_split(ticks);
        Self {
            base,
            extension,
            reserved: ESCR_RESERVED_VALUE,
        }
    }

    /// Decode from the 6-byte ESCR field.
    ///
    /// Bit layout (ISO/IEC 13818-1 §2.4.3.7, Table 2-21):
    /// `B0[7:6]`=reserved, `B0[5:3]`=`base[32:30]`, `B0[2]`=marker,
    /// `B0[1:0]`=`base[29:28]`, `B1[7:0]`=`base[27:20]`,
    /// `B2[7:3]`=`base[19:15]`, `B2[2]`=marker, `B2[1:0]`=`base[14:13]`,
    /// `B3[7:0]`=`base[12:5]`,
    /// `B4[7:3]`=`base[4:0]`, `B4[2]`=marker, `B4[1:0]`=`ext[8:7]`,
    /// `B5[7:1]`=`ext[6:0]`, `B5[0]`=marker.
    pub fn from_field_bytes(b: &[u8; 6]) -> Result<Self> {
        let base = ((((b[0] >> 3) & 0x07) as u64) << 30)   // base[32:30]
            | (((b[0] & 0x03) as u64) << 28)                 // base[29:28]
            | ((b[1] as u64) << 20)                           // base[27:20]
            | ((((b[2] >> 3) & 0x1F) as u64) << 15)          // base[19:15]
            | (((b[2] & 0x03) as u64) << 13)                  // base[14:13]
            | ((b[3] as u64) << 5)                             // base[12:5]
            | (((b[4] >> 3) & 0x1F) as u64); // base[4:0]
        let extension = ((((b[4] & 0x03) as u16) << 7) | ((b[5] >> 1) as u16)) & ESCR_EXT_MASK;
        Ok(Self {
            base,
            extension,
            reserved: b[0] >> ESCR_RESERVED_SHIFT,
        })
    }

    /// Encode as the 6-byte ESCR field.
    ///
    /// Reserved bits are set to `1` per the spec convention.
    /// Exact inverse of [`from_field_bytes`](Self::from_field_bytes).
    #[must_use]
    pub fn to_field_bytes(self) -> [u8; 6] {
        let b = self.base & ESCR_BASE_MASK;
        let e = (self.extension & ESCR_EXT_MASK) as u64;
        [
            // B0: reserved(2)='11' | base[32:30](3) | marker(1)='1' | base[29:28](2)
            ((self.reserved & ESCR_RESERVED_VALUE) << ESCR_RESERVED_SHIFT)
                | (((b >> 30) & 0x07) as u8) << 3
                | ESCR_MARKER_MID
                | ((b >> 28) & 0x03) as u8,
            // B1: base[27:20](8)
            ((b >> 20) & 0xFF) as u8,
            // B2: base[19:15](5) | marker(1)='1' | base[14:13](2)
            (((b >> 15) & 0x1F) as u8) << 3 | ESCR_MARKER_MID | ((b >> 13) & 0x03) as u8,
            // B3: base[12:5](8)
            ((b >> 5) & 0xFF) as u8,
            // B4: base[4:0](5) | marker(1)='1' | ext[8:7](2)
            (((b & 0x1F) as u8) << 3) | ESCR_MARKER_MID | ((e >> 7) & 0x03) as u8,
            // B5: ext[6:0](7) | marker(1)='1'
            (((e & 0x7F) as u8) << 1) | ESCR_MARKER_LAST,
        ]
    }
}

// ── DSM trick mode (ISO/IEC 13818-1 §2.4.3.7, Table 2-24) ──────────────────

/// Trick-mode control values for the `DSM_trick_mode_flag` field
/// (ISO/IEC 13818-1 §2.4.3.7, Table 2-24).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
pub enum TrickMode {
    /// `000` — fast forward.
    FastForward {
        /// 2-bit `field_id`.
        field_id: u8,
        /// `intra_slice_refresh` flag.
        intra_slice_refresh: bool,
        /// 2-bit `frequency_truncation`.
        frequency_truncation: u8,
    },
    /// `001` — slow motion.
    SlowMotion {
        /// 5-bit `rep_cntrl`.
        rep_cntrl: u8,
    },
    /// `010` — freeze frame.
    FreezeFrame {
        /// 2-bit `field_id`.
        field_id: u8,
        /// The 3 `reserved` bits after `field_id` (Table 2-24; spec
        /// convention [`FREEZE_FRAME_RESERVED_VALUE`] = `0b111`), kept so a
        /// real stream's value round-trips.
        reserved: u8,
    },
    /// `011` — fast reverse.
    FastReverse {
        /// 2-bit `field_id`.
        field_id: u8,
        /// `intra_slice_refresh` flag.
        intra_slice_refresh: bool,
        /// 2-bit `frequency_truncation`.
        frequency_truncation: u8,
    },
    /// `100` — slow reverse.
    SlowReverse {
        /// 5-bit `rep_cntrl`.
        rep_cntrl: u8,
    },
    /// `101`–`111` — reserved.
    Reserved {
        /// Raw 3-bit `trick_mode_control` value.
        trick_mode_control: u8,
        /// Raw 5-bit remainder.
        data: u8,
    },
}

impl TrickMode {
    /// Decode from the 1-byte trick-mode field (ISO/IEC 13818-1 §2.4.3.7).
    pub fn from_byte(b: u8) -> Self {
        let control = (b >> 5) & 0x07;
        let data = b & 0x1F;
        match control {
            0b000 => TrickMode::FastForward {
                field_id: (data >> 3) & 0x03,
                intra_slice_refresh: (data >> 2) & 0x01 != 0,
                frequency_truncation: data & 0x03,
            },
            0b001 => TrickMode::SlowMotion { rep_cntrl: data },
            0b010 => TrickMode::FreezeFrame {
                field_id: (data >> 3) & 0x03,
                reserved: data & 0x07,
            },
            0b011 => TrickMode::FastReverse {
                field_id: (data >> 3) & 0x03,
                intra_slice_refresh: (data >> 2) & 0x01 != 0,
                frequency_truncation: data & 0x03,
            },
            0b100 => TrickMode::SlowReverse { rep_cntrl: data },
            _ => TrickMode::Reserved {
                trick_mode_control: control,
                data,
            },
        }
    }

    /// Encode as the 1-byte trick-mode field.
    pub fn to_byte(self) -> u8 {
        match self {
            TrickMode::FastForward {
                field_id,
                intra_slice_refresh,
                frequency_truncation,
            } => {
                ((field_id & 0x03) << 3)
                    | ((intra_slice_refresh as u8) << 2)
                    | (frequency_truncation & 0x03)
            }
            TrickMode::SlowMotion { rep_cntrl } => (0b001 << 5) | (rep_cntrl & 0x1F),
            TrickMode::FreezeFrame { field_id, reserved } => {
                (0b010 << 5) | ((field_id & 0x03) << 3) | (reserved & 0x07)
            }
            TrickMode::FastReverse {
                field_id,
                intra_slice_refresh,
                frequency_truncation,
            } => {
                (0b011 << 5)
                    | ((field_id & 0x03) << 3)
                    | ((intra_slice_refresh as u8) << 2)
                    | (frequency_truncation & 0x03)
            }
            TrickMode::SlowReverse { rep_cntrl } => (0b100 << 5) | (rep_cntrl & 0x1F),
            TrickMode::Reserved {
                trick_mode_control,
                data,
            } => ((trick_mode_control & 0x07) << 5) | (data & 0x1F),
        }
    }
}

// ── PES extension (ISO/IEC 13818-1 §2.4.3.7) ──────────────────────────────

/// `program_packet_sequence_counter` sub-field of [`PesExtension`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct ProgramPacketSequenceCounter {
    /// 7-bit counter.
    pub counter: u8,
    /// `MPEG1_MPEG2_identifier` flag.
    pub mpeg1_mpeg2_identifier: bool,
    /// 6-bit `original_stuff_length`.
    pub original_stuff_length: u8,
}

/// `P-STD_buffer` sub-field of [`PesExtension`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct PStdBuffer {
    /// P-STD buffer size scale: `false` = 128 bytes/unit, `true` = 1024 bytes/unit.
    pub scale: bool,
    /// 13-bit buffer size in units of the scale.
    pub size: u16,
}

/// `PES_extension_field()` payload, present when `PES_extension_flag_2` is set
/// (ISO/IEC 13818-1 §2.4.3.7, Table 2-21).
///
/// The field itself is `marker_bit(1) + PES_extension_field_length(7)`
/// (handled by [`PesExtension`]'s parse/serialize) followed by these bytes.
/// The first byte is `stream_id_extension_flag`(1) + 7 more bits that are
/// `stream_id_extension` when the flag is `0`, or `reserved`(6)+
/// `tref_extension_flag`(1) when the flag is `1`; the TREF sub-fields or
/// reserved padding that can follow are not decoded further and stay opaque.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct PesExtensionField<'a> {
    /// `stream_id_extension_flag`.
    pub stream_id_extension_flag: bool,
    /// The low 7 bits of the `stream_id_extension` byte (see struct docs for
    /// how to interpret them against `stream_id_extension_flag`).
    pub low_bits: u8,
    /// Bytes following the `stream_id_extension` byte (opaque per spec).
    pub rest: &'a [u8],
}

impl PesExtensionField<'_> {
    /// The 7-bit `stream_id_extension` (Table 2-21), or `None` when
    /// `stream_id_extension_flag` is `1` (the low bits are then `reserved` +
    /// `tref_extension_flag`, not an extension id).
    #[must_use]
    pub const fn stream_id_extension(&self) -> Option<u8> {
        if self.stream_id_extension_flag {
            None
        } else {
            Some(self.low_bits)
        }
    }
}

/// The `additional_copy_info` byte: `marker_bit(1) | additional_copy_info(7)`
/// (ISO/IEC 13818-1 Table 2-21). The marker is spec-fixed to `1` but kept so a
/// real stream's value round-trips; it lives with the value (not as a
/// `PesHeader` field) so the header does not grow.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
pub struct AdditionalCopyInfo {
    /// 7-bit `additional_copy_info`.
    pub info: u8,
    /// The `marker_bit` in front of it (spec `1`).
    pub marker: bool,
}

impl AdditionalCopyInfo {
    /// A value with the spec-conformant marker bit.
    #[must_use]
    pub const fn new(info: u8) -> Self {
        Self { info, marker: true }
    }
}

/// Typed PES header extension sub-structure
/// (ISO/IEC 13818-1 §2.4.3.7, Table 2-21, `PES_extension_flag = 1`).
///
/// `#[non_exhaustive]`: build with [`PesExtension::new`] and set fields, so
/// further additions are not a breaking change again.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct PesExtension<'a> {
    /// 128-bit PES private data, if `PES_private_data_flag` is set.
    pub pes_private_data: Option<[u8; 16]>,
    /// Pack header field bytes (opaque per spec — `&[u8]` is correct here).
    pub pack_header: Option<&'a [u8]>,
    /// Program packet sequence counter sub-fields.
    pub program_packet_sequence_counter: Option<ProgramPacketSequenceCounter>,
    /// P-STD buffer sub-field.
    pub p_std_buffer: Option<PStdBuffer>,
    /// `PES_extension_field()` payload, if `PES_extension_flag_2` is set.
    pub pes_extension_field: Option<PesExtensionField<'a>>,
    /// The 3 `reserved` bits of the extension flags byte (Table 2-21; spec
    /// convention `0b111`), kept so a real stream's value round-trips.
    pub reserved_bits: u8,
}

impl Default for PesExtension<'_> {
    fn default() -> Self {
        Self::new()
    }
}

impl<'a> PesExtension<'a> {
    /// An extension with no optional sub-fields and the spec-convention
    /// reserved bits (`0b111`).
    #[must_use]
    pub const fn new() -> Self {
        Self {
            pes_private_data: None,
            pack_header: None,
            program_packet_sequence_counter: None,
            p_std_buffer: None,
            pes_extension_field: None,
            reserved_bits: EXT_RESERVED_VALUE,
        }
    }

    fn parse(data: &'a [u8]) -> Result<Self> {
        if data.is_empty() {
            return Err(Error::BufferTooShort {
                need: 1,
                have: 0,
                what: "PES_extension flags byte",
            });
        }
        let flags = data[0];
        let mut cursor = 1usize;

        let pes_private_data = if flags & EXT_PES_PRIVATE_DATA != 0 {
            let end = cursor + 16;
            let arr: [u8; 16] = data
                .get(cursor..end)
                .and_then(|s| s.try_into().ok())
                .ok_or(Error::BufferTooShort {
                    need: end,
                    have: data.len(),
                    what: "PES_private_data",
                })?;
            cursor = end;
            Some(arr)
        } else {
            None
        };

        let pack_header = if flags & EXT_PACK_HEADER != 0 {
            let pack_len = *data.get(cursor).ok_or(Error::BufferTooShort {
                need: cursor + 1,
                have: data.len(),
                what: "pack_field_length",
            })? as usize;
            cursor += 1;
            let end = cursor + pack_len;
            let slice = data.get(cursor..end).ok_or(Error::BufferTooShort {
                need: end,
                have: data.len(),
                what: "pack_header",
            })?;
            cursor = end;
            Some(slice)
        } else {
            None
        };

        let program_packet_sequence_counter = if flags & EXT_PROGRAM_PACKET_SEQUENCE_COUNTER != 0 {
            if data.len() < cursor + 2 {
                return Err(Error::BufferTooShort {
                    need: cursor + 2,
                    have: data.len(),
                    what: "program_packet_sequence_counter",
                });
            }
            let b0 = data[cursor];
            let b1 = data[cursor + 1];
            cursor += 2;
            Some(ProgramPacketSequenceCounter {
                counter: b0 & 0x7F,
                mpeg1_mpeg2_identifier: (b1 & 0x40) != 0,
                original_stuff_length: b1 & 0x3F,
            })
        } else {
            None
        };

        let p_std_buffer = if flags & EXT_P_STD_BUFFER != 0 {
            if data.len() < cursor + 2 {
                return Err(Error::BufferTooShort {
                    need: cursor + 2,
                    have: data.len(),
                    what: "P-STD_buffer",
                });
            }
            let b0 = data[cursor];
            let b1 = data[cursor + 1];
            cursor += 2;
            Some(PStdBuffer {
                scale: (b0 & 0x20) != 0,
                size: (((b0 & 0x1F) as u16) << 8) | (b1 as u16),
            })
        } else {
            None
        };

        let pes_extension_field = if flags & EXT_FLAG_2 != 0 {
            let len_byte = *data.get(cursor).ok_or(Error::BufferTooShort {
                need: cursor + 1,
                have: data.len(),
                what: "PES_extension_field_length",
            })?;
            // Table 2-21: marker_bit(1) + PES_extension_field_length(7), not a
            // plain 8-bit length (issue #1052) — the high bit is a marker,
            // not part of the count.
            let ext_len = (len_byte & LOW7_MASK) as usize;
            cursor += 1;
            let end = cursor + ext_len;
            let field_bytes = data.get(cursor..end).ok_or(Error::BufferTooShort {
                need: end,
                have: data.len(),
                what: "PES_extension_field",
            })?;
            cursor = end;
            // First byte: stream_id_extension_flag(1) + 7 more bits (Table 2-21).
            let (sie_byte, rest) = field_bytes.split_first().ok_or(Error::BufferTooShort {
                need: 1,
                have: 0,
                what: "PES_extension_field.stream_id_extension byte",
            })?;
            Some(PesExtensionField {
                stream_id_extension_flag: (sie_byte & MSB_FLAG) != 0,
                low_bits: sie_byte & LOW7_MASK,
                rest,
            })
        } else {
            None
        };
        let _ = cursor;

        Ok(PesExtension {
            pes_private_data,
            pack_header,
            program_packet_sequence_counter,
            p_std_buffer,
            pes_extension_field,
            reserved_bits: (flags & EXT_RESERVED_MASK) >> EXT_RESERVED_SHIFT,
        })
    }

    /// Number of bytes this PES extension occupies on the wire.
    pub fn serialized_len(&self) -> usize {
        let mut n = 1usize; // flags byte
        if self.pes_private_data.is_some() {
            n += 16;
        }
        if let Some(ph) = self.pack_header {
            n += 1 + ph.len();
        }
        if self.program_packet_sequence_counter.is_some() {
            n += 2;
        }
        if self.p_std_buffer.is_some() {
            n += 2;
        }
        if let Some(ef) = &self.pes_extension_field {
            // length byte + stream_id_extension byte + trailing bytes.
            n += 1 + 1 + ef.rest.len();
        }
        n
    }

    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize> {
        let need = self.serialized_len();
        if buf.len() < need {
            return Err(Error::BufferTooShort {
                need,
                have: buf.len(),
                what: "PES_extension serialize output",
            });
        }

        let mut flags = broadcast_common::len::fit_mask(
            self.reserved_bits,
            EXT_RESERVED_VALUE,
            "PES_extension.reserved",
        )? << EXT_RESERVED_SHIFT;
        if self.pes_private_data.is_some() {
            flags |= EXT_PES_PRIVATE_DATA;
        }
        if self.pack_header.is_some() {
            flags |= EXT_PACK_HEADER;
        }
        if self.program_packet_sequence_counter.is_some() {
            flags |= EXT_PROGRAM_PACKET_SEQUENCE_COUNTER;
        }
        if self.p_std_buffer.is_some() {
            flags |= EXT_P_STD_BUFFER;
        }
        if self.pes_extension_field.is_some() {
            flags |= EXT_FLAG_2;
        }
        buf[0] = flags;
        let mut cursor = 1usize;

        if let Some(pd) = &self.pes_private_data {
            buf[cursor..cursor + 16].copy_from_slice(pd);
            cursor += 16;
        }
        if let Some(ph) = self.pack_header {
            buf[cursor] =
                broadcast_common::len::fit_u8(ph.len(), "PES_extension.pack_field_length")?;
            cursor += 1;
            buf[cursor..cursor + ph.len()].copy_from_slice(ph);
            cursor += ph.len();
        }
        if let Some(ppsc) = self.program_packet_sequence_counter {
            // byte 0: marker(1) | counter(7)
            buf[cursor] = 0x80 | (ppsc.counter & 0x7F);
            // byte 1: marker(1) | mpeg1_mpeg2_id(1) | original_stuff_length(6)
            buf[cursor + 1] = 0x80
                | ((ppsc.mpeg1_mpeg2_identifier as u8) << 6)
                | (ppsc.original_stuff_length & 0x3F);
            cursor += 2;
        }
        if let Some(ps) = self.p_std_buffer {
            // '01' | scale(1) | size(13)
            // size is 13 bits: reject, never mask, an over-range value (#1129).
            let size = broadcast_common::len::fit_bits(
                u64::from(ps.size),
                13,
                "PES_extension.P-STD_buffer_size",
            )? as u16;
            buf[cursor] = 0x40 | ((ps.scale as u8) << 5) | ((size >> 8) as u8 & 0x1F);
            buf[cursor + 1] = (size & 0xFF) as u8;
            cursor += 2;
        }
        if let Some(ef) = &self.pes_extension_field {
            let field_len = 1 + ef.rest.len(); // stream_id_extension byte + rest
            // Table 2-21: the length is 7 bits, not 8 (issue #1052) — the high
            // bit written below is `marker_bit`, always 1.
            let checked = broadcast_common::len::fit_bits(
                field_len as u64,
                7,
                "PES_extension.PES_extension_field_length",
            )?;
            buf[cursor] = MSB_FLAG | (checked as u8);
            cursor += 1;
            buf[cursor] = ((ef.stream_id_extension_flag as u8) << 7) | (ef.low_bits & LOW7_MASK);
            cursor += 1;
            buf[cursor..cursor + ef.rest.len()].copy_from_slice(ef.rest);
            cursor += ef.rest.len();
        }
        Ok(cursor)
    }
}

// ── PesHeader ──────────────────────────────────────────────────────────────

/// The optional PES header present for non-special `stream_id`s
/// (ISO/IEC 13818-1 §2.4.3.6, §2.4.3.7). All optional sub-fields are fully
/// typed — the raw `optional_fields` blob has been replaced with the
/// individual decoded fields.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct PesHeader<'a> {
    /// PES_scrambling_control (2 bits).
    pub scrambling_control: u8,
    /// PES_priority.
    pub pes_priority: bool,
    /// data_alignment_indicator.
    pub data_alignment_indicator: bool,
    /// copyright.
    pub copyright: bool,
    /// original_or_copy.
    pub original_or_copy: bool,
    /// Presentation time stamp, if `PTS_DTS_flags` indicated one.
    pub pts: Option<Pts>,
    /// Decoding time stamp, if `PTS_DTS_flags` was `11`.
    pub dts: Option<Dts>,
    /// Elementary stream clock reference (6 bytes), if `ESCR_flag` is set.
    pub escr: Option<Escr>,
    /// 22-bit ES rate (bytes/second × 50), if `ES_rate_flag` is set.
    pub es_rate: Option<u32>,
    /// The two `marker_bit`s around `ES_rate` (Table 2-21), packed as
    /// `0b<leading><trailing>`; the spec fixes both to `1` (`0b11`) but a real
    /// stream (TSDuck `test-002.ts`) carries a `0` leading marker, so they are
    /// kept for a byte-exact round trip. Only meaningful when `es_rate` is
    /// `Some`.
    pub es_rate_marker_bits: u8,
    /// DSM trick-mode control byte (typed), if `DSM_trick_mode_flag` is set.
    pub dsm_trick_mode: Option<TrickMode>,
    /// `marker_bit` + 7-bit `additional_copy_info`, if
    /// `additional_copy_info_flag` is set.
    pub additional_copy_info: Option<AdditionalCopyInfo>,
    /// Previous PES packet CRC (16 bits), if `PES_CRC_flag` is set.
    pub pes_crc: Option<u16>,
    /// PES extension sub-structure, if `PES_extension_flag` is set.
    pub pes_extension: Option<PesExtension<'a>>,
    /// The `stuffing_byte`s inside the `PES_header_data_length` region, after
    /// the typed optional fields (ISO/IEC 13818-1 Table 2-21 —
    /// "stuffing_byte: fixed 8-bit value `0xFF`").
    ///
    /// Encoders pad the optional-header block (often so the elementary stream
    /// starts at a fixed offset). These bytes are part of the wire image and
    /// are kept verbatim (not just counted), so a non-`0xFF` filler from a
    /// non-conforming encoder round-trips byte-for-byte too. Use `&[]` for a
    /// header with no stuffing.
    pub header_stuffing: &'a [u8],
}

impl<'a> PesHeader<'a> {
    /// A header with `PES_scrambling_control = 0`, every flag clear, no
    /// optional fields, no stuffing and spec-conformant marker bits. Set
    /// fields on the result (the struct is `#[non_exhaustive]`).
    #[must_use]
    pub const fn new() -> Self {
        Self {
            scrambling_control: 0,
            pes_priority: false,
            data_alignment_indicator: false,
            copyright: false,
            original_or_copy: false,
            pts: None,
            dts: None,
            escr: None,
            es_rate: None,
            es_rate_marker_bits: ES_RATE_MARKERS_VALUE,
            dsm_trick_mode: None,
            additional_copy_info: None,
            pes_crc: None,
            pes_extension: None,
            header_stuffing: &[],
        }
    }
}

impl Default for PesHeader<'_> {
    fn default() -> Self {
        Self::new()
    }
}

impl PesHeader<'_> {
    /// Number of bytes this header occupies in the serialized `PES_header_data_length`
    /// region (not counting the 3 fixed header bytes — the 2 flag bytes + length byte).
    fn optional_len(&self) -> usize {
        let mut n = 0usize;
        if self.pts.is_some() {
            n += 5;
        }
        if self.dts.is_some() {
            n += 5;
        }
        if self.escr.is_some() {
            n += 6;
        }
        if self.es_rate.is_some() {
            n += 3;
        }
        if self.dsm_trick_mode.is_some() {
            n += 1;
        }
        if self.additional_copy_info.is_some() {
            n += 1;
        }
        if self.pes_crc.is_some() {
            n += 2;
        }
        if let Some(ref ext) = self.pes_extension {
            n += ext.serialized_len();
        }
        n += self.header_stuffing.len();
        n
    }
}

/// A parsed PES packet.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct PesPacket<'a> {
    /// stream_id (Table 2-22).
    pub stream_id: StreamId,
    /// PES_packet_length as carried; `0` means unbounded (video).
    pub pes_packet_length: u16,
    /// Optional PES header (absent for the special `stream_id`s).
    pub header: Option<PesHeader<'a>>,
    /// The elementary-stream bytes (`PES_packet_data_byte`s).
    #[cfg_attr(feature = "serde", serde(skip))]
    pub payload: &'a [u8],
}

impl<'a> PesPacket<'a> {
    /// Parse a PES packet from the bytes starting at its `packet_start_code_prefix`.
    pub fn parse(b: &'a [u8]) -> Result<Self> {
        if b.len() < MIN_LEN {
            return Err(Error::BufferTooShort {
                need: MIN_LEN,
                have: b.len(),
                what: "PES packet header",
            });
        }
        if b[0..3] != PACKET_START_CODE_PREFIX {
            return Err(Error::BadStartCode(
                (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]),
            ));
        }
        let stream_id = StreamId(b[3]);
        let pes_packet_length = u16::from_be_bytes([b[4], b[5]]);
        // Where the payload ends: bounded by PES_packet_length unless 0 (unbounded).
        let payload_end = if pes_packet_length == 0 {
            b.len()
        } else {
            (MIN_LEN + pes_packet_length as usize).min(b.len())
        };

        if !stream_id.has_optional_header() {
            return Ok(PesPacket {
                stream_id,
                pes_packet_length,
                header: None,
                payload: &b[MIN_LEN..payload_end],
            });
        }

        if b.len() < MIN_LEN + HEADER_FIXED {
            return Err(Error::BufferTooShort {
                need: MIN_LEN + HEADER_FIXED,
                have: b.len(),
                what: "PES optional header",
            });
        }
        let f1 = b[6];
        let f2 = b[7];
        // Table 2-21: the first two bits are the fixed `'10'`. Anything else
        // is not an MPEG-2 PES header (MPEG-1 PES, or damage) and would be
        // misparsed as one.
        if f1 & F1_MARKER_MASK != F1_MARKER_VALUE {
            return Err(Error::BadHeaderMarker);
        }
        let hdl = usize::from(b[8]);
        let hdr_start = MIN_LEN + HEADER_FIXED; // = 9
        let hdr_end = hdr_start + hdl;
        if b.len() < hdr_end {
            return Err(Error::BufferTooShort {
                need: hdr_end,
                have: b.len(),
                what: "PES_header_data_length",
            });
        }
        // The header lies inside a bounded packet: a `PES_packet_length` too
        // small to hold `PES_header_data_length` is malformed (and would make
        // serialize write header bytes beyond the declared length).
        if pes_packet_length != 0 && hdr_end > payload_end {
            return Err(Error::BufferTooShort {
                need: hdr_end,
                have: payload_end,
                what: "PES_header_data_length exceeds PES_packet_length",
            });
        }
        let opt = &b[hdr_start..hdr_end];
        let mut cursor = 0usize;

        // PTS/DTS (ISO/IEC 13818-1 §2.4.3.7 Table 2-21).
        let pts_dts_flags = (f2 >> 6) & 0x03;
        let (pts, dts) = match pts_dts_flags {
            0b10 => {
                if opt.len() < cursor + 5 {
                    return Err(Error::BufferTooShort {
                        need: cursor + 5,
                        have: opt.len(),
                        what: "PTS",
                    });
                }
                let pts = Pts(timestamp::read(&opt[cursor..], 0b0010, "PTS")?);
                cursor += 5;
                (Some(pts), None)
            }
            0b11 => {
                if opt.len() < cursor + 10 {
                    return Err(Error::BufferTooShort {
                        need: cursor + 10,
                        have: opt.len(),
                        what: "PTS+DTS",
                    });
                }
                let pts = Pts(timestamp::read(&opt[cursor..], 0b0011, "PTS")?);
                cursor += 5;
                let dts = Dts(timestamp::read(&opt[cursor..], 0b0001, "DTS")?);
                cursor += 5;
                (Some(pts), Some(dts))
            }
            0b00 => (None, None),
            // 0b01 is a reserved/forbidden combination (Table 2-21 defines
            // only 00/10/11); accepting it silently as "no timestamps"
            // discards a real stream error instead of surfacing it, and the
            // 5 bytes that would have been the timestamp are then misread
            // as whatever comes next (ESCR, ES_rate, ...).
            _ => return Err(Error::ForbiddenPtsDtsFlags),
        };

        // ESCR (6 bytes, ISO/IEC 13818-1 §2.4.3.7).
        let escr = if f2 & F2_ESCR != 0 {
            if opt.len() < cursor + 6 {
                return Err(Error::BufferTooShort {
                    need: cursor + 6,
                    have: opt.len(),
                    what: "ESCR",
                });
            }
            let arr: &[u8; 6] = opt[cursor..cursor + 6].try_into().unwrap();
            let e = Escr::from_field_bytes(arr)?;
            cursor += 6;
            Some(e)
        } else {
            None
        };

        // ES_rate (3 bytes: 1 marker + 22-bit rate + 1 marker).
        let mut es_rate_marker_bits = ES_RATE_MARKERS_VALUE;
        let es_rate = if f2 & F2_ES_RATE != 0 {
            if opt.len() < cursor + 3 {
                return Err(Error::BufferTooShort {
                    need: cursor + 3,
                    have: opt.len(),
                    what: "ES_rate",
                });
            }
            es_rate_marker_bits = ((opt[cursor] >> 7) << 1) | (opt[cursor + 2] & 1);
            let rate = (((opt[cursor] & 0x7F) as u32) << 15)
                | ((opt[cursor + 1] as u32) << 7)
                | ((opt[cursor + 2] >> 1) as u32);
            cursor += 3;
            Some(rate)
        } else {
            None
        };

        // DSM trick mode (1 byte).
        let dsm_trick_mode = if f2 & F2_DSM_TRICK_MODE != 0 {
            if opt.len() < cursor + 1 {
                return Err(Error::BufferTooShort {
                    need: cursor + 1,
                    have: opt.len(),
                    what: "trick_mode",
                });
            }
            let tm = TrickMode::from_byte(opt[cursor]);
            cursor += 1;
            Some(tm)
        } else {
            None
        };

        // additional_copy_info (1 byte: marker + 7-bit info).
        let additional_copy_info = if f2 & F2_ADDITIONAL_COPY_INFO != 0 {
            if opt.len() < cursor + 1 {
                return Err(Error::BufferTooShort {
                    need: cursor + 1,
                    have: opt.len(),
                    what: "additional_copy_info",
                });
            }
            let v = AdditionalCopyInfo {
                info: opt[cursor] & 0x7F,
                marker: opt[cursor] & ADDITIONAL_COPY_INFO_MARKER != 0,
            };
            cursor += 1;
            Some(v)
        } else {
            None
        };

        // PES_CRC (2 bytes).
        let pes_crc = if f2 & F2_PES_CRC != 0 {
            if opt.len() < cursor + 2 {
                return Err(Error::BufferTooShort {
                    need: cursor + 2,
                    have: opt.len(),
                    what: "PES_CRC",
                });
            }
            let crc = u16::from_be_bytes([opt[cursor], opt[cursor + 1]]);
            cursor += 2;
            Some(crc)
        } else {
            None
        };

        // PES_extension.
        let pes_extension = if f2 & F2_PES_EXTENSION != 0 {
            let ext = PesExtension::parse(&opt[cursor..])?;
            cursor += ext.serialized_len();
            Some(ext)
        } else {
            None
        };

        // Bytes remaining in the `PES_header_data_length` region after the typed
        // optional fields are `0xFF` stuffing (ISO/IEC 13818-1:2007 §2.4.3.7).
        // Record the count so serialization reproduces the header byte-for-byte.
        let header_stuffing = opt.get(cursor..).unwrap_or(&[]);

        let header = PesHeader {
            scrambling_control: (f1 >> 4) & 0x03,
            pes_priority: f1 & F1_PRIORITY != 0,
            data_alignment_indicator: f1 & F1_DATA_ALIGNMENT != 0,
            copyright: f1 & F1_COPYRIGHT != 0,
            original_or_copy: f1 & F1_ORIGINAL_OR_COPY != 0,
            pts,
            dts,
            escr,
            es_rate,
            es_rate_marker_bits,
            dsm_trick_mode,
            additional_copy_info,
            pes_crc,
            pes_extension,
            header_stuffing,
        };

        Ok(PesPacket {
            stream_id,
            pes_packet_length,
            header: Some(header),
            payload: &b[hdr_end.min(payload_end)..payload_end],
        })
    }

    /// Serialized length in bytes.
    #[must_use]
    pub fn serialized_len(&self) -> usize {
        let hdr = self
            .header
            .as_ref()
            .map_or(0, |h| HEADER_FIXED + h.optional_len());
        MIN_LEN + hdr + self.payload.len()
    }

    /// Serialize back to bytes (byte-identical to a spec-compliant input).
    pub fn serialize_into(&self, buf: &mut [u8]) -> Result<usize> {
        let len = self.serialized_len();
        if buf.len() < len {
            return Err(Error::BufferTooShort {
                need: len,
                have: buf.len(),
                what: "PES serialize output",
            });
        }
        buf[0..3].copy_from_slice(&PACKET_START_CODE_PREFIX);
        buf[3] = self.stream_id.0;
        buf[4..6].copy_from_slice(&self.pes_packet_length.to_be_bytes());
        let payload_at = match &self.header {
            None => MIN_LEN,
            Some(h) => {
                if h.dts.is_some() && h.pts.is_none() {
                    // ISO/IEC 13818-1 Table 2-21 has no `PTS_DTS_flags` code
                    // for "DTS but no PTS": without this guard, the flags
                    // written below fall through to `_ => 0b00` (no
                    // timestamps present) while the DTS bytes are written
                    // into the optional region anyway, producing a header
                    // whose declared PES_header_data_length/flags disagree
                    // with its actual bytes.
                    return Err(Error::ForbiddenPtsDtsFlags);
                }
                let opt_len = h.optional_len();
                if opt_len > 255 {
                    return Err(Error::OptionalFieldsTooLarge(opt_len));
                }

                // f1: marker '10' | scrambling(2) | priority(1) | align(1) | copyright(1) | orig(1)
                let f1 = 0x80
                    | ((h.scrambling_control & 0x03) << 4)
                    | (u8::from(h.pes_priority) << 3)
                    | (u8::from(h.data_alignment_indicator) << 2)
                    | (u8::from(h.copyright) << 1)
                    | u8::from(h.original_or_copy);

                // f2: pts_dts_flags(2) | escr_flag(1) | es_rate_flag(1) |
                //     trick_mode(1) | add_copy(1) | crc(1) | ext(1)
                let pts_dts_flags = match (h.pts.is_some(), h.dts.is_some()) {
                    (true, true) => 0b11u8,
                    (true, false) => 0b10,
                    _ => 0b00,
                };
                let f2 = (pts_dts_flags << 6)
                    | (u8::from(h.escr.is_some()) << 5)
                    | (u8::from(h.es_rate.is_some()) << 4)
                    | (u8::from(h.dsm_trick_mode.is_some()) << 3)
                    | (u8::from(h.additional_copy_info.is_some()) << 2)
                    | (u8::from(h.pes_crc.is_some()) << 1)
                    | u8::from(h.pes_extension.is_some());

                buf[6] = f1;
                buf[7] = f2;
                buf[8] = opt_len as u8;

                let mut cursor = MIN_LEN + HEADER_FIXED; // = 9

                // PTS (and/or DTS).
                if let Some(pts) = h.pts {
                    let prefix = if h.dts.is_some() { 0b0011u8 } else { 0b0010u8 };
                    buf[cursor..cursor + 5].copy_from_slice(&timestamp::write(pts.0, prefix));
                    cursor += 5;
                }
                if let Some(dts) = h.dts {
                    buf[cursor..cursor + 5].copy_from_slice(&timestamp::write(dts.0, 0b0001));
                    cursor += 5;
                }
                // ESCR.
                if let Some(escr) = h.escr {
                    buf[cursor..cursor + 6].copy_from_slice(&escr.to_field_bytes());
                    cursor += 6;
                }
                // ES_rate: marker(1) | rate(22) | marker(1) = 3 bytes.
                if let Some(rate) = h.es_rate {
                    let leading = if h.es_rate_marker_bits & 0b10 != 0 {
                        ES_RATE_LEADING_MARKER
                    } else {
                        0
                    };
                    buf[cursor] = leading | ((rate >> 15) as u8 & 0x7F);
                    buf[cursor + 1] = ((rate >> 7) & 0xFF) as u8;
                    buf[cursor + 2] = (((rate & 0x7F) as u8) << 1)
                        | (h.es_rate_marker_bits & ES_RATE_TRAILING_MARKER);
                    cursor += 3;
                }
                // DSM trick mode.
                if let Some(tm) = h.dsm_trick_mode {
                    buf[cursor] = tm.to_byte();
                    cursor += 1;
                }
                // additional_copy_info: marker(1) | info(7).
                if let Some(aci) = h.additional_copy_info {
                    let marker = if aci.marker {
                        ADDITIONAL_COPY_INFO_MARKER
                    } else {
                        0
                    };
                    buf[cursor] = marker | (aci.info & 0x7F);
                    cursor += 1;
                }
                // PES_CRC (2 bytes, big-endian).
                if let Some(crc) = h.pes_crc {
                    buf[cursor..cursor + 2].copy_from_slice(&crc.to_be_bytes());
                    cursor += 2;
                }
                // PES_extension.
                if let Some(ref ext) = h.pes_extension {
                    let written = ext.serialize_into(&mut buf[cursor..])?;
                    cursor += written;
                }

                // Trailing stuffing inside the header_data_length region
                // (ISO/IEC 13818-1 Table 2-21), reproducing the encoder's pad.
                buf[cursor..cursor + h.header_stuffing.len()].copy_from_slice(h.header_stuffing);
                cursor += h.header_stuffing.len();

                cursor
            }
        };
        buf[payload_at..len].copy_from_slice(self.payload);
        Ok(len)
    }
}

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

    fn round_trip(b: &[u8]) {
        let pkt = PesPacket::parse(b).unwrap();
        let mut out = vec![0u8; pkt.serialized_len()];
        pkt.serialize_into(&mut out).unwrap();
        assert_eq!(&out[..], b, "round-trip mismatch");
        let re = PesPacket::parse(&out).unwrap();
        // Compare without the borrowed lifetime complexity — compare serialized form.
        let mut re_out = vec![0u8; re.serialized_len()];
        re.serialize_into(&mut re_out).unwrap();
        assert_eq!(out, re_out, "re-parse mismatch");
    }

    #[test]
    fn video_pts_only() {
        // stream_id 0xE0, len=0x0A, flags 0x80/0x80, hdl=5, PTS=0, payload AA BB.
        let b = [
            0x00, 0x00, 0x01, 0xE0, 0x00, 0x0A, 0x80, 0x80, 0x05, 0x21, 0x00, 0x01, 0x00, 0x01,
            0xAA, 0xBB,
        ];
        let pkt = PesPacket::parse(&b).unwrap();
        assert_eq!(pkt.stream_id, StreamId(0xE0));
        let h = pkt.header.as_ref().unwrap();
        assert_eq!(h.pts, Some(Pts(0)));
        assert!(h.dts.is_none());
        assert_eq!(pkt.payload, &[0xAA, 0xBB]);
        round_trip(&b);
    }

    #[test]
    fn pts_and_dts() {
        // PTS_DTS_flags=11, hdl=10. PTS prefix 0011, DTS prefix 0001.
        let b = [
            0x00, 0x00, 0x01, 0xE0, 0x00, 0x0F, 0x80, 0xC0, 0x0A, 0x31, 0x00, 0x03, 0x00, 0x01,
            0x11, 0x00, 0x05, 0x00, 0x01, 0xCC,
        ];
        let pkt = PesPacket::parse(&b).unwrap();
        let h = pkt.header.as_ref().unwrap();
        assert!(h.pts.is_some());
        assert!(h.dts.is_some());
        round_trip(&b);
    }

    // Regression (audit run-09 W4): `PTS_DTS_flags = 01` is a reserved/
    // forbidden combination (ISO/IEC 13818-1 Table 2-21 defines only
    // 00/10/11) that used to be silently accepted as "no timestamps",
    // discarding a real stream error and misreading the 5 bytes that would
    // have been the timestamp as whatever field comes next.
    #[test]
    fn forbidden_pts_dts_flags_01_is_rejected() {
        let mut b = [
            0x00, 0x00, 0x01, 0xE0, 0x00, 0x0F, 0x80, 0xC0, 0x0A, 0x31, 0x00, 0x03, 0x00, 0x01,
            0x11, 0x00, 0x05, 0x00, 0x01, 0xCC,
        ];
        b[7] = 0x40; // pts_dts_flags = 01 (top two bits of f2)
        assert!(matches!(
            PesPacket::parse(&b),
            Err(Error::ForbiddenPtsDtsFlags)
        ));
    }

    // Regression (audit run-09 W3): a `PesHeader` with `dts.is_some()` but
    // `pts.is_none()` must be rejected on serialize, not silently written
    // with `PTS_DTS_flags = 00` while the DTS bytes still occupy the
    // optional region — a header whose declared flags and actual bytes
    // disagree.
    #[test]
    fn serialize_rejects_dts_without_pts() {
        let header = PesHeader {
            scrambling_control: 0,
            pes_priority: false,
            data_alignment_indicator: false,
            copyright: false,
            original_or_copy: false,
            pts: None,
            dts: Some(Dts(0)),
            escr: None,
            es_rate: None,
            es_rate_marker_bits: 0b11,
            dsm_trick_mode: None,
            additional_copy_info: None,
            pes_crc: None,
            pes_extension: None,
            header_stuffing: &[],
        };
        let pkt = PesPacket {
            stream_id: StreamId(0xE0),
            pes_packet_length: 0,
            header: Some(header),
            payload: &[0xAA],
        };
        let mut buf = vec![0u8; pkt.serialized_len()];
        assert!(matches!(
            pkt.serialize_into(&mut buf),
            Err(Error::ForbiddenPtsDtsFlags)
        ));
    }

    #[test]
    fn pes_header_stuffing_round_trip() {
        // PTS-only (flags 0x80), PES_header_data_length = 8: 5 PTS bytes + 3
        // 0xFF stuffing bytes (ISO/IEC 13818-1:2007 §2.4.3.7).
        let b = [
            0x00, 0x00, 0x01, 0xE0, 0x00, 0x0C, 0x80, 0x80, 0x08, // hdl = 8
            0x21, 0x00, 0x01, 0x00, 0x01, // PTS = 0
            0xFF, 0xFF, 0xFF, // 3 stuffing bytes
            0xAA, // payload
        ];
        let pkt = PesPacket::parse(&b).unwrap();
        let h = pkt.header.as_ref().unwrap();
        assert!(h.pts.is_some());
        assert_eq!(
            h.header_stuffing,
            &[0xFF, 0xFF, 0xFF],
            "3 stuffing bytes after the 5-byte PTS"
        );
        // serialized_len must account for the stuffing.
        assert_eq!(pkt.serialized_len(), b.len());
        round_trip(&b); // byte-identical, incl. the 0xFF stuffing
    }

    #[test]
    fn special_stream_no_header() {
        // padding_stream 0xBE: bytes after length are payload directly.
        let b = [0x00, 0x00, 0x01, 0xBE, 0x00, 0x03, 0xFF, 0xFF, 0xFF];
        let pkt = PesPacket::parse(&b).unwrap();
        assert!(pkt.header.is_none());
        assert_eq!(pkt.payload, &[0xFF, 0xFF, 0xFF]);
        round_trip(&b);
    }

    #[test]
    fn unbounded_length_zero() {
        // PES_packet_length=0 (video): payload runs to end of buffer.
        let b = [
            0x00, 0x00, 0x01, 0xE0, 0x00, 0x00, 0x80, 0x80, 0x05, 0x21, 0x00, 0x01, 0x00, 0x01,
            0x01, 0x02, 0x03,
        ];
        let pkt = PesPacket::parse(&b).unwrap();
        assert_eq!(pkt.pes_packet_length, 0);
        assert_eq!(pkt.payload, &[0x01, 0x02, 0x03]);
        round_trip(&b);
    }

    #[test]
    fn rejects_bad_start_code() {
        let err = PesPacket::parse(&[0x00, 0x00, 0x02, 0xE0, 0x00, 0x00]).unwrap_err();
        assert!(matches!(err, Error::BadStartCode(0x000002)));
    }

    #[test]
    fn rejects_short() {
        let err = PesPacket::parse(&[0x00, 0x00, 0x01]).unwrap_err();
        assert!(matches!(err, Error::BufferTooShort { .. }));
    }

    #[test]
    fn serialize_rejects_oversized_optional_fields() {
        // Construct a PesHeader whose optional_len() > 255 by adding enough flags.
        // max realistic: 5+5+6+3+1+1+2 = 23, plus PesExtension with big private data.
        // This is structurally impossible with typed fields to reach 256 naturally,
        // but we test the guard exists by checking that OptionalFieldsTooLarge
        // is the right error variant name still exists.
        let _ = Error::OptionalFieldsTooLarge(256);
    }

    // ── Typed optional fields round-trips ──────────────────────────────────

    fn build_pes(h: PesHeader<'_>, payload: &[u8]) -> alloc::vec::Vec<u8> {
        let pkt = PesPacket {
            stream_id: StreamId(0xE0),
            pes_packet_length: 0, // unbounded
            header: Some(h),
            payload,
        };
        let mut out = vec![0u8; pkt.serialized_len()];
        pkt.serialize_into(&mut out).unwrap();
        out
    }

    fn empty_header<'a>() -> PesHeader<'a> {
        PesHeader {
            scrambling_control: 0,
            pes_priority: false,
            data_alignment_indicator: false,
            copyright: false,
            original_or_copy: false,
            pts: None,
            dts: None,
            escr: None,
            es_rate: None,
            es_rate_marker_bits: 0b11,
            dsm_trick_mode: None,
            additional_copy_info: None,
            pes_crc: None,
            pes_extension: None,
            header_stuffing: &[],
        }
    }

    /// Construct PES with ESCR set, serialize, parse, assert field preserved.
    #[test]
    fn pes_header_escr_round_trip() {
        let escr = Escr {
            base: 90_000,
            extension: 150,
            reserved: 0b11,
        };
        let h = PesHeader {
            escr: Some(escr),
            ..empty_header()
        };
        let bytes = build_pes(h, &[0xAA]);
        let pkt = PesPacket::parse(&bytes).unwrap();
        assert_eq!(pkt.header.unwrap().escr, Some(escr));
    }

    /// Escr::from_27mhz / as_27mhz round-trip.
    #[test]
    fn escr_27mhz_round_trip() {
        for ticks in [0u64, 1, 300, 27_000_000, 8_589_934_591] {
            let e = Escr::from_27mhz(ticks);
            assert_eq!(e.as_27mhz(), ticks, "ticks={ticks}");
        }
    }

    /// Escr::to_field_bytes / from_field_bytes round-trip.
    #[test]
    fn escr_field_bytes_round_trip() {
        for (base, ext) in [
            (0u64, 0u16),
            (10_000, 0),
            (0x1_FFFF_FFFF, 0x1FF),
            (1234, 56),
        ] {
            let e = Escr {
                base,
                extension: ext,
                reserved: 0b11,
            };
            let bytes = e.to_field_bytes();
            let decoded = Escr::from_field_bytes(&bytes).unwrap();
            assert_eq!(decoded, e, "base={base} ext={ext}");
        }
    }

    /// ES_rate round-trip.
    #[test]
    fn pes_header_es_rate_round_trip() {
        let h = PesHeader {
            es_rate: Some(0x3FFFFF),
            es_rate_marker_bits: 0b11,
            ..empty_header()
        };
        let bytes = build_pes(h, &[]);
        let pkt = PesPacket::parse(&bytes).unwrap();
        assert_eq!(pkt.header.unwrap().es_rate, Some(0x3FFFFF));
    }

    /// TrickMode round-trip (all variants).
    #[test]
    fn trick_mode_all_variants_round_trip() {
        let cases = [
            TrickMode::FastForward {
                field_id: 0x2,
                intra_slice_refresh: true,
                frequency_truncation: 0x3,
            },
            TrickMode::SlowMotion { rep_cntrl: 0x1F },
            TrickMode::FreezeFrame {
                field_id: 0x1,
                reserved: 0b101,
            },
            TrickMode::FastReverse {
                field_id: 0x0,
                intra_slice_refresh: false,
                frequency_truncation: 0x1,
            },
            TrickMode::SlowReverse { rep_cntrl: 0 },
            TrickMode::Reserved {
                trick_mode_control: 0b101,
                data: 0x1A,
            },
        ];
        for tm in cases {
            let b = tm.to_byte();
            let decoded = TrickMode::from_byte(b);
            assert_eq!(decoded, tm, "tm={tm:?}");
        }
    }

    /// TrickMode in PES header round-trip.
    #[test]
    fn pes_header_trick_mode_round_trip() {
        let tm = TrickMode::FastForward {
            field_id: 1,
            intra_slice_refresh: false,
            frequency_truncation: 2,
        };
        let h = PesHeader {
            dsm_trick_mode: Some(tm),
            ..empty_header()
        };
        let bytes = build_pes(h, &[]);
        let pkt = PesPacket::parse(&bytes).unwrap();
        assert_eq!(pkt.header.unwrap().dsm_trick_mode, Some(tm));
    }

    /// additional_copy_info round-trip.
    #[test]
    fn pes_header_additional_copy_info_round_trip() {
        let h = PesHeader {
            additional_copy_info: Some(AdditionalCopyInfo::new(0x7F)),
            ..empty_header()
        };
        let bytes = build_pes(h, &[]);
        let pkt = PesPacket::parse(&bytes).unwrap();
        assert_eq!(
            pkt.header.unwrap().additional_copy_info,
            Some(AdditionalCopyInfo::new(0x7F))
        );
    }

    /// PES_CRC round-trip.
    #[test]
    fn pes_header_pes_crc_round_trip() {
        let h = PesHeader {
            pes_crc: Some(0xDEAD),
            ..empty_header()
        };
        let bytes = build_pes(h, &[]);
        let pkt = PesPacket::parse(&bytes).unwrap();
        assert_eq!(pkt.header.unwrap().pes_crc, Some(0xDEAD));
    }

    /// PesExtension with program_packet_sequence_counter.
    #[test]
    fn pes_extension_ppsc_round_trip() {
        let ppsc = ProgramPacketSequenceCounter {
            counter: 42,
            mpeg1_mpeg2_identifier: true,
            original_stuff_length: 7,
        };
        let ext = PesExtension {
            pes_private_data: None,
            pack_header: None,
            program_packet_sequence_counter: Some(ppsc),
            p_std_buffer: None,
            pes_extension_field: None,
            ..PesExtension::new()
        };
        let h = PesHeader {
            pes_extension: Some(ext),
            ..empty_header()
        };
        let bytes = build_pes(h, &[]);
        let pkt = PesPacket::parse(&bytes).unwrap();
        let decoded_ext = pkt.header.unwrap().pes_extension.unwrap();
        assert_eq!(decoded_ext.program_packet_sequence_counter, Some(ppsc));
    }

    /// PesExtension with P-STD buffer.
    #[test]
    fn pes_extension_p_std_buffer_round_trip() {
        let pstd = PStdBuffer {
            scale: true,
            size: 0x1FFF,
        };
        let ext = PesExtension {
            pes_private_data: None,
            pack_header: None,
            program_packet_sequence_counter: None,
            p_std_buffer: Some(pstd),
            pes_extension_field: None,
            ..PesExtension::new()
        };
        let h = PesHeader {
            pes_extension: Some(ext),
            ..empty_header()
        };
        let bytes = build_pes(h, &[]);
        let pkt = PesPacket::parse(&bytes).unwrap();
        let decoded_ext = pkt.header.unwrap().pes_extension.unwrap();
        assert_eq!(decoded_ext.p_std_buffer, Some(pstd));
    }

    /// W10 (#1129): `pack_field_length` is an 8-bit field but used to be
    /// written with `ph.len() as u8`, wrapping to a short length while the
    /// full data was still copied after it. Calls the private
    /// `PesExtension::serialize_into` directly (this test module is a
    /// descendant of its defining module) so the assertion isolates this
    /// specific cast: reaching it via the public `PesPacket` API is also
    /// blocked by `PesHeader::optional_len`'s pre-existing `opt_len > 255`
    /// check, since a `pack_header` this size necessarily makes the whole
    /// optional-fields region exceed 255 bytes too.
    #[test]
    fn pack_header_over_255_bytes_rejected_not_wrapped() {
        let data = alloc::vec![0u8; 256];
        let ext = PesExtension {
            pes_private_data: None,
            pack_header: Some(&data),
            program_packet_sequence_counter: None,
            p_std_buffer: None,
            pes_extension_field: None,
            ..PesExtension::new()
        };
        let mut buf = vec![0u8; ext.serialized_len()];
        assert!(ext.serialize_into(&mut buf).is_err());
    }

    /// AVS3-P3 audio (T/AI 109.7 8.1.2 / TS 101 154 V2.10.1 4.1.8.35) is a
    /// `stream_id = 0xFD` PES whose `stream_id_extension` is `100 1111`; AVS3
    /// video uses `0x41`. The extension survives a serialize -> parse trip.
    #[test]
    fn avs3_stream_id_extension_round_trips() {
        for want in [
            crate::STREAM_ID_EXTENSION_AVS3_AUDIO,
            crate::STREAM_ID_EXTENSION_AVS3_VIDEO,
        ] {
            let ext = PesExtension {
                pes_extension_field: Some(PesExtensionField {
                    stream_id_extension_flag: false,
                    low_bits: want,
                    rest: &[],
                }),
                ..PesExtension::new()
            };
            let mut buf = vec![0u8; ext.serialized_len()];
            ext.serialize_into(&mut buf).unwrap();
            let back = PesExtension::parse(&buf).unwrap();
            let f = back.pes_extension_field.unwrap();
            assert_eq!(f.stream_id_extension(), Some(want));
        }
        let tref = PesExtensionField {
            stream_id_extension_flag: true,
            low_bits: 1,
            rest: &[],
        };
        assert_eq!(tref.stream_id_extension(), None);
    }

    /// W10 (#1129): `PES_extension_field_length` is an 8-bit field but used
    /// to be written with `ef.len() as u8`, wrapping the same way. See the
    /// note on `pack_header_over_255_bytes_rejected_not_wrapped` above about
    /// calling the private method directly. Post-#1052 the field is 7 bits
    /// (max 127), so this now also covers the narrower ceiling.
    #[test]
    fn pes_extension_field_over_127_bytes_rejected_not_wrapped() {
        let data = alloc::vec![0u8; 256];
        let ext = PesExtension {
            pes_private_data: None,
            pack_header: None,
            program_packet_sequence_counter: None,
            p_std_buffer: None,
            pes_extension_field: Some(PesExtensionField {
                stream_id_extension_flag: false,
                low_bits: 0,
                rest: &data,
            }),
            ..PesExtension::new()
        };
        let mut buf = vec![0u8; ext.serialized_len()];
        assert!(matches!(
            ext.serialize_into(&mut buf).unwrap_err(),
            Error::FieldOverflow(_)
        ));
    }

    /// #1129: a P-STD buffer size over 13 bits is an error, not masked.
    #[test]
    fn p_std_buffer_size_over_13_bits_rejected_not_masked() {
        let mut ext = PesExtension::new();
        ext.p_std_buffer = Some(PStdBuffer {
            scale: false,
            size: 0x2000,
        });
        let mut buf = vec![0u8; ext.serialized_len()];
        assert!(matches!(
            ext.serialize_into(&mut buf).unwrap_err(),
            Error::FieldOverflow(_)
        ));
        ext.p_std_buffer = Some(PStdBuffer {
            scale: true,
            size: 0x1FFF,
        });
        let mut buf = vec![0u8; ext.serialized_len()];
        assert!(ext.serialize_into(&mut buf).is_ok());
    }

    /// PesExtension with private data (16 bytes).
    #[test]
    fn pes_extension_private_data_round_trip() {
        let pd: [u8; 16] = [
            0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E,
            0x0F, 0x10,
        ];
        let ext = PesExtension {
            pes_private_data: Some(pd),
            pack_header: None,
            program_packet_sequence_counter: None,
            p_std_buffer: None,
            pes_extension_field: None,
            ..PesExtension::new()
        };
        let h = PesHeader {
            pes_extension: Some(ext),
            ..empty_header()
        };
        let bytes = build_pes(h, &[]);
        let pkt = PesPacket::parse(&bytes).unwrap();
        let decoded_ext = pkt.header.unwrap().pes_extension.unwrap();
        assert_eq!(decoded_ext.pes_private_data, Some(pd));
    }

    /// All optional PES header fields set at once — serialize and parse round-trip.
    #[test]
    fn pes_header_all_fields_round_trip() {
        let ppsc = ProgramPacketSequenceCounter {
            counter: 1,
            mpeg1_mpeg2_identifier: false,
            original_stuff_length: 0,
        };
        let ext = PesExtension {
            pes_private_data: None,
            pack_header: None,
            program_packet_sequence_counter: Some(ppsc),
            p_std_buffer: Some(PStdBuffer {
                scale: false,
                size: 100,
            }),
            pes_extension_field: None,
            ..PesExtension::new()
        };
        let h = PesHeader {
            scrambling_control: 0,
            pes_priority: true,
            data_alignment_indicator: false,
            copyright: false,
            original_or_copy: true,
            pts: Some(Pts(90_000)),
            dts: Some(Dts(85_000)),
            escr: Some(Escr {
                base: 1000,
                extension: 0,
                reserved: 0b11,
            }),
            es_rate: Some(50_000),
            es_rate_marker_bits: 0b11,
            dsm_trick_mode: Some(TrickMode::SlowMotion { rep_cntrl: 3 }),
            additional_copy_info: Some(AdditionalCopyInfo::new(5)),
            pes_crc: Some(0xCAFE),
            pes_extension: Some(ext),
            header_stuffing: &[],
        };
        let bytes = build_pes(h, &[0xFF]);
        let pkt = PesPacket::parse(&bytes).unwrap();
        let dh = pkt.header.unwrap();
        assert_eq!(dh.pts, Some(Pts(90_000)));
        assert_eq!(dh.dts, Some(Dts(85_000)));
        assert!(dh.escr.is_some());
        assert_eq!(dh.es_rate, Some(50_000));
        assert_eq!(
            dh.dsm_trick_mode,
            Some(TrickMode::SlowMotion { rep_cntrl: 3 })
        );
        assert_eq!(dh.additional_copy_info, Some(AdditionalCopyInfo::new(5)));
        assert_eq!(dh.pes_crc, Some(0xCAFE));
        assert!(dh.pes_extension.is_some());
    }
}