react-native-queue-player 1.0.0

package/ios/Tests/AudioSessionTests.swift

@@ -0,0 +1,222 @@
+import XCTest
+import AVFoundation
+@testable import QueuePlayer
+
+// `AudioSession` is a pure-AVFoundation wrapper — no Nitrogen types — so
+// `@testable import` works cleanly here (unlike the rest of the library,
+// which wraps C++-interop types).
+
+/// `AudioSession` translates AVAudioSession notifications (interruption +
+/// route-change) into a library-level `InterruptionKind` / `RouteChangeKind`
+/// surface. These tests post synthetic notifications through
+/// NotificationCenter after `installObservers()` and verify the callback
+/// fires (or intentionally does not fire) with the translated value — no
+/// live audio session interaction needed.
+///
+/// Delivery model: `installObservers()` registers with `queue: .main`, so
+/// every observer block is *enqueued* onto the main queue when the
+/// notification is posted (even if posting from main — `NotificationCenter`
+/// still hops through the queue for `queue`-specific observers). The
+/// positive-case tests wait on an `XCTestExpectation` fulfilled inside the
+/// callback, so ordering is safe. The negative-case tests use an
+/// **inverted** expectation with a non-trivial timeout: if the callback
+/// ever fires during that window the expectation counts as over-fulfilled
+/// and XCTest fails the test. This is tighter than a timer-based drain
+/// because it survives main-queue scheduler pressure.
+///
+/// Observer idempotency: covered by calling `installObservers()` twice and
+/// fulfilling a positive expectation fired once by the retained (second)
+/// observer. The body asserts `fireCount == 1` after the main queue has
+/// drained, so stale pending blocks from the first registration would show
+/// up as an over-fulfilment and fail the test.
+final class AudioSessionTests: XCTestCase {
+
+  private var session: AudioSession!
+
+  override func setUp() {
+    super.setUp()
+    session = AudioSession()
+    session.installObservers()
+  }
+
+  override func tearDown() {
+    session.tearDownObservers()
+    session = nil
+    super.tearDown()
+  }
+
+  // MARK: - Interruption translation
+
+  func testInterruptionBeganTranslatesToBegan() {
+    let expect = expectation(description: "onInterruption fires with .began")
+    session.onInterruption = { kind in
+      if kind == .began { expect.fulfill() }
+      else { XCTFail("expected .began, got \(kind)") }
+    }
+    postInterruption(type: .began, options: nil)
+    wait(for: [expect], timeout: 1.0)
+  }
+
+  func testInterruptionEndedShouldResumeTranslatesToShouldResume() {
+    let expect = expectation(description: ".endedShouldResume")
+    session.onInterruption = { kind in
+      if kind == .endedShouldResume { expect.fulfill() }
+      else { XCTFail("expected .endedShouldResume, got \(kind)") }
+    }
+    postInterruption(type: .ended, options: [.shouldResume])
+    wait(for: [expect], timeout: 1.0)
+  }
+
+  func testInterruptionEndedWithoutShouldResumeTranslatesToShouldNotResume() {
+    let expect = expectation(description: ".endedShouldNotResume")
+    session.onInterruption = { kind in
+      if kind == .endedShouldNotResume { expect.fulfill() }
+      else { XCTFail("expected .endedShouldNotResume, got \(kind)") }
+    }
+    postInterruption(type: .ended, options: [])
+    wait(for: [expect], timeout: 1.0)
+  }
+
+  func testInterruptionEndedMissingOptionKeyTreatedAsShouldNotResume() {
+    // AVAudioSession sometimes emits an `.ended` notification without
+    // the `AVAudioSessionInterruptionOptionKey` userInfo entry. The
+    // fallback must be conservative: do NOT auto-resume music.
+    let expect = expectation(description: "missing options → .endedShouldNotResume")
+    session.onInterruption = { kind in
+      if kind == .endedShouldNotResume { expect.fulfill() }
+      else { XCTFail("expected .endedShouldNotResume, got \(kind)") }
+    }
+    let userInfo: [AnyHashable: Any] = [
+      AVAudioSessionInterruptionTypeKey:
+        AVAudioSession.InterruptionType.ended.rawValue,
+    ]
+    NotificationCenter.default.post(
+      name: AVAudioSession.interruptionNotification,
+      object: AVAudioSession.sharedInstance(),
+      userInfo: userInfo)
+    wait(for: [expect], timeout: 1.0)
+  }
+
+  func testInterruptionMalformedNotificationIsIgnored() {
+    let inverted = expectation(description: "onInterruption should NOT fire")
+    inverted.isInverted = true
+    session.onInterruption = { _ in inverted.fulfill() }
+    NotificationCenter.default.post(
+      name: AVAudioSession.interruptionNotification,
+      object: AVAudioSession.sharedInstance(),
+      userInfo: nil)
+    wait(for: [inverted], timeout: 0.5)
+  }
+
+  // MARK: - Route-change translation
+
+  func testRouteChangeOldDeviceUnavailableTranslates() {
+    let expect = expectation(description: ".oldDeviceUnavailable")
+    session.onRouteChange = { kind in
+      if kind == .oldDeviceUnavailable { expect.fulfill() }
+      else { XCTFail("expected .oldDeviceUnavailable, got \(kind)") }
+    }
+    postRouteChange(reason: .oldDeviceUnavailable)
+    wait(for: [expect], timeout: 1.0)
+  }
+
+  func testRouteChangeNewDeviceAvailableTranslates() {
+    let expect = expectation(description: ".newDeviceAvailable")
+    session.onRouteChange = { kind in
+      if kind == .newDeviceAvailable { expect.fulfill() }
+      else { XCTFail("expected .newDeviceAvailable, got \(kind)") }
+    }
+    postRouteChange(reason: .newDeviceAvailable)
+    wait(for: [expect], timeout: 1.0)
+  }
+
+  func testRouteChangeCategoryChangeIsSuppressed() {
+    // Our own `activate()` triggers a category change; exposing it would
+    // leak our own setup as a consumer-visible event. AudioSession filters
+    // these out intentionally.
+    let inverted = expectation(description: ".categoryChange must not fire callback")
+    inverted.isInverted = true
+    session.onRouteChange = { _ in inverted.fulfill() }
+    postRouteChange(reason: .categoryChange)
+    wait(for: [inverted], timeout: 0.5)
+  }
+
+  func testRouteChangeWakeFromSleepIsSuppressed() {
+    let inverted = expectation(description: ".wakeFromSleep must not fire callback")
+    inverted.isInverted = true
+    session.onRouteChange = { _ in inverted.fulfill() }
+    postRouteChange(reason: .wakeFromSleep)
+    wait(for: [inverted], timeout: 0.5)
+  }
+
+  // MARK: - Observer idempotency
+
+  func testInstallObserversIsIdempotent() {
+    // setUp already called installObservers() once. Calling it again must
+    // tear down the previous registration before re-adding, so a posted
+    // notification produces exactly one callback invocation — not two.
+    // `tearDownObservers` inside `installObservers` runs before the
+    // post, so no in-flight block from the first observer can linger.
+    session.installObservers()
+
+    let expect = expectation(description: "callback fires exactly once")
+    var fireCount = 0
+    session.onInterruption = { _ in
+      fireCount += 1
+      if fireCount == 1 { expect.fulfill() }
+    }
+    postInterruption(type: .began, options: nil)
+    wait(for: [expect], timeout: 1.0)
+    // Drain one more main-queue hop to expose any stray second fire from
+    // a stale observer that wasn't actually torn down.
+    let drain = expectation(description: "drain")
+    DispatchQueue.main.async { drain.fulfill() }
+    wait(for: [drain], timeout: 1.0)
+    XCTAssertEqual(fireCount, 1, "re-installing observers must not double-fire the callback")
+  }
+
+  func testTearDownObserversStopsCallbacks() {
+    session.tearDownObservers()
+    let inverted = expectation(description: "teardown should stop all further callbacks")
+    inverted.isInverted = true
+    session.onInterruption = { _ in inverted.fulfill() }
+    postInterruption(type: .began, options: nil)
+    wait(for: [inverted], timeout: 0.5)
+  }
+
+  func testTearDownIsSafeToCallTwice() {
+    XCTAssertNoThrow(session.tearDownObservers())
+    XCTAssertNoThrow(session.tearDownObservers())
+    // If tearDown wasn't idempotent an NSInternalInconsistency exception
+    // would propagate out of NotificationCenter — the two XCTAssertNoThrow
+    // checks capture that.
+  }
+
+  // MARK: - Helpers
+
+  private func postInterruption(
+    type: AVAudioSession.InterruptionType,
+    options: AVAudioSession.InterruptionOptions?
+  ) {
+    var userInfo: [AnyHashable: Any] = [
+      AVAudioSessionInterruptionTypeKey: type.rawValue,
+    ]
+    if let options = options {
+      userInfo[AVAudioSessionInterruptionOptionKey] = options.rawValue
+    }
+    NotificationCenter.default.post(
+      name: AVAudioSession.interruptionNotification,
+      object: AVAudioSession.sharedInstance(),
+      userInfo: userInfo)
+  }
+
+  private func postRouteChange(reason: AVAudioSession.RouteChangeReason) {
+    let userInfo: [AnyHashable: Any] = [
+      AVAudioSessionRouteChangeReasonKey: reason.rawValue,
+    ]
+    NotificationCenter.default.post(
+      name: AVAudioSession.routeChangeNotification,
+      object: AVAudioSession.sharedInstance(),
+      userInfo: userInfo)
+  }
+}

