MapMapKit (iOS) reference

Generated from the published MapMapKit 0.8.0 sources (github.com/Mapmapai/mapmap-ios, tag 0.8.0) by website/scripts/sdk-reference-native.mjs. Do not edit by hand: change the doc comments in the SDK, or the examples in website/content/sdk-reference/ios.examples.md, and regenerate.

Every public declaration of the Swift package at release 0.8.0: the MapMapKit, MapMapValhalla and MapMapCarPlay products. The guide is iOS (Swift) in SDKs & installation, with Mobile maps with MapLibre Native for the map itself.

// Package.swift
.package(url: "https://github.com/Mapmapai/mapmap-ios.git", exact: "0.8.0")

Other SDK references: @mapmap/maps, @mapmap/points, @mapmap/core, @mapmap/tile, @mapmap/react-native, @mapmap/voice, ai.mapmap:core.

236 public declarations across 3 modules: 50 written by hand, 186 in the generated Rust bindings.

How to read this page

Each entry gives the declaration as written in the release source (in Kotlin without identifier backticks or the kotlin. package prefix), its doc comment, and its public members. The Default column shows a value only where the source writes one (an initialiser, a parameter's default, or a doc comment that states it); otherwise it is blank. Types and classes written by hand carry a minimal example. The generated bindings are the Rust core's types as UniFFI exposes them; their descriptions are the Rust doc comments.

Contents

• MapMapKit: 219 declarations
• MapMapValhalla: 1 declarations
• MapMapCarPlay: 16 declarations

MapMapKit

Classes (MapMapKit)

CoreLocationProvider, HTTPChannelFetcher, URLSessionProbeUploader, VoiceGuidance

CoreLocationProvider

Class · Sources/MapMapKit/Navigation/CoreLocationProvider.swift

public final class CoreLocationProvider: LocationProvider

Live LocationProvider on Core Location.

The SDK's Info.plist declares no usage strings. Apps must add NSLocationWhenInUseUsageDescription (and NSLocationAlwaysAndWhenInUseUsageDescription plus the location background mode for background guidance) and obtain authorisation before the stream is consumed, see ios/README.md ("Location authorisation"). If authorisation is denied while streaming, the stream finishes by throwing CLError.denied.

Samples map platform sentinels to nil: negative horizontalAccuracy (invalid fix channels), negative speed and negative course are all reported as absent rather than passed through.

Initialisers and methods

• public init(configuration: Configuration = Configuration())

Nested: CoreLocationProvider.Configuration.

Example

import MapMapKit

let gps = CoreLocationProvider(configuration: .init(allowsBackgroundLocationUpdates: true))
for try await fix in gps.locations {
    print(fix.lat, fix.lon, fix.horizontalAccuracyM ?? -1)
}

HTTPChannelFetcher

Class · Sources/MapMapKit/Territory/ChannelSource.swift

public final class HTTPChannelFetcher: LayerFetcher, @unchecked Sendable

A blocking HTTPS LayerFetcher for a ChannelSource, on URLSession. TerritoryStore calls it off the cooperative pool.

apiKey is sent as Authorization: Bearer <apiKey> (the hosted gateway meters layer downloads against the key's allowance); nil for an open mirror. cancel is polled while a request is in flight, so a tripped token aborts the transfer, not only the next one. configuration defaults to an ephemeral session (pass your own for a proxy or a test URLProtocol).

Initialisers and methods

• public init(source: ChannelSource, apiKey: String? = nil, cancel: CancelToken? = nil, onBytes: (@Sendable (Int64) -> Void)? = nil, configuration: URLSessionConfiguration? = nil)
• public func fetchIndex() throws -> SignedChannelIndex: GET the signed index and its signature, exact bytes.
• public func fetch(relPath: String, expectedBlake3: String, destPath: String) throws

Example

import MapMapKit

// The fetcher TerritoryStore.sync(territoryId:source:apiKey:) builds for you; use it directly
// when you drive installFromChannel or checkForUpdate yourself.
let fetcher = HTTPChannelFetcher(source: .gateway(), apiKey: "snk_…")
let index = try fetcher.fetchIndex()
print(index.json.count, fetcher.bytesReceived)

URLSessionProbeUploader

Class · Sources/MapMapKit/Navigation/ProbeContribution.swift

public final class URLSessionProbeUploader: ProbeUploader, @unchecked Sendable

Default ProbeUploader: POSTs each body to {baseURL}/v1/probe with a bearer key via URLSession. Transient failures (transport or 5xx) are retried with bounded backoff; permanent ones (400/403/501) are dropped. No third-party dependency.

Initialisers and methods

• public init(baseURL: String, apiKey: String, session: URLSession = .shared, maxAttempts: Int = 4, backoff: @escaping @Sendable (Int) -> TimeInterval = { TimeInterval($0) }, onResult: @escaping @Sendable (ProbeUploadOutcome) -> Void = { _ in }): - Parameters: - baseURL: gateway origin, e.g. https://api.mapmap.ai (a trailing slash is tolerated). - maxAttempts: total tries including the first. - backoff: attempt number → delay before the next try.
• public func enqueue(_ body: String)

Example

import MapMapKit

// Opt-in aggregate probe upload (POST /v1/probe), retried with backoff.
let uploader = URLSessionProbeUploader(baseURL: "https://api.mapmap.ai", apiKey: "snk_…") { outcome in
    print("probe upload:", outcome)
}
let routeJson = "{}" // a Valhalla route response
let engine = NavigationEngine(routeResponseJson: routeJson)
let states = contributingProbe(
    await engine.navigate(provider: CoreLocationProvider()),
    config: ProbeConfig(enabled: true),
    uploader: uploader
)
for try await state in states { if state.isArrived { break } }

VoiceGuidance

Class · Sources/MapMapKit/Navigation/VoiceGuidance.swift

public final class VoiceGuidance: NSObject, AVSpeechSynthesizerDelegate

Spoken turn-by-turn guidance over AVSpeechSynthesizer (offline, the platform voices synthesise on device).

Feed every NavigationState (or raw GuidanceUpdate) from NavigationEngine/navigate(provider:):

swift let voice = VoiceGuidance() for try await state in await engine.navigate(provider: provider) { voice.handle(state) render(state) }

The core schedules each spoken prompt by its trigger distance and repeats it on every update until it is superseded, so the speaking rule is: announce each utteranceId exactly once, the first time it appears. Severity maps to prosody and earcons via VoiceProsody; critical prompts stop pending speech. Off-route plays the warning earcon once per episode. Observe isSpeaking / onSpeakingChanged to reflect live speaking state in UI (e.g. a pulsing voice icon). On iOS the audio session ducks other audio around announcements (.duckOthers + .voicePrompt), so music dims rather than stops, and is deactivated again once the last utterance finishes, so music comes back to full volume instead of staying ducked forever.

Initialisers and methods

• public init(language: String? = nil, baseRate: Float = AVSpeechUtteranceDefaultSpeechRate): - Parameters: - language: BCP 47 tag for the voice, e.g. en-GB. nil keeps the device default voice. - baseRate: base AVSpeechUtterance rate (platform default when omitted).
• public func handle(_ update: GuidanceUpdate): Consume one guidance update. Cheap; call it for every emission of NavigationEngine/navigate(provider:).
• public func handle(_ state: NavigationState): Convenience overload for NavigationEngine/navigate(provider:) emissions.
• public func stop(): Stop speech and release the earcon player. Deactivates the audio session (un-ducking whatever else plays) when anything was live.
• public func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didFinish utterance: AVSpeechUtterance)
• public func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didCancel utterance: AVSpeechUtterance)

Example

import MapMapKit

let voice = VoiceGuidance(language: "en-GB")
voice.volume = 0.8
voice.onSpeakingChanged = { speaking in print("speaking:", speaking) }
// For every emission of NavigationEngine.navigate(provider:):
// voice.handle(state.update)
voice.muted = true

Actors (MapMapKit)

NavigationEngine, TerritoryStore

NavigationEngine

Actor · Sources/MapMapKit/Navigation/NavigationEngine.swift

public actor NavigationEngine

Turn-by-turn guidance over one computed route.

The Rust core's GuidanceSession (Ferrostar-based) is the navigation state machine; this engine owns its lifecycle and adapts it to Swift concurrency: stream LocationSamples in from any LocationProvider, receive NavigationStates out. The stream completes after arrived. An engine is bound to a single route, on offRoute, compute a new route and build a new engine (see NavigationState/needsReroute).

