draco-core 1.0.1

//! EdgeBreaker connectivity encoder.
//!
//! [`MeshEdgebreakerEncoder`] traverses the corner table and emits the
//! EdgeBreaker symbol stream that encodes mesh topology, plus the attribute-seam
//! connectivity ([`EdgebreakerAttributeConnectivity`]) used when attributes have
//! their own corner tables. Port of Draco's `mesh_edgebreaker_encoder.h`.

// Edgebreaker connectivity bitstream layout (C++-compatible).
//
// All integers are Varints unless specified otherwise.
//
// 1) num_vertices (total encoded vertices)
// 2) num_faces
// 3) num_attribute_data (non-position attributes)
// 4) num_encoded_symbols
// 5) num_split_symbols (count of Split symbols)
// 6) topology_split_event_data (see EncodeSplitData below)
// 7) traversal_buffer (as produced by Draco traversal encoder):
//    - bit-encoded traversal symbols (size-prefixed)
//    - start_face_configurations (rANS-bit)
//    - attribute_seam_data (rANS-bit per non-position attribute data entry)
//
// Split event encoding (from C++ EncodeSplitData):
//   - num_events (varint)
//   - For each event:
//     - delta(source_symbol_id) from last_source_symbol_id (varint)
//     - delta(source_symbol_id - split_symbol_id) (varint, always positive)
//   - All source_edge bits (1 bit each, direct bit-encoded; only if num_events > 0)

use crate::corner_table::CornerTable;
use crate::encoder_buffer::EncoderBuffer;
use crate::geometry_indices::{
    CornerIndex, FaceIndex, PointIndex, VertexIndex, INVALID_CORNER_INDEX, INVALID_FACE_INDEX,
    INVALID_VERTEX_INDEX,
};
use crate::mesh::Mesh;
use crate::mesh_edgebreaker_shared::{EdgeFaceName, EdgebreakerSymbol, TopologySplitEventData};
#[cfg(feature = "edgebreaker_valence_encode")]
use crate::mesh_edgebreaker_traversal_valence_encoder::MeshEdgebreakerTraversalValenceEncoder;
use crate::rans_bit_encoder::RAnsBitEncoder;
use crate::status::DracoError;
use crate::test_event_log;
use std::collections::HashMap;

#[derive(Debug, Clone)]
pub struct EdgebreakerAttributeConnectivity {
    pub attribute_id: i32,
    pub seam_edges: Vec<bool>,
    pub no_interior_seams: bool,
}

impl EdgebreakerAttributeConnectivity {
    pub fn build(mesh: &Mesh, corner_table: &CornerTable, attribute_id: i32) -> Self {
        let mut seam_edges = vec![false; corner_table.num_corners()];
        let mut no_interior_seams = true;
        let att = mesh.attribute(attribute_id);

        for c_idx in 0..corner_table.num_corners() {
            let c = CornerIndex(c_idx as u32);
            let face = corner_table.face(c);
            if face == INVALID_FACE_INDEX || corner_table.is_degenerated(face) {
                continue;
            }

            let opp = corner_table.opposite(c);
            if opp == INVALID_CORNER_INDEX {
                seam_edges[c_idx] = true;
                continue;
            }
            if opp.0 < c.0 {
                continue;
            }

            let mut is_interior_seam = false;
            let pairs = [
                (corner_table.next(c), corner_table.previous(opp)),
                (corner_table.previous(c), corner_table.next(opp)),
            ];
            for (a, b) in pairs {
                let pa = Self::corner_to_point_id(mesh, a);
                let pb = Self::corner_to_point_id(mesh, b);
                if att.mapped_index(pa) != att.mapped_index(pb) {
                    is_interior_seam = true;
                    break;
                }
            }

            if is_interior_seam {
                no_interior_seams = false;
                seam_edges[c.0 as usize] = true;
                seam_edges[opp.0 as usize] = true;
            }
        }

        Self {
            attribute_id,
            seam_edges,
            no_interior_seams,
        }
    }

    pub fn is_corner_opposite_to_seam_edge(&self, corner: CornerIndex) -> bool {
        if corner == INVALID_CORNER_INDEX {
            return false;
        }
        self.seam_edges
            .get(corner.0 as usize)
            .copied()
            .unwrap_or(false)
    }

    fn corner_to_point_id(mesh: &Mesh, corner: CornerIndex) -> PointIndex {
        let face = mesh.face(FaceIndex(corner.0 / 3));
        face[(corner.0 % 3) as usize]
    }
}

pub struct MeshEdgebreakerEncoder {
    visited_faces: Vec<bool>,
    visited_vertices: Vec<bool>,
    face_to_symbol_id: Vec<u32>,
    symbols: Vec<u32>,
    topology_split_event_data: Vec<TopologySplitEventData>,
    face_to_split_symbol_map: HashMap<usize, i32>,
    last_encoded_symbol_id: i32,

    // Traversal order for attribute encoding
    processed_connectivity_corners: Vec<CornerIndex>,
    init_face_connectivity_corners: Vec<CornerIndex>,
    init_face_input_indices: Vec<FaceIndex>, // Track which input faces are init faces

    // Sequence of vertices as they would be generated by the Decoder.
    // Stored per symbol (in Encoder order).
    symbol_to_encoder_corner: Vec<CornerIndex>,

    // Boundary tracking
    init_face_configurations: Vec<bool>,
    encoded_faces: Vec<(FaceIndex, CornerIndex)>,

    // Hole tracking (for boundary vertices)
    // Maps vertex index to hole id (-1 if not on a hole)
    vertex_hole_id: Vec<i32>,
    // Tracks which holes have been visited during encoding
    visited_holes: Vec<bool>,
    encoding_speed: usize,
    #[cfg(feature = "debug_logs")]
    verbose_logging: bool,

    #[cfg(feature = "edgebreaker_valence_encode")]
    valence_encoder: Option<MeshEdgebreakerTraversalValenceEncoder>,
    /// When set, emit the legacy predictive (type-1) traversal instead of
    /// standard/valence. Uses the standard traversal to collect symbols, then a
    /// post-pass replays them to build the prediction + main symbol streams.
    force_predictive: bool,
}

impl MeshEdgebreakerEncoder {
    #[inline(always)]
    fn verbose_logging(&self) -> bool {
        #[cfg(feature = "debug_logs")]
        {
            self.verbose_logging
        }
        #[cfg(not(feature = "debug_logs"))]
        {
            false
        }
    }

    pub fn new(num_faces: usize, num_vertices: usize) -> Self {
        Self {
            visited_faces: vec![false; num_faces],
            visited_vertices: vec![false; num_vertices],
            face_to_symbol_id: vec![u32::MAX; num_faces],
            symbols: Vec::new(),
            topology_split_event_data: Vec::new(),
            face_to_split_symbol_map: HashMap::new(),
            last_encoded_symbol_id: -1,
            processed_connectivity_corners: Vec::new(),
            init_face_connectivity_corners: Vec::new(),
            init_face_input_indices: Vec::new(),
            symbol_to_encoder_corner: Vec::new(),
            init_face_configurations: Vec::new(),
            encoded_faces: Vec::new(),
            vertex_hole_id: vec![-1; num_vertices],
            visited_holes: Vec::new(),
            encoding_speed: 5, // Default
            #[cfg(feature = "debug_logs")]
            verbose_logging: crate::debug_env_enabled("DRACO_VERBOSE"),
            #[cfg(feature = "edgebreaker_valence_encode")]
            valence_encoder: None,
            force_predictive: false,
        }
    }

    /// Selects the legacy predictive (type-1) traversal for the next encode.
    pub fn set_force_predictive(&mut self, force: bool) {
        self.force_predictive = force;
    }

    /// Find the starting corner for encoding a component.
    /// For boundary faces, returns the corner opposite to a boundary edge.
    /// This matches the C++ FindInitFaceConfiguration logic:
    /// Find the start corner for a face following C++ FindInitFaceConfiguration logic:
    /// - First check each corner for boundary edges (no opposite)
    /// - Also check for boundary vertices (vertex_hole_id != -1) and swing to find boundary edge
    /// - Returns (start_corner, is_interior) - interior is true if no boundary found
    fn find_init_face_configuration(
        &self,
        corner_table: &CornerTable,
        face_id: FaceIndex,
    ) -> (CornerIndex, bool) {
        let mut corner_index = corner_table.first_corner(face_id);

        for _ in 0..3 {
            // Check for boundary edge
            if corner_table.opposite(corner_index) == INVALID_CORNER_INDEX {
                // Boundary edge found - exterior configuration
                return (corner_index, false);
            }

            // Check for boundary vertex
            let vert_id = corner_table.vertex(corner_index);
            if self
                .vertex_hole_id
                .get(vert_id.0 as usize)
                .copied()
                .unwrap_or(-1)
                != -1
            {
                // Boundary vertex found. Find the first boundary edge attached to the point.
                let mut right_corner = corner_index;
                while right_corner != INVALID_CORNER_INDEX {
                    corner_index = right_corner;
                    right_corner = corner_table.swing_right(right_corner);
                }
                // corner_index now lies on a boundary edge and its previous corner is
                // guaranteed to be the opposite corner of the boundary edge.
                return (corner_table.previous(corner_index), false);
            }

            corner_index = corner_table.next(corner_index);
        }

        // Interior configuration: return the current corner (loops back to first after 3 iterations)
        (corner_index, true)
    }

