rusty_h264_decoder/

mb16.rs

//! I_16x16 macroblock decoding — the mirror of the encoder's `mb16`.
//!
//! Parses each macroblock's residuals and reconstructs it with the exact same
//! prediction + inverse-transform helpers the encoder uses, so decoder output
//! matches encoder reconstruction bit-for-bit.
#![allow(clippy::needless_range_loop)]

use rusty_h264_common::bit_reader::OutOfData;
use rusty_h264_common::cavlc::{
    decode_residual_block, read_cbp_inter, read_cbp_intra, un_scan_4x4_ac_into, un_scan_4x4_dcac,
};
use rusty_h264_common::inter::{
    inter_partitions, mc_chroma, mc_luma, predict_mv, predict_partition_mv, MvNeighbor,
};
use rusty_h264_common::predict::{
    add_residual_8x8, chroma8x8_pred, chroma_qp, intra4x4_pred, intra8x8_pred, luma16x16_pred,
    reconstruct_4x4, I16Mode, CHROMA_4X4_SCAN_XY, LUMA_4X4_SCAN_XY,
};
use rusty_h264_common::transform::{
    dequantize, dequantize_weighted, inverse_quant_8x8, inverse_quant_chroma_dc,
    inverse_quant_chroma_dc_weighted, inverse_quant_luma_dc, inverse_quant_luma_dc_weighted,
};
use rusty_h264_common::{BitReader, YuvFrame};

/// One frame's motion field, in 4x4-block raster (`mb_w*4` wide).
///
/// Captured from any conformant stream this decoder parses — including x264's —
/// so a harness can compare motion fields between encoders without depending on
/// external MV-export tooling.
pub struct MvField {
    pub mb_w: usize,
    pub mb_h: usize,
    pub mv: Vec<(i32, i32)>,
    pub ref_idx: Vec<i32>,
    pub inter: Vec<bool>,
}

/// Frames captured in decode order when `RFF_MV_DUMP=1`. Diagnostic only.
pub static MV_DUMP: std::sync::Mutex<Vec<MvField>> = std::sync::Mutex::new(Vec::new());

pub fn mv_dump_on() -> bool {
    static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
    *ON.get_or_init(|| std::env::var("RFF_MV_DUMP").map_or(false, |v| v != "0"))
}

/// Reconstructed coded-size planes plus CAVLC `nnz` context grids.
pub struct FrameDecoder {
    mb_w: usize,
    mb_h: usize,
    /// Slice QP (`SliceQPy`) — the deblock filter's frame-level QP.
    qp: u8,
    /// Running luma QP (`QPy`), carried across macroblocks and stepped by each
    /// `mb_qp_delta` (spec §7.4.5). Equals `qp` on constant-QP streams.
    cur_qp: u8,
    /// `chroma_qp_index_offset` from the active PPS (§8.5.8).
    chroma_qp_offset: i32,
    cw: usize,
    ch: usize,
    ccw: usize,
    cch: usize,
    rec_y: Vec<u8>,
    rec_u: Vec<u8>,
    rec_v: Vec<u8>,
    /// Per-macroblock luma QP (`QPy`), for per-edge deblock strength.
    mb_qp: Vec<u8>,
    /// First macroblock address of the slice currently being decoded. Neighbors
    /// with a lower address belong to an earlier slice and are "not available"
    /// for prediction (spec §8.3/§8.4). Slices are contiguous raster ranges (we
    /// reject FMO/slice-groups), so address ≥ this ⇔ same slice.
    slice_first_mb: usize,
    nnz_y: Vec<u8>,
    nnz_c: [Vec<u8>; 2],
    modes_y: Vec<u8>,
    coded_y: Vec<bool>,
    /// Per-4×4-block List-0 motion (mv + ref index, `-1` = no L0). For P slices
    /// this is the only motion; B slices add the List-1 grids below.
    mv_y: Vec<(i32, i32)>,
    inter_y: Vec<bool>,
    ref_idx_y: Vec<i32>,
    /// Per-4×4-block List-1 motion for B slices (`ref_idx1 = -1` = no L1).
    mv1: Vec<(i32, i32)>,
    ref_idx1: Vec<i32>,
    /// `RefPicList1` and B-slice flags (unused outside B slices).
    refs1: Vec<crate::RefFrame>,
    num_ref_active1: usize,
    is_b: bool,
    /// True if the stream's profile permits B-slices (`profile_idc != 66`). When
    /// false (Baseline / Constrained Baseline), `as_reference` skips the per-block
    /// motion (mv/ref_idx/ref_poc) that only B temporal/spatial direct ever reads.
    b_possible: bool,
    direct_spatial: bool,
    nnz_l_cache: [u8; 25],
    nnz_c_cache: [[u8; 9]; 2],
    /// Decoded-picture buffer (most-recent first); empty in I-slices. `ref_idx`
    /// indexes into this list.
    refs: Vec<crate::RefFrame>,
    /// `num_ref_idx_l0_active` for the current slice — drives whether `ref_idx`
    /// is coded (active > 1) and its te(v)/ue(v) form, independently of how many
    /// reference pictures actually exist (spec §7.4.5.1, §9.1).
    num_ref_active: usize,
    /// `constrained_intra_pred_flag`: when set, intra prediction may only use
    /// samples from intra-coded neighbors (inter neighbors are "not available").
    constrained_intra: bool,
    /// High-profile 4×4 scaling matrices in **raster** order, indexed by
    /// `[Y-intra, Cb-intra, Cr-intra, Y-inter, Cb-inter, Cr-inter]`. `None` = flat.
    scaling: Option<[[i32; 16]; 6]>,
    /// High-profile 8×8 luma scaling matrices in raster order `[Y-intra, Y-inter]`
    /// (4:2:0 has only these two). `None` = flat.
    scaling8: Option<[[i32; 64]; 2]>,
    /// `transform_8x8_mode_flag` from the PPS: enables `transform_size_8x8_flag`.
    transform_8x8_mode: bool,
    /// Per-macroblock `transform_size_8x8_flag` (for deblocking: internal 4×4
    /// luma edges of 8×8-transform MBs are not filtered).
    mb_t8x8: Vec<bool>,
    /// Explicit weighted-prediction tables, when active for this slice.
    weights: Option<WeightTable>,
    /// Current picture's `PicOrderCnt` (for temporal direct + implicit weighting).
    cur_poc: i32,
    /// `weighted_bipred_idc` (0 = none/average, 1 = explicit, 2 = implicit).
    weighted_bipred_idc: u8,
    /// `direct_8x8_inference_flag` (B direct co-located sub-block selection).
    direct_8x8_inference: bool,
}

/// Explicit weighted-prediction tables (spec §7.4.3.2 / §8.4.2.3.2). Per
/// reference list, per ref index: a luma `(weight, offset)` and two chroma
/// `(weight, offset)` (Cb, Cr). `log2` denominators are shared.
#[derive(Clone, Default)]
pub struct WeightTable {
    pub luma_log2_denom: i32,
    pub chroma_log2_denom: i32,
    /// `[list][ref_idx] = (weight, offset)`.
    pub luma: [Vec<(i32, i32)>; 2],
    /// `[list][ref_idx][cb=0/cr=1] = (weight, offset)`.
    pub chroma: [Vec<[(i32, i32); 2]>; 2],
}

impl WeightTable {
    /// Applies a single-list (uni-prediction) luma weight (spec §8.4.2.3.2).
    fn apply_luma(&self, sample: u8, list: usize, refi: usize) -> u8 {
        let (w, o) = self.luma[list][refi];
        let lwd = self.luma_log2_denom;
        let v = if lwd >= 1 {
            ((sample as i32 * w + (1 << (lwd - 1))) >> lwd) + o
        } else {
            sample as i32 * w + o
        };
        v.clamp(0, 255) as u8
    }

    /// Applies a single-list (uni-prediction) chroma weight for component `cc`.
    fn apply_chroma(&self, sample: u8, list: usize, refi: usize, cc: usize) -> u8 {
        let (w, o) = self.chroma[list][refi][cc];
        let cwd = self.chroma_log2_denom;
        let v = if cwd >= 1 {
            ((sample as i32 * w + (1 << (cwd - 1))) >> cwd) + o
        } else {
            sample as i32 * w + o
        };
        v.clamp(0, 255) as u8
    }
}

/// Why a macroblock could not be decoded.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MbError {
    Truncated,
    Unsupported(&'static str),
}

impl From<OutOfData> for MbError {
    fn from(_: OutOfData) -> Self {
        MbError::Truncated
    }
}

impl FrameDecoder {
    pub fn new(
        mb_w: usize,
        mb_h: usize,
        qp: u8,
        chroma_qp_offset: i32,
        refs: Vec<crate::RefFrame>,
        num_ref_active: usize,
        constrained_intra: bool,
        transform_8x8_mode: bool,
        b_possible: bool,
    ) -> Self {
        let (cw, ch) = (mb_w * 16, mb_h * 16);
        let (ccw, cch) = (cw / 2, ch / 2);
        Self {
            mb_w,
            mb_h,
            qp,
            cur_qp: qp,
            chroma_qp_offset,
            cw,
            ch,
            ccw,
            cch,
            rec_y: vec![0; cw * ch],
            rec_u: vec![0; ccw * cch],
            rec_v: vec![0; ccw * cch],
            mb_qp: vec![qp; mb_w * mb_h],
            slice_first_mb: 0,
            nnz_y: vec![0; (mb_w * 4) * (mb_h * 4)],
            nnz_c: [vec![0; (mb_w * 2) * (mb_h * 2)], vec![0; (mb_w * 2) * (mb_h * 2)]],
            modes_y: vec![2; (mb_w * 4) * (mb_h * 4)],
            coded_y: vec![false; (mb_w * 4) * (mb_h * 4)],
            mv_y: vec![(0, 0); (mb_w * 4) * (mb_h * 4)],
            inter_y: vec![false; (mb_w * 4) * (mb_h * 4)],
            ref_idx_y: vec![-1; (mb_w * 4) * (mb_h * 4)],
            mv1: vec![(0, 0); (mb_w * 4) * (mb_h * 4)],
            ref_idx1: vec![-1; (mb_w * 4) * (mb_h * 4)],
            refs1: Vec::new(),
            num_ref_active1: 0,
            is_b: false,
            b_possible,
            direct_spatial: true,
            nnz_l_cache: [0x80; 25],
            nnz_c_cache: [[0x80; 9]; 2],
            refs,
            num_ref_active,
            constrained_intra,
            scaling: None,
            scaling8: None,
            transform_8x8_mode,
            mb_t8x8: vec![false; mb_w * mb_h],
            weights: None,
            cur_poc: 0,
            weighted_bipred_idc: 0,
            direct_8x8_inference: false,
        }
    }

    /// Sets the explicit weighted-prediction tables for this slice.
    pub fn set_weights(&mut self, weights: WeightTable) {
        self.weights = Some(weights);
    }

    /// Applies explicit uni-prediction weighting to a motion-compensated partition
    /// (luma `pred_y` region + the two chroma planes), if weighting is active.
    /// `list` is the reference list and `refi` the partition's reference index.
    fn weight_partition(
        &self,
        pred_y: &mut [u8; 256],
        c_pred: &mut [[u8; 64]; 2],
        list: usize,
        refi: usize,
        rx: usize,
        ry: usize,
        rw: usize,
        rh: usize,
    ) {
        let Some(wt) = &self.weights else { return };
        for dy in 0..rh {
            for dx in 0..rw {
                let i = (ry + dy) * 16 + (rx + dx);
                pred_y[i] = wt.apply_luma(pred_y[i], list, refi);
            }
        }
        let (crx, cry, crw, crh) = (rx / 2, ry / 2, rw / 2, rh / 2);
        for cc in 0..2 {
            for dy in 0..crh {
                for dx in 0..crw {
                    let i = (cry + dy) * 8 + (crx + dx);
                    c_pred[cc][i] = wt.apply_chroma(c_pred[cc][i], list, refi, cc);
                }
            }
        }
    }

    /// Sets the High-profile scaling matrices (raster order: six 4×4 lists, two
    /// 8×8 luma lists). The caller un-zig-zags the SPS lists. Flat is the default.
    pub fn set_scaling(&mut self, scaling: [[i32; 16]; 6], scaling8: [[i32; 64]; 2]) {
        self.scaling = Some(scaling);
        self.scaling8 = Some(scaling8);
    }

    /// Dequantizes a 4×4 AC block with scaling list `list` (flat if none active).
    fn dequant(&self, levels: &[i32; 16], qp: u8, list: usize) -> [i32; 16] {
        match &self.scaling {
            Some(s) => dequantize_weighted(levels, qp, &s[list]),
            None => dequantize(levels, qp),
        }
    }

    /// Inverse-quantizes the I_16x16 luma DC with scaling list `list`'s DC weight.
    fn dequant_luma_dc(&self, levels: &[i32; 16], qp: u8, list: usize) -> [i32; 16] {
        match &self.scaling {
            Some(s) => inverse_quant_luma_dc_weighted(levels, qp, s[list][0]),
            None => inverse_quant_luma_dc(levels, qp),
        }
    }

    /// Inverse-quantizes a chroma DC block with scaling list `list`'s DC weight.
    fn dequant_chroma_dc(&self, levels: &[i32; 4], qp: u8, list: usize) -> [i32; 4] {
        match &self.scaling {
            Some(s) => inverse_quant_chroma_dc_weighted(levels, qp, s[list][0]),
            None => inverse_quant_chroma_dc(levels, qp),
        }
    }

    /// Sets the B-slice context for the slice about to be decoded: `RefPicList1`,
    /// its active count, and the direct-mode flag.
    #[allow(clippy::too_many_arguments)]
    pub fn set_b_context(
        &mut self,
        refs1: Vec<crate::RefFrame>,
        num_ref_active1: usize,
        direct_spatial: bool,
        cur_poc: i32,
        weighted_bipred_idc: u8,
        direct_8x8_inference: bool,
    ) {
        self.is_b = true;
        self.refs1 = refs1;
        self.num_ref_active1 = num_ref_active1;
        self.direct_spatial = direct_spatial;
        self.cur_poc = cur_poc;
        self.weighted_bipred_idc = weighted_bipred_idc;
        self.direct_8x8_inference = direct_8x8_inference;
    }

    /// Steps the running luma QP by a `mb_qp_delta` (spec §7.4.5, 8-bit depth):
    /// `QPy = (QPy_prev + delta + 52) % 52`.
    fn step_qp(&mut self, delta: i32) {
        self.cur_qp = (self.cur_qp as i32 + delta + 52).rem_euclid(52) as u8;
    }

    /// Maps a luma QP to its chroma QP, applying `chroma_qp_index_offset`
    /// (spec §8.5.8): `QPc = qpc_table(Clip3(0, 51, QPy + offset))`.
    fn chroma_qp_for(&self, qp_y: u8) -> u8 {
        let qpi = (qp_y as i32 + self.chroma_qp_offset).clamp(0, 51) as u8;
        chroma_qp(qpi)
    }

    /// Resets per-slice state before decoding a continuation slice of the same
    /// picture: the running QP (each slice carries its own `slice_qp`) and the
    /// reference list (each slice may reorder it).
    pub fn begin_slice(&mut self, slice_qp: u8, refs: Vec<crate::RefFrame>, num_ref_active: usize) {
        self.cur_qp = slice_qp;
        self.qp = slice_qp;
        self.refs = refs;
        self.num_ref_active = num_ref_active;
        self.weights = None; // re-set per slice if a pred_weight_table is present
    }

    /// Whether the neighbor macroblock at `(nbx, nby)` is in the slice currently
    /// being decoded (address ≥ the slice's first MB). For single-slice pictures
    /// `slice_first_mb == 0`, so this is always true and prediction is unchanged.
    #[inline]
    fn nbr_in_slice(&self, nbx: usize, nby: usize) -> bool {
        nby * self.mb_w + nbx >= self.slice_first_mb
    }

    /// Whether the neighbor 4×4 block at `(nbx, nby)` may contribute to intra
    /// prediction. With `constrained_intra_pred`, an inter-coded neighbor is
    /// treated as unavailable (spec §8.3.1.2.{1,2}); otherwise always usable.
    #[inline]
    fn intra_nbr_ok(&self, nbx: usize, nby: usize) -> bool {
        !self.constrained_intra || !self.inter_y[nby * (self.mb_w * 4) + nbx]
    }

    fn mv_neighbors(&self, mb_x: usize, mb_y: usize) -> [MvNeighbor; 3] {
        let w4 = self.mb_w * 4;
        let get = |avail: bool, bx: isize, by: isize| {
            if avail {
                let idx = by as usize * w4 + bx as usize;
                MvNeighbor {
                    available: true,
                    mv: self.mv_y[idx],
                    ref_idx: self.ref_idx_y[idx],
                }
            } else {
                MvNeighbor::NONE
            }
        };
        let (bx, by) = (mb_x as isize * 4, mb_y as isize * 4);
        let a = get(mb_x > 0 && self.nbr_in_slice(mb_x - 1, mb_y), bx - 1, by);
        let b = get(mb_y > 0 && self.nbr_in_slice(mb_x, mb_y - 1), bx, by - 1);
        let c = if mb_y > 0 && mb_x + 1 < self.mb_w && self.nbr_in_slice(mb_x + 1, mb_y - 1) {
            get(true, bx + 4, by - 1)
        } else {
            get(mb_x > 0 && mb_y > 0 && self.nbr_in_slice(mb_x - 1, mb_y - 1), bx - 1, by - 1)
        };
        [a, b, c]
    }

    fn mv_neighbors_block(&self, pbx: isize, pby: isize, pwb: isize) -> [MvNeighbor; 3] {
        let _g = rusty_h264_common::prof::scope(rusty_h264_common::prof::Stage::Neighbors);
        let (w4, h4) = ((self.mb_w * 4) as isize, (self.mb_h * 4) as isize);
        let get = |bx: isize, by: isize| -> MvNeighbor {
            // Available iff inside the frame, decoded, and in the current slice.
            if bx < 0
                || by < 0
                || bx >= w4
                || by >= h4
                || !self.coded_y[(by * w4 + bx) as usize]
                || !self.nbr_in_slice(bx as usize / 4, by as usize / 4)
            {
                MvNeighbor::NONE
            } else {
                let idx = (by * w4 + bx) as usize;
                MvNeighbor { available: true, mv: self.mv_y[idx], ref_idx: self.ref_idx_y[idx] }
            }
        };
        let a = get(pbx - 1, pby);
        let b = get(pbx, pby - 1);
        let mut c = get(pbx + pwb, pby - 1);
        if !c.available {
            c = get(pbx - 1, pby - 1);
        }
        [a, b, c]
    }

    fn skip_mv(&self, mb_x: usize, mb_y: usize) -> (i32, i32) {
        let [a, b, c] = self.mv_neighbors(mb_x, mb_y);
        if !a.available
            || !b.available
            || (a.ref_idx == 0 && a.mv == (0, 0))
            || (b.ref_idx == 0 && b.mv == (0, 0))
        {
            (0, 0)
        } else {
            predict_mv(a, b, c, 0)
        }
    }

    fn set_mb_mv(&mut self, mb_x: usize, mb_y: usize, mv: (i32, i32), inter: bool, refi: i32) {
        let w4 = self.mb_w * 4;
        for dy in 0..4 {
            for dx in 0..4 {
                let idx = (mb_y * 4 + dy) * w4 + (mb_x * 4 + dx);
                self.mv_y[idx] = mv;
                self.inter_y[idx] = inter;
                self.ref_idx_y[idx] = if inter { refi } else { -1 };
            }
        }
    }

    /// Commit one inter partition's motion into the 4×4 grid (ref 0, 1-ref P).
    /// `(rx,ry,rw,rh)` are MB-relative luma pixels; committing before the next
    /// partition's prediction is what lets a later partition predict from it.
    fn commit_inter_grid(&mut self, mb_x: usize, mb_y: usize, rx: usize, ry: usize, rw: usize, rh: usize, mv: (i32, i32), refi: i8) {
        let w4 = self.mb_w * 4;
        for by in ry / 4..ry / 4 + rh / 4 {
            for bx in rx / 4..rx / 4 + rw / 4 {
                let idx = (mb_y * 4 + by) * w4 + (mb_x * 4 + bx);
                self.mv_y[idx] = mv;
                self.inter_y[idx] = true;
                self.ref_idx_y[idx] = refi as i32;
                self.coded_y[idx] = true;
            }
        }
    }

    /// Snapshots the (deblocked) reconstruction as a reference picture.
    pub fn as_reference(&self) -> crate::RefFrame {
        // MV CAPTURE (`RFF_MV_DUMP=1`) — lets a harness read the motion field any
        // conformant H.264 stream carries, including x264's, using this decoder as
        // the parser. Diagnostic only; inert unless the env var is set.
        if mv_dump_on() {
            MV_DUMP.lock().unwrap().push(MvField {
                mb_w: self.mb_w,
                mb_h: self.mb_h,
                mv: self.mv_y.clone(),
                ref_idx: self.ref_idx_y.clone(),
                inter: self.inter_y.clone(),
            });
        }

        // The per-block motion (mv/ref_idx/ref_poc) is read ONLY by B temporal/spatial
        // direct (`col.mv/ref_idx/ref_poc`, guarded on `w4 != 0` + `idx < len`). On
        // Baseline/Constrained-Baseline streams (no B) it's pure waste — skip the two
        // grid clones + the per-block ref_poc resolve/alloc. `w4 = 0` makes the B
        // readers no-op even on malformed input.
        let (mv, ref_idx, ref_poc, w4) = if self.b_possible {
            (
                self.mv_y.clone(),
                self.ref_idx_y.clone(),
                // Resolve each block's List-0 ref index to the referenced picture's
                // POC, so temporal direct can map it into the current list.
                self.ref_idx_y
                    .iter()
                    .map(|&r| {
                        if r >= 0 {
                            self.refs.get(r as usize).map_or(i32::MIN, |f| f.poc)
                        } else {
                            i32::MIN
                        }
                    })
                    .collect(),
                self.mb_w * 4,
            )
        } else {
            (Vec::new(), Vec::new(), Vec::new(), 0)
        };
        crate::RefFrame {
            y: self.rec_y.clone(),
            u: self.rec_u.clone(),
            v: self.rec_v.clone(),
            cw: self.cw,
            ch: self.ch,
            frame_num: 0, // set by the caller (decode_slice knows frame_num)
            poc: 0,       // set by the caller
            mv,
            ref_idx,
            ref_poc,
            w4,
            long_term: false,
            long_term_idx: 0,
        }
    }