Ferrostar UI note: the Stadia Maps Ferrostar iOS packages (https://github.com/stadiamaps/ferrostar, SwiftPM products FerrostarCore, FerrostarMapLibreUI, FerrostarSwiftUI, FerrostarCarPlayUI) can render on top of this state, but our GuidanceSession remains the state machine, see ios/README.md, "Ferrostar boundary".

Initialisers and methods

• public init(routeResponseJson: String, config: GuidanceConfig = GuidanceConfig())
• public init(route: RouteResult, config: GuidanceConfig = GuidanceConfig()): Build an engine from a route computed by OfflineRouting/route(router:waypoints:costing:adr:).
• public func totalSteps() throws -> UInt32: Total number of steps in the route (including arrival), for progress UIs. Opens a short-lived native session. - Throws: NavCoreError if the route response cannot start a session (e.g. malformed JSON).
• public func navigate(provider: some LocationProvider) -> AsyncThrowingStream< NavigationState, Error >: Run guidance: feed every fix from provider into a fresh native session and emit the resulting states. Each call starts a new session at the first route step; a previous run on the same engine is stopped first. The stream completes after arrival, or fails with NavCoreError if the route response cannot start a session, or with the provider's error if the fix stream fails.
• public func advanceToNextStep() throws: Manually advance to the next step, the tunnel/no-GNSS escape hatch (Ferrostar exposes this on its navigator; the core forwards it). Ignored before the first fix of the active run, mirroring the Android SDK.
• public func stop(): Stop the active run, if any: the stream finishes without error and the native session is released.

Example

import MapMapKit

// A Valhalla route response (hosted /route, or OfflineRouting.route on the device).
let routeJson: String = try String(contentsOf: Bundle.main.url(forResource: "route", withExtension: "json")!)
let engine = NavigationEngine(routeResponseJson: routeJson)
let voice = VoiceGuidance(language: "en-GB")
for try await state in await engine.navigate(provider: CoreLocationProvider()) {
    voice.handle(state.update)
    if state.isArrived { break }
    if state.needsReroute { /* request a new route and build a new engine */ }
}

TerritoryStore

Actor · Sources/MapMapKit/Territory/TerritoryStore.swift

public actor TerritoryStore

Actor-isolated store of signed offline territory packages.

Wraps the Rust TerritoryManager: every package is ed25519-signature and BLAKE3-layer-hash verified before promotion, and nothing is trusted until verification passes. Verification is fail-closed, a package that does not verify is never promoted and leaves nothing on disk.

All methods are async by actor isolation; the disk-heavy calls (installs read whole archives) additionally hop onto a detached utility task so they never occupy a cooperative-pool thread for the duration of an install.

territories caches the installed set; it refreshes after every mutating call and on refresh(). Observe changes with territoryUpdates().

Installs are cancellable. The cancel: overloads take a CancelToken (from the core) that can be tripped from any thread, and they also trip it when the calling Swift Task is cancelled, so task.cancel() works the way callers expect. A cancelled install returns InstallOutcome.cancelled / UpdateOutcome.cancelled rather than throwing: nothing was installed, staging is removed, the previous version is untouched. Cancelling after completion changes nothing.

Custom regions (region- ids, cut by POST /v1/jobs/territory) are signed by a separate region key. Pass its public half as regionKeyHex (TerritoryKeys/hostedRegionKeyHex for the hosted gateway) to accept them; the core then verifies region- ids against that key only and every other id against the factory key only. Without it every region- package is refused as a bad signature.

Initialisers and methods

• public init(rootDir: URL, verifyingKeyHex: String, regionKeyHex: String? = nil): - Parameters: - rootDir: directory the store owns; created on first use. - verifyingKeyHex: the factory signing key's public half, 64 hex characters (sn_package::VerifyingKey::to_hex). Baked into the app at build time, treat it like a pin. - regionKeyHex: the region signing key's public half, 64 hex characters, or nil to refuse custom regions. Pinned like the factory key; never read from the network.
• public func refresh() async throws -> [TerritoryInfo]: Re-read the installed set from disk, cache and broadcast it.
• public func install(snpkg: URL) async throws -> TerritoryInfo: Install a packed .snpkg archive. Verify-then-promote: a package that fails verification leaves no trace on disk. - Throws: NavCoreError/Verification(message:) if the signature or any layer hash does not verify.
• public func install(snpkg: URL, cancel: CancelToken) async throws -> InstallOutcome: install(snpkg:) with a cancellation handle. The core polls cancel between archive entries, before verification and before promotion; a tripped token (or a cancelled calling task) yields .cancelled with staging removed and nothing installed.
• public func installDirectory(_ packageDir: URL) async throws -> TerritoryInfo: Install an unpacked package directory (same verification rules).
• public func installDirectory(_ packageDir: URL, cancel: CancelToken) async throws -> InstallOutcome: installDirectory(_:) with a cancellation handle; see install(snpkg:cancel:).
• public func installFromChannel(territoryId: String, indexJson: String, indexSigBase64: String, fetcher: LayerFetcher, omit: [MapLayerKind] = [], cancel: CancelToken = CancelToken()) async throws -> ChannelInstallOutcome: Install territoryId from its channel: the first-install counterpart of applyUpdate(territoryId:manifestJson:manifestSigBase64:fetcher:). indexJson / indexSigBase64 are the exact served bytes of the channel index and its detached signature; the channel's latest version is installed, fetching only the layers not in omit. Nothing is trusted but the pinned keys: the index signature, the manifest signature and every layer hash are checked, and the assembled package goes through the full verification pass before it is promoted. Interrupted installs resume. A tripped cancel (or a cancelled calling task) yields .cancelled with nothing installed. - Throws: NavCoreError/Verification(message:) if a signature or hash does not verify, including a region- id on a store without a region key.
• public func sync(territoryId: String, indexJson: String, indexSigBase64: String, fetcher: LayerFetcher, omit: [MapLayerKind] = [], cancel: CancelToken = CancelToken()) async throws -> ChannelSync: Bring territoryId to the channel's latest version, whichever way that takes: a first install from the channel when it is not installed, a signed differential update when an older version is, nothing when it is already current. Updates go through checkForUpdate(territoryId:indexJson:indexSigBase64:fetcher:), so a channel can never move an installed territory backwards.
• public func sync(territoryId: String, source: ChannelSource, apiKey: String? = nil, omit: [MapLayerKind] = [], cancel: CancelToken = CancelToken(), onBytes: (@Sendable (Int64) -> Void)? = nil) async throws -> ChannelSync: sync(territoryId:indexJson:indexSigBase64:fetcher:omit:cancel:) over HTTPS: fetch the signed index from source and every layer relative to it with an HTTPChannelFetcher. cancel also stops a transfer in progress.
• public func installCustomRegion(territoryId: String, indexURL: URL, indexSigURL: URL, apiKey: String? = nil, omit: [MapLayerKind] = [], cancel: CancelToken = CancelToken(), onBytes: (@Sendable (Int64) -> Void)? = nil) async throws -> ChannelSync: Install, or update, a custom region from the territory_id, index_url and index_sig_url of a POST /v1/jobs/territory result. A re-cut of the same area after the country is republished is the same id at a newer version, so calling this again is the update. - Throws: ChannelSourceError/noRegionKey if this store has no region key; ChannelSourceError for a malformed id or URL.
• public func verify(territoryId: String) async throws -> TerritoryInfo: Re-verify an installed territory from disk: the manifest signature (against the key its id is partitioned to), the hash of every layer it holds and the absence of every layer it omitted. The on-demand integrity check for after a restore or a crash. - Throws: NavCoreError/Verification(message:) when the install must be repaired or reinstalled.
• public func setActive(_ territoryId: String) async throws: Mark territoryId active; persisted atomically by the core.
• public func active() async throws -> String?: The active territory id, if one is set and still installed.
• public func activeTerritory() async throws -> TerritoryInfo?: The active territory's full info, if any.
• public func layerPath(territoryId: String, kind: MapLayerKind) async throws -> URL: Absolute path of one layer of an installed territory, e.g. MapLayerKind/valhallaTiles for the on-device router, MapLayerKind/pmtiles for MapLibre.
• public func territoryStyle(territoryId: String, theme: StyleTheme = .light) async throws -> String: A complete MapLibre style JSON for an installed territory with local (offline) references, mirroring the web SDK's buildStyle(). Load it straight into MapLibre, the territory tile source points at the installed PMTiles layer via a pmtiles://<absolute path> URL, so the map renders with radios off. Packages without a baked style layer get the default MapMap theme compiled on the fly.
• public func openSearch(territoryId: String) async throws -> TerritorySearch: Open the installed territory's bundled geocode index for fully offline on-device search. The returned handle holds the index open (mmap-backed), create it once per territory and reuse it: swift let search = try await store.openSearch(territoryId: "uk") let places = try search.search( query: "watford gap", near: nil, limit: 10)
• public func remove(_ territoryId: String) async throws: Remove an installed territory (clears the active marker if needed).
• public func planUpdate(newManifestJson: String) async throws -> UpdatePlan: Plan a differential update against a newly served (signed) manifest JSON: which layers must be downloaded, and how many bytes.
• public func checkForUpdate(territoryId: String, indexJson: String, indexSigBase64: String, fetcher: LayerFetcher) async throws -> AvailableUpdate?: Check the signed channel index for an update to an installed territory. indexJson must be the exact bytes served as index.json and indexSigBase64 the content of index.json.sig; the remote manifest is fetched and verified through fetcher (the app's download transport, URLSession, an air-gapped mirror, …, the core decides what to fetch and cryptographically verifies everything itself). Returns nil when the device is already on the channel's latest version or the channel does not list the territory.
• public func applyUpdate(territoryId: String, manifestJson: String, manifestSigBase64: String, fetcher: LayerFetcher) async throws -> UpdateResult: Apply a differential update: stage, fetch only the changed layers through fetcher, verify everything and swap atomically. Any failure leaves the installed territory untouched; the active flag is preserved.
• public func applyUpdate(territoryId: String, update: AvailableUpdate, fetcher: LayerFetcher) async throws -> UpdateResult: Apply an update discovered by checkForUpdate(territoryId:indexJson:indexSigBase64:fetcher:), passing its manifest and signature through verbatim.
• public func applyUpdate(territoryId: String, manifestJson: String, manifestSigBase64: String, fetcher: LayerFetcher, cancel: CancelToken) async throws -> UpdateOutcome: applyUpdate(territoryId:manifestJson:manifestSigBase64:fetcher:) with a cancellation handle. The core polls cancel before every layer download, between archive entries while unpacking, before each hash pass and before promotion; a tripped token (or a cancelled calling task) yields .cancelled. The installed version is untouched and staging removed; layers already fetched and verified stay in the resumable cache, so a later attempt with the same manifest re-fetches only what is missing. The token cannot interrupt fetcher while it is inside a transfer: give the fetcher the same token and have it poll isCancelled() between chunks (or cancel its URLSessionTask). Whatever the fetcher then throws, a tripped token reports .cancelled rather than a transport error.
• public func applyUpdate(territoryId: String, update: AvailableUpdate, fetcher: LayerFetcher, cancel: CancelToken) async throws -> UpdateOutcome: applyUpdate(territoryId:update:fetcher:) with a cancellation handle; see applyUpdate(territoryId:manifestJson:manifestSigBase64:fetcher:cancel:).
• public func territoryUpdates() -> AsyncStream<[TerritoryInfo]>: A stream of the installed set: yields the current value immediately, then every subsequent change. Each call returns an independent stream; it finishes when the store is deallocated.

Example

import MapMapKit

let root = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
    .appendingPathComponent("territories")
let store = TerritoryStore(
    rootDir: root,
    verifyingKeyHex: TerritoryKeys.hostedFactoryKeyHex,
    regionKeyHex: TerritoryKeys.hostedRegionKeyHex
)
// First install or update, whichever is needed, from the hosted channel.
let result = try await store.sync(territoryId: "uk", source: .gateway(), apiKey: "snk_…")
try await store.setActive("uk")
let styleJson = try await store.territoryStyle(territoryId: "uk", theme: .dark)
print(result, styleJson.count)

Structs (MapMapKit)

ChannelSource, CoreLocationProvider.Configuration, CorpusFormatError, DriveCorpus, DriveFix, DriveHeader, LocationSample, NavigationCameraInterpolator, NavigationState, ReplayLocationProvider, SignedChannelIndex, SpeechSessionRefCount, VoiceProsody

ChannelSource

Struct · Sources/MapMapKit/Territory/ChannelSource.swift

public struct ChannelSource: Equatable, Sendable

Where a signed territory channel lives over HTTPS: its index, the index's detached signature, and the base every channel-relative layer path (territories/<id>/<version>/...) is resolved against.

Nothing fetched from here is trusted: the core verifies the index signature, the manifest signature and every layer hash against the keys pinned in the TerritoryStore.

Initialisers and methods

• public init(indexURL: URL, indexSigURL: URL, layerBaseURL: URL)
• public static func gateway(_ base: URL = defaultGateway) -> ChannelSource: A gateway's country channel: GET /territories (the signed index) and GET /territories/index.sig.
• public static func customRegion(territoryId: String, indexURL: URL, indexSigURL: URL) throws -> ChannelSource: A custom region's own one-territory channel, from the index_url / index_sig_url of a POST /v1/jobs/territory result. The gateway serves the index at <base>/v1/territories/<id>/index.json and the layers under <base>/territories/<id>/..., so the layer base is <base>. Any other .../index.json (a mirror of the region directory, laid out as SN_REGION_DIR/<id>/) resolves layers next to the index. - Throws: ChannelSourceError if territoryId is not a custom-region id or indexURL does not end in index.json.
• public static func isCustomRegionId(_ territoryId: String) -> Bool: Whether territoryId has the shape the gateway gives custom regions: region- plus 16 lowercase hex characters.

CoreLocationProvider.Configuration

Struct · Sources/MapMapKit/Navigation/CoreLocationProvider.swift

public struct Configuration: Sendable

Configuration forwarded to CLLocationManager.

Initialisers and methods

• public init(desiredAccuracy: CLLocationAccuracy = kCLLocationAccuracyBestForNavigation, distanceFilter: CLLocationDistance = kCLDistanceFilterNone, activityType: CLActivityType = .automotiveNavigation, allowsBackgroundLocationUpdates: Bool = false)

CorpusFormatError

Struct · Sources/MapMapKit/Replay/DriveCorpus.swift

public struct CorpusFormatError: Error, Equatable, LocalizedError

A .drive.jsonl document violated the corpus format.

Initialisers and methods

• public init(_ message: String)

DriveCorpus

Struct · Sources/MapMapKit/Replay/DriveCorpus.swift

public struct DriveCorpus: Equatable, Sendable

Parser for the .drive.jsonl replay corpus format produced by the workspace's sn-replay crate (see crates/sn-replay/src/corpus.rs).

Line 1 is a JSON header (format_version, name, description, route_fixture, seed, optional generator); every following non-blank line is one GPS fix (t_ms, lat, lon, optional speed_mps, bearing_deg, horizontal_accuracy_m). The Swift parser enforces the same invariants as the Rust one (and the Kotlin one in android/): supported format version, non-empty name, at least one fix, strictly increasing t_ms, and sane coordinate/channel ranges.

Initialisers and methods

• public static func parse(_ jsonl: String) throws -> DriveCorpus: Parse and validate a corpus from JSON-lines text. - Throws: CorpusFormatError describing the first violation, with its 1-based line number where applicable.
• public static func parse(contentsOf url: URL) throws -> DriveCorpus: Read and parse a corpus file.

DriveFix

Struct · Sources/MapMapKit/Replay/DriveCorpus.swift

public struct DriveFix: Equatable, Sendable

One GPS fix line of a corpus. tMs is milliseconds since drive start.

DriveHeader

Struct · Sources/MapMapKit/Replay/DriveCorpus.swift

public struct DriveHeader: Equatable, Sendable

Header line of a .drive.jsonl corpus.

LocationSample

Struct · Sources/MapMapKit/Navigation/LocationProvider.swift

public struct LocationSample: Equatable, Sendable

One position sample fed into guidance.

Initialisers and methods

• public init(lat: Double, lon: Double, timestampMs: Int64, speedMps: Double? = nil, bearingDeg: Double? = nil, horizontalAccuracyM: Double? = nil)

NavigationCameraInterpolator

Struct · Sources/MapMapKit/Navigation/NavigationCameraInterpolator.swift

public struct NavigationCameraInterpolator: Sendable

Turns a ~1 Hz stream of guidance fixes into a value that can be sampled on every display frame, so a follow camera moves continuously instead of stepping once per fix.

Why this type exists

Guidance fixes arrive at roughly 1 Hz (the replay corpora and Core Location both). Driving a map camera straight off them looks jerky in two distinct ways, and only one of them is fixed by easing:

1. Per-tick easing. Kicking off one animation per fix (MapLibre's easeTo/setCamera(_:withDuration:)) hands the camera a new target while the previous animation is still running. Each new animation restarts from wherever the last one had got to, with its own easing curve, so the velocity resets 1x/second, visible as a pulse.
2. Two clocks. Animating a map-anchored puck while the camera is itself animating gives the scene two independent clocks that drift against each other. That desync is the "stutters back and forth, worse at low zoom" bug already diagnosed and fixed in the MapMapNav app (see src/screens/guidance/ChaseLayer.tsx, whose fix, camera only, puck as a fixed screen overlay, this iOS work mirrors).

This type addresses (1): the host samples it from a CADisplayLink and applies the result to the map with no animation, so the frame clock is the only clock. (2) is addressed by the host drawing the puck as a fixed overlay at the camera focal point.

There is a third way for this to look wrong, and setRoute(coordinates:) is the answer to it: interpolating in a straight line between two fixes a second apart cuts corners, so through a bend the vehicle drifts off the road and back on. Given the route, the interpolation runs in arc length along it and every position reported is a point of the route.

Presentation lag (deliberate)

state(at:) reports where the vehicle was one fix-interval ago. That lag is what lets it interpolate between two known fixes rather than guess ahead of the newest one, and it is what makes the motion continuous: the sample reaches fix N exactly as fix N+1 lands, and the next segment starts from that same point.

This is not a new trade-off. The approved MapMapNav chase camera has the identical lag by construction, ChaseLayer eases to each fix over a duration equal to the gap since the previous one, so its camera also arrives at fix N as fix N+1 appears. The difference here is only that a frame clock replaces one animation per tick.

Guidance text, distances and ETA are not lagged: they come straight from the engine tick. Only the camera geometry is interpolated.

Clock

The type is clock-agnostic: timestamp is whatever monotonic seconds the host feeds, and state(at:) must be queried on the same clock. Hosts should feed the arrival time of each fix (CACurrentMediaTime()), not the fix's own timestampMs: arrival time is what the extrapolation cap needs to reason about, and it stays correct when a replay runs at a time scale (ReplayLocationProvider(timeScale:)) or when fixes are delivered late.

Pure value type: no UIKit, no MapLibre, no CarPlay, so it builds and is tested on the macOS host path (MAPMAP_HOST_CORE=1 swift test) as well as on iOS.

Initialisers and methods

• public init()
• public mutating func setRoute(coordinates: [CLLocationCoordinate2D]): Give the interpolator the route the vehicle is driving, so that it interpolates along the road instead of straight between fixes. Why this matters: fixes arrive about a second apart, which at urban speed is 10–15 m. Interpolating in a straight line between two of them cuts every corner, through a bend the interpolated point leaves the route line, and the puck visibly drifts off the road and back on again. Interpolating in arc length along the route and emitting the point on the polyline cannot do that: every position it reports is a point of the route. The cumulative-distance table is built once, here. Rebuilding it per tick is the mistake that froze MapMapNav's JS thread (src/state/guidance/routeProgress.ts documents the same precompute); this type projects a fix onto the route once per fix (~1 Hz), and the per-frame query is a binary search and a lerp. Pass the route geometry in order. Fewer than two points clears it. Both stored fixes are re-snapped onto the new geometry here. A sample's alongM is an arc length measured against whatever polyline was current when the fix arrived, and state(at:) evaluates it against whatever polyline is current now, so carrying the old numbers across a reroute reads "2 km along route A" as "2 km along route B" and puts the camera wherever that happens to land, which on a reroute starting elsewhere is a jump of degrees of latitude (reproduced on the Android side). The re-snap honours onRouteToleranceM exactly as feed(coordinate:courseDeg:speedMps:timestamp:) does, so a pose the new route does not pass near loses its match and falls back to point-to-point rather than being dragged onto a line it was never on.
• public mutating func feed(coordinate: CLLocationCoordinate2D, courseDeg: Double?, speedMps: Double?, timestamp: TimeInterval): Feed one guidance fix. - Parameters: - coordinate: the position to follow. Use the route-snapped fix (GuidanceDisplay.snappedFix), never the raw one: raw GPS drifts off the carriageway, and on a course-up camera that reads as the whole world shaking. - courseDeg: course over ground, degrees clockwise from true north. Values outside [0, 360) are wrapped. - speedMps: speed over ground. Below standstillSpeedMps the bearing is frozen (see the property). - timestamp: monotonic seconds on the host's clock, the fix's arrival time (see the type's "Clock" note). Fixes that are out of order, simultaneous with the newest one, or non-finite are ignored: replaying them would send the camera backwards.
• public func state(at timestamp: TimeInterval) -> (coordinate: CLLocationCoordinate2D, bearingDeg: Double)?: The camera position and bearing to render at timestamp. nil before the first fix, the host should leave the camera where it framed the route. Behaviour, in the order the cases arise: - first fix: snaps to it (nothing to interpolate between); - healthy feed: linear interpolation between the two newest fixes, one interval behind live (see the type's "Presentation lag" note); - late fix: keeps going along the last segment, but only as far as extrapolationCap, half an interval past the newest fix; - stale feed: holds at that capped point. With a route set (setRoute(coordinates:)) and both fixes on it, the interpolation runs in arc length along the route and the position returned is a point on the route line, with the bearing taken from the route's own direction there. Without a route, or once a fix projects further than onRouteToleranceM off it, it falls back to interpolating the two fixes directly. The fallback interpolates linearly in latitude/longitude. Over one fix interval of driving (tens of metres) the difference from a great-circle path is far below a pixel, so the cheap form is the honest one. It does not handle a segment crossing the antimeridian; no MapMap route fixture does.
• public static func wrap360(_ degrees: Double) -> Double: Normalise to [0, 360).
• public static func shortestArcDelta(from: Double, to: Double) -> Double: Signed shortest-arc difference from -> to, in [-180, 180). Positive is clockwise. The half-open range matches shortestArcDeltaDeg on the Android side down to the boundary: an exact 180 degree reversal resolves anticlockwise on both platforms rather than one each way.

NavigationState

Struct · Sources/MapMapKit/Navigation/NavigationState.swift

public struct NavigationState: Equatable, Sendable

One guidance emission: the fix that produced it plus the core's verdict.

GuidanceUpdate is the Rust core's state, navigating, arrived or offRoute, and the single source of truth. This wrapper only adds the triggering sample and display conveniences.

Initialisers and methods

• public init(fix: LocationSample, update: GuidanceUpdate)

ReplayLocationProvider

Struct · Sources/MapMapKit/Navigation/ReplayLocationProvider.swift

public struct ReplayLocationProvider: LocationProvider

Replays a .drive.jsonl corpus (the sn-replay QA format) as a LocationProvider.

Fix timestamps in the corpus are relative to drive start; they are rebased onto epochStartMs so guidance sees monotonic wall-clock-like times.

Initialisers and methods

• public init(corpus: DriveCorpus, timeScale: Double = 1.0, epochStartMs: Int64 = 0): - Parameters: - corpus: a parsed corpus (see DriveCorpus/parse(_:)). - timeScale: playback speed: 1.0 = real time, 2.0 = twice as fast, 0.0 = emit every fix immediately (unit tests). - epochStartMs: epoch milliseconds assigned to the first fix.

SignedChannelIndex

Struct · Sources/MapMapKit/Territory/ChannelSource.swift

public struct SignedChannelIndex: Equatable, Sendable

The exact served bytes of a channel index and its detached signature.

SpeechSessionRefCount

Struct · Sources/MapMapKit/Navigation/VoiceGuidance.swift

public struct SpeechSessionRefCount: Equatable, Sendable

Ref-count of in-flight utterances, deciding when the shared audio session may be deactivated (so ducked music comes back up), pure and unit-testable anywhere, like VoiceProsody. The platform wiring in VoiceGuidance mutates it under a lock: AVSpeechSynthesizer delegate callbacks arrive on an arbitrary queue.

Initialisers and methods

• public init()
• public mutating func willSpeak(): Record one utterance handed to the synthesiser.
• public mutating func didEnd() -> Bool: Record one utterance finishing or being cancelled. Returns true when that was the last one, nothing is speaking or queued, so the audio session should be deactivated. Spurious callbacks after a reset() never trigger another deactivation.
• public mutating func reset() -> Bool: Clear everything (stop()). Returns true when there was anything outstanding, i.e. the session should be deactivated.

VoiceProsody

Struct · Sources/MapMapKit/Navigation/VoiceGuidance.swift

public struct VoiceProsody: Equatable, Sendable

Prosody and earcon policy per InstructionSeverity, pure and unit-testable anywhere (the platform wiring lives in VoiceGuidance).

The core derives severity (see InstructionSeverity in crates/sn-nav-core): .info for routine manoeuvres, .warning when approaching a restriction (toll, ferry, and off-route), .critical for prohibitions (ADR tunnel block, gate).

Initialisers and methods

• public static func prosody(for severity: InstructionSeverity, baseRate: Float = AVSpeechUtteranceDefaultSpeechRate) -> VoiceProsody: Prosody for severity at baseRate (defaults to the platform's default speech rate). Critical prompts speak slightly faster, clamped to the platform maximum.
• public static func earconName(for severity: InstructionSeverity) -> String?: The earcon resource name for severity, or nil when the severity plays none by default (info stays silent so a chime does not precede every routine manoeuvre). Assets are generated by scripts/generate-earcons.py.
• public static func earconURL(for severity: InstructionSeverity) -> URL?: URL of the earcon WAV inside MapMapKit's resource bundle, or nil for severities that play none.

Enums (MapMapKit)

AdrCompliance, ChannelSourceError, ChannelSync, GuidanceDisplay, MapMap, MapMapKitError, OfflineRouting, ProbeUploadOutcome, TerritoryKeys, ValhallaConfigWriter

AdrCompliance

Enum · Sources/MapMapKit/Adr/AdrCompliance.swift

public enum AdrCompliance

On-device ADR 8.6.4 dangerous-goods enforcement.

Two enforcement points, both running the same Rust domain model (sn-adr, conservative ADR 8.6.4 reading):

1. Pre-route, pass the AdrProfile to OfflineRouting/route(router:waypoints:costing:adr:); the core merges the restrictions into Valhalla truck costing, so forbidden tunnels and undersized roads are excluded before a route exists.
2. En-route, call checkTunnel(profile:category:) against a tunnel's category (e.g. from map data ahead of the vehicle) to gate entry while driving, and forbiddenCategories(profile:) to badge the whole profile in the UI.

Initialisers and methods

• public static func checkTunnel(profile: AdrProfile, category: AdrTunnelCategory) -> AdrDecision: May the vehicle described by profile pass through a tunnel of category? Blocked decisions carry a human-readable reason citing ADR 8.6.4.
• public static func forbiddenCategories(profile: AdrProfile) -> [AdrTunnelCategory]: All tunnel categories the vehicle is forbidden from, ascending. Empty when unrestricted.
• public static func isTunnelRestricted(profile: AdrProfile) -> Bool: True when the profile is barred from at least one tunnel category.
• public static func validateProfile(_ profile: AdrProfile) -> [String]: Validate a profile's physical plausibility before it goes anywhere near routing. Returns a list of human-readable problems; empty means valid. Pure Swift, safe to call from previews and tests without the native library.

ChannelSourceError

Enum · Sources/MapMapKit/Territory/ChannelSource.swift

public enum ChannelSourceError: Error, Equatable, CustomStringConvertible

Why a ChannelSource could not be built.

ChannelSync

Enum · Sources/MapMapKit/Territory/TerritoryStore.swift

public enum ChannelSync: Sendable

What TerritoryStore/sync(territoryId:indexJson:indexSigBase64:fetcher:omit:cancel:) did.

GuidanceDisplay

Enum · Sources/MapMapKit/Navigation/NavigationState.swift

public enum GuidanceDisplay

Pure display mappers for GuidanceUpdate. Kept free of native calls so they are unit-testable anywhere.

Initialisers and methods

• public static func instruction(_ update: GuidanceUpdate) -> String?: The instruction to show for the current update, if any.
• public static func visualBanner(_ update: GuidanceUpdate) -> VisualBanner?: The visual banner for the upcoming manoeuvre, when one is active at the current distance (primary/secondary/sub lines with lane diagrams; render primary.text with the arrow named by primary.maneuverType/maneuverModifier).
• public static func spokenPrompt(_ update: GuidanceUpdate) -> SpokenPrompt?: The spoken prompt currently due. Hand ssml ?? text to AVSpeechSynthesizer, and de-duplicate by utteranceId, the same prompt is reported on every update until it is superseded.
• public static func severity(_ update: GuidanceUpdate) -> InstructionSeverity: How urgently the update should be surfaced (see the core's InstructionSeverity for the derivation). Off-route is a .warning, the driver has left the route and a recalculation is due; arrival is routine.
• public static func snappedFix(_ update: GuidanceUpdate) -> SnappedFix?: The route-snapped position and course for the current update, if any. Drive follow-cameras from this, e.g. feed it into a MapLibre course-tracking camera (MapViewCamera.automotiveNavigation() style: course-up, zoom 16, pitch 45), never the raw fix, which jitters and drifts off the carriageway.
• public static func speedLimit(_ update: GuidanceUpdate) -> SpeedLimit?: The posted speed limit for the current edge, when the route carries a maxspeed annotation at the current position. Render a speed-limit badge from .known(kmh:), and compare the fix's speed against it for an over-limit warning. nil with stock map data (no annotation); .unlimited/.unknown distinguish an explicit no-limit from an explicitly-unvalued annotation.
• public static func formatDistance(_ metres: Double) -> String: Format a distance in metres for guidance display: metres under 1 km (10 m steps under 100 m, 50 m steps above), kilometres with one decimal from 1 km.
• public static func summarise(_ update: GuidanceUpdate) -> String: One-line status suitable for a debug HUD or live activity.

MapMap

Enum · Sources/MapMapKit/MapMapKit.swift

public enum MapMap

Entry point for the MapMap iOS SDK.

The SDK is a thin, idiomatic Swift layer over the Rust navigation core (sn-nav-core, linked as a static library inside MapMapFFI.xcframework). The raw UniFFI bindings, the mapmap component and the ferrostar component, which is compiled into the same library, live in Generated/; everything else in this module is the supported surface:

• TerritoryStore, signed offline territory packages (install / verify / activate / update planning), actor-isolated.
• OfflineRouting, on-device Valhalla routing with ADR dangerous-goods enforcement merged into every request.
• AdrCompliance, pre-route and en-route ADR 8.6.4 tunnel checks.
• NavigationEngine, turn-by-turn guidance over a computed route, fed by any LocationProvider (CoreLocationProvider live, ReplayLocationProvider for QA corpora).

Initialisers and methods

• public static func ensureLoaded(): Eagerly verify that the bindings match the linked native core. Calling this is optional, the first native call performs the same UniFFI contract check lazily, but doing it at app start surfaces packaging problems (mismatched binding checksums, wrong framework slice) as an immediate, attributable crash instead of a mid-drive one.
• public static func defaultGuidanceConfig() -> GuidanceConfig: A GuidanceConfig with the core's documented defaults.
• public static func defaultAdrProfile() -> AdrProfile: An AdrProfile with the core's documented defaults: EU maximum authorised dimensions (Council Directive 96/53/EC), no dangerous goods.

MapMapKitError

Enum · Sources/MapMapKit/MapMapKit.swift

public enum MapMapKitError: Error, Equatable, LocalizedError

Errors raised by the Swift layer itself, before a call ever crosses into the Rust core (which throws NavCoreError).

OfflineRouting

Enum · Sources/MapMapKit/Routing/OfflineRouting.swift

public enum OfflineRouting

On-device route computation.

The Rust core builds the Valhalla request (merging ADR dangerous-goods and dimensional costing options, rejecting conflicts), the injected OfflineRouter executes it against local tiles, and the core parses the response into a RouteResult whose valhallaResponseJson feeds NavigationEngine.

Initialisers and methods

• public static func requireCompatibleCosting(costing: CostingModel, adr: AdrProfile?) throws: ADR profiles ride on Valhalla truck costing options; requesting any other costing model with an ADR profile is a contract violation the Rust core rejects. Checked here too so the failure is a fast, clearly-attributed MapMapKitError/incompatibleCosting(costing:) rather than a routing error after the FFI hop.
• public static func route(router: LocalRouter, waypoints: [RoutePoint], costing: CostingModel = .auto, adr: AdrProfile? = nil) async throws -> RouteResult: Compute a route on-device. Routing is CPU-bound native work; it runs on a detached utility task, never on the caller's executor. - Parameters: - router: the on-device engine, usually a ValhallaMobileRouter. - waypoints: at least two RoutePoints, in visit order. - costing: the Valhalla costing model; must be CostingModel/truck when adr is supplied. - adr: optional dangerous-goods/dimensional profile, when set, the request is built with the restrictions merged in, so illegal roads and tunnels are excluded before the route exists. - Throws: NavCoreError/Routing(message:) when the engine returns a Valhalla error body (e.g. no route, no tiles for the area).
• public static func buildRequest(waypoints: [RoutePoint], costing: CostingModel = .auto, adr: AdrProfile? = nil) throws -> String: Build the raw Valhalla request JSON without executing it, for callers that drive the engine themselves or log requests for audit.
• public static func parseResponse(_ responseJson: String) throws -> RouteResult: Parse a raw engine response into a RouteResult.

ProbeUploadOutcome

Enum · Sources/MapMapKit/Navigation/ProbeContribution.swift

public enum ProbeUploadOutcome: Sendable, Equatable

The outcome of one upload attempt, surfaced through URLSessionProbeUploader's result callback for observability and tests.

TerritoryKeys

Enum · Sources/MapMapKit/Territory/TerritoryKeys.swift

public enum TerritoryKeys

The public halves of the keys that sign MapMap's hosted territory packages, for pinning in an app. Both are ed25519 public keys as 64 hex characters, the form TerritoryStore takes.

Pin them at build time; never read either from the network. An app that runs its own factory or region signer passes its own keys instead.

ValhallaConfigWriter

Enum · Sources/MapMapKit/Routing/OfflineRouting.swift

public enum ValhallaConfigWriter

Writes the valhalla.json the on-device Valhalla engine needs.

The document is Valhalla's own complete default config (valhalla_build_config, MIT, https://github.com/valhalla/valhalla/blob/master/scripts/valhalla_build_config), bundled as Resources/valhalla-defaults.json, with the tile source and a mobile-sized cache set on top. The engine reads many keys (every service_limits section, loki, thor, meili) with no compiled-in fallback: a config carrying only mjolnir makes every route fail with "No such node (service_limits.isochrone.max_contours)", which is what this writer produced before (found on an Android device; the Android writer bundles the same file).

Initialisers and methods

• public static func configJSON(tileDir: URL, maxCacheBytes: Int64 = defaultMaxCacheBytes) throws -> String: Render the config document for a routing-tile directory (the territory's MapLayerKind/valhallaTiles layer).

Protocols (MapMapKit)

LocationProvider, OfflineRouter, ProbeUploader

LocationProvider

Protocol · Sources/MapMapKit/Navigation/LocationProvider.swift

public protocol LocationProvider: Sendable

A source of location fixes for NavigationEngine.

Implementations: CoreLocationProvider (Core Location) for live navigation, ReplayLocationProvider (a .drive.jsonl corpus) for QA and demos. Any stream of samples in ascending timestamp order qualifies.

The stream is cold: every access to locations starts a fresh sequence, and it is consumed once per navigation session.

OfflineRouter

Protocol · Sources/MapMapKit/Routing/OfflineRouting.swift

public protocol OfflineRouter: LocalRouter

An on-device routing engine.

This is the Rust core's LocalRouter callback interface with a Swift name: implementations execute a Valhalla turn-by-turn request JSON synchronously and return the raw response JSON (either a route response or a Valhalla error body, the core parses and classifies both).

The production implementation is ValhallaMobileRouter in the MapMapValhalla product (iOS only, it wraps the valhalla-mobile engine); tests inject fakes that return canned responses.

ProbeUploader

Protocol · Sources/MapMapKit/Navigation/ProbeContribution.swift

public protocol ProbeUploader: Sendable

Where a completed probe batch goes. Called off the guidance stream, so enqueue(_:) must not block and must never throw.

Initialisers and methods

• func enqueue(_ body: String): Hand one probe body, the string from ProbeCollector.finishJson, off to be POSTed to /v1/probe. Fire-and-forget.

Functions (MapMapKit)

contributingProbe

contributingProbe

Function · Sources/MapMapKit/Navigation/ProbeContribution.swift

public func contributingProbe(_ upstream: AsyncThrowingStream<NavigationState, Error>, config: ProbeConfig, uploader: ProbeUploader, routeRef: String? = nil, territory: String? = nil, vehicleClass: String? = nil, now: @escaping @Sendable () -> Int64 = { Int64(Date().timeIntervalSince1970 * 1000) }) -> AsyncThrowingStream<NavigationState, Error>

Accumulate an aggregate probe batch from a guidance stream and upload it when the trip ends. A transparent pass-through when config.enabled is false (the shipped default): no collector is constructed and nothing is uploaded, so leaving collection off costs nothing.

Wrap it around NavigationEngine/navigate(provider:)'s stream: swift let stream = contributingProbe( await engine.navigate(provider: provider), config: ProbeConfig(enabled: consentGranted), uploader: URLSessionProbeUploader(baseURL: "https://api.mapmap.ai", apiKey: key), routeRef: servedRouteToken, territory: "uk", vehicleClass: "truck_40t" ) for try await state in stream { render(state) }

Consent is the caller's responsibility: only pass enabled: true for a key whose operator has set probe_opt_in and, for a consumer app, with the user's opt-in consent. See docs/PROBE-SDK-INTEGRATION.md.

Only aggregates leave the device: the collector cannot emit a trajectory, and the first/last stretch of every trip is discarded on-device.

• Parameters:
  • routeRef: opaque served-route token so the server can resolve segment indices.
  • vehicleClass: a costing class only, never a registration, VIN or driver id.
  • now: injectable clock (Unix millis) for deterministic tests.

MapMap core bindings (generated)

Classes (MapMap core bindings (generated))

CancelToken, GuidanceSession, LayerFetcherImpl, LocalRouterImpl, ProbeCollector, TerritoryManager, TerritorySearch

CancelToken

Class · Sources/MapMapKit/Generated/mapmap.swift

open class CancelToken: CancelTokenProtocol, @unchecked Sendable

A cancellation handle for an in-flight territory install or update.

The install calls on TerritoryManager block the calling thread for as long as a multi-gigabyte package takes to download, unpack and verify. Create a token, pass it to one of the _cancellable variants running on a background thread, and call [CancelToken::cancel] from the UI thread when the user taps Cancel. The install polls it at safe points and returns [InstallOutcome::Cancelled] / [UpdateOutcome::Cancelled] with its staging directory removed: no partial package is left on disk, the previously installed version is untouched, and layers that had already been verified stay in the resumable cache for the next attempt. Cancelling after the call has returned changes nothing.

The token cannot interrupt a LayerFetcher blocked in a transfer: give the fetcher the same token and have it poll [CancelToken::is_cancelled] between chunks (or abort its request when the app cancels). Whatever the fetcher then returns, the install reports Cancelled, not a transport error.

Initialisers and methods

• public convenience init(): A fresh, uncancelled token.
• open func cancel(): Request cancellation. Idempotent and safe from any thread.
• open func isCancelled() -> Bool: Whether [Self::cancel] has been called.

GuidanceSession

Class · Sources/MapMapKit/Generated/mapmap.swift

open class GuidanceSession: GuidanceSessionProtocol, @unchecked Sendable

A turn-by-turn guidance session (see [crate::guidance]).

Thread-safe: the mutable Ferrostar navigation state is guarded by a mutex, matching UniFFI's shared-object concurrency model.

Initialisers and methods

• public convenience init(routeResponseJson: String, config: GuidanceConfig) throws: Create a session from a Valhalla route response JSON (as returned by route_offline in valhalla_response_json).
• open func advanceToNextStep() throws -> GuidanceUpdate: Manually advance to the next step (e.g. in a tunnel with no GNSS).
• open func totalSteps() -> UInt32: Number of steps in the route, including the arrival step.
• open func updateLocation(lat: Double, lon: Double, timestampMs: Int64, speedMps: Double?, courseDeg: Double?, horizontalAccuracyM: Double?) throws -> GuidanceUpdate: Feed a location fix; returns the updated guidance state. horizontal_accuracy_m defaults to 0.0 (trusted exactly) when absent; pass the platform's reported accuracy when available so step advance and deviation gating behave correctly.

LayerFetcherImpl

Class · Sources/MapMapKit/Generated/mapmap.swift

open class LayerFetcherImpl: LayerFetcher, @unchecked Sendable

The platform's download transport for over-the-air territory updates, exported as a UniFFI callback interface like [crate::routing::LocalRouter]: the core decides what to fetch and cryptographically verifies everything; Kotlin/Swift decide how bytes move (OkHttp, URLSession, an air-gapped mirror, …).

Initialisers and methods

• open func fetch(relPath: String, expectedBlake3: String, destPath: String) throws: Download the channel-relative rel_path (e.g. territories/uk/2.0.0/layers/<addr>/valhalla.tar.zst) to the local file dest_path. expected_blake3 is advisory (empty for signed metadata files); the core re-verifies all content itself.

LocalRouterImpl

Class · Sources/MapMapKit/Generated/mapmap.swift

open class LocalRouterImpl: LocalRouter, @unchecked Sendable

The injection point for the platform's on-device Valhalla binding.

valhalla-mobile (https://github.com/Rallista/valhalla-mobile) exposes a route(request_json) -> response_json actor on both Android and iOS; Kotlin/Swift implement this interface with that actor and pass it to [crate::ffi::route_offline]. Exported as a UniFFI callback interface (with_foreign) so the implementation lives in foreign code.

Initialisers and methods

• open func route(requestJson: String) -> String: Execute a Valhalla turn-by-turn request and return the raw response JSON (either a route response or a Valhalla error body).

ProbeCollector

Class · Sources/MapMapKit/Generated/mapmap.swift

open class ProbeCollector: ProbeCollectorProtocol, @unchecked Sendable

On-device probe collector. Feed it every guidance update with the fix's position, speed and timestamp; call finish at arrival or trip abandonment to get the ProbeBatch to upload.

Interior mutability (a Mutex) lets the FFI methods take &self, matching the [crate::guidance::GuidanceSession] object shape.

Initialisers and methods

• public convenience init(config: ProbeConfig): Create a collector with the given configuration.
• open func finish(arrived: Bool, timestampMs: Int64) -> ProbeBatch: Close the trip and return the batch to upload. arrived distinguishes a completed trip from an abandoned one (both apply end suppression).
• open func finishJson(arrived: Bool, timestampMs: Int64) -> String?: Close the trip and return the exact JSON body to POST /v1/probe, or None when the batch carries nothing worth uploading. This is the single canonical serialiser for the probe wire format, platform code should upload this verbatim rather than re-encoding the record, so the wire form can never drift from what the gateway ingests.
• open func observe(update: GuidanceUpdate, fixLat: Double, fixLon: Double, speedMps: Double?, timestampMs: Int64): Feed one guidance update and its fix. speed_mps is the device's reported ground speed when available (preferred); pass None to let the collector estimate it from successive positions.
• open func setRouteRef(routeRef: String): Set the opaque served-route token so the server can resolve segments.
• open func setTerritory(territory: String): Set the territory id stamped into the batch.
• open func setVehicleClass(vehicleClass: String): Set the vehicle costing class stamped into the batch (a class only, never a vehicle or driver identifier).

TerritoryManager

Class · Sources/MapMapKit/Generated/mapmap.swift

open class TerritoryManager: TerritoryManagerProtocol, @unchecked Sendable

Manages signed offline territory packages (see [crate::territory]).

Initialisers and methods

• public convenience init(rootDir: String, verifyingKeyHex: String) throws: Open a manager rooted at root_dir, trusting packages signed by the ed25519 public key given as 64 hex characters (the factory signing key's public half, [sn_package::VerifyingKey::to_hex]).
• public static func withRegionKey(rootDir: String, verifyingKeyHex: String, regionKeyHex: String) throws -> TerritoryManager: [Self::new], also trusting custom regions (region-… ids, cut by POST /v1/jobs/territory) signed by region_key_hex, the public half of the gateway's region signing key. The keys are partitioned by id: the region key verifies region- ids only and the factory key everything else. Pin both in the app; never read either from the network.
• open func active() throws -> String?: The active territory id, if one is set and still installed.
• open func applyUpdate(territoryId: String, newManifestJson: String, newManifestSigBase64: String, fetcher: LayerFetcher) throws -> UpdateResult: Apply a differential update: stage, fetch only the changed layers through fetcher, verify everything and swap atomically. Any failure leaves the installed territory untouched; the active flag is preserved. Blocks until done and cannot be interrupted; see [Self::apply_update_cancellable].
• open func applyUpdateCancellable(territoryId: String, newManifestJson: String, newManifestSigBase64: String, fetcher: LayerFetcher, cancel: CancelToken) throws -> UpdateOutcome: [Self::apply_update] with a CancelToken. Polled before every layer download, between archive entries while unpacking, before each hash pass and before promotion. A tripped token yields [UpdateOutcome::Cancelled]: the installed version is untouched, staging is removed, and layers that had already been fetched and verified stay in the resumable cache, so calling again with the same manifest re-fetches only what is missing. Give fetcher the same token so it can stop an in-flight transfer (the token cannot interrupt foreign code on its own); whatever the fetcher then returns, a tripped token reports Cancelled rather than a transport error.
• open func cachedLayerBytes() throws -> UInt64: Bytes parked in the resumable layer cache: downloads a failed install already paid for, which a retry will not pay for again. Surface this next to a "resume" affordance and in storage settings.
• open func checkForUpdate(territoryId: String, indexJson: String, indexSigBase64: String, fetcher: LayerFetcher) throws -> AvailableUpdate?: Check the signed channel index for an update to an installed territory. index_json must be the exact bytes served as index.json and index_sig_base64 the content of index.json.sig; the remote manifest is fetched and verified through fetcher. Returns None when the device is already on the channel's latest version (or the channel does not list the territory).
• open func clearLayerCache() throws: Discard every parked layer. The bytes are lost and a later install re-downloads (and on a metered channel re-pays for) them, so offer this only as a deliberate "free up space" action.
• open func installDir(packageDir: String) throws -> TerritoryInfo: Install an unpacked package directory. Blocks until done and cannot be interrupted; see [Self::install_dir_cancellable].
• open func installDirCancellable(packageDir: String, cancel: CancelToken) throws -> InstallOutcome: [Self::install_dir] with a CancelToken. Polled between copied files, before verification and before promotion.
• open func installDirPartial(packageDir: String, omit: [MapLayerKind], cancel: CancelToken) throws -> InstallOutcome: Install an unpacked package directory, holding only the layers this app can use: omit names the kinds to leave out (e.g. Pmtiles and Extra("style") for an app with no map view). The install records what it left out, and every later verification requires those layers to be absent rather than exempting them from hashing, so the record cannot be forged into admitting tampered bytes. Asking for an omitted layer answers [NavCoreError::LayerNotInstalled], which is not an error state: it is "you chose not to download this". The selection is sticky: updates carry it forward, so an app that skipped the render layers never downloads them on an update either.
• open func installFromChannel(territoryId: String, indexJson: String, indexSigBase64: String, omit: [MapLayerKind], fetcher: LayerFetcher, cancel: CancelToken) throws -> ChannelInstallOutcome: Install a territory from the channel, downloading only the layers this app can use. The first-install counterpart of [Self::apply_update], and the only path on which omitting layers saves bandwidth: a layer in omit is never requested, so it is never metered and never stored. index_json / index_sig_base64 are the exact served bytes of index.json and index.json.sig; the channel's latest version of the territory is installed. Nothing is trusted but the pinned key: the index signature, the manifest signature and every blob's BLAKE3 are checked, and the assembled directory goes through the same full verification pass as any other install before it is promoted. Interrupted installs resume: verified layers stay parked in the layer cache. Calling it again for a territory that is already installed is how a selection is widened later. Layers already on the device at the same content hash are linked, not re-downloaded, so adding the map to a router-only install costs the map alone.
• open func installSnpkg(archivePath: String) throws -> TerritoryInfo: Install a packed .snpkg archive (verify-then-promote; rejected packages leave no trace). Blocks until done and cannot be interrupted; see [Self::install_snpkg_cancellable].
• open func installSnpkgCancellable(archivePath: String, cancel: CancelToken) throws -> InstallOutcome: [Self::install_snpkg] with a CancelToken. Polled between archive entries, before verification and before promotion; a tripped token yields [InstallOutcome::Cancelled] with staging removed and nothing installed.
• open func installSnpkgPartial(archivePath: String, omit: [MapLayerKind], cancel: CancelToken) throws -> InstallOutcome: [Self::install_dir_partial] from a packed .snpkg archive. The archive carries every layer, so this saves storage, not bandwidth: the omitted layers are unpacked and then dropped before verification. For the bandwidth saving use [Self::install_from_channel], which never fetches a blob it does not want.
• open func layerPath(territoryId: String, kind: MapLayerKind) throws -> String: Absolute path of a layer inside an installed territory (e.g. the Valhalla tile tree for valhalla-mobile, the PMTiles file for MapLibre).
• open func list() throws -> [TerritoryInfo]: List installed territories in territory-id order.
• open func openSearch(territoryId: String) throws -> TerritorySearch: Open the installed territory's bundled geocode index for on-device search. The returned TerritorySearch holds the index open (mmap-backed), create it once per territory and reuse it across queries.
• open func planUpdate(newManifestJson: String) throws -> UpdatePlan: Plan a differential update from the installed manifest to new_manifest_json (a signed manifest's JSON body, as served by the update channel).
• open func remove(territoryId: String) throws: Remove an installed territory (clears the active marker if needed).
• open func setActive(territoryId: String) throws: Mark a territory as active (persisted atomically).
• open func territoryStyle(territoryId: String, theme: StyleTheme) throws -> String: A complete MapLibre style JSON for an installed territory with local (offline) references, mirroring the web SDK's buildStyle(). Load it straight into MapLibre, the territory tile source points at the installed PMTiles layer via a pmtiles://<absolute path> URL, so the map renders with radios off. Packages without a baked style layer get the default MapMap theme compiled on the fly over the package's PMTiles layer. The glyphs endpoint stays hosted (MapLibre caches fetched glyph ranges; no offline glyph bundle ships in packages today).
• open func verifyTerritory(territoryId: String) throws -> TerritoryInfo: Re-verify an installed territory from disk: the manifest signature, the BLAKE3 of every layer this install holds, and the absence of every layer it recorded as omitted. The ordinary calls do not re-hash gigabytes; this is the on-demand integrity check for after a restore or a crash. A failure arrives as [NavCoreError::Verification] and means the install must be repaired or reinstalled, not retried.

TerritorySearch

Class · Sources/MapMapKit/Generated/mapmap.swift

open class TerritorySearch: TerritorySearchProtocol, @unchecked Sendable

On-device search over an installed territory's bundled geocode index (see [TerritoryManager::open_search]). Fully offline; queries are synchronous and mmap-backed, call from a background thread/dispatcher like any other disk-bound SDK call.

Initialisers and methods

• open func reverse(lat: Double, lon: Double, limit: UInt32) throws -> [Place]: Reverse geocode: the nearest indexed places to a coordinate, nearest first.
• open func search(query: String, near: RoutePoint?, limit: UInt32) throws -> [Place]: Free-text search (addresses, streets, places, POIs, UK postcodes; prefix-tokenised, so it works for search-as-you-type). near biases ranking towards the given point and fills each result's distance_m; limit caps the number of hits.

Structs (MapMap core bindings (generated))

AdrProfile, AvailableUpdate, BannerLine, ChangedLayer, ChannelInstallResult, FasterRouteCandidate, FasterRouteConfig, FasterRouteRecommendation, GuidanceConfig, LaneGuidance, OdRecord, Place, ProbeBatch, ProbeConfig, RerouteAnchor, RerouteConfig, RerouteDecision, RerouteWaypoint, RouteManeuver, RoutePoint, RouteResult, RouteSummary, SegmentAggregate, SnappedFix, SpokenPrompt, TerritoryInfo, UpdatePlan, UpdateResult, VisualBanner

AdrProfile

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct AdrProfile: Equatable, Hashable

Vehicle profile for ADR and dimensional enforcement, mirroring [sn_adr::AdrVehicleProfile]. Defaults are the EU maximum authorised dimensions (Council Directive 96/53/EC) with no dangerous goods.

Initialisers and methods

• public init(heightM: Double = Double(4.0), widthM: Double = Double(2.55), lengthM: Double = Double(16.5), grossWeightT: Double = Double(40.0), axleLoadT: Double? = nil, axleCount: UInt32? = nil, hazmat: Bool = false, tunnelCode: AdrTunnelCode? = nil)

AvailableUpdate

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct AvailableUpdate: Equatable, Hashable

An update the channel offers for an installed territory.

Initialisers and methods

• public init(version: String, changedLayers: [ChangedLayer], installedBytes: UInt64, manifestJson: String, manifestSig: String)

BannerLine

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct BannerLine: Equatable, Hashable

One line of a visual banner (primary/secondary/sub).

Initialisers and methods

• public init(text: String, maneuverType: String?, maneuverModifier: String?, roundaboutExitDegrees: UInt16?, exitNumbers: [String], lanes: [LaneGuidance])

ChangedLayer

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct ChangedLayer: Equatable, Hashable

One layer that a territory update must download.

Initialisers and methods

• public init(kind: String, path: String, bytes: UInt64)

ChannelInstallResult

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct ChannelInstallResult: Equatable, Hashable

What [TerritoryManager::install_from_channel] did.

Initialisers and methods

• public init(territory: TerritoryInfo, layersFetched: UInt32, layersReused: UInt32, bytesDownloaded: UInt64)

FasterRouteCandidate

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct FasterRouteCandidate: Equatable, Hashable

One candidate route for the remaining journey, summarised from the router's response (a primary route or an alternate).

Initialisers and methods

• public init(id: String?, durationS: Double)

FasterRouteConfig

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct FasterRouteConfig: Equatable, Hashable

Faster-route evaluator configuration, flattened for FFI like [crate::reroute::RerouteConfig].

Initialisers and methods

• public init(checkIntervalS: Double = Double(120.0), minSavingS: UInt32 = UInt32(180), minSavingFrac: Double = Double(0.08), dismissSuppressS: Double = Double(600.0), maneuverBlackoutS: Double = Double(60.0), enabled: Bool = true)

FasterRouteRecommendation

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct FasterRouteRecommendation: Equatable, Hashable

A recommendation to switch to a faster candidate route.

Initialisers and methods

• public init(savesS: UInt32, candidateIdx: UInt32)

GuidanceConfig

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct GuidanceConfig: Equatable, Hashable

Guidance behaviour configuration, flattened for FFI.

Maps onto Ferrostar's NavigationControllerConfig: a distance-to-end-of-step advance condition, a static-threshold route deviation tracker and course snapping.

Initialisers and methods

• public init(stepAdvanceDistanceM: UInt16 = UInt16(20), minimumHorizontalAccuracyM: UInt16 = UInt16(25), routeDeviationThresholdM: Double = Double(25.0), snapCourseToRoute: Bool = true, waypointAdvanceRangeM: Double = Double(100.0))

LaneGuidance

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct LaneGuidance: Equatable, Hashable

One lane at the upcoming maneuver, for lane-diagram UIs.

Initialisers and methods

• public init(directions: [String], active: Bool, activeDirection: String?)

OdRecord

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct OdRecord: Equatable, Hashable

Coarse origin/destination for a trip. Both cells are geohashes of suppressed (mid-trip) positions, so they are already [ProbeConfig::trip_end_suppression_m] away from the true ends.

Initialisers and methods

• public init(originCell: String, destCell: String, departBucket: String)

Place

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct Place: Equatable, Hashable

One on-device search result: the matched document's display and context fields plus its position.

Initialisers and methods

• public init(id: String, kind: PlaceKind, name: String, housenumber: String?, street: String?, locality: String?, region: String?, postcode: String?, countryCode: String, lat: Double, lon: Double, categories: [String], importance: Float, distanceM: Double?)

ProbeBatch

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct ProbeBatch: Equatable, Hashable

A completed trip's aggregates, ready for the platform layer to POST to the probe ingest endpoint. Contains no trajectory.

Initialisers and methods

• public init(probeFormat: UInt32, territory: String?, vehicleClass: String?, routeRef: String?, segments: [SegmentAggregate], events: [ProbeEvent], od: OdRecord?)

ProbeConfig

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct ProbeConfig: Equatable, Hashable

Probe collector configuration, flattened for FFI like [crate::guidance::GuidanceConfig].

Collection is off by default: enabled must be set explicitly (and, in deployment, gated on the fleet customer's opt-in). Everything a batch contains follows from these knobs.

Initialisers and methods

• public init(enabled: Bool = false, tripEndSuppressionM: Double = Double(500.0), minSegmentObservations: UInt32 = UInt32(1), timeBucketMinutes: UInt32 = UInt32(5), odCellPrecision: UInt8 = UInt8(5), collectOd: Bool = true)

RerouteAnchor

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct RerouteAnchor: Equatable, Hashable

The point and course a recalculated route should depart from.

Initialisers and methods

• public init(lat: Double, lon: Double, courseDeg: Double?)

RerouteConfig

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct RerouteConfig: Equatable, Hashable

Reroute controller configuration, flattened for FFI like [crate::guidance::GuidanceConfig].

Both the count gate and the duration gate must pass for a reroute to be confirmed: a burst of fixes arriving in a fraction of a second should not out-vote the duration requirement, and a slow trickle of fixes should not out-vote the count requirement.

Initialisers and methods

• public init(minConsecutiveOffrouteFixes: UInt32 = UInt32(3), minOffrouteDurationS: Double = Double(5.0), minIntervalBetweenReroutesS: Double = Double(10.0), enabled: Bool = true)

RerouteDecision

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct RerouteDecision: Equatable, Hashable

A confirmed reroute: where to route from, where to, and why.

Initialisers and methods

• public init(reason: RerouteReason, anchor: RerouteAnchor, waypointsRemaining: [RerouteWaypoint])

RerouteWaypoint

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct RerouteWaypoint: Equatable, Hashable

One onward waypoint of the active route.

Initialisers and methods

• public init(lat: Double, lon: Double, isBreak: Bool)

RouteManeuver

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct RouteManeuver: Equatable, Hashable

One maneuver of the primary route, in SI units with shape indices into [RouteResult::geometry]. Parsed once by the core so integrators never re-parse the raw Valhalla JSON themselves.

Initialisers and methods

• public init(instruction: String, maneuverType: UInt32, verbalPreTransitionInstruction: String?, verbalPostTransitionInstruction: String?, streetNames: [String], distanceM: Double, durationS: Double, beginShapeIndex: UInt32, endShapeIndex: UInt32, roundaboutExitCount: UInt32?)

RoutePoint

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct RoutePoint: Equatable, Hashable

A route waypoint.

Initialisers and methods

• public init(lat: Double, lon: Double)

RouteResult

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct RouteResult: Equatable, Hashable

Result of an offline route computation.

Initialisers and methods

• public init(summary: RouteSummary, geometry: [RoutePoint] = [], maneuvers: [RouteManeuver] = [], valhallaResponseJson: String, osrmResponseJson: String)

RouteSummary

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct RouteSummary: Equatable, Hashable

SI summary of a parsed route.

Initialisers and methods

• public init(distanceM: Double, durationS: Double, hasToll: Bool, hasHighway: Bool, hasFerry: Bool)

SegmentAggregate

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct SegmentAggregate: Equatable, Hashable

One aggregated road segment: statistics for a step_index within the served route, in one day-of-week × time-of-day bucket.

Initialisers and methods

• public init(stepIndex: UInt32, todBucket: String, observations: UInt32, meanSpeedKmh: Double, p85SpeedKmh: Double, stoppedS: Double, limitDeltaKmh: Double?)

SnappedFix

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct SnappedFix: Equatable, Hashable

The route-snapped position for the current update.

This is Ferrostar's snapped_user_location: the raw fix projected onto the route line, with the course snapped to the route direction when [GuidanceConfig::snap_course_to_route] is on (the default). Drive follow-cameras (course-up / chase views) from this, never the raw fix, the raw GPS trace jitters and drifts off the carriageway.

Initialisers and methods

• public init(lat: Double, lon: Double, courseDeg: Double?)

SpokenPrompt

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct SpokenPrompt: Equatable, Hashable

The spoken prompt to synthesise for the upcoming maneuver.

Initialisers and methods

• public init(text: String, ssml: String?, triggerDistanceM: Double, utteranceId: String)

TerritoryInfo

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct TerritoryInfo: Equatable, Hashable

Summary of one installed territory.

Initialisers and methods

• public init(territoryId: String, displayName: String, version: String, dataTimestamp: String, west: Double, south: Double, east: Double, north: Double, totalBytes: UInt64, installedBytes: UInt64, omittedKinds: [MapLayerKind], path: String, active: Bool)

UpdatePlan

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct UpdatePlan: Equatable, Hashable

A differential update plan.

Initialisers and methods

• public init(changed: [ChangedLayer], installedBytes: UInt64)

UpdateResult

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct UpdateResult: Equatable, Hashable

What [TerritoryManager::apply_update] did.

Initialisers and methods

• public init(territory: TerritoryInfo, previousVersion: String, layersFetched: UInt32, layersReused: UInt32, bytesDownloaded: UInt64)

VisualBanner

Struct · Sources/MapMapKit/Generated/mapmap.swift

public struct VisualBanner: Equatable, Hashable

The visual banner to display for the upcoming maneuver.

Initialisers and methods

• public init(primary: BannerLine, secondary: BannerLine?, sub: BannerLine?, triggerDistanceM: Double, drivingSide: String? = nil, roadRef: String? = nil, country: String? = nil, subdivision: String? = nil, roadClass: String? = nil)

Enums (MapMap core bindings (generated))

AdrDecision, AdrTunnelCategory, AdrTunnelCode, ChannelInstallOutcome, CostingModel, FetchError, GuidanceUpdate, InstallOutcome, InstructionSeverity, MapLayerKind, NavCoreError, PlaceKind, ProbeEvent, RerouteReason, RerouteState, SpeedLimit, StyleTheme, UpdateOutcome

AdrDecision

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum AdrDecision: Equatable, Hashable

Outcome of a tunnel-entry check, mirroring [sn_adr::Decision].

AdrTunnelCategory

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum AdrTunnelCategory: Equatable, Hashable

ADR tunnel category A–E (ascending restrictiveness), mirroring [sn_adr::TunnelCategory].

AdrTunnelCode

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum AdrTunnelCode: Equatable, Hashable

ADR 8.6.4 tunnel restriction code of a load, mirroring [sn_adr::TunnelRestrictionCode]. NoCode is ADR's (, ): explicitly unrestricted.

ChannelInstallOutcome

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum ChannelInstallOutcome: Equatable, Hashable

How a channel install ended.

CostingModel

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum CostingModel: Equatable, Hashable

Valhalla costing model, mirroring [sn_valhalla::valhalla::Costing].

FetchError

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum FetchError: Swift.Error, Equatable, Hashable, Foundation.LocalizedError

A transport failure thrown by a foreign LayerFetcher implementation.

GuidanceUpdate

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum GuidanceUpdate: Equatable, Hashable

The guidance state reported after each location update, flattened for FFI from Ferrostar's TripState.

The Navigating variant is deliberately larger than the others: it is the steady-state payload and the FFI shape (UniFFI enums cannot box), and one allocation per location fix is irrelevant next to the fix cadence.

InstallOutcome

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum InstallOutcome: Equatable, Hashable

How a cancellable install ended.

InstructionSeverity

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum InstructionSeverity: Equatable, Hashable

How urgently a guidance update should be surfaced to the driver.

Voice layers map this to prosody (pitch/rate) and earcons; visual layers to banner styling. Ordered: Info < Warning < Critical.

Derivation (single source of truth for every SDK):

• Critical, restriction prohibitions: an ADR tunnel prohibition ([InstructionSeverity::for_adr_decision] on a Blocked decision, the hook platform layers use when check_tunnel fires off-route) and manoeuvres crossing a gate (a physical barrier the vehicle must not run).
• Warning, approaching a restriction or interruption of the drive: toll booths and ferry boardings/landings.
• Info, every normal manoeuvre.

Off-route updates carry no instruction; platform voice layers treat [GuidanceUpdate::OffRoute] itself as Warning.

MapLayerKind

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum MapLayerKind: Equatable, Hashable

Map layer kind, mirroring [sn_package::LayerKind].

NavCoreError

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum NavCoreError: Swift.Error, Equatable, Hashable, Foundation.LocalizedError

The flat error type crossing the FFI boundary.

Rich typed errors live on the Rust side (TerritoryError, RoutingError, GuidanceError); foreign code gets a stable category plus a human-readable message.

PlaceKind

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum PlaceKind: Equatable, Hashable

The kind of entity a Place describes, mirroring [sn_geocode::DocKind].

ProbeEvent

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum ProbeEvent: Equatable, Hashable

A coarse, time-bucketed event within a trip.

RerouteReason

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum RerouteReason: Equatable, Hashable

Why a reroute was requested.

RerouteState

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum RerouteState: Equatable, Hashable

The controller's state after the most recent update, for UI and telemetry.

SpeedLimit

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum SpeedLimit: Equatable, Hashable

The posted speed limit for the current edge, for a speed-limit badge and over-limit warnings.

This is surfaced from the OSRM annotation.maxspeed that Ferrostar threads through its navigation state (TripState::Navigating.annotation_json) at the current geometry index, in the Mapbox shape (https://docs.mapbox.com/api/navigation/directions/#route-leg-object). It appears only when the route actually carries speed-limit data: on-device that means the Valhalla graph was built with OSM maxspeed (and admin data for implicit limits) and the engine emitted per-maneuver limits, which the translator forwarded (see [sn_valhalla::valhalla::SpeedLimit]). With stock data there is no annotation and [GuidanceUpdate::Navigating] reports no limit at all, values are never invented.

StyleTheme

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum StyleTheme: Equatable, Hashable

Which packaged style variant [TerritoryManager::territory_style] returns, mirroring [crate::territory::StyleTheme] (and the web SDK's buildStyle({ theme }) names).

UpdateOutcome

Enum · Sources/MapMapKit/Generated/mapmap.swift

public enum UpdateOutcome: Equatable, Hashable

How a cancellable update ended.

Protocols (MapMap core bindings (generated))

CancelTokenProtocol, GuidanceSessionProtocol, LayerFetcher, LocalRouter, ProbeCollectorProtocol, TerritoryManagerProtocol, TerritorySearchProtocol

CancelTokenProtocol

Protocol · Sources/MapMapKit/Generated/mapmap.swift

public protocol CancelTokenProtocol: AnyObject, Sendable

A cancellation handle for an in-flight territory install or update.

The install calls on TerritoryManager block the calling thread for as long as a multi-gigabyte package takes to download, unpack and verify. Create a token, pass it to one of the _cancellable variants running on a background thread, and call [CancelToken::cancel] from the UI thread when the user taps Cancel. The install polls it at safe points and returns [InstallOutcome::Cancelled] / [UpdateOutcome::Cancelled] with its staging directory removed: no partial package is left on disk, the previously installed version is untouched, and layers that had already been verified stay in the resumable cache for the next attempt. Cancelling after the call has returned changes nothing.

The token cannot interrupt a LayerFetcher blocked in a transfer: give the fetcher the same token and have it poll [CancelToken::is_cancelled] between chunks (or abort its request when the app cancels). Whatever the fetcher then returns, the install reports Cancelled, not a transport error.

Initialisers and methods

• func cancel(): Request cancellation. Idempotent and safe from any thread.
• func isCancelled() -> Bool: Whether [Self::cancel] has been called.

GuidanceSessionProtocol

Protocol · Sources/MapMapKit/Generated/mapmap.swift

public protocol GuidanceSessionProtocol: AnyObject, Sendable

A turn-by-turn guidance session (see [crate::guidance]).

Thread-safe: the mutable Ferrostar navigation state is guarded by a mutex, matching UniFFI's shared-object concurrency model.

Initialisers and methods

• func advanceToNextStep() throws -> GuidanceUpdate: Manually advance to the next step (e.g. in a tunnel with no GNSS).
• func totalSteps() -> UInt32: Number of steps in the route, including the arrival step.
• func updateLocation(lat: Double, lon: Double, timestampMs: Int64, speedMps: Double?, courseDeg: Double?, horizontalAccuracyM: Double?) throws -> GuidanceUpdate: Feed a location fix; returns the updated guidance state. horizontal_accuracy_m defaults to 0.0 (trusted exactly) when absent; pass the platform's reported accuracy when available so step advance and deviation gating behave correctly.

LayerFetcher

Protocol · Sources/MapMapKit/Generated/mapmap.swift

public protocol LayerFetcher: AnyObject, Sendable

The platform's download transport for over-the-air territory updates, exported as a UniFFI callback interface like [crate::routing::LocalRouter]: the core decides what to fetch and cryptographically verifies everything; Kotlin/Swift decide how bytes move (OkHttp, URLSession, an air-gapped mirror, …).

Initialisers and methods

• func fetch(relPath: String, expectedBlake3: String, destPath: String) throws: Download the channel-relative rel_path (e.g. territories/uk/2.0.0/layers/<addr>/valhalla.tar.zst) to the local file dest_path. expected_blake3 is advisory (empty for signed metadata files); the core re-verifies all content itself.

LocalRouter

Protocol · Sources/MapMapKit/Generated/mapmap.swift

public protocol LocalRouter: AnyObject, Sendable

The injection point for the platform's on-device Valhalla binding.

valhalla-mobile (https://github.com/Rallista/valhalla-mobile) exposes a route(request_json) -> response_json actor on both Android and iOS; Kotlin/Swift implement this interface with that actor and pass it to [crate::ffi::route_offline]. Exported as a UniFFI callback interface (with_foreign) so the implementation lives in foreign code.

Initialisers and methods

• func route(requestJson: String) -> String: Execute a Valhalla turn-by-turn request and return the raw response JSON (either a route response or a Valhalla error body).

ProbeCollectorProtocol

Protocol · Sources/MapMapKit/Generated/mapmap.swift

public protocol ProbeCollectorProtocol: AnyObject, Sendable

On-device probe collector. Feed it every guidance update with the fix's position, speed and timestamp; call finish at arrival or trip abandonment to get the ProbeBatch to upload.

Interior mutability (a Mutex) lets the FFI methods take &self, matching the [crate::guidance::GuidanceSession] object shape.

Initialisers and methods

• func finish(arrived: Bool, timestampMs: Int64) -> ProbeBatch: Close the trip and return the batch to upload. arrived distinguishes a completed trip from an abandoned one (both apply end suppression).
• func finishJson(arrived: Bool, timestampMs: Int64) -> String?: Close the trip and return the exact JSON body to POST /v1/probe, or None when the batch carries nothing worth uploading. This is the single canonical serialiser for the probe wire format, platform code should upload this verbatim rather than re-encoding the record, so the wire form can never drift from what the gateway ingests.
• func observe(update: GuidanceUpdate, fixLat: Double, fixLon: Double, speedMps: Double?, timestampMs: Int64): Feed one guidance update and its fix. speed_mps is the device's reported ground speed when available (preferred); pass None to let the collector estimate it from successive positions.
• func setRouteRef(routeRef: String): Set the opaque served-route token so the server can resolve segments.
• func setTerritory(territory: String): Set the territory id stamped into the batch.
• func setVehicleClass(vehicleClass: String): Set the vehicle costing class stamped into the batch (a class only, never a vehicle or driver identifier).

TerritoryManagerProtocol

Protocol · Sources/MapMapKit/Generated/mapmap.swift

public protocol TerritoryManagerProtocol: AnyObject, Sendable

Manages signed offline territory packages (see [crate::territory]).

Initialisers and methods

• func active() throws -> String?: The active territory id, if one is set and still installed.
• func applyUpdate(territoryId: String, newManifestJson: String, newManifestSigBase64: String, fetcher: LayerFetcher) throws -> UpdateResult: Apply a differential update: stage, fetch only the changed layers through fetcher, verify everything and swap atomically. Any failure leaves the installed territory untouched; the active flag is preserved. Blocks until done and cannot be interrupted; see [Self::apply_update_cancellable].
• func applyUpdateCancellable(territoryId: String, newManifestJson: String, newManifestSigBase64: String, fetcher: LayerFetcher, cancel: CancelToken) throws -> UpdateOutcome: [Self::apply_update] with a CancelToken. Polled before every layer download, between archive entries while unpacking, before each hash pass and before promotion. A tripped token yields [UpdateOutcome::Cancelled]: the installed version is untouched, staging is removed, and layers that had already been fetched and verified stay in the resumable cache, so calling again with the same manifest re-fetches only what is missing. Give fetcher the same token so it can stop an in-flight transfer (the token cannot interrupt foreign code on its own); whatever the fetcher then returns, a tripped token reports Cancelled rather than a transport error.
• func cachedLayerBytes() throws -> UInt64: Bytes parked in the resumable layer cache: downloads a failed install already paid for, which a retry will not pay for again. Surface this next to a "resume" affordance and in storage settings.
• func checkForUpdate(territoryId: String, indexJson: String, indexSigBase64: String, fetcher: LayerFetcher) throws -> AvailableUpdate?: Check the signed channel index for an update to an installed territory. index_json must be the exact bytes served as index.json and index_sig_base64 the content of index.json.sig; the remote manifest is fetched and verified through fetcher. Returns None when the device is already on the channel's latest version (or the channel does not list the territory).
• func clearLayerCache() throws: Discard every parked layer. The bytes are lost and a later install re-downloads (and on a metered channel re-pays for) them, so offer this only as a deliberate "free up space" action.
• func installDir(packageDir: String) throws -> TerritoryInfo: Install an unpacked package directory. Blocks until done and cannot be interrupted; see [Self::install_dir_cancellable].
• func installDirCancellable(packageDir: String, cancel: CancelToken) throws -> InstallOutcome: [Self::install_dir] with a CancelToken. Polled between copied files, before verification and before promotion.
• func installDirPartial(packageDir: String, omit: [MapLayerKind], cancel: CancelToken) throws -> InstallOutcome: Install an unpacked package directory, holding only the layers this app can use: omit names the kinds to leave out (e.g. Pmtiles and Extra("style") for an app with no map view). The install records what it left out, and every later verification requires those layers to be absent rather than exempting them from hashing, so the record cannot be forged into admitting tampered bytes. Asking for an omitted layer answers [NavCoreError::LayerNotInstalled], which is not an error state: it is "you chose not to download this". The selection is sticky: updates carry it forward, so an app that skipped the render layers never downloads them on an update either.
• func installFromChannel(territoryId: String, indexJson: String, indexSigBase64: String, omit: [MapLayerKind], fetcher: LayerFetcher, cancel: CancelToken) throws -> ChannelInstallOutcome: Install a territory from the channel, downloading only the layers this app can use. The first-install counterpart of [Self::apply_update], and the only path on which omitting layers saves bandwidth: a layer in omit is never requested, so it is never metered and never stored. index_json / index_sig_base64 are the exact served bytes of index.json and index.json.sig; the channel's latest version of the territory is installed. Nothing is trusted but the pinned key: the index signature, the manifest signature and every blob's BLAKE3 are checked, and the assembled directory goes through the same full verification pass as any other install before it is promoted. Interrupted installs resume: verified layers stay parked in the layer cache. Calling it again for a territory that is already installed is how a selection is widened later. Layers already on the device at the same content hash are linked, not re-downloaded, so adding the map to a router-only install costs the map alone.
• func installSnpkg(archivePath: String) throws -> TerritoryInfo: Install a packed .snpkg archive (verify-then-promote; rejected packages leave no trace). Blocks until done and cannot be interrupted; see [Self::install_snpkg_cancellable].
• func installSnpkgCancellable(archivePath: String, cancel: CancelToken) throws -> InstallOutcome: [Self::install_snpkg] with a CancelToken. Polled between archive entries, before verification and before promotion; a tripped token yields [InstallOutcome::Cancelled] with staging removed and nothing installed.
• func installSnpkgPartial(archivePath: String, omit: [MapLayerKind], cancel: CancelToken) throws -> InstallOutcome: [Self::install_dir_partial] from a packed .snpkg archive. The archive carries every layer, so this saves storage, not bandwidth: the omitted layers are unpacked and then dropped before verification. For the bandwidth saving use [Self::install_from_channel], which never fetches a blob it does not want.
• func layerPath(territoryId: String, kind: MapLayerKind) throws -> String: Absolute path of a layer inside an installed territory (e.g. the Valhalla tile tree for valhalla-mobile, the PMTiles file for MapLibre).
• func list() throws -> [TerritoryInfo]: List installed territories in territory-id order.
• func openSearch(territoryId: String) throws -> TerritorySearch: Open the installed territory's bundled geocode index for on-device search. The returned TerritorySearch holds the index open (mmap-backed), create it once per territory and reuse it across queries.
• func planUpdate(newManifestJson: String) throws -> UpdatePlan: Plan a differential update from the installed manifest to new_manifest_json (a signed manifest's JSON body, as served by the update channel).
• func remove(territoryId: String) throws: Remove an installed territory (clears the active marker if needed).
• func setActive(territoryId: String) throws: Mark a territory as active (persisted atomically).
• func territoryStyle(territoryId: String, theme: StyleTheme) throws -> String: A complete MapLibre style JSON for an installed territory with local (offline) references, mirroring the web SDK's buildStyle(). Load it straight into MapLibre, the territory tile source points at the installed PMTiles layer via a pmtiles://<absolute path> URL, so the map renders with radios off. Packages without a baked style layer get the default MapMap theme compiled on the fly over the package's PMTiles layer. The glyphs endpoint stays hosted (MapLibre caches fetched glyph ranges; no offline glyph bundle ships in packages today).
• func verifyTerritory(territoryId: String) throws -> TerritoryInfo: Re-verify an installed territory from disk: the manifest signature, the BLAKE3 of every layer this install holds, and the absence of every layer it recorded as omitted. The ordinary calls do not re-hash gigabytes; this is the on-demand integrity check for after a restore or a crash. A failure arrives as [NavCoreError::Verification] and means the install must be repaired or reinstalled, not retried.

TerritorySearchProtocol

Protocol · Sources/MapMapKit/Generated/mapmap.swift

public protocol TerritorySearchProtocol: AnyObject, Sendable

On-device search over an installed territory's bundled geocode index (see [TerritoryManager::open_search]). Fully offline; queries are synchronous and mmap-backed, call from a background thread/dispatcher like any other disk-bound SDK call.

Initialisers and methods

• func reverse(lat: Double, lon: Double, limit: UInt32) throws -> [Place]: Reverse geocode: the nearest indexed places to a coordinate, nearest first.
• func search(query: String, near: RoutePoint?, limit: UInt32) throws -> [Place]: Free-text search (addresses, streets, places, POIs, UK postcodes; prefix-tokenised, so it works for search-as-you-type). near biases ranking towards the given point and fills each result's distance_m; limit caps the number of hits.

Functions (MapMap core bindings (generated))

buildOfflineRouteRequest, checkTunnel, forbiddenCategories, parseRouteResult, routeOffline, styleForNavigation, styleWithBuildings3d

buildOfflineRouteRequest

Function · Sources/MapMapKit/Generated/mapmap.swift

public func buildOfflineRouteRequest(locations: [RoutePoint], costing: CostingModel, adr: AdrProfile?) throws -> String

Build the Valhalla request JSON an on-device engine accepts, with ADR costing options merged (conflicts rejected). Useful when foreign code wants to drive the engine itself.

checkTunnel

Function · Sources/MapMapKit/Generated/mapmap.swift

public func checkTunnel(profile: AdrProfile, category: AdrTunnelCategory) -> AdrDecision

Decide whether the vehicle may pass through a tunnel of category (conservative ADR 8.6.4 reading; see [crate::adr::check_tunnel]).

forbiddenCategories

Function · Sources/MapMapKit/Generated/mapmap.swift

public func forbiddenCategories(profile: AdrProfile) -> [AdrTunnelCategory]

All tunnel categories the vehicle is forbidden from (ascending). Empty when unrestricted.

parseRouteResult

Function · Sources/MapMapKit/Generated/mapmap.swift

public func parseRouteResult(responseJson: String) throws -> RouteResult

Parse a raw on-device route response into a RouteResult, including the typed [RouteResult::geometry] and [RouteResult::maneuvers].

routeOffline

Function · Sources/MapMapKit/Generated/mapmap.swift

public func routeOffline(router: LocalRouter, locations: [RoutePoint], costing: CostingModel, adr: AdrProfile?) throws -> RouteResult

Full offline routing orchestration: build the request, run it through the injected LocalRouter (the platform's valhalla-mobile binding) and parse the response.

styleForNavigation

Function · Sources/MapMapKit/Generated/mapmap.swift

public func styleForNavigation(styleJson: String, keepBuildings3d: Bool = true) throws -> String

Prepares a style for a turn-by-turn navigation view. Call it on whatever style the app otherwise uses, right before loading the navigation map; it is where nav-view safeguards live.

By default (keep_buildings_3d = true) the style's 3D building state is left exactly as the app configured it: MapLibre Native's historical fill-extrusion memory blow-up (maplibre-native#4107) is fixed by the instancing rework (#4256; Android >= 13.2.0, iOS >= 6.26.1), and a navigation-loop soak (qa/expo-3d-soak, 17 Jul 2026) measured a bounded ~170 MB for city-wide 3D at nav zoom, flat, no growth.

Pass keep_buildings_3d = false to strip the building-3d layer, the pre-fix behaviour, when targeting MapLibre pins older than the fix or low-memory devices you have not measured.

styleWithBuildings3d

Function · Sources/MapMapKit/Generated/mapmap.swift

public func styleWithBuildings3d(styleJson: String, enabled: Bool) throws -> String

Toggle 3D building extrusions on a MapMap style.json document (a territory package's baked style or a hosted style body), returning the adjusted document to load into MapLibre. Idempotent; errors with [NavCoreError::InvalidArgument] on non-style input.

Safe on MapLibre Native releases carrying the fill-extrusion instancing fix (maplibre-native#4256, merged 2026-05-05: Android

= 13.2.0, iOS >= 6.26.1), the historical street-zoom memory blow-up (#4107, 900 MB+ at zoom 17) is fixed there. Measured 17 Jul 2026 on a Pixel-class device (qa/expo-3d-soak): city-wide extrusions at zoom 16.5/pitch 60 cost a bounded ~170 MB over an identical no-3D control, flat over the soak. On pins older than the fix, keep this off outside measured map-browsing views.

Ferrostar bindings (generated)

Classes (Ferrostar bindings (generated))

AndAdvanceConditions, DistanceEntryAndExitCondition, DistanceEntryAndSnappedExitCondition, DistanceFromStepCondition, DistanceToEndOfStepCondition, ManualStepCondition, NavigationCacheImpl, NavigationController, NavigationObserverImpl, NavigationRecorder, NavigationReplay, NavigationSession, NavigationSessionCache, Navigator, OrAdvanceConditions, RouteAdapter, RouteDeviationDetectorImpl, RouteRequestGeneratorImpl, RouteResponseParserImpl, StepAdvanceCondition

AndAdvanceConditions

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class AndAdvanceConditions: AndAdvanceConditionsProtocol, @unchecked Sendable

Advance if all of the conditions are met (AND).

DistanceEntryAndExitCondition

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class DistanceEntryAndExitCondition: DistanceEntryAndExitConditionProtocol, @unchecked Sendable

A stateful condition that requires the user to reach the end of the step then proceed past it to advance.

DistanceEntryAndSnappedExitCondition

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class DistanceEntryAndSnappedExitCondition: DistanceEntryAndSnappedExitConditionProtocol, @unchecked Sendable

A stateful condition that requires the user to reach the end of the step then proceed past it to advance.

This variant uses route snapping (snapping to the combined current+next step geometry) for the exit check, making it more robust for pedestrian/hiking navigation where users may walk on the opposite side of the street or wander around the optimal path. The route-snapped exit check prevents premature advancement while still allowing natural pedestrian movement patterns. The exit distance is measured from the current step to the route-snapped position.

DistanceFromStepCondition

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class DistanceFromStepCondition: DistanceFromStepConditionProtocol, @unchecked Sendable

Advances once the user is at least [Self::distance] meters from the current step's polyline.

This results in delayed advance, but is more robust to spurious / unwanted step changes in scenarios including self-intersecting routes (sudden jumps to the next step) and pauses at intersections (advancing too soon before the maneuver is complete).

NOTE! This may be less robust to things like short steps, out-and-backs, and U-turns, where this may eagerly exit a current step before the user has traversed it if the start of the step is within range of the end.

DistanceToEndOfStepCondition

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class DistanceToEndOfStepCondition: DistanceToEndOfStepConditionProtocol, @unchecked Sendable

Automatically advances when the user's location is close enough to the end of the step.

This results in an eager advance where the user will jump to the next step when the condition is met.

ManualStepCondition

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class ManualStepCondition: ManualStepConditionProtocol, @unchecked Sendable

Never advances to the next step automatically; requires calling NavigationController::advance_to_next_step.

You can use this to implement custom behaviors in external code.

NavigationCacheImpl

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class NavigationCacheImpl: NavigationCache, @unchecked Sendable

Initialisers and methods

• open func save(record: Data)
• open func load() -> Data?
• open func delete()

NavigationController

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class NavigationController: NavigationControllerProtocol, @unchecked Sendable

Manages the navigation lifecycle through a route, returning an updated state given inputs like user location.

Notes for implementing a new platform:

• A controller is bound to a single route; if you want recalculation, create a new instance.
• This is a pure type (no interior mutability), so a core function of your platform code is responsibly managing mutable state.

Initialisers and methods

• public convenience init(route: Route, config: NavigationControllerConfig): Create a navigation controller for a route and configuration.

NavigationObserverImpl

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class NavigationObserverImpl: NavigationObserver, @unchecked Sendable

Initialisers and methods

• open func onGetInitialState(state: NavState)
• open func onUserLocationUpdate(location: UserLocation, state: NavState)
• open func onAdvanceToNextStep(state: NavState)
• open func onRouteAvailable(route: Route)

NavigationRecorder

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class NavigationRecorder: NavigationRecorderProtocol, @unchecked Sendable

Initialisers and methods

• public convenience init(route: Route, config: NavigationControllerConfig)
• open func getEvents() -> [NavigationRecordingEvent]
• open func getRecordingJson() throws -> String
• open func onAdvanceToNextStep(state: NavState)
• open func onGetInitialState(state: NavState)
• open func onRouteAvailable(route: Route)
• open func onUserLocationUpdate(location: UserLocation, state: NavState)

NavigationReplay

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class NavigationReplay: NavigationReplayProtocol, @unchecked Sendable

A wrapper around NavigationRecording to facilitate replaying the event stream.

NavigationSession

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class NavigationSession: NavigationSessionProtocol, @unchecked Sendable

Initialisers and methods

• public convenience init(controller: Navigator, observers: [NavigationObserver])
• open func advanceToNextStep(state: NavState) -> NavState
• open func getInitialState(location: UserLocation) -> NavState
• open func route() -> Route
• open func updateUserLocation(location: UserLocation, state: NavState) -> NavState

NavigationSessionCache

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class NavigationSessionCache: NavigationSessionCacheProtocol, @unchecked Sendable

Initialisers and methods

• public convenience init(config: NavigationCachingConfig, cache: NavigationCache)
• open func canResume() -> Bool: Check if the navigation session can be resumed.
• open func load() -> NavigationSessionSnapshot?: Load the navigation session record from the cache if it exists and is not stale.
• open func onAdvanceToNextStep(state: NavState)
• open func onGetInitialState(state: NavState)
• open func onRouteAvailable(route: Route)
• open func onUserLocationUpdate(location: UserLocation, state: NavState)

Navigator

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class Navigator: NavigatorProtocol, @unchecked Sendable

Core interface for navigation functionalities.

This trait defines the essential operations for a navigation state manager. This lets us build additional layers (e.g. event logging) around NavigationController in a composable manner.

Initialisers and methods

• open func route() -> Route
• open func getInitialState(location: UserLocation) -> NavState
• open func advanceToNextStep(state: NavState) -> NavState
• open func updateUserLocation(location: UserLocation, state: NavState) -> NavState

OrAdvanceConditions

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class OrAdvanceConditions: OrAdvanceConditionsProtocol, @unchecked Sendable

Advance if any of the conditions are met (OR).

This is ideal for short circuit type advance conditions.

E.g. you may have:

1. A short circuit detecting if the user has exceeded a large distance from the current step.
2. A default advance behavior.

RouteAdapter

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class RouteAdapter: RouteAdapterProtocol, @unchecked Sendable

The route adapter bridges between the common core and a routing backend where interaction takes place over a generic request/response flow (typically over a network; local/offline routers do not use this object as the interaction patterns are different).

This is essentially the composite of the RouteRequestGenerator and RouteResponseParser traits, but it provides one further level of abstraction which is helpful to consumers. As there is no way to signal compatibility between request generators and response parsers, the RouteAdapter provides convenience constructors which take the guesswork out of it, while still leaving consumers free to implement one or both halves.

In the future, we may provide additional methods or conveniences, and this indirection leaves the design open to such changes without necessarily breaking source compatibility. One such possible extension would be the ability to fetch more detailed attributes in real time. This is supported by the Valhalla stack, among others.

Ideas welcome re: how to signal compatibility between request generators and response parsers. I don't think we can do this in the type system, since one of the reasons for the split design is modularity, including the possibility of user-provided implementations, and these will not always be of a "known" type to the Rust side.

Initialisers and methods

• public convenience init(requestGenerator: RouteRequestGenerator, responseParser: RouteResponseParser): Creates a route adapter from any request generator and response parser. This constructor offers unlimited flexibility, but if you're using a major routing vendor API, [RouteAdapter::from_well_known_route_provider] may be a more convenient interface.
• public static func fromWellKnownRouteProvider(wellKnownRouteProvider: WellKnownRouteProvider) throws -> RouteAdapter: Creates a route adapter from a well-known provider configuration.
• open func generateRequest(userLocation: UserLocation, waypoints: [Waypoint]) throws -> RouteRequest
• open func parseResponse(response: Data) throws -> [Route]

RouteDeviationDetectorImpl

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class RouteDeviationDetectorImpl: RouteDeviationDetector, @unchecked Sendable

A custom deviation detector (for extending the behavior of RouteDeviationTracking).

This allows for arbitrarily complex implementations when the provided ones are not enough. For example, detecting that the user is proceeding the wrong direction by keeping a ring buffer of recent locations, or perform local map matching.

Initialisers and methods

• open func checkRouteDeviation(route: Route, tripState: TripState) -> RouteDeviation: Determines whether the user is following the route correctly or not. NOTE: This function has a single responsibility. Side-effects like whether to recalculate a route are left to higher levels, and implementations should only be concerned with determining the facts. IMPORTANT: If you are short circuiting StepAdvanceCondition's to allow skipping steps, you must always fall back to checking the deviation from the full route line.

RouteRequestGeneratorImpl

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class RouteRequestGeneratorImpl: RouteRequestGenerator, @unchecked Sendable

A trait describing any object capable of generating RouteRequests.

The interface is intentionally generic. Every routing backend has its own set of parameters, including a "profile," max travel speed, units of speed and distance, and more. It is assumed that these properties will be set at construction time or otherwise configured before use, so that we can keep the public interface as generic as possible.

Implementations may be either in Rust (most popular engines should eventually have Rust glue code) or foreign code.

Initialisers and methods

• open func generateRequest(userLocation: UserLocation, waypoints: [Waypoint]) throws -> RouteRequest: Generates a routing backend request given the set of locations. While most implementations will treat the locations as an ordered sequence, this is not guaranteed (ex: an optimized router).

RouteResponseParserImpl

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class RouteResponseParserImpl: RouteResponseParser, @unchecked Sendable

A generic interface describing any object capable of parsing a response from a routing backend into one or more Routes.

Initialisers and methods

• open func parseResponse(response: Data) throws -> [Route]: Parses a raw response from the routing backend into a route. We use a sequence of octets as a common interchange format. as this works for all currently conceivable formats (JSON, PBF, etc.).

StepAdvanceCondition

Class · Sources/MapMapKit/Generated/ferrostar.swift

open class StepAdvanceCondition: StepAdvanceConditionProtocol, @unchecked Sendable

When implementing custom step advance logic, this trait allows you to define whether the condition should advance to the next condition, the next step or not.

At the moment, these must be implemented in Rust.

Initialisers and methods

• open func shouldAdvanceStep(tripState: TripState) -> StepAdvanceResult: This callback method is used by a step advance condition to receive step updates. The step advance condition can choose based on its outcome and internal state whether to advance to the next step or not.
• open func newInstance() -> StepAdvanceCondition: Creates a clean instance of this condition with the same configuration but reset state. This is used by composite conditions (Or/And) to ensure proper state isolation when any condition triggers advancement. Implementation Requirements: - Stateless conditions: Return a copy/clone of self - Stateful conditions: Return a new instance with initial state but preserve configuration parameters - Composite conditions: Recursively create fresh instances of all nested conditions This method prevents the state leakage bugs that can cause rapid step advancement and jumping behavior in navigation.

Structs (Ferrostar bindings (generated))

BoundingBox, Congestion, CourseOverGround, GeographicCoordinate, Heading, Incident, LaneInfo, LocationSimulationState, NavigationCachingConfig, NavigationControllerConfig, NavigationRecordingEvent, NavigationSessionSnapshot, NavState, OsrmWaypointProperties, Route, RouteStep, SerializableNavState, Speed, SpokenInstruction, StepAdvanceResult, TripProgress, TripSummary, UserLocation, ValhallaLocationSearchFilter, ValhallaWaypointProperties, VisualInstruction, VisualInstructionContent, Waypoint

BoundingBox

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct BoundingBox: Equatable, Hashable, Codable

A geographic bounding box defined by its corners.

Initialisers and methods

• public init(sw: GeographicCoordinate, ne: GeographicCoordinate)

Congestion

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct Congestion: Equatable, Hashable, Codable

Details about congestion for an incident.

Initialisers and methods

• public init(value: UInt8)

CourseOverGround

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct CourseOverGround: Equatable, Hashable, Codable

The direction in which the user/device is observed to be traveling.

Initialisers and methods

• public init(degrees: UInt16, accuracy: UInt16?)

GeographicCoordinate

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct GeographicCoordinate: Equatable, Hashable, Codable

A geographic coordinate in WGS84.

Initialisers and methods

• public init(lat: Double, lng: Double)

Heading

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct Heading: Equatable, Hashable, Codable

The heading of the user/device.

Initialisers and methods

• public init(trueHeading: UInt16, accuracy: UInt16, timestamp: Date)

Incident

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct Incident: Equatable, Hashable, Codable

An incident affecting the free flow of traffic, such as constructions, accidents, and congestion.

Initialisers and methods

• public init(id: String, incidentType: IncidentType, description: String?, longDescription: String?, creationTime: UtcDateTime?, startTime: UtcDateTime?, endTime: UtcDateTime?, impact: Impact?, lanesBlocked: [BlockedLane], congestion: Congestion?, closed: Bool?, geometryIndexStart: UInt64, geometryIndexEnd: UInt64?, subType: String?, subTypeDescription: String?, iso31661Alpha2: String?, iso31661Alpha3: String?, affectedRoadNames: [String], bbox: BoundingBox?)

LaneInfo

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct LaneInfo: Equatable, Hashable, Codable

The content of a visual instruction.

Initialisers and methods

• public init(active: Bool, directions: [String], activeDirection: String?)

LocationSimulationState

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct LocationSimulationState: Equatable, Hashable, Codable

The current state of the simulation.

Initialisers and methods

• public init(currentLocation: UserLocation, remainingLocations: [GeographicCoordinate], bias: LocationBias)

NavigationCachingConfig

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct NavigationCachingConfig: Equatable, Hashable, Codable

Initialisers and methods

• public init(cacheIntervalSeconds: Int64, maxAgeSeconds: Int64)

NavigationControllerConfig

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct NavigationControllerConfig

Initialisers and methods

• public init(waypointAdvance: WaypointAdvanceMode, stepAdvanceCondition: StepAdvanceCondition, arrivalStepAdvanceCondition: StepAdvanceCondition, routeDeviationTracking: RouteDeviationTracking, snappedLocationCourseFiltering: CourseFiltering)

NavigationRecordingEvent

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct NavigationRecordingEvent: Equatable, Hashable, Codable

An event that occurs during navigation.

This is used for the optional session recording / telemetry.

Initialisers and methods

• public init(timestamp: Int64, eventData: NavigationRecordingEventData)

NavigationSessionSnapshot

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct NavigationSessionSnapshot: Equatable, Hashable, Codable

Initialisers and methods

• public init(savedAt: UtcDateTime, route: Route, tripState: TripState?)

NavState

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct NavState

The navigation state.

This is typically created from an initial trip state and conditions for advancing navigation to the next step. Any internal navigation state is packed in here so that the navigation controller can remain functionally pure.

Initialisers and methods

• public init(tripState: TripState, stepAdvanceCondition: StepAdvanceCondition)

OsrmWaypointProperties

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct OsrmWaypointProperties: Equatable, Hashable, Codable

Waypoint properties parsed from an OSRM-compatible server response.

NOTE: Some servers (such as Valhalla) may support additional parameters at request time which are not echoed back in the response time. This is unfortunate; PRs upstream would likely be welcomed! Similarly, if your server is OSRM-compatible and returns additional attributes, feel free to open a PR to include these as optional properties.

Initialisers and methods

• public init(name: String?, distance: Double?)

Route

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct Route: Equatable, Hashable, Codable

Information describing the series of steps needed to travel between two or more points.

NOTE: This type is unstable and is still under active development and should be considered unstable.

Initialisers and methods

• public init(geometry: [GeographicCoordinate], bbox: BoundingBox, distance: Double, waypoints: [Waypoint], steps: [RouteStep])

RouteStep

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct RouteStep: Equatable, Hashable, Codable

A maneuver (such as a turn or merge) followed by travel of a certain distance until reaching the next step.

Initialisers and methods

• public init(geometry: [GeographicCoordinate], distance: Double, duration: Double, roadName: String?, exits: [String], instruction: String, visualInstructions: [VisualInstruction], spokenInstructions: [SpokenInstruction], annotations: [String]?, incidents: [Incident], drivingSide: DrivingSide?, roundaboutExitNumber: UInt8?)

SerializableNavState

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct SerializableNavState: Equatable, Hashable, Codable

Initialisers and methods

• public init(tripState: TripState, stepAdvanceCondition: SerializableStepAdvanceCondition)

Speed

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct Speed: Equatable, Hashable, Codable

The speed of the user from the location provider.

Initialisers and methods

• public init(value: Double, accuracy: Double?)

SpokenInstruction

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct SpokenInstruction: Equatable, Hashable, Codable

An instruction that can be synthesized using a TTS engine to announce an upcoming maneuver.

Note that these do not have any locale information attached.

Initialisers and methods

• public init(text: String, ssml: String?, triggerDistanceBeforeManeuver: Double, utteranceId: Uuid)

StepAdvanceResult

Struct · Sources/MapMapKit/Generated/ferrostar.swift

public struct StepAdvanceResult

The step advance result is produced on every iteration of the navigation state machine and used by the navigation to build a new NavState instance for that update.

Initialisers and methods

• public init(shouldAdvance: Bool, nextIteration: StepAdvanceCondition)