gh-50 Add PointIntersectsHandler for point-only intersection detection

Add a new spatial predicate that returns true only when shapes touch by
vertex coincidence without any edge overlap. This fills the gap between
touches() (which includes edge contact) and interiors_intersect().

- Add PointIntersectsHandler with early exit on interior/boundary overlap
- Add point_intersects() to PredicateOverlay and FloatPredicateOverlay
- Add point_intersects() to FloatRelate trait

Author: bretttully

iOverlay/src/core/predicate.rs

@@ -224,6 +224,52 @@ impl FillHandler<ShapeCountBoolean> for TouchesHandler {
     }
 }
 
+/// Handler that checks if subject and clip shapes intersect by point coincidence only.
+///
+/// Returns `true` if shapes share boundary vertices but NOT edges.
+/// - Returns `false` if there's interior overlap (early exit)
+/// - Returns `false` if there's edge/boundary contact (shared segments, early exit)
+/// - Returns `true` ONLY if shapes touch by point coincidence without any edge overlap
+pub(crate) struct PointIntersectsHandler {
+    point_checker: PointCoincidenceChecker,
+}
+
+impl PointIntersectsHandler {
+    pub(crate) fn new(capacity: usize) -> Self {
+        Self {
+            point_checker: PointCoincidenceChecker::new(capacity),
+        }
+    }
+}
+
+impl FillHandler<ShapeCountBoolean> for PointIntersectsHandler {
+    type Output = bool;
+
+    #[inline(always)]
+    fn handle(
+        &mut self,
+        _index: usize,
+        segment: &Segment<ShapeCountBoolean>,
+        fill: SegmentFill,
+    ) -> ControlFlow<bool> {
+        // Interior overlap = not a point-only intersection (early exit false)
+        if (fill & BOTH_TOP) == BOTH_TOP || (fill & BOTH_BOTTOM) == BOTH_BOTTOM {
+            return ControlFlow::Break(false);
+        }
+        // Boundary contact (edge sharing) = not point-only (early exit false)
+        if (fill & SUBJ_BOTH) != 0 && (fill & CLIP_BOTH) != 0 {
+            return ControlFlow::Break(false);
+        }
+        self.point_checker.add_segment(segment, fill);
+        ControlFlow::Continue(())
+    }
+
+    #[inline(always)]
+    fn finalize(self) -> bool {
+        self.point_checker.has_coincidence()
+    }
+}
+
 /// Handler that checks if subject is completely within clip.
 ///
 /// Returns `true` if everywhere the subject has fill, the clip also has fill
@@ -499,4 +545,51 @@ mod tests {
         assert!(matches!(result, ControlFlow::Continue(())));
         assert!(!handler.finalize());
     }
+
+    #[test]
+    fn test_point_intersects_handler_point_only() {
+        let mut handler = PointIntersectsHandler::new(10);
+        // Subject segment ending at (10, 10)
+        let seg1 = make_segment(0, 0, 10, 10, 1, 0);
+        // Clip segment starting at (10, 10)
+        let seg2 = make_segment(10, 10, 20, 20, 0, 1);
+        let _ = handler.handle(0, &seg1, SUBJ_TOP);
+        let _ = handler.handle(1, &seg2, CLIP_TOP);
+        // Point coincidence without edge contact → true
+        assert!(handler.finalize());
+    }
+
+    #[test]
+    fn test_point_intersects_handler_edge_contact() {
+        // Segment belongs to both subject and clip (shared edge)
+        let seg = make_segment(0, 0, 10, 0, 1, 1);
+        let mut handler = PointIntersectsHandler::new(10);
+        // Both shapes have fill on opposite sides (boundary contact)
+        let fill = SUBJ_TOP | CLIP_BOTTOM;
+        let result = handler.handle(0, &seg, fill);
+        // Early exit false on boundary contact (edge sharing)
+        assert!(matches!(result, ControlFlow::Break(false)));
+    }
+
+    #[test]
+    fn test_point_intersects_handler_interior_overlap() {
+        let seg = make_segment(0, 0, 10, 0, 1, 1);
+        let mut handler = PointIntersectsHandler::new(10);
+        // Interior overlap (both shapes fill the same side)
+        let fill = SUBJ_TOP | CLIP_TOP;
+        let result = handler.handle(0, &seg, fill);
+        // Early exit false on interior overlap
+        assert!(matches!(result, ControlFlow::Break(false)));
+    }
+
+    #[test]
+    fn test_point_intersects_handler_no_contact() {
+        let seg1 = make_segment(0, 0, 5, 5, 1, 0);
+        let seg2 = make_segment(10, 10, 20, 20, 0, 1);
+        let mut handler = PointIntersectsHandler::new(10);
+        let _ = handler.handle(0, &seg1, SUBJ_TOP);
+        let _ = handler.handle(1, &seg2, CLIP_TOP);
+        // No contact at all → false
+        assert!(!handler.finalize());
+    }
 }