    fn nnz_cache_load(&mut self, mb_x: usize, mb_y: usize) {
        let w4 = self.mb_w * 4;
        let top_unavail = mb_y == 0 || !self.nbr_in_slice(mb_x, mb_y - 1);
        let left_unavail = mb_x == 0 || !self.nbr_in_slice(mb_x - 1, mb_y);
        for lbx in 0..4 {
            self.nnz_l_cache[1 + lbx] =
                if top_unavail { 0x80 } else { self.nnz_y[(mb_y * 4 - 1) * w4 + (mb_x * 4 + lbx)] };
        }
        for lby in 0..4 {
            self.nnz_l_cache[(lby + 1) * 5] =
                if left_unavail { 0x80 } else { self.nnz_y[(mb_y * 4 + lby) * w4 + (mb_x * 4 - 1)] };
        }
    }
    #[inline]
    fn nc_pred(&self, lbx: usize, lby: usize) -> i32 {
        let left = self.nnz_l_cache[(lby + 1) * 5 + lbx] as i32;
        let top = self.nnz_l_cache[lby * 5 + (lbx + 1)] as i32;
        let r = left + top;
        if r < 0x80 { (r + 1) >> 1 } else { r & 0x7f }
    }
    #[inline]
    fn nnz_cache_set(&mut self, lbx: usize, lby: usize, total: u8) {
        self.nnz_l_cache[(lby + 1) * 5 + (lbx + 1)] = total;
    }
    fn chroma_cache_load(&mut self, mb_x: usize, mb_y: usize) {
        let w2 = self.mb_w * 2;
        let top_unavail = mb_y == 0 || !self.nbr_in_slice(mb_x, mb_y - 1);
        let left_unavail = mb_x == 0 || !self.nbr_in_slice(mb_x - 1, mb_y);
        for c in 0..2 {
            for bx in 0..2 {
                self.nnz_c_cache[c][1 + bx] =
                    if top_unavail { 0x80 } else { self.nnz_c[c][(mb_y * 2 - 1) * w2 + (mb_x * 2 + bx)] };
            }
            for by in 0..2 {
                self.nnz_c_cache[c][(by + 1) * 3] =
                    if left_unavail { 0x80 } else { self.nnz_c[c][(mb_y * 2 + by) * w2 + (mb_x * 2 - 1)] };
            }
        }
    }
    #[inline]
    fn chroma_nc_pred(&self, c: usize, bx: usize, by: usize) -> i32 {
        let left = self.nnz_c_cache[c][(by + 1) * 3 + bx] as i32;
        let top = self.nnz_c_cache[c][by * 3 + (bx + 1)] as i32;
        let r = left + top;
        if r < 0x80 { (r + 1) >> 1 } else { r & 0x7f }
    }
    #[inline]
    fn chroma_nnz_cache_set(&mut self, c: usize, bx: usize, by: usize, total: u8) {
        self.nnz_c_cache[c][(by + 1) * 3 + (bx + 1)] = total;
    }

