rscad_csg_bsp/

factory.rs

use nalgebra::{Point, Point3, Vector3};
use slotmap::SlotMap;

use crate::metadata::*;
use crate::*;

/// Maps old `FaceKey`s to new `FaceKey`s after a factory merge or cast.
#[derive(Clone, Debug, Default)]
pub struct FaceKeyRemap(pub std::collections::HashMap<FaceKey, FaceKey>);

/// A factory that creates CSG primitives while tracking face and edge metadata.
///
/// All metadata is owned by the factory. Polygons and CSGs store only
/// [`FaceKey`] references that can be looked up here.
///
/// # Example
///
/// ```
/// use rscad_csg_bsp::CsgFactory;
///
/// let mut factory = CsgFactory::<f64>::new();
/// let csg = factory.cuboid(2.0, 1.0, 3.0);
///
/// // Pick a polygon and find all siblings sharing the same face.
/// let face_key = csg.polygons()[0].face_key().unwrap();
/// let siblings = factory.polygons_sharing_face(&csg, face_key);
/// ```
#[derive(Clone, Debug)]
pub struct CsgFactory<T: Number> {
    pub primitives: SlotMap<PrimitiveKey, PrimitiveMeta>,
    pub faces: SlotMap<FaceKey, FaceMeta<T>>,
    pub edges: SlotMap<EdgeKey, EdgeMeta<T>>,
}

impl<T: Number> Default for CsgFactory<T> {
    fn default() -> Self {
        Self::new()
    }
}

impl<T: Number> CsgFactory<T> {
    pub fn new() -> Self {
        Self {
            primitives: SlotMap::with_key(),
            faces: SlotMap::with_key(),
            edges: SlotMap::with_key(),
        }
    }

    // ── Merge ──────────────────────────────────────────────────

    /// Absorb all entries from `other` into `self`, remapping keys.
    ///
    /// Returns a [`FaceKeyRemap`] so callers can update polygon `face_key`s.
    pub fn absorb(&mut self, other: &Self) -> FaceKeyRemap {
        let mut prim_remap: std::collections::HashMap<PrimitiveKey, PrimitiveKey> =
            std::collections::HashMap::with_capacity(other.primitives.len());
        let mut face_remap =
            FaceKeyRemap(std::collections::HashMap::with_capacity(other.faces.len()));
        let mut edge_remap: std::collections::HashMap<EdgeKey, EdgeKey> =
            std::collections::HashMap::with_capacity(other.edges.len());

        // 1. Primitives
        for (old_pk, meta) in &other.primitives {
            let new_pk = self.primitives.insert(meta.clone());
            prim_remap.insert(old_pk, new_pk);
        }

        // 2. Faces (update primitive_key)
        for (old_fk, meta) in &other.faces {
            let mut meta = meta.clone();
            if let Some(&new_pk) = prim_remap.get(&meta.primitive_key) {
                meta.primitive_key = new_pk;
            }
            let new_fk = self.faces.insert(meta);
            face_remap.0.insert(old_fk, new_fk);
        }

        // 3. Edges (update primitive_key + face_keys)
        for (old_ek, meta) in &other.edges {
            let mut meta = meta.clone();
            if let Some(&new_pk) = prim_remap.get(&meta.primitive_key) {
                meta.primitive_key = new_pk;
            }
            meta.face_keys = meta
                .face_keys
                .map(|fk| face_remap.0.get(&fk).copied().unwrap_or(fk));
            let new_ek = self.edges.insert(meta);
            edge_remap.insert(old_ek, new_ek);
        }

        // 4. Fix up face_keys/edge_keys inside the newly inserted PrimitiveMetas
        for new_pk in prim_remap.values() {
            if let Some(pm) = self.primitives.get_mut(*new_pk) {
                pm.face_keys = pm
                    .face_keys
                    .iter()
                    .map(|fk| face_remap.0.get(fk).copied().unwrap_or(*fk))
                    .collect();
                pm.edge_keys = pm
                    .edge_keys
                    .iter()
                    .map(|ek| edge_remap.get(ek).copied().unwrap_or(*ek))
                    .collect();
            }
        }

        face_remap
    }

