feat(macos): UI overhaul -- toolbar, unified log, PM windows, settings window, hotkeys

Mirrors the Windows client's UI overhaul (commit 97fa659 + 540ec13) adapted to
Mac-native conventions. The main window is now just toolbar + channels + users
+ chat; audio device settings moved to a modeless Settings window.

- NSToolbar: Join Voice, Share Screen Audio, Mute, Deafen (SF Symbol toggle
  buttons) + Output Volume slider (NSSlider 0-100, default 80). Voice actions,
  mute/deafen, and output volume moved out of the bottom panel into the toolbar
- Audio device settings (input mode, VAD sensitivity, PTT key, device picker,
  level meter) moved to a new SettingsWindowController -- a modeless window
  opened via the app menu's "Settings..." (Cmd+,) item. Source-of-truth for
  audio state lives in MainWindowController so voice start applies settings even
  before the window has been opened; SettingsWindowController reads from /
  writes back to those properties and applies changes live when voice is active.
  Level meter forwarded from handleLevel -> updateLevel(rms:)
- Unified log: chat NSTextView + activity NSTableView collapsed into a single
  NSTextView -- activity events in secondaryLabelColor (gray), chat in default
- Private messaging: scope dropdown removed; compose always sends to the
  current channel. Each PM conversation opens in its own modeless
  PrivateMessageWindowController. Incoming .textMessage with .private scope
  routed to the right window; outgoing PMs echoed by server arrive through the
  same path. "Send Private Message..." added to user context menu.
- Messages menu: "New Private Message..." (Cmd+Shift+N) opens a UserPickerSheet
  listing all server users so you can PM anyone on the server
- Channel tree now shows live user counts, e.g. "General (3)"; refreshChannelTree
  called on .userJoined/.userLeft (was missing)
- Voice menu: Join Voice (Cmd+Shift+V), Share Screen Audio (Cmd+Shift+S),
  Mute (Cmd+Shift+M), Deafen (Cmd+Shift+D) -- NSMenuItem key equivalents with
  [.command, .shift] mask, dispatched by the responder chain
- setOutputVolume(_:) wrapper added to VoiceCatClient.swift (was missing -- the
  C ABI + C# wrapper shipped in commit 97fa659 but the Swift wrapper was never
  added); wired end-to-end: toolbar slider -> client.setOutputVolume(gain)

Part A -- fixed and verified the previously-uncompiled Swift from the external
PCM feed/tap commit (615d2a8):
- Rebuilt the macOS xcframework slice (regenerated the module map from current
  voicecat.h, exposing vc_pcm_sink_cb / vc_stream_feed_pcm / vc_set_pcm_sink)
- Fixed feedPcm type bug: size_t imports as Int in Swift not UInt; the original
  UInt(samplesPerChannel) was wrong
- Added VoiceCatPcmSinkCallback typealias -- a Swift-idiomatic public alias for
  the C vc_pcm_sink_cb so consumers (tests, the macOS app) can declare a sink
  callback without directly importing the VoiceCatC C module. Mirrors the C#
  VcPcmSinkCallback delegate
- keyCodeName helper deduplicated (was in PttKeyCaptureSheet.swift +
  MainWindowController.swift -- now shared)

Platform-specific adaptations (vs. Windows): NSToolbar instead of ToolStrip;
global menu bar + NSMenuItem key equivalents (Cmd not Ctrl, responder-chain
dispatched, no custom key monitor needed); PM windows as modeless NSWindows;
picker as Mac sheet; gray = secondaryLabelColor; SF Symbols for toolbar icons.

swift test 10/10 (4 ExternalPcmTests + 6 VoiceCatClientSmokeTests against a
live server); xcodebuild Debug + Release BUILD SUCCEEDED with 0 Swift warnings.

PROGRESS.md

@@ -10,6 +10,17 @@ up instantly. Newest status at the top.
 
 ## ▶ Where we left off / next action
 
+- **Done (2026-06-20):** **macOS client UI overhaul** — mirrors the Windows client's UI
+  overhaul (commit 97fa659 + 540ec13), adapted to Mac-native conventions. Also fixed and
+  verified the previously-uncompiled Swift changes from the external PCM feed/tap commit
+  (615d2a8). The main window is now just toolbar + channels + users + chat; audio device
+  settings (input mode, VAD, PTT key, device picker, level meter) moved to a modeless
+  Settings window (⌘,). Details in M5 section below. `swift test` 10/10; `xcodebuild` Debug
+  + Release BUILD SUCCEEDED with 0 Swift warnings.
+  Next: live manual verification (toolbar toggles, unified log colors, PM windows, channel
+  counts, volume slider, settings window); then iOS ReplayKit and macOS ScreenCaptureKit
+  consumers of `vc_stream_feed_pcm`.
+
 - **Awaiting on-device verification:** **iOS stereo mic kills headphone/A2DP output — REAL
   root cause found & fixed** (2026-06-20, on Windows; verify on Mac). All prior "fixes" (the
   2026-06-19 entries below) targeted the Swift `IOSAudioRouter` on the false premise that
@@ -430,6 +441,58 @@ iOS 18.0 deployment target. App Group `group.cat.voice.VoiceCat` for Keychain sh
   `test_pcm_sink`), 4 Swift XCTest smoke tests, 4 C# xUnit smoke tests. Docs updated
   (architecture.md §4 new subsection, voice.md §9 updated, protocol.md §8 explicit
   no-protocol-change note, roadmap.md M5 entry). `ctest --preset dev` 23/23.