    /// Decodes one slice's macroblocks (raster order) starting at `first_mb`,
    /// until `more_rbsp_data()` is exhausted or the picture is full. Returns the
    /// next macroblock address (= total when the picture is complete). In a
    /// P-slice each macroblock is preceded by `mb_skip_run`.
    /// CABAC slice-data decode (docs/cabac-decode-plan.md), brought up brick by brick
    /// against the instrumented openh264 oracle. Phase 1: verify engine init; the
    /// syntax layer (Phase 2+) is WIP.
    #[allow(clippy::too_many_arguments)]
    pub fn decode_slice_data_cabac(
        &mut self,
        rbsp: &[u8],
        start_byte: usize,
        slice_qp: u8,
        cabac_init_idc: u32,
        is_i: bool,
        is_p: bool,
        first_mb: usize,
    ) -> Result<usize, MbError> {
        let mut cab = crate::cabac::Cabac::new(rbsp, start_byte, slice_qp as i32, cabac_init_idc, is_i);
        let (range, _offset) = cab.dbg_state();
        let trace = std::env::var_os("RH_CABAC_TRACE").is_some();
        debug_assert_eq!(range, 510, "CABAC init range must be 510");

        const I16_CBP: [u32; 6] = [0, 16, 32, 15, 31, 47];
        let mbw = self.mb_w;
        let total = self.mb_w * self.mb_h;
        // Per-MB neighbour state (single-slice assumption: avail == in-bounds).
        let mut cat = vec![255u8; total]; // 0=I4x4, 2=I16, 255=unavailable
        let mut mb_cbp = vec![0u8; total];
        let mut cmode = vec![-1i32; total]; // chroma pred mode
        let mut mb_nzc = vec![[0u8; 24]; total]; // 16 luma raster + 8 chroma
        let mut cbf_dc = vec![0u16; total];
        let mut mb_skip = vec![false; total];
        let mut mb_ref = vec![[-1i8; 16]; total]; // per-4×4-block List-0 ref (-1 = intra)
        let mut mb_mvd = vec![[[0i16; 2]; 16]; total]; // per-block mvd (for mvd ctxInc)
        let mut mb_ref1 = vec![[-1i8; 16]; total]; // B: per-block List-1 ref (-1 = not in list)
        let mut mb_mvd1 = vec![[[0i16; 2]; 16]; total]; // B: per-block List-1 mvd (ctxInc)
        let mut mb_direct = vec![false; total]; // B: MB is (skip/)direct — for mb_type ctxInc
        let mut last_delta_qp = 0i32;
        let mut addr = first_mb;

        loop {
            // BOUND the entropy-coded loop. `decode_terminate` is the only exit, and a
            // mutated stream can simply never produce it — the arithmetic decoder
            // zero-fills past the end of the buffer and keeps yielding symbols. Without
            // this the loop walks `addr` past the picture and indexes out of bounds.
            // (Surfaced by the fuzzer the moment CABAC became the default; the CAVLC
            // slice loop already had its own bound.)
            if addr >= total {
                return Err(MbError::Truncated);
            }
            let (mbx, mby) = (addr % mbw, addr / mbw);
            let left = (mbx > 0).then(|| addr - 1);
            let top = (mby > 0).then(|| addr - mbw);

            // Brick 3.1/3.2: P-slice mb_skip_flag, then mb_type (P mb_type is neighbour-
            // independent; intra sub-types map to the I dispatch below).
            let mb_type;
            if is_p {
                let sctx = 11
                    + left.map_or(0, |a| (!mb_skip[a]) as usize)
                    + top.map_or(0, |a| (!mb_skip[a]) as usize);
                if parse_mb_skip_cabac(&mut cab, sctx) {
                    mb_skip[addr] = true;
                    cat[addr] = 100; // inter (not I16/PCM) for neighbour context
                    last_delta_qp = 0; // skip codes no mb_qp_delta → delta ctxInc resets
                    // P_Skip recon reuses the entropy-free CAVLC primitive verbatim: it
                    // takes no bit-reader (skip has no coded syntax past the flag), just
                    // predicts the skip MV, motion-compensates, and commits the grid.
                    self.decode_p_skip(mbx, mby)?;
                    self.mb_qp[addr] = self.cur_qp; // skip inherits QPy
                    let eos = cab.decode_terminate();
                    addr += 1;
                    if eos || addr >= total {
                        break;
                    }
                    continue;
                }
                let mbt = parse_mb_type_p_cabac(&mut cab);
                if mbt == 30 {
                    return Err(MbError::Unsupported("CABAC I_PCM (WIP)"));
                }
                if mbt <= 3 {
                    // Inter MB (Bricks 3.3/3.4/3.5). 1-ref stream → ref_idx not coded (ref=0).
                    // Build the 30-entry mvd/ref neighbour cache (openh264 WelsFillCacheInterCabac).
                    let mut mvdc = [[0i16; 2]; 30];
                    let mut refc = [-1i8; 30];
                    if let Some(l) = left {
                        for (ci, bi) in [(6usize, 3usize), (12, 7), (18, 11), (24, 15)] {
                            refc[ci] = mb_ref[l][bi];
                            mvdc[ci] = mb_mvd[l][bi];
                        }
                    }
                    if let Some(t) = top {
                        for (ci, bi) in [(1usize, 12usize), (2, 13), (3, 14), (4, 15)] {
                            refc[ci] = mb_ref[t][bi];
                            mvdc[ci] = mb_mvd[t][bi];
                        }
                    }
                    if mbx > 0 && mby > 0 {
                        let a = addr - mbw - 1;
                        (refc[0], mvdc[0]) = (mb_ref[a][15], mb_mvd[a][15]);
                    }
                    if mby > 0 && mbx + 1 < mbw {
                        let a = addr - mbw + 1;
                        (refc[5], mvdc[5]) = (mb_ref[a][12], mb_mvd[a][12]);
                    }
                    let mut mmvd = [[0i16; 2]; 16];
                    let mut mref = [0i8; 16];
                    // mb_pred (spec 7.3.5.1): all ref_idx_l0 FIRST (only when >1 active
                    // ref), then all mvd + ref-aware predict + commit. `refidx!` parses one
                    // partition's ref_idx (ctxIdxOffset 54, ctx from neighbour refc) and
                    // seeds refc so a later partition's ref/mvd context sees it — mirror
                    // of the encoder's two-phase emit_mb_cabac_p_inter.
                    macro_rules! refidx {
                        ($pi:expr, $zb:expr) => {{
                            if self.num_ref_active > 1 {
                                let s = CACHE30[$pi];
                                let c0 = (refc[s - 1] > 0) as usize + 2 * (refc[s - 6] > 0) as usize;
                                let r = parse_ref_idx_cabac(&mut cab, c0);
                                for &zb in $zb.iter() {
                                    refc[CACHE30[zb]] = r;
                                }
                                r
                            } else {
                                0i8
                            }
                        }};
                    }
                    macro_rules! part {
                        ($pi:expr, $zb:expr, $pred:expr, $rx:expr, $ry:expr, $rw:expr, $rh:expr, $refi:expr) => {{
                            let (mvx, mvy) = parse_mvd_partition(&mut cab, $pi, $zb, &mut mvdc, &mut refc, &mut mmvd, &mut mref, $refi);
                            let [na, nb, nc] = self.mv_neighbors_block(
                                (mbx * 4 + $rx / 4) as isize,
                                (mby * 4 + $ry / 4) as isize,
                                ($rw / 4) as isize,
                            );
                            let pmv = $pred(na, nb, nc);
                            self.commit_inter_grid(mbx, mby, $rx, $ry, $rw, $rh, (pmv.0 + mvx, pmv.1 + mvy), $refi);
                        }};
                    }
                    match mbt {
                        0 => {
                            let r0 = refidx!(0, &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]);
                            part!(0, &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15], |a, b, c| predict_partition_mv(0, 0, a, b, c, r0 as i32), 0, 0, 16, 16, r0);
                        }
                        1 => {
                            let r0 = refidx!(0, &[0, 1, 2, 3, 4, 5, 6, 7]);
                            let r1 = refidx!(8, &[8, 9, 10, 11, 12, 13, 14, 15]);
                            part!(0, &[0, 1, 2, 3, 4, 5, 6, 7], |a, b, c| predict_partition_mv(1, 0, a, b, c, r0 as i32), 0, 0, 16, 8, r0);
                            part!(8, &[8, 9, 10, 11, 12, 13, 14, 15], |a, b, c| predict_partition_mv(1, 1, a, b, c, r1 as i32), 0, 8, 16, 8, r1);
                        }
                        2 => {
                            let r0 = refidx!(0, &[0, 1, 2, 3, 8, 9, 10, 11]);
                            let r1 = refidx!(4, &[4, 5, 6, 7, 12, 13, 14, 15]);
                            part!(0, &[0, 1, 2, 3, 8, 9, 10, 11], |a, b, c| predict_partition_mv(2, 0, a, b, c, r0 as i32), 0, 0, 8, 16, r0);
                            part!(4, &[4, 5, 6, 7, 12, 13, 14, 15], |a, b, c| predict_partition_mv(2, 1, a, b, c, r1 as i32), 8, 0, 8, 16, r1);
                        }
                        _ => {
                            // P_8x8: 4 sub_mb_types, then 4 ref_idx (one per 8×8), then mvd.
                            let mut subt = [0u32; 4];
                            for st in &mut subt {
                                *st = parse_sub_mb_type_p_cabac(&mut cab);
                            }
                            let mut pr = [0i8; 4];
                            for (i, r) in pr.iter_mut().enumerate() {
                                let b = i * 4;
                                *r = refidx!(b, &[b, b + 1, b + 2, b + 3]);
                            }
                            for i in 0..4usize {
                                let b = i * 4;
                                let (ox, oy) = ((i % 2) * 8, (i / 2) * 8); // 8×8 pixel origin in MB
                                let ri = pr[i];
                                match subt[i] {
                                    0 => part!(b, &[b, b + 1, b + 2, b + 3], |a, b, c| predict_mv(a, b, c, ri as i32), ox, oy, 8, 8, ri),
                                    1 => {
                                        part!(b, &[b, b + 1], |a, b, c| predict_mv(a, b, c, ri as i32), ox, oy, 8, 4, ri);
                                        part!(b + 2, &[b + 2, b + 3], |a, b, c| predict_mv(a, b, c, ri as i32), ox, oy + 4, 8, 4, ri);
                                    }
                                    2 => {
                                        part!(b, &[b, b + 2], |a, b, c| predict_mv(a, b, c, ri as i32), ox, oy, 4, 8, ri);
                                        part!(b + 1, &[b + 1, b + 3], |a, b, c| predict_mv(a, b, c, ri as i32), ox + 4, oy, 4, 8, ri);
                                    }
                                    _ => {
                                        for j in 0..4usize {
                                            let (sx, sy) = ((j % 2) * 4, (j / 2) * 4);
                                            part!(b + j, &[b + j], |a, b, c| predict_mv(a, b, c, ri as i32), ox + sx, oy + sy, 4, 4, ri);
                                        }
                                    }
                                }
                            }
                        }
                    }
                    mb_ref[addr] = mref;
                    mb_mvd[addr] = mmvd;
                    cat[addr] = 100;

                    // Inter cbp + residual (is_intra = false → cbf default nA=nB=0).
                    let cbp = parse_cbp_cabac(&mut cab, top.map(|a| mb_cbp[a]), left.map(|a| mb_cbp[a]));
                    mb_cbp[addr] = cbp as u8;
                    let (cbp_luma, cbp_chroma) = (cbp & 15, cbp >> 4);
                    let mut nzc = [0xffu8; 48];
                    if let Some(t) = top {
                        let tnz = mb_nzc[t];
                        nzc[1..5].copy_from_slice(&tnz[12..16]);
                        (nzc[0], nzc[5], nzc[29]) = (0, 0, 0);
                        (nzc[6], nzc[7], nzc[30], nzc[31]) = (tnz[20], tnz[21], tnz[22], tnz[23]);
                    }
                    if let Some(l) = left {
                        let lnz = mb_nzc[l];
                        (nzc[8], nzc[16], nzc[24], nzc[32]) = (lnz[3], lnz[7], lnz[11], lnz[15]);
                        (nzc[13], nzc[21], nzc[37], nzc[45]) = (lnz[17], lnz[21], lnz[19], lnz[23]);
                    }
                    let mut cbfdc = 0u16;
                    let mut luma_scan = [[0i32; 16]; 16]; // per z-order 4×4 block (scan order)
                    let mut cdc = [[0i32; 4]; 2]; // chroma DC per plane (scan order)
                    let mut cac = [[[0i32; 16]; 4]; 2]; // chroma AC per plane, per 4×4 block
                    // A cbp==0 MB codes no mb_qp_delta → the next MB's delta ctxInc sees 0.
                    if cbp == 0 {
                        last_delta_qp = 0;
                    }
                    if cbp != 0 {
                        let ndc = (top.map(|a| cbf_dc[a]), left.map(|a| cbf_dc[a]));
                        let qpd = parse_mb_qp_delta_cabac(&mut cab, &mut last_delta_qp);
                        self.step_qp(qpd);
                        for id8 in 0..4usize {
                            if cbp_luma & (1 << id8) != 0 {
                                for id4 in 0..4usize {
                                    let iz = id8 * 4 + id4;
                                    parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, iz, RP_LUMA_4X4, false, ndc, &mut luma_scan[iz]);
                                }
                            } else {
                                for k in 0..4 {
                                    nzc[NZC_CACHE[id8 * 4 + k]] = 0;
                                }
                            }
                        }
                        if cbp_chroma >= 1 {
                            for i in 0..2usize {
                                parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, 16 + i * 4, RP_CHROMA_DC + i, false, ndc, &mut cdc[i]);
                            }
                        }
                        if cbp_chroma == 2 {
                            for i in 0..2usize {
                                for id4 in 0..4usize {
                                    parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, 16 + i * 4 + id4, RP_CHROMA_AC + i, false, ndc, &mut cac[i][id4]);
                                }
                            }
                        }
                    }
                    self.mb_qp[addr] = self.cur_qp;
                    cbf_dc[addr] = cbfdc;
                    let mut mn = [0u8; 24];
                    for k in 0..4 {
                        mn[k] = nzc[9 + k];
                        mn[4 + k] = nzc[17 + k];
                        mn[8 + k] = nzc[25 + k];
                        mn[12 + k] = nzc[33 + k];
                    }
                    (mn[16], mn[17], mn[20], mn[21]) = (nzc[14], nzc[15], nzc[22], nzc[23]);
                    (mn[18], mn[19], mn[22], mn[23]) = (nzc[38], nzc[39], nzc[46], nzc[47]);
                    // A block whose residual was skipped (cbp bit clear / no chroma AC)
                    // has 0 coeffs, not "unavailable" — export 0 so an intra neighbour's
                    // CBF ctxInc reads 0 (not the 0xff sentinel → is_intra default).
                    for v in mn.iter_mut() {
                        if *v == 0xff {
                            *v = 0;
                        }
                    }
                    mb_nzc[addr] = mn;

                    // ---- Recon: motion-comp (per 4×4 luma / co-located 2×2 chroma using the
                    // committed grid MV — the 6-tap/bilinear filter is per-output-pixel, so
                    // per-block MC is bit-identical to per-partition MC) + residual add via the
                    // SAME reconstruct_4x4 as intra, with the MC output as the prediction.
                    if self.refs.is_empty() {
                        return Err(MbError::Unsupported("inter without reference"));
                    }
                    let qp = self.cur_qp;
                    let qpc = self.chroma_qp_for(qp);
                    let (w4r, w2r) = (mbw * 4, mbw * 2);
                    let mut pred_y = [0u8; 256];
                    let mut c_pred = [[0u8; 64]; 2];
                    {
                        let (rh16, cch) = (self.mb_h * 16, self.mb_h * 8);
                        for by in 0..4usize {
                            for bx in 0..4usize {
                                let bidx = (mby * 4 + by) * w4r + (mbx * 4 + bx);
                                let mv = self.mv_y[bidx];
                                // Per-block reference (multi-ref P): ref_idx_l0 committed to the
                                // grid. Clamp — a corrupt stream can over-range it (never panic).
                                let refi = (self.ref_idx_y[bidx].max(0) as usize).min(self.refs.len() - 1);
                                let reference = &self.refs[refi];
                                let mut t = [0u8; 16];
                                mc_luma(&reference.y, self.cw, rh16, mbx * 16 + bx * 4, mby * 16 + by * 4, 4, 4, mv.0, mv.1, &mut t);
                                for dy in 0..4 {
                                    for dx in 0..4 {
                                        pred_y[(by * 4 + dy) * 16 + (bx * 4 + dx)] = t[dy * 4 + dx];
                                    }
                                }
                                for cc in 0..2 {
                                    let rc = if cc == 0 { &reference.u } else { &reference.v };
                                    let mut tc = [0u8; 4];
                                    mc_chroma(rc, self.ccw, cch, mbx * 8 + bx * 2, mby * 8 + by * 2, 2, 2, mv.0, mv.1, &mut tc);
                                    for dy in 0..2 {
                                        for dx in 0..2 {
                                            c_pred[cc][(by * 2 + dy) * 8 + (bx * 2 + dx)] = tc[dy * 2 + dx];
                                        }
                                    }
                                }
                            }
                        }
                    }
                    // Luma residual add (an uncoded block has zero residual → recon = pred).
                    for (blk, &(lbx, lby)) in LUMA_4X4_SCAN_XY.iter().enumerate() {
                        let qb = un_scan_4x4_dcac(&luma_scan[blk]);
                        let deq = self.dequant(&qb, qp, 3);
                        let predb: [i32; 16] = std::array::from_fn(|i| pred_y[(lby * 4 + i / 4) * 16 + (lbx * 4 + i % 4)] as i32);
                        let s = reconstruct_4x4(&deq, &predb);
                        store(&mut self.rec_y, self.cw, (mbx * 4 + lbx) * 4, (mby * 4 + lby) * 4, &s);
                        self.nnz_y[(mby * 4 + lby) * w4r + (mbx * 4 + lbx)] = luma_scan[blk].iter().filter(|&&v| v != 0).count() as u8;
                    }
                    // Chroma residual add (2×2 DC Hadamard in cdc; per-block AC in cac).
                    let mut c_dc = [[0i32; 4]; 2];
                    if cbp_chroma != 0 {
                        for c in 0..2 {
                            c_dc[c] = self.dequant_chroma_dc(&cdc[c], qpc, 4 + c);
                        }
                    }
                    for c in 0..2 {
                        for &(bx, by) in &CHROMA_4X4_SCAN_XY {
                            let mut ac = [0i32; 16];
                            if cbp_chroma == 2 {
                                un_scan_4x4_ac_into(&cac[c][by * 2 + bx], &mut ac);
                                self.nnz_c[c][(mby * 2 + by) * w2r + (mbx * 2 + bx)] =
                                    cac[c][by * 2 + bx].iter().filter(|&&v| v != 0).count() as u8;
                            }
                            let mut deq = self.dequant(&ac, qpc, 4 + c);
                            deq[0] = c_dc[c][by * 2 + bx];
                            let predb: [i32; 16] =
                                std::array::from_fn(|i| c_pred[c][(by * 4 + i / 4) * 8 + (bx * 4 + i % 4)] as i32);
                            let s = reconstruct_4x4(&deq, &predb);
                            let plane = if c == 0 { &mut self.rec_u } else { &mut self.rec_v };
                            store(plane, self.ccw, (mbx * 2 + bx) * 4, (mby * 2 + by) * 4, &s);
                        }
                    }

                    let eos = cab.decode_terminate();
                    addr += 1;
                    if eos || addr >= total {
                        break;
                    }
                    continue;
                }
                mb_type = mbt - 5; // 5→0 (I_4x4), 6..29→1..24 (I_16x16)
            } else if self.is_b {
                // B-slice: mb_skip_flag (ctx 24 + neighbour-not-skip), then B mb_type.
                let sctx = 24
                    + left.map_or(0, |a| (!mb_skip[a]) as usize)
                    + top.map_or(0, |a| (!mb_skip[a]) as usize);
                if parse_mb_skip_cabac(&mut cab, sctx) {
                    mb_skip[addr] = true;
                    cat[addr] = 100;
                    mb_direct[addr] = true;
                    last_delta_qp = 0; // skip codes no mb_qp_delta → delta ctxInc resets
                    // B_Skip recon reuses the entropy-free CAVLC primitive (spatial/temporal
                    // direct with no residual), which also commits the motion grid.
                    self.decode_b_skip(mbx, mby)?;
                    self.mb_qp[addr] = self.cur_qp;
                    // Skip/direct blocks contribute mvd 0 to a later MB's mvd ctxInc; the
                    // ref stays in-list so |mvd|=0 is summed (same result either way).
                    mb_ref[addr] = [0i8; 16];
                    mb_ref1[addr] = [0i8; 16];
                    let eos = cab.decode_terminate();
                    addr += 1;
                    if eos || addr >= total {
                        break;
                    }
                    continue;
                }
                let bci = left.map_or(0, |a| (!mb_direct[a]) as usize)
                    + top.map_or(0, |a| (!mb_direct[a]) as usize);
                let bmt = parse_mb_type_b_cabac(&mut cab, bci);
                if bmt < 23 {
                    // ---- B inter: parse motion (mvd L0/L1; ref not coded on this 1-ref
                    // stream) + residual. Recon (b_mc/direct) deferred to B.3. ----
                    let mut mvdc0 = [[0i16; 2]; 30];
                    let mut refc0 = [-1i8; 30];
                    let mut mvdc1 = [[0i16; 2]; 30];
                    let mut refc1 = [-1i8; 30];
                    // WelsFillCacheInterCabac, per list (L0 = mb_ref/mb_mvd, L1 = mb_ref1/mb_mvd1).
                    macro_rules! fill {
                        ($mrf:expr, $mmv:expr, $rc:expr, $mc:expr) => {{
                            if let Some(l) = left {
                                for (ci, bi) in [(6usize, 3usize), (12, 7), (18, 11), (24, 15)] {
                                    $rc[ci] = $mrf[l][bi];
                                    $mc[ci] = $mmv[l][bi];
                                }
                            }
                            if let Some(t) = top {
                                for (ci, bi) in [(1usize, 12usize), (2, 13), (3, 14), (4, 15)] {
                                    $rc[ci] = $mrf[t][bi];
                                    $mc[ci] = $mmv[t][bi];
                                }
                            }
                            if mbx > 0 && mby > 0 {
                                let a = addr - mbw - 1;
                                ($rc[0], $mc[0]) = ($mrf[a][15], $mmv[a][15]);
                            }
                            if mby > 0 && mbx + 1 < mbw {
                                let a = addr - mbw + 1;
                                ($rc[5], $mc[5]) = ($mrf[a][12], $mmv[a][12]);
                            }
                        }};
                    }
                    fill!(mb_ref, mb_mvd, refc0, mvdc0);
                    fill!(mb_ref1, mb_mvd1, refc1, mvdc1);
                    let mut mmvd0 = [[0i16; 2]; 16];
                    let mut mref0 = [-1i8; 16];
                    let mut mmvd1 = [[0i16; 2]; 16];
                    let mut mref1 = [-1i8; 16];
                    if self.refs.is_empty() || self.refs1.is_empty() {
                        return Err(MbError::Unsupported("B without references"));
                    }
                    // Recon (mirrors CAVLC decode_b_mb / decode_b_8x8): predict each list's
                    // MV off the committed grid + the CABAC-parsed mvd, commit, MC (bi-pred
                    // blend), then add the residual. Prediction reads mmvd0/mmvd1 (the mvd
                    // per raster block, splatted during the parse above).
                    let mut pred_y = [0u8; 256];
                    let mut c_pred = [[0u8; 64]; 2];

                    if bmt == 0 {
                        // B_Direct_16x16: no coded motion. A direct block contributes mvd 0
                        // to a later MB's mvd ctxInc with its ref in-list (|0| summed).
                        mb_direct[addr] = true;
                        (mref0, mref1) = ([0i8; 16], [0i8; 16]);
                        self.decode_b_direct(mbx, mby, 0, 0, 16, 16, &mut pred_y, &mut c_pred);
                    } else if bmt == 22 {
                        // B_8x8: 4 sub_mb_types, (ref not coded on 1-ref), then mvd
                        // list-major → sub-MB → sub-partition (openh264 order).
                        let mut subt = [0u32; 4];
                        for s in &mut subt {
                            *s = parse_sub_mb_type_b_cabac(&mut cab);
                        }
                        // A direct sub-partition contributes mvd 0 / ref in-list to the
                        // ctxInc — both the per-MB export and the within-MB 30-cache that a
                        // later (non-direct) sub in this MB reads.
                        for i in 0..4usize {
                            if subt[i] == 0 {
                                let b = i * 4;
                                for &zb in &[b, b + 1, b + 2, b + 3] {
                                    (mref0[G_SCAN4[zb]], mref1[G_SCAN4[zb]]) = (0, 0);
                                    (refc0[CACHE30[zb]], refc1[CACHE30[zb]]) = (0, 0);
                                }
                            }
                        }
                        for list in 0..2usize {
                            let (mmv, mrf, mc, rc) = if list == 0 {
                                (&mut mmvd0, &mut mref0, &mut mvdc0, &mut refc0)
                            } else {
                                (&mut mmvd1, &mut mref1, &mut mvdc1, &mut refc1)
                            };
                            for i in 0..4usize {
                                let st = subt[i];
                                if st == 0 || !b_sub_uses(st, list) {
                                    continue;
                                }
                                let b = i * 4;
                                for &(sx, sy, sw, sh) in b_sub_parts(st) {
                                    let mut zb = [0usize; 4];
                                    let mut n = 0;
                                    for ly in sy / 4..sy / 4 + sh / 4 {
                                        for lx in sx / 4..sx / 4 + sw / 4 {
                                            zb[n] = b + ly * 2 + lx;
                                            n += 1;
                                        }
                                    }
                                    parse_mvd_partition(&mut cab, zb[0], &zb[..n], mc, rc, mmv, mrf, 0);
                                }
                            }
                        }
                        // Recon each 8×8: direct sub → decode_b_direct; else per sub-part
                        // predict (median) + commit + MC.
                        for (p, &st) in subt.iter().enumerate() {
                            let (b8x, b8y) = ((p % 2) * 8, (p / 2) * 8);
                            if st == 0 {
                                self.decode_b_direct(mbx, mby, b8x, b8y, 8, 8, &mut pred_y, &mut c_pred);
                                continue;
                            }
                            for &(sx, sy, sw, sh) in b_sub_parts(st) {
                                let (px, py) = (b8x + sx, b8y + sy);
                                let mut mv = [(0i32, 0i32); 2];
                                for list in 0..2usize {
                                    if b_sub_uses(st, list) {
                                        let d = if list == 0 { mmvd0 } else { mmvd1 }[(py / 4) * 4 + px / 4];
                                        let n = self.mv_neighbors_list((mbx * 4 + px / 4) as isize, (mby * 4 + py / 4) as isize, (sw / 4) as isize, list);
                                        let pmv = predict_mv(n[0], n[1], n[2], 0);
                                        mv[list] = (pmv.0 + d[0] as i32, pmv.1 + d[1] as i32);
                                    }
                                }
                                let refi0 = if b_sub_uses(st, 0) { 0 } else { -1 };
                                let refi1 = if b_sub_uses(st, 1) { 0 } else { -1 };
                                self.b_set_motion(mbx, mby, px, py, sw, sh, refi0, mv[0], refi1, mv[1]);
                                self.b_mc(mbx, mby, px, py, sw, sh, refi0, mv[0], refi1, mv[1], &mut pred_y, &mut c_pred);
                            }
                        }
                    } else {
                        let (layout, mvmode, preds) = b_inter_layout(bmt);
                        let parts: &[(usize, &[usize])] = match mvmode {
                            0 => &[(0, &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])],
                            1 => &[(0, &[0, 1, 2, 3, 4, 5, 6, 7]), (8, &[8, 9, 10, 11, 12, 13, 14, 15])],
                            _ => &[(0, &[0, 1, 2, 3, 8, 9, 10, 11]), (4, &[4, 5, 6, 7, 12, 13, 14, 15])],
                        };
                        // mvd parse order: list-major, partition-minor (openh264
                        // ParseInterBMotionInfoCabac); the ctxInc reads the same-list cache.
                        for list in 0..2usize {
                            let (mmv, mrf, mc, rc) = if list == 0 {
                                (&mut mmvd0, &mut mref0, &mut mvdc0, &mut refc0)
                            } else {
                                (&mut mmvd1, &mut mref1, &mut mvdc1, &mut refc1)
                            };
                            for (p, &(pidx, zb)) in parts.iter().enumerate() {
                                if preds[p].uses(list) {
                                    parse_mvd_partition(&mut cab, pidx, zb, mc, rc, mmv, mrf, 0);
                                }
                            }
                        }
                        // Per-partition recon: predict each list's MV, commit, MC.
                        for (p, &(rx, ry, rw, rh)) in layout.iter().enumerate() {
                            let mut mv = [(0i32, 0i32); 2];
                            for list in 0..2usize {
                                if preds[p].uses(list) {
                                    let d = if list == 0 { mmvd0 } else { mmvd1 }[(ry / 4) * 4 + rx / 4];
                                    let n = self.mv_neighbors_list((mbx * 4 + rx / 4) as isize, (mby * 4 + ry / 4) as isize, (rw / 4) as isize, list);
                                    let pmv = predict_partition_mv(mvmode, p, n[0], n[1], n[2], 0);
                                    mv[list] = (pmv.0 + d[0] as i32, pmv.1 + d[1] as i32);
                                }
                            }
                            let refi0 = if preds[p].uses(0) { 0 } else { -1 };
                            let refi1 = if preds[p].uses(1) { 0 } else { -1 };
                            self.b_set_motion(mbx, mby, rx, ry, rw, rh, refi0, mv[0], refi1, mv[1]);
                            // Proper spec bi-prediction (average of L0+L1). NOTE: the CAVLC
                            // decode_b_mb replicates an openh264 bug here for a Bi 16×8/8×16
                            // partition; our pixel gate is ffmpeg (spec-correct), so we do NOT.
                            self.b_mc(mbx, mby, rx, ry, rw, rh, refi0, mv[0], refi1, mv[1], &mut pred_y, &mut c_pred);
                        }
                    }
                    mb_ref[addr] = mref0;
                    mb_mvd[addr] = mmvd0;
                    mb_ref1[addr] = mref1;
                    mb_mvd1[addr] = mmvd1;
                    cat[addr] = 100;

                    // Inter cbp + residual (identical to the P path).
                    let cbp = parse_cbp_cabac(&mut cab, top.map(|a| mb_cbp[a]), left.map(|a| mb_cbp[a]));
                    mb_cbp[addr] = cbp as u8;
                    let (cbp_luma, cbp_chroma) = (cbp & 15, cbp >> 4);
                    let mut nzc = [0xffu8; 48];
                    if let Some(t) = top {
                        let tnz = mb_nzc[t];
                        nzc[1..5].copy_from_slice(&tnz[12..16]);
                        (nzc[0], nzc[5], nzc[29]) = (0, 0, 0);
                        (nzc[6], nzc[7], nzc[30], nzc[31]) = (tnz[20], tnz[21], tnz[22], tnz[23]);
                    }
                    if let Some(l) = left {
                        let lnz = mb_nzc[l];
                        (nzc[8], nzc[16], nzc[24], nzc[32]) = (lnz[3], lnz[7], lnz[11], lnz[15]);
                        (nzc[13], nzc[21], nzc[37], nzc[45]) = (lnz[17], lnz[21], lnz[19], lnz[23]);
                    }
                    let mut cbfdc = 0u16;
                    let mut luma_scan = [[0i32; 16]; 16];
                    let mut cdc = [[0i32; 4]; 2];
                    let mut cac = [[[0i32; 16]; 4]; 2];
                    if cbp == 0 {
                        last_delta_qp = 0;
                    }
                    if cbp != 0 {
                        let ndc = (top.map(|a| cbf_dc[a]), left.map(|a| cbf_dc[a]));
                        let qpd = parse_mb_qp_delta_cabac(&mut cab, &mut last_delta_qp);
                        self.step_qp(qpd);
                        for id8 in 0..4usize {
                            if cbp_luma & (1 << id8) != 0 {
                                for id4 in 0..4usize {
                                    let iz = id8 * 4 + id4;
                                    parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, iz, RP_LUMA_4X4, false, ndc, &mut luma_scan[iz]);
                                }
                            } else {
                                for k in 0..4 {
                                    nzc[NZC_CACHE[id8 * 4 + k]] = 0;
                                }
                            }
                        }
                        if cbp_chroma >= 1 {
                            for i in 0..2usize {
                                parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, 16 + i * 4, RP_CHROMA_DC + i, false, ndc, &mut cdc[i]);
                            }
                        }
                        if cbp_chroma == 2 {
                            for i in 0..2usize {
                                for id4 in 0..4usize {
                                    parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, 16 + i * 4 + id4, RP_CHROMA_AC + i, false, ndc, &mut cac[i][id4]);
                                }
                            }
                        }
                    }
                    self.mb_qp[addr] = self.cur_qp;
                    cbf_dc[addr] = cbfdc;
                    let mut mn = [0u8; 24];
                    for k in 0..4 {
                        mn[k] = nzc[9 + k];
                        mn[4 + k] = nzc[17 + k];
                        mn[8 + k] = nzc[25 + k];
                        mn[12 + k] = nzc[33 + k];
                    }
                    (mn[16], mn[17], mn[20], mn[21]) = (nzc[14], nzc[15], nzc[22], nzc[23]);
                    (mn[18], mn[19], mn[22], mn[23]) = (nzc[38], nzc[39], nzc[46], nzc[47]);
                    // A block whose residual was skipped (cbp bit clear / no chroma AC)
                    // has 0 coeffs, not "unavailable" — export 0 so an intra neighbour's
                    // CBF ctxInc reads 0 (not the 0xff sentinel → is_intra default).
                    for v in mn.iter_mut() {
                        if *v == 0xff {
                            *v = 0;
                        }
                    }
                    mb_nzc[addr] = mn;
                    self.add_inter_residual(mbx, mby, &pred_y, &c_pred, &luma_scan, &cdc, &cac, cbp_chroma);

                    let eos = cab.decode_terminate();
                    addr += 1;
                    if eos || addr >= total {
                        break;
                    }
                    continue;
                }
                mb_type = bmt - 23; // 23→0 (I_4x4), 24..=47→1..24 (I_16x16), 48→25 (PCM)
                if mb_type == 25 {
                    return Err(MbError::Unsupported("CABAC I_PCM (WIP)"));
                }
            } else {
                let li = left.map_or(0, |a| (cat[a] >= 2) as usize);
                let ti = top.map_or(0, |a| (cat[a] >= 2) as usize);
                mb_type = parse_mb_type_i_cabac(&mut cab, li + ti);
                if mb_type == 25 {
                    return Err(MbError::Unsupported("CABAC I_PCM (WIP)"));
                }
            }
            // chroma-pred-mode ctxInc from neighbour chroma modes (1..=3).
            let cci = left.map_or(0, |a| (1..=3).contains(&cmode[a]) as usize)
                + top.map_or(0, |a| (1..=3).contains(&cmode[a]) as usize);

            if mb_type != 0 {
                // ---- I_16x16 (mb_type 1..=24): pred mode & cbp DERIVED from mb_type;
                // luma DC always coded. Syntax order: intra_chroma_pred_mode, mb_qp_delta,
                // luma DC (Hadamard), luma AC (if cbp_luma), chroma DC/AC. Mirrors the CAVLC
                // decode_i16, driven by the CABAC residual. ----
                let mt = mb_type - 1;
                let pred_mode = I16Mode::from_id(mt % 4);
                let cbp_chroma = (mt % 12) / 4;
                let cbp_luma_15 = mt / 12 == 1;
                let chroma_mode = parse_intra_chroma_pred_mode_cabac(&mut cab, cci) as u8;
                cmode[addr] = chroma_mode as i32;
                cat[addr] = 2;
                mb_cbp[addr] = ((cbp_chroma as u8) << 4) | if cbp_luma_15 { 15 } else { 0 };
                let w4 = self.mb_w * 4;

                let mut nzc = [0xffu8; 48];
                if let Some(t) = top {
                    let tn = mb_nzc[t];
                    nzc[1..5].copy_from_slice(&tn[12..16]);
                    (nzc[0], nzc[5], nzc[29]) = (0, 0, 0);
                    (nzc[6], nzc[7]) = (tn[20], tn[21]);
                    (nzc[30], nzc[31]) = (tn[22], tn[23]);
                }
                if let Some(l) = left {
                    let ln = mb_nzc[l];
                    (nzc[8], nzc[16], nzc[24], nzc[32]) = (ln[3], ln[7], ln[11], ln[15]);
                    (nzc[13], nzc[21], nzc[37], nzc[45]) = (ln[17], ln[21], ln[19], ln[23]);
                }

                let ndc = (top.map(|a| cbf_dc[a]), left.map(|a| cbf_dc[a]));
                let qpd = parse_mb_qp_delta_cabac(&mut cab, &mut last_delta_qp);
                self.step_qp(qpd);
                let qp = self.cur_qp;
                let mut cbfdc = 0u16;

                // Luma DC (iz=0, category I16_LUMA_DC, 16 coeffs) → Hadamard dequant.
                let mut dc_scan = [0i32; 16];
                parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, 0, RP_I16_DC, true, ndc, &mut dc_scan);
                let recon_dc = self.dequant_luma_dc(&un_scan_4x4_dcac(&dc_scan), qp, 0);

                // Luma AC (iz 0..15, category I16_LUMA_AC, 15 coeffs) when cbp_luma set.
                let mut q_blocks = [[0i32; 16]; 16];
                for (iz, &(lbx, lby)) in LUMA_4X4_SCAN_XY.iter().enumerate() {
                    let total = if cbp_luma_15 {
                        let mut ac = [0i32; 16];
                        let t = parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, iz, RP_I16_AC, true, ndc, &mut ac);
                        un_scan_4x4_ac_into(&ac, &mut q_blocks[lby * 4 + lbx]);
                        t as u8
                    } else {
                        nzc[NZC_CACHE[iz]] = 0;
                        0
                    };
                    self.nnz_y[(mby * 4 + lby) * w4 + (mbx * 4 + lbx)] = total;
                }

                let mut cdc = [[0i32; 4]; 2];
                let mut cac = [[[0i32; 16]; 4]; 2];
                if cbp_chroma >= 1 {
                    for i in 0..2usize {
                        parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, 16 + i * 4, RP_CHROMA_DC + i, true, ndc, &mut cdc[i]);
                    }
                }
                if cbp_chroma == 2 {
                    for i in 0..2usize {
                        for id4 in 0..4usize {
                            parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, 16 + i * 4 + id4, RP_CHROMA_AC + i, true, ndc, &mut cac[i][id4]);
                        }
                    }
                }

                // Luma recon: 16×16 intra prediction, then per-4×4 (dequant AC + injected DC).
                let top_ok = mby > 0 && self.nbr_in_slice(mbx, mby - 1) && self.intra_nbr_ok(mbx * 4, mby * 4 - 1);
                let left_ok = mbx > 0 && self.nbr_in_slice(mbx - 1, mby) && self.intra_nbr_ok(mbx * 4 - 1, mby * 4);
                let (lx, ly) = (mbx * 16, mby * 16);
                let mut t16 = [0u8; 16];
                let mut l16 = [0u8; 16];
                if top_ok {
                    t16.copy_from_slice(&self.rec_y[(ly - 1) * self.cw + lx..][..16]);
                }
                if left_ok {
                    for i in 0..16 {
                        l16[i] = self.rec_y[(ly + i) * self.cw + lx - 1];
                    }
                }
                let corner = if top_ok && left_ok { self.rec_y[(ly - 1) * self.cw + lx - 1] } else { 0 };
                let pred_l = luma16x16_pred(pred_mode, top_ok, left_ok, &t16, &l16, corner);
                for by in 0..4 {
                    for bx in 0..4 {
                        let mut deq = self.dequant(&q_blocks[by * 4 + bx], qp, 0);
                        deq[0] = recon_dc[by * 4 + bx];
                        let predb: [i32; 16] = std::array::from_fn(|i| pred_l[(by * 4 + i / 4) * 16 + (bx * 4 + i % 4)] as i32);
                        let s = reconstruct_4x4(&deq, &predb);
                        store(&mut self.rec_y, self.cw, lx + bx * 4, ly + by * 4, &s);
                        // I_16x16 blocks predict as DC for neighbour mode-prediction, and
                        // must be marked coded so a later I_4x4 MB's top-right availability
                        // (gather_i4 reads coded_y) sees this block as present.
                        self.modes_y[(mby * 4 + by) * w4 + (mbx * 4 + bx)] = 2;
                        self.coded_y[(mby * 4 + by) * w4 + (mbx * 4 + bx)] = true;
                    }
                }
                self.recon_chroma_cabac(mbx, mby, chroma_mode, &cdc, &cac, cbp_chroma, top_ok, left_ok);

                self.mb_qp[addr] = self.cur_qp;
                cbf_dc[addr] = cbfdc;
                let mut mn = [0u8; 24];
                for k in 0..4 {
                    mn[k] = nzc[9 + k];
                    mn[4 + k] = nzc[17 + k];
                    mn[8 + k] = nzc[25 + k];
                    mn[12 + k] = nzc[33 + k];
                }
                (mn[16], mn[17], mn[20], mn[21]) = (nzc[14], nzc[15], nzc[22], nzc[23]);
                (mn[18], mn[19], mn[22], mn[23]) = (nzc[38], nzc[39], nzc[46], nzc[47]);
                for v in mn.iter_mut() {
                    if *v == 0xff {
                        *v = 0;
                    }
                }
                mb_nzc[addr] = mn;

                let eos = cab.decode_terminate();
                addr += 1;
                if eos || addr >= total {
                    break;
                }
                continue;
            }
            cat[addr] = 0;
            let w4 = self.mb_w * 4;
            // Brick 2.4 + recon: derive & store each intra4x4 mode (prev-flag → the
            // neighbour-predicted mode, else rem), exactly as the CAVLC path.
            let mut modes = [2u8; 16]; // raster [lby*4+lbx]
            for &(lbx, lby) in &LUMA_4X4_SCAN_XY {
                let (bx, by) = (mbx * 4 + lbx, mby * 4 + lby);
                let predicted = self.predict_i4_mode(bx, by);
                let rr = parse_intra4x4_pred_mode_cabac(&mut cab);
                let actual = if rr < 0 {
                    predicted
                } else {
                    let rem = rr as u8;
                    if rem < predicted { rem } else { rem + 1 }
                };
                self.modes_y[by * w4 + bx] = actual;
                modes[lby * 4 + lbx] = actual;
            }
            let chroma_mode = parse_intra_chroma_pred_mode_cabac(&mut cab, cci) as u8;
            cmode[addr] = chroma_mode as i32;
            let cbp = parse_cbp_cabac(&mut cab, top.map(|a| mb_cbp[a]), left.map(|a| mb_cbp[a]));
            mb_cbp[addr] = cbp as u8;
            let (cbp_luma, cbp_chroma) = (cbp & 15, cbp >> 4);

            // Build the padded nzc cache from neighbours (openh264 WelsFillCacheNonZeroCount).
            let mut nzc = [0xffu8; 48];
            if let Some(t) = top {
                let tn = mb_nzc[t];
                nzc[1..5].copy_from_slice(&tn[12..16]);
                (nzc[0], nzc[5], nzc[29]) = (0, 0, 0);
                (nzc[6], nzc[7]) = (tn[20], tn[21]);
                (nzc[30], nzc[31]) = (tn[22], tn[23]);
            }
            if let Some(l) = left {
                let ln = mb_nzc[l];
                (nzc[8], nzc[16], nzc[24], nzc[32]) = (ln[3], ln[7], ln[11], ln[15]);
                (nzc[13], nzc[21], nzc[37], nzc[45]) = (ln[17], ln[21], ln[19], ln[23]);
            }

            // Bricks 2.6 + 2.7: mb_qp_delta + residual (I_4x4 luma 4×4 + chroma DC/AC),
            // storing scan-order coefficients for recon.
            let mut cbfdc = 0u16;
            let mut luma_scan = [[0i32; 16]; 16]; // per z-order 4×4 block
            let mut cdc = [[0i32; 4]; 2]; // chroma DC per plane
            let mut cac = [[[0i32; 16]; 4]; 2]; // chroma AC per plane, per 4×4 block
            if cbp == 0 {
                last_delta_qp = 0;
            }
            if cbp != 0 {
                let ndc = (top.map(|a| cbf_dc[a]), left.map(|a| cbf_dc[a]));
                let qpd = parse_mb_qp_delta_cabac(&mut cab, &mut last_delta_qp);
                self.step_qp(qpd);
                for id8 in 0..4usize {
                    if cbp_luma & (1 << id8) != 0 {
                        for id4 in 0..4usize {
                            let iz = id8 * 4 + id4;
                            parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, iz, RP_LUMA_4X4, true, ndc, &mut luma_scan[iz]);
                        }
                    } else {
                        for k in 0..4 {
                            nzc[NZC_CACHE[id8 * 4 + k]] = 0;
                        }
                    }
                }
                if cbp_chroma >= 1 {
                    for i in 0..2usize {
                        parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, 16 + i * 4, RP_CHROMA_DC + i, true, ndc, &mut cdc[i]);
                    }
                }
                if cbp_chroma == 2 {
                    for i in 0..2usize {
                        for id4 in 0..4usize {
                            parse_residual_cabac(&mut cab, &mut nzc, &mut cbfdc, 16 + i * 4 + id4, RP_CHROMA_AC + i, true, ndc, &mut cac[i][id4]);
                        }
                    }
                }
            }
            self.mb_qp[addr] = self.cur_qp;
            cbf_dc[addr] = cbfdc;
            // Extract the MB's nzc (raster luma + chroma) for future neighbours.
            let mut mn = [0u8; 24];
            for k in 0..4 {
                mn[k] = nzc[9 + k];
                mn[4 + k] = nzc[17 + k];
                mn[8 + k] = nzc[25 + k];
                mn[12 + k] = nzc[33 + k];
            }
            (mn[16], mn[17], mn[20], mn[21]) = (nzc[14], nzc[15], nzc[22], nzc[23]);
            (mn[18], mn[19], mn[22], mn[23]) = (nzc[38], nzc[39], nzc[46], nzc[47]);
            for v in mn.iter_mut() {
                if *v == 0xff {
                    *v = 0;
                }
            }
            mb_nzc[addr] = mn;

            // ---- Brick 4.3a: recon (I_4x4 luma + chroma) via the CAVLC-proven primitives.
            let qp = self.cur_qp;
            let top_ok = mby > 0 && self.nbr_in_slice(mbx, mby - 1) && self.intra_nbr_ok(mbx * 4, mby * 4 - 1);
            let left_ok = mbx > 0 && self.nbr_in_slice(mbx - 1, mby) && self.intra_nbr_ok(mbx * 4 - 1, mby * 4);
            for (blk, &(lbx, lby)) in LUMA_4X4_SCAN_XY.iter().enumerate() {
                let (bx, by) = (mbx * 4 + lbx, mby * 4 + lby);
                let (px, py) = (bx * 4, by * 4);
                let at = lby > 0 || top_ok;
                let al = lbx > 0 || left_ok;
                let qb = un_scan_4x4_dcac(&luma_scan[blk]);
                self.nnz_y[by * w4 + bx] = luma_scan[blk].iter().filter(|&&v| v != 0).count() as u8;
                let (t, l, corner) = self.gather_i4(px, py, at, al, bx, by);
                let pred = intra4x4_pred(modes[lby * 4 + lbx], at, al, &t, &l, corner);
                let predb = std::array::from_fn(|i| pred[i] as i32);
                let s = reconstruct_4x4(&self.dequant(&qb, qp, 0), &predb);
                store(&mut self.rec_y, self.cw, px, py, &s);
                self.coded_y[by * w4 + bx] = true;
            }
            self.recon_chroma_cabac(mbx, mby, chroma_mode, &cdc, &cac, cbp_chroma, top_ok, left_ok);

            // Brick 2.1: end_of_slice_flag.
            let eos = cab.decode_terminate();
            addr += 1;
            if eos || addr >= total {
                break;
            }
        }
        if trace {
            eprintln!("# CABAC decoded {} MBs (of {total})", addr - first_mb);
        }
        Ok(addr)
    }

    /// CABAC chroma recon (mirrors `decode_chroma`'s reconstruction, driven by the
    /// CABAC-parsed DC/AC coefficients). `cdc[c]` = 2×2 DC (scan order); `cac[c][blk]`
    /// = 15 AC per 4×4 block (scan order).
    #[allow(clippy::too_many_arguments)]
    /// Add a CABAC-parsed inter residual to an already-built motion-comp prediction
    /// (`pred_y`/`c_pred`), writing the reconstruction. Shared by the P and B inter
    /// paths — same `reconstruct_4x4` as intra, MC output as the prediction, inter
    /// scaling lists (luma 3 / chroma 4+c). `luma_scan[z]`/`cdc`/`cac` are the
    /// scan-order coefficients; uncoded blocks are zero so recon == prediction.
    #[allow(clippy::too_many_arguments)]
    fn add_inter_residual(
        &mut self,
        mb_x: usize,
        mb_y: usize,
        pred_y: &[u8; 256],
        c_pred: &[[u8; 64]; 2],
        luma_scan: &[[i32; 16]; 16],
        cdc: &[[i32; 4]; 2],
        cac: &[[[i32; 16]; 4]; 2],
        cbp_chroma: u32,
    ) {
        let qp = self.cur_qp;
        let qpc = self.chroma_qp_for(qp);
        let (w4r, w2r) = (self.mb_w * 4, self.mb_w * 2);
        for (blk, &(lbx, lby)) in LUMA_4X4_SCAN_XY.iter().enumerate() {
            let qb = un_scan_4x4_dcac(&luma_scan[blk]);
            let deq = self.dequant(&qb, qp, 3);
            let predb: [i32; 16] = std::array::from_fn(|i| pred_y[(lby * 4 + i / 4) * 16 + (lbx * 4 + i % 4)] as i32);
            let s = reconstruct_4x4(&deq, &predb);
            store(&mut self.rec_y, self.cw, (mb_x * 4 + lbx) * 4, (mb_y * 4 + lby) * 4, &s);
            self.nnz_y[(mb_y * 4 + lby) * w4r + (mb_x * 4 + lbx)] =
                luma_scan[blk].iter().filter(|&&v| v != 0).count() as u8;
        }
        let mut c_dc = [[0i32; 4]; 2];
        if cbp_chroma != 0 {
            for c in 0..2 {
                c_dc[c] = self.dequant_chroma_dc(&cdc[c], qpc, 4 + c);
            }
        }
        for c in 0..2 {
            for &(bx, by) in &CHROMA_4X4_SCAN_XY {
                let mut ac = [0i32; 16];
                if cbp_chroma == 2 {
                    un_scan_4x4_ac_into(&cac[c][by * 2 + bx], &mut ac);
                    self.nnz_c[c][(mb_y * 2 + by) * w2r + (mb_x * 2 + bx)] =
                        cac[c][by * 2 + bx].iter().filter(|&&v| v != 0).count() as u8;
                }
                let mut deq = self.dequant(&ac, qpc, 4 + c);
                deq[0] = c_dc[c][by * 2 + bx];
                let predb: [i32; 16] =
                    std::array::from_fn(|i| c_pred[c][(by * 4 + i / 4) * 8 + (bx * 4 + i % 4)] as i32);
                let s = reconstruct_4x4(&deq, &predb);
                let plane = if c == 0 { &mut self.rec_u } else { &mut self.rec_v };
                store(plane, self.ccw, (mb_x * 2 + bx) * 4, (mb_y * 2 + by) * 4, &s);
            }
        }
    }

    fn recon_chroma_cabac(
        &mut self,
        mb_x: usize,
        mb_y: usize,
        chroma_mode: u8,
        cdc: &[[i32; 4]; 2],
        cac: &[[[i32; 16]; 4]; 2],
        cbp_chroma: u32,
        avail_top: bool,
        avail_left: bool,
    ) {
        let qpc = self.chroma_qp_for(self.cur_qp);
        let (cx, cy) = (mb_x * 8, mb_y * 8);
        let mut c_dc = [[0i32; 4]; 2];
        if cbp_chroma != 0 {
            for c in 0..2 {
                c_dc[c] = self.dequant_chroma_dc(&cdc[c], qpc, 1 + c);
            }
        }
        let w2 = self.mb_w * 2;
        for c in 0..2 {
            let mut ctop = [0u8; 8];
            let mut cleft = [0u8; 8];
            let mut ccorner = 0u8;
            {
                let rec_c = if c == 0 { &self.rec_u } else { &self.rec_v };
                if avail_top {
                    ctop.copy_from_slice(&rec_c[(cy - 1) * self.ccw + cx..][..8]);
                }
                if avail_left {
                    for i in 0..8 {
                        cleft[i] = rec_c[(cy + i) * self.ccw + cx - 1];
                    }
                }
                if avail_top && avail_left {
                    ccorner = rec_c[(cy - 1) * self.ccw + cx - 1];
                }
            }
            let pred8 = chroma8x8_pred(chroma_mode, avail_top, avail_left, &ctop, &cleft, ccorner);
            for &(bx, by) in &CHROMA_4X4_SCAN_XY {
                let mut ac = [0i32; 16];
                if cbp_chroma == 2 {
                    un_scan_4x4_ac_into(&cac[c][by * 2 + bx], &mut ac);
                    self.nnz_c[c][(mb_y * 2 + by) * w2 + (mb_x * 2 + bx)] =
                        cac[c][by * 2 + bx].iter().filter(|&&v| v != 0).count() as u8;
                }
                let mut deq = self.dequant(&ac, qpc, 1 + c);
                deq[0] = c_dc[c][by * 2 + bx];
                let predb: [i32; 16] =
                    std::array::from_fn(|i| pred8[(by * 4 + i / 4) * 8 + (bx * 4 + i % 4)] as i32);
                let s = reconstruct_4x4(&deq, &predb);
                let plane = if c == 0 { &mut self.rec_u } else { &mut self.rec_v };
                store(plane, self.ccw, cx + bx * 4, cy + by * 4, &s);
            }
        }
    }

    pub fn decode_slice_data(
        &mut self,
        r: &mut BitReader,
        is_p: bool,
        first_mb: usize,
    ) -> Result<usize, MbError> {
        let total = self.mb_w * self.mb_h;
        self.slice_first_mb = first_mb;
        let mut addr = first_mb;
        while addr < total {
            if is_p || self.is_b {
                let skip_run = {
                    let _g = rusty_h264_common::prof::scope(rusty_h264_common::prof::Stage::Syntax);
                    r.read_ue()?
                } as usize;
                for _ in 0..skip_run {
                    if addr >= total {
                        break;
                    }
                    if self.is_b {
                        self.decode_b_skip(addr % self.mb_w, addr / self.mb_w)?;
                    } else {
                        self.decode_p_skip(addr % self.mb_w, addr / self.mb_w)?;
                    }
                    self.mb_qp[addr] = self.cur_qp; // skip inherits QPy
                    addr += 1;
                }
                if addr >= total {
                    break;
                }
                // A trailing skip run with no following macroblock ends the slice.
                if skip_run > 0 && !r.more_rbsp_data() {
                    break;
                }
            }
            if self.is_b {
                self.decode_b_mb(r, addr % self.mb_w, addr / self.mb_w)?;
            } else {
                self.decode_mb(r, addr % self.mb_w, addr / self.mb_w, is_p)?;
            }
            self.mb_qp[addr] = self.cur_qp;
            addr += 1;
            // CAVLC slice end: no more data after this macroblock.
            if !r.more_rbsp_data() {
                break;
            }
        }
        Ok(addr)
    }

    fn decode_mb(
        &mut self,
        r: &mut BitReader,
        mb_x: usize,
        mb_y: usize,
        is_p: bool,
    ) -> Result<(), MbError> {
        let mut mb_type = {
            let _g = rusty_h264_common::prof::scope(rusty_h264_common::prof::Stage::Syntax);
            r.read_ue()?
        };
        if is_p {
            // In P-slices, mb_type 0/1/2 are inter (16×16, 16×8, 8×16),
            // 3 = P_8x8, 4 = P_8x8ref0 (ref_idx forced 0), 5+ intra.
            if mb_type <= 2 {
                return self.decode_inter(r, mb_x, mb_y, mb_type as u8);
            }
            if mb_type == 3 || mb_type == 4 {
                return self.decode_p8x8(r, mb_x, mb_y, mb_type == 4);
            }
            mb_type -= 5;
        }
        self.decode_intra_mb(r, mb_x, mb_y, mb_type)
    }

    /// Decodes an intra macroblock given its intra `mb_type` (0 = I_4x4,
    /// 1..=24 = I_16x16, 25 = I_PCM) — shared by I-, P- and B-slice paths.
    fn decode_intra_mb(
        &mut self,
        r: &mut BitReader,
        mb_x: usize,
        mb_y: usize,
        mb_type: u32,
    ) -> Result<(), MbError> {
        if mb_type == 0 {
            // I_NxN: transform_size_8x8_flag (when enabled) selects I_8x8 vs I_4x4.
            if self.transform_8x8_mode && r.read_bit()? {
                self.decode_i8x8(r, mb_x, mb_y)?;
            } else {
                self.decode_i4x4(r, mb_x, mb_y)?;
            }
        } else if (1..=24).contains(&mb_type) {
            self.decode_i16(r, mb_x, mb_y, mb_type - 1)?;
        } else if mb_type == 25 {
            self.decode_ipcm(r, mb_x, mb_y)?;
        } else {
            return Err(MbError::Unsupported("only I_4x4 / I_16x16 / I_PCM macroblocks"));
        }
        // Mark all luma blocks coded for the next macroblock's top-right.
        let w4 = self.mb_w * 4;
        for &(lbx, lby) in &LUMA_4X4_SCAN_XY {
            self.coded_y[(mb_y * 4 + lby) * w4 + (mb_x * 4 + lbx)] = true;
        }
        Ok(())
    }

    /// Reconstructs an inter macroblock (`mode` 0 = P_L0_16x16, 1 = P_16x8,
    /// 2 = P_8x16): parse the per-partition motion vectors and residual,
    /// motion-compensate each partition, and add the residual.
    fn decode_inter(
        &mut self,
        r: &mut BitReader,
        mb_x: usize,
        mb_y: usize,
        mode: u8,
    ) -> Result<(), MbError> {
        if self.refs.is_empty() {
            return Err(MbError::Unsupported("inter without reference"));
        }
        // QP (qp/qpc) is bound after mb_qp_delta is read below.
        let w4 = self.mb_w * 4;
        let (ch, cch) = (self.mb_h * 16, self.mb_h * 8);
        let num_refs = self.refs.len();
        let layout = inter_partitions(mode);

        // mb_pred order (spec 7.3.5.1): all ref_idx_l0 first (only when more than
        // one reference is active), then all mvd_l0.
        let nparts = layout.len();
        let mut ref_idxs = [0i32; 4];
        if self.num_ref_active > 1 {
            for ri in ref_idxs[..nparts].iter_mut() {
                *ri = read_ref_idx(r, self.num_ref_active)?;
                if *ri as usize >= num_refs {
                    return Err(MbError::Truncated); // references a non-existent picture
                }
            }
        }

        // Phase 1: per partition, ref-aware MV prediction + mvd, committing the
        // motion grid so a later partition predicts from an earlier one.
        let mut part_mv = [(0i32, (0i32, 0i32)); 4];
        {
            let _g = rusty_h264_common::prof::scope(rusty_h264_common::prof::Stage::MvGrid);
            for (part, &(rx, ry, rw, rh)) in layout.iter().enumerate() {
                let refi = ref_idxs[part];
                let (pbx, pby) = ((mb_x * 4 + rx / 4) as isize, (mb_y * 4 + ry / 4) as isize);
                let [a, b, c] = self.mv_neighbors_block(pbx, pby, (rw / 4) as isize);
                let pmv = predict_partition_mv(mode, part, a, b, c, refi);
                let mvd_x = r.read_se()?;
                let mvd_y = r.read_se()?;
                let mv = (pmv.0 + mvd_x, pmv.1 + mvd_y);
                part_mv[part] = (refi, mv);
                for by in ry / 4..ry / 4 + rh / 4 {
                    for bx in rx / 4..rx / 4 + rw / 4 {
                        let idx = (mb_y * 4 + by) * w4 + (mb_x * 4 + bx);
                        self.mv_y[idx] = mv;
                        self.inter_y[idx] = true;
                        self.ref_idx_y[idx] = refi;
                        self.coded_y[idx] = true;
                    }
                }
            }
        }

        // Phase 2: motion-compensate each partition from its reference.
        let mut pred_y = [0u8; 256];
        let mut c_pred = [[0u8; 64]; 2];
        for (part, &(rx, ry, rw, rh)) in layout.iter().enumerate() {
            let (refi, mv) = part_mv[part];
            let reference = &self.refs[refi as usize];
            let mut tmp = [0u8; 256];
            mc_luma(&reference.y, self.cw, ch, mb_x * 16 + rx, mb_y * 16 + ry, rw, rh, mv.0, mv.1, &mut tmp);
            {
                let _g = rusty_h264_common::prof::scope(rusty_h264_common::prof::Stage::PredBuf);
                for dy in 0..rh {
                    for dx in 0..rw {
                        pred_y[(ry + dy) * 16 + (rx + dx)] = tmp[dy * rw + dx];
                    }
                }
            }
            let (crx, cry, crw, crh) = (rx / 2, ry / 2, rw / 2, rh / 2);
            for cc in 0..2 {
                let rc = if cc == 0 { &reference.u } else { &reference.v };
                let mut tc = [0u8; 64];
                mc_chroma(rc, self.ccw, cch, mb_x * 8 + crx, mb_y * 8 + cry, crw, crh, mv.0, mv.1, &mut tc);
                {
                    let _g = rusty_h264_common::prof::scope(rusty_h264_common::prof::Stage::PredBuf);
                    for dy in 0..crh {
                        for dx in 0..crw {
                            c_pred[cc][(cry + dy) * 8 + (crx + dx)] = tc[dy * crw + dx];
                        }
                    }
                }
            }
            self.weight_partition(&mut pred_y, &mut c_pred, 0, refi as usize, rx, ry, rw, rh);
        }

        // 16×16/16×8/8×16 partitions are all ≥ 8×8, so the 8×8 transform is allowed.
        self.inter_finish(r, mb_x, mb_y, &pred_y, &c_pred, true)
    }

    /// Shared inter tail: parse `coded_block_pattern` + `mb_qp_delta`, decode the
    /// luma/chroma residual, and add it to the already-built motion-compensated
    /// prediction. Used by both the 16×16/16×8/8×16 path and `P_8x8`.
    fn inter_finish(
        &mut self,
        r: &mut BitReader,
        mb_x: usize,
        mb_y: usize,
        pred_y: &[u8; 256],
        c_pred: &[[u8; 64]; 2],
        allow_8x8: bool,
    ) -> Result<(), MbError> {
        let w4 = self.mb_w * 4;
        let cbp = {
            let _g = rusty_h264_common::prof::scope(rusty_h264_common::prof::Stage::Syntax);
            read_cbp_inter(r)?
        };
        let cbp_luma = cbp & 15;
        let cbp_chroma = cbp >> 4;
        // transform_size_8x8_flag follows cbp (before mb_qp_delta) when luma has
        // coefficients, the 8×8 transform is enabled, and every partition ≥ 8×8.
        let t8x8 = cbp_luma > 0 && self.transform_8x8_mode && allow_8x8 && r.read_bit()?;
        if t8x8 {
            self.mb_t8x8[mb_y * self.mb_w + mb_x] = true;
        }
        if cbp != 0 {
            self.step_qp(r.read_se()?);
        }
        let (qp, qpc) = (self.cur_qp, self.chroma_qp_for(self.cur_qp));

        // ---- luma residual ----
        self.nnz_cache_load(mb_x, mb_y);
        let mut q_blocks = [[0i32; 16]; 16];
        let mut luma8 = [[0i32; 64]; 4]; // 8×8-transform residuals (when t8x8)
        if t8x8 {
            for b8 in 0..4 {
                let (b8x, b8y) = (b8 % 2, b8 / 2);
                let (bx, by) = (mb_x * 4 + b8x * 2, mb_y * 4 + b8y * 2);
                if cbp_luma & (1 << b8) != 0 {
                    let mut scan8 = [0i32; 64];
                    for sub in 0..4 {
                        let (sx, sy) = (sub % 2, sub / 2);
                        let (cx, cy) = (b8x * 2 + sx, b8y * 2 + sy);
                        let nc = self.nc_pred(cx, cy);
                        let blk = decode_residual_block(r, 16, nc)?;
                        let total = blk.iter().filter(|&&v| v != 0).count() as u8;
                        self.nnz_cache_set(cx, cy, total);
                        self.nnz_y[(by + sy) * w4 + (bx + sx)] = total;
                        for k in 0..16 {
                            scan8[4 * k + sub] = blk[k];
                        }
                    }
                    luma8[b8] = self.inv_quant8(&un_scan_8x8(&scan8), qp, 1);
                } else {
                    for sub in 0..4 {
                        let (sx, sy) = (sub % 2, sub / 2);
                        self.nnz_cache_set(b8x * 2 + sx, b8y * 2 + sy, 0);
                        self.nnz_y[(by + sy) * w4 + (bx + sx)] = 0;
                    }
                }
            }
        } else {
            for (blk, &(lbx, lby)) in LUMA_4X4_SCAN_XY.iter().enumerate() {
                let (bx, by) = (mb_x * 4 + lbx, mb_y * 4 + lby);
                let total = if cbp_luma & (1 << (blk / 4)) != 0 {
                    let nc = self.nc_pred(lbx, lby);
                    let scan16 = decode_residual_block(r, 16, nc)?;
                    q_blocks[lby * 4 + lbx] = un_scan_4x4_dcac(&scan16);
                    scan16.iter().filter(|&&v| v != 0).count() as u8
                } else {
                    0
                };
                self.nnz_cache_set(lbx, lby, total);
                self.nnz_y[by * w4 + bx] = total;
            }
        }

        // ---- chroma residual ----
        let mut c_recon_dc = [[0i32; 4]; 2];
        if cbp_chroma != 0 {
            for (c, slot) in c_recon_dc.iter_mut().enumerate() {
                let dc = decode_residual_block(r, 4, -1)?;
                *slot = self.dequant_chroma_dc(&[dc[0], dc[1], dc[2], dc[3]], qpc, 4 + c);
            }
        }
        let mut c_q = [[[0i32; 16]; 4]; 2];
        if cbp_chroma == 2 {
            self.chroma_cache_load(mb_x, mb_y);
            let w2 = self.mb_w * 2;
            for c in 0..2 {
                for &(bx, by) in &CHROMA_4X4_SCAN_XY {
                    let nc = self.chroma_nc_pred(c, bx, by);
                    let ac = decode_residual_block(r, 15, nc)?;
                    let total = ac.iter().filter(|&&v| v != 0).count() as u8;
                    self.chroma_nnz_cache_set(c, bx, by, total);
                    self.nnz_c[c][(mb_y * 2 + by) * w2 + (mb_x * 2 + bx)] = total;
                    un_scan_4x4_ac_into(&ac, &mut c_q[c][by * 2 + bx]);
                }
            }
        }

        // ---- reconstruction (prediction already built per partition) ----
        if t8x8 {
            for b8 in 0..4 {
                let (b8x, b8y) = (b8 % 2, b8 / 2);
                let (px, py) = (b8x * 8, b8y * 8);
                for dy in 0..8 {
                    for dx in 0..8 {
                        let p = pred_y[(py + dy) * 16 + (px + dx)] as i32;
                        let v = (p + luma8[b8][dy * 8 + dx]).clamp(0, 255) as u8;
                        self.rec_y[(mb_y * 16 + py + dy) * self.cw + (mb_x * 16 + px + dx)] = v;
                    }
                }
            }
        } else {
            // Inverse 4×4 transform + add prediction, per 8×8 region (four blocks).
            // An UNCODED region (its `cbp_luma` bit clear) has zero residual, so the
            // reconstruction *is* the prediction — copy it row-wise and skip the
            // transform entirely (openh264's residual-skip; bit-identical). The asm
            // path (`WelsIDctFourT4Rec`) does butterfly + `(x+32)>>6` + add-pred +
            // clip for four coded blocks at once.
            for b8 in 0..4 {
                let (b8x, b8y) = (b8 % 2, b8 / 2);
                let pred_off = (b8y * 8) * 16 + b8x * 8;
                let rec_off = (mb_y * 16 + b8y * 8) * self.cw + (mb_x * 16 + b8x * 8);
                if cbp_luma & (1 << b8) == 0 {
                    for r in 0..8 {
                        let (s, d) = (pred_off + r * 16, rec_off + r * self.cw);
                        self.rec_y[d..d + 8].copy_from_slice(&pred_y[s..s + 8]);
                    }
                    continue;
                }
                #[cfg(accel)]
                {
                    let mut dct = [0i16; 64];
                    for (i, (sx, sy)) in [(0, 0), (1, 0), (0, 1), (1, 1)].into_iter().enumerate() {
                        let (lbx, lby) = (2 * b8x + sx, 2 * b8y + sy);
                        let deq = self.dequant(&q_blocks[lby * 4 + lbx], qp, 3);
                        for k in 0..16 {
                            dct[i * 16 + k] = deq[k] as i16;
                        }
                    }
                    rusty_h264_accel::idct_four_t4_rec(
                        &mut self.rec_y[rec_off..],
                        self.cw,
                        &pred_y[pred_off..],
                        16,
                        &dct,
                    );
                }
                #[cfg(not(accel))]
                for (sx, sy) in [(0, 0), (1, 0), (0, 1), (1, 1)] {
                    let (lbx, lby) = (2 * b8x + sx, 2 * b8y + sy);
                    let mut predb = [0i32; 16];
                    for dy in 0..4 {
                        for dx in 0..4 {
                            predb[dy * 4 + dx] = pred_y[(lby * 4 + dy) * 16 + (lbx * 4 + dx)] as i32;
                        }
                    }
                    let deq = self.dequant(&q_blocks[lby * 4 + lbx], qp, 3);
                    let s = reconstruct_4x4(&deq, &predb);
                    store(&mut self.rec_y, self.cw, mb_x * 16 + lbx * 4, mb_y * 16 + lby * 4, &s);
                }
            }
        }
        // Chroma: an uncoded MB (cbp_chroma == 0) has zero chroma residual → the
        // prediction is the reconstruction. Copy row-wise and skip the transform.
        if cbp_chroma == 0 {
            for c in 0..2 {
                let plane = if c == 0 { &mut self.rec_u } else { &mut self.rec_v };
                for dy in 0..8 {
                    let d = (mb_y * 8 + dy) * self.ccw + mb_x * 8;
                    plane[d..d + 8].copy_from_slice(&c_pred[c][dy * 8..dy * 8 + 8]);
                }
            }
        } else {
            for c in 0..2 {
                let plane = if c == 0 { &mut self.rec_u } else { &mut self.rec_v };
                for &(bx, by) in &CHROMA_4X4_SCAN_XY {
                    let mut predb = [0i32; 16];
                    for dy in 0..4 {
                        for dx in 0..4 {
                            predb[dy * 4 + dx] = c_pred[c][(by * 4 + dy) * 8 + (bx * 4 + dx)] as i32;
                        }
                    }
                    let mut deq = match &self.scaling {
                        Some(s) => dequantize_weighted(&c_q[c][by * 2 + bx], qpc, &s[4 + c]),
                        None => dequantize(&c_q[c][by * 2 + bx], qpc),
                    };
                    deq[0] = c_recon_dc[c][by * 2 + bx];
                    let s = reconstruct_4x4(&deq, &predb);
                    store(plane, self.ccw, mb_x * 8 + bx * 4, mb_y * 8 + by * 4, &s);
                }
            }
        }

        // MV grid + coded flags were set per partition; mark modes as DC.
        for &(lbx, lby) in &LUMA_4X4_SCAN_XY {
            self.modes_y[(mb_y * 4 + lby) * w4 + (mb_x * 4 + lbx)] = 2;
        }
        Ok(())
    }

    // ---------------------------------------------------------------------
    // B-slice macroblock decoding
    // ---------------------------------------------------------------------

    /// Per-list (`list` 0 or 1) MV-prediction neighbors for the block region at
    /// `(pbx, pby)` of width `pwb` blocks — the L0/L1 analogue of
    /// `mv_neighbors_block`.
    fn mv_neighbors_list(&self, pbx: isize, pby: isize, pwb: isize, list: usize) -> [MvNeighbor; 3] {
        let (w4, h4) = ((self.mb_w * 4) as isize, (self.mb_h * 4) as isize);
        let (mvg, refg) = if list == 0 {
            (&self.mv_y, &self.ref_idx_y)
        } else {
            (&self.mv1, &self.ref_idx1)
        };
        let get = |bx: isize, by: isize| -> MvNeighbor {
            if bx < 0
                || by < 0
                || bx >= w4
                || by >= h4
                || !self.coded_y[(by * w4 + bx) as usize]
                || !self.nbr_in_slice(bx as usize / 4, by as usize / 4)
            {
                MvNeighbor::NONE
            } else {
                let idx = (by * w4 + bx) as usize;
                MvNeighbor { available: true, mv: mvg[idx], ref_idx: refg[idx] }
            }
        };
        let a = get(pbx - 1, pby);
        let b = get(pbx, pby - 1);
        let mut c = get(pbx + pwb, pby - 1);
        if !c.available {
            c = get(pbx - 1, pby - 1);
        }
        [a, b, c]
    }

    /// `colZeroFlag` for the 4×4 block at absolute block coords `(bx, by)`: true
    /// when `RefPicList1[0]` is a short-term picture whose co-located block uses
    /// reference 0 with a near-zero motion vector (spec §8.4.1.2.2).
    fn col_zero(&self, bx: usize, by: usize) -> bool {
        let Some(col) = self.refs1.first() else { return false };
        if col.long_term || col.w4 == 0 {
            return false;
        }
        let idx = by * col.w4 + bx;
        if idx >= col.ref_idx.len() {
            return false;
        }
        col.ref_idx[idx] == 0 && col.mv[idx].0.abs() <= 1 && col.mv[idx].1.abs() <= 1
    }

    /// Implicit bi-prediction weights `(w0, w1)` from POC distances (spec
    /// §8.4.2.3.2), or `None` for the plain average (idc≠2, uni-pred, or the
    /// equidistant / out-of-range fall-back to 32:32 which equals the average).
    fn implicit_weights(&self, refi0: i32, refi1: i32) -> Option<(i32, i32)> {
        if self.weighted_bipred_idc != 2 || refi0 < 0 || refi1 < 0 {
            return None;
        }
        let r0 = &self.refs[refi0 as usize];
        let r1 = &self.refs1[refi1 as usize];
        let td = (r1.poc - r0.poc).clamp(-128, 127);
        let tb = (self.cur_poc - r0.poc).clamp(-128, 127);
        if td == 0 || r0.long_term || r1.long_term {
            return None; // 32:32 → identical to the average
        }
        let tx = (16384 + td.abs() / 2) / td;
        let dsf = ((tb * tx + 32) >> 6).clamp(-1024, 1023);
        let w1 = dsf >> 2;
        if !(-64..=128).contains(&w1) {
            return None; // out of range → 32:32 average
        }
        Some((64 - w1, w1))
    }

    /// Motion-compensates a region with the given per-list refs/MVs. Bi-prediction
    /// is the simple `(a+b+1)>>1` average, or POC-weighted when implicit weighting
    /// (idc 2) is active. Writes into `pred_y`/`c_pred`.
    #[allow(clippy::too_many_arguments)]
    fn b_mc(
        &self,
        mb_x: usize,
        mb_y: usize,
        px: usize,
        py: usize,
        rw: usize,
        rh: usize,
        refi0: i32,
        mv0: (i32, i32),
        refi1: i32,
        mv1: (i32, i32),
        pred_y: &mut [u8; 256],
        c_pred: &mut [[u8; 64]; 2],
    ) {
        let (ch, cch) = (self.mb_h * 16, self.mb_h * 8);
        let weights = self.implicit_weights(refi0, refi1);
        // Bi-prediction blend of two MC samples `p` (L0) and `q` (L1).
        let blend = |p: i32, q: i32| -> u8 {
            match weights {
                Some((w0, w1)) => (((p * w0 + q * w1 + 32) >> 6).clamp(0, 255)) as u8,
                None => ((p + q + 1) >> 1) as u8,
            }
        };
        let (mut a, mut b) = ([0u8; 256], [0u8; 256]);
        if refi0 >= 0 {
            mc_luma(&self.refs[refi0 as usize].y, self.cw, ch, mb_x * 16 + px, mb_y * 16 + py, rw, rh, mv0.0, mv0.1, &mut a);
        }
        if refi1 >= 0 {
            mc_luma(&self.refs1[refi1 as usize].y, self.cw, ch, mb_x * 16 + px, mb_y * 16 + py, rw, rh, mv1.0, mv1.1, &mut b);
        }
        // Hoist the loop-invariant L0/L1 branch out of the inner loop: uni-pred is
        // a row copy (memcpy), bi-pred a branchless blend (both autovectorize).
        match (refi0 >= 0, refi1 >= 0) {
            (true, true) => {
                for dy in 0..rh {
                    for dx in 0..rw {
                        let (p, q) = (a[dy * rw + dx] as i32, b[dy * rw + dx] as i32);
                        pred_y[(py + dy) * 16 + (px + dx)] = blend(p, q);
                    }
                }
            }
            (true, false) => {
                for dy in 0..rh {
                    let d = (py + dy) * 16 + px;
                    pred_y[d..d + rw].copy_from_slice(&a[dy * rw..dy * rw + rw]);
                }
            }
            _ => {
                for dy in 0..rh {
                    let d = (py + dy) * 16 + px;
                    pred_y[d..d + rw].copy_from_slice(&b[dy * rw..dy * rw + rw]);
                }
            }
        }
        let (crx, cry, crw, crh) = (px / 2, py / 2, rw / 2, rh / 2);
        for c in 0..2 {
            let (mut ca, mut cb) = ([0u8; 64], [0u8; 64]);
            if refi0 >= 0 {
                let rf = &self.refs[refi0 as usize];
                let pl = if c == 0 { &rf.u } else { &rf.v };
                mc_chroma(pl, self.ccw, cch, mb_x * 8 + crx, mb_y * 8 + cry, crw, crh, mv0.0, mv0.1, &mut ca);
            }
            if refi1 >= 0 {
                let rf = &self.refs1[refi1 as usize];
                let pl = if c == 0 { &rf.u } else { &rf.v };
                mc_chroma(pl, self.ccw, cch, mb_x * 8 + crx, mb_y * 8 + cry, crw, crh, mv1.0, mv1.1, &mut cb);
            }
            match (refi0 >= 0, refi1 >= 0) {
                (true, true) => {
                    for dy in 0..crh {
                        for dx in 0..crw {
                            let (p, q) = (ca[dy * crw + dx] as i32, cb[dy * crw + dx] as i32);
                            c_pred[c][(cry + dy) * 8 + (crx + dx)] = blend(p, q);
                        }
                    }
                }
                (true, false) => {
                    for dy in 0..crh {
                        let d = (cry + dy) * 8 + crx;
                        c_pred[c][d..d + crw].copy_from_slice(&ca[dy * crw..dy * crw + crw]);
                    }
                }
                _ => {
                    for dy in 0..crh {
                        let d = (cry + dy) * 8 + crx;
                        c_pred[c][d..d + crw].copy_from_slice(&cb[dy * crw..dy * crw + crw]);
                    }
                }
            }
        }
    }

    /// Commits a region's per-list motion to the 4×4 grids (and marks coded).
    #[allow(clippy::too_many_arguments)]
    fn b_set_motion(&mut self, mb_x: usize, mb_y: usize, px: usize, py: usize, rw: usize, rh: usize, refi0: i32, mv0: (i32, i32), refi1: i32, mv1: (i32, i32)) {
        let w4 = self.mb_w * 4;
        for by in py / 4..(py + rh) / 4 {
            for bx in px / 4..(px + rw) / 4 {
                let idx = (mb_y * 4 + by) * w4 + (mb_x * 4 + bx);
                self.ref_idx_y[idx] = refi0;
                self.mv_y[idx] = if refi0 >= 0 { mv0 } else { (0, 0) };
                self.ref_idx1[idx] = refi1;
                self.mv1[idx] = if refi1 >= 0 { mv1 } else { (0, 0) };
                self.inter_y[idx] = true;
                self.coded_y[idx] = true;
                self.modes_y[idx] = 2;
            }
        }
    }

    /// Spatial direct prediction for a region (whole MB or an 8×8): derives the
    /// per-list reference indices and base MVs, then motion-compensates each 4×4
    /// sub-block (applying `colZeroFlag`) and commits the motion (spec §8.4.1.2.2).
    #[allow(clippy::too_many_arguments)]
    fn decode_b_direct(&mut self, mb_x: usize, mb_y: usize, px: usize, py: usize, rw: usize, rh: usize, pred_y: &mut [u8; 256], c_pred: &mut [[u8; 64]; 2]) {
        if !self.direct_spatial {
            return self.decode_b_direct_temporal(mb_x, mb_y, px, py, rw, rh, pred_y, c_pred);
        }
        // MB-level neighbors drive the direct reference indices and base MVs.
        let (nbx, nby) = ((mb_x * 4) as isize, (mb_y * 4) as isize);
        let n0 = self.mv_neighbors_list(nbx, nby, 4, 0);
        let n1 = self.mv_neighbors_list(nbx, nby, 4, 1);
        let min_pos = |a: i32, b: i32| if a < 0 { b } else if b < 0 { a } else { a.min(b) };
        let rid = |n: &[MvNeighbor; 3]| min_pos(min_pos(n[0].ref_idx, n[1].ref_idx), n[2].ref_idx);
        let (mut refi0, mut refi1) = (rid(&n0), rid(&n1));
        let direct_zero = refi0 < 0 && refi1 < 0;
        if direct_zero {
            refi0 = 0;
            refi1 = 0;
        }
        let mv0 = if refi0 >= 0 && !direct_zero { predict_mv(n0[0], n0[1], n0[2], refi0) } else { (0, 0) };
        let mv1 = if refi1 >= 0 && !direct_zero { predict_mv(n1[0], n1[1], n1[2], refi1) } else { (0, 0) };
        // Per 4×4 sub-block: colZeroFlag zeroes the ref-0 motion vector.
        for sby in py / 4..(py + rh) / 4 {
            for sbx in px / 4..(px + rw) / 4 {
                let cz = !direct_zero && self.col_zero(mb_x * 4 + sbx, mb_y * 4 + sby);
                let m0 = if refi0 == 0 && cz { (0, 0) } else { mv0 };
                let m1 = if refi1 == 0 && cz { (0, 0) } else { mv1 };
                self.b_mc(mb_x, mb_y, sbx * 4, sby * 4, 4, 4, refi0, m0, refi1, m1, pred_y, c_pred);
                self.b_set_motion(mb_x, mb_y, sbx * 4, sby * 4, 4, 4, refi0, m0, refi1, m1);
            }
        }
    }

    /// Temporal direct prediction for a region (spec §8.4.1.2.3): for each 4×4
    /// (or per-8×8 corner under `direct_8x8_inference`), take the co-located
    /// List-0 motion from `RefPicList1[0]`, map its reference into the current
    /// List-0 by POC, and scale the motion vector by the POC distances.
    #[allow(clippy::too_many_arguments)]
    fn decode_b_direct_temporal(&mut self, mb_x: usize, mb_y: usize, px: usize, py: usize, rw: usize, rh: usize, pred_y: &mut [u8; 256], c_pred: &mut [[u8; 64]; 2]) {
        let poc1 = self.refs1.first().map_or(0, |f| f.poc);
        let infer = self.direct_8x8_inference;
        // Under direct_8x8_inference every 4×4 in an 8×8 takes the same MB-corner
        // co-located motion, so motion-compensate the whole 8×8 in one call — this
        // hits the width-8 MC asm and pays the per-call tile/blend setup 4× less.
        // Without inference, motion is genuinely per-4×4. Bit-identical either way
        // (MC of an 8×8 with one MV == four 4×4 MCs with that same MV).
        let step = if infer { 8 } else { 4 };
        let mut sy = py;
        while sy < py + rh {
            let mut sx = px;
            while sx < px + rw {
                let (cx4, cy4) = (sx / 4, sy / 4);
                // Co-located 4×4 (the 8×8's MB-corner under inference).
                let (colx, coly) = if infer {
                    ((cx4 / 2) * 3, (cy4 / 2) * 3)
                } else {
                    (cx4, cy4)
                };
                let (mvcol, refpoc) = {
                    let col = &self.refs1[0];
                    let idx = (mb_y * 4 + coly) * col.w4 + (mb_x * 4 + colx);
                    if col.w4 != 0 && idx < col.mv.len() && col.ref_poc[idx] != i32::MIN {
                        (col.mv[idx], col.ref_poc[idx])
                    } else {
                        ((0, 0), i32::MIN) // intra co-located → zero motion, refIdxL0 = 0
                    }
                };
                // MapColToList0: the current-list index of the co-located reference.
                let (refi0, mvc) = if refpoc == i32::MIN {
                    (0, (0, 0))
                } else {
                    let r = self.refs.iter().position(|f| f.poc == refpoc).unwrap_or(0) as i32;
                    (r, mvcol)
                };
                let poc0 = self.refs[refi0 as usize].poc;
                let td = (poc1 - poc0).clamp(-128, 127);
                let tb = (self.cur_poc - poc0).clamp(-128, 127);
                let (mv0, mv1) = if td == 0 || self.refs[refi0 as usize].long_term {
                    (mvc, (0, 0))
                } else {
                    let tx = (16384 + td.abs() / 2) / td;
                    let dsf = ((tb * tx + 32) >> 6).clamp(-1024, 1023);
                    let m0 = ((dsf * mvc.0 + 128) >> 8, (dsf * mvc.1 + 128) >> 8);
                    (m0, (m0.0 - mvc.0, m0.1 - mvc.1))
                };
                self.b_mc(mb_x, mb_y, sx, sy, step, step, refi0, mv0, 0, mv1, pred_y, c_pred);
                self.b_set_motion(mb_x, mb_y, sx, sy, step, step, refi0, mv0, 0, mv1);
                sx += step;
            }
            sy += step;
        }
    }

    /// Reads `ref_idx_lX` for a B partition (te(v)/ue(v) by the list's active
    /// count), bounds-checked against the available reference count.
    fn read_b_ref(&self, r: &mut BitReader, list: usize) -> Result<i32, MbError> {
        let (active, avail) = if list == 0 {
            (self.num_ref_active, self.refs.len())
        } else {
            (self.num_ref_active1, self.refs1.len())
        };
        let v = if active > 1 { read_ref_idx(r, active)? } else { 0 };
        if v as usize >= avail {
            return Err(MbError::Truncated);
        }
        Ok(v)
    }

    /// Reconstructs a `B_Skip` macroblock: spatial-direct prediction, no residual.
    fn decode_b_skip(&mut self, mb_x: usize, mb_y: usize) -> Result<(), MbError> {
        if self.refs.is_empty() || self.refs1.is_empty() {
            return Err(MbError::Unsupported("B without references"));
        }
        let mut pred_y = [0u8; 256];
        let mut c_pred = [[0u8; 64]; 2];
        self.decode_b_direct(mb_x, mb_y, 0, 0, 16, 16, &mut pred_y, &mut c_pred);
        // Zero residual: the prediction is the reconstruction — copy it row-wise.
        for dy in 0..16 {
            let d = (mb_y * 16 + dy) * self.cw + mb_x * 16;
            self.rec_y[d..d + 16].copy_from_slice(&pred_y[dy * 16..dy * 16 + 16]);
        }
        for c in 0..2 {
            let plane = if c == 0 { &mut self.rec_u } else { &mut self.rec_v };
            for dy in 0..8 {
                let d = (mb_y * 8 + dy) * self.ccw + mb_x * 8;
                plane[d..d + 8].copy_from_slice(&c_pred[c][dy * 8..dy * 8 + 8]);
            }
        }
        // nnz stays 0 (no residual) — clear the grids for neighbor context.
        let w4 = self.mb_w * 4;
        for &(lbx, lby) in &LUMA_4X4_SCAN_XY {
            self.nnz_y[(mb_y * 4 + lby) * w4 + (mb_x * 4 + lbx)] = 0;
        }
        Ok(())
    }

    /// Reconstructs a B macroblock (spec Table 7-14): direct, L0/L1/Bi partitions,
    /// `B_8x8`, or intra.
    fn decode_b_mb(&mut self, r: &mut BitReader, mb_x: usize, mb_y: usize) -> Result<(), MbError> {
        let mb_type = r.read_ue()?;
        if mb_type >= 23 {
            return self.decode_intra_mb(r, mb_x, mb_y, mb_type - 23);
        }
        if self.refs.is_empty() || self.refs1.is_empty() {
            return Err(MbError::Unsupported("B without references"));
        }
        let mut pred_y = [0u8; 256];
        let mut c_pred = [[0u8; 64]; 2];

        if mb_type == 0 {
            // B_Direct_16x16 — 8×8 transform allowed only with direct_8x8_inference.
            self.decode_b_direct(mb_x, mb_y, 0, 0, 16, 16, &mut pred_y, &mut c_pred);
            return self.inter_finish(r, mb_x, mb_y, &pred_y, &c_pred, self.direct_8x8_inference);
        }
        if mb_type == 22 {
            return self.decode_b_8x8(r, mb_x, mb_y);
        }

        // 16x16 / 16x8 / 8x16 partitions with per-partition L0/L1/Bi.
        let (layout, mvmode, preds) = b_inter_layout(mb_type);
        // mb_pred order: ref_idx_l0 (all L0 parts), ref_idx_l1, mvd_l0, mvd_l1.
        let mut refi = [[-1i32; 2]; 2]; // [part][list]
        for (p, &(_, _, _, _)) in layout.iter().enumerate() {
            if preds[p].uses(0) {
                refi[p][0] = self.read_b_ref(r, 0)?;
            }
        }
        for (p, _) in layout.iter().enumerate() {
            if preds[p].uses(1) {
                refi[p][1] = self.read_b_ref(r, 1)?;
            }
        }
        let mut mvd = [[(0i32, 0i32); 2]; 2];
        for (p, _) in layout.iter().enumerate() {
            if preds[p].uses(0) {
                mvd[p][0] = (r.read_se()?, r.read_se()?);
            }
        }
        for (p, _) in layout.iter().enumerate() {
            if preds[p].uses(1) {
                mvd[p][1] = (r.read_se()?, r.read_se()?);
            }
        }
        // Per partition: predict + commit each list's MV, then motion-compensate.
        for (p, &(rx, ry, rw, rh)) in layout.iter().enumerate() {
            let (pbx, pby) = ((mb_x * 4 + rx / 4) as isize, (mb_y * 4 + ry / 4) as isize);
            let pwb = (rw / 4) as isize;
            let mut mv = [(0i32, 0i32); 2];
            for list in 0..2 {
                if refi[p][list] >= 0 {
                    let n = self.mv_neighbors_list(pbx, pby, pwb, list);
                    let pmv = predict_partition_mv(mvmode, p, n[0], n[1], n[2], refi[p][list]);
                    mv[list] = (pmv.0 + mvd[p][list].0, pmv.1 + mvd[p][list].1);
                }
            }
            self.b_set_motion(mb_x, mb_y, rx, ry, rw, rh, refi[p][0], mv[0], refi[p][1], mv[1]);
            // Bug-for-bug compatibility with openh264 (the conformance oracle): its
            // 16x8/8x16 B macroblock path mis-handles a Bi partition's destination
            // buffer. Partition 0 has its List-0 prediction overwritten by List-1
            // (result = List-1 only); partition 1's List-1 prediction lands at a
            // doubly-offset address, leaving List-0 in place (result = List-0 only).
            // 16x16 Bi averages correctly; only the partitioned path is affected.
            let (mc_r0, mc_r1) = if mvmode != 0 && refi[p][0] >= 0 && refi[p][1] >= 0 {
                if p == 0 {
                    (-1, refi[p][1])
                } else {
                    (refi[p][0], -1)
                }
            } else {
                (refi[p][0], refi[p][1])
            };
            self.b_mc(mb_x, mb_y, rx, ry, rw, rh, mc_r0, mv[0], mc_r1, mv[1], &mut pred_y, &mut c_pred);
        }
        self.inter_finish(r, mb_x, mb_y, &pred_y, &c_pred, true)
    }

    /// Reconstructs a `B_8x8` macroblock: four 8×8 sub-macroblock partitions, each
    /// direct or L0/L1/Bi with its own sub-partitioning (spec Table 7-18).
    fn decode_b_8x8(&mut self, r: &mut BitReader, mb_x: usize, mb_y: usize) -> Result<(), MbError> {
        let mut sub = [0u32; 4];
        for s in sub.iter_mut() {
            let v = r.read_ue()?;
            if v > 12 {
                return Err(MbError::Unsupported("invalid B sub_mb_type"));
            }
            *s = v;
        }
        let mut pred_y = [0u8; 256];
        let mut c_pred = [[0u8; 64]; 2];
        // ref_idx for all 8×8 partitions (L0 batch, then L1 batch), for the
        // non-direct sub-partitions.
        let mut refi = [[-1i32; 2]; 4];
        for (p, &st) in sub.iter().enumerate() {
            if st != 0 && b_sub_uses(st, 0) {
                refi[p][0] = self.read_b_ref(r, 0)?;
            }
        }
        for (p, &st) in sub.iter().enumerate() {
            if st != 0 && b_sub_uses(st, 1) {
                refi[p][1] = self.read_b_ref(r, 1)?;
            }
        }
        // mvd: all mvd_l0 (partition-major, sub-partition order), then all mvd_l1.
        let mut mvd0: Vec<(i32, i32)> = Vec::new();
        let mut mvd1: Vec<(i32, i32)> = Vec::new();
        for &st in &sub {
            if st != 0 && b_sub_uses(st, 0) {
                for _ in b_sub_parts(st) {
                    mvd0.push((r.read_se()?, r.read_se()?));
                }
            }
        }
        for &st in &sub {
            if st != 0 && b_sub_uses(st, 1) {
                for _ in b_sub_parts(st) {
                    mvd1.push((r.read_se()?, r.read_se()?));
                }
            }
        }
        // Decode each 8×8 partition.
        let (mut i0, mut i1) = (0usize, 0usize);
        for (p, &st) in sub.iter().enumerate() {
            let (b8x, b8y) = ((p % 2) * 8, (p / 2) * 8);
            if st == 0 {
                self.decode_b_direct(mb_x, mb_y, b8x, b8y, 8, 8, &mut pred_y, &mut c_pred);
                continue;
            }
            for &(sx, sy, sw, sh) in b_sub_parts(st) {
                let (px, py) = (b8x + sx, b8y + sy);
                let (pbx, pby) = ((mb_x * 4 + px / 4) as isize, (mb_y * 4 + py / 4) as isize);
                let pwb = (sw / 4) as isize;
                let mut mv = [(0i32, 0i32); 2];
                if b_sub_uses(st, 0) {
                    let n = self.mv_neighbors_list(pbx, pby, pwb, 0);
                    let pmv = predict_mv(n[0], n[1], n[2], refi[p][0]);
                    let d = mvd0[i0];
                    i0 += 1;
                    mv[0] = (pmv.0 + d.0, pmv.1 + d.1);
                }
                if b_sub_uses(st, 1) {
                    let n = self.mv_neighbors_list(pbx, pby, pwb, 1);
                    let pmv = predict_mv(n[0], n[1], n[2], refi[p][1]);
                    let d = mvd1[i1];
                    i1 += 1;
                    mv[1] = (pmv.0 + d.0, pmv.1 + d.1);
                }
                self.b_set_motion(mb_x, mb_y, px, py, sw, sh, refi[p][0], mv[0], refi[p][1], mv[1]);
                self.b_mc(mb_x, mb_y, px, py, sw, sh, refi[p][0], mv[0], refi[p][1], mv[1], &mut pred_y, &mut c_pred);
            }
        }
        // noSubMbPartSizeLessThan8x8: each sub-partition must be ≥ 8×8 (direct
        // counts only with the 8×8 inference flag).
        let allow_8x8 = sub
            .iter()
            .all(|&st| if st == 0 { self.direct_8x8_inference } else { st <= 3 });
        self.inter_finish(r, mb_x, mb_y, &pred_y, &c_pred, allow_8x8)
    }

    /// Reconstructs a `P_8x8` macroblock: four 8×8 sub-macroblock partitions,
    /// each independently split (8×8 / 8×4 / 4×8 / 4×4) with its own motion
    /// vector(s). `ref0` is `P_8x8ref0` (every `ref_idx` forced to 0, not coded).
    fn decode_p8x8(
        &mut self,
        r: &mut BitReader,
        mb_x: usize,
        mb_y: usize,
        ref0: bool,
    ) -> Result<(), MbError> {
        if self.refs.is_empty() {
            return Err(MbError::Unsupported("inter without reference"));
        }
        let w4 = self.mb_w * 4;
        let (ch, cch) = (self.mb_h * 16, self.mb_h * 8);
        let num_refs = self.refs.len();

        // mb_pred order (spec §7.3.5.2): all sub_mb_type, then all ref_idx_l0,
        // then all mvd_l0 (partition-major, sub-partition order within each).
        let mut sub_types = [0u32; 4];
        for st in sub_types.iter_mut() {
            let v = r.read_ue()?;
            if v > 3 {
                return Err(MbError::Unsupported("B-slice / invalid sub_mb_type"));
            }
            *st = v;
        }
        let mut ref_idxs = [0i32; 4];
        if self.num_ref_active > 1 && !ref0 {
            for ri in ref_idxs.iter_mut() {
                *ri = read_ref_idx(r, self.num_ref_active)?;
                if *ri as usize >= num_refs {
                    return Err(MbError::Truncated); // references a non-existent picture
                }
            }
        }

        // Per sub-partition (in decoding order): median MV prediction from the
        // committed neighbor grid, mvd, commit, then motion-compensate. Committing
        // before the next prediction is what lets sub-partitions chain correctly.
        let mut pred_y = [0u8; 256];
        let mut c_pred = [[0u8; 64]; 2];
        for part in 0..4usize {
            let refi = ref_idxs[part];
            let (b8x, b8y) = ((part % 2) * 8, (part / 2) * 8);
            for &(srx, sry, srw, srh) in sub_mb_partitions(sub_types[part]) {
                let (px, py) = (b8x + srx, b8y + sry);
                let (pbx, pby) = ((mb_x * 4 + px / 4) as isize, (mb_y * 4 + py / 4) as isize);
                let [a, b, c] = self.mv_neighbors_block(pbx, pby, (srw / 4) as isize);
                let pmv = predict_mv(a, b, c, refi);
                let mvd_x = r.read_se()?;
                let mvd_y = r.read_se()?;
                let mv = (pmv.0 + mvd_x, pmv.1 + mvd_y);
                for by in py / 4..py / 4 + srh / 4 {
                    for bx in px / 4..px / 4 + srw / 4 {
                        let idx = (mb_y * 4 + by) * w4 + (mb_x * 4 + bx);
                        self.mv_y[idx] = mv;
                        self.inter_y[idx] = true;
                        self.ref_idx_y[idx] = refi;
                        self.coded_y[idx] = true;
                    }
                }
                let reference = &self.refs[refi as usize];
                let mut tmp = [0u8; 256];
                mc_luma(&reference.y, self.cw, ch, mb_x * 16 + px, mb_y * 16 + py, srw, srh, mv.0, mv.1, &mut tmp);
                for dy in 0..srh {
                    for dx in 0..srw {
                        pred_y[(py + dy) * 16 + (px + dx)] = tmp[dy * srw + dx];
                    }
                }
                let (crx, cry, crw, crh) = (px / 2, py / 2, srw / 2, srh / 2);
                for cc in 0..2 {
                    let rc = if cc == 0 { &reference.u } else { &reference.v };
                    let mut tc = [0u8; 64];
                    mc_chroma(rc, self.ccw, cch, mb_x * 8 + crx, mb_y * 8 + cry, crw, crh, mv.0, mv.1, &mut tc);
                    for dy in 0..crh {
                        for dx in 0..crw {
                            c_pred[cc][(cry + dy) * 8 + (crx + dx)] = tc[dy * crw + dx];
                        }
                    }
                }
                self.weight_partition(
                    &mut pred_y, &mut c_pred, 0, refi as usize, px, py, srw, srh,
                );
            }
        }

        // P_8x8 allows the 8×8 transform only when every sub-partition is 8×8.
        let allow_8x8 = sub_types.iter().all(|&t| t == 0);
        self.inter_finish(r, mb_x, mb_y, &pred_y, &c_pred, allow_8x8)
    }

    /// Reconstructs a `P_Skip` macroblock: motion-compensate from the reference
    /// at the skip MV, with no residual.
    fn decode_p_skip(&mut self, mb_x: usize, mb_y: usize) -> Result<(), MbError> {
        // P_Skip always references index 0 (the most recent picture). Borrow it —
        // a full-frame `.cloned()` here was ~86% of total decode time (one ~3 MB
        // plane copy per skip MB, thousands per frame).
        if self.refs.is_empty() {
            return Err(MbError::Unsupported("P_Skip without reference"));
        }
        let mv = self.skip_mv(mb_x, mb_y);
        let (ch, cch) = (self.mb_h * 16, self.mb_h * 8);

        let mut pred = [0u8; 256];
        mc_luma(&self.refs[0].y, self.cw, ch, mb_x * 16, mb_y * 16, 16, 16, mv.0, mv.1, &mut pred);
        if let Some(wt) = &self.weights {
            for p in pred.iter_mut() {
                *p = wt.apply_luma(*p, 0, 0);
            }
        }
        {
            let _g = rusty_h264_common::prof::scope(rusty_h264_common::prof::Stage::SkipRecon);
            for dy in 0..16 {
                let d = (mb_y * 16 + dy) * self.cw + mb_x * 16;
                self.rec_y[d..d + 16].copy_from_slice(&pred[dy * 16..dy * 16 + 16]);
            }
        }
        for c in 0..2 {
            let mut pc = [0u8; 64];
            let rc = if c == 0 { &self.refs[0].u } else { &self.refs[0].v };
            mc_chroma(rc, self.ccw, cch, mb_x * 8, mb_y * 8, 8, 8, mv.0, mv.1, &mut pc);
            if let Some(wt) = &self.weights {
                for p in pc.iter_mut() {
                    *p = wt.apply_chroma(*p, 0, 0, c);
                }
            }
            let plane = if c == 0 { &mut self.rec_u } else { &mut self.rec_v };
            for dy in 0..8 {
                let d = (mb_y * 8 + dy) * self.ccw + mb_x * 8;
                plane[d..d + 8].copy_from_slice(&pc[dy * 8..dy * 8 + 8]);
            }
        }
        {
            let _g = rusty_h264_common::prof::scope(rusty_h264_common::prof::Stage::SkipRecon);
            self.set_mb_mv(mb_x, mb_y, mv, true, 0);
            // Mark blocks coded; inter blocks count as DC (not I_4x4) for mode pred.
            let w4 = self.mb_w * 4;
            for &(lbx, lby) in &LUMA_4X4_SCAN_XY {
                self.coded_y[(mb_y * 4 + lby) * w4 + (mb_x * 4 + lbx)] = true;
                self.modes_y[(mb_y * 4 + lby) * w4 + (mb_x * 4 + lbx)] = 2;
            }
        }
        Ok(())
    }

    /// Predicted `Intra_4x4` mode for the block at absolute coords `(bx, by)`.
    /// If either the left or top neighbor is outside the frame or in another
    /// slice, the prediction is DC (mode 2) (spec §8.3.1.1).
    fn predict_i4_mode(&self, bx: usize, by: usize) -> u8 {
        if bx == 0 || by == 0 {
            return 2;
        }
        // Left neighbor block (bx-1,by); top neighbor block (bx,by-1). A neighbor
        // in another slice — or, under constrained_intra, an inter neighbor — is
        // unavailable, forcing the predicted mode to DC.
        if !self.nbr_in_slice((bx - 1) / 4, by / 4)
            || !self.nbr_in_slice(bx / 4, (by - 1) / 4)
            || !self.intra_nbr_ok(bx - 1, by)
            || !self.intra_nbr_ok(bx, by - 1)
        {
            return 2;
        }
        let w4 = self.mb_w * 4;
        self.modes_y[by * w4 + (bx - 1)].min(self.modes_y[(by - 1) * w4 + bx])
    }

    /// Gathers 4×4 luma intra neighbors at pixel `(px, py)` from `rec_y`.
    fn gather_i4(
        &self,
        px: usize,
        py: usize,
        avail_top: bool,
        avail_left: bool,
        bx: usize,
        by: usize,
    ) -> ([u8; 8], [u8; 4], u8) {
        let (cw, w4) = (self.cw, self.mb_w * 4);
        let mut top = [0u8; 8];
        let mut left = [0u8; 4];
        let mut corner = 0;
        if avail_top {
            for i in 0..4 {
                top[i] = self.rec_y[(py - 1) * cw + px + i];
            }
            let tr_avail = bx + 1 < w4
                && self.coded_y[(by - 1) * w4 + (bx + 1)]
                && self.nbr_in_slice((bx + 1) / 4, (by - 1) / 4)
                && self.intra_nbr_ok(bx + 1, by - 1);
            for i in 0..4 {
                top[4 + i] = if tr_avail {
                    self.rec_y[(py - 1) * cw + px + 4 + i]
                } else {
                    top[3]
                };
            }
        }
        if avail_left {
            for i in 0..4 {
                left[i] = self.rec_y[(py + i) * cw + px - 1];
            }
        }
        // The above-left corner has its own availability (block D); under
        // constrained_intra it is gone if that block is inter.
        if avail_top && avail_left && self.intra_nbr_ok(bx - 1, by - 1) {
            corner = self.rec_y[(py - 1) * cw + px - 1];
        }
        (top, left, corner)
    }

    /// Reconstructs an `I_PCM` macroblock: byte-aligned raw 8-bit samples, no
    /// prediction/transform/quant (spec §7.3.5, §8.3.5).
    fn decode_ipcm(&mut self, r: &mut BitReader, mb_x: usize, mb_y: usize) -> Result<(), MbError> {
        r.align_to_byte()?;
        let (lx, ly) = (mb_x * 16, mb_y * 16);
        for dy in 0..16 {
            for dx in 0..16 {
                self.rec_y[(ly + dy) * self.cw + (lx + dx)] = r.read_bits(8)? as u8;
            }
        }
        let (cx, cy) = (mb_x * 8, mb_y * 8);
        for plane in [&mut self.rec_u, &mut self.rec_v] {
            for dy in 0..8 {
                for dx in 0..8 {
                    plane[(cy + dy) * self.ccw + (cx + dx)] = r.read_bits(8)? as u8;
                }
            }
        }
        // Neighbor context: an I_PCM block contributes TotalCoeff = 16, counts as
        // intra with DC mode for prediction, and has no motion (§9.2.1, §8.3.1.2.2).
        let (w4, w2) = (self.mb_w * 4, self.mb_w * 2);
        for &(lbx, lby) in &LUMA_4X4_SCAN_XY {
            let idx = (mb_y * 4 + lby) * w4 + (mb_x * 4 + lbx);
            self.nnz_y[idx] = 16;
            self.modes_y[idx] = 2;
            self.inter_y[idx] = false;
            self.ref_idx_y[idx] = -1;
            self.mv_y[idx] = (0, 0);
        }
        for c in 0..2 {
            for by in 0..2 {
                for bx in 0..2 {
                    self.nnz_c[c][(mb_y * 2 + by) * w2 + (mb_x * 2 + bx)] = 16;
                }
            }
        }
        Ok(())
    }

    fn decode_i4x4(&mut self, r: &mut BitReader, mb_x: usize, mb_y: usize) -> Result<(), MbError> {
        let w4 = self.mb_w * 4;

        // intra4x4 mode signalling
        let mut modes = [2u8; 16]; // raster [lby*4+lbx]
        for &(lbx, lby) in &LUMA_4X4_SCAN_XY {
            let (bx, by) = (mb_x * 4 + lbx, mb_y * 4 + lby);
            let predicted = self.predict_i4_mode(bx, by);
            let actual = if r.read_bit()? {
                predicted
            } else {
                let rem = r.read_bits(3)? as u8;
                if rem < predicted {
                    rem
                } else {
                    rem + 1
                }
            };
            self.modes_y[by * w4 + bx] = actual;
            modes[lby * 4 + lbx] = actual;
        }

        let chroma_mode = r.read_ue()? as u8;
        let cbp = read_cbp_intra(r)?;
        let cbp_luma = cbp & 15;
        let cbp_chroma = cbp >> 4;
        if cbp != 0 {
            self.step_qp(r.read_se()?);
        }
        let qp = self.cur_qp;

        // luma residuals + serial reconstruction. Cross-MB neighbors are only
        // available when the adjacent macroblock is in this slice (and, under
        // constrained_intra_pred, is itself intra-coded).
        let top_mb_avail = mb_y > 0
            && self.nbr_in_slice(mb_x, mb_y - 1)
            && self.intra_nbr_ok(mb_x * 4, mb_y * 4 - 1);
        let left_mb_avail = mb_x > 0
            && self.nbr_in_slice(mb_x - 1, mb_y)
            && self.intra_nbr_ok(mb_x * 4 - 1, mb_y * 4);
        self.nnz_cache_load(mb_x, mb_y);
        for (blk, &(lbx, lby)) in LUMA_4X4_SCAN_XY.iter().enumerate() {
            let (bx, by) = (mb_x * 4 + lbx, mb_y * 4 + lby);
            let (px, py) = (bx * 4, by * 4);
            let avail_top = lby > 0 || top_mb_avail;
            let avail_left = lbx > 0 || left_mb_avail;
            let mut qb = [0i32; 16];
            let total = if cbp_luma & (1 << (blk / 4)) != 0 {
                let nc = self.nc_pred(lbx, lby);
                let scan16 = decode_residual_block(r, 16, nc)?;
                qb = un_scan_4x4_dcac(&scan16);
                scan16.iter().filter(|&&v| v != 0).count() as u8
            } else {
                0
            };
            self.nnz_cache_set(lbx, lby, total);
            self.nnz_y[by * w4 + bx] = total;
            let (top, left, corner) = self.gather_i4(px, py, avail_top, avail_left, bx, by);
            let pred = intra4x4_pred(modes[lby * 4 + lbx], avail_top, avail_left, &top, &left, corner);
            let mut predb = [0i32; 16];
            for i in 0..16 {
                predb[i] = pred[i] as i32;
            }
            let s = reconstruct_4x4(&self.dequant(&qb, qp, 0), &predb);
            store(&mut self.rec_y, self.cw, px, py, &s);
            self.coded_y[by * w4 + bx] = true;
        }

        self.decode_chroma(r, mb_x, mb_y, cbp_chroma, chroma_mode)
    }

    /// Decodes an `I_8x8` macroblock (High profile): four 8×8 luma blocks, each
    /// with its own intra mode, 8×8 transform residual (CAVLC = four interleaved
    /// 4×4 blocks), and 8×8 intra prediction.
    fn decode_i8x8(&mut self, r: &mut BitReader, mb_x: usize, mb_y: usize) -> Result<(), MbError> {
        let w4 = self.mb_w * 4;
        self.mb_t8x8[mb_y * self.mb_w + mb_x] = true;

        // intra8x8 mode signalling — one mode per 8×8 block (raster 0..3),
        // stored into all four of its 4×4 cells so neighbors can read it.
        let mut modes8 = [2u8; 4];
        for (b8, mode) in modes8.iter_mut().enumerate() {
            let (b8x, b8y) = (b8 % 2, b8 / 2);
            let (bx, by) = (mb_x * 4 + b8x * 2, mb_y * 4 + b8y * 2);
            let predicted = self.predict_i4_mode(bx, by);
            let actual = if r.read_bit()? {
                predicted
            } else {
                let rem = r.read_bits(3)? as u8;
                if rem < predicted { rem } else { rem + 1 }
            };
            *mode = actual;
            for sy in 0..2 {
                for sx in 0..2 {
                    self.modes_y[(by + sy) * w4 + (bx + sx)] = actual;
                }
            }
        }

        let chroma_mode = r.read_ue()? as u8;
        let cbp = read_cbp_intra(r)?;
        let cbp_luma = cbp & 15;
        let cbp_chroma = cbp >> 4;
        if cbp != 0 {
            self.step_qp(r.read_se()?);
        }
        let qp = self.cur_qp;

        let top_mb_avail = mb_y > 0
            && self.nbr_in_slice(mb_x, mb_y - 1)
            && self.intra_nbr_ok(mb_x * 4, mb_y * 4 - 1);
        let left_mb_avail = mb_x > 0
            && self.nbr_in_slice(mb_x - 1, mb_y)
            && self.intra_nbr_ok(mb_x * 4 - 1, mb_y * 4);
        self.nnz_cache_load(mb_x, mb_y);

        for b8 in 0..4 {
            let (b8x, b8y) = (b8 % 2, b8 / 2);
            let (bx, by) = (mb_x * 4 + b8x * 2, mb_y * 4 + b8y * 2);
            let (px, py) = (bx * 4, by * 4);

            // residual: 8×8 CAVLC = four 4×4 sub-blocks, coeff k of sub-block s
            // mapping to 8×8 scan position 4·k + s (spec §7.3.5.3.2).
            let mut res8 = [0i32; 64];
            if cbp_luma & (1 << b8) != 0 {
                let mut scan8 = [0i32; 64];
                for sub in 0..4 {
                    let (sx, sy) = (sub % 2, sub / 2);
                    let (cx, cy) = (b8x * 2 + sx, b8y * 2 + sy);
                    let nc = self.nc_pred(cx, cy);
                    let blk = decode_residual_block(r, 16, nc)?;
                    let total = blk.iter().filter(|&&v| v != 0).count() as u8;
                    self.nnz_cache_set(cx, cy, total);
                    self.nnz_y[(by + sy) * w4 + (bx + sx)] = total;
                    for k in 0..16 {
                        scan8[4 * k + sub] = blk[k];
                    }
                }
                let raster = un_scan_8x8(&scan8);
                res8 = self.inv_quant8(&raster, qp, 0);
            } else {
                for sub in 0..4 {
                    let (sx, sy) = (sub % 2, sub / 2);
                    self.nnz_cache_set(b8x * 2 + sx, b8y * 2 + sy, 0);
                    self.nnz_y[(by + sy) * w4 + (bx + sx)] = 0;
                }
            }

            let avail_top = b8y > 0 || top_mb_avail;
            let avail_left = b8x > 0 || left_mb_avail;
            let (top, left, corner, avail_corner) =
                self.gather_i8(px, py, avail_top, avail_left, bx, by);
            let pred = intra8x8_pred(
                modes8[b8], avail_top, avail_left, avail_corner, &top, &left, corner,
            );
            let mut predb = [0i32; 64];
            for i in 0..64 {
                predb[i] = pred[i] as i32;
            }
            let recon = add_residual_8x8(&res8, &predb);
            for dy in 0..8 {
                for dx in 0..8 {
                    self.rec_y[(py + dy) * self.cw + (px + dx)] = recon[dy * 8 + dx];
                }
            }
            for sy in 0..2 {
                for sx in 0..2 {
                    self.coded_y[(by + sy) * w4 + (bx + sx)] = true;
                }
            }
        }

        self.decode_chroma(r, mb_x, mb_y, cbp_chroma, chroma_mode)
    }

    /// Dequantizes + inverse-transforms an 8×8 luma block, applying the scaling
    /// matrix `list` (0 = intra, 1 = inter) or flat weights.
    fn inv_quant8(&self, raster: &[i32; 64], qp: u8, list: usize) -> [i32; 64] {
        match &self.scaling8 {
            Some(s) => inverse_quant_8x8(raster, qp, &s[list]),
            None => inverse_quant_8x8(raster, qp, &[16i32; 64]),
        }
    }

    /// Gathers the 8×8 luma intra reference samples at pixel `(px, py)`: the 16
    /// top samples (8..15 substituted from the last when no top-right), 8 left
    /// samples, the above-left corner, and whether the corner is available.
    #[allow(clippy::too_many_arguments)]
    fn gather_i8(
        &self,
        px: usize,
        py: usize,
        avail_top: bool,
        avail_left: bool,
        bx: usize,
        by: usize,
    ) -> ([u8; 16], [u8; 8], u8, bool) {
        let (cw, w4) = (self.cw, self.mb_w * 4);
        let mut top = [0u8; 16];
        let mut left = [0u8; 8];
        let mut corner = 0;
        if avail_top {
            for i in 0..8 {
                top[i] = self.rec_y[(py - 1) * cw + px + i];
            }
            let tr_avail = bx + 2 < w4
                && self.coded_y[(by - 1) * w4 + (bx + 2)]
                && self.nbr_in_slice((bx + 2) / 4, (by - 1) / 4)
                && self.intra_nbr_ok(bx + 2, by - 1);
            for i in 0..8 {
                top[8 + i] = if tr_avail {
                    self.rec_y[(py - 1) * cw + px + 8 + i]
                } else {
                    top[7]
                };
            }
        }
        if avail_left {
            for i in 0..8 {
                left[i] = self.rec_y[(py + i) * cw + px - 1];
            }
        }
        let avail_corner = avail_top && avail_left && self.intra_nbr_ok(bx - 1, by - 1);
        if avail_corner {
            corner = self.rec_y[(py - 1) * cw + px - 1];
        }
        (top, left, corner, avail_corner)
    }

    fn decode_i16(
        &mut self,
        r: &mut BitReader,
        mb_x: usize,
        mb_y: usize,
        mt: u32,
    ) -> Result<(), MbError> {
        let pred_mode = I16Mode::from_id(mt % 4);
        let cbp_chroma = (mt % 12) / 4;
        let cbp_luma_15 = mt / 12 == 1;
        let chroma_mode = r.read_ue()? as u8;
        self.step_qp(r.read_se()?);
        let qp = self.cur_qp;
        let w4 = self.mb_w * 4;

        // luma DC
        self.nnz_cache_load(mb_x, mb_y);
        let nc_dc = self.nc_pred(0, 0);
        let dc_scan = decode_residual_block(r, 16, nc_dc)?;
        let dc_levels = un_scan_4x4_dcac(&dc_scan);
        let recon_dc = self.dequant_luma_dc(&dc_levels, qp, 0);

        // luma AC (nnz set for all 16 blocks: 0 when DC-only, matching the encoder)
        let mut q_blocks = [[0i32; 16]; 16];
        for &(bx, by) in &LUMA_4X4_SCAN_XY {
            let total = if cbp_luma_15 {
                let nc = self.nc_pred(bx, by);
                let ac = decode_residual_block(r, 15, nc)?;
                un_scan_4x4_ac_into(&ac, &mut q_blocks[by * 4 + bx]);
                ac.iter().filter(|&&v| v != 0).count() as u8
            } else {
                0
            };
            self.nnz_cache_set(bx, by, total);
            self.nnz_y[(mb_y * 4 + by) * w4 + (mb_x * 4 + bx)] = total;
        }

        // prediction + reconstruction
        let avail_top = mb_y > 0
            && self.nbr_in_slice(mb_x, mb_y - 1)
            && self.intra_nbr_ok(mb_x * 4, mb_y * 4 - 1);
        let avail_left = mb_x > 0
            && self.nbr_in_slice(mb_x - 1, mb_y)
            && self.intra_nbr_ok(mb_x * 4 - 1, mb_y * 4);
        let (lx, ly) = (mb_x * 16, mb_y * 16);
        let mut top = [0u8; 16];
        let mut left = [0u8; 16];
        if avail_top {
            for i in 0..16 {
                top[i] = self.rec_y[(ly - 1) * self.cw + lx + i];
            }
        }
        if avail_left {
            for i in 0..16 {
                left[i] = self.rec_y[(ly + i) * self.cw + lx - 1];
            }
        }
        let corner = if avail_top && avail_left {
            self.rec_y[(ly - 1) * self.cw + lx - 1]
        } else {
            0
        };
        let pred_l = luma16x16_pred(pred_mode, avail_top, avail_left, &top, &left, corner);
        for by in 0..4 {
            for bx in 0..4 {
                let mut deq = self.dequant(&q_blocks[by * 4 + bx], qp, 0);
                deq[0] = recon_dc[by * 4 + bx];
                let mut predb = [0i32; 16];
                for dy in 0..4 {
                    for dx in 0..4 {
                        predb[dy * 4 + dx] = pred_l[(by * 4 + dy) * 16 + (bx * 4 + dx)] as i32;
                    }
                }
                let s = reconstruct_4x4(&deq, &predb);
                store(&mut self.rec_y, self.cw, lx + bx * 4, ly + by * 4, &s);
            }
        }
        // I_16x16 blocks are treated as DC for neighbor mode prediction.
        for &(lbx, lby) in &LUMA_4X4_SCAN_XY {
            self.modes_y[(mb_y * 4 + lby) * w4 + (mb_x * 4 + lbx)] = 2;
        }

        self.decode_chroma(r, mb_x, mb_y, cbp_chroma, chroma_mode)
    }

    /// Reads and reconstructs the chroma residual (shared by both luma types).
    fn decode_chroma(
        &mut self,
        r: &mut BitReader,
        mb_x: usize,
        mb_y: usize,
        cbp_chroma: u32,
        chroma_mode: u8,
    ) -> Result<(), MbError> {
        let qpc = self.chroma_qp_for(self.cur_qp);
        let (cx, cy) = (mb_x * 8, mb_y * 8);
        let avail_top = mb_y > 0
            && self.nbr_in_slice(mb_x, mb_y - 1)
            && self.intra_nbr_ok(mb_x * 4, mb_y * 4 - 1);
        let avail_left = mb_x > 0
            && self.nbr_in_slice(mb_x - 1, mb_y)
            && self.intra_nbr_ok(mb_x * 4 - 1, mb_y * 4);

        let mut c_recon_dc = [[0i32; 4]; 2];
        if cbp_chroma != 0 {
            for (c, slot) in c_recon_dc.iter_mut().enumerate() {
                let dc = decode_residual_block(r, 4, -1)?;
                *slot = self.dequant_chroma_dc(&[dc[0], dc[1], dc[2], dc[3]], qpc, 1 + c);
            }
        }
        let mut c_q_blocks = [[[0i32; 16]; 4]; 2];
        if cbp_chroma == 2 {
            self.chroma_cache_load(mb_x, mb_y);
            let w2 = self.mb_w * 2;
            for c in 0..2 {
                for &(bx, by) in &CHROMA_4X4_SCAN_XY {
                    let nc = self.chroma_nc_pred(c, bx, by);
                    let ac = decode_residual_block(r, 15, nc)?;
                    let total = ac.iter().filter(|&&v| v != 0).count() as u8;
                    self.chroma_nnz_cache_set(c, bx, by, total);
                    self.nnz_c[c][(mb_y * 2 + by) * w2 + (mb_x * 2 + bx)] = total;
                    un_scan_4x4_ac_into(&ac, &mut c_q_blocks[c][by * 2 + bx]);
                }
            }
        }
        for c in 0..2 {
            let mut ctop = [0u8; 8];
            let mut cleft = [0u8; 8];
            let mut ccorner = 0u8;
            {
                let rec_c = if c == 0 { &self.rec_u } else { &self.rec_v };
                if avail_top {
                    for i in 0..8 {
                        ctop[i] = rec_c[(cy - 1) * self.ccw + cx + i];
                    }
                }
                if avail_left {
                    for i in 0..8 {
                        cleft[i] = rec_c[(cy + i) * self.ccw + cx - 1];
                    }
                }
                if avail_top && avail_left {
                    ccorner = rec_c[(cy - 1) * self.ccw + cx - 1];
                }
            }
            let pred8 = chroma8x8_pred(chroma_mode, avail_top, avail_left, &ctop, &cleft, ccorner);
            for &(bx, by) in &CHROMA_4X4_SCAN_XY {
                let mut predb = [0i32; 16];
                for dy in 0..4 {
                    for dx in 0..4 {
                        predb[dy * 4 + dx] = pred8[(by * 4 + dy) * 8 + (bx * 4 + dx)] as i32;
                    }
                }
                let mut deq = self.dequant(&c_q_blocks[c][by * 2 + bx], qpc, 1 + c);
                deq[0] = c_recon_dc[c][by * 2 + bx];
                let s = reconstruct_4x4(&deq, &predb);
                let plane = if c == 0 { &mut self.rec_u } else { &mut self.rec_v };
                store(plane, self.ccw, cx + bx * 4, cy + by * 4, &s);
            }
        }
        Ok(())
    }

    /// Applies the in-loop deblocking filter to the reconstructed frame, with
    /// the slice's `FilterOffsetA`/`FilterOffsetB` (each = the coded `*_div2`
    /// value × 2).
    pub fn deblock(&mut self, offset_a: i32, offset_b: i32) {
        // Deblock boundary strength uses the *transform block's* coded status. For
        // an 8×8-transform macroblock the unit is the whole 8×8, so every 4×4 cell
        // shares the 8×8's coefficient presence (OR of its four sub-block counts)
        // — distinct from the per-sub-block `nnz_y` used for the CAVLC nC context.
        // Only differs from `nnz_y` when some MB uses the 8×8 transform (High
        // profile). On Baseline (no 8×8) it's identical — skip the clone + rewrite.
        let nnz_db_storage;
        let nnz_db: &[u8] = if self.mb_t8x8.iter().any(|&t| t) {
            let mut n = self.nnz_y.clone();
            let w4 = self.mb_w * 4;
            for mb_y in 0..self.mb_h {
                for mb_x in 0..self.mb_w {
                    if !self.mb_t8x8[mb_y * self.mb_w + mb_x] {
                        continue;
                    }
                    for b8 in 0..4 {
                        let (bx, by) = (mb_x * 4 + (b8 % 2) * 2, mb_y * 4 + (b8 / 2) * 2);
                        let any = (0..2).any(|sy| (0..2).any(|sx| self.nnz_y[(by + sy) * w4 + (bx + sx)] > 0));
                        for sy in 0..2 {
                            for sx in 0..2 {
                                n[(by + sy) * w4 + (bx + sx)] = u8::from(any);
                            }
                        }
                    }
                }
            }
            nnz_db_storage = n;
            &nnz_db_storage
        } else {
            &self.nnz_y
        };
        // Map per-block reference indices to a stable picture identity (POC) so
        // the boundary-strength comparison recognises the same picture across lists.
        let ref_id: Vec<i32> = self
            .ref_idx_y
            .iter()
            .map(|&r| if r >= 0 { self.refs.get(r as usize).map_or(i32::MIN, |f| f.poc) } else { i32::MIN })
            .collect();
        // List-1 identities are read only by B bi-pred edges; on P frames `refs1` is
        // empty (every entry would be NO_REF), so skip the whole per-block collect.
        let ref_id1: Vec<i32> = if self.refs1.is_empty() {
            Vec::new()
        } else {
            self.ref_idx1
                .iter()
                .map(|&r| if r >= 0 { self.refs1.get(r as usize).map_or(i32::MIN, |f| f.poc) } else { i32::MIN })
                .collect()
        };
        let info = rusty_h264_common::deblock::BlockInfo {
            inter: &self.inter_y,
            nnz: nnz_db,
            mv: &self.mv_y,
            ref_id: &ref_id,
            mv1: &self.mv1,
            ref_id1: &ref_id1,
            w4: self.mb_w * 4,
            t8x8: &self.mb_t8x8,
            bs: &[],
        };
        rusty_h264_common::deblock::filter_frame(
            &mut self.rec_y,
            &mut self.rec_u,
            &mut self.rec_v,
            self.mb_w,
            self.mb_h,
            &self.mb_qp,
            self.chroma_qp_offset,
            offset_a,
            offset_b,
            &info,
        );
    }

    /// Crops the reconstructed coded-size planes to the display window.
    pub fn into_frame(self, crop_r: usize, crop_b: usize) -> YuvFrame {
        // No cropping (the common case): the reconstruction planes ARE the output —
        // move them out instead of allocating + copying three full planes per frame.
        if crop_r == 0 && crop_b == 0 {
            return YuvFrame {
                width: self.cw,
                height: self.ch,
                y: self.rec_y,
                u: self.rec_u,
                v: self.rec_v,
            };
        }
        let dw = self.cw - 2 * crop_r;
        let dh = self.ch - 2 * crop_b;
        let mut y = vec![0u8; dw * dh];
        for row in 0..dh {
            y[row * dw..row * dw + dw].copy_from_slice(&self.rec_y[row * self.cw..row * self.cw + dw]);
        }
        let (cdw, cdh) = (dw / 2, dh / 2);
        let mut u = vec![0u8; cdw * cdh];
        let mut v = vec![0u8; cdw * cdh];
        for row in 0..cdh {
            u[row * cdw..row * cdw + cdw]
                .copy_from_slice(&self.rec_u[row * self.ccw..row * self.ccw + cdw]);
            v[row * cdw..row * cdw + cdw]
                .copy_from_slice(&self.rec_v[row * self.ccw..row * self.ccw + cdw]);
        }
        let _ = self.cch;
        YuvFrame {
            width: dw,
            height: dh,
            y,
            u,
            v,
        }
    }
}

