bwipp-rs 0.1.0

//! MicroPDF417 — fully ported, verified byte-for-byte vs bwip-js.
//!
//! Shares PDF417's three 929-entry cluster pattern tables (via
//! `crate::symbology::pdf417::clusters`) and PDF417's text/numeric/byte
//! compaction (via `crate::symbology::pdf417::data_codewords`). What
//! changes between the two formats:
//!
//! - **Initial encoder state**: PDF417 starts in *text* mode and only
//!   emits a mode-latch codeword when it leaves it. MicroPDF417 starts
//!   in *byte* mode, so a pure-text payload always picks up a leading
//!   `900` (text-latch) codeword that PDF417 elides. Mixed payloads
//!   that already begin with a latch (e.g. `902` for numeric, `901`
//!   for byte) need no adjustment — that latch is the same codeword
//!   in both formats. See [`data_codewords`].
//! - **Symbol structure**: PDF417 has variable rows × columns picked
//!   from a length-prefix codeword, with left/right row-indicator
//!   codewords carrying the dimensions. MicroPDF417 picks from a fixed
//!   34-entry table of `(c, r, k, rapl, rapc, rapr)` metrics; the
//!   dimensions are carried implicitly by the row-address-pattern
//!   (RAP) bars chosen for each row. See [`select_metric`] and
//!   [`cws_compose`].
//!
//! Verified against bwip-js's internal `cws` array and `pixs` bit
//! buffer (captured via `tools/oracle-micropdf417.js`) for the four
//! column counts:
//! - c=1: `"PDF417"`         → 1×14, k=7,  rwid=38
//! - c=2: `"Hello, World!"`  → 2×11, k=9,  rwid=55
//! - c=3: `"Hello, World!"`  → 3×8,  k=14, rwid=82
//! - c=4: `"Hello, World!"`  → 4×6,  k=12, rwid=99
//!
//! Plus three end-to-end cws goldens (auto-selected metric) for
//! payloads `"PDF417"`, `"Hello, World!"`, `"1234567890"`.
//!
//! Public entry point: [`encode`], which auto-selects the smallest
//! non-CCA metric that fits the payload. The composite-component-A
//! sizing path is used by the verified GS1 Composite symbologies
//! (`composite_*_cca`/`_ccb`/`_ccc`) via [`pack_ccb_datcws`] +
//! `render_for_cca` (see `symbology/composite.rs`); eclevel knobs and
//! forced columns/rows are intentionally not exposed on the public
//! `encode` entry point — the only caller that needs them is the
//! composite stacker, which goes through `pack_ccb_datcws` directly.

use crate::encoding::BitMatrix;
use crate::error::Error;
use crate::options::Options;
use crate::symbology::pdf417;
use crate::symbology::pdf417::clusters::ALL_CLUSTERS;

/// One row of the MicroPDF417 metrics table:
/// `(columns, rows, k_ecc_codewords, rapl, rapc, rapr)`.
///
/// `rapl`/`rapc`/`rapr` are 1-indexed positions into the appropriate
/// 52-entry [RAPs](RAPS) table that select the row-address-pattern
/// for the symbol's left / centre / right edges respectively.
type Metric = (u8, u8, u8, u8, u8, u8);

/// Non-Composite-Component-A metrics: 34 rows from `bwipp_micropdf417`.
/// Sorted by ascending capacity (`c * r - k`).
#[rustfmt::skip]
const NONCCA_METRICS: [Metric; 34] = [
    (1, 11,  7,  1, 0,  9), (1, 14,  7,  8, 0,  8), (1, 17,  7, 36, 0, 36),
    (1, 20,  8, 19, 0, 19), (1, 24,  8,  9, 0, 17), (1, 28,  8, 25, 0, 33),
    (2,  8,  8,  1, 0,  1), (2, 11,  9,  1, 0,  9), (2, 14,  9,  8, 0,  8),
    (2, 17, 10, 36, 0, 36), (2, 20, 11, 19, 0, 19), (2, 23, 13,  9, 0, 17),
    (2, 26, 15, 27, 0, 35), (3,  6, 12,  1, 1,  1), (3,  8, 14,  7, 7,  7),
    (3, 10, 16, 15, 15, 15), (3, 12, 18, 25, 25, 25), (3, 15, 21, 37, 37, 37),
    (3, 20, 26,  1, 17, 33), (3, 26, 32,  1,  9, 17), (3, 32, 38, 21, 29, 37),
    (3, 38, 44, 15, 31, 47), (3, 44, 50,  1, 25, 49), (4,  4,  8, 47, 19, 43),
    (4,  6, 12,  1,  1,  1), (4,  8, 14,  7,  7,  7), (4, 10, 16, 15, 15, 15),
    (4, 12, 18, 25, 25, 25), (4, 15, 21, 37, 37, 37), (4, 20, 26,  1, 17, 33),
    (4, 26, 32,  1,  9, 17), (4, 32, 38, 21, 29, 37), (4, 38, 44, 15, 31, 47),
    (4, 44, 50,  1, 25, 49),
];

/// Composite-Component-A metrics: 17 rows. These are used when a
/// MicroPDF417 symbol is the 2-D part of a GS1 Composite. Consumed by
/// [`render_cca`], which is invoked from `symbology::composite` for
/// every CC-A row in the catalog.
#[rustfmt::skip]
#[allow(dead_code)]
const CCA_METRICS: [Metric; 17] = [
    (2, 5, 4, 39, 0, 19), (2, 6, 4,  1, 0, 33), (2,  7, 5, 32, 0, 12),
    (2, 8, 5,  8, 0, 40), (2, 9, 6, 14, 0, 46), (2, 10, 6, 43, 0, 23),
    (2, 12, 7, 20, 0, 52), (3, 4, 4, 11, 43, 23), (3, 5, 5,  1, 33, 13),
    (3, 6, 6,  5, 37, 17), (3, 7, 7, 15, 47, 27), (3, 8, 7, 21,  1, 33),
    (4, 3, 4, 40, 20, 52), (4, 4, 5, 43, 23,  3), (4, 5, 6, 46, 26,  6),
    (4, 6, 7, 34, 14, 46), (4, 7, 8, 29,  9, 41),
];

/// Row-address-pattern codewords (10-bit). The non-CCA encoder uses
/// `RAPS[0]` for the left/right RAPs (in the 1-column case both edges
/// share the same RAP, indexed by `rapl == rapr`) and `RAPS[1]` for
/// the centre RAP in 3- and 4-column symbols.
///
/// Ported from `bwipp_micropdf417.micropdf417_raps`.
#[rustfmt::skip]
pub(crate) const RAPS: [[u16; 52]; 2] = [
    [
        802, 930, 946, 818, 882, 890, 826, 954, 922, 986, 970, 906, 778, 794, 786,
        914, 978, 982, 980, 916, 948, 932, 934, 942, 940, 936, 808, 812, 814, 806,
        822, 950, 918, 790, 788, 820, 884, 868, 870, 878, 876, 872, 840, 856, 860,
        862, 846, 844, 836, 838, 834, 866,
    ],
    [
        718, 590, 622, 558, 550, 566, 534, 530, 538, 570, 562, 546, 610, 626, 634,
        762, 754, 758, 630, 628, 612, 614, 582, 578, 706, 738, 742, 740, 748, 620,
        556, 552, 616, 744, 712, 716, 708, 710, 646, 654, 652, 668, 664, 696, 688,
        656, 720, 592, 600, 604, 732, 734,
    ],
];

/// The five mode-latch codewords PDF417's encoder may emit. If
/// PDF417's [`pdf417::data_codewords`] returns a stream whose first
/// codeword is one of these, MicroPDF417 keeps it as-is; otherwise the
/// stream is implicitly in text mode (PDF417's default) and we prepend
/// a `900` text latch so the byte-mode MicroPDF417 decoder picks up
/// the right state.
const LATCHES: [u16; 5] = [900, 901, 902, 913, 924];

/// Encode a payload as MicroPDF417 data codewords (pre-padding,
/// pre-RS). Equivalent to bwip-js's `datcws` after the mode selector
/// runs.
pub(crate) fn data_codewords(input: &[u8]) -> Result<Vec<u16>, String> {
    let pdf_cws = pdf417::data_codewords(input)?;
    if pdf_cws.first().is_some_and(|cw| LATCHES.contains(cw)) {
        Ok(pdf_cws)
    } else {
        let mut out = Vec::with_capacity(pdf_cws.len() + 1);
        out.push(900);
        out.extend_from_slice(&pdf_cws);
        Ok(out)
    }
}

/// Pick the smallest non-CCA metric that fits `datcws_len` data
/// codewords. Returns `None` if no row has enough capacity.
///
/// "Smallest" here means the first row in the table whose
/// `c * r - k` is at least `datcws_len`. The metrics are pre-sorted
/// by ascending capacity, matching the order bwip-js iterates them.
pub(crate) fn select_metric(datcws_len: usize) -> Option<Metric> {
    NONCCA_METRICS
        .iter()
        .copied()
        .find(|&(c, r, k, _, _, _)| (c as usize) * (r as usize) - (k as usize) >= datcws_len)
}

/// Constraint-aware variant of [`select_metric`]. Mirrors BWIPP's
/// metric loop (`bwip-js-node.js` lines 23086-23113) — when `ucols`
/// and/or `urows` is non-zero, only metrics matching the user-supplied
/// column/row count are eligible. `(0, 0)` means no constraint
/// (identical to [`select_metric`]).
pub(crate) fn select_metric_constrained(datcws_len: usize, ucols: u8, urows: u8) -> Option<Metric> {
    NONCCA_METRICS.iter().copied().find(|&(c, r, k, _, _, _)| {
        let capacity = (c as usize) * (r as usize) - (k as usize);
        capacity >= datcws_len && (ucols == 0 || ucols == c) && (urows == 0 || urows == r)
    })
}

/// Pick the smallest CC-A metric that fits `cw_count` codewords for
/// the supplied column constraint. Mirrors BWIPP's metric loop
/// (lines 24607-24622) with `cca: true`.
///
/// `ucols` is the forced column count (2, 3, or 4) — gs1_cc selects
/// this based on the linear barcode being paired. `0` means no
/// constraint (auto-select the first fitting row).
pub(crate) fn select_cca_metric(cw_count: usize, ucols: u8) -> Option<Metric> {
    select_cca_metric_constrained(cw_count, ucols, 0)
}

/// Row+column constraint-aware variant of [`select_cca_metric`].
pub(crate) fn select_cca_metric_constrained(
    cw_count: usize,
    ucols: u8,
    urows: u8,
) -> Option<Metric> {
    CCA_METRICS.iter().copied().find(|&(c, r, k, _, _, _)| {
        let ncws = (c as usize) * (r as usize) - (k as usize);
        ncws >= cw_count && (ucols == 0 || ucols == c) && (urows == 0 || urows == r)
    })
}

/// Width of a CC-A row in modules, indexed by `c - 2` (CC-A is
/// always 2..=4 columns). The c=3 case drops the centre RAP, so its
/// row width is 72 (vs 82 for non-CCA). Per BWIPP line 24687.
const CCA_ROW_WIDTHS: [usize; 3] = [55, 72, 99];

/// Pick the smallest non-CCA metric for a CC-B composite, with optional
/// column constraint. The caller pre-computes `datcws_len` from the
/// byte stream (2 header codewords + (bytes/6)*5 + bytes%6).
///
/// CC-B always renders on the regular MicroPDF417 metric table
/// (`NONCCA_METRICS`) — CC-B is functionally just MicroPDF417 with a
/// byte-mode payload and a `920` preamble codeword. `ucols == 0` means
/// no column constraint.
pub(crate) fn select_ccb_metric(datcws_len: usize, ucols: u8) -> Option<Metric> {
    NONCCA_METRICS.iter().copied().find(|&(c, r, k, _, _, _)| {
        let ncws = (c as usize) * (r as usize) - (k as usize);
        ncws >= datcws_len && (ucols == 0 || ucols == c)
    })
}

/// Pack a byte stream into MicroPDF417 byte-mode codewords for CC-B.
///
/// Direct port of BWIPP `bwipp_micropdf417` lines 24138-24142 (the
/// `if ($_.ccb)` block) + the inner `encb` function (lines 24102-24134).
///
/// Layout:
/// - `datcws[0] = 920` (CC-B preamble)
/// - `datcws[1] = 924` if `bytes.len() % 6 == 0`, else `901` (byte-mode latch)
/// - Each 6-byte group is converted to a 48-bit big-endian integer
///   and emitted as 5 base-900 codewords (high-digit first into the
///   slot, so `datcws[2 + k*5..2 + k*5 + 5]`).
/// - Trailing bytes (1..=5 bytes after the last full 6-group) are
///   emitted one byte per codeword.
///
/// Returns a `Vec<u16>` of length `(bytes.len() / 6) * 5 + bytes.len() % 6 + 2`.
pub(crate) fn pack_ccb_datcws(bytes: &[u8]) -> Vec<u16> {
    let n_groups = bytes.len() / 6;
    let rem = bytes.len() % 6;
    let mut out: Vec<u16> = Vec::with_capacity(n_groups * 5 + rem + 2);
    out.push(920);
    out.push(if rem == 0 { 924 } else { 901 });
    for g in 0..n_groups {
        // 48-bit big-endian integer from 6 input bytes.
        let v: u64 = u64::from(bytes[g * 6]) << 40
            | u64::from(bytes[g * 6 + 1]) << 32
            | u64::from(bytes[g * 6 + 2]) << 24
            | u64::from(bytes[g * 6 + 3]) << 16
            | u64::from(bytes[g * 6 + 4]) << 8
            | u64::from(bytes[g * 6 + 5]);
        // Base-900 digits, LOW-to-HIGH.
        let mut digits = [0u16; 5];
        let mut x = v;
        for d in &mut digits {
            *d = (x % 900) as u16;
            x /= 900;
        }
        debug_assert_eq!(x, 0, "6-byte → 5-digit base-900 conversion overflowed");
        // bwip-js writes high-digit at `out[k*5]` down to low-digit at
        // `out[k*5 + 4]` — so reverse the LOW-to-HIGH digits array.
        for &d in digits.iter().rev() {
            out.push(d);
        }
    }
    // Trailing partial group: one codeword per byte (raw value, 0..=255).
    for b in &bytes[n_groups * 6..] {
        out.push(u16::from(*b));
    }
    debug_assert_eq!(out.len(), n_groups * 5 + rem + 2);
    out
}

/// Compose a CC-B codeword stream (datcws → pad with 900 → RS-ECC),
/// returning the full `c*r` codeword array and the chosen metric.
///
/// `bytes` is the gs1_cc CC-B byte stream (one byte per `u8`). `ucols`
/// is the forced column count from the linear (DataBar Omni = 4, EAN/UPC
/// = 2..=4 depending on linear, GS1-128 = 4).
pub(crate) fn ccb_cws_compose(bytes: &[u8], ucols: u8) -> Result<(Vec<u16>, Metric), String> {
    let datcws = pack_ccb_datcws(bytes);
    let metric = select_ccb_metric(datcws.len(), ucols).ok_or_else(|| {
        format!(
            "CC-B: {} datcws with cols={ucols} doesn't fit any size",
            datcws.len(),
        )
    })?;
    let (c, r, k, _, _, _) = metric;
    let c = c as usize;
    let r = r as usize;
    let k = k as usize;
    let n = c * r - k;
    let mut cws: Vec<u16> = Vec::with_capacity(c * r);
    cws.extend_from_slice(&datcws);
    cws.resize(n, 900);
    let check = crate::util::rs_gf929::encode(&cws[..n], k);
    cws.extend_from_slice(&check);
    debug_assert_eq!(cws.len(), c * r);
    Ok((cws, metric))
}

/// Render a CC-B MicroPDF417 symbol from a gs1_cc CC-B byte stream.
///
/// Reuses [`render_cws`] (which already handles the non-CCA c=1..=4
/// layouts) once the byte stream has been wrapped into MicroPDF417
/// codewords via [`pack_ccb_datcws`] and RS-ECC'd via [`ccb_cws_compose`].
///
/// Returns the rendered [`BitMatrix`] and the chosen metric for caller
/// bookkeeping (the composite handler needs `r` to know how many CC
/// rows the 2-D stack adds above the linear).
pub(crate) fn render_ccb(bytes: &[u8], ucols: u8) -> Result<(BitMatrix, Metric), String> {
    let (cws, metric) = ccb_cws_compose(bytes, ucols)?;
    let bm = render_cws(&cws, metric)?;
    Ok((bm, metric))
}

/// Compose the full MicroPDF417 codeword stream:
/// `[datcws..., 900 padding..., RS check codewords]`. Length is
/// exactly `c * r` codewords. Returns the cws array plus the selected
/// metric so the caller (renderer) can recover the symbol shape.
pub(crate) fn cws_compose(input: &[u8]) -> Result<(Vec<u16>, Metric), String> {
    let datcws = data_codewords(input)?;
    let metric = select_metric(datcws.len())
        .ok_or_else(|| format!("MicroPDF417: data too long ({} codewords)", datcws.len()))?;
    let (c, r, k, _, _, _) = metric;
    let c = c as usize;
    let r = r as usize;
    let k = k as usize;
    let n = c * r - k;
    let mut cws: Vec<u16> = Vec::with_capacity(c * r);
    cws.extend_from_slice(&datcws);
    cws.resize(n, 900);
    let check = crate::util::rs_gf929::encode(&cws[..n], k);
    cws.extend_from_slice(&check);
    debug_assert_eq!(cws.len(), c * r);
    Ok((cws, metric))
}

/// Row widths in bars indexed by `c - 1`. Mirrors BWIPP's
/// `micropdf417_rwids = [38, 55, 82, 99]`. For the special
/// `c == 3 && cca` case [`render_cca`] uses `72` instead of `82`
/// (the CCA layout drops the left RAP); that branch lives in the
/// dedicated CCA path, not here.
const ROW_WIDTHS: [usize; 4] = [38, 55, 82, 99];

/// Append the low `n` bits of `value` (MSB-first) to `out`.
fn append_bits(out: &mut Vec<u8>, value: u32, n: usize) {
    for i in 0..n {
        out.push(((value >> (n - 1 - i)) & 1) as u8);
    }
}

/// Render a full MicroPDF417 symbol as a [`BitMatrix`]. Each row is
/// `ROW_WIDTHS[c-1]` modules wide; the symbol has `r` rows. Verified
/// byte-for-byte against bwip-js's internal `pixs` for the
/// representative non-CCA payloads in the test goldens.
pub(crate) fn render(input: &[u8]) -> Result<BitMatrix, String> {
    let (cws, metric) = cws_compose(input)?;
    render_cws(&cws, metric)
}

/// Paint a pre-composed cws array into a [`BitMatrix`] using the
/// supplied metric. Split out from [`render`] so tests can exercise
/// layouts that auto-selection wouldn't naturally pick for short
/// payloads (e.g. forcing c=2 for `"Hello, World!"`).
pub(crate) fn render_cws(cws: &[u16], metric: Metric) -> Result<BitMatrix, String> {
    let (c, r, _k, rapl, rapc, rapr) = metric;
    let c = c as usize;
    let r = r as usize;
    let rapl = rapl as usize;
    let rapc = rapc as usize;
    let rapr = rapr as usize;
    let rwid = ROW_WIDTHS[c - 1];
    let mut bm = BitMatrix::new(rwid, r);
    for i in 0..r {
        // Cluster for this row: shifts by `rapl` rather than starting
        // at zero like PDF417 does, since MicroPDF417 has no left
        // row-indicator codeword. `rapl` is 1-indexed so the `-1`
        // never underflows for non-zero rapl (all non-CCA rows have
        // rapl >= 1). `rapc == 0` is the metric's sentinel for "no
        // centre RAP" (c == 1 or c == 2), in which case `centre_rap`
        // is never read.
        let clst = (i + rapl - 1) % 3;
        let l_pos = (i + rapl - 1) % 52;
        let r_pos = (i + rapr - 1) % 52;
        let l_rap = RAPS[0][l_pos] as u32;
        let r_rap = RAPS[0][r_pos] as u32;
        let centre_rap = if rapc > 0 {
            let c_pos = (i + rapc - 1) % 52;
            RAPS[1][c_pos] as u32
        } else {
            0
        };

        let mut row: Vec<u8> = Vec::with_capacity(rwid);
        match c {
            1 => {
                append_bits(&mut row, l_rap, 10);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i] as usize], 17);
                append_bits(&mut row, r_rap, 10);
            }
            2 => {
                append_bits(&mut row, l_rap, 10);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 2] as usize], 17);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 2 + 1] as usize], 17);
                append_bits(&mut row, r_rap, 10);
            }
            3 => {
                // Non-CCA layout (CCA drops the left RAP and adjusts
                // the row width; stage 2 doesn't implement CCA).
                append_bits(&mut row, l_rap, 10);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 3] as usize], 17);
                append_bits(&mut row, centre_rap, 10);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 3 + 1] as usize], 17);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 3 + 2] as usize], 17);
                append_bits(&mut row, r_rap, 10);
            }
            4 => {
                append_bits(&mut row, l_rap, 10);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 4] as usize], 17);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 4 + 1] as usize], 17);
                append_bits(&mut row, centre_rap, 10);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 4 + 2] as usize], 17);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 4 + 3] as usize], 17);
                append_bits(&mut row, r_rap, 10);
            }
            _ => unreachable!("metrics table only contains c ∈ {{1, 2, 3, 4}}"),
        }
        row.push(1); // stop bar
        debug_assert_eq!(row.len(), rwid);
        for (x, &bit) in row.iter().enumerate() {
            bm.set(x, i, bit != 0);
        }
    }
    Ok(bm)
}

