craft-native 0.0.236 → 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()
@@ -5746,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)))
@@ -7153,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.236";
+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.236";
+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.236";
+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
@@ -6298,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 }

package/package.json

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