oxideav-otf 0.1.3

//! Type 2 charstring interpreter (Adobe TN5177).
//!
//! A Type 2 charstring is a stream of bytes representing operands
//! (signed integers + 16-bit fixed reals) and operators (path
//! construction, hint declaration, subroutine calls). Operands push
//! onto a stack; operators pop their inputs from it. The interpreter
//! maintains a "current point" (CP) that path operators advance.
//!
//! Operand encoding (TN5177 §3.2 / Tables 1, 2):
//! - byte b0 = 32..246          → integer  b0 - 139           (1 byte)
//! - byte b0 = 247..250         → integer  ((b0-247)*256 + b1 + 108)
//! - byte b0 = 251..254         → integer  -((b0-251)*256) - b1 - 108
//! - byte b0 = 28               → integer  i16 from b1..b2
//! - byte b0 = 255              → fixed real i16.16 from b1..b4
//! - byte b0 = 12               → 2-byte operator (escape)
//!
//! Operators implemented in round 1 (every common one a real font
//! uses):
//! - Path: rmoveto, hmoveto, vmoveto, rlineto, hlineto, vlineto,
//!   rrcurveto, hhcurveto, hvcurveto, vvcurveto, vhcurveto,
//!   rcurveline, rlinecurve, callsubr, callgsubr, return, endchar
//! - Hint: hstem, vstem, hstemhm, vstemhm, hintmask, cntrmask
//!   (recorded but not enforced — we'll antialias at >= 16 px)
//! - Flex: flex, hflex, hflex1, flex1
//! - Arithmetic (TN5177 §4.4): abs, add, sub, div, neg, mul, sqrt,
//!   random; stack: drop, dup, exch, index, roll
//! - Storage (TN5177 §4.5): put, get over a 32-element transient array
//!   (Appendix B)
//! - Conditional (TN5177 §4.6): and, or, not, eq, ifelse
//!
//! Arithmetic / storage / conditional operators differ from path
//! operators: they pop their inputs from the TOP of the argument stack
//! and push their result back, leaving the rest of the stack intact
//! (they never clear it).
//!
//! Width handling (TN5177 §4.7): the FIRST operand on the stack at
//! the time of the FIRST hstem / hstemhm / vstem / vstemhm /
//! cntrmask / hintmask / hmoveto / vmoveto / rmoveto / endchar is
//! treated as the glyph's advance-width *delta* from `nominalWidthX`
//! IF the stack count is one more than the operator's normal arity.
//! Otherwise the glyph uses `defaultWidthX`. We record the resolved
//! width even though it isn't currently surfaced — `Font::glyph_advance`
//! routes through `hmtx`, which is the spec-preferred path.

use crate::cff::charset::Charset;
use crate::cff::encoding::STANDARD_ENCODING;
use crate::cff::index::Index;
use crate::cff::subrs::bias_for;
use crate::outline::{CubicContour, CubicOutline, CubicSegment, Point};
use crate::Error;

/// Maximum subroutine recursion depth (TN5177 §4.5 says "no more
/// than 10 deep" for type 2; we use 16 to leave headroom for fonts
/// that push the limit).
const MAX_CALL_DEPTH: u8 = 16;

/// Maximum bytes a single charstring may consume before we abort.
/// Real-world charstrings are well under 2 KB; the cap exists
/// purely to bound adversarial / malformed input.
const MAX_BYTES_PROCESSED: usize = 1 << 20;

/// Type 2 operand stack — TN5177 §3 says it holds at most 48
/// numbers, but the OpenType profile bumps that to 96 (and we add
/// slack to keep panics out of unusual but valid fonts).
const STACK_CAP: usize = 192;

/// Transient-array element count for the `put` / `get` storage
/// operators (TN5177 Appendix B: "TransientArray elements 32").
const TRANSIENT_LEN: usize = 32;

/// A small helper for the interpreter's state.
pub(crate) struct Interpreter<'a> {
    /// Operand stack (cleared at every operator that consumes its
    /// operands).
    stack: Vec<f32>,
    /// Output outline being built.
    out: CubicOutline,
    /// Current subpath, accumulated until the next move terminator.
    current_contour: CubicContour,
    /// Current pen position (font-unit coordinates, Y-up).
    pen: Point,
    /// Most-recent move target — needed for the implicit ClosePath
    /// emitted at every subpath boundary.
    subpath_start: Point,
    /// Whether `current_contour` currently contains any segments
    /// (drives ClosePath emission and avoids producing empty
    /// contours for blank glyphs).
    contour_has_data: bool,

    /// Hints declared so far (not enforced). Counted because
    /// `hintmask` / `cntrmask` operators read a bitmask whose width
    /// depends on the hint count.
    hint_count: u32,

    /// Whether we've processed the first width-relevant operator yet
    /// — used to decode the charstring-encoded glyph advance width.
    seen_width_op: bool,
    /// Resolved glyph width in font units. `defaultWidthX` if no
    /// width was prepended to the first operator; otherwise
    /// `nominalWidthX + the stack's bottom value`.
    #[allow(dead_code)]
    pub(crate) glyph_width: f32,

    /// Local subroutines INDEX (may be `None` if the font has none).
    local_subrs: Option<&'a Index<'a>>,
    /// Global subroutines INDEX.
    global_subrs: &'a Index<'a>,
    /// Subroutine call depth.
    depth: u8,
    /// Bytes processed across all called subroutines (DoS cap).
    bytes_processed: usize,

    /// Width parameters from the Private DICT, used to resolve the
    /// first operator's optional leading width operand.
    nominal_width_x: f32,
    default_width_x: f32,

    /// CharStrings INDEX + Charset for the legacy `seac` (4-operand
    /// `endchar`) component lookup (TN5177 Appendix C). Both are
    /// required to resolve a `bchar` / `achar` byte via the Standard
    /// Encoding table; absent, a 4-operand `endchar` errors out.
    charstrings: Option<&'a Index<'a>>,
    charset: Option<&'a Charset<'a>>,
    /// True when this interpreter is itself a seac component — used
    /// to enforce TN5177 Appendix C's "may not be nested" rule.
    is_seac_component: bool,

    /// Transient array used by the `put` / `get` storage operators
    /// (TN5177 §4.5). Appendix B fixes its size at 32 elements. The
    /// spec offers "no provision to initialize this array, except
    /// explicitly using the `put` operator"; we zero-fill so that a
    /// `get` of an unwritten slot returns a defined 0 rather than
    /// erroring, matching the spec's "value returned is undefined"
    /// (a defined-but-arbitrary value is a conforming choice).
    transient: [f32; TRANSIENT_LEN],
    /// State for the `random` operator's pseudo-random generator
    /// (TN5177 §4.4). The spec only requires a value in (0, 1]; the
    /// sequence is deliberately deterministic so outline decoding is
    /// reproducible.
    rng_state: u32,
}

impl<'a> Interpreter<'a> {
    pub(crate) fn new(
        global_subrs: &'a Index<'a>,
        local_subrs: Option<&'a Index<'a>>,
        nominal_width_x: f32,
        default_width_x: f32,
    ) -> Self {
        Self {
            stack: Vec::with_capacity(STACK_CAP),
            out: CubicOutline::default(),
            current_contour: CubicContour::default(),
            pen: Point::new(0.0, 0.0),
            subpath_start: Point::new(0.0, 0.0),
            contour_has_data: false,
            hint_count: 0,
            seen_width_op: false,
            glyph_width: default_width_x,
            local_subrs,
            global_subrs,
            depth: 0,
            bytes_processed: 0,
            nominal_width_x,
            default_width_x,
            charstrings: None,
            charset: None,
            is_seac_component: false,
            transient: [0.0; TRANSIENT_LEN],
            // Non-zero seed so the very first `random` is in (0, 1];
            // an LCG never reaches 0 from a non-zero odd seed under
            // the modulus we use below.
            rng_state: 0x2545_F491,
        }
    }

    /// Equip the interpreter with the CharStrings INDEX + charset
    /// references needed to handle the deprecated four-operand
    /// `endchar` (Type 1 `seac`) form (TN5177 Appendix C). When both
    /// are absent, a 4-operand `endchar` returns
    /// [`Error::CharstringSeacBadComponent`] instead of resolving.
    pub(crate) fn with_seac_resolver(
        mut self,
        charstrings: &'a Index<'a>,
        charset: &'a Charset<'a>,
    ) -> Self {
        self.charstrings = Some(charstrings);
        self.charset = Some(charset);
        self
    }

    /// Run the top-level charstring `bytes` to completion (`endchar`).
    pub(crate) fn run(&mut self, bytes: &[u8]) -> Result<(), Error> {
        let result = self.execute(bytes);
        // .notdef and a small number of malformed glyphs may finish
        // without endchar — for round 1 we surface that as a
        // best-effort outline rather than a hard error, because real
        // fonts often have one or two glyphs that decode silently to
        // empty (the .notdef itself is usually a hand-drawn box that
        // does run to endchar, but some open-source toolchains emit
        // truly empty .notdef charstrings).
        match result {
            Ok(_) | Err(Error::CharstringEnd) => Ok(()),
            Err(e) => Err(e),
        }
    }

