@glassly/bluetooth-sdk 0.1.0-dev.26

package/ios/Source/tts/TTSTools.swift

@@ -0,0 +1,171 @@
+import Foundation
+
+/// Utilities for offline Sherpa-ONNX Supertonic 3 TTS.
+///
+/// Supertonic 3 is a single multilingual model bundle (31 languages) with
+/// 10 preset voice styles packed into voice.bin. Speaker IDs are indexed
+/// alphabetically by JSON filename, so the order is F1, F2, F3, F4, F5,
+/// M1, M2, M3, M4, M5 (sids 0..9). We default to F1 (sid 0) for a female
+/// voice.
+class TTSTools {
+    private static let kFileDurationPredictor = "duration_predictor.int8.onnx"
+    private static let kFileTextEncoder = "text_encoder.int8.onnx"
+    private static let kFileVectorEstimator = "vector_estimator.int8.onnx"
+    private static let kFileVocoder = "vocoder.int8.onnx"
+    private static let kFileTtsJson = "tts.json"
+    private static let kFileUnicodeIndexer = "unicode_indexer.bin"
+    private static let kFileVoiceStyle = "voice.bin"
+
+    private static let kRequiredFiles: [String] = [
+        kFileDurationPredictor,
+        kFileTextEncoder,
+        kFileVectorEstimator,
+        kFileVocoder,
+        kFileTtsJson,
+        kFileUnicodeIndexer,
+        kFileVoiceStyle,
+    ]
+
+    private static let kSupportedLangs: Set<String> = [
+        "en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et",
+        "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl",
+        "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi",
+    ]
+
+    static func setTtsModelDetails(_ path: String, _ languageCode: String) {
+        UserDefaults.standard.set(path, forKey: "TTSModelPath")
+        UserDefaults.standard.set(languageCode, forKey: "TTSModelLanguageCode")
+        UserDefaults.standard.synchronize()
+    }
+
+    static func getTtsModelPath() -> String {
+        return UserDefaults.standard.string(forKey: "TTSModelPath") ?? ""
+    }
+
+    static func getTtsModelLanguage() -> String {
+        return UserDefaults.standard.string(forKey: "TTSModelLanguageCode") ?? "en-US"
+    }
+
+    static func checkTTSModelAvailable() -> Bool {
+        guard let modelPath = UserDefaults.standard.string(forKey: "TTSModelPath") else {
+            return false
+        }
+        return validateTTSModel(modelPath)
+    }
+
+    static func validateTTSModel(_ path: String) -> Bool {
+        let fileManager = FileManager.default
+        var isDirectory: ObjCBool = false
+        if !fileManager.fileExists(atPath: path, isDirectory: &isDirectory) || !isDirectory.boolValue {
+            Bridge.log("TTS model path does not exist or is not a directory: \(path)")
+            return false
+        }
+
+        for name in kRequiredFiles {
+            let filePath = (path as NSString).appendingPathComponent(name)
+            if !fileManager.fileExists(atPath: filePath) {
+                Bridge.log("TTS model missing required file '\(name)' at: \(path)")
+                return false
+            }
+            let size = (try? fileManager.attributesOfItem(atPath: filePath)[.size] as? UInt64) ?? 0
+            if size == 0 {
+                Bridge.log("TTS model file '\(name)' is empty at: \(path)")
+                return false
+            }
+        }
+
+        return true
+    }
+
+    static func generateTtsAudio(
+        text: String,
+        modelPath: String,
+        outputPath: String,
+        speakerId: Int,
+        speed: Double
+    ) -> Bool {
+        guard !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            Bridge.log("TTS_ERROR: text is empty")
+            return false
+        }
+        guard validateTTSModel(modelPath) else {
+            Bridge.log("TTS_ERROR: model is invalid: \(modelPath)")
+            return false
+        }
+
+        do {
+            let outputURL = URL(fileURLWithPath: outputPath)
+            try FileManager.default.createDirectory(
+                at: outputURL.deletingLastPathComponent(),
+                withIntermediateDirectories: true,
+                attributes: nil
+            )
+
+            // Build the config and construct the engine inside one C-string
+            // scope: the config's `const char*` fields point at buffers owned by
+            // that scope (see toCPointer in SherpaOnnx.swift). Only construction
+            // goes inside — `tts` itself is safe to use afterwards, since
+            // sherpa-onnx copies every string during construction.
+            let tts = withSherpaOnnxCStrings { () -> SherpaOnnxOfflineTtsWrapper in
+                let supertonic = sherpaOnnxOfflineTtsSupertonicModelConfig(
+                    durationPredictor: (modelPath as NSString).appendingPathComponent(kFileDurationPredictor),
+                    textEncoder: (modelPath as NSString).appendingPathComponent(kFileTextEncoder),
+                    vectorEstimator: (modelPath as NSString).appendingPathComponent(kFileVectorEstimator),
+                    vocoder: (modelPath as NSString).appendingPathComponent(kFileVocoder),
+                    ttsJson: (modelPath as NSString).appendingPathComponent(kFileTtsJson),
+                    unicodeIndexer: (modelPath as NSString).appendingPathComponent(kFileUnicodeIndexer),
+                    voiceStyle: (modelPath as NSString).appendingPathComponent(kFileVoiceStyle)
+                )
+                let modelConfig = sherpaOnnxOfflineTtsModelConfig(
+                    numThreads: 8,
+                    supertonic: supertonic
+                )
+                var config = sherpaOnnxOfflineTtsConfig(model: modelConfig, maxNumSentences: 1)
+                return SherpaOnnxOfflineTtsWrapper(config: &config)
+            }
+
+            // The new wrapper dropped numSpeakers() in v1.13.2; call the C API
+            // directly. The C signature accepts the underlying OpaquePointer.
+            let numSpeakers = max(1, Int(SherpaOnnxOfflineTtsNumSpeakers(tts.tts)))
+            let sid = max(0, min(speakerId, numSpeakers - 1))
+            let clampedSpeed = Float(min(max(speed, 0.5), 2.0))
+            let lang = languageTagToSupertonicLang(getTtsModelLanguage())
+
+            // generate(...) no longer accepts `extra`; that field moved onto
+            // SherpaOnnxGenerationConfigSwift and is delivered via
+            // generateWithConfig(...).
+            //
+            // numSteps controls the Supertonic flow-matching vocoder's
+            // iteration count. The Swift wrapper defaults to 1, which produces
+            // unintelligible robot audio — sherpa-onnx's actual C-side default
+            // is 5. Pin it here so we don't inherit the wrapper's bug.
+            let genConfig = SherpaOnnxGenerationConfigSwift(
+                speed: clampedSpeed,
+                sid: sid,
+                numSteps: 5,
+                extra: ["lang": lang]
+            )
+            let audio = tts.generateWithConfig(
+                text: text,
+                config: genConfig,
+                callback: nil,
+                arg: nil
+            )
+            let saved = audio.save(filename: outputPath) == 1
+            Bridge.log(
+                "TTS generated \(outputPath): saved=\(saved) sid=\(sid) lang=\(lang) " +
+                    "sr=\(audio.sampleRate) samples=\(audio.n) speed=\(clampedSpeed)"
+            )
+            return saved
+        } catch {
+            Bridge.log("TTS_ERROR: \(error.localizedDescription)")
+            return false
+        }
+    }
+
+    /// Convert a BCP-47 tag (e.g. "en-US", "fr-FR") to a Supertonic 2-letter code.
+    private static func languageTagToSupertonicLang(_ tag: String) -> String {
+        let primary = tag.split(separator: "-").first.map(String.init)?.lowercased() ?? "en"
+        return kSupportedLangs.contains(primary) ? primary : "en"
+    }
+}

