@mentra/glasses-media 3.3.0 → 3.4.0-beta.1241

package/index.d.ts

@@ -7,5 +7,5 @@ export const glassesHotspot: {
     gateway?: string,
     purpose?: "outgoing-client" | "incoming-server",
   ): Promise<string>
-  leave(id: string): Promise<void>
+  leave(id: string, waitForInternet?: boolean): Promise<void>
 }

package/index.js

@@ -6,5 +6,5 @@ const native = () => require("expo-modules-core").requireNativeModule("MentraGla
 export const glassesHotspot = Object.freeze({
   join: (id, ssid, password, gateway, purpose = "outgoing-client") =>
     native().joinLocalHotspot(id, ssid, password, gateway ?? null, purpose),
-  leave: (id) => native().leaveLocalHotspot(id),
+  leave: (id, waitForInternet = false) => native().leaveLocalHotspot(id, waitForInternet),
 })

package/ios/CoreKit/Sources/GlassesMediaCore/HotspotInternetPolicy.swift

@@ -8,9 +8,106 @@ public enum HotspotInternetPolicy {
         if cellular { return "cellular" }
         if ethernet { return "ethernet" }
         // Callers supply a Wi-Fi SSID only after releasing the glasses hotspot.
-        if let restoredWifiSSID, !restoredWifiSSID.isEmpty, restoredWifiSSID != glassesSSID {
+        if let restoredWifiSSID, let glassesSSID, !glassesSSID.isEmpty, !restoredWifiSSID.isEmpty, restoredWifiSSID != glassesSSID {
             return "wifi"
         }
         return nil
     }
 }
+
+/// One queue-confined route observation. Late SSID callbacks cannot settle a
+/// newer path or session, and timeout/cancellation settle this observation once.
+public final class HotspotInternetObservation {
+    private let generation: Int
+    private let glassesSSID: String?
+    private var pathRevision = 0
+    private var finished = false
+    private var readingSSID = false
+    private var settledReply: (() -> Void)?
+
+    public init(generation: Int, glassesSSID: String?) {
+        self.generation = generation
+        self.glassesSSID = glassesSSID
+    }
+
+    public func beginPath(currentGeneration: Int) -> Int? {
+        guard !finished, currentGeneration == generation else { return nil }
+        pathRevision += 1
+        return pathRevision
+    }
+
+    public func restoredWifiRoute(ssid: String?, pathRevision: Int, currentGeneration: Int) -> String? {
+        guard !finished, currentGeneration == generation, pathRevision == self.pathRevision else { return nil }
+        return HotspotInternetPolicy.route(satisfied: true, cellular: false, ethernet: false,
+                                           restoredWifiSSID: ssid, glassesSSID: glassesSSID)
+    }
+
+    public func beginSSIDRead() -> Bool {
+        guard !finished, !readingSSID else { return false }
+        readingSSID = true
+        return true
+    }
+
+    public func completeSSIDRead() {
+        readingSSID = false
+        let reply = settledReply
+        settledReply = nil
+        reply?()
+    }
+
+    public func afterSSIDRead(_ reply: @escaping () -> Void) {
+        if readingSSID { settledReply = reply } else { reply() }
+    }
+
+    public func settle() -> Bool {
+        guard !finished else { return false }
+        finished = true
+        return true
+    }
+}
+
+/// Queue-confined cancellation owner. An old observation may finish joining its
+/// native read after its replacement starts, but cannot clear that replacement.
+public final class HotspotInternetObservationOwner {
+    private var current: (observation: HotspotInternetObservation, cancel: () -> Void)?
+
+    public init() {}
+
+    public func install(_ observation: HotspotInternetObservation, cancel: @escaping () -> Void) {
+        current?.cancel()
+        current = (observation, cancel)
+    }
+
+    public func clear(_ observation: HotspotInternetObservation) {
+        if current?.observation === observation { current = nil }
+    }
+
+    public func cancel() {
+        current?.cancel()
+    }
+}
+
+/// Queue-confined completion of one leave. Concurrent callers share cleanup;
+/// the original ownership token is released before any caller can start again.
+public final class HotspotLeaveCompletion {
+    private var replies: [(Result<Void, Error>) -> Void] = []
+    private var pending = true
+    private let release: () -> Void
+
+    public init(release: @escaping () -> Void) {
+        self.release = release
+    }
+
+    public func append(_ reply: @escaping (Result<Void, Error>) -> Void) {
+        replies.append(reply)
+    }
+
+    public func complete(_ result: Result<Void, Error>) {
+        guard pending else { return }
+        pending = false
+        if case .success = result { release() }
+        let current = replies
+        replies.removeAll()
+        current.forEach { $0(result) }
+    }
+}

package/ios/CoreKit/Sources/GlassesMediaCore/HotspotReapplyPolicy.swift

@@ -0,0 +1,26 @@
+import Foundation
+
+/// When to ask iOS again to join the glasses hotspot.
+///
+/// iOS accepts a hotspot configuration and then makes one short directed scan for it. When that
+/// scan misses the glasses' beacon, iOS shows "Unable to join the network", stays on the current
+/// Wi-Fi and still reports the configuration as applied. Only the phone's current network shows
+/// that the join failed, so a request that has not put the phone on the hotspot after a few
+/// seconds is made again, a bounded number of times, within the join's overall deadline.
+public struct HotspotReapplyPolicy {
+    /// Polls of the current network, half a second apart, before a request counts as missed.
+    public let pollsBeforeReapply: Int
+    /// Requests in one join, the first included.
+    public let maxApplies: Int
+
+    public init(pollsBeforeReapply: Int = 16, maxApplies: Int = 3) {
+        self.pollsBeforeReapply = pollsBeforeReapply
+        self.maxApplies = maxApplies
+    }
+
+    /// Whether to request the join again, with the phone not on the hotspot after `pollsSinceApply`
+    /// polls of the `applies`-th request.
+    public func shouldReapply(applies: Int, pollsSinceApply: Int) -> Bool {
+        applies < maxApplies && pollsSinceApply >= pollsBeforeReapply
+    }
+}

package/ios/CoreKit/Sources/GlassesMediaCore/MacHotspotAssociation.swift

@@ -5,46 +5,64 @@ import ObjectiveC
 /// Blocking public CoreWLAN calls are isolated here; the existing hotspot owner
 /// retains custody until they return, even after cancellation or a timeout.
 final class MacHotspotAssociation {
-    private let lock = NSLock()
+    private let condition = NSCondition()
     private var cancelled = false
     private var interface: MacWifiInterface?
     private var joinedSSID: String?
+    private let deadline: TimeInterval
+    private let now: () -> TimeInterval
+    private let pause: ((TimeInterval) -> Void)?
     private let makeInterface: () throws -> MacWifiInterface
-
-    init(makeInterface: @escaping () throws -> MacWifiInterface = { try PublicCoreWlanInterface() }) {
-        self.makeInterface = makeInterface
+    private let authorization: MacHotspotAuthorization?
+
+    init(deadline: TimeInterval = ProcessInfo.processInfo.systemUptime + 60,
+         now: @escaping () -> TimeInterval = { ProcessInfo.processInfo.systemUptime },
+         pause: ((TimeInterval) -> Void)? = nil,
+         makeInterface: (() throws -> MacWifiInterface)? = nil,
+         authorizationFacts: MacHotspotAuthorizationFacts? = nil,
+         authorization: MacHotspotAuthorization? = nil)
+    {
+        self.deadline = deadline
+        self.now = now
+        self.pause = pause
+        self.authorization = authorization
+        self.makeInterface = makeInterface ?? { try PublicCoreWlanInterface(authorizationFacts: authorizationFacts, authorization: authorization) }
     }
 
     func associate(ssid: String, password: String) throws -> String {
         try checkCurrent()
         let interface = try makeInterface()
         self.interface = interface
-        if try interface.currentSSID() != ssid {
-            let network = try interface.network(ssid: ssid)
-            try checkCurrent()
-            // Record the intended association before this blocking call. A late
-            // successful join still belongs to us and must be cleaned up.
-            joinedSSID = ssid
-            try interface.associate(network: network, password: password)
+        if try readSSID(interface) != ssid {
+            let network = try discoverNetwork(ssid: ssid, interface: interface)
+            try checkDiscoveryCurrent()
+            if let network, try readSSID(interface) != ssid {
+                try checkDiscoveryCurrent()
+                try authorization?.requireCurrentAuthorization()
+                // Record the intended association before this blocking call. A late
+                // successful join still belongs to us and must be cleaned up.
+                joinedSSID = ssid
+                try interface.associate(network: network, password: password)
+            }
         }
         try checkCurrent()
-        guard try interface.currentSSID() == ssid else {
+        guard try readSSID(interface) == ssid else {
             throw LocalMediaError("Mac Wi-Fi did not associate with the requested glasses hotspot")
         }
         return try interface.name()
     }
 
     func cancel() {
-        lock.lock(); cancelled = true; lock.unlock()
+        condition.lock(); cancelled = true; condition.broadcast(); condition.unlock()
     }
 
     /// Run on the same worker as association, after its blocking call returns.
     /// A connection the user replaced must never be disconnected by our cleanup.
     func leave() throws {
         if let joinedSSID {
-            if try interface?.currentSSID() == joinedSSID {
-                interface?.disassociate()
-                guard try interface?.currentSSID() != joinedSSID else {
+            if let interface, try readSSID(interface) == joinedSSID {
+                interface.disassociate()
+                guard try readSSID(interface) != joinedSSID else {
                     throw LocalMediaError("Mac Wi-Fi has not released the glasses hotspot")
                 }
             }
@@ -54,11 +72,52 @@ final class MacHotspotAssociation {
     }
 
     func currentSSID() throws -> String? {
-        try interface?.currentSSID()
+        guard let interface else { return nil }
+        return try readSSID(interface)
+    }
+
+    private func readSSID(_ interface: MacWifiInterface) throws -> String? {
+        try authorization?.requireCurrentAuthorization()
+        let ssid = try interface.currentSSID()
+        try authorization?.requireCurrentAuthorization()
+        return ssid
+    }
+
+    static func observeCurrentSSID() throws -> String? {
+        try PublicCoreWlanInterface().currentSSID()
+    }
+
+    private func discoverNetwork(ssid: String, interface: MacWifiInterface) throws -> NSObject? {
+        while true {
+            try checkDiscoveryCurrent()
+            // Recheck Location authorization before and after each blocking scan.
+            if try readSSID(interface) == ssid { return nil }
+            try authorization?.requireCurrentAuthorization()
+            let network = try interface.network(ssid: ssid)
+            try checkDiscoveryCurrent()
+            if try readSSID(interface) == ssid { return nil }
+            if let network { return network }
+            // Successful empty scans remain pending within this same join window.
+            // Native scan errors escape immediately; association is never retried.
+            let remaining = max(0, deadline - now())
+            if let pause { pause(min(1, remaining)) }
+            else {
+                condition.lock()
+                if !cancelled { _ = condition.wait(until: Date(timeIntervalSinceNow: min(1, remaining))) }
+                condition.unlock()
+            }
+        }
+    }
+
+    private func checkDiscoveryCurrent() throws {
+        try checkCurrent()
+        guard now() < deadline else {
+            throw LocalMediaError("The requested glasses hotspot was not found by Mac Wi-Fi before the hotspot join timed out")
+        }
     }
 
     private func checkCurrent() throws {
-        lock.lock(); let stopped = cancelled; lock.unlock()
+        condition.lock(); let stopped = cancelled; condition.unlock()
         if stopped { throw CancellationError() }
     }
 }
@@ -66,7 +125,7 @@ final class MacHotspotAssociation {
 protocol MacWifiInterface: AnyObject {
     func name() throws -> String
     func currentSSID() throws -> String?
-    func network(ssid: String) throws -> NSObject
+    func network(ssid: String) throws -> NSObject?
     func associate(network: NSObject, password: String) throws
     func disassociate()
 }
@@ -84,9 +143,13 @@ enum MacWifiInvocation {
 private final class PublicCoreWlanInterface: MacWifiInterface {
     private let bundle: Bundle
     private let interface: NSObject
+    private let authorizationFacts: MacHotspotAuthorizationFacts
+    private let authorization: MacHotspotAuthorization?
     private typealias Disassociate = @convention(c) (AnyObject, Selector) -> Void
 
-    init() throws {
+    init(authorizationFacts: MacHotspotAuthorizationFacts? = nil, authorization: MacHotspotAuthorization? = nil) throws {
+        self.authorizationFacts = authorizationFacts ?? MacHotspotAuthorizationFacts()
+        self.authorization = authorization
         guard let bundle = Bundle(path: "/System/Library/Frameworks/CoreWLAN.framework") else {
             throw LocalMediaError("Mac Wi-Fi framework is unavailable")
         }
@@ -114,15 +177,24 @@ private final class PublicCoreWlanInterface: MacWifiInterface {
     }
 
     func currentSSID() throws -> String? {
+        try requireAuthorization()
+        guard let data = interface.perform(NSSelectorFromString("ssidData"))?.takeUnretainedValue() as? Data else { return nil }
+        return String(data: data, encoding: .utf8)
+    }
+
+    private func requireAuthorization() throws {
+        if let authorization { try authorization.requireCurrentAuthorization(); return }
+        // Independent internet-return observation has no owned join recipient.
+        // Its existing static authorization guard remains unchanged.
         let authorization = CLLocationManager.authorizationStatus()
         guard MacHotspotAuthorization.isAuthorized(authorization) else {
-            throw LocalMediaError("Location access is required to verify the current Mac Wi-Fi network")
+            throw authorizationFacts.failure("Location access is required to verify the current Mac Wi-Fi network", raw: authorization.rawValue,
+                                             getter: .staticSSID, foreground: MacHotspotAuthorizationFacts.foreground())
         }
-        guard let data = interface.perform(NSSelectorFromString("ssidData"))?.takeUnretainedValue() as? Data else { return nil }
-        return String(data: data, encoding: .utf8)
     }
 
-    func network(ssid: String) throws -> NSObject {
+    func network(ssid: String) throws -> NSObject? {
+        try requireAuthorization()
         let selector = NSSelectorFromString("scanForNetworksWithSSID:error:")
         let invoke = unsafeBitCast(interface.method(for: selector), to: MacWifiInvocation.Scan.self)
         var error: NSError?
@@ -137,10 +209,11 @@ private final class PublicCoreWlanInterface: MacWifiInterface {
                   data == Data(ssid.utf8) else { continue }
             return network
         }
-        throw LocalMediaError("The requested glasses hotspot was not found by Mac Wi-Fi")
+        return nil
     }
 
     func associate(network: NSObject, password: String) throws {
+        try requireAuthorization()
         let selector = NSSelectorFromString("associateToNetwork:password:error:")
         let invoke = unsafeBitCast(interface.method(for: selector), to: MacWifiInvocation.Associate.self)
         var error: NSError?

package/ios/CoreKit/Sources/GlassesMediaCore/MacHotspotAuthorization.swift

@@ -6,26 +6,82 @@ import Foundation
 final class MacHotspotAuthorization: NSObject, CLLocationManagerDelegate {
     private var manager: CLLocationManager?
     private var completion: ((Result<Void, Error>) -> Void)?
-    private var finished = false
+    private var started = false
+    private var closed = false
+    private var ready = false
+    private var revoked = false
+    private let facts: MacHotspotAuthorizationFacts
+    private let makeManager: () -> CLLocationManager
+    private let locationServicesEnabled: () -> Bool
+    var onRevoked: ((Error) -> Void)?
+    var onRestored: (() -> Void)?
+
+    init(facts: MacHotspotAuthorizationFacts = MacHotspotAuthorizationFacts(), makeManager: @escaping () -> CLLocationManager = { CLLocationManager() },
+         locationServicesEnabled: @escaping () -> Bool = { CLLocationManager.locationServicesEnabled() })
+    {
+        self.facts = facts
+        self.makeManager = makeManager
+        self.locationServicesEnabled = locationServicesEnabled
+        super.init()
+    }
 
     func start(completion: @escaping (Result<Void, Error>) -> Void) {
         DispatchQueue.main.async {
-            guard !self.finished else { completion(.failure(CancellationError())); return }
+            guard !self.closed, !self.started else { completion(.failure(CancellationError())); return }
+            self.started = true
             self.completion = completion
-            let manager = CLLocationManager()
+            let manager = self.makeManager()
             self.manager = manager
             manager.delegate = self
-            self.handle(manager.authorizationStatus)
+            self.handle(manager.authorizationStatus, getter: .instanceInitial)
             if manager.authorizationStatus == .notDetermined { manager.requestWhenInUseAuthorization() }
         }
     }
 
     func cancel() {
-        DispatchQueue.main.async { self.finish(.failure(CancellationError())) }
+        DispatchQueue.main.async {
+            self.closed = true
+            self.ready = false
+            self.reply(.failure(CancellationError()))
+            self.manager?.delegate = nil
+            self.manager = nil
+            self.onRevoked = nil
+            self.onRestored = nil
+        }
+    }
+
+    /// A ready session retains its manager through owned Wi-Fi cleanup. An unanswered
+    /// authorization request must still settle when the join is cancelled.
+    func cancelPending() {
+        DispatchQueue.main.async {
+            if self.completion != nil { self.cancel() }
+        }
+    }
+
+    /// Query the same initialized recipient on its owning thread for every native read
+    /// or write. An earlier success is never an authorization cache.
+    func requireCurrentAuthorization() throws {
+        let check = {
+            guard !self.closed, let manager = self.manager else { throw CancellationError() }
+            let status = manager.authorizationStatus
+            let foreground = MacHotspotAuthorizationFacts.foreground()
+            self.facts.observeInstance(raw: status.rawValue, getter: .instanceCurrent, foreground: foreground)
+            guard self.locationServicesEnabled() else {
+                throw self.facts.failure("Location services are required to verify the current Mac Wi-Fi network", raw: status.rawValue,
+                                         getter: .instanceCurrent, foreground: foreground)
+            }
+            guard Self.isAuthorized(status) else {
+                throw self.facts.failure("Location access is required to verify the current Mac Wi-Fi network", raw: status.rawValue,
+                                         getter: .instanceCurrent, foreground: foreground)
+            }
+        }
+        if Thread.isMainThread { try check() }
+        else { try DispatchQueue.main.sync(execute: check) }
     }
 
     func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
-        handle(manager.authorizationStatus)
+        guard manager === self.manager, !closed else { return }
+        handle(manager.authorizationStatus, getter: .instanceCallback)
     }
 
     static func isAuthorized(_ status: CLAuthorizationStatus) -> Bool {
@@ -36,22 +92,33 @@ final class MacHotspotAuthorization: NSObject, CLLocationManagerDelegate {
         return false
     }
 
-    private func handle(_ status: CLAuthorizationStatus) {
-        if Self.isAuthorized(status) { finish(.success(())); return }
+    private func handle(_ status: CLAuthorizationStatus, getter: MacHotspotAuthorizationFacts.Getter) {
+        let foreground = MacHotspotAuthorizationFacts.foreground()
+        guard !closed else { return }
+        facts.observeInstance(raw: status.rawValue, getter: getter, foreground: foreground)
+        if Self.isAuthorized(status) {
+            ready = true
+            if revoked { revoked = false; onRestored?() }
+            reply(.success(()))
+            return
+        }
+        let error = facts.failure("Location access is required to identify the glasses hotspot on Mac", raw: status.rawValue, getter: getter, foreground: foreground)
+        if ready {
+            ready = false
+            revoked = true
+            onRevoked?(error)
+            return
+        }
         switch status {
         case .denied, .restricted:
-            finish(.failure(LocalMediaError("Location access is required to identify the glasses hotspot on Mac")))
+            reply(.failure(error))
         case .notDetermined: break
         default:
-            finish(.failure(LocalMediaError("Mac hotspot Location authorization is unavailable")))
+            reply(.failure(facts.failure("Mac hotspot Location authorization is unavailable", raw: status.rawValue, getter: getter, foreground: foreground)))
         }
     }
 
-    private func finish(_ result: Result<Void, Error>) {
-        guard !finished else { return }
-        finished = true
-        manager?.delegate = nil
-        manager = nil
+    private func reply(_ result: Result<Void, Error>) {
         let reply = completion
         completion = nil
         reply?(result)

package/ios/CoreKit/Sources/GlassesMediaCore/MacHotspotAuthorizationFacts.swift

@@ -0,0 +1,51 @@
+import Foundation
+#if canImport(UIKit)
+    import UIKit
+#elseif canImport(AppKit)
+    import AppKit
+#endif
+
+/// Diagnostic observations only. These facts never authorize a network read or a join.
+final class MacHotspotAuthorizationFacts {
+    enum Getter: String { case instanceInitial = "instance-initial", instanceCallback = "instance-callback", instanceCurrent = "instance-current", staticSSID = "static-ssid" }
+    enum Foreground: String { case active, inactive, background, unknown }
+    private let lock = NSLock()
+    private var instance: (raw: Int32, getter: Getter, foreground: Foreground)?
+    private var initialCallbackObserved = false
+    private let pid = ProcessInfo.processInfo.processIdentifier
+    private let bundleID = Bundle.main.bundleIdentifier.flatMap { value in
+        value.range(of: "^[A-Za-z0-9_.-]{1,128}$", options: .regularExpression) == nil ? nil : value
+    } ?? "unknown"
+
+    /// UIKit/AppKit state is sampled only on its owning thread. A worker read stays unknown.
+    static func foreground() -> Foreground {
+        guard Thread.isMainThread else { return .unknown }
+        #if canImport(UIKit)
+            switch UIApplication.shared.applicationState {
+            case .active: return .active
+            case .inactive: return .inactive
+            case .background: return .background
+            @unknown default: return .unknown
+            }
+        #elseif canImport(AppKit)
+            return NSApplication.shared.isActive ? .active : .inactive
+        #else
+            return .unknown
+        #endif
+    }
+
+    func observeInstance(raw: Int32, getter: Getter, foreground: Foreground) {
+        lock.lock(); defer { lock.unlock() }
+        instance = (raw, getter, foreground)
+        if getter == .instanceCallback { initialCallbackObserved = true }
+    }
+
+    /// Only enums and this process's identity cross the existing bounded error bridge.
+    func failure(_ message: String, raw: Int32, getter: Getter, foreground: Foreground) -> LocalMediaError {
+        lock.lock(); defer { lock.unlock() }
+        let instanceRaw = instance.map { String($0.raw) } ?? "unknown"
+        let instanceGetter = instance?.getter.rawValue ?? "unknown"
+        let instanceForeground = instance?.foreground.rawValue ?? "unknown"
+        return LocalMediaError("\(message) [location raw=\(raw) getter=\(getter.rawValue) foreground=\(foreground.rawValue) instanceRaw=\(instanceRaw) instanceGetter=\(instanceGetter) instanceForeground=\(instanceForeground) initialCallbackObserved=\(initialCallbackObserved) pid=\(pid) bundle=\(bundleID)]")
+    }
+}

package/ios/CoreKit/Sources/GlassesMediaCore/MacHotspotCleanupContinuation.swift

@@ -0,0 +1,35 @@
+import Foundation
+
+/// Retain a real authorization restoration while this session's cleanup result
+/// is still returning from its worker. All state belongs to the hotspot owner queue.
+final class MacHotspotCleanupContinuation {
+    private var restorationPending = false
+    private let isCurrentCancelledSession: () -> Bool
+    private let requestCleanup: () -> Void
+
+    init(authorization: MacHotspotAuthorization, queue: DispatchQueue,
+         isCurrentCancelledSession: @escaping () -> Bool, requestCleanup: @escaping () -> Void)
+    {
+        self.isCurrentCancelledSession = isCurrentCancelledSession
+        self.requestCleanup = requestCleanup
+        authorization.onRestored = { [weak self] in
+            queue.async { [weak self] in
+                guard let self, self.isCurrentCancelledSession() else { return }
+                self.restorationPending = true
+                self.requestCleanup()
+            }
+        }
+    }
+
+    func cleanupStarted() {
+        restorationPending = false
+    }
+
+    func cleanupFailed() {
+        guard restorationPending, isCurrentCancelledSession() else { return }
+        restorationPending = false
+        // A current restoration was not consumed by the failed worker attempt.
+        // Resume only its owned cleanup, which rechecks live permission and SSID.
+        requestCleanup()
+    }
+}

package/ios/GlassesHotspotNetwork.swift

@@ -17,9 +17,11 @@ public final class GlassesHotspotNetwork {
     private var generation = 0
     private var applying = false
     private var ownsConfiguration = false
+    private var applies = 0
+    private let reapplyPolicy = HotspotReapplyPolicy()
     private var cancelled = false
     private var joinReply: ((Result<String, Error>) -> Void)?
-    private var leaveReplies: [(Result<Void, Error>) -> Void] = []
+    private var leaveCompletion: HotspotLeaveCompletion?
     private var interfaceMonitors: [NWPathMonitor] = []
     /// Wi-Fi identity learned since this join started; replaced on every join and cleared on leave.
     private var wifiIdentity = HotspotWifiIdentity()
@@ -31,8 +33,11 @@ public final class GlassesHotspotNetwork {
     private let macWorker = DispatchQueue(label: "com.mentra.glassesmedia.mac-wifi")
     private var macAssociation: MacHotspotAssociation?
     private var macAuthorization: MacHotspotAuthorization?
+    private var macCleanupContinuation: MacHotspotCleanupContinuation?
     private var ownershipToken: UUID?
     private var finishingLeave = false
+    private var waitForInternetAfterLeave = false
+    private let internetObservationOwner = HotspotInternetObservationOwner()
     public var onLost: ((String) -> Void)?
     public var onPermissionRequired: (() -> Void)?
     public init() {}
@@ -52,6 +57,7 @@ public final class GlassesHotspotNetwork {
             self.ownershipToken = token
             self.generation += 1
             let gen = self.generation
+            let deadline = ProcessInfo.processInfo.systemUptime + 60
             self.ssid = ssid
             self.lastHotspotSSID = ssid
             self.gatewayAddress = gateway
@@ -59,20 +65,21 @@ public final class GlassesHotspotNetwork {
             self.cancelled = false
             self.applying = false
             self.ownsConfiguration = false
+            self.applies = 0
             self.joinReply = completion
             self.startInterfaceMonitors(generation: gen)
             if ProcessInfo.processInfo.isiOSAppOnMac {
-                self.authorizeMacAssociation(ssid: ssid, passphrase: passphrase, generation: gen)
+                self.authorizeMacAssociation(ssid: ssid, passphrase: passphrase, generation: gen, deadline: deadline)
             } else {
                 self.applyConfiguration(ssid: ssid, passphrase: passphrase, generation: gen)
             }
-            self.queue.asyncAfter(deadline: .now() + 60) {
+            self.queue.asyncAfter(deadline: .now() + max(0, deadline - ProcessInfo.processInfo.systemUptime)) {
                 // Once associated, the user may still be reading the Local Network alert.
                 // Its response time is not a hotspot association timeout.
                 guard gen == self.generation, self.joinReply != nil, self.localAccess == nil else { return }
                 self.cancelled = true
                 self.macAssociation?.cancel()
-                self.macAuthorization?.cancel()
+                self.macAuthorization?.cancelPending()
                 self.finishJoin(.failure(LocalMediaError("Hotspot join timed out")))
                 // apply() cannot be cancelled. Retain the reservation until its callback and remove the
                 // late configuration before another call is permitted to acquire the network.
@@ -82,12 +89,20 @@ public final class GlassesHotspotNetwork {
         }
     }
 
-    public func leave(completion: @escaping (Result<Void, Error>) -> Void) {
+    public func leave(waitForInternet: Bool = false, completion: @escaping (Result<Void, Error>) -> Void) {
         queue.async {
+            if !waitForInternet { self.internetObservationOwner.cancel() }
+            self.waitForInternetAfterLeave = self.waitForInternetAfterLeave || waitForInternet
             self.cancelled = true
             self.macAssociation?.cancel()
-            self.macAuthorization?.cancel()
-            self.leaveReplies.append(completion)
+            self.macAuthorization?.cancelPending()
+            if self.leaveCompletion == nil {
+                self.leaveCompletion = HotspotLeaveCompletion {
+                    if let token = self.ownershipToken { HotspotNetworkOwnership.shared.release(token) }
+                    self.ownershipToken = nil
+                }
+            }
+            self.leaveCompletion?.append(completion)
             self.finishJoin(.failure(LocalMediaError("Hotspot join cancelled")))
             if let ssid = self.ssid, self.ownsConfiguration { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
             if !self.applying { self.finishLeave() }
@@ -157,52 +172,104 @@ public final class GlassesHotspotNetwork {
     }
 
     public func awaitInternet(allowWifiAfterRelease: Bool = false, completion: @escaping (Bool, String) -> Void) {
-        queue.async {
-            let monitor = NWPathMonitor()
-            var finished = false
-            let finish: (Bool, String) -> Void = { usable, detail in
-                guard !finished else { return }
-                finished = true
-                monitor.cancel()
+        queue.async { self.startInternetObservation(allowWifiAfterRelease: allowWifiAfterRelease, completion: completion) }
+    }
+
+    /// Called on the owner queue, including directly from completeLeave. A queued
+    /// cancellation therefore cannot overtake observation initialization.
+    private func startInternetObservation(allowWifiAfterRelease: Bool, completion: @escaping (Bool, String) -> Void) {
+        let gen = generation
+        let observation = HotspotInternetObservation(generation: gen, glassesSSID: lastHotspotSSID)
+        let monitor = NWPathMonitor()
+        let sampleTimer = DispatchSource.makeTimerSource(queue: queue)
+        var currentPath: Network.NWPath?
+        let finish: (Bool, String) -> Void = { usable, detail in
+            guard observation.settle() else { return }
+            monitor.pathUpdateHandler = nil
+            monitor.cancel()
+            sampleTimer.setEventHandler {}
+            sampleTimer.cancel()
+            currentPath = nil
+            let reply = {
+                self.internetObservationOwner.clear(observation)
                 completion(usable, detail)
             }
-            monitor.pathUpdateHandler = { path in
-                if let route = HotspotInternetPolicy.route(satisfied: path.status == .satisfied,
-                                                           cellular: path.usesInterfaceType(.cellular),
-                                                           ethernet: path.usesInterfaceType(.wiredEthernet))
-                {
+            // Even a timed-out/cancelled observation joins its dispatched
+            // CoreWLAN read before releasing this session's owner.
+            observation.afterSSIDRead(reply)
+        }
+        internetObservationOwner.install(observation) { finish(false, "Hotspot internet observation cancelled") }
+        var currentPathRevision = 0
+        let sample = {
+            guard let path = currentPath else { return }
+            if let route = HotspotInternetPolicy.route(satisfied: path.status == .satisfied,
+                                                       cellular: path.usesInterfaceType(.cellular),
+                                                       ethernet: path.usesInterfaceType(.wiredEthernet))
+            {
+                finish(true, route)
+                return
+            }
+            // Sample returned membership while the route remains on Wi-Fi;
+            // NWPath need not report a new interface when the SSID changes.
+            guard allowWifiAfterRelease, path.status == .satisfied,
+                  path.usesInterfaceType(.wifi), observation.beginSSIDRead() else { return }
+            let pathRevision = currentPathRevision
+            let observed: (String?) -> Void = { ssid in
+                self.queue.async {
+                    observation.completeSSIDRead()
+                    guard gen == self.generation else { finish(false, "Hotspot session changed"); return }
+                    guard let route = observation.restoredWifiRoute(ssid: ssid, pathRevision: pathRevision, currentGeneration: self.generation)
+                    else { return }
                     finish(true, route)
-                    return
                 }
-                // Once the hotspot is released, a return to the user's Wi-Fi is also valid.
-                // Do not mistake the departing glasses AP's local-only path for restored internet.
-                if allowWifiAfterRelease, path.status == .satisfied, path.usesInterfaceType(.wifi) {
-                    NEHotspotNetwork.fetchCurrent { network in
-                        self.queue.async {
-                            guard let route = HotspotInternetPolicy.route(satisfied: true, cellular: false, ethernet: false,
-                                                                          restoredWifiSSID: network?.ssid, glassesSSID: self.lastHotspotSSID)
-                            else { return }
-                            finish(true, route)
-                        }
-                    }
-                }
-            }
-            monitor.start(queue: self.queue)
-            self.queue.asyncAfter(deadline: .now() + 15) {
-                finish(false, allowWifiAfterRelease ? "Internet did not return after leaving the glasses hotspot" : "Cellular or Ethernet internet did not become the default route")
             }
+            if ProcessInfo.processInfo.isiOSAppOnMac {
+                self.macWorker.async { observed(try? MacHotspotAssociation.observeCurrentSSID()) }
+            } else { NEHotspotNetwork.fetchCurrent { observed($0?.ssid) } }
+        }
+        monitor.pathUpdateHandler = { path in
+            guard let pathRevision = observation.beginPath(currentGeneration: self.generation) else { finish(false, "Hotspot session changed"); return }
+            currentPath = path
+            currentPathRevision = pathRevision
+            sample()
+        }
+        sampleTimer.setEventHandler(handler: sample)
+        sampleTimer.schedule(deadline: .now() + 0.5, repeating: 0.5)
+        sampleTimer.resume()
+        monitor.start(queue: queue)
+        queue.asyncAfter(deadline: .now() + 15) {
+            finish(false, allowWifiAfterRelease ? "Internet did not return after leaving the glasses hotspot" : "Cellular or Ethernet internet did not become the default route")
         }
     }
 
-    private func authorizeMacAssociation(ssid: String, passphrase: String, generation gen: Int) {
-        let authorization = MacHotspotAuthorization()
+    private func authorizeMacAssociation(ssid: String, passphrase: String, generation gen: Int, deadline: TimeInterval) {
+        let facts = MacHotspotAuthorizationFacts()
+        let authorization = MacHotspotAuthorization(facts: facts)
         macAuthorization = authorization
+        authorization.onRevoked = { [weak self] error in
+            guard let self else { return }
+            self.queue.async {
+                guard gen == self.generation, !self.cancelled else { return }
+                self.cancelled = true
+                self.macAssociation?.cancel()
+                self.finishJoin(.failure(error))
+                self.onLost?("Glasses hotspot Location authorization was revoked")
+                if !self.applying { self.finishLeave() }
+            }
+        }
+        macCleanupContinuation = MacHotspotCleanupContinuation(authorization: authorization, queue: queue,
+                                                               isCurrentCancelledSession: { [weak self] in
+                                                                   guard let self else { return false }
+                                                                   return gen == self.generation && self.cancelled
+                                                               }, requestCleanup: { [weak self] in
+                                                                   guard let self, !self.applying else { return }
+                                                                   self.finishLeave()
+                                                               })
         authorization.start { result in
             self.queue.async {
                 guard gen == self.generation, !self.cancelled else { return }
-                self.macAuthorization = nil
                 switch result {
-                case .success: self.applyMacAssociation(ssid: ssid, passphrase: passphrase, generation: gen)
+                case .success: self.applyMacAssociation(ssid: ssid, passphrase: passphrase, generation: gen, deadline: deadline, authorizationFacts: facts, authorization: authorization)
                 case let .failure(error):
                     self.finishJoin(.failure(error)); self.finishLeave()
                 }
@@ -210,8 +277,8 @@ public final class GlassesHotspotNetwork {
         }
     }
 
-    private func applyMacAssociation(ssid: String, passphrase: String, generation gen: Int) {
-        let association = MacHotspotAssociation()
+    private func applyMacAssociation(ssid: String, passphrase: String, generation gen: Int, deadline: TimeInterval, authorizationFacts: MacHotspotAuthorizationFacts, authorization: MacHotspotAuthorization) {
+        let association = MacHotspotAssociation(deadline: deadline, authorizationFacts: authorizationFacts, authorization: authorization)
         macAssociation = association
         applying = true
         macWorker.async {
@@ -260,12 +327,13 @@ public final class GlassesHotspotNetwork {
         }
     }
 
-    private func applyConfiguration(ssid: String, passphrase: String, generation gen: Int) {
+    private func applyConfiguration(ssid: String, passphrase: String, generation gen: Int, remaining: Int = 60) {
         let config = NEHotspotConfiguration(ssid: ssid, passphrase: passphrase, isWEP: false)
         config.joinOnce = false
         applying = true
         ownsConfiguration = true
-        logger.info("HOTSPOT_JOIN apply_start ios_on_mac=\(ProcessInfo.processInfo.isiOSAppOnMac)")
+        applies += 1
+        logger.info("HOTSPOT_JOIN apply_start attempt=\(self.applies) ios_on_mac=\(ProcessInfo.processInfo.isiOSAppOnMac)")
         NEHotspotConfigurationManager.shared.apply(config) { error in
             self.queue.async {
                 guard gen == self.generation else { return }
@@ -283,12 +351,12 @@ public final class GlassesHotspotNetwork {
                     }
                 }
                 self.logger.info("HOTSPOT_JOIN apply_accepted")
-                self.waitForAddress(ssid: ssid, generation: gen, remaining: 60)
+                self.waitForAddress(ssid: ssid, passphrase: passphrase, generation: gen, remaining: remaining, pollsSinceApply: 0)
             }
         }
     }
 
-    private func waitForAddress(ssid: String, generation gen: Int, remaining: Int) {
+    private func waitForAddress(ssid: String, passphrase: String, generation gen: Int, remaining: Int, pollsSinceApply: Int) {
         guard gen == generation, !cancelled else { return }
         NEHotspotNetwork.fetchCurrent { [weak self] network in
             self?.queue.async {
@@ -297,8 +365,15 @@ public final class GlassesHotspotNetwork {
                 if network?.ssid == ssid, let selected = self.selectBinding() {
                     self.bind(selected)
                     self.finishAssociation(address: selected.address, generation: gen)
+                } else if remaining > 0, network?.ssid != ssid,
+                          self.reapplyPolicy.shouldReapply(applies: self.applies, pollsSinceApply: pollsSinceApply) {
+                    // iOS reports the request applied even when its one scan missed the hotspot.
+                    self.logger.info("HOTSPOT_JOIN reapply after_polls=\(pollsSinceApply)")
+                    self.applyConfiguration(ssid: ssid, passphrase: passphrase, generation: gen, remaining: remaining)
                 } else if remaining > 0 {
-                    self.queue.asyncAfter(deadline: .now() + 0.5) { self.waitForAddress(ssid: ssid, generation: gen, remaining: remaining - 1) }
+                    self.queue.asyncAfter(deadline: .now() + 0.5) {
+                        self.waitForAddress(ssid: ssid, passphrase: passphrase, generation: gen, remaining: remaining - 1, pollsSinceApply: pollsSinceApply + 1)
+                    }
                 } else {
                     let association = network == nil ? "unavailable" : (network?.ssid == ssid ? "matched" : "different")
                     self.finishJoin(.failure(LocalMediaError("Glasses hotspot has no verified Wi-Fi address (SSID=\(association), \(self.wifiDiagnostic()))")))
@@ -412,6 +487,7 @@ public final class GlassesHotspotNetwork {
     private func finishLeave() {
         guard !finishingLeave else { return }
         finishingLeave = true
+        macCleanupContinuation?.cleanupStarted()
         if let association = macAssociation {
             association.cancel()
             // This queue is also the association queue: cleanup cannot overtake
@@ -427,9 +503,10 @@ public final class GlassesHotspotNetwork {
                         // Retain the owner when we cannot prove which association
                         // cleanup would disconnect. A later leave can retry safely.
                         self.finishingLeave = false
-                        let replies = self.leaveReplies
-                        self.leaveReplies.removeAll()
-                        replies.forEach { $0(.failure(error)) }
+                        let completion = self.leaveCompletion
+                        self.leaveCompletion = nil
+                        completion?.complete(.failure(error))
+                        self.macCleanupContinuation?.cleanupFailed()
                     }
                 }
             }
@@ -437,6 +514,8 @@ public final class GlassesHotspotNetwork {
     }
 
     private func completeLeave() {
+        internetObservationOwner.cancel()
+        macCleanupContinuation = nil
         generation += 1
         macAuthorization?.cancel(); macAuthorization = nil
         localAccess?.cancel(); localAccess = nil
@@ -448,12 +527,25 @@ public final class GlassesHotspotNetwork {
         ssid = nil
         binding = nil
         gatewayAddress = nil
-        finishingLeave = false
-        if let token = ownershipToken { HotspotNetworkOwnership.shared.release(token) }
-        ownershipToken = nil
-        let replies = leaveReplies
-        leaveReplies.removeAll()
-        replies.forEach { $0(.success(())) }
+        let finish = {
+            self.waitForInternetAfterLeave = false
+            self.finishingLeave = false
+            let completion = self.leaveCompletion
+            self.leaveCompletion = nil
+            if let completion { completion.complete(.success(())) } else {
+                if let token = self.ownershipToken { HotspotNetworkOwnership.shared.release(token) }
+                self.ownershipToken = nil
+            }
+        }
+        if waitForInternetAfterLeave, ProcessInfo.processInfo.isiOSAppOnMac {
+            // Keep this owner until the default route returns or the existing
+            // bounded observation ends. Route readiness is not HTTP success;
+            // the following ordinary update check still owns that result.
+            startInternetObservation(allowWifiAfterRelease: true) { ready, reason in
+                self.logger.info("HOTSPOT_LEAVE internet_recovery ready=\(ready) reason=\(reason, privacy: .public)")
+                finish()
+            }
+        } else { finish() }
     }
 
     /// Every attached interface's kernel index and link type (its AF_LINK row) and every IPv4

package/ios/GlassesMediaRelayModule.swift

@@ -31,10 +31,10 @@ public final class GlassesMediaRelayModule: Module {
             }
         }
 
-        AsyncFunction("leaveLocalHotspot") { (id: String, promise: Promise) in
+        AsyncFunction("leaveLocalHotspot") { (id: String, waitForInternet: Bool, promise: Promise) in
             self.queue.async {
                 guard self.localHotspotOwner == id else { promise.resolve(nil); return }
-                self.localHotspot.leave { result in
+                self.localHotspot.leave(waitForInternet: waitForInternet) { result in
                     self.queue.async {
                         switch result {
                         case .success:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/glasses-media",
-  "version": "3.3.0",
+  "version": "3.4.0-beta.1241",
   "description": "Shared native glasses media receivers and local network transport",
   "license": "MIT",
   "author": "Mentra Community",