    // Returns (point_ids, data_to_corner_map, vertex_to_data_map) as a tuple.
    // These three vectors represent different aspects of the attribute traversal mapping
    // and are logically separate outputs. Using a struct would obscure their independence.
    #[allow(clippy::type_complexity)]
    pub fn encode_connectivity(
        &mut self,
        mesh: &Mesh,
        corner_table: &CornerTable,
        attribute_connectivity: &[EdgebreakerAttributeConnectivity],
        out_buffer: &mut EncoderBuffer,
        speed: usize,
    ) -> Result<(Vec<PointIndex>, Vec<u32>, Vec<i32>), DracoError> {
        self.visited_faces = vec![false; mesh.num_faces()];
        // Use corner_table.num_vertices() instead of mesh.num_points()
        // because corner table may create additional vertices for non-manifold cases
        self.visited_vertices = vec![false; corner_table.num_vertices()];
        self.symbols.clear();
        self.topology_split_event_data.clear();
        self.face_to_split_symbol_map.clear();
        self.last_encoded_symbol_id = -1;
        self.init_face_configurations.clear();
        self.processed_connectivity_corners.clear();
        self.init_face_connectivity_corners.clear();
        self.init_face_input_indices.clear();
        self.symbol_to_encoder_corner.clear();
        self.encoded_faces.clear();
        self.encoding_speed = speed;

        // C++ uses standard encoding for:
        // 1. speed >= 5, OR
        // 2. tiny meshes (< 1000 faces) - overhead of predictive/valence is too big
        // See mesh_edgebreaker_encoder.cc: const bool is_tiny_mesh = mesh()->num_faces() < 1000;
        let is_tiny_mesh = mesh.num_faces() < 1000;

        #[cfg(feature = "edgebreaker_valence_encode")]
        if speed < 5 && !is_tiny_mesh && !self.force_predictive {
            let mut ve = MeshEdgebreakerTraversalValenceEncoder::new();
            ve.init(corner_table);
            self.valence_encoder = Some(ve);
        }
        #[cfg(not(feature = "edgebreaker_valence_encode"))]
        {
            let _ = speed;
            let _ = is_tiny_mesh;
        }
        #[cfg(feature = "edgebreaker_valence_encode")]
        if speed >= 5 || is_tiny_mesh {
            self.valence_encoder = None;
        }

        // Reset hole tracking
        self.vertex_hole_id = vec![-1; corner_table.num_vertices()];
        self.visited_holes.clear();

        // Find all holes (boundary loops) in the mesh before encoding
        self.find_holes(corner_table);

        // Traverse the surface starting from each unvisited corner (Draco C++ behavior).
        // For interior components, the init face is not represented by symbols; the
        // decoder reconstructs it from the start-face configuration stream.
        #[cfg(feature = "edgebreaker_valence_encode")]
        let mut valence_encoder = self.valence_encoder.take();
        #[cfg(not(feature = "edgebreaker_valence_encode"))]
        let mut valence_encoder = ();

        for c_id in 0..corner_table.num_corners() {
            let corner_index = CornerIndex(c_id as u32);
            let face_id = corner_table.face(corner_index);
            if face_id == crate::geometry_indices::INVALID_FACE_INDEX {
                continue;
            }
            if self.visited_faces[face_id.0 as usize] {
                continue;
            }
            if corner_table.is_degenerated(face_id) {
                continue;
            }

            let (start_corner, interior_config) =
                self.find_init_face_configuration(corner_table, face_id);
            self.init_face_configurations.push(interior_config);

            if interior_config {
                // Mark all vertices of the init face as visited.
                let v0 = corner_table.vertex(start_corner);
                let v1 = corner_table.vertex(corner_table.next(start_corner));
                let v2 = corner_table.vertex(corner_table.previous(start_corner));
                self.visited_vertices[v0.0 as usize] = true;
                self.visited_vertices[v1.0 as usize] = true;
                self.visited_vertices[v2.0 as usize] = true;

                // Mark the init face as visited (it is reconstructed on decode).
                self.visited_faces[face_id.0 as usize] = true;

                // Store the init-face connectivity corner (processed after regular corners).
                let init_corner = corner_table.next(start_corner);
                self.init_face_connectivity_corners.push(init_corner);
                // Track which input face this init face corresponds to
                self.init_face_input_indices.push(face_id);

                // Start compressing from the opposite face of the "next" corner.
                let opp_id = corner_table.opposite(init_corner);
                let opp_face_id = corner_table.face(opp_id);
                if opp_face_id != crate::geometry_indices::INVALID_FACE_INDEX
                    && !self.visited_faces[opp_face_id.0 as usize]
                {
                    self.encode_component(corner_table, opp_id, &mut valence_encoder)?;
                }
            } else {
                // Boundary configuration: start on the boundary.
                // Mark the init face as visited first to prevent re-processing
                // (Note: encode_component will also mark it when processing the first symbol)
                // First encode the hole that's opposite to the start_corner.
                let next_corner = corner_table.next(start_corner);
                self.encode_hole(corner_table, next_corner, true);

                // NOTE: For boundary case, C++ does NOT push to init_face_connectivity_corners.
                // The init face is reconstructed differently in the decoder.
                // We only track init_face_input_indices for our own debugging.
                self.init_face_input_indices.push(face_id);

                // Start processing the face containing the start_corner.
                self.encode_component(corner_table, start_corner, &mut valence_encoder)?;
            }
        }

        // Restore valence encoder ownership.
        #[cfg(feature = "edgebreaker_valence_encode")]
        {
            self.valence_encoder = valence_encoder;
        }

        // Write traversal decoder type (Standard = 0, Predictive = 1, Valence = 2).
        #[cfg(feature = "edgebreaker_valence_encode")]
        let traversal_decoder_type = if self.force_predictive {
            1
        } else if self.valence_encoder.is_some() {
            2
        } else {
            0
        };
        #[cfg(not(feature = "edgebreaker_valence_encode"))]
        let traversal_decoder_type = if self.force_predictive { 1 } else { 0 };
        out_buffer.encode_u8(traversal_decoder_type);

        let bitstream_version = out_buffer.bitstream_version();
        // Pre-2.0 stores the connectivity counts as fixed u32; 2.0+ uses varints.
        let legacy_u32_counts = cfg!(feature = "legacy_bitstream_encode")
            && bitstream_version != 0
            && bitstream_version < 0x0200;

        // Pre-2.2 connectivity carries a leading "new vertices" count (vertices
        // introduced during encoding) that the modern layout dropped. The decoder
        // reads but ignores the value, so 0 keeps the byte layout aligned. Behind
        // legacy_bitstream_encode and only when targeting a < 2.2 stream.
        #[cfg(feature = "legacy_bitstream_encode")]
        {
            if bitstream_version < 0x0200 {
                out_buffer.encode_u32(0);
            } else if bitstream_version < 0x0202 {
                out_buffer.encode_varint(0u64);
            }
        }

        // Write header (C++ format)
        let num_encoded_vertices =
            corner_table.num_vertices() - corner_table.num_isolated_vertices();
        let num_encoded_faces = corner_table.num_faces() - corner_table.num_degenerated_faces();
        let num_split_symbols = self
            .symbols
            .iter()
            .filter(|&&s| s == EdgebreakerSymbol::Split as u32)
            .count();

        if legacy_u32_counts {
            out_buffer.encode_u32(num_encoded_vertices as u32);
            out_buffer.encode_u32(num_encoded_faces as u32);
            out_buffer.encode_u8(attribute_connectivity.len() as u8);
            out_buffer.encode_u32(self.symbols.len() as u32);
            out_buffer.encode_u32(num_split_symbols as u32);
        } else {
            out_buffer.encode_varint(num_encoded_vertices as u64);
            out_buffer.encode_varint(num_encoded_faces as u64);
            out_buffer.encode_u8(attribute_connectivity.len() as u8);
            out_buffer.encode_varint(self.symbols.len() as u64);
            out_buffer.encode_varint(num_split_symbols as u64);
        }

        // Sort split data by source symbol id
        self.topology_split_event_data
            .sort_by_key(|e| e.source_symbol_id);

        // Pre-2.2 stores the connectivity (traversal) block length-prefixed, with
        // the hole/topology-split events placed *after* it; 2.2+ stores the events
        // inline before the traversal block. Behind legacy_bitstream_encode.
        let bitstream_version = out_buffer.bitstream_version();
        let legacy_layout = cfg!(feature = "legacy_bitstream_encode") && bitstream_version < 0x0202;

        if legacy_layout {
            let mut block = EncoderBuffer::new();
            block.set_version(out_buffer.version_major(), out_buffer.version_minor());
            self.encode_traversal_buffer(mesh, corner_table, attribute_connectivity, &mut block)?;
            if bitstream_version < 0x0200 {
                out_buffer.encode_u32(block.data().len() as u32);
            } else {
                out_buffer.encode_varint(block.data().len() as u64);
            }
            out_buffer.encode_data(block.data());
            self.encode_split_data(out_buffer)?;
        } else {
            // Encode split event data
            self.encode_split_data(out_buffer)?;
            // Encode traversal buffer (C++ compatible): symbols + start faces.
            self.encode_traversal_buffer(mesh, corner_table, attribute_connectivity, out_buffer)?;
        }

        // Generate attribute traversal order using DFS on the encoder's corner table.
        // This matches C++ MeshTraversalSequencer which uses SetCornerOrder(processed_connectivity_corners_).
        // The key is that encoder and decoder use the same DFS logic on topologically equivalent
        // corner tables, producing matching vertex_to_data_map values.
        if self.verbose_logging() {
            debug_log!(
                "Encoder: processed_connectivity_corners count = {}",
                self.processed_connectivity_corners.len()
            );
            debug_log!(
                "Encoder: processed_connectivity_corners (last 10) = {:?}",
                self.processed_connectivity_corners
                    .iter()
                    .rev()
                    .take(10)
                    .map(|c| c.0)
                    .collect::<Vec<_>>()
            );
            debug_log!(
                "Encoder: init_face_connectivity_corners = {:?}",
                self.init_face_connectivity_corners
                    .iter()
                    .map(|c| c.0)
                    .collect::<Vec<_>>()
            );
            // Show what corners will be processed first (after reversal + init)
            let mut corner_order: Vec<u32> = self
                .processed_connectivity_corners
                .iter()
                .rev()
                .map(|c| c.0)
                .collect();
            corner_order.extend(self.init_face_connectivity_corners.iter().map(|c| c.0));
            debug_log!(
                "Encoder: full corner_order (first 10) = {:?}",
                &corner_order[..10.min(corner_order.len())]
            );
            // Show corresponding face IDs
            let face_ids: Vec<u32> = corner_order.iter().take(10).map(|&c| c / 3).collect();
            debug_log!("Encoder: face IDs for first 10 corners = {:?}", face_ids);
            // Show corner_to_vertex mapping for those corners
            let vertices: Vec<u32> = corner_order
                .iter()
                .take(10)
                .map(|&c| corner_table.vertex(CornerIndex(c)).0)
                .collect();
            debug_log!(
                "Encoder: tip vertices for first 10 corners = {:?}",
                vertices
            );
            // Show encoder's corner table structure (limit to actual size)
            let num_corners = corner_table.num_faces() * 3;
            let print_limit = num_corners.min(36);
            debug_log!(
                "Encoder: opposites (first {}) = {:?}",
                print_limit,
                (0..print_limit)
                    .map(|c| corner_table.opposite(CornerIndex(c as u32)).0)
                    .collect::<Vec<_>>()
            );
            debug_log!(
                "Encoder: corner_to_vertex (first {}) = {:?}",
                print_limit,
                (0..print_limit)
                    .map(|c| corner_table.vertex(CornerIndex(c as u32)).0)
                    .collect::<Vec<_>>()
            );
        }
        let (point_ids, data_to_corner_map, vertex_to_data_map) =
            self.generate_attribute_traversal(mesh, corner_table);

        if self.verbose_logging() {
            debug_log!(
                "Encoder: Using corner_table with {} faces, {} vertices",
                corner_table.num_faces(),
                corner_table.num_vertices()
            );
            debug_log!(
                "Encoder: point_ids (first 10) = {:?}",
                point_ids.iter().take(10).collect::<Vec<_>>()
            );
            debug_log!(
                "Encoder: data_to_corner_map (first 10) = {:?}",
                &data_to_corner_map[..data_to_corner_map.len().min(10)]
            );
            debug_log!(
                "Encoder: vertex_to_data_map (first 10) = {:?}",
                &vertex_to_data_map[..vertex_to_data_map.len().min(10)]
            );
        }

        Ok((point_ids, data_to_corner_map, vertex_to_data_map))
    }