package/ios/Tests/AudioTapProviderReplayGainTests.swift

@@ -0,0 +1,136 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// Unit tests for the ReplayGain mode + gain-math paths in
+/// `AudioTapProvider`. The metadata-extraction async path + per-item
+/// recompute walk are covered at the integration layer (auto-suite
+/// `replaygain.ts` step). These tests drive the pure
+/// `computeLinearGain(data:mode:)` static helper plus the mode
+/// getter/setter round-trip.
+final class AudioTapProviderReplayGainTests: XCTestCase {
+
+  // Mode getter / setter round-trip is exercised at the integration
+  // layer (`replaygain.ts` auto-suite) — `getReplayGainMode`'s
+  // `ReplayGainMode` return type touches the Swift↔C++ interop
+  // graph, so direct equality from `@testable` XCTest can't observe
+  // it (NOTES.md §6). The pure gain-math matrix below is the unit
+  // surface; mode propagation lands in the integration tests.
+
+  // MARK: - computeLinearGain — strict mode + selection
+
+  func testComputeLinearGainOffAlwaysReturnsUnity() {
+    let data = ReplayGainData(
+      trackGainDb: -6.0, trackPeak: 0.95,
+      albumGainDb: -10.0, albumPeak: 0.90
+    )
+    XCTAssertEqual(AudioTapProvider.computeLinearGain(data: data, mode: .off), 1.0)
+  }
+
+  func testComputeLinearGainTrackMode() {
+    let data = ReplayGainData(
+      trackGainDb: -6.0, trackPeak: nil,
+      albumGainDb: -10.0, albumPeak: nil
+    )
+    let expected = Float(pow(10.0, -6.0 / 20.0))
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      expected, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainAlbumMode() {
+    let data = ReplayGainData(
+      trackGainDb: -6.0, trackPeak: nil,
+      albumGainDb: -10.0, albumPeak: nil
+    )
+    let expected = Float(pow(10.0, -10.0 / 20.0))
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .album),
+      expected, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainAlbumModeStrictReturnsUnityWhenAlbumTagMissing() {
+    // Strict no-fallback semantics: album mode requires album tag.
+    let data = ReplayGainData(
+      trackGainDb: -6.0, trackPeak: nil,
+      albumGainDb: nil, albumPeak: nil
+    )
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .album), 1.0,
+      "strict mode — album mode without album tag plays at unity"
+    )
+  }
+
+  func testComputeLinearGainNilDataReturnsUnity() {
+    for mode: ReplayGainSelectorMode in [.off, .track, .album] {
+      XCTAssertEqual(
+        AudioTapProvider.computeLinearGain(data: nil, mode: mode), 1.0,
+        "mode \(mode) on nil data should return unity"
+      )
+    }
+  }
+
+  // MARK: - Peak clip protection
+
+  func testComputeLinearGainPeakCapInactiveWhenRawBelowCap() {
+    // -3 dB ≈ 0.7079 linear; cap = 1 / 0.7 ≈ 1.4286. Raw < cap.
+    let data = ReplayGainData(
+      trackGainDb: -3.0, trackPeak: 0.7,
+      albumGainDb: nil, albumPeak: nil
+    )
+    let raw = Float(pow(10.0, -3.0 / 20.0))
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      raw, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainPeakCapKicksInAboveCap() {
+    // +6 dB ≈ 1.995 linear, peak 0.6 → cap = 1/0.6 ≈ 1.667. Cap wins.
+    let data = ReplayGainData(
+      trackGainDb: 6.0, trackPeak: 0.6,
+      albumGainDb: nil, albumPeak: nil
+    )
+    let cap = Float(1.0 / 0.6)
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      cap, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainEncoderDefaultPeakIsIgnored() {
+    // peak == 1.0 is the encoder-default sentinel; cap path skipped.
+    let data = ReplayGainData(
+      trackGainDb: -6.0, trackPeak: 1.0,
+      albumGainDb: nil, albumPeak: nil
+    )
+    let raw = Float(pow(10.0, -6.0 / 20.0))
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      raw, accuracy: 0.001
+    )
+  }
+
+  func testComputeLinearGainNearZeroPeakIsIgnored() {
+    // peak < 0.001 sentinel — also bypasses the cap.
+    let data = ReplayGainData(
+      trackGainDb: -6.0, trackPeak: 0.0005,
+      albumGainDb: nil, albumPeak: nil
+    )
+    let raw = Float(pow(10.0, -6.0 / 20.0))
+    XCTAssertEqual(
+      AudioTapProvider.computeLinearGain(data: data, mode: .track),
+      raw, accuracy: 0.001
+    )
+  }
+
+  // MARK: - replayGainActiveForItem
+
+  func testReplayGainActiveForItemReturnsFalseForUnattachedItem() {
+    let provider = AudioTapProvider()
+    let item = AVPlayerItem(url: URL(string: "https://example.test/x.mp3")!)
+    XCTAssertFalse(provider.replayGainActiveForItem(item))
+  }
+}

