craft-native 0.0.235 → 0.0.237

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

@@ -43,6 +43,7 @@ import kotlin.math.roundToInt
 private const val CRAFT_NATIVE_FETCH_MAX_RESPONSE_BYTES = 8 * 1024 * 1024
 private const val CRAFT_NATIVE_FETCH_TIMEOUT_MS = 30_000
 private const val CRAFT_NATIVE_FILE_PICK_REQUEST = 4101
+private const val CRAFT_NATIVE_NOTIFICATION_PERMISSION_REQUEST = 4102
 private const val CRAFT_NATIVE_FILE_DEFAULT_MAX_PIXELS = 2048
 private const val CRAFT_NATIVE_FILE_LARGEST_MAX_PIXELS = 8192
 private const val CRAFT_NATIVE_FILE_DEFAULT_QUALITY = 0.85
@@ -88,6 +89,7 @@ internal class CraftNativeCapabilities(
     private val fetchConnections = ConcurrentHashMap<String, HttpURLConnection>()
     private val fileRoot by lazy { File(context.cacheDir, "craft-files").apply { mkdirs() } }
     private var pendingFilePick: PendingFilePick? = null
+    private var pendingNotificationPermission: ((Boolean) -> Unit)? = null
     private var database: SQLiteDatabase? = null
     private val biometricPrompts = ConcurrentHashMap<String, BiometricPrompt>()
 
@@ -891,7 +893,16 @@ internal class CraftNativeCapabilities(
             return
         }
         when (method) {
-            "schedule" -> complete(requestToken, schedule(args.optJSONObject(0)), completion)
+            "schedule" -> {
+                val notification = args.optJSONObject(0)
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU && ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) != PackageManager.PERMISSION_GRANTED) {
+                    val host = activity
+                    if (host == null) { complete(requestToken, failure("PERMISSION_DENIED", "Notification permission must be requested while the app is open"), completion); return }
+                    if (pendingNotificationPermission != null) { complete(requestToken, failure("BUSY", "A notification permission request is already open"), completion); return }
+                    pendingNotificationPermission = { granted -> complete(requestToken, if (granted) schedule(notification) else failure("PERMISSION_DENIED", "Notification permission denied"), completion) }
+                    mainHandler.post { androidx.core.app.ActivityCompat.requestPermissions(host, arrayOf(Manifest.permission.POST_NOTIFICATIONS), CRAFT_NATIVE_NOTIFICATION_PERMISSION_REQUEST) }
+                } else complete(requestToken, schedule(notification), completion)
+            }
             "cancel" -> {
                 val id = validKey(args.opt(0))
                 complete(requestToken, if (id == null) failure("INVALID_ARGUMENT", "Notifications.cancel needs an id")
@@ -909,6 +920,13 @@ internal class CraftNativeCapabilities(
         }
     }
 
+    fun onNotificationPermissions(requestCode: Int) {
+        if (requestCode != CRAFT_NATIVE_NOTIFICATION_PERMISSION_REQUEST) return
+        val complete = pendingNotificationPermission ?: return
+        pendingNotificationPermission = null
+        complete(Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU || ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED)
+    }
+
     private fun schedule(value: JSONObject?): CraftNativeCapabilityResult {
         val title = value?.optString("title").orEmpty()
         if (title.isEmpty()) return failure("INVALID_ARGUMENT", "Notifications.schedule needs a title")

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

@@ -600,19 +600,43 @@ private class CraftNativeSvgView(context: Context) : View(context) {
 /** The Android host for the small, host-neutral native trail map contract. */
 private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMapReadyCallback {
     private val mapView = MapView(context)
+    private val scaleView = LinearLayout(context).apply {
+        orientation = LinearLayout.VERTICAL
+        setPadding(4, 2, 4, 2)
+        background = GradientDrawable().apply { setColor(Color.argb(230, 255, 255, 255)); cornerRadius = 4f }
+        importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO
+    }
+    private val scaleLabel = TextView(context).apply { textSize = 11f; setTextColor(Color.rgb(37, 51, 33)) }
+    private val scaleLine = View(context).apply { setBackgroundColor(Color.rgb(37, 51, 33)) }
     private var googleMap: GoogleMap? = null
+    private var tileOverlay: com.google.android.gms.maps.model.TileOverlay? = null
+    private var tileTemplate: String? = null
+    private val tileAttribution = TextView(context).apply { textSize = 9f; setTextColor(Color.DKGRAY); setBackgroundColor(Color.argb(220, 255, 255, 255)); maxLines = 2; visibility = View.GONE }
     private var pendingProps = JSONObject()
     private var pendingChildren = JSONArray()
     private val markers = mutableMapOf<String, Marker>()
     private val polylines = mutableMapOf<String, Polyline>()
     private val markerHandlers = mutableMapOf<String, String>()
     private var onMarkerTap: ((String) -> Unit)? = null
+    var onMapPress: ((LatLng) -> Unit)? = null
+    var onRegionChangeComplete: ((JSONObject) -> Unit)? = null
+    private var userChangingCamera = false
+    private var markerBearings = mutableMapOf<String, Float>()
+    private var directionIcon: com.google.android.gms.maps.model.BitmapDescriptor? = null
     private var lifecycleStarted = false
     private var destroyed = false
     private var initialCameraKey: String? = null
 
     init {
         addView(mapView, LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT))
+        scaleView.addView(scaleLabel)
+        scaleView.addView(scaleLine, LinearLayout.LayoutParams(1, 2))
+        addView(scaleView, LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT, Gravity.BOTTOM or Gravity.START).apply {
+            leftMargin = (8 * resources.displayMetrics.density).roundToInt()
+            bottomMargin = (24 * resources.displayMetrics.density).roundToInt()
+        })
+        scaleView.visibility = View.GONE
+        addView(tileAttribution, LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT, Gravity.BOTTOM or Gravity.END).apply { rightMargin = (8 * resources.displayMetrics.density).roundToInt(); bottomMargin = (8 * resources.displayMetrics.density).roundToInt() })
         mapView.onCreate(null)
         mapView.getMapAsync(this)
     }
@@ -620,6 +644,24 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
     override fun onMapReady(map: GoogleMap) {
         if (destroyed) return
         googleMap = map
+        map.setOnMapClickListener { point -> onMapPress?.invoke(point) }
+        map.setOnCameraMoveStartedListener { reason ->
+            if (reason == GoogleMap.OnCameraMoveStartedListener.REASON_GESTURE) userChangingCamera = true
+        }
+        map.setOnCameraMoveListener { updateScale() }
+        map.setOnCameraIdleListener {
+            updateScale()
+            if (userChangingCamera) {
+                userChangingCamera = false
+                val bounds = map.projection.visibleRegion.latLngBounds
+                val position = map.cameraPosition
+                val longitudeDelta = (bounds.northeast.longitude - bounds.southwest.longitude + 360) % 360
+                onRegionChangeComplete?.invoke(JSONObject()
+                    .put("center", JSONObject().put("latitude", position.target.latitude).put("longitude", position.target.longitude))
+                    .put("span", JSONObject().put("latitudeDelta", bounds.northeast.latitude - bounds.southwest.latitude).put("longitudeDelta", longitudeDelta))
+                    .put("heading", position.bearing).put("pitch", position.tilt))
+            }
+        }
         map.setOnMarkerClickListener { marker ->
             val id = markers.entries.firstOrNull { it.value == marker }?.key ?: return@setOnMarkerClickListener false
             onMarkerTap?.invoke(id)
@@ -642,6 +684,10 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
 
     private fun applyPending() {
         val map = googleMap ?: return
+        applyMapPadding()
+        map.uiSettings.isCompassEnabled = craftNativeBoolean(pendingProps.opt("showsCompass"))
+        // The toolbar is replaced by authored actions; the scale uses the native projection.
+        map.uiSettings.isMapToolbarEnabled = false
         map.uiSettings.isScrollGesturesEnabled = craftNativeBoolean(pendingProps.opt("scrollEnabled"), true)
         map.uiSettings.isZoomGesturesEnabled = craftNativeBoolean(pendingProps.opt("zoomEnabled"), true)
         map.uiSettings.isRotateGesturesEnabled = craftNativeBoolean(pendingProps.opt("rotateEnabled"))
@@ -651,9 +697,11 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
             "terrain" -> GoogleMap.MAP_TYPE_TERRAIN
             else -> GoogleMap.MAP_TYPE_NORMAL
         }
+        applyTileOverlay()
         val showUserLocation = craftNativeBoolean(pendingProps.opt("showsUserLocation")) && hasLocationPermission()
         runCatching { map.isMyLocationEnabled = showUserLocation }
         val nextMarkers = mutableMapOf<String, Pair<LatLng, String?>>()
+        val nextBearings = mutableMapOf<String, Float>()
         val nextHandlers = mutableMapOf<String, String>()
         val nextPolylines = mutableMapOf<String, Triple<List<LatLng>, Int, Float>>()
         for (index in 0 until pendingChildren.length()) {
@@ -668,6 +716,7 @@ 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)
+                    (props.opt("bearing") as? Number)?.toDouble()?.takeIf { it.isFinite() }?.let { nextBearings[id] = (it % 360).toFloat() }
                     listOf(events.opt("onPress"), events.opt("onMarkerPress"))
                         .firstNotNullOfOrNull(::craftNativeOptionalString)
                         ?.let { nextHandlers[id] = it }
@@ -694,14 +743,19 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
                 }
             }
         }