    /// Generates attribute traversal order using DFS on the encoder's corner table.
    /// This matches C++ MeshTraversalSequencer::GenerateSequenceInternal with SetCornerOrder.
    /// The C++ encoder uses processed_connectivity_corners_ as seeds for DFS.
    fn generate_attribute_traversal(
        &self,
        mesh: &Mesh,
        corner_table: &CornerTable,
    ) -> (Vec<PointIndex>, Vec<u32>, Vec<i32>) {
        let num_vertices = corner_table.num_vertices();
        let num_faces = corner_table.num_faces();

        let mut point_ids = Vec::with_capacity(num_vertices);
        let mut data_to_corner_map = Vec::with_capacity(num_vertices);
        let mut vertex_to_data_map = vec![-1i32; num_vertices];
        let mut visited_vertices = vec![false; num_vertices];
        let mut visited_faces = vec![false; num_faces];

        // C++ encoder uses processed_connectivity_corners (reversed) + init_face_connectivity_corners.
        // This matches C++ MeshTraversalSequencer::SetCornerOrder behavior exactly.
        let mut corner_order: Vec<CornerIndex> = self
            .processed_connectivity_corners
            .iter()
            .rev() // Reverse to get decode order (matches C++ std::reverse)
            .cloned()
            .collect();

        // Append init face corners (matches C++ insert at end)
        for &c in &self.init_face_connectivity_corners {
            corner_order.push(c);
        }

        #[cfg(feature = "debug_logs")]
        let debug_cmp = crate::debug_env_enabled("DRACO_DEBUG_CMP");
        #[cfg(not(feature = "debug_logs"))]
        let debug_cmp = false;
        let verbose = self.verbose_logging();
        let event_log_enabled = test_event_log::enabled();

        // Debug: compare corner_order with C++
        if debug_cmp {
            debug_log!(
                "RUST init_face_connectivity_corners = {:?}",
                self.init_face_connectivity_corners
                    .iter()
                    .map(|c| c.0)
                    .collect::<Vec<_>>()
            );
            debug_log!(
                "RUST corner_order: (first 10) = {:?}",
                corner_order
                    .iter()
                    .take(10)
                    .map(|c| c.0)
                    .collect::<Vec<_>>()
            );
            debug_log!(
                "RUST corner_order: (last 10) = {:?}",
                corner_order
                    .iter()
                    .rev()
                    .take(10)
                    .map(|c| c.0)
                    .collect::<Vec<_>>()
            );
            debug_log!("RUST corner_order total: {}", corner_order.len());
        }

        if verbose {
            debug_log!(
                "Encoder: ACTUAL corner_order (first 10) = {:?}",
                corner_order
                    .iter()
                    .take(10)
                    .map(|c| c.0)
                    .collect::<Vec<_>>()
            );
        }

        // Choose traversal method based on encoding speed
        // Speed 0 uses MaxPredictionDegree traversal for better compression (matches C++)
        if self.encoding_speed == 0 {
            if debug_cmp {
                debug_log!("RUST: Using MaxPredictionDegree traversal (speed 0)");
            }
            Self::max_prediction_degree_visit(
                &corner_order,
                mesh,
                corner_table,
                &mut point_ids,
                &mut data_to_corner_map,
                &mut vertex_to_data_map,
                &mut visited_vertices,
                &mut visited_faces,
            );
        } else {
            // DFS traversal for speeds 1-10
            if debug_cmp {
                debug_log!("RUST: Using DFS traversal (speed {})", self.encoding_speed);
            }
            // DFS is seeded from those corners in order.
            for (seed_idx, &corner) in corner_order.iter().enumerate() {
                let face = FaceIndex(corner.0 / 3);
                let face_already_visited = visited_faces[face.0 as usize];
                if face_already_visited {
                    if verbose && seed_idx < 15 {
                        debug_log!(
                            "Encoder: seed[{}] corner={} face={} was_visited=true added 0 points (total now {})",
                            seed_idx, corner.0, face.0, point_ids.len()
                        );
                    }
                    continue;
                }
                let old_point_count = point_ids.len();

                self.dfs_visit_from_corner_cpp(
                    corner,
                    mesh,
                    corner_table,
                    &mut point_ids,
                    &mut data_to_corner_map,
                    &mut vertex_to_data_map,
                    &mut visited_vertices,
                    &mut visited_faces,
                    verbose,
                    debug_cmp,
                    event_log_enabled,
                );

                let new_points = point_ids.len() - old_point_count;
                if verbose && (seed_idx < 15 || new_points > 0) {
                    debug_log!(
                        "Encoder: seed[{}] corner={} face={} was_visited={} added {} points (total now {})",
                        seed_idx, corner.0, face.0, face_already_visited, new_points, point_ids.len()
                    );
                }
            }
        }

        // Handle any unvisited vertices (isolated vertices or disconnected components)
        for vi in 0..num_vertices {
            if !visited_vertices[vi] {
                visited_vertices[vi] = true;
                let data_id = point_ids.len() as i32;
                vertex_to_data_map[vi] = data_id;
                // Find a corner that references this vertex
                let corner = corner_table.left_most_corner(VertexIndex(vi as u32));
                if corner != INVALID_CORNER_INDEX {
                    let mesh_face = FaceIndex(corner.0 / 3);
                    let corner_offset = (corner.0 % 3) as usize;
                    point_ids.push(mesh.face(mesh_face)[corner_offset]);
                    data_to_corner_map.push(corner.0);
                } else {
                    // Isolated vertex - use vertex index as point
                    point_ids.push(PointIndex(vi as u32));
                    data_to_corner_map.push(u32::MAX);
                }
            }
        }

        // Debug: print specific data_to_corner_map entries
        if debug_cmp {
            debug_log!(
                "RUST data_to_corner_map[0..5] = {:?}",
                &data_to_corner_map[0..5.min(data_to_corner_map.len())]
            );
            if data_to_corner_map.len() > 2498 {
                debug_log!(
                    "RUST data_to_corner_map[2498] = {}",
                    data_to_corner_map[2498]
                );
            }
        }

        (point_ids, data_to_corner_map, vertex_to_data_map)
    }