+- [x] **macOS client UI overhaul** — done 2026-06-20. Mirrors the Windows client's UI
+  overhaul (toolbar, unified log, PM windows, channel counts, output volume, keyboard
+  shortcuts), adapted to Mac-native conventions:
+  - **NSToolbar**: Join Voice, Share Screen Audio, Mute, Deafen (SF Symbol toggle buttons),
+    and Output Volume slider (NSSlider 0–100, default 80). Voice actions + mute/deafen +
+    output volume moved out of the bottom voice panel into the toolbar. Bottom panel keeps
+    input-mode segmented control / VAD slider / PTT key / device picker / level meter.
+  - **Unified log**: chat `NSTextView` + activity `NSTableView` collapsed into a single
+    `NSTextView` — activity events in `secondaryLabelColor` (gray), chat in default color.
+    Removed `activityTableView` and `activityLog` array.
+  - **Private messaging**: scope dropdown removed; compose bar always sends to the current
+    channel. Each PM conversation opens in its own modeless `PrivateMessageWindowController`
+    (NSWindow). Incoming `.textMessage` with `.private` scope routed to the right window;
+    outgoing PMs echoed by server arrive through the same path. "Send Private Message…"
+    added to user context menu. "New Private Message…" (⌘⇧N) opens `UserPickerSheet`
+    listing all server users.
+  - **Channel counts**: outline view renders `"Name (n)"` with live user counts;
+    `refreshChannelTree()` called on `.userJoined`/`.userLeft` (was missing).
+  - **Voice menu** (⌘⇧V join/leave, ⌘⇧S share screen, ⌘⇧M mute, ⌘⇧D deafen) and **Messages
+    menu** (⌘⇧N new PM) added to `NSApp.mainMenu` via `NSMenuItem` key equivalents with
+    `[.command, .shift]` mask. Removed on `windowWillClose`. Mac-native: ⌘ not Ctrl, dispatched
+    by the responder chain (no custom key monitor needed).
+  - **Output volume**: `setOutputVolume(_:)` wrapper added to `VoiceCatClient.swift` (was
+    missing — the C ABI + C# wrapper shipped in commit 97fa659 but the Swift wrapper was
+    never added). Wired end-to-end: toolbar slider → `client.setOutputVolume(gain)`.
+  - **Part A (uncompiled Swift fix)**: the external PCM feed/tap Swift wrapper (commit
+    615d2a8) was never compiled — the local xcframework predating the `voicecat.h` PCM
+    additions. Fixed: rebuilt xcframework (regenerated module map), fixed `UInt`→`Int` type
+    mismatch in `feedPcm` (Swift imports `size_t` as `Int` not `UInt`), added
+    `VoiceCatPcmSinkCallback` typealias (Swift-idiomatic alias for the C `vc_pcm_sink_cb`
+    so consumers don't need to directly import `VoiceCatC`). `swift test` 10/10 green.
+  - **Audio settings moved to Settings window**: the bottom voice panel (input mode, VAD
+    slider, PTT key, device picker, level meter) was removed from the main window and moved
+    into a new `SettingsWindowController` — a modeless window opened via the app menu's
+    "Settings…" (⌘,) item. The main window is now just toolbar + channels + users + chat.
+    Source-of-truth for audio settings (`selectedInputMode`, `vadThresholdValue`,
+    `selectedInputDeviceId`, `pttKeyCode`) lives in `MainWindowController` so voice start can
+    apply them even before the settings window has been opened; `SettingsWindowController`
+    reads from and writes back to those properties and applies changes to the client
+    immediately when voice is active. The level meter is forwarded from
+    `MainWindowController.handleLevel` → `settingsWindowController.updateLevel(rms:)`.
+    `keyCodeName` helper deduplicated (was duplicated in `PttKeyCaptureSheet.swift` +
+    `MainWindowController.swift` — now shared from `MainWindowController.swift`).
+  - Files: `MainWindowController.swift` (overhauled), `PrivateMessageWindowController.swift`
+    (new), `UserPickerSheet.swift` (new), `SettingsWindowController.swift` (new),
+    `VoiceCatClient.swift` (setOutputVolume + VoiceCatPcmSinkCallback typealias + feedPcm
+    type fix), `ExternalPcmTests.swift` (use typealias), `PttKeyCaptureSheet.swift` (removed
+    duplicate `keyCodeName`), `VoiceCatMac.xcodeproj/project.pbxproj` (register 3 new files).
+  - **Platform-specific adaptations** (vs. Windows): `NSToolbar` instead of `ToolStrip`;
+    global menu bar + `NSMenuItem` key equivalents (⌘ not Ctrl, responder-chain dispatched);
+    PM windows as modeless `NSWindow`s; picker as Mac sheet; gray = `secondaryLabelColor`;
+    SF Symbols for toolbar icons.
 
 ---
 

clients/apple/Sources/VoiceCatCore/VoiceCatClient.swift

@@ -35,6 +35,12 @@
 import VoiceCatC
 import Foundation
 
+/// Swift-idiomatic alias for the C `vc_pcm_sink_cb` function-pointer type from
+/// `voicecat.h`. Exposed publicly so consumers (`VoiceCatMac`, tests) can declare a sink
+/// callback without directly importing the `VoiceCatC` C module. Mirrors the C# wrapper's
+/// `VcPcmSinkCallback` delegate.
+public typealias VoiceCatPcmSinkCallback = vc_pcm_sink_cb
+
 /// The Swift wrapper around `vc_client*`. Owns the native handle for its entire lifetime;
 /// `deinit` destroys it. Events and level meters are delivered on the main queue via the
 /// `onEvent` / `onLevel` closures.
@@ -324,7 +330,7 @@ public final class VoiceCatClient {
     public func feedPcm(streamId: UInt32, pcm: UnsafePointer<Int16>,
                         samplesPerChannel: Int, channels: UInt32) -> VoiceCatResult {
         VoiceCatResult(vc_stream_feed_pcm(handle, streamId, pcm,
-                                         UInt(samplesPerChannel), channels))
+                                          samplesPerChannel, channels))
     }
 
     /// Convenience overload for feeding from a Swift `[Int16]` array.
