From 3863fe64124502ec0f356f55c01c9f5eba734ee8 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 13 Dec 2025 12:28:34 +0000
Subject: [PATCH] fix(ios): stabilize voice wake + bridge UI

---
 apps/ios/README.md                            |  2 +-
 .../Sources/Bridge/BridgeDiscoveryModel.swift | 10 ++++----
 .../ios/Sources/Bridge/BridgeEndpointID.swift | 19 +++++++++++++++
 apps/ios/Sources/Info.plist                   |  8 +++----
 apps/ios/Sources/Model/NodeAppModel.swift     | 10 ++++----
 apps/ios/Sources/Settings/SettingsTab.swift   |  8 ++-----
 apps/ios/Sources/Voice/VoiceWakeManager.swift | 23 ++++++++++++-------
 apps/ios/project.yml                          |  8 +++----
 docs/gateway/pairing.md                       |  6 +++++
 9 files changed, 60 insertions(+), 34 deletions(-)
 create mode 100644 apps/ios/Sources/Bridge/BridgeEndpointID.swift

diff --git a/apps/ios/README.md b/apps/ios/README.md
index cc7f5cba2..2d0dd056f 100644
--- a/apps/ios/README.md
+++ b/apps/ios/README.md
@@ -1,4 +1,4 @@
-# ClawdisNode (iOS)
+# ClawdisKit (iOS)
 
 Internal-only SwiftUI app scaffold.
 
diff --git a/apps/ios/Sources/Bridge/BridgeDiscoveryModel.swift b/apps/ios/Sources/Bridge/BridgeDiscoveryModel.swift
index 79f5b6d67..cf47b88a4 100644
--- a/apps/ios/Sources/Bridge/BridgeDiscoveryModel.swift
+++ b/apps/ios/Sources/Bridge/BridgeDiscoveryModel.swift
@@ -5,9 +5,10 @@ import Network
 @MainActor
 final class BridgeDiscoveryModel: ObservableObject {
     struct DiscoveredBridge: Identifiable, Equatable {
-        var id: String { self.debugID }
+        var id: String { self.stableID }
         var name: String
         var endpoint: NWEndpoint
+        var stableID: String
         var debugID: String
     }
 
@@ -54,7 +55,8 @@ final class BridgeDiscoveryModel: ObservableObject {
                         return DiscoveredBridge(
                             name: decodedName,
                             endpoint: result.endpoint,
-                            debugID: Self.prettyEndpointDebugID(result.endpoint))
+                            stableID: BridgeEndpointID.stableID(result.endpoint),
+                            debugID: BridgeEndpointID.prettyDescription(result.endpoint))
                     default:
                         return nil
                     }
@@ -73,8 +75,4 @@ final class BridgeDiscoveryModel: ObservableObject {
         self.bridges = []
         self.statusText = "Stopped"
     }
-
-    private static func prettyEndpointDebugID(_ endpoint: NWEndpoint) -> String {
-        BonjourEscapes.decode(String(describing: endpoint))
-    }
 }
diff --git a/apps/ios/Sources/Bridge/BridgeEndpointID.swift b/apps/ios/Sources/Bridge/BridgeEndpointID.swift
new file mode 100644
index 000000000..e5662f433
--- /dev/null
+++ b/apps/ios/Sources/Bridge/BridgeEndpointID.swift
@@ -0,0 +1,19 @@
+import ClawdisKit
+import Foundation
+import Network
+
+enum BridgeEndpointID {
+    static func stableID(_ endpoint: NWEndpoint) -> String {
+        switch endpoint {
+        case let .service(name, type, domain, _):
+            // Keep this stable across encode/decode differences; use raw service tuple.
+            "\(type)|\(domain)|\(name)"
+        default:
+            String(describing: endpoint)
+        }
+    }
+
+    static func prettyDescription(_ endpoint: NWEndpoint) -> String {
+        BonjourEscapes.decode(String(describing: endpoint))
+    }
+}
diff --git a/apps/ios/Sources/Info.plist b/apps/ios/Sources/Info.plist
index e525cf7b4..05d3889f5 100644
--- a/apps/ios/Sources/Info.plist
+++ b/apps/ios/Sources/Info.plist
@@ -5,7 +5,7 @@
 	<key>CFBundleDevelopmentRegion</key>
 	<string>$(DEVELOPMENT_LANGUAGE)</string>
 	<key>CFBundleDisplayName</key>
-	<string>Clawdis Node</string>
+	<string>ClawdisKit</string>
 	<key>CFBundleExecutable</key>
 	<string>$(EXECUTABLE_NAME)</string>
 	<key>CFBundleIdentifier</key>
