@craft-native/ios 0.0.143 → 0.0.144

package/README.md

@@ -178,6 +178,7 @@ Edit `craft.config.json` in your iOS project:
   "enableBluetooth": true,
   "enableNFC": true,
   "enableHealthKit": false,
+  "enableAppleMusic": false,
   "enableScreenCapture": true,
   "iosVersion": "15.0",
   "teamId": ""
@@ -188,6 +189,18 @@ The app name is shown as written (`"HQ.training"` is fine); the Xcode
 project, target and Swift types use a PascalCase identifier made from it
 (`HQTraining`). A key left out of the file keeps its default.
 
+Purpose strings in your own words, by Info.plist key (each replaces Craft's
+generic sentence; the keys for frameworks the shell links are always written,
+since App Store Connect checks the binary):
+
+```json
+{
+  "usageDescriptions": {
+    "NSAppleMusicUsageDescription": "Shows the song playing during a workout and lets you pause or skip it."
+  }
+}
+```
+
 Appearance and navigation:
 
 ```json
@@ -520,6 +533,31 @@ window.craft.setKeepAwake(false); // Allow screen dimming
 const level = await window.craft.getBrightness();   // 0.62
 await window.craft.setBrightness(0.1);              // resolves with what the screen reports
 
+// Apple Music (enableAppleMusic): what the Music app is playing, and its
+// transport, through MPMusicPlayerController.systemMusicPlayer. Only Apple
+// Music: iOS gives no app another player's controls, so while Spotify or a
+// podcast app plays, the song fields are null and otherAudioPlaying is true.
+// Nothing is read until the person allows media library access, which only
+// requestAuthorization() asks for (call it from their tap, never at launch).
+// Word the prompt with usageDescriptions.NSAppleMusicUsageDescription.
+await window.craft.music.requestAuthorization(); // 'authorized' | 'denied' | 'restricted' | 'notDetermined'
+const now = await window.craft.music.getNowPlaying();
+// { available, authorization, source: 'appleMusic', playbackState: 'playing', isPlaying,
+//   itemId, title, artist, album, duration, position, timestamp,
+//   artworkDataURL: 'data:image/jpeg;base64,…' (120 px, or null), otherAudioPlaying }
+await window.craft.music.togglePlayPause(); // play() / pause() too; each resolves with the snapshot
+await window.craft.music.skipToNext();
+await window.craft.music.skipToPrevious({ restartAfter: 3 }); // like Music's own button; 0 = always previous
+await window.craft.music.observe(true); // then every change arrives as craftMusicChange
+window.addEventListener('craftMusicChange', (event) => render(event.detail));
+// Or `import { music } from 'craft-native/mobile'`: music.onChange(callback)
+// observes while anyone listens, and off a phone every call answers
+// { available: false } without doing anything.
+// The simulator's Music app has nothing to play: launch with
+// `-CraftFakeMusicPlayer YES` (or `simctl spawn <device> defaults write <bundle id>
+// CraftFakeMusicPlayer -bool YES`) for three made-up songs that play and skip.
+// Simulator builds only; a device always talks to the Music app.
+
 // Speech: short spoken cues that duck the person's music instead of stopping
 // it, and play with the silent switch on. Always available (no config flag).
 // Resolves when the utterance ends: true if spoken, false if stopped or

package/dist/cli.js

@@ -114,6 +114,7 @@ var DEFAULT_CONFIG = {
   enablePDFViewer: false,
   enableAR: false,
   enableMLKit: false,
+  enableAppleMusic: false,
   iosVersion: "16.0",
   watchosVersion: "9.0",
   teamId: "",
@@ -157,7 +158,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 = [
@@ -175,9 +177,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];
@@ -724,6 +731,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/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/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/package.json

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

package/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/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?() }
+    }
+}