Fix bugs, reduce duplication, and improve robustness (#66)

* Fix bugs, reduce duplication, and improve robustness across codebase

Bugs fixed:
- Fix double IOSurfaceUnlock in SimulatorBridge when CIImage creation fails
- Replace non-deterministic hashValue with stable FNV-1a hash in PreviewSession module naming
- Fix exception safety in HostApp.loadPreview() — validate new loader before retiring old one

Duplication reduced:
- Extract MCP parameter helpers (extractString/Int/Double/Bool and optional variants)
- Consolidate trait validation into PreviewTraits.validated() factory method
- Define iOS target triple as PreviewPlatform.targetTriple constant
- Replace magic tool name strings with ToolName enum in MCPServer

Robustness improvements:
- Use null-byte indexed placeholders in LiteralDiffer to prevent source collisions
- Validate all paths in FileWatcher init, not just the first
- Add LocalizedError conformance to DylibLoaderError and FileWatcherError

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

* Address review feedback: error messages, coercion, tests, and cleanup

- Add ParamError.wrongType to distinguish missing vs wrong-type params
- Handle double→int coercion in extractInt/extractOptionalInt
- Fix iOS host app exception safety: set currentDylibHandle after dlsym
- Nest TraitValidationError as PreviewTraits.ValidationError
- Add tests for PreviewTraits.validated() (4 cases)
- Add determinism tests for stableHash (known-value pin)
- Remove unused CaseIterable on ToolName
- Add null-byte rationale comment in LiteralDiffer
- Fix inaccurate doc comment on parseTraits

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: obj-p

Sources/PreviewsCLI/MCPServer.swift

@@ -45,14 +45,10 @@ struct RunCommand: ParsableCommand {
             throw ValidationError("File not found: \(file)")
         }
 
-        if let cs = colorScheme, !PreviewTraits.validColorSchemes.contains(cs) {
-            throw ValidationError(
-                "Invalid color scheme '\(cs)'. Must be 'light' or 'dark'.")
-        }
-        if let dts = dynamicTypeSize, !PreviewTraits.validDynamicTypeSizes.contains(dts) {
-            throw ValidationError(
-                "Invalid dynamic type size '\(dts)'. Valid values: \(PreviewTraits.validDynamicTypeSizes.sorted().joined(separator: ", "))"
-            )
+        do {
+            _ = try PreviewTraits.validated(colorScheme: colorScheme, dynamicTypeSize: dynamicTypeSize)
+        } catch {
+            throw ValidationError(error.localizedDescription)
         }
 
         switch platform {

Sources/PreviewsCLI/RunCommand.swift

@@ -47,14 +47,10 @@ struct SnapshotCommand: ParsableCommand {
             throw ValidationError("File not found: \(file)")
         }
 
-        if let cs = colorScheme, !PreviewTraits.validColorSchemes.contains(cs) {
-            throw ValidationError(
-                "Invalid color scheme '\(cs)'. Must be 'light' or 'dark'.")
-        }
-        if let dts = dynamicTypeSize, !PreviewTraits.validDynamicTypeSizes.contains(dts) {
-            throw ValidationError(
-                "Invalid dynamic type size '\(dts)'. Valid values: \(PreviewTraits.validDynamicTypeSizes.sorted().joined(separator: ", "))"
-            )
+        do {
+            _ = try PreviewTraits.validated(colorScheme: colorScheme, dynamicTypeSize: dynamicTypeSize)
+        } catch {
+            throw ValidationError(error.localizedDescription)
         }
 
         switch platform {

Sources/PreviewsCLI/SnapshotCommand.swift

@@ -51,11 +51,10 @@ public actor Compiler {
         switch platform {
         case .macOS:
             self.sdkPath = try await Self.resolve("xcrun", "--show-sdk-path")
-            self.targetTriple = "arm64-apple-macosx14.0"
         case .iOS:
             self.sdkPath = try await Self.resolve("xcrun", "--show-sdk-path", "--sdk", "iphonesimulator")
-            self.targetTriple = "arm64-apple-ios17.0-simulator"
         }
+        self.targetTriple = platform.targetTriple
         self.swiftcPath = try await Self.resolve("xcrun", "--find", "swiftc")
         self.codesignPath = try await Self.resolve("xcrun", "--find", "codesign")
     }

Sources/PreviewsCore/Compiler.swift

@@ -29,7 +29,7 @@ public final class DylibLoader: @unchecked Sendable {
     // Closing a dylib while its types are in use causes crashes.
 }
 
-public enum DylibLoaderError: Error, CustomStringConvertible {
+public enum DylibLoaderError: Error, LocalizedError, CustomStringConvertible {
     case loadFailed(path: String, reason: String)
     case symbolNotFound(name: String, reason: String)
 
@@ -41,4 +41,6 @@ public enum DylibLoaderError: Error, CustomStringConvertible {
             return "Symbol '\(name)' not found: \(reason)"
         }
     }
+
+    public var errorDescription: String? { description }
 }

Sources/PreviewsCore/DylibLoader.swift

@@ -26,8 +26,13 @@ public final class FileWatcher: @unchecked Sendable {
         interval: TimeInterval = 0.5,
         callback: @escaping @Sendable () -> Void
     ) throws {
-        guard let first = paths.first, FileManager.default.fileExists(atPath: first) else {
-            throw FileWatcherError.cannotOpen(path: paths.first ?? "<empty>")
+        guard !paths.isEmpty else {
+            throw FileWatcherError.cannotOpen(path: "<empty>")
+        }
+        for path in paths {
+            guard FileManager.default.fileExists(atPath: path) else {
+                throw FileWatcherError.cannotOpen(path: path)
+            }
         }
 
         self.filePaths = paths
@@ -77,7 +82,7 @@ public final class FileWatcher: @unchecked Sendable {
     }
 }
 
-public enum FileWatcherError: Error, CustomStringConvertible {
+public enum FileWatcherError: Error, LocalizedError, CustomStringConvertible {
     case cannotOpen(path: String)
 
     public var description: String {
@@ -86,4 +91,6 @@ public enum FileWatcherError: Error, CustomStringConvertible {
             return "Cannot watch file: \(path)"
         }
     }
+
+    public var errorDescription: String? { description }
 }

Sources/PreviewsCore/FileWatcher.swift

@@ -48,9 +48,10 @@ public enum LiteralDiffer {
 
     private static func buildSkeleton(source: String, literals: [RawLiteralEntry]) -> String {
         var utf8 = Array(source.utf8)
-        let placeholder = Array("__LIT__".utf8)
-        // Replace from back to front
-        for entry in literals.reversed() {
+        // Replace from back to front with null-byte-delimited indexed placeholders.
+        // Null bytes cannot appear in valid Swift source, so these won't collide.
+        for (index, entry) in literals.enumerated().reversed() {
+            let placeholder = Array("\0LIT_\(index)\0".utf8)
             utf8.replaceSubrange(entry.utf8Start..<entry.utf8End, with: placeholder)
         }
         return String(decoding: utf8, as: UTF8.self)

Sources/PreviewsCore/LiteralDiffer.swift

@@ -2,4 +2,12 @@
 public enum PreviewPlatform: String, Sendable {
     case macOS
     case iOS
+
+    /// The compiler target triple for this platform.
+    public var targetTriple: String {
+        switch self {
+        case .macOS: return "arm64-apple-macosx14.0"
+        case .iOS: return "arm64-apple-ios17.0-simulator"
+        }
+    }
 }

Sources/PreviewsCore/Platform.swift

@@ -173,9 +173,19 @@ public actor PreviewSession {
 
     private static func moduleName(for file: URL) -> String {
         let stem = file.deletingPathExtension().lastPathComponent
-        let hash = String(abs(file.path.hashValue), radix: 16).prefix(6)
+        let hash = String(stableHash(file.path), radix: 16).prefix(6)
         return "Preview_\(stem)_\(hash)"
     }
+
+    /// FNV-1a hash producing a stable, deterministic value across processes.
+    static func stableHash(_ string: String) -> UInt64 {
+        var hash: UInt64 = 0xcbf2_9ce4_8422_2325  // FNV offset basis
+        for byte in string.utf8 {
+            hash ^= UInt64(byte)
+            hash &*= 0x0000_0100_0000_01B3  // FNV prime
+        }
+        return hash
+    }
 }
 
 public enum PreviewSessionError: Error, LocalizedError, CustomStringConvertible {

Sources/PreviewsCore/PreviewSession.swift

@@ -29,4 +29,33 @@ public struct PreviewTraits: Sendable, Equatable {
         "accessibility1", "accessibility2", "accessibility3",
         "accessibility4", "accessibility5",
     ]
+
+    /// Validate optional trait values and return a PreviewTraits, or throw on invalid input.
+    public static func validated(
+        colorScheme: String?,
+        dynamicTypeSize: String?
+    ) throws -> PreviewTraits {
+        if let cs = colorScheme, !validColorSchemes.contains(cs) {
+            throw ValidationError.invalidColorScheme(cs)
+        }
+        if let dts = dynamicTypeSize, !validDynamicTypeSizes.contains(dts) {
+            throw ValidationError.invalidDynamicTypeSize(dts)
+        }
+        return PreviewTraits(colorScheme: colorScheme, dynamicTypeSize: dynamicTypeSize)
+    }
+
+    public enum ValidationError: Error, LocalizedError {
+        case invalidColorScheme(String)
+        case invalidDynamicTypeSize(String)
+
+        public var errorDescription: String? {
+            switch self {
+            case .invalidColorScheme(let cs):
+                return "Invalid color scheme '\(cs)'. Must be 'light' or 'dark'."
+            case .invalidDynamicTypeSize(let dts):
+                return
+                    "Invalid dynamic type size '\(dts)'. Valid values: \(PreviewTraits.validDynamicTypeSizes.sorted().joined(separator: ", "))"
+            }
+        }
+    }
 }