@@ -345,7 +351,7 @@ public final class VoiceCatClient {
     ///
     /// Pass `nil` to disable (default). The callback MUST NOT block or allocate.
     @discardableResult
-    public func setPcmSink(_ cb: vc_pcm_sink_cb?, user: UnsafeMutableRawPointer?) -> VoiceCatResult {
+    public func setPcmSink(_ cb: VoiceCatPcmSinkCallback?, user: UnsafeMutableRawPointer?) -> VoiceCatResult {
         VoiceCatResult(vc_set_pcm_sink(handle, cb, user))
     }
 
@@ -370,6 +376,14 @@ public final class VoiceCatClient {
         VoiceCatResult(vc_set_self_mute(handle, micMuted ? 1 : 0, deafened ? 1 : 0))
     }
 
+    /// Global playback volume applied after mixing all remote streams. gain 0.0 = silent,
+    /// 1.0 = unity (default), >1.0 amplifies. Always LOCAL — no protocol traffic. Mirrors the
+    /// Windows client's `SetOutputVolume` and the C ABI `vc_set_output_volume` added in M5.
+    @discardableResult
+    public func setOutputVolume(_ gain: Float) -> VoiceCatResult {
+        VoiceCatResult(vc_set_output_volume(handle, gain < 0 ? 0 : gain))
+    }
+
     // MARK: - AVAudioSession interruption hooks (iOS)
 
     /// Pause miniaudio device I/O. Call when AVAudioSession interruption begins.

clients/apple/Tests/VoiceCatCoreTests/ExternalPcmTests.swift

@@ -61,7 +61,7 @@ final class ExternalPcmTests: XCTestCase {
             logLevel: .off
         ))
 
-        let mySink: vc_pcm_sink_cb = { _, _, _, _, _, _, _ in }
+        let mySink: VoiceCatPcmSinkCallback = { _, _, _, _, _, _, _ in }
         XCTAssertEqual(client.setPcmSink(mySink, user: nil), .ok)
         XCTAssertEqual(client.setPcmSink(nil, user: nil), .ok)
     }

clients/apple/macOS/VoiceCatMac.xcodeproj/project.pbxproj

@@ -27,6 +27,9 @@
 		AAAA00000000000000000041 /* VoiceCatCore in Frameworks */ = {isa = PBXBuildFile; productRef = AAAA00000000000000000027 /* VoiceCatCore */; };
 		AAAA00000000000000000042 /* Info.plist in Resources */ = {isa = PBXBuildFile; fileRef = AAAA00000000000000000013 /* Info.plist */; };
 		AAAA00000000000000000043 /* PttKeyCaptureSheet.swift in Sources */ = {isa = PBXBuildFile; fileRef = AAAA00000000000000000044 /* PttKeyCaptureSheet.swift */; };
+		AAAA00000000000000000046 /* PrivateMessageWindowController.swift in Sources */ = {isa = PBXBuildFile; fileRef = AAAA00000000000000000045 /* PrivateMessageWindowController.swift */; };
+		AAAA00000000000000000048 /* UserPickerSheet.swift in Sources */ = {isa = PBXBuildFile; fileRef = AAAA00000000000000000047 /* UserPickerSheet.swift */; };
+		AAAA0000000000000000004A /* SettingsWindowController.swift in Sources */ = {isa = PBXBuildFile; fileRef = AAAA00000000000000000049 /* SettingsWindowController.swift */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXFileReference section */
@@ -50,6 +53,9 @@
 		AAAA00000000000000000023 /* BanUserSheet.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BanUserSheet.swift; sourceTree = "<group>"; };
 		AAAA00000000000000000024 /* PermissionsSheet.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PermissionsSheet.swift; sourceTree = "<group>"; };
 		AAAA00000000000000000044 /* PttKeyCaptureSheet.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PttKeyCaptureSheet.swift; sourceTree = "<group>"; };
+		AAAA00000000000000000045 /* PrivateMessageWindowController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PrivateMessageWindowController.swift; sourceTree = "<group>"; };
+		AAAA00000000000000000047 /* UserPickerSheet.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = UserPickerSheet.swift; sourceTree = "<group>"; };
+		AAAA00000000000000000049 /* SettingsWindowController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SettingsWindowController.swift; sourceTree = "<group>"; };
 		AAAA00000000000000000025 /* Security.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Security.framework; path = System/Library/Frameworks/Security.framework; sourceTree = SDKROOT; };
 /* End PBXFileReference section */
 
@@ -103,6 +109,8 @@
 			children = (
 				AAAA00000000000000000019 /* ConnectWindowController.swift */,
 				AAAA0000000000000000001A /* MainWindowController.swift */,
+				AAAA00000000000000000045 /* PrivateMessageWindowController.swift */,
+				AAAA00000000000000000049 /* SettingsWindowController.swift */,
 			);
 			path = Windows;
 			sourceTree = "<group>";
@@ -121,6 +129,7 @@
 				AAAA00000000000000000023 /* BanUserSheet.swift */,
 				AAAA00000000000000000024 /* PermissionsSheet.swift */,
 				AAAA00000000000000000044 /* PttKeyCaptureSheet.swift */,
+				AAAA00000000000000000047 /* UserPickerSheet.swift */,
 			);
 			path = Sheets;
 			sourceTree = "<group>";