package/ios/Source/types/DeviceModels.swift

@@ -0,0 +1,177 @@
+import Foundation
+
+public struct BluetoothSDKConfiguration {
+    public static let `default` = BluetoothSDKConfiguration()
+
+    public let analytics: BluetoothSdkAnalyticsConfiguration
+
+    public init(analytics: BluetoothSdkAnalyticsConfiguration = BluetoothSdkAnalyticsConfiguration()) {
+        self.analytics = analytics
+    }
+}
+
+public enum DeviceModel: String {
+    case g1
+    case g2
+    case mentraLive
+    case mentraNex
+    case mach1
+    case z100
+    case frame
+    case nimo
+    case ar99
+    case simulated
+    case r1
+
+    public var deviceType: String {
+        switch self {
+        case .g1:
+            DeviceTypes.G1
+        case .g2:
+            DeviceTypes.G2
+        case .mentraLive:
+            DeviceTypes.LIVE
+        case .mentraNex:
+            DeviceTypes.NEX
+        case .mach1:
+            DeviceTypes.MACH1
+        case .z100:
+            DeviceTypes.Z100
+        case .frame:
+            DeviceTypes.FRAME
+        case .nimo:
+            DeviceTypes.NIMO
+        case .ar99:
+            DeviceTypes.AR99
+        case .simulated:
+            DeviceTypes.SIMULATED
+        case .r1:
+            ControllerTypes.R1
+        }
+    }
+
+    public static func fromDeviceType(_ deviceType: String?) -> DeviceModel {
+        switch deviceType {
+        case DeviceTypes.G1:
+            .g1
+        case DeviceTypes.G2:
+            .g2
+        case DeviceTypes.LIVE:
+            .mentraLive
+        case DeviceTypes.NEX:
+            .mentraNex
+        case DeviceTypes.MACH1:
+            .mach1
+        case DeviceTypes.Z100:
+            .z100
+        case DeviceTypes.FRAME:
+            .frame
+        case DeviceTypes.NIMO:
+            .nimo
+        case DeviceTypes.AR99:
+            .ar99
+        case DeviceTypes.SIMULATED:
+            .simulated
+        case ControllerTypes.R1:
+            .r1
+        default:
+            .mentraLive
+        }
+    }
+}
+
+public struct Device: Identifiable, Equatable, CustomStringConvertible {
+    public let model: DeviceModel
+    public let name: String
+    /// CoreBluetooth identifier when available.
+    public let identifier: String?
+    public let projectName: String?
+    public let rssi: Int?
+    /// Stable app-facing scan-result key. Do not parse; use typed fields instead.
+    public let id: String
+    public let pairingMode: Bool?
+    public let pairingCode: String?
+    public let securePairingCapable: Bool?
+
+    public init(
+        model: DeviceModel,
+        name: String,
+        identifier: String? = nil,
+        projectName: String? = nil,
+        rssi: Int? = nil,
+        id: String? = nil,
+        pairingMode: Bool? = nil,
+        pairingCode: String? = nil,
+        securePairingCapable: Bool? = nil
+    ) {
+        self.model = model
+        self.name = name
+        self.identifier = identifier
+        self.projectName = projectName
+        self.rssi = rssi
+        self.id = id ?? identifier.flatMap { $0.isEmpty ? nil : $0 } ?? "\(model.deviceType):\(name)"
+        self.pairingMode = pairingMode
+        self.pairingCode = pairingCode
+        self.securePairingCapable = securePairingCapable
+    }
+
+    public var description: String {
+        "Device(model: \(model), name: \(name))"
+    }
+
+    var dictionary: [String: Any] {
+        var values: [String: Any] = [
+            "id": id,
+            "model": model.deviceType,
+            "name": name,
+        ]
+        if let identifier, !identifier.isEmpty {
+            values["address"] = identifier
+        }
+        if let projectName, !projectName.isEmpty {
+            values["projectName"] = projectName
+        }
+        if let rssi {
+            values["rssi"] = rssi
+        }
+        if let pairingMode {
+            values["pairingMode"] = pairingMode
+        }
+        if let pairingCode, !pairingCode.isEmpty {
+            values["pairingCode"] = pairingCode
+        }
+        if let securePairingCapable {
+            values["securePairingCapable"] = securePairingCapable
+        }
+        return values
+    }
+
+    init?(values: [String: Any]) {
+        guard let model = stringValue(values, "model") else { return nil }
+        guard let name = stringValue(values, "name") else { return nil }
+        let identifier = stringValue(values, "address").flatMap { $0.isEmpty ? nil : $0 }
+        let projectName = stringValue(values, "projectName").flatMap { $0.isEmpty ? nil : $0 }
+        let rssi = intValue(values["rssi"])
+        self.init(
+            model: DeviceModel.fromDeviceType(model),
+            name: name,
+            identifier: identifier,
+            projectName: projectName,
+            rssi: rssi,
+            id: stringValue(values, "id"),
+            pairingMode: boolValue(values, "pairingMode"),
+            pairingCode: stringValue(values, "pairingCode").flatMap { $0.isEmpty ? nil : $0 },
+            securePairingCapable: boolValue(values, "securePairingCapable")
+        )
+    }
+}
+
+public struct ConnectOptions {
+    public let saveAsDefault: Bool
+    public let cancelExistingConnectionAttempt: Bool
+
+    public init(saveAsDefault: Bool = true, cancelExistingConnectionAttempt: Bool = true) {
+        self.saveAsDefault = saveAsDefault
+        self.cancelExistingConnectionAttempt = cancelExistingConnectionAttempt
+    }
+}

