craft-native 0.0.142 → 0.0.144

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

@@ -1928,6 +1928,7 @@ class MainActivity : AppCompatActivity() {
             if (!screen.controls.containsKey("id:$target")) return false
             makeView(screen, document, target, screen.controls)
             val updated = screen.controls["id:$target"] ?: return false
+            screen.lastLayoutBounds.remove(updated)
             if (!updateParentLayoutStyle(updated, document.optJSONObject("style") ?: JSONObject())) return false
         }
         if (applied.isNotEmpty()) {
@@ -1940,14 +1941,16 @@ class MainActivity : AppCompatActivity() {
         if (!screen.active) return
         val observer = screen.view.viewTreeObserver
         if (observer.isAlive) {
-            val listener = object : ViewTreeObserver.OnGlobalLayoutListener {
-                override fun onGlobalLayout() {
-                    if (observer.isAlive) observer.removeOnGlobalLayoutListener(this)
+            val listener = object : ViewTreeObserver.OnPreDrawListener {
+                override fun onPreDraw(): Boolean {
+                    if (observer.isAlive) observer.removeOnPreDrawListener(this)
                     if (screen.active) emitLayoutEvents(screen)
+                    return true
                 }
             }
-            observer.addOnGlobalLayoutListener(listener)
+            observer.addOnPreDrawListener(listener)
         }
+        screen.view.forceLayout()
         screen.view.requestLayout()
         // A tree that is already settled may not produce a global-layout
         // callback; keep the event path live for that case as well.
@@ -1961,15 +1964,23 @@ class MainActivity : AppCompatActivity() {
      */
     private fun updateParentLayoutStyle(view: View, style: JSONObject): Boolean {
         var parent = view.parent
+        var found = false
         while (parent != null) {
-            if (parent is CraftNativeFlexLayout) {
-                parent.setChildStyle(view, style, resources.displayMetrics.density)
-                parent.requestLayout()
-                return true
+            when (parent) {
+                is CraftNativeFlexLayout -> {
+                    if (!found) parent.setChildStyle(view, style, resources.displayMetrics.density)
+                    parent.forceLayout()
+                    parent.requestLayout()
+                    found = true
+                }
+                is CraftNativeScrollView -> {
+                    parent.forceLayout()
+                    parent.requestLayout()
+                }
             }
             parent = parent.parent
         }
-        return false
+        return found
     }
 
     private fun renderCommitted(screen: Screen, document: JSONObject) {

package/dist/api/mobile.d.ts

@@ -762,6 +762,69 @@ export declare const speech: {
     /** Stop speaking at once. Every pending `speak()` resolves `false`. */
     stop(): Promise<void>;
 };
+export type MusicAuthorization = 'authorized' | 'denied' | 'restricted' | 'notDetermined' | 'unavailable';
+export type MusicPlaybackState = 'stopped' | 'playing' | 'paused' | 'interrupted' | 'seekingForward' | 'seekingBackward' | 'unknown';
+export interface NowPlaying {
+    /** False where there is no Music app to ask: a browser, Android, an app built without `enableAppleMusic`. */
+    available: boolean;
+    authorization: MusicAuthorization;
+    /** `appleMusic`, or `simulated` for the simulator's stand-in; null without access. */
+    source: 'appleMusic' | 'simulated' | null;
+    playbackState: MusicPlaybackState;
+    isPlaying: boolean;
+    itemId: string | null;
+    title: string | null;
+    artist: string | null;
+    album: string | null;
+    /** Seconds. */
+    duration: number | null;
+    /** Seconds into the song at `timestamp`. */
+    position: number | null;
+    /** A small square JPEG (120 px) as a data URL, when the song has artwork. */
+    artworkDataURL: string | null;
+    /** Some app is playing audio, Apple Music included: read it beside `isPlaying`. */
+    otherAudioPlaying: boolean;
+    /** When the snapshot was taken, in ms since the epoch. */
+    timestamp: number;
+}
+export interface MusicSkipOptions {
+    /**
+     * Past this many seconds into a song, go back to its start instead of the
+     * previous song, as the Music app's own button does. 3 by default; 0
+     * always goes to the previous song.
+     */
+    restartAfter?: number;
+}
+export type MusicMethod = 'getAuthorizationStatus' | 'requestAuthorization' | 'getNowPlaying' | 'play' | 'pause' | 'togglePlayPause' | 'skipToNext' | 'skipToPrevious' | 'observe';
+/** A snapshot from native, made safe to render whatever an older or newer build sent. */
+export declare function normalizeNowPlaying(value: unknown): NowPlaying;
+export declare const music: {
+    /** Whether this app can show and steer the Music app. */
+    isAvailable(): boolean;
+    /** Whether this app build answers `method`; an older build may lack one. */
+    supports(method: MusicMethod): boolean;
+    /** Where access stands, without asking. `unavailable` off a phone. */
+    getAuthorizationStatus(): Promise<MusicAuthorization>;
+    /**
+     * Ask for media library access: iOS's prompt the first time, its
+     * remembered answer after that. Call it from the person's own tap.
+     */
+    requestAuthorization(): Promise<MusicAuthorization>;
+    /** The song, its artwork and the playback state, as one snapshot. */
+    getNowPlaying(): Promise<NowPlaying>;
+    /** Each resolves with the snapshot once the Music app has moved. */
+    play: () => Promise<NowPlaying>;
+    pause: () => Promise<NowPlaying>;
+    togglePlayPause: () => Promise<NowPlaying>;
+    skipToNext: () => Promise<NowPlaying>;
+    skipToPrevious: (options?: MusicSkipOptions) => Promise<NowPlaying>;
+    /**
+     * Hear every change of song or playback state, pushed by native rather
+     * than polled. The first listener starts native observation and the last
+     * one to leave stops it. Off a phone it never fires.
+     */
+    onChange(callback: (nowPlaying: NowPlaying) => void): () => void;
+};
 export declare const deepLinks: {
     getInitialURL(): Promise<string | null>;
     /**
@@ -1244,6 +1307,7 @@ declare const mobile: {
     keepAwake: typeof keepAwake;
     brightness: typeof brightness;
     speech: typeof speech;
+    music: typeof music;
     deepLinks: typeof deepLinks;
     network: typeof network;
     appReview: typeof appReview;

package/dist/cli.js

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

package/dist/index.cjs

@@ -310,7 +310,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.142";
+var version = "0.0.144";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -5324,6 +5324,7 @@ var notifications = {
   }
 };
 var speakingOnTheWeb = new Set;
+var musicWatch = { listeners: new Set, stop: null };
 function onCraftEvent(eventName, callback) {
   if (typeof globalThis === "undefined")
     return () => {};

package/dist/index.js

@@ -58,7 +58,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.142";
+var version = "0.0.144";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -5084,6 +5084,7 @@ var notifications = {
   }
 };
 var speakingOnTheWeb = new Set;
+var musicWatch = { listeners: new Set, stop: null };
 function onCraftEvent(eventName, callback) {
   if (typeof globalThis === "undefined")
     return () => {};

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

@@ -60,6 +60,20 @@ export interface CraftConfig {
     enablePDFViewer?: boolean;
     enableAR?: boolean;
     enableMLKit?: boolean;
+    /**
+     * Show and control what the Music app is playing (`craft.music`, through
+     * MPMusicPlayerController.systemMusicPlayer). Only Apple Music: iOS gives
+     * no app the controls of another player such as Spotify. iOS asks the
+     * person for media library access the first time the page calls
+     * `craft.music.requestAuthorization()`, never at launch.
+     */
+    enableAppleMusic?: boolean;
+    /**
+     * Purpose strings in the app's own words, by Info.plist key
+     * (`{ NSAppleMusicUsageDescription: 'Shows the song playing during a workout.' }`).
+     * Each replaces the generic sentence Craft writes for that key.
+     */
+    usageDescriptions?: Record<string, string>;
     devServerURL?: string;
     iosVersion?: string;
     watchosVersion?: string;

package/dist/ios/src/index.js

@@ -169,6 +169,7 @@ var DEFAULT_CONFIG = {
   enablePDFViewer: false,
   enableAR: false,
   enableMLKit: false,
+  enableAppleMusic: false,
   iosVersion: "16.0",
   watchosVersion: "9.0",
   teamId: "",
@@ -212,7 +213,8 @@ var LINKED_PURPOSES = {
   NSCalendarsUsageDescription: "your calendar",
   NSBluetoothAlwaysUsageDescription: "Bluetooth",
   NSMotionUsageDescription: "motion data",
-  NSFaceIDUsageDescription: "Face ID"
+  NSFaceIDUsageDescription: "Face ID",
+  NSAppleMusicUsageDescription: "your music"
 };
 function renderUsageDescriptions(config) {
   const entries = [
@@ -230,9 +232,14 @@ function renderUsageDescriptions(config) {
     [config.enableLocalNetwork, "NSLocalNetworkUsageDescription", `${config.appName} connects to your own devices on this network.`],
     [config.enableHealthKit, "NSHealthShareUsageDescription", `${config.appName} reads health data you choose to share.`],
     [config.enableHealthKit, "NSHealthUpdateUsageDescription", `${config.appName} writes health data only with your permission.`],
-    [config.enableBiometric, "NSFaceIDUsageDescription", `${config.appName} uses Face ID to protect your account.`]
+    [config.enableBiometric, "NSFaceIDUsageDescription", `${config.appName} uses Face ID to protect your account.`],
+    [config.enableAppleMusic, "NSAppleMusicUsageDescription", `${config.appName} shows and controls the music playing in the Music app.`]
   ];
+  const own = config.usageDescriptions ?? {};
   return entries.map(([enabled, key, value]) => {
+    const custom = own[key]?.trim();
+    if (custom)
+      return [key, custom];
     if (enabled)
       return [key, value];
     const linked = LINKED_PURPOSES[key];
@@ -779,6 +786,7 @@ async function init(options) {
   cpSync(join(TEMPLATES_DIR, "CraftNativeFlatList.swift"), join(output, "Sources", "CraftNativeFlatList.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftHealth.swift"), join(output, "Sources", "CraftHealth.swift"));
+  cpSync(join(TEMPLATES_DIR, "CraftMusic.swift"), join(output, "Sources", "CraftMusic.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeMutation.swift"), join(output, "Sources", "CraftNativeMutation.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeUI.swift"), join(output, "Sources", "CraftNativeUI.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftHybrid.swift"), join(output, "Sources", "CraftHybrid.swift"));

package/dist/ios/templates/CraftApp.swift

@@ -1105,6 +1105,8 @@ struct CraftConfig: Codable {
     var enablePDFViewer: Bool = false
     var enableAR: Bool = false
     var enableMLKit: Bool = false
+    /// The Music app's song and transport through `craft.music` (CraftMusic.swift).
+    var enableAppleMusic: Bool = false
     var devServerURL: String? = nil
     var trustedOrigins: [String] = []
     /// The longest the launch splash stays up when the page neither says it is
@@ -2162,6 +2164,43 @@ struct CraftWebView: UIViewRepresentable {
                 } else {
                     rejectCallback(callbackId, error: "setBrightness was called without the values it needs", code: "INVALID_ARGUMENT")
                 }
+            // MARK: - Apple Music (CraftMusic.swift)
+            // Gated on enableAppleMusic. Only musicRequestAuthorization asks
+            // the person anything; the rest answer from what is allowed.
+            case "musicGetAuthorization":
+                if config.enableAppleMusic {
+                    DispatchQueue.main.async { self.resolveCallback(callbackId, result: CraftMusic.shared.authorization) }
+                } else {
+                    rejectCallback(callbackId, error: "Apple Music is disabled", code: "CAPABILITY_DISABLED")
+                }
+            case "musicRequestAuthorization":
+                if config.enableAppleMusic {
+                    DispatchQueue.main.async {
+                        CraftMusic.shared.requestAuthorization { [weak self] status in self?.resolveCallback(callbackId, result: status) }
+                    }
+                } else {
+                    rejectCallback(callbackId, error: "Apple Music is disabled", code: "CAPABILITY_DISABLED")
+                }
+            case "musicGetNowPlaying":
+                if config.enableAppleMusic {
+                    DispatchQueue.main.async { self.resolveCallback(callbackId, result: CraftMusic.shared.snapshot()) }
+                } else {
+                    rejectCallback(callbackId, error: "Apple Music is disabled", code: "CAPABILITY_DISABLED")
+                }
+            case "musicControl":
+                if !config.enableAppleMusic {
+                    rejectCallback(callbackId, error: "Apple Music is disabled", code: "CAPABILITY_DISABLED")
+                } else if let command = body["command"] as? String {
+                    musicControl(command, restartAfter: (body["restartAfter"] as? NSNumber)?.doubleValue, callbackId: callbackId)
+                } else {
+                    rejectCallback(callbackId, error: "musicControl was called without a command", code: "INVALID_ARGUMENT")
+                }
+            case "musicObserve":
+                if config.enableAppleMusic {
+                    musicObserve(body["enabled"] as? Bool ?? true, callbackId: callbackId)
+                } else {
+                    rejectCallback(callbackId, error: "Apple Music is disabled", code: "CAPABILITY_DISABLED")
+                }
             // MARK: - Orientation Lock
             case "lockOrientation":
                 if config.enableOrientationLock {
@@ -3146,6 +3185,7 @@ struct CraftWebView: UIViewRepresentable {
                     deepLinks: \(config.enableDeepLinks),
                     flashlight: true,
                     brightness: true,
+                    music: \(config.enableAppleMusic),
                     speech: true,
                     network: true,
                     deviceInfo: true,
@@ -4684,6 +4724,7 @@ struct CraftWebView: UIViewRepresentable {
                 // still open; these wait for the answer instead.
                 var personFacing = {
                     requestHealthAuthorization: true,
+                    musicRequestAuthorization: true,
                     requestPermission: true,
                     signInWithApple: true,
                     dialogAlert: true,
@@ -4881,6 +4922,23 @@ struct CraftWebView: UIViewRepresentable {
                         return craft._invoke('getHealthSleepIntervals', {startDate: options.startDate, endDate: options.endDate});
                     }
                 };
+                // The Music app's song and transport. Nothing is read until
+                // requestAuthorization() has been allowed; observe(true) makes
+                // every change arrive as a craftMusicChange event.
+                craft.music = {
+                    getAuthorizationStatus: function() { return craft._invoke('musicGetAuthorization'); },
+                    requestAuthorization: function() { return craft._invoke('musicRequestAuthorization'); },
+                    getNowPlaying: function() { return craft._invoke('musicGetNowPlaying'); },
+                    play: function() { return craft._invoke('musicControl', {command: 'play'}); },
+                    pause: function() { return craft._invoke('musicControl', {command: 'pause'}); },
+                    togglePlayPause: function() { return craft._invoke('musicControl', {command: 'togglePlayPause'}); },
+                    skipToNext: function() { return craft._invoke('musicControl', {command: 'skipToNext'}); },
+                    skipToPrevious: function(options) {
+                        var restartAfter = options && typeof options.restartAfter === 'number' ? options.restartAfter : null;
+                        return craft._invoke('musicControl', {command: 'skipToPrevious', restartAfter: restartAfter});
+                    },
+                    observe: function(enabled) { return craft._invoke('musicObserve', {enabled: enabled !== false}); }
+                };
                 craft.liveActivity = {
                     start: function(options) { return craft._invoke('startLiveActivity', options || {}); },
                     update: function(idOrState, state) {
@@ -6932,6 +6990,29 @@ struct CraftWebView: UIViewRepresentable {
             CraftHealth.shared.getSleepIntervals(startDate: startDate, endDate: endDate) { [weak self] in self?.answer(callbackId, $0) }
         }
 
+        // MARK: - Apple Music
+        // The player itself is CraftMusic.swift.
+        private func musicControl(_ command: String, restartAfter: Double?, callbackId: String?) {
+            DispatchQueue.main.async {
+                CraftMusic.shared.control(command, restartAfter: restartAfter) { [weak self] result in
+                    switch result {
+                    case .success(let snapshot): self?.resolveCallback(callbackId, result: snapshot)
+                    case .failure(let failure): self?.rejectCallback(callbackId, error: failure.message, code: failure.code)
+                    }
+                }
+            }
+        }
+
+        /// Every change of song or playback state reaches the page as
+        /// `craftMusicChange`, carrying the same snapshot musicGetNowPlaying
+        /// answers with.
+        private func musicObserve(_ enabled: Bool, callbackId: String?) {
+            DispatchQueue.main.async {
+                CraftMusic.shared.observe(enabled ? { [weak self] snapshot in self?.sendToWeb("craftMusicChange", data: snapshot) } : nil)
+                self.resolveCallback(callbackId, result: enabled)
+            }
+        }
+
         // MARK: - Live Activities
         private func startLiveActivity(body: [String: Any], callbackId: String?) {
             guard #available(iOS 16.2, *), ActivityAuthorizationInfo().areActivitiesEnabled else {

package/dist/ios/templates/CraftMusic.swift

@@ -0,0 +1,413 @@
+import AVFoundation
+import Foundation
+import MediaPlayer
+import UIKit
+
+/// A music call that did not happen: the message a page sees, and the
+/// bridge's error code.
+struct CraftMusicError: Error {
+    let message: String
+    var code: String = "CRAFT_ERROR"
+}
+
+/// The song a player has up, whoever the player is.
+struct CraftMusicItem {
+    let id: String
+    let title: String?
+    let artist: String?
+    let album: String?
+    let duration: TimeInterval
+    /// The artwork drawn at about `size`, or nil when the song has none.
+    let artwork: (CGSize) -> UIImage?
+}
+
+/// The slice of MPMusicPlayerController the bridge uses, so the simulator,
+/// whose Music app has nothing to play, can stand a fake in for it.
+protocol CraftMusicPlayer: AnyObject {
+    /// "appleMusic" for the Music app, "simulated" for the fake.
+    var source: String { get }
+    var item: CraftMusicItem? { get }
+    var playbackState: MPMusicPlaybackState { get }
+    var currentPlaybackTime: TimeInterval { get }
+    /// Called on main whenever the song or the playback state changes.
+    var onChange: (() -> Void)? { get set }
+    func play()
+    func pause()
+    func skipToNextItem()
+    func skipToPreviousItem()
+    func skipToBeginning()
+    func startObserving()
+    func stopObserving()
+}
+
+/// What the Music app is playing, and its transport: the page's
+/// `craft.music` (CraftApp.swift).
+///
+/// Through `MPMusicPlayerController.systemMusicPlayer`, which is the Music
+/// app's own queue: what it plays, this sees and steers, and nothing else.
+/// iOS gives no app another player's controls, so while Spotify or a podcast
+/// app plays, `title` is null and `otherAudioPlaying` is true; a page should
+/// say so rather than show controls that do nothing.
+///
+/// Media library access is asked for only by `requestAuthorization`, which a
+/// page calls when the person chooses to see their music; until then the
+/// player is not touched at all, so nothing is read without consent.
+///
+/// Everything here runs on main: MediaPlayer wants it, and every caller hops
+/// there first.
+final class CraftMusic {
+    typealias Listener = ([String: Any]) -> Void
+
+    static let shared = CraftMusic()
+
+    /// The longest side of the artwork a page is sent, in pixels. Small on
+    /// purpose: it is a thumbnail beside a title, and it crosses the bridge as
+    /// base64 on every change.
+    static let artworkPixels: CGFloat = 120
+
+    private lazy var player: CraftMusicPlayer = {
+        let player = CraftMusic.makePlayer()
+        player.onChange = { [weak self] in self?.playerDidChange() }
+        return player
+    }()
+
+    private var listener: Listener?
+    private var observing = false
+    private var changeScheduled = false
+    private var foregroundObserver: NSObjectProtocol?
+    private var artworkCache: (id: String, dataURL: String?)?
+
+    /// The real player, or on the simulator the fake when the
+    /// `CraftFakeMusicPlayer` default is set: as a launch argument
+    /// (`-CraftFakeMusicPlayer YES`) or with
+    /// `xcrun simctl spawn booted defaults write <bundle id> CraftFakeMusicPlayer -bool YES`.
+    private static func makePlayer() -> CraftMusicPlayer {
+        #if targetEnvironment(simulator)
+        if UserDefaults.standard.bool(forKey: "CraftFakeMusicPlayer") { return CraftFakeMusicPlayer() }
+        #endif
+        return CraftSystemMusicPlayer()
+    }
+
+    // MARK: Authorization
+
+    static func authorizationName(_ status: MPMediaLibraryAuthorizationStatus) -> String {
+        switch status {
+        case .authorized: return "authorized"
+        case .denied: return "denied"
+        case .restricted: return "restricted"
+        case .notDetermined: return "notDetermined"
+        @unknown default: return "denied"
+        }
+    }
+
+    var authorization: String { Self.authorizationName(MPMediaLibrary.authorizationStatus()) }
+    var isAuthorized: Bool { MPMediaLibrary.authorizationStatus() == .authorized }
+
+    /// Ask once; iOS answers from memory after that. Resolves with the
+    /// status's name.
+    func requestAuthorization(completion: @escaping (String) -> Void) {
+        guard MPMediaLibrary.authorizationStatus() == .notDetermined else {
+            completion(authorization)
+            return
+        }
+        MPMediaLibrary.requestAuthorization { status in
+            DispatchQueue.main.async {
+                completion(Self.authorizationName(status))
+                // A page that was already listening hears what there is now.
+                if status == .authorized, self.observing { self.startPlayerObservation() }
+            }
+        }
+    }
+
+    // MARK: Now playing
+
+    static func playbackStateName(_ state: MPMusicPlaybackState) -> String {
+        switch state {
+        case .stopped: return "stopped"
+        case .playing: return "playing"
+        case .paused: return "paused"
+        case .interrupted: return "interrupted"
+        case .seekingForward: return "seekingForward"
+        case .seekingBackward: return "seekingBackward"
+        @unknown default: return "stopped"
+        }
+    }
+
+    /// Everything a page shows about the music, in one answer. Without
+    /// access, only what can be said without touching the player.
+    func snapshot() -> [String: Any] {
+        var result: [String: Any] = [
+            "available": true,
+            "authorization": authorization,
+            "otherAudioPlaying": AVAudioSession.sharedInstance().isOtherAudioPlaying,
+            "timestamp": Int(Date().timeIntervalSince1970 * 1000),
+            "source": NSNull(),
+            "playbackState": "unknown",
+            "isPlaying": false,
+            "itemId": NSNull(),
+            "title": NSNull(),
+            "artist": NSNull(),
+            "album": NSNull(),
+            "duration": NSNull(),
+            "position": NSNull(),
+            "artworkDataURL": NSNull(),
+        ]
+        guard isAuthorized else { return result }
+
+        let player = self.player
+        let state = player.playbackState
+        result["source"] = player.source
+        result["playbackState"] = Self.playbackStateName(state)
+        result["isPlaying"] = state == .playing || state == .seekingForward || state == .seekingBackward
+        guard let item = player.item else { return result }
+
+        result["itemId"] = item.id
+        result["title"] = Self.orNull(item.title)
+        result["artist"] = Self.orNull(item.artist)
+        result["album"] = Self.orNull(item.album)
+        result["duration"] = Self.orNull(item.duration.isFinite && item.duration > 0 ? item.duration : nil)
+        let position = player.currentPlaybackTime
+        result["position"] = Self.orNull(position.isFinite && position >= 0 ? position : nil)
+        result["artworkDataURL"] = Self.orNull(artworkDataURL(for: item))
+        return result
+    }
+
+    private static func orNull(_ value: Any?) -> Any { value ?? NSNull() }
+
+    /// A small JPEG of the artwork as a data URL, drawn once per song.
+    private func artworkDataURL(for item: CraftMusicItem) -> String? {
+        if let cached = artworkCache, cached.id == item.id { return cached.dataURL }
+        let side = Self.artworkPixels
+        var dataURL: String?
+        if let image = item.artwork(CGSize(width: side, height: side)) {
+            let format = UIGraphicsImageRendererFormat()
+            format.scale = 1
+            format.opaque = true
+            let fitted = UIGraphicsImageRenderer(size: CGSize(width: side, height: side), format: format).image { _ in
+                // Fill the square, as a cover does, cropping the long side.
+                let scale = max(side / max(image.size.width, 1), side / max(image.size.height, 1))
+                let size = CGSize(width: image.size.width * scale, height: image.size.height * scale)
+                image.draw(in: CGRect(x: (side - size.width) / 2, y: (side - size.height) / 2, width: size.width, height: size.height))
+            }
+            if let jpeg = fitted.jpegData(compressionQuality: 0.75) {
+                dataURL = "data:image/jpeg;base64," + jpeg.base64EncodedString()
+            }
+        }
+        artworkCache = (item.id, dataURL)
+        return dataURL
+    }
+
+    // MARK: Transport
+
+    /// play, pause, togglePlayPause, skipToNext or skipToPrevious. Resolves
+    /// with the snapshot a moment later, once the Music app has moved, so a
+    /// page can show the outcome without waiting for the change event.
+    ///
+    /// skipToPrevious behaves like the Music app's own back button: more
+    /// than `restartAfter` seconds into a song (3 unless given) it goes back
+    /// to the start of that song; 0 always goes to the previous one.
+    func control(_ command: String, restartAfter: Double?, completion: @escaping (Result<[String: Any], CraftMusicError>) -> Void) {
+        guard isAuthorized else {
+            completion(.failure(CraftMusicError(message: "Music access has not been allowed", code: "NOT_AUTHORIZED")))
+            return
+        }
+        let player = self.player
+        switch command {
+        case "play":
+            player.play()
+        case "pause":
+            player.pause()
+        case "togglePlayPause":
+            if player.playbackState == .playing { player.pause() } else { player.play() }
+        case "skipToNext":
+            player.skipToNextItem()
+        case "skipToPrevious":
+            let threshold = max(restartAfter ?? 3, 0)
+            if threshold > 0, player.currentPlaybackTime > threshold { player.skipToBeginning() } else { player.skipToPreviousItem() }
+        default:
+            completion(.failure(CraftMusicError(message: "Unknown music command: \(command)", code: "INVALID_ARGUMENT")))
+            return
+        }
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.25) {
+            completion(.success(self.snapshot()))
+        }
+    }
+
+    // MARK: Change events
+
+    /// Hear every change of song or playback state as a snapshot, or stop
+    /// hearing them (`nil`). One listener: the web view's page.
+    func observe(_ listener: Listener?) {
+        self.listener = listener
+        if listener != nil, !observing {
+            observing = true
+            if isAuthorized { startPlayerObservation() }
+            // Notifications stop while the app is suspended; coming back,
+            // the page hears where the music is now.
+            foregroundObserver = NotificationCenter.default.addObserver(
+                forName: UIApplication.willEnterForegroundNotification, object: nil, queue: .main
+            ) { [weak self] _ in self?.playerDidChange() }
+        } else if listener == nil, observing {
+            observing = false
+            if let observer = foregroundObserver { NotificationCenter.default.removeObserver(observer) }
+            foregroundObserver = nil
+            if isAuthorized { player.stopObserving() }
+        }
+    }
+
+    private func startPlayerObservation() {
+        player.startObserving()
+    }
+
+    /// A song change arrives as two or three notifications at once; the page
+    /// gets one snapshot for them.
+    private func playerDidChange() {
+        guard observing, !changeScheduled else { return }
+        changeScheduled = true
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
+            self.changeScheduled = false
+            guard self.observing, let listener = self.listener else { return }
+            listener(self.snapshot())
+        }
+    }
+}
+
+// MARK: - The Music app
+
+/// `MPMusicPlayerController.systemMusicPlayer`: the Music app's queue.
+final class CraftSystemMusicPlayer: CraftMusicPlayer {
+    let source = "appleMusic"
+    var onChange: (() -> Void)?
+    private var observers: [NSObjectProtocol] = []
+    private var player: MPMusicPlayerController { MPMusicPlayerController.systemMusicPlayer }
+
+    var item: CraftMusicItem? {
+        guard let item = player.nowPlayingItem else { return nil }
+        // A song streamed from the catalog and not in the library has no
+        // persistent ID; its store ID, or what it is called, still tells one
+        // song from the next.
+        let id: String
+        if item.persistentID != 0 { id = String(item.persistentID) }
+        else if !item.playbackStoreID.isEmpty && item.playbackStoreID != "0" { id = "store:" + item.playbackStoreID }
+        else { id = "title:" + (item.title ?? "") + "|" + (item.artist ?? "") }
+        let artwork = item.artwork
+        return CraftMusicItem(
+            id: id,
+            title: item.title,
+            artist: item.artist ?? item.albumArtist,
+            album: item.albumTitle,
+            duration: item.playbackDuration,
+            artwork: { size in artwork?.image(at: size) }
+        )
+    }
+
+    var playbackState: MPMusicPlaybackState { player.playbackState }
+    var currentPlaybackTime: TimeInterval { player.currentPlaybackTime }
+
+    func play() { player.play() }
+    func pause() { player.pause() }
+    func skipToNextItem() { player.skipToNextItem() }
+    func skipToPreviousItem() { player.skipToPreviousItem() }
+    func skipToBeginning() { player.skipToBeginning() }
+
+    func startObserving() {
+        guard observers.isEmpty else { return }
+        let player = self.player
+        player.beginGeneratingPlaybackNotifications()
+        let center = NotificationCenter.default
+        for name in [Notification.Name.MPMusicPlayerControllerNowPlayingItemDidChange, .MPMusicPlayerControllerPlaybackStateDidChange] {
+            observers.append(center.addObserver(forName: name, object: player, queue: .main) { [weak self] _ in self?.onChange?() })
+        }
+    }
+
+    func stopObserving() {
+        guard !observers.isEmpty else { return }
+        observers.forEach { NotificationCenter.default.removeObserver($0) }
+        observers.removeAll()
+        player.endGeneratingPlaybackNotifications()
+    }
+}
+
+// MARK: - The simulator's stand-in
+
+/// Three made-up songs that play, pause and skip like the Music app, so the
+/// bridge, the page's bar and its events can be tried in the simulator.
+/// Never used on a device (see `CraftMusic.makePlayer`).
+final class CraftFakeMusicPlayer: CraftMusicPlayer {
+    let source = "simulated"
+    var onChange: (() -> Void)?
+    private var observing = false
+
+    private let songs: [(title: String, artist: String, album: String, duration: TimeInterval, hue: CGFloat)] = [
+        ("Intervals", "The Pacers", "Tempo Run", 214, 0.02),
+        ("Long Way Home", "Zone Two", "Base Miles", 251, 0.58),
+        ("Cooldown", "Recovery Club", "Easy Days", 187, 0.33),
+    ]
+    private var index = 0
+    private var state: MPMusicPlaybackState = .paused
+    /// Where the song was when it last started or stopped, and when that was.
+    private var offset: TimeInterval = 0
+    private var startedAt: Date?
+
+    var item: CraftMusicItem? {
+        let song = songs[index]
+        return CraftMusicItem(
+            id: "simulated-\(index)",
+            title: song.title,
+            artist: song.artist,
+            album: song.album,
+            duration: song.duration,
+            artwork: { size in
+                UIGraphicsImageRenderer(size: size).image { context in
+                    UIColor(hue: song.hue, saturation: 0.7, brightness: 0.85, alpha: 1).setFill()
+                    context.fill(CGRect(origin: .zero, size: size))
+                }
+            }
+        )
+    }
+
+    var playbackState: MPMusicPlaybackState { state }
+    var currentPlaybackTime: TimeInterval {
+        guard let startedAt = startedAt else { return offset }
+        return min(offset + Date().timeIntervalSince(startedAt), songs[index].duration)
+    }
+
+    func play() {
+        guard state != .playing else { return }
+        state = .playing
+        startedAt = Date()
+        changed()
+    }
+
+    func pause() {
+        guard state == .playing else { return }
+        offset = currentPlaybackTime
+        startedAt = nil
+        state = .paused
+        changed()
+    }
+
+    func skipToNextItem() { move(to: (index + 1) % songs.count) }
+    func skipToPreviousItem() { move(to: (index + songs.count - 1) % songs.count) }
+
+    func skipToBeginning() {
+        offset = 0
+        if state == .playing { startedAt = Date() }
+        changed()
+    }
+
+    func startObserving() { observing = true }
+    func stopObserving() { observing = false }
+
+    private func move(to next: Int) {
+        index = next
+        offset = 0
+        startedAt = state == .playing ? Date() : nil
+        changed()
+    }
+
+    private func changed() {
+        guard observing else { return }
+        DispatchQueue.main.async { self.onChange?() }
+    }
+}

package/dist/ios/templates/CraftNativeActions.swift

@@ -38,7 +38,7 @@ enum CraftNativeActions {
     private static let sqliteTransient = unsafeBitCast(-1, to: sqlite3_destructor_type.self)
 
     static func capabilities(config: CraftConfig) -> [String] {
-        var values = ["device", "clipboard", "haptics", "storage", "lifecycle", "fetch"]
+        var values = ["device", "clipboard", "haptics", "storage", "lifecycle", "fetch", "dialog"]
         if config.enableBiometric { values.append("biometric") }
         if config.enableSecureStorage { values.append("secureStorage") }
         if config.enableLocalDatabase { values.append("database") }
@@ -146,6 +146,23 @@ enum CraftNativeActions {
             }
             databaseQueue.async { complete(requestToken, database(method: method, args: args), completion) }
             return
+        case ("Dialog", _):
+            // The system's own alert, confirmation and action sheet, the same
+            // ones a page gets (CraftNativeUI.swift), over the native screen.
+            let body = args.first as? [String: Any] ?? [:]
+            DispatchQueue.main.async {
+                switch method {
+                case "alert":
+                    CraftDialogs.alert(body, from: nil) { complete(requestToken, .success(NSNull()), completion) }
+                case "confirm":
+                    CraftDialogs.confirm(body, from: nil) { complete(requestToken, .success($0), completion) }
+                case "actionSheet":
+                    CraftDialogs.actionSheet(body, from: nil) { complete(requestToken, .success($0 ?? NSNull()), completion) }
+                default:
+                    complete(requestToken, failure("UNKNOWN_ACTION", "Unsupported Dialog method"), completion)
+                }
+            }
+            return
         case ("Health", _):
             // Apple Health, the same as a page's `craft.health` (CraftHealth.swift).
             guard config.enableHealthKit else {

package/dist/ios/templates/CraftNativeFlatList.swift

@@ -525,7 +525,7 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
 
     private static func identity(for node: [String: Any]) -> String? {
         let props = node["props"] as? [String: Any] ?? [:]
-        return [node["id"], node["key"], props["key"], props["testID"]]
+        return [node["key"], props["key"], props["testID"], node["id"]]
             .compactMap { $0 as? String }
             .first { !$0.isEmpty }
     }

package/dist/ios/templates/CraftNativeScreen.swift

@@ -3528,7 +3528,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     private func explicitKey(_ node: [String: Any], props: [String: Any]) -> String? {
         // The current @stacksjs/stx native compiler emits key in props; accept the IR
         // field too so keyed children keep working when the compiler adopts it.
-        [node["id"], node["key"], props["key"], props["testID"]]
+        [node["key"], props["key"], props["testID"], node["id"]]
             .compactMap { $0 as? String }
             .first { !$0.isEmpty }
     }
@@ -4328,7 +4328,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             view.accessibilityValue = nil
         }
         let role = props["accessibilityRole"] as? String
-        view.isAccessibilityElement = role != "none" && (view.accessibilityLabel != nil || role != nil || ["Text", "Button", "Link", "Image", "TextInput", "Picker", "Switch", "Slider"].contains(type))
+        view.isAccessibilityElement = role != "none" && (view.accessibilityLabel != nil || role != nil || ["Text", "Button", "Link", "Image", "Video", "TextInput", "Picker", "Switch", "Slider"].contains(type))
         var traits: UIAccessibilityTraits = []
         switch role ?? type.lowercased() {
         case "button": traits.insert(.button)

package/dist/mobile.js

@@ -713,6 +713,116 @@ var speech = {
     getWebSpeech()?.synthesis.cancel();
   }
 };
+var MUSIC_AUTHORIZATIONS = ["authorized", "denied", "restricted", "notDetermined", "unavailable"];
+var MUSIC_STATES = ["stopped", "playing", "paused", "interrupted", "seekingForward", "seekingBackward", "unknown"];
+function musicAuthorization(value) {
+  return MUSIC_AUTHORIZATIONS.includes(value) ? value : "unavailable";
+}
+function musicText(value) {
+  return typeof value === "string" && value.trim() ? value : null;
+}
+function musicSeconds(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function normalizeNowPlaying(value) {
+  const raw = value && typeof value === "object" ? value : {};
+  const playbackState = MUSIC_STATES.includes(raw.playbackState) ? raw.playbackState : "unknown";
+  const artwork = musicText(raw.artworkDataURL);
+  return {
+    available: raw.available !== false && Object.keys(raw).length > 0,
+    authorization: musicAuthorization(raw.authorization),
+    source: raw.source === "appleMusic" || raw.source === "simulated" ? raw.source : null,
+    playbackState,
+    isPlaying: raw.isPlaying === true,
+    itemId: musicText(raw.itemId),
+    title: musicText(raw.title),
+    artist: musicText(raw.artist),
+    album: musicText(raw.album),
+    duration: musicSeconds(raw.duration),
+    position: musicSeconds(raw.position),
+    artworkDataURL: artwork && artwork.startsWith("data:image/") ? artwork : null,
+    otherAudioPlaying: raw.otherAudioPlaying === true,
+    timestamp: typeof raw.timestamp === "number" && Number.isFinite(raw.timestamp) ? raw.timestamp : Date.now()
+  };
+}
+function nothingPlaying() {
+  return normalizeNowPlaying({ available: false, authorization: "unavailable" });
+}
+function nativeMusic() {
+  const craft = getCraftRoot();
+  if (!craft?.music || craft.capabilities?.music === false)
+    return;
+  return craft.music;
+}
+var musicWatch = { listeners: new Set, stop: null };
+function startMusicWatch(native) {
+  if (musicWatch.stop || typeof window === "undefined")
+    return;
+  const onChange = (event) => {
+    const nowPlaying = normalizeNowPlaying(event.detail);
+    for (const listener of [...musicWatch.listeners]) {
+      try {
+        listener(nowPlaying);
+      } catch {}
+    }
+  };
+  window.addEventListener("craftMusicChange", onChange);
+  Promise.resolve(native.observe?.(true)).catch(() => {});
+  musicWatch.stop = () => {
+    window.removeEventListener("craftMusicChange", onChange);
+    Promise.resolve(native.observe?.(false)).catch(() => {});
+  };
+}
+async function musicCommand(method, options) {
+  const native = nativeMusic();
+  if (typeof native?.[method] !== "function")
+    return nothingPlaying();
+  return normalizeNowPlaying(await native[method](options));
+}
+var music = {
+  isAvailable() {
+    return typeof nativeMusic()?.getNowPlaying === "function";
+  },
+  supports(method) {
+    return typeof nativeMusic()?.[method] === "function";
+  },
+  async getAuthorizationStatus() {
+    const native = nativeMusic();
+    if (typeof native?.getAuthorizationStatus !== "function")
+      return "unavailable";
+    return musicAuthorization(await native.getAuthorizationStatus());
+  },
+  async requestAuthorization() {
+    const native = nativeMusic();
+    if (typeof native?.requestAuthorization !== "function")
+      return "unavailable";
+    return musicAuthorization(await native.requestAuthorization());
+  },
+  async getNowPlaying() {
+    const native = nativeMusic();
+    if (typeof native?.getNowPlaying !== "function")
+      return nothingPlaying();
+    return normalizeNowPlaying(await native.getNowPlaying());
+  },
+  play: () => musicCommand("play"),
+  pause: () => musicCommand("pause"),
+  togglePlayPause: () => musicCommand("togglePlayPause"),
+  skipToNext: () => musicCommand("skipToNext"),
+  skipToPrevious: (options = {}) => musicCommand("skipToPrevious", options),
+  onChange(callback) {
+    const native = nativeMusic();
+    if (typeof native?.observe !== "function")
+      return () => {};
+    musicWatch.listeners.add(callback);
+    startMusicWatch(native);
+    return () => {
+      if (!musicWatch.listeners.delete(callback) || musicWatch.listeners.size > 0)
+        return;
+      musicWatch.stop?.();
+      musicWatch.stop = null;
+    };
+  }
+};
 var deepLinks = {
   async getInitialURL() {
     return normalizeDeepLinkURL(await getCraftRoot()?.deepLinks?.getInitialURL?.());
@@ -1203,8 +1313,10 @@ export {
   pushNotifications,
   permissions,
   notifications,
+  normalizeNowPlaying,
   normalizeDeepLinkURL,
   network,
+  music,
   location,
   liveActivities,
   lifecycle,

package/package.json

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