Docs: voice overlay plan and fix web mocks

apps/macos/Sources/Clawdis/VoiceWakeChime.swift

@@ -28,19 +28,71 @@ enum VoiceWakeChime: Codable, Equatable, Sendable {
 
 struct VoiceWakeChimeCatalog {
     /// Options shown in the picker.
-    static let systemOptions: [String] = [
-        "Glass", // default
-        "Ping",
-        "Pop",
-        "Frog",
-        "Submarine",
-        "Funk",
-        "Tink",
-    ]
+    static let systemOptions: [String] = {
+        let discovered = Self.discoveredSoundMap.keys
+        let fallback: [String] = [
+            "Glass", // default
+            "Ping",
+            "Pop",
+            "Frog",
+            "Submarine",
+            "Funk",
+            "Tink",
+            "Basso",
+            "Blow",
+            "Bottle",
+            "Hero",
+            "Morse",
+            "Purr",
+            "Sosumi",
+            "Mail Sent",
+        ]
+
+        // Keep Glass first, then present the rest alphabetically without duplicates.
+        var names = Set(discovered).union(fallback)
+        names.remove("Glass")
+        let sorted = names.sorted { $0.localizedCaseInsensitiveCompare($1) == .orderedAscending }
+        return ["Glass"] + sorted
+    }()
 
     static func displayName(for raw: String) -> String {
         return raw
     }
+
+    static func url(for name: String) -> URL? {
+        return self.discoveredSoundMap[name]
+    }
+
+    private static let allowedExtensions: Set<String> = [
+        "aif", "aiff", "caf", "wav", "m4a", "mp3",
+    ]
+
+    private static let searchRoots: [URL] = [
+        FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent("Library/Sounds"),
+        URL(fileURLWithPath: "/Library/Sounds"),
+        URL(fileURLWithPath: "/System/Applications/Mail.app/Contents/Resources"), // Mail “swoosh”
+        URL(fileURLWithPath: "/System/Library/Sounds"),
+    ]
+
+    private static let discoveredSoundMap: [String: URL] = {
+        var map: [String: URL] = [:]
+        for root in self.searchRoots {
+            guard let contents = try? FileManager.default.contentsOfDirectory(
+                at: root,
+                includingPropertiesForKeys: nil,
+                options: [.skipsHiddenFiles])
+            else { continue }
+
+            for url in contents where self.allowedExtensions.contains(url.pathExtension.lowercased()) {
+                let name = url.deletingPathExtension().lastPathComponent
+                // Preserve the first match in priority order.
+                if map[name] == nil {
+                    map[name] = url
+                }
+            }
+        }
+        return map
+    }()
 }
 
 @MainActor
@@ -62,7 +114,13 @@ enum VoiceWakeChimePlayer {
         case .none:
             return nil
         case let .system(name):
-            return NSSound(named: NSSound.Name(name))
+            if let named = NSSound(named: NSSound.Name(name)) {
+                return named
+            }
+            if let url = VoiceWakeChimeCatalog.url(for: name) {
+                return NSSound(contentsOf: url, byReference: false)
+            }
+            return nil
 
         case let .custom(_, bookmark):
             var stale = false