@@ -219,6 +228,9 @@
 				AAAA0000000000000000003E /* BanUserSheet.swift in Sources */,
 				AAAA0000000000000000003F /* PermissionsSheet.swift in Sources */,
 				AAAA00000000000000000043 /* PttKeyCaptureSheet.swift in Sources */,
+				AAAA00000000000000000046 /* PrivateMessageWindowController.swift in Sources */,
+				AAAA00000000000000000048 /* UserPickerSheet.swift in Sources */,
+				AAAA0000000000000000004A /* SettingsWindowController.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};

clients/apple/macOS/VoiceCatMac/Sheets/PttKeyCaptureSheet.swift

@@ -101,13 +101,3 @@ private final class KeyCaptureView: NSView {
     }
     override var focusRingMaskBounds: NSRect { bounds }
 }
-
-private func keyCodeName(_ keyCode: UInt16) -> String {
-    let map: [UInt16: String] = [
-        0x60: "F5", 0x61: "F6", 0x62: "F7", 0x63: "F3", 0x64: "F8", 0x65: "F9",
-        0x67: "F11", 0x69: "F13", 0x6A: "F16", 0x6B: "F14", 0x6D: "F10", 0x6F: "F12",
-        0x71: "F15", 0x72: "Help", 0x73: "Home", 0x74: "PgUp", 0x75: "Del",
-        0x76: "F4", 0x77: "End", 0x78: "F2", 0x79: "PgDn", 0x7A: "F1",
-    ]
-    return map[keyCode] ?? "Key\(keyCode)"
-}

clients/apple/macOS/VoiceCatMac/Sheets/UserPickerSheet.swift

@@ -0,0 +1,137 @@
+import AppKit
+import VoiceCatCore
+
+// UserPickerSheet — a modal sheet for picking one user from the list of all connected server
+// users. Used by the "Messages → New Private Message…" menu item so the user can start a PM
+// with anyone on the server, not just the current channel. Mirrors the Windows client's
+// `UserPickerDialog` (clients/windows/VoiceCat.App/Forms/UserPickerDialog.cs), adapted to the
+// Mac sheet pattern used by the rest of the macOS client (InputSheet, MoveUserSheet, etc.).
+
+final class UserPickerSheet: NSViewController, NSTableViewDataSource, NSTableViewDelegate {
+
+    /// Called with the selected user's ID, or `nil` if the user cancelled.
+    var onComplete: ((UInt32?) -> Void)?
+
+    private let users: [User]
+    private let tableView = NSTableView()
+    private var okButton: NSButton?
+    private var selectedRow: Int = -1
+
+    init(users: [User]) {
+        self.users = users
+        super.init(nibName: nil, bundle: nil)
+    }
+
+    required init?(coder: NSCoder) { fatalError() }
+
+    override func loadView() {
+        view = NSView(frame: NSRect(x: 0, y: 0, width: 300, height: 320))
+    }
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        buildUI()
+    }
+
+    // MARK: - UI
+
+    private func buildUI() {
+        let titleLabel = NSTextField(labelWithString: "Select a user:")
+        titleLabel.font = .boldSystemFont(ofSize: 13)
+        titleLabel.setAccessibilityLabel("Select a user")
+
+        let col = NSTableColumn(identifier: NSUserInterfaceItemIdentifier("user"))
+        tableView.addTableColumn(col)
+        tableView.headerView = nil
+        tableView.dataSource = self
+        tableView.delegate = self
+        tableView.doubleAction = #selector(okClicked)
+        tableView.target = self
+        tableView.setAccessibilityLabel("User list")
+
+        let scroll = NSScrollView()
+        scroll.documentView = tableView
+        scroll.hasVerticalScroller = true
+        scroll.borderType = .bezelBorder
+        scroll.translatesAutoresizingMaskIntoConstraints = false
+
+        let cancelButton = NSButton(title: "Cancel", target: self, action: #selector(cancelClicked))
+        cancelButton.bezelStyle = .rounded
+
+        let okButton = NSButton(title: "OK", target: self, action: #selector(okClicked))
+        okButton.bezelStyle = .rounded
+        okButton.keyEquivalent = "\r"
+        okButton.isEnabled = false
+        self.okButton = okButton
+
+        let buttonRow = NSStackView(views: [NSView(), cancelButton, okButton])
+        buttonRow.orientation = .horizontal
+        buttonRow.spacing = 8
+
+        let stack = NSStackView(views: [titleLabel, scroll, buttonRow])
+        stack.orientation = .vertical
+        stack.spacing = 8
+        stack.edgeInsets = NSEdgeInsets(top: 16, left: 16, bottom: 16, right: 16)
+        stack.translatesAutoresizingMaskIntoConstraints = false
+        view.addSubview(stack)
+        NSLayoutConstraint.activate([
+            stack.topAnchor.constraint(equalTo: view.topAnchor),
+            stack.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+            stack.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+            stack.bottomAnchor.constraint(equalTo: view.bottomAnchor),
+        ])
+    }
+
+    override func viewDidAppear() {
+        super.viewDidAppear()
+        if users.count == 1 {
+            tableView.selectRowIndexes(IndexSet(integer: 0), byExtendingSelection: false)
+        }
+    }
+
+    // MARK: - Actions
+
+    @objc private func okClicked() {
+        guard selectedRow >= 0, selectedRow < users.count else { return }
+        let userId = users[selectedRow].id
+        dismiss(nil)
+        onComplete?(userId)
+    }
+
+    @objc private func cancelClicked() {
+        dismiss(nil)
+        onComplete?(nil)
+    }
+
+    // MARK: - NSTableViewDataSource / Delegate
+
+    func numberOfRows(in tableView: NSTableView) -> Int { users.count }
+
+    func tableView(_ tableView: NSTableView, viewFor tableColumn: NSTableColumn?, row: Int) -> NSView? {
+        let id = NSUserInterfaceItemIdentifier("userCell")
+        let cell = tableView.makeView(withIdentifier: id, owner: nil) as? NSTableCellView
+                   ?? makeCellView(identifier: id)
+        cell.textField?.stringValue = users[row].nickname
+        return cell
+    }
+
+    func tableViewSelectionDidChange(_ notification: Notification) {
+        selectedRow = tableView.selectedRow
+        okButton?.isEnabled = selectedRow >= 0
+    }
+
+    private func makeCellView(identifier: NSUserInterfaceItemIdentifier) -> NSTableCellView {
+        let cell = NSTableCellView()
+        cell.identifier = identifier
+        let tf = NSTextField(labelWithString: "")
+        tf.translatesAutoresizingMaskIntoConstraints = false
+        cell.addSubview(tf)
+        cell.textField = tf
+        NSLayoutConstraint.activate([
+            tf.leadingAnchor.constraint(equalTo: cell.leadingAnchor, constant: 4),
+            tf.trailingAnchor.constraint(equalTo: cell.trailingAnchor, constant: -4),
+            tf.centerYAnchor.constraint(equalTo: cell.centerYAnchor),
+        ])
+        return cell
+    }
+}

clients/apple/macOS/VoiceCatMac/Windows/PrivateMessageWindowController.swift

@@ -0,0 +1,165 @@
+import AppKit
+import VoiceCatCore
+
+// PrivateMessageWindowController — a modeless window for a single private message
+// conversation, owned and routed-to by MainWindowController. Mirrors the Windows client's
+// `PrivateMessageForm` (clients/windows/VoiceCat.App/Forms/PrivateMessageForm.cs): each PM
+// conversation opens in its own window instead of sharing the main chat log via a scope
+// dropdown. MainWindowController routes incoming `.textMessage` events with `.private` scope
+// to the right window; outgoing PMs are echoed back by the server and arrive through the
+// same path (no optimistic local echo).
+//
+// The window is modeless (`NSWindow`) rather than a sheet because the user should be able to
+// keep chatting in the main channel while a PM window is open — the same Discord/Slack
+// pattern the Windows client follows.
+
+final class PrivateMessageWindowController: NSWindowController, NSWindowDelegate, NSTextViewDelegate {
+
+    // MARK: - Owned state
+
+    private let client: VoiceCatClient
+    let otherUserId: UInt32
+    private let selfUserId: UInt32
+    private let nickname: String
+
+    // MARK: - UI
+
+    private let historyTextView: NSTextView = {
+        let tv = NSTextView()
+        tv.isEditable = false
+        tv.isSelectable = true
+        tv.isAutomaticQuoteSubstitutionEnabled = false
+        tv.textContainerInset = NSSize(width: 4, height: 4)
+        return tv
+    }()
+
+    private let composeField = NSTextField()
+    private let sendButton = NSButton()
+
+    // MARK: - Init
+
+    init(client: VoiceCatClient, otherUserId: UInt32, nickname: String, selfUserId: UInt32) {
+        self.client = client
+        self.otherUserId = otherUserId
+        self.selfUserId = selfUserId
+        self.nickname = nickname
+
+        let window = NSWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 460, height: 360),
+            styleMask: [.titled, .closable, .miniaturizable, .resizable],
+            backing: .buffered,
+            defer: false
+        )
+        window.title = "Private Message — \(nickname)"
+        window.minSize = NSSize(width: 300, height: 220)
+        window.center()
+        super.init(window: window)
+        window.delegate = self
+
+        buildUI()
+    }
+
+    required init?(coder: NSCoder) { fatalError() }
+
+    // MARK: - UI construction
+
+    private func buildUI() {
+        guard let contentView = window?.contentView else { return }
+
+        historyTextView.setAccessibilityLabel("Private message history with \(nickname)")
+
+        let scroll = NSScrollView()
+        scroll.documentView = historyTextView
+        scroll.hasVerticalScroller = true
+        scroll.borderType = .noBorder
+        scroll.translatesAutoresizingMaskIntoConstraints = false
+        contentView.addSubview(scroll)
+
+        composeField.placeholderString = "Type a private message…"
+        composeField.setAccessibilityLabel("Private message to \(nickname)")
+        composeField.target = self
+        composeField.action = #selector(sendClicked)
+
+        sendButton.title = "Send"
+        sendButton.bezelStyle = .rounded
+        sendButton.target = self
+        sendButton.action = #selector(sendClicked)
+        sendButton.setAccessibilityLabel("Send private message")
+        sendButton.keyEquivalent = "\r"
+
+        let sep = NSBox()
+        sep.boxType = .separator
+        sep.translatesAutoresizingMaskIntoConstraints = false
+        contentView.addSubview(sep)
+
+        let composeBar = NSStackView(views: [composeField, sendButton])
+        composeBar.orientation = .horizontal
+        composeBar.spacing = 6
+        composeBar.translatesAutoresizingMaskIntoConstraints = false
+        contentView.addSubview(composeBar)
+
+        NSLayoutConstraint.activate([
+            scroll.topAnchor.constraint(equalTo: contentView.topAnchor),
+            scroll.leadingAnchor.constraint(equalTo: contentView.leadingAnchor),
+            scroll.trailingAnchor.constraint(equalTo: contentView.trailingAnchor),
+            scroll.bottomAnchor.constraint(equalTo: sep.topAnchor),
+
+            sep.leadingAnchor.constraint(equalTo: contentView.leadingAnchor),
+            sep.trailingAnchor.constraint(equalTo: contentView.trailingAnchor),
+            sep.heightAnchor.constraint(equalToConstant: 1),
+            sep.bottomAnchor.constraint(equalTo: composeBar.topAnchor),
+
+            composeBar.leadingAnchor.constraint(equalTo: contentView.leadingAnchor, constant: 8),
+            composeBar.trailingAnchor.constraint(equalTo: contentView.trailingAnchor, constant: -8),
+            composeBar.bottomAnchor.constraint(equalTo: contentView.bottomAnchor, constant: -8),
+            composeBar.heightAnchor.constraint(equalToConstant: 28),
+
+            sendButton.widthAnchor.constraint(equalToConstant: 70),
+        ])
+
+        window?.makeFirstResponder(composeField)
+    }
+
+    // MARK: - Public — called by MainWindowController
+
+    /// Append a message line. `isSelf=true` renders in gray (our own echoed outgoing message);
+    /// `false` renders in default color (incoming from the other user). Mirrors the Windows
+    /// `PrivateMessageForm.AppendMessage`.
+    func appendMessage(time: String, isSelf: Bool, sender: String, text: String) {
+        let line = "[\(time)] \(sender): \(text)\n"
+        let attrs: [NSAttributedString.Key: Any] = isSelf
+            ? [.foregroundColor: NSColor.secondaryLabelColor]
+            : [:]
+        let attributed = NSAttributedString(string: line, attributes: attrs)
+        historyTextView.textStorage?.append(attributed)
+        historyTextView.scrollToEndOfDocument(nil)
+    }
+
+    /// Append a gray status/activity line (e.g. the other user disconnected). Mirrors the
+    /// Windows `PrivateMessageForm.AppendActivity`.
+    func appendActivity(_ text: String) {
+        let time = DateFormatter.localizedString(from: Date(), dateStyle: .none, timeStyle: .short)
+        let line = "[\(time)] \(text)\n"
+        let attributed = NSAttributedString(string: line, attributes: [
+            .foregroundColor: NSColor.secondaryLabelColor,
+        ])
+        historyTextView.textStorage?.append(attributed)
+        historyTextView.scrollToEndOfDocument(nil)
+    }
+
+    // MARK: - Send
+
+    @objc private func sendClicked() {
+        let msg = composeField.stringValue.trimmingCharacters(in: .whitespaces)
+        guard !msg.isEmpty else { return }
+        client.sendText(scope: .private, targetId: otherUserId, text: msg)
+        composeField.stringValue = ""
+    }
+
+    // MARK: - NSWindowDelegate
+
+    func windowWillClose(_ notification: Notification) {
+        // Notify the owner so it can drop this controller from its pmWindows map.
+        // MainWindowController observes NSWindow.willCloseNotification on this window.
+    }
+}

clients/apple/macOS/VoiceCatMac/Windows/SettingsWindowController.swift

@@ -0,0 +1,297 @@
+import AppKit
+import VoiceCatCore
+
+// SettingsWindowController — a modeless window containing the audio input settings that used
+// to live in the main window's bottom voice panel: input mode (VAD/PTT/Always On), VAD
+// sensitivity, PTT key selection, input device picker, and the live microphone level meter.
+//
+// The main window is now just toolbar + channels + users + chat; audio settings live here
+// and are accessed via the app menu's "Settings…" item (⌘,). The window is modeless so the
+// user can keep it open while interacting with the main window — essential for watching the
+// level meter while adjusting VAD threshold or testing a device.
+//
+// Source-of-truth for the current settings lives in MainWindowController (so voice start can
+// apply them even before this window has been opened). This window reads from and writes back
+// to MainWindowController's stored properties, and applies changes to the client immediately
+// when voice is active.
+
+final class SettingsWindowController: NSWindowController, NSWindowDelegate {
+
+    // MARK: - References
+
+    private let client: VoiceCatClient
+    weak var mainController: MainWindowController?
+
+    // MARK: - UI
+
+    private let inputModeControl = NSSegmentedControl(labels: ["VAD", "PTT", "Always On"],
+                                                      trackingMode: .selectOne,
+                                                      target: nil, action: nil)
+    private let vadSlider: NSSlider = {
+        let s = NSSlider(value: 50, minValue: 1, maxValue: 100, target: nil, action: nil)
+        s.numberOfTickMarks = 0
+        return s
+    }()
+    private let vadLabel = NSTextField(labelWithString: "Sensitivity:")
+    private let pttKeyLabel = NSTextField(labelWithString: "(F8)")
+    private let changePttButton = NSButton()
+    private let devicePicker = NSPopUpButton()
+    private let refreshDevicesButton = NSButton()
+    private let levelMeter: NSProgressIndicator = {
+        let p = NSProgressIndicator()
+        p.style = .bar
+        p.isIndeterminate = false
+        p.minValue = 0
+        p.maxValue = 100
+        p.doubleValue = 0
+        return p
+    }()
+
+    // Cached VAD slider position so we can restore it when the window reopens.
+    private var vadSliderValue: Double = 50
+
+    // MARK: - Init
+
+    init(client: VoiceCatClient, mainController: MainWindowController) {
+        self.client = client
+        self.mainController = mainController
+
+        let window = NSWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 380, height: 260),
+            styleMask: [.titled, .closable, .miniaturizable],
+            backing: .buffered,
+            defer: false
+        )
+        window.title = "Audio Settings"
+        window.minSize = NSSize(width: 340, height: 220)
+        window.center()
+        super.init(window: window)
+        window.delegate = self
+
+        buildUI()
+        syncFromMainController()
+        loadInputDevices()
+    }
+
+    required init?(coder: NSCoder) { fatalError() }
+
+    // MARK: - UI construction
+
+    private func buildUI() {
+        guard let contentView = window?.contentView else { return }
+
+        let inputModeLabel = NSTextField(labelWithString: "Input mode:")
+        inputModeLabel.setAccessibilityLabel("Input mode")
+
+        inputModeControl.target = self
+        inputModeControl.action = #selector(inputModeChanged)
+        inputModeControl.selectedSegment = 0
+        inputModeControl.setAccessibilityLabel("Input mode: VAD, PTT, or Always On")
+
+        vadLabel.setAccessibilityLabel("VAD sensitivity")
+        vadSlider.target = self
+        vadSlider.action = #selector(vadSliderChanged)
+        vadSlider.setAccessibilityLabel("Voice activation sensitivity")
+        vadSlider.setAccessibilityHelp("Drag right for more sensitive, left for less")
+
+        pttKeyLabel.setAccessibilityLabel("Current PTT key")
+        changePttButton.title = "Change…"
+        changePttButton.bezelStyle = .rounded
+        changePttButton.target = self
+        changePttButton.action = #selector(changePttClicked)
+        changePttButton.setAccessibilityLabel("Change push-to-talk key")
+        pttKeyLabel.isHidden = true
+        changePttButton.isHidden = true
+
+        let deviceLabel = NSTextField(labelWithString: "Input device:")
+        deviceLabel.setAccessibilityLabel("Input device")
+        devicePicker.setAccessibilityLabel("Input audio device")
+        devicePicker.target = self
+        devicePicker.action = #selector(deviceChanged)
+        refreshDevicesButton.title = "↺"
+        refreshDevicesButton.bezelStyle = .rounded
+        refreshDevicesButton.target = self
+        refreshDevicesButton.action = #selector(refreshDevicesClicked)
+        refreshDevicesButton.setAccessibilityLabel("Refresh device list")
+        refreshDevicesButton.toolTip = "Refresh"
+
+        let levelLabel = NSTextField(labelWithString: "Level:")
+        levelLabel.setAccessibilityLabel("Microphone input level")
+        levelMeter.setAccessibilityLabel("Microphone input level")
+        levelMeter.setAccessibilityHelp("Shows current microphone volume level")
+
+        let inputModeRow = NSStackView(views: [inputModeLabel, inputModeControl])
+        inputModeRow.orientation = .horizontal
+        inputModeRow.spacing = 8
+
+        let vadRow = NSStackView(views: [vadLabel, vadSlider])
+        vadRow.orientation = .horizontal
+        vadRow.spacing = 8
+
+        let pttRow = NSStackView(views: [pttKeyLabel, changePttButton])
+        pttRow.orientation = .horizontal
+        pttRow.spacing = 8
+
+        let deviceRow = NSStackView(views: [deviceLabel, devicePicker, refreshDevicesButton])
+        deviceRow.orientation = .horizontal
+        deviceRow.spacing = 8
+
+        let levelRow = NSStackView(views: [levelLabel, levelMeter])
+        levelRow.orientation = .horizontal
+        levelRow.spacing = 8
+
+        let stack = NSStackView(views: [inputModeRow, vadRow, pttRow, deviceRow, levelRow])
+        stack.orientation = .vertical
+        stack.spacing = 12
+        stack.alignment = .leading
+        stack.edgeInsets = NSEdgeInsets(top: 20, left: 20, bottom: 20, right: 20)
+        stack.translatesAutoresizingMaskIntoConstraints = false
+        contentView.addSubview(stack)
+
+        NSLayoutConstraint.activate([
+            stack.topAnchor.constraint(equalTo: contentView.topAnchor),
+            stack.leadingAnchor.constraint(equalTo: contentView.leadingAnchor),
+            stack.trailingAnchor.constraint(equalTo: contentView.trailingAnchor),
+            stack.bottomAnchor.constraint(equalTo: contentView.bottomAnchor),
+
+            vadSlider.widthAnchor.constraint(greaterThanOrEqualToConstant: 200),
+            levelMeter.widthAnchor.constraint(equalToConstant: 200),
+            devicePicker.widthAnchor.constraint(greaterThanOrEqualToConstant: 180),
+        ])
+    }
+
+    // MARK: - Sync from MainWindowController
+
+    /// Read the current settings from MainWindowController and update our UI to match.
+    /// Called on init and whenever the window is re-shown.
+    private func syncFromMainController() {
+        guard let mc = mainController else { return }
+
+        switch mc.selectedInputMode {
+        case .voiceActivation: inputModeControl.selectedSegment = 0
+        case .pushToTalk:      inputModeControl.selectedSegment = 1
+        case .alwaysOn:        inputModeControl.selectedSegment = 2
+        }
+
+        vadSlider.doubleValue = vadSliderValue
+        pttKeyLabel.stringValue = "(\(keyCodeName(mc.pttKeyCode)))"
+
+        updateConditionalControls()
+    }
+
+    /// Show/hide VAD and PTT controls based on the selected input mode.
+    private func updateConditionalControls() {
+        let seg = inputModeControl.selectedSegment
+        vadLabel.isHidden = seg != 0
+        vadSlider.isHidden = seg != 0
+        pttKeyLabel.isHidden = seg != 1
+        changePttButton.isHidden = seg != 1
+    }
+
+    // MARK: - Actions
+
+    @objc private func inputModeChanged() {
+        updateConditionalControls()
+        let mode = currentInputMode()
+        mainController?.selectedInputMode = mode
+        if let mc = mainController, mc.micStreamId != 0 {
+            client.setInputMode(mode)
+            if mode == .voiceActivation {
+                client.setVadThreshold(vadThresholdFromSlider())
+            } else if mode == .pushToTalk {
+                client.setPushToTalk(false)
+            }
+        }
+    }
+
+    @objc private func vadSliderChanged() {
+        vadSliderValue = vadSlider.doubleValue
+        let threshold = vadThresholdFromSlider()
+        mainController?.vadThresholdValue = threshold
+        if let mc = mainController, mc.micStreamId != 0, mc.selectedInputMode == .voiceActivation {
+            client.setVadThreshold(threshold)
+        }
+    }
+
+    @objc private func changePttClicked() {
+        guard let mc = mainController else { return }
+        let sheet = PttKeyCaptureSheet(currentKeyCode: mc.pttKeyCode)
+        sheet.onComplete = { [weak self] keyCode in
+            guard let self, let keyCode else { return }
+            self.mainController?.pttKeyCode = keyCode
+            self.pttKeyLabel.stringValue = "(\(keyCodeName(keyCode)))"
+        }
+        presentSheet(sheet)
+    }
+
+    @objc private func refreshDevicesClicked() { loadInputDevices() }
+
+    @objc private func deviceChanged() {
+        let devId = devicePicker.selectedItem?.representedObject as? String
+        mainController?.selectedInputDeviceId = devId
+        if let mc = mainController, mc.micStreamId != 0, let devId {
+            client.setInputDevice(streamId: mc.micStreamId, deviceId: devId)
+        }
+    }
+
+    // MARK: - Level meter (called by MainWindowController)
+
+    func updateLevel(rms: Float) {
+        levelMeter.doubleValue = min(100, Double(rms * 400))
+        levelMeter.setAccessibilityValue("\(Int(levelMeter.doubleValue)) percent")
+    }
+
+    func resetLevel() {
+        levelMeter.doubleValue = 0
+    }
+
+    // MARK: - Device enumeration
+
+    private func loadInputDevices() {
+        let devices = client.listDevices(.input)
+        let prevSelected = devicePicker.selectedItem?.representedObject as? String
+        devicePicker.removeAllItems()
+        for d in devices {
+            let item = NSMenuItem(title: d.name, action: nil, keyEquivalent: "")
+            item.representedObject = d.id
+            devicePicker.menu?.addItem(item)
+        }
+        // Restore previous selection, or pick default, or first
+        if let prev = prevSelected,
+           let item = devicePicker.itemArray.first(where: { ($0.representedObject as? String) == prev }) {
+            devicePicker.select(item)
+        } else if let def = devices.first(where: { $0.isDefault }) {
+            devicePicker.select(devicePicker.item(withTitle: def.name))
+        } else if devicePicker.numberOfItems > 0 {
+            devicePicker.selectItem(at: 0)
+        }
+        // Sync the selected device back to main controller
+        let devId = devicePicker.selectedItem?.representedObject as? String
+        mainController?.selectedInputDeviceId = devId
+    }
+
+    // MARK: - Helpers
+
+    private func currentInputMode() -> VoiceCatInputMode {
+        switch inputModeControl.selectedSegment {
+        case 1:  return .pushToTalk
+        case 2:  return .alwaysOn
+        default: return .voiceActivation
+        }
+    }
+
+    private func vadThresholdFromSlider() -> Float {
+        0.1 * (1.0 - Float(vadSlider.doubleValue - 1.0) / 99.0)
+    }
+
+    private func presentSheet(_ vc: NSViewController) {
+        if let cvc = window?.contentViewController {
+            cvc.presentAsSheet(vc)
+        } else {
+            let cvc = NSViewController()
+            cvc.view = window!.contentView!
+            window?.contentViewController = cvc
+            cvc.presentAsSheet(vc)
+        }
+    }
+}