    /// Cast the factory's numeric type from `T` to `T2`.
    ///
    /// Returns the new factory and a face-key remap (needed to update polygons).
    pub fn cast<T2: Number>(self) -> (CsgFactory<T2>, FaceKeyRemap)
    where
        T: num_traits::cast::AsPrimitive<T2>,
    {
        // PrimitiveMeta has no T — copy as-is (keys stay the same inside the same SlotMap)
        let primitives = self.primitives;

        let mut face_remap = FaceKeyRemap::default();
        let mut faces: SlotMap<FaceKey, FaceMeta<T2>> = SlotMap::with_key();
        for (old_fk, meta) in self.faces {
            let new_fk = faces.insert(FaceMeta {
                primitive_key: meta.primitive_key,
                normal: meta.normal.map(|x| x.as_()),
                label: meta.label,
            });
            face_remap.0.insert(old_fk, new_fk);
        }

        let mut edges: SlotMap<EdgeKey, EdgeMeta<T2>> = SlotMap::with_key();
        for (_, meta) in self.edges {
            edges.insert(EdgeMeta {
                primitive_key: meta.primitive_key,
                vertices: (
                    meta.vertices.0.map(|x| x.as_()),
                    meta.vertices.1.map(|x| x.as_()),
                ),
                face_keys: meta
                    .face_keys
                    .map(|fk| face_remap.0.get(&fk).copied().unwrap_or(fk)),
            });
        }

        (
            CsgFactory {
                primitives,
                faces,
                edges,
            },
            face_remap,
        )
    }

    // ── Queries ────────────────────────────────────────────────

    pub fn face(&self, key: FaceKey) -> Option<&FaceMeta<T>> {
        self.faces.get(key)
    }

    pub fn edge(&self, key: EdgeKey) -> Option<&EdgeMeta<T>> {
        self.edges.get(key)
    }

    pub fn primitive(&self, key: PrimitiveKey) -> Option<&PrimitiveMeta> {
        self.primitives.get(key)
    }

    /// Returns the indices of all polygons in `csg` that share the given face.
    pub fn polygons_sharing_face(&self, csg: &Csg<T>, face_key: FaceKey) -> Vec<usize> {
        csg.polygons()
            .iter()
            .enumerate()
            .filter(|(_, p)| p.face_key() == Some(face_key))
            .map(|(i, _)| i)
            .collect()
    }

    // ── Primitive factories ────────────────────────────────────

    /// Create a cube (uniform cuboid) centered at the origin.
    pub fn cube(&mut self, size: T) -> Csg<T> {
        self.cuboid(size, size, size)
    }