/// Reads `ref_idx_l0` as `te(v)` with range `num_ref_active - 1`: a single flag
/// when exactly two references are active (cMax == 1), else `ue(v)`.
// ---- CABAC binarization engine helpers (openh264 cabac_decoder.cpp) ----

/// Unary bin (`DecodeUnaryBinCabac`): bin0 at `ctx`; if 1, count bins at `ctx+off`
/// (including the terminating 0) until a 0.
fn cabac_unary(cab: &mut crate::cabac::Cabac, ctx: usize, off: usize) -> u32 {
    if cab.decode_decision(ctx) == 0 {
        return 0;
    }
    let mut sym = 0;
    loop {
        let bin = cab.decode_decision(ctx + off);
        sym += 1;
        // Cap the unary run: no valid H.264 element coded through this helper
        // (mb_qp_delta) exceeds a few dozen bins, but on malformed / buffer-exhausted
        // input the arithmetic engine keeps yielding 1s (it zero-fills past the end),
        // which would loop forever. 512 is far beyond any legal value.
        if bin == 0 || sym >= 512 {
            break;
        }
    }
    sym
}

/// k-th order Exp-Golomb in bypass (`DecodeExpBypassCabac`).
fn cabac_exp_bypass(cab: &mut crate::cabac::Cabac, mut count: i32) -> u32 {
    let mut sym = 0u32;
    loop {
        let c = cab.decode_bypass();
        if c == 1 {
            sym += 1 << count;
            count += 1;
        }
        if c == 0 || count == 16 {
            break;
        }
    }
    let mut sym2 = 0u32;
    while count > 0 {
        count -= 1;
        if cab.decode_bypass() != 0 {
            sym2 |= 1 << count;
        }
    }
    sym + sym2
}

