Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Changelog

The SDK is in active development; everything below is unreleased. The FFI contract surface it describes changes addition-only: existing members keep their signature and meaning. This page is a curated, public-facing summary. The complete development log lives in the source repository.

Imagery and caching

  • All seven MapQuest provider APIs are implemented and fixture-tested. They cover routes with strategies and multiple legs, the route matrix, forward and reverse geocoding, search prediction, traffic incidents, traffic-flow congestion polylines, and raster tiles in standard and retina resolutions.
  • A SQLite-backed response cache holds provider responses under an absolute byte budget, a share of free disk space, or both. It provides per-category time-to-live, LRU eviction, and cache-then-network behavior around every provider contract. Tile imagery caches heavily by default: 30 calendar days, the common maximum under imagery-provider terms. Each provider contract declares its own caching terms, so an integrator tunes the cache knowingly per provider (setRasterTileCacheTimeToLive, read back through rasterTileCacheTerms). Values above a provider’s declared ceiling stay compliance-clamped.

Rendering

  • The project maintains its own minimal wgpu raster renderer. It implements web-mercator projection with exact frustum tile listing (Sutherland–Hodgman over the six frustum planes, with antimeridian world-copy handling), an anchored camera with fit-bounds and insets-aware framing and a flyTo-style hyperbolic arc, a byte-bounded GPU texture cache, and a tile scheduler with per-frame dedup, parent fallback, and a fetch budget. Route, polygon, marker, and traffic overlay layers sit on top of the tiles, and the renderer owns the location indicator (a tracking dot with accuracy ring, or a guided course arrow).
  • The same renderer scene draws headless (deterministic golden-image tests), into live Android/iOS surfaces, and in the browser through WebGPU. One WGSL/vertex pattern is byte-identical across the wasm and native paths.

Offline routing

  • The offline routing pipeline is in place. A deterministic compiler turns an OpenStreetMap PBF extract into a self-describing routing archive (nodes, a per-edge pack with road class, speed, and access columns, and turn restrictions). A memory-mapped reader validates the container’s alignment invariants. An offline routing provider answers routes with A* over the graph. It honors recorded turn restrictions and derives turn maneuvers (left/right/slight/sharp/U-turn) from the geometry’s bearing change; its texts stay honest where the archive carries no street names. A routing decorator retries over the offline graph when the primary (online) provider fails.
  • The same graph runs in the browser: the wasm surface loads the compiled archive from in-memory bytes and answers the same route-shaped objects and typed refusals, so offline routing behavior is regression-tested in a plain browser run.
  • Navigation state is a pure reducer over Option<NavigationSession>. It implements Ferrostar-pattern step-advance conditions (manual, eager distance-to-end, delayed current-step, Or/And combinators, and the fresh-instance reset contract), deviation detection with accuracy-aware allowances, and provider-verbatim instruction composition (banner and speech text; nothing rewritten).
  • Deviation is graded. A fully-off-route state freezes the guidance and asks for a reroute; an off-step-but-on-route state keeps counting down and reconciles to the projected step. Speed runs advance through many steps per fix, and the advance is bounded and stack-safety-tested. The fully-off-route instruction text suppresses the countdown honestly rather than projecting it from a stale anchor.
  • The SDK owns speech triggering: it publishes a speech-instruction topic over documented distance bands. Platforms voice that topic and keep their own pacing and focus policies.

Camera and gestures

  • The gesture-input camera seam keeps the camera math in the SDK. Platform recognizers forward plain deltas, and the SDK applies them: pan by screen pixels, focal-point zoom and rotation with an exact hold-the-focal-point correction, clamped through the camera’s own ranges.

Bindings and platforms

  • UniFFI drives the generated Kotlin/Swift bindings and the React Native bindings from a frozen, addition-only UDL contract. The wasm surface is a hand-reviewed TypeScript mirror regression-checked against the same UDL. Callback providers (geocoding, tiles) and a navigation controller with per-topic subscriptions cross the foreign callbacks seam. Exported async methods run through a crate-owned runtime handback, so foreign event loops never meet an unserved reactor.
  • Reference applications on Android (Compose), iOS (SwiftUI), and the web playground implement one shared design language. Each reaches search → route → simulated turn-by-turn with speech through a bottom-sheet home, a five-control cluster (zoom, scale bar, my-location, 2D/3D, compass), a follow camera, an offline tile-cache card, and a readiness-chip diagnostics readout. The web surface reaches reference-app parity with the native demos.

Vector tiles

  • A Mapbox Vector Tile v2.1 decoder turns fetched tiles into layers, features and geometries with typed errors on every malformed path. A data-only style pass maps decoded layers into the renderer’s fill, polyline and point overlays (an optional one-attribute text filter is supported). The OpenStreetMap US Sourdough tileset is the first vector-tile provider, with attribution and terms carried by its source descriptor.

Provider credentials

  • The reference applications never embed a provider key in a build. They start keyless and take credentials at runtime from a settings surface whose rows come from one shared provider registry; keys stay in memory unless the user opts in to device secure storage (Keychain or Android Keystore). Automated UI runs can inject a credential through a launch intent/environment; it is never persisted or logged.

Releases and the live demo

  • A tag-driven release pipeline runs the gate set on the tagged tree, builds the Android AAR, the iOS XCFramework archive and the wasm package, and assembles a draft GitHub Release with an exact asset-set check, SHA-256 sidecars and manifest, keyless Sigstore signature bundles, regenerated third-party notices and changelog-derived notes.
  • The same WebAssembly build powers a live, keyless demo at this site’s /demo path. Its provider panel can take a runtime key for live geocoding, routing and tile probes; the static demo defaults to the recorded fixture data.

Diagnostics and ops

  • A tracing-facade diagnostics layer provides bounded, per-subsystem ring sinks with coordinate scrubbing at the sink. Its severity gate never raises once finer events have been requested. Subscribe and flush seams on the native and wasm surfaces back the reference apps’ readouts and a later log-sharing story.
  • CI runs fmt, clippy with warnings-as-errors, the workspace test suite, a wasm-targeted clippy closure, a browser e2e suite, and the documentation-site pipeline (build → scrub → stage) on every push.

Attribution

Each provider descriptor carries its own attribution line, and the reference applications render it from the shared registry. The bundled demo currently shows MapQuest imagery and OpenStreetMap data: map imagery © MapQuest; map data © OpenStreetMap contributors (ODbL). Third-party dependency notices are regenerated into their chapter.