@craft-native/ios 0.0.235 → 0.0.237

package/README.md

@@ -2,6 +2,18 @@
 
 Build native iOS apps with web technologies using Craft.
 
+## Native celebration
+
+Any native `View` may opt into a finite card entrance, light sweep and confetti
+burst with `:celebration="{ replay: replayCount, enabled: true }"`. The numeric
+`replay` value identifies the request: unrelated renders keep the current run;
+increment it to replay. `enabled: false` displays an existing card quietly.
+The effect takes three seconds, uses native animation frames, never captures
+touches, and keeps the view's authored transform. iOS Reduce Motion and Android's
+disabled animations show the complete content without movement or confetti.
+Leaving the screen, detaching the view or backgrounding the app cancels the
+decoration. Resuming does not replay it. Available on both native renderers.
+
 ## Features
 
 ### Core

package/dist/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/cli.js

@@ -10,6 +10,60 @@ import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync as readdirSync
 import { dirname as dirname2, extname, join as join3, resolve, sep as sep2 } from "path";
 var {$ } = globalThis.Bun;
 
+// 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}
+    }
+}
+` : ""}`;
+}
+
 // src/source-audit.ts
 import { readdirSync } from "fs";
 import { join, relative, sep } from "path";
@@ -890,11 +944,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);
   mkdirSync(join3(output, "Sources"), { recursive: true });
   mkdirSync(join3(output, "Shared"), { recursive: true });
   const swiftTemplate = readFileSync(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);
   writeFileSync(join3(output, "Sources", `${name}App.swift`), swiftSource);
+  writeFileSync(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/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/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;
 
+// 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}
+    }
+}
+` : ""}`;
+}
+
 // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-native/ios",
-  "version": "0.0.235",
+  "version": "0.0.237",
   "homepage": "https://github.com/craft-native/craft/tree/main/packages/ios#readme",
   "repository": {
     "type": "git",

package/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/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":