    /// Create a cuboid centered at the origin with the given dimensions.
    pub fn cuboid(&mut self, x: T, y: T, z: T) -> Csg<T> {
        let two = T::one() + T::one();
        let hx = x / two;
        let hy = y / two;
        let hz = z / two;

        let v = [
            Point::from([-hx, -hy, -hz]), // 0: left  bottom back
            Point::from([hx, -hy, -hz]),  // 1: right bottom back
            Point::from([hx, hy, -hz]),   // 2: right top    back
            Point::from([-hx, hy, -hz]),  // 3: left  top    back
            Point::from([-hx, -hy, hz]),  // 4: left  bottom front
            Point::from([hx, -hy, hz]),   // 5: right bottom front
            Point::from([hx, hy, hz]),    // 6: right top    front
            Point::from([-hx, hy, hz]),   // 7: left  top    front
        ];

        // (vertices, normal, distance, label, edge vertex-index pairs)
        #[allow(clippy::type_complexity)]
        let face_defs: [([Point<T, 3>; 4], Vector3<T>, T, &str, [[usize; 2]; 4]); 6] = [
            (
                [v[3], v[2], v[1], v[0]],
                -Vector3::z(),
                hz,
                "back",
                [[3, 2], [2, 1], [1, 0], [0, 3]],
            ),
            (
                [v[4], v[5], v[6], v[7]],
                Vector3::z(),
                hz,
                "front",
                [[4, 5], [5, 6], [6, 7], [7, 4]],
            ),
            (
                [v[3], v[0], v[4], v[7]],
                -Vector3::x(),
                hx,
                "left",
                [[3, 0], [0, 4], [4, 7], [7, 3]],
            ),
            (
                [v[1], v[2], v[6], v[5]],
                Vector3::x(),
                hx,
                "right",
                [[1, 2], [2, 6], [6, 5], [5, 1]],
            ),
            (
                [v[0], v[1], v[5], v[4]],
                -Vector3::y(),
                hy,
                "bottom",
                [[0, 1], [1, 5], [5, 4], [4, 0]],
            ),
            (
                [v[2], v[3], v[7], v[6]],
                Vector3::y(),
                hy,
                "top",
                [[2, 3], [3, 7], [7, 6], [6, 2]],
            ),
        ];

        // Reserve a primitive key first (we'll fill in face/edge keys after).
        let prim_key = self.primitives.insert(PrimitiveMeta {
            kind: PrimitiveKind::Cuboid,
            face_keys: Vec::new(),
            edge_keys: Vec::new(),
            color: None,
        });

        let mut all_face_keys = Vec::with_capacity(6);
        let mut all_edge_keys = Vec::new();

        // Build face keys first so edges can reference them.
        let face_keys_arr: Vec<FaceKey> = face_defs
            .iter()
            .map(|(_, normal, _, label, _)| {
                self.faces.insert(FaceMeta {
                    primitive_key: prim_key,
                    normal: *normal,
                    label: label.to_string(),
                })
            })
            .collect();
        all_face_keys.extend_from_slice(&face_keys_arr);

        // Build edges — deduplicate by canonical (min, max) vertex index pair.
        // Each edge belongs to exactly two faces.
        let mut edge_map: std::collections::BTreeMap<(usize, usize), (EdgeKey, bool)> =
            std::collections::BTreeMap::new();

        for (face_idx, (_, _, _, _, edge_pairs)) in face_defs.iter().enumerate() {
            for &[a, b] in edge_pairs {
                let canonical = if a < b { (a, b) } else { (b, a) };
                edge_map
                    .entry(canonical)
                    .and_modify(|(ek, _)| {
                        // Second face referencing this edge — update the metadata.
                        if let Some(em) = self.edges.get_mut(*ek) {
                            em.face_keys[1] = face_keys_arr[face_idx];
                        }
                    })
                    .or_insert_with(|| {
                        let ek = self.edges.insert(EdgeMeta {
                            primitive_key: prim_key,
                            vertices: (v[a], v[b]),
                            face_keys: [face_keys_arr[face_idx], face_keys_arr[face_idx]],
                        });
                        all_edge_keys.push(ek);
                        (ek, true)
                    });
            }
        }

        // Update the primitive with collected keys.
        if let Some(pm) = self.primitives.get_mut(prim_key) {
            pm.face_keys = all_face_keys;
            pm.edge_keys = all_edge_keys;
        }

        // Build polygons, stamping each with its face key.
        let polygons = face_defs.iter().zip(face_keys_arr.iter()).flat_map(
            |((verts, normal, dist, _, _), &fk)| {
                Polygon::from_points_and_plane(verts.to_vec(), Plane::new(*normal, *dist))
                    .ok()
                    .map(|mut p| {
                        p.set_face_key(Some(fk));
                        p
                    })
            },
        );

        Csg::from_polygons(polygons)
    }

