oxideav-av1 0.1.21

//! Conformance-grade intra KEY-frame encoder (r409, generalised r410).
//!
//! Unlike the historical encoder-mirror drivers (retired in r428;
//! their leaf syntax coded `y_mode` with the §5.11.22 non-keyframe
//! CDFs and was therefore decodable only by this crate's matching —
//! also retired — mirror decoder), this driver emits the REAL §5.11 keyframe syntax through the
//! spec-faithful write side ([`super::write_partition_tree_syntax`],
//! whose output the decode walker
//! [`crate::cdf::PartitionWalker::decode_partition_syntax`] replays
//! bit-for-bit): §5.11.7 `intra_frame_mode_info()` with the
//! neighbour-CDF `intra_frame_y_mode`, the §5.11.22 `uv_mode` +
//! §5.11.45 CFL alphas, and the §5.11.34 `residual()` per-TU
//! coefficient emission with live §8.3.2 contexts.
//!
//! The produced bitstream is a complete §5.2 low-overhead stream:
//! IVF v0 container, `OBU_TEMPORAL_DELIMITER` then
//! `OBU_SEQUENCE_HEADER` then the combined §5.10 `OBU_FRAME` (frame
//! header, `byte_alignment()`, tile group in one OBU) — decodable by
//! the crate's own spec-faithful frame driver
//! ([`crate::decoder::decode_av1_spec`]) and by independent AV1
//! decoders.
//!
//! ## Scope (r410, format-generalised r427)
//!
//! * Any §6.4.1 (bit depth, chroma format) pairing ([`YuvFrame`]):
//!   8 / 10 / 12-bit samples in 4:2:0, 4:2:2, 4:4:4 or monochrome
//!   layout, with `seq_profile` elected per pairing (the historical
//!   [`Yuv420Frame`] entries widen into the same core). `(width,
//!   height)` multiples of 8 in `[8, KEY_FRAME_MAX_DIM]` per axis
//!   (any rectangle; frames wider/taller than 64 ride the
//!   multi-superblock walk). The §5.11.46 palette and §5.9.20
//!   intra-block-copy elections stay 8-bit-4:2:0-scoped (an encoder
//!   choice); under 4:2:2 the §5.11.38 admissibility rule bars the
//!   tall partition shapes from the search.
//! * One KEY frame per stream (`show_frame = 1`,
//!   `error_resilient_mode = 1`, `refresh_frame_flags = allFrames`),
//!   single tile, 64×64 superblocks.
//! * `base_q_idx == 0` selects the §5.9.2 `CodedLossless` arm
//!   (forward/inverse WHT, `TxMode = ONLY_4X4`): the decoded planes
//!   equal the input byte-for-byte. `base_q_idx > 0` selects the
//!   lossy DCT_DCT arm (`TxMode = TX_MODE_LARGEST`): the decoded
//!   planes equal the encoder's own reconstruction byte-for-byte.
//! * Full square §5.11.4 partition search (r410): every in-frame
//!   square node from `BLOCK_64X64` down to `BLOCK_8X8` is
//!   trial-encoded both as one `PARTITION_NONE` leaf and as a
//!   `PARTITION_SPLIT` of four recursively-searched quadrants,
//!   keeping the lower rate-distortion score (SSD over the node's
//!   pixels + a q-scaled coefficient/mode rate proxy). Nodes that
//!   straddle the frame edge take the §5.11.4 forced-split arms.
//!   A leaf at `BLOCK_N×N` codes its luma as one
//!   `Max_Tx_Size_Rect[MiSize]` TU on the lossy `TX_MODE_LARGEST`
//!   arm (`TX_8X8` … `TX_64X64`, the latter with the §7.12.3
//!   compact-`tw` coefficient layout) or as the §5.11.35 grid of
//!   `TX_4X4` TUs on the lossless arm; chroma rides the §5.11.38
//!   `get_tx_size` derivation (`TX_4X4` … `TX_32X32`).
//! * Per-leaf luma mode decision by residual SSD over ALL 13 §6.10.x
//!   intra modes (r410): the directional D-modes run the §7.11.2.4
//!   projection kernel against §7.11.2.1 neighbour arrays derived
//!   with the real `haveAboveRight` / `haveBelowLeft` availability —
//!   the encoder mirrors the §6.10.3 `BlockDecoded[]` superblock
//!   state (§5.11.3 per-SB clear + §5.11.35 per-TU stamps) so its
//!   neighbour extension is bit-identical to the decode walker's.
//!   `angle_delta` stays 0. The chroma picker evaluates the same 13
//!   modes jointly over U+V plus `UV_CFL_PRED` (§7.11.5) over a
//!   compact (αU, αV) grid when the §5.11.22 `cfl_allowed` gate
//!   (`Block_Width <= 32 && Block_Height <= 32`) is open.
//! * `skip = 1` on leaves whose every TU quantises to zero (residual
//!   == prediction), `skip = 0` with per-TU `Quant[]` commitments
//!   otherwise.
//! * In-loop filters all disabled by the header set (`CodedLossless`
//!   forces them off at q=0; the lossy FH keeps deblock levels 0,
//!   `enable_cdef = 0`, `enable_restoration = 0`, `enable_superres =
//!   0`), so the §7.4 post chain is a no-op and the walker
//!   reconstruction IS the output frame.
//!
//! ## Why the reconstruction loop is exact
//!
//! Every per-TU prediction is computed from the encoder's running
//! reconstruction with the same §7.11.2 kernels the decode walker
//! runs — including the §7.11.2.1 `AboveRow[]` / `LeftCol[]`
//! derivation with the `aboveLimit` / `leftLimit` extension clamps
//! and the §6.10.3 `BlockDecoded[]`-driven `haveAboveRight` /
//! `haveBelowLeft` reads — and the coefficient inverse
//! ([`crate::cdf::dequantize_step1`] +
//! [`crate::transform::inverse_transform_2d`]) is the decoder's own
//! primitive. So the encoder's `recon` tracks the decoder's
//! `CurrFrame` sample-for-sample by induction along the §5.11.4
//! dispatch order. On the lossless arm the residual chain is
//! bit-exact (`recon == input` at every leaf), which the round-trip
//! suite pins.
//!
//! Spec provenance: `docs/video/av1/av1-spec.txt` §5.2/§5.3 (framing),
//! §5.5/§5.9 (headers), §5.10 (`frame_obu`), §5.11 (tile syntax; the
//! §5.11.3 `clear_block_decoded_flags` reset and §5.11.35
//! `transform_block` stamps for `BlockDecoded[]`), §7.11.2 (intra
//! prediction), §7.11.5 (CFL), §7.12/§7.13 (quant + transforms).

use crate::cdf::{
    dequantize_step1, get_tx_size, intra_tx_type_set, is_tx_type_in_set, tx_size_sqr_index,
    QuantizerParams, TileCdfContext, TileGeometry, ANGLE_STEP, BLOCK_4X4, BLOCK_64X64, BLOCK_8X8,
    D67_PRED, DCT_DCT, DC_PRED, H_PRED, INTRA_MODES, MAX_TX_DEPTH, MAX_TX_SIZE_RECT, MODE_TO_ANGLE,
    MODE_TO_TXFM, NUM_4X4_BLOCKS_WIDE, PAETH_PRED, SMOOTH_H_PRED, SMOOTH_PRED, SMOOTH_V_PRED,
    SPLIT_TX_SIZE, TX_4X4, TX_HEIGHT, TX_SIZE_SQR_UP, TX_WIDTH, UV_CFL_PRED, V_PRED,
};
use crate::cdf::{
    predict_intra_dc_pred, predict_intra_directional, predict_intra_h_pred,
    predict_intra_paeth_pred, predict_intra_smooth_h_pred, predict_intra_smooth_pred,
    predict_intra_smooth_v_pred, predict_intra_v_pred,
};
use crate::encoder::forward_quantize::forward_quantize_rounded;
use crate::encoder::forward_transform_2d::forward_transform_2d;
use crate::encoder::forward_wht::forward_wht_4x4;
use crate::encoder::frame_obu::encode_uncompressed_header;
use crate::encoder::ivf::{IvfWriter, FOURCC_AV01};
use crate::encoder::obu::{build_temporal_unit, ObuFrame};
use crate::encoder::partition_tree::{
    write_partition_tree_syntax, PartitionSyntaxWriter, SyntaxBlock, SyntaxFrameParams, SyntaxNode,
};
use crate::encoder::rate_twin::{score256, RateModel, RateTwin, TuCtx, TuFork, TwinScope};
use crate::encoder::sequence_obu::write_sequence_header_obu;
use crate::encoder::symbol_writer::SymbolWriter;
use crate::encoder::tile_group_obu::{write_tile_group_obu, TileGroupObu, TilePayload};
use crate::encoder::yuv_frame::{build_intra_only_seq_yuv, ChromaFormat, YuvFrame};
use crate::encoder::yuv_frame::{
    build_intra_only_yuv420_8bit_fh_with_q, sb_grid_origins, Yuv420Frame, SB_SIZE4_64,
};
use crate::frame_header::FrameHeader;
use crate::obu::ObuType;
use crate::sequence_header::SequenceHeader;
use crate::transform::inverse_transform_2d;
use crate::uncompressed_header_tail::FilmGrainParams;
use crate::Error;

/// Result of [`encode_key_frame_yuv`] / [`encode_key_frame_yuv_with_q`]
/// — the general-format sibling of [`EncodedKeyFrame`] (r427): recon
/// planes are `u16` at the input's bit depth, chroma at the input's
/// subsampled extent (empty on the monochrome arm).
#[derive(Debug, Clone)]
pub struct EncodedKeyFrameYuv {
    /// Complete IVF v0 file (header + one frame record).
    pub ivf_bytes: Vec<u8>,
    /// The bare §7.5 temporal unit (TD + SH + §5.10 `OBU_FRAME`).
    pub temporal_unit_bytes: Vec<u8>,
    /// Encoder reconstruction of the luma plane (row-major). The
    /// decoded output equals these sample-for-sample; at `base_q_idx
    /// == 0` they additionally equal the input.
    pub recon_y: Vec<u16>,
    /// U plane reconstruction (subsampled extent; empty on
    /// monochrome).
    pub recon_u: Vec<u16>,
    /// V plane reconstruction.
    pub recon_v: Vec<u16>,
    /// The emitted sequence header descriptor.
    pub seq: SequenceHeader,
    /// The emitted frame header descriptor.
    pub fh: FrameHeader,
}

/// Result of [`encode_key_frame_yuv420`] /
/// [`encode_key_frame_yuv420_with_q`].
#[derive(Debug, Clone)]
pub struct EncodedKeyFrame {
    /// Complete IVF v0 file (header + one frame record).
    pub ivf_bytes: Vec<u8>,
    /// The bare §7.5 temporal unit (TD + SH + §5.10 `OBU_FRAME`) — the
    /// per-packet payload a container muxer would carry.
    pub temporal_unit_bytes: Vec<u8>,
    /// Encoder reconstruction of the three planes (row-major). The
    /// decoded output equals these byte-for-byte; at `base_q_idx == 0`
    /// they additionally equal the input.
    pub recon_y: Vec<u8>,
    /// U plane reconstruction (`(width/2) × (height/2)`).
    pub recon_u: Vec<u8>,
    /// V plane reconstruction.
    pub recon_v: Vec<u8>,
    /// The emitted sequence header descriptor.
    pub seq: SequenceHeader,
    /// The emitted frame header descriptor.
    pub fh: FrameHeader,
}

/// Per-axis extent bound (inclusive) for [`encode_key_frame_yuv420`]
/// — r410 raises the r409 `512` cap to `4096` (the RD search works
/// superblock-by-superblock, so state stays flat; HD/UHD extents were
/// validated against independent black-box decoders during the round).
pub const KEY_FRAME_MAX_DIM: u32 = 16384;

/// Lossless (`base_q_idx = 0`) conformance-grade KEY-frame encode —
/// see [`encode_key_frame_yuv420_with_q`].
pub fn encode_key_frame_yuv420(input: &Yuv420Frame) -> Result<EncodedKeyFrame, Error> {
    encode_key_frame_yuv420_with_q(input, 0)
}

/// Encode one 8-bit 4:2:0 KEY frame at `base_q_idx` into a
/// spec-conformant IVF stream (see the module docs for the exact
/// scope and the reconstruction-exactness argument).
///
/// ## Errors
///
/// * Dimensions not multiples of 8, or outside
///   `[8, KEY_FRAME_MAX_DIM]` per axis, or plane lengths inconsistent
///   with the dimensions — [`Error::PartitionWalkOutOfRange`].
/// * Internal writer overflow surfaces the underlying [`Error`].
pub fn encode_key_frame_yuv420_with_q(
    input: &Yuv420Frame,
    base_q_idx: u8,
) -> Result<EncodedKeyFrame, Error> {
    encode_key_frame_yuv420_with_q_rate_model(input, base_q_idx, RateModel::Twin)
}

/// r421 — [`encode_key_frame_yuv420_with_q`] with an explicit
/// [`RateModel`], kept public (hidden) so the sweep harnesses can A/B
/// the twin-priced elections against the pre-r421 heuristic baseline
/// on identical inputs.
#[doc(hidden)]
pub fn encode_key_frame_yuv420_with_q_rate_model(
    input: &Yuv420Frame,
    base_q_idx: u8,
    model: RateModel,
) -> Result<EncodedKeyFrame, Error> {
    encode_key_frame_yuv420_with_q_carry(input, base_q_idx, model).map(|(k, _)| k)
}

/// r423 — [`encode_key_frame_yuv420_with_q_rate_model`] plus the §7.20
/// per-slot reference state the KEY frame's `allFrames` refresh
/// deposits: the §8.4 frame-end CDF table (`save_cdfs`, the adapted
/// state of the single tile — `context_update_tile_id = 0`,
/// `disable_frame_end_update_cdf = 0`), the `SavedSegmentIds` grid
/// (all-zero — `segmentation_enabled = 0` stamps the literal `0` per
/// block), and the `SavedGmParams` identity table. A following INTER
/// frame electing `primary_ref_frame != PRIMARY_REF_NONE` against a
/// KEY-refreshed slot loads exactly this state (§5.9.2 `load_cdfs` +
/// `load_previous` + `load_previous_segment_ids`).
pub(crate) fn encode_key_frame_yuv420_with_q_carry(
    input: &Yuv420Frame,
    base_q_idx: u8,
    model: RateModel,
) -> Result<(EncodedKeyFrame, crate::encoder::inter_frame::RefSlotCarry), Error> {
    encode_key_frame_yuv420_with_q_seg_carry(input, base_q_idx, model, &[], None)
}

/// r426 — [`encode_key_frame_yuv420_with_q_carry`] with §5.9.14
/// SEG_LVL_ALT_Q segmentation and the exactness-demand mask: the KEY
/// frame codes the same delta table as the GOP's P-frames
/// (`segmentation_enabled = 1`, the §5.11.8 `intra_segment_id` per
/// block), and every leaf overlapping `exact_mask` commits the
/// table's lossless segment — its blocks run the §5.9.2
/// `LosslessArray[]` TX_4X4/WHT semantics, so the demanded region
/// reconstructs pixel-exact from frame 0. `alt_q` empty keeps the
/// unsegmented r413 shape (and `exact_mask` must then be `None`).
pub(crate) fn encode_key_frame_yuv420_with_q_seg_carry(
    input: &Yuv420Frame,
    base_q_idx: u8,
    model: RateModel,
    alt_q: &[i16],
    exact_mask: Option<&[bool]>,
) -> Result<(EncodedKeyFrame, crate::encoder::inter_frame::RefSlotCarry), Error> {
    let wide = YuvFrame::from_yuv420_8bit(input);
    let (k, carry) = encode_key_frame_yuv_seg_carry(
        &wide, base_q_idx, model, alt_q, exact_mask, true, true, true,
    )?;
    let narrow = |p: Vec<u16>| p.into_iter().map(|s| s as u8).collect::<Vec<u8>>();
    Ok((
        EncodedKeyFrame {
            ivf_bytes: k.ivf_bytes,
            temporal_unit_bytes: k.temporal_unit_bytes,
            recon_y: narrow(k.recon_y),
            recon_u: narrow(k.recon_u),
            recon_v: narrow(k.recon_v),
            seq: k.seq,
            fh: k.fh,
        },
        carry,
    ))
}

/// r427 — general-format lossless (`base_q_idx = 0`) KEY-frame encode:
/// see [`encode_key_frame_yuv_with_q`].
pub fn encode_key_frame_yuv(input: &YuvFrame) -> Result<EncodedKeyFrameYuv, Error> {
    encode_key_frame_yuv_with_q(input, 0)
}

/// r431 — [`encode_key_frame_yuv420_with_q`] with the §5.9.17
/// KEY-frame delta-q ELECTION switch exposed (hidden), so the A/B
/// harness can measure the elected arm against the single-quantiser
/// baseline on identical input. `delta_q = true` is what every
/// production entry point runs; `false` forces the single-quantiser
/// shape unconditionally.
#[doc(hidden)]
pub fn encode_key_frame_yuv420_with_q_dq(
    input: &Yuv420Frame,
    base_q_idx: u8,
    delta_q: bool,
) -> Result<EncodedKeyFrame, Error> {
    let wide = YuvFrame::from_yuv420_8bit(input);
    let (k, _) = encode_key_frame_yuv_seg_carry_tiles(
        &wide,
        base_q_idx,
        RateModel::Twin,
        &[],
        None,
        true,
        true,
        true,
        (0, 0),
        1,
        None,
        delta_q,
        // r439 — the delta-q A/B entry holds the §5.9.12 QM election
        // OFF so the delta-q axis stays the only variable (r441: the
        // §5.9.8 superres election too).
        false,
        false,
        false,
    )?;
    let narrow = |p: Vec<u16>| p.into_iter().map(|s| s as u8).collect::<Vec<u8>>();
    Ok(EncodedKeyFrame {
        ivf_bytes: k.ivf_bytes,
        temporal_unit_bytes: k.temporal_unit_bytes,
        recon_y: narrow(k.recon_y),
        recon_u: narrow(k.recon_u),
        recon_v: narrow(k.recon_v),
        seq: k.seq,
        fh: k.fh,
    })
}

/// r441 — [`encode_key_frame_yuv420_with_q`] with the §5.9.8
/// superres ELECTION switch exposed (hidden), so the A/B harness can
/// measure the elected arm against the flat-width baseline on
/// identical input. `superres = true` is what every production entry
/// point runs; `false` forces the flat-width shape unconditionally.
#[doc(hidden)]
pub fn encode_key_frame_yuv420_with_q_sr(
    input: &Yuv420Frame,
    base_q_idx: u8,
    superres: bool,
) -> Result<EncodedKeyFrame, Error> {
    let wide = YuvFrame::from_yuv420_8bit(input);
    let (k, _) = encode_key_frame_yuv_seg_carry_tiles(
        &wide,
        base_q_idx,
        RateModel::Twin,
        &[],
        None,
        true,
        true,
        true,
        (0, 0),
        1,
        None,
        true,
        true,
        superres,
        false,
    )?;
    let narrow = |p: Vec<u16>| p.into_iter().map(|s| s as u8).collect::<Vec<u8>>();
    Ok(EncodedKeyFrame {
        ivf_bytes: k.ivf_bytes,
        temporal_unit_bytes: k.temporal_unit_bytes,
        recon_y: narrow(k.recon_y),
        recon_u: narrow(k.recon_u),
        recon_v: narrow(k.recon_v),
        seq: k.seq,
        fh: k.fh,
    })
}

/// r441 — FORCE one §5.9.8 superres candidate arm (hidden): the KEY
/// codes at `denom`'s downscaled width regardless of the arming
/// window, so the A/B harness can measure the arm inside AND outside
/// the committed regime. The returned reconstruction lives at the
/// UPSCALED extent (the decoder's own §7.16 driver), exactly what the
/// spec decode driver outputs.
#[doc(hidden)]
pub fn encode_key_frame_yuv420_with_q_sr_forced(
    input: &Yuv420Frame,
    base_q_idx: u8,
    denom: u32,
) -> Result<EncodedKeyFrame, Error> {
    let wide = YuvFrame::from_yuv420_8bit(input);
    let extras = KeyExtras {
        delta_q: true,
        qm: true,
        ..KeyExtras::default()
    };
    let (k, _) = encode_key_frame_superres_arm(
        &wide,
        base_q_idx,
        RateModel::Twin,
        &[],
        None,
        true,
        true,
        true,
        &extras,
        denom,
    )?;
    let narrow = |p: Vec<u16>| p.into_iter().map(|s| s as u8).collect::<Vec<u8>>();
    Ok(EncodedKeyFrame {
        ivf_bytes: k.ivf_bytes,
        temporal_unit_bytes: k.temporal_unit_bytes,
        recon_y: narrow(k.recon_y),
        recon_u: narrow(k.recon_u),
        recon_v: narrow(k.recon_v),
        seq: k.seq,
        fh: k.fh,
    })
}

/// r427 — encode one KEY frame at any conformant (bit depth, chroma
/// format) pairing into a spec-conformant IVF stream: 8 / 10 / 12-bit
/// samples in 4:2:0, 4:2:2, 4:4:4 or monochrome layout, with the
/// §6.4.1 `seq_profile` elected per pairing. Same scope and
/// reconstruction-exactness argument as
/// [`encode_key_frame_yuv420_with_q`] (whose 8-bit 4:2:0 arm now
/// routes through this driver); the §5.11.46 palette and §5.9.20
/// intra-block-copy elections stay 8-bit-4:2:0-scoped (an encoder
/// choice — the header gates close on the other pairings).
///
/// ## Errors
///
/// * [`YuvFrame::validate`] failures (shape / depth / sample range) —
///   [`Error::PartitionWalkOutOfRange`].
/// * Internal writer overflow surfaces the underlying [`Error`].
pub fn encode_key_frame_yuv_with_q(
    input: &YuvFrame,
    base_q_idx: u8,
) -> Result<EncodedKeyFrameYuv, Error> {
    encode_key_frame_yuv_seg_carry(
        input,
        base_q_idx,
        RateModel::Twin,
        &[],
        None,
        true,
        true,
        true,
    )
    .map(|(k, _)| k)
}

/// r431 — [`encode_key_frame_yuv_with_q`] with an explicitly
/// configured §5.9.15 uniform multi-tile layout: `tile_cols_log2` /
/// `tile_rows_log2` are the coded `TileColsLog2` / `TileRowsLog2`
/// (the realized tile counts follow the §5.9.15 uniform-spacing
/// derivation — e.g. a 256-wide frame at `tile_cols_log2 = 1` codes
/// two 128-wide tile columns). `(0, 0)` reproduces the single-tile
/// stream byte for byte.
///
/// Every tile is a complete §8.2 symbol partition starting from the
/// §8.3.1 frame-start CDF state; non-last tiles carry §5.11.1
/// `tile_size_minus_1` fields sized by the realized §6.8.14
/// `TileSizeBytes`; tile 0 donates the §8.4 frame-end CDF state
/// (`context_update_tile_id = 0`).
///
/// ## Errors
///
/// * The requested pair is outside the §5.9.15 legal window for the
///   frame size (see [`crate::tile_info::TileInfo::uniform_layout`]),
///   plus every [`encode_key_frame_yuv_with_q`] reject —
///   [`Error::PartitionWalkOutOfRange`].
pub fn encode_key_frame_yuv_with_q_tiles(
    input: &YuvFrame,
    base_q_idx: u8,
    tile_cols_log2: u32,
    tile_rows_log2: u32,
) -> Result<EncodedKeyFrameYuv, Error> {
    encode_key_frame_yuv_seg_carry_tiles(
        input,
        base_q_idx,
        RateModel::Twin,
        &[],
        None,
        true,
        true,
        true,
        (tile_cols_log2, tile_rows_log2),
        1,
        None,
        true,
        true,
        // r441 — the §5.9.8 superres election rides the default
        // switches (it self-scopes to the single-tile shape).
        true,
        false,
    )
    .map(|(k, _)| k)
}

/// 8-bit 4:2:0 sibling of [`encode_key_frame_yuv_with_q_tiles`].
pub fn encode_key_frame_yuv420_with_q_tiles(
    input: &Yuv420Frame,
    base_q_idx: u8,
    tile_cols_log2: u32,
    tile_rows_log2: u32,
) -> Result<EncodedKeyFrame, Error> {
    let wide = YuvFrame::from_yuv420_8bit(input);
    let k = encode_key_frame_yuv_with_q_tiles(&wide, base_q_idx, tile_cols_log2, tile_rows_log2)?;
    let narrow = |p: Vec<u16>| p.into_iter().map(|s| s as u8).collect::<Vec<u8>>();
    Ok(EncodedKeyFrame {
        ivf_bytes: k.ivf_bytes,
        temporal_unit_bytes: k.temporal_unit_bytes,
        recon_y: narrow(k.recon_y),
        recon_u: narrow(k.recon_u),
        recon_v: narrow(k.recon_v),
        seq: k.seq,
        fh: k.fh,
    })
}

/// r433 — [`encode_key_frame_yuv_with_q_tiles`] with §5.11.1
/// multi-tile-group PACKAGING: the frame's tiles are split across
/// `tile_groups` separate `OBU_TILE_GROUP` OBUs (contiguous
/// `tg_start ..= tg_end` slices with `tile_start_and_end_present_flag
/// = 1`, per §6.10.1 as even as possible), emitted after a standalone
/// `OBU_FRAME_HEADER` instead of the §5.10 `OBU_FRAME` packing.
///
/// The per-tile §8.2 entropy payloads are BYTE-IDENTICAL to the
/// single-group stream's — only the §5.2 OBU framing changes — so the
/// decoded pixels match the `_tiles` entry exactly. `tile_groups <= 1`
/// reproduces the `_tiles` stream byte for byte; values above the
/// realized tile count clamp to one group per tile.
///
/// ## Errors
///
/// * Every [`encode_key_frame_yuv_with_q_tiles`] reject —
///   [`Error::PartitionWalkOutOfRange`].
pub fn encode_key_frame_yuv_with_q_tile_groups(
    input: &YuvFrame,
    base_q_idx: u8,
    tile_cols_log2: u32,
    tile_rows_log2: u32,
    tile_groups: u32,
) -> Result<EncodedKeyFrameYuv, Error> {
    encode_key_frame_yuv_full(
        input,
        base_q_idx,
        RateModel::Twin,
        &[],
        None,
        true,
        true,
        true,
        &KeyExtras {
            tiles: (tile_cols_log2, tile_rows_log2),
            tile_groups,
            delta_q: true,
            qm: true,
            ..KeyExtras::default()
        },
    )
    .map(|(k, _)| k)
}

/// 8-bit 4:2:0 sibling of [`encode_key_frame_yuv_with_q_tile_groups`].
pub fn encode_key_frame_yuv420_with_q_tile_groups(
    input: &Yuv420Frame,
    base_q_idx: u8,
    tile_cols_log2: u32,
    tile_rows_log2: u32,
    tile_groups: u32,
) -> Result<EncodedKeyFrame, Error> {
    let wide = YuvFrame::from_yuv420_8bit(input);
    let k = encode_key_frame_yuv_with_q_tile_groups(
        &wide,
        base_q_idx,
        tile_cols_log2,
        tile_rows_log2,
        tile_groups,
    )?;
    let narrow = |p: Vec<u16>| p.into_iter().map(|s| s as u8).collect::<Vec<u8>>();
    Ok(EncodedKeyFrame {
        ivf_bytes: k.ivf_bytes,
        temporal_unit_bytes: k.temporal_unit_bytes,
        recon_y: narrow(k.recon_y),
        recon_u: narrow(k.recon_u),
        recon_v: narrow(k.recon_v),
        seq: k.seq,
        fh: k.fh,
    })
}

/// r433 — [`encode_key_frame_yuv_with_q`] with an explicitly
/// configured §5.9.15 **NON-UNIFORM** tile layout
/// (`uniform_tile_spacing_flag = 0`): `widths_sb` / `heights_sb` give
/// each tile column's width and each tile row's height in SUPERBLOCK
/// units (64-pel superblocks on every conformance-grade stream), coded
/// through the `width_in_sbs_minus_1` / `height_in_sbs_minus_1`
/// `ns()` walks. The widths must sum to the frame's superblock
/// columns (heights to its rows) and respect the §5.9.15 bounds —
/// see [`crate::tile_info::TileInfo::explicit_layout`].
///
/// ## Errors
///
/// * The layout is outside the §5.9.15 legal window, plus every
///   [`encode_key_frame_yuv_with_q`] reject —
///   [`Error::PartitionWalkOutOfRange`].
pub fn encode_key_frame_yuv_with_q_tile_layout(
    input: &YuvFrame,
    base_q_idx: u8,
    widths_sb: &[u32],
    heights_sb: &[u32],
) -> Result<EncodedKeyFrameYuv, Error> {
    encode_key_frame_yuv_full(
        input,
        base_q_idx,
        RateModel::Twin,
        &[],
        None,
        true,
        true,
        true,
        &KeyExtras {
            explicit_tiles: Some((widths_sb, heights_sb)),
            delta_q: true,
            qm: true,
            ..KeyExtras::default()
        },
    )
    .map(|(k, _)| k)
}

/// 8-bit 4:2:0 sibling of [`encode_key_frame_yuv_with_q_tile_layout`].
pub fn encode_key_frame_yuv420_with_q_tile_layout(
    input: &Yuv420Frame,
    base_q_idx: u8,
    widths_sb: &[u32],
    heights_sb: &[u32],
) -> Result<EncodedKeyFrame, Error> {
    let wide = YuvFrame::from_yuv420_8bit(input);
    let k = encode_key_frame_yuv_with_q_tile_layout(&wide, base_q_idx, widths_sb, heights_sb)?;
    let narrow = |p: Vec<u16>| p.into_iter().map(|s| s as u8).collect::<Vec<u8>>();
    Ok(EncodedKeyFrame {
        ivf_bytes: k.ivf_bytes,
        temporal_unit_bytes: k.temporal_unit_bytes,
        recon_y: narrow(k.recon_y),
        recon_u: narrow(k.recon_u),
        recon_v: narrow(k.recon_v),
        seq: k.seq,
        fh: k.fh,
    })
}

/// r427 — the general-format KEY-frame core: every entry point above
/// funnels here. `alt_q` / `exact_mask` carry the r426 §5.9.14
/// SEG_LVL_ALT_Q + exactness-demand configuration.
#[allow(clippy::too_many_arguments)]
pub(crate) fn encode_key_frame_yuv_seg_carry(
    input: &YuvFrame,
    base_q_idx: u8,
    model: RateModel,
    alt_q: &[i16],
    exact_mask: Option<&[bool]>,
    cdef: bool,
    cdef_units: bool,
    lr: bool,
) -> Result<
    (
        EncodedKeyFrameYuv,
        crate::encoder::inter_frame::RefSlotCarry,
    ),
    Error,
> {
    encode_key_frame_yuv_seg_carry_tiles(
        input,
        base_q_idx,
        model,
        alt_q,
        exact_mask,
        cdef,
        cdef_units,
        lr,
        (0, 0),
        1,
        None,
        true,
        true,
        // r441 — the standalone entries run the §5.9.8 superres
        // election (regime-gated; unsegmented lossy frames only).
        true,
        false,
    )
}

/// r431 — [`encode_key_frame_yuv_seg_carry`] with an explicitly
/// configured §5.9.15 uniform tile layout: `tiles = (TileColsLog2,
/// TileRowsLog2)`. `(0, 0)` is the single-tile shape every pre-r431
/// entry point produces (bit-identical — the per-tile walk collapses
/// to the whole-frame walk). A multi-tile layout emits one §8.2
/// symbol partition per tile (each tile starting from the §8.3.1
/// frame-start CDF state, per-tile `clear_above_context()` /
/// availability scoping), `tile_size_minus_1` fields on every
/// non-last tile (§5.11.1), and the §5.9.15 trailing
/// `context_update_tile_id` (0 — tile 0 donates the §8.4 frame-end
/// CDF state) + `tile_size_bytes_minus_1` (minimal for the realized
/// payloads) pair.
///
/// The §5.9.20 intra-block-copy election is closed on multi-tile
/// layouts (the search's §6.10.24 hash index is frame-scoped; an
/// encoder election, not a conformance limit). Everything else —
/// palette, filter intra, CDEF (frame-level and per-unit), loop
/// restoration — runs per tile exactly as in the single-tile arm.
///
/// ## Errors
///
/// * `tiles` outside the §5.9.15 legal window for the frame size
///   (see [`TileInfo::uniform_layout`]) —
///   [`Error::PartitionWalkOutOfRange`].
#[allow(clippy::too_many_arguments)]
pub(crate) fn encode_key_frame_yuv_seg_carry_tiles(
    input: &YuvFrame,
    base_q_idx: u8,
    model: RateModel,
    alt_q: &[i16],
    exact_mask: Option<&[bool]>,
    cdef: bool,
    cdef_units: bool,
    lr: bool,
    tiles: (u32, u32),
    tile_groups: u32,
    explicit_tiles: Option<(&[u32], &[u32])>,
    delta_q: bool,
    qm: bool,
    superres: bool,
    collect_donor_cdfs: bool,
) -> Result<
    (
        EncodedKeyFrameYuv,
        crate::encoder::inter_frame::RefSlotCarry,
    ),
    Error,
> {
    encode_key_frame_yuv_full(
        input,
        base_q_idx,
        model,
        alt_q,
        exact_mask,
        cdef,
        cdef_units,
        lr,
        &KeyExtras {
            tiles,
            tile_groups,
            explicit_tiles,
            delta_q,
            qm,
            superres_elect: superres,
            collect_donor_cdfs,
            ..KeyExtras::default()
        },
    )
}

/// r460 — one tile's search output (see the tile loop in
/// `encode_key_frame_yuv_core`).
pub(crate) struct TileSearchOut {
    pub payload: Vec<u8>,
    pub cdfs: Box<TileCdfContext>,
    pub trees: Vec<crate::encoder::partition_tree::SyntaxNode>,
    pub sbs: Vec<(u32, u32)>,
}

/// r460 — search-effort limits on the intra RD ladders. The default
/// is the exhaustive pre-r460 search (every entry point that does not
/// set them stays bit-identical); the still-picture speed presets
/// tighten them.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct SearchLimits {
    /// §5.11.15 `Split_Tx_Size` ladder depth tried per leaf
    /// (`MAX_TX_DEPTH` = the full ladder; `1` = the largest rect size
    /// plus one split; `0` = the largest only).
    pub tx_depth_steps: usize,
    /// Prune the §5.11.47 per-TU transform-type search to `DCT_DCT` +
    /// the mode's `Mode_To_Txfm` default (+ `IDTX` under screen-content
    /// tools) instead of the full §5.11.48 intra set.
    pub prune_tx_types: bool,
    /// Try the §5.11.4 `PARTITION_HORZ` / `PARTITION_VERT` arms at
    /// >= 16×16 nodes.
    pub rect_partitions: bool,
    /// Smallest leaf the fully-inside search descends to (`BLOCK_4X4`
    /// = full; `BLOCK_8X8` skips the 4×4 level).
    pub min_leaf: usize,
    /// Do not try the split (or rect) arms below a node whose
    /// square leaf coded `skip = 1` (no residual at all).
    pub skip_leaf_early_exit: bool,
    /// Every `sgr_step`-th §7.17 self-guided parameter set is tried
    /// by the loop-restoration election (`1` = all 16).
    pub sgr_step: usize,
    /// Gate `allow_screen_content_tools` behind a luma colour-count
    /// probe (photographic content keeps the palette / intra-bc
    /// searches and the per-block palette syntax off).
    pub screen_content_probe: bool,
    /// AC quantiser rounding offset in 1/64 steps
    /// ([`crate::encoder::forward_quantize::forward_quantize_rounded`];
    /// `32` = round to nearest, the pre-r460 rule).
    pub quant_round_64: i64,
    /// §7.14 deblocking-level election effort
    /// ([`crate::encoder::lf_elect`]): `0` = off (the pre-r460
    /// `loop_filter_level = 0` shape), `1` = coarse ladder, `2` =
    /// coarse + refinement.
    pub lf_effort: u8,
    /// Tile-search threads (`1` = sequential; more only matters on
    /// multi-tile layouts — tiles are stitched in order, so the output
    /// is identical either way).
    pub threads: usize,
    /// Smallest §5.9.20 `lr_unit_shift` the restoration election
    /// tries (`0` = the full 64 / 128 / 256 ladder; `2` = 256-sample
    /// units only). Each rung is a complete per-unit election, and at
    /// 12 MP the ladder dominates the still's wall clock.
    pub lr_min_unit_shift: u8,
    /// r464 — the reduced §5.9.19 CDEF sweep (see
    /// [`crate::encoder::cdef_elect::CdefElectInput::fast`]).
    pub cdef_fast: Option<(u8, u8)>,
    /// r464 — intra mode pre-screen: the pickers score the 13 §6.10.x
    /// modes at `angle_delta = 0` (plus filter-intra on luma) and
    /// refine the §5.11.42 `-3..=3` deltas only around the two best
    /// directional modes (30 predictions per block instead of 66).
    pub intra_mode_prescreen: bool,
    /// r464 — partition early termination, in 1/64 of the luma AC
    /// quantiser step squared per sample: a fully-inside square leaf
    /// whose `D` (SSD over the node, every plane) is at most
    /// `samples · step² · k / 65536` ends the descent — no split /
    /// rect arm is trialled below it. `0` = off.
    pub split_early_term_k64: u32,
    /// r464 — a leaf that codes no residual at the largest §5.11.15
    /// transform size skips the split-size trials.
    pub tx_split_prescreen: bool,
    /// r464 — the per-TU §5.11.47 transform-type choice scores rate
    /// with the magnitude proxy instead of the exact twin chain (the
    /// leaf as a whole is still priced exactly).
    pub tu_proxy_pricing: bool,
    /// r464 — alternating-least-squares rounds of the §7.17.4 Wiener
    /// fit (`2` = the r429 fit).
    pub wiener_rounds: u8,
}

impl Default for SearchLimits {
    fn default() -> Self {
        Self {
            tx_depth_steps: MAX_TX_DEPTH,
            prune_tx_types: false,
            rect_partitions: true,
            min_leaf: BLOCK_4X4,
            skip_leaf_early_exit: false,
            sgr_step: 1,
            screen_content_probe: false,
            quant_round_64: crate::encoder::forward_quantize::QUANT_ROUND_HALF,
            lf_effort: 0,
            threads: 1,
            lr_min_unit_shift: 0,
            cdef_fast: None,
            intra_mode_prescreen: false,
            split_early_term_k64: 0,
            tx_split_prescreen: false,
            tu_proxy_pricing: false,
            wiener_rounds: 2,
        }
    }
}

impl SearchLimits {
    /// The `StillSpeed::Fast` shape.
    pub(crate) fn fast() -> Self {
        Self {
            tx_depth_steps: 0,
            prune_tx_types: true,
            rect_partitions: false,
            min_leaf: crate::cdf::BLOCK_8X8,
            skip_leaf_early_exit: true,
            sgr_step: 8,
            screen_content_probe: true,
            quant_round_64: 22,
            lf_effort: 1,
            threads: 1,
            lr_min_unit_shift: 2,
            cdef_fast: Some((0, 3)),
            intra_mode_prescreen: true,
            split_early_term_k64: 4,
            tx_split_prescreen: true,
            tu_proxy_pricing: true,
            wiener_rounds: 1,
        }
    }

    /// The `StillSpeed::Balanced` shape (r464): the `Fast` ladders
    /// plus the §5.11.4 rect partition arms, the refined §7.14
    /// deblock ladder, the §5.9.19 CDEF sweep on a quarter of the
    /// units with the four best strengths tabled everywhere, two
    /// §7.17 unit-size rungs with every fourth self-guided set and
    /// two Wiener fit rounds, no partition early termination.
    pub(crate) fn balanced() -> Self {
        Self {
            tx_depth_steps: 0,
            prune_tx_types: true,
            rect_partitions: true,
            min_leaf: crate::cdf::BLOCK_8X8,
            skip_leaf_early_exit: true,
            sgr_step: 4,
            screen_content_probe: true,
            quant_round_64: 22,
            lf_effort: 2,
            threads: 1,
            lr_min_unit_shift: 1,
            cdef_fast: Some((2, 4)),
            intra_mode_prescreen: true,
            split_early_term_k64: 0,
            tx_split_prescreen: true,
            tu_proxy_pricing: true,
            wiener_rounds: 2,
        }
    }
}

/// r464 — [`tile_local_state`]'s result: the local geometry, the local
/// superblock origins, the tile origin in frame mi units, the cropped
/// source, the tile reconstruction and the tile syntax driver.
type TileLocalState = (
    TileGeometry,
    Vec<(u32, u32)>,
    (u32, u32),
    YuvFrame,
    ReconState,
    PartitionSyntaxWriter,
);

/// r464 — the tile-sized search state for the threaded tile walk (see
/// the tile loop in `encode_key_frame_yuv_core`): the source cropped
/// to the tile, a tile-extent [`ReconState`] (quantiser, limits and
/// gates copied from the frame state) and a tile-extent
/// [`PartitionSyntaxWriter`], with the tile at the origin. Returns the
/// local geometry, the local superblock origins, the tile origin in
/// frame mi units, and the three objects.
fn tile_local_state(
    input: &YuvFrame,
    frame: &ReconState,
    geo: TileGeometry,
    origins: &[(u32, u32)],
) -> TileLocalState {
    let (ssx, ssy) = (frame.subsampling_x, frame.subsampling_y);
    let mi_rows = geo.mi_row_end - geo.mi_row_start;
    let mi_cols = geo.mi_col_end - geo.mi_col_start;
    let (row0, col0) = (
        (geo.mi_row_start as usize) * 4,
        (geo.mi_col_start as usize) * 4,
    );
    let width = ((mi_cols as usize) * 4).min(frame.width - col0);
    let height = ((mi_rows as usize) * 4).min(frame.height - row0);
    let (crow0, ccol0) = frame.chroma_origin(geo.mi_row_start, geo.mi_col_start);
    let (chroma_w, chroma_h) = if frame.num_planes > 1 {
        (
            ((width + usize::from(ssx)) >> ssx).min(frame.chroma_w - ccol0),
            ((height + usize::from(ssy)) >> ssy).min(frame.chroma_h - crow0),
        )
    } else {
        (0, 0)
    };
    let crop = |src: &[u16], stride: usize, x0: usize, y0: usize, w: usize, h: usize| -> Vec<u16> {
        let mut out = Vec::with_capacity(w * h);
        for y in 0..h {
            out.extend_from_slice(&src[(y0 + y) * stride + x0..(y0 + y) * stride + x0 + w]);
        }
        out
    };
    let lin = YuvFrame {
        width: width as u32,
        height: height as u32,
        bit_depth: input.bit_depth,
        format: input.format,
        y: crop(&input.y, frame.width, col0, row0, width, height),
        u: crop(&input.u, frame.chroma_w, ccol0, crow0, chroma_w, chroma_h),
        v: crop(&input.v, frame.chroma_w, ccol0, crow0, chroma_w, chroma_h),
    };
    let lgeo = TileGeometry {
        mi_row_start: 0,
        mi_row_end: mi_rows,
        mi_col_start: 0,
        mi_col_end: mi_cols,
    };
    let rc = ReconState {
        y: vec![0u16; width * height],
        u: vec![0u16; chroma_w * chroma_h],
        v: vec![0u16; chroma_w * chroma_h],
        width,
        height,
        chroma_w,
        chroma_h,
        bit_depth: frame.bit_depth,
        subsampling_x: ssx,
        subsampling_y: ssy,
        num_planes: frame.num_planes,
        mi_rows,
        mi_cols,
        lossless: frame.lossless,
        allow_screen_content_tools: frame.allow_screen_content_tools,
        allow_intrabc: false,
        qp: frame.qp,
        search: frame.search,
        bd: BlockDecodedMirror::new(ssx, ssy, frame.num_planes),
        dv_hash: crate::encoder::dv_hash::DvHashIndex::default(),
    };
    let st = PartitionSyntaxWriter::new(mi_rows, mi_cols, lgeo)
        .expect("tile geometry is a valid frame geometry");
    let local_origins: Vec<(u32, u32)> = origins
        .iter()
        .map(|&(r, c)| (r - geo.mi_row_start, c - geo.mi_col_start))
        .collect();
    (
        lgeo,
        local_origins,
        (geo.mi_row_start, geo.mi_col_start),
        lin,
        rc,
        st,
    )
}

/// r460 — the luma colour-count probe behind
/// [`SearchLimits::screen_content_probe`]: the fraction of 16×16
/// luma blocks with at most 8 distinct sample values. Screen-like
/// content (text, UI, flat fills) scores high; photographic content
/// near zero.
pub(crate) fn screen_content_probe(input: &YuvFrame) -> bool {
    let (w, h) = (input.width as usize, input.height as usize);
    let mut blocks = 0usize;
    let mut flat = 0usize;
    let mut y = 0;
    while y + 16 <= h {
        let mut x = 0;
        while x + 16 <= w {
            let mut seen: Vec<u16> = Vec::with_capacity(9);
            let mut few = true;
            'scan: for i in 0..16 {
                for j in 0..16 {
                    let v = input.y[(y + i) * w + x + j];
                    if !seen.contains(&v) {
                        if seen.len() == 8 {
                            few = false;
                            break 'scan;
                        }
                        seen.push(v);
                    }
                }
            }
            blocks += 1;
            flat += usize::from(few);
            x += 16;
        }
        y += 16;
    }
    blocks == 0 || flat * 4 >= blocks
}

/// r431 — the spatial-scalability shape knobs on the intra driver
/// (see [`encode_key_frame_yuv_full`]). Every field's default keeps
/// the pre-r431 KEY shape bit-for-bit.
#[derive(Default, Clone, Copy)]
pub(crate) struct KeyExtras<'a> {
    /// §5.9.15 uniform tile layout `(TileColsLog2, TileRowsLog2)`.
    pub tiles: (u32, u32),
    /// r433 — §5.11.1 tile-group packaging: split the frame's tiles
    /// across this many `OBU_TILE_GROUP` OBUs (contiguous, as even as
    /// possible, each coding `tile_start_and_end_present_flag = 1`
    /// with its `tg_start` / `tg_end` slice), emitted after a
    /// standalone `OBU_FRAME_HEADER` instead of the §5.10 `OBU_FRAME`
    /// packing. `0` / `1` keep the historical single-`OBU_FRAME`
    /// shape; values above the realized tile count clamp to it. The
    /// per-tile entropy payloads are byte-identical either way — only
    /// the §5.2 OBU framing changes.
    pub tile_groups: u32,
    /// r450 — see [`crate::encoder::inter_frame::GopTuning::tile_spans`]:
    /// a single-group multi-tile KEY codes
    /// `tile_start_and_end_present_flag = 1` under the split
    /// (`OBU_FRAME_HEADER` + `OBU_TILE_GROUP`) framing.
    pub tile_spans: bool,
    /// r433 — §5.9.15 NON-UNIFORM (explicit) tile layout: per-column
    /// widths and per-row heights in superblock units
    /// (`uniform_tile_spacing_flag = 0` on the wire, coded through
    /// the `width_in_sbs_minus_1` / `height_in_sbs_minus_1` `ns()`
    /// walks). Overrides [`KeyExtras::tiles`] when `Some`; the
    /// layout must satisfy the §5.9.15 legal window (see
    /// [`crate::tile_info::TileInfo::explicit_layout`]).
    pub explicit_tiles: Option<(&'a [u32], &'a [u32])>,
    /// Code the frame under THIS sequence header instead of building
    /// one from the input dimensions (the §6.7.5 layered-stream shape
    /// — one sequence header spans every spatial layer, so smaller
    /// layers code §5.9.5 `frame_size_override_flag = 1` explicit
    /// dimensions). The caller's header must carry the same tool
    /// gates the internal builder would set (the spatial driver
    /// builds it through [`build_intra_only_seq_yuv`] +
    /// `enable_filter_intra = true` at the TOP layer's dimensions).
    pub seq_override: Option<&'a SequenceHeader>,
    /// `Some(refresh_frame_flags)` codes the intra frame as §5.9.2
    /// `INTRA_ONLY_FRAME` with that EXPLICIT refresh mask (a shown
    /// KEY refreshes ALL slots — an enhancement spatial layer must
    /// not clobber its siblings' §7.20 state; §5.9.2 bars `0xFF`
    /// here). `error_resilient_mode` drops to 0 on this arm (the
    /// §5.9.2 ref_order_hint block stays silent).
    pub intra_only_refresh: Option<u8>,
    /// r431 — §5.9.17 per-superblock delta-q ELECTION switch (the KEY
    /// twin of the inter driver's r428 arm): when the complexity
    /// probe finds real activity spread on an unsegmented lossy
    /// frame, a second full search runs under the per-superblock
    /// `CurrentQIndex` plan and the frame-level election keeps
    /// whichever arm scores better under the masking-weighted
    /// `Dw + λ·R` objective over exact realized bytes.
    pub delta_q: bool,
    /// The armed §5.11.13 plan (per-superblock units in FRAME-raster
    /// order) — set internally by the election's second arm; callers
    /// leave it `None`.
    pub delta_plan: Option<&'a [i32]>,
    /// r439 — §5.9.12 quantizer-matrix ELECTION switch (the KEY twin
    /// of the inter driver's arm): on an unsegmented lossy frame
    /// whose luma carries real high-frequency energy (the
    /// [`crate::encoder::inter_frame::qm_probe`] gate), a second full
    /// search runs under `using_qmatrix = 1` at the
    /// [`crate::encoder::inter_frame::qm_level_for_q`] §9.5.3 level
    /// and the frame-level joint-objective election keeps the better
    /// arm; the winner then feeds the delta-q election (the arms
    /// compose).
    pub qm: bool,
    /// The armed §9.5.3 level — set internally by the election's
    /// second arm; callers leave it `None`.
    pub qm_level: Option<u8>,
    /// r436 — collect every tile's frame-end adapted CDF state into
    /// the returned carry so a consumer frame chaining its §8.3.1
    /// primary reference off this KEY's slot can run the §6.8.14
    /// donor election. Inert on single-tile layouts.
    pub collect_donor_cdfs: bool,
    /// r441 — §5.9.8 SUPERRES election switch (stage 0 of the
    /// dispatcher): on an unsegmented lossy single-tile KEY frame
    /// inside the measured win regime, each candidate denominator
    /// codes the frame at the §5.9.8 downscaled width (the inner
    /// QM / delta-q elections run at the coded extent), the
    /// reconstruction is upscaled through the decoder's own §7.16
    /// driver, and the plain joint objective over the ORIGINAL-extent
    /// SSE + exact realized bytes keeps the winner.
    pub superres_elect: bool,
    /// The armed §5.9.8 pair `(UpscaledWidth, SuperresDenom)` — set
    /// internally by the election's candidate arms (the CORE then
    /// codes `input` as the downscaled frame and the header carries
    /// the upscaled width + `coded_denom`); callers leave it `None`.
    pub superres: Option<(u32, u32)>,
    /// r441 — the armed §5.9.30 film-grain parameter set: the
    /// internally-built sequence header opens
    /// `film_grain_params_present` and the frame header carries the
    /// full §5.9.30 block (`apply_grain = 1`). OUTPUT-ONLY — the
    /// reconstruction this core returns stays PRE-grain (the §7.20
    /// reference payload); the GOP-level election applies the
    /// §7.18.3 synthesis to the output planes it publishes. Callers
    /// outside the film-grain election leave it `None`.
    pub film_grain: Option<&'a FilmGrainParams>,
    /// r444 — the ORIGINAL (upscaled-extent) source behind an armed
    /// [`KeyExtras::superres`] pair: `input` is the downscaled frame,
    /// and the in-core elections that operate at the §7.16 upscaled
    /// extent (the §7.17 LR fit, the QM / delta-q settlement scores)
    /// measure distortion against THIS frame. Set internally by
    /// [`encode_key_frame_superres_arm`]; callers leave it `None`.
    pub superres_source: Option<&'a YuvFrame>,
    /// r456 — open the sequence-level `enable_superres` gate WITHOUT
    /// arming a KEY-side pair: the GOP driver's mid-GOP inter
    /// election needs every frame header to carry the §5.9.8
    /// `use_superres` bit under ONE sequence header, so the KEY is
    /// coded under the open gate (its own election / plain shape
    /// unchanged otherwise). Inert under `seq_override`.
    pub superres_gate: bool,
    /// r460 — code the frame as a §6.4.1 STILL PICTURE: the sequence
    /// header carries `still_picture = 1` +
    /// `reduced_still_picture_header = 1` (operating point 0 only,
    /// `seq_level_idx` elected from the picture size per Annex A,
    /// the inter tool gates closed the way §5.5.1 infers them), and
    /// the frame header rides the §5.9.2 reduced arm
    /// (`disable_frame_end_update_cdf = 1` derived). Inert under
    /// `seq_override`.
    pub still: bool,
    /// r460 — `still_picture = 1` under a FULL (non-reduced) sequence
    /// header. Inert under `seq_override` or when `still` is set.
    pub still_full_header: bool,
    /// r460 — signal §5.5.2 `color_range = 1` (full-range samples).
    /// Inert under `seq_override`.
    pub full_range: bool,
    /// r460 — the CODED picture extent when `input` is the §5.9.5
    /// mi-grid-padded copy of a picture whose extent is not a
    /// multiple of 8 (see [`YuvFrame::padded_to_mi_grid`]): the
    /// sequence maximum, the §5.9.5 `frame_size`, the §7.17
    /// restoration geometry and the IVF header carry THIS extent
    /// while every plane buffer / RD walk runs at the padded one.
    /// Set by [`encode_key_frame_yuv_full`]; callers leave it `None`.
    pub coded_size: Option<(u32, u32)>,
    /// r460 — signal a §5.5.2 colour description
    /// (`color_primaries`, `transfer_characteristics`,
    /// `matrix_coefficients` — H.273 code points) instead of the
    /// unspecified triple. Signalling only. Inert under
    /// `seq_override`.
    pub color_description: Option<(u8, u8, u8)>,
    /// r460 — search-effort limits (see [`SearchLimits`]).
    pub search: SearchLimits,
}

/// r427/r431 — the general-format intra-frame core: every entry
/// point above funnels here (KEY frames; `INTRA_ONLY` via
/// [`KeyExtras::intra_only_refresh`]).
#[allow(clippy::too_many_arguments)]
pub(crate) fn encode_key_frame_yuv_full(
    input: &YuvFrame,
    base_q_idx: u8,
    model: RateModel,
    alt_q: &[i16],
    exact_mask: Option<&[bool]>,
    cdef: bool,
    cdef_units: bool,
    lr: bool,
    extras: &KeyExtras<'_>,
) -> Result<
    (
        EncodedKeyFrameYuv,
        crate::encoder::inter_frame::RefSlotCarry,
    ),
    Error,
> {
    input.validate_any_extent()?;
    // r460 — raise a requested uniform layout to the §5.9.15 legal
    // minimum (`MAX_TILE_WIDTH` / `MAX_TILE_AREA`): a 12 MP picture
    // cannot be one tile, so `(0, 0)` means "as few tiles as the
    // spec allows" rather than a reject.
    let mut extras = *extras;
    if extras.explicit_tiles.is_none() {
        let mi_cols = 2 * input.width.div_ceil(8);
        let mi_rows = 2 * input.height.div_ceil(8);
        if let Some((min_cols, min_rows_at_min_cols)) =
            crate::tile_info::TileInfo::min_uniform_layout(mi_cols, mi_rows, false)
        {
            let min_tiles = min_cols + min_rows_at_min_cols;
            let cols = extras.tiles.0.max(min_cols);
            let rows = extras.tiles.1.max(min_tiles.saturating_sub(cols));
            extras.tiles = (cols, rows);
        }
    }
    let extras = &extras;
    if input.width % 8 == 0 && input.height % 8 == 0 {
        return encode_key_frame_yuv_full_aligned(
            input, base_q_idx, model, alt_q, exact_mask, cdef, cdef_units, lr, extras,
        );
    }
    // r460 — ANY extent: the picture is replicated out to the §5.9.5
    // mi grid (the decoder reconstructs every mi block in full, so the
    // encoder's reconstruction / neighbour mirror must span the
    // padded extent too), coded under the TRUE extent
    // (`KeyExtras::coded_size` — sequence maximum, §5.9.5
    // `frame_size`, §7.17 restoration geometry, IVF header), and the
    // returned reconstruction is cropped back. The layered-stream /
    // §5.9.8 superres / per-segment-demand arms keep the aligned
    // contract (they carry their own extent bookkeeping).
    if extras.seq_override.is_some()
        || extras.superres.is_some()
        || extras.superres_source.is_some()
        || extras.superres_gate
        || exact_mask.is_some()
        || !alt_q.is_empty()
    {
        return Err(Error::PartitionWalkOutOfRange);
    }
    let padded = input.padded_to_mi_grid();
    let mut ex = *extras;
    ex.coded_size = Some((input.width, input.height));
    ex.superres_elect = false;
    let (mut k, carry) = encode_key_frame_yuv_full_aligned(
        &padded, base_q_idx, model, alt_q, exact_mask, cdef, cdef_units, lr, &ex,
    )?;
    let crop = |src: &[u16], sw: u32, w: u32, h: u32| -> Vec<u16> {
        let (sw, w, h) = (sw as usize, w as usize, h as usize);
        let mut out = Vec::with_capacity(w * h);
        for y in 0..h {
            out.extend_from_slice(&src[y * sw..y * sw + w]);
        }
        out
    };
    k.recon_y = crop(&k.recon_y, padded.width, input.width, input.height);
    if input.format != ChromaFormat::Monochrome {
        let (cw, ch) = (input.chroma_width(), input.chroma_height());
        k.recon_u = crop(&k.recon_u, padded.chroma_width(), cw, ch);
        k.recon_v = crop(&k.recon_v, padded.chroma_width(), cw, ch);
    }
    Ok((k, carry))
}

/// The aligned-extent core behind [`encode_key_frame_yuv_full`]
/// (`input` a multiple of 8 per axis — the pre-r460 contract).
#[allow(clippy::too_many_arguments)]
pub(crate) fn encode_key_frame_yuv_full_aligned(
    input: &YuvFrame,
    base_q_idx: u8,
    model: RateModel,
    alt_q: &[i16],
    exact_mask: Option<&[bool]>,
    cdef: bool,
    cdef_units: bool,
    lr: bool,
    extras: &KeyExtras<'_>,
) -> Result<
    (
        EncodedKeyFrameYuv,
        crate::encoder::inter_frame::RefSlotCarry,
    ),
    Error,
> {
    input.validate()?;
    // r441 — §5.9.8 SUPERRES election (stage 0, outermost): on an
    // unsegmented lossy single-tile KEY frame inside the measured win
    // regime, each candidate denominator codes the frame at the
    // §5.9.8 downscaled width — a COMPLETE dispatcher run, so the
    // §5.9.12 / §5.9.17 elections settle at the coded extent inside
    // each arm — the reconstruction is upscaled through the decoder's
    // own §7.16 driver, and the plain joint objective over the
    // ORIGINAL-extent SSE + exact realized bytes keeps the winner
    // (the flat arm on ties: streams outside an elected win stay
    // bit-identical to the pre-r441 baseline).
    if extras.superres_elect && extras.superres.is_none() {
        // r447 — the single-tile-frame scope is lifted: uniform
        // multi-tile layouts and §5.11.1 tile-group packaging ride
        // the election (each candidate codes its tiles at the §5.9.8
        // downscaled width — legality re-checked per denominator
        // below; the tile-group split is framing-only and clamps to
        // the realized tile count). EXPLICIT layouts stay out: their
        // per-column superblock widths are bound to the full-width
        // geometry and have no defined §5.9.8 remapping.
        let sr_ok = base_q_idx > 0
            && alt_q.is_empty()
            && exact_mask.is_none()
            && model == RateModel::Twin
            && extras.seq_override.is_none()
            && extras.intra_only_refresh.is_none()
            && extras.explicit_tiles.is_none()
            && extras.coded_size.is_none()
            && crate::encoder::superres_elect::superres_arm_allowed(
                base_q_idx,
                input.width as usize,
                input.height as usize,
            )
            && crate::encoder::superres_elect::superres_probe(input);
        let candidates: Vec<u32> = if sr_ok {
            crate::encoder::superres_elect::candidate_denoms(input.width)
                .into_iter()
                .filter(|&denom| {
                    // r447 — a multi-tile layout must stay inside the
                    // §5.9.15 legality window AT THE DOWNSCALED width
                    // (`MiCols` shrinks with the coded width; rows are
                    // untouched — §7.16 resamples columns only), AND
                    // inside the Annex A tile-width conformance rule:
                    // on a `use_superres = 1` frame every tile except
                    // the right-most must be at least 128 luma
                    // samples wide (64 on flat frames — reference
                    // decoders enforce it).
                    crate::encoder::superres_elect::denom_tile_ok(
                        input.width,
                        input.height,
                        denom,
                        extras.tiles,
                    )
                })
                .collect()
        } else {
            Vec::new()
        };
        let mut plain_extras = *extras;
        plain_extras.superres_elect = false;
        if candidates.is_empty() {
            return encode_key_frame_yuv_full_aligned(
                input,
                base_q_idx,
                model,
                alt_q,
                exact_mask,
                cdef,
                cdef_units,
                lr,
                &plain_extras,
            );
        }
        let lambda = lambda_for(&QuantizerParams::neutral(base_q_idx, input.bit_depth));
        let score = |k: &EncodedKeyFrameYuv| -> u64 {
            let mut d = 0u64;
            for (a, b) in k
                .recon_y
                .iter()
                .zip(&input.y)
                .chain(k.recon_u.iter().zip(&input.u))
                .chain(k.recon_v.iter().zip(&input.v))
            {
                let diff = i64::from(*a) - i64::from(*b);
                d += (diff * diff) as u64;
            }
            score256(d, lambda, (k.temporal_unit_bytes.len() as u64) * 8 * 256)
        };
        let mut best = encode_key_frame_yuv_full_aligned(
            input,
            base_q_idx,
            model,
            alt_q,
            exact_mask,
            cdef,
            cdef_units,
            lr,
            &plain_extras,
        )?;
        let mut best_score = score(&best.0);
        for denom in candidates {
            let cand = encode_key_frame_superres_arm(
                input,
                base_q_idx,
                model,
                alt_q,
                exact_mask,
                cdef,
                cdef_units,
                lr,
                &plain_extras,
                denom,
            )?;
            let s = score(&cand.0);
            if s < best_score {
                best_score = s;
                best = cand;
            }
        }
        return Ok(best);
    }
    // r431 — §5.9.17 per-superblock delta-q ELECTION (the KEY twin of
    // the inter driver's r428 arm): both arms are complete frame
    // encodes (their trees decode to different reconstructions), so
    // the election runs the frame-level adaptive-quantisation
    // objective `Dw·256 + λ·R_bits256` over exact realized frame
    // bytes, with each superblock's squared error weighted by
    // `2^(-2·units)` from the SAME probe plan on both arms (masking:
    // banding shows first where nothing hides it).
    //
    // r439 — the §5.9.12 quantizer-matrix ELECTION runs FIRST (the
    // KEY twin of the inter driver's arm, plain joint objective over
    // full-frame SSE + exact realized bytes), and the winner feeds
    // the delta-q election — the arms compose: a delta-q plan
    // quantises at the running index with the SAME §7.12.3 QM
    // scaling on both sides.
    //
    // This dispatcher stays THIN on purpose: it runs the
    // `encode_key_frame_yuv_core` arms at its OWN (shallow) stack
    // depth rather than nesting one core call inside another's huge
    // frame (a 2 MiB test-thread stack overflows otherwise).
    let elections_ok = base_q_idx > 0
        && alt_q.is_empty()
        && exact_mask.is_none()
        && model == RateModel::Twin
        && extras.delta_plan.is_none()
        && extras.qm_level.is_none();
    // r441 — the multi-level QM ladder (the KEY twin of the inter
    // driver's: the quantiser-keyed level plus its lighter §9.5.3
    // neighbour, each settled by the same joint objective).
    let qm_candidates: Vec<u8> = if elections_ok
        && extras.qm
        && crate::encoder::inter_frame::qm_arm_allowed(
            base_q_idx,
            input.width as usize,
            input.height as usize,
        )
        && crate::encoder::inter_frame::qm_probe(input)
    {
        crate::encoder::inter_frame::qm_ladder_for_q(base_q_idx)
    } else {
        Vec::new()
    };
    let delta_plan_opt: Option<Vec<i32>> = if elections_ok && extras.delta_q {
        let (mi_rows_probe, mi_cols_probe) = (input.height / 4, input.width / 4);
        crate::encoder::inter_frame::delta_q_plan_units(input, mi_rows_probe, mi_cols_probe)
    } else {
        None
    };
    if qm_candidates.is_empty() && delta_plan_opt.is_none() {
        return encode_key_frame_yuv_core(
            input, base_q_idx, model, alt_q, exact_mask, cdef, cdef_units, lr, extras,
        );
    }
    let flat_extras = KeyExtras {
        tiles: extras.tiles,
        tile_groups: extras.tile_groups,
        tile_spans: extras.tile_spans,
        explicit_tiles: extras.explicit_tiles,
        seq_override: extras.seq_override,
        intra_only_refresh: extras.intra_only_refresh,
        delta_q: false,
        delta_plan: None,
        qm: false,
        qm_level: None,
        collect_donor_cdfs: extras.collect_donor_cdfs,
        // r441 — an armed §5.9.8 pair / §5.9.30 parameter set rides
        // every inner-election arm (the QM / delta-q stages of a
        // superres or film-grain candidate encode).
        superres_elect: false,
        superres: extras.superres,
        film_grain: extras.film_grain,
        superres_source: extras.superres_source,
        superres_gate: extras.superres_gate,
        still: extras.still,
        still_full_header: extras.still_full_header,
        full_range: extras.full_range,
        coded_size: extras.coded_size,
        color_description: extras.color_description,
        search: extras.search,
    };
    let lambda = lambda_for(&QuantizerParams::neutral(base_q_idx, input.bit_depth));
    type KeyOut = (
        EncodedKeyFrameYuv,
        crate::encoder::inter_frame::RefSlotCarry,
    );
    // r444 — on an armed §5.9.8 pair the core returns its
    // reconstruction at the UPSCALED extent (LR runs there per §7.4),
    // so the stage elections score against the ORIGINAL source — the
    // same objective the outer superres election settles on.
    let score_src: &YuvFrame = match (extras.superres, extras.superres_source) {
        (Some(_), Some(orig)) => orig,
        _ => input,
    };
    // Stage 1 — §5.9.12 QM election under the plain joint objective.
    let plain_score = |k: &KeyOut| -> u64 {
        let mut d = 0u64;
        for (a, b) in
            k.0.recon_y
                .iter()
                .zip(&score_src.y)
                .chain(k.0.recon_u.iter().zip(&score_src.u))
                .chain(k.0.recon_v.iter().zip(&score_src.v))
        {
            let diff = i64::from(*a) - i64::from(*b);
            d += (diff * diff) as u64;
        }
        score256(d, lambda, (k.0.temporal_unit_bytes.len() as u64) * 8 * 256)
    };
    let base = encode_key_frame_yuv_core(
        input,
        base_q_idx,
        model,
        alt_q,
        exact_mask,
        cdef,
        cdef_units,
        lr,
        &flat_extras,
    )?;
    let mut stage1_extras = flat_extras;
    let mut stage1 = base;
    let mut stage1_score = plain_score(&stage1);
    let mut stage1_won = false;
    for &lvl in &qm_candidates {
        let qm_extras = KeyExtras {
            qm_level: Some(lvl),
            ..flat_extras
        };
        let armed = encode_key_frame_yuv_core(
            input, base_q_idx, model, alt_q, exact_mask, cdef, cdef_units, lr, &qm_extras,
        )?;
        let score = plain_score(&armed);
        if score < stage1_score {
            stage1_score = score;
            stage1_extras = qm_extras;
            stage1 = armed;
            stage1_won = true;
        }
        // Refinement discipline (see the inter driver's ladder): only
        // a winning keyed level earns the neighbour's extra search.
        if crate::encoder::inter_frame::QM_LADDER_REFINES_ONLY && !stage1_won {
            break;
        }
    }
    // Stage 2 — §5.9.17 delta-q election on the stage-1 winner (the
    // masking-weighted objective, exactly the r431 arm).
    if let Some(plan) = &delta_plan_opt {
        let armed_extras = KeyExtras {
            delta_plan: Some(plan),
            ..stage1_extras
        };
        let armed = encode_key_frame_yuv_core(
            input,
            base_q_idx,
            model,
            alt_q,
            exact_mask,
            cdef,
            cdef_units,
            lr,
            &armed_extras,
        )?;
        let score = |k: &KeyOut| -> u64 {
            score256(
                key_weighted_sse(
                    score_src,
                    &k.0.recon_y,
                    &k.0.recon_u,
                    &k.0.recon_v,
                    plan,
                    (input.height / 4, input.width / 4),
                    extras
                        .superres
                        .map_or(crate::frame_header::SUPERRES_NUM, |(_, d)| d),
                ),
                lambda,
                (k.0.temporal_unit_bytes.len() as u64) * 8 * 256,
            )
        };
        return Ok(if score(&armed) < score(&stage1) {
            armed
        } else {
            stage1
        });
    }
    Ok(stage1)
}

/// r441 — one §5.9.8 superres candidate arm: downscale the source to
/// the denominator's §5.9.8 coded width, then run the COMPLETE
/// dispatcher on the downscaled frame with the pair armed (the inner
/// §5.9.12 / §5.9.17 elections settle inside the arm, scored at the
/// upscaled extent against the ORIGINAL source). r444 — the CORE
/// performs the §7.16 upscale itself, in §7.4 order between CDEF and
/// LR, so the §7.17 loop-restoration election runs at the UPSCALED
/// extent on this arm too; the returned `recon_*` planes live at the
/// upscaled extent, exactly what the decoder outputs and stores in
/// the §7.20 reference slots.
#[allow(clippy::too_many_arguments)]
pub(crate) fn encode_key_frame_superres_arm(
    input: &YuvFrame,
    base_q_idx: u8,
    model: RateModel,
    alt_q: &[i16],
    exact_mask: Option<&[bool]>,
    cdef: bool,
    cdef_units: bool,
    lr: bool,
    extras: &KeyExtras<'_>,
    denom: u32,
) -> Result<
    (
        EncodedKeyFrameYuv,
        crate::encoder::inter_frame::RefSlotCarry,
    ),
    Error,
> {
    let wd = crate::encoder::superres_elect::superres_coded_width(input.width, denom);
    let down = crate::encoder::superres_elect::downscale_width(input, wd);
    let mut ex = *extras;
    ex.superres_elect = false;
    ex.superres = Some((input.width, denom));
    ex.superres_source = Some(input);
    encode_key_frame_yuv_full_aligned(
        &down, base_q_idx, model, alt_q, exact_mask, cdef, cdef_units, lr, &ex,
    )
}

/// r431 — the general-format intra-frame CORE (no delta-q election;
/// the [`encode_key_frame_yuv_full`] dispatcher runs that above). One
/// complete encode under the resolved [`KeyExtras`] (including an
/// already-armed [`KeyExtras::delta_plan`]).
#[allow(clippy::too_many_arguments)]
fn encode_key_frame_yuv_core(
    input: &YuvFrame,
    base_q_idx: u8,
    model: RateModel,
    alt_q: &[i16],
    exact_mask: Option<&[bool]>,
    cdef: bool,
    cdef_units: bool,
    lr: bool,
    extras: &KeyExtras<'_>,
) -> Result<
    (
        EncodedKeyFrameYuv,
        crate::encoder::inter_frame::RefSlotCarry,
    ),
    Error,
> {
    let tiles = extras.tiles;
    // r426 — same table validation as the P-frame entry (`alt_q[0] ==
    // 0`, su(1+8) range, no over-255 sums, no base-0 segmentation).
    if !alt_q.is_empty() {
        if alt_q.len() == 1
            || alt_q.len() > crate::uncompressed_header_tail::MAX_SEGMENTS
            || alt_q[0] != 0
            || base_q_idx == 0
            || model != RateModel::Twin
        {
            // (The §5.11.9 skip-leaf pred inheritance rides the rate
            // twin's writer mirror — the segmented-KEY arm is
            // twin-model-only, like every production entry point.)
            return Err(Error::PartitionWalkOutOfRange);
        }
        for &d in alt_q {
            if !(-255..=255).contains(&d) || i32::from(base_q_idx) + i32::from(d) > 255 {
                return Err(Error::PartitionWalkOutOfRange);
            }
        }
    } else if exact_mask.is_some() {
        return Err(Error::PartitionWalkOutOfRange);
    }
    // Shape / depth / sample-range gate (multiples of 8, [8, MAX] per
    // axis, planes consistent with the format).
    input.validate()?;
    let bit_depth = input.bit_depth;
    let (ssx, ssy) = input.format.subsampling();
    let mono = input.format == ChromaFormat::Monochrome;
    let num_planes = input.format.num_planes();
    let width = input.width as usize;
    let height = input.height as usize;
    let chroma_w = input.chroma_width() as usize;
    let chroma_h = input.chroma_height() as usize;
    // r460 — the coded (true) extent vs the padded plane extent.
    let (coded_w, coded_h) = extras.coded_size.unwrap_or((input.width, input.height));
    // §5.11.46 palette + §5.9.20 intra-block-copy scope (r427): the
    // screen-content searches stay 8-bit 4:2:0 (their content scans
    // and the even-DV chroma alignment are built for that pairing);
    // other pairings close the §5.9.5 header gate — an encoder
    // election, not a conformance constraint.
    let sc_eligible = bit_depth == 8 && input.format == ChromaFormat::Yuv420;

    // r441 — the armed §5.9.8 superres pair (see
    // [`KeyExtras::superres`]): `input` is the DOWNSCALED frame; the
    // sequence maximum + §5.9.6 render size carry the upscaled width,
    // the header codes `use_superres = 1` + `coded_denom`, and the
    // §5.9.8 derivation must land exactly on the coded width.
    let superres: Option<(u32, u32)> = extras.superres;
    if let Some((up_w, denom)) = superres {
        if !(crate::frame_header::SUPERRES_DENOM_MIN..=16).contains(&denom)
            || crate::encoder::superres_elect::superres_coded_width(up_w, denom) != input.width
            || up_w <= input.width
            || up_w > KEY_FRAME_MAX_DIM
        {
            return Err(Error::PartitionWalkOutOfRange);
        }
        // r444 — the layered arm (`seq_override`, KEY or INTRA_ONLY
        // opener alike): the shared header must open the §5.9.8 gate
        // and its budget must cover the UPSCALED width — the §5.9.5
        // override fields then carry `up_w` and §5.9.8 re-derives the
        // coded width, exactly the flat-arm derivation.
        if let Some(shared) = extras.seq_override {
            if !shared.enable_superres || up_w > shared.max_frame_width_minus_1 + 1 {
                return Err(Error::PartitionWalkOutOfRange);
            }
        }
        // r444 — the arm carries the ORIGINAL source (the upscaled-
        // extent elections measure against it); shape-check it.
        match extras.superres_source {
            Some(s)
                if s.width == up_w
                    && s.height == input.height
                    && s.bit_depth == input.bit_depth
                    && s.format == input.format => {}
            _ => return Err(Error::PartitionWalkOutOfRange),
        }
    }

    let seq = match extras.seq_override {
        // r431 — layered-stream shape: code under the caller's shared
        // sequence header (its dimension budget must cover this
        // frame).
        Some(shared) => {
            if input.width > shared.max_frame_width_minus_1 + 1
                || input.height > shared.max_frame_height_minus_1 + 1
            {
                return Err(Error::PartitionWalkOutOfRange);
            }
            shared.clone()
        }
        None => {
            // r441 — under superres the sequence maximum is the
            // UPSCALED width: §5.9.5 `frame_size_override_flag = 0`
            // seeds `FrameWidth` from it and §5.9.8 then derives the
            // coded width.
            let seq_w = superres.map_or(coded_w, |(up_w, _)| up_w);
            let mut s = build_intra_only_seq_yuv(seq_w, coded_h, bit_depth, input.format)?;
            // r410: open the §5.11.24 filter-intra gate — the mode
            // picker now evaluates the five §7.11.2.3 recursive modes
            // on eligible luma blocks (the historical mirror drivers
            // build their own sequence headers and stay unaffected).
            s.enable_filter_intra = true;
            s.enable_superres = superres.is_some() || extras.superres_gate;
            // r441 — the §5.9.30 sequence gate (see
            // [`KeyExtras::film_grain`]).
            s.film_grain_params_present = extras.film_grain.is_some();
            if extras.still {
                crate::encoder::still::apply_still_picture_shape(&mut s);
            } else if extras.still_full_header {
                s.still_picture = true;
                if let Some(op) = s.operating_points.first_mut() {
                    op.seq_level_idx = crate::encoder::still::elect_seq_level_idx(
                        s.max_frame_width_minus_1 + 1,
                        s.max_frame_height_minus_1 + 1,
                    );
                }
            }
            s.color_config.color_range = extras.full_range;
            if let Some((cp, tc, mc)) = extras.color_description {
                s.color_config.color_description_present_flag = true;
                s.color_config.color_primaries = cp;
                s.color_config.transfer_characteristics = tc;
                s.color_config.matrix_coefficients = mc;
            }
            s
        }
    };
    let mut fh = build_intra_only_yuv420_8bit_fh_with_q(&seq, coded_w, coded_h, base_q_idx);
    if seq.reduced_still_picture_header {
        // §5.9.2: `disable_frame_end_update_cdf` is derived to 1 on
        // the reduced arm (no bit on the wire).
        fh.disable_frame_end_update_cdf = true;
    }
    // r441 — patch the §5.9.8 fields: the wire codes the UPSCALED
    // width (via the sequence maximum) + `coded_denom`; `FrameWidth`
    // / the mi grid stay at the coded (downscaled) extent the builder
    // derived from `input`.
    if let Some((up_w, denom)) = superres {
        let fs = fh
            .frame_size
            .as_mut()
            .ok_or(Error::PartitionWalkOutOfRange)?;
        fs.upscaled_width = up_w;
        fs.render_width = up_w;
        fs.use_superres = true;
        fs.superres_denom = denom;
        fs.coded_denom = (denom - crate::frame_header::SUPERRES_DENOM_MIN) as u8;
    }
    // r441 — the armed §5.9.30 film-grain block (see
    // [`KeyExtras::film_grain`]): full parameters on the wire; the
    // reconstruction below stays pre-grain.
    if let Some(fg) = extras.film_grain {
        if extras.seq_override.is_some() || !seq.film_grain_params_present || !fg.apply_grain {
            return Err(Error::PartitionWalkOutOfRange);
        }
        fh.film_grain_params = Some(fg.clone());
    }
    // r431 — §5.9.5: under a shared sequence header a smaller frame
    // codes its dimensions explicitly. r444 — the coded fields carry
    // the DISPLAY (upscaled) width on a §5.9.8 arm, so the override
    // decision compares that, not the downscaled coding extent.
    let display_w = superres.map_or(coded_w, |(up_w, _)| up_w);
    fh.frame_size_override_flag = extras.seq_override.is_some()
        && (display_w != seq.max_frame_width_minus_1 + 1
            || coded_h != seq.max_frame_height_minus_1 + 1);
    // r431 — §5.9.2 INTRA_ONLY arm: explicit refresh mask (never
    // `allFrames` — §5.9.2 bars it), no error resilience (the
    // ref_order_hint block stays silent; primary_ref is intra-skipped
    // either way), showable per the `frame_type != KEY_FRAME`
    // derivation.
    if let Some(mask) = extras.intra_only_refresh {
        if mask == 0xFF {
            return Err(Error::PartitionWalkOutOfRange);
        }
        fh.frame_type = crate::frame_header::FrameType::IntraOnly;
        fh.refresh_frame_flags = mask;
        fh.error_resilient_mode = false;
        fh.showable_frame = true;
    }
    // r427 — screen-content election is 8-bit-4:2:0-scoped (see
    // `sc_eligible` above); the §5.9.5 SELECT arm codes the header
    // bit either way.
    fh.allow_screen_content_tools = fh.allow_screen_content_tools
        && sc_eligible
        && (!extras.search.screen_content_probe || screen_content_probe(input));
    // r431 — the §5.9.15 uniform tile layout (single-tile unless the
    // caller configured columns/rows). Derived before the intra-bc
    // gate below: the DV hash index is frame-scoped, so the §5.9.20
    // election closes on multi-tile layouts.
    let (fs_mi_rows, fs_mi_cols) = {
        let fs = fh
            .frame_size
            .as_ref()
            .ok_or(Error::PartitionWalkOutOfRange)?;
        (fs.mi_rows, fs.mi_cols)
    };
    let mut ti = match extras.explicit_tiles {
        // r433 — §5.9.15 non-uniform (explicit) layout.
        Some((widths_sb, heights_sb)) => crate::tile_info::TileInfo::explicit_layout(
            fs_mi_cols,
            fs_mi_rows,
            seq.use_128x128_superblock,
            widths_sb,
            heights_sb,
        ),
        None => crate::tile_info::TileInfo::uniform_layout(
            fs_mi_cols,
            fs_mi_rows,
            seq.use_128x128_superblock,
            tiles.0,
            tiles.1,
        ),
    }
    .ok_or(Error::PartitionWalkOutOfRange)?;
    let multi_tile = !ti.is_single_tile();
    fh.tile_info = Some(ti.clone());
    // r418: open the §5.9.20 intra-block-copy gate only when the
    // content-level scan finds at least one §6.10.24-reachable exact
    // duplicate superblock — the per-leaf `use_intrabc` S() overhead
    // is only worth coding when a copy source provably exists.
    // r441 — §5.9.5 gates `allow_intrabc` on `UpscaledWidth ==
    // FrameWidth`: a superres frame never codes the bit, so the
    // search must not commit intra-bc leaves.
    fh.allow_intrabc = superres.is_none()
        && fh.allow_screen_content_tools
        && !multi_tile
        && intrabc_beneficial(input);
    // §5.9.19: `allow_intrabc = 1` short-circuits the cdef_params
    // block — keep the header descriptor on the parser's
    // short-circuit shape (the r428 election is gated off there too).
    if fh.allow_intrabc {
        fh.cdef_params = Some(crate::uncompressed_header_tail::CdefParams::short_circuit());
        // §5.9.20: `allow_intrabc = 1` short-circuits lr_params too.
        fh.lr_params = Some(crate::uncompressed_header_tail::LrParams::short_circuit());
    }
    // r410: the lossy arm codes §5.9.21 `TxMode = TX_MODE_SELECT` so
    // every leaf carries the §5.11.15 `tx_depth` choice the RD search
    // makes (lossless stays on the §5.9.2 CodedLossless ONLY_4X4 arm).
    if base_q_idx > 0 {
        fh.tx_mode = Some(crate::uncompressed_header_tail::TxMode::TxModeSelect);
    }
    let fs = fh
        .frame_size
        .as_ref()
        .ok_or(Error::PartitionWalkOutOfRange)?;
    let (mi_rows, mi_cols) = (fs.mi_rows, fs.mi_cols);

    let lossless = base_q_idx == 0;
    let mut qp = QuantizerParams::neutral(base_q_idx, bit_depth);
    if !alt_q.is_empty() {
        // r426 — §7.12.2 get_qindex inputs: the write-side §5.11.47
        // guard and the §5.11.39 quantiser chain key off these.
        qp.segmentation_enabled = true;
        for (seg, &d) in alt_q.iter().enumerate() {
            qp.seg_alt_q_active[seg] = true;
            qp.seg_alt_q_data[seg] = d;
        }
        fh.segmentation_params = Some(crate::encoder::inter_frame::segmentation_params_for(alt_q));
    }
    // r439 — the armed §5.9.12 quantizer-matrix arm (see
    // [`KeyExtras::qm_level`]): `using_qmatrix = 1` + the level on
    // all three planes in the header, and the `SegQMLevel[ plane ][
    // 0 ]` rows on the quantiser bundle — every §7.12.3
    // quantise/dequantise step in the search and the residual chain
    // rides the QM-scaled `q2`, matching the decoder's §5.9.2
    // derivation (segment 0 is the only coded segment).
    if let Some(lvl) = extras.qm_level {
        if base_q_idx == 0
            || !alt_q.is_empty()
            || exact_mask.is_some()
            || model != RateModel::Twin
            || lvl >= 15
        {
            return Err(Error::PartitionWalkOutOfRange);
        }
        qp.using_qmatrix = true;
        for plane in 0..3 {
            for seg in 0..crate::uncompressed_header_tail::MAX_SEGMENTS {
                qp.seg_qm_level[plane][seg] = lvl;
            }
        }
        if let Some(q) = fh.quantization_params.as_mut() {
            q.using_qmatrix = true;
            q.qm_y = lvl;
            q.qm_u = lvl;
            q.qm_v = lvl;
        }
    }
    // r431 — the armed §5.9.17 delta-q arm (see [`KeyExtras::delta_plan`]):
    // per-superblock `CurrentQIndex` walk, §5.11.13 deltas on the wire.
    let delta_plan = extras.delta_plan;
    if let Some(plan) = delta_plan {
        if base_q_idx == 0
            || !alt_q.is_empty()
            || exact_mask.is_some()
            || model != RateModel::Twin
            || plan.len() != sb_grid_origins(mi_rows, mi_cols).len()
        {
            return Err(Error::PartitionWalkOutOfRange);
        }
        qp.delta_q_present = true;
        qp.current_q_index = base_q_idx;
        fh.delta_q_params = Some(crate::uncompressed_header_tail::DeltaQParams {
            delta_q_present: true,
            delta_q_res: crate::encoder::inter_frame::DELTA_Q_RES,
        });
    }
    // r426 — the mask requires a lossless segment; resolve it once.
    let seg_ll = crate::encoder::inter_frame::seg_lossless_array(base_q_idx, alt_q);
    let ll_seg = (0..alt_q.len())
        .find(|&sid| seg_ll[sid])
        .map(|sid| sid as u8);
    if exact_mask.is_some() && ll_seg.is_none() {
        return Err(Error::PartitionWalkOutOfRange);
    }
    if let Some(mask) = exact_mask {
        if mask.len() != (mi_rows as usize) * (mi_cols as usize) {
            return Err(Error::PartitionWalkOutOfRange);
        }
    }

    // §5.11 frame-scope parameter bundle — mirrors the decode driver's
    // `TileDecodeParams` derivation for this header set field by field.
    let params = SyntaxFrameParams {
        subsampling_x: ssx,
        subsampling_y: ssy,
        num_planes,
        seg_id_pre_skip: false,
        segmentation_enabled: !alt_q.is_empty(),
        seg_ref_frame: [None; crate::uncompressed_header_tail::MAX_SEGMENTS],
        seg_skip: [false; crate::uncompressed_header_tail::MAX_SEGMENTS],
        seg_globalmv: [false; crate::uncompressed_header_tail::MAX_SEGMENTS],
        last_active_seg_id: alt_q.len().saturating_sub(1) as u8,
        lossless_array: seg_ll,
        coded_lossless: lossless,
        enable_cdef: seq.enable_cdef,
        allow_intrabc: fh.allow_intrabc,
        cdef_bits: 0,
        read_deltas: delta_plan.is_some(),
        use_128x128_superblock: seq.use_128x128_superblock,
        delta_q_res: if delta_plan.is_some() {
            crate::encoder::inter_frame::DELTA_Q_RES
        } else {
            0
        },
        delta_lf_present: false,
        delta_lf_multi: false,
        mono_chrome: mono,
        delta_lf_res: 0,
        allow_screen_content_tools: fh.allow_screen_content_tools,
        enable_filter_intra: seq.enable_filter_intra,
        bit_depth,
        tx_mode_select: !lossless,
        quant: qp,
        reduced_tx_set: fh.reduced_tx_set.unwrap_or(false),
        inter: None,
    };

    // Running reconstruction — tracks the decoder's `CurrFrame`
    // sample-for-sample (see module docs).
    let mut recon = ReconState {
        y: vec![0u16; width * height],
        u: vec![0u16; chroma_w * chroma_h],
        v: vec![0u16; chroma_w * chroma_h],
        width,
        height,
        chroma_w,
        chroma_h,
        bit_depth,
        subsampling_x: ssx,
        subsampling_y: ssy,
        num_planes,
        mi_rows,
        mi_cols,
        lossless,
        allow_screen_content_tools: fh.allow_screen_content_tools,
        allow_intrabc: fh.allow_intrabc,
        qp,
        search: extras.search,
        bd: BlockDecodedMirror::new(ssx, ssy, num_planes),
        // r425 — arm the exact-match DV index whenever the §5.9.20
        // gate opened (input-space hash seeds for the §5.11.7
        // search; validity + SSD/RD stay reconstruction-space).
        dv_hash: if fh.allow_intrabc {
            crate::encoder::dv_hash::DvHashIndex::build(&input.y, width, height)
        } else {
            crate::encoder::dv_hash::DvHashIndex::default()
        },
    };

    // §5.11.2 tile walk, 64×64 superblocks in raster order per tile
    // (r431: tiles in tile-scan order; every pre-r431 layout is the
    // degenerate single tile, whose walk is the whole-frame raster).
    // Per superblock: §5.11.3 `clear_block_decoded_flags`, then the
    // recursive §5.11.4 rate-distortion partition search (running the
    // mode picker + residual pipeline at every leaf in NW/NE/SW/SE
    // dispatch order), then emit its syntax. Per tile: fresh §8.2
    // `SymbolWriter`, fresh §8.3.1 frame-start CDF state, and the
    // §5.11.2 `begin_tile` re-scope (clear_above_context, per-tile
    // availability, delta lifecycle) on the ONE frame-scope syntax
    // driver whose grids (`MiSizes[]`, `SegmentIds[]`, `Cdef_Idx[]`)
    // accumulate across tiles like the decode walker's.
    let num_tiles = ti.tile_cols * ti.tile_rows;
    let tile_plan: Vec<(TileGeometry, Vec<(u32, u32)>)> = (0..num_tiles)
        .map(|t| {
            let g = ti.tile_geometry(t).expect("tile_num < NumTiles");
            let mut origins: Vec<(u32, u32)> = Vec::new();
            let mut r = g.mi_row_start;
            while r < g.mi_row_end {
                let mut c = g.mi_col_start;
                while c < g.mi_col_end {
                    origins.push((r, c));
                    c += SB_SIZE4_64;
                }
                r += SB_SIZE4_64;
            }
            (g, origins)
        })
        .collect();
    debug_assert_eq!(
        tile_plan.iter().map(|(_, o)| o.len()).sum::<usize>(),
        sb_grid_origins(mi_rows, mi_cols).len(),
        "tile plan must cover every superblock exactly once"
    );

    let mut state = PartitionSyntaxWriter::new(
        mi_rows,
        mi_cols,
        TileGeometry {
            mi_row_start: 0,
            mi_row_end: mi_rows,
            mi_col_start: 0,
            mi_col_end: mi_cols,
        },
    )
    .ok_or(Error::PartitionWalkOutOfRange)?;

    // r429 — the committed trees are retained: the per-unit CDEF
    // election re-emits the tile with §5.11.56 strength ids stamped.
    // r431: tile-scan order, with the superblock origin of each tree
    // kept alongside (the CDEF unit grid is frame-raster indexed).
    let mut trees: Vec<crate::encoder::partition_tree::SyntaxNode> = Vec::new();
    let mut tree_sb: Vec<(u32, u32)> = Vec::new();
    let mut tile_payloads: Vec<Vec<u8>> = Vec::with_capacity(num_tiles as usize);
    // The §8.4 frame-end donation: tile `context_update_tile_id`'s
    // adapted CDFs (`save_cdfs`). r436: EVERY tile's end state is
    // kept (boxed — far too large for by-value moves) so the carry
    // can offer the §6.8.14 donor-candidate set.
    let mut all_cdfs: Vec<Box<TileCdfContext>> = Vec::with_capacity(num_tiles as usize);
    // r460 — the per-tile search body (one closure, run sequentially
    // or on `SearchLimits::threads` scoped threads: tiles are
    // independent by construction — no intra neighbour, context or
    // symbol state crosses a tile boundary — so each thread walks its
    // tiles on a private copy of the reconstruction / syntax mirror
    // and the results are stitched back in tile order, bit-identical
    // to the sequential walk).
    let disable_cdf_update_search = fh.disable_cdf_update;
    let frame_mi_cols = mi_cols;
    // r464 — `input` / `rc` / `st` are either the frame-scope objects
    // (sequential walk) or TILE-SIZED objects with the tile at their
    // origin (the threaded walk — see `tile_local` below); `abs` is
    // the tile origin in frame mi units (the §5.9.17 delta plan is
    // frame-raster indexed), and the returned superblock origins are
    // frame coordinates.
    let run_tile = |geo: TileGeometry,
                    origins: &[(u32, u32)],
                    abs: (u32, u32),
                    input: &YuvFrame,
                    rc: &mut ReconState,
                    st: &mut PartitionSyntaxWriter|
     -> Result<TileSearchOut, Error> {
        let mut out_trees: Vec<crate::encoder::partition_tree::SyntaxNode> = Vec::new();
        let mut out_sbs: Vec<(u32, u32)> = Vec::new();
        if !st.begin_tile(geo) {
            return Err(Error::PartitionWalkOutOfRange);
        }
        rc.bd.set_tile(geo);
        let (mi_rows, mi_cols) = (rc.mi_rows, rc.mi_cols);
        let mut writer = SymbolWriter::new(disable_cdf_update_search);
        let mut tile_cdfs = TileCdfContext::new_from_defaults();
        tile_cdfs.init_coeff_cdfs(base_q_idx);
        // §5.11.1 per-tile prologue: `CurrentQIndex = base_q_idx` at
        // every tile entry.
        rc.qp.current_q_index = base_q_idx;
        let sb_cols_frame = (mi_cols + abs.1).max(frame_mi_cols).div_ceil(16);
        // r464 — ONE rate twin per tile: its syntax mirror is committed
        // to exactly the trees the writer emits, so after each
        // superblock it equals the live state (asserted below) and
        // only the coder side is re-seated per superblock. The
        // pre-r464 per-superblock `snapshot` cloned the whole-frame
        // mirror (~40 MB at 12 MP) 3000 times per picture.
        let mut twin = RateTwin::snapshot(&tile_cdfs, st, &writer);
        for &(sb_r, sb_c) in origins {
            rc.bd.clear_for_sb(sb_r, sb_c, mi_rows, mi_cols);
            // r431 — §5.11.13 `CurrentQIndex` walk (the KEY twin of
            // the inter r428 arm): apply the plan step BEFORE the
            // superblock's search so every trial quantises (and the
            // twin prices the first block's delta symbol) at the
            // target index. The plan is FRAME-raster indexed and
            // ABSOLUTE (offset from `base_q_idx`); the §5.11.13
            // symbol codes the RELATIVE step from the running index,
            // computed so the §7.12.2 `Clip3( 1, 255, _ )` never
            // truncates.
            let prev_q = rc.qp.current_q_index;
            let dq_units = if let Some(p) = delta_plan {
                let k = (((sb_r + abs.0) / 16) * sb_cols_frame + ((sb_c + abs.1) / 16)) as usize;
                let step = 1i32 << params.delta_q_res;
                let want = (i32::from(base_q_idx) + p[k] * step).clamp(1, 255);
                let units = (want - i32::from(prev_q)) / step;
                rc.qp.current_q_index = (i32::from(prev_q) + units * step) as u8;
                units
            } else {
                0
            };
            // r421 — arm the §5.11.2 delta lifecycle on the live state
            // AND the rate twin's fork, so both enter the superblock
            // identically.
            st.arm_read_deltas();
            twin.resync_coder(&tile_cdfs, &writer);
            twin.arm_read_deltas();
            let seg_demand = exact_mask.map(|mask| KeySegDemand {
                mask,
                ll_seg: ll_seg.expect("mask requires a lossless segment (validated above)"),
            });
            let (tree, _cost) = build_search_tree(
                sb_r,
                sb_c,
                BLOCK_64X64,
                input,
                rc,
                &mut twin,
                &params,
                model,
                seg_demand.as_ref(),
                dq_units,
            )?;
            write_partition_tree_syntax(
                &mut writer,
                &mut tile_cdfs,
                st,
                &tree,
                sb_r,
                sb_c,
                BLOCK_64X64,
                &params,
            )?;
            // r421 anti-desync invariant: the search committed EXACTLY
            // the symbols the writer just emitted, so the twin's CDFs
            // and coder range must equal the live state — always, in
            // both rate models (commits are model-independent).
            debug_assert!(
                twin.matches_state(&tile_cdfs, st, &writer),
                "rate twin desynced from the writer after superblock ({sb_r},{sb_c}): {:?}",
                twin.differing_state_fields(st)
            );
            // r431 — realized `CurrentQIndex`: a full-superblock skip
            // leaf takes the §5.11.13 short-circuit arm (no delta on
            // the wire), so the decoder's running index never moves —
            // mirror that for the next superblock's step.
            if delta_plan.is_some() {
                if let SyntaxNode::Leaf(b) = &tree {
                    if b.skip == 1 {
                        rc.qp.current_q_index = prev_q;
                    }
                }
            }
            out_trees.push(tree);
            out_sbs.push((sb_r + abs.0, sb_c + abs.1));
        }
        Ok(TileSearchOut {
            payload: writer.finish(),
            cdfs: Box::new(tile_cdfs),
            trees: out_trees,
            sbs: out_sbs,
        })
    };
    let threads = extras.search.threads.max(1).min(num_tiles as usize);
    if threads <= 1 {
        for (geo, origins) in tile_plan.iter() {
            let out = run_tile(*geo, origins, (0, 0), input, &mut recon, &mut state)?;
            tile_payloads.push(out.payload);
            all_cdfs.push(out.cdfs);
            trees.extend(out.trees);
            tree_sb.extend(out.sbs);
        }
    } else {
        // r464 — each tile is searched on TILE-SIZED state: a crop of
        // the source, a tile-extent reconstruction and a tile-extent
        // syntax driver with the tile at the origin. Every §5.11
        // context, neighbour availability and intra edge is
        // tile-scoped (and the tile boundaries are superblock
        // aligned, so "inside the frame" means the same thing), so
        // the walk is the frame walk's, bit for bit — and the
        // per-thread footprint is one tile instead of one frame (the
        // r460 walk cloned the whole-frame reconstruction and mirror
        // per thread: ~130 MB per thread at 12 MP). The results are
        // stitched back in tile order. The §5.11.7 intra-block-copy
        // arm indexes the frame-level hash and the frame-level
        // reconstruction, so it keeps the frame-scope clone.
        let tile_local = !recon.allow_intrabc && exact_mask.is_none();
        let next = core::sync::atomic::AtomicUsize::new(0);
        type TileRun = (usize, TileSearchOut, ReconState, PartitionSyntaxWriter);
        let results: Vec<Result<TileRun, Error>> = std::thread::scope(|scope| {
            let mut handles = Vec::with_capacity(threads);
            for _ in 0..threads {
                let recon_ref = &recon;
                let state_ref = &state;
                let plan_ref = &tile_plan;
                let next_ref = &next;
                let run = &run_tile;
                handles.push(scope.spawn(move || {
                    let mut outs = Vec::new();
                    loop {
                        let t = next_ref.fetch_add(1, core::sync::atomic::Ordering::SeqCst);
                        if t >= plan_ref.len() {
                            break;
                        }
                        let (geo, origins) = &plan_ref[t];
                        if tile_local {
                            let (lgeo, local_origins, abs, lin, mut rc, mut st) =
                                tile_local_state(input, recon_ref, *geo, origins);
                            outs.push(
                                run(lgeo, &local_origins, abs, &lin, &mut rc, &mut st)
                                    .map(|o| (t, o, rc, st)),
                            );
                        } else {
                            let mut rc = recon_ref.clone();
                            let mut st = state_ref.clone();
                            outs.push(
                                run(*geo, origins, (0, 0), input, &mut rc, &mut st)
                                    .map(|o| (t, o, rc, st)),
                            );
                        }
                    }
                    outs
                }));
            }
            let mut all = Vec::with_capacity(tile_plan.len());
            for h in handles {
                all.extend(h.join().expect("tile search thread panicked"));
            }
            all
        });
        let mut per_tile: Vec<Option<(TileSearchOut, ReconState, PartitionSyntaxWriter)>> =
            (0..tile_plan.len()).map(|_| None).collect();
        for r in results {
            let (t, o, rc, st) = r?;
            per_tile[t] = Some((o, rc, st));
        }
        for (t, slot) in per_tile.into_iter().enumerate() {
            let (o, rc, st) = slot.expect("every tile searched");
            let geo = tile_plan[t].0;
            // Stitch the tile's reconstruction rect and mirror rect.
            let (r0, r1, c0, c1) = (
                geo.mi_row_start as usize * 4,
                (geo.mi_row_end as usize * 4).min(height),
                geo.mi_col_start as usize * 4,
                (geo.mi_col_end as usize * 4).min(width),
            );
            // Source rect origin inside `rc` (tile-local: the origin).
            let (sr0, sc0, sw) = if tile_local {
                (0usize, 0usize, rc.width)
            } else {
                (r0, c0, width)
            };
            for y in r0..r1 {
                let sy = y - r0 + sr0;
                recon.y[y * width + c0..y * width + c1]
                    .copy_from_slice(&rc.y[sy * sw + sc0..sy * sw + sc0 + (c1 - c0)]);
            }
            if num_planes > 1 {
                let (cr0, cr1) = (r0 >> ssy, ((r1 + usize::from(ssy)) >> ssy).min(chroma_h));
                let (cc0, cc1) = (c0 >> ssx, ((c1 + usize::from(ssx)) >> ssx).min(chroma_w));
                let (scr0, scc0, scw) = if tile_local {
                    (0usize, 0usize, rc.chroma_w)
                } else {
                    (cr0, cc0, chroma_w)
                };
                for y in cr0..cr1 {
                    let sy = y - cr0 + scr0;
                    recon.u[y * chroma_w + cc0..y * chroma_w + cc1]
                        .copy_from_slice(&rc.u[sy * scw + scc0..sy * scw + scc0 + (cc1 - cc0)]);
                    recon.v[y * chroma_w + cc0..y * chroma_w + cc1]
                        .copy_from_slice(&rc.v[sy * scw + scc0..sy * scw + scc0 + (cc1 - cc0)]);
                }
            }
            if tile_local {
                state.import_tile_from(&st, geo, ssx, ssy);
            } else {
                let snap = st.snapshot_price_scope(
                    geo.mi_row_start,
                    geo.mi_col_start,
                    geo.mi_col_end - geo.mi_col_start,
                    geo.mi_row_end - geo.mi_row_start,
                    &params,
                );
                state.restore_price_scope(&snap);
            }
            tile_payloads.push(o.payload);
            all_cdfs.push(o.cdfs);
            trees.extend(o.trees);
            tree_sb.extend(o.sbs);
        }
    }

    // §5.11.1 assembled tile-group body length — what the exact-bytes
    // elections below price (for a single tile this IS the tile
    // payload, byte for byte; multi-tile adds the flag byte + the
    // `le(TileSizeBytes)` size fields).
    let (layout_cols_log2, layout_rows_log2, ctx_update_id) = (
        ti.tile_cols_log2,
        ti.tile_rows_log2,
        ti.context_update_tile_id,
    );
    let assemble = move |payloads: &[Vec<u8>]| -> Result<Vec<u8>, Error> {
        let tsb = min_tile_size_bytes(payloads);
        write_tile_group_obu(&TileGroupObu::whole_frame(
            num_tiles,
            layout_cols_log2,
            layout_rows_log2,
            tsb,
            payloads.iter().cloned().map(TilePayload::new).collect(),
        ))
    };
    let mut tile_group_body = assemble(&tile_payloads)?;

    // r431 — replay the committed trees under `emit_params` (plus the
    // optional §5.11.57 `write_lr` interleave) across the tile plan:
    // per tile a fresh §8.2 writer, fresh §8.3.1 frame-start CDFs and
    // fresh §5.11.2 LR-reference state, on a fresh frame-scope syntax
    // driver re-scoped tile by tile. The replay emits the identical
    // symbols the search committed (only header-armed literals — CDEF
    // strength ids, LR coefficients — move the coder), so the elected
    // arms below compare EXACT realized bytes. Returns the per-tile
    // payloads, the `context_update_tile_id` §8.4 donation, and the
    // accumulated driver.
    let disable_cdf_update = fh.disable_cdf_update;
    type EmitOut = (
        Vec<Vec<u8>>,
        Vec<Box<TileCdfContext>>,
        PartitionSyntaxWriter,
    );
    let emit_tiles = |trees: &[crate::encoder::partition_tree::SyntaxNode],
                      emit_params: &SyntaxFrameParams,
                      lr_plan: Option<&crate::encoder::lr_elect::LrPlan>|
     -> Result<EmitOut, Error> {
        let mut re_state = PartitionSyntaxWriter::new(
            mi_rows,
            mi_cols,
            TileGeometry {
                mi_row_start: 0,
                mi_row_end: mi_rows,
                mi_col_start: 0,
                mi_col_end: mi_cols,
            },
        )
        .ok_or(Error::PartitionWalkOutOfRange)?;
        let mut payloads: Vec<Vec<u8>> = Vec::with_capacity(num_tiles as usize);
        let mut all: Vec<Box<TileCdfContext>> = Vec::with_capacity(num_tiles as usize);
        let mut tree_idx = 0usize;
        for (geo, origins) in tile_plan.iter() {
            if !re_state.begin_tile(*geo) {
                return Err(Error::PartitionWalkOutOfRange);
            }
            let mut re_writer = SymbolWriter::new(disable_cdf_update);
            let mut re_cdfs = TileCdfContext::new_from_defaults();
            re_cdfs.init_coeff_cdfs(base_q_idx);
            let mut lr_write_state = crate::encoder::loop_restoration_write::LrWriteState::new();
            for &(sb_r, sb_c) in origins {
                re_state.arm_read_deltas();
                if let Some(plan) = lr_plan {
                    crate::encoder::loop_restoration_write::write_lr(
                        &mut re_writer,
                        &mut re_cdfs,
                        &mut lr_write_state,
                        sb_r,
                        sb_c,
                        BLOCK_64X64,
                        &plan.write_params,
                        &plan.units,
                    )?;
                }
                write_partition_tree_syntax(
                    &mut re_writer,
                    &mut re_cdfs,
                    &mut re_state,
                    &trees[tree_idx],
                    sb_r,
                    sb_c,
                    BLOCK_64X64,
                    emit_params,
                )?;
                tree_idx += 1;
            }
            payloads.push(re_writer.finish());
            all.push(Box::new(re_cdfs));
        }
        Ok((payloads, all, re_state))
    };

    // r428/r429 — §5.9.19/§7.15 CDEF election on the KEY frame
    // (deblock levels are 0 on this header, so the reconstruction IS
    // the §7.15 input; `allow_intrabc = 1` closes the §5.9.19 gate —
    // the header short-circuits there and the decoder never filters).
    // r429 extends the r428 frame-level arm to `cdef_bits > 0`: the
    // election may propose per-64×64 strength ids, in which case the
    // tile is RE-EMITTED from the committed trees with the §5.11.56
    // `L(cdef_bits)` literals stamped (the fresh writer replays the
    // identical symbols from the identical §8.3.1 frame-start state —
    // only the equiprobable literals move the coder) and the final
    // arm settles on EXACT realized bytes: `D·256 + λ·8·256·(header +
    // tile)` for the per-unit arm vs the frame-level / unfiltered
    // fallback (the plan-stage bit prices are exact, but emission is
    // byte-aligned — same doctrine as the hp / temporal-seg /
    // primary-ref elections). The winner lands in the header and in
    // the reconstruction the §7.20 `allFrames` refresh stores.
    // (Same HARD gate as the inter driver on exactness-demand frames:
    // §7.15 would filter the demanded region's blocks.)
    // r429 — loop restoration needs the PRE-CDEF reconstruction
    // (§7.17 reads `CurrFrame` at stripe boundaries): snapshot before
    // the CDEF election below overwrites it.
    // r444 — the LR × superres pairing is live: on a §5.9.8 arm the
    // reconstruction (and this snapshot) are §7.16-upscaled between
    // the CDEF election and the LR election below, so §7.17 fits,
    // prices and applies at the UPSCALED extent — exactly the §7.4
    // order the decoder runs.
    // r460 — §7.14 deblocking-level election (runs first in the §7.4
    // in-loop order: deblock, then CDEF, then loop restoration).
    if extras.search.lf_effort > 0
        && base_q_idx > 0
        && !fh.allow_intrabc
        && exact_mask.is_none()
        && alt_q.is_empty()
    {
        if let Some(e) =
            crate::encoder::lf_elect::elect_loop_filter(&crate::encoder::lf_elect::LfElectInput {
                mirror: state.mirror(),
                input,
                recon_y: &recon.y,
                recon_u: &recon.u,
                recon_v: &recon.v,
                width,
                height,
                chroma_w,
                chroma_h,
                frame_width: coded_w,
                frame_height: coded_h,
                bit_depth,
                subsampling_x: ssx,
                subsampling_y: ssy,
                num_planes,
                effort: extras.search.lf_effort,
            })
        {
            recon.y = e.y;
            recon.u = e.u;
            recon.v = e.v;
            fh.loop_filter_params = Some(e.params);
        }
    }
    let lr_armed =
        lr && base_q_idx > 0 && seq.enable_restoration && !fh.allow_intrabc && exact_mask.is_none();
    // r464 — on a flat-width frame only the stripe-boundary rows of
    // the pre-CDEF reconstruction are kept (`StripeRows`: what §7.17
    // reads from `CurrFrame`); the §5.9.8 superres arm keeps the whole
    // planes (it upscales them below).
    let pre_cdef: Option<(Vec<u16>, Vec<u16>, Vec<u16>)> = (lr_armed && superres.is_some())
        .then(|| (recon.y.clone(), recon.u.clone(), recon.v.clone()));
    let pre_cdef_rows: Option<[crate::encoder::lr_elect::StripeRows; 3]> =
        (lr_armed && superres.is_none()).then(|| {
            use crate::encoder::lr_elect::StripeRows;
            [
                StripeRows::capture(&recon.y, width, height, 0),
                StripeRows::capture(&recon.u, chroma_w, chroma_h, ssy),
                StripeRows::capture(&recon.v, chroma_w, chroma_h, ssy),
            ]
        });
    // The §5.9.19 `cdef_bits` the FINAL committed tile was emitted
    // under (the LR re-emission below must replay the same literals).
    let mut committed_cdef_bits: u32 = 0;
    if cdef && base_q_idx > 0 && seq.enable_cdef && !fh.allow_intrabc && exact_mask.is_none() {
        if let Some(election) =
            crate::encoder::cdef_elect::elect_cdef(&crate::encoder::cdef_elect::CdefElectInput {
                mirror: state.mirror(),
                input,
                recon_y: &recon.y,
                recon_u: &recon.u,
                recon_v: &recon.v,
                width,
                height,
                chroma_w,
                chroma_h,
                bit_depth,
                subsampling_x: ssx,
                subsampling_y: ssy,
                num_planes,
                lambda: lambda_for(&recon.qp),
                max_bits: if cdef_units { 3 } else { 0 },
                fast: extras.search.cdef_fast,
                threads: extras.search.threads.max(1),
            })
        {
            let lambda = lambda_for(&recon.qp);
            let header_len = |cdef_params: &crate::uncompressed_header_tail::CdefParams| {
                let mut fh_c = fh.clone();
                fh_c.cdef_params = Some(*cdef_params);
                let mut bw = crate::encoder::bitwriter::BitWriter::new();
                encode_uncompressed_header(&mut bw, &fh_c, &seq);
                bw.byte_align();
                bw.finish().len()
            };
            let adopted: Option<crate::encoder::cdef_elect::CdefPlan>;
            if election.best.params.cdef_bits > 0 {
                let plan = &election.best;
                let mut cdef_params_w = params.clone();
                cdef_params_w.cdef_bits = u32::from(plan.params.cdef_bits);
                // r431 — `plan.unit_idx` is frame-raster per 64×64
                // unit; the trees ride tile-scan order, so the stamp
                // maps each tree through its superblock origin.
                let sb_cols_frame = mi_cols.div_ceil(16);
                for (tree, &(sb_r, sb_c)) in trees.iter_mut().zip(tree_sb.iter()) {
                    let k = ((sb_r / 16) * sb_cols_frame + (sb_c / 16)) as usize;
                    tree.stamp_cdef_idx(plan.unit_idx[k].max(0));
                }
                let (re_payloads, re_cdfs, re_state) = emit_tiles(&trees, &cdef_params_w, None)?;
                let re_body = assemble(&re_payloads)?;
                // Exact-bytes settlement: per-unit vs the fallback arm
                // (frame-level when it beats unfiltered, else the
                // unfiltered default header) on the SAME `D + λ·R`
                // scale the leaf ladders use.
                let unit_score = plan.d * 256
                    + lambda * 8 * 256 * ((header_len(&plan.params) + re_body.len()) as u64);
                let (fb_d, fb_hdr) = match &election.frame_level {
                    Some(p) => (p.d, header_len(&p.params)),
                    None => (
                        election.base_d,
                        header_len(
                            fh.cdef_params
                                .as_ref()
                                .expect("lossy KEY header carries cdef params"),
                        ),
                    ),
                };
                let fb_score =
                    fb_d * 256 + lambda * 8 * 256 * ((fb_hdr + tile_group_body.len()) as u64);
                if unit_score < fb_score {
                    tile_payloads = re_payloads;
                    tile_group_body = re_body;
                    all_cdfs = re_cdfs;
                    state = re_state;
                    committed_cdef_bits = u32::from(plan.params.cdef_bits);
                    // The re-emitted mirror's §5.11.56 grid must equal
                    // the plan (the decoder will derive ITS grid from
                    // these bytes; the filter below runs on the plan's
                    // grid).
                    debug_assert!(
                        {
                            let grid = state.mirror().cdef_idx();
                            let sb_cols_dbg = mi_cols.div_ceil(16);
                            plan.unit_idx.iter().enumerate().all(|(k, &idx)| {
                                let (ur, uc) = (k as u32 / sb_cols_dbg, k as u32 % sb_cols_dbg);
                                grid[((ur * 16) * mi_cols + uc * 16) as usize] == idx
                            })
                        },
                        "re-emitted cdef_idx grid diverged from the elected plan"
                    );
                    adopted = Some(election.best);
                } else {
                    // The per-unit arm lost the settlement: the
                    // original tile stands. Re-stamp the trees to id
                    // 0 — a later re-emission (the LR election)
                    // replays them at `cdef_bits = 0`, whose §5.11.56
                    // range check rejects any stamped id > 0.
                    for tree in trees.iter_mut() {
                        tree.stamp_cdef_idx(0);
                    }
                    adopted = election.frame_level;
                }
            } else {
                adopted = Some(election.best);
            }
            if let Some(plan) = adopted {
                crate::encoder::cdef_elect::apply_cdef_plan(
                    state.mirror(),
                    &plan,
                    input,
                    &mut recon.y,
                    &mut recon.u,
                    &mut recon.v,
                    width,
                    height,
                    chroma_w,
                    chroma_h,
                    bit_depth,
                    ssx,
                    ssy,
                    num_planes,
                    extras.search.threads.max(1),
                );
                fh.cdef_params = Some(plan.params);
            }
        }
    }

    // r444 — §7.4 steps 3-4 / §7.16 on the superres arm: upscale the
    // post-CDEF reconstruction (and the pre-CDEF snapshot §7.17
    // reads across stripe boundaries) to the upscaled extent through
    // the decoder's OWN driver, BETWEEN the CDEF and LR elections.
    // From here on the recon planes — the §7.20 reference payload —
    // live at the upscaled extent.
    let mut pre_cdef = pre_cdef;
    let (lr_w, lr_chroma_w, lr_src): (usize, usize, &YuvFrame) = if let Some((up_w, _)) = superres {
        let np = usize::from(num_planes);
        let upscale = |y: &[u16], u: &[u16], v: &[u16]| {
            crate::encoder::superres_elect::upscale_recon(
                [y, u, v],
                width as u32,
                height as u32,
                up_w,
                mi_cols,
                bit_depth,
                ssx,
                ssy,
                np,
            )
        };
        let (uy, uu, uv) = upscale(&recon.y, &recon.u, &recon.v)?;
        recon.y = uy;
        recon.u = uu;
        recon.v = uv;
        if let Some(pc) = pre_cdef.as_mut() {
            let (py, pu, pv) = upscale(&pc.0, &pc.1, &pc.2)?;
            *pc = (py, pu, pv);
        }
        let src = extras
            .superres_source
            .ok_or(Error::PartitionWalkOutOfRange)?;
        (
            up_w as usize,
            ((up_w + u32::from(ssx)) >> ssx) as usize,
            src,
        )
    } else {
        (width, chroma_w, input)
    };

    // r429 — §5.9.20/§5.11.57/§7.17 loop-restoration election: the
    // LAST in-loop stage runs on the post-CDEF reconstruction (r444:
    // post-§7.16 on a superres arm, at the upscaled extent, fitted
    // against the ORIGINAL source). The
    // election fits per-64×64-unit Wiener / self-guided candidates
    // through the decoder's own §7.17 kernels, then the tile is
    // RE-EMITTED with the §5.11.57 `write_lr` interleave (one window
    // per superblock, the same §5.11.56 CDEF literals as the
    // committed tile; on a superres frame the window maps superblock
    // columns through the §5.9.8 denominator ratio) and LR-on vs
    // LR-off settles on EXACT realized bytes. On adoption the plan
    // is applied through the §7.17 frame driver, so the stored
    // reference planes equal the decoder's byte-for-byte.
    let pre_cdef_curr: Option<[crate::encoder::lr_elect::LrCurr<'_>; 3]> =
        match (pre_cdef.as_ref(), pre_cdef_rows.as_ref()) {
            (Some((y, u, v)), _) => Some([
                crate::encoder::lr_elect::LrCurr::Full(y),
                crate::encoder::lr_elect::LrCurr::Full(u),
                crate::encoder::lr_elect::LrCurr::Full(v),
            ]),
            (None, Some(rows)) => Some([
                crate::encoder::lr_elect::LrCurr::Rows(&rows[0]),
                crate::encoder::lr_elect::LrCurr::Rows(&rows[1]),
                crate::encoder::lr_elect::LrCurr::Rows(&rows[2]),
            ]),
            (None, None) => None,
        };
    if let Some([pcy, pcu, pcv]) = pre_cdef_curr {
        let price_cdfs = {
            let mut c = TileCdfContext::new_from_defaults();
            c.init_coeff_cdfs(base_q_idx);
            c
        };
        let lambda = lambda_for(&recon.qp);
        let lr_header_len = |lrp: &crate::uncompressed_header_tail::LrParams| {
            let mut fh_c = fh.clone();
            fh_c.lr_params = Some(*lrp);
            let mut bw = crate::encoder::bitwriter::BitWriter::new();
            encode_uncompressed_header(&mut bw, &fh_c, &seq);
            bw.byte_align();
            bw.finish().len()
        };
        let off_hdr = lr_header_len(
            fh.lr_params
                .as_ref()
                .expect("lossy KEY header carries lr_params"),
        );
        let off_score = {
            let mut d = 0u64;
            let (fw, fhh) = if superres.is_some() {
                (lr_w, height)
            } else {
                (coded_w as usize, coded_h as usize)
            };
            let (cfw, cfh) = (
                (fw + usize::from(ssx)) >> ssx,
                (fhh + usize::from(ssy)) >> ssy,
            );
            for y in 0..fhh {
                for x in 0..fw {
                    let e = i64::from(recon.y[y * lr_w + x]) - i64::from(lr_src.y[y * lr_w + x]);
                    d += (e * e) as u64;
                }
            }
            if num_planes > 1 {
                for y in 0..cfh {
                    for x in 0..cfw {
                        let eu = i64::from(recon.u[y * lr_chroma_w + x])
                            - i64::from(lr_src.u[y * lr_chroma_w + x]);
                        let ev = i64::from(recon.v[y * lr_chroma_w + x])
                            - i64::from(lr_src.v[y * lr_chroma_w + x]);
                        d += (eu * eu + ev * ev) as u64;
                    }
                }
            }
            d * 256 + lambda * 8 * 256 * ((off_hdr + tile_group_body.len()) as u64)
        };
        // r460 — the §5.9.20 unit-size ladder: 64 / 128 / 256 px units
        // (128 / 256 under 128×128 superblocks), each a complete
        // per-unit election + tile re-emission, the frame keeping the
        // best `D·256 + λ·bits` — larger units amortise the per-unit
        // Wiener / SGR signalling, which is what lets restoration pay
        // on small pictures.
        type LrCand = (
            crate::encoder::lr_elect::LrPlan,
            Vec<Vec<u8>>,
            Vec<u8>,
            Vec<Box<TileCdfContext>>,
            PartitionSyntaxWriter,
            u64,
        );
        let mut best_lr: Option<LrCand> = None;
        let min_shift: u8 = if seq.use_128x128_superblock { 1 } else { 0 };
        for unit_shift in min_shift.max(extras.search.lr_min_unit_shift.min(2))..=2u8 {
            let Some(plan) =
                crate::encoder::lr_elect::elect_lr(&crate::encoder::lr_elect::LrElectInput {
                    input: lr_src,
                    curr_y: pcy,
                    curr_u: pcu,
                    curr_v: pcv,
                    cdef_y: &recon.y,
                    cdef_u: &recon.u,
                    cdef_v: &recon.v,
                    width: lr_w,
                    height,
                    chroma_w: lr_chroma_w,
                    chroma_h,
                    bit_depth,
                    subsampling_x: ssx,
                    subsampling_y: ssy,
                    num_planes,
                    mi_rows,
                    mi_cols,
                    frame_width: if superres.is_some() {
                        lr_w
                    } else {
                        coded_w as usize
                    },
                    frame_height: coded_h as usize,
                    sgr_step: extras.search.sgr_step,
                    wiener_rounds: extras.search.wiener_rounds,
                    unit_shift,
                    lambda,
                    price_cdfs: &price_cdfs,
                    disable_cdf_update: fh.disable_cdf_update,
                    use_superres: superres.is_some(),
                    superres_denom: superres.map_or(crate::frame_header::SUPERRES_NUM, |(_, d)| d),
                    threads: extras.search.threads.max(1),
                })
            else {
                continue;
            };
            let mut lr_params_w = params.clone();
            lr_params_w.cdef_bits = committed_cdef_bits;
            let (re_payloads, re_cdfs, re_state) = emit_tiles(&trees, &lr_params_w, Some(&plan))?;
            let re_body = assemble(&re_payloads)?;
            let on_score = plan.d * 256
                + lambda * 8 * 256 * ((lr_header_len(&plan.header) + re_body.len()) as u64);
            if std::env::var_os("OXIDEAV_AV1_LR_DEBUG").is_some() {
                eprintln!(
                    "lr-elect q={base_q_idx} units {}: d_pre {} d {} | bytes off {} on {} | score off {off_score} on {on_score} | frt {:?}",
                    64u32 << unit_shift,
                    plan.d_pre,
                    plan.d,
                    off_hdr + tile_group_body.len(),
                    lr_header_len(&plan.header) + re_body.len(),
                    plan.header.frame_restoration_type
                );
            }
            if on_score < off_score && best_lr.as_ref().map_or(true, |b| on_score < b.5) {
                best_lr = Some((plan, re_payloads, re_body, re_cdfs, re_state, on_score));
            }
        }
        if let Some((plan, re_payloads, re_body, re_cdfs, re_state, _)) = best_lr {
            tile_payloads = re_payloads;
            tile_group_body = re_body;
            all_cdfs = re_cdfs;
            state = re_state;
            let applied_d = crate::encoder::lr_elect::apply_lr_plan(
                &plan,
                lr_src,
                pcy,
                pcu,
                pcv,
                &mut recon.y,
                &mut recon.u,
                &mut recon.v,
                lr_w,
                height,
                lr_chroma_w,
                chroma_h,
                bit_depth,
                ssx,
                ssy,
                num_planes,
                mi_rows,
                mi_cols,
                if superres.is_some() {
                    lr_w
                } else {
                    coded_w as usize
                },
                coded_h as usize,
            );
            debug_assert_eq!(
                applied_d, plan.d,
                "applied §7.17 SSD diverged from the elected plan"
            );
            fh.lr_params = Some(plan.header);
        }
    }

    // §5.11.1 tile-group body — already assembled from the winning
    // per-tile payloads (`tile_group_body`); stamp the REALIZED
    // §6.8.14 `TileSizeBytes` into the header descriptor so the coded
    // `tile_size_bytes_minus_1` matches the assembly (the header BIT
    // LENGTH is invariant — the field is a fixed `f(2)` — so the
    // election prices above stay exact).
    ti.tile_size_bytes = min_tile_size_bytes(&tile_payloads) as u8;
    fh.tile_info = Some(ti.clone());

    // r436 — locate the §5.9.15 `context_update_tile_id` field on
    // the wire (see the inter driver's twin): two header writes with
    // field values 0 and 1 differ in exactly the field's LSB.
    let ctx_update_span: Option<(u32, u32)> = if ti.tile_cols_log2 + ti.tile_rows_log2 > 0 {
        let write_with = |ctx: u32| -> Vec<u8> {
            let mut fh_c = fh.clone();
            if let Some(t) = fh_c.tile_info.as_mut() {
                t.context_update_tile_id = ctx;
            }
            let mut bw = crate::encoder::bitwriter::BitWriter::new();
            encode_uncompressed_header(&mut bw, &fh_c, &seq);
            bw.byte_align();
            bw.finish()
        };
        let a = write_with(0);
        let b = write_with(1);
        debug_assert_eq!(a.len(), b.len(), "f(n) field cannot move the header length");
        let n = ti.tile_cols_log2 + ti.tile_rows_log2;
        let mut lsb: Option<u32> = None;
        for (i, (&x, &y)) in a.iter().zip(b.iter()).enumerate() {
            let d = x ^ y;
            if d != 0 {
                debug_assert!(
                    d.count_ones() == 1 && lsb.is_none(),
                    "exactly one bit distinguishes ctx ids 0 and 1"
                );
                lsb = Some((i as u32) * 8 + (7 - d.trailing_zeros()));
            }
        }
        let lsb = lsb.ok_or(Error::PartitionWalkOutOfRange)?;
        Some((lsb + 1 - n, n))
    } else {
        None
    };

    // §7.5 temporal unit. r433 — two packagings of the SAME header
    // bits and tile payloads:
    //
    //   * `tile_groups <= 1` (or a single tile): the §5.10
    //     `OBU_FRAME` — `frame_header_obu()` + `byte_alignment()`
    //     (zero pad — NOT §5.3.4 trailing_bits; OBU_FRAME is one of
    //     the §5.3.1 trailer-exempt types) + `tile_group_obu()`.
    //   * `tile_groups > 1`: a standalone `OBU_FRAME_HEADER` (§5.3.4
    //     trailing_bits) followed by that many `OBU_TILE_GROUP` OBUs,
    //     the whole-frame body re-framed into contiguous
    //     `tg_start ..= tg_end` slices (§6.10.1).
    let sh_body = write_sequence_header_obu(&seq);
    let effective_groups = extras.tile_groups.clamp(1, num_tiles);
    // r450 — `extras.tile_spans` forces the split framing on a
    // single-group multi-tile frame so the group can CODE its span
    // (`tile_start_and_end_present_flag = 1`; the §5.10 `OBU_FRAME`
    // packing requires the flag to be 0).
    let spans_split = extras.tile_spans && effective_groups == 1 && num_tiles > 1;
    let temporal_unit_bytes = if effective_groups > 1 || spans_split {
        let fh_payload = crate::encoder::frame_obu::write_frame_header_obu(&fh, &seq);
        let tg_bodies = if spans_split {
            vec![crate::encoder::tile_group_obu::single_group_with_spans(
                &tile_group_body,
                num_tiles,
                ti.tile_cols_log2,
                ti.tile_rows_log2,
                u32::from(ti.tile_size_bytes),
            )?]
        } else {
            crate::encoder::tile_group_obu::split_whole_frame_body(
                &tile_group_body,
                num_tiles,
                ti.tile_cols_log2,
                ti.tile_rows_log2,
                u32::from(ti.tile_size_bytes),
                effective_groups,
            )?
        };
        let mut obus = vec![ObuFrame::new(ObuType::FrameHeader, fh_payload)];
        obus.extend(
            tg_bodies
                .into_iter()
                .map(|b| ObuFrame::new(ObuType::TileGroup, b)),
        );
        build_temporal_unit(Some(&sh_body), &obus)
    } else {
        let frame_body = {
            let mut bw = crate::encoder::bitwriter::BitWriter::new();
            encode_uncompressed_header(&mut bw, &fh, &seq);
            bw.byte_align();
            let mut body = bw.finish();
            body.extend_from_slice(&tile_group_body);
            body
        };
        build_temporal_unit(Some(&sh_body), &[ObuFrame::new(ObuType::Frame, frame_body)])
    };

    // IVF v0 wrap. r441 — the container carries DISPLAY dimensions:
    // the §5.9.8 upscaled width on a superres frame.
    let ivf_w = superres.map_or(coded_w, |(up_w, _)| up_w);
    let mut ivf_bytes: Vec<u8> = Vec::new();
    {
        let cursor = std::io::Cursor::new(&mut ivf_bytes);
        let mut iw = IvfWriter::new(cursor, FOURCC_AV01, ivf_w as u16, coded_h as u16, 25, 1)
            .map_err(|_| Error::PartitionWalkOutOfRange)?;
        iw.write_frame(&temporal_unit_bytes, 0)
            .map_err(|_| Error::PartitionWalkOutOfRange)?;
        iw.patch_frame_count()
            .map_err(|_| Error::PartitionWalkOutOfRange)?;
    }

    // r423 — §7.20 slot payload for the KEY frame's `allFrames`
    // refresh: `save_cdfs` takes tile `context_update_tile_id`'s
    // adapted frame-end CDFs (r431: tile 0 on every layout;
    // `disable_frame_end_update_cdf = 0` on this header), and
    // `SavedSegmentIds` is the walker mirror's fully-stamped grid
    // (all-zero — §5.11.8 disabled-branch stamps).
    // r436 — the donation is `all_cdfs[ context_update_tile_id ]`
    // (id 0 as emitted); the full donor set rides along when the
    // caller armed the §6.8.14 election.
    let (cdfs, donor_cdfs) = if extras.collect_donor_cdfs && all_cdfs.len() > 1 {
        (all_cdfs[ctx_update_id as usize].clone(), all_cdfs)
    } else {
        (all_cdfs.swap_remove(ctx_update_id as usize), Vec::new())
    };
    let carry = crate::encoder::inter_frame::RefSlotCarry {
        cdfs,
        segment_ids: state.mirror().segment_ids().to_vec(),
        mi_rows,
        mi_cols,
        gm_params: crate::uncompressed_header_tail::prev_gm_params_default(),
        donor_cdfs,
        ctx_update_span,
    };

    Ok((
        EncodedKeyFrameYuv {
            ivf_bytes,
            temporal_unit_bytes,
            recon_y: recon.y,
            recon_u: recon.u,
            recon_v: recon.v,
            seq,
            fh,
        },
        carry,
    ))
}

/// r431 — the KEY twin of the inter driver's masking-weighted
/// distortion: per superblock (frame raster), the luma+chroma SSE
/// against the source weighted by `2^(-2·units)` from the delta-q
/// probe plan — a flat superblock's error counts up (banding shows
/// first where nothing masks it), a textured one's counts down.
///
/// r444 — `coded_mi` is the CODED frame's `(MiRows, MiCols)` (the
/// grid the plan indexes) and `superres_denom` the §5.9.8 ratio: on
/// a superres arm `src` / the recon planes live at the UPSCALED
/// extent, and each upscaled column maps back to its coded
/// superblock through `c · SUPERRES_NUM / SuperresDenom`. A
/// flat-width caller passes `SUPERRES_NUM` (identity mapping).
pub(crate) fn key_weighted_sse(
    src: &YuvFrame,
    ry: &[u16],
    ru: &[u16],
    rv: &[u16],
    plan: &[i32],
    coded_mi: (u32, u32),
    superres_denom: u32,
) -> u64 {
    let w = src.width as usize;
    let h = src.height as usize;
    let (ssx, ssy) = src.format.subsampling();
    let cw = src.chroma_width() as usize;
    let ch = src.chroma_height() as usize;
    let num_planes = src.format.num_planes();
    let (mi_rows, mi_cols) = coded_mi;
    let sb_rows = mi_rows.div_ceil(16) as usize;
    let sb_cols = mi_cols.div_ceil(16) as usize;
    debug_assert_eq!(
        plan.len(),
        sb_rows * sb_cols,
        "plan is per coded superblock"
    );
    let num = u64::from(crate::frame_header::SUPERRES_NUM);
    let den = u64::from(superres_denom);
    let sb_col_of =
        |c: usize| -> usize { (((c as u64 * num / den) / 64) as usize).min(sb_cols - 1) };
    let sb_row_of = |r: usize| -> usize { (r / 64).min(sb_rows - 1) };
    let mut sse = vec![0u64; sb_rows * sb_cols];
    for r in 0..h {
        let k_row = sb_row_of(r) * sb_cols;
        for c in 0..w {
            let diff = i64::from(ry[r * w + c]) - i64::from(src.y[r * w + c]);
            sse[k_row + sb_col_of(c)] += (diff * diff) as u64;
        }
    }
    if num_planes > 1 {
        for r in 0..ch {
            let k_row = sb_row_of(r << ssy) * sb_cols;
            for c in 0..cw {
                let k = k_row + sb_col_of(c << ssx);
                let du = i64::from(ru[r * cw + c]) - i64::from(src.u[r * cw + c]);
                let dv = i64::from(rv[r * cw + c]) - i64::from(src.v[r * cw + c]);
                sse[k] += (du * du + dv * dv) as u64;
            }
        }
    }
    let mut d = 0u64;
    for (k, &s) in sse.iter().enumerate() {
        let units = plan[k];
        d += if units >= 0 {
            s >> (2 * units)
        } else {
            s << (-2 * units)
        };
    }
    d
}

/// r431 — the minimal §6.8.14 `TileSizeBytes` (1..=4) that fits every
/// non-last tile's `tile_size_minus_1` (§5.11.1: the last tile of the
/// group carries no size field). `1` for a single-tile frame (the
/// field is then never coded — §5.9.15 skips the trailing pair when
/// both log2 counts are 0).
pub(crate) fn min_tile_size_bytes(payloads: &[Vec<u8>]) -> u32 {
    let mut need = 1u32;
    if let Some((_, non_last)) = payloads.split_last() {
        for p in non_last {
            debug_assert!(!p.is_empty(), "§5.11.1: non-last tile cannot be empty");
            let v = (p.len().max(1) - 1) as u64;
            let bytes = match v {
                0..=0xFF => 1,
                0x100..=0xFFFF => 2,
                0x1_0000..=0xFF_FFFF => 3,
                _ => 4,
            };
            need = need.max(bytes);
        }
    }
    need
}

// ---------------------------------------------------------------------
// §6.10.3 `BlockDecoded[]` encoder-side mirror (r410).
// ---------------------------------------------------------------------

/// SB-local index span: `-1..=16` for the 64×64 superblock
/// (`sbSize4 = 16`), folded by `+1` into `0..18`.
const BD_STRIDE: usize = 18;

/// Encoder-side mirror of the decode walker's §6.10.3
/// `BlockDecoded[ plane ][ y ][ x ]` superblock-local state — the
/// §5.11.3 per-SB clear plus the §5.11.35 per-TU stamps. Drives the
/// §7.11.2.1 `haveAboveRight` / `haveBelowLeft` reads so the
/// encoder's directional-mode neighbour extension is bit-identical
/// to the decoder's.
#[derive(Clone)]
pub(crate) struct BlockDecodedMirror {
    bd: Vec<u8>,
    /// §5.5.2 `subsampling_x` for the chroma planes (r427 — the
    /// §5.11.3 clear and the §5.11.35 anchor derivations key off it).
    sub_x: u8,
    /// §5.5.2 `subsampling_y`.
    sub_y: u8,
    /// §5.5.2 `NumPlanes` (1 or 3).
    num_planes: u8,
    /// r431 — the §5.11.2 tile scope the walk currently runs under
    /// (`MiRowStart` / `MiRowEnd` / `MiColStart` / `MiColEnd`). The
    /// §5.11.3 clear derives `sbWidth4` / `sbHeight4` from the tile's
    /// END coordinates, and the §7.11.2 `haveAbove` / `haveLeft`
    /// availability collapses to "TU origin strictly below/right of
    /// the tile origin" (see [`build_tu_neighbours`]). Defaults to a
    /// whole-frame sentinel (`start = 0`, `end = u32::MAX` — the ends
    /// are clamped against the frame extents at use sites), so every
    /// single-tile driver is unchanged; multi-tile drivers re-scope
    /// via [`Self::set_tile`] at each tile entry.
    tile: TileGeometry,
}

impl BlockDecodedMirror {
    pub(crate) fn new(sub_x: u8, sub_y: u8, num_planes: u8) -> Self {
        Self {
            bd: vec![0u8; 3 * BD_STRIDE * BD_STRIDE],
            sub_x,
            sub_y,
            num_planes,
            tile: TileGeometry {
                mi_row_start: 0,
                mi_row_end: u32::MAX,
                mi_col_start: 0,
                mi_col_end: u32::MAX,
            },
        }
    }

    /// r431 — re-scope the mirror to `tile` (see [`Self::tile`]).
    pub(crate) fn set_tile(&mut self, tile: TileGeometry) {
        self.tile = tile;
    }

    /// r431 — the current tile's origin in `plane`'s own sample space
    /// (`(x0, y0)` = the §5.11.51 `MiColStart` / `MiRowStart` scaled
    /// by `MI_SIZE` and the plane's subsampling) — the
    /// [`build_tu_neighbours`] `tile_x0` / `tile_y0` inputs.
    pub(crate) fn tile_origin_px(&self, plane: usize) -> (usize, usize) {
        let (sx, sy) = self.plane_sub(plane);
        (
            ((self.tile.mi_col_start as usize) * 4) >> sx,
            ((self.tile.mi_row_start as usize) * 4) >> sy,
        )
    }

    /// Per-plane §6.4.2 `(subX, subY)` (`(0, 0)` for luma, the
    /// sequence pair for chroma).
    #[inline]
    fn plane_sub(&self, plane: usize) -> (u32, u32) {
        if plane > 0 {
            (u32::from(self.sub_x), u32::from(self.sub_y))
        } else {
            (0, 0)
        }
    }

    #[inline]
    fn slot(plane: usize, y: i32, x: i32) -> Option<usize> {
        if plane >= 3 {
            return None;
        }
        let yi = y + 1;
        let xi = x + 1;
        if yi < 0 || xi < 0 {
            return None;
        }
        let (yi, xi) = (yi as usize, xi as usize);
        if yi >= BD_STRIDE || xi >= BD_STRIDE {
            return None;
        }
        Some(plane * BD_STRIDE * BD_STRIDE + yi * BD_STRIDE + xi)
    }

    /// §5.11.3 `clear_block_decoded_flags( r, c, sbSize4 = 16 )` at
    /// this mirror's subsampling / plane count. The §5.11.3
    /// `sbWidth4` / `sbHeight4` derivations read the TILE's `MiRowEnd`
    /// / `MiColEnd` — the [`Self::tile`] scope clamped to the frame
    /// extents (`mi_rows` / `mi_cols`), which collapses to the frame
    /// edge for the single-tile drivers (the pre-r431 behaviour).
    pub(crate) fn clear_for_sb(&mut self, sb_r: u32, sb_c: u32, mi_rows: u32, mi_cols: u32) {
        const SB_SIZE4: i32 = 16;
        let mi_row_end = self.tile.mi_row_end.min(mi_rows);
        let mi_col_end = self.tile.mi_col_end.min(mi_cols);
        for plane in 0..usize::from(self.num_planes) {
            let (sx, sy) = self.plane_sub(plane);
            let (sub_x, sub_y) = (sx as i32, sy as i32);
            let sb_width4 = (mi_col_end as i32 - sb_c as i32) >> sub_x;
            let sb_height4 = (mi_row_end as i32 - sb_r as i32) >> sub_y;
            let y_max = SB_SIZE4 >> sub_y;
            let x_max = SB_SIZE4 >> sub_x;
            for y in -1..=y_max {
                for x in -1..=x_max {
                    let val = u8::from((y < 0 && x < sb_width4) || (x < 0 && y < sb_height4));
                    if let Some(slot) = Self::slot(plane, y, x) {
                        self.bd[slot] = val;
                    }
                }
            }
            // §5.11.3 final line: the below-left corner of the SB is
            // never available.
            if let Some(slot) = Self::slot(plane, y_max, -1) {
                self.bd[slot] = 0;
            }
        }
    }

    #[inline]
    fn get(&self, plane: usize, y: i32, x: i32) -> bool {
        Self::slot(plane, y, x).is_some_and(|s| self.bd[s] != 0)
    }

    #[inline]
    fn set(&mut self, plane: usize, y: i32, x: i32) {
        if let Some(slot) = Self::slot(plane, y, x) {
            self.bd[slot] = 1;
        }
    }
}

/// SB-local §5.11.35 anchor for a TU at plane-space `(start_x,
/// start_y)`: `(base_row, base_col)` per the spec's
/// `subBlockMiRow/Col` derivation (`sbMask = 15` for 64×64 SBs).
#[inline]
fn tu_bd_anchor(
    bd: &BlockDecodedMirror,
    plane: usize,
    start_x: usize,
    start_y: usize,
) -> (i32, i32) {
    let (sub_x, sub_y) = bd.plane_sub(plane);
    let row = ((start_y as u32) << sub_y) >> 2;
    let col = ((start_x as u32) << sub_x) >> 2;
    let base_row = ((row & 15) >> sub_y) as i32;
    let base_col = ((col & 15) >> sub_x) as i32;
    (base_row, base_col)
}

/// §7.11.2.1 `haveAboveRight` / `haveBelowLeft` for a `tx_w × tx_h`
/// TU — the §5.11.35 `BlockDecoded[]` border reads.
#[inline]
pub(crate) fn tu_corner_avail(
    bd: &BlockDecodedMirror,
    plane: usize,
    start_x: usize,
    start_y: usize,
    tx_w: usize,
    tx_h: usize,
) -> (bool, bool) {
    let (base_row, base_col) = tu_bd_anchor(bd, plane, start_x, start_y);
    let step_x4 = (tx_w >> 2) as i32;
    let step_y4 = (tx_h >> 2) as i32;
    let above_right = bd.get(plane, base_row - 1, base_col + step_x4);
    let below_left = bd.get(plane, base_row + step_y4, base_col - 1);
    (above_right, below_left)
}

/// §5.11.35 per-TU `BlockDecoded[]` stamp over the TU footprint.
#[inline]
pub(crate) fn tu_bd_stamp(
    bd: &mut BlockDecodedMirror,
    plane: usize,
    start_x: usize,
    start_y: usize,
    tx_w: usize,
    tx_h: usize,
) {
    let (base_row, base_col) = tu_bd_anchor(bd, plane, start_x, start_y);
    let step_x4 = (tx_w >> 2) as i32;
    let step_y4 = (tx_h >> 2) as i32;
    for i in 0..step_y4 {
        for j in 0..step_x4 {
            bd.set(plane, base_row + i, base_col + j);
        }
    }
}

/// Encoder-side running reconstruction + quantiser bundle. r427:
/// planes are `u16` at [`Self::bit_depth`], chroma at the
/// [`Self::subsampling_x`] / [`Self::subsampling_y`] extents (empty
/// when [`Self::num_planes`] is 1).
#[derive(Clone)]
pub(crate) struct ReconState {
    pub(crate) y: Vec<u16>,
    pub(crate) u: Vec<u16>,
    pub(crate) v: Vec<u16>,
    pub(crate) width: usize,
    pub(crate) height: usize,
    pub(crate) chroma_w: usize,
    pub(crate) chroma_h: usize,
    /// §5.5.2 `BitDepth` (8 / 10 / 12).
    pub(crate) bit_depth: u8,
    /// §5.5.2 `subsampling_x` (0 or 1).
    pub(crate) subsampling_x: u8,
    /// §5.5.2 `subsampling_y`.
    pub(crate) subsampling_y: u8,
    /// §5.5.2 `NumPlanes` (1 or 3).
    pub(crate) num_planes: u8,
    pub(crate) mi_rows: u32,
    pub(crate) mi_cols: u32,
    pub(crate) lossless: bool,
    /// §5.9.2 `allow_screen_content_tools` for the frame this state
    /// reconstructs — gates the §5.11.46 palette election in
    /// [`encode_leaf_sq`] (the write side rejects palette commitments
    /// when the frame-header gate is closed, so the search must not
    /// build them).
    pub(crate) allow_screen_content_tools: bool,
    /// §5.9.20 `allow_intrabc` for the frame — gates the §5.11.7
    /// intra-block-copy election in [`encode_leaf_sq`]. Only ever
    /// `true` on intra frames (the §5.9.20 read is intra-only).
    pub(crate) allow_intrabc: bool,
    pub(crate) qp: QuantizerParams,
    pub(crate) bd: BlockDecodedMirror,
    /// r425 — per-frame block-hash index over the §6.10.24-reachable
    /// intra-block-copy source region (see
    /// [`crate::encoder::dv_hash`]). Inert (`Default`) unless the KEY
    /// driver armed it alongside `allow_intrabc`; maintained once per
    /// superblock via [`Self::advance_dv_hash`].
    pub(crate) dv_hash: crate::encoder::dv_hash::DvHashIndex,
    /// r460 — see [`SearchLimits`].
    pub(crate) search: SearchLimits,
}

impl ReconState {
    pub(crate) fn plane(&self, plane: usize) -> (&[u16], usize, usize) {
        match plane {
            0 => (&self.y, self.width, self.height),
            1 => (&self.u, self.chroma_w, self.chroma_h),
            _ => (&self.v, self.chroma_w, self.chroma_h),
        }
    }

    /// r427 — chroma-space origin of the mi cell `(r, c)` per the
    /// §5.11.5 `(MiRow >> subsampling_y, MiCol >> subsampling_x)`
    /// derivation, in samples.
    #[inline]
    pub(crate) fn chroma_origin(&self, r: u32, c: u32) -> (usize, usize) {
        (
            ((r >> self.subsampling_y) as usize) * 4,
            ((c >> self.subsampling_x) as usize) * 4,
        )
    }
}

// ---------------------------------------------------------------------
// §7.11.2 exact-mirror intra prediction (r410).
// ---------------------------------------------------------------------

/// §7.11.2.1 neighbour-array derivation against a `u16` running plane
/// — the encoder twin of the decode walker's `AboveRow[]` / `LeftCol[]`
/// build (head-extended representation: spec index `k` at offset
/// `k + 2`, the `-1` corner at offset 1). `have_above` / `have_left`
/// are the §5.11.35 `(AvailU || y > 0)` / `(AvailL || x > 0)` values.
/// `AvailU` / `AvailL` are TILE-scoped (§5.11.51 `is_inside`), so the
/// pair collapses to "TU origin strictly below / right of the tile
/// origin **in this plane's sample space**" — `tile_x0` / `tile_y0`
/// carry that plane-scaled tile origin (both `0` for a single-tile
/// whole-frame walk, reproducing the pre-r431 `start_y > 0` /
/// `start_x > 0` forms). r427: the no-neighbour fills are the
/// §7.11.2.2 depth-scaled `(1 << (BitDepth - 1)) ± 1` constants.
#[allow(clippy::type_complexity, clippy::too_many_arguments)]
pub(crate) fn build_tu_neighbours(
    plane_buf: &[u16],
    pw: usize,
    ph: usize,
    start_x: usize,
    start_y: usize,
    tile_x0: usize,
    tile_y0: usize,
    w: usize,
    h: usize,
    have_above_right: bool,
    have_below_left: bool,
    bit_depth: u8,
) -> (Vec<u16>, Vec<u16>, bool, bool) {
    let have_above = start_y > tile_y0;
    let have_left = start_x > tile_x0;
    let max_x = pw - 1;
    let max_y = ph - 1;
    let read = |yy: usize, xx: usize| -> u16 { plane_buf[yy.min(max_y) * pw + xx.min(max_x)] };
    let half: u16 = 1 << (bit_depth - 1);
    let corner: u16 = if have_above && have_left {
        read(start_y - 1, start_x - 1)
    } else if have_above {
        read(start_y - 1, start_x)
    } else if have_left {
        read(start_y, start_x - 1)
    } else {
        half
    };
    let span = w + h;
    let ext_cap = 2 * span + 2;
    let mut above_ext = vec![0u16; ext_cap];
    above_ext[0] = corner;
    above_ext[1] = corner;
    if !have_above && have_left {
        let v = read(start_y, start_x - 1);
        for slot in above_ext.iter_mut().skip(2).take(span) {
            *slot = v;
        }
    } else if !have_above && !have_left {
        let v = half - 1;
        for slot in above_ext.iter_mut().skip(2).take(span) {
            *slot = v;
        }
    } else {
        let above_limit = max_x.min(start_x + (if have_above_right { 2 * w } else { w }) - 1);
        for (i, slot) in above_ext.iter_mut().skip(2).take(span).enumerate() {
            *slot = read(start_y - 1, above_limit.min(start_x + i));
        }
    }
    let mut left_ext = vec![0u16; ext_cap];
    left_ext[0] = corner;
    left_ext[1] = corner;
    if !have_left && have_above {
        let v = read(start_y - 1, start_x);
        for slot in left_ext.iter_mut().skip(2).take(span) {
            *slot = v;
        }
    } else if !have_left && !have_above {
        let v = half + 1;
        for slot in left_ext.iter_mut().skip(2).take(span) {
            *slot = v;
        }
    } else {
        let left_limit = max_y.min(start_y + (if have_below_left { 2 * h } else { h }) - 1);
        for (i, slot) in left_ext.iter_mut().skip(2).take(span).enumerate() {
            *slot = read(left_limit.min(start_y + i), start_x - 1);
        }
    }
    (above_ext, left_ext, have_above, have_left)
}

/// §7.11.2 mode dispatch over pre-built head-extended neighbour
/// arrays — the same kernel routing the decode walker performs for
/// this driver's header set (`enable_intra_edge_filter = 0`,
/// `use_filter_intra = 0` ⇒ no §7.11.2.4 step-4 pre-pass,
/// `upsampleAbove = upsampleLeft = 0`). `angle_delta` (r410, in
/// `-3..=3`) shifts the §7.11.2.4 projection angle by
/// `ANGLE_STEP * delta` for the directional modes; a V_PRED / H_PRED
/// with a non-zero delta becomes fully directional per §7.11.2.1
/// (only the exact 90°/180° cases take the plain copies).
#[allow(clippy::too_many_arguments)]
fn predict_mode_from_neighbours(
    mode: usize,
    angle_delta: i32,
    w: usize,
    h: usize,
    above_ext: &[u16],
    left_ext: &[u16],
    have_above: bool,
    have_left: bool,
    bit_depth: u8,
) -> Option<Vec<u16>> {
    let span = w + h;
    let above_row = &above_ext[2..2 + span];
    let left_col = &left_ext[2..2 + span];
    let corner = above_ext[1];
    let log2_w = w.trailing_zeros();
    let log2_h = h.trailing_zeros();
    let mut pred = vec![0u16; w * h];
    let ok = match mode {
        m if m == DC_PRED => predict_intra_dc_pred(
            u8::from(have_left),
            u8::from(have_above),
            log2_w,
            log2_h,
            w,
            h,
            bit_depth,
            above_row,
            left_col,
            &mut pred,
        )
        .is_ok(),
        m if m == V_PRED && angle_delta == 0 => {
            predict_intra_v_pred(w, h, above_row, &mut pred).is_ok()
        }
        m if m == H_PRED && angle_delta == 0 => {
            predict_intra_h_pred(w, h, left_col, &mut pred).is_ok()
        }
        m if (V_PRED..=D67_PRED).contains(&m) => predict_intra_directional(
            w,
            h,
            MODE_TO_ANGLE[m] + angle_delta * ANGLE_STEP,
            0,
            0,
            above_ext,
            left_ext,
            &mut pred,
        )
        .is_ok(),
        m if m == SMOOTH_PRED => {
            predict_intra_smooth_pred(log2_w, log2_h, w, h, above_row, left_col, &mut pred).is_ok()
        }
        m if m == SMOOTH_V_PRED => {
            predict_intra_smooth_v_pred(log2_h, w, h, above_row, left_col, &mut pred).is_ok()
        }
        m if m == SMOOTH_H_PRED => {
            predict_intra_smooth_h_pred(log2_w, w, h, above_row, left_col, &mut pred).is_ok()
        }
        m if m == PAETH_PRED => {
            predict_intra_paeth_pred(w, h, above_row, left_col, corner, &mut pred).is_ok()
        }
        _ => false,
    };
    if !ok {
        return None;
    }
    Some(pred)
}

/// §7.11.2.3 recursive (filter-intra) prediction over pre-built
/// head-extended neighbour arrays — the `use_filter_intra == 1` luma
/// arm of the §7.11.2.1 dispatch (replaces the mode-driven kernels).
pub(crate) fn predict_filter_intra_from_neighbours(
    fim: usize,
    w: usize,
    h: usize,
    above_ext: &[u16],
    left_ext: &[u16],
    bit_depth: u8,
) -> Option<Vec<u16>> {
    let mut pred = vec![0u16; w * h];
    crate::cdf::predict_intra_recursive(w, h, fim, bit_depth, above_ext, left_ext, &mut pred)
        .ok()?;
    Some(pred)
}

/// One-TU §7.11.2 prediction from the running plane: neighbour build
/// (with real `BlockDecoded[]` corner availability) + kernel dispatch.
/// `fim = Some(mode)` (luma only) routes through the §7.11.2.3
/// recursive process instead of the mode-driven kernels.
#[allow(clippy::too_many_arguments)]
fn predict_tu(
    recon: &ReconState,
    plane: usize,
    start_x: usize,
    start_y: usize,
    w: usize,
    h: usize,
    mode: usize,
    angle_delta: i32,
    fim: Option<usize>,
) -> Vec<u16> {
    let (buf, pw, ph) = recon.plane(plane);
    let (avail_ar, avail_bl) = tu_corner_avail(&recon.bd, plane, start_x, start_y, w, h);
    let (tile_x0, tile_y0) = recon.bd.tile_origin_px(plane);
    let (above_ext, left_ext, have_above, have_left) = build_tu_neighbours(
        buf,
        pw,
        ph,
        start_x,
        start_y,
        tile_x0,
        tile_y0,
        w,
        h,
        avail_ar,
        avail_bl,
        recon.bit_depth,
    );
    if let Some(f) = fim.filter(|_| plane == 0) {
        return predict_filter_intra_from_neighbours(
            f,
            w,
            h,
            &above_ext,
            &left_ext,
            recon.bit_depth,
        )
        .expect("filter-intra kernel domain holds for coded TU sizes");
    }
    predict_mode_from_neighbours(
        mode,
        angle_delta,
        w,
        h,
        &above_ext,
        &left_ext,
        have_above,
        have_left,
        recon.bit_depth,
    )
    .expect("supported intra mode always predicts")
}

/// §3 `Round2Signed(x, n)`.
#[inline]
fn round2_signed(x: i64, n: u32) -> i64 {
    let half: i64 = 1i64 << (n - 1);
    if x < 0 {
        -(((-x) + half) >> n)
    } else {
        (x + half) >> n
    }
}

/// §7.11.5 predict-chroma-from-luma — layer the CFL AC contribution
/// onto an already-computed `DC_PRED` base for one `w × h` chroma TU
/// at chroma-space `(start_x, start_y)`. `max_luma_w` / `max_luma_h`
/// are the §5.11.35 `MaxLumaW` / `MaxLumaH` extents (the current
/// block's luma right/bottom edge — the last luma TU coded before the
/// chroma TUs). r427: general `(subX, subY)` — the §7.11.5 `L[]`
/// build sums the `(1 + subY) × (1 + subX)` collocated luma cell and
/// scales by `t << (3 - subX - subY)`; the output clamp is
/// `Clip1(BitDepth)`.
#[allow(clippy::too_many_arguments)]
fn cfl_layer(
    dc_pred: &[u16],
    recon_y: &[u16],
    luma_w: usize,
    start_x: usize,
    start_y: usize,
    w: usize,
    h: usize,
    alpha: i8,
    max_luma_w: usize,
    max_luma_h: usize,
    sub_x: u8,
    sub_y: u8,
    bit_depth: u8,
) -> Vec<u16> {
    let (sub_x, sub_y) = (u32::from(sub_x), u32::from(sub_y));
    // §7.11.5: `lumaX = Min( lumaX, MaxLumaW - (1 << subX) )` (and the
    // Y twin).
    let clamp_x = max_luma_w.saturating_sub(1 << sub_x);
    let clamp_y = max_luma_h.saturating_sub(1 << sub_y);
    let mut l = vec![0i64; w * h];
    let mut luma_sum: i64 = 0;
    for i in 0..h {
        let luma_y = ((start_y + i) << sub_y).min(clamp_y);
        for j in 0..w {
            let luma_x = ((start_x + j) << sub_x).min(clamp_x);
            let mut t = 0i64;
            for dy in 0..=sub_y as usize {
                for dx in 0..=sub_x as usize {
                    t += i64::from(recon_y[(luma_y + dy) * luma_w + luma_x + dx]);
                }
            }
            let v = t << (3 - sub_x - sub_y);
            l[i * w + j] = v;
            luma_sum += v;
        }
    }
    let log2_w = w.trailing_zeros();
    let log2_h = h.trailing_zeros();
    let luma_avg = round2_signed(luma_sum, log2_w + log2_h);
    let max_val = (1i64 << bit_depth) - 1;
    let mut out = vec![0u16; w * h];
    for k in 0..w * h {
        let scaled = round2_signed((alpha as i64) * (l[k] - luma_avg), 6);
        out[k] = (i64::from(dc_pred[k]) + scaled).clamp(0, max_val) as u16;
    }
    out
}

/// r460 — the §7.11.5 luma AC term `L - luma_avg` a CfL prediction
/// scales by α (see [`cfl_layer`]), for the least-squares α seed.
#[allow(clippy::too_many_arguments)]
fn cfl_luma_ac(
    recon_y: &[u16],
    luma_w: usize,
    start_x: usize,
    start_y: usize,
    w: usize,
    h: usize,
    max_luma_w: usize,
    max_luma_h: usize,
    sub_x: u8,
    sub_y: u8,
) -> Vec<i64> {
    let (sub_x, sub_y) = (u32::from(sub_x), u32::from(sub_y));
    let clamp_x = max_luma_w.saturating_sub(1 << sub_x);
    let clamp_y = max_luma_h.saturating_sub(1 << sub_y);
    let mut l = vec![0i64; w * h];
    let mut luma_sum: i64 = 0;
    for i in 0..h {
        let luma_y = ((start_y + i) << sub_y).min(clamp_y);
        for j in 0..w {
            let luma_x = ((start_x + j) << sub_x).min(clamp_x);
            let mut t = 0i64;
            for dy in 0..=sub_y as usize {
                for dx in 0..=sub_x as usize {
                    t += i64::from(recon_y[(luma_y + dy) * luma_w + luma_x + dx]);
                }
            }
            let v = t << (3 - sub_x - sub_y);
            l[i * w + j] = v;
            luma_sum += v;
        }
    }
    let luma_avg = round2_signed(luma_sum, w.trailing_zeros() + h.trailing_zeros());
    for v in l.iter_mut() {
        *v -= luma_avg;
    }
    l
}

// ---------------------------------------------------------------------
// Residual pipeline (any square TX size).
// ---------------------------------------------------------------------

/// §7.12.3 / §9.2: 64-dim transforms code only the top-left
/// `Min(32, w) × Min(32, h)` coefficients, addressed with the COMPACT
/// `tw`-stride layout. Repack the dense forward-quantize output; the
/// padding tail stays zero (never scanned). Sizes ≤ 32 pass through.
pub(crate) fn repack_compact(dense: Vec<i32>, w: usize, h: usize) -> Vec<i32> {
    let tw = w.min(32);
    let th = h.min(32);
    if tw == w && th == h {
        return dense;
    }
    let mut q = vec![0i32; w * h];
    for i in 0..th {
        for j in 0..tw {
            q[i * tw + j] = dense[i * w + j];
        }
    }
    q
}

/// §7.12.3 step-3 `flipUD` / `flipLR` destination-remap pair for a
/// `TxType` — the FLIPADST-family selectors (av1-spec lines
/// 16292-16296). Both false for every non-FLIPADST type (the whole
/// intra set — the remap below is then the identity).
#[inline]
pub(crate) fn step3_flips(tx_type: usize) -> (bool, bool) {
    use crate::cdf::{
        ADST_FLIPADST, DCT_FLIPADST, FLIPADST_ADST, FLIPADST_DCT, FLIPADST_FLIPADST, H_FLIPADST,
        V_FLIPADST,
    };
    let flip_ud = matches!(
        tx_type,
        FLIPADST_DCT | FLIPADST_ADST | V_FLIPADST | FLIPADST_FLIPADST
    );
    let flip_lr = matches!(
        tx_type,
        DCT_FLIPADST | ADST_FLIPADST | H_FLIPADST | FLIPADST_FLIPADST
    );
    (flip_ud, flip_lr)
}

/// One residual leg at `tx_sz`: forward (WHT for the lossless TX_4X4 /
/// DCT-family otherwise) + quantize, then the decoder's dequant +
/// inverse, stitching `Clip1(pred + res)` into the running plane with
/// the §7.12.3 step-3 `flipUD` / `flipLR` destination remap (the
/// FLIPADST family reaches this through the r411 inter chroma
/// inheritance; every intra-set type remaps as the identity).
/// Returns the committed `Quant[]` in the §5.11.39 coefficient layout
/// (the §7.12.3 compact-`tw` stride for 64-wide transforms, dense
/// row-major otherwise), zero-padded to `Tx_Width * Tx_Height`.
#[allow(clippy::too_many_arguments)]
pub(crate) fn residual_tx(
    input_plane: &[u16],
    recon_plane: &mut [u16],
    pw: usize,
    row0: usize,
    col0: usize,
    tx_sz: usize,
    pred: &[u16],
    plane: u8,
    lossless: bool,
    tx_type: usize,
    qp: &QuantizerParams,
) -> Vec<i32> {
    let w = TX_WIDTH[tx_sz];
    let h = TX_HEIGHT[tx_sz];
    residual_tx_avail(
        input_plane,
        recon_plane,
        pw,
        row0,
        col0,
        tx_sz,
        pred,
        plane,
        lossless,
        tx_type,
        qp,
        w,
        h,
        crate::encoder::forward_quantize::QUANT_ROUND_HALF,
    )
}

/// r425 — clip-aware twin of [`residual_tx`] for TUs of a
/// frame-edge-straddling block that extend past the plane: only the
/// `avail_w × avail_h` on-screen sub-rectangle reads input samples
/// (the off-screen residual is coded as zero — the decoder discards
/// those samples, so the choice is free) and only on-screen samples
/// are stitched back. Fully-on-screen TUs (`avail >= (w, h)`) take
/// the exact pre-r425 path.
#[allow(clippy::too_many_arguments)]
pub(crate) fn residual_tx_avail(
    input_plane: &[u16],
    recon_plane: &mut [u16],
    pw: usize,
    row0: usize,
    col0: usize,
    tx_sz: usize,
    pred: &[u16],
    plane: u8,
    lossless: bool,
    tx_type: usize,
    qp: &QuantizerParams,
    avail_w: usize,
    avail_h: usize,
    round_num_64: i64,
) -> Vec<i32> {
    let w = TX_WIDTH[tx_sz];
    let h = TX_HEIGHT[tx_sz];
    let (aw, ah) = (avail_w.min(w), avail_h.min(h));
    let mut residual = vec![0i64; w * h];
    for i in 0..ah {
        for j in 0..aw {
            residual[i * w + j] =
                i64::from(input_plane[(row0 + i) * pw + (col0 + j)]) - i64::from(pred[i * w + j]);
        }
    }
    let coeffs = if lossless {
        debug_assert_eq!(tx_sz, TX_4X4);
        let mut r16 = [0i64; 16];
        r16.copy_from_slice(&residual);
        forward_wht_4x4(&r16).to_vec()
    } else {
        forward_transform_2d(&residual, tx_sz, tx_type, false)
    };
    // r439 — the §5.9.12 `SegQMLevel[ plane ][ 0 ]` row rides the
    // quantiser bundle (15 = the no-QM §7.12.3 short-circuit; the
    // QM election sets it on unsegmented lossy frames, so segment 0
    // is the only coded segment whenever it is < 15).
    let qm = qp.seg_qm_level[plane as usize][0];
    let dense = forward_quantize_rounded(&coeffs, tx_sz, plane, 0, tx_type, qm, qp, round_num_64);
    let quant = repack_compact(dense, w, h);
    let dequant = dequantize_step1(&quant, tx_sz, plane, 0, tx_type, qm, qp);
    let res_back =
        inverse_transform_2d(&dequant, tx_sz, tx_type, u32::from(qp.bit_depth), lossless);
    let (flip_ud, flip_lr) = step3_flips(tx_type);
    let max_val = (1i64 << qp.bit_depth) - 1;
    for i in 0..h {
        let yy = if flip_ud { h - 1 - i } else { i };
        for j in 0..w {
            let xx = if flip_lr { w - 1 - j } else { j };
            if yy >= ah || xx >= aw {
                continue;
            }
            let p = i64::from(pred[yy * w + xx]) + res_back[i * w + j];
            recon_plane[(row0 + yy) * pw + (col0 + xx)] = p.clamp(0, max_val) as u16;
        }
    }
    quant
}

/// r410 — §5.11.47 per-TU LUMA transform-type RD search (lossy arm).
/// Trials every `TxType` admissible in the §5.11.48 intra set for
/// `tx_sz` (`TX_SET_INTRA_1`'s 7 types at 4×4/8×8, `TX_SET_INTRA_2`'s
/// 5 at 16×16, `DCT_DCT` alone at 32×32+), scoring each full
/// quantise→dequantise→inverse chain by `D + λ·R` over the TU, then
/// stitches the winner into the running plane. Returns the committed
/// `Quant[]` plus the `TxType` label — forced to `DCT_DCT` when the
/// winning TU quantises to all-zero (the §5.11.39 `all_zero` arm reads
/// no `transform_type` symbol and the walker stamps `DCT_DCT`).
///
/// r424 — with `fork = Some((tu_fork, tu_ctx))` each candidate's rate
/// is the EXACT §5.11.39 coefficient chain (the `all_zero` symbol at
/// its true neighbour context, the `intra_tx_type` S() against the
/// current adaptive CDFs at the leaf's §8.3.2 `intra_dir` axis, and
/// the full coefficient tail) priced through the writer's own one-TU
/// body, and the winner is committed into the running fork; `None`
/// keeps the magnitude proxy.
/// r425 — the search is clip-aware (see [`residual_tx_avail`]):
/// input reads, distortion and stitching stay inside the
/// `avail_w × avail_h` on-screen sub-rectangle; the coded off-screen
/// residual is zero. Fully-on-screen TUs pass the full TU extent.
#[allow(clippy::too_many_arguments)]
fn residual_tx_search_luma_avail(
    input_plane: &[u16],
    recon_plane: &mut [u16],
    pw: usize,
    row0: usize,
    col0: usize,
    tx_sz: usize,
    pred: &[u16],
    qp: &QuantizerParams,
    fork: Option<(&mut TuFork, &TuCtx<'_>)>,
    avail_w: usize,
    avail_h: usize,
    // r460 — `Some(set)`: only these §5.11.47 types are trialled (the
    // pruned search); `None` = the full admissible set.
    tx_type_shortlist: Option<&[usize]>,
    round_num_64: i64,
) -> Result<(Vec<i32>, u8), Error> {
    let w = TX_WIDTH[tx_sz];
    let h = TX_HEIGHT[tx_sz];
    let (aw, ah) = (avail_w.min(w), avail_h.min(h));
    let max_val = (1i64 << qp.bit_depth) - 1;
    let mut residual = vec![0i64; w * h];
    for i in 0..ah {
        for j in 0..aw {
            residual[i * w + j] =
                i64::from(input_plane[(row0 + i) * pw + (col0 + j)]) - i64::from(pred[i * w + j]);
        }
    }
    let set = intra_tx_type_set(
        tx_size_sqr_index(tx_sz) as u32,
        TX_SIZE_SQR_UP[tx_sz] as u32,
        false,
    );
    let lambda = lambda_for(qp);
    let fork_xy = fork.as_ref().map(|(_, ctx)| {
        (
            (col0 as u32 - ctx.base_x) / 4,
            (row0 as u32 - ctx.base_y) / 4,
        )
    });
    let mut best: Option<(Vec<i32>, Vec<i64>, u8, u64)> = None;
    for t in 0..crate::cdf::TX_TYPES {
        let admissible = t == DCT_DCT || (set > 0 && is_tx_type_in_set(false, set, t));
        if !admissible || tx_type_shortlist.is_some_and(|l| !l.contains(&t)) {
            continue;
        }
        let coeffs = forward_transform_2d(&residual, tx_sz, t, false);
        // r439 — luma §5.9.12 QM row (15 = no-QM; see `residual_tx_avail`).
        let qm = qp.seg_qm_level[0][0];
        let quant = repack_compact(
            forward_quantize_rounded(&coeffs, tx_sz, 0, 0, t, qm, qp, round_num_64),
            w,
            h,
        );
        let all_zero = quant.iter().all(|&q| q == 0);
        let dequant = dequantize_step1(&quant, tx_sz, 0, 0, t, qm, qp);
        let res_back = inverse_transform_2d(&dequant, tx_sz, t, u32::from(qp.bit_depth), false);
        // r460 — the §7.12.3 step-3 `flipUD` / `flipLR` destination
        // remap: the decoder places the inverse-transformed residual
        // flipped for the FLIPADST family, so the candidate's
        // distortion (and the committed reconstruction below) must
        // read it the same way — the pre-r460 search scored those
        // types against the unflipped residual and never elected one.
        let (flip_ud, flip_lr) = step3_flips(t);
        let src_idx = |i: usize, j: usize| -> usize {
            let yy = if flip_ud { h - 1 - i } else { i };
            let xx = if flip_lr { w - 1 - j } else { j };
            yy * w + xx
        };
        let mut d = 0u64;
        for i in 0..ah {
            for j in 0..aw {
                let rec = (i64::from(pred[i * w + j]) + res_back[src_idx(i, j)]).clamp(0, max_val);
                let diff = i64::from(input_plane[(row0 + i) * pw + (col0 + j)]) - rec;
                d += (diff * diff) as u64;
            }
        }
        // §5.11.39: an all-zero TU codes no transform_type symbol and
        // the walker stamps DCT_DCT — the label must follow.
        let label = if all_zero { DCT_DCT as u8 } else { t as u8 };
        // r424 — exact §5.11.39 chain bits through the running fork,
        // or the pre-r424 magnitude proxy. One scale per call.
        let score = match (&fork, fork_xy) {
            (Some((tu_fork, ctx)), Some((fx, fy))) => {
                let bits256 = tu_fork.price_luma_tu(ctx, tx_sz, fx, fy, &quant, label)?;
                score256(d, lambda, bits256)
            }
            _ => {
                let mut rate = 0u64;
                for &qv in &quant {
                    if qv != 0 {
                        rate += 3 + u64::from(32 - qv.unsigned_abs().leading_zeros());
                    }
                }
                d + lambda * rate
            }
        };
        let improves = match best.as_ref() {
            Some((_, _, _, s)) => score < *s,
            None => true,
        };
        if improves {
            best = Some((quant, res_back, label, score));
        }
        // The DCT_DCT trial quantising to all-zero means the residual
        // is below the quantisation floor — pred-exact reconstruction;
        // skip the remaining types (they would commit the same
        // all-zero DCT_DCT shape at best-marginal gains).
        if t == DCT_DCT && all_zero {
            break;
        }
    }
    let (quant, res_back, label, _) = best.expect("DCT_DCT is always admissible");
    if let (Some((tu_fork, ctx)), Some((fx, fy))) = (fork, fork_xy) {
        tu_fork.commit_luma_tu(ctx, tx_sz, fx, fy, &quant, label)?;
    }
    let (flip_ud, flip_lr) = step3_flips(label as usize);
    for i in 0..ah {
        for j in 0..aw {
            let yy = if flip_ud { h - 1 - i } else { i };
            let xx = if flip_lr { w - 1 - j } else { j };
            let p = i64::from(pred[i * w + j]) + res_back[yy * w + xx];
            recon_plane[(row0 + i) * pw + (col0 + j)] = p.clamp(0, max_val) as u16;
        }
    }
    Ok((quant, label))
}

// ---------------------------------------------------------------------
// Mode pickers.
// ---------------------------------------------------------------------

/// §5.11.42/§5.11.43 angle-delta candidate range for a mode: the
/// directional modes (`V_PRED..=D67_PRED`) search the full `-3..=3`
/// span when the block is `>= BLOCK_8X8` (below that no angle symbol
/// is coded and the delta is spec-forced to 0); everything else is 0.
fn angle_delta_candidates(mode: usize, n: usize) -> core::ops::RangeInclusive<i32> {
    if (V_PRED..=D67_PRED).contains(&mode) && n >= 8 {
        -3..=3
    } else {
        0..=0
    }
}

/// SSD-minimising luma (mode, angle_delta, filter_intra) pick — ALL
/// 13 §6.10.x intra modes, the §5.11.42 `-3..=3` angle-delta span for
/// the directional ones, and (r410) the five §7.11.2.3 filter-intra
/// modes on §5.11.24-eligible blocks (`Max(w, h) <= 32`; a
/// filter-intra win codes `y_mode = DC_PRED` + `use_filter_intra`) —
/// for one `bw × bh` block (recon-neighbour prediction at whole-block
/// extent, input-target SSD; r425: rectangular shapes ride the same
/// picker). The neighbour build uses the same `BlockDecoded[]` state
/// the block's first luma TU will observe.
fn pick_y_mode(
    recon: &ReconState,
    input: &YuvFrame,
    row0: usize,
    col0: usize,
    bw: usize,
    bh: usize,
) -> (u8, i8, Option<u8>) {
    // r425 — frame-edge-straddling blocks score on the on-screen
    // sub-rectangle only (the off-screen samples are discarded by the
    // decoder and carry no distortion).
    let (aw, ah) = (bw.min(recon.width - col0), bh.min(recon.height - row0));
    let (avail_ar, avail_bl) = tu_corner_avail(&recon.bd, 0, col0, row0, bw, bh);
    let (tile_x0, tile_y0) = recon.bd.tile_origin_px(0);
    let (above_ext, left_ext, have_above, have_left) = build_tu_neighbours(
        &recon.y,
        recon.width,
        recon.height,
        col0,
        row0,
        tile_x0,
        tile_y0,
        bw,
        bh,
        avail_ar,
        avail_bl,
        recon.bit_depth,
    );
    let ssd_of = |pred: &[u16]| -> u64 {
        let mut ssd = 0u64;
        for i in 0..ah {
            for j in 0..aw {
                let d = i64::from(input.y[(row0 + i) * recon.width + (col0 + j)])
                    - i64::from(pred[i * bw + j]);
                ssd += (d * d) as u64;
            }
        }
        ssd
    };
    let mut best = (DC_PRED as u8, 0i8, None);
    let mut best_ssd = u64::MAX;
    let try_mode = |mode: usize,
                    delta: i32,
                    best: &mut (u8, i8, Option<u8>),
                    best_ssd: &mut u64|
     -> Option<u64> {
        let pred = predict_mode_from_neighbours(
            mode,
            delta,
            bw,
            bh,
            &above_ext,
            &left_ext,
            have_above,
            have_left,
            recon.bit_depth,
        )?;
        let ssd = ssd_of(&pred);
        if ssd < *best_ssd {
            *best_ssd = ssd;
            *best = (mode as u8, delta as i8, None);
        }
        Some(ssd)
    };
    if recon.search.intra_mode_prescreen {
        // r464 — delta-0 screen over every mode, then the §5.11.42
        // delta refinement around the two best directional modes.
        let mut dir_scores: Vec<(u64, usize)> = Vec::with_capacity(8);
        for mode in 0..INTRA_MODES {
            if let Some(ssd) = try_mode(mode, 0, &mut best, &mut best_ssd) {
                if (V_PRED..=D67_PRED).contains(&mode) {
                    dir_scores.push((ssd, mode));
                }
            }
        }
        dir_scores.sort_unstable();
        for &(_, mode) in dir_scores.iter().take(2) {
            for delta in angle_delta_candidates(mode, bw.min(bh)) {
                if delta != 0 && delta.abs() <= 1 {
                    try_mode(mode, delta, &mut best, &mut best_ssd);
                }
            }
        }
    } else {
        for mode in 0..INTRA_MODES {
            for delta in angle_delta_candidates(mode, bw.min(bh)) {
                try_mode(mode, delta, &mut best, &mut best_ssd);
            }
        }
    }
    // §5.11.24 gate: Max(Block_Width, Block_Height) <= 32 (the coded
    // y_mode is DC_PRED and this driver never codes palette).
    if bw.max(bh) <= 32 {
        for fim in 0..crate::cdf::INTRA_FILTER_MODES {
            let Some(pred) = predict_filter_intra_from_neighbours(
                fim,
                bw,
                bh,
                &above_ext,
                &left_ext,
                recon.bit_depth,
            ) else {
                continue;
            };
            let ssd = ssd_of(&pred);
            if ssd < best_ssd {
                best_ssd = ssd;
                best = (DC_PRED as u8, 0, Some(fim as u8));
            }
        }
    }
    best
}

/// Joint U+V picker over the 13 §6.10.x modes plus the §7.11.5.3
/// `UV_CFL_PRED` (αU, αV) grid (when `cfl_allowed`) for one `cn × cn`
/// chroma block. One shared `uv_mode` per §5.11.22.
#[allow(clippy::too_many_arguments)]
fn pick_uv_mode(
    recon: &ReconState,
    input: &YuvFrame,
    crow0: usize,
    ccol0: usize,
    cbw: usize,
    cbh: usize,
    cfl_allowed: bool,
    // §5.11.43 gate operand: the block's LUMA extent (`Block_Width[
    // MiSize ]`) — angle deltas are coded for `MiSize >= BLOCK_8X8`
    // regardless of the subsampled chroma extent.
    luma_n: usize,
    max_luma_w: usize,
    max_luma_h: usize,
    // r464 — the leaf's luma `(y_mode, angle_delta_y)`: under the
    // pre-screen the chroma shortlist is DC / V / H / SMOOTH / PAETH
    // plus the luma mode at its delta, and the CfL seed ± 1 per axis.
    luma_hint: (u8, i8),
) -> (u8, i8, Option<(i8, i8)>) {
    let pw = recon.chroma_w;
    let (ar_u, bl_u) = tu_corner_avail(&recon.bd, 1, ccol0, crow0, cbw, cbh);
    let (ctile_x0, ctile_y0) = recon.bd.tile_origin_px(1);
    let (above_u, left_u, ha_u, hl_u) = build_tu_neighbours(
        &recon.u,
        recon.chroma_w,
        recon.chroma_h,
        ccol0,
        crow0,
        ctile_x0,
        ctile_y0,
        cbw,
        cbh,
        ar_u,
        bl_u,
        recon.bit_depth,
    );
    let (ar_v, bl_v) = tu_corner_avail(&recon.bd, 2, ccol0, crow0, cbw, cbh);
    let (above_v, left_v, ha_v, hl_v) = build_tu_neighbours(
        &recon.v,
        recon.chroma_w,
        recon.chroma_h,
        ccol0,
        crow0,
        ctile_x0,
        ctile_y0,
        cbw,
        cbh,
        ar_v,
        bl_v,
        recon.bit_depth,
    );
    // r425 — clipped blocks score on-screen chroma only.
    let (caw, cah) = (
        cbw.min(recon.chroma_w - ccol0),
        cbh.min(recon.chroma_h - crow0),
    );
    let ssd_uv = |pred_u: &[u16], pred_v: &[u16]| -> u64 {
        let mut ssd = 0u64;
        for i in 0..cah {
            for j in 0..caw {
                let idx = (crow0 + i) * pw + (ccol0 + j);
                let du = i64::from(input.u[idx]) - i64::from(pred_u[i * cbw + j]);
                let dv = i64::from(input.v[idx]) - i64::from(pred_v[i * cbw + j]);
                ssd += (du * du + dv * dv) as u64;
            }
        }
        ssd
    };
    let mut best_mode = DC_PRED as u8;
    let mut best_delta = 0i8;
    let mut best_alpha: Option<(i8, i8)> = None;
    let mut best_ssd = u64::MAX;
    let mut dc_pred_u: Vec<u16> = Vec::new();
    let mut dc_pred_v: Vec<u16> = Vec::new();
    let try_mode = |mode: usize,
                    delta: i32,
                    best_mode: &mut u8,
                    best_delta: &mut i8,
                    best_alpha: &mut Option<(i8, i8)>,
                    best_ssd: &mut u64,
                    dc_pred_u: &mut Vec<u16>,
                    dc_pred_v: &mut Vec<u16>|
     -> Option<u64> {
        let pred_u = predict_mode_from_neighbours(
            mode,
            delta,
            cbw,
            cbh,
            &above_u,
            &left_u,
            ha_u,
            hl_u,
            recon.bit_depth,
        )?;
        let pred_v = predict_mode_from_neighbours(
            mode,
            delta,
            cbw,
            cbh,
            &above_v,
            &left_v,
            ha_v,
            hl_v,
            recon.bit_depth,
        )?;
        let ssd = ssd_uv(&pred_u, &pred_v);
        if ssd < *best_ssd {
            *best_ssd = ssd;
            *best_mode = mode as u8;
            *best_delta = delta as i8;
            *best_alpha = None;
        }
        if mode == DC_PRED {
            *dc_pred_u = pred_u;
            *dc_pred_v = pred_v;
        }
        Some(ssd)
    };
    if recon.search.intra_mode_prescreen {
        // r464 — the chroma shortlist: DC / V / H / SMOOTH / PAETH at
        // delta 0 plus the luma mode at the luma delta (chroma
        // structure follows luma on photographic content).
        let mut list: Vec<(usize, i32)> = vec![
            (DC_PRED, 0),
            (V_PRED, 0),
            (H_PRED, 0),
            (SMOOTH_PRED, 0),
            (PAETH_PRED, 0),
        ];
        let (ym, yd) = (luma_hint.0 as usize, i32::from(luma_hint.1));
        if ym < INTRA_MODES && !list.contains(&(ym, yd)) {
            let yd = if angle_delta_candidates(ym, luma_n).contains(&yd) {
                yd
            } else {
                0
            };
            if !list.contains(&(ym, yd)) {
                list.push((ym, yd));
            }
        }
        for (mode, delta) in list {
            try_mode(
                mode,
                delta,
                &mut best_mode,
                &mut best_delta,
                &mut best_alpha,
                &mut best_ssd,
                &mut dc_pred_u,
                &mut dc_pred_v,
            );
        }
    } else {
        for mode in 0..INTRA_MODES {
            for delta in angle_delta_candidates(mode, luma_n) {
                try_mode(
                    mode,
                    delta,
                    &mut best_mode,
                    &mut best_delta,
                    &mut best_alpha,
                    &mut best_ssd,
                    &mut dc_pred_u,
                    &mut dc_pred_v,
                );
            }
        }
    }
    if cfl_allowed {
        // r460 — least-squares (αU, αV) seeds: with `pred = dc +
        // Round2Signed(α · ac, 6)` (§7.11.5), the SSD-optimal α per
        // plane is `64 · Σ(res · ac) / Σ(ac²)` over the block; the
        // candidates are each plane's seed ±1 (the neighbouring
        // §5.11.45 alphabet entries), replacing the fixed 20-pair grid
        // that reached no further than |α| = 4.
        let ac = cfl_luma_ac(
            &recon.y,
            recon.width,
            ccol0,
            crow0,
            cbw,
            cbh,
            max_luma_w,
            max_luma_h,
            recon.subsampling_x,
            recon.subsampling_y,
        );
        let seed = |plane_in: &[u16], dc: &[u16]| -> i8 {
            let mut num = 0i128;
            let mut den = 0i128;
            for i in 0..cah {
                for j in 0..caw {
                    let k = i * cbw + j;
                    let r = i64::from(plane_in[(crow0 + i) * pw + (ccol0 + j)]) - i64::from(dc[k]);
                    num += i128::from(r) * i128::from(ac[k]);
                    den += i128::from(ac[k]) * i128::from(ac[k]);
                }
            }
            if den == 0 {
                return 0;
            }
            let a = (64 * num + den.signum() * den / 2) / den;
            a.clamp(-16, 16) as i8
        };
        let (su, sv) = (seed(&input.u, &dc_pred_u), seed(&input.v, &dc_pred_v));
        let around =
            |a: i8| -> [i8; 3] { [a.saturating_sub(1).max(-16), a, a.saturating_add(1).min(16)] };
        let mut cands: Vec<(i8, i8)> = Vec::with_capacity(9);
        if recon.search.intra_mode_prescreen {
            // r464 — the seed and its four axis-aligned neighbours.
            let (ar, av_) = (around(su), around(sv));
            for &(au, av) in &[
                (su, sv),
                (ar[0], sv),
                (ar[2], sv),
                (su, av_[0]),
                (su, av_[2]),
            ] {
                if (au != 0 || av != 0) && !cands.contains(&(au, av)) {
                    cands.push((au, av));
                }
            }
        } else {
            for &au in &around(su) {
                for &av in &around(sv) {
                    if (au != 0 || av != 0) && !cands.contains(&(au, av)) {
                        cands.push((au, av));
                    }
                }
            }
        }
        for &(au, av) in &cands {
            let pred_u = cfl_layer(
                &dc_pred_u,
                &recon.y,
                recon.width,
                ccol0,
                crow0,
                cbw,
                cbh,
                au,
                max_luma_w,
                max_luma_h,
                recon.subsampling_x,
                recon.subsampling_y,
                recon.bit_depth,
            );
            let pred_v = cfl_layer(
                &dc_pred_v,
                &recon.y,
                recon.width,
                ccol0,
                crow0,
                cbw,
                cbh,
                av,
                max_luma_w,
                max_luma_h,
                recon.subsampling_x,
                recon.subsampling_y,
                recon.bit_depth,
            );
            let ssd = ssd_uv(&pred_u, &pred_v);
            if ssd < best_ssd {
                best_ssd = ssd;
                best_mode = UV_CFL_PRED as u8;
                best_delta = 0;
                best_alpha = Some((au, av));
            }
        }
    }
    (best_mode, best_delta, best_alpha)
}

// ---------------------------------------------------------------------
// Leaf encoder (any square block size).
// ---------------------------------------------------------------------

/// §5.11.40 `compute_tx_type` chroma-intra arm: `Mode_To_Txfm[
/// UVMode ]` filtered by the §5.11.48 intra set at the chroma TU size
/// (DCT_DCT fallback when out of set; lossless short-circuits before
/// the table).
fn chroma_tx_type_for(uv_mode: u8, chroma_tx: usize, lossless: bool) -> usize {
    if lossless {
        return DCT_DCT;
    }
    if TX_SIZE_SQR_UP[chroma_tx] > crate::cdf::TX_32X32 {
        return DCT_DCT;
    }
    let t = MODE_TO_TXFM
        .get(uv_mode as usize)
        .copied()
        .unwrap_or(DCT_DCT);
    let set = intra_tx_type_set(
        tx_size_sqr_index(chroma_tx) as u32,
        TX_SIZE_SQR_UP[chroma_tx] as u32,
        false,
    );
    if is_tx_type_in_set(false, set, t) {
        t
    } else {
        DCT_DCT
    }
}

/// Encode one in-frame square leaf at `b_size` (`BLOCK_4X4` …
/// `BLOCK_64X64`). Luma: mode picked on a whole-block prediction,
/// then coded as the §5.11.34 TU grid (`TX_4X4` fan-out on the
/// lossless arm — each TU re-predicted from the running
/// reconstruction with the block mode, exactly like the decode walk —
/// or one `Max_Tx_Size_Rect` TU on the lossy `TX_MODE_LARGEST` arm).
/// Chroma on §5.11.5 `HasChroma` leaves: same shape at the §5.11.38
/// `get_tx_size` chroma TU size, coded after the luma TUs per
/// §5.11.34 plane order (all U TUs, then all V TUs).
pub(crate) fn encode_leaf_sq(
    mi_r: u32,
    mi_c: u32,
    b_size: usize,
    input: &YuvFrame,
    recon: &mut ReconState,
    // r421 — `Some((twin, params))` prices the leaf-level elections
    // (tx-depth ladder, §5.11.46 palette combos, §5.11.7 intra-bc)
    // with exact twin bits; `None` keeps the pre-r421 heuristics.
    pricing: Option<(&RateTwin, &SyntaxFrameParams)>,
) -> Result<SyntaxBlock, Error> {
    encode_leaf_sq_seg(mi_r, mi_c, b_size, input, recon, pricing, None)
}

/// r426 — [`encode_leaf_sq`] with a committed segment id: every
/// candidate leaf carries `segment_override` BEFORE it is priced
/// (skip leaves on segmented INTER frames still take the §5.11.19
/// bit-silent pred cascade afterwards), so the twin prices the
/// §5.11.9 segment symbols and the per-segment
/// `Lossless`/quantiser-derived syntax shape exactly as the write
/// pass will emit them. The caller owns the matching `recon.qp` /
/// `recon.lossless` configuration for the override's segment.
#[allow(clippy::too_many_arguments)]
pub(crate) fn encode_leaf_sq_seg(
    mi_r: u32,
    mi_c: u32,
    b_size: usize,
    input: &YuvFrame,
    recon: &mut ReconState,
    pricing: Option<(&RateTwin, &SyntaxFrameParams)>,
    segment_override: Option<u8>,
) -> Result<SyntaxBlock, Error> {
    // §5.11.46 palette candidates (r418) — only built when the
    // frame-header gate is open and the block is an eligible square.
    // r424: with twin pricing available the k-means proxy ladder
    // surfaces its top TWO per-`k` palettes per plane and the exact
    // full-leaf price (§5.11.46 entries + §5.11.49 tokens + the
    // palette-predicted §5.11.39 residual chain) settles `k`; the
    // heuristic path keeps the single proxy pick.
    let max_pal = if pricing.is_some() { 2 } else { 1 };
    let (pal_y_list, pal_uv_list) = if recon.allow_screen_content_tools {
        (
            palette_candidates_y(input, recon, mi_r, mi_c, b_size, max_pal),
            palette_candidates_uv(input, recon, mi_r, mi_c, b_size, max_pal),
        )
    } else {
        (Vec::new(), Vec::new())
    };
    // §5.11.15: lossless forces TX_4X4; a BLOCK_4X4 block has no
    // tx_depth choice. Otherwise step the luma TX down from
    // `Max_Tx_Size_Rect[MiSize]` via `Split_Tx_Size` (one step for
    // BLOCK_8X8 — its tx_depth alphabet is 2-valued — two for larger
    // squares) and trial-encode the leaf at each size against the
    // same starting state, keeping the lower `D + λ·R`.
    let single_shape = recon.lossless || b_size == BLOCK_4X4;
    let cands: Vec<usize> = if single_shape {
        vec![if recon.lossless {
            TX_4X4
        } else {
            MAX_TX_SIZE_RECT[b_size]
        }]
    } else {
        let max_steps = if b_size == BLOCK_8X8 {
            1.min(recon.search.tx_depth_steps)
        } else {
            MAX_TX_DEPTH.min(recon.search.tx_depth_steps)
        };
        let mut v = vec![MAX_TX_SIZE_RECT[b_size]];
        for _ in 0..max_steps {
            let next = SPLIT_TX_SIZE[*v.last().expect("non-empty")];
            v.push(next);
        }
        v
    };
    // r418: per-TX-shape §5.11.46 palette combinations — every
    // available candidate arm (luma / chroma / both) trials against
    // the plain intra leaf over the same starting state (r424: per-`k`
    // candidates fan out the arms under twin pricing).
    let mut combos: Vec<(Option<&PaletteCandY>, Option<&PaletteCandUv>)> = vec![(None, None)];
    for p in &pal_y_list {
        combos.push((Some(p), None));
    }
    for p in &pal_uv_list {
        combos.push((None, Some(p)));
    }
    for a in &pal_y_list {
        for b in &pal_uv_list {
            combos.push((Some(a), Some(b)));
        }
    }
    // r418 §5.11.7 intra-block-copy candidate — ranked on the pristine
    // pre-trial reconstruction (the ladder below restores it between
    // trials).
    let intrabc_dv = if recon.allow_intrabc
        && matches!(
            b_size,
            BLOCK_8X8 | crate::cdf::BLOCK_16X16 | crate::cdf::BLOCK_32X32 | BLOCK_64X64
        ) {
        intrabc_best_dv(input, recon, mi_r, mi_c, b_size)
    } else {
        None
    };
    // r464 — a one-candidate ladder (one TX shape, no palette / intra-bc
    // arm) needs no pricing: the leaf is taken as coded.
    if (single_shape || cands.len() == 1) && combos.len() == 1 && intrabc_dv.is_none() {
        let mut leaf = encode_leaf_with_tx(
            mi_r, mi_c, b_size, cands[0], input, recon, None, None, pricing,
        )?;
        // r426 — the committed segment rides every candidate before
        // any pricing (see `encode_leaf_sq_seg`).
        if let Some(seg) = segment_override {
            leaf.segment_id = seg;
        }
        // r423 — same §5.11.19 skip-leaf invariant as the ladder
        // below (see `fix_skip_segment`): a segmented caller prices
        // this leaf through the write path next. r426: the §5.11.9
        // `if ( skip ) segment_id = pred` short-circuit is
        // frame-type-agnostic — read_segment_id runs it on the intra
        // §5.11.8 arm too — so segmented KEY frames take the same
        // bit-silent inheritance.
        if let Some((twin, params)) = pricing {
            if params.segmentation_enabled && !params.seg_id_pre_skip && leaf.skip == 1 {
                leaf.segment_id = twin.spatial_segment_pred(mi_r, mi_c);
                // r426 — a lossless pred segment flips the §5.11.15
                // derivation to the bit-silent TX_4X4 default: the
                // skip leaf's tx commitment reverts to `None` (its
                // residual is empty either way).
                if params.lossless_array[leaf.segment_id as usize] {
                    leaf.tx_size = None;
                }
            }
        }
        return Ok(leaf);
    }
    let w4 = NUM_4X4_BLOCKS_WIDE[b_size];
    let h4 = crate::cdf::NUM_4X4_BLOCKS_HIGH[b_size];
    let lambda = lambda_for(&recon.qp);
    // r421 — one election, one rate scale: exact twin bits (1/256-bit
    // units, block syntax only — the partition symbol is constant
    // across every candidate here and cancels) or the pre-r421
    // heuristic. The two scales never mix within a call.
    let rate_of = |leaf: &SyntaxBlock, depth: u64| -> Result<u64, Error> {
        match pricing {
            Some((twin, params)) => twin.price_block(leaf, mi_r, mi_c, b_size, params),
            None => Ok(leaf_rate(leaf) + 2 * depth),
        }
    };
    let score_of = |d: u64, rate: u64| -> u64 {
        match pricing {
            Some(_) => score256(d, lambda, rate),
            None => d + lambda * rate,
        }
    };
    let before = save_region_wh(recon, mi_r, mi_c, w4, h4);
    // r423 — §5.11.19: on a segmented INTER frame a `skip == 1` leaf's
    // segment id is the bit-silent spatial `pred` cascade, and the
    // write path (which prices these candidates through its own
    // emission body) validates the invariant. Trial candidates carry
    // the twin-derived pred BEFORE pricing; the plain-KEY and
    // heuristic paths (no twin, or segmentation off) are untouched —
    // their callers apply the same rule before any pricing runs.
    let fix_skip_segment = |leaf: &mut SyntaxBlock| {
        // r426 — committed segment first (see `encode_leaf_sq_seg`),
        // then the §5.11.19 bit-silent pred on skip leaves.
        if let Some(seg) = segment_override {
            leaf.segment_id = seg;
        }
        if let Some((twin, params)) = pricing {
            if params.segmentation_enabled && !params.seg_id_pre_skip && leaf.skip == 1 {
                leaf.segment_id = twin.spatial_segment_pred(mi_r, mi_c);
                // r426 — lossless pred segment ⇒ bit-silent TX_4X4
                // default (see the single-shape arm above).
                if params.lossless_array[leaf.segment_id as usize] {
                    leaf.tx_size = None;
                }
            }
        }
    };
    // r424 — §5.11.46 signed-delta V-plane arm election (ladder item
    // 5): a UV-palette leaf's V entries code either as direct
    // literals or through the `delta_encode_palette_colors_v` chain;
    // both arms decode to the identical entry values, so under twin
    // pricing the exact-bits smaller arm wins outright. A V list
    // whose deltas the signed-subexp chain cannot represent simply
    // keeps the literal arm (the writer rejects the commitment and
    // the trial is dropped).
    let elect_v_arm = |leaf: &mut SyntaxBlock| -> Result<(), Error> {
        if leaf.palette.size_uv == 0 {
            return Ok(());
        }
        if let Some((twin, params)) = pricing {
            let literal = twin.price_block(leaf, mi_r, mi_c, b_size, params)?;
            let mut alt = leaf.clone();
            alt.palette.delta_encode_v = true;
            if let Ok(delta) = twin.price_block(&alt, mi_r, mi_c, b_size, params) {
                if delta < literal {
                    *leaf = alt;
                }
            }
        }
        Ok(())
    };
    let mut best: Option<(SyntaxBlock, RegionSnapshot, u64)> = None;
    for (depth, &cand) in cands.iter().enumerate() {
        // r464 — TX-size pre-screen: a residual-free leaf at the
        // largest transform size is below the quantiser floor; the
        // split sizes are not trialled (`SearchLimits::tx_split_prescreen`).
        if depth > 0
            && recon.search.tx_split_prescreen
            && best.as_ref().is_some_and(|(leaf, _, _)| leaf.skip == 1)
        {
            break;
        }
        for &(py, puv) in combos.iter() {
            let mut leaf =
                encode_leaf_with_tx(mi_r, mi_c, b_size, cand, input, recon, py, puv, pricing)?;
            fix_skip_segment(&mut leaf);
            elect_v_arm(&mut leaf)?;
            let d = region_distortion_wh(recon, input, mi_r, mi_c, w4, h4);
            let score = score_of(d, rate_of(&leaf, depth as u64)?);
            let improves = match best.as_ref() {
                Some((_, _, s)) => score < *s,
                None => true,
            };
            if improves {
                best = Some((leaf, save_region_wh(recon, mi_r, mi_c, w4, h4), score));
            }
            restore_region(recon, mi_r, mi_c, &before);
        }
    }
    // r418 §5.11.7 intra-block-copy trial — one fixed-shape candidate
    // against the same starting state.
    if let Some(dv) = intrabc_dv {
        let mut leaf = encode_intrabc_leaf(mi_r, mi_c, b_size, dv, input, recon, pricing)?;
        fix_skip_segment(&mut leaf);
        let d = region_distortion_wh(recon, input, mi_r, mi_c, w4, h4);
        let score = score_of(d, rate_of(&leaf, 0)?);
        let improves = match best.as_ref() {
            Some((_, _, s)) => score < *s,
            None => true,
        };
        if improves {
            best = Some((leaf, save_region_wh(recon, mi_r, mi_c, w4, h4), score));
        }
        restore_region(recon, mi_r, mi_c, &before);
    }
    let (leaf, after, _) = best.expect("at least one tx candidate");
    restore_region(recon, mi_r, mi_c, &after);
    Ok(leaf)
}

/// §5.11.46 luma palette commitment candidate for one square leaf —
/// the colour list (sorted ascending, the §5.11.46 canonical form)
/// plus the §5.11.49 `ColorMapY` (row-major, stride = block width).
#[derive(Debug, Clone)]
pub(crate) struct PaletteCandY {
    /// `2..=PALETTE_COLORS` strictly-ascending colours.
    pub(crate) colors: Vec<u16>,
    /// `n × n` row-major indices into `colors`.
    pub(crate) map: Vec<u8>,
}

/// Build the §5.11.46 luma palette candidate for one square leaf, or
/// `None` when the block is ineligible or not exactly representable.
///
/// Eligibility mirrors the §5.11.46 outer gate on the write side
/// (square `BLOCK_8X8..=BLOCK_64X64`) plus this driver's own
/// restrictions: the block must be fully on-screen (clipped leaves
/// would need the §5.11.49 on-screen bump handling in the map) and
/// carry `2..=PALETTE_COLORS` distinct sample values (r418 scope —
/// exact-representable blocks; quantised palettes for busier blocks
/// are a follow-up arc).
#[cfg(test)]
fn palette_candidate_y(
    input: &YuvFrame,
    recon: &ReconState,
    mi_r: u32,
    mi_c: u32,
    b_size: usize,
) -> Option<PaletteCandY> {
    palette_candidates_y(input, recon, mi_r, mi_c, b_size, 1)
        .into_iter()
        .next()
}

/// r424 — up to `max_cands` §5.11.46 luma palette candidates for one
/// leaf, best proxy score first: the exact-representable arm yields
/// its single zero-distortion palette; the k-means arm yields the
/// proxy ladder's top `max_cands` DISTINCT per-`k` palettes so the
/// caller's exact-bits election (`RateTwin::price_block` over the
/// fully-coded leaf — §5.11.46 entries, §5.11.49 tokens AND the
/// palette-predicted §5.11.39 residual chain) settles the `k` choice
/// the `SSE + λ·entry-cost` proxy used to make alone.
fn palette_candidates_y(
    input: &YuvFrame,
    recon: &ReconState,
    mi_r: u32,
    mi_c: u32,
    b_size: usize,
    max_cands: usize,
) -> Vec<PaletteCandY> {
    use crate::cdf::PALETTE_COLORS;
    // r427 — the palette search stays 8-bit 4:2:0 (the dense 256-bin
    // histogram below indexes by sample value); the general drivers
    // never open the §5.9.5 gate outside that pairing.
    if recon.bit_depth != 8 || recon.subsampling_x != 1 || recon.subsampling_y != 1 {
        return Vec::new();
    }
    // §5.11.46 outer gate — r425: rectangular shapes join the squares
    // (`MiSize >= BLOCK_8X8 && Block_Width <= 64 && Block_Height <=
    // 64`; this driver keeps both dims >= 8 — its rect leaves come
    // from the >= 16 HORZ / VERT arms).
    let bw = NUM_4X4_BLOCKS_WIDE[b_size] * 4;
    let bh = crate::cdf::NUM_4X4_BLOCKS_HIGH[b_size] * 4;
    if !(8..=64).contains(&bw) || !(8..=64).contains(&bh) {
        return Vec::new();
    }
    let (row0, col0) = ((mi_r as usize) * 4, (mi_c as usize) * 4);
    if row0 >= recon.height || col0 >= recon.width {
        return Vec::new();
    }
    // r425 — frame-edge-straddling blocks build over the ACTUAL
    // on-screen sub-rectangle (§5.11.49 codes only its
    // anti-diagonals; the off-screen map is spec-replicated below).
    let os_w = bw.min(recon.width - col0);
    let os_h = bh.min(recon.height - row0);
    let mut hist = [0u32; 256];
    let mut distinct = 0usize;
    for i in 0..os_h {
        let row = &input.y[(row0 + i) * recon.width + col0..][..os_w];
        for &v in row {
            if hist[v as usize] == 0 {
                distinct += 1;
            }
            hist[v as usize] += 1;
        }
    }
    if distinct < 2 {
        return Vec::new();
    }
    let color_lists: Vec<Vec<u16>> = if distinct <= PALETTE_COLORS {
        // Exact-representable block: the distinct values ARE the
        // palette (zero-distortion prediction).
        vec![(0..256u16).filter(|&c| hist[c as usize] > 0).collect()]
    } else if !recon.lossless && distinct <= kmeans_distinct_bound(os_w * os_h) {
        // r418 colour clustering: weighted 1-D k-means over the value
        // histogram with a size-RD pick of `k` (§5.11.46
        // `palette_size` election — each extra colour costs entry
        // bits, each dropped colour costs clustering SSE). r424: the
        // proxy ladder now surfaces its top candidates for the exact
        // election.
        kmeans_palette_1d_candidates(&hist, lambda_for(&recon.qp), max_cands)
    } else {
        return Vec::new();
    };
    color_lists
        .into_iter()
        .filter(|colors| colors.len() >= 2)
        .map(|colors| {
            // Nearest-colour LUT over the present values (identity on
            // the exact arm).
            let mut lut = [0u8; 256];
            for (c, &cnt) in hist.iter().enumerate() {
                if cnt > 0 {
                    let mut best = 0usize;
                    let mut best_d = u32::MAX;
                    for (idx, &pc) in colors.iter().enumerate() {
                        let d = (c as i32 - i32::from(pc)).unsigned_abs();
                        if d < best_d {
                            best_d = d;
                            best = idx;
                        }
                    }
                    lut[c] = best as u8;
                }
            }
            let mut map = vec![0u8; bw * bh];
            for i in 0..os_h {
                let row = &input.y[(row0 + i) * recon.width + col0..][..os_w];
                for (j, &v) in row.iter().enumerate() {
                    map[i * bw + j] = lut[v as usize];
                }
            }
            // §5.11.49 off-screen replication (right columns from the
            // last on-screen column, bottom rows from the last
            // on-screen row) — the decoder's ColorMap fill, so the
            // §7.11.4 prediction of overhanging TUs matches exactly.
            for i in 0..os_h {
                for j in os_w..bw {
                    map[i * bw + j] = map[i * bw + os_w - 1];
                }
            }
            for i in os_h..bh {
                let (head, tail) = map.split_at_mut(i * bw);
                tail[..bw].copy_from_slice(&head[(os_h - 1) * bw..][..bw]);
            }
            PaletteCandY { colors, map }
        })
        .collect()
}

/// Distinct-value bound above which the k-means arm is not attempted
/// (dense texture / noise blocks: a palette cannot win there and the
/// trial would be wasted work).
const KMEANS_MAX_DISTINCT: usize = 64;

/// Density-aware clustering gate: a block only clusters when its
/// distinct-value count is at most one eighth of its sample count
/// (capped at [`KMEANS_MAX_DISTINCT`]) — 8×8 blocks stay on the exact
/// arm, 16×16 admit up to 32 values, 32×32+ up to 64. Denser blocks
/// are texture, not palette territory, and the trial would only slow
/// the search / destabilise elections.
fn kmeans_distinct_bound(samples: usize) -> usize {
    (samples / 8).min(KMEANS_MAX_DISTINCT)
}

/// Weighted 1-D k-means (Lloyd) over a value histogram with a
/// size-RD proxy score of `k ∈ 2..=PALETTE_COLORS`: for each `k`,
/// quantile seeding + 8 Lloyd rounds, scored as `SSE + λ · (10 + 8k)`
/// (the [`leaf_rate`] palette entry cost); every `k`'s converged
/// (rounded, deduped, strictly-ascending) palette is returned
/// best-first, truncated to `max_cands` DISTINCT lists — r424: the
/// caller's exact-bits election picks among them.
fn kmeans_palette_1d_candidates(hist: &[u32; 256], lambda: u64, max_cands: usize) -> Vec<Vec<u16>> {
    use crate::cdf::PALETTE_COLORS;
    let values: Vec<(u32, u32)> = (0..256u32)
        .filter(|&c| hist[c as usize] > 0)
        .map(|c| (c, hist[c as usize]))
        .collect();
    let total: u64 = values.iter().map(|&(_, w)| u64::from(w)).sum();
    let mut scored: Vec<(Vec<u16>, u64)> = Vec::new();
    for k in 2..=PALETTE_COLORS {
        // Quantile seeding over the cumulative distribution.
        let mut centroids: Vec<f64> = Vec::with_capacity(k);
        let mut acc = 0u64;
        let mut vi = 0usize;
        for c in 0..k {
            let target = (total * (2 * c as u64 + 1)) / (2 * k as u64);
            while vi + 1 < values.len() && acc + u64::from(values[vi].1) <= target {
                acc += u64::from(values[vi].1);
                vi += 1;
            }
            centroids.push(f64::from(values[vi].0));
        }
        for _ in 0..8 {
            // Assign + recompute (1-D: nearest centroid).
            let mut sum = vec![0f64; k];
            let mut cnt = vec![0f64; k];
            for &(v, w) in &values {
                let mut bi = 0usize;
                let mut bd = f64::MAX;
                for (i, &c) in centroids.iter().enumerate() {
                    let d = (f64::from(v) - c).abs();
                    if d < bd {
                        bd = d;
                        bi = i;
                    }
                }
                sum[bi] += f64::from(v) * f64::from(w);
                cnt[bi] += f64::from(w);
            }
            for i in 0..k {
                if cnt[i] > 0.0 {
                    centroids[i] = sum[i] / cnt[i];
                }
            }
        }
        // Round, sort, dedupe.
        let mut cols: Vec<u16> = centroids
            .iter()
            .map(|&c| c.round().clamp(0.0, 255.0) as u16)
            .collect();
        cols.sort_unstable();
        cols.dedup();
        if cols.len() < 2 {
            continue;
        }
        // Weighted SSE at the rounded palette + entry-cost RD.
        let mut sse = 0u64;
        for &(v, w) in &values {
            let d = cols
                .iter()
                .map(|&c| (i64::from(v) - i64::from(c)).unsigned_abs())
                .min()
                .unwrap_or(0);
            sse += d * d * u64::from(w);
        }
        let score = sse + lambda * (10 + 8 * cols.len() as u64);
        if !scored.iter().any(|(c, _)| *c == cols) {
            scored.push((cols, score));
        }
    }
    scored.sort_by_key(|&(_, s)| s);
    scored.truncate(max_cands);
    scored.into_iter().map(|(cols, _)| cols).collect()
}

/// §5.11.46 chroma palette commitment candidate for one square leaf —
/// the joint (U, V) colour pairs (U non-strictly ascending — the
/// §5.11.46 post-sort canonical order; V by pair index) plus the
/// §5.11.49 `ColorMapUV` (row-major over the subsampled block).
#[derive(Debug, Clone)]
pub(crate) struct PaletteCandUv {
    /// `2..=PALETTE_COLORS` U colours, non-strictly ascending.
    pub(crate) colors_u: Vec<u16>,
    /// Per-index V partner of each U colour (arbitrary order).
    pub(crate) colors_v: Vec<u16>,
    /// `(n/2) × (n/2)` row-major indices into the pair list.
    pub(crate) map: Vec<u8>,
}

/// r424 — up to `max_cands` §5.11.46 chroma palette candidates, best
/// proxy score first (the chroma twin of [`palette_candidates_y`]):
/// the distinct count is taken over joint (U, V) sample PAIRS of the
/// subsampled block — §5.11.49 codes ONE shared `ColorMapUV` for both
/// chroma planes.
fn palette_candidates_uv(
    input: &YuvFrame,
    recon: &ReconState,
    mi_r: u32,
    mi_c: u32,
    b_size: usize,
    max_cands: usize,
) -> Vec<PaletteCandUv> {
    use crate::cdf::PALETTE_COLORS;
    // r427 — same 8-bit 4:2:0 scope as the luma twin.
    if recon.bit_depth != 8 || recon.subsampling_x != 1 || recon.subsampling_y != 1 {
        return Vec::new();
    }
    // §5.11.46 outer gate — r425: rectangular shapes join the squares
    // (both dims `8..=64` for this driver). Every such leaf has
    // chroma under 4:2:0.
    let bw = NUM_4X4_BLOCKS_WIDE[b_size] * 4;
    let bh = crate::cdf::NUM_4X4_BLOCKS_HIGH[b_size] * 4;
    if !(8..=64).contains(&bw) || !(8..=64).contains(&bh) {
        return Vec::new();
    }
    let (row0, col0) = ((mi_r as usize) * 4, (mi_c as usize) * 4);
    if row0 >= recon.height || col0 >= recon.width {
        return Vec::new();
    }
    let (cbw, cbh) = (bw / 2, bh / 2);
    let (crow0, ccol0) = (row0 / 2, col0 / 2);
    let cw = recon.chroma_w;
    // r425 — clipped blocks build over the on-screen chroma
    // sub-rectangle (see the luma twin).
    let os_cw = cbw.min(cw - ccol0);
    let os_ch = cbh.min(recon.chroma_h - crow0);
    // Distinct joint (U, V) pairs with weights.
    let mut weights: std::collections::BTreeMap<(u16, u16), u32> =
        std::collections::BTreeMap::new();
    for i in 0..os_ch {
        for j in 0..os_cw {
            let off = (crow0 + i) * cw + (ccol0 + j);
            let p = (input.u[off], input.v[off]);
            *weights.entry(p).or_insert(0) += 1;
            if weights.len() > kmeans_distinct_bound(os_cw * os_ch).max(PALETTE_COLORS) {
                return Vec::new();
            }
        }
    }
    if weights.len() < 2 {
        return Vec::new();
    }
    let pair_lists: Vec<Vec<(u16, u16)>> = if weights.len() <= PALETTE_COLORS {
        // Exact-representable chroma block.
        vec![weights.keys().copied().collect()]
    } else if !recon.lossless {
        // r418 colour clustering: weighted 2-D k-means over the joint
        // (U, V) pairs with the size-RD pick of `k` (each pair codes
        // BOTH a U and a V entry — double the entry cost of the luma
        // arm). r424: the proxy ladder surfaces its top candidates
        // for the exact election.
        kmeans_palette_2d_candidates(&weights, lambda_for(&recon.qp), max_cands)
    } else {
        return Vec::new();
    };
    pair_lists
        .into_iter()
        .filter(|pairs| pairs.len() >= 2)
        .map(|mut pairs| {
            // §5.11.46 canonical order: U non-strictly ascending
            // (ties broken by V for determinism — pair order among
            // equal U values is unconstrained by the entry coding).
            pairs.sort_unstable();
            let mut map = vec![0u8; cbw * cbh];
            for i in 0..os_ch {
                for j in 0..os_cw {
                    let off = (crow0 + i) * cw + (ccol0 + j);
                    let p = (i64::from(input.u[off]), i64::from(input.v[off]));
                    // Nearest pair (exact arm: the pair itself).
                    let mut bi = 0usize;
                    let mut bd = i64::MAX;
                    for (idx, &(pu, pv)) in pairs.iter().enumerate() {
                        let d = (p.0 - i64::from(pu)).pow(2) + (p.1 - i64::from(pv)).pow(2);
                        if d < bd {
                            bd = d;
                            bi = idx;
                        }
                    }
                    map[i * cbw + j] = bi as u8;
                }
            }
            // §5.11.49 off-screen replication on the shared UV map.
            for i in 0..os_ch {
                for j in os_cw..cbw {
                    map[i * cbw + j] = map[i * cbw + os_cw - 1];
                }
            }
            for i in os_ch..cbh {
                let (head, tail) = map.split_at_mut(i * cbw);
                tail[..cbw].copy_from_slice(&head[(os_ch - 1) * cbw..][..cbw]);
            }
            PaletteCandUv {
                colors_u: pairs.iter().map(|&(u, _)| u).collect(),
                colors_v: pairs.iter().map(|&(_, v)| v).collect(),
                map,
            }
        })
        .collect()
}

/// Weighted 2-D k-means (Lloyd) over joint (U, V) pair weights with a
/// size-RD pick of `k ∈ 2..=PALETTE_COLORS` — the chroma twin of the
/// 1-D ladder (entry cost doubled: each §5.11.46 UV pair codes a U
/// and a V entry). r424: returns the proxy ladder's top `max_cands`
/// DISTINCT per-`k` centroid-pair lists, best first — the caller's
/// exact-bits election settles the final `k`.
fn kmeans_palette_2d_candidates(
    weights: &std::collections::BTreeMap<(u16, u16), u32>,
    lambda: u64,
    max_cands: usize,
) -> Vec<Vec<(u16, u16)>> {
    use crate::cdf::PALETTE_COLORS;
    let values: Vec<((f64, f64), u32)> = weights
        .iter()
        .map(|(&(u, v), &w)| ((f64::from(u), f64::from(v)), w))
        .collect();
    let total: u64 = values.iter().map(|&(_, w)| u64::from(w)).sum();
    let mut scored: Vec<(Vec<(u16, u16)>, u64)> = Vec::new();
    for k in 2..=PALETTE_COLORS {
        // Seed along the weighted BTreeMap (U-major) order.
        let mut centroids: Vec<(f64, f64)> = Vec::with_capacity(k);
        let mut acc = 0u64;
        let mut vi = 0usize;
        for c in 0..k {
            let target = (total * (2 * c as u64 + 1)) / (2 * k as u64);
            while vi + 1 < values.len() && acc + u64::from(values[vi].1) <= target {
                acc += u64::from(values[vi].1);
                vi += 1;
            }
            centroids.push(values[vi].0);
        }
        for _ in 0..8 {
            let mut sum = vec![(0f64, 0f64); k];
            let mut cnt = vec![0f64; k];
            for &((u, v), w) in &values {
                let mut bi = 0usize;
                let mut bd = f64::MAX;
                for (i, &(cu, cv)) in centroids.iter().enumerate() {
                    let d = (u - cu) * (u - cu) + (v - cv) * (v - cv);
                    if d < bd {
                        bd = d;
                        bi = i;
                    }
                }
                sum[bi].0 += u * f64::from(w);
                sum[bi].1 += v * f64::from(w);
                cnt[bi] += f64::from(w);
            }
            for i in 0..k {
                if cnt[i] > 0.0 {
                    centroids[i] = (sum[i].0 / cnt[i], sum[i].1 / cnt[i]);
                }
            }
        }
        let mut cols: Vec<(u16, u16)> = centroids
            .iter()
            .map(|&(u, v)| {
                (
                    u.round().clamp(0.0, 255.0) as u16,
                    v.round().clamp(0.0, 255.0) as u16,
                )
            })
            .collect();
        cols.sort_unstable();
        cols.dedup();
        if cols.len() < 2 {
            continue;
        }
        let mut sse = 0u64;
        for &((u, v), w) in &values {
            let d = cols
                .iter()
                .map(|&(cu, cv)| {
                    let du = (u - f64::from(cu)).abs() as u64;
                    let dv = (v - f64::from(cv)).abs() as u64;
                    du * du + dv * dv
                })
                .min()
                .unwrap_or(0);
            sse += d * u64::from(w);
        }
        let score = sse + lambda * (10 + 16 * cols.len() as u64);
        if !scored.iter().any(|(c, _)| *c == cols) {
            scored.push((cols, score));
        }
    }
    scored.sort_by_key(|&(_, s)| s);
    scored.truncate(max_cands);
    scored.into_iter().map(|(cols, _)| cols).collect()
}

// ---------------------------------------------------------------------
// r418 §5.11.7 intra-block-copy search.
// ---------------------------------------------------------------------

/// §6.10.24 `is_mv_valid` with `use_intrabc = 1` — the DV validity
/// predicate for this single-tile driver (`MiRowStart = MiColStart =
/// 0`, `MiRowEnd = mi_rows`, `MiColEnd = mi_cols`, 64×64 superblocks).
/// `dv_r` / `dv_c` are whole-pel; this driver additionally restricts
/// them to EVEN values so the 4:2:0 chroma copy stays integer-aligned
/// (candidate generation only emits even offsets).
///
/// Spec walk: integer alignment (`force_integer_mv = 1` on intra
/// frames), source rectangle inside the tile, the
/// `INTRABC_DELAY_SB64 = 4` raster-delay guard, and the wavefront
/// guard with `gradient = 1 + INTRABC_DELAY_SB64 +
/// use_128x128_superblock = 5`.
pub(crate) fn intrabc_dv_valid(
    mi_r: u32,
    mi_c: u32,
    b_size: usize,
    dv_r: i32,
    dv_c: i32,
    mi_rows: u32,
    mi_cols: u32,
) -> bool {
    const INTRABC_DELAY_SB64: i64 = 4;
    let bw = (NUM_4X4_BLOCKS_WIDE[b_size] * 4) as i64;
    let bh = bw; // square driver shapes only
                 // §6.10.24 magnitude bound: |Mv| < 1 << 14 in 1/8-pel units.
    if (i64::from(dv_r) * 8).abs() >= (1 << 14) || (i64::from(dv_c) * 8).abs() >= (1 << 14) {
        return false;
    }
    let src_top = i64::from(mi_r) * 4 + i64::from(dv_r);
    let src_left = i64::from(mi_c) * 4 + i64::from(dv_c);
    let src_bottom = src_top + bh;
    let src_right = src_left + bw;
    // HasChroma sub-8 adjustments never fire: bw, bh >= 8 here.
    if src_top < 0
        || src_left < 0
        || src_bottom > i64::from(mi_rows) * 4
        || src_right > i64::from(mi_cols) * 4
    {
        return false;
    }
    let active_sb_row = (i64::from(mi_r) * 4) / 64;
    let active_sb64_col = (i64::from(mi_c) * 4) >> 6;
    let src_sb_row = (src_bottom - 1) / 64;
    let src_sb64_col = (src_right - 1) >> 6;
    let total_sb64_per_row = ((i64::from(mi_cols) - 1) >> 4) + 1;
    let active_sb64 = active_sb_row * total_sb64_per_row + active_sb64_col;
    let src_sb64 = src_sb_row * total_sb64_per_row + src_sb64_col;
    if src_sb64 >= active_sb64 - INTRABC_DELAY_SB64 {
        return false;
    }
    let gradient = 1 + INTRABC_DELAY_SB64; // + use_128x128_superblock = 0
    let wf_offset = gradient * (active_sb_row - src_sb_row);
    if src_sb_row > active_sb_row
        || src_sb64_col >= active_sb64_col - INTRABC_DELAY_SB64 + wf_offset
    {
        return false;
    }
    true
}

/// Frame-level §5.9.20 gate heuristic — `true` iff a provable
/// §6.10.24-reachable exact copy source exists, on either tier:
///
/// * **r418 superblock tier**: some pair of exact duplicate 64×64
///   tiles (all three planes) where the later can copy the earlier.
/// * **r425 glyph tier**: at least [`INTRABC_GATE_MIN_CELLS`] 16×16
///   grid cells (all three planes, non-flat luma) with an exact
///   earlier duplicate at a §6.10.24-valid displacement, covering at
///   least 1/[`INTRABC_GATE_CELL_FRACTION`] of the grid — repeated
///   glyphs / UI patterns that never align to whole superblocks.
///
/// Content without a provable copy source keeps the gate closed —
/// the per-leaf `use_intrabc` S() is pure overhead there.
fn intrabc_beneficial(input: &YuvFrame) -> bool {
    let (w, h) = (input.width as usize, input.height as usize);
    let cw = w / 2;
    let mi_rows = 2 * ((h as u32 + 7) >> 3);
    let mi_cols = 2 * ((w as u32 + 7) >> 3);
    let fnv = |hash: &mut u64, v: u16| {
        *hash ^= u64::from(v);
        *hash = hash.wrapping_mul(0x0000_0100_0000_01B3);
    };

    // --- r418 superblock tier. ---
    let (sb_rows, sb_cols) = (h / 64, w / 64);
    if sb_rows * sb_cols >= 2 {
        let mut tiles: Vec<(usize, usize, u64)> = Vec::new();
        for sbr in 0..sb_rows {
            for sbc in 0..sb_cols {
                let mut hash = 0xcbf2_9ce4_8422_2325u64;
                for i in 0..64 {
                    for j in 0..64 {
                        fnv(&mut hash, input.y[(sbr * 64 + i) * w + sbc * 64 + j]);
                    }
                }
                for i in 0..32 {
                    for j in 0..32 {
                        let off = (sbr * 32 + i) * cw + sbc * 32 + j;
                        fnv(&mut hash, input.u[off]);
                        fnv(&mut hash, input.v[off]);
                    }
                }
                tiles.push((sbr, sbc, hash));
            }
        }
        for (i, &(r1, c1, h1)) in tiles.iter().enumerate() {
            for &(r0, c0, h0) in &tiles[..i] {
                if h0 == h1
                    && intrabc_dv_valid(
                        (r1 * 16) as u32,
                        (c1 * 16) as u32,
                        BLOCK_64X64,
                        (r0 as i32 - r1 as i32) * 64,
                        (c0 as i32 - c1 as i32) * 64,
                        mi_rows,
                        mi_cols,
                    )
                {
                    return true;
                }
            }
        }
    }

    // --- r425 glyph tier: 16×16 grid cells. ---
    let (cell_rows, cell_cols) = (h / 16, w / 16);
    let total_cells = cell_rows * cell_cols;
    if total_cells < 2 * INTRABC_GATE_MIN_CELLS {
        return false;
    }
    let mut buckets: std::collections::HashMap<u64, Vec<(usize, usize)>> =
        std::collections::HashMap::new();
    let mut matched = 0usize;
    for cr in 0..cell_rows {
        for cc in 0..cell_cols {
            let (py, px) = (cr * 16, cc * 16);
            let first = input.y[py * w + px];
            let mut flat = true;
            let mut hash = 0xcbf2_9ce4_8422_2325u64;
            for i in 0..16 {
                for j in 0..16 {
                    let v = input.y[(py + i) * w + px + j];
                    flat &= v == first;
                    fnv(&mut hash, v);
                }
            }
            if flat {
                continue;
            }
            for i in 0..8 {
                for j in 0..8 {
                    let off = (py / 2 + i) * cw + px / 2 + j;
                    fnv(&mut hash, input.u[off]);
                    fnv(&mut hash, input.v[off]);
                }
            }
            let bucket = buckets.entry(hash).or_default();
            // Scan a bounded prefix of earlier duplicates for one the
            // §6.10.24 lag admits.
            if bucket.iter().take(16).any(|&(sy, sx)| {
                intrabc_dv_valid(
                    (py / 4) as u32,
                    (px / 4) as u32,
                    crate::cdf::BLOCK_16X16,
                    sy as i32 - py as i32,
                    sx as i32 - px as i32,
                    mi_rows,
                    mi_cols,
                )
            }) {
                matched += 1;
            }
            bucket.push((py, px));
        }
    }
    matched >= INTRABC_GATE_MIN_CELLS && matched * INTRABC_GATE_CELL_FRACTION >= total_cells
}

/// r425 glyph-tier gate floor: fewer provable copies than this can't
/// amortise the frame-wide `use_intrabc` flag overhead.
const INTRABC_GATE_MIN_CELLS: usize = 4;

/// r425 glyph-tier gate density: matched cells must cover at least
/// `1 / INTRABC_GATE_CELL_FRACTION` of the 16×16 grid.
const INTRABC_GATE_CELL_FRACTION: usize = 64;

/// Pick the best §5.11.7 DV candidate for one square leaf by luma SSD
/// of the reconstruction copy against the input block, over a bounded
/// even-offset candidate set (multiples of the superblock stride and
/// of the block extent, leftward / upward / diagonal). Returns `None`
/// when no candidate passes §6.10.24 validity.
fn intrabc_best_dv(
    input: &YuvFrame,
    recon: &ReconState,
    mi_r: u32,
    mi_c: u32,
    b_size: usize,
) -> Option<(i32, i32)> {
    let n = NUM_4X4_BLOCKS_WIDE[b_size] * 4;
    let (row0, col0) = ((mi_r as usize) * 4, (mi_c as usize) * 4);
    if row0 + n > recon.height || col0 + n > recon.width {
        return None;
    }
    let mut cands: Vec<(i32, i32)> = Vec::new();
    // r425 — exact-match seeds first: probe the per-frame block-hash
    // index with this block's INPUT samples (nearest sources first —
    // strictly-better ties in the SSD ranking below keep the first,
    // i.e. cheapest-DV, winner; §6.10.24-unreachable seeds fall to
    // the validity check like any other candidate). Uniform blocks
    // skip the probe: DC / palette arms already code them at
    // near-zero cost.
    if let Some(tier) = crate::encoder::dv_hash::dv_hash_size_idx(n) {
        let (hash, uniform) =
            crate::encoder::dv_hash::hash_block_direct(&input.y, recon.width, row0, col0, n);
        if !uniform {
            cands.extend(recon.dv_hash.candidates(hash, tier, row0, col0));
        }
    }
    for k in 1..=3i32 {
        for &(dr, dc) in &[(0, -64 * k), (-64 * k, 0), (-64 * k, -64 * k)] {
            cands.push((dr, dc));
        }
        if n < 64 {
            let s = (n as i32) * k;
            for &(dr, dc) in &[(0, -s), (-s, 0), (-s, -s)] {
                cands.push((dr, dc));
            }
        }
    }
    let mut best: Option<((i32, i32), u64)> = None;
    for (dr, dc) in cands {
        if !intrabc_dv_valid(mi_r, mi_c, b_size, dr, dc, recon.mi_rows, recon.mi_cols) {
            continue;
        }
        let (sr, sc) = ((row0 as i32 + dr) as usize, (col0 as i32 + dc) as usize);
        let mut ssd = 0u64;
        for i in 0..n {
            for j in 0..n {
                let d = i64::from(input.y[(row0 + i) * recon.width + col0 + j])
                    - i64::from(recon.y[(sr + i) * recon.width + sc + j]);
                ssd += (d * d) as u64;
            }
        }
        if best.as_ref().map_or(true, |&(_, s)| ssd < s) {
            best = Some(((dr, dc), ssd));
        }
    }
    best.map(|(dv, _)| dv)
}

/// Encode one square leaf on the §5.11.7 intra-block-copy arm at DV
/// `(dv_r, dv_c)` (whole-pel, even): `is_inter = 1` residual layout —
/// one `Max_Tx_Size_Rect` luma TU on the lossy arm (uniform §5.11.17
/// depth 0, committed as one no-split [`VarTxSyntaxTree`]) or the
/// row-major `TX_4X4` grid on the lossless arm, the §5.11.48 INTER
/// tx-type sets, and the §5.11.40 chroma inheritance. Prediction is
/// the §7.11.3 whole-pel copy from the running reconstruction (the
/// §6.10.24 wavefront guarantee keeps the source strictly before the
/// current superblock neighbourhood, so it cannot alias this leaf).
fn encode_intrabc_leaf(
    mi_r: u32,
    mi_c: u32,
    b_size: usize,
    dv: (i32, i32),
    input: &YuvFrame,
    recon: &mut ReconState,
    // r424 — running per-TU twin fork threading (the intrabc arm
    // prices the §5.11.48 INTER-set candidates exactly like an inter
    // leaf: `is_inter = 1` on the residual layout).
    pricing: Option<(&RateTwin, &SyntaxFrameParams)>,
) -> Result<SyntaxBlock, Error> {
    use crate::cdf::inter_tx_type_set;
    let n = NUM_4X4_BLOCKS_WIDE[b_size] * 4;
    let (row0, col0) = ((mi_r as usize) * 4, (mi_c as usize) * 4);
    let width = recon.width;
    let lossless = recon.lossless;
    let qp = recon.qp;
    let mut tu_fork = match (&pricing, lossless) {
        (Some((twin, _)), false) if !recon.search.tu_proxy_pricing => Some(twin.tu_fork()),
        _ => None,
    };
    let tu_ctx = pricing.map(|(_, params)| TuCtx {
        params,
        mi_row: mi_r,
        mi_col: mi_c,
        mi_size: b_size,
        base_x: col0 as u32,
        base_y: row0 as u32,
        is_inter: true,
        segment_id: 0,
        y_mode: 0,
        use_filter_intra: false,
        filter_intra_mode: None,
    });
    let (dv_r, dv_c) = dv;
    let (src_row0, src_col0) = ((row0 as i32 + dv_r) as usize, (col0 as i32 + dv_c) as usize);

    let luma_tx = if lossless {
        TX_4X4
    } else {
        MAX_TX_SIZE_RECT[b_size]
    };
    let (ltw, lth) = (TX_WIDTH[luma_tx], TX_HEIGHT[luma_tx]);
    let mut residual_quant: Vec<Vec<i32>> = Vec::new();
    let mut luma_tx_types: Vec<u8> = Vec::new();
    let tu_cols = n / ltw;
    let mut tu_type_grid = vec![DCT_DCT as u8; tu_cols * (n / lth)];
    // §5.11.34 luma walk: row-major on the lossless arm; the lossy arm
    // is a single `Max_Tx_Size_Rect` TU (depth 0) — row-major order is
    // the §5.11.36 order for both.
    let mut ty = 0usize;
    while ty < n {
        let mut tx = 0usize;
        while tx < n {
            let (tr, tc) = (row0 + ty, col0 + tx);
            let mut pred = vec![0u16; ltw * lth];
            for i in 0..lth {
                for j in 0..ltw {
                    pred[i * ltw + j] = recon.y[(src_row0 + ty + i) * width + src_col0 + tx + j];
                }
            }
            let (q, tt) = if lossless {
                (
                    residual_tx(
                        &input.y,
                        &mut recon.y,
                        width,
                        tr,
                        tc,
                        luma_tx,
                        &pred,
                        0,
                        lossless,
                        DCT_DCT,
                        &qp,
                    ),
                    DCT_DCT as u8,
                )
            } else {
                crate::encoder::inter_frame::residual_tx_search_luma_inter(
                    &input.y,
                    &mut recon.y,
                    width,
                    tr,
                    tc,
                    luma_tx,
                    &pred,
                    &qp,
                    match (&mut tu_fork, &tu_ctx) {
                        (Some(f), Some(c)) => Some((f, c)),
                        _ => None,
                    },
                )?
            };
            tu_bd_stamp(&mut recon.bd, 0, tc, tr, ltw, lth);
            residual_quant.push(q);
            luma_tx_types.push(tt);
            tu_type_grid[(ty / lth) * tu_cols + tx / ltw] = tt;
            tx += ltw;
        }
        ty += lth;
    }

    // --- Chroma (always `HasChroma` at the square >= 8x8 shapes;
    // r427: subsampling-derived extents — the intrabc election is
    // 8-bit-4:2:0-gated today, but the walk is format-general). ---
    let (ssx, ssy) = (
        u32::from(recon.subsampling_x),
        u32::from(recon.subsampling_y),
    );
    let (cn_w, cn_h) = (n >> ssx, n >> ssy);
    let (crow0, ccol0) = (row0 >> ssy, col0 >> ssx);
    let (csrc_row0, csrc_col0) = (
        ((row0 as i32 + dv_r) >> ssy) as usize,
        ((col0 as i32 + dv_c) >> ssx) as usize,
    );
    let chroma_tx = if lossless {
        TX_4X4
    } else {
        get_tx_size(1, luma_tx, b_size, recon.subsampling_x, recon.subsampling_y).unwrap_or(TX_4X4)
    };
    let (ctw, cth) = (TX_WIDTH[chroma_tx], TX_HEIGHT[chroma_tx]);
    let chroma_set = inter_tx_type_set(
        tx_size_sqr_index(chroma_tx) as u32,
        TX_SIZE_SQR_UP[chroma_tx] as u32,
        false,
    );
    let cw = recon.chroma_w;
    for plane in 1..usize::from(recon.num_planes) {
        let mut ty = 0usize;
        while ty < cn_h {
            let mut tx = 0usize;
            while tx < cn_w {
                let (tr, tc) = (crow0 + ty, ccol0 + tx);
                // §5.11.40 inter-chroma TxType inheritance from the
                // subsampling-lifted luma cell, filtered by the
                // chroma-size inter set.
                let chroma_tt = if lossless || TX_SIZE_SQR_UP[chroma_tx] > crate::cdf::TX_32X32 {
                    DCT_DCT
                } else {
                    let lifted_x = ((tc >> 2) << (2 + ssx)).saturating_sub(col0);
                    let lifted_y = ((tr >> 2) << (2 + ssy)).saturating_sub(row0);
                    let luma_tt =
                        tu_type_grid[(lifted_y / lth) * tu_cols + lifted_x / ltw] as usize;
                    if is_tx_type_in_set(true, chroma_set, luma_tt) {
                        luma_tt
                    } else {
                        DCT_DCT
                    }
                };
                let src_plane: &[u16] = if plane == 1 { &recon.u } else { &recon.v };
                let mut pred = vec![0u16; ctw * cth];
                for i in 0..cth {
                    for j in 0..ctw {
                        pred[i * ctw + j] =
                            src_plane[(csrc_row0 + ty + i) * cw + csrc_col0 + tx + j];
                    }
                }
                let plane_buf = if plane == 1 {
                    &mut recon.u
                } else {
                    &mut recon.v
                };
                let q = residual_tx(
                    if plane == 1 { &input.u } else { &input.v },
                    plane_buf,
                    cw,
                    tr,
                    tc,
                    chroma_tx,
                    &pred,
                    plane as u8,
                    lossless,
                    chroma_tt,
                    &qp,
                );
                tu_bd_stamp(&mut recon.bd, plane, tc, tr, ctw, cth);
                residual_quant.push(q);
                tx += ctw;
            }
            ty += cth;
        }
    }

    let all_zero = residual_quant.iter().all(|tu| tu.iter().all(|&q| q == 0));
    let skip = u8::from(all_zero);
    if all_zero {
        residual_quant.clear();
        luma_tx_types.clear();
    }
    if luma_tx_types.iter().all(|&t| t == DCT_DCT as u8) {
        luma_tx_types.clear();
    }

    let mut block = SyntaxBlock::skip_leaf(0, None);
    block.skip = skip;
    block.intrabc_mv = Some([dv_r * 8, dv_c * 8]);
    block.residual_quant = residual_quant.into();
    block.residual_tx_type = luma_tx_types;
    if !lossless && skip == 0 {
        block.var_tx_trees = vec![crate::encoder::inter_frame::uniform_var_tx_tree(
            MAX_TX_SIZE_RECT[b_size],
            0,
        )];
    }
    Ok(block)
}

/// One-shape leaf encode at a fixed luma TX size — see
/// [`encode_leaf_sq`] for the §5.11.15 TX search wrapper. When
/// `palette_y` is `Some`, the luma plane rides the §5.11.46 palette
/// arm: `y_mode = DC_PRED`, no filter-intra (the §5.11.24 gate closes
/// on `PaletteSizeY > 0`), and every luma TU predicts from the
/// §7.11.4 palette-mapped samples before the coded residual. When
/// `palette_uv` is `Some`, the chroma planes ride the same arm:
/// `uv_mode = DC_PRED` (the §5.11.46 UV gate), no CFL, and every
/// chroma TU predicts from its plane's palette colours through the
/// shared §5.11.49 `ColorMapUV`.
#[allow(clippy::too_many_arguments)]
pub(crate) fn encode_leaf_with_tx(
    mi_r: u32,
    mi_c: u32,
    b_size: usize,
    luma_tx: usize,
    input: &YuvFrame,
    recon: &mut ReconState,
    palette_y: Option<&PaletteCandY>,
    palette_uv: Option<&PaletteCandUv>,
    // r424 — `Some` threads a running per-TU twin fork through the
    // luma residual chain (exact §5.11.47/§5.11.39 candidate pricing
    // — see [`TuFork`]); `None` keeps the magnitude proxy.
    pricing: Option<(&RateTwin, &SyntaxFrameParams)>,
) -> Result<SyntaxBlock, Error> {
    // r425 — rectangular leaves ride the same encoder: all extents
    // split into (bw, bh) / (cbw, cbh).
    let bw = NUM_4X4_BLOCKS_WIDE[b_size] * 4;
    let bh = crate::cdf::NUM_4X4_BLOCKS_HIGH[b_size] * 4;
    let row0 = (mi_r as usize) * 4;
    let col0 = (mi_c as usize) * 4;
    let width = recon.width;
    let lossless = recon.lossless;
    let qp = recon.qp;

    // --- Luma ---
    // §5.11.46 palette arm (r418): the coded `y_mode` is DC_PRED and
    // the §5.11.24 filter-intra gate is closed; the luma prediction is
    // the §7.11.4 palette map instead of a §7.11.2 neighbour mode.
    let (y_mode, angle_delta_y, filter_intra_mode) = match palette_y {
        Some(_) => (DC_PRED as u8, 0i8, None),
        None => pick_y_mode(recon, input, row0, col0, bw, bh),
    };
    // r424 — the running per-TU fork (lossy arm only), armed with the
    // leaf's §8.3.2 `intra_dir` inputs.
    let mut tu_fork = match (&pricing, lossless) {
        (Some((twin, _)), false) if !recon.search.tu_proxy_pricing => Some(twin.tu_fork()),
        _ => None,
    };
    let tu_ctx = pricing.map(|(_, params)| TuCtx {
        params,
        mi_row: mi_r,
        mi_col: mi_c,
        mi_size: b_size,
        base_x: col0 as u32,
        base_y: row0 as u32,
        is_inter: false,
        segment_id: 0,
        y_mode,
        use_filter_intra: filter_intra_mode.is_some(),
        filter_intra_mode,
    });
    // r460 — the pruned §5.11.47 shortlist: DCT_DCT + the mode's
    // `Mode_To_Txfm` default (+ IDTX under screen-content tools).
    let tx_shortlist: Option<Vec<usize>> = recon.search.prune_tx_types.then(|| {
        let mut l = vec![DCT_DCT];
        let default = if palette_y.is_some() || filter_intra_mode.is_some() {
            DCT_DCT
        } else {
            MODE_TO_TXFM
                .get(y_mode as usize)
                .copied()
                .unwrap_or(DCT_DCT)
        };
        if !l.contains(&default) {
            l.push(default);
        }
        if recon.allow_screen_content_tools {
            l.push(crate::cdf::IDTX);
        }
        l
    });
    let (ltw, lth) = (TX_WIDTH[luma_tx], TX_HEIGHT[luma_tx]);
    // r425 — on-screen extent for frame-edge-straddling leaves: the
    // §5.11.35 walk skips TUs whose origin is off-screen and the
    // clip-aware residual legs zero the off-screen samples.
    let os_w = bw.min(width - col0);
    let os_h = bh.min(recon.height - row0);
    let mut residual_quant: Vec<Vec<i32>> = Vec::new();
    let mut luma_tx_types: Vec<u8> = Vec::new();
    let mut ty = 0usize;
    while ty < bh {
        let mut tx = 0usize;
        while tx < bw {
            // §5.11.35 line-13 `startX >= maxX || startY >= maxY`
            // early return — the TU is never coded.
            if ty >= os_h || tx >= os_w {
                tx += ltw;
                continue;
            }
            let (tr, tc) = (row0 + ty, col0 + tx);
            let pred = match palette_y {
                Some(p) => {
                    // §7.11.4 `predict_palette` over this TU's
                    // footprint: map indices → palette colours.
                    let mut buf = vec![0u16; ltw * lth];
                    for i in 0..lth {
                        for j in 0..ltw {
                            let idx = p.map[(ty + i) * bw + (tx + j)] as usize;
                            buf[i * ltw + j] = p.colors[idx];
                        }
                    }
                    buf
                }
                None => predict_tu(
                    recon,
                    0,
                    tc,
                    tr,
                    ltw,
                    lth,
                    y_mode as usize,
                    angle_delta_y as i32,
                    filter_intra_mode.map(|f| f as usize),
                ),
            };
            let (q, tt) = if lossless {
                (
                    residual_tx_avail(
                        &input.y,
                        &mut recon.y,
                        width,
                        tr,
                        tc,
                        luma_tx,
                        &pred,
                        0,
                        lossless,
                        DCT_DCT,
                        &qp,
                        os_w - tx,
                        os_h - ty,
                        crate::encoder::forward_quantize::QUANT_ROUND_HALF,
                    ),
                    DCT_DCT as u8,
                )
            } else {
                // r410: §5.11.47 per-TU luma transform-type RD search
                // over the §5.11.48 intra set for this TX size (r424:
                // exact chain pricing through the running fork).
                residual_tx_search_luma_avail(
                    &input.y,
                    &mut recon.y,
                    width,
                    tr,
                    tc,
                    luma_tx,
                    &pred,
                    &qp,
                    match (&mut tu_fork, &tu_ctx) {
                        (Some(f), Some(c)) => Some((f, c)),
                        _ => None,
                    },
                    os_w - tx,
                    os_h - ty,
                    tx_shortlist.as_deref(),
                    recon.search.quant_round_64,
                )?
            };
            tu_bd_stamp(&mut recon.bd, 0, tc, tr, ltw, lth);
            residual_quant.push(q);
            luma_tx_types.push(tt);
            tx += ltw;
        }
        ty += lth;
    }

    // --- Chroma on §5.11.5 HasChroma leaves ---
    // r427 general derivation (the §5.11.5 prologue): a `bw4 == 1` /
    // `bh4 == 1` block on a subsampled axis only carries chroma from
    // its odd mi coordinate (the last cell covering the chroma unit);
    // monochrome never has chroma. Under 4:2:0 this reduces to the
    // historical "BLOCK_4X4 needs both coords odd" rule.
    let bw4 = NUM_4X4_BLOCKS_WIDE[b_size] as u32;
    let bh4 = crate::cdf::NUM_4X4_BLOCKS_HIGH[b_size] as u32;
    let chroma_y_edge = bh4 == 1 && recon.subsampling_y != 0 && (mi_r & 1) == 0;
    let chroma_x_edge = bw4 == 1 && recon.subsampling_x != 0 && (mi_c & 1) == 0;
    let has_chroma = recon.num_planes > 1 && !chroma_y_edge && !chroma_x_edge;
    let mut uv_mode: Option<u8> = None;
    let mut angle_delta_uv = 0i8;
    let mut cfl_alpha: Option<(i8, i8)> = None;
    if has_chroma {
        let (crow0, ccol0) = recon.chroma_origin(mi_r, mi_c);
        // §5.11.35 MaxLumaW / MaxLumaH: the block's own luma extent
        // (the last luma TU coded above ends the block).
        let max_luma_w = col0 + bw;
        let max_luma_h = row0 + bh;
        // §5.11.38 chroma residual block for this leaf.
        let plane_sz = crate::cdf::get_plane_residual_size(
            b_size,
            1,
            recon.subsampling_x,
            recon.subsampling_y,
        )
        .unwrap_or(BLOCK_4X4);
        // §8.3.2 cfl_allowed: on the lossless arm CFL is only allowed
        // when the subsampled chroma residual block is 4×4
        // (`get_plane_residual_size(MiSize, 1) == BLOCK_4X4`); on the
        // lossy arm `Max(Block_Width, Block_Height) <= 32`. r425:
        // this driver additionally keeps CFL off frame-edge-clipped
        // leaves (an encoder choice — the §7.11.5 luma-average region
        // interacts with the visited-TU extent there, and the palette
        // / directional arms carry the clipped shapes).
        let cfl_allowed = if os_w < bw || os_h < bh {
            false
        } else if lossless {
            plane_sz == BLOCK_4X4
        } else {
            bw.max(bh) <= 32
        };
        let chroma_tx = if lossless {
            TX_4X4
        } else {
            get_tx_size(1, luma_tx, b_size, recon.subsampling_x, recon.subsampling_y)
                .unwrap_or(TX_4X4)
        };
        let (ctw, cth) = (TX_WIDTH[chroma_tx], TX_HEIGHT[chroma_tx]);
        // Chroma extent of this leaf's residual grid (§5.11.38
        // subsampled plane size — sub-subsampled shapes round up to
        // the 4×4 floor).
        let cbw = NUM_4X4_BLOCKS_WIDE[plane_sz] * 4;
        let cbh = crate::cdf::NUM_4X4_BLOCKS_HIGH[plane_sz] * 4;
        // §5.11.46 UV palette arm (r418): the coded `uv_mode` is
        // DC_PRED (the UV palette gate) and CFL is off; each chroma
        // TU predicts from the §7.11.4 palette map instead.
        let (m, delta_uv, alpha) = match palette_uv {
            Some(_) => (DC_PRED as u8, 0i8, None),
            None => pick_uv_mode(
                recon,
                input,
                crow0,
                ccol0,
                cbw,
                cbh,
                cfl_allowed,
                bw.min(bh),
                max_luma_w,
                max_luma_h,
                (y_mode, angle_delta_y),
            ),
        };
        uv_mode = Some(m);
        angle_delta_uv = delta_uv;
        cfl_alpha = alpha;
        let is_cfl = m as usize == UV_CFL_PRED;
        let chroma_tx_type = chroma_tx_type_for(m, chroma_tx, lossless);
        let cw = recon.chroma_w;
        for plane in 1..usize::from(recon.num_planes) {
            let alpha_p = match (is_cfl, plane, alpha) {
                (true, 1, Some((au, _))) => Some(au),
                (true, 2, Some((_, av))) => Some(av),
                _ => None,
            };
            // r425 — on-screen chroma extent (clipped leaves).
            let os_cw = cbw.min(cw - ccol0);
            let os_ch = cbh.min(recon.chroma_h - crow0);
            let mut ty = 0usize;
            while ty < cbh {
                let mut tx = 0usize;
                while tx < cbw {
                    // §5.11.35 off-screen-origin skip (chroma maxX /
                    // maxY are the subsampled plane bounds).
                    if ty >= os_ch || tx >= os_cw {
                        tx += ctw;
                        continue;
                    }
                    let (tr, tc) = (crow0 + ty, ccol0 + tx);
                    // §5.11.35: a CFL chroma TU writes the DC_PRED
                    // base, then §7.11.5 layers the luma AC on top.
                    let pred = if let Some(p) = palette_uv {
                        // §7.11.4 `predict_palette` over this TU's
                        // footprint on the shared `ColorMapUV`.
                        let colors = if plane == 1 { &p.colors_u } else { &p.colors_v };
                        let mut buf = vec![0u16; ctw * cth];
                        for i in 0..cth {
                            for j in 0..ctw {
                                let idx = p.map[(ty + i) * cbw + (tx + j)] as usize;
                                buf[i * ctw + j] = colors[idx];
                            }
                        }
                        buf
                    } else if is_cfl {
                        let dc = predict_tu(recon, plane, tc, tr, ctw, cth, DC_PRED, 0, None);
                        cfl_layer(
                            &dc,
                            &recon.y,
                            recon.width,
                            tc,
                            tr,
                            ctw,
                            cth,
                            alpha_p.unwrap_or(0),
                            max_luma_w,
                            max_luma_h,
                            recon.subsampling_x,
                            recon.subsampling_y,
                            recon.bit_depth,
                        )
                    } else {
                        predict_tu(
                            recon,
                            plane,
                            tc,
                            tr,
                            ctw,
                            cth,
                            m as usize,
                            delta_uv as i32,
                            None,
                        )
                    };
                    let plane_buf = if plane == 1 {
                        &mut recon.u
                    } else {
                        &mut recon.v
                    };
                    let q = residual_tx_avail(
                        if plane == 1 { &input.u } else { &input.v },
                        plane_buf,
                        cw,
                        tr,
                        tc,
                        chroma_tx,
                        &pred,
                        plane as u8,
                        lossless,
                        chroma_tx_type,
                        &qp,
                        os_cw - tx,
                        os_ch - ty,
                        recon.search.quant_round_64,
                    );
                    tu_bd_stamp(&mut recon.bd, plane, tc, tr, ctw, cth);
                    residual_quant.push(q);
                    tx += ctw;
                }
                ty += cth;
            }
        }
    }

    // §5.11.11 skip: 1 iff every visited TU quantised to zero — the
    // reconstruction is then the bare prediction on every plane (the
    // dequant + inverse of an all-zero Quant[] is exactly zero, so the
    // stitches above already equal pred).
    let all_zero = residual_quant.iter().all(|tu| tu.iter().all(|&q| q == 0));
    let skip = u8::from(all_zero);
    if all_zero {
        residual_quant.clear();
        // §5.11.47 commitments are per-visited-luma-TU on the `!skip`
        // arm only — a skip leaf must commit none.
        luma_tx_types.clear();
    }
    // An all-DCT_DCT vector is the writer's back-compat default —
    // commit the compact empty form then (keeps the lossless arm's
    // emitted bytes identical to r409).
    if luma_tx_types.iter().all(|&t| t == DCT_DCT as u8) {
        luma_tx_types.clear();
    }
    let (cfl_alpha_u, cfl_alpha_v) = match cfl_alpha {
        Some((au, av)) => (Some(au), Some(av)),
        None => (None, None),
    };
    // §5.11.46 / §5.11.49 palette commitments (r418).
    let mut palette = crate::encoder::partition_tree::SyntaxPalette::default();
    if let Some(p) = palette_y {
        palette.size_y = p.colors.len() as u8;
        palette.colors_y[..p.colors.len()].copy_from_slice(&p.colors);
        palette.color_map_y = p.map.clone();
    }
    if let Some(p) = palette_uv {
        palette.size_uv = p.colors_u.len() as u8;
        palette.colors_u[..p.colors_u.len()].copy_from_slice(&p.colors_u);
        palette.colors_v[..p.colors_v.len()].copy_from_slice(&p.colors_v);
        // §5.11.46 V-plane arm: direct literals (r418 scope; the
        // signed-delta arm is an encoder-choice follow-up).
        palette.delta_encode_v = false;
        palette.color_map_uv = p.map.clone();
    }

    Ok(SyntaxBlock {
        skip,
        segment_id: 0,
        cdef_idx: 0,
        reduced_delta_q_index: 0,
        reduced_delta_lf: [0; crate::cdf::FRAME_LF_COUNT],
        intrabc_mv: None,
        y_mode,
        uv_mode,
        angle_delta_y,
        angle_delta_uv,
        cfl_alpha_u,
        cfl_alpha_v,
        use_filter_intra: u8::from(filter_intra_mode.is_some()),
        filter_intra_mode,
        palette,
        residual_quant: residual_quant.into(),
        // §5.11.15 TxSize commitment: on the lossy TX_MODE_SELECT arm
        // the tx_depth S() fires for every MiSize > BLOCK_4X4 block
        // (intra ⇒ allowSelect); lossless / BLOCK_4X4 stay on the
        // spec-forced default (`None`).
        tx_size: if !lossless && b_size > BLOCK_4X4 {
            Some(luma_tx as u8)
        } else {
            None
        },
        residual_tx_type: luma_tx_types,
        var_tx_trees: Vec::new(),
        inter: None,
    })
}

// ---------------------------------------------------------------------
// Rate-distortion partition search.
// ---------------------------------------------------------------------

/// Snapshot of the pixel region one square node covers (its luma
/// square + the collocated chroma squares) plus the §6.10.3
/// `BlockDecoded[]` mirror — the working set a §5.11.4 partition
/// trial saves/restores.
pub(crate) struct RegionSnapshot {
    w: usize,
    h: usize,
    cw: usize,
    ch: usize,
    y: Vec<u16>,
    u: Vec<u16>,
    v: Vec<u16>,
    bd: BlockDecodedMirror,
}

pub(crate) fn save_region(recon: &ReconState, r: u32, c: u32, n4: usize) -> RegionSnapshot {
    save_region_wh(recon, r, c, n4, n4)
}

/// r412 — rectangular twin of [`save_region`] (`w4 × h4` mi units;
/// the square helper delegates here). Chroma rides the same
/// `(r >> 1, c >> 1)` origin derivation, so rect callers keep their
/// mi origins even on both axes (the P-frame HORZ/VERT halves are
/// BLOCK_16X8 and larger, whose half offsets are even).
pub(crate) fn save_region_wh(
    recon: &ReconState,
    r: u32,
    c: u32,
    w4: usize,
    h4: usize,
) -> RegionSnapshot {
    // r425 — frame-edge-straddling nodes snapshot the on-screen
    // intersection only (there is nothing else to save or restore).
    let (row0, col0) = ((r as usize) * 4, (c as usize) * 4);
    let (crow0, ccol0) = recon.chroma_origin(r, c);
    let w = (w4 * 4).min(recon.width - col0);
    let h = (h4 * 4).min(recon.height - row0);
    // r427 — chroma extents at the subsampled shape; monochrome
    // snapshots no chroma.
    let (cw, ch) = if recon.num_planes > 1 {
        (
            ((w4 * 4) >> recon.subsampling_x).min(recon.chroma_w - ccol0),
            ((h4 * 4) >> recon.subsampling_y).min(recon.chroma_h - crow0),
        )
    } else {
        (0, 0)
    };
    let mut y = vec![0u16; w * h];
    let mut u = vec![0u16; cw * ch];
    let mut v = vec![0u16; cw * ch];
    for i in 0..h {
        y[i * w..(i + 1) * w].copy_from_slice(&recon.y[(row0 + i) * recon.width + col0..][..w]);
    }
    for i in 0..ch {
        u[i * cw..(i + 1) * cw]
            .copy_from_slice(&recon.u[(crow0 + i) * recon.chroma_w + ccol0..][..cw]);
        v[i * cw..(i + 1) * cw]
            .copy_from_slice(&recon.v[(crow0 + i) * recon.chroma_w + ccol0..][..cw]);
    }
    RegionSnapshot {
        w,
        h,
        cw,
        ch,
        y,
        u,
        v,
        bd: recon.bd.clone(),
    }
}

pub(crate) fn restore_region(recon: &mut ReconState, r: u32, c: u32, snap: &RegionSnapshot) {
    let (w, h) = (snap.w, snap.h);
    let (cw, ch) = (snap.cw, snap.ch);
    let (row0, col0) = ((r as usize) * 4, (c as usize) * 4);
    let (crow0, ccol0) = recon.chroma_origin(r, c);
    for i in 0..h {
        recon.y[(row0 + i) * recon.width + col0..][..w].copy_from_slice(&snap.y[i * w..][..w]);
    }
    for i in 0..ch {
        recon.u[(crow0 + i) * recon.chroma_w + ccol0..][..cw]
            .copy_from_slice(&snap.u[i * cw..][..cw]);
        recon.v[(crow0 + i) * recon.chroma_w + ccol0..][..cw]
            .copy_from_slice(&snap.v[i * cw..][..cw]);
    }
    recon.bd = snap.bd.clone();
}

/// Distortion (SSD, luma + both chroma cells) of the current
/// reconstruction against the input over one square node's region.
pub(crate) fn region_distortion(
    recon: &ReconState,
    input: &YuvFrame,
    r: u32,
    c: u32,
    n4: usize,
) -> u64 {
    region_distortion_wh(recon, input, r, c, n4, n4)
}

/// r464 — the luma term of [`region_distortion`] alone (the running
/// lower bound of the split arm at the 8×8 level).
pub(crate) fn region_distortion_luma(
    recon: &ReconState,
    input: &YuvFrame,
    r: u32,
    c: u32,
    n4: usize,
) -> u64 {
    let (row0, col0) = ((r as usize) * 4, (c as usize) * 4);
    let w = (n4 * 4).min(recon.width.saturating_sub(col0));
    let h = (n4 * 4).min(recon.height.saturating_sub(row0));
    let mut d = 0u64;
    for i in 0..h {
        let base = (row0 + i) * recon.width + col0;
        for (a, b) in recon.y[base..base + w].iter().zip(&input.y[base..base + w]) {
            let diff = i64::from(*a) - i64::from(*b);
            d += (diff * diff) as u64;
        }
    }
    d
}

/// r412 — rectangular twin of [`region_distortion`].
pub(crate) fn region_distortion_wh(
    recon: &ReconState,
    input: &YuvFrame,
    r: u32,
    c: u32,
    w4: usize,
    h4: usize,
) -> u64 {
    let (row0, col0) = ((r as usize) * 4, (c as usize) * 4);
    let (crow0, ccol0) = recon.chroma_origin(r, c);
    // r425 — straddling nodes score their on-screen intersection.
    let w = (w4 * 4).min(recon.width - col0);
    let h = (h4 * 4).min(recon.height - row0);
    let (cw, ch) = if recon.num_planes > 1 {
        (
            ((w4 * 4) >> recon.subsampling_x).min(recon.chroma_w - ccol0),
            ((h4 * 4) >> recon.subsampling_y).min(recon.chroma_h - crow0),
        )
    } else {
        (0, 0)
    };
    let mut ssd = 0u64;
    for i in 0..h {
        for j in 0..w {
            let idx = (row0 + i) * recon.width + (col0 + j);
            let d = i64::from(recon.y[idx]) - i64::from(input.y[idx]);
            ssd += (d * d) as u64;
        }
    }
    for i in 0..ch {
        for j in 0..cw {
            let idx = (crow0 + i) * recon.chroma_w + (ccol0 + j);
            let du = i64::from(recon.u[idx]) - i64::from(input.u[idx]);
            let dv = i64::from(recon.v[idx]) - i64::from(input.v[idx]);
            ssd += (du * du + dv * dv) as u64;
        }
    }
    ssd
}

/// r427 — §5.11.38 partition-admissibility gate: "It is a
/// requirement of bitstream conformance that
/// `get_plane_residual_size( subSize, 1 )` is not equal to
/// BLOCK_INVALID every time subSize is computed" (the note: UV blocks
/// must keep aspect ratios within 1:4..4:1 — under 4:2:2 every tall
/// luma shape like 32×64 or 4×16 subsamples to an out-of-range chroma
/// shape). The search must never elect such a subSize; monochrome
/// streams compute no chroma size and are unconstrained.
pub(crate) fn chroma_partition_ok(recon: &ReconState, sub_size: usize) -> bool {
    recon.num_planes == 1
        || crate::cdf::get_plane_residual_size(
            sub_size,
            1,
            recon.subsampling_x,
            recon.subsampling_y,
        )
        .is_some()
}

/// q-scaled Lagrange multiplier for the `D + λ·R` decisions. r427:
/// the SSD distortions scale with `2^(2·(BitDepth - 8))` at matched
/// relative error (and so do the squared §7.12.2 step sizes for a
/// given `q_index`), so λ carries the same factor — 8-bit behaviour
/// is bit-identical to the historical constant.
pub(crate) fn lambda_for(qp: &QuantizerParams) -> u64 {
    // r428 — on a §5.9.17 delta-q frame the leaf ladders trade rate
    // against the SUPERBLOCK's own quantiser (`CurrentQIndex`), not
    // the frame's: a refined superblock must value its cheaper
    // distortion at a matching cheaper λ or the ladder just skips
    // (finer steps cost more bits at unchanged λ), and a coarsened
    // one must skip harder. Identity on every non-delta frame
    // (`CurrentQIndex == base_q_idx` there).
    let q = if qp.delta_q_present {
        u64::from(qp.current_q_index)
    } else {
        u64::from(qp.base_q_idx)
    };
    let l8 = 1 + q * q / 32;
    l8 << (2 * u32::from(qp.bit_depth.saturating_sub(8)))
}

/// Crude rate proxy for one leaf: a fixed per-leaf mode/skip cost
/// plus a magnitude-aware per-nonzero-coefficient cost
/// (`3 + bitlength(|q|)` roughly tracks the §5.11.39 base + BR +
/// golomb growth). Deliberately simple — it only has to ORDER the
/// §5.11.4 candidates consistently.
pub(crate) fn leaf_rate(block: &SyntaxBlock) -> u64 {
    let mut rate = 24u64;
    for tu in &block.residual_quant {
        for &(_, q) in tu.nonzeros() {
            rate += 3 + u64::from(32 - q.unsigned_abs().leading_zeros());
        }
    }
    // §5.11.7 intra-block-copy proxy (r418): the `use_intrabc` S()
    // plus an MV-magnitude term for the §5.11.31 `read_mv` cost.
    if let Some(mv) = block.intrabc_mv {
        let mag = |v: i32| u64::from(32 - (v.unsigned_abs() / 8 + 1).leading_zeros());
        rate += 6 + mag(mv[0]) + mag(mv[1]);
    }
    // §5.11.46 / §5.11.49 palette proxy (r418): colour entries at
    // roughly a literal each, plus a transition-weighted map term —
    // the §5.11.49 context coding makes runs nearly free while index
    // changes cost real bits.
    for (size, map) in [
        (block.palette.size_y, &block.palette.color_map_y),
        (block.palette.size_uv, &block.palette.color_map_uv),
    ] {
        if size > 0 {
            rate += 10 + 8 * u64::from(size);
            let mut transitions = 0u64;
            for w in map.windows(2) {
                if w[0] != w[1] {
                    transitions += 1;
                }
            }
            rate += map.len() as u64 / 16 + transitions * 2;
        }
    }
    rate
}

/// Recursive rate proxy over a candidate subtree (each split node adds
/// a small partition-symbol weight).
pub(crate) fn tree_rate(node: &SyntaxNode) -> u64 {
    match node {
        SyntaxNode::Leaf(b) => leaf_rate(b),
        SyntaxNode::Split(children) => 4 + children.iter().map(|c| tree_rate(c)).sum::<u64>(),
        // r412/r413: asymmetric partitions are P-frame-search
        // territory — the KEY driver never builds them.
        SyntaxNode::Horz(blocks) | SyntaxNode::Vert(blocks) => {
            4 + blocks.iter().map(|b| leaf_rate(b)).sum::<u64>()
        }
        SyntaxNode::HorzA(blocks)
        | SyntaxNode::HorzB(blocks)
        | SyntaxNode::VertA(blocks)
        | SyntaxNode::VertB(blocks) => 5 + blocks.iter().map(|b| leaf_rate(b)).sum::<u64>(),
        SyntaxNode::Horz4(blocks) | SyntaxNode::Vert4(blocks) => {
            5 + blocks.iter().map(|b| leaf_rate(b)).sum::<u64>()
        }
    }
}

/// r426 — the KEY frame's exactness-demand configuration: the
/// row-major mi-cell demand mask plus the (validated) lossless
/// segment every demanded leaf commits. On intra frames the §5.11.8
/// `intra_segment_id` is coded for EVERY block — no skip-pred
/// cascade — so a demanded leaf always carries the lossless segment
/// explicitly.
pub(crate) struct KeySegDemand<'a> {
    pub(crate) mask: &'a [bool],
    pub(crate) ll_seg: u8,
}

/// r426 — one KEY-frame leaf with per-segment lossless awareness:
/// a leaf overlapping the demand mask codes on the lossless segment
/// (segment id committed on every candidate BEFORE pricing; the KEY
/// driver's `recon.qp` / `recon.lossless` swapped to the qindex-0
/// configuration for the call), everything else keeps the segment-0
/// frame-quantiser shape.
#[allow(clippy::too_many_arguments)]
fn encode_key_leaf(
    r: u32,
    c: u32,
    b_size: usize,
    input: &YuvFrame,
    recon: &mut ReconState,
    pricing: Option<(&RateTwin, &SyntaxFrameParams)>,
    seg: Option<&KeySegDemand<'_>>,
    dq_units: i32,
) -> Result<SyntaxBlock, Error> {
    let demanded = seg.is_some_and(|d| {
        let bh4 = crate::cdf::NUM_4X4_BLOCKS_HIGH[b_size] as u32;
        let bw4 = NUM_4X4_BLOCKS_WIDE[b_size] as u32;
        let r1 = (r + bh4).min(recon.mi_rows);
        let c1 = (c + bw4).min(recon.mi_cols);
        (r..r1).any(|rr| (c..c1).any(|cc| d.mask[(rr * recon.mi_cols + cc) as usize]))
    });
    let mut out = if !demanded {
        encode_leaf_sq(r, c, b_size, input, recon, pricing)?
    } else {
        let ll_seg = seg.expect("demanded implies seg").ll_seg;
        let saved_qp = recon.qp;
        let saved_lossless = recon.lossless;
        recon.qp = QuantizerParams::neutral(0, recon.bit_depth);
        recon.lossless = true;
        let o = encode_leaf_sq_seg(r, c, b_size, input, recon, pricing, Some(ll_seg));
        recon.qp = saved_qp;
        recon.lossless = saved_lossless;
        o?
    };
    // r431 — the KEY twin of the inter driver's `stamp_delta_q`: the
    // §5.11.2 lifecycle codes the §5.11.13 delta only on the FIRST
    // coded block of the superblock (the twin's pending bit is
    // authoritative — build-time state == write-time state), and a
    // full-superblock skip leaf takes the §5.11.13 short-circuit arm
    // (zero bits; the writer validates the field is 0 there).
    if dq_units != 0 {
        let pending = pricing.is_some_and(|(twin, _)| twin.deltas_pending());
        out.reduced_delta_q_index = if pending && !(b_size == BLOCK_64X64 && out.skip == 1) {
            dq_units
        } else {
            0
        };
    }
    Ok(out)
}

/// Recursive §5.11.4 rate-distortion partition search. At every
/// fully-in-frame square node from `BLOCK_64X64` down to `BLOCK_8X8`,
/// trial-encode the node both as one `PARTITION_NONE` leaf and as a
/// `PARTITION_SPLIT` of four recursively-searched quadrants against
/// the same starting reconstruction (+ `BlockDecoded[]`) state, and
/// keep the lower `D + λ·R` score (ties prefer the leaf — fewer
/// symbols). Nodes straddling the frame edge take the §5.11.4 forced
/// split; out-of-frame quadrants get the short-circuited dummy node.
/// The running reconstruction ends in the winning shape's state.
///
/// r421 — rate is priced by the search-side rate twin: `twin` enters
/// holding the live write state at this node's stream position, every
/// candidate is priced by count-writing its exact symbol sequence
/// through the real write path, and the twin leaves committed to the
/// WINNING shape's symbols (so later nodes price against the adapted
/// CDFs the writer will actually hold). Under
/// [`RateModel::Heuristic`] the twin is still threaded (commits are
/// how the state stays consistent) but scores use the pre-r421
/// proxies — the sweep harnesses A/B the two models. Returns the
/// chosen node plus its exact cost in 1/256-bit units.
#[allow(clippy::too_many_arguments)]
fn build_search_tree(
    r: u32,
    c: u32,
    b_size: usize,
    input: &YuvFrame,
    recon: &mut ReconState,
    twin: &mut RateTwin,
    params: &SyntaxFrameParams,
    model: RateModel,
    seg: Option<&KeySegDemand<'_>>,
    dq_units: i32,
) -> Result<(SyntaxNode, u64), Error> {
    if r >= recon.mi_rows || c >= recon.mi_cols {
        // §5.11.4 line 1 — never inspected by the writer (and never
        // costed: the write pass short-circuits before any symbol).
        return Ok((SyntaxNode::dummy_oob(), 0));
    }
    let n4 = NUM_4X4_BLOCKS_WIDE[b_size] as u32;
    let fully_inside = r + n4 <= recon.mi_rows && c + n4 <= recon.mi_cols;
    // r460 — `min_leaf` stops the fully-inside descent early (edge
    // nodes keep the §5.11.4 forced-split arms).
    if b_size == BLOCK_4X4 || (fully_inside && b_size <= recon.search.min_leaf) {
        let pricing = (model == RateModel::Twin).then_some((&*twin, params));
        let leaf = encode_key_leaf(r, c, b_size, input, recon, pricing, seg, dq_units)?;
        let node = SyntaxNode::Leaf(Box::new(leaf));
        let cost = twin.commit_subtree(&node, r, c, b_size, params)?;
        return Ok((node, cost));
    }
    let half = n4 >> 1;
    let sub = crate::cdf::partition_subsize(crate::cdf::PARTITION_SPLIT, b_size)
        .expect("PARTITION_SPLIT subsize exists for every b_size >= BLOCK_8X8");

    if !fully_inside {
        // §5.11.4 edge arms: a node straddling the frame edge cannot
        // code PARTITION_NONE. The half-straddle cases carry a real
        // choice — `split_or_horz` (hasCols && !hasRows) admits a
        // single clipped HORZ top block, `split_or_vert` (hasRows &&
        // !hasCols) a single clipped VERT left block — which r425
        // elects against the recursive SPLIT under the same scoring
        // as the interior ladder. The bottom-right corner stays the
        // forced no-symbol SPLIT. BLOCK_8X8 keeps the pre-r425 forced
        // split (its rect subs are the sub-8-chroma shapes).
        let has_rows = r + half < recon.mi_rows;
        let has_cols = c + half < recon.mi_cols;
        let lambda = lambda_for(&recon.qp);
        // Twin-model only: the heuristic arm stays the pre-r425
        // forced-split baseline the A/B harnesses measure against.
        let rect_part = if model != RateModel::Twin {
            None
        } else if b_size > BLOCK_8X8 && has_cols && !has_rows {
            Some(crate::cdf::PARTITION_HORZ)
        } else if b_size > BLOCK_8X8 && has_rows && !has_cols {
            Some(crate::cdf::PARTITION_VERT)
        } else {
            None
        };
        let before = save_region_wh(recon, r, c, n4 as usize, n4 as usize);
        let origin = twin.scope(r, c, b_size, params);
        let mut rect_best: Option<(SyntaxNode, RegionSnapshot, u64, TwinScope, u64)> = None;
        if let Some(part) = rect_part {
            if let Some(psub) = crate::cdf::partition_subsize(part, b_size)
                .filter(|&p| chroma_partition_ok(recon, p))
            {
                let mut cost_s = twin.commit_partition_symbol(part, r, c, b_size)?;
                let pricing_s = (model == RateModel::Twin).then_some((&*twin, params));
                let blk = encode_key_leaf(r, c, psub, input, recon, pricing_s, seg, dq_units)?;
                let h_rate = 4 + leaf_rate(&blk);
                cost_s += twin.commit_block(&blk, r, c, psub, params)?;
                let d = region_distortion_wh(recon, input, r, c, n4 as usize, n4 as usize);
                // §5.11.4: the second block of the pair is never
                // coded on the edge arm — the writer ignores the
                // placeholder entry.
                let placeholder = Box::new(SyntaxBlock::skip_leaf(0, None));
                let node = if part == crate::cdf::PARTITION_HORZ {
                    SyntaxNode::Horz([Box::new(blk), placeholder])
                } else {
                    SyntaxNode::Vert([Box::new(blk), placeholder])
                };
                let score = match model {
                    RateModel::Twin => score256(d, lambda, cost_s),
                    RateModel::Heuristic => score256(d, lambda, h_rate * 256),
                };
                rect_best = Some((
                    node,
                    save_region_wh(recon, r, c, n4 as usize, n4 as usize),
                    score,
                    twin.scope(r, c, b_size, params),
                    cost_s,
                ));
                restore_region(recon, r, c, &before);
                twin.restore(&origin);
            }
        }
        // SPLIT arm (forced on the corner case; elected otherwise).
        let mut cost = twin.commit_partition_symbol(crate::cdf::PARTITION_SPLIT, r, c, b_size)?;
        let (nw, c0) =
            build_search_tree(r, c, sub, input, recon, twin, params, model, seg, dq_units)?;
        let (ne, c1) = build_search_tree(
            r,
            c + half,
            sub,
            input,
            recon,
            twin,
            params,
            model,
            seg,
            dq_units,
        )?;
        let (sw, c2) = build_search_tree(
            r + half,
            c,
            sub,
            input,
            recon,
            twin,
            params,
            model,
            seg,
            dq_units,
        )?;
        let (se, c3) = build_search_tree(
            r + half,
            c + half,
            sub,
            input,
            recon,
            twin,
            params,
            model,
            seg,
            dq_units,
        )?;
        cost += c0 + c1 + c2 + c3;
        let children = [Box::new(nw), Box::new(ne), Box::new(sw), Box::new(se)];
        if let Some((node, after, rect_score, twin_s, rect_cost)) = rect_best {
            let d_b = region_distortion_wh(recon, input, r, c, n4 as usize, n4 as usize);
            let r_b = match model {
                RateModel::Twin => cost,
                RateModel::Heuristic => {
                    (children.iter().map(|ch| tree_rate(ch)).sum::<u64>() + 4) * 256
                }
            };
            if rect_score <= score256(d_b, lambda, r_b) {
                restore_region(recon, r, c, &after);
                twin.restore(&twin_s);
                return Ok((node, rect_cost));
            }
        }
        return Ok((SyntaxNode::Split(children), cost));
    }

    let lambda = lambda_for(&recon.qp);
    let before = save_region(recon, r, c, n4 as usize);

    // Candidate A: one PARTITION_NONE leaf (partition symbol + block
    // syntax committed to a twin fork).
    let pricing = (model == RateModel::Twin).then_some((&*twin, params));
    let leaf = encode_key_leaf(r, c, b_size, input, recon, pricing, seg, dq_units)?;
    let leaf_is_skip = leaf.skip == 1;
    let node_a = SyntaxNode::Leaf(Box::new(leaf));
    let d_a = region_distortion(recon, input, r, c, n4 as usize);
    let origin = twin.scope(r, c, b_size, params);
    let cost_a = twin.commit_subtree(&node_a, r, c, b_size, params)?;
    if recon.search.skip_leaf_early_exit && leaf_is_skip {
        // r460 — a residual-free square leaf is kept as is: no split /
        // rect arm is trialled below it.
        return Ok((node_a, cost_a));
    }
    if recon.search.split_early_term_k64 > 0 {
        // r464 — the leaf already codes the node near the quantiser's
        // distortion floor: no finer partition can buy enough `D`
        // back to pay for its symbols. Threshold in units of the luma
        // AC step squared per sample (every plane counted).
        let n = (n4 as u64) * 4;
        let samples = n * n
            + if recon.num_planes > 1 {
                2 * (n >> recon.subsampling_x) * (n >> recon.subsampling_y)
            } else {
                0
            };
        let step = u64::from(crate::cdf::get_ac_quant(&recon.qp, 0, 0).unsigned_abs());
        let thresh = samples * step * step * u64::from(recon.search.split_early_term_k64) / 65536;
        if d_a <= thresh {
            return Ok((node_a, cost_a));
        }
    }
    let twin_a = twin.scope(r, c, b_size, params);
    twin.restore(&origin);
    let after_a = save_region(recon, r, c, n4 as usize);
    restore_region(recon, r, c, &before);
    let score_a = {
        let r_a = match model {
            RateModel::Twin => cost_a,
            RateModel::Heuristic => {
                let lr = match &node_a {
                    SyntaxNode::Leaf(b) => leaf_rate(b),
                    _ => unreachable!("candidate A is always a leaf"),
                };
                lr * 256
            }
        };
        score256(d_a, lambda, r_a)
    };
    // Running best over the non-split candidates (ties prefer the
    // earlier candidate — fewer coded blocks).
    let mut best: (SyntaxNode, RegionSnapshot, u64, TwinScope, u64) =
        (node_a, after_a, score_a, twin_a, cost_a);

    // Candidates A2/A3 (r425): §5.11.4 PARTITION_HORZ / PARTITION_VERT
    // with two INTRA leaves — the rectangular §5.11.46 palette /
    // §7.11.2 shapes. `BLOCK_16X16` and larger (the 8×8 HORZ / VERT
    // arms code 8×4 / 4×8 leaves, whose sub-8 chroma pairing stays
    // out of this driver's scope); Twin model only (the heuristic arm
    // stays the pre-r425 NONE/SPLIT baseline the A/B harnesses
    // measure against). Each shape's second leaf searches against the
    // first leaf's committed twin state, exactly like the emitting
    // pass.
    if model == RateModel::Twin && b_size >= crate::cdf::BLOCK_16X16 && recon.search.rect_partitions
    {
        for part in [crate::cdf::PARTITION_HORZ, crate::cdf::PARTITION_VERT] {
            let Some(psub) = crate::cdf::partition_subsize(part, b_size) else {
                continue;
            };
            // r427 — §5.11.38 admissibility (4:2:2 forbids the tall
            // rect shapes; see `chroma_partition_ok`).
            if !chroma_partition_ok(recon, psub) {
                continue;
            }
            let cells: [(u32, u32); 2] = if part == crate::cdf::PARTITION_HORZ {
                [(r, c), (r + half, c)]
            } else {
                [(r, c), (r, c + half)]
            };
            let mut cost_s = twin.commit_partition_symbol(part, r, c, b_size)?;
            let mut h_rate = 4u64;
            let mut blocks: Vec<SyntaxBlock> = Vec::with_capacity(2);
            for &(rr, cc) in &cells {
                let pricing_s = (model == RateModel::Twin).then_some((&*twin, params));
                let blk = encode_key_leaf(rr, cc, psub, input, recon, pricing_s, seg, dq_units)?;
                h_rate += leaf_rate(&blk);
                cost_s += twin.commit_block(&blk, rr, cc, psub, params)?;
                blocks.push(blk);
            }
            let d = region_distortion(recon, input, r, c, n4 as usize);
            let mut it = blocks.into_iter();
            let pair = [
                Box::new(it.next().expect("two leaves")),
                Box::new(it.next().expect("two leaves")),
            ];
            let node = if part == crate::cdf::PARTITION_HORZ {
                SyntaxNode::Horz(pair)
            } else {
                SyntaxNode::Vert(pair)
            };
            let score = match model {
                RateModel::Twin => score256(d, lambda, cost_s),
                RateModel::Heuristic => score256(d, lambda, h_rate * 256),
            };
            if score < best.2 {
                best = (
                    node,
                    save_region(recon, r, c, n4 as usize),
                    score,
                    twin.scope(r, c, b_size, params),
                    cost_s,
                );
            }
            twin.restore(&origin);
            restore_region(recon, r, c, &before);
        }
    }

    // Candidate B: PARTITION_SPLIT into four recursively-searched
    // quadrants (NW/NE/SW/SE dispatch order — the writer's order),
    // each child searched against the twin state its symbols will
    // actually be written under (SPLIT arm + earlier siblings).
    // r464 — running-cost abort: the quadrants' regions are disjoint
    // and their twin costs add, so the split's final score is at
    // least the partial `D·256 + λ·R` after any prefix of quadrants
    // (`Twin` model: exact costs; the heuristic proxy is summed the
    // same way). Once the partial exceeds the running best, the split
    // cannot win (`best.2 <= score_b` keeps the best on ties) — the
    // remaining quadrants are never searched. Decision-identical to
    // the exhaustive walk.
    let mut cost_b = twin.commit_partition_symbol(crate::cdf::PARTITION_SPLIT, r, c, b_size)?;
    let quadrants = [(r, c), (r, c + half), (r + half, c), (r + half, c + half)];
    let mut children: Vec<Box<SyntaxNode>> = Vec::with_capacity(4);
    let mut partial_d = 0u64;
    let mut partial_rate = 0u64;
    let mut twin_cost = 0u64;
    for (qi, &(qr, qc)) in quadrants.iter().enumerate() {
        let (node, cost) = build_search_tree(
            qr, qc, sub, input, recon, twin, params, model, seg, dq_units,
        )?;
        twin_cost += cost;
        partial_rate += match model {
            RateModel::Twin => cost,
            RateModel::Heuristic => tree_rate(&node) * 256,
        };
        children.push(Box::new(node));
        if qi == 3 {
            break;
        }
        // The quadrants' chroma is final only when each quadrant
        // carries its own chroma (`sub >= BLOCK_8X8`); the four 4×4
        // leaves of an 8×8 node share one chroma block coded by the
        // last of them, so that level bounds on luma alone.
        partial_d += if sub >= BLOCK_8X8 {
            region_distortion(recon, input, qr, qc, half as usize)
        } else {
            region_distortion_luma(recon, input, qr, qc, half as usize)
        };
        let partial_rate_total = match model {
            RateModel::Twin => cost_b + partial_rate,
            RateModel::Heuristic => partial_rate + 4 * 256,
        };
        if best.2 < score256(partial_d, lambda, partial_rate_total) {
            let (node, after, _, twin_best, cost) = best;
            restore_region(recon, r, c, &after);
            twin.restore(&twin_best);
            return Ok((node, cost));
        }
    }
    cost_b += twin_cost;
    let children: [Box<SyntaxNode>; 4] = children
        .try_into()
        .unwrap_or_else(|_| unreachable!("four quadrants searched"));
    let d_b = region_distortion(recon, input, r, c, n4 as usize);

    let r_b = match model {
        RateModel::Twin => cost_b,
        // Heuristic scores scaled by 256 so both models run through
        // the same `score256` comparison with identical decisions to
        // the pre-r421 integer scores.
        RateModel::Heuristic => (children.iter().map(|ch| tree_rate(ch)).sum::<u64>() + 4) * 256,
    };
    let score_b = score256(d_b, lambda, r_b);
    if best.2 <= score_b {
        let (node, after, _, twin_best, cost) = best;
        restore_region(recon, r, c, &after);
        twin.restore(&twin_best);
        Ok((node, cost))
    } else {
        Ok((SyntaxNode::Split(children), cost_b))
    }
}

// ---------------------------------------------------------------------
// r418 §5.11.46 palette-election witnesses.
// ---------------------------------------------------------------------

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

    /// 8-bit view of a `u16` recon plane for byte-comparisons against
    /// the spec driver's 8-bit output surface.
    fn plane8(p: &[u16]) -> Vec<u8> {
        p.iter().map(|&s| s as u8).collect()
    }

    /// r421 — fresh-frame search context (rate twin + frame params)
    /// for driving [`build_search_tree`] directly: §8.3.1 default
    /// CDFs at the recon's quantiser, a whole-frame single-tile write
    /// state, and the KEY driver's frame-scope parameter bundle.
    fn search_ctx_for_tests(recon: &ReconState) -> (RateTwin, SyntaxFrameParams) {
        let writer = SymbolWriter::new(false);
        let mut cdfs = TileCdfContext::new_from_defaults();
        cdfs.init_coeff_cdfs(recon.qp.base_q_idx);
        let state = PartitionSyntaxWriter::new(
            recon.mi_rows,
            recon.mi_cols,
            TileGeometry {
                mi_row_start: 0,
                mi_row_end: recon.mi_rows,
                mi_col_start: 0,
                mi_col_end: recon.mi_cols,
            },
        )
        .expect("test geometry is valid");
        let params = SyntaxFrameParams {
            subsampling_x: 1,
            subsampling_y: 1,
            num_planes: 3,
            seg_id_pre_skip: false,
            segmentation_enabled: false,
            seg_ref_frame: [None; crate::uncompressed_header_tail::MAX_SEGMENTS],
            seg_skip: [false; crate::uncompressed_header_tail::MAX_SEGMENTS],
            seg_globalmv: [false; crate::uncompressed_header_tail::MAX_SEGMENTS],
            last_active_seg_id: 0,
            lossless_array: [recon.lossless; crate::uncompressed_header_tail::MAX_SEGMENTS],
            coded_lossless: recon.lossless,
            enable_cdef: false,
            allow_intrabc: recon.allow_intrabc,
            cdef_bits: 0,
            read_deltas: false,
            use_128x128_superblock: false,
            delta_q_res: 0,
            delta_lf_present: false,
            delta_lf_multi: false,
            mono_chrome: false,
            delta_lf_res: 0,
            allow_screen_content_tools: recon.allow_screen_content_tools,
            enable_filter_intra: true,
            bit_depth: 8,
            tx_mode_select: !recon.lossless,
            quant: recon.qp,
            reduced_tx_set: false,
            inter: None,
        };
        (RateTwin::snapshot(&cdfs, &state, &writer), params)
    }

    /// Deterministic 4-colour dither over the luma plane (xorshift cell
    /// noise) with flat chroma — exactly representable by a §5.11.46
    /// palette on every square leaf, while every §7.11.2 neighbour
    /// mode leaves a large residual.
    fn dither4(w: u32, h: u32, seed: u32) -> YuvFrame {
        const COLORS: [u16; 4] = [16, 80, 160, 240];
        let (wu, hu) = (w as usize, h as usize);
        let mut f = YuvFrame::filled(w, h, 8, ChromaFormat::Yuv420, 128);
        let mut state = 0x1234_5678u32 ^ seed;
        let mut next = move || {
            state ^= state << 13;
            state ^= state >> 17;
            state ^= state << 5;
            state
        };
        for i in 0..hu {
            for j in 0..wu {
                f.y[i * wu + j] = COLORS[(next() & 3) as usize];
            }
        }
        // Chroma: per-2x2-cell checker over two (U, V) pairs — at most
        // four distinct joint pairs per chroma block, sharp cell edges
        // no §7.11.2 mode predicts.
        let (cw, ch) = (wu / 2, hu / 2);
        for i in 0..ch {
            for j in 0..cw {
                let par = ((i / 2) + (j / 2)) & 1;
                f.u[i * cw + j] = if par == 0 { 96 } else { 168 };
                f.v[i * cw + j] = if ((i / 4) & 1) == par { 108 } else { 152 };
            }
        }
        f
    }

    /// r421 — end-to-end rate-twin witness: replicate the driver loop
    /// over a multi-superblock textured frame, sum the per-superblock
    /// committed twin costs, and (a) assert the twin state matches the
    /// live writer state after every superblock (the anti-desync
    /// invariant, here as a hard assert), (b) assert the summed exact
    /// cost predicts the emitted tile payload to within the §8.2.4
    /// termination slack (15 seed bits − 14 dropped trailing zeros ±
    /// byte padding ± 1 fractional bit).
    #[test]
    fn r421_twin_costs_sum_to_writer_emission() {
        let input = dither4(128, 64, 77);
        let (mi_rows, mi_cols) = (16u32, 32u32);
        let mut recon = ReconState {
            y: vec![0u16; 128 * 64],
            u: vec![0u16; 64 * 32],
            v: vec![0u16; 64 * 32],
            width: 128,
            height: 64,
            chroma_w: 64,
            chroma_h: 32,
            mi_rows,
            mi_cols,
            lossless: false,
            allow_screen_content_tools: true,
            allow_intrabc: false,
            qp: QuantizerParams::neutral(60, 8),
            bit_depth: 8,
            subsampling_x: 1,
            subsampling_y: 1,
            num_planes: 3,
            search: SearchLimits::default(),
            bd: BlockDecodedMirror::new(1, 1, 3),
            dv_hash: Default::default(),
        };
        let mut writer = SymbolWriter::new(false);
        let mut cdfs = TileCdfContext::new_from_defaults();
        cdfs.init_coeff_cdfs(60);
        let mut state = PartitionSyntaxWriter::new(
            mi_rows,
            mi_cols,
            TileGeometry {
                mi_row_start: 0,
                mi_row_end: mi_rows,
                mi_col_start: 0,
                mi_col_end: mi_cols,
            },
        )
        .unwrap();
        // Params must mirror the twin's exactly (same object).
        let (_, params) = search_ctx_for_tests(&recon);
        let mut total_cost256 = 0u64;
        for (sb_r, sb_c) in sb_grid_origins(mi_rows, mi_cols) {
            recon.bd.clear_for_sb(sb_r, sb_c, mi_rows, mi_cols);
            state.arm_read_deltas();
            let mut twin = RateTwin::snapshot(&cdfs, &state, &writer);
            twin.arm_read_deltas();
            let (tree, cost) = build_search_tree(
                sb_r,
                sb_c,
                BLOCK_64X64,
                &input,
                &mut recon,
                &mut twin,
                &params,
                RateModel::Twin,
                None,
                0,
            )
            .unwrap();
            total_cost256 += cost;
            write_partition_tree_syntax(
                &mut writer,
                &mut cdfs,
                &mut state,
                &tree,
                sb_r,
                sb_c,
                BLOCK_64X64,
                &params,
            )
            .unwrap();
            assert!(
                twin.matches(&cdfs, &writer),
                "rate twin desynced after superblock ({sb_r},{sb_c})"
            );
        }
        let tile_bits = writer.finish().len() as u64 * 8;
        let predicted_bits = total_cost256 / 256;
        // Emission = 15 seed bits + renorm bits − 14 dropped trailing
        // zeros, padded up to a byte: |emitted − predicted| ≤ 1 + 7 +
        // 1 (fractional accumulation) bits — use 16 for slack.
        assert!(
            tile_bits.abs_diff(predicted_bits) <= 16,
            "twin predicted {predicted_bits} bits, tile payload is {tile_bits} bits"
        );
        // The prediction is meaningful (a real multi-superblock lossy
        // payload, thousands of bits).
        assert!(predicted_bits > 2000, "payload unexpectedly trivial");
    }

    fn count_palette_leaves(node: &SyntaxNode, pal: &mut u32, other: &mut u32) {
        count_palette_leaves_by(node, pal, other, |b| b.palette.size_y > 0)
    }

    fn count_palette_uv_leaves(node: &SyntaxNode, pal: &mut u32, other: &mut u32) {
        count_palette_leaves_by(node, pal, other, |b| b.palette.size_uv > 0)
    }

    fn count_palette_leaves_by(
        node: &SyntaxNode,
        pal: &mut u32,
        other: &mut u32,
        pred: fn(&SyntaxBlock) -> bool,
    ) {
        let leafc = |b: &SyntaxBlock, pal: &mut u32, other: &mut u32| {
            if pred(b) {
                *pal += 1;
            } else {
                *other += 1;
            }
        };
        match node {
            SyntaxNode::Leaf(b) => leafc(b, pal, other),
            SyntaxNode::Split(children) => {
                for ch in children.iter() {
                    count_palette_leaves_by(ch, pal, other, pred);
                }
            }
            rest => {
                for b in rest.asymmetric_blocks().iter() {
                    leafc(b, pal, other);
                }
            }
        }
    }

    /// The §5.11.46 luma palette arm must actually be SELECTED where a
    /// palette predicts exactly and every §7.11.2 mode misses: the
    /// search tree over 4-colour dither content commits
    /// `PaletteSizeY > 0` leaves, the committed colour lists are the
    /// §5.11.46 canonical (strictly ascending) form, and the emitted
    /// stream round-trips byte-exact through the spec driver — on the
    /// lossy AND the lossless arm.
    #[test]
    fn r418_search_selects_luma_palette_on_dither_content() {
        for q in [60u8, 0] {
            let input = dither4(64, 64, 40 + u32::from(q));
            let mut recon = ReconState {
                y: vec![0u16; 64 * 64],
                u: vec![0u16; 32 * 32],
                v: vec![0u16; 32 * 32],
                width: 64,
                height: 64,
                chroma_w: 32,
                chroma_h: 32,
                mi_rows: 16,
                mi_cols: 16,
                lossless: q == 0,
                allow_screen_content_tools: true,
                allow_intrabc: false,
                qp: QuantizerParams::neutral(q, 8),
                bit_depth: 8,
                subsampling_x: 1,
                subsampling_y: 1,
                num_planes: 3,
                search: SearchLimits::default(),
                bd: BlockDecodedMirror::new(1, 1, 3),
                dv_hash: Default::default(),
            };
            recon.bd.clear_for_sb(0, 0, 16, 16);
            let (mut twin, params) = search_ctx_for_tests(&recon);
            let (tree, _) = build_search_tree(
                0,
                0,
                BLOCK_64X64,
                &input,
                &mut recon,
                &mut twin,
                &params,
                RateModel::Twin,
                None,
                0,
            )
            .unwrap();
            let (mut pal, mut other) = (0u32, 0u32);
            count_palette_leaves(&tree, &mut pal, &mut other);
            assert!(
                pal > 0,
                "q={q}: 4-colour dither content must commit PaletteSizeY > 0 leaves \
                 (got PALETTE={pal} OTHER={other})"
            );
            let (mut pal_uv, mut other_uv) = (0u32, 0u32);
            count_palette_uv_leaves(&tree, &mut pal_uv, &mut other_uv);
            assert!(
                pal_uv > 0,
                "q={q}: 2x2-cell chroma checker content must commit PaletteSizeUV > 0 \
                 leaves (got PALETTE_UV={pal_uv} OTHER={other_uv})"
            );
            fn check_sorted(node: &SyntaxNode) {
                let leafc = |b: &SyntaxBlock| {
                    let k = b.palette.size_y as usize;
                    if k > 0 {
                        assert!((2..=PALETTE_COLORS).contains(&k));
                        for i in 1..k {
                            assert!(
                                b.palette.colors_y[i] > b.palette.colors_y[i - 1],
                                "§5.11.46 canonical form: colours strictly ascending"
                            );
                        }
                        assert!(b.palette.color_map_y.iter().all(|&m| (m as usize) < k));
                    }
                    let kuv = b.palette.size_uv as usize;
                    if kuv > 0 {
                        assert!((2..=PALETTE_COLORS).contains(&kuv));
                        for i in 1..kuv {
                            assert!(
                                b.palette.colors_u[i] >= b.palette.colors_u[i - 1],
                                "§5.11.46 canonical form: U colours non-strictly ascending"
                            );
                        }
                        assert!(b.palette.color_map_uv.iter().all(|&m| (m as usize) < kuv));
                    }
                };
                match node {
                    SyntaxNode::Leaf(b) => leafc(b),
                    SyntaxNode::Split(children) => children.iter().for_each(|ch| check_sorted(ch)),
                    rest => rest.asymmetric_blocks().iter().for_each(|b| leafc(b)),
                }
            }
            check_sorted(&tree);

            // Full-stream conformance through the spec driver.
            let enc = encode_key_frame_yuv_with_q(&input, q).unwrap();
            let frames = crate::decoder::decode_av1_spec(&enc.ivf_bytes).unwrap();
            assert_eq!(frames.len(), 1);
            assert_eq!(frames[0].planes[0], plane8(&enc.recon_y), "q={q}: luma");
            assert_eq!(frames[0].planes[1], plane8(&enc.recon_u), "q={q}: U");
            assert_eq!(frames[0].planes[2], plane8(&enc.recon_v), "q={q}: V");
            if q == 0 {
                assert_eq!(enc.recon_y, input.y, "lossless palette arm must be exact");
            }
        }
    }

    /// r424 — the §5.11.46 signed-delta V-plane arm must actually be
    /// ELECTED where it is cheaper: chroma content whose UV-palette V
    /// entries cluster tightly (delta 6 fits the 4-bit minimum-width
    /// delta chain; the direct literal costs the full 8 bits per
    /// entry) must commit `delta_encode_palette_colors_v = 1` on the
    /// UV-palette leaves under exact twin pricing, and the emitted
    /// stream must still round-trip byte-exact through the spec
    /// driver's §5.11.46 delta-arm reader.
    #[test]
    fn r424_search_elects_signed_delta_v_palette_arm() {
        // Luma: 4-colour dither (palette-friendly). Chroma: 2x2-cell
        // checker with a WIDE U spread and a TIGHT V spread.
        let mut input = dither4(64, 64, 91);
        for i in 0..32usize {
            for j in 0..32usize {
                let cell = ((i / 2) + (j / 2)) & 1;
                input.u[i * 32 + j] = if cell == 0 { 64 } else { 192 };
                input.v[i * 32 + j] = if cell == 0 { 100 } else { 106 };
            }
        }
        let mut recon = ReconState {
            y: vec![0u16; 64 * 64],
            u: vec![0u16; 32 * 32],
            v: vec![0u16; 32 * 32],
            width: 64,
            height: 64,
            chroma_w: 32,
            chroma_h: 32,
            mi_rows: 16,
            mi_cols: 16,
            lossless: false,
            allow_screen_content_tools: true,
            allow_intrabc: false,
            qp: QuantizerParams::neutral(60, 8),
            bit_depth: 8,
            subsampling_x: 1,
            subsampling_y: 1,
            num_planes: 3,
            search: SearchLimits::default(),
            bd: BlockDecodedMirror::new(1, 1, 3),
            dv_hash: Default::default(),
        };
        recon.bd.clear_for_sb(0, 0, 16, 16);
        let (mut twin, params) = search_ctx_for_tests(&recon);
        let (tree, _) = build_search_tree(
            0,
            0,
            BLOCK_64X64,
            &input,
            &mut recon,
            &mut twin,
            &params,
            RateModel::Twin,
            None,
            0,
        )
        .unwrap();
        let (mut pal_uv, mut other_uv) = (0u32, 0u32);
        count_palette_uv_leaves(&tree, &mut pal_uv, &mut other_uv);
        assert!(pal_uv > 0, "the checker chroma must commit UV palettes");
        let (mut delta_v, mut literal_v) = (0u32, 0u32);
        count_palette_leaves_by(&tree, &mut delta_v, &mut literal_v, |b| {
            b.palette.size_uv > 0 && b.palette.delta_encode_v
        });
        assert!(
            delta_v > 0,
            "tight V clustering must elect the §5.11.46 signed-delta arm \
             (delta={delta_v} literal-or-other={literal_v})"
        );

        // Full-stream conformance through the spec driver.
        let enc = encode_key_frame_yuv_with_q(&input, 60).unwrap();
        let frames = crate::decoder::decode_av1_spec(&enc.ivf_bytes).unwrap();
        assert_eq!(frames.len(), 1);
        assert_eq!(frames[0].planes[0], plane8(&enc.recon_y), "luma");
        assert_eq!(frames[0].planes[1], plane8(&enc.recon_u), "U");
        assert_eq!(frames[0].planes[2], plane8(&enc.recon_v), "V");
    }

    /// r418 — the §5.11.7 intra-block-copy arm must actually be
    /// SELECTED where a whole-pel copy of already-reconstructed
    /// content is the winner: a 192×192 frame tiled from one 64×64
    /// noise tile (every superblock identical) opens the §5.9.20 gate
    /// through the duplicate-tile scan, the search tree commits
    /// `use_intrabc = 1` leaves at §6.10.24-valid DVs, and the
    /// emitted stream round-trips byte-exact through the spec driver
    /// — on the lossy AND the lossless arm.
    #[test]
    fn r418_search_selects_intrabc_on_tiled_content() {
        // One 64x64 xorshift noise tile, repeated over 3x3 superblocks.
        let mut tile_y = [0u16; 64 * 64];
        let mut tile_u = [0u16; 32 * 32];
        let mut tile_v = [0u16; 32 * 32];
        let mut state = 0x00C0_FFEEu32;
        let mut next = move || {
            state ^= state << 13;
            state ^= state >> 17;
            state ^= state << 5;
            state
        };
        for p in tile_y.iter_mut() {
            *p = (next() & 0xFF) as u16;
        }
        for p in tile_u.iter_mut() {
            *p = (next() & 0xFF) as u16;
        }
        for p in tile_v.iter_mut() {
            *p = (next() & 0xFF) as u16;
        }
        let (w, h) = (192u32, 192u32);
        let mut input = YuvFrame::filled(w, h, 8, ChromaFormat::Yuv420, 0);
        for i in 0..192usize {
            for j in 0..192usize {
                input.y[i * 192 + j] = tile_y[(i % 64) * 64 + (j % 64)];
            }
        }
        for i in 0..96usize {
            for j in 0..96usize {
                input.u[i * 96 + j] = tile_u[(i % 32) * 32 + (j % 32)];
                input.v[i * 96 + j] = tile_v[(i % 32) * 32 + (j % 32)];
            }
        }

        for q in [60u8, 0] {
            let enc = encode_key_frame_yuv_with_q(&input, q).unwrap();
            assert!(
                enc.fh.allow_intrabc,
                "q={q}: duplicate-tile scan must open the §5.9.20 gate"
            );
            // Tree-level witness over the same driver state.
            let mut recon = ReconState {
                y: vec![0u16; 192 * 192],
                u: vec![0u16; 96 * 96],
                v: vec![0u16; 96 * 96],
                width: 192,
                height: 192,
                chroma_w: 96,
                chroma_h: 96,
                mi_rows: 48,
                mi_cols: 48,
                lossless: q == 0,
                allow_screen_content_tools: true,
                allow_intrabc: true,
                qp: QuantizerParams::neutral(q, 8),
                bit_depth: 8,
                subsampling_x: 1,
                subsampling_y: 1,
                num_planes: 3,
                search: SearchLimits::default(),
                bd: BlockDecodedMirror::new(1, 1, 3),
                dv_hash: Default::default(),
            };
            let (mut ibc, mut other) = (0u32, 0u32);
            let (mut twin, params) = search_ctx_for_tests(&recon);
            for (sb_r, sb_c) in sb_grid_origins(48, 48) {
                recon.bd.clear_for_sb(sb_r, sb_c, 48, 48);
                twin.arm_read_deltas();
                let (tree, _) = build_search_tree(
                    sb_r,
                    sb_c,
                    BLOCK_64X64,
                    &input,
                    &mut recon,
                    &mut twin,
                    &params,
                    RateModel::Twin,
                    None,
                    0,
                )
                .unwrap();
                count_palette_leaves_by(&tree, &mut ibc, &mut other, |b| b.intrabc_mv.is_some());
            }
            assert!(
                ibc > 0,
                "q={q}: tiled content must commit use_intrabc = 1 leaves \
                 (got INTRABC={ibc} OTHER={other})"
            );

            // Full-stream conformance through the spec driver.
            let frames = crate::decoder::decode_av1_spec(&enc.ivf_bytes).unwrap();
            assert_eq!(frames.len(), 1);
            assert_eq!(frames[0].planes[0], plane8(&enc.recon_y), "q={q}: luma");
            assert_eq!(frames[0].planes[1], plane8(&enc.recon_u), "q={q}: U");
            assert_eq!(frames[0].planes[2], plane8(&enc.recon_v), "q={q}: V");
            if q == 0 {
                assert_eq!(enc.recon_y, input.y, "lossless intrabc arm must be exact");
                assert_eq!(enc.recon_u, input.u);
                assert_eq!(enc.recon_v, input.v);
            }
        }
    }

    /// r425 — the hash-match DV search must find exact copy sources
    /// the geometric candidate set cannot reach, and the glyph-tier
    /// §5.9.20 gate must open on repeated sub-superblock patterns:
    /// a 256×192 frame with a per-superblock DISTINCT flat background
    /// (no duplicate 64×64 tiles — the r418 tier stays closed) and
    /// one 16×16 noise glyph stamped at four §6.10.24-reachable
    /// destinations whose displacements sit on none of the geometric
    /// strides. The search must commit `use_intrabc = 1` leaves at
    /// exactly those hash-seeded DVs, and the stream must round-trip
    /// byte-exact through the spec driver (whose own §6.10.24
    /// validation re-checks every committed DV).
    #[test]
    fn r425_hash_dv_search_finds_off_stride_glyph_copies() {
        let (w, h) = (256usize, 192usize);
        // Distinct flat background per superblock: kills the r418
        // duplicate-superblock tier AND flat-cell false matches.
        let mut input = YuvFrame::filled(w as u32, h as u32, 8, ChromaFormat::Yuv420, 128);
        for i in 0..h {
            for j in 0..w {
                let sb = (i / 64) * 4 + j / 64;
                input.y[i * w + j] = 60 + 3 * sb as u16;
            }
        }
        // One 16×16 xorshift noise glyph...
        let mut glyph = [0u16; 16 * 16];
        let mut state = 0x0BAD_CAFEu32;
        let mut next = move || {
            state ^= state << 13;
            state ^= state >> 17;
            state ^= state << 5;
            state
        };
        for p in glyph.iter_mut() {
            *p = (next() & 0xFF) as u16;
        }
        // ... stamped at one early source and four late destinations.
        // Sources sit in superblocks 0..=1; every destination's
        // superblock raster index is >= 5, so §6.10.24 admits the
        // copy. None of the displacements is a multiple of the
        // 16-/64-stride geometric candidate set.
        // Destination superblocks (raster 5, 6, 7, 8) all watermark
        // BELOW every other glyph superblock, so (0, 0) is each
        // destination's only reachable source — the committed DVs
        // are fully determined.
        let stamps: [(usize, usize); 5] = [(0, 0), (80, 80), (80, 160), (80, 224), (144, 32)];
        for &(sy, sx) in &stamps {
            for i in 0..16 {
                for j in 0..16 {
                    input.y[(sy + i) * w + sx + j] = glyph[i * 16 + j];
                }
            }
        }
        let expected_dvs: Vec<[i32; 2]> = stamps[1..]
            .iter()
            .map(|&(dy, dx)| [-8 * (dy as i32), -8 * (dx as i32)])
            .collect();

        // Background-only twin: the glyph tier must be what opens the
        // gate (no duplicate superblocks, no duplicate glyph cells).
        let mut bg_only = input.clone();
        for &(sy, sx) in &stamps {
            let sb = (sy / 64) * 4 + sx / 64;
            for i in 0..16 {
                for j in 0..16 {
                    bg_only.y[(sy + i) * w + sx + j] = 60 + 3 * sb as u16;
                }
            }
        }
        assert!(
            !intrabc_beneficial(&bg_only),
            "background alone opens the gate"
        );
        assert!(
            intrabc_beneficial(&input),
            "four reachable glyph duplicates must open the glyph tier"
        );

        for q in [60u8, 0] {
            let enc = encode_key_frame_yuv_with_q(&input, q).unwrap();
            assert!(enc.fh.allow_intrabc, "q={q}: glyph tier gate");

            // Tree-level witness with an armed index, mirroring the
            // driver's staircase maintenance.
            let mut recon = ReconState {
                y: vec![0u16; w * h],
                u: vec![0u16; (w / 2) * (h / 2)],
                v: vec![0u16; (w / 2) * (h / 2)],
                width: w,
                height: h,
                chroma_w: w / 2,
                chroma_h: h / 2,
                mi_rows: (h / 4) as u32,
                mi_cols: (w / 4) as u32,
                lossless: q == 0,
                allow_screen_content_tools: true,
                allow_intrabc: true,
                qp: QuantizerParams::neutral(q, 8),
                bit_depth: 8,
                subsampling_x: 1,
                subsampling_y: 1,
                num_planes: 3,
                search: SearchLimits::default(),
                bd: BlockDecodedMirror::new(1, 1, 3),
                dv_hash: crate::encoder::dv_hash::DvHashIndex::build(&input.y, w, h),
            };
            let (mut twin, params) = search_ctx_for_tests(&recon);
            let mut committed: Vec<[i32; 2]> = Vec::new();
            fn collect_dvs(node: &SyntaxNode, out: &mut Vec<[i32; 2]>) {
                match node {
                    SyntaxNode::Leaf(b) => {
                        if let Some(mv) = b.intrabc_mv {
                            out.push(mv);
                        }
                    }
                    SyntaxNode::Split(ch) => {
                        for c in ch.iter() {
                            collect_dvs(c, out);
                        }
                    }
                    _ => {}
                }
            }
            for (sb_r, sb_c) in sb_grid_origins(recon.mi_rows, recon.mi_cols) {
                recon
                    .bd
                    .clear_for_sb(sb_r, sb_c, recon.mi_rows, recon.mi_cols);
                twin.arm_read_deltas();
                let (tree, _) = build_search_tree(
                    sb_r,
                    sb_c,
                    BLOCK_64X64,
                    &input,
                    &mut recon,
                    &mut twin,
                    &params,
                    RateModel::Twin,
                    None,
                    0,
                )
                .unwrap();
                collect_dvs(&tree, &mut committed);
            }
            for dv in &expected_dvs {
                assert!(
                    committed.contains(dv),
                    "q={q}: hash-seeded DV {dv:?} missing from committed set {committed:?}"
                );
            }

            // Full-stream conformance through the spec driver.
            let frames = crate::decoder::decode_av1_spec(&enc.ivf_bytes).unwrap();
            assert_eq!(frames.len(), 1);
            assert_eq!(frames[0].planes[0], plane8(&enc.recon_y), "q={q}: luma");
            assert_eq!(frames[0].planes[1], plane8(&enc.recon_u), "q={q}: U");
            assert_eq!(frames[0].planes[2], plane8(&enc.recon_v), "q={q}: V");
            if q == 0 {
                assert_eq!(enc.recon_y, input.y, "lossless glyph copies must be exact");
            }
        }
    }

    /// r425 — rectangular §5.11.46 palette leaves: a 64×64 superblock
    /// made of two DIFFERENT 8-colour dither strips (left / right
    /// 32×64, disjoint colour sets) must elect PARTITION_VERT with
    /// palette-coded 32×64 leaves — each strip is exactly
    /// representable at the §5.11.46 cap while the whole block's 16
    /// colours are not, and the VERT pair costs two palette lists /
    /// token walks against the SPLIT arm's four — and the stream must
    /// round-trip byte-exact through the spec driver on the lossy AND
    /// lossless arms. r460 — with the forward-transform gain
    /// corrected, one 64×64 palette of the 16 colours' midpoints plus a
    /// small residual can legitimately undercut two exact palettes, so
    /// the strips sit 16 levels apart (a ±8 residual) and the lossy arm
    /// runs at a fine quantiser (`q = 20`) — the regime where the
    /// residual is not free.
    #[test]
    fn r425_rect_palette_leaf_elected_on_split_content() {
        let (w, h) = (64usize, 64usize);
        const LEFT: [u16; 8] = [16, 48, 80, 112, 144, 176, 208, 240];
        // r460 — the strips sit 16 levels apart (a ±8 residual on any
        // shared 8-colour palette), so the lossy arm cannot fold both
        // into one list plus a free residual.
        const RIGHT: [u16; 8] = [32, 64, 96, 128, 160, 192, 224, 255];
        let mut input = YuvFrame::filled(w as u32, h as u32, 8, ChromaFormat::Yuv420, 128);
        let mut state = 0x5EED_0425u32;
        let mut next = move || {
            state ^= state << 13;
            state ^= state >> 17;
            state ^= state << 5;
            state
        };
        for i in 0..h {
            for j in 0..w {
                let pal = if j < 32 { &LEFT } else { &RIGHT };
                input.y[i * w + j] = pal[(next() & 7) as usize];
            }
        }

        for q in [20u8, 0] {
            let mut recon = ReconState {
                y: vec![0u16; w * h],
                u: vec![0u16; (w / 2) * (h / 2)],
                v: vec![0u16; (w / 2) * (h / 2)],
                width: w,
                height: h,
                chroma_w: w / 2,
                chroma_h: h / 2,
                mi_rows: (h / 4) as u32,
                mi_cols: (w / 4) as u32,
                lossless: q == 0,
                allow_screen_content_tools: true,
                allow_intrabc: false,
                qp: QuantizerParams::neutral(q, 8),
                bit_depth: 8,
                subsampling_x: 1,
                subsampling_y: 1,
                num_planes: 3,
                search: SearchLimits::default(),
                bd: BlockDecodedMirror::new(1, 1, 3),
                dv_hash: Default::default(),
            };
            let (mut twin, params) = search_ctx_for_tests(&recon);
            recon.bd.clear_for_sb(0, 0, recon.mi_rows, recon.mi_cols);
            twin.arm_read_deltas();
            let (tree, _) = build_search_tree(
                0,
                0,
                BLOCK_64X64,
                &input,
                &mut recon,
                &mut twin,
                &params,
                RateModel::Twin,
                None,
                0,
            )
            .unwrap();
            // The winning shape must be a rect node carrying a
            // palette leaf on a non-square block.
            fn find_rect_palette(node: &SyntaxNode) -> bool {
                match node {
                    SyntaxNode::Horz(blocks) | SyntaxNode::Vert(blocks) => {
                        blocks.iter().any(|b| b.palette.size_y > 0)
                    }
                    SyntaxNode::Split(ch) => ch.iter().any(|c| find_rect_palette(c)),
                    _ => false,
                }
            }
            assert!(
                find_rect_palette(&tree),
                "q={q}: split-content superblock must elect a rect palette leaf: {tree:?}"
            );

            // Full-stream conformance through the public API + spec
            // driver (the emitting pass walks the same elected rect
            // shapes).
            let enc = encode_key_frame_yuv_with_q(&input, q).unwrap();
            let frames = crate::decoder::decode_av1_spec(&enc.ivf_bytes).unwrap();
            assert_eq!(frames.len(), 1);
            assert_eq!(frames[0].planes[0], plane8(&enc.recon_y), "q={q}: luma");
            assert_eq!(frames[0].planes[1], plane8(&enc.recon_u), "q={q}: U");
            assert_eq!(frames[0].planes[2], plane8(&enc.recon_v), "q={q}: V");
            if q == 0 {
                assert_eq!(enc.recon_y, input.y, "lossless rect palette must be exact");
            }
        }
    }

    /// r425 — clipped palette leaves on the §5.11.4 `split_or_horz`
    /// edge arm: a 64×80 frame (bottom superblock row straddles the
    /// edge by 48 rows) filled with a 2-colour dither must elect the
    /// single clipped HORZ top block (64×32 coded, 16 rows on-screen)
    /// over the forced-split cascade — one palette list + one
    /// §5.11.49 on-screen-sub-rectangle token walk instead of the
    /// split arm's duplicated pairs — and the stream must round-trip
    /// byte-exact through the spec driver on the lossy AND lossless
    /// arms (the driver's own §5.11.49 reader walks the same
    /// on-screen anti-diagonals).
    #[test]
    fn r425_clipped_palette_leaf_on_bottom_edge() {
        let (w, h) = (64usize, 80usize);
        let mut input = YuvFrame::filled(w as u32, h as u32, 8, ChromaFormat::Yuv420, 128);
        let mut state = 0xC11B_0425u32;
        let mut next = move || {
            state ^= state << 13;
            state ^= state >> 17;
            state ^= state << 5;
            state
        };
        for p in input.y.iter_mut() {
            *p = if next() & 1 == 0 { 40 } else { 200 };
        }

        for q in [60u8, 0] {
            let mut recon = ReconState {
                y: vec![0u16; w * h],
                u: vec![0u16; (w / 2) * (h / 2)],
                v: vec![0u16; (w / 2) * (h / 2)],
                width: w,
                height: h,
                chroma_w: w / 2,
                chroma_h: h / 2,
                mi_rows: (h / 4) as u32,
                mi_cols: (w / 4) as u32,
                lossless: q == 0,
                allow_screen_content_tools: true,
                allow_intrabc: false,
                qp: QuantizerParams::neutral(q, 8),
                bit_depth: 8,
                subsampling_x: 1,
                subsampling_y: 1,
                num_planes: 3,
                search: SearchLimits::default(),
                bd: BlockDecodedMirror::new(1, 1, 3),
                dv_hash: Default::default(),
            };
            let (mut twin, params) = search_ctx_for_tests(&recon);
            let mut found_clipped_palette = false;
            for (sb_r, sb_c) in sb_grid_origins(recon.mi_rows, recon.mi_cols) {
                recon
                    .bd
                    .clear_for_sb(sb_r, sb_c, recon.mi_rows, recon.mi_cols);
                twin.arm_read_deltas();
                let (tree, _) = build_search_tree(
                    sb_r,
                    sb_c,
                    BLOCK_64X64,
                    &input,
                    &mut recon,
                    &mut twin,
                    &params,
                    RateModel::Twin,
                    None,
                    0,
                )
                .unwrap();
                if sb_r == 16 {
                    // The straddling superblock: the elected shape
                    // must be the HORZ edge arm with a palette-coded
                    // clipped top block.
                    if let SyntaxNode::Horz(blocks) = &tree {
                        found_clipped_palette = blocks[0].palette.size_y > 0;
                    }
                }
            }
            assert!(
                found_clipped_palette,
                "q={q}: the straddling superblock must elect a clipped HORZ palette leaf"
            );

            // Full-stream conformance through the public API + spec
            // driver.
            let enc = encode_key_frame_yuv_with_q(&input, q).unwrap();
            let frames = crate::decoder::decode_av1_spec(&enc.ivf_bytes).unwrap();
            assert_eq!(frames.len(), 1);
            assert_eq!(frames[0].planes[0], plane8(&enc.recon_y), "q={q}: luma");
            assert_eq!(frames[0].planes[1], plane8(&enc.recon_u), "q={q}: U");
            assert_eq!(frames[0].planes[2], plane8(&enc.recon_v), "q={q}: V");
            if q == 0 {
                assert_eq!(
                    enc.recon_y, input.y,
                    "lossless clipped palette must be exact"
                );
            }
        }
    }

    // -----------------------------------------------------------------
    // r425 — screen-content measurement harness (ladder item 5).
    // -----------------------------------------------------------------

    /// One tile-payload encode of `input` through the search + write
    /// path: `screen` opens the §5.9.2/§5.9.20 tool gates exactly like
    /// the public driver (content-adaptive intrabc gate + armed hash
    /// index), `hash = false` leaves the r425 DV index inert (the
    /// r418-r424 geometric search). Returns (tile bytes, luma SSD).
    fn scc_tile_encode(input: &YuvFrame, q: u8, screen: bool, hash: bool) -> (usize, u64) {
        let (w, h) = (input.width as usize, input.height as usize);
        let allow_intrabc = screen && intrabc_beneficial(input);
        let mut recon = ReconState {
            y: vec![0u16; w * h],
            u: vec![0u16; (w / 2) * (h / 2)],
            v: vec![0u16; (w / 2) * (h / 2)],
            width: w,
            height: h,
            chroma_w: w / 2,
            chroma_h: h / 2,
            mi_rows: (h / 4) as u32,
            mi_cols: (w / 4) as u32,
            lossless: q == 0,
            allow_screen_content_tools: screen,
            allow_intrabc,
            qp: QuantizerParams::neutral(q, 8),
            bit_depth: 8,
            subsampling_x: 1,
            subsampling_y: 1,
            num_planes: 3,
            search: SearchLimits::default(),
            bd: BlockDecodedMirror::new(1, 1, 3),
            dv_hash: if hash && allow_intrabc {
                crate::encoder::dv_hash::DvHashIndex::build(&input.y, w, h)
            } else {
                Default::default()
            },
        };
        let (_, params) = search_ctx_for_tests(&recon);
        let mut writer = SymbolWriter::new(false);
        let mut cdfs = TileCdfContext::new_from_defaults();
        cdfs.init_coeff_cdfs(q);
        let mut state = PartitionSyntaxWriter::new(
            recon.mi_rows,
            recon.mi_cols,
            TileGeometry {
                mi_row_start: 0,
                mi_row_end: recon.mi_rows,
                mi_col_start: 0,
                mi_col_end: recon.mi_cols,
            },
        )
        .expect("geometry");
        for (sb_r, sb_c) in sb_grid_origins(recon.mi_rows, recon.mi_cols) {
            recon
                .bd
                .clear_for_sb(sb_r, sb_c, recon.mi_rows, recon.mi_cols);
            state.arm_read_deltas();
            let mut twin = RateTwin::snapshot(&cdfs, &state, &writer);
            twin.arm_read_deltas();
            let (tree, _) = build_search_tree(
                sb_r,
                sb_c,
                BLOCK_64X64,
                input,
                &mut recon,
                &mut twin,
                &params,
                RateModel::Twin,
                None,
                0,
            )
            .expect("search");
            crate::encoder::partition_tree::write_partition_tree_syntax(
                &mut writer,
                &mut cdfs,
                &mut state,
                &tree,
                sb_r,
                sb_c,
                BLOCK_64X64,
                &params,
            )
            .expect("write");
        }
        let bytes = writer.finish().len();
        let mut ssd = 0u64;
        for (a, b) in recon.y.iter().zip(input.y.iter()) {
            let d = *a as i64 - *b as i64;
            ssd += (d * d) as u64;
        }
        (bytes, ssd)
    }

    /// Deterministic 2-colour glyph-text page: flat paper, six random
    /// 8×8 bit-pattern glyphs laid out in text lines — the canonical
    /// repeated-glyph screen content (palette-exact blocks, intrabc
    /// sources at arbitrary offsets).
    fn scc_glyph_text(w: usize, h: usize, seed: u32) -> YuvFrame {
        let mut f = YuvFrame::filled(w as u32, h as u32, 8, ChromaFormat::Yuv420, 128);
        for p in f.y.iter_mut() {
            *p = 235;
        }
        let mut state = seed | 1;
        let mut next = move || {
            state ^= state << 13;
            state ^= state >> 17;
            state ^= state << 5;
            state
        };
        let glyphs: Vec<u64> = (0..6)
            .map(|_| (u64::from(next()) << 32) | u64::from(next()))
            .collect();
        let mut row = 8usize;
        while row + 8 <= h.saturating_sub(4) {
            let mut col = 8usize;
            while col + 8 <= w.saturating_sub(4) {
                if next() % 5 == 0 {
                    col += 8; // word gap
                    continue;
                }
                let g = glyphs[(next() % 6) as usize];
                for i in 0..8 {
                    for j in 0..8 {
                        if (g >> (i * 8 + j)) & 1 == 1 {
                            f.y[(row + i) * w + col + j] = 32;
                        }
                    }
                }
                col += 8;
            }
            row += 12;
        }
        f
    }

    /// UI-panel content: flat regions, a title bar, hairline borders,
    /// a 2-colour dither texture pane and a repeated 16×16 icon.
    fn scc_ui_panel(w: usize, h: usize, seed: u32) -> YuvFrame {
        let mut f = YuvFrame::filled(w as u32, h as u32, 8, ChromaFormat::Yuv420, 128);
        let mut state = seed | 1;
        let mut next = move || {
            state ^= state << 13;
            state ^= state >> 17;
            state ^= state << 5;
            state
        };
        for i in 0..h {
            for j in 0..w {
                f.y[i * w + j] = if i < 16 {
                    64
                } else if i == 16 || j == 0 || j + 1 == w || i + 1 == h {
                    16
                } else {
                    200
                };
            }
        }
        // Dither pane in the lower-left quadrant.
        for i in (h / 2)..(h - 8) {
            for j in 8..(w / 2) {
                f.y[i * w + j] = if next() & 1 == 0 { 40 } else { 200 };
            }
        }
        // One 16×16 2-colour icon repeated on the top row of panes.
        let icon: Vec<bool> = (0..256).map(|_| next() & 1 == 1).collect();
        let mut anchors = vec![(24usize, 8usize)];
        let mut x = 8 + 40;
        while x + 16 < w - 8 {
            anchors.push((24, x));
            x += 40;
        }
        for &(ay, ax) in &anchors {
            if ay + 16 <= h && ax + 16 <= w {
                for i in 0..16 {
                    for j in 0..16 {
                        f.y[(ay + i) * w + ax + j] = if icon[i * 16 + j] { 96 } else { 224 };
                    }
                }
            }
        }
        f
    }

    /// Text lines over a smooth diagonal gradient — the mixed case
    /// (screen tools must pay only where they win).
    fn scc_text_over_gradient(w: usize, h: usize, seed: u32) -> YuvFrame {
        let mut f = scc_glyph_text(w, h, seed);
        for i in 0..h {
            for j in 0..w {
                if f.y[i * w + j] == 235 {
                    f.y[i * w + j] = (48 + (i + j) * 160 / (w + h)) as u16;
                }
            }
        }
        f
    }

    /// Always-on tripwire: on canonical glyph-text screen content the
    /// full r425 screen path must code pixel-exact luma at a fraction
    /// of the natural-coding bytes, and the hash-armed DV search must
    /// not lose to the geometric-only search.
    #[test]
    fn r425_scc_screen_tools_multiple_tripwire() {
        let input = scc_glyph_text(192, 192, 0x7357_0425);
        let (natural, _) = scc_tile_encode(&input, 60, false, false);
        let (screen, ssd) = scc_tile_encode(&input, 60, true, true);
        let (nohash, _) = scc_tile_encode(&input, 60, true, false);
        assert_eq!(ssd, 0, "glyph text must code pixel-exact luma at q60");
        assert!(
            screen * 2 < natural,
            "screen tools must at least halve glyph-text bytes (screen={screen} natural={natural})"
        );
        assert!(
            screen <= nohash,
            "hash-armed DV search must not lose to geometric-only (hash={screen} nohash={nohash})"
        );
    }

    /// Env-gated (`OXIDEAV_AV1_SCC_AB_DIR`) screen-content matrix:
    /// 3 content kinds × 2 sizes (one with a clipped bottom edge) ×
    /// 3 quantisers, natural vs screen vs screen-without-hash tile
    /// bytes + luma SSD, CSV per config + aggregate multiples.
    #[test]
    fn r425_scc_measurement_matrix() {
        let Ok(dir) = std::env::var("OXIDEAV_AV1_SCC_AB_DIR") else {
            return;
        };
        std::fs::create_dir_all(&dir).unwrap();
        let mut csv = String::from("content,w,h,q,natural,screen,nohash,ssd_screen\n");
        let (mut nat_total, mut scr_total, mut nohash_total) = (0u64, 0u64, 0u64);
        let mut exact_nat = 0u64;
        let mut exact_scr = 0u64;
        let mut exact_n = 0u32;
        for &(name, which) in &[("glyph", 0u8), ("ui", 1), ("textgrad", 2)] {
            for &(w, h) in &[(192usize, 192usize), (256, 144)] {
                for &q in &[20u8, 60, 100] {
                    let input = match which {
                        0 => scc_glyph_text(w, h, 0x7357_0425),
                        1 => scc_ui_panel(w, h, 0x0425_0426),
                        _ => scc_text_over_gradient(w, h, 0x0425_0427),
                    };
                    let (nat, _) = scc_tile_encode(&input, q, false, false);
                    let (scr, ssd) = scc_tile_encode(&input, q, true, true);
                    let (noh, _) = scc_tile_encode(&input, q, true, false);
                    csv.push_str(&format!("{name},{w},{h},{q},{nat},{scr},{noh},{ssd}\n"));
                    nat_total += nat as u64;
                    scr_total += scr as u64;
                    nohash_total += noh as u64;
                    if ssd == 0 {
                        exact_nat += nat as u64;
                        exact_scr += scr as u64;
                        exact_n += 1;
                    }
                }
            }
        }
        csv.push_str(&format!(
            "# totals natural={nat_total} screen={scr_total} nohash={nohash_total} \
             multiple={:.2} nohash_multiple={:.2} exact_multiple={:.2} exact_configs={exact_n}\n",
            nat_total as f64 / scr_total as f64,
            nat_total as f64 / nohash_total as f64,
            if exact_scr > 0 {
                exact_nat as f64 / exact_scr as f64
            } else {
                0.0
            },
        ));
        std::fs::write(format!("{dir}/scc_ab_r425.csv"), &csv).unwrap();
        eprintln!("{csv}");
    }

    /// r425 pin content — one deterministic 256×144 "screen page"
    /// exercising every ladder-item-5 arm at once: 2-colour glyph
    /// text lines (repeated glyphs at §6.10.24-reachable off-stride
    /// lags — the hash-DV win case), a two-strip 8+8-colour dither
    /// band (rect VERT palette territory), and a full-width 2-colour
    /// dither footer over the clipped bottom superblock row (144 =
    /// 2×64 + 16 — the `split_or_horz` clipped-palette arm).
    fn scc_pin_page(w: usize, h: usize) -> YuvFrame {
        let mut f = YuvFrame::filled(w as u32, h as u32, 8, ChromaFormat::Yuv420, 128);
        for p in f.y.iter_mut() {
            *p = 235;
        }
        let mut state = 0x0425_C0DEu32;
        let mut next = move || {
            state ^= state << 13;
            state ^= state >> 17;
            state ^= state << 5;
            state
        };
        // Six "anti-aliased" glyphs: dense multi-value 8×8 patterns
        // (deliberately NOT palette-representable — the exact-copy
        // arms are the only cheap coding for a repeat).
        let glyphs: Vec<[u16; 64]> = (0..6)
            .map(|_| {
                let mut g = [0u16; 64];
                for p in g.iter_mut() {
                    *p = (next() & 0xFF) as u16;
                }
                g
            })
            .collect();
        // Text lines at a 16-row pitch (every line lands at the same
        // offset inside its 16×16 gate cell) whose content repeats
        // every third line — later repeats sit at §6.10.24-reachable
        // lags that only the hash index seeds (e.g. Δrow = −48).
        let footer_top = (h / 64) * 64;
        let mut line = 0usize;
        let mut row = 8usize;
        while row + 8 + 4 <= footer_top {
            for slot in 0..(w / 8).saturating_sub(2) {
                // Deterministic per-(repeated-line, slot) glyph pick
                // with sparse word gaps.
                let key = (line % 3) * 131 + slot;
                if key % 5 == 0 {
                    continue;
                }
                let g = &glyphs[key % 6];
                let col = 8 + slot * 8;
                for i in 0..8 {
                    for j in 0..8 {
                        f.y[(row + i) * w + col + j] = g[i * 8 + j];
                    }
                }
            }
            line += 1;
            row += 16;
        }
        // Two-strip band: cols w-64..w of the second superblock row
        // (rect VERT palette territory — two disjoint 8-colour
        // dithers).
        const LEFT: [u16; 8] = [16, 48, 80, 112, 144, 176, 208, 240];
        const RIGHT: [u16; 8] = [20, 52, 84, 116, 148, 180, 212, 244];
        let band_c = w - 64;
        for i in 64..footer_top.min(128) {
            for j in band_c..w {
                let pal = if j < band_c + 32 { &LEFT } else { &RIGHT };
                f.y[i * w + j] = pal[(next() & 7) as usize];
            }
        }
        // Clipped footer: the last (partial) superblock row.
        for i in footer_top..h {
            for j in 0..w {
                f.y[i * w + j] = if next() & 1 == 0 { 40 } else { 200 };
            }
        }
        f
    }

    /// The pin page must actually carry all three r425 arms in its
    /// elected tree: hash-seeded intrabc leaves, an interior rect
    /// palette node, and a clipped-edge HORZ palette top block — and
    /// the emitted stream must round-trip byte-exact through the spec
    /// driver (whose §6.10.24 / §5.11.49 readers re-validate them).
    #[test]
    fn r425_scc_pin_page_features() {
        let (w, h) = (256usize, 144usize);
        let input = scc_pin_page(w, h);
        let q = 60u8;
        let allow_intrabc = intrabc_beneficial(&input);
        assert!(allow_intrabc, "the glyph page must open the §5.9.20 gate");
        let mut recon = ReconState {
            y: vec![0u16; w * h],
            u: vec![0u16; (w / 2) * (h / 2)],
            v: vec![0u16; (w / 2) * (h / 2)],
            width: w,
            height: h,
            chroma_w: w / 2,
            chroma_h: h / 2,
            mi_rows: (h / 4) as u32,
            mi_cols: (w / 4) as u32,
            lossless: false,
            allow_screen_content_tools: true,
            allow_intrabc,
            qp: QuantizerParams::neutral(q, 8),
            bit_depth: 8,
            subsampling_x: 1,
            subsampling_y: 1,
            num_planes: 3,
            search: SearchLimits::default(),
            bd: BlockDecodedMirror::new(1, 1, 3),
            dv_hash: crate::encoder::dv_hash::DvHashIndex::build(&input.y, w, h),
        };
        let (mut twin, params) = search_ctx_for_tests(&recon);
        let (mut ibc, mut rect_pal, mut clipped_pal) = (0u32, 0u32, 0u32);
        fn scan(node: &SyntaxNode, ibc: &mut u32, rect_pal: &mut u32) {
            match node {
                SyntaxNode::Leaf(b) if b.intrabc_mv.is_some() => *ibc += 1,
                SyntaxNode::Leaf(_) => {}
                SyntaxNode::Split(ch) => {
                    for c in ch.iter() {
                        scan(c, ibc, rect_pal);
                    }
                }
                SyntaxNode::Horz(blocks) | SyntaxNode::Vert(blocks) => {
                    for b in blocks.iter() {
                        if b.intrabc_mv.is_some() {
                            *ibc += 1;
                        }
                        if b.palette.size_y > 0 {
                            *rect_pal += 1;
                        }
                    }
                }
                _ => {}
            }
        }
        for (sb_r, sb_c) in sb_grid_origins(recon.mi_rows, recon.mi_cols) {
            recon
                .bd
                .clear_for_sb(sb_r, sb_c, recon.mi_rows, recon.mi_cols);
            twin.arm_read_deltas();
            let (tree, _) = build_search_tree(
                sb_r,
                sb_c,
                BLOCK_64X64,
                &input,
                &mut recon,
                &mut twin,
                &params,
                RateModel::Twin,
                None,
                0,
            )
            .unwrap();
            if sb_r == 32 {
                if let SyntaxNode::Horz(blocks) = &tree {
                    if blocks[0].palette.size_y > 0 {
                        clipped_pal += 1;
                    }
                }
            }
            scan(&tree, &mut ibc, &mut rect_pal);
        }
        assert!(ibc > 0, "pin page must commit intrabc leaves");
        assert!(rect_pal > 0, "pin page must commit rect palette leaves");
        assert!(
            clipped_pal > 0,
            "pin page must elect the clipped HORZ palette arm on the footer row"
        );

        // Public-API stream conformance through the spec driver.
        let enc = encode_key_frame_yuv_with_q(&input, q).unwrap();
        let frames = crate::decoder::decode_av1_spec(&enc.ivf_bytes).unwrap();
        assert_eq!(frames.len(), 1);
        assert_eq!(frames[0].planes[0], plane8(&enc.recon_y), "luma");
        assert_eq!(frames[0].planes[1], plane8(&enc.recon_u), "U");
        assert_eq!(frames[0].planes[2], plane8(&enc.recon_v), "V");
    }

    /// Env-gated pin generation twin (`OXIDEAV_AV1_SCC_FIXTURE_DIR`):
    /// the r425 KEY screen page and a 3-frame scrolled-page GOP,
    /// written as IVF + encoder-reconstruction YUV for external
    /// black-box decoder validation and corpus pinning.
    #[test]
    fn r425_scc_pin_dump() {
        let Ok(dir) = std::env::var("OXIDEAV_AV1_SCC_FIXTURE_DIR") else {
            return;
        };
        std::fs::create_dir_all(&dir).unwrap();
        // Pin A — KEY screen page.
        let input = scc_pin_page(256, 144);
        let enc = encode_key_frame_yuv_with_q(&input, 60).unwrap();
        std::fs::write(
            format!("{dir}/self-kf-256x144-q60-screen-rect.ivf"),
            &enc.ivf_bytes,
        )
        .unwrap();
        let mut yuv = Vec::new();
        yuv.extend_from_slice(&plane8(&enc.recon_y));
        yuv.extend_from_slice(&plane8(&enc.recon_u));
        yuv.extend_from_slice(&plane8(&enc.recon_v));
        std::fs::write(format!("{dir}/self-kf-256x144-q60-screen-rect.yuv"), &yuv).unwrap();

        // Pin B — 3-frame GOP: the page scrolls up 8 px per frame
        // (the text region moves; the footer dither refreshes), so
        // the P-frames mix inter text motion with palette intra
        // re-coding of the changed regions.
        let (w, h) = (192usize, 112usize);
        let page = scc_pin_page(w, h + 16);
        let frame_at = |scroll: usize| -> YuvFrame {
            let mut f = YuvFrame::filled(w as u32, h as u32, 8, ChromaFormat::Yuv420, 128);
            for i in 0..h {
                for j in 0..w {
                    f.y[i * w + j] = page.y[(i + scroll) * w + j];
                }
            }
            f
        };
        let gop: Vec<YuvFrame> = vec![frame_at(0), frame_at(8), frame_at(16)];
        let enc = crate::encoder::inter_frame::encode_gop_yuv_with_q(&gop, 60).expect("gop encode");
        std::fs::write(
            format!("{dir}/self-gop-192x112-q60-screen-scroll.ivf"),
            &enc.ivf_bytes,
        )
        .unwrap();
        let mut yuv = Vec::new();
        for fr in &enc.recon {
            yuv.extend_from_slice(&plane8(&fr.y));
            yuv.extend_from_slice(&plane8(&fr.u));
            yuv.extend_from_slice(&plane8(&fr.v));
        }
        std::fs::write(
            format!("{dir}/self-gop-192x112-q60-screen-scroll.yuv"),
            &yuv,
        )
        .unwrap();
        eprintln!("r425 scc pins dumped to {dir}");
    }

    /// r418 — the k-means clustering arm must win where the block is
    /// NOT exactly representable: 4 colour groups with ±1 jitter
    /// (~12 distinct values per block) cluster to a `<= 8`-colour
    /// §5.11.46 palette whose prediction is within ±1 everywhere,
    /// beating every §7.11.2 mode at q=60; committed leaves stay in
    /// canonical form and the stream round-trips byte-exact.
    #[test]
    fn r418_search_selects_kmeans_palette_on_jittered_dither() {
        const COLORS: [u16; 4] = [16, 80, 160, 240];
        let mut input = YuvFrame::filled(64, 64, 8, ChromaFormat::Yuv420, 128);
        let mut state = 0x0A11_CE55u32;
        let mut next = move || {
            state ^= state << 13;
            state ^= state >> 17;
            state ^= state << 5;
            state
        };
        for p in input.y.iter_mut() {
            let r = next();
            let base = COLORS[(r & 3) as usize];
            let jitter = ((r >> 2) % 3) as i32 - 1;
            *p = (i32::from(base) + jitter).clamp(0, 255) as u16;
        }
        // Distinct count per 64x64 exceeds PALETTE_COLORS (4 groups x
        // 3 jitter levels = 12).
        let mut seen = [false; 256];
        for &v in &input.y {
            seen[v as usize] = true;
        }
        assert!(seen.iter().filter(|&&b| b).count() > PALETTE_COLORS);

        let mut recon = ReconState {
            y: vec![0u16; 64 * 64],
            u: vec![0u16; 32 * 32],
            v: vec![0u16; 32 * 32],
            width: 64,
            height: 64,
            chroma_w: 32,
            chroma_h: 32,
            mi_rows: 16,
            mi_cols: 16,
            lossless: false,
            allow_screen_content_tools: true,
            allow_intrabc: false,
            qp: QuantizerParams::neutral(60, 8),
            bit_depth: 8,
            subsampling_x: 1,
            subsampling_y: 1,
            num_planes: 3,
            search: SearchLimits::default(),
            bd: BlockDecodedMirror::new(1, 1, 3),
            dv_hash: Default::default(),
        };
        recon.bd.clear_for_sb(0, 0, 16, 16);
        let (mut twin, params) = search_ctx_for_tests(&recon);
        let (tree, _) = build_search_tree(
            0,
            0,
            BLOCK_64X64,
            &input,
            &mut recon,
            &mut twin,
            &params,
            RateModel::Twin,
            None,
            0,
        )
        .unwrap();
        let (mut pal, mut other) = (0u32, 0u32);
        count_palette_leaves(&tree, &mut pal, &mut other);
        assert!(
            pal > 0,
            "jittered dither must commit clustered PaletteSizeY > 0 leaves \
             (got PALETTE={pal} OTHER={other})"
        );

        let enc = encode_key_frame_yuv_with_q(&input, 60).unwrap();
        let frames = crate::decoder::decode_av1_spec(&enc.ivf_bytes).unwrap();
        assert_eq!(frames.len(), 1);
        assert_eq!(frames[0].planes[0], plane8(&enc.recon_y));
        assert_eq!(frames[0].planes[1], plane8(&enc.recon_u));
        assert_eq!(frames[0].planes[2], plane8(&enc.recon_v));
    }

    /// r418 conformance-fixture twins: deterministic screen-content
    /// (4-colour glyph tile repeated with period 64 — §5.11.46 palette
    /// AND §5.11.7 intra-block-copy live in one stream) and a k=8
    /// luma+UV palette frame. Each round-trips byte-exact through the
    /// spec driver; when `OXIDEAV_AV1_SCREEN_FIXDIR` is set the exact
    /// streams + reconstructions are written for external validation /
    /// fixture staging.
    #[test]
    fn r418_screen_and_palette_fixture_streams() {
        // --- self-kf-192x192-q60-screen ---
        const COLORS: [u16; 4] = [12, 92, 172, 244];
        let mut tile = vec![0u16; 64 * 64];
        let mut state = 0x5EED_0001u32;
        let mut next = move || {
            state ^= state << 13;
            state ^= state >> 17;
            state ^= state << 5;
            state
        };
        for p in tile.iter_mut() {
            *p = COLORS[(next() & 3) as usize];
        }
        let mut screen = YuvFrame::filled(192, 192, 8, ChromaFormat::Yuv420, 128);
        for i in 0..192usize {
            for j in 0..192usize {
                screen.y[i * 192 + j] = tile[(i % 64) * 64 + (j % 64)];
            }
        }
        for i in 0..96usize {
            for j in 0..96usize {
                let par = ((i / 2) + (j / 2)) & 1;
                screen.u[i * 96 + j] = if par == 0 { 96 } else { 168 };
                screen.v[i * 96 + j] = if ((i / 4) & 1) == par { 108 } else { 152 };
            }
        }
        let enc_screen = encode_key_frame_yuv_with_q(&screen, 60).unwrap();
        assert!(enc_screen.fh.allow_intrabc);
        assert!(enc_screen.fh.allow_screen_content_tools);

        // --- self-kf-96x80-q100-palette (k = 8 luma dither + chroma
        // checker pairs) ---
        const COLORS8: [u16; 8] = [8, 40, 80, 120, 160, 200, 230, 250];
        let mut state8 = 0x1234_5678u32 ^ 0x2C9;
        let mut next8 = move || {
            state8 ^= state8 << 13;
            state8 ^= state8 >> 17;
            state8 ^= state8 << 5;
            state8
        };
        let mut pal = YuvFrame::filled(96, 80, 8, ChromaFormat::Yuv420, 128);
        for i in 0..80usize {
            for j in 0..96usize {
                pal.y[i * 96 + j] = COLORS8[(next8() as usize) % 8];
            }
        }
        for i in 0..40usize {
            for j in 0..48usize {
                let par = ((i / 2) + (j / 2)) & 1;
                pal.u[i * 48 + j] = if par == 0 { 96 } else { 168 };
                pal.v[i * 48 + j] = if ((i / 4) & 1) == par { 108 } else { 152 };
            }
        }
        let enc_pal = encode_key_frame_yuv_with_q(&pal, 100).unwrap();
        assert!(!enc_pal.fh.allow_intrabc, "no duplicate 64x64 tile pair");

        for (name, enc) in [
            ("self-kf-192x192-q60-screen", &enc_screen),
            ("self-kf-96x80-q100-palette", &enc_pal),
        ] {
            let frames = crate::decoder::decode_av1_spec(&enc.ivf_bytes).unwrap();
            assert_eq!(frames.len(), 1, "{name}");
            assert_eq!(frames[0].planes[0], plane8(&enc.recon_y), "{name}: luma");
            assert_eq!(frames[0].planes[1], plane8(&enc.recon_u), "{name}: U");
            assert_eq!(frames[0].planes[2], plane8(&enc.recon_v), "{name}: V");
            if let Ok(dir) = std::env::var("OXIDEAV_AV1_SCREEN_FIXDIR") {
                std::fs::create_dir_all(&dir).unwrap();
                std::fs::write(format!("{dir}/{name}.ivf"), &enc.ivf_bytes).unwrap();
                let mut yuv = Vec::new();
                yuv.extend_from_slice(&plane8(&enc.recon_y));
                yuv.extend_from_slice(&plane8(&enc.recon_u));
                yuv.extend_from_slice(&plane8(&enc.recon_v));
                std::fs::write(format!("{dir}/{name}.yuv"), &yuv).unwrap();
            }
        }
    }

    /// §6.10.24 validity transcription checks: raster delay, wavefront
    /// gradient, tile bounds, magnitude.
    #[test]
    fn r418_intrabc_dv_validity() {
        // 192x192 frame: mi_rows = mi_cols = 48, totalSb64PerRow = 3.
        let (mr, mc) = (48u32, 48u32);
        // SB (1,1) copying SB (0,0): srcSb64 = 0, activeSb64 = 4 —
        // fails the 4-SB64 raster delay.
        assert!(!intrabc_dv_valid(16, 16, BLOCK_64X64, -64, -64, mr, mc));
        // SB (2,2) copying SB (0,0): srcSb64 = 0 < 8 - 4, wavefront
        // offset 10 admits column 0.
        assert!(intrabc_dv_valid(32, 32, BLOCK_64X64, -128, -128, mr, mc));
        // SB (1,2) copying SB (0,0): srcSb64 = 0 < 5 - 4 = 1 and
        // 0 < 2 - 4 + 5 = 3.
        assert!(intrabc_dv_valid(16, 32, BLOCK_64X64, -64, -128, mr, mc));
        // Out of frame.
        assert!(!intrabc_dv_valid(32, 32, BLOCK_64X64, -256, 0, mr, mc));
        // Sources below or right of the wavefront are invalid.
        assert!(!intrabc_dv_valid(32, 32, BLOCK_64X64, 64, -128, mr, mc));
        // An 8x8 leaf inside SB (2,2) reaching into SB (1,1) content:
        // src bottom edge lands in SB row 1 => srcSb64 = 1*3+1 = 4 <
        // active 8 - 4... equals 4 => invalid; two rows up is fine.
        assert!(!intrabc_dv_valid(32, 32, BLOCK_8X8, -64, -64, mr, mc));
        assert!(intrabc_dv_valid(32, 32, BLOCK_8X8, -128, -64, mr, mc));
    }

    /// Ineligible shapes stay palette-free: 1-colour (flat) blocks, >8
    /// distinct colours, and frames with the §5.9.2 gate closed all
    /// yield no candidate.
    #[test]
    fn r418_palette_candidate_gates() {
        let flat = YuvFrame::filled(64, 64, 8, ChromaFormat::Yuv420, 77);
        let recon = ReconState {
            y: vec![0u16; 64 * 64],
            u: vec![0u16; 32 * 32],
            v: vec![0u16; 32 * 32],
            width: 64,
            height: 64,
            chroma_w: 32,
            chroma_h: 32,
            mi_rows: 16,
            mi_cols: 16,
            lossless: false,
            allow_screen_content_tools: true,
            allow_intrabc: false,
            qp: QuantizerParams::neutral(60, 8),
            bit_depth: 8,
            subsampling_x: 1,
            subsampling_y: 1,
            num_planes: 3,
            search: SearchLimits::default(),
            bd: BlockDecodedMirror::new(1, 1, 3),
            dv_hash: Default::default(),
        };
        assert!(
            palette_candidate_y(&flat, &recon, 0, 0, BLOCK_64X64).is_none(),
            "1 distinct colour: no palette candidate"
        );
        let mut many = YuvFrame::filled(64, 64, 8, ChromaFormat::Yuv420, 0);
        for (i, p) in many.y.iter_mut().enumerate() {
            *p = (i % 251) as u16;
        }
        assert!(
            palette_candidate_y(&many, &recon, 0, 0, BLOCK_64X64).is_none(),
            "> PALETTE_COLORS distinct colours: no candidate (r418 scope)"
        );
        let two = {
            let mut f = YuvFrame::filled(64, 64, 8, ChromaFormat::Yuv420, 0);
            for (i, p) in f.y.iter_mut().enumerate() {
                *p = if (i / 3) % 2 == 0 { 10 } else { 200 };
            }
            f
        };
        let cand = palette_candidate_y(&two, &recon, 0, 0, BLOCK_64X64).expect("2-colour block");
        assert_eq!(cand.colors, vec![10, 200]);
        assert_eq!(cand.map.len(), 64 * 64);
        // BLOCK_4X4 is under the §5.11.46 outer gate.
        assert!(palette_candidate_y(&two, &recon, 0, 0, BLOCK_4X4).is_none());
    }
}