package/ios/Tests/AudioTapProviderVisualizationFlagTests.swift

@@ -0,0 +1,104 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Unit coverage for `AudioTapProvider.visualizationEnabled` — the
+/// pin-at-configure flag written by `TrackPlayer.configure(_:)` from
+/// `PlayerConfig.visualizationEnabled` and read by the visualizer
+/// Hybrid's `subscribe(...)` early-return + the visualizer Consumer's
+/// `wantsTap` predicate.
+final class AudioTapProviderVisualizationFlagTests: XCTestCase {
+
+  func testFlagDefaultsToTrue() {
+    let provider = AudioTapProvider()
+    XCTAssertTrue(
+      provider.isVisualizationEnabledSnapshot(),
+      "default visualizationEnabled must be true so existing consumers see no behaviour change"
+    )
+  }
+
+  func testSetEnabledMirrorsThroughSnapshot() {
+    let provider = AudioTapProvider()
+    provider.setVisualizationEnabled(false)
+    XCTAssertFalse(provider.isVisualizationEnabledSnapshot())
+    provider.setVisualizationEnabled(true)
+    XCTAssertTrue(provider.isVisualizationEnabledSnapshot())
+  }
+
+  func testIdempotentReWriteHonoursLatestValue() {
+    // Configure runs the flag write on every call. Mirroring iOS
+    // behaviour: a re-write to the same value is harmless; a re-write
+    // to a new value must reflect immediately.
+    let provider = AudioTapProvider()
+    provider.setVisualizationEnabled(true)
+    provider.setVisualizationEnabled(true)
+    XCTAssertTrue(provider.isVisualizationEnabledSnapshot())
+    provider.setVisualizationEnabled(false)
+    XCTAssertFalse(provider.isVisualizationEnabledSnapshot())
+    provider.setVisualizationEnabled(false)
+    XCTAssertFalse(provider.isVisualizationEnabledSnapshot())
+  }
+
+  func testFlagDoesNotAffectIsEnabled() {
+    // EQ-enabled flag is a separate piece of state — viz disable must
+    // not flip it.
+    let provider = AudioTapProvider()
+    provider.setEnabled(true)
+    provider.setVisualizationEnabled(false)
+    XCTAssertTrue(
+      provider.isEnabledSnapshot(),
+      "visualizationEnabled must not bleed into the EQ enabled flag"
+    )
+  }
+
+  func testReadsFromConcurrentThreadsAreSafe() {
+    // The flag is read from the JS bridge thread (subscribe) +
+    // possibly the audio render thread (Consumer.wantsTap predicate).
+    // Writes happen on main from configure. The lock-protected
+    // accessor serialises both. Spin 8 readers + 1 writer alternating
+    // true/false; collect every observed read; assert every observed
+    // value is one of the two written values (no torn read returning
+    // some other bit-pattern), and that the final state matches the
+    // writer's last pinned write.
+    let provider = AudioTapProvider()
+    let writeQueue = DispatchQueue(label: "viz.flag.test.writer")
+    let readGroup = DispatchGroup()
+    let writeGroup = DispatchGroup()
+    var observed: [Bool] = []
+    let observedLock = NSLock()
+    for _ in 0..<8 {
+      readGroup.enter()
+      DispatchQueue.global().async {
+        for _ in 0..<200 {
+          let value = provider.isVisualizationEnabledSnapshot()
+          observedLock.lock()
+          observed.append(value)
+          observedLock.unlock()
+        }
+        readGroup.leave()
+      }
+    }
+    writeGroup.enter()
+    writeQueue.async {
+      for i in 0..<200 {
+        provider.setVisualizationEnabled(i % 2 == 0)
+      }
+      // Pin the final state so the post-join assertion is deterministic.
+      provider.setVisualizationEnabled(true)
+      writeGroup.leave()
+    }
+    readGroup.wait()
+    writeGroup.wait()
+    XCTAssertGreaterThan(
+      observed.count, 0,
+      "concurrent reads should record values without crashing"
+    )
+    // Bool can only legally be true or false — this is trivially
+    // satisfied on iOS but documents the contract: no torn read.
+    let invalid = observed.filter { $0 != true && $0 != false }
+    XCTAssertTrue(invalid.isEmpty, "torn reads observed: \(invalid)")
+    XCTAssertTrue(
+      provider.isVisualizationEnabledSnapshot(),
+      "expected final state true after writer pin"
+    )
+  }
+}

