expo-arcgis 0.1.3 → 0.1.5

package/android/src/main/java/expo/modules/arcgis/AnalysisOverlayRef.kt

@@ -1,6 +1,8 @@
 package expo.modules.arcgis
 
 import com.arcgismaps.analysis.interactive.Analysis
+import com.arcgismaps.analysis.interactive.ExploratoryGeoElementLineOfSight
+import com.arcgismaps.analysis.interactive.ExploratoryGeoElementViewshed
 import com.arcgismaps.analysis.interactive.ExploratoryLineOfSightTargetVisibility
 import com.arcgismaps.analysis.interactive.ExploratoryLocationDistanceMeasurement
 import com.arcgismaps.analysis.interactive.ExploratoryLocationLineOfSight
@@ -75,6 +77,42 @@ class ViewshedRef(appContext: AppContext, props: Map<String, Any?>) : AnalysisRe
   }
 }
 
+/**
+ * SharedObject wrapping an [ExploratoryGeoElementViewshed] — a viewshed whose observer tracks a
+ * [GraphicRef]'s native [Graphic] (a [GeoElement]) as it moves.
+ */
+class GeoElementViewshedRef(appContext: AppContext, graphic: GraphicRef, props: Map<String, Any?>) : AnalysisRef(appContext) {
+  private val viewshed = ExploratoryGeoElementViewshed(
+    graphic.graphic,
+    numOr(props["horizontalAngle"], 45.0),
+    numOr(props["verticalAngle"], 45.0),
+    numOr(props["headingOffset"], 0.0),
+    numOr(props["pitchOffset"], 0.0),
+    (props["minDistance"] as? Number)?.toDouble(),
+    (props["maxDistance"] as? Number)?.toDouble(),
+  )
+
+  override val analysis: Analysis get() = viewshed
+
+  init {
+    applyProps(props)
+  }
+
+  fun applyProps(changed: Map<String, Any?>) {
+    changed.forEach { (key, value) ->
+      when (key) {
+        "headingOffset" -> (value as? Number)?.toDouble()?.let { viewshed.headingOffset = it }
+        "pitchOffset" -> (value as? Number)?.toDouble()?.let { viewshed.pitchOffset = it }
+        "horizontalAngle" -> (value as? Number)?.toDouble()?.let { viewshed.horizontalAngle = it }
+        "verticalAngle" -> (value as? Number)?.toDouble()?.let { viewshed.verticalAngle = it }
+        "minDistance" -> viewshed.minDistance = (value as? Number)?.toDouble()
+        "maxDistance" -> viewshed.maxDistance = (value as? Number)?.toDouble()
+        "frustumOutlineVisible" -> (value as? Boolean)?.let { viewshed.frustumOutlineVisible = it }
+      }
+    }
+  }
+}
+
 /** SharedObject wrapping an [ExploratoryLocationLineOfSight] — streams target visibility to JS. */
 class LineOfSightRef(appContext: AppContext, props: Map<String, Any?>) : AnalysisRef(appContext) {
   private val lineOfSight = ExploratoryLocationLineOfSight(
@@ -151,6 +189,34 @@ class DistanceMeasurementRef(appContext: AppContext, props: Map<String, Any?>) :
   }
 }
 
+/**
+ * SharedObject wrapping an [ExploratoryGeoElementLineOfSight] — a line of sight whose observer
+ * and target both track a [GraphicRef]'s native [Graphic] (a [GeoElement]) as it moves.
+ * Streams the target's visibility back to JS via `onTargetVisibilityChange`.
+ */
+class GeoElementLineOfSightRef(appContext: AppContext, observer: GraphicRef, target: GraphicRef) : AnalysisRef(appContext) {
+  private val lineOfSight = ExploratoryGeoElementLineOfSight(
+    observer.graphic,
+    target.graphic,
+  )
+  private val scope = CoroutineScope(Dispatchers.Main + SupervisorJob())
+
+  override val analysis: Analysis get() = lineOfSight
+
+  init {
+    scope.launch {
+      lineOfSight.targetVisibility.collect { visibility ->
+        emit("onTargetVisibilityChange", mapOf("visibility" to visibilityString(visibility)))
+      }
+    }
+  }
+
+  override fun deallocate() {
+    scope.cancel()
+    super.deallocate()
+  }
+}
+
 /** Decodes a JS point dict into a [Point] (returns null if the value is not a point geometry). */
 internal fun analysisPoint(value: Any?): Point? =
   (value as? Map<*, *>)?.let { geometryFromDict(it) } as? Point