    /// Create a cylinder centered at the origin, axis along Y.
    pub fn cylinder(&mut self, radius: T, height: T, segments: usize) -> Csg<T> {
        let segments = segments.max(3);
        let two = T::one() + T::one();
        let half_h = height / two;
        let pi = T::PI();
        let two_pi = pi + pi;
        let seg_t = T::from(segments).expect("BUG: f64 must represent segment count");

        let circle_point = |j: usize, y: T| -> Point<T, 3> {
            let angle = two_pi * T::from(j).expect("BUG: f64 must represent loop index") / seg_t;
            Point::from([
                radius * num_traits::real::Real::cos(angle),
                y,
                radius * num_traits::real::Real::sin(angle),
            ])
        };

        let top_pts: Vec<Point<T, 3>> = (0..segments).map(|j| circle_point(j, half_h)).collect();
        let bot_pts: Vec<Point<T, 3>> = (0..segments).map(|j| circle_point(j, -half_h)).collect();

        let prim_key = self.primitives.insert(PrimitiveMeta {
            kind: PrimitiveKind::Cylinder,
            face_keys: Vec::new(),
            edge_keys: Vec::new(),
            color: None,
        });

        // Top cap face
        let top_fk = self.faces.insert(FaceMeta {
            primitive_key: prim_key,
            normal: Vector3::y(),
            label: "top".to_string(),
        });

        // Bottom cap face
        let bot_fk = self.faces.insert(FaceMeta {
            primitive_key: prim_key,
            normal: -Vector3::y(),
            label: "bottom".to_string(),
        });

        let mut all_face_keys = vec![top_fk, bot_fk];
        let mut all_edge_keys = Vec::new();
        let mut polygons = Vec::new();

        // Top cap polygon
        if let Ok(mut p) =
            Polygon::from_points_and_plane(top_pts.clone(), Plane::new(Vector3::y(), half_h))
        {
            p.set_face_key(Some(top_fk));
            polygons.push(p);
        }

        // Bottom cap polygon (reversed winding)
        let mut bot_cap = bot_pts.clone();
        bot_cap.reverse();
        if let Ok(mut p) =
            Polygon::from_points_and_plane(bot_cap, Plane::new(-Vector3::y(), half_h))
        {
            p.set_face_key(Some(bot_fk));
            polygons.push(p);
        }

        // Side quads — each is its own face
        for j in 0..segments {
            let jn = (j + 1) % segments;

            let mid_angle =
                (two * T::from(j).expect("BUG: f64 must represent loop index") + T::one()) * pi
                    / seg_t;
            let normal = Vector3::new(
                num_traits::real::Real::cos(mid_angle),
                T::zero(),
                num_traits::real::Real::sin(mid_angle),
            );
            let dist = radius * num_traits::real::Real::cos(pi / seg_t);

            let side_fk = self.faces.insert(FaceMeta {
                primitive_key: prim_key,
                normal,
                label: format!("side_{j}"),
            });
            all_face_keys.push(side_fk);

            // Top edge of this side quad (shared with top cap)
            let top_ek = self.edges.insert(EdgeMeta {
                primitive_key: prim_key,
                vertices: (top_pts[j], top_pts[jn]),
                face_keys: [side_fk, top_fk],
            });
            all_edge_keys.push(top_ek);

            // Bottom edge of this side quad (shared with bottom cap)
            let bot_ek = self.edges.insert(EdgeMeta {
                primitive_key: prim_key,
                vertices: (bot_pts[j], bot_pts[jn]),
                face_keys: [side_fk, bot_fk],
            });
            all_edge_keys.push(bot_ek);

            let verts = [top_pts[j], top_pts[jn], bot_pts[jn], bot_pts[j]];
            if let Ok(mut p) = Polygon::from_points_and_plane(verts, Plane::new(normal, dist)) {
                p.set_face_key(Some(side_fk));
                polygons.push(p);
            }
        }

        // Vertical edges between adjacent side faces
        for j in 0..segments {
            let jn = (j + 1) % segments;
            // Find the side face keys for face j and face jn
            // side faces start at index 2 in all_face_keys
            let side_fk_j = all_face_keys[2 + j];
            let side_fk_jn = all_face_keys[2 + jn];
            let ek = self.edges.insert(EdgeMeta {
                primitive_key: prim_key,
                vertices: (top_pts[jn], bot_pts[jn]),
                face_keys: [side_fk_j, side_fk_jn],
            });
            all_edge_keys.push(ek);
        }

        if let Some(pm) = self.primitives.get_mut(prim_key) {
            pm.face_keys = all_face_keys;
            pm.edge_keys = all_edge_keys;
        }

        Csg::from_polygons(polygons)
    }