package/ios/Tests/BiquadCoefficientsTests.swift

@@ -0,0 +1,84 @@
+import XCTest
+@testable import QueuePlayer
+
+final class BiquadCoefficientsTests: XCTestCase {
+
+  func testZeroGainReturnsIdentityBlock() {
+    let block = BiquadCoefficients.peaking(
+      centerFreqHz: 1000,
+      q: 1.0,
+      gainDb: 0,
+      sampleRateHz: 44_100
+    )
+    XCTAssertEqual(block, .identity)
+  }
+
+  func testCenterFreqAtNyquistReturnsIdentity() {
+    let block = BiquadCoefficients.peaking(
+      centerFreqHz: 22_050,
+      q: 1.0,
+      gainDb: 6,
+      sampleRateHz: 44_100
+    )
+    XCTAssertEqual(block, .identity)
+  }
+
+  func testNonZeroGainProducesNonIdentityCoefficients() {
+    let block = BiquadCoefficients.peaking(
+      centerFreqHz: 1000,
+      q: 1.0,
+      gainDb: 6,
+      sampleRateHz: 44_100
+    )
+    XCTAssertNotEqual(block, .identity)
+    // Sanity bounds — RBJ peaking at +6 dB / Q=1 / 1kHz / 44.1k:
+    // b0 should sit slightly above 1; a1 reflects -2*cos(omega).
+    XCTAssertGreaterThan(block.b0, 1.0)
+    XCTAssertLessThan(block.b0, 2.0)
+  }
+
+  func testB1EqualsA1WithinABlock() {
+    // RBJ peaking unnormalized: b1 = a1 = -2*cos(omega). After
+    // a0-normalization both become b1/a0 = a1/a0, so the ratio
+    // collapses to equality regardless of gain or Q.
+    for gain in [-12.0, -6.0, 6.0, 12.0] {
+      let block = BiquadCoefficients.peaking(
+        centerFreqHz: 1000, q: 1.0, gainDb: gain, sampleRateHz: 44_100
+      )
+      XCTAssertEqual(block.b1, block.a1, accuracy: 1e-12, "gain=\(gain)")
+    }
+  }
+
+  func testInvalidInputsResolveToIdentity() {
+    XCTAssertEqual(
+      BiquadCoefficients.peaking(centerFreqHz: 0, q: 1, gainDb: 6, sampleRateHz: 44_100),
+      .identity
+    )
+    XCTAssertEqual(
+      BiquadCoefficients.peaking(centerFreqHz: 1000, q: 0, gainDb: 6, sampleRateHz: 44_100),
+      .identity
+    )
+    XCTAssertEqual(
+      BiquadCoefficients.peaking(centerFreqHz: 1000, q: 1, gainDb: 6, sampleRateHz: 0),
+      .identity
+    )
+  }
+
+  func testCoefficientsAreFiniteForAllPresetBands() {
+    // Sweep the 10 ISO frequencies at extreme gains and verify
+    // every block is finite. Coefficients stay finite across the
+    // project's spec range (no NaN, no inf).
+    for freq in EqualizerPresets.frequencies {
+      for gain in [-12.0, -6.0, 0.0, 6.0, 12.0] {
+        let block = BiquadCoefficients.peaking(
+          centerFreqHz: freq, q: 1.0, gainDb: gain, sampleRateHz: 48_000
+        )
+        XCTAssertTrue(block.b0.isFinite)
+        XCTAssertTrue(block.b1.isFinite)
+        XCTAssertTrue(block.b2.isFinite)
+        XCTAssertTrue(block.a1.isFinite)
+        XCTAssertTrue(block.a2.isFinite)
+      }
+    }
+  }
+}