    /// DFS visit from a corner matching C++ DepthFirstTraverser::TraverseFromCorner.
    /// Maps vertices to mesh points directly.
    // DFS traversal state requires 8 parameters: start corner, mesh, corner table,
    // and 4 mutable output vectors (point_ids, corners, vertex_map, visited flags).
    // This is a performance-critical inner loop that matches C++ DepthFirstTraverser.
    #[allow(clippy::too_many_arguments)]
    fn dfs_visit_from_corner_cpp(
        &self,
        start_corner: CornerIndex,
        mesh: &Mesh,
        corner_table: &CornerTable,
        point_ids: &mut Vec<PointIndex>,
        data_to_corner_map: &mut Vec<u32>,
        vertex_to_data_map: &mut [i32],
        visited_vertices: &mut [bool],
        visited_faces: &mut [bool],
        verbose: bool,
        debug_cmp: bool,
        event_log_enabled: bool,
    ) {
        let start_face = corner_table.face(start_corner);
        if start_face == INVALID_FACE_INDEX || visited_faces[start_face.0 as usize] {
            return;
        }

        // DEBUG: First DFS call
        #[cfg(feature = "debug_logs")]
        {
            static DFS_COUNT: std::sync::atomic::AtomicUsize =
                std::sync::atomic::AtomicUsize::new(0);
            let count = DFS_COUNT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
            if count < 3 {
                debug_log!(
                    "Rust Encoder TraverseFromCorner STARTED: seed_corner={} face={} offset={}",
                    start_corner.0,
                    start_corner.0 / 3,
                    start_corner.0 % 3
                );
                // Show corner table structure
                let opposites: Vec<u32> = (0..12.min(corner_table.num_faces() * 3))
                    .map(|c| corner_table.opposite(CornerIndex(c as u32)).0)
                    .collect();
                let vertices: Vec<u32> = (0..12.min(corner_table.num_faces() * 3))
                    .map(|c| corner_table.vertex(CornerIndex(c as u32)).0)
                    .collect();
                debug_log!(
                    "Rust Encoder corner_table opposites (first 12): {:?}",
                    opposites
                );
                debug_log!(
                    "Rust Encoder corner_table vertices (first 12): {:?}",
                    vertices
                );
            }
        }

        let mut corner_stack: Vec<CornerIndex> = Vec::new();
        corner_stack.push(start_corner);

        // C++ visits Next, then Previous vertices BEFORE the main loop
        let next_c = corner_table.next(start_corner);
        let prev_c = corner_table.previous(start_corner);
        let next_vert = corner_table.vertex(next_c);
        let prev_vert = corner_table.vertex(prev_c);

        if next_vert == INVALID_VERTEX_INDEX || prev_vert == INVALID_VERTEX_INDEX {
            return;
        }

        // Helper to visit a vertex and record its point
        let mut visit_vertex = |c: CornerIndex, v: VertexIndex| {
            if !visited_vertices[v.0 as usize] {
                visited_vertices[v.0 as usize] = true;
                let mesh_face = FaceIndex(c.0 / 3);
                let corner_offset = (c.0 % 3) as usize;
                let mesh_point = mesh.face(mesh_face)[corner_offset];
                let data_id = point_ids.len() as i32;

                if event_log_enabled {
                    // Record parity events for tests: vertex mapping and canonical point id.
                    test_event_log::record_event(format!("MAP:{}->v{}", c.0, v.0));
                    test_event_log::record_event(format!("MAP_POINT:{}->p{}", c.0, mesh_point.0));
                }

                vertex_to_data_map[v.0 as usize] = data_id;
                point_ids.push(mesh_point);
                data_to_corner_map.push(c.0);
            }
        };

        // Visit Next vertex (before main loop)
        if verbose {
            let mesh_face = FaceIndex(next_c.0 / 3);
            let corner_offset = (next_c.0 % 3) as usize;
            let mesh_point = mesh.face(mesh_face)[corner_offset];
            debug_log!(
                "Encoder PREVISIT Next: corner={} vertex={} -> point={}",
                next_c.0,
                next_vert.0,
                mesh_point.0
            );
        }
        visit_vertex(next_c, next_vert);
        // Visit Previous vertex (before main loop)
        if verbose {
            let mesh_face = FaceIndex(prev_c.0 / 3);
            let corner_offset = (prev_c.0 % 3) as usize;
            let mesh_point = mesh.face(mesh_face)[corner_offset];
            debug_log!(
                "Encoder PREVISIT Prev: corner={} vertex={} -> point={}",
                prev_c.0,
                prev_vert.0,
                mesh_point.0
            );
        }
        visit_vertex(prev_c, prev_vert);

        // Main traversal loop
        while let Some(top_corner) = corner_stack.pop() {
            let mut corner_id = top_corner;
            let mut face_id = corner_table.face(corner_id);

            if corner_id == INVALID_CORNER_INDEX || visited_faces[face_id.0 as usize] {
                if verbose && point_ids.len() < 30 {
                    debug_log!(
                        "  DFS: popped corner={} face={} - SKIP (invalid or visited)",
                        corner_id.0,
                        face_id.0
                    );
                }
                continue;
            }
            if verbose && point_ids.len() < 30 {
                debug_log!(
                    "  DFS: popped corner={} face={} - processing",
                    corner_id.0,
                    face_id.0
                );
            }

            loop {
                visited_faces[face_id.0 as usize] = true;

                let vert_id = corner_table.vertex(corner_id);
                if vert_id == INVALID_VERTEX_INDEX {
                    if verbose && point_ids.len() < 30 {
                        debug_log!("  DFS: corner={} has INVALID vertex - break", corner_id.0);
                    }
                    break;
                }

                if !visited_vertices[vert_id.0 as usize] {
                    let on_boundary = self.is_vertex_on_boundary(corner_table, vert_id);

                    // Debug boundary check for specific vertices
                    if verbose && (vert_id.0 == 10 || vert_id.0 == 15 || vert_id.0 == 20) {
                        let lmc = corner_table.left_most_corner(vert_id);
                        let sl = corner_table.swing_left(lmc);
                        debug_log!("  DEBUG boundary check: vertex={} left_most_corner={} swing_left={} on_boundary={}",
                            vert_id.0, lmc.0, sl.0, on_boundary);
                    }

                    visited_vertices[vert_id.0 as usize] = true;

                    // Visit the tip vertex
                    let mesh_face = FaceIndex(corner_id.0 / 3);
                    let corner_offset = (corner_id.0 % 3) as usize;
                    let mesh_point = mesh.face(mesh_face)[corner_offset];
                    let data_id = point_ids.len() as i32;

                    // DEBUG: Print milestone visits for comparison with C++
                    if debug_cmp
                        && (data_id < 10
                            || data_id == 100
                            || data_id == 500
                            || data_id == 1000
                            || data_id == 1100
                            || data_id == 1200
                            || data_id == 1300
                            || data_id == 1400
                            || data_id == 1500
                            || data_id == 1600
                            || data_id == 1700
                            || data_id == 1800
                            || data_id == 1810
                            || data_id == 1820
                            || data_id == 1830
                            || data_id == 1840
                            || data_id == 1850
                            || data_id == 1860
                            || data_id == 1870
                            || data_id == 1871
                            || data_id == 1872
                            || data_id == 1873
                            || data_id == 1874
                            || data_id == 1875
                            || data_id == 1876
                            || data_id == 1877
                            || data_id == 1878
                            || data_id == 1879
                            || data_id == 1880
                            || data_id == 1890
                            || data_id == 1900
                            || data_id == 2000
                            || data_id == 2498)
                    {
                        debug_log!(
                            "RUST OnNewVertexVisited: data_id={} vertex={} corner={}",
                            data_id,
                            vert_id.0,
                            corner_id.0
                        );
                    }

                    vertex_to_data_map[vert_id.0 as usize] = data_id;
                    point_ids.push(mesh_point);
                    data_to_corner_map.push(corner_id.0);

                    if event_log_enabled {
                        // Record parity events: both vertex mapping and canonical point id.
                        test_event_log::record_event(format!(
                            "MAP:{}->v{}",
                            corner_id.0, vert_id.0
                        ));
                        test_event_log::record_event(format!(
                            "MAP_POINT:{}->p{}",
                            corner_id.0, mesh_point.0
                        ));
                    }

                    // DEBUG: Add detailed trace for specific data_id range
                    let debug_trace = debug_cmp && (1875..=1880).contains(&data_id);

                    if !on_boundary {
                        // Continue to right corner (GetRightCorner = Opposite(Next))
                        let right_c = corner_table.opposite(corner_table.next(corner_id));
                        if verbose && point_ids.len() < 30 {
                            debug_log!(
                                "  DFS: corner={} vertex={} NOT on boundary -> right_corner={}",
                                corner_id.0,
                                vert_id.0,
                                right_c.0
                            );
                        }
                        if debug_trace {
                            debug_log!("  TRACE data_id={}: vertex={} on_boundary={} -> continue right_c={}", data_id, vert_id.0, on_boundary, right_c.0);
                        }
                        corner_id = right_c;
                        if corner_id == INVALID_CORNER_INDEX {
                            break;
                        }

                        face_id = corner_table.face(corner_id);
                        continue;
                    } else {
                        if verbose && point_ids.len() < 30 {
                            debug_log!(
                                "  DFS: corner={} vertex={} ON BOUNDARY",
                                corner_id.0,
                                vert_id.0
                            );
                        }
                        if debug_trace {
                            debug_log!("  TRACE data_id={}: vertex={} on_boundary={} -> will check neighbors", data_id, vert_id.0, on_boundary);
                        }
                    }
                } else {
                    // Vertex already visited
                    if verbose && point_ids.len() < 30 {
                        debug_log!(
                            "  DFS: corner={} vertex={} ALREADY VISITED - check neighbors",
                            corner_id.0,
                            vert_id.0
                        );
                    }
                }

                // DEBUG: Add detailed trace for specific data_id range
                let debug_trace = debug_cmp && (point_ids.len() >= 1875 && point_ids.len() <= 1880);

                // Determine which neighboring faces to visit
                let right_corner_id = corner_table.opposite(corner_table.next(corner_id));
                let left_corner_id = corner_table.opposite(corner_table.previous(corner_id));

                let right_face_id = if right_corner_id == INVALID_CORNER_INDEX {
                    INVALID_FACE_INDEX
                } else {
                    corner_table.face(right_corner_id)
                };
                let left_face_id = if left_corner_id == INVALID_CORNER_INDEX {
                    INVALID_FACE_INDEX
                } else {
                    corner_table.face(left_corner_id)
                };

                let right_visited =
                    right_face_id == INVALID_FACE_INDEX || visited_faces[right_face_id.0 as usize];
                let left_visited =
                    left_face_id == INVALID_FACE_INDEX || visited_faces[left_face_id.0 as usize];

                if verbose && point_ids.len() < 30 {
                    debug_log!("  DFS: corner={} neighbors: right_c={} right_f={} right_vis={}, left_c={} left_f={} left_vis={}",
                        corner_id.0, right_corner_id.0, right_face_id.0, right_visited, left_corner_id.0, left_face_id.0, left_visited);
                }

                if debug_trace {
                    debug_log!("  TRACE data_id={}: corner={} neighbors: right_c={} right_f={} right_vis={}, left_c={} left_f={} left_vis={}",
                        point_ids.len(), corner_id.0, right_corner_id.0, right_face_id.0, right_visited, left_corner_id.0, left_face_id.0, left_visited);
                }

                if right_visited {
                    if left_visited {
                        if debug_trace {
                            debug_log!(
                                "  TRACE data_id={}: both visited -> break",
                                point_ids.len()
                            );
                        }
                        break;
                    } else {
                        if debug_trace {
                            debug_log!(
                                "  TRACE data_id={}: right visited, go left -> corner={}",
                                point_ids.len(),
                                left_corner_id.0
                            );
                        }
                        corner_id = left_corner_id;
                        face_id = left_face_id;
                    }
                } else if left_visited {
                    if debug_trace {
                        debug_log!(
                            "  TRACE data_id={}: left visited, go right -> corner={}",
                            point_ids.len(),
                            right_corner_id.0
                        );
                    }
                    corner_id = right_corner_id;
                    face_id = right_face_id;
                } else {
                    // Both neighbors unvisited - split traversal.
                    // C++ behavior: replace top with left, push right on top.
                    // This means right is visited first (LIFO).
                    // We already popped the current corner, so push left first (visited second),
                    // then push right (visited first).
                    if debug_trace {
                        debug_log!("  TRACE data_id={}: both unvisited -> push left={} then right={}, break", point_ids.len(), left_corner_id.0, right_corner_id.0);
                    }
                    corner_stack.push(left_corner_id); // Will be visited second
                    corner_stack.push(right_corner_id); // Will be visited first (popped next)
                    break;
                }
            }
        }
    }

