Align vehicle interpolation docs with 500 m snap (#1341)

OBAKit/Mapping/Layers/StopRouteFocus/StopVehicleAnnotation.swift

@@ -95,9 +95,7 @@ final class StopVehicleAnnotation: VehicleAnnotation {
         // position-preferred coordinate must be assigned AFTER, or it gets
         // clobbered exactly as the initializer's comment describes.
         //
-        // Restore `from` before `VehicleCoordinateUpdate.apply` so a city-block
-        // hop interpolates instead of that didSet teleporting the pin. A
-        // kilometre-scale jump still snaps; see VehicleCoordinateUpdate.
+        // A kilometre-scale jump still snaps; see VehicleCoordinateUpdate (#1341).
         let from = self.coordinate
         self.tripStatus = tripStatus
         self.coordinate = from

OBAKit/Mapping/VehicleCoordinateUpdate.swift

@@ -16,10 +16,13 @@ import UIKit
 ///
 /// Arrival polls land every 15–30s. Assigning `coordinate` each time teleports
 /// the pin; interpolating every hop looks like motion. Hops longer than
-/// `snapBeyondMeters` are a new fix (or a trip change), not something to ease
-/// across the map.
+/// `snapBeyondMeters` (**500 m** — a bit over one 30s poll at ~50 km/h) snap
+/// instead. That is a deliberate city-traffic tuning: freeway/express buses
+/// near or above ~60 km/h usually snap and degrade to the pre-interpolation
+/// behavior rather than easing across hundreds of metres.
 ///
 /// See: https://github.com/OneBusAway/onebusaway-ios/issues/1109
+/// Follow-up: https://github.com/OneBusAway/onebusaway-ios/issues/1341
 enum VehicleCoordinateUpdate {
     enum Decision: Equatable {
         case unchanged

OBAKit/Trip/TripViewController.swift

@@ -272,7 +272,16 @@ class TripViewController: UIViewController,
             }
 
             if let vehicleAnnotation = vehicleAnnotation {
+                // `tripStatus`'s didSet writes lastKnownLocation onto coordinate
+                // immediately. Restore `from` so `VehicleCoordinateUpdate` can
+                // interpolate instead of teleporting (#1341) — same pattern as
+                // `TripFocusMapLayer.drawVehicle`.
+                let from = vehicleAnnotation.coordinate
                 vehicleAnnotation.tripStatus = currentTripStatus
+                vehicleAnnotation.coordinate = from
+                if let to = currentTripStatus.lastKnownLocation?.coordinate {
+                    VehicleCoordinateUpdate.apply(from: from, to: to, on: vehicleAnnotation)
+                }
                 // Update the annotation view's heading and real-time state since
                 // the annotation property didSet on the view won't re-fire.
                 if let vehicleAnnotationView = vehicleAnnotationView as? PulsingVehicleAnnotationView {

OBAKitTests/Mapping/VehicleCoordinateUpdateTests.swift

@@ -8,6 +8,7 @@
 //
 
 import CoreLocation
+import MapKit
 import Testing
 import OBAKitCore
 @testable import OBAKit
@@ -35,8 +36,9 @@ struct VehicleCoordinateUpdateTests {
         #expect(decision == .animate(duration: VehicleCoordinateUpdate.animationDuration))
     }
 
-    /// Farther than `snapBeyondMeters` is a new fix, not motion.
-    @Test func `A kilometre jump snaps`() {
+    /// Farther than `snapBeyondMeters` (500 m) is a new fix, not motion.
+    /// A ~1 km hop is well past that cliff — snaps rather than animating.
+    @Test func `A jump beyond snapBeyondMeters snaps`() {
         let far = CLLocationCoordinate2D(latitude: 47.62, longitude: -122.33)
         #expect(VehicleCoordinateUpdate.decision(from: seattle, to: far) == .snap)
     }
@@ -49,4 +51,41 @@ struct VehicleCoordinateUpdateTests {
     @Test func `An invalid coordinate snaps`() {
         #expect(VehicleCoordinateUpdate.decision(from: kCLLocationCoordinate2DInvalid, to: seattle) == .snap)
     }
+
+    // MARK: - apply(from:to:on:)
+
+    @Test @MainActor func `Apply snap writes the destination coordinate`() {
+        let annotation = MKPointAnnotation()
+        annotation.coordinate = seattle
+        let far = CLLocationCoordinate2D(latitude: 47.62, longitude: -122.33)
+
+        VehicleCoordinateUpdate.apply(from: seattle, to: far, on: annotation)
+
+        #expect(annotation.coordinate.latitude == far.latitude)
+        #expect(annotation.coordinate.longitude == far.longitude)
+    }
+
+    @Test @MainActor func `Apply unchanged leaves the coordinate alone`() {
+        let annotation = MKPointAnnotation()
+        annotation.coordinate = seattle
+        let almost = CLLocationCoordinate2D(latitude: 47.6062, longitude: -122.33211)
+
+        VehicleCoordinateUpdate.apply(from: seattle, to: almost, on: annotation)
+
+        #expect(annotation.coordinate.latitude == seattle.latitude)
+        #expect(annotation.coordinate.longitude == seattle.longitude)
+    }
+
+    @Test @MainActor func `Apply animate eventually reaches the destination`() async {
+        let annotation = MKPointAnnotation()
+        annotation.coordinate = seattle
+
+        VehicleCoordinateUpdate.apply(from: seattle, to: nearby, on: annotation)
+
+        // Linear 0.8s animation; wait past it before asserting.
+        try? await Task.sleep(for: .milliseconds(900))
+
+        #expect(abs(annotation.coordinate.latitude - nearby.latitude) < 0.00001)
+        #expect(abs(annotation.coordinate.longitude - nearby.longitude) < 0.00001)
+    }
 }

docs/vehicle-coordinate-interpolation.md

@@ -0,0 +1,23 @@
+# Vehicle coordinate interpolation (#1109 / #1341)
+
+Between arrival polls the trip-page (and stop-route-focus) vehicle marker
+interpolates when the hop is short, and snaps when it is not.
+
+## Threshold
+
+`VehicleCoordinateUpdate.snapBeyondMeters` is **500 m** — a bit over one 30 s
+poll at ~50 km/h. That is a **city-traffic** tuning choice: a 30 s poll at
+60 km/h is exactly 500 m, so freeway / express buses usually snap and degrade to
+the old teleport behavior. Docs and tests describe the constant, not a
+motorway-speed framing.
+
+## Apply path
+
+Callers that assign `VehicleAnnotation.tripStatus` must restore the previous
+`coordinate` before `VehicleCoordinateUpdate.apply`, because `tripStatus`'s
+`didSet` writes `lastKnownLocation` immediately and would otherwise skip the
+animation. Used by:
+
+- `TripFocusMapLayer.drawVehicle`
+- `StopVehicleAnnotation.update`
+- `TripViewController.currentTripStatus` (legacy trip screen; fixed in #1341)