From 336b2266e89a16ef3701390e75b8e13b111a564d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BE=90=E7=BF=94=E5=AE=87?= <xu010314@163.com>
Date: Mon, 20 Apr 2026 15:02:36 +0800
Subject: [PATCH] =?UTF-8?q?v2.0.4:=20latency=20razor=20=E2=80=94=20event-d?=
 =?UTF-8?q?riven=20+=20running-app=20gate=20+=20parallel=20probing?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Target: push state-change detection latency under 200ms in the common case,
and cold start under 2s.

Changes:

1. Event-driven primary path, poll becomes safety-net
   - Poll interval 1.5s → 15s. Was firing 40 AppleScript probes per minute
     on a Mac that's playing nothing.
   - MediaRemote notifications + DistributedNotificationCenter broadcasts
     (com.spotify.client.PlaybackStateChanged,
      com.apple.Music.playerInfo, com.apple.iTunes.playerInfo)
     already handle track changes in <100ms. The 1.5s poll was just
     backup, and now 15s is enough backup.

2. NSWorkspace launch/terminate observers
   - New observers on NSWorkspace.didLaunchApplicationNotification +
     didTerminateApplicationNotification. When Spotify, Apple Music, or
     Chrome launches / quits, refresh fires immediately instead of
     waiting for the next poll. Beats the old path by up to 15s on
     first-launch-of-day scenarios.

3. Running-app gate (NSWorkspace.runningApplications)
   - Each source now exposes `static var isRunning` via
     NSWorkspace.shared.runningApplications.contains(bundleId).
   - Router checks before probing. AppleScript `with timeout of 2 seconds`
     still trips when the target app isn't running, so avoiding those
     probes saves up to 6s per refresh on a clean Mac.

4. MediaRemote 15.4+ entitlement memoization
   - When MRMediaRemoteGetNowPlayingInfo returns an empty dict AND at
     least one player app is running (likelyBlocked heuristic), mark
     MediaRemote blocked for 60s and skip in the router. Saves ~50ms
     per refresh on restricted macOS versions and lets the first-pass
     AppleScript probe happen without a preceding MR round-trip.
   - Retries every 60s in case the gate state changes (macOS minor
     update / user-granted entitlement).

5. Parallel fallback probing
   - Old router was serial: MediaRemote → Spotify → Music → Chrome.
     Cold start worst-case 4-6s when all three AppleScript sources
     trip their 2s timeouts.
   - New router uses `async let` to fan out every live candidate
     concurrently. First-in-priority-order non-nil result wins.
     Cold start worst-case now ≈ slowest single AppleScript probe.

6. Sticky-source fast path survives
   - When the last-successful source is still a live candidate
     (its app still running, MR still not blocked), try it alone
     first. On steady-state playback this is one round-trip per
     refresh, same as before.

7. Transport control perceived latency
   - scheduleRefresh(after: 0.3) → 0.1 for togglePlay/next/prev/seek.
     UI already flips optimistically; the 100ms re-sync is enough
     to catch the real app state without feeling laggy.

Reference: Atoll (github.com/Ebullioscopic/Atoll) uses a bundled
mediaremote-adapter framework + Perl stream client to bypass the
macOS 15.4 MediaRemote entitlement gate entirely. That's a bigger
lift and left for a future phase — this commit wrings out the latency
that's achievable without that adapter.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 Info.plist                                  |   4 +-
 Sources/NowPlayingState.swift               | 231 ++++++++++++++++++--
 Sources/sources/AppleMusicAppleScript.swift |   9 +
 Sources/sources/ChromeWebSource.swift       |   8 +
 Sources/sources/SpotifyAppleScript.swift    |  11 +-
 5 files changed, 238 insertions(+), 25 deletions(-)

diff --git a/Info.plist b/Info.plist
index ae24d67..a8f2804 100644
--- a/Info.plist
+++ b/Info.plist
@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>BNDL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2.0.3</string>
+    <string>2.0.4</string>
     <key>CFBundleVersion</key>