package/ios/Source/utils/AudioSessionMonitor.swift

@@ -0,0 +1,283 @@
+//
+//  AudioSessionMonitor.swift
+//  AOS
+//
+//  Monitors iOS AVAudioSession for Bluetooth audio device connections
+//  Used to detect when Mentra Live glasses are paired/connected for audio
+//
+
+import AVFoundation
+import Foundation
+import UIKit
+
+class AudioSessionMonitor {
+    /// Singleton instance
+    private static var instance: AudioSessionMonitor?
+
+    // Current monitoring state
+    static var isMonitoring = false
+    static var devicePattern: String?
+    static var callback: ((Bool, String?) -> Void)?
+
+    private init() {
+        Bridge.log("AudioMonitor: Initialized")
+    }
+
+    static func getInstance() -> AudioSessionMonitor {
+        if instance == nil {
+            instance = AudioSessionMonitor()
+        }
+        return instance!
+    }
+
+    /// Check if AVAudioSession is configured for Bluetooth
+    /// Returns true if session allows Bluetooth audio
+    /// NOTE: We don't configure the session - PhoneMic.swift handles that when recording
+    static func isAudioSessionConfigured() -> Bool {
+        let session = AVAudioSession.sharedInstance()
+
+        // Check if category supports Bluetooth
+        let category = session.category
+        let supportsBluetooth =
+            category == .playAndRecord || category == .record || category == .multiRoute
+
+        Bridge.log(
+            "AudioMonitor: Audio session category: \(category.rawValue), supports BT: \(supportsBluetooth)"
+        )
+        return supportsBluetooth
+    }
+
+    /// Check if a Bluetooth audio device matching the pattern is currently the active audio route
+    /// Returns true if device is actively routing audio
+    static func isAudioDeviceConnected(devicePattern: String) -> Bool {
+        let session = AVAudioSession.sharedInstance()
+        let outputs = session.currentRoute.outputs
+
+        Bridge.log("AudioMonitor: Checking active route, output count: \(outputs.count)")
+        for output in outputs {
+            Bridge.log("AudioMonitor:   - \(output.portName) (type: \(output.portType.rawValue))")
+            if output.portType == .bluetoothHFP || output.portType == .bluetoothA2DP {
+                if output.portName.localizedCaseInsensitiveContains(devicePattern) {
+                    Bridge.log("AudioMonitor: ✅ Found active audio device: \(output.portName)")
+                    return true
+                }
+            }
+        }
+
+        Bridge.log("AudioMonitor: No active audio device matching '\(devicePattern)'")
+        return false
+    }
+
+    static func isOtherAudioDeviceConnected(devicePattern: String) -> Bool {
+        let connected = isAudioDeviceConnected(devicePattern: devicePattern)
+        if connected {
+            return false
+        }
+
+        // do we have multiple devices connected?
+        let session = AVAudioSession.sharedInstance()
+        let outputs = session.currentRoute.outputs
+
+        Bridge.log("AudioMonitor: Checking active route, output count: \(outputs.count)")
+        if outputs.count > 1 {
+            return true
+        }
+
+        return false
+    }
+
+    /// Check if a Bluetooth device matching the pattern is paired (appears in availableInputs)
+    /// Returns true if device is found (paired), WITHOUT activating it
+    /// This avoids switching A2DP music playback to HFP microphone mode
+    static func isDevicePaired(devicePattern: String) -> Bool {
+        let session = AVAudioSession.sharedInstance()
+
+        // Check if already active (using A2DP for music or HFP for calls)
+        if isAudioDeviceConnected(devicePattern: devicePattern) {
+            Bridge.log("AudioMonitor: Device '\(devicePattern)' already active")
+            return true
+        }
+
+        // Try to find in availableInputs (includes paired devices)
+        guard let availableInputs = session.availableInputs else {
+            Bridge.log("AudioMonitor: ❌ availableInputs is nil")
+            return false
+        }
+
+        Bridge.log("AudioMonitor: availableInputs count: \(availableInputs.count)")
+        for input in availableInputs {
+            Bridge.log("AudioMonitor:   - \(input.portName) (type: \(input.portType.rawValue))")
+        }
+
+        let bluetoothInput = availableInputs.first { input in
+            input.portType == .bluetoothHFP
+                && input.portName.localizedCaseInsensitiveContains(devicePattern)
+        }
+
+        if let btInput = bluetoothInput {
+            Bridge.log(
+                "AudioMonitor: ✅ Found paired device '\(btInput.portName)' (not activating to preserve A2DP)"
+            )
+            return true
+        } else {
+            Bridge.log(
+                "AudioMonitor: ❌ Bluetooth HFP device '\(devicePattern)' not found in availableInputs"
+            )
+            return false
+        }
+    }
+
+    /// Start monitoring for audio route changes
+    /// Callback will be called when device matching pattern connects/disconnects
+    static func startMonitoring(devicePattern: String, callback: @escaping (Bool, String?) -> Void) {
+        guard !isMonitoring else {
+            Bridge.log("AudioMonitor: Already monitoring")
+            return
+        }
+
+        self.devicePattern = devicePattern
+        self.callback = callback
+
+        // Register for route change notifications
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleRouteChange),
+            name: AVAudioSession.routeChangeNotification,
+            object: nil
+        )
+
+        // Register for app foreground notifications
+        // This handles the case where user pairs in Settings and returns to app
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleAppBecameActive),
+            name: UIApplication.didBecomeActiveNotification,
+            object: nil
+        )
+
+        isMonitoring = true
+        Bridge.log("AudioMonitor: Started monitoring for '\(devicePattern)'")
+    }
+
+    /// Stop monitoring for audio route changes
+    static func stopMonitoring() {
+        guard isMonitoring else {
+            Bridge.log("AudioMonitor: Not currently monitoring")
+            return
+        }
+
+        NotificationCenter.default.removeObserver(
+            self,
+            name: AVAudioSession.routeChangeNotification,
+            object: nil
+        )
+
+        NotificationCenter.default.removeObserver(
+            self,
+            name: UIApplication.didBecomeActiveNotification,
+            object: nil
+        )
+
+        AudioSessionMonitor.isMonitoring = false
+        AudioSessionMonitor.devicePattern = nil
+        AudioSessionMonitor.callback = nil
+
+        Bridge.log("AudioMonitor: Stopped monitoring")
+    }
+
+    @objc private func handleRouteChange(notification: Notification) {
+        guard let userInfo = notification.userInfo,
+              let reasonValue = userInfo[AVAudioSessionRouteChangeReasonKey] as? UInt,
+              let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue),
+              let pattern = AudioSessionMonitor.devicePattern
+        else {
+            return
+        }
+
+        Bridge.log("AudioMonitor: Route change detected: \(reason.rawValue)")
+
+        switch reason {
+        case .newDeviceAvailable:
+            // When a new device becomes available, try to set it as preferred
+            // This handles the case where user pairs in Settings and returns to app
+            Bridge.log("AudioMonitor: New device available, attempting to activate '\(pattern)'")
+
+            // Add small delay to let iOS populate availableInputs
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
+                if AudioSessionMonitor.isDevicePaired(devicePattern: pattern) {
+                    let session = AVAudioSession.sharedInstance()
+                    let deviceName = session.availableInputs?.first(where: {
+                        $0.portName.localizedCaseInsensitiveContains(pattern)
+                    })?.portName
+                    Bridge.log(
+                        "AudioMonitor: ✅ Successfully detected newly paired device '\(pattern)'"
+                    )
+                    AudioSessionMonitor.callback?(true, deviceName)
+                } else {
+                    Bridge.log("AudioMonitor: New device available but not matching '\(pattern)'")
+                }
+            }
+
+        case .oldDeviceUnavailable:
+            // Check if our device disconnected
+            if !AudioSessionMonitor.isAudioDeviceConnected(devicePattern: pattern) {
+                Bridge.log("AudioMonitor: Device '\(pattern)' disconnected")
+                AudioSessionMonitor.callback?(false, nil)
+            }
+
+        default:
+            break
+        }
+    }
+
+    @objc private static func handleAppBecameActive() {
+        guard let pattern = AudioSessionMonitor.devicePattern else { return }
+
+        Bridge.log("AudioMonitor: App became active, checking for paired device '\(pattern)'")
+
+        // Don't reconfigure session - it's already configured from when monitoring started
+        // Just wait a bit for iOS to update availableInputs after returning from background
+        // iOS needs time to populate availableInputs after app foreground
+        // Use retry with progressive delays: 100ms, 400ms, 500ms = 1s total
+        AudioSessionMonitor.attemptActivateDevice(pattern: pattern, attempt: 0, maxAttempts: 3)
+    }
+
+    /// Try to detect if the audio device is paired with retry logic
+    /// Delays: [100ms, 400ms, 500ms] = 1 second total
+    static func attemptActivateDevice(pattern: String, attempt: Int, maxAttempts: Int) {
+        // Progressive delays in seconds (total: 1 second)
+        let delays: [TimeInterval] = [0.1, 0.4, 0.5]
+
+        if attempt >= maxAttempts {
+            Bridge.log(
+                "AudioMonitor: ❌ Failed to find paired device '\(pattern)' after \(maxAttempts) attempts"
+            )
+            return
+        }
+
+        let delay = attempt < delays.count ? delays[attempt] : 0.5
+
+        DispatchQueue.main.asyncAfter(deadline: .now() + delay) {
+            Bridge.log(
+                "AudioMonitor: Attempt \(attempt + 1)/\(maxAttempts) to detect '\(pattern)'..."
+            )
+
+            if AudioSessionMonitor.isDevicePaired(devicePattern: pattern) {
+                let session = AVAudioSession.sharedInstance()
+                // Try to get device name from availableInputs
+                let deviceName = session.availableInputs?.first(where: {
+                    $0.portName.localizedCaseInsensitiveContains(pattern)
+                })?.portName
+                Bridge.log("AudioMonitor: ✅ Found paired device on attempt \(attempt + 1)")
+                AudioSessionMonitor.callback?(true, deviceName)
+            } else {
+                Bridge.log(
+                    "AudioMonitor: Attempt \(attempt + 1) failed, retrying in \(delays[min(attempt + 1, delays.count - 1)])s..."
+                )
+                AudioSessionMonitor.attemptActivateDevice(
+                    pattern: pattern, attempt: attempt + 1, maxAttempts: maxAttempts
+                )
+            }
+        }
+    }
+}