/// UEG0 coeff-level suffix (`DecodeUEGLevelCabac`): TU prefix at `ctx` (≤13) then an
/// EG0 bypass suffix.
fn cabac_ueg_level(cab: &mut crate::cabac::Cabac, ctx: usize) -> u32 {
    if cab.decode_decision(ctx) == 0 {
        return 0;
    }
    let mut code = 0u32;
    let mut count = 1;
    let mut tmp;
    loop {
        tmp = cab.decode_decision(ctx);
        code += 1;
        count += 1;
        if tmp == 0 || count == 13 {
            break;
        }
    }
    if tmp != 0 {
        code += cabac_exp_bypass(cab, 0) + 1;
    }
    code
}

/// `mb_qp_delta` CABAC (`ParseDeltaQpCabac`): ctxIdxOffset 60, ctxInc = (prev delta ≠ 0).
fn parse_mb_qp_delta_cabac(cab: &mut crate::cabac::Cabac, last_delta_qp: &mut i32) -> i32 {
    const O: usize = 60;
    let ctx_inc = (*last_delta_qp != 0) as usize;
    let mut qp_delta = 0;
    if cab.decode_decision(O + ctx_inc) != 0 {
        let code = cabac_unary(cab, O + 2, 1) + 1;
        qp_delta = ((code + 1) >> 1) as i32;
        if code & 1 == 0 {
            qp_delta = -qp_delta;
        }
    }
    *last_delta_qp = qp_delta;
    qp_delta
}