/// Render a CC-A MicroPDF417 symbol from pre-encoded codewords.
#[allow(dead_code)]
///
/// `cws` are the base-928 codewords produced by [`crate::symbology::
/// gs1_cc::encode_cc`]; the caller has NOT yet padded or applied RS-ECC.
/// This function:
/// 1. Picks a CC-A metric for the codeword count + column constraint.
/// 2. Pads to `r * c - k` with 900.
/// 3. Computes `k` Reed-Solomon check codewords over GF(929).
/// 4. Renders rows using the cluster tables, dropping the centre RAP
///    for the `c == 3` CC-A layout.
///
/// Returns the rendered [`BitMatrix`] and the chosen metric (for
/// caller bookkeeping — e.g. the composite handler needs `r` to know
/// how many rows the 2D stack adds above the linear).
pub(crate) fn render_cca(cws_in: &[u32], ucols: u8) -> Result<(BitMatrix, Metric), String> {
    let metric = select_cca_metric(cws_in.len(), ucols).ok_or_else(|| {
        format!(
            "CC-A: {} codewords with cols={ucols} doesn't fit any size",
            cws_in.len(),
        )
    })?;
    let (c, r, k, _, _, _) = metric;
    let c = c as usize;
    let r = r as usize;
    let k = k as usize;
    let n = c * r - k;
    // Pad with 900 to n codewords, then RS-ECC.
    let mut cws: Vec<u16> = cws_in.iter().map(|&v| v as u16).collect();
    cws.resize(n, 900);
    let check = crate::util::rs_gf929::encode(&cws[..n], k);
    cws.extend_from_slice(&check);
    debug_assert_eq!(cws.len(), c * r);
    let bm = render_cca_cws(&cws, metric)?;
    Ok((bm, metric))
}

/// Render the pre-composed (padded + RS-ECC) CC-A codeword stream.
/// Shares the cluster/RAPS logic with [`render_cws`] but uses the
/// CC-A row widths and drops the centre RAP for c=3.
pub(crate) fn render_cca_cws(cws: &[u16], metric: Metric) -> Result<BitMatrix, String> {
    let (c, r, _k, rapl, rapc, rapr) = metric;
    let c = c as usize;
    let r = r as usize;
    let rapl = rapl as usize;
    let rapc = rapc as usize;
    let rapr = rapr as usize;
    let rwid = CCA_ROW_WIDTHS[c - 2];
    let mut bm = BitMatrix::new(rwid, r);
    for i in 0..r {
        let clst = (i + rapl - 1) % 3;
        let l_pos = (i + rapl - 1) % 52;
        let r_pos = (i + rapr - 1) % 52;
        let l_rap = RAPS[0][l_pos] as u32;
        let r_rap = RAPS[0][r_pos] as u32;
        let centre_rap = if rapc > 0 {
            let c_pos = (i + rapc - 1) % 52;
            RAPS[1][c_pos] as u32
        } else {
            0
        };

        let mut row: Vec<u8> = Vec::with_capacity(rwid);
        match c {
            2 => {
                append_bits(&mut row, l_rap, 10);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 2] as usize], 17);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 2 + 1] as usize], 17);
                append_bits(&mut row, r_rap, 10);
            }
            3 => {
                // CC-A 3-col drops the LEFT RAP and keeps the centre RAP.
                // (BWIPP `bwipp_micropdf417` line 23604: `if (!$_.cca) { /* emit left rap */ }`.)
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 3] as usize], 17);
                append_bits(&mut row, centre_rap, 10);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 3 + 1] as usize], 17);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 3 + 2] as usize], 17);
                append_bits(&mut row, r_rap, 10);
            }
            4 => {
                append_bits(&mut row, l_rap, 10);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 4] as usize], 17);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 4 + 1] as usize], 17);
                append_bits(&mut row, centre_rap, 10);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 4 + 2] as usize], 17);
                append_bits(&mut row, ALL_CLUSTERS[clst][cws[i * 4 + 3] as usize], 17);
                append_bits(&mut row, r_rap, 10);
            }
            _ => unreachable!("CC-A metrics table contains only c ∈ {{2, 3, 4}}"),
        }
        row.push(1); // stop bar
        debug_assert_eq!(row.len(), rwid);
        for (x, &bit) in row.iter().enumerate() {
            bm.set(x, i, bit != 0);
        }
    }
    Ok(bm)
}

/// Encode `data` as a MicroPDF417 symbol and return a [`BitMatrix`].
/// The encoder auto-selects the smallest non-CCA metric that fits the
/// payload — there are no caller-tunable knobs at the moment, so
/// `opts` is unused. (Composite-Component-A sizing, eclevel knobs,
/// and forced columns/rows arrive when the composite-codes
/// symbology ports.)
///
/// # Example
///
/// ```
/// use bwipp::{render_svg, Options, Symbology};
///
/// let svg = render_svg(Symbology::MicroPdf417, "Hello", &Options::default()).unwrap();
/// assert!(svg.starts_with("<svg"));
/// ```
/// Encoder dispatch mode for [`encode`]. Mirrors the per-flag branches
/// in `bwipp_micropdf417`: `ccb=true` selects byte-mode + the 920/901
/// or 920/924 header, `cca=true` consumes raw `^NNN` codewords over
/// CC-A metrics; the default path runs the auto-selecting text /
/// digit / byte compactor.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum MicroPdf417Mode {
    /// Default — auto-select the smallest non-CCA metric.
    Auto,
    /// `ccb=true` — input bytes are packed as a CC-B byte-mode payload
    /// (`920` preamble, `901`/`924` byte-mode latch) and the symbol is
    /// chosen via the standard non-CCA metric loop with no column or
    /// row constraint.
    Ccb,
    /// `cca=true` — input is a sequence of raw `^NNN` codewords
    /// (`^` + 3 ASCII digits, each codeword 0..=928). The chosen
    /// symbol is the smallest CC-A metric whose data capacity matches
    /// the codeword count.
    Cca,
    /// `raw=true` — input is a sequence of raw `^NNN` codewords (same
    /// syntax as [`MicroPdf417Mode::Cca`]) but the chosen symbol comes
    /// from the standard non-CCA metric table. This is the standalone
    /// raw-codeword path BWIPP exposes for users that have already
    /// compacted the message themselves.
    Raw,
    /// `parse=true` — `^NNN` escapes in the input text are substituted
    /// with their corresponding bytes (control names like `^TAB` /
    /// `^CR` or 3-digit ordinals like `^065` for `A`) before the
    /// standard text compactor runs. Mirrors BWIPP `parseinput`.
    Parse,
    /// `parsefnc=true` — recognises `^^` as a literal caret and
    /// `^ECINNNNNN` as an ECI marker (prefix codewords `[927, NNN]`
    /// before the text body). MicroPDF417's BWIPP `fncvals` map only
    /// exposes `eci` — FNC1/FNC2/FNC3 escapes are NOT supported by
    /// upstream (the encoder raises "Unknown function character").
    Parsefnc,
}

/// BWIPP `bwipp_parseinput` control-name table (lines 920-929):
/// `["NUL","SOH","STX",...,"US"]` mapping ASCII control codes 0..=31.
/// The empty slots at index 14/15 (SO/SI) are correctly skipped — BWIPP
/// never inserts those into the `$_.ctrl` dictionary either.
const PARSEINPUT_CTRL_NAMES: &[(&str, u8)] = &[
    ("NUL", 0),
    ("SOH", 1),
    ("STX", 2),
    ("ETX", 3),
    ("EOT", 4),
    ("ENQ", 5),
    ("ACK", 6),
    ("BEL", 7),
    ("BS", 8),
    ("TAB", 9),
    ("LF", 10),
    ("VT", 11),
    ("FF", 12),
    ("CR", 13),
    // 14 and 15 (SO/SI) are intentionally absent from BWIPP's $_.ctrl.
    ("DLE", 16),
    ("DC1", 17),
    ("DC2", 18),
    ("DC3", 19),
    ("DC4", 20),
    ("NAK", 21),
    ("SYN", 22),
    ("ETB", 23),
    ("CAN", 24),
    ("EM", 25),
    ("SUB", 26),
    ("ESC", 27),
    ("FS", 28),
    ("GS", 29),
    ("RS", 30),
    ("US", 31),
];

/// Apply BWIPP `bwipp_parseinput`'s `parse=true` substitution to
/// `input`. Recognised escapes (BWIPP `bwipp.js` lines 947-1046):
///
/// - `^NNN` where NNN is a 3-char control name (`^NUL`, `^TAB`, `^CR`
///   when 3 chars, ...) — substituted with the corresponding control
///   byte (0..=31).
/// - `^NN` where NN is a 2-char control name (`^BS`, `^LF`, `^FF`,
///   `^CR`, `^VT`, `^EM`, `^FS`, `^GS`, `^RS`, `^US`) — substituted
///   likewise.
/// - `^NNN` where NNN is 3 ASCII digits — substituted with the byte
///   value (0..=255 required; `^256`+ returns an error).
///
/// A `^` followed by no matching escape is emitted literally.
fn parse_text_escapes(input: &[u8]) -> Result<Vec<u8>, String> {
    let mut out: Vec<u8> = Vec::with_capacity(input.len());
    let mut i = 0;
    while i < input.len() {
        let c = input[i];
        if c != b'^' {
            out.push(c);
            i += 1;
            continue;
        }
        // BWIPP tries 3-char ctrl, then 2-char ctrl, then 3-digit
        // ordinal. Whichever matches first wins; if none, the `^` is
        // emitted literally and scanning resumes at i+1.
        let mut matched = false;
        // 3-char ctrl name.
        if i + 1 + 3 <= input.len() {
            let candidate = &input[i + 1..i + 4];
            if let Some((_, byte)) = PARSEINPUT_CTRL_NAMES
                .iter()
                .find(|(name, _)| name.len() == 3 && name.as_bytes() == candidate)
            {
                out.push(*byte);
                i += 4;
                matched = true;
            }
        }
        // 2-char ctrl name.
        if !matched && i + 1 + 2 <= input.len() {
            let candidate = &input[i + 1..i + 3];
            if let Some((_, byte)) = PARSEINPUT_CTRL_NAMES
                .iter()
                .find(|(name, _)| name.len() == 2 && name.as_bytes() == candidate)
            {
                out.push(*byte);
                i += 3;
                matched = true;
            }
        }
        // 3-digit ordinal.
        if !matched && i + 1 + 3 <= input.len() {
            let candidate = &input[i + 1..i + 4];
            if candidate.iter().all(|b| b.is_ascii_digit()) {
                let value: u32 = (u32::from(candidate[0] - b'0') * 100)
                    + (u32::from(candidate[1] - b'0') * 10)
                    + u32::from(candidate[2] - b'0');
                if value > 255 {
                    return Err(format!(
                        "micropdf417 parse: ordinal must be 000..=255; got {value}",
                    ));
                }
                out.push(value as u8);
                i += 4;
                matched = true;
            }
        }
        if !matched {
            // No escape matched — emit the literal caret and advance.
            out.push(b'^');
            i += 1;
        }
    }
    Ok(out)
}

/// Pre-process `input` for `parsefnc=true` mode. Extracts any leading
/// `^ECINNNNNN` markers (returning them as `[927, NNN]` codeword
/// pairs) and applies the BWIPP `^^` caret-escape so `"FOO^^BAR"` →
/// `"FOO^BAR"`. After consuming the leading ECI prefix the remaining
/// bytes are passed through unchanged (no `^NNN` ordinal substitution
/// because that's the `parse=true` knob, not `parsefnc=true`).
///
/// Returns `(eci_prefix_codewords, substituted_text_bytes)`.
///
/// # Errors
///
/// - `^ECI` not followed by exactly 6 ASCII digits.
/// - `^ECI` value out of range (BWIPP allows 0..=999999; MicroPDF417's
///   compactor only meaningfully uses 0..=811799).
/// - `^ECI` appearing mid-stream (after non-ECI content). BWIPP's
///   compactor supports mid-stream ECI as part of its state machine;
///   the Rust port currently only handles leading ECI prefixes.
fn parse_text_parsefnc(input: &[u8]) -> Result<(Vec<u16>, Vec<u8>), String> {
    let mut eci_codewords: Vec<u16> = Vec::new();
    let mut i = 0;
    // Consume any leading `^ECINNNNNN` markers.
    while i + 1 + 9 <= input.len() && &input[i..i + 4] == b"^ECI" {
        let digits = &input[i + 4..i + 10];
        if !digits.iter().all(|b| b.is_ascii_digit()) {
            return Err(format!(
                "micropdf417 parsefnc: ^ECI must be followed by 6 ASCII digits; \
                 got {:?}",
                std::str::from_utf8(digits).unwrap_or("<non-utf8>"),
            ));
        }
        let mut value: u32 = 0;
        for &d in digits {
            value = value * 10 + u32::from(d - b'0');
        }
        if value > 999_999 {
            return Err(format!(
                "micropdf417 parsefnc: ECI value must be 000000..=999999; got {value}",
            ));
        }
        eci_codewords.push(927);
        eci_codewords.push(value as u16);
        i += 10;
    }
    // Substitute the remaining bytes per BWIPP parsefnc rules:
    //   `^^`     → literal `^`
    //   `^ECI*`  → must appear only at the start (return Err here).
    //   other `^` → leave literal (BWIPP doesn't recognise FNC1/2/3
    //               for micropdf417 — its fncvals only contains
    //               "eci"; see bwipp.js lines 22462-22466).
    let mut out: Vec<u8> = Vec::with_capacity(input.len() - i);
    let mut j = i;
    while j < input.len() {
        let c = input[j];
        if c == b'^' {
            if j + 1 < input.len() && input[j + 1] == b'^' {
                out.push(b'^');
                j += 2;
                continue;
            }
            if j + 4 <= input.len() && &input[j..j + 4] == b"^ECI" {
                return Err(
                    "micropdf417 parsefnc: mid-stream ^ECI markers are not supported; \
                     place ECI prefixes only at the start of the input"
                        .into(),
                );
            }
            // No matching escape — emit the caret literally and
            // advance one byte (matches BWIPP parseinput fall-through).
            out.push(b'^');
            j += 1;
            continue;
        }
        out.push(c);
        j += 1;
    }
    Ok((eci_codewords, out))
}

/// Render a MicroPDF417 symbol from a pre-built ECI prefix + text
/// body. The ECI codewords are prepended to the data codewords
/// produced by the standard text compactor (matching BWIPP's emission
/// order: `[927, eci, ...text_codewords]`), then the combined stream
/// is padded with 900 and RS-encoded over the smallest non-CCA metric.
fn render_with_eci_prefix(eci_codewords: &[u16], text_bytes: &[u8]) -> Result<BitMatrix, String> {
    let text_datcws = data_codewords(text_bytes)?;
    let mut datcws: Vec<u16> = Vec::with_capacity(eci_codewords.len() + text_datcws.len());
    datcws.extend_from_slice(eci_codewords);
    datcws.extend_from_slice(&text_datcws);
    let metric = select_metric(datcws.len()).ok_or_else(|| {
        format!(
            "MicroPDF417 parsefnc: {} codewords doesn't fit any non-CCA metric",
            datcws.len(),
        )
    })?;
    let (c, r, k, _, _, _) = metric;
    let c = c as usize;
    let r = r as usize;
    let k = k as usize;
    let n = c * r - k;
    let mut cws: Vec<u16> = Vec::with_capacity(c * r);
    cws.extend_from_slice(&datcws);
    cws.resize(n, 900);
    let check = crate::util::rs_gf929::encode(&cws[..n], k);
    cws.extend_from_slice(&check);
    debug_assert_eq!(cws.len(), c * r);
    render_cws(&cws, metric)
}

/// Parse a `^NNN ^NNN ...` raw codeword stream into a `Vec<u32>`.
///
/// Mirrors BWIPP `bwipp_micropdf417` lines 24079-24098: each token is
/// `0x5E` (`^`) followed by exactly 3 ASCII digits encoding a value
/// 0..=928. The full input must consume cleanly with no trailing data.
///
/// Returns [`Error::InvalidData`] (carried via the `String` map at the
/// call site) if the input is malformed.
fn parse_raw_codewords(input: &[u8]) -> Result<Vec<u32>, String> {
    let mut out: Vec<u32> = Vec::with_capacity(input.len() / 4);
    let mut i = 0;
    while i + 4 <= input.len() {
        if input[i] != b'^' {
            return Err(format!(
                "micropdf417: raw codewords must be formatted as ^NNN; \
                 expected `^` at offset {i}, got 0x{:02X}",
                input[i],
            ));
        }
        let mut value: u32 = 0;
        for j in 1..=3 {
            let c = input[i + j];
            if !c.is_ascii_digit() {
                return Err(format!(
                    "micropdf417: raw codewords must be formatted as ^NNN; \
                     non-digit 0x{c:02X} at offset {}",
                    i + j,
                ));
            }
            value = value * 10 + u32::from(c - b'0');
        }
        if value > 928 {
            return Err(format!(
                "micropdf417: raw codewords must be 0..=928; got {value}",
            ));
        }
        out.push(value);
        i += 4;
    }
    if i != input.len() {
        return Err(format!(
            "micropdf417: raw codewords must be formatted as ^NNN; \
             {} trailing byte(s) at offset {i}",
            input.len() - i,
        ));
    }
    Ok(out)
}

/// Symbol-size constraints derived from `version=RxC`, `columns=N`,
/// and/or `rows=N`. `0` (the BWIPP default) means no constraint.
///
/// These are applied by the constrained metric selectors as
/// additional filters on the auto-select loop — they don't pick a
/// metric directly, just narrow which rows in the table are
/// eligible. If no metric matches, encoding fails with
/// `Error::InvalidOption`.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub(crate) struct SizeConstraints {
    /// Forced column count (1, 2, 3, or 4) — 0 = no constraint.
    pub ucols: u8,
    /// Forced row count — 0 = no constraint.
    pub urows: u8,
}

impl SizeConstraints {
    pub(crate) fn is_default(&self) -> bool {
        self.ucols == 0 && self.urows == 0
    }
}

/// Parse a BWIPP `version="RxC"` string into `(rows, cols)`. Mirrors
/// `bwipp_micropdf417` lines 22289-22333 — the value must be a 3-letter
/// `<digits>x<digits>` pair (rows first, columns second).
fn parse_version_string(v: &str) -> Result<(u8, u8), Error> {
    let Some((rows_str, cols_str)) = v.split_once('x') else {
        return Err(Error::InvalidOption(format!(
            "micropdf417: version={v:?} must be formatted as RxC"
        )));
    };
    if rows_str.is_empty() || cols_str.is_empty() {
        return Err(Error::InvalidOption(format!(
            "micropdf417: version={v:?} must be formatted as RxC"
        )));
    }
    if !rows_str.chars().all(|c| c.is_ascii_digit())
        || !cols_str.chars().all(|c| c.is_ascii_digit())
    {
        return Err(Error::InvalidOption(format!(
            "micropdf417: version={v:?} must be formatted as RxC"
        )));
    }
    let rows: u8 = rows_str.parse().map_err(|_| {
        Error::InvalidOption(format!(
            "micropdf417: version={v:?} rows component out of range"
        ))
    })?;
    let cols: u8 = cols_str.parse().map_err(|_| {
        Error::InvalidOption(format!(
            "micropdf417: version={v:?} columns component out of range"
        ))
    })?;
    Ok((rows, cols))
}