package/ios/Source/utils/BinaryCodec.swift

@@ -0,0 +1,61 @@
+import Compression
+import Foundation
+
+/// Byte-level codecs shared by glasses transports.
+enum BinaryCodec {
+    /// CRC-16/CCITT-FALSE: polynomial 0x1021, initial value 0xFFFF.
+    static func crc16CCITT<S: Sequence>(_ bytes: S) -> UInt16 where S.Element == UInt8 {
+        var crc: UInt32 = 0xFFFF
+        for byte in bytes {
+            crc ^= UInt32(byte) << 8
+            for _ in 0 ..< 8 {
+                crc = (crc & 0x8000) != 0
+                    ? ((crc << 1) ^ 0x1021) & 0xFFFF
+                    : (crc << 1) & 0xFFFF
+            }
+        }
+        return UInt16(crc)
+    }
+
+    static func crc16CCITTLittleEndian<S: Sequence>(_ bytes: S) -> [UInt8]
+        where S.Element == UInt8
+    {
+        let crc = crc16CCITT(bytes)
+        return [UInt8(crc & 0xFF), UInt8((crc >> 8) & 0xFF)]
+    }
+
+    /// RFC1950 zlib stream. Apple's Compression framework emits raw DEFLATE,
+    /// so add the zlib header and Adler-32 trailer here in one shared implementation.
+    static func zlibRFC1950(_ data: Data) -> Data? {
+        guard !data.isEmpty else { return nil }
+        let capacity = data.count + data.count / 16 + 256
+        var deflated = Data(count: capacity)
+        let written = deflated.withUnsafeMutableBytes { destination -> Int in
+            data.withUnsafeBytes { source -> Int in
+                guard let destinationBase = destination.bindMemory(to: UInt8.self).baseAddress,
+                      let sourceBase = source.bindMemory(to: UInt8.self).baseAddress
+                else { return 0 }
+                return compression_encode_buffer(
+                    destinationBase, capacity, sourceBase, data.count, nil, COMPRESSION_ZLIB
+                )
+            }
+        }
+        guard written > 0 else { return nil }
+        deflated.removeSubrange(written ..< deflated.count)
+
+        var output = Data([0x78, 0x9C])
+        output.append(deflated)
+        var a: UInt32 = 1
+        var b: UInt32 = 0
+        for byte in data {
+            a = (a + UInt32(byte)) % 65521
+            b = (b + a) % 65521
+        }
+        let checksum = (b << 16) | a
+        output.append(contentsOf: [
+            UInt8((checksum >> 24) & 0xFF), UInt8((checksum >> 16) & 0xFF),
+            UInt8((checksum >> 8) & 0xFF), UInt8(checksum & 0xFF),
+        ])
+        return output
+    }
+}