+        markerBearings = nextBearings
         markers.keys.filter { nextMarkers[it] == null }.forEach { markers.remove(it)?.remove() }
         for ((id, value) in nextMarkers) {
             val marker = markers[id]
             if (marker != null) {
                 marker.position = value.first
                 marker.title = value.second
+                marker.setIcon(if (markerBearings.containsKey(id)) directionMarkerIcon() else BitmapDescriptorFactory.defaultMarker())
+                marker.isFlat = markerBearings.containsKey(id)
+                marker.rotation = markerBearings[id] ?: 0f
+                marker.setAnchor(0.5f, if (markerBearings.containsKey(id)) 0.5f else 1f)
             } else {
-                map.addMarker(MarkerOptions().position(value.first).title(value.second).icon(BitmapDescriptorFactory.defaultMarker()))?.let { markers[id] = it }
+                map.addMarker(MarkerOptions().position(value.first).title(value.second).icon(if (markerBearings.containsKey(id)) directionMarkerIcon() else BitmapDescriptorFactory.defaultMarker()).flat(markerBearings.containsKey(id)).rotation(markerBearings[id] ?: 0f).anchor(0.5f, if (markerBearings.containsKey(id)) 0.5f else 1f))?.let { markers[id] = it }
             }
         }
         markerHandlers.clear()
@@ -734,17 +788,99 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
                 initialCameraKey = key
             }
         } else if (craftNativeBoolean(pendingProps.opt("fitToBounds"))) {
-            val key = "fit:${overlayKey(nextMarkers, nextPolylines)}"
+            val key = "fit:${overlayKey(nextMarkers, nextPolylines)}:${pendingProps.optJSONObject("edgePadding")}"
             if (initialCameraKey != key) {
                 if (fitToBounds()) initialCameraKey = key
             }
         } else {
             initialCameraKey = null
         }
+        applyCameraOrientation()
+        updateScale()
+    }
+
+    private fun applyTileOverlay() {
+        val map = googleMap ?: return
+        val options = pendingProps.optJSONObject("tileOverlay")
+        val template = options?.optString("urlTemplate").orEmpty()
+        val credit = options?.optString("attribution").orEmpty()
+        val next = template.takeIf { it.startsWith("https://") && listOf("{z}", "{x}", "{y}").all { key -> it.contains(key) } && credit.isNotBlank() }
+        if (next != tileTemplate) {
+            tileOverlay?.remove(); tileOverlay = null; tileTemplate = next
+            if (next != null) {
+                val provider = object : com.google.android.gms.maps.model.UrlTileProvider(256, 256) {
+                    override fun getTileUrl(x: Int, y: Int, zoom: Int): java.net.URL? = runCatching { java.net.URL(next.replace("{x}", x.toString()).replace("{y}", y.toString()).replace("{z}", zoom.toString())) }.getOrNull()
+                }
+                tileOverlay = map.addTileOverlay(com.google.android.gms.maps.model.TileOverlayOptions().tileProvider(provider).zIndex(-1f))
+            }
+        }
+        if (next != null) map.mapType = GoogleMap.MAP_TYPE_NONE
+        tileAttribution.text = credit
+        tileAttribution.visibility = if (next == null) View.GONE else View.VISIBLE
+    }
+
+    private fun applyMapPadding() {
+        val authored = pendingProps.optJSONObject("edgePadding")
+        fun inset(name: String): Double = (authored?.opt(name) as? Number)?.toDouble()?.takeIf { it.isFinite() }?.coerceIn(0.0, 10_000.0)?.times(resources.displayMetrics.density) ?: 0.0
+        var left = inset("left"); var top = inset("top"); var right = inset("right"); var bottom = inset("bottom")
+        val horizontal = left + right
+        val vertical = top + bottom
+        val availableWidth = (width - 40 * resources.displayMetrics.density).coerceAtLeast(0f).toDouble()
+        val availableHeight = (height - 40 * resources.displayMetrics.density).coerceAtLeast(0f).toDouble()
+        if (horizontal > availableWidth && horizontal > 0) { left *= availableWidth / horizontal; right *= availableWidth / horizontal }
+        if (vertical > availableHeight && vertical > 0) { top *= availableHeight / vertical; bottom *= availableHeight / vertical }
+        googleMap?.setPadding(left.roundToInt(), top.roundToInt(), right.roundToInt(), bottom.roundToInt())
+    }
+
+    private fun updateScale() {
+        val map = googleMap ?: return
+        if (!craftNativeBoolean(pendingProps.opt("showsScale")) || width <= 0 || height <= 0) { scaleView.visibility = View.GONE; return }
+        val maximumWidth = (80 * resources.displayMetrics.density).roundToInt()
+        val origin = map.projection.fromScreenLocation(android.graphics.Point(width / 2, height / 2))
+        val end = map.projection.fromScreenLocation(android.graphics.Point(width / 2 + maximumWidth, height / 2))
+        val distance = FloatArray(1)
+        android.location.Location.distanceBetween(origin.latitude, origin.longitude, end.latitude, end.longitude, distance)
+        val metres = distance[0].toDouble()
+        if (!metres.isFinite() || metres <= 0) { scaleView.visibility = View.GONE; return }
+        val magnitude = Math.pow(10.0, kotlin.math.floor(kotlin.math.log10(metres)))
+        val length = listOf(5.0, 2.0, 1.0).firstOrNull { it * magnitude <= metres }?.times(magnitude) ?: magnitude
+        scaleLabel.text = if (length >= 1000) "${length / 1000} km" else "${length.roundToInt()} m"
+        scaleLine.layoutParams = LinearLayout.LayoutParams((maximumWidth * length / metres).roundToInt().coerceAtLeast(1), 2)
+        scaleView.visibility = View.VISIBLE
+    }
+
+    private fun applyCameraOrientation() {
+        val map = googleMap ?: return
+        val camera = map.cameraPosition
+        val pitch = (pendingProps.opt("cameraPitch") as? Number)?.toDouble()?.takeIf { it.isFinite() }?.coerceIn(0.0, 60.0)?.toFloat() ?: camera.tilt
+        val heading = (pendingProps.opt("cameraHeading") as? Number)?.toDouble()?.takeIf { it.isFinite() }?.toFloat() ?: camera.bearing
+        if (kotlin.math.abs(camera.tilt - pitch) > 0.01f || kotlin.math.abs(camera.bearing - heading) > 0.01f) {
+            map.moveCamera(CameraUpdateFactory.newCameraPosition(com.google.android.gms.maps.model.CameraPosition.Builder(camera).tilt(pitch).bearing(heading).build()))
+        }
+    }
+
+    private fun directionMarkerIcon(): com.google.android.gms.maps.model.BitmapDescriptor {
+        directionIcon?.let { return it }
+        val size = (26 * resources.displayMetrics.density).roundToInt().coerceAtLeast(24)
+        val bitmap = Bitmap.createBitmap(size, size, Bitmap.Config.ARGB_8888)
+        val canvas = Canvas(bitmap)
+        val paint = Paint(Paint.ANTI_ALIAS_FLAG)
+        paint.color = Color.WHITE
+        canvas.drawCircle(size / 2f, size / 2f, size / 2f, paint)
+        paint.color = Color.rgb(36, 114, 75)
+        canvas.drawCircle(size / 2f, size / 2f, size * 0.43f, paint)
+        paint.color = Color.WHITE
+        paint.textSize = size * 0.76f
+        paint.textAlign = Paint.Align.CENTER
+        paint.typeface = Typeface.DEFAULT_BOLD
+        canvas.drawText("↑", size / 2f, size / 2f - (paint.ascent() + paint.descent()) / 2, paint)
+        return BitmapDescriptorFactory.fromBitmap(bitmap).also { directionIcon = it }
     }
 
     override fun onSizeChanged(width: Int, height: Int, oldWidth: Int, oldHeight: Int) {
         super.onSizeChanged(width, height, oldWidth, oldHeight)
+        applyMapPadding()
+        updateScale()
         // MapView can become ready before its host has a usable viewport. Do
         // not mark a fit as complete until the camera update can be issued.
         if (width > 0 && height > 0 && craftNativeBoolean(pendingProps.opt("fitToBounds")) && initialCameraKey == null) {
@@ -754,7 +890,10 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
 
     private fun moveCamera(bounds: LatLngBounds, padding: Int = 24) {
         post {
-            if (width > 0 && height > 0) googleMap?.moveCamera(CameraUpdateFactory.newLatLngBounds(bounds, padding))
+            if (width > 0 && height > 0) {
+                googleMap?.moveCamera(CameraUpdateFactory.newLatLngBounds(bounds, padding))
+                applyCameraOrientation()
+            }
         }
     }
 
@@ -780,7 +919,12 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
         polylines.values.flatMap { it.points }.forEach { builder.include(it); count++ }
         if (count == 0) return false
         post {
-            if (width > 0 && height > 0) map.moveCamera(CameraUpdateFactory.newLatLngBounds(builder.build(), 24))
+            if (width > 0 && height > 0) {
+                applyMapPadding()
+                val padding = if (pendingProps.has("edgePadding")) 0 else (24 * resources.displayMetrics.density).roundToInt()
+                map.moveCamera(CameraUpdateFactory.newLatLngBounds(builder.build(), padding))
+                applyCameraOrientation()
+            }
         }
         return true
     }
@@ -811,6 +955,10 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
             lifecycleStarted = false
         }
         onMarkerTap = null