iOverlay/src/core/relate.rs

@@ -1,7 +1,9 @@
 use crate::build::sweep::{FillHandler, SweepRunner};
 use crate::core::fill_rule::FillRule;
 use crate::core::overlay::ShapeType;
-use crate::core::predicate::{InteriorsIntersectHandler, IntersectsHandler, TouchesHandler, WithinHandler};
+use crate::core::predicate::{
+    InteriorsIntersectHandler, IntersectsHandler, PointIntersectsHandler, TouchesHandler, WithinHandler,
+};
 use crate::core::solver::Solver;
 use crate::segm::boolean::ShapeCountBoolean;
 use crate::segm::build::BuildSegments;
@@ -94,6 +96,16 @@ impl PredicateOverlay {
         self.evaluate(TouchesHandler::new(capacity))
     }
 
+    /// Returns `true` if subject and clip shapes intersect by point coincidence only.
+    ///
+    /// This returns `true` when shapes share boundary vertices but NOT edges.
+    /// Unlike `touches()`, this returns `false` for shapes that share edges.
+    #[inline]
+    pub fn point_intersects(&mut self) -> bool {
+        let capacity = self.segments.len();
+        self.evaluate(PointIntersectsHandler::new(capacity))
+    }
+
     /// Returns `true` if subject is completely within clip.
     ///
     /// Subject is within clip if everywhere the subject has fill, the clip
@@ -487,4 +499,74 @@ mod tests {
             "triangle touching outer corner should not have interior intersection"
         );
     }
+
+    #[test]
+    fn test_point_intersects_corner_to_corner() {
+        // Two squares touching at a single corner point (10, 10)
+        let mut overlay = PredicateOverlay::new(16);
+        overlay.add_contour(&square(0, 0, 10), ShapeType::Subject);
+        overlay.add_contour(&square(10, 10, 10), ShapeType::Clip);
+        assert!(
+            overlay.point_intersects(),
+            "corner-to-corner should be point-only intersection"
+        );
+    }
+
+    #[test]
+    fn test_point_intersects_edge_sharing() {
+        // Two squares sharing an edge (not point-only)
+        let mut overlay = PredicateOverlay::new(16);
+        overlay.add_contour(&square(0, 0, 10), ShapeType::Subject);
+        overlay.add_contour(&square(10, 0, 10), ShapeType::Clip);
+        // touches() is true for edge sharing
+        assert!(overlay.touches());
+
+        overlay.clear();
+        overlay.add_contour(&square(0, 0, 10), ShapeType::Subject);
+        overlay.add_contour(&square(10, 0, 10), ShapeType::Clip);
+        // point_intersects() is false for edge sharing
+        assert!(
+            !overlay.point_intersects(),
+            "edge sharing is not point-only intersection"
+        );
+    }
+
+    #[test]
+    fn test_point_intersects_overlapping() {
+        // Overlapping squares (not point-only)
+        let mut overlay = PredicateOverlay::new(16);
+        overlay.add_contour(&square(0, 0, 10), ShapeType::Subject);
+        overlay.add_contour(&square(5, 5, 10), ShapeType::Clip);
+        assert!(
+            !overlay.point_intersects(),
+            "overlapping shapes are not point-only intersection"
+        );
+    }
+
+    #[test]
+    fn test_point_intersects_disjoint() {
+        // Disjoint squares (no contact at all)
+        let mut overlay = PredicateOverlay::new(16);
+        overlay.add_contour(&square(0, 0, 10), ShapeType::Subject);
+        overlay.add_contour(&square(20, 20, 10), ShapeType::Clip);
+        assert!(
+            !overlay.point_intersects(),
+            "disjoint shapes have no point intersection"
+        );
+    }
+
+    #[test]
+    fn test_point_intersects_triangle_vertex() {
+        // Two triangles touching at a single vertex
+        let tri1 = vec![IntPoint::new(0, 0), IntPoint::new(10, 0), IntPoint::new(5, 10)];
+        let tri2 = vec![IntPoint::new(10, 0), IntPoint::new(20, 0), IntPoint::new(15, 10)];
+
+        let mut overlay = PredicateOverlay::new(16);
+        overlay.add_contour(&tri1, ShapeType::Subject);
+        overlay.add_contour(&tri2, ShapeType::Clip);
+        assert!(
+            overlay.point_intersects(),
+            "triangles touching at vertex should be point-only intersection"
+        );
+    }
 }

