@@ -6,6 +6,20 @@ All notable changes to this project are documented here. Format follows
 
 ## [Unreleased]
 
+### Added
+
+- **`NavigationHandoff` — the first write this library builds towards the car.** Everything else
+  here reads. This composes a `geo:` URI so a route the driver has chosen can be handed to the
+  car's own navigation instead of retyped, and it is separated from the sending because the
+  format is the part that can be wrong and the part a JVM test can settle without a head unit.
+  It refuses coordinates that are not a place on Earth — latitude and longitude are two doubles
+  of the same type and a swap routes to the wrong continent while looking like an ordinary
+  number — and it formats in `Locale.ROOT`, because a head unit set to French writes 43.5 as
+  `43,5` and a comma is a field separator in this URI. A label from a geocoder or a charger
+  dataset is reduced to letters, digits, spaces and hyphens: it is text this project did not
+  write, and a parenthesis in it would end the label early. `geo:` carries one point and no
+  waypoints, which is a limit the caller has to show the driver rather than paper over.
+
 ### Fixed
 
 - **A momentarily unreadable battery power no longer blanks a settled range estimate.**
 
@@ -0,0 +1,67 @@
+package com.evsuite.hardware.saic
+
+import java.util.Locale
+
+/**
+ * A destination, in the one form every Android navigation app has agreed to understand.
+ *
+ * **This is the library's first write towards the car.** Everything else here reads: the hub,
+ * the nav adapter, the guidance getters all answer questions and change nothing. This builds a
+ * string that will move the screen a driver is about to follow at 130 km/h, and it is separated
+ * from the sending on purpose — the format is the part that can be wrong, and the part a JVM
+ * test can prove right without a head unit.
+ *
+ * **Why an intent rather than the OEM's own hook.** `IMapNotificationListener` carries
+ * `startNavFromEVRout`, which is exactly what this is for, but reaching it means registering on
+ * the channel the head unit uses to *command* the navigation app — impersonating a navigation
+ * provider to send one destination. `geo:` is the platform's own answer, it is one line, and if
+ * the head unit answers it there is nothing left to decompile. CP-056's Q9 says which.
+ *
+ * **What it cannot do.** `geo:` carries one point. There are no waypoints in it, so a route
+ * planned *through* somewhere cannot be pinned by handing over its endpoint — the caller hands
+ * over the charging stop instead, which is the leg the forecast is about, and says so on screen.
+ */
+object NavigationHandoff {
+
+    /**
+     * The destination as a `geo:` URI, or null when the coordinates are not a place on Earth.
+     *
+     * Refusing out-of-range coordinates is not defensive padding: latitude and longitude are two
+     * doubles of the same type and a swap routes to the wrong continent while looking like an
+     * ordinary number the whole way. Half the swaps land outside ±90 and this catches those.
+     *
+     * [Locale.ROOT] because a head unit set to French formats 43.5 as `43,5`, and a comma is a
+     * field separator in this URI. The destination would parse, silently, as somewhere else.
+     */
+    fun geoUri(latitude: Double, longitude: Double, label: String? = null): String? {
+        if (!latitude.isFinite() || !longitude.isFinite()) return null
+        if (latitude < -90.0 || latitude > 90.0) return null
+        if (longitude < -180.0 || longitude > 180.0) return null
+        val point = String.format(Locale.ROOT, "%.6f,%.6f", latitude, longitude)
+        val name = label?.let(::sanitise)?.takeIf { it.isNotEmpty() }
+        // The `q=` form is what carries a name; the leading point is what an app that ignores
+        // `q=` still shows. Both are the same place, so neither reading is wrong.
+        return if (name == null) "geo:$point?q=$point" else "geo:$point?q=$point($name)"
+    }
+
+    /**
+     * A label reduced to what cannot change the meaning of the URI around it.
+     *
+     * The name comes from a geocoder or a charger dataset — text this project did not write and
+     * cannot constrain. A parenthesis, an ampersand or a percent in it would end the label early
+     * or introduce a parameter, so the allowlist is letters, digits, spaces and hyphens, and
+     * everything else becomes a space. Accented letters are kept: a French place name without
+     * them is a different name.
+     */
+    private fun sanitise(label: String): String =
+        label.take(MAX_LABEL_CHARS)
+            .map { if (it.isLetterOrDigit() || it == ' ' || it == '-') it else ' ' }
+            .joinToString("")
+            .trim()
+            .replace(SPACES, "%20")
+
+    /** Long enough for "Ionity Béziers Est", short enough not to be a payload. */
+    private const val MAX_LABEL_CHARS = 48
+
+    private val SPACES = Regex(" +")
+}
@@ -0,0 +1,73 @@
+package com.evsuite.hardware.saic
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+import java.util.Locale
+
+class NavigationHandoffTest {
+
+    @Test fun `a destination becomes a geo uri both readings agree on`() {
+        assertEquals(
+            "geo:43.558300,1.533300?q=43.558300,1.533300",
+            NavigationHandoff.geoUri(43.5583, 1.5333),
+        )
+    }
+
+    @Test fun `a label travels in the q parameter`() {
+        assertEquals(
+            "geo:43.343000,3.215000?q=43.343000,3.215000(Ionity%20Beziers%20Est)",
+            NavigationHandoff.geoUri(43.343, 3.215, "Ionity Beziers Est"),
+        )
+    }
+
+    @Test fun `a french locale does not turn the decimal point into a field separator`() {
+        val previous = Locale.getDefault()
+        Locale.setDefault(Locale.FRANCE)
+        try {
+            assertEquals(
+                "geo:43.558300,1.533300?q=43.558300,1.533300",
+                NavigationHandoff.geoUri(43.5583, 1.5333),
+            )
+        } finally {
+            Locale.setDefault(previous)
+        }
+    }
+
+    @Test fun `a label cannot end itself or add a parameter`() {
+        assertEquals(
+            "geo:43.343000,3.215000?q=43.343000,3.215000(Total%20Energies%20A9)",
+            NavigationHandoff.geoUri(43.343, 3.215, "Total (Energies) &A9"),
+        )
+    }
+
+    @Test fun `an accented place name keeps its accents`() {
+        // Carried literally rather than percent-encoded. Android's Uri is lenient about this and
+        // a French place name stripped of its accents is a different name on a map.
+        assertEquals(
+            "geo:43.343000,3.215000?q=43.343000,3.215000(Béziers)",
+            NavigationHandoff.geoUri(43.343, 3.215, "Béziers"),
+        )
+    }
+
+    @Test fun `a label of nothing but punctuation is no label at all`() {
+        assertEquals(
+            "geo:43.343000,3.215000?q=43.343000,3.215000",
+            NavigationHandoff.geoUri(43.343, 3.215, "()&"),
+        )
+    }
+
+    @Test fun `coordinates that are not a place on earth are refused`() {
+        // The common swap: a French longitude read as a latitude stays in range, but a latitude
+        // read as a longitude does not always, and neither does anything from a parse failure.
+        assertNull(NavigationHandoff.geoUri(191.0, 3.0))
+        assertNull(NavigationHandoff.geoUri(43.0, 210.0))
+        assertNull(NavigationHandoff.geoUri(Double.NaN, 3.0))
+        assertNull(NavigationHandoff.geoUri(43.0, Double.POSITIVE_INFINITY))
+    }
+
+    @Test fun `the poles and the meridian are places`() {
+        assertEquals("geo:-90.000000,-180.000000?q=-90.000000,-180.000000", NavigationHandoff.geoUri(-90.0, -180.0))
+        assertEquals("geo:0.000000,0.000000?q=0.000000,0.000000", NavigationHandoff.geoUri(0.0, 0.0))
+    }
+}