0.46.1

Upgrade guide

This release's primary change is upgrading the MapLibre SwiftUI DSL to the latest version. The previous release should have upgraded the dependency, since the default behavior of SPM is to install the latest version of a package that can be used given the version requirements. Until the SwiftUI DSL reaches 1.0, our policy is to track the latest release, and recent clean-up of some APIs there led to breakage in Ferrostar for some users.

This release should not contain result in breaking changes, unless you were relying on low-level access to the MapLibre map view and you were using an older version of the MapLibre SwiftUI DSL.

PRs merged

Bug fixes

• Fix typos flagged by the December release by @ianthetechie in #766

Dependency upgrades

• Bump serde_json from 1.0.145 to 1.0.148 in /common by @dependabot[bot] in #762
• Bump github.com/maplibre/swiftui-dsl from 0.18.0 to 0.19.0 by @dependabot[bot] in #764
• Bump node-forge from 1.3.1 to 1.3.3 in /react-native in the npm_and_yarn group across 1 directory by @dependabot[bot] in #757
• Bump androidx.compose.ui:ui-test-junit4 from 1.8.3 to 1.10.0 in /android by @dependabot[bot] in #758
• Bump wasm-bindgen-test from 0.3.55 to 0.3.56 in /common by @dependabot[bot] in #759
• Bump log from 0.4.28 to 0.4.29 in /common by @dependabot[bot] in #760
• Bump serde_with from 3.15.1 to 3.16.1 in /common by @dependabot[bot] in #761
• Bump undici from 6.22.0 to 6.23.0 in /react-native in the npm_and_yarn group across 1 directory by @dependabot[bot] in #770
• Bump tar from 7.5.2 to 7.5.3 in /react-native in the npm_and_yarn group across 1 directory by @dependabot[bot] in #771
• Update MapLibreSwiftUI DSL to 0.21.1 by @ianthetechie in #788

Full Changelog: 0.46.0...0.46.1

0.46.0

Upgrade guide

Breaking changes

[Core] Route deviation now uses TripState internally

If you're simply using the Ferrostar SDK in your app, this change should not affect you.

We've made another round of improvements the logical framework for deciding when the user is off the route. This change concerns the data structures used, and do not affect most users of the Ferrostar SDK (e.g. if you're just consuming the public releases in your app). If you are deep in the Rust code though, this may cause some compiler errors.

This change gives the route deviation logic even more context, so we can all make better decisions. No information was removed; it just might be under a different key path.

Other breaking changes

We have a pair of breaking changes related to automatic rerouting "cooldown" behavior.

• Fixed a typo (recaluclation -> recalculation) in the public Swift API.
• The public property minimumTimeBeforeRecalculation has changed from a Long to a kotlin.time.Duration. This was always ambiguous, and now that Kotlin has had a stable cross-platform, cross-language Duration API, it was time to adopt that!

Both of these other changes may not necessarily break your project; you'll only notice (with a compile error) if you had explicitly set either of these properties.

Non-breaking highlights

• @radityagumay identified & fixed a bug in Android affecting the route recalculation cooldown
• The community continues improving on step advance logic, with some new changes landing this release from @devnull133
• Costing options on Android can now accept more collection types (this was mistakenly not implemented previously; thanks to @bjtrounson for noticing this!)

PRs merged

Enhancements

• [Core] Converted route deviation to trip state pattern by @Archdoog in #724
• [Core] Fix/improve DistanceEntryAndSnappedExitCondition with multi-step geometry accumulation by @devnull133 in #737
• [Android] Serialize more collection types by @ianthetechie in #749

Bug fixes

• [Android] fix: Allow course propagation with unknown bearing accuracy by @ianthetechie in #745
• [iOS] Fix "recaluclation" typo in FerrostarCore by @ianthetechie in #750
• [Bug] : Fix isMinimumTimeBeforeRecalcExceeded by @radityagumay in #755

Dependency upgrades