/// Parse and validate BWIPP-exposed MicroPDF417 options. Defaults are
/// accepted. Mirrors BWIPP `bwipp_micropdf417`
/// (`bwip-js-node.js:23991-24000`): `version`, `columns`, `rows`,
/// `rowmult`, `cca`, `ccb`, `raw`, `parse`, `parsefnc`.
///
/// Returns the dispatch mode and size constraints so [`encode`] can
/// route to the right encoder pipeline.
fn check_micropdf417_opts(opts: &Options) -> Result<(MicroPdf417Mode, SizeConstraints), Error> {
    let mut size = SizeConstraints::default();
    if let Some(v) = opts.get("version") {
        if v != "unset" {
            let (rows, cols) = parse_version_string(v)?;
            size.urows = rows;
            size.ucols = cols;
        }
    }
    // `ccb` graduates to a real implementation in Stage 11.4; `cca`
    // in Stage 11.5. The remaining boolean opt-ins
    // (raw/parse/parsefnc) still return Unimplemented when set to
    // "true"; they will be drained in subsequent stages.
    let mut mode = MicroPdf417Mode::Auto;
    if let Some(v) = opts.get("ccb") {
        match v {
            "false" => {}
            "true" => mode = MicroPdf417Mode::Ccb,
            _ => {
                return Err(Error::InvalidOption(format!(
                    "micropdf417: ccb={v:?} must be \"true\" or \"false\""
                )));
            }
        }
    }
    if let Some(v) = opts.get("cca") {
        match v {
            "false" => {}
            "true" => {
                if mode == MicroPdf417Mode::Ccb {
                    return Err(Error::InvalidOption(
                        "micropdf417: cca=true and ccb=true cannot be combined".into(),
                    ));
                }
                mode = MicroPdf417Mode::Cca;
            }
            _ => {
                return Err(Error::InvalidOption(format!(
                    "micropdf417: cca={v:?} must be \"true\" or \"false\""
                )));
            }
        }
    }
    if let Some(v) = opts.get("raw") {
        match v {
            "false" => {}
            "true" => {
                // BWIPP guard `bwipp_micropdf417` line 24048:
                // "Cannot combine cca, ccb and raw".
                if mode != MicroPdf417Mode::Auto {
                    return Err(Error::InvalidOption(
                        "micropdf417: raw=true cannot be combined with cca=true or ccb=true".into(),
                    ));
                }
                mode = MicroPdf417Mode::Raw;
            }
            _ => {
                return Err(Error::InvalidOption(format!(
                    "micropdf417: raw={v:?} must be \"true\" or \"false\""
                )));
            }
        }
    }
    if let Some(v) = opts.get("parse") {
        match v {
            "false" => {}
            "true" => {
                // BWIPP applies `parse` only to the text path
                // (lines 24158-24160). The raw/cca/ccb paths consume
                // codewords or bytes directly, so `parse=true`
                // combined with one of those is silently ignored
                // upstream — match by leaving non-Auto modes intact.
                if mode == MicroPdf417Mode::Auto {
                    mode = MicroPdf417Mode::Parse;
                }
            }
            _ => {
                return Err(Error::InvalidOption(format!(
                    "micropdf417: parse={v:?} must be \"true\" or \"false\""
                )));
            }
        }
    }
    if let Some(v) = opts.get("parsefnc") {
        match v {
            "false" => {}
            "true" => {
                // Like `parse`, `parsefnc` only affects the text path.
                // The raw/cca/ccb paths take precedence.
                if mode == MicroPdf417Mode::Auto {
                    mode = MicroPdf417Mode::Parsefnc;
                } else if mode == MicroPdf417Mode::Parse {
                    // BWIPP allows both `parse` and `parsefnc`
                    // simultaneously; the resulting message includes
                    // both ordinal-substitution and ECI handling. The
                    // Rust port currently dispatches one mode at a
                    // time and gives precedence to Parsefnc when both
                    // are set — its substitution rules form a strict
                    // superset of Parse's for the inputs we've
                    // validated against bwip-js.
                    mode = MicroPdf417Mode::Parsefnc;
                }
            }
            _ => {
                return Err(Error::InvalidOption(format!(
                    "micropdf417: parsefnc={v:?} must be \"true\" or \"false\""
                )));
            }
        }
    }
    for key in ["columns", "rows"] {
        if let Some(v) = opts.get(key) {
            let parsed: u8 = v.parse().map_err(|_| {
                Error::InvalidOption(format!(
                    "micropdf417: {key}={v:?} must be a non-negative integer"
                ))
            })?;
            if parsed != 0 {
                // Explicit columns/rows override the corresponding
                // component of `version=RxC` (BWIPP processes them in
                // order; the last write wins).
                if key == "columns" {
                    size.ucols = parsed;
                } else {
                    size.urows = parsed;
                }
            }
        }
    }
    Ok((mode, size))
}

pub fn encode(data: &str, opts: &Options) -> Result<BitMatrix, Error> {
    let (mode, size) = check_micropdf417_opts(opts)?;
    match mode {
        MicroPdf417Mode::Auto => {
            render_constrained(data.as_bytes(), size).map_err(Error::InvalidData)
        }
        MicroPdf417Mode::Ccb => render_ccb_constrained(data.as_bytes(), size)
            .map(|(bm, _)| bm)
            .map_err(Error::InvalidData),
        MicroPdf417Mode::Cca => {
            let codewords = parse_raw_codewords(data.as_bytes()).map_err(Error::InvalidData)?;
            render_cca_constrained(&codewords, size)
                .map(|(bm, _)| bm)
                .map_err(Error::InvalidData)
        }
        MicroPdf417Mode::Raw => {
            let codewords = parse_raw_codewords(data.as_bytes()).map_err(Error::InvalidData)?;
            render_raw_codewords_constrained(&codewords, size).map_err(Error::InvalidData)
        }
        MicroPdf417Mode::Parse => {
            let substituted = parse_text_escapes(data.as_bytes()).map_err(Error::InvalidData)?;
            render_constrained(&substituted, size).map_err(Error::InvalidData)
        }
        MicroPdf417Mode::Parsefnc => {
            let (eci_codewords, substituted) =
                parse_text_parsefnc(data.as_bytes()).map_err(Error::InvalidData)?;
            if eci_codewords.is_empty() {
                render_constrained(&substituted, size).map_err(Error::InvalidData)
            } else {
                render_with_eci_prefix_constrained(&eci_codewords, &substituted, size)
                    .map_err(Error::InvalidData)
            }
        }
    }
}

/// Constraint-aware variant of [`render`]. Threads `SizeConstraints`
/// through to the metric selector so `version=RxC`, `columns=N`, and
/// `rows=N` actually narrow the auto-select loop. With
/// `size.is_default()` it behaves identically to [`render`].
fn render_constrained(input: &[u8], size: SizeConstraints) -> Result<BitMatrix, String> {
    if size.is_default() {
        return render(input);
    }
    let datcws = data_codewords(input)?;
    let metric =
        select_metric_constrained(datcws.len(), size.ucols, size.urows).ok_or_else(|| {
            format!(
                "MicroPDF417: no metric for {} datcws with constraints \
                 columns={} rows={}",
                datcws.len(),
                size.ucols,
                size.urows,
            )
        })?;
    let (c, r, k, _, _, _) = metric;
    let (c, r, k) = (c as usize, r as usize, k as usize);
    let n = c * r - k;
    let mut cws: Vec<u16> = Vec::with_capacity(c * r);
    cws.extend_from_slice(&datcws);
    cws.resize(n, 900);
    let check = crate::util::rs_gf929::encode(&cws[..n], k);
    cws.extend_from_slice(&check);
    debug_assert_eq!(cws.len(), c * r);
    render_cws(&cws, metric)
}

/// Constraint-aware variant of [`render_ccb`].
fn render_ccb_constrained(
    bytes: &[u8],
    size: SizeConstraints,
) -> Result<(BitMatrix, Metric), String> {
    if size.is_default() {
        return render_ccb(bytes, 0);
    }
    let datcws = pack_ccb_datcws(bytes);
    let metric =
        select_metric_constrained(datcws.len(), size.ucols, size.urows).ok_or_else(|| {
            format!(
                "CC-B: no metric for {} datcws with constraints \
                 columns={} rows={}",
                datcws.len(),
                size.ucols,
                size.urows,
            )
        })?;
    let (c, r, k, _, _, _) = metric;
    let (c, r, k) = (c as usize, r as usize, k as usize);
    let n = c * r - k;
    let mut cws: Vec<u16> = Vec::with_capacity(c * r);
    cws.extend_from_slice(&datcws);
    cws.resize(n, 900);
    let check = crate::util::rs_gf929::encode(&cws[..n], k);
    cws.extend_from_slice(&check);
    let bm = render_cws(&cws, metric)?;
    Ok((bm, metric))
}

/// Constraint-aware variant of [`render_cca`].
fn render_cca_constrained(
    cws_in: &[u32],
    size: SizeConstraints,
) -> Result<(BitMatrix, Metric), String> {
    if size.is_default() {
        return render_cca(cws_in, 0);
    }
    let metric =
        select_cca_metric_constrained(cws_in.len(), size.ucols, size.urows).ok_or_else(|| {
            format!(
                "CC-A: no metric for {} codewords with constraints \
                 columns={} rows={}",
                cws_in.len(),
                size.ucols,
                size.urows,
            )
        })?;
    let (c, r, k, _, _, _) = metric;
    let (c, r, k) = (c as usize, r as usize, k as usize);
    let n = c * r - k;
    let mut cws: Vec<u16> = cws_in.iter().map(|&v| v as u16).collect();
    cws.resize(n, 900);
    let check = crate::util::rs_gf929::encode(&cws[..n], k);
    cws.extend_from_slice(&check);
    debug_assert_eq!(cws.len(), c * r);
    let bm = render_cca_cws(&cws, metric)?;
    Ok((bm, metric))
}

/// Constraint-aware variant of [`render_raw_codewords`].
fn render_raw_codewords_constrained(
    cws_in: &[u32],
    size: SizeConstraints,
) -> Result<BitMatrix, String> {
    if size.is_default() {
        return render_raw_codewords(cws_in);
    }
    let metric =
        select_metric_constrained(cws_in.len(), size.ucols, size.urows).ok_or_else(|| {
            format!(
                "micropdf417 raw: no metric for {} codewords with constraints \
                 columns={} rows={}",
                cws_in.len(),
                size.ucols,
                size.urows,
            )
        })?;
    let (c, r, k, _, _, _) = metric;
    let (c, r, k) = (c as usize, r as usize, k as usize);
    let n = c * r - k;
    let mut cws: Vec<u16> = cws_in.iter().map(|&v| v as u16).collect();
    cws.resize(n, 900);
    let check = crate::util::rs_gf929::encode(&cws[..n], k);
    cws.extend_from_slice(&check);
    debug_assert_eq!(cws.len(), c * r);
    render_cws(&cws, metric)
}

/// Constraint-aware variant of [`render_with_eci_prefix`].
fn render_with_eci_prefix_constrained(
    eci_codewords: &[u16],
    text_bytes: &[u8],
    size: SizeConstraints,
) -> Result<BitMatrix, String> {
    if size.is_default() {
        return render_with_eci_prefix(eci_codewords, text_bytes);
    }
    let text_datcws = data_codewords(text_bytes)?;
    let mut datcws: Vec<u16> = Vec::with_capacity(eci_codewords.len() + text_datcws.len());
    datcws.extend_from_slice(eci_codewords);
    datcws.extend_from_slice(&text_datcws);
    let metric =
        select_metric_constrained(datcws.len(), size.ucols, size.urows).ok_or_else(|| {
            format!(
                "MicroPDF417 parsefnc: no metric for {} datcws with constraints \
                 columns={} rows={}",
                datcws.len(),
                size.ucols,
                size.urows,
            )
        })?;
    let (c, r, k, _, _, _) = metric;
    let (c, r, k) = (c as usize, r as usize, k as usize);
    let n = c * r - k;
    let mut cws: Vec<u16> = Vec::with_capacity(c * r);
    cws.extend_from_slice(&datcws);
    cws.resize(n, 900);
    let check = crate::util::rs_gf929::encode(&cws[..n], k);
    cws.extend_from_slice(&check);
    debug_assert_eq!(cws.len(), c * r);
    render_cws(&cws, metric)
}