package/android/src/main/java/expo/modules/arcgis/AuthChallengeHandler.kt

@@ -22,11 +22,17 @@ import kotlinx.coroutines.launch
 object AuthChallengeHandler : ArcGISAuthenticationChallengeHandler {
   private var username: String? = null
   private var password: String? = null
+  private var tokenExpirationMinutes: Int? = null
 
-  /** Stores (or clears, when null) the login the handler uses to mint token credentials on demand. */
-  fun setCredentials(username: String?, password: String?) {
+  /**
+   * Stores (or clears, when null) the login the handler uses to mint token credentials on demand.
+   * [tokenExpirationMinutes] is forwarded to [TokenCredential.createWithChallenge]; pass null to
+   * use the server's default expiry.
+   */
+  fun setCredentials(username: String?, password: String?, tokenExpirationMinutes: Int? = null) {
     this.username = username
     this.password = password
+    this.tokenExpirationMinutes = tokenExpirationMinutes
   }
 
   override suspend fun handleArcGISAuthenticationChallenge(
@@ -34,7 +40,7 @@ object AuthChallengeHandler : ArcGISAuthenticationChallengeHandler {
   ): ArcGISAuthenticationChallengeResponse {
     val user = username ?: return ArcGISAuthenticationChallengeResponse.ContinueAndFail
     val pass = password ?: return ArcGISAuthenticationChallengeResponse.ContinueAndFail
-    return TokenCredential.create(challenge.requestUrl, user, pass)
+    return TokenCredential.createWithChallenge(challenge, user, pass, tokenExpirationMinutes)
       .map { ArcGISAuthenticationChallengeResponse.ContinueWithCredential(it) }
       .getOrElse { ArcGISAuthenticationChallengeResponse.ContinueAndFail }
   }

package/android/src/main/java/expo/modules/arcgis/DynamicEntityLayerRef.kt

@@ -60,6 +60,24 @@ class DynamicEntityLayerRef(appContext: AppContext, props: Map<String, Any?>) :
     flow.tryEmit(CustomDynamicEntityDataSource.FeedEvent.NewObservation(geom, attributes))
   }
 
+  /**
+   * Returns the observation history for the entity with the given track id, newest first,
+   * capped at [max] entries (default 100). Each observation carries its own `attributes` and
+   * `geometry` snapshot at the time it was received.
+   */
+  suspend fun queryObservations(entityId: String, max: Int = 100): List<Map<String, Any?>> {
+    val result = dataSource.queryDynamicEntities(listOf(entityId)).getOrThrow()
+    val entity = result.toList().firstOrNull()
+      ?: return emptyList()
+    return entity.getObservations(max).map { obs ->
+      val entry = mutableMapOf<String, Any?>(
+        "attributes" to obs.attributes.toMap(),
+      )
+      obs.geometry?.let { entry["geometry"] = dictFromGeometry(it) }
+      entry
+    }
+  }
+
   /** Returns the data source's currently-tracked dynamic entities (attributes + geometry). */
   suspend fun queryDynamicEntities(): Map<String, Any?> {
     val result = dataSource.queryDynamicEntities(DynamicEntityQueryParameters()).getOrThrow()
@@ -93,6 +111,11 @@ class DynamicEntityLayerRef(appContext: AppContext, props: Map<String, Any?>) :
       }
       (dataSource as? ArcGISStreamService)?.filter = filter
     }
+    (changed["purgeOptions"] as? Map<*, *>)?.let { purgeDict ->
+      val opts = dataSource.purgeOptions
+      (purgeDict["maximumObservations"] as? Number)?.let { opts.maximumObservations = it.toLong() }
+      (purgeDict["maximumDuration"] as? Number)?.let { opts.maximumDuration = it.toDouble() }
+    }
   }
 
   override fun deallocate() {

package/android/src/main/java/expo/modules/arcgis/ExpoArcgisGeometryModule.kt

@@ -61,6 +61,9 @@ class ExpoArcgisGeometryModule : Module() {
     Function("geScale", ::geScale)
     Function("geEllipseGeodesic", ::geEllipseGeodesic)
     Function("geSectorGeodesic", ::geSectorGeodesic)
+    Function("geWithZ", ::geWithZ)
+    Function("geWithM", ::geWithM)
+    Function("geWithZAndM", ::geWithZAndM)
 
     // CoordinateFormatter — point <-> notation strings, exposed as the JS `coordinateFormatter` namespace.
     Function("cfToLatLong", ::cfToLatLong)
@@ -82,6 +85,11 @@ class ExpoArcgisGeometryModule : Module() {
     AsyncFunction("suggest") Coroutine { searchText: String, params: Map<String, Any?> ->
       suggest(searchText, params)
     }
+    // FLAG: ExpoArcgisGeometry is approaching 64 KB; if the module's definition() grows further,
+    // relocate geocodeSuggestion (and the other geocoder AsyncFunctions) to ExpoArcgisExtrasModule.
+    AsyncFunction("geocodeSuggestion") Coroutine { suggestionId: Int, params: Map<String, Any?> ->
+      geocodeSuggestion(suggestionId, params)
+    }
 
     // Routing — solve a route between stops, exposed as the JS `router` namespace.
     AsyncFunction("solveRoute") Coroutine { stops: List<Map<String, Any?>>, params: Map<String, Any?> ->
@@ -174,8 +182,8 @@ class ExpoArcgisGeometryModule : Module() {
     }
 
     // Offline — take maps/data offline, exposed as the JS `offline` namespace.
-    AsyncFunction("generateOfflineMap") Coroutine { portalItemId: String, areaOfInterest: Map<String, Any?>, downloadName: String ->
-      generateOfflineMap(appContext, appContext.reactContext?.filesDir, portalItemId, areaOfInterest, downloadName)
+    AsyncFunction("generateOfflineMap") Coroutine { portalItemId: String, areaOfInterest: Map<String, Any?>, downloadName: String, overrides: Map<String, Any?>? ->
+      generateOfflineMap(appContext, appContext.reactContext?.filesDir, portalItemId, areaOfInterest, downloadName, overrides)
     }
     AsyncFunction("syncOfflineMap") Coroutine { mobileMapPackagePath: String ->
       syncOfflineMap(appContext, mobileMapPackagePath)

package/android/src/main/java/expo/modules/arcgis/ExpoArcgisModule.kt

@@ -4,6 +4,7 @@ import android.content.Context
 import com.arcgismaps.ApiKey
 import com.arcgismaps.ArcGISEnvironment
 import com.arcgismaps.httpcore.authentication.OAuthApplicationCredential
+import com.arcgismaps.httpcore.authentication.OAuthUserCredential
 import com.arcgismaps.httpcore.authentication.TokenCredential
 import expo.modules.kotlin.Promise
 import expo.modules.kotlin.functions.Coroutine
@@ -34,14 +35,21 @@ class ExpoArcgisModule : Module() {
 
     // Token auth for secured services (e.g. utility-network feature services) — store the login;
     // the challenge handler mints a TokenCredential for the exact challenged resource on demand.
-    Function("setTokenCredential") { username: String, password: String ->
-      AuthChallengeHandler.setCredentials(username, password)
+    // `tokenExpirationMinutes` is optional; the server's default expiry is used when omitted.
+    Function("setTokenCredential") { username: String, password: String, tokenExpirationMinutes: Int? ->
+      AuthChallengeHandler.setCredentials(username, password, tokenExpirationMinutes)
     }
 
-    // Clears the stored login and all cached credentials (token + OAuth).
+    // Revokes any OAuth user credentials on the server, then clears all cached credentials.
     AsyncFunction("signOut") Coroutine { ->
+      val store = ArcGISEnvironment.authenticationManager.arcGISCredentialStore
+      for (credential in store.getCredentials()) {
+        if (credential is OAuthUserCredential) {
+          credential.revokeToken()
+        }
+      }
       AuthChallengeHandler.setCredentials(null, null)
-      ArcGISEnvironment.authenticationManager.arcGISCredentialStore.removeAll()
+      store.removeAll()
     }
 
     // OAuth user sign-in (Android): JS opens the browser between these two steps.
@@ -247,6 +255,9 @@ class ExpoArcgisModule : Module() {
       AsyncFunction("queryDynamicEntities") Coroutine { ref: DynamicEntityLayerRef ->
         ref.queryDynamicEntities()
       }
+      AsyncFunction("queryObservations") Coroutine { ref: DynamicEntityLayerRef, entityId: String, max: Int ->
+        ref.queryObservations(entityId, max)
+      }
       Function("pushObservation") { ref: DynamicEntityLayerRef, attributes: Map<String, Any?>, geometry: Map<String, Any?> ->
         ref.pushObservation(attributes, geometry)
       }
@@ -292,6 +303,16 @@ class ExpoArcgisModule : Module() {
       Function("applyProps") { ref: ViewshedRef, changed: Map<String, Any?> -> ref.applyProps(changed) }
     }
 
+    // GeoElement-anchored viewshed — observer tracks a Graphic as it moves.
+    Class(GeoElementViewshedRef::class) {
+      Constructor { graphic: GraphicRef, props: Map<String, Any?> ->
+        GeoElementViewshedRef(appContext, graphic, props)
+      }
+      Function("applyProps") { ref: GeoElementViewshedRef, changed: Map<String, Any?> ->
+        ref.applyProps(changed)
+      }
+    }
+
     // Line of sight — emits onTargetVisibilityChange as the target's visibility changes.
     Class(LineOfSightRef::class) {
       Constructor { props: Map<String, Any?> -> LineOfSightRef(appContext, props) }
@@ -299,6 +320,15 @@ class ExpoArcgisModule : Module() {
       Function("applyProps") { ref: LineOfSightRef, changed: Map<String, Any?> -> ref.applyProps(changed) }
     }
 
+    // GeoElement-anchored line of sight — observer and target each track a Graphic as it moves.
+    // FLAG: added to the main module — integrator may need to relocate for the 64 KB budget.
+    Class(GeoElementLineOfSightRef::class) {
+      Constructor { observer: GraphicRef, target: GraphicRef ->
+        GeoElementLineOfSightRef(appContext, observer, target)
+      }
+      Events("onTargetVisibilityChange")
+    }
+
     Class(DistanceMeasurementRef::class) {
       Constructor { props: Map<String, Any?> -> DistanceMeasurementRef(appContext, props) }
       Events("onMeasurementChange")
@@ -329,6 +359,9 @@ class ExpoArcgisModule : Module() {
       AsyncFunction("associations") Coroutine { ref: UtilityNetworkRef, tableName: String, whereClause: String ->
         ref.associations(tableName, whereClause)
       }
+      Function("getTerminalConfigurations") { ref: UtilityNetworkRef ->
+        ref.getTerminalConfigurations()
+      }
       AsyncFunction("getState") Coroutine { ref: UtilityNetworkRef -> ref.getState() }
       Function("validateNetworkTopology") { ref: UtilityNetworkRef, extent: Map<String, Any?> ->
         ref.validateNetworkTopology(extent)

package/android/src/main/java/expo/modules/arcgis/GeocoderFunctions.kt

@@ -1,6 +1,7 @@
 package expo.modules.arcgis
 
 import com.arcgismaps.geometry.Point
+import com.arcgismaps.geometry.SpatialReference
 import com.arcgismaps.tasks.geocode.GeocodeParameters
 import com.arcgismaps.tasks.geocode.GeocodeResult
 import com.arcgismaps.tasks.geocode.LocatorTask
@@ -12,8 +13,31 @@ import java.util.concurrent.ConcurrentHashMap
 /**
  * Free functions backing the JS `geocoder` namespace — forward / reverse geocoding via a
  * [LocatorTask]. Registered as `AsyncFunction`s in `ExpoArcgisGeometryModule`.
+ *
+ * SuggestResult round-trip
+ * ─────────────────────────
+ * [suggest] attaches a `suggestionId` (Int) to each returned item and stashes the native
+ * [SuggestResult] (and its locator URL) in [SuggestRegistry]. The registry is REPLACED on each
+ * new [suggest] call (ids restart from 0) so memory never grows unboundedly.
+ * [geocodeSuggestion] looks up the held result and calls `LocatorTask.geocode(suggestResult)` —
+ * the SDK's precise overload that avoids a text re-search.
  */
 
+/** Holds the native [SuggestResult]s from the most recent [suggest] call. */
+private object SuggestRegistry {
+  @Volatile private var locatorUrl: String = ""
+  @Volatile private var results: Map<Int, SuggestResult> = emptyMap()
+
+  /** Replaces the registry with a fresh set of results (called at the start of each [suggest]). */
+  @Synchronized fun reset(url: String, items: List<SuggestResult>) {
+    locatorUrl = url
+    results = items.mapIndexed { id, r -> id to r }.toMap()
+  }
+
+  @Synchronized fun lookup(id: Int): Pair<SuggestResult, String>? =
+    results[id]?.let { it to locatorUrl }
+}
+
 private const val WORLD_GEOCODER =
   "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"
 
@@ -49,6 +73,8 @@ private fun buildGeocodeParameters(params: Map<String, Any?>): GeocodeParameters
   (params["maxResults"] as? Number)?.toInt()?.let { maxResults = it }
   (params["countryCode"] as? String)?.let { countryCode = it }
   (params["categories"] as? List<*>)?.filterIsInstance<String>()?.let { categories.addAll(it) }
+  (params["resultAttributeNames"] as? List<*>)?.filterIsInstance<String>()?.let { resultAttributeNames.addAll(it) }
+  (params["outputSpatialReference"] as? Number)?.toInt()?.let { outputSpatialReference = SpatialReference(it) }
   ((params["preferredSearchLocation"] as? Map<*, *>)?.let { geometryFromDict(it) } as? Point)
     ?.let { preferredSearchLocation = it }
 }
@@ -59,9 +85,25 @@ private fun buildReverseGeocodeParameters(params: Map<String, Any?>): ReverseGeo
     (params["maxDistance"] as? Number)?.toDouble()?.let { maxDistance = it }
   }
 
-internal suspend fun suggest(searchText: String, params: Map<String, Any?>): List<Map<String, Any?>> =
-  locatorTask(params).suggest(searchText, buildSuggestParameters(params)).getOrThrow()
-    .map { serializeSuggestResult(it) }
+internal suspend fun suggest(searchText: String, params: Map<String, Any?>): List<Map<String, Any?>> {
+  val url = params["locatorUrl"] as? String ?: WORLD_GEOCODER
+  val results = locatorTask(params).suggest(searchText, buildSuggestParameters(params)).getOrThrow()
+  // Stash all results in the registry (replaces any prior batch; ids restart from 0).
+  SuggestRegistry.reset(url, results)
+  return results.mapIndexed { id, r ->
+    serializeSuggestResult(r) + mapOf("suggestionId" to id)
+  }
+}
+
+internal suspend fun geocodeSuggestion(suggestionId: Int, params: Map<String, Any?>): List<Map<String, Any?>> {
+  val (suggestResult, storedUrl) = SuggestRegistry.lookup(suggestionId)
+    ?: error("suggestionId $suggestionId not found — call suggest() first")
+  // Allow the caller to override the locator URL, but fall back to the one stored by suggest().
+  val url = params["locatorUrl"] as? String ?: storedUrl
+  return locators.getOrPut(url) { LocatorTask(url) }
+    .geocode(suggestResult).getOrThrow()
+    .map { serializeGeocodeResult(it) }
+}
 
 private fun buildSuggestParameters(params: Map<String, Any?>): SuggestParameters = SuggestParameters().apply {
   (params["maxResults"] as? Number)?.toInt()?.let { maxResults = it }

package/android/src/main/java/expo/modules/arcgis/GeometryEngineFunctions.kt

@@ -259,6 +259,17 @@ internal fun geScale(
   )
 }
 
+// region Z / M builders
+
+internal fun geWithZ(g: Map<String, Any?>, z: Double): Map<String, Any?>? =
+  parseGeo(g)?.let { encode(GeometryEngine.createWithZOrNull(it, z)) }
+
+internal fun geWithM(g: Map<String, Any?>, m: Double): Map<String, Any?>? =
+  parseGeo(g)?.let { encode(GeometryEngine.createWithMOrNull(it, m)) }
+
+internal fun geWithZAndM(g: Map<String, Any?>, z: Double, m: Double): Map<String, Any?>? =
+  parseGeo(g)?.let { encode(GeometryEngine.createWithZAndMOrNull(it, z, m)) }
+
 // region Geodesic construction
 
 internal fun geEllipseGeodesic(params: Map<String, Any?>): Map<String, Any?>? {

package/android/src/main/java/expo/modules/arcgis/GeoprocessingFunctions.kt

@@ -6,6 +6,7 @@ import com.arcgismaps.tasks.geoprocessing.GeoprocessingTask
 import com.arcgismaps.tasks.geoprocessing.geoprocessingparameters.GeoprocessingBoolean
 import com.arcgismaps.tasks.geoprocessing.geoprocessingparameters.GeoprocessingDataFile
 import com.arcgismaps.tasks.geoprocessing.geoprocessingparameters.GeoprocessingDate
+import com.arcgismaps.tasks.geoprocessing.geoprocessingparameters.GeoprocessingRaster
 import com.arcgismaps.tasks.geoprocessing.geoprocessingparameters.GeoprocessingDouble
 import com.arcgismaps.tasks.geoprocessing.geoprocessingparameters.GeoprocessingFeatures
 import com.arcgismaps.tasks.geoprocessing.geoprocessingparameters.GeoprocessingLinearUnit
@@ -82,8 +83,16 @@ private fun buildGeoprocessingParameter(d: Map<*, *>): GeoprocessingParameter? =
     GeoprocessingMultiValue(paramType, elements)
   }
   "dataFile" -> {
-    val url = d["url"] as? String ?: return null
-    GeoprocessingDataFile.Companion.createWithUrl(url)
+    val filePath = d["filePath"] as? String
+    if (filePath != null) {
+      // Local-file path — use GeoprocessingDataFile.inputFilePath (a settable property).
+      val df = GeoprocessingDataFile.Companion.create()
+      df.inputFilePath = filePath
+      df
+    } else {
+      val url = d["url"] as? String ?: return null
+      GeoprocessingDataFile.Companion.createWithUrl(url)
+    }
   }
   else -> null
 }
@@ -105,5 +114,12 @@ private suspend fun serializeGeoprocessingParameter(param: GeoprocessingParamete
     if (param.canFetchOutputFeatures) param.fetchOutputFeatures().getOrThrow()
     param.features?.map { serializeFeature(it) } ?: emptyList<Map<String, Any?>>()
   }
+  // GeoprocessingRaster extends GeoprocessingDataFile — must come before any GeoprocessingDataFile branch.
+  is GeoprocessingRaster -> {
+    val result = mutableMapOf<String, Any?>("type" to "raster")
+    param.url?.let { result["url"] = it }
+    param.inputFilePath?.let { result["filePath"] = it }
+    result
+  }
   else -> null
 }

package/android/src/main/java/expo/modules/arcgis/GraphicsOverlayRef.kt

@@ -58,36 +58,188 @@ class GraphicsOverlayRef(appContext: AppContext) : SharedObject(appContext) {
 /**
  * Builds a [Renderer] (simple / unique-value / class-breaks) from a JS renderer dict.
  * Shared by [GraphicsOverlayRef.setRenderer] and [FeatureLayerRef.applyProps].
+ *
+ * When `visualVariables` is present, round-trips through [Renderer.toJson] /
+ * [Renderer.Companion.fromJsonOrNull] so the native C++ engine applies data-driven
+ * size/color/rotation/opacity — typed Kotlin wrappers do not expose `VisualVariable` classes
+ * in SDK 300.0.0.
  */
-internal fun buildRenderer(r: Map<*, *>): Renderer? = when (r["type"]) {
-  "simple" -> (r["symbol"] as? Map<*, *>)?.let(::buildSymbol)?.let { SimpleRenderer(it) }
-  "unique-value" -> {
-    val fields = (r["fields"] as? List<*>)?.filterIsInstance<String>() ?: emptyList()
-    val values = (r["uniqueValues"] as? List<*>)?.mapNotNull { uv ->
-      (uv as? Map<*, *>)?.let {
-        val symbol = (it["symbol"] as? Map<*, *>)?.let(::buildSymbol) ?: return@mapNotNull null
-        UniqueValue(it["label"] as? String ?: "", "", symbol, rendererValues(it["values"]))
+internal fun buildRenderer(r: Map<*, *>): Renderer? {
+  val typed: Renderer? = when (r["type"]) {
+    "simple" -> (r["symbol"] as? Map<*, *>)?.let(::buildSymbol)?.let { SimpleRenderer(it) }
+    "unique-value" -> {
+      val fields = (r["fields"] as? List<*>)?.filterIsInstance<String>() ?: emptyList()
+      val values = (r["uniqueValues"] as? List<*>)?.mapNotNull { uv ->
+        (uv as? Map<*, *>)?.let {
+          val symbol = (it["symbol"] as? Map<*, *>)?.let(::buildSymbol) ?: return@mapNotNull null
+          UniqueValue(it["label"] as? String ?: "", "", symbol, rendererValues(it["values"]))
+        }
+      } ?: emptyList()
+      UniqueValueRenderer(
+        fields,
+        values,
+        r["defaultLabel"] as? String ?: "",
+        (r["defaultSymbol"] as? Map<*, *>)?.let(::buildSymbol) ?: transparentMarker(),
+      )
+    }
+    "class-breaks" -> {
+      val breaks = (r["classBreaks"] as? List<*>)?.mapNotNull { cb ->
+        (cb as? Map<*, *>)?.let {
+          val symbol = (it["symbol"] as? Map<*, *>)?.let(::buildSymbol) ?: return@mapNotNull null
+          ClassBreak(it["label"] as? String ?: "", "", num(it["min"]), num(it["max"]), symbol)
+        }
+      } ?: emptyList()
+      ClassBreaksRenderer(r["field"] as? String ?: "", breaks).apply {
+        (r["defaultSymbol"] as? Map<*, *>)?.let(::buildSymbol)?.let { defaultSymbol = it }
       }
-    } ?: emptyList()
-    UniqueValueRenderer(
-      fields,
-      values,
-      r["defaultLabel"] as? String ?: "",
-      (r["defaultSymbol"] as? Map<*, *>)?.let(::buildSymbol) ?: transparentMarker(),
-    )
+    }
+    else -> null
   }
-  "class-breaks" -> {
-    val breaks = (r["classBreaks"] as? List<*>)?.mapNotNull { cb ->
-      (cb as? Map<*, *>)?.let {
-        val symbol = (it["symbol"] as? Map<*, *>)?.let(::buildSymbol) ?: return@mapNotNull null
-        ClassBreak(it["label"] as? String ?: "", "", num(it["min"]), num(it["max"]), symbol)
-      }
-    } ?: emptyList()
-    ClassBreaksRenderer(r["field"] as? String ?: "", breaks).apply {
-      (r["defaultSymbol"] as? Map<*, *>)?.let(::buildSymbol)?.let { defaultSymbol = it }
+  // If visualVariables are present, inject them into the renderer JSON and reconstruct.
+  val vvRaw = (r["visualVariables"] as? List<*>)?.mapNotNull { it as? Map<*, *> }
+  if (vvRaw.isNullOrEmpty() || typed == null) return typed
+  return applyVisualVariables(vvRaw, typed) ?: typed
+}
+
+/**
+ * Builds the ArcGIS REST JSON representation of [vvRaw], injects it into [renderer]'s own JSON,
+ * and reconstructs the renderer so the native C++ engine applies data-driven symbology.
+ * Returns `null` if JSON manipulation fails; the caller falls back to [renderer].
+ */
+private fun applyVisualVariables(vvRaw: List<Map<*, *>>, renderer: Renderer): Renderer? {
+  val vvJson = vvRaw.mapNotNull(::buildVisualVariableJson)
+  if (vvJson.isEmpty()) return null
+  return try {
+    val rendererJson = renderer.toJson()
+    val rendererMap = jsonObjToMap(org.json.JSONObject(rendererJson))
+    rendererMap["visualVariables"] = vvJson
+    val modifiedJson = mapToJsonObject(rendererMap).toString()
+    Renderer.fromJsonOrNull(modifiedJson)
+  } catch (e: Exception) {
+    null
+  }
+}
+
+/** Converts an [org.json.JSONObject] to a mutable [Map] recursively (for round-trip JSON mutation). */
+private fun jsonObjToMap(obj: org.json.JSONObject): MutableMap<String, Any?> {
+  val map = mutableMapOf<String, Any?>()
+  for (key in obj.keys()) {
+    map[key] = when (val v = obj.get(key)) {
+      is org.json.JSONObject -> jsonObjToMap(v)
+      is org.json.JSONArray -> jsonArrToList(v)
+      org.json.JSONObject.NULL -> null
+      else -> v
     }
   }
-  else -> null
+  return map
+}
+
+private fun jsonArrToList(arr: org.json.JSONArray): List<Any?> =
+  (0 until arr.length()).map { i ->
+    when (val v = arr.get(i)) {
+      is org.json.JSONObject -> jsonObjToMap(v)
+      is org.json.JSONArray -> jsonArrToList(v)
+      org.json.JSONObject.NULL -> null
+      else -> v
+    }
+  }
+
+/** Recursively converts a [Map] to a [org.json.JSONObject]. */
+private fun mapToJsonObject(map: Map<*, *>): org.json.JSONObject {
+  val obj = org.json.JSONObject()
+  for ((k, v) in map) {
+    val key = k?.toString() ?: continue
+    when (v) {
+      null -> obj.put(key, org.json.JSONObject.NULL)
+      is Map<*, *> -> obj.put(key, mapToJsonObject(v))
+      is List<*> -> obj.put(key, listToJsonArray(v))
+      else -> obj.put(key, v)
+    }
+  }
+  return obj
+}
+
+/** Recursively converts a [List] to a [org.json.JSONArray]. */
+private fun listToJsonArray(list: List<*>): org.json.JSONArray {
+  val arr = org.json.JSONArray()
+  for (v in list) {
+    when (v) {
+      null -> arr.put(org.json.JSONObject.NULL)
+      is Map<*, *> -> arr.put(mapToJsonObject(v))
+      is List<*> -> arr.put(listToJsonArray(v))
+      else -> arr.put(v)
+    }
+  }
+  return arr
+}
+
+/**
+ * Converts one JS `VisualVariable` map to the ArcGIS REST JSON map understood by the native
+ * renderer engine. Hex color strings (`#RRGGBB`/`#RRGGBBAA`, alpha-last) are converted to
+ * `[R, G, B, A]` integer lists as required by the REST spec.
+ */
+private fun buildVisualVariableJson(vv: Map<*, *>): Map<String, Any?>? = when (vv["type"]) {
+  "size" -> buildMap {
+    put("type", "sizeInfo")
+    (vv["field"] as? String)?.let { put("field", it) }
+    (vv["valueExpression"] as? String)?.let { put("valueExpression", it) }
+    (vv["minDataValue"] as? Number)?.toDouble()?.let { put("minDataValue", it) }
+    (vv["maxDataValue"] as? Number)?.toDouble()?.let { put("maxDataValue", it) }
+    (vv["minSize"] as? Number)?.toDouble()?.let { put("minSize", it) }
+    (vv["maxSize"] as? Number)?.toDouble()?.let { put("maxSize", it) }
+    (vv["stops"] as? List<*>)?.mapNotNull { s ->
+      (s as? Map<*, *>)?.let {
+        val value = (it["value"] as? Number)?.toDouble() ?: return@mapNotNull null
+        val size = (it["size"] as? Number)?.toDouble() ?: return@mapNotNull null
+        mapOf("value" to value, "size" to size)
+      }
+    }?.takeIf { it.isNotEmpty() }?.let { put("stops", it) }
+  }
+  "color" -> buildMap {
+    put("type", "colorInfo")
+    (vv["field"] as? String)?.let { put("field", it) }
+    (vv["valueExpression"] as? String)?.let { put("valueExpression", it) }
+    (vv["stops"] as? List<*>)?.mapNotNull { s ->
+      (s as? Map<*, *>)?.let {
+        val value = (it["value"] as? Number)?.toDouble() ?: return@mapNotNull null
+        val colorArr = restColor(it["color"]) ?: return@mapNotNull null
+        mapOf("value" to value, "color" to colorArr)
+      }
+    }?.takeIf { it.isNotEmpty() }?.let { put("stops", it) }
+  }
+  "rotation" -> buildMap {
+    put("type", "rotationInfo")
+    (vv["field"] as? String)?.let { put("field", it) }
+    (vv["valueExpression"] as? String)?.let { put("valueExpression", it) }
+    (vv["rotationType"] as? String)?.let { put("rotationType", it) }
+  }
+  "opacity" -> buildMap {
+    put("type", "opacityInfo")
+    (vv["field"] as? String)?.let { put("field", it) }
+    (vv["valueExpression"] as? String)?.let { put("valueExpression", it) }
+    (vv["stops"] as? List<*>)?.mapNotNull { s ->
+      (s as? Map<*, *>)?.let {
+        val value = (it["value"] as? Number)?.toDouble() ?: return@mapNotNull null
+        val opacity = (it["opacity"] as? Number)?.toDouble() ?: return@mapNotNull null
+        mapOf("value" to value, "opacity" to opacity)
+      }
+    }?.takeIf { it.isNotEmpty() }?.let { put("stops", it) }
+  }
+  else -> null // skip unknown visual variable types gracefully
+}
+
+/**
+ * Converts a hex color string (`#RRGGBB` / `#RRGGBBAA`, alpha-last) to an
+ * `[R, G, B, A]` integer list as required by the ArcGIS REST renderer JSON spec.
+ */
+private fun restColor(value: Any?): List<Int>? {
+  val hex = (value as? String)?.trim()?.removePrefix("#") ?: return null
+  val v = hex.toLongOrNull(16) ?: return null
+  return when (hex.length) {
+    6 -> listOf(((v shr 16) and 0xff).toInt(), ((v shr 8) and 0xff).toInt(), (v and 0xff).toInt(), 255)
+    8 -> listOf(((v shr 24) and 0xff).toInt(), ((v shr 16) and 0xff).toInt(), ((v shr 8) and 0xff).toInt(), (v and 0xff).toInt())
+    else -> null
+  }
 }
 
 /** Converts JS unique values to comparable scalars (whole numbers → Int, else Double/String). */