feat(clients): Wake-on-LAN in apple/linux/windows/android/decky

Each client learns a host's MAC from the mDNS `mac` TXT while it's awake, persists it on the saved-host record, and — when reconnecting to an offline host — sends a magic packet before connecting, plus an explicit "Wake host" action. Apple wraps the C-ABI; linux/windows call the core fn directly (linux also gains a --wake CLI mode); android via a new nativeWakeOnLan JNI export (the mDNS browse record gains a 7th mac field); decky shells out to the linux client's --wake before launching the stream.

iOS/tvOS need the managed com.apple.developer.networking.multicast entitlement (pending Apple approval), so the wake path + UI are gated off via PunktfunkConnection.wakeOnLANAvailable and the entitlement is commented out — keeping iOS/tvOS releasable. MAC-learning stays active on every platform so it lights up the moment it's ungated. macOS works today.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -408,6 +408,7 @@ struct ContentView: View {
         _ host: StoredHost, launchID: String? = nil,
         allowTofu: Bool, requestAccess: Bool = false
     ) {
+        prepareWake(for: host)
         model.connect(
             to: host,
             width: UInt32(clamping: width), height: UInt32(clamping: height),
@@ -426,6 +427,25 @@ struct ContentView: View {
             requestAccess: requestAccess)
     }
 
+    /// Learn-while-awake, wake-while-asleep — run just before every connect:
+    ///  • host currently advertising (awake) → refresh its stored Wake-on-LAN MAC(s) from the live
+    ///    advert, so a later wake has an up-to-date target;
+    ///  • host NOT advertising (likely asleep/off) and we have MAC(s) → fire a magic packet first.
+    ///    The connect that follows already retries/times out long enough for a woken host to come
+    ///    up; if it's genuinely off/unreachable the connect fails as before. Best-effort and
+    ///    non-blocking (the send runs off the main thread).
+    private func prepareWake(for host: StoredHost) {
+        if let live = discovery.hosts.first(where: { host.matches($0) }) {
+            store.updateMacs(host.id, macs: live.macAddresses) // learn — on every platform
+        } else if PunktfunkConnection.wakeOnLANAvailable, !host.wakeMacs.isEmpty {
+            let macs = host.wakeMacs
+            let ip = host.address
+            DispatchQueue.global(qos: .userInitiated).async {
+                PunktfunkConnection.wakeOnLAN(macs: macs, lastKnownIP: ip)
+            }
+        }
+    }
+
     /// The no-PIN delegated-approval flow: open an identified connect the host parks until the
     /// operator approves it in the console, showing the cancelable "Waiting for approval" prompt
     /// meanwhile. On success the SAME connection is admitted (no reconnect) and the host is pinned
@@ -455,7 +475,9 @@ struct ContentView: View {
     /// inside `connect`.)
     private func connectDiscovered(_ d: DiscoveredHost) {
         guard !model.isBusy else { return }
-        let host = StoredHost(name: d.name, address: d.host, port: d.port)
+        let host = StoredHost(
+            name: d.name, address: d.host, port: d.port,
+            macAddresses: d.macAddresses.isEmpty ? nil : d.macAddresses)
         store.add(host)
         if d.allowsTofu {
             connect(host, allowTofu: true)

clients/apple/Sources/PunktfunkClient/Home/HomeView.swift

@@ -154,7 +154,14 @@ struct HomeView: View {
             onSpeedTest: { if !model.isBusy { speedTestTarget = host } },
             onForget: { store.forgetIdentity(host) },
             onRemove: { store.remove(host) },
-            onBrowseLibrary: onBrowseLibrary)
+            onBrowseLibrary: onBrowseLibrary,
+            onWake: {
+                let macs = host.wakeMacs
+                let ip = host.address
+                DispatchQueue.global(qos: .userInitiated).async {
+                    PunktfunkConnection.wakeOnLAN(macs: macs, lastKnownIP: ip)
+                }
+            })
     }
 
     private var discoveredSection: some View {

clients/apple/Sources/PunktfunkClient/Home/HostCards.swift

@@ -86,6 +86,9 @@ struct HostCardView: View {
     let onRemove: () -> Void
     /// Open the experimental library browser — nil (no menu item) unless the feature flag is on.
     var onBrowseLibrary: (() -> Void)? = nil
+    /// Send a Wake-on-LAN magic packet. Shown only when the host is offline and we have a stored
+    /// MAC to target (a tap-to-connect already auto-wakes; this is the explicit "just wake it").
+    var onWake: (() -> Void)? = nil
 
     var body: some View {
         let m = CardMetrics.current
@@ -138,6 +141,9 @@ struct HostCardView: View {
             if let onBrowseLibrary {
                 Button("Browse Library…", action: onBrowseLibrary)
             }
+            if !isOnline, !host.wakeMacs.isEmpty, PunktfunkConnection.wakeOnLANAvailable, let onWake {
+                Button("Wake Host", systemImage: "power", action: onWake)
+            }
             if host.pinnedSHA256 != nil {
                 // Dropping the pin does NOT downgrade to TOFU: the next connect must re-pair via
                 // PIN (unless the host advertises pair=optional). Wording reflects that.

clients/apple/Sources/PunktfunkClient/Stores/HostStore.swift

@@ -26,9 +26,16 @@ struct StoredHost: Identifiable, Codable, Hashable {
     /// decode: synthesized Decodable ignores property defaults but treats a missing Optional as
     /// nil. Resolve via `effectiveMgmtPort`. (Auth is mTLS by the pinned identity — no token.)
     var mgmtPort: UInt16?
+    /// Wake-on-LAN MAC address(es) of the host's wake-capable NIC(s), each `aa:bb:cc:dd:ee:ff`.
+    /// Learned from the host's mDNS `mac` TXT record while it's awake and persisted here, so the
+    /// client can send a magic packet to wake the host later (when it's asleep and no longer
+    /// advertising). Optional (same forward-compat reason as `mgmtPort`); nil until first learned.
+    var macAddresses: [String]?
 
     var displayName: String { name.isEmpty ? address : name }
     var effectiveMgmtPort: UInt16 { mgmtPort ?? punktfunkDefaultMgmtPort }
+    /// Wake-capable, in a form the wake helper accepts (empty when none learned yet).
+    var wakeMacs: [String] { macAddresses ?? [] }
 }
 
 extension StoredHost {
@@ -101,6 +108,16 @@ final class HostStore: ObservableObject {
         hosts[i].pinnedSHA256 = fingerprint
     }
 
+    /// Learn/refresh this host's Wake-on-LAN MAC(s) from its live advert (called while the host is
+    /// awake, so the client can wake it once it sleeps). No-op when unchanged, so it doesn't churn
+    /// UserDefaults on every discovery tick.
+    func updateMacs(_ hostID: UUID, macs: [String]) {
+        guard !macs.isEmpty,
+              let i = hosts.firstIndex(where: { $0.id == hostID }),
+              hosts[i].macAddresses != macs else { return }
+        hosts[i].macAddresses = macs
+    }
+
     /// Drop the pinned identity (e.g. after a legitimate host reinstall). This does NOT downgrade
     /// to TOFU: the next connect re-pairs via the PIN ceremony, unless the host advertises
     /// `pair=optional` (the only case the connect path still offers the trust prompt).