/// Render a pre-parsed raw codeword stream using the standalone
/// (non-CCA) MicroPDF417 metric table — the implementation behind
/// `raw=true`. Mirrors BWIPP `bwipp_micropdf417` lines 24604-24622
/// with `cca=false` (so the metric loop uses `nonccametrics`).
fn render_raw_codewords(cws_in: &[u32]) -> Result<BitMatrix, String> {
    let metric = select_metric(cws_in.len()).ok_or_else(|| {
        format!(
            "micropdf417 raw: {} codewords doesn't fit any non-CCA metric",
            cws_in.len(),
        )
    })?;
    let (c, r, k, _, _, _) = metric;
    let c = c as usize;
    let r = r as usize;
    let k = k as usize;
    let n = c * r - k;
    let mut cws: Vec<u16> = cws_in.iter().map(|&v| v as u16).collect();
    // Pad with 900 to n codewords, then RS-ECC.
    cws.resize(n, 900);
    let check = crate::util::rs_gf929::encode(&cws[..n], k);
    cws.extend_from_slice(&check);
    debug_assert_eq!(cws.len(), c * r);
    render_cws(&cws, metric)
}

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

    /// Goldens captured via `tools/oracle-micropdf417.js`. Each tuple
    /// is `(text, expected_datcws, expected_cws, expected_metric)`.
    fn goldens() -> &'static [(&'static str, &'static [u16], &'static [u16], Metric)] {
        &[
            (
                "PDF417",
                &[900, 453, 178, 121, 239],
                &[
                    900, 453, 178, 121, 239, 900, 900, 393, 904, 95, 716, 3, 811, 744,
                ],
                (1, 14, 7, 8, 0, 8),
            ),
            (
                "Hello, World!",
                &[900, 237, 131, 344, 883, 807, 674, 521, 119, 329],
                &[
                    900, 237, 131, 344, 883, 807, 674, 521, 119, 329, 899, 128, 32, 538, 603, 7,
                    568,
                ],
                (1, 17, 7, 36, 0, 36),
            ),
            (
                "1234567890",
                &[902, 15, 369, 753, 190],
                &[
                    902, 15, 369, 753, 190, 900, 900, 467, 14, 648, 330, 592, 604, 219,
                ],
                (1, 14, 7, 8, 0, 8),
            ),
        ]
    }

    #[test]
    fn select_cca_metric_picks_smallest_fitting() {
        // Stage 11.A8c (cont) — `.unwrap()` → `.expect(...)` naming the
        // CC-A metric geometry it must return for each (ncws, ucols)
        // request.
        // For 8 codewords with ucols=4, smallest CCA fit is the 4×3 row
        // (c=4, r=3, k=4 → ncws=8). It's the first row with c=4 in the
        // table.
        let m = select_cca_metric(8, 4)
            .expect("select_cca_metric(8 cws, ucols=4) must return Some((c=4, r=3, k=4, ..)) — smallest 4-col fit");
        assert_eq!(m, (4, 3, 4, 40, 20, 52));
        // For 8 codewords with ucols=2, smallest is the 2×6 row
        // (c=2, r=6, k=4 → ncws=8): the 2nd row of CCA_METRICS.
        let m = select_cca_metric(8, 2)
            .expect("select_cca_metric(8 cws, ucols=2) must return Some((c=2, r=6, k=4, ..)) — smallest 2-col fit (2nd row of CCA_METRICS)");
        assert_eq!(m, (2, 6, 4, 1, 0, 33));
        // 100 codewords doesn't fit any CC-A size.
        assert!(
            select_cca_metric(100, 4).is_none(),
            "select_cca_metric(100 cws, ucols=4) must return None — 100 exceeds the largest CC-A metric capacity at any column count"
        );
    }

    #[test]
    fn render_cca_matches_bwip_js_gtin() {
        // (01)12345678901231 via gs1_cc method "0" CC-A 4-col.
        // Oracle (oracle-cca-pixs.js): rwid=99 rows=3, 297-cell pixs
        // verified byte-for-byte vs bwip-js on 2026-05-19.
        // Stage 11.A8c (cont) — `.unwrap()` → `.expect(...)` naming
        // gs1_cc encode + render path.
        let enc = crate::symbology::gs1_cc::encode_cc("(01)12345678901231", 4).expect(
            "gs1_cc::encode_cc(\"(01)12345678901231\", 4 cols) (canonical GTIN-14 via CC-A method 0) must succeed",
        );
        let (bm, metric) = super::render_cca(&enc.codewords, 4).expect(
            "render_cca(cws, ucols=4) (CC-A render at 4 columns, expected (4,3,4,..) metric → rwid=99 rows=3, 297-cell pixs) must succeed",
        );
        assert_eq!(metric, (4, 3, 4, 40, 20, 52));
        let want: [u8; 297] = [
            1, 1, 0, 1, 1, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 1, 0, 0, 1, 1,
            0, 1, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 1, 1, 1, 0, 1, 0, 0, 1, 0, 1, 0,
            0, 0, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0, 0, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 0, 0, 1, 0, 0, 0,
            0, 1, 1, 0, 1, 1, 0, 0, 0, 1, 0, 1, 1, 1, 0, 1, 1, 0, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1,
            0, 0, 1, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, 1, 1, 1, 1, 0, 0, 1, 0, 1, 1, 1, 1, 0, 1, 0,
            0, 1, 1, 0, 0, 1, 0, 0, 1, 1, 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 0, 0, 0, 0, 0, 1, 1, 1, 0,
            1, 0, 1, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 1, 0, 1, 1,
            0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 1, 1, 0, 0, 1, 1, 1, 1, 0, 1, 1, 0, 0, 0, 1, 1,
            1, 1, 1, 0, 0, 1, 0, 0, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0,
            1, 0, 0, 0, 1, 1, 1, 0, 1, 0, 1, 1, 0, 0, 0, 0, 1, 0, 1, 1, 1, 0, 0, 0, 0, 1, 1, 1, 0,
            1, 0, 0, 0, 1, 0, 1,
        ];
        for y in 0..3 {
            for x in 0..99 {
                let got = u8::from(bm.get(x, y));
                let w = want[y * 99 + x];
                assert_eq!(got, w, "mismatch at ({x}, {y})");
            }
        }
    }

    #[test]
    fn render_cca_smoke_test() {
        // Encode "(01)12345678901231" via gs1_cc → render via CC-A.
        // Just verify the symbol has the right dimensions.
        // Stage 11.A8c (cont) — `.unwrap()` → `.expect(...)` naming
        // dimension-only smoke-test path.
        let enc = crate::symbology::gs1_cc::encode_cc("(01)12345678901231", 4).expect(
            "gs1_cc::encode_cc(\"(01)12345678901231\", 4 cols) (dimension-only smoke-test setup) must succeed",
        );
        let cws: Vec<u32> = enc.codewords;
        // 8 cws @ cols=4 → metric (4, 3, 4, ...). 4*3 = 12 ncws total.
        let (bm, metric) = super::render_cca(&cws, 4).expect(
            "render_cca(8 cws, ucols=4) (dimension-only smoke-test, expecting CCA_ROW_WIDTHS[2]=99 wide × 3 tall) must succeed",
        );
        assert_eq!(metric, (4, 3, 4, 40, 20, 52));
        assert_eq!(bm.width(), super::CCA_ROW_WIDTHS[2]); // 99
        assert_eq!(bm.height(), 3);
    }

    #[test]
    fn data_codewords_match_bwip_js() {
        for &(text, want, _, _) in goldens() {
            let got = data_codewords(text.as_bytes()).unwrap();
            assert_eq!(got, want, "datcws mismatch for {text:?}");
        }
    }

    #[test]
    fn cws_compose_matches_bwip_js() {
        for &(text, _, want_cws, want_metric) in goldens() {
            let (got_cws, got_metric) = cws_compose(text.as_bytes()).unwrap();
            assert_eq!(got_cws, want_cws, "cws mismatch for {text:?}");
            assert_eq!(got_metric, want_metric, "metric mismatch for {text:?}");
        }
    }

    #[test]
    fn select_metric_picks_smallest_fit() {
        // 5 codewords → first row (1×11, capacity 4 — too small) →
        // skip to 1×14 (capacity 7). Matches "PDF417" golden.
        assert_eq!(select_metric(5), Some((1, 14, 7, 8, 0, 8)));
        // 10 codewords → 1×17 (capacity 10). Matches "Hello, World!".
        assert_eq!(select_metric(10), Some((1, 17, 7, 36, 0, 36)));
        // Just over the largest non-CCA capacity (4×44 → 176) returns
        // None.
        assert_eq!(select_metric(177), None);
    }

    /// Full-symbol pixs golden for `"PDF417"` (c=1, r=14, rwid=38).
    /// Captured via `tools/oracle-micropdf417.js "PDF417"` from
    /// bwip-js's `$_.pixs` array right after the row-fill loop and
    /// before renmatrix consumes it.
    #[test]
    fn render_matches_bwip_js_pixs_c1() {
        #[rustfmt::skip]
        let want_pixs: [u8; 532] = [
            1, 1, 1, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1,
            1, 1, 0, 1, 0, 1, 1, 0, 0, 0, 0, 1, 1, 1, 0, 1,
            1, 1, 0, 1, 0, 1, 1, 1, 1, 0, 0, 1, 1, 0, 1, 0,
            1, 0, 1, 1, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 1,
            0, 1, 1, 1, 0, 0, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1,
            0, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 0, 1,
            0, 1, 1, 1, 1, 0, 0, 1, 1, 1, 1, 0, 1, 1, 0, 1,
            0, 1, 1, 1, 1, 1, 0, 0, 1, 0, 1, 0, 1, 1, 1, 1,
            0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 1, 1, 1,
            1, 0, 0, 1, 0, 1, 0, 1, 1, 1, 1, 0, 0, 0, 1, 0,
            1, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 1, 1,
            0, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 1, 0, 1, 1, 1,
            0, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0, 0, 1, 1, 0,
            0, 0, 1, 1, 0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0, 1,
            0, 1, 0, 1, 1, 1, 0, 0, 0, 1, 1, 0, 1, 0, 1, 0,
            1, 1, 1, 1, 1, 1, 0, 1, 0, 1, 1, 0, 0, 0, 0, 1,
            1, 0, 0, 0, 1, 1, 0, 1, 0, 1, 1, 1, 0, 0, 0, 1,
            0, 0, 1, 0, 1, 0, 1, 1, 1, 0, 0, 1, 0, 1, 1, 0,
            0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 1, 0, 0, 1, 0, 1,
            1, 1, 1, 0, 0, 1, 0, 0, 1, 0, 1, 0, 0, 0, 0, 1,
            1, 0, 0, 0, 1, 1, 0, 0, 0, 1, 0, 1, 1, 1, 0, 0,
            1, 0, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 0, 0, 1, 0,
            1, 1, 1, 1, 0, 1, 0, 0, 1, 1, 1, 0, 0, 1, 1, 1,
            0, 1, 1, 1, 1, 0, 1, 0, 0, 1, 0, 1, 1, 1, 1, 1,
            0, 1, 0, 1, 1, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0,
            0, 1, 0, 1, 1, 1, 0, 1, 1, 1, 1, 0, 1, 0, 1, 1,
            0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 0, 1, 1, 1, 0,
            1, 0, 1, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 1, 1, 1,
            1, 0, 1, 0, 1, 0, 0, 1, 1, 1, 1, 0, 0, 1, 0, 1,
            0, 0, 1, 1, 0, 0, 0, 0, 0, 1, 0, 1, 1, 1, 0, 0,
            0, 1, 0, 1, 1, 1, 0, 0, 1, 0, 1, 0, 0, 1, 1, 1,
            1, 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 1, 1, 1, 1, 1,
            0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 1, 1, 0, 1, 1, 0,
            1, 0, 0, 1,
        ];
        let bm = render(b"PDF417").unwrap();
        assert_eq!(bm.width(), 38);
        assert_eq!(bm.height(), 14);
        let mut got: Vec<u8> = Vec::with_capacity(bm.width() * bm.height());
        for y in 0..bm.height() {
            for x in 0..bm.width() {
                got.push(bm.get(x, y) as u8);
            }
        }
        assert_eq!(got, want_pixs);
    }

    /// Full-symbol pixs golden for `"Hello, World!"` forced to a 2-
    /// column symbol (c=2, r=11, rwid=55, k=9). Captured via
    /// `tools/oracle-micropdf417.js "Hello, World!" 2`. The Rust
    /// `render` auto-selects c=1 for this short payload, so the test
    /// drives `render_cws` directly with the cws bwip-js produced
    /// when forced to c=2.
    #[test]
    fn render_matches_bwip_js_pixs_c2() {
        let cws_c2: [u16; 22] = [
            900, 237, 131, 344, 883, 807, 674, 521, 119, 329, 900, 900, 900, 640, 562, 805, 162,
            290, 508, 845, 886, 7,
        ];
        let metric_c2: Metric = (2, 11, 9, 1, 0, 9);
        #[rustfmt::skip]
        let want_pixs: [u8; 605] = [
            1, 1, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 1,
            1, 0, 0, 0, 1, 1, 0, 0, 1, 0, 0, 1, 1, 1, 1, 0,
            1, 1, 0, 0, 1, 0, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0,
            0, 1, 1, 0, 1, 0, 1, 1, 1, 1, 0, 1, 0, 0, 0, 1,
            0, 1, 1, 1, 1, 0, 1, 0, 0, 0, 1, 1, 0, 1, 1, 0,
            0, 0, 1, 0, 1, 1, 0, 0, 1, 0, 0, 1, 1, 1, 1, 1,
            1, 0, 0, 1, 1, 1, 1, 0, 1, 1, 0, 1, 0, 1, 1, 1,
            1, 0, 1, 1, 0, 0, 1, 0, 1, 1, 1, 0, 0, 0, 1, 1,
            1, 1, 1, 0, 1, 0, 1, 1, 0, 1, 0, 0, 1, 1, 1, 1,
            1, 0, 1, 1, 0, 1, 0, 0, 0, 0, 1, 1, 1, 1, 0, 0,
            1, 0, 1, 0, 1, 1, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1,
            1, 0, 0, 1, 1, 1, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0,
            1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0,
            0, 1, 1, 1, 0, 0, 0, 1, 0, 1, 0, 1, 1, 1, 0, 1,
            1, 1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 1, 1, 1, 1,
            1, 0, 1, 1, 1, 0, 0, 1, 0, 1, 1, 0, 1, 1, 1, 1,
            1, 0, 0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0, 1, 0,
            1, 0, 1, 1, 1, 0, 1, 1, 1, 1, 0, 1, 0, 1, 1, 0,
            0, 0, 1, 1, 1, 1, 1, 0, 0, 1, 0, 0, 1, 0, 1, 1,
            0, 0, 0, 1, 1, 1, 1, 1, 0, 0, 1, 0, 0, 1, 0, 1,
            1, 0, 0, 0, 1, 1, 0, 1, 0, 1, 1, 1, 0, 0, 1, 1,
            1, 0, 1, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 1, 1,
            0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 1, 1, 0, 1, 1, 0,
            0, 0, 0, 1, 1, 0, 1, 1, 0, 0, 0, 1, 0, 0, 1, 0,
            1, 1, 1, 1, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1,
            0, 1, 1, 0, 1, 1, 1, 1, 1, 1, 0, 0, 1, 1, 1, 1,
            0, 0, 0, 0, 0, 1, 0, 1, 1, 0, 1, 1, 0, 1, 1, 1,
            0, 0, 1, 0, 0, 1, 0, 1, 1, 1, 1, 0, 0, 1, 1, 0,
            1, 0, 1, 1, 1, 0, 0, 1, 0, 1, 1, 1, 1, 1, 0, 0,
            0, 1, 0, 1, 0, 1, 1, 0, 0, 0, 0, 0, 1, 1, 0, 1,
            1, 1, 1, 0, 1, 1, 1, 1, 0, 1, 0, 0, 1, 0, 1, 1,
            1, 1, 1, 0, 1, 1, 0, 1, 0, 1, 1, 1, 0, 0, 1, 1,
            0, 0, 0, 1, 0, 1, 1, 0, 0, 0, 1, 1, 1, 0, 0, 0,
            1, 1, 1, 0, 1, 0, 1, 0, 0, 0, 0, 1, 1, 1, 1, 0,
            1, 0, 1, 1, 0, 1, 1, 1, 1, 1, 0, 0, 1, 0, 1, 0,
            1, 1, 1, 0, 0, 0, 0, 0, 1, 1, 0, 1, 1, 1, 0, 1,
            0, 1, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 0, 0, 1, 1,
            1, 0, 1, 1, 1, 1, 0, 1, 0, 1, 0, 0, 1,
        ];
        let bm = render_cws(&cws_c2, metric_c2).unwrap();
        assert_eq!(bm.width(), 55);
        assert_eq!(bm.height(), 11);
        let mut got: Vec<u8> = Vec::with_capacity(bm.width() * bm.height());
        for y in 0..bm.height() {
            for x in 0..bm.width() {
                got.push(bm.get(x, y) as u8);
            }
        }
        assert_eq!(got, want_pixs);
    }

    /// `"Hello, World!"` forced to c=3 (3×8, k=14, rwid=82, non-CCA).
    /// Captured via `tools/oracle-micropdf417.js "Hello, World!" 3`.
    /// Exercises the centre-RAP code path that c=1/c=2 don't reach.
    #[test]
    fn render_matches_bwip_js_pixs_c3() {
        let cws_c3: [u16; 24] = [
            900, 237, 131, 344, 883, 807, 674, 521, 119, 329, 844, 915, 199, 454, 360, 748, 341,
            841, 760, 135, 444, 2, 762, 884,
        ];
        let metric_c3: Metric = (3, 8, 14, 7, 7, 7);
        #[rustfmt::skip]
        let want_pixs: [u8; 656] = [
            1, 1, 0, 0, 1, 1, 1, 0, 1, 0, 1, 0, 0, 0, 0, 1,
            1, 0, 0, 0, 1, 1, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0,
            1, 0, 1, 1, 0, 1, 1, 1, 1, 0, 1, 1, 0, 0, 1, 0,
            0, 1, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 0, 0, 0, 1,
            0, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 1, 0, 1,
            0, 1, 1, 1, 1, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1,
            0, 0, 1, 0, 0, 1, 1, 1, 1, 1, 1, 0, 0, 1, 0, 0,
            0, 0, 1, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0,
            1, 1, 1, 1, 0, 0, 1, 0, 1, 1, 1, 0, 0, 0, 0, 0,
            1, 0, 1, 1, 0, 0, 0, 1, 0, 1, 1, 1, 0, 1, 1, 1,
            0, 1, 0, 1, 1, 1, 1, 0, 0, 1, 1, 0, 1, 0, 1, 0,
            0, 1, 1, 1, 1, 0, 1, 1, 0, 0, 0, 1, 1, 0, 0, 1,
            0, 0, 0, 0, 1, 1, 0, 1, 0, 1, 1, 1, 0, 1, 1, 1,
            1, 0, 1, 0, 0, 1, 1, 1, 0, 0, 1, 1, 1, 1, 1, 0,
            1, 0, 0, 0, 0, 1, 1, 1, 0, 1, 0, 1, 1, 1, 0, 0,
            1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 0, 1, 0,
            1, 1, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0,
            0, 1, 0, 0, 0, 1, 1, 1, 0, 1, 0, 1, 0, 0, 0, 0,
            1, 1, 0, 1, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 1,
            0, 0, 1, 1, 1, 1, 0, 0, 1, 0, 0, 1, 0, 1, 1, 1,
            1, 0, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 0, 1, 0,
            1, 0, 1, 1, 0, 1, 0, 0, 0, 0, 0, 1, 1, 1, 0, 0,
            0, 1, 0, 1, 0, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 1,
            1, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0, 0, 0, 1, 1,
            1, 0, 1, 1, 0, 0, 1, 1, 1, 0, 1, 0, 0, 0, 0, 1,
            1, 1, 1, 0, 0, 1, 0, 1, 0, 1, 1, 1, 1, 0, 0, 0,
            1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 0, 0, 1, 1,
            0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1,
            1, 1, 1, 1, 1, 0, 0, 1, 1, 0, 1, 1, 1, 0, 1, 0,
            1, 0, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 0, 1,
            0, 1, 1, 1, 0, 0, 0, 1, 0, 1, 0, 1, 1, 1, 0, 0,
            0, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1,
            0, 0, 1, 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 0, 1,
            0, 1, 0, 1, 0, 0, 0, 0, 0, 1, 1, 0, 1, 1, 0, 0,
            0, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 0, 0, 0, 0, 0,
            1, 0, 0, 1, 1, 0, 0, 0, 0, 1, 0, 1, 0, 1, 1, 1,
            0, 0, 0, 1, 1, 0, 1, 0, 1, 1, 1, 1, 0, 1, 0, 1,
            0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 1, 1, 1, 0,
            0, 1, 0, 1, 0, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1,
            0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 1, 1, 0,
            1, 1, 0, 1, 0, 1, 1, 0, 0, 0, 1, 1, 0, 1, 0, 1,
        ];
        let bm = render_cws(&cws_c3, metric_c3).unwrap();
        assert_eq!(bm.width(), 82);
        assert_eq!(bm.height(), 8);
        let mut got: Vec<u8> = Vec::with_capacity(bm.width() * bm.height());
        for y in 0..bm.height() {
            for x in 0..bm.width() {
                got.push(bm.get(x, y) as u8);
            }
        }
        assert_eq!(got, want_pixs);
    }

    /// `"Hello, World!"` forced to c=4 (4×6, k=12, rwid=99). Captured
    /// via `tools/oracle-micropdf417.js "Hello, World!" 4`. Exercises
    /// the longest non-CCA row layout.
    #[test]
    fn render_matches_bwip_js_pixs_c4() {
        let cws_c4: [u16; 24] = [
            900, 237, 131, 344, 883, 807, 674, 521, 119, 329, 900, 900, 827, 207, 535, 470, 340,
            64, 712, 198, 866, 136, 221, 283,
        ];
        let metric_c4: Metric = (4, 6, 12, 1, 1, 1);
        #[rustfmt::skip]
        let want_pixs: [u8; 594] = [
            1, 1, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 1,
            1, 0, 0, 0, 1, 1, 0, 0, 1, 0, 0, 1, 1, 1, 1, 0,
            1, 1, 0, 0, 1, 0, 0, 1, 1, 1, 0, 0, 1, 0, 1, 1,
            0, 0, 1, 1, 1, 0, 1, 1, 0, 1, 0, 0, 0, 0, 0, 1,
            0, 0, 0, 1, 1, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0,
            1, 1, 0, 1, 1, 0, 0, 0, 1, 1, 0, 0, 1, 0, 0, 0,
            1, 0, 1, 1, 1, 1, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0,
            0, 0, 0, 0, 1, 0, 1, 1, 1, 1, 0, 0, 1, 0, 1, 1,
            1, 0, 0, 0, 0, 0, 1, 0, 1, 1, 0, 0, 0, 1, 0, 1,
            0, 0, 1, 0, 0, 1, 1, 1, 0, 1, 1, 1, 0, 0, 0, 0,
            1, 0, 1, 1, 0, 0, 0, 1, 0, 0, 1, 1, 1, 0, 0, 1,
            1, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 1, 1, 1, 0, 1,
            0, 0, 0, 1, 0, 1, 1, 1, 1, 0, 1, 1, 0, 0, 1, 0,
            1, 1, 1, 1, 1, 0, 1, 0, 0, 0, 0, 1, 1, 1, 0, 1,
            0, 1, 0, 0, 0, 1, 0, 0, 1, 0, 1, 1, 1, 1, 0, 0,
            0, 0, 1, 0, 0, 1, 1, 0, 1, 1, 1, 0, 1, 1, 0, 0,
            0, 1, 1, 1, 1, 1, 0, 0, 1, 0, 0, 1, 0, 1, 1, 0,
            0, 0, 1, 1, 1, 1, 1, 0, 0, 1, 0, 0, 1, 0, 1, 1,
            1, 0, 1, 1, 0, 0, 1, 0, 1, 1, 1, 0, 0, 1, 1, 0,
            0, 1, 0, 1, 1, 0, 0, 0, 0, 1, 1, 0, 1, 1, 0, 1,
            1, 0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 1, 0, 1, 1, 0,
            0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 1, 0, 1,
            0, 0, 1, 1, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0,
            1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0,
            0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 1, 0, 1,
            1, 1, 0, 0, 1, 0, 1, 1, 1, 1, 1, 1, 0, 1, 1, 0,
            0, 1, 0, 1, 1, 0, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1,
            1, 0, 0, 1, 1, 1, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1,
            1, 0, 1, 1, 0, 0, 0, 1, 1, 0, 1, 1, 1, 1, 0, 1,
            0, 0, 0, 1, 1, 0, 1, 0, 0, 0, 0, 0, 1, 1, 1, 0,
            0, 1, 0, 0, 1, 1, 0, 1, 1, 1, 0, 0, 1, 0, 1, 1,
            1, 0, 1, 1, 1, 1, 0, 1, 0, 1, 0, 0, 0, 0, 0, 1,
            1, 1, 0, 1, 0, 1, 1, 0, 0, 0, 1, 1, 0, 0, 1, 0,
            1, 0, 0, 0, 1, 1, 1, 1, 1, 0, 0, 1, 0, 0, 0, 1,
            1, 0, 1, 1, 0, 1, 1, 0, 0, 1, 0, 0, 1, 1, 1, 1,
            1, 1, 0, 0, 1, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 1,
            0, 0, 1, 1, 1, 1, 0, 1, 1, 0, 1, 1, 1, 1, 0, 1,
            0, 1,
        ];
        let bm = render_cws(&cws_c4, metric_c4).unwrap();
        assert_eq!(bm.width(), 99);
        assert_eq!(bm.height(), 6);
        let mut got: Vec<u8> = Vec::with_capacity(bm.width() * bm.height());
        for y in 0..bm.height() {
            for x in 0..bm.width() {
                got.push(bm.get(x, y) as u8);
            }
        }
        assert_eq!(got, want_pixs);
    }

    /// The RAPs table is part of the symbol-level metadata that the
    /// renderer will consume; this test just freezes the first and
    /// last few values so a botched copy/paste is caught immediately.
    #[test]
    fn raps_table_endpoints() {
        assert_eq!(RAPS[0][0], 802);
        assert_eq!(RAPS[0][51], 866);
        assert_eq!(RAPS[1][0], 718);
        assert_eq!(RAPS[1][51], 734);
    }

    #[test]
    fn pack_ccb_datcws_matches_bwip_js_oracle() {
        // For "(01)24012345678905|(10)BATCH(21)SERIAL1234567(91)EXTRADATAFORCC"
        // the gs1_cc CC-B byte stream produces these 30 datcws per bwip-js
        // (oracle-ccb-cws.js, captured 2026-05-19):
        //   [920, 901, 295, 741, 122, 515, 891, 327, 50, 671, 298, 425, 143,
        //    546, 297, 824, 583, 347, 49, 198, 652, 85, 313, 487, 186, 25,
        //    510, 16, 132, 33]
        // Use the gs1_cc encoder to produce the byte stream, then verify
        // pack_ccb_datcws produces the bwip-js datcws byte-for-byte.
        let (_linear, comp) = crate::symbology::composite::split_composite_input(
            "(01)24012345678905|(10)BATCH(21)SERIAL1234567(91)EXTRADATAFORCC",
        )
        .unwrap();
        let cc = crate::symbology::gs1_cc::encode_cc(comp, 4).unwrap();
        assert_eq!(cc.version, crate::symbology::gs1_cc::CcVersion::B);
        // CC-B codewords are bytes (0..256).
        let bytes: Vec<u8> = cc.codewords.iter().map(|&v| v as u8).collect();
        let datcws = pack_ccb_datcws(&bytes);
        let want: [u16; 30] = [
            920, 901, 295, 741, 122, 515, 891, 327, 50, 671, 298, 425, 143, 546, 297, 824, 583,
            347, 49, 198, 652, 85, 313, 487, 186, 25, 510, 16, 132, 33,
        ];
        assert_eq!(datcws, want.to_vec(), "CC-B datcws mismatch vs bwip-js");
    }

    /// Stage 11.A8c — pin `pack_ccb_datcws` arithmetic at the helper
    /// level (not via gs1_cc + oracle). Targets:
    ///
    ///   * `if rem == 0 { 924 } else { 901 }` boundary — verified by
    ///     0-byte (rem=0), 6-byte (rem=0), and 7-byte (rem=1) inputs.
    ///   * 920 prefix constant.
    ///   * 48-bit big-endian pack: comparing `[1,0,0,0,0,0]` vs
    ///     `[0,0,0,0,0,1]` (same byte set, opposite ends) yields very
    ///     different base-900 digits, killing any shift-direction mutation
    ///     on the `<<40`/`<<32`/.../`<<0` chain.
    ///   * Base-900 conversion + `iter().rev()` push order: hand-computed
    ///     for 6×0xFF: v = 0xFFFF_FFFF_FFFF = 281_474_976_710_655.
    ///     LOW→HIGH digits = [855, 222, 71, 11, 429] (verified:
    ///     281474976710655 % 900 = 855, /900=312749974122, %900=222,
    ///     /900=347499971, %900=71, /900=386111, %900=11, /900=429,
    ///     %900=429). Reversed for push: [429, 11, 71, 222, 855].
    ///     Mutations on `% 900` ↔ `/ 900` or `iter().rev()` direction
    ///     would change every cell.
    #[test]
    fn pack_ccb_datcws_narrow_arithmetic() {
        // Empty bytes: just the 920 prefix and the 924 group-aligned
        // continuation flag.
        assert_eq!(pack_ccb_datcws(&[]), vec![920u16, 924]);
        // Single byte (rem=1, no groups): 920 + 901 + raw byte.
        assert_eq!(pack_ccb_datcws(&[42]), vec![920u16, 901, 42]);
        // 6 zero bytes: one group, all digits 0; rem=0 → 924.
        assert_eq!(
            pack_ccb_datcws(&[0, 0, 0, 0, 0, 0]),
            vec![920u16, 924, 0, 0, 0, 0, 0]
        );
        // 6 0xFF bytes: hand-computed base-900 digits (see test doc).
        assert_eq!(
            pack_ccb_datcws(&[0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]),
            vec![920u16, 924, 429, 11, 71, 222, 855]
        );
        // Asymmetric pack: only byte 0 set vs only byte 5 set must
        // produce different digit streams (catches shift-direction
        // flips in the 48-bit pack).
        let only_msb = pack_ccb_datcws(&[1, 0, 0, 0, 0, 0]);
        let only_lsb = pack_ccb_datcws(&[0, 0, 0, 0, 0, 1]);
        assert_ne!(only_msb, only_lsb, "byte 0 vs byte 5 must differ");
        // Only-LSB: v=1 → digits = [1,0,0,0,0] LOW-to-HIGH → rev
        // [0,0,0,0,1]. Prefix [920, 924].
        assert_eq!(only_lsb, vec![920u16, 924, 0, 0, 0, 0, 1]);
        // 7-byte input (6-byte group + 1 trailing): rem=1 → 901.
        // First 6 zeros → digits [0,0,0,0,0]; trailing 42 → 42.
        assert_eq!(
            pack_ccb_datcws(&[0, 0, 0, 0, 0, 0, 42]),
            vec![920u16, 901, 0, 0, 0, 0, 0, 42]
        );
    }

    #[test]
    fn render_ccb_cws_matches_bwip_js_after_rs_ecc() {
        // Same input as above; bwip-js's full cws (datcws + 18 RS-ECC check
        // codewords for k=18, c=4, r=12) is:
        //   [920, 901, 295, 741, 122, 515, 891, 327, 50, 671, 298, 425, 143,
        //    546, 297, 824, 583, 347, 49, 198, 652, 85, 313, 487, 186, 25,
        //    510, 16, 132, 33, 548, 371, 837, 211, 271, 234, 345, 751, 858,
        //    512, 887, 804, 631, 488, 531, 153, 23, 116]
        let (_, comp) = crate::symbology::composite::split_composite_input(
            "(01)24012345678905|(10)BATCH(21)SERIAL1234567(91)EXTRADATAFORCC",
        )
        .unwrap();
        let cc = crate::symbology::gs1_cc::encode_cc(comp, 4).unwrap();
        let bytes: Vec<u8> = cc.codewords.iter().map(|&v| v as u8).collect();
        let (cws, metric) = ccb_cws_compose(&bytes, 4).unwrap();
        assert_eq!(metric, (4, 12, 18, 25, 25, 25));
        let want_check: [u16; 18] = [
            548, 371, 837, 211, 271, 234, 345, 751, 858, 512, 887, 804, 631, 488, 531, 153, 23, 116,
        ];
        assert_eq!(&cws[30..48], &want_check, "RS-ECC mismatch vs bwip-js");
        assert_eq!(cws.len(), 48);
    }

    /// Stage 11.4 — `encode(.., ccb=true)` now drives the same CC-B
    /// pipeline that the composite-codes path already uses. Pin the
    /// full bwip-js corpus (8 records captured via
    /// `rust/tools/oracle-micropdf417-opts.js`) so any drift in the
    /// dispatch shape or the byte-mode packer surfaces immediately.
    #[test]
    fn encode_ccb_matches_bwip_js_corpus() {
        // Each row: (input, datcws, cws, (c, r, k)).
        // Values are byte-for-byte against bwip-js 4.10.1.
        type CcbRow = (&'static str, &'static [u16], &'static [u16], (u8, u8, u8));
        let golden: &[CcbRow] = &[
            (
                "A",
                &[920, 901, 65],
                &[920, 901, 65, 900, 104, 433, 214, 488, 430, 798, 54],
                (1, 11, 7),
            ),
            (
                "ABC",
                &[920, 901, 65, 66, 67],
                &[
                    920, 901, 65, 66, 67, 900, 900, 627, 760, 860, 307, 924, 236, 543,
                ],
                (1, 14, 7),
            ),
            (
                "ABCDE",
                &[920, 901, 65, 66, 67, 68, 69],
                &[
                    920, 901, 65, 66, 67, 68, 69, 196, 173, 108, 78, 603, 262, 767,
                ],
                (1, 14, 7),
            ),
            (
                "ABCDEF",
                &[920, 924, 109, 326, 368, 127, 330],
                &[
                    920, 924, 109, 326, 368, 127, 330, 543, 96, 102, 553, 316, 639, 822,
                ],
                (1, 14, 7),
            ),
            (
                "ABCDEFG",
                &[920, 901, 109, 326, 368, 127, 330, 71],
                &[
                    920, 901, 109, 326, 368, 127, 330, 71, 900, 900, 135, 863, 777, 878, 861, 819,
                    293,
                ],
                (1, 17, 7),
            ),
            (
                "ABCDEFGHIJKL",
                &[920, 924, 109, 326, 368, 127, 330, 119, 411, 338, 47, 816],
                &[
                    920, 924, 109, 326, 368, 127, 330, 119, 411, 338, 47, 816, 232, 220, 183, 180,
                    681, 376, 562, 810,
                ],
                (1, 20, 8),
            ),
            (
                "ABCDEFGHIJKLMNOP",
                &[
                    920, 901, 109, 326, 368, 127, 330, 119, 411, 338, 47, 816, 77, 78, 79, 80,
                ],
                &[
                    920, 901, 109, 326, 368, 127, 330, 119, 411, 338, 47, 816, 77, 78, 79, 80, 142,
                    207, 419, 668, 743, 726, 848, 615,
                ],
                (1, 24, 8),
            ),
            (
                "ABCDEFGHIJKLMNOPQRSTUVWX",
                &[
                    920, 924, 109, 326, 368, 127, 330, 119, 411, 338, 47, 816, 129, 496, 307, 868,
                    402, 139, 581, 277, 788, 888,
                ],
                &[
                    920, 924, 109, 326, 368, 127, 330, 119, 411, 338, 47, 816, 129, 496, 307, 868,
                    402, 139, 581, 277, 788, 888, 900, 900, 381, 346, 202, 85, 160, 435, 498, 254,
                    657, 0,
                ],
                (2, 17, 10),
            ),
        ];
        for (text, want_datcws, want_cws, want_crk) in golden {
            let datcws = pack_ccb_datcws(text.as_bytes());
            assert_eq!(&datcws, want_datcws, "datcws mismatch for {text:?}");
            let (cws, metric) = ccb_cws_compose(text.as_bytes(), 0).unwrap();
            assert_eq!(&cws, want_cws, "cws mismatch for {text:?}");
            let (c, r, k, _, _, _) = metric;
            assert_eq!(
                (c, r, k),
                *want_crk,
                "metric (c, r, k) mismatch for {text:?}",
            );
            // End-to-end through the public `encode` with `ccb=true`.
            let bm = encode(text, &Options::default().with("ccb", "true"))
                .unwrap_or_else(|e| panic!("encode failed for {text:?}: {e:?}"));
            assert!(
                bm.width() > 0 && bm.height() > 0,
                "empty matrix for {text:?}",
            );
        }
    }

    /// Stage 11.4 — explicit `ccb=false` is equivalent to omitting the
    /// option entirely.
    #[test]
    fn encode_ccb_false_equivalent_to_default() {
        let a = encode("PDF417", &Options::default()).unwrap();
        let b = encode("PDF417", &Options::default().with("ccb", "false")).unwrap();
        assert_eq!(a.width(), b.width());
        assert_eq!(a.height(), b.height());
        // The BitMatrix doesn't expose its backing buffer, so verify
        // every cell instead.
        for y in 0..a.height() {
            for x in 0..a.width() {
                assert_eq!(a.get(x, y), b.get(x, y), "pixel mismatch at ({x},{y})");
            }
        }
    }

    /// Stage 11.4 — invalid `ccb` value returns `InvalidOption`.
    #[test]
    fn encode_ccb_rejects_invalid_value() {
        // Diagnostic at line 925:
        //   "micropdf417: ccb={v:?} must be \"true\" or \"false\""
        // 4-anchor pin upgrades the previous single-substring check:
        let err = encode("A", &Options::default().with("ccb", "maybe")).unwrap_err();
        match err {
            Error::InvalidOption(msg) => {
                assert!(
                    msg.contains("micropdf417:"),
                    "must carry the micropdf417 prefix; got {msg:?}"
                );
                assert!(
                    msg.contains("ccb=\"maybe\""),
                    "must Debug-echo the offending value; got {msg:?}"
                );
                assert!(
                    msg.contains("must be"),
                    "must carry the predicate; got {msg:?}"
                );
                assert!(
                    msg.contains("\"true\"") && msg.contains("\"false\""),
                    "must name BOTH valid values; got {msg:?}"
                );
                // Cross-option contamination guard: ccb diagnostic must
                // NOT pick up the cca-side wording (both options share
                // the same boolean-validation shape but with different
                // option names).
                assert!(
                    !msg.contains("cca="),
                    "ccb diagnostic must NOT leak cca-option wording; got {msg:?}"
                );
            }
            other => panic!("expected InvalidOption, got {other:?}"),
        }
    }

    /// Stage 11.5 — `cca=true` parses `^NNN` raw codewords, RS-encodes
    /// over the CC-A metric, and renders. Pin the full bwip-js corpus
    /// (5 records captured via `rust/tools/oracle-micropdf417-opts.js`).
    #[test]
    fn encode_cca_matches_bwip_js_corpus() {
        type CcaRow = (&'static str, &'static [u32], &'static [u16], (u8, u8, u8));
        // Each row: (input, parsed datcws, cws after RS, (c, r, k)).
        // Values are byte-for-byte against bwip-js 4.10.1.
        let golden: &[CcaRow] = &[
            (
                "^000^123^456^789^900",
                &[0, 123, 456, 789, 900],
                &[0, 123, 456, 789, 900, 900, 904, 445, 644, 131],
                (2, 5, 4),
            ),
            (
                "^001^002^003^004^005^006",
                &[1, 2, 3, 4, 5, 6],
                &[1, 2, 3, 4, 5, 6, 820, 514, 788, 278],
                (2, 5, 4),
            ),
            (
                "^010^020^030^040^050^060^070",
                &[10, 20, 30, 40, 50, 60, 70],
                &[10, 20, 30, 40, 50, 60, 70, 900, 298, 635, 657, 263],
                (2, 6, 4),
            ),
            (
                "^100^200^300^400^500^600^700^800^900^001^002^003",
                &[100, 200, 300, 400, 500, 600, 700, 800, 900, 1, 2, 3],
                &[
                    100, 200, 300, 400, 500, 600, 700, 800, 900, 1, 2, 3, 844, 726, 417, 104, 183,
                    168,
                ],
                (2, 9, 6),
            ),
            (
                "^928^000^928^000^928",
                &[928, 0, 928, 0, 928],
                &[928, 0, 928, 0, 928, 900, 363, 554, 450, 893],
                (2, 5, 4),
            ),
        ];
        for (text, want_datcws, want_cws, want_crk) in golden {
            // Stage 11.A8c — input-echoing failure-mode label so a
            // regression in the parser identifies WHICH corpus row
            // (e.g. which `^NNN^NNN…` escape sequence) failed.
            let datcws = parse_raw_codewords(text.as_bytes())
                .unwrap_or_else(|e| panic!("parse_raw_codewords({text:?}) failed: {e:?}"));
            assert_eq!(&datcws, want_datcws, "datcws mismatch for {text:?}");
            let (bm, metric) = render_cca(want_datcws, 0)
                .unwrap_or_else(|e| panic!("render_cca({text:?}) failed: {e}"));
            // Reconstruct the full cws (datcws + 900 padding + RS) the same
            // way `render_cca` does internally and verify against bwip-js.
            let (c, r, k, _, _, _) = metric;
            assert_eq!((c, r, k), *want_crk, "metric mismatch for {text:?}",);
            let n = (c as usize) * (r as usize) - (k as usize);
            let mut cws: Vec<u16> = want_datcws.iter().map(|&v| v as u16).collect();
            cws.resize(n, 900);
            let check = crate::util::rs_gf929::encode(&cws[..n], k as usize);
            cws.extend_from_slice(&check);
            assert_eq!(&cws, want_cws, "cws mismatch for {text:?}");
            // End-to-end through the public `encode` with `cca=true`.
            let bm_public = encode(text, &Options::default().with("cca", "true"))
                .unwrap_or_else(|e| panic!("encode failed for {text:?}: {e:?}"));
            assert_eq!(bm.width(), bm_public.width(), "width mismatch for {text:?}",);
            assert_eq!(
                bm.height(),
                bm_public.height(),
                "height mismatch for {text:?}",
            );
        }
    }

    /// Stage 11.5 — explicit `cca=false` is equivalent to omitting the
    /// option (and the input is text-encoded, not parsed as `^NNN`).
    #[test]
    fn encode_cca_false_equivalent_to_default() {
        let a = encode("PDF417", &Options::default()).unwrap();
        let b = encode("PDF417", &Options::default().with("cca", "false")).unwrap();
        assert_eq!(a.width(), b.width());
        assert_eq!(a.height(), b.height());
    }

    /// Stage 11.5 — invalid `cca` value returns `InvalidOption`.
    /// Diagnostic format mirrors the ccb sibling at line 925
    /// ("micropdf417: cca={v:?} must be \"true\" or \"false\""):
    /// 5-anchor pin with cross-option contamination guard against ccb=.
    #[test]
    fn encode_cca_rejects_invalid_value() {
        let err = encode("^001", &Options::default().with("cca", "maybe")).unwrap_err();
        match err {
            Error::InvalidOption(msg) => {
                assert!(
                    msg.contains("micropdf417:"),
                    "must carry the micropdf417 prefix; got {msg:?}"
                );
                assert!(
                    msg.contains("cca=\"maybe\""),
                    "must Debug-echo the offending value; got {msg:?}"
                );
                assert!(
                    msg.contains("must be"),
                    "must carry the predicate; got {msg:?}"
                );
                assert!(
                    msg.contains("\"true\"") && msg.contains("\"false\""),
                    "must name BOTH valid values; got {msg:?}"
                );
                // Cross-option contamination guard: cca diagnostic must
                // NOT pick up the ccb-side wording.
                assert!(
                    !msg.contains("ccb="),
                    "cca diagnostic must NOT leak ccb-option wording; got {msg:?}"
                );
            }
            other => panic!("expected InvalidOption, got {other:?}"),
        }
    }

    /// Stage 11.5 — `cca=true` + `ccb=true` is rejected (BWIPP error:
    /// "Cannot combine cca, ccb and raw", line 24048).
    #[test]
    fn encode_cca_and_ccb_combined_rejected() {
        let err = encode(
            "^001",
            &Options::default().with("cca", "true").with("ccb", "true"),
        )
        .unwrap_err();
        match err {
            Error::InvalidOption(msg) => assert!(
                msg.contains("cca") && msg.contains("ccb"),
                "msg was {msg:?}",
            ),
            other => panic!("expected InvalidOption, got {other:?}"),
        }
    }

    /// Stage 11.A8c — pin `parse_raw_codewords` happy-path arithmetic.
    /// The existing `_rejects_malformed` test covers error paths; the
    /// successful-parse arithmetic (the `value * 10 + (c - b'0')` MSB-
    /// first accumulator, the `<= 928` upper bound, and the 4-byte
    /// token stride) was only exercised transitively via the
    /// raw-corpus golden which uses specific real codewords.
    ///
    /// Mutations to catch:
    ///   - `value * 10` → `value + 10`: every 3-digit ordinal reads as
    ///     the sum-of-digits instead of base-10.
    ///   - `c - b'0'` → `c + b'0'`: ASCII codes accumulate (huge).
    ///   - `i += 4` → `i += 3`: off-by-one stride.
    ///   - `value > 928` → `>= 928`: rejects the boundary value 928.
    ///   - Boundary value 928 (max valid).
    #[test]
    fn parse_raw_codewords_happy_path_arithmetic() {
        // Empty input → empty vec.
        assert_eq!(parse_raw_codewords(b"").unwrap(), Vec::<u32>::new());

        // Single token at lower bound.
        assert_eq!(parse_raw_codewords(b"^000").unwrap(), vec![0]);

        // Single mid-range token: 123.
        assert_eq!(parse_raw_codewords(b"^123").unwrap(), vec![123]);

        // Upper bound — value=928 is the MAX VALID (catches `> 928` →
        // `>= 928` mutation).
        assert_eq!(parse_raw_codewords(b"^928").unwrap(), vec![928]);
        // Just above the bound — value=929 must error. Pin the diagnostic
        // here too (defense-in-depth with the dedicated rejection test
        // `parse_raw_codewords_rejects_malformed`): both sibling tests
        // now anchor the "0..=928" bound + "929" value echo, so dropping
        // the `{value}` interpolation OR mutating the bound text in the
        // format string would fail in BOTH places.
        let err_929 = parse_raw_codewords(b"^929").unwrap_err();
        assert!(
            err_929.contains("must be 0..=928"),
            "boundary+1 diagnostic must carry the bound; got {err_929:?}"
        );
        assert!(
            err_929.contains("929"),
            "boundary+1 diagnostic must echo the offending value 929; got {err_929:?}"
        );

        // Multiple tokens.
        assert_eq!(
            parse_raw_codewords(b"^001^002^900").unwrap(),
            vec![1, 2, 900]
        );
        assert_eq!(parse_raw_codewords(b"^900^928").unwrap(), vec![900, 928]);

        // MSB-first digit accumulator anchor: "^321" → 321, not 6 (sum)
        // or anything else. If `value * 10` → `value + 10`, then 3*10
        // + 2 = 32 + 1 = 33 ≠ 321.
        assert_eq!(
            parse_raw_codewords(b"^321").unwrap(),
            vec![321],
            "MSB-first base-10 accumulator (rejects `+` instead of `*`)"
        );
    }

    /// Stage 11.5 — `^NNN` parser rejects malformed inputs.
    ///
    /// Stage 11.A8c — upgrade from 4 weak `is_err()` checks to per-arm
    /// diagnostic-substring pins. The function has FOUR rejection arms
    /// (lines 805-838 of parse_raw_codewords):
    ///   1. bad prefix (input[i] != '^')   → "expected `^` at offset N, got 0xHH"
    ///   2. non-digit in 3-digit segment   → "non-digit 0xHH at offset N"
    ///   3. value > 928                    → "must be 0..=928; got V"
    ///   4. trailing partial token         → "N trailing byte(s) at offset M"
    ///
    /// All four arms share the "micropdf417: raw codewords" prefix but
    /// the path-specific tails distinguish them. A mutant that swaps
    /// any two arm bodies would survive the variant-only is_err()
    /// check (since the fn returns `Result<_, String>`, not even a
    /// variant tag is being checked). Each case now pins the
    /// path-specific substring AND the offset/byte echo to kill
    /// `{i}` / `{c:02X}` / `{value}` drops.
    #[test]
    fn parse_raw_codewords_rejects_malformed() {
        // Arm 1: bad prefix at offset 0.
        let err = parse_raw_codewords(b"AAA0").unwrap_err();
        assert!(
            err.contains("micropdf417:") && err.contains("raw codewords"),
            "bad-prefix diagnostic must carry the symbology + 'raw codewords' tags; got {err:?}"
        );
        assert!(
            err.contains("expected `^` at offset 0"),
            "bad-prefix diagnostic must call out the missing caret + offset; got {err:?}"
        );
        assert!(
            err.contains("0x41"),
            "bad-prefix diagnostic must echo the offending byte 0x41 ('A'); got {err:?}"
        );

        // Arm 2: non-digit inside the 3-digit segment.
        let err = parse_raw_codewords(b"^00X").unwrap_err();
        assert!(
            err.contains("non-digit"),
            "non-digit-segment diagnostic must say 'non-digit'; got {err:?}"
        );
        assert!(
            err.contains("0x58"),
            "non-digit-segment diagnostic must echo the offending byte 0x58 ('X'); got {err:?}"
        );
        assert!(
            err.contains("at offset 3"),
            "non-digit-segment diagnostic must echo the offset (3); got {err:?}"
        );
        assert!(
            !err.contains("must be 0..=928"),
            "non-digit-segment diagnostic must not leak the value-range arm; got {err:?}"
        );

        // Arm 3: codeword > 928.
        let err = parse_raw_codewords(b"^929").unwrap_err();
        assert!(
            err.contains("must be 0..=928"),
            "value-range diagnostic must carry the 0..=928 bound; got {err:?}"
        );
        assert!(
            err.contains("929"),
            "value-range diagnostic must echo the offending value 929; got {err:?}"
        );
        assert!(
            !err.contains("non-digit") && !err.contains("expected `^`"),
            "value-range diagnostic must not leak other arms' tags; got {err:?}"
        );

        // Arm 4: trailing partial token.
        let err = parse_raw_codewords(b"^001^00").unwrap_err();
        assert!(
            err.contains("trailing"),
            "trailing-partial diagnostic must say 'trailing'; got {err:?}"
        );
        assert!(
            err.contains("3 trailing byte(s)"),
            "trailing-partial diagnostic must echo the count (3); got {err:?}"
        );
        assert!(
            err.contains("at offset 4"),
            "trailing-partial diagnostic must echo the offset (4); got {err:?}"
        );
    }

    /// Stage 11.6 — `raw=true` parses `^NNN` raw codewords, RS-encodes
    /// over the non-CCA metric table, and renders with the standalone
    /// MicroPDF417 layout. Pin the full bwip-js corpus (6 records).
    #[test]
    fn encode_raw_matches_bwip_js_corpus() {
        type RawRow = (&'static str, &'static [u32], &'static [u16], (u8, u8, u8));
        let golden: &[RawRow] = &[
            (
                "^900",
                &[900],
                &[900, 900, 900, 900, 78, 541, 601, 125, 9, 181, 356],
                (1, 11, 7),
            ),
            (
                "^902^123",
                &[902, 123],
                &[902, 123, 900, 900, 452, 808, 48, 873, 256, 59, 878],
                (1, 11, 7),
            ),
            (
                "^001^002^003^004",
                &[1, 2, 3, 4],
                &[1, 2, 3, 4, 650, 91, 697, 750, 240, 109, 321],
                (1, 11, 7),
            ),
            (
                "^001^002^003^004^005",
                &[1, 2, 3, 4, 5],
                &[1, 2, 3, 4, 5, 900, 900, 474, 434, 104, 515, 563, 606, 586],
                (1, 14, 7),
            ),
            (
                "^001^002^003^004^005^006^007^008",
                &[1, 2, 3, 4, 5, 6, 7, 8],
                &[
                    1, 2, 3, 4, 5, 6, 7, 8, 900, 900, 147, 13, 316, 647, 695, 78, 212,
                ],
                (1, 17, 7),
            ),
            (
                "^000^928^000^928",
                &[0, 928, 0, 928],
                &[0, 928, 0, 928, 267, 578, 316, 264, 921, 33, 539],
                (1, 11, 7),
            ),
        ];
        for (text, want_datcws, want_cws, want_crk) in golden {
            // Stage 11.A8c — input + length echo so a regression
            // in either the parser or the metric selector points
            // at the specific corpus row that failed.
            let datcws = parse_raw_codewords(text.as_bytes())
                .unwrap_or_else(|e| panic!("parse_raw_codewords({text:?}) failed: {e:?}"));
            assert_eq!(&datcws, want_datcws, "datcws mismatch for {text:?}");
            let metric = select_metric(want_datcws.len()).unwrap_or_else(|| {
                panic!(
                    "select_metric(len={}) returned None for {text:?}",
                    want_datcws.len()
                )
            });
            let (c, r, k, _, _, _) = metric;
            assert_eq!((c, r, k), *want_crk, "metric mismatch for {text:?}");
            // Reconstruct the full cws (datcws + 900 padding + RS) the
            // same way `render_raw_codewords` does internally.
            let n = (c as usize) * (r as usize) - (k as usize);
            let mut cws: Vec<u16> = want_datcws.iter().map(|&v| v as u16).collect();
            cws.resize(n, 900);
            let check = crate::util::rs_gf929::encode(&cws[..n], k as usize);
            cws.extend_from_slice(&check);
            assert_eq!(&cws, want_cws, "cws mismatch for {text:?}");
            // End-to-end through the public `encode` with `raw=true`.
            let bm = encode(text, &Options::default().with("raw", "true"))
                .unwrap_or_else(|e| panic!("encode failed for {text:?}: {e:?}"));
            assert!(
                bm.width() > 0 && bm.height() > 0,
                "empty matrix for {text:?}",
            );
        }
    }

    /// Stage 11.6 — explicit `raw=false` is equivalent to omitting the
    /// option (and the input is text-encoded, not parsed as `^NNN`).
    #[test]
    fn encode_raw_false_equivalent_to_default() {
        let a = encode("PDF417", &Options::default()).unwrap();
        let b = encode("PDF417", &Options::default().with("raw", "false")).unwrap();
        assert_eq!(a.width(), b.width());
        assert_eq!(a.height(), b.height());
    }

    /// Stage 11.6 — invalid `raw` value returns `InvalidOption`.
    /// Mirrors the cca/ccb sibling pattern (41b8ea8, 7776b54) with
    /// cross-option contamination guards against cca/ccb.
    #[test]
    fn encode_raw_rejects_invalid_value() {
        let err = encode("^001", &Options::default().with("raw", "maybe")).unwrap_err();
        match err {
            Error::InvalidOption(msg) => {
                assert!(
                    msg.contains("micropdf417:"),
                    "must carry the micropdf417 prefix; got {msg:?}"
                );
                assert!(
                    msg.contains("raw=\"maybe\""),
                    "must Debug-echo the offending value; got {msg:?}"
                );
                assert!(
                    msg.contains("must be"),
                    "must carry the predicate; got {msg:?}"
                );
                assert!(
                    msg.contains("\"true\"") && msg.contains("\"false\""),
                    "must name BOTH valid values; got {msg:?}"
                );
                // Cross-option contamination guards: raw=maybe diagnostic
                // must NOT pick up cca= or ccb= wording.
                assert!(
                    !msg.contains("cca=") && !msg.contains("ccb="),
                    "raw diagnostic must NOT leak cca/ccb option wording; got {msg:?}"
                );
            }
            other => panic!("expected InvalidOption, got {other:?}"),
        }
    }

    /// Stage 11.6 — `raw=true` combined with `cca=true` or `ccb=true`
    /// is rejected (BWIPP error: "Cannot combine cca, ccb and raw").
    ///
    /// Stage 11.A8c — upgrade from `matches!(_, Error::InvalidOption(_))`
    /// to pin the full diagnostic substring "raw=true cannot be combined
    /// with cca=true or ccb=true". Distinguishes this rejection arm
    /// from the OTHER raw rejection in the same `if let` block (the
    /// `_ => Err("raw=... must be 'true' or 'false'")` arm at line
    /// 961-963). A mutant that swaps the two raw-arm bodies (so a
    /// non-bool raw value triggers the cca/ccb error message and
    /// vice-versa) would survive the variant-only check.
    #[test]
    fn encode_raw_combined_with_cca_or_ccb_rejected() {
        for combine in ["cca", "ccb"] {
            let err = encode(
                "^001",
                &Options::default().with("raw", "true").with(combine, "true"),
            )
            .unwrap_err();
            let Error::InvalidOption(msg) = err else {
                panic!("expected InvalidOption for raw+{combine}; got {err:?}");
            };
            assert!(
                msg.contains("micropdf417:"),
                "diagnostic for raw+{combine} must carry micropdf417 prefix; got {msg:?}"
            );
            assert!(
                msg.contains("raw=true cannot be combined with cca=true or ccb=true"),
                "diagnostic for raw+{combine} must carry the full combine guard message; got {msg:?}"
            );
            // Cross-arm contamination guard: must NOT leak the
            // `raw=<val> must be "true" or "false"` template (which
            // would indicate the wrong raw-arm fired).
            assert!(
                !msg.contains("must be \"true\" or \"false\""),
                "diagnostic for raw+{combine} must not leak the value-parse template; got {msg:?}"
            );
        }
    }

    /// Stage 11.7 — `parse_text_escapes` substitutes `^NNN` ordinals
    /// and `^NAME` control names per BWIPP `parseinput`.
    #[test]
    fn parse_text_escapes_substitutes_correctly() {
        // 3-digit ordinal: ^065 = 'A'.
        assert_eq!(parse_text_escapes(b"^065BC").unwrap(), b"ABC");
        // Three back-to-back ordinals.
        assert_eq!(parse_text_escapes(b"^065^066^067").unwrap(), b"ABC");
        // Boundary 255.
        assert_eq!(parse_text_escapes(b"^255AB").unwrap(), &[255, b'A', b'B']);
        // 3-char control name TAB = 9.
        assert_eq!(parse_text_escapes(b"X^TABY").unwrap(), &[b'X', 9, b'Y']);
        // 2-char control name CR = 13.
        assert_eq!(parse_text_escapes(b"X^CRY").unwrap(), &[b'X', 13, b'Y']);
        // 3-char NUL = 0.
        assert_eq!(parse_text_escapes(b"^NUL!").unwrap(), &[0, b'!']);
        // Plain text — no escapes.
        assert_eq!(parse_text_escapes(b"ABC").unwrap(), b"ABC");
    }

    /// Stage 11.7 — invalid `^NNN` with ordinal > 255 returns Err.
    ///
    /// Stage 11.A8c — upgrade from weak `is_err()` to per-input
    /// diagnostic-substring + value-echo pins. The function has only
    /// ONE error arm (line 666-670 of parse_text_escapes), but the
    /// previous test never validated:
    ///   * that the diagnostic carries the "ordinal must be 000..=255"
    ///     bound text,
    ///   * that the offending value is echoed via `{value}` (kills
    ///     `{value}` drop / fixed-replacement mutants),
    ///   * the boundary `^255` MUST succeed (kills `> 255` → `>= 255`
    ///     off-by-one mutants — this is anchored elsewhere via
    ///     parse_text_escapes_substitutes_correctly but worth
    ///     duplicating here as the negative-side complement).
    #[test]
    fn parse_text_escapes_rejects_ordinal_above_255() {
        // Two anchor cases distinguish 256 (just over the bound) from
        // 999 (max 3-digit). A mutant that hard-codes a fixed value
        // in the diagnostic is caught when 256 and 999 produce the
        // SAME echo. A mutant that off-by-ones the bound to `>= 255`
        // would cause the boundary anchor at the bottom to fail.
        for (input, want_value) in [(b"^256AB" as &[u8], "256"), (b"^999X", "999")] {
            let err = parse_text_escapes(input).unwrap_err();
            assert!(
                err.contains("micropdf417 parse:"),
                "diagnostic for {input:?} must carry the symbology+mode prefix; got {err:?}"
            );
            assert!(
                err.contains("ordinal must be 000..=255"),
                "diagnostic for {input:?} must carry the 000..=255 bound text; got {err:?}"
            );
            assert!(
                err.contains(want_value),
                "diagnostic for {input:?} must echo the offending value {want_value:?}; got {err:?}"
            );
        }

        // Boundary anchor: 255 is the MAX VALID ordinal — catches
        // `> 255` → `>= 255` mutants (which would reject 255 too).
        assert_eq!(
            parse_text_escapes(b"^255").unwrap(),
            vec![255u8],
            "^255 must encode as byte 0xFF; kills `>= 255` off-by-one"
        );
    }

    /// Stage 11.7 — full `encode(.., parse=true)` produces the same
    /// datcws as a baseline text encode of the substituted bytes.
    /// Cross-verified against bwip-js corpus.
    #[test]
    fn encode_parse_matches_baseline_text_encode() {
        // Each row: (parse_input, expected_substituted_text).
        let cases: &[(&str, &[u8])] = &[
            // Plain text — no-op.
            ("ABC", b"ABC"),
            // 3-digit ordinal at the start.
            ("^065BC", b"ABC"),
            // Three ordinals in a row.
            ("^065^066^067", b"ABC"),
            // Max ordinal 255 + ASCII tail.
            ("^255AB", &[255, b'A', b'B']),
            // Control name TAB = 9.
            ("X^TABY", &[b'X', 9, b'Y']),
            // Control name CR = 13.
            ("X^CRY", &[b'X', 13, b'Y']),
        ];
        for (text, want_bytes) in cases {
            let substituted = parse_text_escapes(text.as_bytes()).unwrap();
            assert_eq!(
                &substituted, want_bytes,
                "substitution mismatch for {text:?}"
            );
            // Both code paths must produce identical symbols.
            let via_parse = encode(text, &Options::default().with("parse", "true"))
                .unwrap_or_else(|e| panic!("parse=true encode failed for {text:?}: {e:?}"));
            // Stage 11.A8c — input-echoing failure-mode label.
            let direct = render(want_bytes)
                .unwrap_or_else(|e| panic!("render({want_bytes:?}) baseline failed: {e:?}"));
            assert_eq!(
                via_parse.width(),
                direct.width(),
                "width mismatch for {text:?}"
            );
            assert_eq!(
                via_parse.height(),
                direct.height(),
                "height mismatch for {text:?}",
            );
            for y in 0..direct.height() {
                for x in 0..direct.width() {
                    assert_eq!(
                        via_parse.get(x, y),
                        direct.get(x, y),
                        "pixel mismatch at ({x},{y}) for {text:?}",
                    );
                }
            }
        }
    }

    /// Stage 11.7 — explicit `parse=false` is equivalent to omitting
    /// the option entirely.
    #[test]
    fn encode_parse_false_equivalent_to_default() {
        let a = encode("PDF417", &Options::default()).unwrap();
        let b = encode("PDF417", &Options::default().with("parse", "false")).unwrap();
        assert_eq!(a.width(), b.width());
        assert_eq!(a.height(), b.height());
    }

    /// Stage 11.7 — invalid `parse` value returns `InvalidOption`.
    #[test]
    fn encode_parse_rejects_invalid_value() {
        // Single-substring `msg.contains("parse")` would also pass a
        // mutated diagnostic that says "parsefnc" instead of "parse" —
        // since "parse" is a prefix of "parsefnc". Pin the precise
        // `parse=` Debug-echo + cross-option guard against parsefnc=
        // to distinguish.
        let err = encode("ABC", &Options::default().with("parse", "maybe")).unwrap_err();
        match err {
            Error::InvalidOption(msg) => {
                assert!(
                    msg.contains("micropdf417:"),
                    "must carry the micropdf417 prefix; got {msg:?}"
                );
                assert!(
                    msg.contains("parse=\"maybe\""),
                    "must Debug-echo as parse= (NOT parsefnc=); got {msg:?}"
                );
                assert!(
                    msg.contains("must be"),
                    "must carry the predicate; got {msg:?}"
                );
                assert!(
                    msg.contains("\"true\"") && msg.contains("\"false\""),
                    "must name BOTH valid values; got {msg:?}"
                );
                // Cross-option contamination guard: parse= must NOT
                // pick up parsefnc= wording (parse is a prefix of
                // parsefnc, so the substring would alias).
                assert!(
                    !msg.contains("parsefnc="),
                    "parse diagnostic must NOT leak parsefnc-option wording; got {msg:?}"
                );
            }
            other => panic!("expected InvalidOption, got {other:?}"),
        }
    }

    /// Stage 11.8 — `parse_text_parsefnc` extracts leading `^ECI`
    /// markers, applies `^^` caret-escape, and leaves the rest intact.
    #[test]
    fn parse_text_parsefnc_handles_eci_and_caret_escape() {
        // Plain text, no escapes.
        // Stage 11.A8c (cont) — descriptive labels naming no-ECI invariant.
        let (eci, body) = parse_text_parsefnc(b"PDF417").unwrap();
        assert!(
            eci.is_empty(),
            "parse_text_parsefnc(b\"PDF417\") (plain text, no ^ECI marker) must produce empty eci vec; got {eci:?}"
        );
        assert_eq!(body, b"PDF417");
        // ^^ → single literal caret.
        let (eci, body) = parse_text_parsefnc(b"FOO^^BAR").unwrap();
        assert!(
            eci.is_empty(),
            "parse_text_parsefnc(b\"FOO^^BAR\") (caret-escape ^^ → literal '^', no ^ECI prefix) must produce empty eci vec; got {eci:?}"
        );
        assert_eq!(body, b"FOO^BAR");
        // Leading ^ECI marker, ECI=26 (UTF-8).
        let (eci, body) = parse_text_parsefnc(b"^ECI000026ABC").unwrap();
        assert_eq!(eci, vec![927, 26]);
        assert_eq!(body, b"ABC");
        // Leading ECI with digit body.
        let (eci, body) = parse_text_parsefnc(b"^ECI0000091234").unwrap();
        assert_eq!(eci, vec![927, 9]);
        assert_eq!(body, b"1234");
        // ECI 3 + HELLO.
        let (eci, body) = parse_text_parsefnc(b"^ECI000003HELLO").unwrap();
        assert_eq!(eci, vec![927, 3]);
        assert_eq!(body, b"HELLO");
    }

    /// Stage 11.8 — `^ECI` with bad format is rejected.
    ///
    /// Stage 11.A8c — upgrade from two weak is_err() checks to
    /// distinct-substring + body-echo pins. parse_text_parsefnc has
    /// two reachable rejection arms exercised here:
    ///   1. Leading-ECI non-digit body (line 708-714) →
    ///      "micropdf417 parsefnc: ^ECI must be followed by 6 ASCII
    ///       digits; got \"<chars>\""
    ///   2. Mid-stream ^ECI in body section (line 744-749) →
    ///      "micropdf417 parsefnc: mid-stream ^ECI markers are not
    ///       supported; place ECI prefixes only at the start of the
    ///       input"
    ///
    /// The two messages differ entirely. A mutant that swaps the two
    /// arm bodies (so non-digit ECI returns the mid-stream message
    /// or vice versa) survives `is_err()` but fails distinct-substring
    /// pins. Body-echo of "abcdef" also kills `{...}` drop in arm 1.
    #[test]
    fn parse_text_parsefnc_rejects_bad_eci() {
        // Arm 1: non-digit body in leading ^ECI.
        let err = parse_text_parsefnc(b"^ECIabcdef").unwrap_err();
        assert!(
            err.contains("micropdf417 parsefnc:"),
            "non-digit-ECI diagnostic must carry the symbology+mode prefix; got {err:?}"
        );
        assert!(
            err.contains("^ECI must be followed by 6 ASCII digits"),
            "non-digit-ECI diagnostic must carry the 6-digit-requirement text; got {err:?}"
        );
        assert!(
            err.contains("\"abcdef\""),
            "non-digit-ECI diagnostic must echo the offending body via {{:?}}; got {err:?}"
        );
        assert!(
            !err.contains("mid-stream"),
            "non-digit-ECI diagnostic must not leak the mid-stream arm; got {err:?}"
        );

        // Arm 2: mid-stream ^ECI in body.
        let err = parse_text_parsefnc(b"ABC^ECI000003").unwrap_err();
        assert!(
            err.contains("mid-stream ^ECI"),
            "mid-stream diagnostic must call out 'mid-stream ^ECI'; got {err:?}"
        );
        assert!(
            err.contains("place ECI prefixes only at the start"),
            "mid-stream diagnostic must carry the placement hint; got {err:?}"
        );
        assert!(
            !err.contains("6 ASCII digits"),
            "mid-stream diagnostic must not leak the non-digit-ECI arm; got {err:?}"
        );
    }

    /// Stage 11.8 — full `encode(.., parsefnc=true)` matches bwip-js
    /// datcws byte-for-byte across the 5-record corpus.
    #[test]
    fn encode_parsefnc_matches_bwip_js_corpus() {
        // (input, expected datcws). Captured via the parsefnc rows of
        // `rust/tools/oracle-micropdf417-opts.js`.
        let cases: &[(&str, &[u16])] = &[
            ("FOO^^BAR", &[900, 164, 448, 748, 30, 539]),
            ("^ECI000026ABC", &[927, 26, 901, 65, 66, 67]),
            ("^ECI0000091234", &[927, 9, 901, 49, 50, 51, 52]),
            ("PDF417", &[900, 453, 178, 121, 239]),
            ("^ECI000003HELLO", &[927, 3, 900, 214, 341, 449]),
        ];
        for (text, want_datcws) in cases {
            // Stage 11.A8c — input-echoing failure-mode labels for
            // both parse_text_parsefnc and data_codewords so a
            // regression points at the specific corpus row.
            let (eci, body) = parse_text_parsefnc(text.as_bytes())
                .unwrap_or_else(|e| panic!("parse_text_parsefnc({text:?}) failed: {e:?}"));
            // Reconstruct the datcws via the same internal path as
            // `encode` so any divergence shows up here.
            let mut datcws: Vec<u16> = Vec::new();
            datcws.extend_from_slice(&eci);
            datcws.extend_from_slice(
                &data_codewords(&body)
                    .unwrap_or_else(|e| panic!("data_codewords(body for {text:?}) failed: {e:?}")),
            );
            assert_eq!(&datcws, want_datcws, "datcws mismatch for {text:?}");
            // End-to-end through the public `encode` with parsefnc=true.
            let bm = encode(text, &Options::default().with("parsefnc", "true"))
                .unwrap_or_else(|e| panic!("encode failed for {text:?}: {e:?}"));
            assert!(
                bm.width() > 0 && bm.height() > 0,
                "empty matrix for {text:?}",
            );
        }
    }

    /// Stage 11.8 — explicit `parsefnc=false` is equivalent to omitting
    /// the option.
    #[test]
    fn encode_parsefnc_false_equivalent_to_default() {
        let a = encode("PDF417", &Options::default()).unwrap();
        let b = encode("PDF417", &Options::default().with("parsefnc", "false")).unwrap();
        assert_eq!(a.width(), b.width());
        assert_eq!(a.height(), b.height());
    }

    /// Stage 11.8 — invalid `parsefnc` value returns `InvalidOption`.
    /// Mirrors the parse= sibling at 9effd76 with the prefix-alias
    /// cross-option guard. Note: a `msg.contains("parsefnc=")` check
    /// alone would NOT catch a mutation that says "parse=" instead
    /// (since "parse=" is a substring of "parsefnc="), but a
    /// `msg.contains("parsefnc=")` check DOES catch that direction
    /// because "parse=" doesn't contain "parsefnc=" — so the cross-
    /// alias guard for parsefnc is one-way (vs the parse= test which
    /// is also one-way the other direction).
    #[test]
    fn encode_parsefnc_rejects_invalid_value() {
        let err = encode("ABC", &Options::default().with("parsefnc", "maybe")).unwrap_err();
        match err {
            Error::InvalidOption(msg) => {
                assert!(
                    msg.contains("micropdf417:"),
                    "must carry the micropdf417 prefix; got {msg:?}"
                );
                assert!(
                    msg.contains("parsefnc=\"maybe\""),
                    "must Debug-echo as parsefnc=; got {msg:?}"
                );
                assert!(
                    msg.contains("must be"),
                    "must carry the predicate; got {msg:?}"
                );
                assert!(
                    msg.contains("\"true\"") && msg.contains("\"false\""),
                    "must name BOTH valid values; got {msg:?}"
                );
            }
            other => panic!("expected InvalidOption, got {other:?}"),
        }
    }

    /// Stage 11.8 — mid-stream `^ECI` returns InvalidData (not a panic).
    ///
    /// Stage 11.A8c — upgrade from `matches!(_, Error::InvalidData(_))`
    /// to pin the full diagnostic substring + ABSENCE of competing
    /// substrings. Three rejection paths in parsefnc all return
    /// InvalidData, so variant-only assertion can't distinguish:
    ///   * mid-stream ECI (this test): "mid-stream ^ECI markers are
    ///     not supported"
    ///   * parsefnc=true + raw=true elsewhere: different message
    ///   * value-parse failure of parsefnc itself: InvalidOption
    ///     (different variant entirely)
    ///
    /// Kills mutants that swap the mid-stream guard with another
    /// arm's message OR drop the "place ECI prefixes only at the
    /// start of the input" hint.
    #[test]
    fn encode_parsefnc_rejects_midstream_eci() {
        let err = encode(
            "ABC^ECI000003DEF",
            &Options::default().with("parsefnc", "true"),
        )
        .unwrap_err();
        let Error::InvalidData(msg) = err else {
            panic!("expected InvalidData for mid-stream ^ECI; got {err:?}");
        };
        assert!(
            msg.contains("mid-stream ^ECI"),
            "diagnostic must call out 'mid-stream ^ECI'; got {msg:?}"
        );
        assert!(
            msg.contains("not supported"),
            "diagnostic must say the marker is not supported; got {msg:?}"
        );
        assert!(
            msg.contains("place ECI prefixes only at the start"),
            "diagnostic must include the placement hint; got {msg:?}"
        );
        assert!(
            msg.contains("micropdf417"),
            "diagnostic must carry the symbology tag; got {msg:?}"
        );
    }

    /// Stage 11.A8c — pin `append_bits(out, value, n)`. MSB-first
    /// bit packer used inside `render_cws` for the row-pattern bit
    /// assembly. Existing tests exercise it transitively via the
    /// micropdf417 rendering goldens; mutations on `n - 1 - i`
    /// (shift direction), `& 1` (mask width), or body-replacement
    /// could survive.
    ///
    /// Mutations to catch:
    ///   - `n - 1 - i` → `i`: LSB-first instead of MSB-first.
    ///   - `& 1` → `& 0`: pushes all zeros.
    ///   - `& 1` → `& 3`: pushes 0/1/2/3 values (not boolean).
    ///   - Body replaced with `()`: out unchanged.
    ///   - `for i in 0..n` → `0..=n`: off-by-one.
    #[test]
    fn append_bits_msb_first_packing() {
        // n=0: out unchanged.
        let mut out: Vec<u8> = vec![5, 6];
        append_bits(&mut out, 0xFF, 0);
        assert_eq!(out, vec![5, 6], "n=0 → no change");

        // value=0, n=4: push 4 zeros.
        let mut out: Vec<u8> = Vec::new();
        append_bits(&mut out, 0, 4);
        assert_eq!(out, vec![0, 0, 0, 0]);

        // 0b1010 (=10) in 4 bits MSB-first → [1, 0, 1, 0].
        let mut out: Vec<u8> = Vec::new();
        append_bits(&mut out, 0b1010, 4);
        assert_eq!(out, vec![1, 0, 1, 0], "MSB-first: 0b1010 → [1,0,1,0]");

        // 0b11111 (=31) in 5 bits → 5 ones.
        let mut out: Vec<u8> = Vec::new();
        append_bits(&mut out, 0b11111, 5);
        assert_eq!(out, vec![1, 1, 1, 1, 1]);

        // 0b1 in 1 bit → just [1].
        let mut out: Vec<u8> = Vec::new();
        append_bits(&mut out, 1, 1);
        assert_eq!(out, vec![1]);

        // Append preserves existing prefix.
        let mut out: Vec<u8> = vec![9, 9];
        append_bits(&mut out, 0b101, 3);
        assert_eq!(
            out,
            vec![9, 9, 1, 0, 1],
            "append_bits must extend, not replace"
        );

        // Full-byte: 0xAB = 0b10101011 in 8 bits.
        let mut out: Vec<u8> = Vec::new();
        append_bits(&mut out, 0xAB, 8);
        assert_eq!(out, vec![1, 0, 1, 0, 1, 0, 1, 1]);

        // Width 17 (matches MicroPDF417 codeword width): pack 0x12345
        // = 0b1_0010_0011_0100_0101 → [1,0,0,1,0, 0,0,1,1, 0,1,0,0, 0,1,0,1].
        let mut out: Vec<u8> = Vec::new();
        append_bits(&mut out, 0x12345, 17);
        assert_eq!(
            out,
            vec![1, 0, 0, 1, 0, 0, 0, 1, 1, 0, 1, 0, 0, 0, 1, 0, 1],
            "17-bit pack matches MicroPDF417 codeword width"
        );
    }

    /// Stage 11.9 — `version="RxC"` parser validates BWIPP's RxC
    /// syntax. The grammar is `<digits>x<digits>` with no leading
    /// zero requirements.
    #[test]
    fn parse_version_string_happy_path() {
        assert_eq!(parse_version_string("14x1").unwrap(), (14, 1));
        assert_eq!(parse_version_string("20x1").unwrap(), (20, 1));
        assert_eq!(parse_version_string("11x2").unwrap(), (11, 2));
        assert_eq!(parse_version_string("44x4").unwrap(), (44, 4));
    }

    /// Stage 11.9 — malformed `version` strings are rejected.
    ///
    /// Stage 11.A8c — upgrade from 7 weak `is_err()` checks to
    /// per-arm diagnostic-substring pins. The function has FIVE
    /// rejection arms (lines 868-894):
    ///   1. no 'x' separator                → "must be formatted as RxC"
    ///   2. empty rows or cols              → "must be formatted as RxC"
    ///   3. non-digit in either component   → "must be formatted as RxC"
    ///   4. rows component overflows u8     → "rows component out of range"
    ///   5. cols component overflows u8     → "columns component out of range"
    ///                                        (previously UNTESTED — added
    ///                                        the 9x999 case below)
    ///
    /// Each case now pins the path-specific tail to distinguish arms
    /// 1-3 (all share the RxC-format tail) from arms 4-5 (which use
    /// "rows/columns component out of range"). A mutant that routes
    /// rows-overflow through the cols-overflow arm (or vice versa)
    /// is caught by the rows-vs-columns substring check.
    #[test]
    fn parse_version_string_rejects_malformed() {
        // Arms 1-3: all surface "must be formatted as RxC".
        for (input, arm) in [
            ("11", "no 'x' separator"),
            ("11x", "empty cols"),
            ("xN", "empty rows"),
            ("Ax1", "non-digit rows"),
            ("11xC", "non-digit cols"),
            ("11x1x1", "extra 'x' in cols → non-digit"),
        ] {
            let err = parse_version_string(input).unwrap_err();
            let Error::InvalidOption(msg) = err else {
                panic!("{input:?} ({arm}) must yield InvalidOption; got {err:?}");
            };
            assert!(
                msg.contains("micropdf417:"),
                "{input:?} ({arm}) diagnostic must carry symbology prefix; got {msg:?}"
            );
            assert!(
                msg.contains("must be formatted as RxC"),
                "{input:?} ({arm}) must surface the RxC-format diagnostic; got {msg:?}"
            );
            assert!(
                !msg.contains("out of range"),
                "{input:?} ({arm}) must not leak the overflow diagnostic; got {msg:?}"
            );
        }

        // Arm 4: rows component overflows u8.
        let err = parse_version_string("999x9").unwrap_err();
        let Error::InvalidOption(msg) = err else {
            panic!("'999x9' must yield InvalidOption; got {err:?}");
        };
        assert!(
            msg.contains("rows component out of range"),
            "'999x9' must hit the rows-overflow arm; got {msg:?}"
        );
        assert!(
            !msg.contains("columns component"),
            "'999x9' must not leak the cols-overflow text; got {msg:?}"
        );

        // Arm 5: cols component overflows u8 — previously UNTESTED.
        let err = parse_version_string("9x999").unwrap_err();
        let Error::InvalidOption(msg) = err else {
            panic!("'9x999' must yield InvalidOption; got {err:?}");
        };
        assert!(
            msg.contains("columns component out of range"),
            "'9x999' must hit the cols-overflow arm; got {msg:?}"
        );
        assert!(
            !msg.contains("rows component"),
            "'9x999' must not leak the rows-overflow text; got {msg:?}"
        );
    }

    /// Stage 11.9 — `encode(.., version="RxC")` and `columns`/`rows`
    /// drive the same metric-constraint logic. Pin the corpus rows
    /// captured by `rust/tools/oracle-micropdf417-opts.js`.
    #[test]
    fn encode_with_size_constraints_matches_bwip_js() {
        // (text, opts (each k/v pair), expected (c, r, k))
        type SizeCase = (
            &'static str,
            &'static [(&'static str, &'static str)],
            (u8, u8, u8),
        );
        let cases: &[SizeCase] = &[
            ("ABC", &[("version", "14x1")], (1, 14, 7)),
            ("ABC", &[("version", "20x1")], (1, 20, 8)),
            ("ABCDEFGH", &[("version", "11x2")], (2, 11, 9)),
            ("ABCDEFGH", &[("version", "14x2")], (2, 14, 9)),
            ("ABCDEFGH", &[("columns", "2")], (2, 8, 8)),
            ("ABC", &[("rows", "14")], (1, 14, 7)),
            ("ABCDEFGH", &[("columns", "2"), ("rows", "11")], (2, 11, 9)),
        ];
        for (text, kvs, want_crk) in cases {
            let mut opts = Options::default();
            for (k, v) in *kvs {
                opts = opts.with(*k, *v);
            }
            // Verify the constraint plumbing picks the same metric BWIPP
            // would by checking the symbol dimensions via render_cws
            // path (data_codewords + select_metric_constrained).
            let datcws = data_codewords(text.as_bytes()).unwrap();
            let (_, size) = check_micropdf417_opts(&opts).unwrap();
            let metric = select_metric_constrained(datcws.len(), size.ucols, size.urows).unwrap();
            let (c, r, k, _, _, _) = metric;
            assert_eq!((c, r, k), *want_crk, "metric mismatch for {text:?} {kvs:?}");

            // End-to-end through encode().
            let bm = encode(text, &opts)
                .unwrap_or_else(|e| panic!("encode failed for {text:?} with {kvs:?}: {e:?}"));
            assert!(bm.width() > 0 && bm.height() > 0);
        }
    }

    /// Stage 11.9 — invalid `version` value returns InvalidOption.
    ///
    /// Stage 11.A8c — upgrade from `matches!(_, Error::InvalidOption(_))`
    /// to pin the parse_version_string-arm diagnostic. The encode
    /// entry point can also surface InvalidOption from the
    /// `cca/ccb/raw` arms, so variant-only assertion is insufficient.
    /// "garbage" has no 'x', so it hits arm 1 of parse_version_string
    /// ("must be formatted as RxC"), distinguishing this path from
    /// the cca/ccb/raw value-parse arms.
    #[test]
    fn encode_rejects_invalid_version() {
        let err = encode("ABC", &Options::default().with("version", "garbage")).unwrap_err();
        let Error::InvalidOption(msg) = err else {
            panic!("expected InvalidOption for version=\"garbage\"; got {err:?}");
        };
        assert!(
            msg.contains("micropdf417:"),
            "diagnostic must carry the symbology prefix; got {msg:?}"
        );
        assert!(
            msg.contains("\"garbage\""),
            "diagnostic must echo the offending spec; got {msg:?}"
        );
        assert!(
            msg.contains("must be formatted as RxC"),
            "diagnostic must carry the RxC-format tail; got {msg:?}"
        );
        assert!(
            !msg.contains("out of range") && !msg.contains("cca") && !msg.contains("raw="),
            "version=garbage must short-circuit before other option arms; got {msg:?}"
        );
    }

    /// Stage 11.9 — constraints that don't match any metric return
    /// an error (the data is too long for the requested size).
    ///
    /// Stage 11.A8c — upgrade from `matches!(_, Error::InvalidData(_))`
    /// to pin the render_constrained no-metric diagnostic. Multiple
    /// codepaths surface InvalidData in encode (parse_text_escapes,
    /// parse_raw_codewords, parse_text_parsefnc, mid-stream ^ECI,
    /// render_constrained no-metric). Variant-only assertion can't
    /// distinguish — a mutant that swaps the no-metric branch with
    /// any other InvalidData arm survives.
    #[test]
    fn encode_with_oversized_constraint_errors() {
        // 1x11 has capacity 4 datcws; "ABCDEFGHIJK…X" needs more.
        let err = encode(
            "ABCDEFGHIJKLMNOPQRSTUVWX",
            &Options::default().with("version", "11x1"),
        )
        .unwrap_err();
        let Error::InvalidData(msg) = err else {
            panic!("expected InvalidData for oversized constraint; got {err:?}");
        };
        assert!(
            msg.contains("MicroPDF417:"),
            "diagnostic must carry the symbology prefix; got {msg:?}"
        );
        assert!(
            msg.contains("no metric for"),
            "diagnostic must call out 'no metric for'; got {msg:?}"
        );
        assert!(
            msg.contains("datcws"),
            "diagnostic must tag the codeword unit (datcws); got {msg:?}"
        );
        assert!(
            msg.contains("columns=1"),
            "diagnostic must echo the requested columns constraint; got {msg:?}"
        );
        assert!(
            msg.contains("rows=11"),
            "diagnostic must echo the requested rows constraint; got {msg:?}"
        );
        assert!(
            !msg.contains("^ECI") && !msg.contains("ordinal") && !msg.contains("trailing"),
            "no-metric diagnostic must not leak parser-stage arms; got {msg:?}"
        );
    }

    /// Stage 11.A8c — pin `select_metric` smallest-fit search.
    /// Kills `>= with <` / `>= with ==` / `* with /` / `- with +`
    /// mutations on line 145 (the metric-fit predicate).
    #[test]
    fn select_metric_smallest_fit() {
        // Smallest payload → smallest metric.
        // Stage 11.A8c (cont) — give the second `.expect` a descriptive
        // input echo so a None-returning mutation reports which call site
        // (not just "determinism") tripped — pairs with the assert_eq!
        // below for a 2-anchor diagnostic.
        let m1 = select_metric(1).expect(
            "select_metric(1) must yield Some(metric) — smallest payload must fit smallest metric",
        );
        let m2 = select_metric(1).expect(
            "select_metric(1) called twice must yield Some(metric) — determinism check requires non-None on repeat",
        );
        assert_eq!(m1, m2, "select_metric must be deterministic");

        // Verify the chosen metric has enough capacity for the
        // requested payload.
        let (c, r, k, _, _, _) = m1;
        let capacity = (c as usize) * (r as usize) - (k as usize);
        assert!(capacity >= 1, "metric capacity {capacity} < 1");

        // Larger payload → larger-or-equal metric.
        if let Some(big) = select_metric(50) {
            let (c, r, k, _, _, _) = big;
            let big_cap = (c as usize) * (r as usize) - (k as usize);
            assert!(big_cap >= 50, "metric for 50 cws has cap {big_cap}");
        }

        // Payload so big nothing fits → None.
        assert_eq!(select_metric(usize::MAX), None);
    }

    /// Stage 11.A8c — pin `select_metric_constrained` ucols/urows gating.
    /// Kills `== with !=` / `|| with &&` mutations on line 156.
    #[test]
    fn select_metric_constrained_respects_constraints() {
        // No constraint (0,0) ≡ select_metric.
        assert_eq!(select_metric_constrained(1, 0, 0), select_metric(1));

        // Specific column constraint: any returned metric must have
        // that column count.
        if let Some(m) = select_metric_constrained(1, 2, 0) {
            assert_eq!(m.0, 2, "ucols=2 returned metric with cols {}", m.0);
        }
        if let Some(m) = select_metric_constrained(1, 3, 0) {
            assert_eq!(m.0, 3);
        }
        if let Some(m) = select_metric_constrained(1, 4, 0) {
            assert_eq!(m.0, 4);
        }

        // Row constraint: returned metric must have that row count.
        if let Some(m) = select_metric_constrained(1, 0, 5) {
            assert_eq!(m.1, 5);
        }
    }

    /// Stage 11.A8c — pin `select_ccb_metric` against NONCCA_METRICS.
    /// The function is structurally similar to
    /// `select_metric_constrained` but only takes `ucols` (no urows
    /// constraint). It's used by the CC-B render path and previously
    /// had no direct test — mutations on the column-equality check
    /// or the capacity comparison would only surface as opaque
    /// composite-code render errors.
    ///
    /// Hand-computed:
    ///   - select_ccb_metric(5, 0) → first row capacity >= 5, ignoring
    ///     column: NONCCA_METRICS[1] = (1, 14, 7, ...) capacity=7.
    ///   - select_ccb_metric(5, 2) → first row with c=2 AND capacity >= 5.
    ///     Rows 0-5 are c=1 (skipped); row 6 = (2, 8, 8, ...) capacity=8.
    ///   - select_ccb_metric(5, 3) → first c=3 row with capacity >= 5.
    ///     Row 13 = (3, 6, 12, ...) capacity = 6 (≥5) ✓.
    ///   - select_ccb_metric(200, 0) → None (exceeds max capacity).
    #[test]
    fn select_ccb_metric_respects_column_constraint() {
        // ucols=0 (no constraint): smallest fitting row.
        let m = select_ccb_metric(5, 0).expect("5 cws should fit");
        assert_eq!(m, (1, 14, 7, 8, 0, 8));
        // ucols=2: skip c=1 rows, pick first c=2.
        let m = select_ccb_metric(5, 2).expect("5 cws should fit in c=2");
        assert_eq!(m.0, 2, "ucols=2 must return c=2 metric");
        assert_eq!(m, (2, 8, 8, 1, 0, 1));
        // ucols=3: first c=3 with capacity >= 5. NONCCA_METRICS[13] =
        // (3, 6, 12, ...) capacity 6, which IS >= 5.
        let m = select_ccb_metric(5, 3).expect("5 cws fits c=3");
        assert_eq!(m.0, 3);
        // ucols=4: first c=4 with capacity >= 5.
        let m = select_ccb_metric(5, 4).expect("5 cws fits c=4");
        assert_eq!(m.0, 4);
        // Capacity > largest NONCCA row → None.
        assert_eq!(
            select_ccb_metric(200, 0),
            None,
            "200 cws should exceed largest NONCCA capacity (176)"
        );
        // Capacity > largest c=2 row's max (26 rows × 2 = 52 - 15 = 37).
        assert_eq!(
            select_ccb_metric(50, 2),
            None,
            "50 cws should not fit any c=2 metric (max 37)"
        );
    }

    /// Stage 11.A8c — pin `parse_version_string`. Six branches:
    ///   * happy path (RxC two u8 digits).
    ///   * missing 'x' separator → InvalidOption.
    ///   * empty rows component ("x4") → InvalidOption.
    ///   * empty cols component ("4x") → InvalidOption.
    ///   * non-digit char in either component → InvalidOption.
    ///   * u8 overflow (rows or cols > 255) → InvalidOption with the
    ///     "out of range" sub-string.
    ///
    /// Kills `replace parse_version_string with Ok((0,0))` and the
    /// per-branch `delete match arm` mutants, plus `&& with ||` on the
    /// emptiness guard (`||` collapse hides the cols-empty arm).
    #[test]
    fn parse_version_string_all_branches() {
        // Happy: rows=11 cols=2 — round-trips exactly.
        assert_eq!(parse_version_string("11x2").unwrap(), (11, 2));
        // Happy with multi-digit cols.
        assert_eq!(parse_version_string("4x44").unwrap(), (4, 44));

        // Missing 'x' separator.
        let err = parse_version_string("114").unwrap_err();
        assert!(
            matches!(&err, Error::InvalidOption(m) if m.contains("RxC")),
            "no-separator: got {err:?}",
        );

        // Empty rows component.
        let err = parse_version_string("x4").unwrap_err();
        assert!(
            matches!(&err, Error::InvalidOption(m) if m.contains("RxC")),
            "empty rows: got {err:?}",
        );

        // Empty cols component — `||` mutant on the guard
        // (`rows_str.is_empty() || cols_str.is_empty()`) would let this
        // through to the parse stage where "" → parse fails with the
        // "out of range" message; the guard message contains "RxC".
        let err = parse_version_string("4x").unwrap_err();
        assert!(
            matches!(&err, Error::InvalidOption(m) if m.contains("RxC")),
            "empty cols: got {err:?}",
        );

        // Non-digit in rows. Stage 11.A8c — pin RxC substring AND the
        // ABSENCE of "out of range" so a mutant that drops the digit-
        // check arm (letting "aa" fall through to u8::parse, which
        // fails with the overflow message) is caught.
        let err = parse_version_string("aax2").unwrap_err();
        assert!(
            matches!(&err, Error::InvalidOption(m) if m.contains("RxC")),
            "non-digit rows: got {err:?}"
        );
        assert!(
            matches!(&err, Error::InvalidOption(m) if !m.contains("out of range")),
            "non-digit rows must short-circuit before u8 parse; got {err:?}"
        );

        // Non-digit in cols. Same pin shape — also kills a mutant that
        // swaps the rows/cols digit-check ordering (rejecting "4xab"
        // via the rows arm would still report RxC but with a different
        // implementation; pinning RxC + absence of overflow is enough
        // for this layer).
        let err = parse_version_string("4xab").unwrap_err();
        assert!(
            matches!(&err, Error::InvalidOption(m) if m.contains("RxC")),
            "non-digit cols: got {err:?}"
        );
        assert!(
            matches!(&err, Error::InvalidOption(m) if !m.contains("out of range")),
            "non-digit cols must short-circuit before u8 parse; got {err:?}"
        );

        // u8 overflow on rows — 256 > 255. Distinct message stem
        // ("rows component out of range") pins which u8 parse fired.
        let err = parse_version_string("256x2").unwrap_err();
        assert!(
            matches!(&err, Error::InvalidOption(m) if m.contains("rows component out of range")),
            "rows overflow: got {err:?}",
        );

        // u8 overflow on cols — 4x256.
        let err = parse_version_string("4x256").unwrap_err();
        assert!(
            matches!(
                &err,
                Error::InvalidOption(m) if m.contains("columns component out of range")
            ),
            "cols overflow: got {err:?}",
        );
    }

    /// Stage 11.A8c — pin `parse_raw_codewords(input)`. Parses BWIPP's
    /// `^NNN` raw-codeword token format used by `raw=true`. Each token
    /// is exactly 4 bytes: a literal `^` + 3 ASCII digits forming a
    /// value in 0..=928 (the GF(929) codeword range).
    ///
    /// Branches: empty → Ok(empty); single token; multiple tokens;
    /// missing caret; non-digit interior; value > 928; trailing bytes
    /// (input.len() % 4 != 0). All exercised end-to-end via the
    /// raw=true micropdf417 corpus but no direct unit anchor.
    ///
    /// Mutations killed:
    ///   * `i + 4 <= input.len()` → `<` (would drop the last full token);
    ///   * `value > 928` → `>=` (would reject 928, the valid max) or
    ///     `> 999` (would admit out-of-range codewords);
    ///   * `c - b'0'` → other arithmetic;
    ///   * `value * 10 + ...` → other base;
    ///   * `1..=3` → `1..=4` (would over-consume by one byte);
    ///   * `i += 4` → `+= 3` (cursor desync);
    ///   * caret guard removed/inverted.
    #[test]
    fn parse_raw_codewords_micropdf_token_format_and_range() {
        // Empty input → Ok([]).
        assert_eq!(parse_raw_codewords(b"").unwrap(), Vec::<u32>::new());

        // Single token: smallest value.
        assert_eq!(parse_raw_codewords(b"^000").unwrap(), vec![0]);
        // Mid value.
        assert_eq!(parse_raw_codewords(b"^123").unwrap(), vec![123]);
        // Boundary fit: 928 (max valid codeword in GF(929)).
        assert_eq!(
            parse_raw_codewords(b"^928").unwrap(),
            vec![928],
            "928 must fit (kills `> 928` → `>= 928`)"
        );

        // Two tokens.
        assert_eq!(parse_raw_codewords(b"^123^456").unwrap(), vec![123, 456]);

        // Three tokens.
        assert_eq!(parse_raw_codewords(b"^001^002^003").unwrap(), vec![1, 2, 3]);

        // ---- error branches -----------------------------------------
        // Stage 11.A8c — upgrade these 9 bare `is_err()` checks to pin
        // the path-specific diagnostic substring (parallel to the
        // strong sibling `parse_raw_codewords_rejects_malformed` in
        // a57b6b5). Provides defense-in-depth: if either test is ever
        // refactored to drop coverage, the other still pins each arm.
        //
        // parse_raw_codewords has 4 arms:
        //   * value > 928 → "must be 0..=928; got V"
        //   * missing/wrong `^` → "expected `^` at offset N, got 0xHH"
        //   * non-digit interior → "non-digit 0xHH at offset N"
        //   * trailing partial → "N trailing byte(s) at offset M"

        // Out of range: 929, 999 → value-range arm.
        for (input, want_value) in [(b"^929" as &[u8], "929"), (b"^999", "999")] {
            let err = parse_raw_codewords(input).unwrap_err();
            assert!(
                err.contains("must be 0..=928") && err.contains(want_value),
                "{input:?} must pin value-range diagnostic + {want_value:?}; got {err:?}"
            );
        }

        // Wrong leading byte → bad-prefix arm. Requires a full 4-byte
        // input so the while-loop iteration enters before the prefix
        // check (3-byte inputs like "123" fall through to the
        // trailing-bytes arm instead).
        for (input, want_byte) in [(b"$123" as &[u8], "0x24"), (b"1234", "0x31")] {
            let err = parse_raw_codewords(input).unwrap_err();
            assert!(
                err.contains("expected `^` at offset 0") && err.contains(want_byte),
                "{input:?} must pin bad-prefix diagnostic + {want_byte:?}; got {err:?}"
            );
        }

        // Non-digit interior → non-digit arm.
        for (input, want_offset) in [(b"^12A" as &[u8], "at offset 3"), (b"^A23", "at offset 1")] {
            let err = parse_raw_codewords(input).unwrap_err();
            assert!(
                err.contains("non-digit") && err.contains(want_offset),
                "{input:?} must pin non-digit diagnostic + {want_offset:?}; got {err:?}"
            );
        }

        // Trailing bytes after last full token → trailing-bytes arm.
        for (input, want_count) in [
            (b"^123^" as &[u8], "1 trailing byte(s)"),
            (b"^123^45", "3 trailing byte(s)"),
            (b"^", "1 trailing byte(s)"),
            (b"^12", "3 trailing byte(s)"),
        ] {
            let err = parse_raw_codewords(input).unwrap_err();
            assert!(
                err.contains("trailing") && err.contains(want_count),
                "{input:?} must pin trailing-bytes diagnostic + {want_count:?}; got {err:?}"
            );
        }
    }

    /// `append_bits(out, value, n)` appends `n` MSB-first bits of
    /// `value` to `out` as 0/1 u8s. Used by the MicroPDF417 codeword-
    /// to-bit-stream rendering pipeline (`render_cws` and friends).
    /// Never directly tested.
    ///
    /// Mutations to catch:
    /// * Shift index `(n - 1 - i)` → `(n - i)` (off-by-one shift).
    /// * Shift index → `i` (LSB-first instead of MSB-first).
    /// * Loop bound `0..n` → `0..=n` (extra bit).
    /// * Mask `& 1` → other mask.
    /// * Replace push with insert(0, …) (reverses order).
    #[test]
    fn append_bits_msb_first_bit_emission() {
        // Empty: n=0 is a no-op.
        let mut out = vec![];
        append_bits(&mut out, 42, 0);
        assert_eq!(out, Vec::<u8>::new(), "n=0 → no-op");

        // Single-bit values.
        let mut out = vec![];
        append_bits(&mut out, 0, 1);
        assert_eq!(out, vec![0], "0 in 1 bit → [0]");

        let mut out = vec![];
        append_bits(&mut out, 1, 1);
        assert_eq!(out, vec![1], "1 in 1 bit → [1]");

        // ---- MSB-first discriminator with asymmetric value.
        // 0b110 in 3 bits = [1, 1, 0] MSB-first.
        // LSB-first mutant would give [0, 1, 1].
        let mut out = vec![];
        append_bits(&mut out, 0b110, 3);
        assert_eq!(
            out,
            vec![1, 1, 0],
            "0b110 in 3 bits → [1, 1, 0] MSB-first (LSB mutant would give [0, 1, 1])"
        );

        let mut out = vec![];
        append_bits(&mut out, 0b100, 3);
        assert_eq!(
            out,
            vec![1, 0, 0],
            "0b100 in 3 bits → [1, 0, 0] MSB-first (LSB mutant would give [0, 0, 1])"
        );

        // ---- 4-bit symmetric value.
        let mut out = vec![];
        append_bits(&mut out, 0b1100, 4);
        assert_eq!(out, vec![1, 1, 0, 0]);

        // ---- Saturated all-ones.
        let mut out = vec![];
        append_bits(&mut out, 0b1111_1111, 8);
        assert_eq!(out, vec![1, 1, 1, 1, 1, 1, 1, 1], "all-ones 8 bits");

        // ---- Mixed bits — exercises the per-bit shift.
        // 0b10101010 = 0xAA.
        let mut out = vec![];
        append_bits(&mut out, 0xAA, 8);
        assert_eq!(out, vec![1, 0, 1, 0, 1, 0, 1, 0], "0xAA → alternating 1,0");

        // 0b01010101 = 0x55.
        let mut out = vec![];
        append_bits(&mut out, 0x55, 8);
        assert_eq!(out, vec![0, 1, 0, 1, 0, 1, 0, 1], "0x55 → alternating 0,1");

        // ---- Accumulator semantics: appends to existing buffer.
        let mut out = vec![5, 9];
        append_bits(&mut out, 0b10, 2);
        assert_eq!(
            out,
            vec![5, 9, 1, 0],
            "prior [5, 9] preserved, appended [1, 0]"
        );

        // ---- High-bit at boundary: pin that `& 1` mask is correct.
        // value=2 (0b10) in 2 bits: MSB-first → [1, 0].
        let mut out = vec![];
        append_bits(&mut out, 2, 2);
        assert_eq!(out, vec![1, 0]);

        // ---- 32-bit width: max u32 → 32 ones.
        let mut out = vec![];
        append_bits(&mut out, u32::MAX, 32);
        assert_eq!(out.len(), 32);
        assert!(out.iter().all(|&b| b == 1), "u32::MAX in 32 bits → 32 ones");

        // ---- Round-trip sweep: every 4-bit value 0..16 must
        // round-trip via base-2 reconstruction of the emitted bits.
        for v in 0u32..16 {
            let mut out = vec![];
            append_bits(&mut out, v, 4);
            assert_eq!(out.len(), 4, "v={v}: length must equal n=4");
            let reconstructed: u32 = out
                .iter()
                .enumerate()
                .map(|(i, &b)| (b as u32) << (3 - i))
                .sum();
            assert_eq!(
                reconstructed, v,
                "v={v} → bits {out:?} must reconstruct via MSB-first base-2"
            );
        }
    }

    /// Stage 11.A8c — pin `select_cca_metric_constrained` urows arm.
    /// The non-constrained `select_cca_metric` uses `urows=0` (no row
    /// constraint), so the actual `urows == 0 || urows == r` clause was
    /// never exercised with a non-zero `urows`. The function is used by
    /// `build_*_cca_composite_sized` paths when a user supplies an
    /// explicit row count, so the clause matters for explicit-size
    /// composite codes.
    ///
    /// Hand-computed against CCA_METRICS (17 rows, indexed in declaration
    /// order):
    ///   * Row 0 = (2, 5, 4, 39, 0, 19), capacity = 10-4 = 6.
    ///   * Row 3 = (2, 8, 5, 8, 0, 40),  capacity = 16-5 = 11.
    ///   * Row 8 = (3, 5, 5, 1, 33, 13), capacity = 15-5 = 10.
    ///   * Row 12 = (4, 3, 4, 40, 20, 52), capacity = 12-4 = 8.
    ///   * Row 16 = (4, 7, 8, 29, 9, 41), capacity = 28-8 = 20.
    ///
    /// Anchors:
    ///   1. (cw=5, ucols=2, urows=0) → row 0 (no row constraint).
    ///   2. (cw=5, ucols=2, urows=8) → row 3 (urows enforced, distinct
    ///      from row 0 — kills `urows == 0 || urows == r` → `true`).
    ///   3. (cw=5, ucols=3, urows=5) → row 8 (c=3 ∧ r=5).
    ///   4. (cw=12, ucols=3, urows=5) → None (row 8 cap=10 < 12; no other
    ///      c=3 r=5 row exists — pins the AND-merge of constraints).
    ///   5. (cw=5, ucols=4, urows=3) → row 12 (c=4 ∧ r=3).
    ///   6. (cw=20, ucols=4, urows=7) → row 16 (boundary: capacity == 20).
    ///   7. (cw=21, ucols=4, urows=7) → None (capacity 20 strictly < 21
    ///      kills the `>= cw_count` → `> cw_count` mutation).
    ///   8. (cw=0, ucols=0, urows=0) → row 0 (first row; all constraints
    ///      disabled).
    ///
    /// Mutations to catch:
    ///   * `urows == 0 || urows == r` → `true`: would return row 0 for
    ///     anchor 2 (instead of row 3).
    ///   * `urows == 0 || urows == r` → `urows == 0 && urows == r`:
    ///     would return None for anchor 2.
    ///   * `urows == r` → `urows != r`: would return None for anchor 2.
    ///   * `ucols == 0 || ucols == c` → `true`: would return row 0 for
    ///     anchor 3 (instead of row 8).
    ///   * `ncws >= cw_count` → `> cw_count`: would return None for
    ///     anchor 6 (cap=20 boundary).
    ///   * `&&` swapped to `||` anywhere collapses the conjunction.
    #[test]
    fn select_cca_metric_constrained_respects_row_and_col_constraints() {
        // Anchor 1: no urows ≡ select_cca_metric.
        let m = select_cca_metric_constrained(5, 2, 0).expect("5 cws c=2");
        assert_eq!(m, (2, 5, 4, 39, 0, 19), "no urows → smallest c=2 row");

        // Anchor 2: urows=8 forces row 3 instead of row 0.
        let m = select_cca_metric_constrained(5, 2, 8).expect("5 cws c=2 r=8");
        assert_eq!(
            m,
            (2, 8, 5, 8, 0, 40),
            "urows=8 must skip r=5 row 0 and land on r=8 row 3"
        );

        // Anchor 3: c=3 + r=5 → row 8.
        let m = select_cca_metric_constrained(5, 3, 5).expect("5 cws c=3 r=5");
        assert_eq!(m, (3, 5, 5, 1, 33, 13));

        // Anchor 4: capacity insufficient at the requested size → None.
        assert_eq!(
            select_cca_metric_constrained(12, 3, 5),
            None,
            "12 cws should not fit c=3 r=5 (cap=10) and no other c=3 r=5 row exists"
        );

        // Anchor 5: c=4 + r=3 → row 12.
        let m = select_cca_metric_constrained(5, 4, 3).expect("5 cws c=4 r=3");
        assert_eq!(m, (4, 3, 4, 40, 20, 52));

        // Anchor 6: boundary cw == capacity (20) accepted.
        let m = select_cca_metric_constrained(20, 4, 7).expect("20 cws c=4 r=7 (cap=20)");
        assert_eq!(
            m,
            (4, 7, 8, 29, 9, 41),
            "cap==cw boundary must be accepted (>= not >)"
        );

        // Anchor 7: one past capacity → None.
        assert_eq!(
            select_cca_metric_constrained(21, 4, 7),
            None,
            "21 cws should exceed c=4 r=7 max capacity (20)"
        );

        // Anchor 8: cw=0, no constraints → row 0.
        let m = select_cca_metric_constrained(0, 0, 0).expect("0 cws no constraints");
        assert_eq!(m, (2, 5, 4, 39, 0, 19), "first row of CCA_METRICS");

        // Consistency: select_cca_metric ≡ select_cca_metric_constrained(.., .., 0).
        for cw_count in [0, 1, 5, 10, 50, 100] {
            for ucols in [0u8, 2, 3, 4] {
                assert_eq!(
                    select_cca_metric(cw_count, ucols),
                    select_cca_metric_constrained(cw_count, ucols, 0),
                    "select_cca_metric must equal the (.., .., urows=0) variant for cw={cw_count} ucols={ucols}"
                );
            }
        }
    }
}