+        onMapPress = null
+        onRegionChangeComplete = null
+        directionIcon = null
+        tileOverlay?.remove(); tileOverlay = null
         markerHandlers.clear()
         markers.values.forEach { it.remove() }
         markers.clear()
@@ -866,8 +1014,146 @@ private class CraftNativeMapView(context: Context) : FrameLayout(context), OnMap
     private fun color(value: String): Int = runCatching { craftNativeColor(value) }.getOrDefault(Color.BLUE)
 }
 
+/** A finite celebration owned by a View, never by the JavaScript frame loop. */
+internal class CraftNativeCelebration(private val view: View) {
+    private var request: Pair<Double, Boolean>? = null
+    private var pending = false
+    private var animator: ValueAnimator? = null
+    private var decoration: Drawable? = null
+    private var root: View? = null
+    private var radius = 0f
+    var starts = 0
+        private set
+    val isRunning: Boolean get() = animator != null
+
+    fun configure(raw: JSONObject?, radius: Float) {
+        val replay = craftNativeNumber(raw?.opt("replay"))?.takeIf { it >= 0 }
+        val next = replay?.let { it to (raw?.opt("enabled") != false) }
+        this.radius = radius
+        if (next == request) return
+        stop()
+        request = next
+        pending = next?.second == true
+        view.requestLayout()
+    }
+
+    fun stop() {
+        pending = false
+        animator?.removeAllUpdateListeners()
+        animator?.removeAllListeners()
+        animator?.cancel()
+        animator = null
+        decoration?.let { root?.overlay?.remove(it) }
+        decoration = null
+        root = null
+        view.clearAnimation()
+    }
+
+    fun layout(animationsEnabled: Boolean = ValueAnimator.areAnimatorsEnabled()) {
+        if (!pending || !view.isAttachedToWindow || !view.isShown || view.width <= 0 || view.height <= 0) return
+        pending = false
+        if (!animationsEnabled) return
+        starts += 1
+        val root = view.rootView
+        this.root = root
+        val at = IntArray(2)
+        val origin = IntArray(2)
+        view.getLocationInWindow(at)
+        root.getLocationInWindow(origin)
+        val frame = RectF((at[0] - origin[0]).toFloat(), (at[1] - origin[1]).toFloat(), (at[0] - origin[0] + view.width).toFloat(), (at[1] - origin[1] + view.height).toFloat())
+        val density = view.resources.displayMetrics.density
+        var progress = 0f
+        val paint = Paint(Paint.ANTI_ALIAS_FLAG)
+        val colors = intArrayOf(Color.rgb(59, 130, 246), Color.rgb(153, 246, 228), Color.rgb(230, 196, 140), Color.WHITE)
+        val decoration = object : Drawable() {
+            override fun draw(canvas: Canvas) {
+                for (index in 0 until 52) {
+                    val side = if (index % 2 == 0) -1f else 1f
+                    val spread = (index * 37 % 101) / 100f
+                    val t = ((progress * 3f - (index % 7) * .018f) / (2.2f + spread * .45f)).coerceIn(0f, 1f)
+                    if (t <= 0 || t >= 1) continue
+                    val startX = frame.centerX() + side * frame.width() * .42f
+                    val startY = frame.top + 28 * density
+                    val endX = frame.centerX() + side * (35 * density + spread * root.width * .7f)
+                    val endY = root.height + 30 * density
+                    val x = startX + (endX - startX) * t
+                    val y = startY + (endY - startY) * t * t - (70 + spread * 100) * density * 4 * t * (1 - t)
+                    val saved = canvas.save()
+                    canvas.translate(x, y)
+                    canvas.rotate(side * (index * 30f + t * (400 + spread * 600)))
+                    paint.shader = null
+                    paint.color = colors[index % colors.size]
+                    paint.alpha = (255 * min(1f, min(t / .04f, (1 - t) / .3f))).roundToInt()
+                    canvas.drawRoundRect(RectF(-3 * density, -5 * density, (if (index % 3 == 0) 1 else 4) * density, 6 * density), density, density, paint)
+                    canvas.restoreToCount(saved)
+                }
+                val light = (progress * 3f - .55f) / 1.15f
+                if (light > 0 && light < 1) {
+                    val saved = canvas.save()
+                    val mask = Path().apply { addRoundRect(frame, radius, radius, Path.Direction.CW) }
+                    canvas.clipPath(mask)
+                    val x = frame.left - frame.width() + light * frame.width() * 3
+                    paint.alpha = 255
+                    paint.shader = LinearGradient(x - frame.width() * .25f, frame.top, x + frame.width() * .25f, frame.bottom, intArrayOf(Color.TRANSPARENT, 0x33ffffff, Color.TRANSPARENT), null, Shader.TileMode.CLAMP)
+                    canvas.drawRect(frame, paint)
+                    paint.shader = null
+                    canvas.restoreToCount(saved)
+                }
+            }
+            override fun setAlpha(alpha: Int) {}
+            override fun setColorFilter(colorFilter: ColorFilter?) {}
+            @Deprecated("Deprecated in Java")
+            override fun getOpacity(): Int = PixelFormat.TRANSLUCENT
+        }
+        decoration.setBounds(0, 0, root.width, root.height)
+        this.decoration = decoration
+        root.overlay.add(decoration)
+        // Classic view animations leave authored transform properties intact.
+        val entrance = android.view.animation.AnimationSet(true).apply {
+            addAnimation(android.view.animation.ScaleAnimation(.86f, 1f, .86f, 1f, android.view.animation.Animation.RELATIVE_TO_SELF, .5f, android.view.animation.Animation.RELATIVE_TO_SELF, .5f))
+            addAnimation(android.view.animation.TranslateAnimation(0f, 0f, 34 * density, 0f))
+            addAnimation(android.view.animation.RotateAnimation(-2.6f, 0f, android.view.animation.Animation.RELATIVE_TO_SELF, .5f, android.view.animation.Animation.RELATIVE_TO_SELF, .5f))
+            duration = 950
+            interpolator = android.view.animation.OvershootInterpolator(.65f)
+        }
+        view.startAnimation(entrance)
+        val clock = ValueAnimator.ofFloat(0f, 1f)
+        animator = clock
+        clock.apply {
+            duration = 3000
+            interpolator = LinearInterpolator()
+            addUpdateListener {
+                if (!ValueAnimator.areAnimatorsEnabled()) { stop(); return@addUpdateListener }
+                progress = it.animatedValue as Float
+                decoration.invalidateSelf()
+            }
+            addListener(object : android.animation.AnimatorListenerAdapter() {
+                override fun onAnimationEnd(animation: android.animation.Animator) { stop() }
+            })
+            start()
+        }
+    }
+}
+
 /** A deterministic flex-shaped container shared by normal views and scroll content. */
 private class CraftNativeFlexLayout(context: Context) : LinearLayout(context) {
+    private var celebration: CraftNativeCelebration? = null
+    fun configureCelebration(raw: JSONObject?, radius: Float) {
+        if (raw != null && celebration == null) celebration = CraftNativeCelebration(this)
+        celebration?.configure(raw, radius)
+    }
+    override fun onDetachedFromWindow() {
+        celebration?.stop()
+        super.onDetachedFromWindow()
+    }
+    override fun onVisibilityChanged(changedView: View, visibility: Int) {
+        super.onVisibilityChanged(changedView, visibility)
+        if (visibility != View.VISIBLE) celebration?.stop()
+    }
+    override fun onWindowVisibilityChanged(visibility: Int) {
+        super.onWindowVisibilityChanged(visibility)
+        if (visibility != View.VISIBLE) celebration?.stop()
+    }
     var onLayoutChanged: (() -> Unit)? = null
     private val styles = mutableMapOf<View, CraftNativeLayoutStyle>()
     private var wrap = false
@@ -1770,6 +2056,7 @@ private class CraftNativeFlexLayout(context: Context) : LinearLayout(context) {
     }
 
     override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
+        celebration?.layout()
         widthDefinite = true
         if (grid) {
             val layout = gridLayout(width, height)
@@ -5607,6 +5894,16 @@ class MainActivity : AppCompatActivity() {
             }
             "Map" -> (previous as? CraftNativeMapView ?: CraftNativeMapView(this)).apply {
                 val mapMarkerHandler = craftNativeOptionalString(events.opt("onMarkerPress"))
+                onMapPress = { point ->
+                    craftNativeOptionalString(events.opt("onPress"))?.let { handler ->
+                        send(screen, "EVENT", JSONObject().put("handlerName", handler).put("nativeEvent", JSONObject().put("latitude", point.latitude).put("longitude", point.longitude)))
+                    }
+                }
+                onRegionChangeComplete = { region ->
+                    craftNativeOptionalString(events.opt("onRegionChangeComplete"))?.let { handler ->
+                        send(screen, "EVENT", JSONObject().put("handlerName", handler).put("nativeEvent", region))
+                    }
+                }
                 configure(props, children) { markerId ->
                     (markerHandler(markerId) ?: mapMarkerHandler)?.let { handler ->
                         send(screen, "EVENT", JSONObject().put("handlerName", handler).put("nativeEvent", JSONObject().put("id", markerId)))
@@ -5749,6 +6046,7 @@ class MainActivity : AppCompatActivity() {
             }
         }
         if (control is CraftNativeFlexLayout) {
+            control.configureCelebration(props.optJSONObject("celebration"), ((craftNativeNumber(style.opt("borderRadius")) ?: 0.0) * resources.displayMetrics.density).toFloat())
             control.onLayoutChanged = { if (screen.active) emitLayoutEvents(screen) }
         } else if (control is CraftNativeKeyboardAvoidingView) {
             control.content.onLayoutChanged = { if (screen.active) emitLayoutEvents(screen) }
@@ -7013,7 +7311,7 @@ class MainActivity : AppCompatActivity() {
 
     override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {
         super.onRequestPermissionsResult(requestCode, permissions, grantResults)
-        if (::capabilities.isInitialized) capabilities.onBluetoothPermissions(requestCode)
+        if (::capabilities.isInitialized) { capabilities.onBluetoothPermissions(requestCode); capabilities.onNotificationPermissions(requestCode) }
         if (::services.isInitialized) services.onRequestPermissionsResult(requestCode)
     }
 

package/dist/cli.js

@@ -3424,7 +3424,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.235";
+var version = "0.0.237";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/components/index.d.ts

@@ -491,6 +491,18 @@ export interface MapProps extends BaseProps {
     region?: MapRegion;
     /** Initial camera region; applied once, then controlled by subsequent props. */
     initialRegion?: MapRegion;
+    /** A native raster basemap, with required provider attribution. */
+    tileOverlay?: {
+        urlTemplate: string;
+        attribution: string;
+    };
+    /** Logical points reserved for floating controls when fitting overlays. */
+    edgePadding?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
     fitToBounds?: boolean;
     showsUserLocation?: boolean;
     scrollEnabled?: boolean;
@@ -498,6 +510,25 @@ export interface MapProps extends BaseProps {
     rotateEnabled?: boolean;
     /** Map styles implemented consistently by the maintained iOS and Android hosts. */
     mapType?: 'standard' | 'satellite' | 'hybrid';
+    showsCompass?: boolean;
+    showsScale?: boolean;
+    /** Requested tilt in degrees; the platform may lower it for the current altitude or map type. */
+    cameraPitch?: number;
+    cameraHeading?: number;
+    /** A coordinate tapped on the map, excluding annotation presses. */
+    onPress?: (event: {
+        nativeEvent: {
+            latitude: number;
+            longitude: number;
+        };
+    }) => void;
+    /** Settled camera after a person pans, rotates, zooms or tilts the map. */
+    onRegionChangeComplete?: (event: {
+        nativeEvent: MapRegion & {
+            heading: number;
+            pitch: number;
+        };
+    }) => void;
     onMarkerPress?: (event: {
         nativeEvent: {
             id: string;
@@ -513,6 +544,8 @@ export interface MapMarkerProps extends BaseProps {
     geometry: number[];
     id: string;
     title?: string;
+    /** A direction arrow in place of the default marker, clockwise from north. */
+    bearing?: number;
     onPress?: (event: {
         nativeEvent: {
             id: string;

package/dist/index.cjs

@@ -309,7 +309,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.235";
+var version = "0.0.237";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/index.js

@@ -57,7 +57,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.235";
+var version = "0.0.237";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/ios/src/app-shortcuts.d.ts

@@ -0,0 +1,11 @@
+export interface CraftAppShortcut {
+    id: string;
+    title: string;
+    subtitle?: string;
+    symbol: string;
+    url: string;
+    /** Each phrase includes exactly one `{app}` token for Siri's app name. */
+    phrases: string[];
+}
+/** Build-owned App Intents survive shell restoration and need no app Swift. */
+export declare function appShortcutsSwift(shortcuts?: CraftAppShortcut[], schemes?: string[]): string;

package/dist/ios/src/index.d.ts

@@ -3,12 +3,14 @@
  *
  * Generates native iOS apps from web content using WKWebView.
  */
+import { type CraftAppShortcut } from './app-shortcuts.js';
 /** Package custom fonts and their licenses; removed fonts cannot linger in the app. */
 export declare function syncNativeFonts(fonts: CraftConfig['nativeFonts'], output: string): string[];
 /** This package's version, which the app names in its user agent (`Craft/<version>`). */
 export declare function resolveCraftVersion(startDir?: string): string;
 export type CraftAppearance = 'light' | 'dark' | 'system';
 export interface CraftConfig {
+    appShortcuts?: CraftAppShortcut[];
     /** Bundled font files keyed by their PostScript font name, used as native fontFamily. */
     nativeFonts?: Record<string, {
         src: string;

package/dist/ios/src/index.js

@@ -4,6 +4,60 @@ import { cpSync, existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSy
 import { dirname as dirname2, extname, join as join3, resolve, sep as sep2 } from "path";
 var {$ } = globalThis.Bun;
 
+// ../ios/src/app-shortcuts.ts
+function literal(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
+}
+function appShortcutsSwift(shortcuts = [], schemes = []) {
+  if (shortcuts.length > 10)
+    throw new Error("iOS supports at most ten app shortcuts");
+  const ids = new Set;
+  for (const shortcut of shortcuts) {
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(shortcut.id) || ids.has(shortcut.id))
+      throw new Error(`Invalid or duplicate app shortcut id: ${shortcut.id}`);
+    ids.add(shortcut.id);
+    const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(shortcut.url)?.[1];
+    if (!scheme || !schemes.includes(scheme) || /[\s\\]/.test(shortcut.url))
+      throw new Error(`App shortcut ${shortcut.id} needs a registered app URL scheme`);
+    if (!shortcut.title?.trim() || !shortcut.symbol?.trim() || !shortcut.phrases?.length || shortcut.phrases.some((phrase) => phrase.split("{app}").length !== 2))
+      throw new Error(`App shortcut ${shortcut.id} needs a title, symbol and phrases with exactly one {app}`);
+  }
+  const name = (id) => `CraftShortcut${id.split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join("")}Intent`;
+  const intents = shortcuts.map((shortcut) => `@available(iOS 16.4, *)
+struct ${name(shortcut.id)}: AppIntent {
+    static var title: LocalizedStringResource = ${literal(shortcut.title)}
+    static var description = IntentDescription(${literal(shortcut.subtitle ?? shortcut.title)})
+    static var openAppWhenRun: Bool = true
+    @MainActor
+    func perform() async throws -> some IntentResult {
+        if let url = URL(string: ${literal(shortcut.url)}) { await UIApplication.shared.open(url) }
+        return .result()
+    }
+}`).join(`
+
+`);
+  const entries = shortcuts.map((shortcut) => `        AppShortcut(
+            intent: ${name(shortcut.id)}(),
+            phrases: [${shortcut.phrases.map((phrase) => literal(phrase).replace("{app}", "\\(.applicationName)")).join(", ")}],
+            shortTitle: ${literal(shortcut.title)},
+            systemImageName: ${literal(shortcut.symbol)}
+        )`).join(`
+`);
+  return `// Generated by Craft from appShortcuts. Restored from the package at build time.
+import AppIntents
+import UIKit
+
+${intents}
+${shortcuts.length ? `
+@available(iOS 16.4, *)
+struct CraftConfiguredAppShortcuts: AppShortcutsProvider {
+    static var appShortcuts: [AppShortcut] {
+${entries}
+    }
+}
+` : ""}`;
+}
+
 // ../ios/src/source-audit.ts
 import { readdirSync } from "fs";
 import { join, relative, sep } from "path";
@@ -1073,11 +1127,13 @@ function writeShell(output, config) {
   if (!config.appName || !/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/.test(config.bundleId))
     throw new Error("The iOS shell needs an appName and a valid bundleId in craft.config.json.");
   const name = productName(config.appName);
+  const shortcutSource = appShortcutsSwift(config.appShortcuts, config.urlSchemes);
   mkdirSync2(join3(output, "Sources"), { recursive: true });
   mkdirSync2(join3(output, "Shared"), { recursive: true });
   const swiftTemplate = readFileSync2(join3(TEMPLATES_DIR, "CraftApp.swift"), "utf-8");
   const swiftSource = swiftTemplate.replace(/CraftApp/g, `${name}App`).replace(/\{\{BUNDLE_ID\}\}/g, config.bundleId).replace(/\{\{CRAFT_VERSION\}\}/g, CRAFT_VERSION);
   writeFileSync2(join3(output, "Sources", `${name}App.swift`), swiftSource);
+  writeFileSync2(join3(output, "Sources", "CraftAppShortcuts.swift"), shortcutSource);
   cpSync(join3(TEMPLATES_DIR, "CraftNativeScreen.swift"), join3(output, "Sources", "CraftNativeScreen.swift"));
   cpSync(join3(TEMPLATES_DIR, "CraftNativeFlatList.swift"), join3(output, "Sources", "CraftNativeFlatList.swift"));
   cpSync(join3(TEMPLATES_DIR, "CraftNativeActions.swift"), join3(output, "Sources", "CraftNativeActions.swift"));

package/dist/ios/templates/CraftApp.swift

@@ -205,6 +205,12 @@ final class CraftAppDelegate: NSObject, UIApplicationDelegate, UNUserNotificatio
         // push, a refresh, a route recording's location) draws nothing, and
         // its events still need someone to hear them.
         CraftHybrid.shared.configure(config)
+        if let shortcuts = config.appShortcuts {
+            application.shortcutItems = shortcuts.prefix(4).map { shortcut in
+                UIApplicationShortcutItem(type: shortcut.id, localizedTitle: shortcut.title, localizedSubtitle: shortcut.subtitle,
+                    icon: UIApplicationShortcutIcon(systemImageName: shortcut.symbol), userInfo: ["url": shortcut.url as NSString])
+            }
+        }
         if let shortcut = launchOptions?[.shortcutItem] as? UIApplicationShortcutItem {
             CraftEventManager.shared.handleShortcut(shortcut)
             // Returning false tells UIKit the launch-time item was handled and
@@ -1399,7 +1405,17 @@ extension CraftConfig {
 }
 
 // MARK: - Configuration
+struct CraftConfiguredShortcut: Codable {
+    var id: String
+    var title: String
+    var subtitle: String?
+    var symbol: String
+    var url: String
+    var phrases: [String]
+}
+
 struct CraftConfig: Codable {
+    var appShortcuts: [CraftConfiguredShortcut]? = nil
     var appName: String = "Craft App"
     var bundleId: String = "com.craft.app"
     /// Opt-in UIKit + JavaScriptCore screen; existing apps keep WKWebView.

package/dist/ios/templates/CraftNativeScreen.swift

@@ -1161,8 +1161,29 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
     private var overlayWidths: [ObjectIdentifier: CGFloat] = [:]
     private var initialCameraKey: String?
     private var pendingFitKey: String?
+    private var pendingRegion: MKCoordinateRegion?
     private(set) var markerHandlers: [String: String] = [:]
     var onMarkerTap: ((String) -> Void)?
+    var onMapPress: ((CLLocationCoordinate2D) -> Void)?
+    var onRegionChangeComplete: ((MKCoordinateRegion, Double, Double) -> Void)?
+    private var userChangingCamera = false
+    private var authoredPitch: Double?
+    private var authoredHeading: Double?
+    private var edgePadding = UIEdgeInsets(top: 24, left: 24, bottom: 24, right: 24)
+    private var markerBearings: [String: Double] = [:]
+    private var tileOverlay: MKTileOverlay?
+    private var tileTemplate: String?
+    private lazy var tileAttribution: UILabel = {
+        let label = UILabel()
+        label.font = .systemFont(ofSize: 9)
+        label.textColor = .darkGray
+        label.backgroundColor = UIColor.white.withAlphaComponent(0.85)
+        label.translatesAutoresizingMaskIntoConstraints = false
+        label.numberOfLines = 2
+        addSubview(label)
+        NSLayoutConstraint.activate([label.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -8), label.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -8), label.leadingAnchor.constraint(greaterThanOrEqualTo: leadingAnchor, constant: 48)])
+        return label
+    }()
 
     override init(frame: CGRect) {
         super.init(frame: frame)
@@ -1170,6 +1191,9 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
         showsCompass = false
         showsScale = false
         isRotateEnabled = false
+        let tap = UITapGestureRecognizer(target: self, action: #selector(pressedMap(_:)))
+        tap.cancelsTouchesInView = false
+        addGestureRecognizer(tap)
     }
 
     required init?(coder: NSCoder) {
@@ -1183,6 +1207,18 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
         isZoomEnabled = props["zoomEnabled"] as? Bool ?? true
         isRotateEnabled = props["rotateEnabled"] as? Bool ?? false
         mapType = Self.mapType(props["mapType"] as? String)
+        configureTiles(props["tileOverlay"] as? [String: Any])
+        showsCompass = props["showsCompass"] as? Bool ?? false
+        showsScale = props["showsScale"] as? Bool ?? false
+        authoredPitch = Self.numeric(props["cameraPitch"])
+        authoredHeading = Self.numeric(props["cameraHeading"])
+        let padding = props["edgePadding"] as? [String: Any]
+        func inset(_ name: String) -> CGFloat {
+            guard let value = Self.numeric(padding?[name]), value.isFinite else { return 24 }
+            return CGFloat(min(10_000, max(0, value)))
+        }
+        edgePadding = UIEdgeInsets(top: inset("top"), left: inset("left"), bottom: inset("bottom"), right: inset("right"))
+        var nextBearings: [String: Double] = [:]
         // Showing the user dot must not trigger a permission prompt from a
         // renderer pass. The app's existing location capability owns that
         // prompt; a map only opts in after authorization is already granted.
@@ -1203,6 +1239,9 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             if type == "mapmarker" || type == "marker" {
                 guard let point = points.first else { continue }
                 nextMarkers[id] = (point, childProps["title"] as? String)
+                if let bearing = Self.numeric(childProps["bearing"]), bearing.isFinite {
+                    nextBearings[id] = bearing.truncatingRemainder(dividingBy: 360)
+                }
                 if let handler = nonEmptyHandler(childEvents["onPress"])
                     ?? nonEmptyHandler(childEvents["onMarkerPress"]) {
                     nextHandlers[id] = handler
@@ -1216,12 +1255,14 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             }
         }
 
+        markerBearings = nextBearings
         let staleMarkers = annotationsByID.keys.filter { nextMarkers[$0] == nil }
         removeAnnotations(staleMarkers.compactMap { annotationsByID.removeValue(forKey: $0) })
         for (id, value) in nextMarkers {
             if let annotation = annotationsByID[id] {
                 annotation.coordinate = value.coordinate
                 annotation.title = value.title
+                if let view = view(for: annotation) { configureMarkerView(view, id: id) }
             } else {
                 let annotation = MKPointAnnotation()
                 annotation.coordinate = value.coordinate
@@ -1266,17 +1307,24 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             // `region` is controlled: an authored change is allowed to move
             // the camera, even when the map itself was already mounted.
             pendingFitKey = nil
-            setRegion(region, animated: false)
+            pendingRegion = bounds.width > 0 && bounds.height > 0 ? nil : region
+            if abs(self.region.center.latitude - region.center.latitude) > 0.00000001
+                || abs(self.region.center.longitude - region.center.longitude) > 0.00000001
+                || abs(self.region.span.latitudeDelta - region.span.latitudeDelta) > 0.00000001
+                || abs(self.region.span.longitudeDelta - region.span.longitudeDelta) > 0.00000001 {
+                setRegion(region, animated: false)
+            }
             initialCameraKey = nil
         } else if let initial = Self.region(props["initialRegion"]) {
             pendingFitKey = nil
             let key = "region:\(Self.regionKey(initial))"
             if initialCameraKey != key {
+                pendingRegion = bounds.width > 0 && bounds.height > 0 ? nil : initial
                 setRegion(initial, animated: false)
                 initialCameraKey = key
             }
         } else if props["fitToBounds"] as? Bool == true {
-            let key = "fit:\(Self.overlayKey(markers: nextMarkers.mapValues { $0.coordinate }, polylines: nextPolylines.mapValues { $0.coordinates }))"
+            let key = "fit:\(Self.overlayKey(markers: nextMarkers.mapValues { $0.coordinate }, polylines: nextPolylines.mapValues { $0.coordinates })):\(edgePadding)"
             if initialCameraKey != key {
                 // A native screen can reconcile before UIKit assigns the map
                 // its final safe-area-constrained bounds. Keep the fit
@@ -1292,10 +1340,96 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             initialCameraKey = nil
             pendingFitKey = nil
         }
+        applyCameraOrientation()
+    }
+
+    private func configureTiles(_ options: [String: Any]?) {
+        let template = options?["urlTemplate"] as? String
+        let credit = options?["attribution"] as? String ?? ""
+        let valid = template.map { value in value.hasPrefix("https://") && ["{z}", "{x}", "{y}"].allSatisfy { value.contains($0) } } ?? false
+        let next = valid && !credit.isEmpty ? template : nil
+        if tileTemplate != next {
+            if let overlay = tileOverlay { removeOverlay(overlay) }
+            tileOverlay = nil
+            tileTemplate = next
+            if let next {
+                let overlay = MKTileOverlay(urlTemplate: next)
+                overlay.canReplaceMapContent = true
+                tileOverlay = overlay
+                insertOverlay(overlay, at: 0, level: .aboveRoads)
+            }
+        }
+        tileAttribution.text = next == nil ? nil : credit
+        tileAttribution.isHidden = next == nil
+    }
+
+    private func applyCameraOrientation() {
+        // Region-to-altitude conversion needs a measured viewport. Applying
+        // pitch to the zero-altitude camera before layout clamps it to zero.
+        guard bounds.width > 0, bounds.height > 0 else { return }
+        let next = camera.copy() as! MKMapCamera
+        var changed = false
+        if let pitch = authoredPitch, pitch.isFinite {
+            let value = CGFloat(min(60, max(0, pitch)))
+            if abs(next.pitch - value) > 0.01 { next.pitch = value; changed = true }
+        }
+        if let heading = authoredHeading, heading.isFinite {
+            let value = heading.truncatingRemainder(dividingBy: 360)
+            if abs(next.heading - value) > 0.01 { next.heading = value; changed = true }
+        }
+        if changed { setCamera(next, animated: false) }
+    }
+
+    @objc private func pressedMap(_ gesture: UITapGestureRecognizer) {
+        guard gesture.state == .ended, onMapPress != nil else { return }
+        let point = gesture.location(in: self)
+        var touched = hitTest(point, with: nil)
+        while let view = touched, view !== self {
+            if view is MKAnnotationView { return }
+            touched = view.superview
+        }
+        onMapPress?(convert(point, toCoordinateFrom: self))
+    }
+
+    func mapView(_ mapView: MKMapView, regionWillChangeAnimated animated: Bool) {
+        func interacting(_ view: UIView) -> Bool {
+            if view.gestureRecognizers?.contains(where: { [.began, .changed, .ended].contains($0.state) }) == true { return true }
+            return view.subviews.contains(where: interacting)
+        }
+        userChangingCamera = userChangingCamera || interacting(self)
+    }
+
+    func mapView(_ mapView: MKMapView, regionDidChangeAnimated animated: Bool) {
+        for (id, annotation) in annotationsByID {
+            if let view = view(for: annotation) { configureMarkerView(view, id: id) }
+        }
+        if userChangingCamera {
+            userChangingCamera = false
+            onRegionChangeComplete?(region, camera.heading, Double(camera.pitch))
+        }
+    }
+
+    private func configureMarkerView(_ view: MKAnnotationView, id: String) {
+        if let bearing = markerBearings[id] {
+            let configuration = UIImage.SymbolConfiguration(pointSize: 24, weight: .semibold)
+                .applying(UIImage.SymbolConfiguration(paletteColors: [.white, .systemGreen]))
+            view.image = UIImage(systemName: "arrow.up.circle.fill", withConfiguration: configuration)
+            view.transform = CGAffineTransform(rotationAngle: CGFloat((bearing - camera.heading) * .pi / 180))
+        } else {
+            view.image = UIImage(systemName: "mappin.circle.fill", withConfiguration: UIImage.SymbolConfiguration(pointSize: 28))?
+                .withTintColor(.systemRed, renderingMode: .alwaysOriginal)
+            view.transform = .identity
+        }
     }
 
     override func layoutSubviews() {
         super.layoutSubviews()
+        if tileTemplate != nil { bringSubviewToFront(tileAttribution) }
+        if let region = pendingRegion, bounds.width > 0, bounds.height > 0 {
+            pendingRegion = nil
+            setRegion(region, animated: false)
+            applyCameraOrientation()
+        }
         guard let key = pendingFitKey else { return }
         pendingFitKey = nil
         guard fitToOverlays() else {
@@ -1303,6 +1437,7 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             return
         }
         initialCameraKey = key
+        applyCameraOrientation()
     }
 
     @discardableResult
@@ -1315,17 +1450,29 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             rect = rect.union(MKMapRect(x: point.x, y: point.y, width: 0, height: 0))
         }
         guard !rect.isNull else { return false }
-        let inset = UIEdgeInsets(top: 24, left: 24, bottom: 24, right: 24)
+        var inset = edgePadding
+        let horizontal = inset.left + inset.right
+        let vertical = inset.top + inset.bottom
+        let availableWidth = max(0, bounds.width - 40)
+        let availableHeight = max(0, bounds.height - 40)
+        if horizontal > availableWidth && horizontal > 0 {
+            inset.left *= availableWidth / horizontal
+            inset.right *= availableWidth / horizontal
+        }
+        if vertical > availableHeight && vertical > 0 {
+            inset.top *= availableHeight / vertical
+            inset.bottom *= availableHeight / vertical
+        }
         setVisibleMapRect(rect, edgePadding: inset, animated: false)
         return true
     }
 
     func mapView(_ mapView: MKMapView, viewFor annotation: MKAnnotation) -> MKAnnotationView? {
         guard let id = annotationsByID.first(where: { $0.value === annotation })?.key else { return nil }
-        let view = (dequeueReusableAnnotationView(withIdentifier: "craft-native-marker") as? MKMarkerAnnotationView)
-            ?? MKMarkerAnnotationView(annotation: annotation, reuseIdentifier: "craft-native-marker")
+        let view = dequeueReusableAnnotationView(withIdentifier: "craft-native-marker")
+            ?? MKAnnotationView(annotation: annotation, reuseIdentifier: "craft-native-marker")
         view.annotation = annotation
-        view.markerTintColor = .systemRed
+        configureMarkerView(view, id: id)
         view.accessibilityIdentifier = id
         return view
     }
@@ -1337,6 +1484,7 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
     }
 
     func mapView(_ mapView: MKMapView, rendererFor overlay: MKOverlay) -> MKOverlayRenderer {
+        if let tiles = overlay as? MKTileOverlay { return MKTileOverlayRenderer(tileOverlay: tiles) }
         let renderer = MKPolylineRenderer(overlay: overlay)
         renderer.strokeColor = overlayColors[ObjectIdentifier(overlay)] ?? .systemBlue
         renderer.lineWidth = overlayWidths[ObjectIdentifier(overlay)] ?? 3
@@ -1834,7 +1982,172 @@ extension UIView {
     }
 }
 
+/// A finite, opt-in native celebration. Reconciliation with the same replay
+/// value never restarts it; Reduce Motion always leaves the complete card still.
+struct CraftNativeCelebrationSpec: Equatable {
+    let replay: Double
+    let enabled: Bool
+
+    init?(_ raw: Any?) {
+        guard let value = raw as? [String: Any],
+              let replay = value["replay"] as? NSNumber,
+              CFGetTypeID(replay) != CFBooleanGetTypeID(),
+              replay.doubleValue.isFinite, replay.doubleValue >= 0 else { return nil }
+        self.replay = replay.doubleValue
+        enabled = value["enabled"] as? Bool != false
+    }
+}
+
+final class CraftNativeCelebration {
+    private weak var view: UIView?
+    private var request: CraftNativeCelebrationSpec?
+    private var pending = false
+    private var overlay: CALayer?
+    private var sheen: CALayer?
+    private var cleanup: DispatchWorkItem?
+    private var observers: [NSObjectProtocol] = []
+    private(set) var starts = 0
+    var isRunning: Bool { overlay != nil }
+
+    init(view: UIView) {
+        self.view = view
+        for name in [UIApplication.didEnterBackgroundNotification, UIAccessibility.reduceMotionStatusDidChangeNotification] {
+            observers.append(NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in self?.stop() })
+        }
+    }
+
+    deinit {
+        cleanup?.cancel()
+        overlay?.removeFromSuperlayer()
+        sheen?.removeFromSuperlayer()
+        observers.forEach(NotificationCenter.default.removeObserver)
+    }
+
+    func configure(_ raw: Any?) {
+        let next = CraftNativeCelebrationSpec(raw)
+        guard next != request else { return }
+        stop()
+        request = next
+        pending = next?.enabled == true
+        view?.setNeedsLayout()
+    }
+
+    func stop() {
+        pending = false
+        cleanup?.cancel()
+        cleanup = nil
+        view?.layer.removeAnimation(forKey: "craft.celebration.entrance")
+        overlay?.removeFromSuperlayer()
+        overlay = nil
+        sheen?.removeFromSuperlayer()
+        sheen = nil
+    }
+
+    func layout(reduceMotion: Bool = UIAccessibility.isReduceMotionEnabled) {
+        guard pending, let view, let window = view.window,
+              view.bounds.width > 0, view.bounds.height > 0, !view.isHidden else { return }
+        var ancestor: UIView? = view.superview
+        while let parent = ancestor {
+            if parent.isHidden { return }
+            ancestor = parent.superview
+        }
+        pending = false
+        guard !reduceMotion else { return }
+        starts += 1
+        let frame = view.convert(view.bounds, to: window)
+        let overlay = CALayer()
+        overlay.name = "craft.celebration.confetti"
+        overlay.frame = window.bounds
+        window.layer.addSublayer(overlay)
+        self.overlay = overlay
+
+        // Core Animation owns every frame. No script timers, per-frame bridge
+        // messages, bitmap assets or touch-intercepting overlay views.
+        let colors: [UIColor] = [.init(red: 0.23, green: 0.51, blue: 0.96, alpha: 1), .init(red: 0.6, green: 0.96, blue: 0.89, alpha: 1), .init(red: 0.9, green: 0.77, blue: 0.55, alpha: 1), .white]
+        let now = CACurrentMediaTime()
+        for index in 0..<52 {
+            let side: CGFloat = index % 2 == 0 ? -1 : 1
+            let spread = CGFloat((index * 37) % 101) / 100
+            let start = CGPoint(x: frame.midX + side * frame.width * 0.42, y: frame.minY + 28)
+            let end = CGPoint(x: frame.midX + side * (35 + spread * window.bounds.width * 0.7), y: window.bounds.height + 30)
+            let piece = CALayer()
+            piece.bounds = CGRect(x: 0, y: 0, width: index % 3 == 0 ? 4 : 7, height: 11)
+            piece.cornerRadius = 1
+            piece.backgroundColor = colors[index % colors.count].cgColor
+            piece.position = end
+            piece.opacity = 0
+            overlay.addSublayer(piece)
+            let path = CAKeyframeAnimation(keyPath: "position")
+            path.values = [NSValue(cgPoint: start), NSValue(cgPoint: CGPoint(x: start.x + side * (45 + spread * 65), y: max(0, start.y - 70 - spread * 100))), NSValue(cgPoint: end)]
+            path.keyTimes = [0, 0.28, 1]
+            path.calculationMode = .cubic
+            let tumble = CABasicAnimation(keyPath: "transform.rotation")
+            tumble.fromValue = side * Double(index)
+            tumble.toValue = side * (Double(index) + 7 + Double(spread) * 10)
+            let fade = CAKeyframeAnimation(keyPath: "opacity")
+            fade.values = [0, 1, 1, 0]
+            fade.keyTimes = [0, 0.04, 0.7, 1]
+            let group = CAAnimationGroup()
+            group.animations = [path, tumble, fade]
+            group.duration = 2.2 + Double(spread) * 0.45
+            group.beginTime = now + Double(index % 7) * 0.018
+            group.fillMode = .backwards
+            piece.add(group, forKey: "craft.celebration.particle")
+        }
+
+        let entrance = CASpringAnimation(keyPath: "transform")
+        var from = CATransform3DMakeTranslation(0, 34, 0)
+        from = CATransform3DRotate(from, -0.045, 0, 0, 1)
+        from = CATransform3DScale(from, 0.86, 0.86, 1)
+        entrance.fromValue = NSValue(caTransform3D: CATransform3DConcat(view.layer.transform, from))
+        entrance.toValue = NSValue(caTransform3D: view.layer.transform)
+        entrance.damping = 19
+        entrance.stiffness = 160
+        entrance.mass = 1
+        entrance.duration = 0.95
+        view.layer.add(entrance, forKey: "craft.celebration.entrance")
+
+        let sheen = CAGradientLayer()
+        sheen.name = "craft.celebration.sheen"
+        sheen.frame = view.bounds
+        sheen.colors = [UIColor.clear.cgColor, UIColor.white.withAlphaComponent(0.2).cgColor, UIColor.clear.cgColor]
+        sheen.locations = [0.25, 0.5, 0.75]
+        sheen.startPoint = CGPoint(x: 0, y: 0.3)
+        sheen.endPoint = CGPoint(x: 1, y: 0.7)
+        sheen.opacity = 0
+        let mask = CAShapeLayer()
+        mask.path = UIBezierPath(roundedRect: view.bounds, cornerRadius: view.layer.cornerRadius).cgPath
+        sheen.mask = mask
+        view.layer.addSublayer(sheen)
+        self.sheen = sheen
+        let sweep = CABasicAnimation(keyPath: "transform.translation.x")
+        sweep.fromValue = -view.bounds.width
+        sweep.toValue = view.bounds.width
+        let light = CAKeyframeAnimation(keyPath: "opacity")
+        light.values = [0, 1, 1, 0]
+        light.keyTimes = [0, 0.15, 0.8, 1]
+        let shine = CAAnimationGroup()
+        shine.animations = [sweep, light]
+        shine.duration = 1.15
+        shine.beginTime = now + 0.55
+        sheen.add(shine, forKey: "craft.celebration.sweep")
+        let cleanup = DispatchWorkItem { [weak self] in self?.stop() }
+        self.cleanup = cleanup
+        DispatchQueue.main.asyncAfter(deadline: .now() + 3, execute: cleanup)
+    }
+}
+
 private class CraftNativeFlowView: UIStackView {
+    var celebration: CraftNativeCelebration?
+    func configureCelebration(_ raw: Any?) {
+        if raw != nil && celebration == nil { celebration = CraftNativeCelebration(view: self) }
+        celebration?.configure(raw)
+    }
+    override func didMoveToWindow() {
+        super.didMoveToWindow()
+        if window == nil { celebration?.stop() }
+        else { setNeedsLayout() }
+    }
     var pressActiveOpacity: CGFloat?
     var pressBaseOpacity: CGFloat = 1
     var pressUnderlayColor: UIColor?
@@ -2051,6 +2364,7 @@ private class CraftNativeFlowView: UIStackView {
     override func layoutSubviews() {
         super.layoutSubviews()
         craftApplyCornerRadius()
+        celebration?.layout()
         let scale = window?.screen.scale ?? traitCollection.displayScale
         let result = layout(width: bounds.width, height: bounds.height, maxWidth: bounds.width, maxHeight: bounds.height, place: true)
         var moved = false
@@ -4134,6 +4448,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     override func viewWillDisappear(_ animated: Bool) {
         super.viewWillDisappear(animated)
+        stopCelebrations(in: view)
         // The accessory belongs to the visible native screen. Clear the
         // shared shell state before a hybrid/web route appears, otherwise a
         // destination from the outgoing screen remains tappable on top of it.
@@ -4188,6 +4503,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// `SCREEN_FOCUS { focused: true }`, and going away is `focused: false`.
     func screenVisibilityChanged(_ visible: Bool) {
         guard !runtimeDisposed else { return }
+        if !visible, isViewLoaded { stopCelebrations(in: view) }
         // Hidden tab stacks receive no UIKit appearance callback. A cancelled
         // preview also restores a screen that never lost focus, so restore its
         // chrome even when no new SCREEN_FOCUS event is needed.
@@ -6130,6 +6446,18 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         case "Map":
             let map = result as! CraftNativeMapView
             let mapMarkerHandler = nonEmptyHandler(events["onMarkerPress"])
+            map.onMapPress = { [weak self] coordinate in
+                guard let self, let handler = self.nonEmptyHandler(events["onPress"]) else { return }
+                self.send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": ["latitude": coordinate.latitude, "longitude": coordinate.longitude]])
+            }
+            map.onRegionChangeComplete = { [weak self] region, heading, pitch in
+                guard let self, let handler = self.nonEmptyHandler(events["onRegionChangeComplete"]) else { return }
+                self.send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": [
+                    "center": ["latitude": region.center.latitude, "longitude": region.center.longitude],
+                    "span": ["latitudeDelta": region.span.latitudeDelta, "longitudeDelta": region.span.longitudeDelta],
+                    "heading": heading, "pitch": pitch,
+                ]])
+            }
             map.configure(props: props, children: children) { [weak self, weak map] markerID in
                 guard let self, let map,
                       let handler = map.markerHandlers[markerID] ?? mapMarkerHandler else { return }
@@ -6217,9 +6545,15 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             if disabled { result.isUserInteractionEnabled = false }
         }
         applyAccessibility(props, type: type, to: result)
+        (result as? CraftNativeFlowView)?.configureCelebration(props["celebration"])
         return current
     }
 
+    private func stopCelebrations(in root: UIView) {
+        (root as? CraftNativeFlowView)?.celebration?.stop()
+        root.subviews.forEach { stopCelebrations(in: $0) }
+    }
+
     private func makeView(_ type: String, props: [String: Any]) -> UIView {
         switch type {
         case "Text":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craft-native",
-  "version": "0.0.235",
+  "version": "0.0.237",
   "type": "module",
   "description": "Build desktop apps with web languages - TypeScript SDK for Craft",
   "author": "Chris Breuer <chris@stacksjs.org>",