react-native-pointr 10.7.0 → 10.7.1

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [10.7.1] - 2026-08-05
+
+### Changed
+- Mobile SDK 10.7.0 integration.
+
+
 ## [10.7.0] - 2026-07-31
 
 ### Changed
@@ -32,6 +38,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - **`PointrSdk` methods** exposing previously native-only capabilities: `shouldRequestPermissionsAtStartup`, `requestPermissions`, `getPois`, `searchPois`, `getSites`, `getBuildings`, `getSiteByExternalId`, `getClientName`, `isWayfindingReady`, `calculateDistance`, `isMyCarMarked`.
+- **Shared bridge key constants** — every string crossing the JS ↔ native boundary for a map widget action (action types, `action` and `sdkConfig` payload keys, view manager command names) is now declared in one constants file per platform: `src/constants/bridgeKeys.ts`, `android/src/main/java/com/pointr/PTRBridgeKeys.kt` and `ios/PTRBridgeKeys.swift`. No literals remain in the action serializer or in either native reader, so a key can no longer be renamed on one side only. `PTRActionParamKeys`, `PTRSdkConfigKeys` and `PTRCommandNames` are exported from the package.
+
+### Changed
+- **Actions serialize through `toPayload()`** — `PTRAction` subclasses now build their JSON payload from `PTRActionParamKeys` instead of the component spreading their class fields, so a field rename can no longer silently change the wire format.
+
+### Fixed
+- **Imperative `focusCoordinate` and `showMyCar` on Android** — the native side matched `focusCoordinate` / `showMyCarForSite` while JS dispatches `coordinate` / `myCarForSite`, so both commands were silently ignored. All three platforms now use the shared command names.
+- **`markMyCar` / `showMyCar` via the declarative `action` prop on Android** — the completion event read an argument slot the declarative path never pushed, throwing inside the callback. Argument reads are now type-checked with defaults.
+- **`personaId` in the `sdkConfig` prop on iOS** — the key was written by JS but never read, so the persona was ignored when the widget initialised the SDK.
 
 
 ## [10.3.0] - 2026-06-30

package/EXTENDING.md