    /// Recursively interpret `bytes`. Returns Ok(()) at `return`
    /// (end-of-subr) and `Err(Error::CharstringEnd)` at `endchar`.
    fn execute(&mut self, bytes: &[u8]) -> Result<(), Error> {
        let mut i = 0usize;
        while i < bytes.len() {
            self.bytes_processed += 1;
            if self.bytes_processed > MAX_BYTES_PROCESSED {
                return Err(Error::CharstringTooLong);
            }
            let b0 = bytes[i];
            // Operand encodings — must check 255 (fixed real) BEFORE the
            // generic `>= 32` integer dispatch since the integer ranges
            // top out at 254.
            if b0 == 255 {
                // 16.16 fixed real.
                if i + 4 >= bytes.len() {
                    return Err(Error::UnexpectedEof);
                }
                let raw =
                    i32::from_be_bytes([bytes[i + 1], bytes[i + 2], bytes[i + 3], bytes[i + 4]]);
                let v = raw as f32 / 65536.0;
                self.push(v)?;
                i += 5;
                continue;
            }
            if b0 >= 32 {
                let (val, n) = parse_int_operand(bytes, i, b0)?;
                self.push(val as f32)?;
                i += n;
                continue;
            }
            if b0 == 28 {
                if i + 2 >= bytes.len() {
                    return Err(Error::UnexpectedEof);
                }
                let v = i16::from_be_bytes([bytes[i + 1], bytes[i + 2]]) as i32;
                self.push(v as f32)?;
                i += 3;
                continue;
            }

            // Operator (1-byte or escape).
            let op: u16 = if b0 == 12 {
                if i + 1 >= bytes.len() {
                    return Err(Error::UnexpectedEof);
                }
                let sub = bytes[i + 1];
                i += 2;
                0x0C00u16 | sub as u16
            } else {
                i += 1;
                b0 as u16
            };

            match op {
                // --- Path construction -------------------------------
                21 /* rmoveto */ => {
                    self.handle_initial_width(2);
                    let n = self.stack.len();
                    if n < 2 {
                        return Err(Error::CharstringStackUnderflow);
                    }
                    let dx = self.stack[n - 2];
                    let dy = self.stack[n - 1];
                    self.move_to(dx, dy);
                    self.stack.clear();
                }
                22 /* hmoveto */ => {
                    self.handle_initial_width(1);
                    let n = self.stack.len();
                    if n < 1 {
                        return Err(Error::CharstringStackUnderflow);
                    }
                    let dx = self.stack[n - 1];
                    self.move_to(dx, 0.0);
                    self.stack.clear();
                }
                4 /* vmoveto */ => {
                    self.handle_initial_width(1);
                    let n = self.stack.len();
                    if n < 1 {
                        return Err(Error::CharstringStackUnderflow);
                    }
                    let dy = self.stack[n - 1];
                    self.move_to(0.0, dy);
                    self.stack.clear();
                }
                5 /* rlineto */ => {
                    // Pairs of (dx, dy) until stack is empty.
                    let pairs = self.stack.len() / 2;
                    for k in 0..pairs {
                        let dx = self.stack[k * 2];
                        let dy = self.stack[k * 2 + 1];
                        self.line_to(dx, dy);
                    }
                    self.stack.clear();
                }
                6 /* hlineto */ => {
                    // Alternating: starts horizontal, then vertical, …
                    for (k, v) in self.stack.clone().into_iter().enumerate() {
                        if k % 2 == 0 {
                            self.line_to(v, 0.0);
                        } else {
                            self.line_to(0.0, v);
                        }
                    }
                    self.stack.clear();
                }
                7 /* vlineto */ => {
                    for (k, v) in self.stack.clone().into_iter().enumerate() {
                        if k % 2 == 0 {
                            self.line_to(0.0, v);
                        } else {
                            self.line_to(v, 0.0);
                        }
                    }
                    self.stack.clear();
                }
                8 /* rrcurveto */ => {
                    // Sextets of (dxa, dya, dxb, dyb, dxc, dyc).
                    let groups = self.stack.len() / 6;
                    for k in 0..groups {
                        let s = &self.stack[k * 6..k * 6 + 6];
                        self.r_curve_to(s[0], s[1], s[2], s[3], s[4], s[5]);
                    }
                    self.stack.clear();
                }
                27 /* hhcurveto */ => {
                    self.op_hhcurveto()?;
                }
                31 /* hvcurveto */ => {
                    self.op_hvcurveto()?;
                }
                26 /* vvcurveto */ => {
                    self.op_vvcurveto()?;
                }
                30 /* vhcurveto */ => {
                    self.op_vhcurveto()?;
                }
                24 /* rcurveline */ => {
                    // {dxa dya dxb dyb dxc dyc}+ dxd dyd
                    let n = self.stack.len();
                    if n < 8 || (n - 2) % 6 != 0 {
                        return Err(Error::CharstringStackUnderflow);
                    }
                    let groups = (n - 2) / 6;
                    for k in 0..groups {
                        let s = &self.stack[k * 6..k * 6 + 6];
                        self.r_curve_to(s[0], s[1], s[2], s[3], s[4], s[5]);
                    }
                    let dx = self.stack[n - 2];
                    let dy = self.stack[n - 1];
                    self.line_to(dx, dy);
                    self.stack.clear();
                }
                25 /* rlinecurve */ => {
                    // {dxa dya}+ dxb dyb dxc dyc dxd dyd
                    let n = self.stack.len();
                    if n < 8 || (n - 6) % 2 != 0 {
                        return Err(Error::CharstringStackUnderflow);
                    }
                    let lines = (n - 6) / 2;
                    for k in 0..lines {
                        let dx = self.stack[k * 2];
                        let dy = self.stack[k * 2 + 1];
                        self.line_to(dx, dy);
                    }
                    let s = &self.stack[lines * 2..lines * 2 + 6];
                    self.r_curve_to(s[0], s[1], s[2], s[3], s[4], s[5]);
                    self.stack.clear();
                }

                // --- Subroutines ---------------------------------------
                10 /* callsubr */ => {
                    let n = self.stack.len();
                    if n == 0 {
                        return Err(Error::CharstringStackUnderflow);
                    }
                    let biased = self.stack[n - 1] as i32;
                    self.stack.pop();
                    let subrs = self.local_subrs.ok_or(Error::CharstringNoLocalSubrs)?;
                    let idx = biased + bias_for(subrs.count);
                    self.call_subr(subrs, idx)?;
                }
                29 /* callgsubr */ => {
                    let n = self.stack.len();
                    if n == 0 {
                        return Err(Error::CharstringStackUnderflow);
                    }
                    let biased = self.stack[n - 1] as i32;
                    self.stack.pop();
                    let subrs = self.global_subrs;
                    let idx = biased + bias_for(subrs.count);
                    self.call_subr(subrs, idx)?;
                }
                11 /* return */ => {
                    return Ok(());
                }
                14 /* endchar */ => {
                    // Two stack shapes per TN5177:
                    //   §4.2:        [width?] endchar             — 0 or 1 operand.
                    //   App. C seac: [width?] adx ady bchar achar endchar
                    //                                            — 4 or 5 operands.
                    // We tolerate the spec by routing on the stack-count
                    // BEFORE consulting handle_initial_width, because the
                    // seac form's leading "width" works just like every
                    // other width-bearing operator (extra operand =
                    // delta-from-nominal, otherwise default).
                    let n = self.stack.len();
                    if n == 4 || n == 5 {
                        self.op_seac()?;
                        // op_seac handles width + component composition;
                        // it always ends the charstring.
                        return Err(Error::CharstringEnd);
                    }
                    self.handle_initial_width(0);
                    self.close_subpath_if_open();
                    return Err(Error::CharstringEnd);
                }

                // --- Hints (recorded but not enforced) -----------------
                1 /* hstem */ | 3 /* vstem */ | 18 /* hstemhm */ | 23 /* vstemhm */ => {
                    self.handle_initial_width_for_stem();
                    // Each hint is a (y, dy) pair. We record the count
                    // because hintmask / cntrmask later consume one
                    // bit per hint.
                    self.hint_count += (self.stack.len() / 2) as u32;
                    self.stack.clear();
                }
                19 /* hintmask */ | 20 /* cntrmask */ => {
                    self.handle_initial_width_for_stem();
                    // Implicit vstem: any operands on the stack are
                    // vertical hints.
                    self.hint_count += (self.stack.len() / 2) as u32;
                    self.stack.clear();
                    // Skip the bitmask: ceil(hint_count / 8) bytes.
                    let mask_bytes = (self.hint_count as usize).div_ceil(8);
                    if i + mask_bytes > bytes.len() {
                        return Err(Error::UnexpectedEof);
                    }
                    i += mask_bytes;
                }

                // --- Flex (two-byte) -----------------------------------
                // Adobe TN5177 §4.6 opcode assignments:
                //   12 34 → hflex   (0x0C22)
                //   12 35 → flex    (0x0C23)
                //   12 36 → hflex1  (0x0C24)
                //   12 37 → flex1   (0x0C25)
                0x0C22 /* hflex */ => self.op_hflex()?,
                0x0C23 /* flex */ => self.op_flex()?,
                0x0C24 /* hflex1 */ => self.op_hflex1()?,
                0x0C25 /* flex1 */ => self.op_flex1()?,

                // --- Arithmetic operators (TN5177 §4.4) ----------------
                // These pop their inputs from the TOP of the argument
                // stack and push the result back; unlike path operators
                // they do NOT clear the stack.
                0x0C09 /* abs    (12 9)  */ => { let a = self.arith_pop1()?; self.push(a.abs())?; }
                0x0C0A /* add    (12 10) */ => { let (a, b) = self.arith_pop2()?; self.push(a + b)?; }
                0x0C0B /* sub    (12 11) */ => { let (a, b) = self.arith_pop2()?; self.push(a - b)?; }
                0x0C0C /* div    (12 12) */ => {
                    // "result is undefined if overflow occurs and is
                    // zero for underflow." We map division by zero to
                    // 0.0 so a malformed font cannot inject a NaN/Inf
                    // into pen coordinates.
                    let (a, b) = self.arith_pop2()?;
                    self.push(if b == 0.0 { 0.0 } else { a / b })?;
                }
                0x0C0E /* neg    (12 14) */ => { let a = self.arith_pop1()?; self.push(-a)?; }
                0x0C18 /* mul    (12 24) */ => { let (a, b) = self.arith_pop2()?; self.push(a * b)?; }
                0x0C1A /* sqrt   (12 26) */ => {
                    // "If num is negative, the result is undefined."
                    let a = self.arith_pop1()?;
                    self.push(if a < 0.0 { 0.0 } else { a.sqrt() })?;
                }
                0x0C17 /* random (12 23) */ => { let r = self.next_random(); self.push(r)?; }

                // --- Stack-manipulation operators (TN5177 §4.4) --------
                0x0C12 /* drop   (12 18) */ => { self.arith_pop1()?; }
                0x0C1B /* dup    (12 27) */ => {
                    let a = self.arith_pop1()?;
                    self.push(a)?;
                    self.push(a)?;
                }
                0x0C1C /* exch   (12 28) */ => {
                    let n = self.stack.len();
                    if n < 2 {
                        return Err(Error::CharstringStackUnderflow);
                    }
                    self.stack.swap(n - 1, n - 2);
                }
                0x0C1D /* index  (12 29) */ => self.op_index()?,
                0x0C1E /* roll   (12 30) */ => self.op_roll()?,

                // --- Storage operators (TN5177 §4.5) -------------------
                0x0C14 /* put    (12 20) */ => {
                    // val i put — stores val at transient[i].
                    let (val, idx) = self.arith_pop2()?;
                    let i = idx as i32;
                    if i < 0 || i as usize >= TRANSIENT_LEN {
                        return Err(Error::CharstringTransientIndex(i));
                    }
                    self.transient[i as usize] = val;
                }
                0x0C15 /* get    (12 21) */ => {
                    // i get — pushes transient[i].
                    let idx = self.arith_pop1()?;
                    let i = idx as i32;
                    if i < 0 || i as usize >= TRANSIENT_LEN {
                        return Err(Error::CharstringTransientIndex(i));
                    }
                    let v = self.transient[i as usize];
                    self.push(v)?;
                }

                // --- Conditional operators (TN5177 §4.6) ---------------
                0x0C03 /* and    (12 3)  */ => {
                    let (a, b) = self.arith_pop2()?;
                    self.push(bool01(a != 0.0 && b != 0.0))?;
                }
                0x0C04 /* or     (12 4)  */ => {
                    let (a, b) = self.arith_pop2()?;
                    self.push(bool01(a != 0.0 || b != 0.0))?;
                }
                0x0C05 /* not    (12 5)  */ => {
                    let a = self.arith_pop1()?;
                    self.push(bool01(a == 0.0))?;
                }
                0x0C0F /* eq     (12 15) */ => {
                    let (a, b) = self.arith_pop2()?;
                    self.push(bool01(a == b))?;
                }
                0x0C16 /* ifelse (12 22) */ => {
                    // s1 s2 v1 v2 ifelse → s1 if v1 <= v2 else s2.
                    let n = self.stack.len();
                    if n < 4 {
                        return Err(Error::CharstringStackUnderflow);
                    }
                    let v2 = self.stack.pop().unwrap();
                    let v1 = self.stack.pop().unwrap();
                    let s2 = self.stack.pop().unwrap();
                    let s1 = self.stack.pop().unwrap();
                    self.push(if v1 <= v2 { s1 } else { s2 })?;
                }

                _ => {
                    return Err(Error::CharstringUnsupportedOp(op));
                }
            }
        }
        // Spec: charstring should end with an explicit endchar; we
        // tolerate a missing terminator here and let the caller
        // accept the partial outline.
        Ok(())
    }