@@ -25,11 +25,11 @@
 		<string>_clawdis-bridge._tcp</string>
 	</array>
 	<key>NSLocalNetworkUsageDescription</key>
-	<string>Clawdis Node discovers and connects to your Clawdis bridge on the local network.</string>
+	<string>ClawdisKit discovers and connects to your Clawdis bridge on the local network.</string>
 	<key>NSMicrophoneUsageDescription</key>
-	<string>Clawdis Node needs microphone access for voice wake.</string>
+	<string>ClawdisKit needs microphone access for voice wake.</string>
 	<key>NSSpeechRecognitionUsageDescription</key>
-	<string>Clawdis Node uses on-device speech recognition for voice wake.</string>
+	<string>ClawdisKit uses on-device speech recognition for voice wake.</string>
 	<key>UIApplicationSceneManifest</key>
 	<dict>
 		<key>UIApplicationSupportsMultipleScenes</key>
diff --git a/apps/ios/Sources/Model/NodeAppModel.swift b/apps/ios/Sources/Model/NodeAppModel.swift
index 0c5227f2c..e86f1c677 100644
--- a/apps/ios/Sources/Model/NodeAppModel.swift
+++ b/apps/ios/Sources/Model/NodeAppModel.swift
@@ -9,7 +9,7 @@ final class NodeAppModel: ObservableObject {
     @Published var bridgeStatusText: String = "Not connected"
     @Published var bridgeServerName: String?
     @Published var bridgeRemoteAddress: String?
-    @Published var connectedBridgeDebugID: String?
+    @Published var connectedBridgeID: String?
 
     private let bridge = BridgeSession()
     private var bridgeTask: Task<Void, Never>?
@@ -58,7 +58,7 @@ final class NodeAppModel: ObservableObject {
         self.bridgeStatusText = "Connecting…"
         self.bridgeServerName = nil
         self.bridgeRemoteAddress = nil
-        self.connectedBridgeDebugID = BonjourEscapes.decode(String(describing: endpoint))
+        self.connectedBridgeID = BridgeEndpointID.stableID(endpoint)
 
         self.bridgeTask = Task {
             do {
@@ -96,14 +96,14 @@ final class NodeAppModel: ObservableObject {
                     self.bridgeStatusText = "Disconnected"
                     self.bridgeServerName = nil
                     self.bridgeRemoteAddress = nil
-                    self.connectedBridgeDebugID = nil
+                    self.connectedBridgeID = nil
                 }
             } catch {
                 await MainActor.run {
                     self.bridgeStatusText = "Bridge error: \(error.localizedDescription)"
                     self.bridgeServerName = nil
                     self.bridgeRemoteAddress = nil
-                    self.connectedBridgeDebugID = nil
+                    self.connectedBridgeID = nil
                 }
             }
         }
@@ -116,7 +116,7 @@ final class NodeAppModel: ObservableObject {
         self.bridgeStatusText = "Disconnected"
         self.bridgeServerName = nil
         self.bridgeRemoteAddress = nil
-        self.connectedBridgeDebugID = nil
+        self.connectedBridgeID = nil
     }
 
     func sendVoiceTranscript(text: String, sessionKey: String?) async throws {
diff --git a/apps/ios/Sources/Settings/SettingsTab.swift b/apps/ios/Sources/Settings/SettingsTab.swift
index 3b19b2332..1a07f731c 100644
--- a/apps/ios/Sources/Settings/SettingsTab.swift
+++ b/apps/ios/Sources/Settings/SettingsTab.swift
@@ -98,9 +98,9 @@ struct SettingsTab: View {
             Text("No bridges found yet.")
                 .foregroundStyle(.secondary)
         } else {
-            let connectedID = self.appModel.connectedBridgeDebugID
+            let connectedID = self.appModel.connectedBridgeID
             let rows = self.discovery.bridges.filter { bridge in
-                let isConnected = bridge.debugID == connectedID
+                let isConnected = bridge.stableID == connectedID
                 switch showing {
                 case .all:
                     return true
@@ -117,10 +117,6 @@ struct SettingsTab: View {
                     HStack {
                         VStack(alignment: .leading, spacing: 2) {
                             Text(bridge.name)
-                            Text(bridge.debugID)
-                                .font(.caption2)
-                                .foregroundStyle(.secondary)
-                                .lineLimit(1)
                         }
                         Spacer()
 
diff --git a/apps/ios/Sources/Voice/VoiceWakeManager.swift b/apps/ios/Sources/Voice/VoiceWakeManager.swift
index aacb5bba6..91871ca22 100644
--- a/apps/ios/Sources/Voice/VoiceWakeManager.swift
+++ b/apps/ios/Sources/Voice/VoiceWakeManager.swift
@@ -2,6 +2,13 @@ import AVFAudio
 import Foundation
 import Speech
 
+private func makeAudioTapEnqueueCallback(queue: AudioBufferQueue) -> AVAudioNodeTapBlock {
+    { buffer, _ in
+        // This callback is invoked on a realtime audio thread/queue. Keep it tiny and nonisolated.
+        queue.enqueueCopy(of: buffer)
+    }
+}
+
 private final class AudioBufferQueue: @unchecked Sendable {
     private let lock = NSLock()
     private var buffers: [AVAudioPCMBuffer] = []
@@ -41,7 +48,7 @@ extension AVAudioPCMBuffer {
             let channels = Int(format.channelCount)
             let frames = Int(frameLength)
             for ch in 0..<channels {
-                dst[ch].assign(from: src[ch], count: frames)
+                dst[ch].update(from: src[ch], count: frames)
             }
             return copy
         }
@@ -50,7 +57,7 @@ extension AVAudioPCMBuffer {
             let channels = Int(format.channelCount)
             let frames = Int(frameLength)
             for ch in 0..<channels {
-                dst[ch].assign(from: src[ch], count: frames)
+                dst[ch].update(from: src[ch], count: frames)
             }
             return copy
         }
@@ -59,7 +66,7 @@ extension AVAudioPCMBuffer {
             let channels = Int(format.channelCount)
             let frames = Int(frameLength)
             for ch in 0..<channels {
-                dst[ch].assign(from: src[ch], count: frames)
+                dst[ch].update(from: src[ch], count: frames)
             }
             return copy
         }
@@ -176,11 +183,11 @@ final class VoiceWakeManager: NSObject, ObservableObject {
 
         let queue = AudioBufferQueue()
         self.tapQueue = queue
-        inputNode.installTap(onBus: 0, bufferSize: 1024, format: recordingFormat) { [weak queue] buffer, _ in
-            // `SFSpeechAudioBufferRecognitionRequest.append` is MainActor-isolated on iOS 26.
-            // Copy + enqueue in the realtime callback, drain + append from the MainActor.
-            queue?.enqueueCopy(of: buffer)
-        }
+        inputNode.installTap(
+            onBus: 0,
+            bufferSize: 1024,
+            format: recordingFormat,
+            block: makeAudioTapEnqueueCallback(queue: queue))
 
         self.audioEngine.prepare()
         try self.audioEngine.start()
diff --git a/apps/ios/project.yml b/apps/ios/project.yml
index 399b5a9d8..5e599261b 100644
--- a/apps/ios/project.yml
+++ b/apps/ios/project.yml
@@ -43,14 +43,14 @@ targets:
     info:
       path: Sources/Info.plist
       properties:
-        CFBundleDisplayName: Clawdis Node
+        CFBundleDisplayName: ClawdisKit
         UILaunchScreen: {}
         UIApplicationSceneManifest:
           UIApplicationSupportsMultipleScenes: false
         UIBackgroundModes:
           - audio
-        NSLocalNetworkUsageDescription: Clawdis Node discovers and connects to your Clawdis bridge on the local network.
+        NSLocalNetworkUsageDescription: ClawdisKit discovers and connects to your Clawdis bridge on the local network.
         NSBonjourServices:
           - _clawdis-bridge._tcp
-        NSMicrophoneUsageDescription: Clawdis Node needs microphone access for voice wake.
-        NSSpeechRecognitionUsageDescription: Clawdis Node uses on-device speech recognition for voice wake.
+        NSMicrophoneUsageDescription: ClawdisKit needs microphone access for voice wake.
+        NSSpeechRecognitionUsageDescription: ClawdisKit uses on-device speech recognition for voice wake.
diff --git a/docs/gateway/pairing.md b/docs/gateway/pairing.md
index 7de492cf9..24f7961e1 100644
--- a/docs/gateway/pairing.md
+++ b/docs/gateway/pairing.md
@@ -74,6 +74,12 @@ CLI must be able to fully operate without any GUI:
 Optional interactive helper:
 - `clawdis nodes watch` (subscribe to `node.pair.requested` and prompt in-place)
 
+Implementation pointers:
+- CLI commands: `src/cli/nodes-cli.ts`
+- Gateway handlers + events: `src/gateway/server.ts`
+- Pairing store: `src/infra/node-pairing.ts` (under `~/.clawdis/nodes/`)
+- Optional macOS UI prompt (frontend only): `apps/macos/Sources/Clawdis/NodePairingApprovalPrompter.swift`
+
 ## Storage (private, local)
 Gateway stores the authoritative state under `~/.clawdis/`:
 - `~/.clawdis/nodes/paired.json`