-    <string>5</string>
+    <string>6</string>
     <key>NSPrincipalClass</key>
     <string>MusicPlugin.MusicPlugin</string>
     <!--
diff --git a/Sources/NowPlayingState.swift b/Sources/NowPlayingState.swift
index a6a4081..380a56c 100644
--- a/Sources/NowPlayingState.swift
+++ b/Sources/NowPlayingState.swift
@@ -100,6 +100,20 @@ final class NowPlayingState: ObservableObject {
     private var isRunning = false
     private var refreshInFlight = false
 
+    /// macOS 15.4+ gates MRMediaRemoteGetNowPlayingInfo behind a private
+    /// entitlement. When the call returns an empty dict we mark the API
+    /// as blocked and skip it for 60 seconds before retrying (macOS minor
+    /// updates can flip the entitlement state, so we don't mark "blocked
+    /// forever"). Saves ~50ms per refresh when blocked, but more importantly
+    /// lets the router hit AppleScript on the first pass instead of the
+    /// second — ~1s faster cold start on restricted systems.
+    private var mediaRemoteBlockedUntil: Date?
+
+    /// NSWorkspace observers for app launch/terminate. When a music app
+    /// opens or closes, refresh immediately — these events beat the poll
+    /// timer by several seconds.
+    private var workspaceObservers: [NSObjectProtocol] = []
+
     private init() {}
 
     // MARK: - Lifecycle
@@ -142,6 +156,39 @@ final class NowPlayingState: ObservableObject {
             object: nil
         )
 
+        // Observe app launch / terminate — when Spotify or Music opens, we
+        // want to detect it within the same RunLoop tick rather than waiting
+        // out the 15s safety-net poll.
+        let wsCenter = NSWorkspace.shared.notificationCenter
+        let trackedBundleIds: Set<String> = [
+            SpotifyAppleScript.bundleId,
+            AppleMusicAppleScript.bundleId,
+            ChromeWebSource.bundleId,
+        ]
+        let launchToken = wsCenter.addObserver(
+            forName: NSWorkspace.didLaunchApplicationNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] note in
+            guard
+                let bid = (note.userInfo?[NSWorkspace.applicationUserInfoKey] as? NSRunningApplication)?.bundleIdentifier,
+                trackedBundleIds.contains(bid)
+            else { return }
+            Task { @MainActor in self?.refresh() }
+        }
+        let terminateToken = wsCenter.addObserver(
+            forName: NSWorkspace.didTerminateApplicationNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] note in
+            guard
+                let bid = (note.userInfo?[NSWorkspace.applicationUserInfoKey] as? NSRunningApplication)?.bundleIdentifier,
+                trackedBundleIds.contains(bid)
+            else { return }
+            Task { @MainActor in self?.refresh() }
+        }
+        workspaceObservers = [launchToken, terminateToken]
+
         startPolling()
         refresh()
     }