    fn push(&mut self, v: f32) -> Result<(), Error> {
        if self.stack.len() >= STACK_CAP {
            return Err(Error::CharstringStackOverflow);
        }
        self.stack.push(v);
        Ok(())
    }

    /// Pop a single operand from the top of the argument stack for an
    /// arithmetic / storage / conditional operator (TN5177 §4.4-4.6).
    fn arith_pop1(&mut self) -> Result<f32, Error> {
        self.stack.pop().ok_or(Error::CharstringStackUnderflow)
    }

    /// Pop two operands from the top of the argument stack, returning
    /// them in pushed order `(num1, num2)` (num2 was on top).
    fn arith_pop2(&mut self) -> Result<(f32, f32), Error> {
        let b = self.stack.pop().ok_or(Error::CharstringStackUnderflow)?;
        let a = self.stack.pop().ok_or(Error::CharstringStackUnderflow)?;
        Ok((a, b))
    }

    /// `index` (12 29): `numX … num0 i index → numX … num0 numi`.
    /// Copies the element `i` deep from the top back onto the top. A
    /// negative `i` copies the top element (TN5177 §4.4). `i` greater
    /// than the available depth is "undefined"; we reject it.
    fn op_index(&mut self) -> Result<(), Error> {
        let i = self.arith_pop1()? as i32;
        let n = self.stack.len();
        if n == 0 {
            return Err(Error::CharstringStackUnderflow);
        }
        // i counts from the (new) top: i=0 → top element.
        let depth = if i < 0 { 0usize } else { i as usize };
        if depth >= n {
            return Err(Error::CharstringStackUnderflow);
        }
        let v = self.stack[n - 1 - depth];
        self.push(v)
    }

    /// `roll` (12 30): `num(N-1) … num0 N J roll` performs a circular
    /// shift of the top `N` elements by `J` (positive = upward, i.e.
    /// toward the top of the stack), per TN5177 §4.4.
    fn op_roll(&mut self) -> Result<(), Error> {
        let j = self.arith_pop1()? as i32;
        let nf = self.arith_pop1()?;
        let n = nf as i32;
        // "The value N must be a non-negative integer."
        if n < 0 {
            return Err(Error::CharstringStackUnderflow);
        }
        let n = n as usize;
        if n == 0 {
            return Ok(());
        }
        let len = self.stack.len();
        if n > len {
            return Err(Error::CharstringStackUnderflow);
        }
        let base = len - n;
        // Reduce J into [0, n) with positive = rotate-right within the
        // window (top element wraps to the bottom of the window for a
        // single upward step).
        let shift = j.rem_euclid(n as i32) as usize;
        if shift != 0 {
            self.stack[base..].rotate_right(shift);
        }
        Ok(())
    }

    /// `random` (12 23): returns a pseudo-random number in (0, 1].
    /// TN5177 §4.4 only constrains the range, so a deterministic LCG
    /// keeps outline decoding reproducible (no system entropy, which
    /// would also be a clean-room dependency surface).
    fn next_random(&mut self) -> f32 {
        // Numerical Recipes "minstd"-style 32-bit LCG. The next state
        // is never 0 for a non-zero seed under this multiplier, so the
        // mapped value stays strictly above 0; we map onto (0, 1].
        self.rng_state = self
            .rng_state
            .wrapping_mul(1_664_525)
            .wrapping_add(1_013_904_223);
        // Take 24 high bits → [0, 2^24); shift to [1, 2^24] → (0, 1].
        let bits = (self.rng_state >> 8) & 0x00FF_FFFF;
        (bits as f32 + 1.0) / 16_777_216.0
    }

    fn move_to(&mut self, dx: f32, dy: f32) {
        // Implicit ClosePath if a subpath was already open.
        self.close_subpath_if_open();
        self.pen.x += dx;
        self.pen.y += dy;
        self.subpath_start = self.pen;
        self.current_contour
            .segments
            .push(CubicSegment::MoveTo(self.pen));
        self.contour_has_data = true;
    }

    fn line_to(&mut self, dx: f32, dy: f32) {
        self.pen.x += dx;
        self.pen.y += dy;
        self.current_contour
            .segments
            .push(CubicSegment::LineTo(self.pen));
        self.contour_has_data = true;
    }

    fn r_curve_to(&mut self, dxa: f32, dya: f32, dxb: f32, dyb: f32, dxc: f32, dyc: f32) {
        let c1 = Point::new(self.pen.x + dxa, self.pen.y + dya);
        let c2 = Point::new(c1.x + dxb, c1.y + dyb);
        let end = Point::new(c2.x + dxc, c2.y + dyc);
        self.pen = end;
        self.current_contour
            .segments
            .push(CubicSegment::CurveTo { c1, c2, end });
        self.contour_has_data = true;
    }

    fn close_subpath_if_open(&mut self) {
        if self.contour_has_data {
            self.current_contour.segments.push(CubicSegment::ClosePath);
            // Move the finished contour into the outline.
            let finished = std::mem::take(&mut self.current_contour);
            self.out.contours.push(finished);
            self.contour_has_data = false;
        }
    }

    fn handle_initial_width(&mut self, normal_arity: usize) {
        if self.seen_width_op {
            return;
        }
        self.seen_width_op = true;
        if self.stack.len() == normal_arity + 1 {
            // Bottom-of-stack value is `width - nominalWidthX`.
            let delta = self.stack.remove(0);
            self.glyph_width = self.nominal_width_x + delta;
        } else {
            self.glyph_width = self.default_width_x;
        }
    }

    /// hstem / vstem-family special width handling: the stem operators
    /// consume an EVEN number of operands (pairs); if the stack count
    /// is odd, the first value is the optional width.
    fn handle_initial_width_for_stem(&mut self) {
        if self.seen_width_op {
            return;
        }
        self.seen_width_op = true;
        if self.stack.len() % 2 == 1 {
            let delta = self.stack.remove(0);
            self.glyph_width = self.nominal_width_x + delta;
        } else {
            self.glyph_width = self.default_width_x;
        }
    }

    fn call_subr(&mut self, subrs: &'a Index<'a>, idx: i32) -> Result<(), Error> {
        if idx < 0 || (idx as u32) >= subrs.count {
            return Err(Error::CharstringBadSubrIndex(idx));
        }
        if self.depth >= MAX_CALL_DEPTH {
            return Err(Error::CharstringTooDeep);
        }
        let body = subrs.entry(idx as u32)?;
        self.depth += 1;
        let r = self.execute(body);
        self.depth -= 1;
        r
    }

    pub(crate) fn into_outline(mut self) -> CubicOutline {
        // Any glyph that ends without endchar still gets its trailing
        // contour closed.
        self.close_subpath_if_open();
        self.out
    }

    // ----------------------------------------------------------------
    //   Curveto family (TN5177 §4.6) — these are encoded compactly
    //   to take advantage of horizontal / vertical-only entry & exit
    //   tangents that real fonts use overwhelmingly.
    // ----------------------------------------------------------------

    fn op_hhcurveto(&mut self) -> Result<(), Error> {
        // {dy1?} {dxa dxb dyb dxc}+
        // 4n or 4n+1 operands. dy1 is the leading vertical step on
        // the first segment; subsequent segments are pure-horizontal
        // tangent-in / tangent-out.
        let mut s = self.stack.clone();
        self.stack.clear();
        let mut dy1 = 0.0f32;
        if s.len() % 4 == 1 {
            dy1 = s.remove(0);
        }
        if s.len() % 4 != 0 {
            return Err(Error::CharstringStackUnderflow);
        }
        let mut first = true;
        for chunk in s.chunks_exact(4) {
            let dxa = chunk[0];
            let (dxb, dyb, dxc) = (chunk[1], chunk[2], chunk[3]);
            let dya = if first { dy1 } else { 0.0 };
            first = false;
            self.r_curve_to(dxa, dya, dxb, dyb, dxc, 0.0);
        }
        Ok(())
    }

    fn op_vvcurveto(&mut self) -> Result<(), Error> {
        // {dx1?} {dya dxb dyb dyc}+
        let mut s = self.stack.clone();
        self.stack.clear();
        let mut dx1 = 0.0f32;
        if s.len() % 4 == 1 {
            dx1 = s.remove(0);
        }
        if s.len() % 4 != 0 {
            return Err(Error::CharstringStackUnderflow);
        }
        let mut first = true;
        for chunk in s.chunks_exact(4) {
            let dya = chunk[0];
            let (dxb, dyb, dyc) = (chunk[1], chunk[2], chunk[3]);
            let dxa = if first { dx1 } else { 0.0 };
            first = false;
            self.r_curve_to(dxa, dya, dxb, dyb, 0.0, dyc);
        }
        Ok(())
    }

    fn op_hvcurveto(&mut self) -> Result<(), Error> {
        // Two-form operator: alternating starts-horizontal and
        // starts-vertical sextet groups, optionally with a final
        // df parameter on the closing curve to pick the off-axis end
        // delta. See TN5177 §4.6 form (a) / (b).
        let s = self.stack.clone();
        self.stack.clear();
        self.alt_curveto(s, /* h_first */ true)
    }

    fn op_vhcurveto(&mut self) -> Result<(), Error> {
        let s = self.stack.clone();
        self.stack.clear();
        self.alt_curveto(s, /* h_first */ false)
    }