/// z-order block → padded (8-stride) nzc-cache index (openh264 g_kCacheNzcScanIdx):
/// 16 luma, 4 Cb, 4 Cr. Top neighbour = cache[idx-8], left = cache[idx-1].
const NZC_CACHE: [usize; 24] = [
    9, 10, 17, 18, 11, 12, 19, 20, 25, 26, 33, 34, 27, 28, 35, 36, // luma
    14, 15, 22, 23, // Cb
    38, 39, 46, 47, // Cr
];

// g_kBlockCat2CtxOffset* + maxPos/maxC2, indexed by CABAC res-property (1..10; 0 unused).
const RES_MAXPOS: [i32; 11] = [0, 15, 14, 15, 3, 14, 63, 3, 3, 14, 14];
const RES_MAXC2: [i32; 11] = [0, 4, 4, 4, 3, 4, 4, 3, 3, 4, 4];
const RES_CBF: [usize; 11] = [0, 0, 4, 8, 12, 16, 0, 12, 12, 16, 16];
const RES_MAP: [usize; 11] = [0, 0, 15, 29, 44, 47, 0, 44, 44, 47, 47];
const RES_ONE: [usize; 11] = [0, 0, 10, 20, 30, 39, 0, 30, 30, 39, 39];
// res-property values (post GetMbResProperty, CABAC): the ctx-table index.
const RP_I16_DC: usize = 1;
const RP_I16_AC: usize = 2;
const RP_LUMA_4X4: usize = 3;
const RP_CHROMA_DC: usize = 7; // U (V=8, same offsets)
const RP_CHROMA_AC: usize = 9; // U (V=10, same offsets)

