craft-native 0.0.355 → 0.0.359

package/dist/android/src/index.js

@@ -964,6 +964,7 @@ import com.google.android.gms.pay.PayClient` : "").replace("{{NATIVE_WALLET_FIEL
         } catch (error: Exception) {
             done(failure("PUSH_UNAVAILABLE", error.message ?: "Firebase Cloud Messaging is not configured"))
         }` : '        done(failure("CAPABILITY_DISABLED", "Push notifications are disabled"))'));
+  write("CraftNativeSounds.kt.template", "CraftNativeSounds.kt");
   if (config.enablePushNotifications)
     write("CraftNativeMessagingService.kt.template", "CraftNativeMessagingService.kt");
   else

package/dist/android/templates/CraftNativeCapabilities.kt.template

@@ -112,6 +112,8 @@ internal class CraftNativeCapabilities(
         val quality: Float,
         val completion: (CraftNativeCapabilityResult) -> Unit,
         val videoLimit: Long = 0,
+        val selectionLimit: Int = 1,
+        val fileLimit: Long = 0,
     )
 
     private val connectivity = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
@@ -218,6 +220,7 @@ internal class CraftNativeCapabilities(
             "Files" -> when (method) {
                 "pickImage" -> pickImage(requestToken, args, completion)
                 "pickVideo" -> pickVideo(requestToken, args, completion)
+                "pickFile" -> pickFile(requestToken, args, completion)
                 "download", "write", "remove" -> networkExecutor.execute {
                     complete(requestToken, files(requestToken, method, args), completion)
                 }
@@ -512,9 +515,10 @@ internal class CraftNativeCapabilities(
     }
 
     /** Copy with a bound even when a cloud provider does not report its size. */
-    private fun copyVideo(uri: Uri, limit: Long): CraftNativeCapabilityResult {
+    private fun copyVideo(requestToken: String, uri: Uri, limit: Long): CraftNativeCapabilityResult {
         var target: File? = null
         return try {
+            if (cancelled.contains(requestToken)) throw IllegalStateException("CANCELLED: Video selection was cancelled")
             val name = context.contentResolver.query(uri, arrayOf(android.provider.OpenableColumns.DISPLAY_NAME), null, null, null)?.use {
                 if (it.moveToFirst()) it.getString(0) else null
             } ?: "video.mp4"
@@ -531,6 +535,7 @@ internal class CraftNativeCapabilities(
                     while (true) {
                         val count = source.read(buffer)
                         if (count < 0) break
+                        if (cancelled.contains(requestToken)) throw IllegalStateException("CANCELLED: Video selection was cancelled")
                         size += count
                         require(size <= limit) { "Choose a video under ${limit / 1024 / 1024}MB." }
                         output.write(buffer, 0, count)
@@ -541,7 +546,9 @@ internal class CraftNativeCapabilities(
             success(descriptor(destination, type))
         } catch (error: Exception) {
             target?.parentFile?.deleteRecursively()
-            failure("READ_ERROR", error.message ?: "The video could not be read")
+            val message = error.message ?: "The video could not be read"
+            if (message.startsWith("CANCELLED:")) failure("CANCELLED", message.removePrefix("CANCELLED:").trim())
+            else failure("READ_ERROR", message)
         }
     }
 
@@ -585,6 +592,76 @@ internal class CraftNativeCapabilities(
         }
     }
 
+    private fun pickFile(requestToken: String, args: JSONArray, completion: (CraftNativeCapabilityResult) -> Unit) {
+        mainHandler.post {
+            val host = activity ?: return@post complete(requestToken, failure("NEEDS_ACTIVITY", "No screen is showing to pick from"), completion)
+            if (pendingFilePick != null) {
+                complete(requestToken, failure("BUSY", "Another file picker is already open"), completion)
+                return@post
+            }
+            val options = args.optJSONObject(0) ?: JSONObject()
+            val types = documentTypes(options.optJSONArray("contentTypes"))
+            if (types == null) {
+                complete(requestToken, failure("INVALID_ARGUMENT", "files.pickFile contentTypes must be MIME types, UTIs, or extensions"), completion)
+                return@post
+            }
+            val selections = options.optInt("maxSelections", 1).coerceIn(1, 20)
+            val limit = options.optLong("maxBytes", 512L * 1024 * 1024).coerceIn(1, 512L * 1024 * 1024)
+            pendingFilePick = PendingFilePick(
+                requestToken,
+                "file",
+                0,
+                1f,
+                completion,
+                selectionLimit = selections,
+                fileLimit = limit,
+            )
+            val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
+                addCategory(Intent.CATEGORY_OPENABLE)
+                type = types.first
+                if (types.second.isNotEmpty()) putExtra(Intent.EXTRA_MIME_TYPES, types.second)
+                putExtra(Intent.EXTRA_ALLOW_MULTIPLE, selections > 1)
+                addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
+            }
+            try { host.startActivityForResult(intent, CRAFT_NATIVE_FILE_PICK_REQUEST) }
+            catch (error: Exception) {
+                pendingFilePick = null
+                complete(requestToken, failure("PICKER_UNAVAILABLE", error.message ?: "File picker could not be opened"), completion)
+            }
+        }
+    }
+
+    /** Android's picker accepts MIME filters; map the common UTI/extension forms used by the shared API. */
+    private fun documentTypes(values: JSONArray?): Pair<String, Array<String>>? {
+        if (values == null || values.length() == 0) return "*/*" to emptyArray()
+        val mime = mutableListOf<String>()
+        for (index in 0 until values.length()) {
+            val raw = values.optString(index).trim().lowercase()
+            if (raw.isBlank()) return null
+            val type = when (raw) {
+                "public.data", "public.item", "public.content" -> "*/*"
+                "public.image" -> "image/*"
+                "public.movie" -> "video/*"
+                "public.audio" -> "audio/*"
+                "public.text" -> "text/*"
+                else -> when {
+                    raw.contains('/') -> raw
+                    raw == "gpx" -> "application/gpx+xml"
+                    raw == "tcx" -> "application/vnd.garmin.tcx+xml"
+                    raw == "fit" -> "application/octet-stream"
+                    raw == "json" -> "application/json"
+                    raw == "csv" -> "text/csv"
+                    raw == "txt" -> "text/plain"
+                    raw == "pdf" -> "application/pdf"
+                    else -> return null
+                }
+            }
+            mime += type
+        }
+        val distinct = mime.distinct()
+        return if (distinct.size == 1) distinct.first() to emptyArray() else "*/*" to distinct.toTypedArray()
+    }
+
     fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?): Boolean {
         if (requestCode != CRAFT_NATIVE_FILE_PICK_REQUEST) return false
         val pending = pendingFilePick ?: return true
@@ -595,24 +672,45 @@ internal class CraftNativeCapabilities(
         }
         if (pending.source == "video") {
             networkExecutor.execute {
-                val result = data?.data?.let { copyVideo(it, pending.videoLimit) }
+                val result = data?.data?.let { copyVideo(pending.requestToken, it, pending.videoLimit) }
                     ?: failure("PICKER_FAILED", "The selected video could not be read")
                 complete(pending.requestToken, result, pending.completion)
             }
             return true
         }
-        val descriptor = if (pending.source == "camera") {
-            val bitmap = data?.extras?.get("data") as? Bitmap
-            bitmap?.let { writeImage(it, pending.maxPixels, pending.quality, "photo.jpg") }
-        } else {
-            val uri = data?.data
-            uri?.let { copyUri(it, pending.maxPixels, pending.quality) }
+        if (pending.source == "file") {
+            networkExecutor.execute {
+                val uris = buildList {
+                    data?.clipData?.let { clips ->
+                        for (index in 0 until clips.itemCount) add(clips.getItemAt(index).uri)
+                    }
+                    data?.data?.let { add(it) }
+                }.distinct().take(pending.selectionLimit)
+                val result = copyDocuments(pending.requestToken, uris, pending.fileLimit)
+                complete(pending.requestToken, result, pending.completion)
+            }
+            return true
+        }
+        networkExecutor.execute {
+            val descriptor = if (pending.source == "camera") {
+                val bitmap = data?.extras?.get("data") as? Bitmap
+                bitmap?.let { writeImage(it, pending.maxPixels, pending.quality, "photo.jpg", pending.requestToken) }
+            } else {
+                val uri = data?.data
+                uri?.let { copyUri(pending.requestToken, it, pending.maxPixels, pending.quality) }
+            }
+            complete(
+                pending.requestToken,
+                descriptor?.let(::success) ?: if (cancelled.contains(pending.requestToken)) failure("CANCELLED", "Image selection was cancelled")
+                else failure("PICKER_FAILED", "The selected image could not be read"),
+                pending.completion,
+            )
         }
-        complete(pending.requestToken, descriptor?.let(::success) ?: failure("PICKER_FAILED", "The selected image could not be read"), pending.completion)
         return true
     }
 
-    private fun copyUri(uri: Uri, maxPixels: Int, quality: Float): JSONObject? {
+    private fun copyUri(requestToken: String, uri: Uri, maxPixels: Int, quality: Float): JSONObject? {
+        if (cancelled.contains(requestToken)) return null
         val name = context.contentResolver.query(uri, arrayOf(android.provider.OpenableColumns.DISPLAY_NAME), null, null, null)?.use {
             if (it.moveToFirst()) it.getString(0) else null
         } ?: "photo"
@@ -623,10 +721,74 @@ internal class CraftNativeCapabilities(
         while (max(bounds.outWidth / sample, bounds.outHeight / sample) > maxPixels * 2) sample *= 2
         val options = BitmapFactory.Options().apply { inSampleSize = sample }
         val bitmap = context.contentResolver.openInputStream(uri)?.use { BitmapFactory.decodeStream(it, null, options) } ?: return null
-        return writeImage(bitmap, maxPixels, quality, jpegName(name))
+        return writeImage(bitmap, maxPixels, quality, jpegName(name), requestToken)
     }
 
-    private fun writeImage(bitmap: Bitmap, maxPixels: Int, quality: Float, name: String): JSONObject? {
+    private fun copyDocuments(requestToken: String, uris: List<Uri>, limit: Long): CraftNativeCapabilityResult {
+        if (uris.isEmpty()) return failure("PICKER_FAILED", "No document was selected")
+        val copied = JSONArray()
+        return try {
+            uris.forEach { copied.put(copyDocument(requestToken, it, limit)) }
+            if (cancelled.contains(requestToken)) throw IllegalStateException("CANCELLED: File selection was cancelled")
+            success(copied)
+        } catch (error: Exception) {
+            for (index in 0 until copied.length()) {
+                copied.optJSONObject(index)?.optString("path")?.let { ownedFile(it)?.parentFile?.deleteRecursively() }
+            }
+            val message = error.message ?: "The selected document could not be read"
+            if (message.startsWith("CANCELLED:")) failure("CANCELLED", message.removePrefix("CANCELLED:").trim())
+            else if (message.startsWith("FILE_TOO_LARGE:")) failure("FILE_TOO_LARGE", message.removePrefix("FILE_TOO_LARGE:").trim())
+            else failure("READ_ERROR", message)
+        }
+    }
+
+    private fun copyDocument(requestToken: String, uri: Uri, limit: Long): JSONObject {
+        var target: File? = null
+        return try {
+            val name = context.contentResolver.query(uri, arrayOf(android.provider.OpenableColumns.DISPLAY_NAME), null, null, null)?.use {
+                if (it.moveToFirst()) it.getString(0) else null
+            } ?: "file"
+            val type = context.contentResolver.getType(uri) ?: documentMimeType(name)
+            val destination = File(fileRoot, UUID.randomUUID().toString()).apply { mkdirs() }.resolve(safeFileName(name))
+            target = destination
+            val input = context.contentResolver.openInputStream(uri) ?: throw IllegalArgumentException("The selected document could not be read")
+            var size = 0L
+            input.use { source ->
+                destination.outputStream().use { output ->
+                    val buffer = ByteArray(64 * 1024)
+                    while (true) {
+                        val count = source.read(buffer)
+                        if (count < 0) break
+                        if (cancelled.contains(requestToken)) throw IllegalStateException("CANCELLED: File selection was cancelled")
+                        size += count
+                        require(size <= limit) { "FILE_TOO_LARGE: Choose a file under ${limit / 1024 / 1024}MB." }
+                        output.write(buffer, 0, count)
+                    }
+                }
+            }
+            require(size > 0) { "Choose a nonempty file." }
+            descriptor(destination, type)
+        } catch (error: Exception) {
+            target?.parentFile?.deleteRecursively()
+            throw error
+        }
+    }
+
+    private fun documentMimeType(name: String): String = when (name.substringAfterLast('.', "").lowercase()) {
+        "gpx" -> "application/gpx+xml"
+        "tcx" -> "application/vnd.garmin.tcx+xml"
+        "json" -> "application/json"
+        "csv" -> "text/csv"
+        "txt" -> "text/plain"
+        "pdf" -> "application/pdf"
+        else -> "application/octet-stream"
+    }
+
+    private fun writeImage(bitmap: Bitmap, maxPixels: Int, quality: Float, name: String, requestToken: String? = null): JSONObject? {
+        if (requestToken != null && cancelled.contains(requestToken)) {
+            bitmap.recycle()
+            return null
+        }
         val longest = max(bitmap.width, bitmap.height)
         val scale = if (longest > maxPixels) maxPixels.toFloat() / longest else 1f
         val output = if (scale < 1f) Bitmap.createScaledBitmap(
@@ -643,7 +805,15 @@ internal class CraftNativeCapabilities(
         }.getOrDefault(false)
         if (output !== bitmap) output.recycle()
         bitmap.recycle()
-        return if (written) descriptor(file, "image/jpeg").put("width", width).put("height", height) else null
+        if (!written) {
+            file.parentFile?.deleteRecursively()
+            return null
+        }
+        if (requestToken != null && cancelled.contains(requestToken)) {
+            file.parentFile?.deleteRecursively()
+            return null
+        }
+        return descriptor(file, "image/jpeg").put("width", width).put("height", height)
     }
 
     private fun store(bytes: ByteArray, name: String, type: String): CraftNativeCapabilityResult {

package/dist/android/templates/CraftNativeMapGoogle.kt.template

@@ -26,6 +26,7 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
     private var userChangingCamera = false
     private var markerBearings = mutableMapOf<String, Float>()
     private var markerPinColors = mutableMapOf<String, Int>()
+    private val markerPhotos = CraftMarkerPhotos(context) { if (!destroyed) applyPending() }
     private val pinIcons = mutableMapOf<Int, com.google.android.gms.maps.model.BitmapDescriptor>()
     private var directionIcon: com.google.android.gms.maps.model.BitmapDescriptor? = null
     private var lifecycleStarted = false
@@ -122,6 +123,7 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
         val nextMarkers = mutableMapOf<String, Pair<LatLng, String?>>()
         val nextBearings = mutableMapOf<String, Float>()
         val nextPinColors = mutableMapOf<String, Int>()
+        val nextPhotos = mutableMapOf<String, CraftMarkerPhoto>()
         val nextHandlers = mutableMapOf<String, String>()
         val nextPolylines = mutableMapOf<String, Triple<List<LatLng>, Int, Float>>()
         val nextPolygons = mutableMapOf<String, PolygonValue>()
@@ -131,6 +133,7 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
             val id = craftNativeOptionalString(overlay.opt("id")) ?: continue
             val point = coordinates(overlay.optJSONArray("geometry")).firstOrNull() ?: continue
             nextMarkers[id] = point to (overlay.opt("title") as? String)
+            CraftMarkerPhoto.from(overlay)?.let { nextPhotos[id] = it }
             (overlay.opt("pinColor") as? String)?.let { nextPinColors[id] = color(it) }
             (overlay.opt("bearing") as? Number)?.toDouble()?.takeIf { it.isFinite() }?.let { nextBearings[id] = (it % 360).toFloat() }
         }
@@ -161,6 +164,8 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
             if (type == "mapmarker" || type == "marker") {
                 points.firstOrNull()?.let { point ->
                     nextMarkers[id] = point to (props.opt("title") as? String)
+                    nextPhotos.remove(id)
+                    CraftMarkerPhoto.from(props)?.let { nextPhotos[id] = it }
                     (props.opt("pinColor") as? String)?.let { value -> nextPinColors[id] = color(value) }
                     (props.opt("bearing") as? Number)?.toDouble()?.takeIf { it.isFinite() }?.let { nextBearings[id] = (it % 360).toFloat() }
                     listOf(events.opt("onPress"), events.opt("onMarkerPress"))
@@ -203,19 +208,26 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
         }
         markerBearings = nextBearings
         markerPinColors = nextPinColors
+        markerPhotos.reconcile(nextPhotos)
         pinIcons.keys.filter { it !in markerPinColors.values }.forEach { pinIcons.remove(it) }
         markers.keys.filter { nextMarkers[it] == null }.forEach { markers.remove(it)?.remove() }
         for ((id, value) in nextMarkers) {
+            val photo = markerPhotos.bitmap(id)
+            val direction = photo == null && markerBearings.containsKey(id)
+            val icon = photo?.let(BitmapDescriptorFactory::fromBitmap)
+                ?: if (direction) directionMarkerIcon() else pinMarkerIcon(id)
+            val anchor = if (photo != null || direction || markerPinColors.containsKey(id)) 0.5f else 1f
             val marker = markers[id]
             if (marker != null) {
                 marker.position = value.first
                 marker.title = value.second
-                marker.setIcon(if (markerBearings.containsKey(id)) directionMarkerIcon() else pinMarkerIcon(id))
-                marker.isFlat = markerBearings.containsKey(id)
-                marker.rotation = markerBearings[id] ?: 0f
-                marker.setAnchor(0.5f, if (markerBearings.containsKey(id) || markerPinColors.containsKey(id)) 0.5f else 1f)
+                marker.setIcon(icon)
+                marker.isFlat = direction
+                marker.rotation = if (direction) markerBearings[id] ?: 0f else 0f
+                marker.setAnchor(0.5f, anchor)
             } else {
-                map.addMarker(MarkerOptions().position(value.first).title(value.second).icon(if (markerBearings.containsKey(id)) directionMarkerIcon() else pinMarkerIcon(id)).flat(markerBearings.containsKey(id)).rotation(markerBearings[id] ?: 0f).anchor(0.5f, if (markerBearings.containsKey(id) || markerPinColors.containsKey(id)) 0.5f else 1f))?.let { markers[id] = it }
+                map.addMarker(MarkerOptions().position(value.first).title(value.second).icon(icon).flat(direction)
+                    .rotation(if (direction) markerBearings[id] ?: 0f else 0f).anchor(0.5f, anchor))?.let { markers[id] = it }
             }
         }
         markerHandlers.clear()
@@ -445,6 +457,7 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
     fun destroy() {
         if (destroyed) return
         destroyed = true
+        markerPhotos.destroy()
         if (lifecycleStarted) {
             mapView.onPause()
             mapView.onStop()

package/dist/android/templates/CraftNativeMapLibre.kt.template

@@ -26,6 +26,8 @@ internal class CraftNativeMapView(context: Context) : FrameLayout(context), OnMa
     private var userChangingCamera = false
     private var geometryPoints = emptyList<LatLng>()
     private val markerHandlers = mutableMapOf<String, String>()
+    private val markerPhotos = CraftMarkerPhotos(context) { if (!destroyed) readyStyle?.let(::updateOverlays) }
+    private val installedPhotos = mutableMapOf<String, Bitmap>()
     private var onMarkerTap: ((String) -> Unit)? = null
     var onMapPress: ((LatLng) -> Unit)? = null
     var onRegionChangeComplete: ((JSONObject) -> Unit)? = null
@@ -83,7 +85,7 @@ internal class CraftNativeMapView(context: Context) : FrameLayout(context), OnMa
         nativeMap.addOnMapClickListener { point ->
             val screen = nativeMap.projection.toScreenLocation(point)
             val radius = 18 * resources.displayMetrics.density
-            val hit = nativeMap.queryRenderedFeatures(android.graphics.RectF(screen.x - radius, screen.y - radius, screen.x + radius, screen.y + radius), "craft-map-markers", "craft-map-directions").firstOrNull()
+            val hit = nativeMap.queryRenderedFeatures(android.graphics.RectF(screen.x - radius, screen.y - radius, screen.x + radius, screen.y + radius), "craft-map-markers", "craft-map-directions", "craft-map-photos").firstOrNull()
             val id = hit?.takeIf { it.hasProperty("craftMarkerId") }?.getStringProperty("craftMarkerId")
             if (id != null) onMarkerTap?.invoke(id) else onMapPress?.invoke(point)
             true
@@ -247,6 +249,7 @@ internal class CraftNativeMapView(context: Context) : FrameLayout(context), OnMa
         .put("type", "raster").put("tiles", JSONArray().put(url)).put("tileSize", 256).put("maxzoom", 19).put("attribution", credit)
 
     private fun installOverlays(style: Style) {
+        installedPhotos.clear()
         style.addSource(GeoJsonSource("craft-map-overlays"))
         style.addImage("craft-map-direction", directionBitmap())
         style.addLayer(LineLayer("craft-map-routes", "craft-map-overlays")
@@ -264,11 +267,29 @@ internal class CraftNativeMapView(context: Context) : FrameLayout(context), OnMa
         style.addLayer(SymbolLayer("craft-map-directions", "craft-map-overlays")
             .withFilter(Expression.eq(Expression.get("kind"), "direction"))
             .withProperties(iconImage("craft-map-direction"), iconRotate(Expression.get("bearing")), iconRotationAlignment("map"), iconAllowOverlap(true), iconIgnorePlacement(true), iconAnchor("center")))
+        style.addLayer(SymbolLayer("craft-map-photos", "craft-map-overlays")
+            .withFilter(Expression.eq(Expression.get("kind"), "photo"))
+            .withProperties(iconImage(Expression.get("photoIcon")), iconAllowOverlap(true), iconIgnorePlacement(true), iconAnchor("center")))
     }
 
     private fun updateOverlays(style: Style) {
         val features = JSONArray()
         val pointsForFit = mutableListOf<LatLng>()
+        val wantedPhotos = mutableMapOf<String, CraftMarkerPhoto>()
+        val usedImages = mutableSetOf<String>()
+        fun photo(id: String, props: JSONObject, properties: JSONObject) {
+            wantedPhotos.remove(id)
+            val spec = CraftMarkerPhoto.from(props) ?: return
+            wantedPhotos[id] = spec
+            val bitmap = markerPhotos.bitmap(id, spec) ?: return
+            val key = "craft-map-photo-${CraftNativeMedia.digest(id)}"
+            usedImages.add(key)
+            if (installedPhotos[key] !== bitmap) {
+                style.addImage(key, bitmap)
+                installedPhotos[key] = bitmap
+            }
+            properties.put("kind", "photo").put("photoIcon", key)
+        }
         markerHandlers.clear()
         val dataMarkers = pendingProps.optJSONArray("markers")
         for (index in 0 until (dataMarkers?.length() ?: 0)) {
@@ -282,6 +303,7 @@ internal class CraftNativeMapView(context: Context) : FrameLayout(context), OnMa
                 .put("craftMarkerId", id)
                 .put("bearing", (bearing ?: 0.0) % 360)
                 .put("color", cssColor(overlay.opt("pinColor"), Color.rgb(36, 114, 75)))
+            photo(id, overlay, properties)
             val geometry = JSONObject().put("type", "Point").put("coordinates", JSONArray().put(point.longitude).put(point.latitude))
             features.put(JSONObject().put("type", "Feature").put("properties", properties).put("geometry", geometry))
             pointsForFit.add(point)
@@ -320,6 +342,7 @@ internal class CraftNativeMapView(context: Context) : FrameLayout(context), OnMa
                 val bearing = finiteNumber(props.opt("bearing"))
                 properties.put("kind", if (bearing == null) "marker" else "direction").put("craftMarkerId", id)
                 properties.put("bearing", (bearing ?: 0.0) % 360).put("color", cssColor(props.opt("pinColor"), Color.rgb(36, 114, 75)))
+                photo(id, props, properties)
                 geometry.put("type", "Point").put("coordinates", JSONArray().put(point.longitude).put(point.latitude))
                 listOf(events.opt("onPress"), events.opt("onMarkerPress")).firstNotNullOfOrNull(::craftNativeOptionalString)?.let { markerHandlers[id] = it }
                 pointsForFit.add(point)
@@ -348,7 +371,9 @@ internal class CraftNativeMapView(context: Context) : FrameLayout(context), OnMa
             features.put(JSONObject().put("type", "Feature").put("properties", properties).put("geometry", geometry))
         }
         geometryPoints = pointsForFit
+        markerPhotos.reconcile(wantedPhotos)
         style.getSourceAs<GeoJsonSource>("craft-map-overlays")?.setGeoJson(JSONObject().put("type", "FeatureCollection").put("features", features).toString())
+        installedPhotos.keys.filter { it !in usedImages }.forEach { style.removeImage(it); installedPhotos.remove(it) }
     }
 
     private fun cssColor(value: Any?, fallback: Int): String {
@@ -521,6 +546,8 @@ internal class CraftNativeMapView(context: Context) : FrameLayout(context), OnMa
     fun destroy() {
         if (destroyed) return
         destroyed = true
+        markerPhotos.destroy()
+        installedPhotos.clear()
         styleVersion++
         onMarkerTap = null; onMapPress = null; onRegionChangeComplete = null
         markerHandlers.clear(); geometryPoints = emptyList()

package/dist/android/templates/CraftNativeMutation.kt.template

@@ -162,6 +162,9 @@ class CraftNativeMutationDocument {
         )
     }
 
+    /** The committed root may have any protocol id supplied by the compiler. */
+    fun document(): JSONObject? = rootId?.let { materialize(it, nodes) }
+
     fun node(id: String): JSONObject? = materialize(id, nodes)
 
     /** Reserve surviving protocol nodes before reusing an authored keyed slot. */

package/dist/android/templates/CraftNativeShell.kt.template

@@ -373,6 +373,10 @@ internal class CraftNativeStores private constructor(
 
     /** `craft.snapshots.set`: null deletes it. `done` hears whether it was kept, on the main thread. */
     fun setSnapshot(name: String, json: String?, from: String?, done: (Boolean) -> Unit) {
+        if (!isSnapshotName(name)) {
+            main.post { done(false) }
+            return
+        }
         writer.execute {
             val file = snapshotFile(name)
             val previous = snapshotCache[name]
@@ -422,6 +426,8 @@ internal class CraftNativeStores private constructor(
         CraftNativeHub.broadcast("SYNC_UPDATE", payload, except = from)
     }
 
+    private fun isSnapshotName(name: String): Boolean = name.matches(Regex("[A-Za-z0-9_-][A-Za-z0-9_.-]{0,127}"))
+
     private fun snapshotFile(name: String): File = File(snapshotsDir, URLEncoder.encode(name, "UTF-8") + ".json")
 
     private fun snapshotName(file: File): String? =
@@ -659,6 +665,9 @@ internal object CraftNativePrelude {
             if (json === null || json === undefined) return null;
             try { return JSON.parse(json); } catch (error) { return null; }
           }
+          function validSnapshotName(name) {
+            return /^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,127}$/.test(name);
+          }
           var craft = globalThis.craft = globalThis.craft || {};
           function keep(name, extras) {
             var current = {};
@@ -681,12 +690,18 @@ internal object CraftNativePrelude {
             }
           });
           keep('snapshots', {
-            get: function(name) { return parsed(sync.snapshots[String(name)]); },
+            get: function(name) {
+              name = String(name);
+              return validSnapshotName(name) ? parsed(sync.snapshots[name]) : null;
+            },
             set: function(name, value) {
-              var json = value === null || value === undefined ? null : JSON.stringify(value);
-              if (json === null) delete sync.snapshots[String(name)];
-              else sync.snapshots[String(name)] = json;
-              return wait('snapshots.set', { store: 'snapshots', key: String(name), value: json });
+              name = String(name);
+              if (!validSnapshotName(name)) return Promise.reject(new TypeError('Snapshot names are letters, digits, ".", "_" and "-"'));
+              var json = value === null ? null : JSON.stringify(value);
+              if (json === undefined) return Promise.reject(new TypeError('Snapshot ' + name + ' is not JSON'));
+              if (json === null) delete sync.snapshots[name];
+              else sync.snapshots[name] = json;
+              return wait('snapshots.set', { store: 'snapshots', key: name, value: json });
             },
             clear: function(keepNames) {
               var names = Array.isArray(keepNames) ? keepNames.map(String) : [];