    fn alt_curveto(&mut self, mut s: Vec<f32>, h_first: bool) -> Result<(), Error> {
        // The curveto shorthand pairs an ON-AXIS entry (horizontal or
        // vertical depending on `h_first`) with an off-axis exit.
        // After two segments the parity flips. Operands are consumed
        // in 4-byte sextets; if the total count is 4n+1 the trailing
        // value is the final "df" delta on the closing tangent.
        let trailing = if s.len() % 8 == 5 || s.len() % 8 == 1 {
            Some(s.pop().unwrap())
        } else {
            None
        };
        if s.len() % 4 != 0 {
            return Err(Error::CharstringStackUnderflow);
        }
        let mut horiz = h_first;
        let mut chunks: Vec<&[f32]> = s.chunks_exact(4).collect();
        let last_idx = chunks.len().saturating_sub(1);
        for (i, chunk) in chunks.iter_mut().enumerate() {
            let (dxa, dya, dxb, dyb, dxc, dyc);
            if horiz {
                // Entry horizontal, exit vertical (typically).
                dxa = chunk[0];
                dya = 0.0;
                dxb = chunk[1];
                dyb = chunk[2];
                dxc = if i == last_idx {
                    trailing.unwrap_or(0.0)
                } else {
                    0.0
                };
                dyc = chunk[3];
            } else {
                dxa = 0.0;
                dya = chunk[0];
                dxb = chunk[1];
                dyb = chunk[2];
                dxc = chunk[3];
                dyc = if i == last_idx {
                    trailing.unwrap_or(0.0)
                } else {
                    0.0
                };
            }
            self.r_curve_to(dxa, dya, dxb, dyb, dxc, dyc);
            horiz = !horiz;
        }
        Ok(())
    }

    // ----------------------------------------------------------------
    //   Flex (Adobe TN5177 §4.6, two-byte ops)
    //
    //   The flex family encodes a pair of cubic Beziers that together
    //   approximate a shallow hump (typically a serif or a soft
    //   curve below the hinting threshold). We decode each operator
    //   into two `rrcurveto`-equivalent emissions and let the
    //   downstream rasterizer collapse the hump if it wants — Type 2
    //   leaves the flex-depth hint advisory.
    //
    //   Opcodes:
    //     12 34 (0x0C22) — hflex
    //     12 35 (0x0C23) — flex
    //     12 36 (0x0C24) — hflex1
    //     12 37 (0x0C25) — flex1
    // ----------------------------------------------------------------

    fn op_flex(&mut self) -> Result<(), Error> {
        // `flex` operands (TN5177 §4.6):
        //   dx1 dy1 dx2 dy2 dx3 dy3 dx4 dy4 dx5 dy5 dx6 dy6 fd
        //
        // 13 operands. `fd` is the "flex depth" in hundredths of a
        // pixel: at small sizes the rasterizer is permitted to draw a
        // straight line instead of the two curves. We always emit
        // the two curves; the AA threshold downstream picks the
        // straight-line collapse if it cares.
        //
        // We accept 12 operands as a permissive shortcut for fonts
        // that omit the depth — the geometry is identical.
        let n = self.stack.len();
        if n != 12 && n != 13 {
            return Err(Error::CharstringStackUnderflow);
        }
        let s = self.stack.clone();
        self.stack.clear();
        self.r_curve_to(s[0], s[1], s[2], s[3], s[4], s[5]);
        self.r_curve_to(s[6], s[7], s[8], s[9], s[10], s[11]);
        Ok(())
    }

    fn op_hflex(&mut self) -> Result<(), Error> {
        // `hflex` operands (TN5177 §4.6):
        //   dx1 dx2 dy2 dx3 dx4 dx5 dx6                  (7 operands)
        //
        // The flex starts and ends on the same y as the pen. Only
        // dy2 carries an explicit y delta; the other five dy values
        // are implicit. We expand to two rrcurveto-equivalent curves:
        //   curve 1: (dx1, 0)    (dx2, dy2)   (dx3, 0)
        //   curve 2: (dx4, 0)    (dx5, -dy2)  (dx6, 0)
        // so the pen ends back at its original y (sum of all dy
        // deltas across both curves is 0).
        if self.stack.len() != 7 {
            return Err(Error::CharstringStackUnderflow);
        }
        let s = self.stack.clone();
        self.stack.clear();
        let (dx1, dx2, dy2, dx3, dx4, dx5, dx6) = (s[0], s[1], s[2], s[3], s[4], s[5], s[6]);
        self.r_curve_to(dx1, 0.0, dx2, dy2, dx3, 0.0);
        self.r_curve_to(dx4, 0.0, dx5, -dy2, dx6, 0.0);
        Ok(())
    }

    fn op_hflex1(&mut self) -> Result<(), Error> {
        // `hflex1` operands (TN5177 §4.6):
        //   dx1 dy1 dx2 dy2 dx3 dx4 dx5 dy5 dx6          (9 operands)
        //
        // Like hflex but the flex's start and end y must be equal —
        // the pen does NOT need to be on the baseline (so dy1 is
        // free), but the final dy6 is constrained by the closure
        // requirement. dy3 = 0 and dy4 = 0 (implicit), so:
        //   curve 1: (dx1, dy1) (dx2, dy2) (dx3, 0)
        //   curve 2: (dx4, 0)   (dx5, dy5) (dx6, dy6)
        // with dy6 = -(dy1 + dy2 + dy5) to close back to start-y.
        if self.stack.len() != 9 {
            return Err(Error::CharstringStackUnderflow);
        }
        let s = self.stack.clone();
        self.stack.clear();
        let (dx1, dy1, dx2, dy2, dx3) = (s[0], s[1], s[2], s[3], s[4]);
        let (dx4, dx5, dy5, dx6) = (s[5], s[6], s[7], s[8]);
        let dy6 = -(dy1 + dy2 + dy5);
        self.r_curve_to(dx1, dy1, dx2, dy2, dx3, 0.0);
        self.r_curve_to(dx4, 0.0, dx5, dy5, dx6, dy6);
        Ok(())
    }

    // ----------------------------------------------------------------
    //   Deprecated four-operand `endchar` (Type 1 `seac` legacy
    //   accented-character composite, TN5177 Appendix C).
    //
    //   Operand layout on entry to endchar:
    //     [width_delta?] adx ady bchar achar
    //
    //   `bchar` and `achar` are *codes* in the CFF Standard Encoding
    //   (TN5176 Appendix B §1): we resolve each code → SID via that
    //   table, then SID → GID via this font's charset. The `bchar`
    //   component is drawn at (0, 0); the `achar` component is drawn
    //   at (adx, ady). The composite's sidebearing is implicitly 0
    //   (TN5177 Appendix C: "all sidebearings are considered to be
    //   zero and hence unencoded in Type 2 charstrings").
    //
    //   The spec also forbids nesting — a component charstring may
    //   not itself end in 4-operand seac form.
    // ----------------------------------------------------------------
    fn op_seac(&mut self) -> Result<(), Error> {
        if self.is_seac_component {
            return Err(Error::CharstringSeacNested);
        }
        // First, handle the optional width: 5-operand form has a
        // leading width-delta, 4-operand form does not. We call
        // handle_initial_width(4) so the width logic stays in one place.
        self.handle_initial_width(4);
        // After width handling, the stack must be exactly 4.
        if self.stack.len() != 4 {
            return Err(Error::CharstringStackUnderflow);
        }
        let achar = self.stack[3] as i32;
        let bchar = self.stack[2] as i32;
        let ady = self.stack[1];
        let adx = self.stack[0];
        self.stack.clear();

        let charstrings = self
            .charstrings
            .ok_or(Error::CharstringSeacBadComponent(0))?;
        let charset = self.charset.ok_or(Error::CharstringSeacBadComponent(0))?;

        // Resolve bchar / achar codes (Standard Encoding → SID → GID).
        let b_gid = resolve_seac_component(bchar, charset)?;
        let a_gid = resolve_seac_component(achar, charset)?;

        // Close any open subpath in *this* (composite) glyph first so
        // the component contours sit alongside, not appended to, any
        // partial subpath. Practically the composite has no path of
        // its own, but the spec doesn't forbid one and a defensive
        // close keeps the geometry well-defined.
        self.close_subpath_if_open();

        // Sub-interpreters for bchar and achar. We carry forward the
        // same global / local subrs + Private DICT widths because
        // component charstrings are normal glyphs in the same font.
        self.render_seac_component(b_gid, 0.0, 0.0, charstrings, charset)?;
        self.render_seac_component(a_gid, adx, ady, charstrings, charset)?;
        Ok(())
    }

    /// Decode `gid`'s charstring as a seac component, translate every
    /// emitted point by `(off_x, off_y)`, and append the resulting
    /// contours to `self.out`. The sub-interpreter's own state is
    /// discarded after `into_outline()`.
    fn render_seac_component(
        &mut self,
        gid: u16,
        off_x: f32,
        off_y: f32,
        charstrings: &'a Index<'a>,
        charset: &'a Charset<'a>,
    ) -> Result<(), Error> {
        let body = charstrings
            .entry(gid as u32)
            .map_err(|_| Error::CharstringSeacBadComponent(0))?;
        let mut sub = Interpreter::new(
            self.global_subrs,
            self.local_subrs,
            self.nominal_width_x,
            self.default_width_x,
        )
        .with_seac_resolver(charstrings, charset);
        sub.is_seac_component = true;
        sub.run(body)?;
        let component_outline = sub.into_outline();
        for contour in component_outline.contours.into_iter() {
            let mut shifted = CubicContour::default();
            for seg in contour.segments.into_iter() {
                let shifted_seg = match seg {
                    CubicSegment::MoveTo(p) => {
                        CubicSegment::MoveTo(Point::new(p.x + off_x, p.y + off_y))
                    }
                    CubicSegment::LineTo(p) => {
                        CubicSegment::LineTo(Point::new(p.x + off_x, p.y + off_y))
                    }
                    CubicSegment::CurveTo { c1, c2, end } => CubicSegment::CurveTo {
                        c1: Point::new(c1.x + off_x, c1.y + off_y),
                        c2: Point::new(c2.x + off_x, c2.y + off_y),
                        end: Point::new(end.x + off_x, end.y + off_y),
                    },
                    CubicSegment::ClosePath => CubicSegment::ClosePath,
                };
                shifted.segments.push(shifted_seg);
            }
            if !shifted.segments.is_empty() {
                self.out.contours.push(shifted);
            }
        }
        Ok(())
    }