    /// MaxPredictionDegree traversal matching C++ MaxPredictionDegreeTraverser.
    /// Used for speed 0 encoding to achieve better compression via priority-based traversal.
    #[allow(clippy::too_many_arguments)]
    fn max_prediction_degree_visit(
        corner_order: &[CornerIndex],
        mesh: &Mesh,
        corner_table: &CornerTable,
        point_ids: &mut Vec<PointIndex>,
        data_to_corner_map: &mut Vec<u32>,
        vertex_to_data_map: &mut [i32],
        visited_vertices: &mut [bool],
        visited_faces: &mut [bool],
    ) {
        const MAX_PRIORITY: usize = 3;
        let num_vertices = corner_table.num_vertices();

        // Prediction degree tracks how many faces can predict a given vertex
        let mut prediction_degree: Vec<i32> = vec![0; num_vertices];

        // Priority stacks (buckets) - corners with lower priority are processed first
        let mut traversal_stacks: [Vec<CornerIndex>; MAX_PRIORITY] = Default::default();
        #[allow(unused_assignments)]
        let mut best_priority: usize = 0;

        // Helper function to compute priority for a corner
        #[inline]
        fn compute_priority(
            corner_id: CornerIndex,
            corner_table: &CornerTable,
            visited_vertices: &[bool],
            prediction_degree: &mut [i32],
        ) -> usize {
            let v_tip = corner_table.vertex(corner_id);
            if v_tip == INVALID_VERTEX_INDEX {
                return MAX_PRIORITY - 1;
            }
            let vi = v_tip.0 as usize;
            // Priority 0 when traversing to already visited vertices
            if visited_vertices[vi] {
                0
            } else {
                prediction_degree[vi] += 1;
                // Priority 1 when prediction degree > 1, otherwise 2
                if prediction_degree[vi] > 1 {
                    1
                } else {
                    2
                }
            }
        }

        // Helper to add corner to traversal stack
        #[inline]
        fn add_corner(
            stacks: &mut [Vec<CornerIndex>; MAX_PRIORITY],
            corner_id: CornerIndex,
            priority: usize,
            best: &mut usize,
        ) {
            stacks[priority].push(corner_id);
            if priority < *best {
                *best = priority;
            }
        }

        // Helper to pop next corner
        #[inline]
        fn pop_next(
            stacks: &mut [Vec<CornerIndex>; MAX_PRIORITY],
            best: &mut usize,
        ) -> Option<CornerIndex> {
            for i in *best..MAX_PRIORITY {
                if !stacks[i].is_empty() {
                    *best = i;
                    return stacks[i].pop();
                }
            }
            None
        }

        // Inline helper to visit a vertex
        #[inline]
        fn visit_vertex_inline(
            corner_id: CornerIndex,
            vert_id: VertexIndex,
            mesh: &Mesh,
            visited_vertices: &mut [bool],
            point_ids: &mut Vec<PointIndex>,
            data_to_corner_map: &mut Vec<u32>,
            vertex_to_data_map: &mut [i32],
        ) {
            let vi = vert_id.0 as usize;
            if visited_vertices[vi] {
                return;
            }
            visited_vertices[vi] = true;

            // Get the mesh point for this corner
            let mesh_face = FaceIndex(corner_id.0 / 3);
            let corner_offset = (corner_id.0 % 3) as usize;
            let mesh_point = mesh.face(mesh_face)[corner_offset];
            let data_id = point_ids.len() as i32;

            vertex_to_data_map[vi] = data_id;
            point_ids.push(mesh_point);
            data_to_corner_map.push(corner_id.0);
        }

        // Process each seed corner from corner_order
        for &seed_corner in corner_order {
            let seed_face = FaceIndex(seed_corner.0 / 3);
            if visited_faces[seed_face.0 as usize] {
                continue;
            }

            // Initialize traversal from seed corner
            traversal_stacks[0].push(seed_corner);
            best_priority = 0;

            // Visit initial triangle vertices (next and prev corners)
            let next_c = corner_table.next(seed_corner);
            let prev_c = corner_table.previous(seed_corner);
            let next_vert = corner_table.vertex(next_c);
            let prev_vert = corner_table.vertex(prev_c);
            let tip_vert = corner_table.vertex(seed_corner);

            if next_vert != INVALID_VERTEX_INDEX {
                visit_vertex_inline(
                    next_c,
                    next_vert,
                    mesh,
                    visited_vertices,
                    point_ids,
                    data_to_corner_map,
                    vertex_to_data_map,
                );
            }
            if prev_vert != INVALID_VERTEX_INDEX {
                visit_vertex_inline(
                    prev_c,
                    prev_vert,
                    mesh,
                    visited_vertices,
                    point_ids,
                    data_to_corner_map,
                    vertex_to_data_map,
                );
            }
            if tip_vert != INVALID_VERTEX_INDEX {
                visit_vertex_inline(
                    seed_corner,
                    tip_vert,
                    mesh,
                    visited_vertices,
                    point_ids,
                    data_to_corner_map,
                    vertex_to_data_map,
                );
            }

            // Main traversal loop
            while let Some(corner_id) = pop_next(&mut traversal_stacks, &mut best_priority) {
                let face_id = FaceIndex(corner_id.0 / 3);

                if visited_faces[face_id.0 as usize] {
                    continue;
                }

                let mut current_corner = corner_id;

                loop {
                    let current_face = FaceIndex(current_corner.0 / 3);
                    visited_faces[current_face.0 as usize] = true;

                    // Visit tip vertex if not already visited
                    let vert_id = corner_table.vertex(current_corner);
                    if vert_id != INVALID_VERTEX_INDEX && !visited_vertices[vert_id.0 as usize] {
                        visit_vertex_inline(
                            current_corner,
                            vert_id,
                            mesh,
                            visited_vertices,
                            point_ids,
                            data_to_corner_map,
                            vertex_to_data_map,
                        );
                    }

                    // Check neighboring faces
                    let right_corner = corner_table.opposite(corner_table.next(current_corner));
                    let left_corner = corner_table.opposite(corner_table.previous(current_corner));

                    let right_face = if right_corner == INVALID_CORNER_INDEX {
                        INVALID_FACE_INDEX
                    } else {
                        corner_table.face(right_corner)
                    };
                    let left_face = if left_corner == INVALID_CORNER_INDEX {
                        INVALID_FACE_INDEX
                    } else {
                        corner_table.face(left_corner)
                    };

                    let is_right_visited =
                        right_face == INVALID_FACE_INDEX || visited_faces[right_face.0 as usize];
                    let is_left_visited =
                        left_face == INVALID_FACE_INDEX || visited_faces[left_face.0 as usize];

                    if !is_left_visited {
                        // Can go to left face
                        let priority = compute_priority(
                            left_corner,
                            corner_table,
                            visited_vertices,
                            &mut prediction_degree,
                        );
                        if is_right_visited && priority <= best_priority {
                            // Right visited, left has good priority - go directly
                            current_corner = left_corner;
                            continue;
                        } else {
                            add_corner(
                                &mut traversal_stacks,
                                left_corner,
                                priority,
                                &mut best_priority,
                            );
                        }
                    }

                    if !is_right_visited {
                        // Can go to right face
                        let priority = compute_priority(
                            right_corner,
                            corner_table,
                            visited_vertices,
                            &mut prediction_degree,
                        );
                        if priority <= best_priority {
                            // Right has good priority - go directly
                            current_corner = right_corner;
                            continue;
                        } else {
                            add_corner(
                                &mut traversal_stacks,
                                right_corner,
                                priority,
                                &mut best_priority,
                            );
                        }
                    }

                    // Couldn't proceed directly
                    break;
                }
            }
        }
    }