• [React Native] Bump the npm_and_yarn group across 3 directories with 1 update by @dependabot[bot] in #738
• Bump js-yaml from 3.14.1 to 3.14.2 in /react-native in the npm_and_yarn group across 1 directory by @dependabot[bot] in #742

New Contributors

• @radityagumay made their first contribution in #755

Full Changelog: 0.45.0...0.46.0

0.45.0

Upgrade guide

Breaking changes

Route providers

This release introduces a number of changes to the public convenience APIs for working with route providers. These changes were made to support the addition of GraphHopper, and to future-proof things when we inevitably add more backends.

Most visibly, the FerrostarCore convenience initializer arguments have changed. These used to have one variant per route provider (only Valhalla in this case, as made specific by the arguments), which would have caused an proliferation of essentially identical convenience constructors. We have unified this by introducing a WellKnownRouteProvider enum, which can be evolved with fewer breaking changes going forward. This also makes things more discoverable and autocomplete-friendly.

Here is an example diff in Kotlin.

      FerrostarCore(
-          valhallaEndpointURL = URL("https://api.stadiamaps.com/route/v1?api_key=YOUR-API-KEY"),
-          profile = "bicycle",
+          wellKnownRouteProvider = WellKnownRouteProvider.Valhalla("https://api.stadiamaps.com/route/v1?api_key=YOUR-API-KEY", "bicycle")

Refer to the demo apps for examples if you're struggling with your platform.

Similarly, the convenience function RouteAdapter::new_valhalla_http (mostly exposed as a camelCase initializer to platform SDKs) has been replaced with RouteAdapter::from_well_known_route_provider.

[Core] More Step Advance Changes

If you're simply using the Ferrostar SDK in your app, this change should not affect you.

We've made another round of improvements on step advance conditions. This is another trait modification, and is only relevant if you're implementing these on your own. This version replaces a few of the method arguments with the full TripState, giving you more flexibility.

Other breaking changes

• The MSRV is now 1.88. This should not affect most users, but if you compile Ferrostar from source, you will need to make sure you're reasonably up to date.

Non-breaking highlights

• Ferrostar now has support for GraphHopper as a routing backend!

PRs merged

Enhancements

• [Core] Add support for GraphHopper by @karussell in #514
• [Core] Feat/common/step advance trip state by @Archdoog in #723

Bug Fixes

• [iOS] Fix device orientation-based dynamic layout by @ianthetechie in #736

Dependency Upgrades

• Bump tar from 7.5.1 to 7.5.2 in /react-native in the npm_and_yarn group across 1 directory by @dependabot[bot] in #729
• Bump kotlin from 2.2.0 to 2.2.21 in /android by @dependabot[bot] in #732
• Upgrade geo and vite; bump MSRV to 1.88 by @ianthetechie in #726

New Contributors

• @karussell made their first contribution in #514

Full Changelog: 0.44.0...0.45.0

0.44.0

Upgrade guide

Breaking changes

[Core] Step Advance

This release introduces a number of changes to the step advance system. This may require some changes to your code, depending on which APIs you used to configure step advance.

• The StepAdvanceCondition trait definition has changed. If you implemented a condition on your own, you'll need to add the route deviation parameter to your should_advance_step method.
• DistanceFromStepCondition has a new required parameter that determines whether to advance when the user has deviated from the route.

Other breaking changes

• [iOS] FerrostarWidgetProvider's update method now takes an additional parameter for the current spoken instruction.

Non-breaking highlights

• WaypointAdvanceMode has a new enum variant and improved documentation.
• DistanceEntryAndSnappedExit is a new built-in step advance condition. See #722 for details and discussion.
• Waypoint can now accept arbitrary properties. This enables you to leverage all properties supported by the routing engine. Valhalla-based routers (incl. Stadia Maps) provide a ton of flexibility, and you can access this in a type-safe manner! The Valhalla route provider documentation has more details and some example code: https://stadiamaps.github.io/ferrostar/route-providers.html#valhalla.
• We added a new step advance condition: DistanceEntryAndSnappedExitCondition. See the discussion on #722 for details.

PRs merged

Enhancements

• [Core] Add route deviation to step advance conditions for short circuit tooling by @Archdoog in #714
• [iOS] Improvements to Dynamic Island in the iOS demo app by @Archdoog in #711
• [Core] Separate waypoint advance and step advance behaviors from each other by @Archdoog in #716
• [Core] "Speed run" step advance until we can't advance anymore by @ianthetechie in #715
• [React Native] React Native Expo example by @bjtrounson in #718
• [Core] Add DistanceEntryAndSnappedExitCondition by @devnull133 in #722
• [Core] Add arbitrary extended waypoint properties by @ianthetechie in #721

Bug fixes

• [iOS, Android] Fix deviation before arrive on demo app by @Archdoog in #712

Dependency Upgrades

• [Android] Bump androidx.test.espresso:espresso-core from 3.6.1 to 3.7.0 in /android by @dependabot[bot] in #702
• [Android] Bump androidx-lifecycle from 2.9.2 to 2.9.4 in /android by @dependabot[bot] in #703
• [Core] Bump serde_json from 1.0.142 to 1.0.145 in /common by @dependabot[bot] in #704
• [Core] Bump uuid from 1.17.0 to 1.18.1 in /common by @dependabot[bot] in #706
• [iOS] Bump github.com/pointfreeco/swift-snapshot-testing from 1.18.6 to 1.18.7 by @dependabot[bot] in #708
• [Core] Bump proptest from 1.7.0 to 1.8.0 in /common by @dependabot[bot] in #707
• [Core] Bump log from 0.4.27 to 0.4.28 in /common by @dependabot[bot] in #709

New Contributors

• @devnull133 made their first contribution in #722

Full Changelog: 0.43.0...0.44.0

0.43.0

What's Changed

• Added dynamic island to guide summary by @Archdoog in #696
• Allow for optional accuracy in Speed by @alvar-bolt in #697
• Added NavigationSession and observers architecture (this enables observing navigation events from either platform layer code or Rust!) by @Archdoog in #698
• Improved CarPlayNavigationView by @Archdoog in #699
• Add navigation "caching" (ability to snapshot and resume; useful for handling things like CarPlay disconnects or Android killing your Activity and restarting later) by @Archdoog in #700

New Contributors

• @alvar-bolt made their first contribution in #697

Full Changelog: 0.42.0...0.43.0

0.42.0

Enhancements

• [SwiftUI] Convert all navigation modifiers into environment params by @Archdoog in #686 (Contains breaking changes, but the compiler should point these out. See the demo app PR diff for the new approach, which is significantly cleaner)
• [Android] Make BorderedPolyline opacity configurable by @ianthetechie in #691
• [iOS] Support route override; edgeinset improvements by @Archdoog in #688
• [SwiftUI] Add a configurable "off route" route banner by @Archdoog in #694

Bug fixes

• Hide road labels on iOS when off route by @Archdoog in #695
• Properly reset internal state when advancing to a new step (enforced via helper methods) by @Archdoog in #693

Dependency updates

• Bump @babel/runtime from 7.28.3 to 7.28.4 in /react-native in the npm_and_yarn group across 1 directory by @dependabot[bot] in #687
• Upgrade AGP to 8.13 by @ianthetechie in #689

Full Changelog: 0.41.0...0.42.0

0.41.0

Enhancements

This release concludes our GSoC 2025 project with @Kandarp05 🎉 Check out the web demo to try it out! You can now record a session and replay it, with some really slick debug controls.

• Add controls for replay in web. by @Kandarp05 in #679
• Write documentation for recording module by @Kandarp05 in #677

Bug fixes

• fix: returns raw user location when there is no deviation by @iboalali in #683
• fix: corrects and or step advance to manage state by @Archdoog in #684

Internal improvements

• Improve lint by @haysmike in #675

New Contributors

• @iboalali made their first contribution in #683

Full Changelog: 0.40.0...0.41.0

0.40.0

Version 0.40.0 is here with a massive set of improvements 🚀

Highlights

Separating the visual web component and core logic

🚨 Breaking change: In addition to being able to bring your own map, we've finally separated the business logic out of the web component thanks to @Kandarp05's work. The business logic now lives in FerrostarCore, just like on other platforms. FerrostarMap now only handles rendering the MapLibre control. Here's the migration guide if you're using Ferrostar on the web.

First, your web component usage in the markup will get a lot simpler!

-      <ferrostar-map
-        id="ferrostar"
-        valhallaEndpointUrl="https://api.stadiamaps.com/route/v1"
-        styleUrl="https://tiles.stadiamaps.com/styles/outdoors.json"
-        profile="bicycle"
-      ></ferrostar-map>
+      <ferrostar-map id="ferrostar"></ferrostar-map>

This is replaced by a little bit more JavaScript, but makes a clear separation between UI and business logic rather than stuffing everything into a single web component:

         // Get a reference to the Ferrostar map component
-        const ferrostar = document.getElementById("ferrostar");
-        ferrostar.map = mapInstance;
+        const ferrostarMap = document.getElementById("ferrostar");
+        let ferrostarCore = new FerrostarCore();
+        ferrostarCore.valhallaEndpointUrl =
+          "https://api.stadiamaps.com/route/v1";
+        ferrostarCore.profile = "bicycle";
+
+        ferrostarMap.map = mapInstance;

Finally, you need to explicitly link the map to a FerrostarCore instance (e.g. when starting navigation).

-          ferrostar.locationProvider = locationProvider;
-          ferrostar.startNavigation(route, config);
+          ferrostarMap.linkWith(ferrostarCore, true);
+          ferrostarCore.locationProvider = locationProvider;
+          ferrostarCore.startNavigation(route, config);

Dynamic Island

A picture is worth a thousand words here. @Archdoog has added some excellent-looking Dynamic Island support for iOS!

iOS Route Overview

The first pass of route overview in iOS has finally landed. There are still a few hiccups with the camera animation that we're working to smooth over; see #330 for discussion.

GSoC project: navigation session recording

@Kandarp05 is on the home stretch with our navigation session recording project. This release includes the full recording implementation AND the ability to replay a session, both in library form and integrated into our web demo!

As we finish out GSoC, we'll be working on some more improvements to the experience.

iOS Demo app improvements

In case you missed it, we've been slowly improving the iOS demo app with CarPlay support thanks to PRs from @bolsinga! We continue working toward a more polished "drop-in" integration with the same quality as the rest of the UI components, but this is more than enough to get you started with CarPlay.

Detailed Changelog

Enhancements

• Add recording events to NavState by @Kandarp05 in #619
• iOS: DemoCarPlayModel now has CPInterfaceController property by @bolsinga in #646
• KotlinX Serialization Migration from Moshi by @ben-burwood in #647
• Add StadiaSearch to iOS Demo App by @bolsinga in #649
• iOS: Demo Models funnel Errors through a single helper func by @bolsinga in #652
• Add serialization for Recording by @Kandarp05 in #630
• iOS Route Overview by @ianthetechie in #330
• Define wrapper of NavigationController for recording by @Kandarp05 in #653
• feat: dynamic island by @Archdoog in #663
• Separate Navigation Logic from Map Rendering in Web by @Kandarp05 in #662
• Navigation Replay in Web by @Kandarp05 in #673

Fixes

• iOS: Toggle the delegate when toggling the LocationProvider by @bolsinga in #644
• Changes necessary to pass newer SwiftFormat 0.57.0 by @bolsinga in #650
• fix: minor fixes for step advance and summary by @Archdoog in #655
• Remove improper main actor annotation by @bolsinga in #658
• Declare DetectorImpl as final to address swift concurrency warning by @bolsinga in #659
• Declare function types as Sendable to address swift concurrency warning by @bolsinga in #660

Dependency updates

• Bump github.com/pointfreeco/swift-snapshot-testing from 1.18.4 to 1.18.6 by @dependabot[bot] in #669
• Bump uniffi from 0.29.3 to 0.29.4 in /common by @dependabot[bot] in #671
• Bump serde_json from 1.0.140 to 1.0.142 in /common by @dependabot[bot] in #670
• Bump rstest from 0.25.0 to 0.26.1 in /common by @dependabot[bot] in #672
• Bump io.mockk:mockk from 1.14.4 to 1.14.5 in /android by @dependabot[bot] in #668
• Bump @babel/runtime from 7.27.6 to 7.28.2 in /react-native in the npm_and_yarn group across 1 directory by @dependabot[bot] in #664
• Bump androidx.test.ext:junit from 1.2.1 to 1.3.0 in /android by @dependabot[bot] in #667
• Bump androidx-lifecycle from 2.9.1 to 2.9.2 in /android by @dependabot[bot] in #666
• Bump proptest from 1.6.0 to 1.7.0 in /common by @dependabot[bot] in #628

Misc

• Initial proptest setup for step advance conditions by @ianthetechie in #656
• Fix Minor Inconsistency between Road/Street Name [ANDROID] by @ben-burwood in #665
• Fix iOS CI by @ianthetechie in #674

Full Changelog: 0.39.0...0.40.0

0.39.0

Step Advance v2

The major feature for this release is a complete overhaul of the step advance logic. You now have a lot more flexibility, including the ability to compose step advance rules, and to track internal state.

This was a massive effort by @Archdoog, and will enable better handling of traffic light pauses, U-turns, and more. The full PR is here.

This includes several 🚨 breaking changes.

iOS and Android

iOS and Android users now have a set of convenience methods available to configure step advance. These are currently exposed as top-level functions (we're still exploring better options to make this more discoverable). You can find browse the documentation for these on docs.rs. All changes for iOS and Android users will be flagged via compilation errors, so there is no chance of unexpected behavior post-upgrade.

The demo apps for both have been updated with usage examples.

• iOS
• Android

Web

Web users will have a few syntactic changes in how the step advance conditions are specified. Unfortunately, JavaScript does not have the same level of type safety as the mobile platforms, so you do need to carefully check your code or else you'll get an exception at runtime.

We've updated the example code to illustrate the most "complicated" step advance type, and you can check out the code here. The Rust documentation of the enum is currently still the best online reference.

Updates

• Bump android_logger from 0.15.0 to 0.15.1 in /common by @dependabot in #627
• Bump kotlinx-coroutines from 1.10.1 to 1.10.2 in /android by @dependabot in #623
• iOS: Update DemoApp only to use Swift 6 by @bolsinga in #635
• Updated dependencies including upgrade for kotlin.time by @Archdoog in #636
• iOS: Update DemoApp CarPlay Support by @bolsinga in #638
• Bump github.com/maplibre/swiftui-dsl from 0.12.0 to 0.14.0 by @dependabot in #626

Full Changelog: 0.38.0...0.39.0

0.38.0

iOS Demo App Enhancements

• Add SwitchableLocationProvider to DemoApp by @bolsinga in #616
• Mark FerrostarCoreFFI as @preconcurrency by @bolsinga in #632
• Use @mainactor and async let and @preconcurrency for DemoModel state changes by @bolsinga in #633

iOS Library Enhancements

• Allow CPTrip to be created with origin / destination by @bolsinga in #615
• Add CustomStringConvertible to FerrostarCore types by @bolsinga in #617
• Add Observable DemoModel by @bolsinga in #618
• Make APIKeys Swift 6 compatible by @bolsinga in #631

Bug Fixes

• Set the audio session mode to .voicePrompt by @ianthetechie in #613
• enforced MainActor on DemoModel state & removed NavigationStack by @Archdoog in

Updates

• Update UniFFI to 0.29.3 by @bjtrounson in #612
  #621

GSoC

• Update NavigationRecording struct by @Kandarp05 in #614

Full Changelog: 0.37.0...0.38.0