iOverlay/src/float/relate.rs

@@ -155,6 +155,12 @@ impl<P: FloatPointCompatible<T>, T: FloatNumber> FloatPredicateOverlay<P, T> {
         self.overlay.touches()
     }
 
+    /// Returns `true` if subject and clip shapes intersect by point coincidence only.
+    #[inline]
+    pub fn point_intersects(&mut self) -> bool {
+        self.overlay.point_intersects()
+    }
+
     /// Returns `true` if subject is completely within clip.
     #[inline]
     pub fn within(&mut self) -> bool {
@@ -221,6 +227,9 @@ where
     /// Returns `true` when shapes share boundary points but their interiors don't overlap.
     fn touches(&self, other: &R1) -> bool;
 
+    /// Returns `true` if this shape intersects another by point coincidence only.
+    fn point_intersects(&self, other: &R1) -> bool;
+
     /// Returns `true` if this shape is completely within another.
     ///
     /// Subject is within clip if everywhere the subject has fill, the clip
@@ -260,6 +269,11 @@ where
         FloatPredicateOverlay::with_subj_and_clip(self, other).touches()
     }
 
+    #[inline]
+    fn point_intersects(&self, other: &R1) -> bool {
+        FloatPredicateOverlay::with_subj_and_clip(self, other).point_intersects()
+    }
+
     #[inline]
     fn within(&self, other: &R1) -> bool {
         FloatPredicateOverlay::with_subj_and_clip(self, other).within()
@@ -614,4 +628,38 @@ mod tests {
         overlay.add_source(&outer, crate::core::overlay::ShapeType::Clip);
         assert!(overlay.within());
     }
+
+    #[test]
+    fn test_point_intersects_trait() {
+        // Two squares touching at a single corner point (10, 10)
+        let square1 = vec![[0.0, 0.0], [0.0, 10.0], [10.0, 10.0], [10.0, 0.0]];
+        let square2 = vec![[10.0, 10.0], [10.0, 20.0], [20.0, 20.0], [20.0, 10.0]];
+
+        // Point-only intersection → true
+        assert!(square1.point_intersects(&square2));
+        assert!(square2.point_intersects(&square1));
+
+        // Edge-sharing squares (not point-only)
+        let square3 = vec![[10.0, 0.0], [10.0, 10.0], [20.0, 10.0], [20.0, 0.0]];
+        assert!(
+            !square1.point_intersects(&square3),
+            "edge sharing is not point-only"
+        );
+        // But they do touch
+        assert!(square1.touches(&square3));
+
+        // Overlapping squares (not point-only)
+        let square4 = vec![[5.0, 5.0], [5.0, 15.0], [15.0, 15.0], [15.0, 5.0]];
+        assert!(
+            !square1.point_intersects(&square4),
+            "overlapping is not point-only"
+        );
+
+        // Disjoint squares (no intersection)
+        let square5 = vec![[100.0, 100.0], [100.0, 110.0], [110.0, 110.0], [110.0, 100.0]];
+        assert!(
+            !square1.point_intersects(&square5),
+            "disjoint has no point intersection"
+        );
+    }
 }