    fn op_flex1(&mut self) -> Result<(), Error> {
        // `flex1` operands (TN5177 §4.6):
        //   dx1 dy1 dx2 dy2 dx3 dy3 dx4 dy4 dx5 dy5 d6   (11 operands)
        //
        // The dominant axis of the cumulative motion across the first
        // five (dx,dy) pairs picks whether d6 names the x or y delta
        // of the closing endpoint; the OTHER axis is computed to
        // bring the pen back to the start coordinate on that axis.
        // Specifically (TN5177): "if abs(sum_dx) > abs(sum_dy), d6
        // is dx6 and dy6 = -sum_dy; otherwise d6 is dy6 and
        // dx6 = -sum_dx".
        if self.stack.len() != 11 {
            return Err(Error::CharstringStackUnderflow);
        }
        let s = self.stack.clone();
        self.stack.clear();
        let sum_dx = s[0] + s[2] + s[4] + s[6] + s[8];
        let sum_dy = s[1] + s[3] + s[5] + s[7] + s[9];
        let (dx6, dy6) = if sum_dx.abs() > sum_dy.abs() {
            (s[10], -sum_dy)
        } else {
            (-sum_dx, s[10])
        };
        self.r_curve_to(s[0], s[1], s[2], s[3], s[4], s[5]);
        self.r_curve_to(s[6], s[7], s[8], s[9], dx6, dy6);
        Ok(())
    }
}

/// Resolve a seac component byte (Type 1 `bchar` / `achar`) to a GID
/// via the CFF Standard Encoding (TN5176 Appendix B §1) followed by
/// the font's per-glyph charset.
///
/// Returns [`Error::CharstringSeacBadComponent`] for any byte outside
/// `0..=255` (the operand technically lives in i32 because it came
/// off the Type 2 number stack), for codes that Standard Encoding
/// leaves unassigned (SID 0 .notdef), or for codes whose SID has no
/// matching glyph in this font.
fn resolve_seac_component(code: i32, charset: &Charset<'_>) -> Result<u16, Error> {
    if !(0..=255).contains(&code) {
        return Err(Error::CharstringSeacBadComponent(0));
    }
    let code_u = code as u8;
    let sid = STANDARD_ENCODING[code_u as usize];
    if sid == 0 {
        return Err(Error::CharstringSeacBadComponent(code_u));
    }
    charset
        .gid_of_sid(sid)
        .ok_or(Error::CharstringSeacBadComponent(code_u))
}

/// Decode a single integer operand from `bytes` starting at `i`.
/// Returns `(value, bytes_consumed)`.
fn parse_int_operand(bytes: &[u8], i: usize, b0: u8) -> Result<(i32, usize), Error> {
    match b0 {
        32..=246 => Ok((b0 as i32 - 139, 1)),
        247..=250 => {
            if i + 1 >= bytes.len() {
                return Err(Error::UnexpectedEof);
            }
            let v = (b0 as i32 - 247) * 256 + bytes[i + 1] as i32 + 108;
            Ok((v, 2))
        }
        251..=254 => {
            if i + 1 >= bytes.len() {
                return Err(Error::UnexpectedEof);
            }
            let v = -((b0 as i32 - 251) * 256) - bytes[i + 1] as i32 - 108;
            Ok((v, 2))
        }
        _ => Err(Error::Cff("invalid charstring integer operand byte")),
    }
}