    fn encode_traversal_buffer(
        &self,
        mesh: &Mesh,
        corner_table: &CornerTable,
        attribute_connectivity: &[EdgebreakerAttributeConnectivity],
        out_buffer: &mut EncoderBuffer,
    ) -> Result<(), DracoError> {
        let verbose = self.verbose_logging();

        // DEBUG: Print symbols before encoding
        if verbose {
            let sym_names: Vec<&str> = self
                .symbols
                .iter()
                .map(|&s| match s {
                    0 => "C",
                    1 => "S",
                    2 => "L",
                    3 => "R",
                    4 => "E",
                    _ => "?",
                })
                .collect();
            debug_log!("DEBUG: Encoder symbols (forward): {:?}", sym_names);
            let rev_names: Vec<&str> = self
                .symbols
                .iter()
                .rev()
                .map(|&s| match s {
                    0 => "C",
                    1 => "S",
                    2 => "L",
                    3 => "R",
                    4 => "E",
                    _ => "?",
                })
                .collect();
            debug_log!(
                "DEBUG: Encoder symbols (reversed for encoding): {:?}",
                rev_names
            );

            // Print symbol-to-face mapping
            let faces: Vec<u32> = self
                .symbol_to_encoder_corner
                .iter()
                .map(|c| c.0 / 3)
                .collect();
            debug_log!("DEBUG: Encoder symbol faces (forward): {:?}", faces);
        }

        #[cfg(feature = "legacy_bitstream_encode")]
        if self.force_predictive {
            return self.encode_predictive_traversal(
                corner_table,
                attribute_connectivity,
                out_buffer,
            );
        }

        #[cfg(feature = "edgebreaker_valence_encode")]
        if let Some(valence_encoder) = self.valence_encoder.as_ref() {
            let bitstream_version = out_buffer.bitstream_version();
            if cfg!(feature = "legacy_bitstream_encode") && bitstream_version < 0x0202 {
                // Pre-2.2 valence block:
                //   [main symbol stream][start faces][seams][num_split][mode][contexts]
                // The valence scheme leaves the last encoded symbol uncontexted (it is
                // the first symbol decoded, when no valence context is active yet); the
                // decoder replays it from this raw main symbol stream rather than
                // assuming E as 2.2+ does.
                out_buffer.start_bit_encoding(self.symbols.len().max(1) * 3, true);
                if let Some(&last) = self.symbols.last() {
                    let (bits, val) = match EdgebreakerSymbol::from(last) {
                        EdgebreakerSymbol::Center => (1u32, 0u32),
                        EdgebreakerSymbol::Split => (3, 1),
                        EdgebreakerSymbol::Left => (3, 3),
                        EdgebreakerSymbol::Right => (3, 5),
                        EdgebreakerSymbol::End | EdgebreakerSymbol::Hole => (3, 7),
                    };
                    out_buffer.encode_least_significant_bits32(bits, val);
                }
                out_buffer.end_bit_encoding();

                // Start faces as a raw bit buffer (pre-2.2 layout, not rANS).
                out_buffer.start_bit_encoding(self.init_face_configurations.len().max(1), true);
                for &is_interior in &self.init_face_configurations {
                    out_buffer.encode_least_significant_bits32(1, is_interior as u32);
                }
                out_buffer.end_bit_encoding();

                // Attribute seams.
                self.encode_attribute_seams(corner_table, attribute_connectivity, out_buffer);

                // Split-symbol count (u32 pre-2.0, varint otherwise) + valence mode
                // (EDGEBREAKER_VALENCE_MODE_2_7 = 0).
                let num_split_symbols = self
                    .symbols
                    .iter()
                    .filter(|&&s| s == EdgebreakerSymbol::Split as u32)
                    .count();
                if bitstream_version < 0x0200 {
                    out_buffer.encode_u32(num_split_symbols as u32);
                } else {
                    out_buffer.encode_varint(num_split_symbols as u64);
                }
                out_buffer.encode_u8(0);

                // Contexts.
                valence_encoder.done(out_buffer, 7);
                return Ok(());
            }

            // Valence encoding order: StartFaces -> Seams -> Symbols (Contexts).
            // This mirrors C++ MeshEdgebreakerTraversalValenceEncoder::Done().
            let mut start_face_encoder = RAnsBitEncoder::new();
            start_face_encoder.start_encoding();
            if verbose {
                debug_log!(
                    "DEBUG: Encoder InitFace Configs: {:?}",
                    self.init_face_configurations
                );
            }
            for &is_interior in &self.init_face_configurations {
                start_face_encoder.encode_bit(is_interior);
            }
            start_face_encoder.end_encoding(out_buffer);

            self.encode_attribute_seams(corner_table, attribute_connectivity, out_buffer);

            // C++ implementation passes nullptr for options in Done(), which uses the
            // default compression level of 7 (kDefaultSymbolCodingCompressionLevel).
            let compression_level = 7;
            valence_encoder.done(out_buffer, compression_level);
            return Ok(());
        }

        // Standard encoding order: Symbols -> StartFaces -> Seams.
        let mut traversal_buffer = EncoderBuffer::new();
        traversal_buffer.set_version(2, 2);

        traversal_buffer.start_bit_encoding(mesh.num_faces() * 3, true);
        for &sym_id in self.symbols.iter().rev() {
            let (pattern_bits, pattern_value) = match EdgebreakerSymbol::from(sym_id) {
                EdgebreakerSymbol::Center => (1u32, 0u32), // TOPOLOGY_C
                EdgebreakerSymbol::Split => (3u32, 1u32),  // TOPOLOGY_S
                EdgebreakerSymbol::Left => (3u32, 3u32),   // TOPOLOGY_L
                EdgebreakerSymbol::Right => (3u32, 5u32),  // TOPOLOGY_R
                EdgebreakerSymbol::End => (3u32, 7u32),    // TOPOLOGY_E
                EdgebreakerSymbol::Hole => (3u32, 7u32),
            };
            traversal_buffer.encode_least_significant_bits32(pattern_bits, pattern_value);
        }
        traversal_buffer.end_bit_encoding();

        let mut start_face_encoder = RAnsBitEncoder::new();
        start_face_encoder.start_encoding();
        if verbose {
            debug_log!(
                "DEBUG: Encoder InitFace Configs: {:?}",
                self.init_face_configurations
            );
        }
        for &is_interior in &self.init_face_configurations {
            start_face_encoder.encode_bit(is_interior);
        }
        start_face_encoder.end_encoding(&mut traversal_buffer);

        self.encode_attribute_seams(corner_table, attribute_connectivity, &mut traversal_buffer);

        out_buffer.encode_data(traversal_buffer.data());
        Ok(())
    }

    /// Emit the legacy predictive (type-1) traversal block. The standard
    /// traversal already collected the symbols and their corners, so this replays
    /// them through [`MeshEdgebreakerTraversalPredictiveEncoder`] (which predicts
    /// each preceding symbol from the pivot valence and records the prediction +
    /// main-stream symbols), then writes the block. Predictive is a pre-2.0
    /// format, so counts are fixed u32.
    #[cfg(feature = "legacy_bitstream_encode")]
    fn encode_predictive_traversal(
        &self,
        corner_table: &CornerTable,
        attribute_connectivity: &[EdgebreakerAttributeConnectivity],
        out_buffer: &mut EncoderBuffer,
    ) -> Result<(), DracoError> {
        use crate::mesh_edgebreaker_traversal_predictive_encoder::{
            symbol_topology_bits, MeshEdgebreakerTraversalPredictiveEncoder,
        };

        let mut encoder = MeshEdgebreakerTraversalPredictiveEncoder::new();
        encoder.init(corner_table);
        for i in 0..self.symbols.len() {
            let last_corner = match self.symbol_to_encoder_corner.get(i) {
                Some(&c)
                    if c != INVALID_CORNER_INDEX && (c.0 as usize) < corner_table.num_corners() =>
                {
                    c
                }
                _ => {
                    return Err(DracoError::DracoError(
                        "Invalid corner for predictive traversal".to_string(),
                    ))
                }
            };
            encoder.encode_symbol(self.symbols[i], corner_table, last_corner);
        }
        encoder.finish();

        // Region 1: main symbol stream (stored symbols, reversed like the standard
        // traversal stream, raw 1-or-3 bits each).
        out_buffer.start_bit_encoding(self.symbols.len().max(1) * 3, true);
        for &sym in encoder.stored_symbols().iter().rev() {
            let (bits, val) = symbol_topology_bits(sym);
            out_buffer.encode_least_significant_bits32(bits, val);
        }
        out_buffer.end_bit_encoding();

        // Region 2: start faces (raw bits).
        out_buffer.start_bit_encoding(self.init_face_configurations.len().max(1), true);
        for &is_interior in &self.init_face_configurations {
            out_buffer.encode_least_significant_bits32(1, is_interior as u32);
        }
        out_buffer.end_bit_encoding();

        // Attribute seams, then the split count and the binary prediction stream.
        self.encode_attribute_seams(corner_table, attribute_connectivity, out_buffer);
        out_buffer.encode_u32(encoder.num_split_symbols());
        encoder.encode_predictions(out_buffer);

        Ok(())
    }

    fn connectivity_corner_order(&self) -> Vec<CornerIndex> {
        let mut corner_order: Vec<CornerIndex> = self
            .processed_connectivity_corners
            .iter()
            .rev()
            .copied()
            .collect();
        corner_order.extend(self.init_face_connectivity_corners.iter().copied());
        corner_order
    }