/// One residual block (openh264 `ParseResidualBlockCabac`), generic over the 5 CABAC
/// block categories. `rp` selects the context offsets. DC categories (I16 luma DC,
/// chroma DC) take the cbf context from the per-MB `cbf_dc` bitmask + neighbour MB DC
/// cbf; AC categories from the padded nzc cache. Returns totalCoeffNum.
#[allow(clippy::too_many_arguments)]
fn parse_residual_cabac(
    cab: &mut crate::cabac::Cabac,
    nzc: &mut [u8; 48],
    cbf_dc: &mut u16,
    iz: usize,
    rp: usize,
    is_intra: bool,
    ndc: (Option<u16>, Option<u16>), // (top MB cbf_dc, left MB cbf_dc); None = unavailable
    out: &mut [i32],                 // scan-order coefficients written here (len ≥ maxPos+1)
) -> u32 {
    // ---- coded_block_flag ----
    let is_dc = rp == RP_I16_DC || rp == RP_CHROMA_DC || rp == RP_CHROMA_DC + 1;
    let (mut na, mut nb) = (is_intra as u8, is_intra as u8);
    let scan = NZC_CACHE[iz.min(23)];
    if is_dc {
        if let Some(t) = ndc.0 {
            nb = ((t >> rp) & 1) as u8;
        }
        if let Some(l) = ndc.1 {
            na = ((l >> rp) & 1) as u8;
        }
    } else {
        if nzc[scan - 8] != 0xff {
            nb = (nzc[scan - 8] != 0) as u8;
        }
        if nzc[scan - 1] != 0xff {
            na = (nzc[scan - 1] != 0) as u8;
        }
    }
    let cbf = cab.decode_decision(85 + RES_CBF[rp] + (na + (nb << 1)) as usize);
    if cbf == 0 {
        if !is_dc {
            nzc[scan] = 0;
        }
        return 0;
    }
    if is_dc {
        *cbf_dc |= 1 << rp;
    }
    // ---- significance map ----
    let maxpos = RES_MAXPOS[rp] as usize;
    let map = 105 + RES_MAP[rp];
    let last = 166 + RES_MAP[rp];
    let mut sig = [0i32; 64];
    let mut coeff_num = 0u32;
    let mut last_hit = false;
    for i in 0..maxpos {
        if cab.decode_decision(map + i) != 0 {
            sig[i] = 1;
            coeff_num += 1;
            if cab.decode_decision(last + i) != 0 {
                last_hit = true;
                break;
            }
        }
    }
    if !last_hit {
        sig[maxpos] = 1;
        coeff_num += 1;
    }
    // ---- levels ----
    let one = 227 + RES_ONE[rp];
    let abs = 232 + RES_ONE[rp];
    let maxc2 = RES_MAXC2[rp];
    let (mut c1, mut c2) = (1i32, 0i32);
    for i in (0..=maxpos).rev() {
        if sig[i] != 0 {
            let mut level = sig[i] + cab.decode_decision(one + c1 as usize) as i32;
            if level == 2 {
                level += cabac_ueg_level(cab, abs + c2 as usize) as i32;
                c2 = (c2 + 1).min(maxc2);
                c1 = 0;
            } else if c1 != 0 {
                c1 = (c1 + 1).min(4);
            }
            if cab.decode_bypass() != 0 {
                level = -level;
            }
            sig[i] = level;
        }
    }
    out[..=maxpos].copy_from_slice(&sig[..=maxpos]);
    if !is_dc {
        nzc[scan] = coeff_num as u8;
    }
    coeff_num
}