@@ -358,6 +358,62 @@ Ensure both iOS and Android implementations return the same data structure:
 }
 ```
 
+### 7. Never Hard-code Bridge Strings
+
+Map widget actions cross the bridge as JSON, so a key that JS writes and native
+reads is matched by string only — rename it on one side and the other side
+silently reads an empty value, with no compile error anywhere. Every such string
+lives in a constants file, one per language, and the three are kept identical:
+
+| Side       | File                                                |
+| ---------- | --------------------------------------------------- |
+| TypeScript | `src/constants/bridgeKeys.ts`                       |
+| Android    | `android/src/main/java/com/pointr/PTRBridgeKeys.kt` |
+| iOS        | `ios/PTRBridgeKeys.swift`                           |
+
+They cover four groups:
+
+- **Action types** — the `type` discriminator of the `action` prop
+- **Action param keys** — every other field of the `action` prop payload
+- **SDK config keys** — the fields of the `sdkConfig` prop
+- **Command names** — the view manager commands `executeMapAction` dispatches
+
+When adding an action or a parameter:
+
+1. Add the constant to all three files (same name, same value).
+2. In TypeScript, build the payload from `PTRActionParamKeys` by overriding
+   `toPayload()` on the action class — never rely on the class field names.
+3. Read it back through `PTRBridgeKeys.ActionParamKeys` in both Kotlin and Swift.
+
+```typescript
+// src/actions/index.ts
+export class PTRMyNewAction extends PTRAction {
+  constructor(readonly site: string, readonly poi: string) {
+    super(PTRActionType.MY_NEW_ACTION);
+  }
+
+  override toPayload(): Record<string, unknown> {
+    return {
+      ...super.toPayload(),
+      [Keys.SITE]: this.site,
+      [Keys.POI]: this.poi,
+    };
+  }
+}
+```
+
+```kotlin
+// PTRMapWidgetManager.kt
+val site = obj.optString(ActionParamKeys.SITE, "")
+val poi = obj.optString(ActionParamKeys.POI, "")
+```
+
+```swift
+// PTRMapWidgetContainerView.swift
+let siteId = json[Keys.site] as? String ?? ""
+let poiId = json[Keys.poi] as? String ?? ""
+```
+
 ## Adding Event Listeners
 
 For continuous data streams or callbacks, use event emitters:

package/android/src/main/java/com/pointr/PTRBridgeKeys.kt

@@ -0,0 +1,153 @@
+package com.pointr
+
+import androidx.annotation.StringDef
+
+/**
+ * Every string that crosses the JS <-> native boundary when an action is sent
+ * to the map widget: action type discriminators, `action` / `sdkConfig` payload
+ * keys and view manager command names.
+ *
+ * Nothing here may be hard-coded anywhere else — a key renamed on one side only
+ * fails silently (`optString` returns an empty string), so all three sides read
+ * them from a constants file:
+ *
+ *   TypeScript  src/constants/bridgeKeys.ts
+ *   Android     android/src/main/java/com/pointr/PTRBridgeKeys.kt   (this file)
+ *   iOS         ios/PTRBridgeKeys.swift
+ *
+ * Changing a value here means changing it in the other two files as well.
+ */
+object PTRBridgeKeys {
+
+    /** Discriminator written to the `type` field of the serialized `action` prop. */
+    object ActionTypes {
+        /** Focus the map on a site, building or level */
+        const val FOCUS_MAP = "focusMap"
+        /** Highlight a single POI */
+        const val HIGHLIGHT_POI = "highlightPoi"
+        /** Draw a static route between two POIs */
+        const val DISPLAY_ROUTE = "displayRoute"
+        /** Start live wayfinding to a destination POI */
+        const val START_WAYFINDING = "startWayfinding"
+        /** Mark the parked car location */
+        const val MARK_MY_CAR = "markMyCar"
+        /** Show the previously marked car location */
+        const val SHOW_MY_CAR = "showMyCar"
+        /** Focus the map on a geographic coordinate */
+        const val FOCUS_COORDINATE = "focusCoordinate"
+        /** Highlight POIs of one or more categories */
+        const val HIGHLIGHT_CATEGORY = "highlightCategory"
+    }
+
+    /**
+     * Field names of the JSON payload carried by the `action` view prop.
+     * JS writes them, Android and iOS read them back out.
+     */
+    object ActionParamKeys {
+        /** Action discriminator — one of [ActionTypes] */
+        const val TYPE = "type"
+        /** Site external identifier */
+        const val SITE = "site"
+        /** Building external identifier */
+        const val BUILDING = "building"
+        /** Level index used by focusMap / markMyCar */
+        const val LEVEL = "level"
+        /** POI external identifier — destination for highlightPoi and startWayfinding */
+        const val POI = "poi"
+        /** Source POI external identifier for displayRoute */
+        const val FROM_POI = "fromPoi"
+        /** Destination POI external identifier for displayRoute */
+        const val TO_POI = "toPoi"
+        /** Whether the car popup is shown */
+        const val SHOULD_SHOW_POPUP = "shouldShowPopup"
+        /** Animation applied to the car marker */
+        const val ANIMATION_TYPE = "animationType"
+        /** Latitude for focusCoordinate */
+        const val LATITUDE = "latitude"
+        /** Longitude for focusCoordinate */
+        const val LONGITUDE = "longitude"
+        /** Level index for focusCoordinate */
+        const val LEVEL_INDEX = "levelIndex"
+        /** Category identifiers for highlightCategory */
+        const val CATEGORY_IDS = "categoryIds"
+    }
+
+    /** Field names of the JSON payload carried by the `sdkConfig` view prop. */
+    object SdkConfigKeys {
+        /** Client identifier issued by Pointr */
+        const val CLIENT_ID = "clientId"
+        /** License key issued by Pointr */
+        const val LICENSE_KEY = "licenseKey"
+        /** Base URL of the Pointr environment */
+        const val BASE_URL = "baseUrl"
+        /** Persona identifier applied to the SDK params */
+        const val PERSONA_ID = "personaId"
+        /** Log level ordinal */
+        const val LOG_LEVEL = "logLevel"
+    }
+
+    /**
+     * View manager command names used by the imperative `executeMapAction` path.
+     * JS dispatches them, Android matches them in `receiveCommand` and iOS
+     * exports them as `@objc` methods — the names must match on all three sides.
+     */
+    object CommandNames {
+        /** Focus the map on a site */
+        const val FOCUS_SITE = "site"
+        /** Focus the map on a building */
+        const val FOCUS_BUILDING = "building"
+        /** Focus the map on a level */
+        const val FOCUS_LEVEL = "level"
+        /** Highlight a POI */
+        const val HIGHLIGHT_POI = "poi"
+        /** Draw a static route between two POIs */
+        const val DISPLAY_ROUTE = "displayRoute"
+        /** Start live wayfinding */
+        const val START_WAYFINDING = "startWayfinding"
+        /** Mark the car at site level */
+        const val MARK_MY_CAR_FOR_SITE = "markMyCarForSite"
+        /** Mark the car at a specific level */
+        const val MARK_MY_CAR_FOR_LEVEL = "markMyCarForLevel"
+        /** Show the marked car at site level */
+        const val SHOW_MY_CAR_FOR_SITE = "myCarForSite"
+        /** Focus the map on a coordinate */
+        const val FOCUS_COORDINATE = "coordinate"
+        /** Highlight a category */
+        const val HIGHLIGHT_CATEGORY = "highlightCategory"
+    }
+}
+
+/** Restricts a String parameter to the [PTRBridgeKeys.ActionTypes] values. */
+@Retention(AnnotationRetention.SOURCE)
+@StringDef(
+    value = [
+        PTRBridgeKeys.ActionTypes.FOCUS_MAP,
+        PTRBridgeKeys.ActionTypes.HIGHLIGHT_POI,
+        PTRBridgeKeys.ActionTypes.DISPLAY_ROUTE,
+        PTRBridgeKeys.ActionTypes.START_WAYFINDING,
+        PTRBridgeKeys.ActionTypes.MARK_MY_CAR,
+        PTRBridgeKeys.ActionTypes.SHOW_MY_CAR,
+        PTRBridgeKeys.ActionTypes.FOCUS_COORDINATE,
+        PTRBridgeKeys.ActionTypes.HIGHLIGHT_CATEGORY
+    ]
+)
+annotation class PTRActionTypeDef
+
+/** Restricts a String parameter to the [PTRBridgeKeys.CommandNames] values. */
+@Retention(AnnotationRetention.SOURCE)
+@StringDef(
+    value = [
+        PTRBridgeKeys.CommandNames.FOCUS_SITE,
+        PTRBridgeKeys.CommandNames.FOCUS_BUILDING,
+        PTRBridgeKeys.CommandNames.FOCUS_LEVEL,
+        PTRBridgeKeys.CommandNames.HIGHLIGHT_POI,
+        PTRBridgeKeys.CommandNames.DISPLAY_ROUTE,
+        PTRBridgeKeys.CommandNames.START_WAYFINDING,
+        PTRBridgeKeys.CommandNames.MARK_MY_CAR_FOR_SITE,
+        PTRBridgeKeys.CommandNames.MARK_MY_CAR_FOR_LEVEL,
+        PTRBridgeKeys.CommandNames.SHOW_MY_CAR_FOR_SITE,
+        PTRBridgeKeys.CommandNames.FOCUS_COORDINATE,
+        PTRBridgeKeys.CommandNames.HIGHLIGHT_CATEGORY
+    ]
+)
+annotation class PTRCommandDef

package/android/src/main/java/com/pointr/PTRMapWidgetManager.kt

@@ -8,12 +8,17 @@ import android.widget.FrameLayout
 import androidx.fragment.app.FragmentActivity
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableType
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.bridge.WritableNativeMap
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.ViewGroupManager
 import com.facebook.react.uimanager.annotations.ReactProp
 import com.facebook.react.uimanager.events.RCTEventEmitter
+import com.pointr.PTRBridgeKeys.ActionParamKeys
+import com.pointr.PTRBridgeKeys.ActionTypes
+import com.pointr.PTRBridgeKeys.CommandNames
+import com.pointr.PTRBridgeKeys.SdkConfigKeys
 import com.pointrlabs.core.management.Pointr
 import com.pointrlabs.core.management.interfaces.PointrListener
 import com.pointrlabs.core.management.models.PTRParams
@@ -57,9 +62,10 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
     // auto-executes it once the view is attached rather than requiring a JS
     // imperative action dispatch.
     //
-    // JSON shape: { "type": "focusMap"|"highlightPoi"|"displayRoute"|"startWayfinding"|"markMyCar"|"showMyCar"|"focusCoordinate"|"highlightCategory",
-    //               "site": String, "building"?: String, "level"?: Int,
-    //               "poi"?: String, "fromPoi"?: String, "toPoi"?: String }
+    // The JSON shape is described by PTRBridgeKeys.ActionTypes (the `type`
+    // discriminator) and PTRBridgeKeys.ActionParamKeys (every other field).
+    // Read the payload only through those constants — the JS side writes it
+    // from the matching src/constants/bridgeKeys.ts.
     private var pendingActionJson: String? = null
     private var pendingSdkConfigJson: String? = null
     private var actionDidExecute = false
@@ -102,16 +108,16 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
         val json = pendingSdkConfigJson ?: return
         try {
             val obj = org.json.JSONObject(json)
-            val clientId = obj.optString("clientId")
-            val licenseKey = obj.optString("licenseKey")
-            val baseUrl = obj.optString("baseUrl")
-            val personaId = obj.optString("personaId", "")
+            val clientId = obj.optString(SdkConfigKeys.CLIENT_ID)
+            val licenseKey = obj.optString(SdkConfigKeys.LICENSE_KEY)
+            val baseUrl = obj.optString(SdkConfigKeys.BASE_URL)
+            val personaId = obj.optString(SdkConfigKeys.PERSONA_ID, "")
             if (clientId.isNotEmpty() && licenseKey.isNotEmpty() && baseUrl.isNotEmpty()) {
                 val params = PTRParams(clientId, licenseKey, baseUrl)
                 if (personaId.isNotEmpty()) {
                     params.personaId = personaId
                 }
-                val logLevel = obj.optInt("logLevel", Plog.LogLevel.ERROR.ordinal)
+                val logLevel = obj.optInt(SdkConfigKeys.LOG_LEVEL, Plog.LogLevel.ERROR.ordinal)
                 params.logLevel = try {
                     Plog.LogLevel.entries[logLevel]
                 } catch (_: Exception) {
@@ -150,69 +156,74 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
                 }
                 try {
                     val obj = org.json.JSONObject(json)
-                    val type = obj.optString("type")
-                    val site = obj.optString("site", "")
-                    val building = obj.optString("building", "")
-                    val level = obj.optInt("level", 0)
-                    val poi = obj.optString("poi", "")
-                    val fromPoi = obj.optString("fromPoi", "")
-                    val toPoi = obj.optString("toPoi", "")
+                    val type = obj.optString(ActionParamKeys.TYPE)
+                    val site = obj.optString(ActionParamKeys.SITE, "")
+                    val building = obj.optString(ActionParamKeys.BUILDING, "")
+                    val level = obj.optInt(ActionParamKeys.LEVEL, 0)
+                    val poi = obj.optString(ActionParamKeys.POI, "")
+                    val fromPoi = obj.optString(ActionParamKeys.FROM_POI, "")
+                    val toPoi = obj.optString(ActionParamKeys.TO_POI, "")
 
                     val args = com.facebook.react.bridge.Arguments.createArray()
-                    val shouldShowPopup = obj.optBoolean("shouldShowPopup", true)
+                    val shouldShowPopup = obj.optBoolean(ActionParamKeys.SHOULD_SHOW_POPUP, true)
+                    val animationType = obj.optInt(ActionParamKeys.ANIMATION_TYPE, 1)
                     when (type) {
-                        PTRMapWidgetActionType.FOCUS_MAP -> {
-                            if (building.isNotEmpty() && obj.has("level")) {
+                        ActionTypes.FOCUS_MAP -> {
+                            if (building.isNotEmpty() && obj.has(ActionParamKeys.LEVEL)) {
                                 args.pushString(site); args.pushString(building); args.pushInt(level)
-                                executeCommand("level", args)
+                                executeCommand(CommandNames.FOCUS_LEVEL, args)
                             } else if (building.isNotEmpty()) {
                                 args.pushString(site); args.pushString(building)
-                                executeCommand("building", args)
+                                executeCommand(CommandNames.FOCUS_BUILDING, args)
                             } else {
                                 args.pushString(site)
-                                executeCommand("site", args)
+                                executeCommand(CommandNames.FOCUS_SITE, args)
                             }
                         }
-                        PTRMapWidgetActionType.HIGHLIGHT_POI -> {
+                        ActionTypes.HIGHLIGHT_POI -> {
                             args.pushString(site); args.pushString(poi)
-                            executeCommand("poi", args)
+                            executeCommand(CommandNames.HIGHLIGHT_POI, args)
                         }
-                        PTRMapWidgetActionType.DISPLAY_ROUTE -> {
+                        ActionTypes.DISPLAY_ROUTE -> {
                             args.pushString(site); args.pushString(fromPoi); args.pushString(toPoi)
-                            executeCommand(PTRMapWidgetActionType.DISPLAY_ROUTE, args)
+                            executeCommand(CommandNames.DISPLAY_ROUTE, args)
                         }
-                        PTRMapWidgetActionType.START_WAYFINDING -> {
-                            args.pushString(site); args.pushString(toPoi)
-                            executeCommand(PTRMapWidgetActionType.START_WAYFINDING, args)
+                        ActionTypes.START_WAYFINDING -> {
+                            // PTRStartWayfindingAction serialises its destination under
+                            // ActionParamKeys.POI; TO_POI stays accepted as a fallback for
+                            // hand-written, deeplink-style payloads.
+                            args.pushString(site); args.pushString(poi.ifEmpty { toPoi })
+                            executeCommand(CommandNames.START_WAYFINDING, args)
                         }
-                        PTRMapWidgetActionType.MARK_MY_CAR -> {
-                            if (building.isNotEmpty() && obj.has("level")) {
-                                args.pushString(site); args.pushString(building); args.pushInt(level); args.pushBoolean(shouldShowPopup)
-                                executeCommand("markMyCarForLevel", args)
+                        ActionTypes.MARK_MY_CAR -> {
+                            if (building.isNotEmpty() && obj.has(ActionParamKeys.LEVEL)) {
+                                args.pushString(site); args.pushString(building); args.pushInt(level)
+                                args.pushBoolean(shouldShowPopup); args.pushInt(animationType)
+                                executeCommand(CommandNames.MARK_MY_CAR_FOR_LEVEL, args)
                             } else {
-                                args.pushString(site); args.pushBoolean(shouldShowPopup)
-                                executeCommand("markMyCarForSite", args)
+                                args.pushString(site); args.pushBoolean(shouldShowPopup); args.pushInt(animationType)
+                                executeCommand(CommandNames.MARK_MY_CAR_FOR_SITE, args)
                             }
                         }
-                        PTRMapWidgetActionType.SHOW_MY_CAR -> {
-                            args.pushString(site); args.pushBoolean(shouldShowPopup)
-                            executeCommand("showMyCarForSite", args)
+                        ActionTypes.SHOW_MY_CAR -> {
+                            args.pushString(site); args.pushBoolean(shouldShowPopup); args.pushInt(animationType)
+                            executeCommand(CommandNames.SHOW_MY_CAR_FOR_SITE, args)
                         }
-                        PTRMapWidgetActionType.FOCUS_COORDINATE -> {
-                            val lat = obj.optDouble("latitude", 0.0)
-                            val lon = obj.optDouble("longitude", 0.0)
-                            val lvl = obj.optInt("levelIndex", -1)
+                        ActionTypes.FOCUS_COORDINATE -> {
+                            val lat = obj.optDouble(ActionParamKeys.LATITUDE, 0.0)
+                            val lon = obj.optDouble(ActionParamKeys.LONGITUDE, 0.0)
+                            val lvl = obj.optInt(ActionParamKeys.LEVEL_INDEX, -1)
                             args.pushString(site); args.pushDouble(lat); args.pushDouble(lon); args.pushInt(lvl)
-                            executeCommand(PTRMapWidgetActionType.FOCUS_COORDINATE, args)
+                            executeCommand(CommandNames.FOCUS_COORDINATE, args)
                         }
-                        PTRMapWidgetActionType.HIGHLIGHT_CATEGORY -> {
+                        ActionTypes.HIGHLIGHT_CATEGORY -> {
                             val catArr = com.facebook.react.bridge.Arguments.createArray()
-                            val jsonArr = obj.optJSONArray("categoryIds")
+                            val jsonArr = obj.optJSONArray(ActionParamKeys.CATEGORY_IDS)
                             if (jsonArr != null) {
                                 for (i in 0 until jsonArr.length()) catArr.pushString(jsonArr.optString(i))
                             }
                             args.pushString(site); args.pushArray(catArr)
-                            executeCommand(PTRMapWidgetActionType.HIGHLIGHT_CATEGORY, args)
+                            executeCommand(CommandNames.HIGHLIGHT_CATEGORY, args)
                         }
                         else -> Log.w(name, "Unknown action type in action prop: $type")
                     }
@@ -272,17 +283,17 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
     }
 
     private fun executeCommand(
-        command: String,
+        @PTRCommandDef command: String,
         args: ReadableArray
     ) {
         val action: PTRMapWidgetAction = when (command) {
-            "site" -> {
+            CommandNames.FOCUS_SITE -> {
                 val siteId = args.getString(0).orEmpty()
                 val location = PTRMapWidgetSiteLocation(PTRIdentifier(siteId, isExternal = true))
                 PTRMapWidgetAction.focusMap(location)
             }
 
-            "building" -> {
+            CommandNames.FOCUS_BUILDING -> {
                 val siteId = args.getString(0).orEmpty()
                 val buildingId = args.getString(1).orEmpty()
                 val location = PTRMapWidgetBuildingLocation(
@@ -292,7 +303,7 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
                 PTRMapWidgetAction.focusMap(location)
             }
 
-            "level" -> {
+            CommandNames.FOCUS_LEVEL -> {
                 val siteId = args.getString(0).orEmpty()
                 val buildingId = args.getString(1).orEmpty()
                 val location = PTRMapWidgetLevelLocation(
@@ -303,7 +314,7 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
                 PTRMapWidgetAction.focusMap(location)
             }
 
-            "poi" -> {
+            CommandNames.HIGHLIGHT_POI -> {
                 val siteId = args.getString(0).orEmpty()
                 val poiId = args.getString(1).orEmpty()
                 val location = PTRMapWidgetPoiLocation(
@@ -313,7 +324,7 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
                 PTRMapWidgetAction.highlightPoi(location)
             }
 
-            PTRMapWidgetActionType.START_WAYFINDING -> {
+            CommandNames.START_WAYFINDING -> {
                 val siteId = args.getString(0).orEmpty()
                 val poiId = args.getString(1).orEmpty()
                 val location = PTRMapWidgetPoiLocation(
@@ -323,7 +334,7 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
                 PTRMapWidgetAction.startWayfinding(location)
             }
 
-            PTRMapWidgetActionType.DISPLAY_ROUTE -> {
+            CommandNames.DISPLAY_ROUTE -> {
                 val siteId = args.getString(0).orEmpty()
                 val sourcePoiId = args.getString(1).orEmpty()
                 val destinationPoiId = args.getString(2).orEmpty()
@@ -338,13 +349,13 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
                 PTRMapWidgetAction.displayRoute(sourceLocation, destinationLocation)
             }
 
-            "markMyCarForSite" -> {
+            CommandNames.MARK_MY_CAR_FOR_SITE -> {
                 val siteId = args.getString(0).orEmpty()
                 val location = PTRMapWidgetSiteLocation(PTRIdentifier(siteId, isExternal = true))
                 PTRMapWidgetAction.markMyCar(location, args.getBoolean(1))
             }
 
-            "markMyCarForLevel" -> {
+            CommandNames.MARK_MY_CAR_FOR_LEVEL -> {
                 val siteId = args.getString(0).orEmpty()
                 val buildingId = args.getString(1).orEmpty()
                 val location = PTRMapWidgetLevelLocation(
@@ -355,13 +366,18 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
                 PTRMapWidgetMarkMyCarAction(location, shouldShowPopup = args.getBoolean(3))
             }
 
-            "showMyCarForSite" -> {
+            CommandNames.SHOW_MY_CAR_FOR_SITE -> {
                 val siteId = args.getString(0).orEmpty()
                 val location = PTRMapWidgetSiteLocation(PTRIdentifier(siteId, isExternal = true))
-                PTRMapWidgetAction.showMyCar(location, shouldShowPopup = args.getBoolean(1))
+                // The declarative path sends (site, shouldShowPopup, animationType) while the
+                // imperative JS path sends (site, animationType) — read index 1 by type so
+                // neither shape throws.
+                val shouldShowPopup =
+                    if (args.size() > 1 && args.getType(1) == ReadableType.Boolean) args.getBoolean(1) else true
+                PTRMapWidgetAction.showMyCar(location, shouldShowPopup = shouldShowPopup)
             }
 
-            PTRMapWidgetActionType.FOCUS_COORDINATE -> {
+            CommandNames.FOCUS_COORDINATE -> {
                 val siteId = args.getString(0).orEmpty()
                 val latitude = args.getDouble(1)
                 val longitude = args.getDouble(2)
@@ -376,7 +392,7 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
                 PTRMapWidgetAction.focusMap(location)
             }
 
-            PTRMapWidgetActionType.HIGHLIGHT_CATEGORY -> {
+            CommandNames.HIGHLIGHT_CATEGORY -> {
                 val siteId = args.getString(0).orEmpty()
                 val categoryIds = mutableListOf<String>()
                 val arr = args.getArray(1)
@@ -401,77 +417,80 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
         getMapWidgetFragment(action)
     }
 
+    // The command arguments are positional, and the two dispatch paths (declarative
+    // `action` prop vs imperative executeMapAction) do not always push the same
+    // number of them. Read them by type with a fallback so a shorter payload
+    // degrades to a default instead of throwing inside the completion callback.
+    private fun argString(args: Array<out Any>, index: Int) = args.getOrNull(index) as? String ?: ""
+    private fun argInt(args: Array<out Any>, index: Int) = (args.getOrNull(index) as? Number)?.toInt() ?: 0
+    private fun argBoolean(args: Array<out Any>, index: Int) = args.getOrNull(index) as? Boolean ?: true
+
+    /** The error is always appended as the last argument by [executeCommand]. */
+    private fun argError(args: Array<out Any>) = args.lastOrNull() as? String ?: ""
+
     private fun mapWidgetDidEndLoading(
-        @PTRMapWidgetActionType command: String,
+        @PTRCommandDef command: String,
         vararg args: Any
     ) {
         val event: WritableMap = WritableNativeMap()
         event.putString("command", command)
         when (command) {
-            "site" -> {
-                event.putString("siteExternalIdentifier", args[0] as String)
-                event.putString("error", args[1] as String)
+            CommandNames.FOCUS_SITE -> {
+                event.putString("siteExternalIdentifier", argString(args, 0))
             }
 
-            "building" -> {
-                event.putString("siteExternalIdentifier", args[0] as String)
-                event.putString("buildingExternalIdentifier", args[1] as String)
-                event.putString("error", args[2] as String)
+            CommandNames.FOCUS_BUILDING -> {
+                event.putString("siteExternalIdentifier", argString(args, 0))
+                event.putString("buildingExternalIdentifier", argString(args, 1))
             }
 
-            "level" -> {
-                event.putString("siteExternalIdentifier", args[0] as String)
-                event.putString("buildingExternalIdentifier", args[1] as String)
-                event.putInt("levelIndex", (args[2] as Number).toInt())
-                event.putString("error", args[3] as String)
+            CommandNames.FOCUS_LEVEL -> {
+                event.putString("siteExternalIdentifier", argString(args, 0))
+                event.putString("buildingExternalIdentifier", argString(args, 1))
+                event.putInt("levelIndex", argInt(args, 2))
             }
 
-            "poi" -> {
-                event.putString("siteExternalIdentifier", args[0] as String)
-                event.putString("poiExternalIdentifier", args[1] as String)
-                event.putString("error", args[2] as String)
+            CommandNames.HIGHLIGHT_POI -> {
+                event.putString("siteExternalIdentifier", argString(args, 0))
+                event.putString("poiExternalIdentifier", argString(args, 1))
             }
 
-            PTRMapWidgetActionType.START_WAYFINDING -> {
-                event.putString("siteExternalIdentifier", args[0] as String)
-                event.putString("poiExternalIdentifier", args[1] as String)
-                event.putString("error", args[2] as String)
+            CommandNames.START_WAYFINDING -> {
+                event.putString("siteExternalIdentifier", argString(args, 0))
+                event.putString("poiExternalIdentifier", argString(args, 1))
             }
 
-            PTRMapWidgetActionType.DISPLAY_ROUTE -> {
-                event.putString("siteExternalIdentifier", args[0] as String)
-                event.putString("fromPoiExternalIdentifier", args[1] as String)
-                event.putString("toPoiExternalIdentifier", args[2] as String)
-                event.putString("error", args[3] as String)
+            CommandNames.DISPLAY_ROUTE -> {
+                event.putString("siteExternalIdentifier", argString(args, 0))
+                event.putString("fromPoiExternalIdentifier", argString(args, 1))
+                event.putString("toPoiExternalIdentifier", argString(args, 2))
             }
 
-            "markMyCarForSite" -> {
-                event.putString("siteExternalIdentifier", args[0] as String)
-                event.putBoolean("shouldShowPopup", args[1] as Boolean)
-                event.putInt("animationType", (args[2] as Number).toInt())
-                event.putString("error", args[3] as String)
+            CommandNames.MARK_MY_CAR_FOR_SITE -> {
+                event.putString("siteExternalIdentifier", argString(args, 0))
+                event.putBoolean("shouldShowPopup", argBoolean(args, 1))
+                event.putInt("animationType", argInt(args, 2))
             }
 
-            "markMyCarForLevel" -> {
-                event.putString("siteExternalIdentifier", args[0] as String)
-                event.putString("buildingExternalIdentifier", args[1] as String)
-                event.putInt("levelIndex", (args[2] as Number).toInt())
-                event.putBoolean("shouldShowPopup", args[3] as Boolean)
-                event.putInt("animationType", (args[4] as Number).toInt())
-                event.putString("error", args[5] as String)
+            CommandNames.MARK_MY_CAR_FOR_LEVEL -> {
+                event.putString("siteExternalIdentifier", argString(args, 0))
+                event.putString("buildingExternalIdentifier", argString(args, 1))
+                event.putInt("levelIndex", argInt(args, 2))
+                event.putBoolean("shouldShowPopup", argBoolean(args, 3))
+                event.putInt("animationType", argInt(args, 4))
             }
 
-            "showMyCarForSite" -> {
-                event.putString("siteExternalIdentifier", args[0] as String)
-                event.putBoolean("shouldShowPopup", args[1] as Boolean)
-                event.putInt("animationType", (args[2] as Number).toInt())
-                event.putString("error", args[3] as String)
+            CommandNames.SHOW_MY_CAR_FOR_SITE -> {
+                event.putString("siteExternalIdentifier", argString(args, 0))
+                event.putBoolean("shouldShowPopup", argBoolean(args, 1))
+                event.putInt("animationType", argInt(args, 2))
             }
 
             else -> {
                 return
             }
         }
+        event.putString("error", argError(args))
         Log.v(name, "sending onMapWidgetDidEndLoading with event: $event")
         reactContext.getJSModule(RCTEventEmitter::class.java).receiveEvent(
             frameLayout.id,