    fn encode_attribute_seams(
        &self,
        corner_table: &CornerTable,
        attribute_connectivity: &[EdgebreakerAttributeConnectivity],
        out_buffer: &mut EncoderBuffer,
    ) {
        for attr_conn in attribute_connectivity {
            let mut seam_encoder = RAnsBitEncoder::new();
            seam_encoder.start_encoding();
            let mut visited_faces = vec![false; corner_table.num_faces()];
            for corner in self.connectivity_corner_order() {
                let face = corner_table.face(corner);
                if face == INVALID_FACE_INDEX {
                    continue;
                }
                let face_idx = face.0 as usize;
                if face_idx >= visited_faces.len() || visited_faces[face_idx] {
                    continue;
                }
                visited_faces[face_idx] = true;

                let corners = [
                    corner,
                    corner_table.next(corner),
                    corner_table.previous(corner),
                ];
                for c in corners {
                    let opp = corner_table.opposite(c);
                    if opp == INVALID_CORNER_INDEX {
                        continue;
                    }
                    let opp_face = corner_table.face(opp);
                    if opp_face == INVALID_FACE_INDEX {
                        continue;
                    }
                    let opp_idx = opp_face.0 as usize;
                    if opp_idx < visited_faces.len() && visited_faces[opp_idx] {
                        continue;
                    }
                    seam_encoder.encode_bit(attr_conn.is_corner_opposite_to_seam_edge(c));
                }
            }
            seam_encoder.end_encoding(out_buffer);
        }
    }

    fn encode_split_data(&self, out_buffer: &mut EncoderBuffer) -> Result<(), DracoError> {
        let bitstream_version = out_buffer.bitstream_version();
        let legacy = cfg!(feature = "legacy_bitstream_encode") && bitstream_version != 0;
        // Pre-2.0 stores the split count as a fixed u32; 2.0+ uses a varint.
        let split_count_u32 = legacy && bitstream_version < 0x0200;
        // Pre-2.2 codes the source-edge selector with 2 bits; 2.2+ uses 1.
        let edge_bits = if legacy && bitstream_version < 0x0202 {
            2
        } else {
            1
        };

        let num_events = self.topology_split_event_data.len();
        if split_count_u32 {
            out_buffer.encode_u32(num_events as u32);
        } else {
            out_buffer.encode_varint(num_events as u64);
        }

        if num_events > 0 {
            // Encode source/split symbol IDs using delta coding.
            let mut last_source_symbol_id: i32 = 0;
            for event in &self.topology_split_event_data {
                let delta = (event.source_symbol_id as i32) - last_source_symbol_id;
                out_buffer.encode_varint(delta as u64);
                let split_delta = (event.source_symbol_id as i32) - (event.split_symbol_id as i32);
                out_buffer.encode_varint(split_delta as u64);
                last_source_symbol_id = event.source_symbol_id as i32;
            }
            // Encode source_edge bits using direct bit encoding (no size prefix).
            out_buffer.start_bit_encoding(num_events, false);
            for event in &self.topology_split_event_data {
                out_buffer.encode_least_significant_bits32(edge_bits, event.source_edge as u32);
            }
            out_buffer.end_bit_encoding();
        }

        // Pre-2.1 stores hole events *after* the topology splits (a count plus the
        // events). The decoder parses but never uses them (dead/legacy data), so an
        // empty section keeps the byte layout aligned. < 2.0 uses a fixed u32 count,
        // 2.0 a varint; 2.1+ has no hole-event section.
        #[cfg(feature = "legacy_bitstream_encode")]
        {
            if bitstream_version != 0 && bitstream_version < 0x0200 {
                out_buffer.encode_u32(0); // num_hole_events
            } else if bitstream_version != 0 && bitstream_version < 0x0201 {
                out_buffer.encode_varint(0u64); // num_hole_events
            }
        }

        Ok(())
    }

    fn is_vertex_on_boundary(&self, corner_table: &CornerTable, v: VertexIndex) -> bool {
        let corner = corner_table.left_most_corner(v);
        if corner == INVALID_CORNER_INDEX {
            return true; // Isolated vertex - treat as boundary
        }
        // C++ checks: if (SwingLeft(corner) == kInvalidCornerIndex) return true;
        if corner_table.swing_left(corner) == INVALID_CORNER_INDEX {
            return true;
        }
        false
    }

    /// Finds all holes (boundary loops) in the mesh and assigns each boundary vertex
    /// to its hole ID. This matches the C++ FindHoles() function.
    fn find_holes(&mut self, corner_table: &CornerTable) {
        let num_corners = corner_table.num_corners();

        // Go over all corners and detect non-visited open boundaries
        for i in 0..num_corners {
            let corner_i = CornerIndex(i as u32);

            // Skip degenerated faces
            let face = corner_table.face(corner_i);
            if face == crate::geometry_indices::INVALID_FACE_INDEX
                || corner_table.is_degenerated(face)
            {
                continue;
            }

            // Check if this corner is opposite to a boundary edge
            if corner_table.opposite(corner_i) == INVALID_CORNER_INDEX {
                // No opposite corner means no opposite face, so the opposite edge
                // of the corner is an open boundary.
                // Check whether we have already traversed the boundary.
                let boundary_vert_id = corner_table.vertex(corner_table.next(corner_i));
                if boundary_vert_id == crate::geometry_indices::INVALID_VERTEX_INDEX {
                    continue;
                }
                let bv = boundary_vert_id.0 as usize;
                if bv >= self.vertex_hole_id.len() {
                    continue;
                }
                if self.vertex_hole_id[bv] != -1 {
                    // Already assigned to a hole
                    continue;
                }

                // New open boundary found - traverse along it and mark all vertices
                let boundary_id = self.visited_holes.len() as i32;
                self.visited_holes.push(false);

                let mut corner_id = corner_i;
                let mut current_boundary_vert = boundary_vert_id;

                // Safety limit for boundary traversal
                let max_verts = corner_table.num_vertices();
                let mut vert_count = 0;

                while self.vertex_hole_id[current_boundary_vert.0 as usize] == -1 {
                    vert_count += 1;
                    if vert_count > max_verts {
                        break; // Safety exit
                    }

                    // Mark the vertex on the open boundary
                    self.vertex_hole_id[current_boundary_vert.0 as usize] = boundary_id;

                    // Move to next corner on the boundary
                    corner_id = corner_table.next(corner_id);

                    // Look for the next attached open boundary edge (with safety limit)
                    let mut inner_iter = 0;
                    while corner_table.opposite(corner_id) != INVALID_CORNER_INDEX {
                        corner_id = corner_table.opposite(corner_id);
                        corner_id = corner_table.next(corner_id);
                        inner_iter += 1;
                        if inner_iter > max_verts {
                            break;
                        }
                    }

                    // Get the next vertex on the hole
                    current_boundary_vert = corner_table.vertex(corner_table.next(corner_id));
                    if current_boundary_vert == crate::geometry_indices::INVALID_VERTEX_INDEX {
                        break;
                    }
                    if (current_boundary_vert.0 as usize) >= self.vertex_hole_id.len() {
                        break;
                    }
                }
            }
        }
    }

    /// Encodes all vertices of a hole starting at start_corner_id.
    /// The vertex associated with the first corner is encoded only if encode_first_vertex is true.
    /// Returns the number of encoded hole vertices.
    /// This matches the C++ EncodeHole() function.
    fn encode_hole(
        &mut self,
        corner_table: &CornerTable,
        start_corner_id: CornerIndex,
        encode_first_vertex: bool,
    ) -> i32 {
        // We know that the start corner lies on a hole but we first need to find the
        // boundary edge going from that vertex. It is the first edge in CW direction.
        let mut corner_id = start_corner_id;
        corner_id = corner_table.previous(corner_id);

        // Add safety limit to prevent infinite loops
        let max_iters = corner_table.num_corners();
        let mut iter_count = 0;
        while corner_table.opposite(corner_id) != INVALID_CORNER_INDEX {
            corner_id = corner_table.opposite(corner_id);
            corner_id = corner_table.next(corner_id);
            iter_count += 1;
            if iter_count > max_iters {
                // Safety exit - we're stuck in a loop
                return 0;
            }
        }

        let start_vertex_id = corner_table.vertex(start_corner_id);
        if start_vertex_id == crate::geometry_indices::INVALID_VERTEX_INDEX {
            return 0;
        }

        let mut num_encoded_hole_verts = 0;
        if encode_first_vertex {
            let sv = start_vertex_id.0 as usize;
            if sv < self.visited_vertices.len() {
                self.visited_vertices[sv] = true;
            }
            num_encoded_hole_verts += 1;
        }

        // Mark the hole as visited
        let start_vid = start_vertex_id.0 as usize;
        if start_vid < self.vertex_hole_id.len() {
            let hole_id = self.vertex_hole_id[start_vid];
            if hole_id >= 0 && (hole_id as usize) < self.visited_holes.len() {
                self.visited_holes[hole_id as usize] = true;
            }
        }

        // corner_id is now opposite to the boundary edge.
        // Get the start vertex of the edge and use it as a reference.
        let _start_vert_id = corner_table.vertex(corner_table.next(corner_id));

        // Get the end vertex of the edge.
        let mut act_vertex_id = corner_table.vertex(corner_table.previous(corner_id));

        // Safety counter for the main loop
        iter_count = 0;
        while act_vertex_id != start_vertex_id {
            if act_vertex_id == crate::geometry_indices::INVALID_VERTEX_INDEX {
                break;
            }

            iter_count += 1;
            if iter_count > max_iters {
                // Safety exit
                break;
            }

            // Mark the vertex as visited
            let av = act_vertex_id.0 as usize;
            if av < self.visited_vertices.len() {
                self.visited_vertices[av] = true;
            }
            num_encoded_hole_verts += 1;

            corner_id = corner_table.next(corner_id);

            // Look for the next attached open boundary edge (with safety limit)
            let mut inner_iter = 0;
            while corner_table.opposite(corner_id) != INVALID_CORNER_INDEX {
                corner_id = corner_table.opposite(corner_id);
                corner_id = corner_table.next(corner_id);
                inner_iter += 1;
                if inner_iter > max_iters {
                    break;
                }
            }

            act_vertex_id = corner_table.vertex(corner_table.previous(corner_id));
        }

        num_encoded_hole_verts
    }