/// 4×4-block (z-order) → 30-entry (6-stride) mv/ref/mvd cache index (openh264
/// g_kCache30ScanIdx). Top neighbour = cache[idx-6], left = cache[idx-1].
const CACHE30: [usize; 16] = [7, 8, 13, 14, 9, 10, 15, 16, 19, 20, 25, 26, 21, 22, 27, 28];

/// z-order 4×4-block → raster index (openh264 g_kuiScan4). Per-MB mvd/ref state is
/// stored raster-indexed (matching how neighbour blocks 3/7/11/15 and 12..15 are read).
const G_SCAN4: [usize; 16] = [0, 1, 4, 5, 2, 3, 6, 7, 8, 9, 12, 13, 10, 11, 14, 15];

/// P `sub_mb_type` CABAC (openh264 `ParseSubMBTypeCabac`, ctx 21). 0=8×8, 1=8×4, 2=4×8, 3=4×4.
fn parse_sub_mb_type_p_cabac(cab: &mut crate::cabac::Cabac) -> u32 {
    const S: usize = 21;
    if cab.decode_decision(S) != 0 {
        return 0;
    }
    if cab.decode_decision(S + 1) != 0 {
        3 - cab.decode_decision(S + 2)
    } else {
        1
    }
}

/// Intra `mb_type` sub-parse for P/B slices (openh264 `DecodeCabacIntraMbType`, `base`=32
/// for B). Returns 0 = I_4x4, 1..=24 = I_16x16, 25 = I_PCM (in the intra numbering).
fn parse_intra_mb_type_cabac(cab: &mut crate::cabac::Cabac, base: usize) -> u32 {
    if cab.decode_decision(base) == 0 {
        return 0; // I_4x4
    }
    if cab.decode_terminate() {
        return 25; // I_PCM
    }
    let mut t = 1 + 12 * cab.decode_decision(base + 1) as u32; // cbp_luma != 0
    if cab.decode_decision(base + 2) != 0 {
        t += 4 + 4 * cab.decode_decision(base + 2) as u32;
    }
    t += 2 * cab.decode_decision(base + 3) as u32;
    t += cab.decode_decision(base + 3) as u32;
    t
}

/// B `mb_type` CABAC (openh264 `ParseMBTypeBSliceCabac`, ctx base 27). `ctx_inc` = (left
/// avail & !direct) + (top avail & !direct). Returns 0 = B_Direct_16x16, 1..=21 = the
/// L0/L1/Bi 16×16/16×8/8×16 shapes, 22 = B_8x8, 23.. = intra (mb_type − 23).
fn parse_mb_type_b_cabac(cab: &mut crate::cabac::Cabac, ctx_inc: usize) -> u32 {
    const B: usize = 27;
    if cab.decode_decision(B + ctx_inc) == 0 {
        return 0; // B_Direct_16x16
    }
    if cab.decode_decision(B + 3) == 0 {
        return 1 + cab.decode_decision(B + 5) as u32; // 16×16 L0 / L1
    }
    let mut m = (cab.decode_decision(B + 4) as u32) << 3;
    m |= (cab.decode_decision(B + 5) as u32) << 2;
    m |= (cab.decode_decision(B + 5) as u32) << 1;
    m |= cab.decode_decision(B + 5) as u32;
    if m < 8 {
        return m + 3;
    }
    if m == 13 {
        return parse_intra_mb_type_cabac(cab, 32) + 23;
    }
    if m == 14 {
        return 11; // B_Bi_8x16
    }
    if m == 15 {
        return 22; // B_8x8
    }
    m = (m << 1) | cab.decode_decision(B + 5) as u32;
    m - 4
}

/// B `sub_mb_type` CABAC (openh264 `ParseBSubMBTypeCabac`, ctx base 36). Returns 0..=12
/// per spec Table 7-18 (0 = B_Direct_8x8, 1 = B_L0_8x8, …, 12 = B_Bi_4x4).
fn parse_sub_mb_type_b_cabac(cab: &mut crate::cabac::Cabac) -> u32 {
    const B: usize = 36;
    if cab.decode_decision(B) == 0 {
        return 0; // B_Direct_8x8
    }
    if cab.decode_decision(B + 1) == 0 {
        return 1 + cab.decode_decision(B + 3) as u32; // B_L0_8x8 / B_L1_8x8
    }
    let mut st = 3u32;
    if cab.decode_decision(B + 2) != 0 {
        if cab.decode_decision(B + 3) != 0 {
            return 11 + cab.decode_decision(B + 3) as u32; // B_L1_4x4 / B_Bi_4x4
        }
        st += 4;
    }
    st += 2 * cab.decode_decision(B + 3) as u32;
    st += cab.decode_decision(B + 3) as u32;
    st
}

/// Parse one motion partition's `mvd` (x,y) and splat it into the 30-entry cache + the
/// per-MB raster mvd/ref state. `part_idx` = the partition's top-left z-order block (for
/// the ctxInc neighbour lookup); `zblocks` = every z-order 4×4 block the partition covers.
fn parse_mvd_partition(
    cab: &mut crate::cabac::Cabac,
    part_idx: usize,
    zblocks: &[usize],
    mvdc: &mut [[i16; 2]; 30],
    refc: &mut [i8; 30],
    mmvd: &mut [[i16; 2]; 16],
    mref: &mut [i8; 16],
    ref_idx: i8,
) -> (i32, i32) {
    let s = CACHE30[part_idx];
    let ctx = |comp: usize| -> usize {
        let mut a = 0i32;
        if refc[s - 6] >= 0 {
            a += mvdc[s - 6][comp].unsigned_abs() as i32;
        }
        if refc[s - 1] >= 0 {
            a += mvdc[s - 1][comp].unsigned_abs() as i32;
        }
        if a >= 3 {
            1 + (a > 32) as usize
        } else {
            0
        }
    };
    let (cx, cy) = (ctx(0), ctx(1));
    let mvx = parse_mvd_cabac(cab, 0, cx);
    let mvy = parse_mvd_cabac(cab, 1, cy);
    for &zb in zblocks {
        mvdc[CACHE30[zb]] = [mvx, mvy];
        refc[CACHE30[zb]] = ref_idx;
        mmvd[G_SCAN4[zb]] = [mvx, mvy];
        mref[G_SCAN4[zb]] = ref_idx;
    }
    (mvx as i32, mvy as i32)
}

/// `ref_idx_l0` (P) CABAC — mirror of the encoder `cb_ref_idx`. Unary, ctxIdxOffset
/// 54: binIdx 0 → `ctx0` (condTermFlagA + 2·condTermFlagB), binIdx 1 → 4, binIdx ≥2 → 5.
fn parse_ref_idx_cabac(cab: &mut crate::cabac::Cabac, ctx0: usize) -> i8 {
    const B: usize = 54;
    let mut r = 0i8;
    let mut bin_idx = 0u32;
    // Cap the unary length: valid ref_idx ≤ 15 (16 refs max); the cap keeps a corrupt
    // stream from looping unboundedly. The MC clamps the index, so an over-range value
    // is decoded as garbage (never a panic) — the robustness contract, not correctness.
    while bin_idx < 32 {
        let ctx = match bin_idx {
            0 => ctx0,
            1 => 4,
            _ => 5,
        };
        if cab.decode_decision(B + ctx) == 0 {
            break;
        }
        r += 1;
        bin_idx += 1;
    }
    r
}

/// UEG3 mvd suffix (openh264 `DecodeUEGMvCabac`): TU prefix at `base + {0,1,2,3,3,..}`
/// (≤7), then EG3 bypass.
fn decode_ueg_mv(cab: &mut crate::cabac::Cabac, base: usize) -> u32 {
    const P2C: [usize; 8] = [0, 1, 2, 3, 3, 3, 3, 3];
    if cab.decode_decision(base) == 0 {
        return 0;
    }
    let mut code = 0u32;
    let mut count = 1usize;
    let mut tmp;
    loop {
        tmp = cab.decode_decision(base + P2C[count]);
        code += 1;
        count += 1;
        if tmp == 0 || count == 8 {
            break;
        }
    }
    if tmp != 0 {
        code += cabac_exp_bypass(cab, 3) + 1;
    }
    code
}

/// One `mvd` component (openh264 `ParseMvdInfoCabac`). `ctx_inc` (0/1/2) from the
/// neighbour |mvd| sum. ctxIdxOffset 40 (x) / 47 (y).
fn parse_mvd_cabac(cab: &mut crate::cabac::Cabac, comp: usize, ctx_inc: usize) -> i16 {
    let base = 40 + comp * 7; // NEW_CTX_OFFSET_MVD + comp*CTX_NUM_MVD
    if cab.decode_decision(base + ctx_inc) == 0 {
        return 0;
    }
    let mag = (decode_ueg_mv(cab, base + 3) + 1) as i16;
    if cab.decode_bypass() != 0 {
        -mag
    } else {
        mag
    }
}

/// `mb_skip_flag` CABAC (openh264 `ParseSkipFlagCabac`). `ctx_inc` = base 11 (P) or 24
/// (B) + (left avail & not-skip) + (top avail & not-skip). Returns true if skipped.
fn parse_mb_skip_cabac(cab: &mut crate::cabac::Cabac, ctx_inc: usize) -> bool {
    cab.decode_decision(ctx_inc) != 0
}

/// P-slice `mb_type` CABAC (openh264 `ParseMBTypePSliceCabac`). Returns 0..3 = inter
/// (P_L0_16x16 / P_16x8 / P_8x16 / P_8x8), 5 = I_4x4, 6..29 = I_16x16, 30 = I_PCM.
fn parse_mb_type_p_cabac(cab: &mut crate::cabac::Cabac) -> u32 {
    const S: usize = 11; // NEW_CTX_OFFSET_SKIP; P mb_type contexts hang off it
    if cab.decode_decision(S + 3) == 0 {
        // inter
        return if cab.decode_decision(S + 4) != 0 {
            if cab.decode_decision(S + 6) != 0 { 1 } else { 2 }
        } else if cab.decode_decision(S + 5) != 0 {
            3
        } else {
            0
        };
    }
    // intra (prefix bit was 1)
    if cab.decode_decision(S + 6) == 0 {
        return 5; // I_4x4
    }
    if cab.decode_terminate() {
        return 30; // I_PCM
    }
    let mut t = 6 + cab.decode_decision(S + 7) * 12;
    if cab.decode_decision(S + 8) != 0 {
        t += 4;
        if cab.decode_decision(S + 8) != 0 {
            t += 4;
        }
    }
    t += cab.decode_decision(S + 9) << 1;
    t += cab.decode_decision(S + 9);
    t
}

/// I-slice `mb_type` CABAC parse (spec §9.3.2.5 / openh264 `ParseMBTypeISliceCabac`).
/// `ctx_inc` = (left MB is I_16x16/non-intra) + (top MB is …), i.e. 0..2; the corner
/// MB has no neighbours so `ctx_inc = 0`. Returns the raw mb_type: 0 = I_NxN (I_4x4/
/// I_8x8), 1..24 = I_16x16 (pred-mode/cbp packed), 25 = I_PCM.
fn parse_mb_type_i_cabac(cab: &mut crate::cabac::Cabac, ctx_inc: usize) -> u32 {
    const O: usize = 3; // ctxIdxOffset for I-slice mb_type
    if cab.decode_decision(O + ctx_inc) == 0 {
        return 0; // I_NxN
    }
    if cab.decode_terminate() {
        return 25; // I_PCM
    }
    let mut t = 1 + cab.decode_decision(O + 3) * 12; // CBP luma: 0 or 12
    if cab.decode_decision(O + 4) != 0 {
        t += 4; // CBP chroma 1 or 2
        if cab.decode_decision(O + 5) != 0 {
            t += 4;
        }
    }
    t += cab.decode_decision(O + 6) << 1; // I_16x16 pred mode (2 bins)
    t += cab.decode_decision(O + 7);
    t
}

/// One `Intra_4x4` (or `8x8`) pred-mode CABAC parse (openh264 `ParseIntraPredModeLuma
/// Cabac`): `prev_intra4x4_pred_mode_flag` (ctx 68) then, if 0, `rem_intra4x4_pred_mode`
/// (3 bins at ctx 69). Returns `-1` for "use predicted mode", else the 0..7 remainder.
fn parse_intra4x4_pred_mode_cabac(cab: &mut crate::cabac::Cabac) -> i32 {
    const IPR: usize = 68;
    if cab.decode_decision(IPR) == 1 {
        return -1; // prev_intra4x4_pred_mode_flag = 1
    }
    let mut m = cab.decode_decision(IPR + 1) as i32;
    m |= (cab.decode_decision(IPR + 1) as i32) << 1;
    m |= (cab.decode_decision(IPR + 1) as i32) << 2;
    m
}

/// `intra_chroma_pred_mode` CABAC parse (openh264 `ParseIntraPredModeChromaCabac`):
/// TU(cMax=3) — bin0 at ctx `64 + ctx_inc` (ctx_inc from neighbour chroma modes, 0 for
/// the corner MB), the rest at ctx 67. Returns the mode 0..3.
fn parse_intra_chroma_pred_mode_cabac(cab: &mut crate::cabac::Cabac, ctx_inc: usize) -> u32 {
    const CIPR: usize = 64;
    if cab.decode_decision(CIPR + ctx_inc) == 0 {
        return 0;
    }
    if cab.decode_decision(CIPR + 3) == 0 {
        return 1;
    }
    if cab.decode_decision(CIPR + 3) == 0 {
        return 2;
    }
    3
}

/// `coded_block_pattern` CABAC parse (openh264 `ParseCbpInfoCabac`), corner-MB variant
/// (top/left neighbours unavailable → their terms are 0). ctxIdxOffset 73 (luma) with 4
/// z-order 8×8 bins whose ctxInc uses the EARLIER-decoded bits within this MB, then
/// chroma bits at 77/81. Returns cbp: bits 0-3 = luma 8×8, bits 4-5 = chroma pattern.
fn parse_cbp_cabac(cab: &mut crate::cabac::Cabac, top: Option<u8>, left: Option<u8>) -> u32 {
    const CBP: usize = 73;
    let t = |m: u32| top.map_or(0u32, |c| ((c as u32 & m) == 0) as u32);
    let l = |m: u32| left.map_or(0u32, |c| ((c as u32 & m) == 0) as u32);
    let nb = |x: u32| (x == 0) as u32; // earlier 8×8 bin within this MB was NOT coded
    // Luma, 4 8×8 blocks in z-order. Top uses cbp bits 2/3, left uses 1/3.
    let b0 = cab.decode_decision(CBP + (l(1 << 1) + (t(1 << 2) << 1)) as usize);
    let b1 = cab.decode_decision(CBP + (nb(b0) + (t(1 << 3) << 1)) as usize);
    let b2 = cab.decode_decision(CBP + (l(1 << 3) + (nb(b0) << 1)) as usize);
    let b3 = cab.decode_decision(CBP + (nb(b2) + (nb(b1) << 1)) as usize);
    let mut cbp = b0 | (b1 << 1) | (b2 << 2) | (b3 << 3);
    // Chroma (4:2:0). ctxInc from neighbour chroma cbp (>>4).
    let ct = top.map_or(0u32, |c| ((c >> 4) != 0) as u32);
    let cl = left.map_or(0u32, |c| ((c >> 4) != 0) as u32);
    if cab.decode_decision(CBP + 4 + (cl + (ct << 1)) as usize) != 0 {
        let ct2 = top.map_or(0u32, |c| ((c >> 4) == 2) as u32);
        let cl2 = left.map_or(0u32, |c| ((c >> 4) == 2) as u32);
        let c1 = cab.decode_decision(CBP + 8 + (cl2 + (ct2 << 1)) as usize);
        cbp |= 1 << (4 + c1);
    }
    cbp
}

fn read_ref_idx(r: &mut BitReader, num_ref_active: usize) -> Result<i32, OutOfData> {
    if num_ref_active == 2 {
        Ok(if r.read_bit()? { 0 } else { 1 }) // te(v): value = !bit
    } else {
        Ok(r.read_ue()? as i32)
    }
}

/// B-partition prediction direction.
#[derive(Clone, Copy, PartialEq)]
enum BPred {
    L0,
    L1,
    Bi,
}
impl BPred {
    /// Whether this direction uses reference list `list` (0 or 1).
    fn uses(self, list: usize) -> bool {
        matches!(
            (self, list),
            (BPred::L0, 0) | (BPred::L1, 1) | (BPred::Bi, 0) | (BPred::Bi, 1)
        )
    }
}

const B16X16: &[(usize, usize, usize, usize)] = &[(0, 0, 16, 16)];
const B16X8: &[(usize, usize, usize, usize)] = &[(0, 0, 16, 8), (0, 8, 16, 8)];
const B8X16: &[(usize, usize, usize, usize)] = &[(0, 0, 8, 16), (8, 0, 8, 16)];

/// A partition region `(x, y, w, h)` in samples.
type Region = (usize, usize, usize, usize);

/// B `mb_type` 1..=21 → (partition layout, MV-prediction mode 0/1/2 for 16×16/
/// 16×8/8×16, per-partition prediction direction) (spec Table 7-14).
fn b_inter_layout(mb_type: u32) -> (&'static [Region], u8, [BPred; 2]) {
    use BPred::*;
    match mb_type {
        1 => (B16X16, 0, [L0, L0]),
        2 => (B16X16, 0, [L1, L1]),
        3 => (B16X16, 0, [Bi, Bi]),
        4 => (B16X8, 1, [L0, L0]),
        5 => (B8X16, 2, [L0, L0]),
        6 => (B16X8, 1, [L1, L1]),
        7 => (B8X16, 2, [L1, L1]),
        8 => (B16X8, 1, [L0, L1]),
        9 => (B8X16, 2, [L0, L1]),
        10 => (B16X8, 1, [L1, L0]),
        11 => (B8X16, 2, [L1, L0]),
        12 => (B16X8, 1, [L0, Bi]),
        13 => (B8X16, 2, [L0, Bi]),
        14 => (B16X8, 1, [L1, Bi]),
        15 => (B8X16, 2, [L1, Bi]),
        16 => (B16X8, 1, [Bi, L0]),
        17 => (B8X16, 2, [Bi, L0]),
        18 => (B16X8, 1, [Bi, L1]),
        19 => (B8X16, 2, [Bi, L1]),
        20 => (B16X8, 1, [Bi, Bi]),
        _ => (B8X16, 2, [Bi, Bi]), // 21
    }
}

/// Whether a B `sub_mb_type` (1..=12) uses reference list `list`.
fn b_sub_uses(st: u32, list: usize) -> bool {
    let pred = match st {
        1 | 4 | 5 | 10 => 0,  // L0
        2 | 6 | 7 | 11 => 1,  // L1
        _ => 2,               // Bi (3, 8, 9, 12)
    };
    (list == 0 && pred != 1) || (list == 1 && pred != 0)
}

/// Sub-partition shapes within an 8×8 for a B `sub_mb_type` (1..=12).
fn b_sub_parts(st: u32) -> &'static [(usize, usize, usize, usize)] {
    match st {
        1..=3 => &[(0, 0, 8, 8)],
        4 | 6 | 8 => &[(0, 0, 8, 4), (0, 4, 8, 4)],
        5 | 7 | 9 => &[(0, 0, 4, 8), (4, 0, 4, 8)],
        _ => &[(0, 0, 4, 4), (4, 0, 4, 4), (0, 4, 4, 4), (4, 4, 4, 4)], // 10/11/12
    }
}

/// Sub-macroblock partition layout `(x, y, w, h)` in samples within an 8×8, for
/// a P-slice `sub_mb_type` (0 = 8×8, 1 = 8×4, 2 = 4×8, 3 = 4×4).
fn sub_mb_partitions(sub_type: u32) -> &'static [(usize, usize, usize, usize)] {
    match sub_type {
        0 => &[(0, 0, 8, 8)],
        1 => &[(0, 0, 8, 4), (0, 4, 8, 4)],
        2 => &[(0, 0, 4, 8), (4, 0, 4, 8)],
        _ => &[(0, 0, 4, 4), (4, 0, 4, 4), (0, 4, 4, 4), (4, 4, 4, 4)],
    }
}

fn store(plane: &mut [u8], stride: usize, x0: usize, y0: usize, s: &[u8; 16]) {
    let _g = rusty_h264_common::prof::scope(rusty_h264_common::prof::Stage::Scatter);
    for dy in 0..4 {
        for dx in 0..4 {
            plane[(y0 + dy) * stride + (x0 + dx)] = s[dy * 4 + dx];
        }
    }
}

/// Un-scans an 8×8 block from frame zig-zag scan order to raster (spec Table 8-12).
fn un_scan_8x8(scan: &[i32; 64]) -> [i32; 64] {
    const ZZ8: [usize; 64] = [
        0, 1, 8, 16, 9, 2, 3, 10, 17, 24, 32, 25, 18, 11, 4, 5, 12, 19, 26, 33, 40, 48, 41, 34, 27,
        20, 13, 6, 7, 14, 21, 28, 35, 42, 49, 56, 57, 50, 43, 36, 29, 22, 15, 23, 30, 37, 44, 51,
        58, 59, 52, 45, 38, 31, 39, 46, 53, 60, 61, 54, 47, 55, 62, 63,
    ];
    let mut out = [0i32; 64];
    for k in 0..64 {
        out[ZZ8[k]] = scan[k];
    }
    out
}

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

    fn fd(qp: u8, offset: i32) -> FrameDecoder {
        FrameDecoder::new(1, 1, qp, offset, Vec::new(), 1, false, false, true)
    }

    #[test]
    fn mb_qp_delta_accumulates_mod_52() {
        let mut d = fd(26, 0);
        assert_eq!(d.cur_qp, 26, "QPy starts at the slice QP");
        d.step_qp(4);
        assert_eq!(d.cur_qp, 30); // 26 + 4
        d.step_qp(-10);
        assert_eq!(d.cur_qp, 20); // carries from the previous MB, not the slice
        // Wrap-around: (20 + 40 + 52) % 52 = 112 % 52 = 8.
        d.step_qp(40);
        assert_eq!(d.cur_qp, 8);
        // Negative wrap: (8 - 20 + 52) % 52 = 40.
        d.step_qp(-20);
        assert_eq!(d.cur_qp, 40);
    }

    #[test]
    fn chroma_qp_index_offset_applied_and_clamped() {
        // Offset 0 reproduces the bare luma->chroma table (QP30 -> 29).
        assert_eq!(fd(0, 0).chroma_qp_for(30), 29);
        // Positive offset shifts the table lookup (QP30 + 2 -> table[2] = 31).
        assert_eq!(fd(0, 2).chroma_qp_for(30), 31);
        // The qPi index is clamped into 0..=51 before the lookup.
        assert_eq!(fd(0, -12).chroma_qp_for(5), chroma_qp(0));
        assert_eq!(fd(0, 99).chroma_qp_for(40), chroma_qp(51));
    }
}