package/ios/Tests/CarPlayBridgeTests.swift

@@ -0,0 +1,91 @@
+import XCTest
+@testable import QueuePlayer
+
+/// `CarPlayBridge` tests cover only the registration/dispose/clear
+/// state machine. Promise-await dispatch is exercised by the
+/// production scene delegate + browse builder via integration paths;
+/// the unit suite stays focused on the slot semantics. The
+/// Android-side `BrowseCallbackRegistry` exposes suspending
+/// `await*Callback()` helpers because its dispatch sites coroutine-
+/// poll for cold-start race recovery; iOS uses NotificationCenter
+/// (`CarPlayBrowseDataProvider.didUpdateNotification`) + the
+/// `CarPlayCoordinator.pending` queue for the same shape, so the
+/// iOS bridge stays slot-only.
+final class CarPlayBridgeTests: XCTestCase {
+
+  func testFreshBridgeHasNoCallbacks() {
+    let bridge = CarPlayBridge()
+    // The browse / playFromId slot reads return a Promise of a
+    // Nitrogen-bridged type, which Swift cxx-interop excludes from
+    // `@testable import`. Their slots use the identical `Slot<>`
+    // machinery asserted here for connect/disconnect, and their
+    // dispatch is covered at the integration layer (scene delegate +
+    // browse builder).
+    XCTAssertNil(bridge.carConnectCallback())
+    XCTAssertNil(bridge.carDisconnectCallback())
+  }
+
+  func testOnCarConnectRegistersAndFires() {
+    let bridge = CarPlayBridge()
+    var fired = 0
+    _ = bridge.registerOnCarConnect { fired += 1 }
+    bridge.carConnectCallback()?()
+    XCTAssertEqual(fired, 1)
+  }
+
+  func testOnCarConnectReplaceSwapsTheActiveCallback() {
+    let bridge = CarPlayBridge()
+    var firstFired = 0
+    var secondFired = 0
+    _ = bridge.registerOnCarConnect { firstFired += 1 }
+    _ = bridge.registerOnCarConnect { secondFired += 1 }
+    bridge.carConnectCallback()?()
+    XCTAssertEqual(firstFired, 0,
+                   "second register replaces the first; the first never fires again")
+    XCTAssertEqual(secondFired, 1)
+  }
+
+  func testDisposerClearsTheRegisteredSlot() {
+    let bridge = CarPlayBridge()
+    let dispose = bridge.registerOnCarConnect { /* no-op */ }
+    XCTAssertNotNil(bridge.carConnectCallback())
+    dispose()
+    XCTAssertNil(bridge.carConnectCallback())
+  }
+
+  func testStaleDisposerLeavesActiveCallbackAlone() {
+    let bridge = CarPlayBridge()
+    let staleDispose = bridge.registerOnCarConnect { /* first */ }
+    var secondFired = 0
+    _ = bridge.registerOnCarConnect { secondFired += 1 }
+
+    // The stale disposer (from the first registration) must not clear
+    // the second callback's slot — the token check guards this.
+    staleDispose()
+    bridge.carConnectCallback()?()
+    XCTAssertEqual(secondFired, 1)
+  }
+
+  func testClearWipesEveryRegisteredSlot() {
+    let bridge = CarPlayBridge()
+    _ = bridge.registerOnCarConnect { }
+    _ = bridge.registerOnCarDisconnect { }
+
+    bridge.clear()
+
+    XCTAssertNil(bridge.carConnectCallback())
+    XCTAssertNil(bridge.carDisconnectCallback())
+  }
+
+  func testRegistrationsAreSlotIsolated() {
+    let bridge = CarPlayBridge()
+    var connectFired = 0
+    var disconnectFired = 0
+    _ = bridge.registerOnCarConnect { connectFired += 1 }
+    _ = bridge.registerOnCarDisconnect { disconnectFired += 1 }
+    bridge.carConnectCallback()?()
+    bridge.carDisconnectCallback()?()
+    XCTAssertEqual(connectFired, 1)
+    XCTAssertEqual(disconnectFired, 1)
+  }
+}