    fn encode_component(
        &mut self,
        corner_table: &CornerTable,
        start_corner: CornerIndex,
        #[cfg(feature = "edgebreaker_valence_encode")] valence_encoder: &mut Option<
            MeshEdgebreakerTraversalValenceEncoder,
        >,
        #[cfg(not(feature = "edgebreaker_valence_encode"))] valence_encoder: &mut (),
    ) -> Result<(), DracoError> {
        let mut corner_traversal_stack: Vec<CornerIndex> = vec![start_corner];

        while !corner_traversal_stack.is_empty() {
            let mut corner_id = *corner_traversal_stack
                .last()
                .expect("loop ensures non-empty");
            loop {
                let face_id = corner_table.face(corner_id);
                if face_id == crate::geometry_indices::INVALID_FACE_INDEX {
                    // Invalid corner / face; end this branch.
                    corner_traversal_stack.pop();
                    break;
                }
                let fi = face_id.0 as usize;
                if self.visited_faces[fi] {
                    // Already visited; end this branch.
                    corner_traversal_stack.pop();
                    break;
                }

                // Mark current face as visited.
                self.visited_faces[fi] = true;
                self.encoded_faces.push((face_id, corner_id));
                // Standard Draco: Record the entry corner for every face reached.
                // This will be used (after reversal) as the seeds for attribute traversal.
                self.processed_connectivity_corners.push(corner_id);
                if self.verbose_logging() {
                    let v = corner_table.vertex(corner_id).0;
                    debug_log!(
                        "Encoder: pushed seed corner {} (face {}) vertex={}",
                        corner_id.0,
                        face_id.0,
                        v
                    );
                }

                self.last_encoded_symbol_id += 1;
                self.face_to_symbol_id[fi] = self.last_encoded_symbol_id as u32;

                // New corner reached.
                Self::valence_new_corner_reached(valence_encoder, corner_id);

                let vert_id = corner_table.vertex(corner_id);
                if vert_id == crate::geometry_indices::INVALID_VERTEX_INDEX {
                    return Err(DracoError::DracoError(
                        "Invalid vertex during Edgebreaker traversal".to_string(),
                    ));
                }
                // Check if vertex is on a boundary using the precomputed hole IDs
                let on_boundary = self
                    .vertex_hole_id
                    .get(vert_id.0 as usize)
                    .copied()
                    .unwrap_or(-1)
                    != -1;

                // If this is a new vertex and it's not on boundary, emit C and go right.
                if !self.visited_vertices[vert_id.0 as usize] {
                    self.visited_vertices[vert_id.0 as usize] = true;
                    if !on_boundary {
                        let right_corner = corner_table.opposite(corner_table.next(corner_id));
                        let right_face = corner_table.face(right_corner);
                        if right_face != crate::geometry_indices::INVALID_FACE_INDEX
                            && !self.visited_faces[right_face.0 as usize]
                        {
                            self.symbols.push(EdgebreakerSymbol::Center as u32);
                            Self::encode_valence_symbol(
                                valence_encoder,
                                EdgebreakerSymbol::Center,
                                corner_table,
                                &self.visited_faces,
                            );
                            self.symbol_to_encoder_corner.push(corner_id);
                            corner_id = right_corner;
                            *corner_traversal_stack.last_mut().expect("stack non-empty") =
                                corner_id;
                            continue;
                        }
                    }
                }

                // Current vertex already visited or it is on boundary: choose next face.
                // Standard Draco Edgebreaker:
                // Right neighbor is Opposite(Next(c)).
                // Left neighbor is Opposite(Previous(c)).
                let right_corner_id = corner_table.opposite(corner_table.next(corner_id));
                let left_corner_id = corner_table.opposite(corner_table.previous(corner_id));
                let right_face_id = corner_table.face(right_corner_id);
                let left_face_id = corner_table.face(left_corner_id);

                let right_visited = right_face_id == crate::geometry_indices::INVALID_FACE_INDEX
                    || self.visited_faces[right_face_id.0 as usize];
                let left_visited = left_face_id == crate::geometry_indices::INVALID_FACE_INDEX
                    || self.visited_faces[left_face_id.0 as usize];

                if right_visited {
                    if right_face_id != crate::geometry_indices::INVALID_FACE_INDEX {
                        self.check_and_store_topology_split_event(
                            face_id.0 as usize,
                            EdgeFaceName::RightFaceEdge,
                            right_face_id.0 as usize,
                        );
                    }
                    if left_visited {
                        if left_face_id != crate::geometry_indices::INVALID_FACE_INDEX {
                            self.check_and_store_topology_split_event(
                                face_id.0 as usize,
                                EdgeFaceName::LeftFaceEdge,
                                left_face_id.0 as usize,
                            );
                        }
                        // End reached.
                        self.symbols.push(EdgebreakerSymbol::End as u32);
                        Self::encode_valence_symbol(
                            valence_encoder,
                            EdgebreakerSymbol::End,
                            corner_table,
                            &self.visited_faces,
                        );
                        self.symbol_to_encoder_corner.push(corner_id);
                        corner_traversal_stack.pop();
                        break;
                    } else {
                        // Go to left face (matches TOPOLOGY_R in C++ - Right is visited, so move Left)
                        self.symbols.push(EdgebreakerSymbol::Right as u32);
                        Self::encode_valence_symbol(
                            valence_encoder,
                            EdgebreakerSymbol::Right,
                            corner_table,
                            &self.visited_faces,
                        );
                        self.symbol_to_encoder_corner.push(corner_id);
                        corner_id = left_corner_id;
                        *corner_traversal_stack.last_mut().expect("stack non-empty") = corner_id;
                    }
                } else if left_visited {
                    if left_face_id != crate::geometry_indices::INVALID_FACE_INDEX {
                        self.check_and_store_topology_split_event(
                            face_id.0 as usize,
                            EdgeFaceName::LeftFaceEdge,
                            left_face_id.0 as usize,
                        );
                    }
                    // Go to right face (matches TOPOLOGY_L in C++ - Left is visited, so move Right)
                    self.symbols.push(EdgebreakerSymbol::Left as u32);
                    Self::encode_valence_symbol(
                        valence_encoder,
                        EdgebreakerSymbol::Left,
                        corner_table,
                        &self.visited_faces,
                    );
                    self.symbol_to_encoder_corner.push(corner_id);
                    corner_id = right_corner_id;
                    *corner_traversal_stack.last_mut().expect("stack non-empty") = corner_id;
                } else {
                    // Split the traversal.
                    self.symbols.push(EdgebreakerSymbol::Split as u32);
                    Self::encode_valence_symbol(
                        valence_encoder,
                        EdgebreakerSymbol::Split,
                        corner_table,
                        &self.visited_faces,
                    );
                    self.symbol_to_encoder_corner.push(corner_id);

                    // If the tip vertex is on a hole boundary and the hole hasn't been
                    // visited yet, we need to encode it. This marks all vertices on
                    // the hole as visited, which matches C++ EncodeHole behavior.
                    if on_boundary {
                        let hole_id = self
                            .vertex_hole_id
                            .get(vert_id.0 as usize)
                            .copied()
                            .unwrap_or(-1);
                        if hole_id >= 0
                            && (hole_id as usize) < self.visited_holes.len()
                            && !self.visited_holes[hole_id as usize]
                        {
                            self.encode_hole(corner_table, corner_id, false);
                        }
                    }

                    self.face_to_split_symbol_map
                        .insert(face_id.0 as usize, self.last_encoded_symbol_id);

                    // Process right face first (matches C++ - push Left, move to Right)
                    // (Note: C++ uses a recursive call for the right neighbor or similar)
                    *corner_traversal_stack.last_mut().expect("stack non-empty") = left_corner_id;
                    corner_traversal_stack.push(right_corner_id);
                    break;
                }
            }
        }

        Ok(())
    }

    #[cfg(feature = "edgebreaker_valence_encode")]
    #[inline]
    fn valence_new_corner_reached(
        valence_encoder: &mut Option<MeshEdgebreakerTraversalValenceEncoder>,
        corner: CornerIndex,
    ) {
        if let Some(encoder) = valence_encoder {
            encoder.new_corner_reached(corner);
        }
    }

    #[cfg(not(feature = "edgebreaker_valence_encode"))]
    #[inline]
    fn valence_new_corner_reached(_valence_encoder: &mut (), _corner: CornerIndex) {}

    #[cfg(feature = "edgebreaker_valence_encode")]
    #[inline]
    fn encode_valence_symbol(
        valence_encoder: &mut Option<MeshEdgebreakerTraversalValenceEncoder>,
        symbol: EdgebreakerSymbol,
        corner_table: &CornerTable,
        visited_faces: &[bool],
    ) {
        if let Some(encoder) = valence_encoder {
            encoder.encode_symbol(symbol, corner_table, visited_faces);
        }
    }

    #[cfg(not(feature = "edgebreaker_valence_encode"))]
    #[inline]
    fn encode_valence_symbol(
        _valence_encoder: &mut (),
        _symbol: EdgebreakerSymbol,
        _corner_table: &CornerTable,
        _visited_faces: &[bool],
    ) {
    }

    fn check_and_store_topology_split_event(
        &mut self,
        _src_face_id: usize,
        src_edge: EdgeFaceName,
        neighbor_face_id: usize,
    ) {
        if let Some(&split_symbol_id) = self.face_to_split_symbol_map.get(&neighbor_face_id) {
            let event = TopologySplitEventData {
                split_symbol_id: split_symbol_id as u32,
                source_symbol_id: self.last_encoded_symbol_id as u32,
                source_edge: src_edge,
            };
            self.topology_split_event_data.push(event);
        }
    }

    /// Return a reference to the generated symbol stream (for testing/inspection).
    pub fn symbols(&self) -> &[u32] {
        &self.symbols
    }
}