@@ -156,6 +203,12 @@ final class NowPlayingState: ObservableObject {
         playbackTimer?.invalidate()
         playbackTimer = nil
         DistributedNotificationCenter.default().removeObserver(self)
+
+        let wsCenter = NSWorkspace.shared.notificationCenter
+        for token in workspaceObservers {
+            wsCenter.removeObserver(token)
+        }
+        workspaceObservers.removeAll()
     }
 
     @objc private func spotifyStateChanged() {
@@ -170,11 +223,17 @@ final class NowPlayingState: ObservableObject {
 
     private func startPolling() {
         pollTimer?.invalidate()
-        // 1.5s poll balances track-change detection latency (previously 3s)
-        // against the cost of repeated AppleScript probes. At 1.5s, switching
-        // between tracks in Apple Music typically reflects in the UI within
-        // two seconds including AppleScript round-trip.
-        pollTimer = Timer.scheduledTimer(withTimeInterval: 1.5, repeats: true) { [weak self] _ in
+        // 15s safety-net poll. The fast path is now fully event-driven:
+        //   - MediaRemote notifications (instant, when not 15.4-blocked)
+        //   - DistributedNotificationCenter for Spotify / Music / iTunes
+        //     playerInfo broadcasts (instant, fires on every track change)
+        //   - NSWorkspace app launch/terminate observers (instant)
+        // The poll only exists to catch web players (no notifications) and
+        // to recover from any missed distributed broadcast. Going from 1.5s
+        // → 15s cuts the AppleScript wake-up rate by 10x without hurting
+        // perceived latency, because every real state change hits one of
+        // the three event paths in under 100ms.
+        pollTimer = Timer.scheduledTimer(withTimeInterval: 15.0, repeats: true) { [weak self] _ in
             Task { @MainActor in self?.refresh() }
         }
     }
@@ -198,21 +257,35 @@ final class NowPlayingState: ObservableObject {
     }
 
     private func routeSources(allowAppleScript: Bool) async {
-        // Build the order: sticky source first, then the default chain.
-        let defaultOrder: [NowPlayingSourceKind] = [
-            .mediaRemote, .spotify, .appleMusic, .chrome
-        ]
-        var order: [NowPlayingSourceKind] = []
-        if stickySource != .none { order.append(stickySource) }
-        for kind in defaultOrder where kind != stickySource {
-            order.append(kind)
+        // Running-app snapshot — read once per pass so we don't hit the
+        // workspace API four times.
+        let spotifyRunning = SpotifyAppleScript.isRunning
+        let musicRunning = AppleMusicAppleScript.isRunning
+        let chromeRunning = ChromeWebSource.isRunning
+
+        // MediaRemote gate: on macOS 15.4+ the call returns an empty dict
+        // without entitlement. Cache that for 60s so we don't keep eating
+        // an IPC round-trip per refresh.
+        let now = Date()
+        let mrBlocked: Bool
+        if let until = mediaRemoteBlockedUntil, until > now {
+            mrBlocked = true
+        } else {
+            mrBlocked = false
         }
 
-        for kind in order {
-            // Skip AppleScript sources when the host cannot grant permission.
-            if !allowAppleScript, kind != .mediaRemote { continue }
-
-            if let used = await tryFetch(kind) {
+        // Sticky-source fast path — if the last successful source is still
+        // a live candidate, try it alone first. One AppleScript round-trip
+        // when music is playing = lowest possible latency path.
+        if stickySource != .none, isCandidateLive(
+            stickySource,
+            spotifyRunning: spotifyRunning,
+            musicRunning: musicRunning,
+            chromeRunning: chromeRunning,
+            mrBlocked: mrBlocked,
+            allowAppleScript: allowAppleScript
+        ) {
+            if let used = await tryFetch(stickySource) {
                 await MainActor.run {
                     self.stickySource = used
                     self.updatePlaybackTimer()
@@ -221,6 +294,80 @@ final class NowPlayingState: ObservableObject {
             }
         }
 
+        // Parallel fallback probing. `async let` fans out all live candidates
+        // concurrently — cold start used to serialize: try MR (~50ms, miss on
+        // 15.4+) → try Spotify AppleScript (~100-2000ms) → try Music (~100-2000ms)
+        // → try Chrome (~200ms+). Worst case ~6s. Now they all race and we
+        // use the first non-nil result by priority.
+        async let mrResult: MediaRemoteInfo? = mrBlocked ? nil : mediaRemoteFetch()
+        async let spotifyResult: AppleScriptTrackInfo? = (allowAppleScript && spotifyRunning)
+            ? SpotifyAppleScript.fetch() : nil
+        async let musicResult: AppleScriptTrackInfo? = (allowAppleScript && musicRunning)
+            ? AppleMusicAppleScript.fetch() : nil
+        async let chromeResult: ChromeTrackInfo? = (allowAppleScript && chromeRunning)
+            ? ChromeWebSource.fetch() : nil
+
+        let mr = await mrResult
+        let sp = await spotifyResult
+        let mu = await musicResult
+        let ch = await chromeResult
+
+        // MediaRemote returning empty on 15.4+ marks it blocked for 60s.
+        if !mrBlocked, mr == nil, mediaRemoteLikelyBlocked() {
+            await MainActor.run {
+                self.mediaRemoteBlockedUntil = Date().addingTimeInterval(60)
+            }
+        }
+
+        // Priority order for picking the winner among the parallel results.
+        // MediaRemote first (it unifies everything when available). Then
+        // Spotify > Apple Music > Chrome — Spotify desktop tends to have
+        // fuller metadata than web, and Apple Music's AppleScript is slower
+        // so it gets slight demotion when a competing hit exists.
+        if let info = mr, info.hasTrack {
+            await MainActor.run {
+                self.apply(mediaRemote: info)
+                self.stickySource = .mediaRemote
+                self.updatePlaybackTimer()
+            }
+            return
+        }
+        if let info = sp, !info.title.isEmpty {
+            await MainActor.run {
+                self.apply(appleScript: info)
+                self.stickySource = .spotify
+                self.updatePlaybackTimer()
+            }
+            if self.albumArt == nil, let art = await SpotifyAppleScript.fetchArtwork() {
+                await MainActor.run { self.albumArt = art }
+            }
+            return
+        }
+        if let info = mu, !info.title.isEmpty {
+            await MainActor.run {
+                self.apply(appleScript: info)
+                self.stickySource = .appleMusic
+                self.updatePlaybackTimer()
+            }
+            if self.albumArt == nil, let art = await AppleMusicAppleScript.fetchArtwork() {
+                await MainActor.run { self.albumArt = art }
+            }
+            return
+        }
+        if let info = ch, !info.title.isEmpty {
+            await MainActor.run {
+                self.apply(chrome: info)
+                self.stickySource = .chrome
+                self.updatePlaybackTimer()
+            }
+            if let artURL = info.artworkURL, let url = URL(string: artURL) {
+                if let image = await downloadImage(from: url) {
+                    await MainActor.run { self.albumArt = image }
+                }
+            }
+            return
+        }
+
         // Nothing returned a hit; clear state.
         await MainActor.run {
             self.clearTrack()
@@ -229,6 +376,46 @@ final class NowPlayingState: ObservableObject {
         }
     }
 
+    /// Whether a source could plausibly produce a hit right now given the
+    /// running-app snapshot + MediaRemote blocked state. Used to short-circuit
+    /// the sticky-source fast path — don't probe Spotify if Spotify is closed.
+    private func isCandidateLive(
+        _ kind: NowPlayingSourceKind,
+        spotifyRunning: Bool,
+        musicRunning: Bool,
+        chromeRunning: Bool,
+        mrBlocked: Bool,
+        allowAppleScript: Bool
+    ) -> Bool {
+        switch kind {
+        case .none: return false
+        case .mediaRemote: return !mrBlocked
+        case .spotify: return allowAppleScript && spotifyRunning
+        case .appleMusic: return allowAppleScript && musicRunning
+        case .chrome: return allowAppleScript && chromeRunning
+        }
+    }
+
+    /// Bridge the MediaRemote callback-style API to async/await so we can
+    /// fan it out alongside the AppleScript sources in `routeSources`.
+    private func mediaRemoteFetch() async -> MediaRemoteInfo? {
+        await withCheckedContinuation { cont in
+            Task { @MainActor in
+                self.mediaRemote.fetchInfo { cont.resume(returning: $0) }
+            }
+        }
+    }
+
+    /// Heuristic for "MediaRemote returned empty because Apple blocked us,
+    /// not because no one is playing". If at least one of the known player
+    /// apps is running but MediaRemote came back nil, the cause is almost
+    /// certainly the 15.4+ entitlement gate.
+    private func mediaRemoteLikelyBlocked() -> Bool {
+        SpotifyAppleScript.isRunning ||
+        AppleMusicAppleScript.isRunning ||
+        ChromeWebSource.isRunning
+    }
+
     /// Try a single source. Returns the source kind on success, nil on miss.
     private func tryFetch(_ kind: NowPlayingSourceKind) async -> NowPlayingSourceKind? {
         switch kind {
@@ -371,7 +558,7 @@ final class NowPlayingState: ObservableObject {
         }
 
         // Confirm from the real source after a short delay.
-        scheduleRefresh(after: 0.3)
+        scheduleRefresh(after: 0.1)
     }
 
     func nextTrack() {
@@ -386,7 +573,7 @@ final class NowPlayingState: ObservableObject {
         case .mediaRemote, .none:
             mediaRemote.sendCommand(.nextTrack)
         }
-        scheduleRefresh(after: 0.3)
+        scheduleRefresh(after: 0.1)
     }
 
     func previousTrack() {
@@ -400,7 +587,7 @@ final class NowPlayingState: ObservableObject {
         case .mediaRemote, .none:
             mediaRemote.sendCommand(.previousTrack)
         }
-        scheduleRefresh(after: 0.3)
+        scheduleRefresh(after: 0.1)
     }
 
     func seek(to time: TimeInterval) {
@@ -420,7 +607,7 @@ final class NowPlayingState: ObservableObject {
             mediaRemote.setElapsedTime(clamped)
         }
 
-        scheduleRefresh(after: 0.3)
+        scheduleRefresh(after: 0.1)
     }
 
     private func scheduleRefresh(after delay: TimeInterval) {
diff --git a/Sources/sources/AppleMusicAppleScript.swift b/Sources/sources/AppleMusicAppleScript.swift
index 8b8ba67..982eca2 100644
--- a/Sources/sources/AppleMusicAppleScript.swift
+++ b/Sources/sources/AppleMusicAppleScript.swift
@@ -15,6 +15,15 @@ enum AppleMusicAppleScript {
     static let bundleId = "com.apple.Music"
     private static let sourceName = "Apple Music"
 
+    /// Fast check: is Music.app actually running? When false, skip
+    /// AppleScript — the 2s `with timeout` still trips but that's two
+    /// wasted seconds per refresh when the user doesn't use Apple Music.
+    static var isRunning: Bool {
+        NSWorkspace.shared.runningApplications.contains {
+            $0.bundleIdentifier == bundleId
+        }
+    }
+
     // MARK: - Fetch
 
     static func fetch() async -> AppleScriptTrackInfo? {
diff --git a/Sources/sources/ChromeWebSource.swift b/Sources/sources/ChromeWebSource.swift
index 3566280..ca9c709 100644
--- a/Sources/sources/ChromeWebSource.swift
+++ b/Sources/sources/ChromeWebSource.swift
@@ -31,6 +31,14 @@ struct ChromeTrackInfo {
 enum ChromeWebSource {
     static let bundleId = "com.google.Chrome"
 
+    /// Fast check: is Chrome running? JS-injection probing costs ~200ms
+    /// even on a hot path; skip entirely when Chrome isn't running.
+    static var isRunning: Bool {
+        NSWorkspace.shared.runningApplications.contains {
+            $0.bundleIdentifier == bundleId
+        }
+    }
+
     // MARK: - Fetch
 
     static func fetch() async -> ChromeTrackInfo? {
diff --git a/Sources/sources/SpotifyAppleScript.swift b/Sources/sources/SpotifyAppleScript.swift
index ffee773..8c4c3da 100644
--- a/Sources/sources/SpotifyAppleScript.swift
+++ b/Sources/sources/SpotifyAppleScript.swift
@@ -28,9 +28,18 @@ struct AppleScriptTrackInfo {
 }
 
 enum SpotifyAppleScript {
-    private static let bundleId = "com.spotify.client"
+    static let bundleId = "com.spotify.client"
     private static let sourceName = "Spotify"
 
+    /// Fast check: is Spotify actually running? When false, skip AppleScript
+    /// entirely — the 2s `with timeout` would still trip but that's two
+    /// wasted seconds per router pass for an app the user isn't using.
+    static var isRunning: Bool {
+        NSWorkspace.shared.runningApplications.contains {
+            $0.bundleIdentifier == bundleId
+        }
+    }
+
     // MARK: - Fetch
 
     static func fetch() async -> AppleScriptTrackInfo? {