    /// Create a cone centered at the origin, axis along Y.
    pub fn cone(&mut self, radius: T, height: T, segments: usize) -> Csg<T> {
        let segments = segments.max(3);
        let two = T::one() + T::one();
        let half_h = height / two;
        let two_pi = two * T::PI();
        let seg_t = T::from(segments).expect("BUG: f64 must represent segment count");

        let apex = Point::from([T::zero(), half_h, T::zero()]);
        let base: Vec<Point<T, 3>> = (0..segments)
            .map(|j| {
                let angle =
                    two_pi * T::from(j).expect("BUG: f64 must represent loop index") / seg_t;
                Point::from([
                    radius * num_traits::real::Real::cos(angle),
                    -half_h,
                    radius * num_traits::real::Real::sin(angle),
                ])
            })
            .collect();

        let prim_key = self.primitives.insert(PrimitiveMeta {
            kind: PrimitiveKind::Cone,
            face_keys: Vec::new(),
            edge_keys: Vec::new(),
            color: None,
        });

        let base_fk = self.faces.insert(FaceMeta {
            primitive_key: prim_key,
            normal: -Vector3::y(),
            label: "base".to_string(),
        });

        let mut all_face_keys = vec![base_fk];
        let mut all_edge_keys = Vec::new();
        let mut polygons = Vec::new();

        // Base cap (reversed winding)
        let mut base_cap = base.clone();
        base_cap.reverse();
        if let Ok(mut p) =
            Polygon::from_points_and_plane(base_cap, Plane::new(-Vector3::y(), half_h))
        {
            p.set_face_key(Some(base_fk));
            polygons.push(p);
        }

        // Side triangles
        for j in 0..segments {
            let jn = (j + 1) % segments;

            let side_fk = self.faces.insert(FaceMeta {
                primitive_key: prim_key,
                normal: {
                    // Approximate outward normal for this side triangle
                    let mid = (base[j].coords + base[jn].coords) / two
                        - nalgebra::Vector3::new(T::zero(), -half_h, T::zero());
                    mid.normalize()
                },
                label: format!("side_{j}"),
            });
            all_face_keys.push(side_fk);

            // Base edge (shared with base cap)
            let base_ek = self.edges.insert(EdgeMeta {
                primitive_key: prim_key,
                vertices: (base[j], base[jn]),
                face_keys: [side_fk, base_fk],
            });
            all_edge_keys.push(base_ek);

            if let Ok(mut p) = Polygon::from_points(vec![apex, base[jn], base[j]]) {
                p.set_face_key(Some(side_fk));
                polygons.push(p);
            }
        }

        // Slant edges (apex to base vertex, shared between adjacent side faces)
        for j in 0..segments {
            let jp = if j == 0 { segments - 1 } else { j - 1 };
            let side_fk_prev = all_face_keys[1 + jp];
            let side_fk_curr = all_face_keys[1 + j];
            let ek = self.edges.insert(EdgeMeta {
                primitive_key: prim_key,
                vertices: (apex, base[j]),
                face_keys: [side_fk_prev, side_fk_curr],
            });
            all_edge_keys.push(ek);
        }

        if let Some(pm) = self.primitives.get_mut(prim_key) {
            pm.face_keys = all_face_keys;
            pm.edge_keys = all_edge_keys;
        }

        Csg::from_polygons(polygons)
    }

    /// Create a torus centered at the origin, lying in the XZ plane.
    pub fn torus(
        &mut self,
        major_radius: T,
        minor_radius: T,
        major_segments: usize,
        minor_segments: usize,
    ) -> Csg<T> {
        let major_segments = major_segments.max(3);
        let minor_segments = minor_segments.max(3);
        let two_pi = T::PI() + T::PI();
        let maj_t = T::from(major_segments).expect("BUG: f64 must represent segment count");
        let min_t = T::from(minor_segments).expect("BUG: f64 must represent segment count");

        let vertex = |i: usize, j: usize| -> Point<T, 3> {
            let theta = two_pi * T::from(i).expect("BUG: f64 must represent loop index") / maj_t;
            let phi = two_pi * T::from(j).expect("BUG: f64 must represent loop index") / min_t;
            let r = major_radius + minor_radius * num_traits::real::Real::cos(phi);
            Point::from([
                r * num_traits::real::Real::cos(theta),
                minor_radius * num_traits::real::Real::sin(phi),
                r * num_traits::real::Real::sin(theta),
            ])
        };

        let prim_key = self.primitives.insert(PrimitiveMeta {
            kind: PrimitiveKind::Torus,
            face_keys: Vec::new(),
            edge_keys: Vec::new(),
            color: None,
        });

        let mut all_face_keys = Vec::new();
        let all_edge_keys = Vec::new();
        let mut polygons = Vec::new();

        // Each quad on the torus surface is its own face.
        for i in 0..major_segments {
            let in_ = (i + 1) % major_segments;
            for j in 0..minor_segments {
                let jn = (j + 1) % minor_segments;

                let v00 = vertex(i, j);
                let v01 = vertex(i, jn);
                let v10 = vertex(in_, j);
                let v11 = vertex(in_, jn);

                let face_fk = self.faces.insert(FaceMeta {
                    primitive_key: prim_key,
                    normal: {
                        let e1 = v01 - v00;
                        let e2 = v10 - v00;
                        e1.cross(&e2).normalize()
                    },
                    label: format!("quad_{i}_{j}"),
                });
                all_face_keys.push(face_fk);

                if let Ok(mut p) = Polygon::from_points(vec![v00, v01, v11, v10]) {
                    p.set_face_key(Some(face_fk));
                    polygons.push(p);
                }
            }
        }

        if let Some(pm) = self.primitives.get_mut(prim_key) {
            pm.face_keys = all_face_keys;
            pm.edge_keys = all_edge_keys;
        }

        Csg::from_polygons(polygons)
    }

