fix(frame): validate plane_count + add Debug for ffmpeg Frame

Audit issue #4 findings:

1. (LOW, accepted) `VideoFrame::new` / `AudioFrame::new` accept
   `plane_count: u8` but the `planes` arrays are fixed at 4 / 8
   slots. A caller passing `plane_count > 4` (or `> 8`) would
   later trip the slice indexing inside `.planes()` far from the
   construction site. Add explicit `assert!` at construction so
   the failure mode names `plane_count` directly. Both
   constructors gain `# Panics` docs and dedicated
   `should_panic` tests.

2. (LOW, accepted) `mediadecode_ffmpeg::Frame` lacked a `Debug`
   impl because the inner `ffmpeg_next::frame::Video` doesn't
   derive one. Add a manual impl that reports width, height,
   pixel format, plane count, and PTS via the public
   accessors — useful for debug-print sites without surfacing
   raw FFI internals.

Other audit recommendations (INFO `Dimensions` overflow,
`#[must_use]` sweep on builder methods, native webcodecs
tests) intentionally not applied — informational or
stylistic, low value relative to churn.

Author: uqio

mediadecode-ffmpeg/src/frame.rs

@@ -75,6 +75,23 @@ pub struct Frame {
   inner: frame::Video,
 }
 
+impl core::fmt::Debug for Frame {
+  /// `frame::Video` (from `ffmpeg_next`) doesn't itself implement
+  /// `Debug`, so route through the public accessors. Shows the
+  /// dimensions, pixel format, plane count, and PTS — enough to
+  /// distinguish frames at debug-print sites without surfacing
+  /// raw FFI internals.
+  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+    f.debug_struct("Frame")
+      .field("width", &self.width())
+      .field("height", &self.height())
+      .field("pix_fmt", &self.pix_fmt())
+      .field("planes", &self.planes())
+      .field("pts", &self.pts())
+      .finish()
+  }
+}
+
 impl Frame {
   /// Construct an empty frame, suitable as the destination passed to
   /// [`crate::VideoDecoder::receive_frame`].

mediadecode/src/frame.rs

@@ -289,6 +289,14 @@ impl<P, E, D> VideoFrame<P, E, D> {
   /// `dimensions` is the coded width/height pair (see
   /// [`Dimensions`] and [`Self::dimensions`] for the visible-vs-
   /// coded distinction).
+  ///
+  /// # Panics
+  ///
+  /// Panics if `plane_count > 4`. The fixed-size `planes` array
+  /// has four slots; passing a larger `plane_count` would later
+  /// trip the slice indexing inside [`Self::planes`] far from
+  /// the construction site. Asserting here fails fast with a
+  /// clear message instead.
   #[cfg_attr(not(tarpaulin), inline(always))]
   pub const fn new(
     dimensions: Dimensions,
@@ -297,6 +305,10 @@ impl<P, E, D> VideoFrame<P, E, D> {
     plane_count: u8,
     extra: E,
   ) -> Self {
+    assert!(
+      plane_count as usize <= 4,
+      "VideoFrame::new: plane_count exceeds the fixed 4-plane array",
+    );
     Self {
       pts: None,
       duration: None,
@@ -459,6 +471,13 @@ pub struct AudioFrame<S, C, E, D> {
 
 impl<S, C, E, D> AudioFrame<S, C, E, D> {
   /// Constructs an `AudioFrame`.
+  ///
+  /// # Panics
+  ///
+  /// Panics if `plane_count > 8`. The fixed-size `planes` array
+  /// has eight slots; passing a larger `plane_count` would
+  /// later trip the slice indexing inside [`Self::planes`] far
+  /// from the construction site.
   #[allow(clippy::too_many_arguments)]
   #[cfg_attr(not(tarpaulin), inline(always))]
   pub const fn new(
@@ -471,6 +490,10 @@ impl<S, C, E, D> AudioFrame<S, C, E, D> {
     plane_count: u8,
     extra: E,
   ) -> Self {
+    assert!(
+      plane_count as usize <= 8,
+      "AudioFrame::new: plane_count exceeds the fixed 8-plane array",
+    );
     Self {
       pts: None,
       duration: None,
@@ -780,6 +803,28 @@ mod tests {
     ]
   }
 
+  #[test]
+  #[should_panic(expected = "plane_count exceeds the fixed 4-plane array")]
+  fn video_frame_rejects_plane_count_above_array_size() {
+    let _f: VideoFrame<u32, (), &[u8]> =
+      VideoFrame::new(Dimensions::new(64, 64), 0u32, empty_planes(), 5, ());
+  }
+
+  #[test]
+  #[should_panic(expected = "plane_count exceeds the fixed 8-plane array")]
+  fn audio_frame_rejects_plane_count_above_array_size() {
+    let _f: AudioFrame<u32, u32, (), &[u8]> = AudioFrame::new(
+      48_000,
+      1024,
+      2,
+      0u32,
+      0u32,
+      audio_planes(),
+      9,
+      (),
+    );
+  }
+
   #[test]
   fn audio_frame_construct_and_access() {
     // AudioFrame<S, C, E, D>: S=u32 (SampleFormat), C=u32 (ChannelLayout),