✨ Harden Swift SDK package

Split XCTest helpers into their own product so native app targets can depend on the core client without test APIs. Align Swift screenshot payloads with the server comparison contract and document the SPM integration path.

Author: Robdel12

clients/swift/Example/ExampleUITests.swift

@@ -1,5 +1,6 @@
 import XCTest
 import Vizzly
+import VizzlyXCTest
 
 /// Example UI tests demonstrating Vizzly integration
 ///
@@ -133,15 +134,13 @@ final class ExampleUITests: XCTestCase {
     func testResponsiveLayout() throws {
         // Test different device orientations
         XCUIDevice.shared.orientation = .portrait
-        sleep(1) // Wait for orientation change
 
         app.vizzlyScreenshot(
             name: "home-portrait",
             properties: ["orientation": "portrait"]
         )
 
         XCUIDevice.shared.orientation = .landscapeLeft
-        sleep(1)
 
         app.vizzlyScreenshot(
             name: "home-landscape",
@@ -187,7 +186,7 @@ final class ExampleUITests: XCTestCase {
     // MARK: - Custom Threshold Example
 
     func testWithCustomThreshold() throws {
-        // Allow up to 5% pixel difference
+        // Allow a higher comparison threshold for animated content
         app.vizzlyScreenshot(
             name: "animation-test",
             threshold: 5,

clients/swift/INTEGRATION.md

@@ -21,7 +21,10 @@ In Xcode:
 1. **File → Add Package Dependencies**
 2. Enter URL: `https://github.com/vizzly-testing/cli`
 3. Select version/branch
-4. **Important**: Add the package to your **UI Test target** (not the main app target)
+4. Add the `VizzlyXCTest` product to your **UI Test target**
+
+Use the core `Vizzly` product directly only when you need to send PNG data from
+app or test-support code without the XCTest convenience extensions.
 
 #### Option B: Local Package
 
@@ -78,6 +81,7 @@ Create or update your UI test file:
 ```swift
 import XCTest
 import Vizzly
+import VizzlyXCTest
 
 final class MyAppUITests: XCTestCase {
 
@@ -265,13 +269,13 @@ For views with animations or timing-sensitive content:
 func testAnimatedView() {
     app.launch()
 
-    // Wait for animation to complete
-    sleep(1) // Or use expectations
+    let finishedState = app.otherElements["AnimatedBannerReady"]
+    XCTAssertTrue(finishedState.waitForExistence(timeout: 5))
 
     // Use threshold for slight variations
     app.vizzlyScreenshot(
         name: "animated-banner",
-        threshold: 5  // Allow 5% difference
+        threshold: 5
     )
 }
 ```

clients/swift/Package.swift

@@ -13,13 +13,19 @@ let package = Package(
         .library(
             name: "Vizzly",
             targets: ["Vizzly"]),
+        .library(
+            name: "VizzlyXCTest",
+            targets: ["VizzlyXCTest"]),
     ],
     targets: [
         .target(
             name: "Vizzly",
             dependencies: []),
+        .target(
+            name: "VizzlyXCTest",
+            dependencies: ["Vizzly"]),
         .testTarget(
             name: "VizzlyTests",
-            dependencies: ["Vizzly"]),
+            dependencies: ["Vizzly", "VizzlyXCTest"]),
     ]
 )

clients/swift/QUICKSTART.md

@@ -13,7 +13,7 @@ npm install -g @vizzly-testing/cli
 1. Open your iOS project in Xcode
 2. **File → Add Package Dependencies**
 3. Paste: `https://github.com/vizzly-testing/cli`
-4. Add to your **UI Test target** (not main app)
+4. Add the `VizzlyXCTest` product to your **UI Test target**
 
 ## 3. Start TDD Server
 
@@ -28,6 +28,7 @@ vizzly tdd start
 ```swift
 import XCTest
 import Vizzly
+import VizzlyXCTest
 
 class MyAppUITests: XCTestCase {
     let app = XCUIApplication()
@@ -96,7 +97,7 @@ button.vizzlyScreenshot(name: "submit-button")
 ### Custom Threshold
 
 ```swift
-// Allow 5% pixel difference (useful for animations)
+// Allow a higher comparison threshold for animated content
 app.vizzlyScreenshot(
     name: "animated-view",
     threshold: 5

clients/swift/README.md

@@ -7,7 +7,7 @@ Unlike tools that render components in isolation, Vizzly captures screenshots di
 ## Features
 
 - **Zero Configuration** - Auto-discovers Vizzly TDD server
-- **Native XCTest Integration** - Simple extensions for `XCUIApplication` and `XCUIElement`
+- **Native XCTest Integration** - Simple extensions for `XCUIApplication` and `XCUIElement` via the `VizzlyXCTest` helper product
 - **iOS & macOS Support** - Works on both platforms
 - **Automatic Metadata** - Captures device, screen size, and platform info
 - **TDD Mode** - Local visual testing with instant feedback
@@ -22,21 +22,29 @@ Add Vizzly to your test target using Xcode:
 
 1. File → Add Package Dependencies
 2. Enter repository URL: `https://github.com/vizzly-testing/cli`
-3. Select version and add to your UI test target
+3. Select version and add the `VizzlyXCTest` product to your UI test target
+
+The core `Vizzly` product has no XCTest dependency and can also be used from
+native app or test-support code when you want to send PNG data directly.
 
 Or add to your `Package.swift`:
 
 ```swift
 dependencies: [
     .package(url: "https://github.com/vizzly-testing/cli", from: "1.0.0")
+],
+targets: [
+    .testTarget(
+        name: "MyAppUITests",
+        dependencies: [
+            .product(name: "VizzlyXCTest", package: "cli")
+        ]
+    )
 ]
 ```
 
-### CocoaPods
-
-```ruby
-pod 'Vizzly', :git => 'https://github.com/vizzly-testing/cli', :branch => 'main'
-```
+Vizzly does not currently ship a CocoaPods podspec. Use Swift Package Manager
+for native app integration.
 
 ## Quick Start
 
@@ -54,6 +62,7 @@ This starts a local server at `http://localhost:47392` that receives screenshots
 ```swift
 import XCTest
 import Vizzly
+import VizzlyXCTest
 
 class MyUITests: XCTestCase {
     let app = XCUIApplication()
@@ -128,14 +137,17 @@ func testNavigationBar() {
 
 ```swift
 func testAnimatedContent() {
-    // Allow up to 5% pixel difference (useful for animations)
+    // Allow a higher comparison threshold for animated content
     app.vizzlyScreenshot(
         name: "animated-banner",
         threshold: 5
     )
 }
 ```
 
+If `threshold` or `minClusterSize` is omitted, the server's configured
+comparison settings are used.
+
 ### Multiple Device Orientations
 
 ```swift
@@ -187,7 +199,8 @@ extension XCUIApplication {
     func vizzlyScreenshot(
         name: String,
         properties: [String: Any]? = nil,
-        threshold: Int = 0,
+        threshold: Double? = nil,
+        minClusterSize: Int? = nil,
         fullPage: Bool = false
     ) -> [String: Any]?
 }
@@ -200,7 +213,8 @@ extension XCUIElement {
     func vizzlyScreenshot(
         name: String,
         properties: [String: Any]? = nil,
-        threshold: Int = 0
+        threshold: Double? = nil,
+        minClusterSize: Int? = nil
     ) -> [String: Any]?
 }
 ```
@@ -213,15 +227,17 @@ extension XCTestCase {
         name: String,
         app: XCUIApplication,
         properties: [String: Any]? = nil,
-        threshold: Int = 0,
+        threshold: Double? = nil,
+        minClusterSize: Int? = nil,
         fullPage: Bool = false
     ) -> [String: Any]?
 
     func vizzlyScreenshot(
         name: String,
         element: XCUIElement,
         properties: [String: Any]? = nil,
-        threshold: Int = 0
+        threshold: Double? = nil,
+        minClusterSize: Int? = nil
     ) -> [String: Any]?
 }
 ```
@@ -236,7 +252,8 @@ class VizzlyClient {
         name: String,
         image: Data,
         properties: [String: Any]? = nil,
-        threshold: Int = 0,
+        threshold: Double? = nil,
+        minClusterSize: Int? = nil,
         fullPage: Bool = false
     ) -> [String: Any]?
 
@@ -254,8 +271,9 @@ class VizzlyClient {
 The SDK automatically discovers a running Vizzly TDD server using this priority order:
 
 1. **VIZZLY_SERVER_URL environment variable** - Explicitly set server URL
-2. **Global server file** - `~/.vizzly/server.json` written by CLI
-3. **Default port health check** - Tests `http://localhost:47392/health`
+2. **Project server file** - `.vizzly/server.json` in the current directory
+3. **Global server file** - `~/.vizzly/server.json` written by CLI
+4. **Default port health check** - Tests `http://localhost:47392/health`
 
 When you run `vizzly tdd start`, the CLI automatically writes server info to `~/.vizzly/server.json` in your home directory, enabling zero-config discovery from iOS tests.