/// Maps a Rust bool to the Type 2 conditional-operator result encoding
/// (`1_or_0`): the spec's `and` / `or` / `not` / `eq` push 1 for true
/// and 0 for false (TN5177 §4.6).
fn bool01(b: bool) -> f32 {
    if b {
        1.0
    } else {
        0.0
    }
}

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

    fn empty_index() -> Vec<u8> {
        vec![0u8, 0]
    }

    fn run(cs: &[u8]) -> CubicOutline {
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        interp.run(cs).unwrap();
        let mut o = interp.into_outline();
        o.recompute_bounds();
        o
    }

    #[test]
    fn endchar_only_yields_empty_outline() {
        // Just an endchar.
        let o = run(&[14]);
        assert!(o.is_empty());
    }

    #[test]
    fn single_rmoveto_lineto_box() {
        // width? (none) → uses defaultWidthX = 500
        // rmoveto 100 100 → MoveTo(100, 100)
        // hlineto 50 → LineTo(150, 100)
        // vlineto 50 → LineTo(150, 150)
        // hlineto -50 → LineTo(100, 150)
        // endchar
        // Encode: 100 = 139 + 100 = 239, -50 = 139 - 50 = 89.
        // rmoveto = 21, hlineto = 6, vlineto = 7.
        let cs = [
            239, 239, 21, // rmoveto 100 100
            189, 6, // hlineto 50  (50 = 139+50 = 189)
            189, 7, // vlineto 50
            89, 6,  // hlineto -50
            14, // endchar
        ];
        let o = run(&cs);
        assert_eq!(o.contours.len(), 1);
        let segs = &o.contours[0].segments;
        // MoveTo + 3 LineTo + ClosePath = 5 segments.
        assert_eq!(segs.len(), 5);
        assert!(matches!(segs[0], CubicSegment::MoveTo(_)));
        assert!(matches!(segs[4], CubicSegment::ClosePath));
        // Bounds reflect the box.
        assert_eq!(o.bounds.x_min, 100.0);
        assert_eq!(o.bounds.x_max, 150.0);
        assert_eq!(o.bounds.y_min, 100.0);
        assert_eq!(o.bounds.y_max, 150.0);
    }

    #[test]
    fn rrcurveto_emits_cubic() {
        let cs = [
            239, 239, 21, // rmoveto 100 100
            // rrcurveto 50 0 50 50 0 50 → curve from pen through
            // (150, 100), (200, 150) to (200, 200).
            189, 139, 189, 189, 139, 189, 8, 14,
        ];
        let o = run(&cs);
        assert_eq!(o.contours.len(), 1);
        let segs = &o.contours[0].segments;
        assert_eq!(segs.len(), 3); // MoveTo, CurveTo, ClosePath
        if let CubicSegment::CurveTo { c1, c2, end } = segs[1] {
            assert_eq!(c1, Point::new(150.0, 100.0));
            assert_eq!(c2, Point::new(200.0, 150.0));
            assert_eq!(end, Point::new(200.0, 200.0));
        } else {
            panic!("expected CurveTo, got {:?}", segs[1]);
        }
    }

    #[test]
    fn callgsubr_jumps_and_returns() {
        // Build a global subrs INDEX with one subroutine that emits
        // a single hlineto then `return`. Then call it from the
        // top-level charstring.
        //
        // Subr body: 189, 6, 11   (hlineto 50, return)
        // INDEX header: count=1, offSize=1, offsets=[1, 4], data=189 6 11
        let subr_body = vec![189, 6, 11];
        let mut subr_index_bytes = vec![
            0x00, 0x01, // count
            0x01, // offSize
            0x01, 0x04, // offsets (1, 4)
        ];
        subr_index_bytes.extend_from_slice(&subr_body);

        let subrs = Index::parse(&subr_index_bytes, 0).unwrap();
        assert_eq!(subrs.count, 1);

        // Top-level charstring: rmoveto 100 100, callgsubr -107
        // (which after bias 107 → subroutine 0), endchar.
        // -107 encoded: 139 - 107 = 32. So byte 32.
        let cs = [
            239, 239, 21, // rmoveto 100 100
            32, 29, // callgsubr (subr 0)
            14, // endchar
        ];
        let g = empty_index(); // we don't use locals here; globals provided below
        let global = subrs;
        let local_index_bytes = empty_index();
        let _local = Index::parse(&local_index_bytes, 0).unwrap();
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        interp.run(&cs).unwrap();
        let mut o = interp.into_outline();
        o.recompute_bounds();
        // We expect MoveTo(100,100), LineTo(150,100), ClosePath.
        let segs = &o.contours[0].segments;
        assert_eq!(segs.len(), 3);
        if let CubicSegment::LineTo(p) = segs[1] {
            assert_eq!(p, Point::new(150.0, 100.0));
        } else {
            panic!("expected LineTo");
        }
        let _ = g; // silence "unused" if the empty placeholder is dropped above.
    }

    #[test]
    fn hintmask_skips_correct_bitmask_size() {
        // hstem 0 50 (1 hint), vstem 0 30 (1 hint) → hint_count = 2.
        // hintmask then must skip ceil(2/8) = 1 byte.
        // After the mask: rmoveto 100 100, endchar.
        let cs = [
            139, 189, 1, // hstem 0 50
            139, 167, 3, // vstem 0 (28-139=-111? — let's just use 28: 139+28=167)
            // hintmask + 1 mask byte
            19, 0xFF, // rmoveto 100 100
            239, 239, 21, 14,
        ];
        let o = run(&cs);
        // We don't assert on the geometry — just that parsing succeeded
        // (no UnexpectedEof from over-skipping the mask).
        assert_eq!(o.contours.len(), 1);
    }

    #[test]
    fn width_decoded_from_first_op_extra_operand() {
        // Stack at first hmoveto has 2 operands: width-delta + dx.
        // nominalWidthX = 100, default = 500. width-delta = 50 → resolved
        // width = 150.
        // 50 = 189, 100 = 239
        let cs = [189, 239, 22, 14]; // hmoveto 100, endchar
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let mut interp = Interpreter::new(&global, None, 100.0, 500.0);
        interp.run(&cs).unwrap();
        assert_eq!(interp.glyph_width, 150.0);
    }

    #[test]
    fn width_default_when_no_extra_operand() {
        // hmoveto 100 alone → exactly 1 operand → no width prefix →
        // glyph uses defaultWidthX = 500.
        let cs = [239, 22, 14];
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let mut interp = Interpreter::new(&global, None, 100.0, 500.0);
        interp.run(&cs).unwrap();
        assert_eq!(interp.glyph_width, 500.0);
    }

    // ----------------------------------------------------------------
    //   Flex-family hand-derived fixtures
    //
    //   Each test constructs a charstring whose only path operators
    //   are an rmoveto followed by one of the four flex operators
    //   plus endchar. The expected CubicSegment output is computed
    //   by hand from the operand expansion documented in TN5177
    //   §4.6 and re-checked against the implementation.
    //
    //   Operand encoding shortcut (TN5177 §3.2 single-byte form):
    //     value = byte - 139, i.e. byte = value + 139.
    //     0 = 139, +10 = 149, +20 = 159, +50 = 189,
    //     -5 = 134, -10 = 129, +100 = 239.
    //   Two-byte operators are emitted as bytes (12, sub) where
    //   sub = opcode_lo. flex = 35, hflex = 34, hflex1 = 36,
    //   flex1 = 37.
    // ----------------------------------------------------------------

    fn cubic_endpoint(seg: &CubicSegment) -> Point {
        match *seg {
            CubicSegment::MoveTo(p) | CubicSegment::LineTo(p) => p,
            CubicSegment::CurveTo { end, .. } => end,
            CubicSegment::ClosePath => Point::new(f32::NAN, f32::NAN),
        }
    }

    #[test]
    fn flex_op_expands_to_two_cubics() {
        // rmoveto 100 100, then flex with 13 operands. We pick a
        // symmetric hump: rising for curve 1, mirror-falling for
        // curve 2, with fd = 50 (flex depth — we don't act on it).
        //
        // Operands: dx1=10 dy1=5 dx2=10 dy2=10 dx3=10 dy3=5
        //           dx4=10 dy4=-5 dx5=10 dy5=-10 dx6=10 dy6=-5 fd=50
        // Expected:
        //   curve 1 control 1: (110, 105)
        //   curve 1 control 2: (120, 115)
        //   curve 1 end:        (130, 120)   ← join (peak of hump)
        //   curve 2 control 1: (140, 115)
        //   curve 2 control 2: (150, 105)
        //   curve 2 end:        (160, 100)   ← back to baseline y
        let cs = [
            239, 239, 21, // rmoveto 100 100
            149, 144, 149, 149, 149, 144, // 10 5 10 10 10 5
            149, 134, 149, 129, 149, 134, // 10 -5 10 -10 10 -5
            189, // fd = 50
            12, 35, // flex (0x0C23)
            14, // endchar
        ];
        let o = run(&cs);
        assert_eq!(o.contours.len(), 1);
        let segs = &o.contours[0].segments;
        // MoveTo + 2 CurveTo + ClosePath = 4 segments.
        assert_eq!(segs.len(), 4);
        if let CubicSegment::CurveTo { c1, c2, end } = segs[1] {
            assert_eq!(c1, Point::new(110.0, 105.0));
            assert_eq!(c2, Point::new(120.0, 115.0));
            assert_eq!(end, Point::new(130.0, 120.0));
        } else {
            panic!("expected first CurveTo, got {:?}", segs[1]);
        }
        if let CubicSegment::CurveTo { c1, c2, end } = segs[2] {
            assert_eq!(c1, Point::new(140.0, 115.0));
            assert_eq!(c2, Point::new(150.0, 105.0));
            assert_eq!(end, Point::new(160.0, 100.0));
        } else {
            panic!("expected second CurveTo, got {:?}", segs[2]);
        }
    }

    #[test]
    fn hflex_op_returns_to_baseline_y() {
        // rmoveto 100 100, hflex with 7 operands.
        //   dx1=10 dx2=10 dy2=20 dx3=10 dx4=10 dx5=10 dx6=10
        // Expansion:
        //   curve 1: (dx1, 0) (dx2, dy2) (dx3, 0)
        //   curve 2: (dx4, 0) (dx5, -dy2) (dx6, 0)
        // Expected control points (pen starts at (100,100)):
        //   c1.c1 = (110, 100); c1.c2 = (120, 120); c1.end = (130, 120)
        //   c2.c1 = (140, 120); c2.c2 = (150, 100); c2.end = (160, 100)
        let cs = [
            239, 239, 21, // rmoveto 100 100
            149, 149, 159, 149, 149, 149, 149, // 10 10 20 10 10 10 10
            12, 34, // hflex (0x0C22)
            14, // endchar
        ];
        let o = run(&cs);
        assert_eq!(o.contours.len(), 1);
        let segs = &o.contours[0].segments;
        assert_eq!(segs.len(), 4);
        if let CubicSegment::CurveTo { c1, c2, end } = segs[1] {
            assert_eq!(c1, Point::new(110.0, 100.0));
            assert_eq!(c2, Point::new(120.0, 120.0));
            assert_eq!(end, Point::new(130.0, 120.0));
        } else {
            panic!("expected hflex curve 1, got {:?}", segs[1]);
        }
        if let CubicSegment::CurveTo { c1, c2, end } = segs[2] {
            assert_eq!(c1, Point::new(140.0, 120.0));
            assert_eq!(c2, Point::new(150.0, 100.0));
            assert_eq!(end, Point::new(160.0, 100.0));
        } else {
            panic!("expected hflex curve 2, got {:?}", segs[2]);
        }
        // The flex must return the pen to start-y (100).
        assert_eq!(cubic_endpoint(&segs[2]).y, 100.0);
    }

    #[test]
    fn hflex1_op_closes_to_start_y() {
        // rmoveto 100 100, hflex1 with 9 operands.
        //   dx1=10 dy1=5 dx2=10 dy2=10 dx3=10
        //   dx4=10 dx5=10 dy5=-5 dx6=10
        // Expansion:
        //   curve 1: (dx1, dy1) (dx2, dy2) (dx3, 0)
        //   curve 2: (dx4, 0)   (dx5, dy5) (dx6, dy6)
        // with dy6 = -(dy1 + dy2 + dy5) = -(5 + 10 + -5) = -10
        // Expected segments:
        //   c1.c1 = (110, 105); c1.c2 = (120, 115); c1.end = (130, 115)
        //   c2.c1 = (140, 115); c2.c2 = (150, 110); c2.end = (160, 100)
        let cs = [
            239, 239, 21, // rmoveto 100 100
            149, 144, 149, 149, 149, // 10 5 10 10 10
            149, 149, 134, 149, // 10 10 -5 10
            12, 36, // hflex1 (0x0C24)
            14, // endchar
        ];
        let o = run(&cs);
        assert_eq!(o.contours.len(), 1);
        let segs = &o.contours[0].segments;
        assert_eq!(segs.len(), 4);
        if let CubicSegment::CurveTo { c1, c2, end } = segs[1] {
            assert_eq!(c1, Point::new(110.0, 105.0));
            assert_eq!(c2, Point::new(120.0, 115.0));
            assert_eq!(end, Point::new(130.0, 115.0));
        } else {
            panic!("expected hflex1 curve 1, got {:?}", segs[1]);
        }
        if let CubicSegment::CurveTo { c1, c2, end } = segs[2] {
            assert_eq!(c1, Point::new(140.0, 115.0));
            assert_eq!(c2, Point::new(150.0, 110.0));
            assert_eq!(end, Point::new(160.0, 100.0));
        } else {
            panic!("expected hflex1 curve 2, got {:?}", segs[2]);
        }
        // hflex1: end y must equal start y.
        assert_eq!(cubic_endpoint(&segs[2]).y, 100.0);
    }

    #[test]
    fn flex1_op_picks_dominant_x_axis() {
        // rmoveto 100 100, flex1 with 11 operands. Choose x-dominant
        // motion so d6 names dx6 and dy6 closes back to start y.
        //   dx1=10 dy1=5 dx2=10 dy2=5 dx3=10 dy3=5
        //   dx4=10 dy4=-5 dx5=10 dy5=-5 d6=50
        // sum_dx = 50, sum_dy = 5 → |sum_dx| > |sum_dy| → dx6 = 50,
        // dy6 = -5 (closes y back to 100).
        // Expected:
        //   c1.c1 = (110, 105); c1.c2 = (120, 110); c1.end = (130, 115)
        //   c2.c1 = (140, 110); c2.c2 = (150, 105); c2.end = (200, 100)
        let cs = [
            239, 239, 21, // rmoveto 100 100
            149, 144, 149, 144, 149, 144, // 10 5 10 5 10 5
            149, 134, 149, 134, // 10 -5 10 -5
            189, // d6 = 50
            12, 37, // flex1 (0x0C25)
            14, // endchar
        ];
        let o = run(&cs);
        assert_eq!(o.contours.len(), 1);
        let segs = &o.contours[0].segments;
        assert_eq!(segs.len(), 4);
        if let CubicSegment::CurveTo { c1, c2, end } = segs[1] {
            assert_eq!(c1, Point::new(110.0, 105.0));
            assert_eq!(c2, Point::new(120.0, 110.0));
            assert_eq!(end, Point::new(130.0, 115.0));
        } else {
            panic!("expected flex1 curve 1, got {:?}", segs[1]);
        }
        if let CubicSegment::CurveTo { c1, c2, end } = segs[2] {
            assert_eq!(c1, Point::new(140.0, 110.0));
            assert_eq!(c2, Point::new(150.0, 105.0));
            assert_eq!(end, Point::new(200.0, 100.0));
        } else {
            panic!("expected flex1 curve 2, got {:?}", segs[2]);
        }
        // dx-dominant flex1: y closes back to start.
        assert_eq!(cubic_endpoint(&segs[2]).y, 100.0);
    }

    #[test]
    fn flex1_op_picks_dominant_y_axis() {
        // y-dominant variant: swap roles so sum_dy > sum_dx.
        //   dx1=5 dy1=10 dx2=5 dy2=10 dx3=5 dy3=10
        //   dx4=-5 dy4=10 dx5=-5 dy5=10 d6=50
        // sum_dx = 5, sum_dy = 50 → |sum_dy| > |sum_dx| → dy6 = 50,
        // dx6 = -5 (closes x back to start x = 100).
        //
        // Pen starts at (100, 100).
        // Curve 1 absolute control / endpoint:
        //   c1.c1 = (105, 110); c1.c2 = (110, 120); c1.end = (115, 130)
        // Curve 2 absolute:
        //   c2.c1 = (110, 140); c2.c2 = (105, 150); c2.end = (100, 200)
        let cs = [
            239, 239, 21, // rmoveto 100 100
            144, 149, 144, 149, 144, 149, // 5 10 5 10 5 10
            134, 149, 134, 149, // -5 10 -5 10
            189, // d6 = 50
            12, 37, // flex1
            14, // endchar
        ];
        let o = run(&cs);
        let segs = &o.contours[0].segments;
        assert_eq!(segs.len(), 4);
        if let CubicSegment::CurveTo { c1, c2, end } = segs[1] {
            assert_eq!(c1, Point::new(105.0, 110.0));
            assert_eq!(c2, Point::new(110.0, 120.0));
            assert_eq!(end, Point::new(115.0, 130.0));
        } else {
            panic!("expected flex1-y curve 1, got {:?}", segs[1]);
        }
        if let CubicSegment::CurveTo { c1, c2, end } = segs[2] {
            assert_eq!(c1, Point::new(110.0, 140.0));
            assert_eq!(c2, Point::new(105.0, 150.0));
            assert_eq!(end, Point::new(100.0, 200.0));
        } else {
            panic!("expected flex1-y curve 2, got {:?}", segs[2]);
        }
        // dy-dominant flex1: x closes back to start.
        assert_eq!(cubic_endpoint(&segs[2]).x, 100.0);
    }

    #[test]
    fn flex_op_rejects_wrong_arity() {
        // flex requires 12 or 13 operands. 11 is too few.
        let cs = [
            239, 239, 21, // rmoveto 100 100
            149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, // 11x 10
            12, 35, // flex
            14,
        ];
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        let r = interp.run(&cs);
        assert!(matches!(r, Err(Error::CharstringStackUnderflow)));
    }

    #[test]
    fn hflex_op_rejects_wrong_arity() {
        // hflex requires exactly 7 operands.
        let cs = [
            239, 239, 21, // rmoveto 100 100
            149, 149, 149, 149, 149, 149, // 6 operands
            12, 34, // hflex
            14,
        ];
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        let r = interp.run(&cs);
        assert!(matches!(r, Err(Error::CharstringStackUnderflow)));
    }

    #[test]
    fn hflex1_op_rejects_wrong_arity() {
        let cs = [
            239, 239, 21, // rmoveto 100 100
            149, 149, 149, 149, 149, 149, 149, 149, // 8 operands
            12, 36, // hflex1
            14,
        ];
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        let r = interp.run(&cs);
        assert!(matches!(r, Err(Error::CharstringStackUnderflow)));
    }

    #[test]
    fn flex1_op_rejects_wrong_arity() {
        let cs = [
            239, 239, 21, // rmoveto 100 100
            149, 149, 149, 149, 149, 149, 149, 149, 149, 149, // 10 operands
            12, 37, // flex1
            14,
        ];
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        let r = interp.run(&cs);
        assert!(matches!(r, Err(Error::CharstringStackUnderflow)));
    }

    // ----------------------------------------------------------------
    //   seac (deprecated 4-operand endchar) — TN5177 Appendix C
    //
    //   These tests construct a tiny synthetic font fragment: a
    //   CharStrings INDEX with three glyphs (.notdef, 'A', 'grave')
    //   and a Format-0 charset that maps gid 1 → SID 34 ('A',
    //   Standard Encoding code 65) and gid 2 → SID 124 ('grave',
    //   Standard Encoding code 193). The top-level charstring then
    //   issues a 4-operand endchar to compose 'Agrave' from its
    //   pieces; the resulting outline should contain the contours of
    //   both components, with the 'grave' translated by (adx, ady).
    // ----------------------------------------------------------------

    fn build_seac_fixture() -> (Vec<u8>, Vec<u8>) {
        // Per-glyph charstrings:
        //   gid 0 (.notdef): endchar (14)
        //   gid 1 ('A'):     rmoveto 10 10 (lineto +20 0 +0 +20 -20 0), endchar
        //                   → square at (10,10) size 20.
        //   gid 2 ('grave'): rmoveto 5 5 (lineto +10 0 +0 +10 -10 0), endchar
        //                   → square at (5,5) size 10.
        // Operand encoding shortcut: value V = byte (V + 139) for the
        // single-byte form (V in -107..=+107). 10=149, 20=159, 5=144,
        // -20=119, -10=129.
        let notdef: Vec<u8> = vec![14];
        // rmoveto 10 10, hlineto 20, vlineto 20, hlineto -20, endchar
        let a: Vec<u8> = vec![
            149, 149, 21, // rmoveto 10 10
            159, 6, // hlineto 20
            159, 7, // vlineto 20
            119, 6,  // hlineto -20
            14, // endchar
        ];
        // rmoveto 5 5, hlineto 10, vlineto 10, hlineto -10, endchar
        let grave: Vec<u8> = vec![
            144, 144, 21, // rmoveto 5 5
            149, 6, // hlineto 10
            149, 7, // vlineto 10
            129, 6,  // hlineto -10
            14, // endchar
        ];
        // Build an INDEX with three entries.
        let mut data = Vec::new();
        data.extend_from_slice(&notdef);
        data.extend_from_slice(&a);
        data.extend_from_slice(&grave);
        // Offsets are 1-based: [1, 1+|notdef|, 1+|notdef|+|a|, total+1].
        let off1 = 1u8;
        let off2 = (1 + notdef.len()) as u8;
        let off3 = (1 + notdef.len() + a.len()) as u8;
        let off4 = (1 + notdef.len() + a.len() + grave.len()) as u8;
        let mut bytes = vec![
            0x00, 0x03, // count = 3
            0x01, // offSize = 1
            off1, off2, off3, off4,
        ];
        bytes.extend_from_slice(&data);
        // Charset Format 0 inline payload — 2 u16 SIDs for gids 1, 2.
        // SID 34 = 'A', SID 124 = 'grave' (per TN5176 Appendix A).
        let charset_payload = vec![0x00, 0x22, 0x00, 0x7C];
        (bytes, charset_payload)
    }

    #[test]
    fn seac_composes_two_components_with_offset() {
        let (cs_bytes, charset_payload) = build_seac_fixture();
        let charstrings = Index::parse(&cs_bytes, 0).unwrap();
        assert_eq!(charstrings.count, 3);
        let charset = Charset::Format0 {
            bytes: &charset_payload,
            num_glyphs: 3,
        };
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();

        // Composite charstring: adx ady bchar achar endchar.
        //   adx = 100 (= byte 239)
        //   ady = 50  (= byte 189)
        //   bchar = 65  ('A')      → byte 65+139=204
        //   achar = 193 ('grave')  → 193 > 107, use two-byte +108..+1131 form:
        //     193 = (b0-247)*256 + b1 + 108, pick b0=247 → 193 = 0 + b1 + 108 → b1=85.
        let top_cs = [
            239, // adx = 100
            189, // ady = 50
            204, // bchar = 65 ('A')
            247, 85, // achar = 193 ('grave')
            14, // endchar (4-arg seac form)
        ];
        let mut interp =
            Interpreter::new(&global, None, 0.0, 500.0).with_seac_resolver(&charstrings, &charset);
        interp.run(&top_cs).unwrap();
        let mut outline = interp.into_outline();
        outline.recompute_bounds();

        // Expect two contours: 'A' (square at 10,10 size 20) and
        // 'grave' (square at 5,5 size 10) shifted by (100, 50).
        // bchar 'A' bounds: x [10, 30], y [10, 30].
        // achar 'grave' is at (5,5) size 10, shifted by (100,50) →
        //   bounds x [105, 115], y [55, 65].
        // Combined bounds: x_min=10, y_min=10, x_max=115, y_max=65.
        assert_eq!(outline.contours.len(), 2);
        assert_eq!(outline.bounds.x_min, 10.0);
        assert_eq!(outline.bounds.y_min, 10.0);
        assert_eq!(outline.bounds.x_max, 115.0);
        assert_eq!(outline.bounds.y_max, 65.0);

        // First contour (bchar 'A') starts unshifted at (10, 10).
        if let CubicSegment::MoveTo(p) = outline.contours[0].segments[0] {
            assert_eq!(p, Point::new(10.0, 10.0));
        } else {
            panic!("bchar should open with MoveTo");
        }
        // Second contour (achar 'grave') is shifted by (100, 50) →
        // start point becomes (5+100, 5+50) = (105, 55).
        if let CubicSegment::MoveTo(p) = outline.contours[1].segments[0] {
            assert_eq!(p, Point::new(105.0, 55.0));
        } else {
            panic!("achar should open with MoveTo");
        }
    }

    #[test]
    fn seac_with_width_extra_operand_records_glyph_width() {
        // 5-operand endchar: width_delta + adx + ady + bchar + achar.
        // nominalWidthX = 100, width-delta = 50 → resolved width = 150.
        let (cs_bytes, charset_payload) = build_seac_fixture();
        let charstrings = Index::parse(&cs_bytes, 0).unwrap();
        let charset = Charset::Format0 {
            bytes: &charset_payload,
            num_glyphs: 3,
        };
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let top_cs = [
            189, // width_delta = 50
            239, // adx = 100
            189, // ady = 50
            204, // bchar = 65 ('A')
            247, 85, // achar = 193 ('grave')
            14, // endchar
        ];
        let mut interp = Interpreter::new(&global, None, 100.0, 500.0)
            .with_seac_resolver(&charstrings, &charset);
        interp.run(&top_cs).unwrap();
        assert_eq!(interp.glyph_width, 150.0);
    }

    #[test]
    fn seac_bchar_not_in_charset_is_an_error() {
        // 'Z' (Standard Encoding code 90, SID 59) is not in the
        // synthetic charset → CharstringSeacBadComponent.
        let (cs_bytes, charset_payload) = build_seac_fixture();
        let charstrings = Index::parse(&cs_bytes, 0).unwrap();
        let charset = Charset::Format0 {
            bytes: &charset_payload,
            num_glyphs: 3,
        };
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let top_cs = [
            139, 139, // adx = 0, ady = 0
            229, // bchar = 90 ('Z')
            204, // achar = 65 ('A')
            14,  // endchar
        ];
        let mut interp =
            Interpreter::new(&global, None, 0.0, 500.0).with_seac_resolver(&charstrings, &charset);
        let r = interp.run(&top_cs);
        assert!(matches!(r, Err(Error::CharstringSeacBadComponent(90))));
    }

    #[test]
    fn seac_without_resolver_errors_out() {
        // Same 4-operand endchar, but the interpreter never received
        // a charstrings/charset pair. The handler should refuse to
        // guess and surface CharstringSeacBadComponent.
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let top_cs = [139, 139, 204, 247, 85, 14];
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        let r = interp.run(&top_cs);
        assert!(matches!(r, Err(Error::CharstringSeacBadComponent(_))));
    }

    #[test]
    fn seac_nested_is_rejected() {
        // Build a fixture where gid 1's body is itself a 4-operand
        // endchar referring back to 'A'/'grave' — the spec forbids
        // nesting.
        // bchar = 65 ('A'), achar = 65 ('A') with adx = ady = 0.
        let nested_a: Vec<u8> = vec![139, 139, 204, 204, 14];
        let grave: Vec<u8> = vec![144, 144, 21, 149, 6, 149, 7, 129, 6, 14];
        let notdef: Vec<u8> = vec![14];
        let mut data = Vec::new();
        data.extend_from_slice(&notdef);
        data.extend_from_slice(&nested_a);
        data.extend_from_slice(&grave);
        let off1 = 1u8;
        let off2 = (1 + notdef.len()) as u8;
        let off3 = (1 + notdef.len() + nested_a.len()) as u8;
        let off4 = (1 + notdef.len() + nested_a.len() + grave.len()) as u8;
        let mut bytes = vec![0x00, 0x03, 0x01, off1, off2, off3, off4];
        bytes.extend_from_slice(&data);
        let charstrings = Index::parse(&bytes, 0).unwrap();
        let charset_payload = vec![0x00, 0x22, 0x00, 0x7C];
        let charset = Charset::Format0 {
            bytes: &charset_payload,
            num_glyphs: 3,
        };
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        // Outer composite calls gid 1, which itself wants to seac →
        // nested-seac error bubbles up.
        let top_cs = [139, 139, 204, 247, 85, 14];
        let mut interp =
            Interpreter::new(&global, None, 0.0, 500.0).with_seac_resolver(&charstrings, &charset);
        let r = interp.run(&top_cs);
        assert!(matches!(r, Err(Error::CharstringSeacNested)));
    }

    #[test]
    fn flex_family_opcodes_routed_per_tn5177() {
        // Sanity check: each flex two-byte opcode must trigger its
        // namesake handler. We feed each operator a stack count that
        // ONLY its handler accepts; any other handler would error.
        // This catches the opcode-shuffle bug we landed against in
        // round 91.
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();

        // hflex (12 34) accepts exactly 7 operands.
        let cs = [239, 239, 21, 149, 149, 149, 149, 149, 149, 149, 12, 34, 14];
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        interp
            .run(&cs)
            .expect("hflex (12 34) should accept 7 operands");

        // flex (12 35) accepts 12 or 13. 13 here.
        let cs = [
            239, 239, 21, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 12, 35,
            14,
        ];
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        interp
            .run(&cs)
            .expect("flex (12 35) should accept 13 operands");

        // hflex1 (12 36) accepts exactly 9 operands.
        let cs = [
            239, 239, 21, 149, 149, 149, 149, 149, 149, 149, 149, 149, 12, 36, 14,
        ];
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        interp
            .run(&cs)
            .expect("hflex1 (12 36) should accept 9 operands");

        // flex1 (12 37) accepts exactly 11 operands.
        let cs = [
            239, 239, 21, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 12, 37, 14,
        ];
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        interp
            .run(&cs)
            .expect("flex1 (12 37) should accept 11 operands");
    }

    // ---- Arithmetic / storage / conditional operators (TN5177 §4.4-4.6) ----

    /// Run a charstring and return the point of its first `MoveTo`.
    /// Used by the arithmetic-operator tests below: each computes an
    /// (x, y) on the stack via the operators under test, then a single
    /// `rmoveto` (op 21) consumes exactly the two computed operands, so
    /// the resulting pen position proves what the operators left.
    fn first_move(cs: &[u8]) -> Point {
        let o = run(cs);
        match o.contours[0].segments[0] {
            CubicSegment::MoveTo(p) => p,
            ref other => panic!("expected MoveTo, got {other:?}"),
        }
    }

    /// Run a charstring expected to fail, returning the error.
    fn run_err(cs: &[u8]) -> Error {
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        interp.run(cs).expect_err("charstring should have errored")
    }

    // Number encodings used below (single-byte ints, v in [-107,107]
    // encode as v + 139): 0→139, 5→144, 10→149, 50→189, 100→239,
    // -5→134, -50→89, 1→140, 2→141, 3→142, 4→143, 7→146.

    #[test]
    fn arith_add_sub() {
        // 50 50 add → 100 ; 200 100 sub → 100 ; rmoveto → (100, 100).
        let p = first_move(&[
            189, 189, 12, 10, // 50 50 add  → 100
            247, 92, 239, 12, 11, // 200 100 sub → 100  (200 = (247-247)*256+92+108)
            21, 14,
        ]);
        assert_eq!(p, Point::new(100.0, 100.0));
    }

    #[test]
    fn arith_neg_abs() {
        // -50 neg → 50 ; -50 abs → 50 ; rmoveto → (50, 50).
        let p = first_move(&[
            89, 12, 14, // -50 neg → 50
            89, 12, 9, // -50 abs → 50
            21, 14,
        ]);
        assert_eq!(p, Point::new(50.0, 50.0));
    }

    #[test]
    fn arith_mul_div() {
        // 10 10 mul → 100 ; 100 2 div → 50 ; rmoveto → (100, 50).
        let p = first_move(&[
            149, 149, 12, 24, // 10 10 mul → 100
            239, 141, 12, 12, // 100 2 div → 50
            21, 14,
        ]);
        assert_eq!(p, Point::new(100.0, 50.0));
    }

    #[test]
    fn arith_div_by_zero_is_zero() {
        // 100 0 div → 0 (spec: undefined on overflow; we choose 0).
        // 50 push, rmoveto → (0, 50).
        let p = first_move(&[
            239, 139, 12, 12,  // 100 0 div → 0
            189, // 50
            21, 14,
        ]);
        assert_eq!(p, Point::new(0.0, 50.0));
        assert!(p.x.is_finite());
    }

    #[test]
    fn arith_sqrt() {
        // 100 sqrt → 10 ; 4 sqrt → 2 ; rmoveto → (10, 2).
        let p = first_move(&[
            239, 12, 26, // 100 sqrt → 10
            143, 12, 26, // 4 sqrt → 2
            21, 14,
        ]);
        assert_eq!(p, Point::new(10.0, 2.0));
    }

    #[test]
    fn stack_dup_drop_exch() {
        // 50 dup → 50 50 ; drop → 50 ; (one operand) ; 100 exch then
        // rmoveto. Build: 50 dup drop → 50 ; 100 exch → 100 50 ;
        // rmoveto → (100, 50)? exch swaps top two: stack [50,100] →
        // exch → [100,50]; rmoveto reads bottom-two → (100, 50).
        let p = first_move(&[
            189, 12, 27, 12, 18, // 50 dup drop → 50
            239, 12, 28, // 100 exch → stack now [100, 50]
            21, 14,
        ]);
        assert_eq!(p, Point::new(100.0, 50.0));
    }

    #[test]
    fn stack_index() {
        // 10 50 1 index → 10 50 10  (copies element 1 deep). Then drop
        // the original duplicate context: stack is [10, 50, 10]. We
        // want rmoveto to read two operands, so drop one: stack
        // [10,50,10] → drop → [10,50] → rmoveto (10,50).
        let p = first_move(&[
            149, 189, 140, 12, 29, // 10 50 1 index → 10 50 10
            12, 18, // drop → 10 50
            21, 14,
        ]);
        assert_eq!(p, Point::new(10.0, 50.0));
    }

    #[test]
    fn stack_index_negative_copies_top() {
        // 10 50 -1 index → 10 50 50 (negative i copies top). Drop one
        // → 10 50; rmoveto → (10, 50).
        let p = first_move(&[
            149, 189, 138, 12, 29, // 10 50 -1 index → 10 50 50
            12, 18, // drop → 10 50
            21, 14,
        ]);
        assert_eq!(p, Point::new(10.0, 50.0));
    }

    #[test]
    fn stack_roll_upward() {
        // 10 50 100 3 1 roll → rotate top 3 up by 1.
        // Window [10,50,100] rolled up by 1 → [100,10,50]
        // (top element 100 wraps to the bottom of the window).
        // Drop one → [100,10]; rmoveto → (100, 10).
        let p = first_move(&[
            149, 189, 239, // 10 50 100
            142, 140, 12, 30, // 3 1 roll
            12, 18, // drop
            21, 14,
        ]);
        assert_eq!(p, Point::new(100.0, 10.0));
    }

    #[test]
    fn storage_put_get_roundtrip() {
        // 100 0 put — store 100 at slot 0. Then 50 (x), 0 get (→100)
        // gives stack [50, 100]; rmoveto → (50, 100).
        let p = first_move(&[
            239, 139, 12, 20,  // 100 0 put
            189, // 50
            139, 12, 21, // 0 get → 100
            21, 14,
        ]);
        assert_eq!(p, Point::new(50.0, 100.0));
    }

    #[test]
    fn storage_get_unwritten_is_zero() {
        // 5 get on an unwritten slot → 0 (we zero-fill). 50 push,
        // rmoveto → (50, 0).
        let p = first_move(&[
            189, // 50
            144, 12, 21, // 5 get → 0
            21, 14,
        ]);
        assert_eq!(p, Point::new(50.0, 0.0));
    }

    #[test]
    fn storage_put_out_of_range_errors() {
        // 100 50 put — index 50 >= 32 → error.
        let e = run_err(&[239, 189, 12, 20, 14]);
        assert!(matches!(e, Error::CharstringTransientIndex(50)));
    }

    #[test]
    fn cond_and_or_not() {
        // and: 1 0 and → 0 ; or: 0 1 or → 1 → so far stack [0,1].
        // not: top (1) not → 0 → stack [0,0]; rmoveto → (0,0).
        let p = first_move(&[
            140, 139, 12, 3, // 1 0 and → 0
            139, 140, 12, 4, // 0 1 or  → 1
            12, 5, // not (of the 1) → 0
            21, 14,
        ]);
        assert_eq!(p, Point::new(0.0, 0.0));
    }

    #[test]
    fn cond_eq() {
        // 50 50 eq → 1 ; 50 100 eq → 0 ; rmoveto → (1, 0).
        let p = first_move(&[
            189, 189, 12, 15, // 50 50 eq → 1
            189, 239, 12, 15, // 50 100 eq → 0
            21, 14,
        ]);
        assert_eq!(p, Point::new(1.0, 0.0));
    }

    #[test]
    fn cond_ifelse_picks_s1_when_v1_le_v2() {
        // s1 s2 v1 v2 ifelse → s1 if v1 <= v2. Use 10 50 1 2 ifelse →
        // 10 (since 1 <= 2). Push 50, rmoveto → (10, 50).
        let p = first_move(&[
            149, 189, 140, 141, 12, 22,  // 10 50 1 2 ifelse → 10
            189, // 50
            21, 14,
        ]);
        assert_eq!(p, Point::new(10.0, 50.0));
    }

    #[test]
    fn cond_ifelse_picks_s2_when_v1_gt_v2() {
        // 10 50 2 1 ifelse → 50 (since 2 > 1). Push 10, rmoveto →
        // (50, 10).
        let p = first_move(&[
            149, 189, 141, 140, 12, 22,  // 10 50 2 1 ifelse → 50
            149, // 10
            21, 14,
        ]);
        assert_eq!(p, Point::new(50.0, 10.0));
    }

    #[test]
    fn random_is_in_unit_interval() {
        // random twice then drop both — confirm the operator both
        // accepts no operands and produces a finite (0,1] value, by
        // routing the value into a coordinate and asserting the range.
        let g = empty_index();
        let global = Index::parse(&g, 0).unwrap();
        let mut interp = Interpreter::new(&global, None, 0.0, 500.0);
        // random → r ; 0 → stack [r, 0] ; rmoveto → MoveTo(r, 0).
        let cs = [12, 23, 139, 21, 14];
        interp.run(&cs).unwrap();
        let o = interp.into_outline();
        if let CubicSegment::MoveTo(p) = o.contours[0].segments[0] {
            assert!(p.x > 0.0 && p.x <= 1.0, "random {} not in (0,1]", p.x);
        } else {
            panic!("expected MoveTo");
        }
    }

    #[test]
    fn arith_underflow_errors() {
        // add with only one operand → underflow.
        let e = run_err(&[189, 12, 10, 14]);
        assert!(matches!(e, Error::CharstringStackUnderflow));
    }
}