Add hysteresis to route deviation tracking

android/demo-app/src/main/java/com/stadiamaps/ferrostar/DemoConfigs.kt

@@ -4,6 +4,7 @@ import uniffi.ferrostar.CourseFiltering
 import uniffi.ferrostar.NavigationCachingConfig
 import uniffi.ferrostar.NavigationControllerConfig
 import uniffi.ferrostar.RouteDeviationTracking
+import uniffi.ferrostar.StaticThresholdConfig
 import uniffi.ferrostar.WaypointAdvanceMode
 import uniffi.ferrostar.stepAdvanceDistanceEntryAndExit
 import uniffi.ferrostar.stepAdvanceDistanceToEndOfStep
@@ -13,7 +14,13 @@ fun NavigationControllerConfig.Companion.demoConfig(): NavigationControllerConfi
       WaypointAdvanceMode.WaypointWithinRange(100.0),
       stepAdvanceDistanceEntryAndExit(30u, 5u, 32u),
       stepAdvanceDistanceToEndOfStep(10u, 32u),
-      RouteDeviationTracking.StaticThreshold(15U, 50.0),
+      RouteDeviationTracking.StaticThreshold(
+          StaticThresholdConfig(
+              minimumHorizontalAccuracy = 15U,
+              maxAcceptableDeviation = 50.0,
+              returnBuffer = 0.0
+          )
+      ),
       CourseFiltering.SNAP_TO_ROUTE)
 }
 

apple/Sources/FerrostarCore/FFIWrappers/RouteDeviationWrapper.swift

@@ -18,7 +18,18 @@ private final class DetectorImpl: RouteDeviationDetector {
 public enum SwiftRouteDeviationTracking {
     case none
 
-    case staticThreshold(minimumHorizontalAccuracy: UInt16, maxAcceptableDeviation: Double)
+    /// Static threshold deviation tracking with hysteresis support.
+    ///
+    /// - Parameters:
+    ///   - minimumHorizontalAccuracy: Minimum GPS accuracy required to trigger deviation checks
+    ///   - maxAcceptableDeviation: Maximum distance from route before going off-route (must be >= 0)
+    ///   - returnBuffer: Buffer distance for hysteresis (must be >= 0 and <= maxAcceptableDeviation).
+    ///     If nil, defaults to 0 (no hysteresis).
+    case staticThreshold(
+        minimumHorizontalAccuracy: UInt16,
+        maxAcceptableDeviation: Double,
+        returnBuffer: Double? = nil
+    )
 
     case custom(detector: @Sendable (Route, TripState) -> RouteDeviation)
 
@@ -28,11 +39,15 @@ public enum SwiftRouteDeviationTracking {
             .none
         case let .staticThreshold(
             minimumHorizontalAccuracy: minimumHorizontalAccuracy,
-            maxAcceptableDeviation: maxAcceptableDeviation
+            maxAcceptableDeviation: maxAcceptableDeviation,
+            returnBuffer: returnBuffer
         ):
             .staticThreshold(
-                minimumHorizontalAccuracy: minimumHorizontalAccuracy,
-                maxAcceptableDeviation: maxAcceptableDeviation
+                StaticThresholdConfig(
+                    minimumHorizontalAccuracy: minimumHorizontalAccuracy,
+                    maxAcceptableDeviation: maxAcceptableDeviation,
+                    returnBuffer: returnBuffer ?? 0.0
+                )
             )
         case let .custom(detector: detectorFunc):
             .custom(detector: DetectorImpl(detectorFunc: detectorFunc))