    /// Create a parallelepiped (rhomboid) centered at the origin.
    pub fn rhomboid(&mut self, a: Vector3<T>, b: Vector3<T>, c: Vector3<T>) -> Csg<T> {
        let two = T::one() + T::one();
        let offset = (a + b + c) / two;

        let corners = [
            Vector3::zeros(), // 0
            a,                // 1: +a
            a + b,            // 2: +a+b
            b,                // 3: +b
            c,                // 4: +c
            a + c,            // 5: +a+c
            a + b + c,        // 6: +a+b+c
            b + c,            // 7: +b+c
        ];
        let v: [Point<T, 3>; 8] = corners.map(|corner| Point::from(corner - offset));

        let face_defs: [([usize; 4], &str); 6] = [
            ([0, 3, 2, 1], "-c"),
            ([4, 5, 6, 7], "+c"),
            ([0, 4, 7, 3], "-a"),
            ([1, 2, 6, 5], "+a"),
            ([0, 1, 5, 4], "-b"),
            ([3, 7, 6, 2], "+b"),
        ];

        let four = T::from(4).expect("BUG: f64 must represent 4");

        let prim_key = self.primitives.insert(PrimitiveMeta {
            kind: PrimitiveKind::Rhomboid,
            face_keys: Vec::new(),
            edge_keys: Vec::new(),
            color: None,
        });

        let mut all_face_keys = Vec::new();
        let mut all_edge_keys = Vec::new();
        let mut polygons = Vec::new();

        let mut face_keys_arr = Vec::with_capacity(6);

        for (idx, label) in face_defs.iter() {
            let verts: Vec<Point<T, 3>> = idx.iter().map(|&i| v[i]).collect();
            let face_center =
                (verts[0].coords + verts[1].coords + verts[2].coords + verts[3].coords) / four;

            let poly = match Polygon::from_points(verts) {
                Ok(p) => p,
                Err(_) => {
                    face_keys_arr.push(None);
                    continue;
                }
            };

            let (poly, normal) = if poly.plane().normal().dot(&face_center) < T::zero() {
                let flipped = poly.flip();
                let n = flipped.plane().normal();
                (flipped, n)
            } else {
                let n = poly.plane().normal();
                (poly, n)
            };

            let fk = self.faces.insert(FaceMeta {
                primitive_key: prim_key,
                normal,
                label: label.to_string(),
            });
            face_keys_arr.push(Some(fk));
            all_face_keys.push(fk);

            let mut poly = poly;
            poly.set_face_key(Some(fk));
            polygons.push(poly);
        }

        // Edges — deduplicate by canonical vertex index pair
        let edge_indices: [[[usize; 2]; 4]; 6] = [
            [[0, 3], [3, 2], [2, 1], [1, 0]],
            [[4, 5], [5, 6], [6, 7], [7, 4]],
            [[0, 4], [4, 7], [7, 3], [3, 0]],
            [[1, 2], [2, 6], [6, 5], [5, 1]],
            [[0, 1], [1, 5], [5, 4], [4, 0]],
            [[3, 7], [7, 6], [6, 2], [2, 3]],
        ];

        let mut edge_map: std::collections::BTreeMap<(usize, usize), EdgeKey> =
            std::collections::BTreeMap::new();

        for (face_idx, edges) in edge_indices.iter().enumerate() {
            let Some(fk) = face_keys_arr[face_idx] else {
                continue;
            };
            for &[ea, eb] in edges {
                let canonical = if ea < eb { (ea, eb) } else { (eb, ea) };
                edge_map
                    .entry(canonical)
                    .and_modify(|ek| {
                        if let Some(em) = self.edges.get_mut(*ek) {
                            em.face_keys[1] = fk;
                        }
                    })
                    .or_insert_with(|| {
                        let ek = self.edges.insert(EdgeMeta {
                            primitive_key: prim_key,
                            vertices: (v[ea], v[eb]),
                            face_keys: [fk, fk],
                        });
                        all_edge_keys.push(ek);
                        ek
                    });
            }
        }

        if let Some(pm) = self.primitives.get_mut(prim_key) {
            pm.face_keys = all_face_keys;
            pm.edge_keys = all_edge_keys;
        }

        Csg::from_polygons(polygons)
    }

    /// Create a UV sphere centered at the origin.
    pub fn sphere(&mut self, radius: T, segments: usize, stacks: usize) -> Csg<T> {
        use itertools::*;

        let segments = segments.max(3);
        let stacks = stacks.max(2);

        let pi = T::PI();
        let two = T::one() + T::one();
        let two_pi = two * pi;

        let stacks_t = T::from(stacks).expect("BUG: failed to convert stacks to T");
        let segments_t = T::from(segments).expect("BUG: failed to convert segments to T");

        let point_on_surface = |frac_seg: T, frac_stack: T| {
            let lat = pi * frac_stack;
            let stack_radius = radius * num_traits::real::Real::sin(lat);
            let x = stack_radius * num_traits::real::Real::sin(two_pi * frac_seg);
            let y = radius * num_traits::real::Real::cos(lat);
            let z = stack_radius * num_traits::real::Real::cos(two_pi * frac_seg);
            Point3::new(x, y, z)
        };

        let seg_fracs: Vec<T> = (0..segments)
            .flat_map(|v| T::from(v))
            .map(|v| v / segments_t)
            .collect();

        let stack_pairs: Vec<(T, T)> = (1..stacks)
            .flat_map(|v| T::from(v))
            .map(|v| v / stacks_t)
            .tuple_windows()
            .collect();

        let first_ring = T::one() / stacks_t;
        let last_ring = T::from(stacks - 1).expect("BUG: stacks > 1") / stacks_t;

        let prim_key = self.primitives.insert(PrimitiveMeta {
            kind: PrimitiveKind::Sphere,
            face_keys: Vec::new(),
            edge_keys: Vec::new(),
            color: None,
        });

        let mut all_face_keys = Vec::new();
        let mut polygons = Vec::new();

        // Top cap
        let top_fk = self.faces.insert(FaceMeta {
            primitive_key: prim_key,
            normal: Vector3::y(),
            label: "top_cap".to_string(),
        });
        all_face_keys.push(top_fk);

        if let Ok(mut p) =
            Polygon::from_points(seg_fracs.iter().map(|&s| point_on_surface(s, first_ring)))
        {
            p.set_face_key(Some(top_fk));
            polygons.push(p);
        }

        // Bottom cap
        let bot_fk = self.faces.insert(FaceMeta {
            primitive_key: prim_key,
            normal: -Vector3::y(),
            label: "bottom_cap".to_string(),
        });
        all_face_keys.push(bot_fk);

        if let Ok(mut p) = Polygon::from_points(
            seg_fracs
                .iter()
                .rev()
                .map(|&s| point_on_surface(s, last_ring)),
        ) {
            p.set_face_key(Some(bot_fk));
            polygons.push(p);
        }

        // Body quads — each quad is its own face
        for (left, right) in seg_fracs.iter().copied().circular_tuple_windows::<(_, _)>() {
            for &(top, bottom) in &stack_pairs {
                let face_fk = self.faces.insert(FaceMeta {
                    primitive_key: prim_key,
                    normal: {
                        let center = point_on_surface((left + right) / two, (top + bottom) / two);
                        center.coords.normalize()
                    },
                    label: "body".to_string(),
                });
                all_face_keys.push(face_fk);

                if let Ok(mut p) = Polygon::from_points([
                    point_on_surface(left, top),
                    point_on_surface(left, bottom),
                    point_on_surface(right, bottom),
                    point_on_surface(right, top),
                ]) {
                    p.set_face_key(Some(face_fk));
                    polygons.push(p);
                }
            }
        }

        if let Some(pm) = self.primitives.get_mut(prim_key) {
            pm.face_keys = all_face_keys;
            // Edge tracking for sphere is omitted — too many edges for little value.
            pm.edge_keys = Vec::new();
        }

        Csg::from_polygons(polygons)
    }
}