Add snapshot canvas theme sidecar support (#273)

Adds support for a new metadata property, `canvas_theme` that can be associated with a snapshot image. When set, the value is respected by the Sentry web UI and renders the image background according to the `light` or `dark` value specified. Expose a view modifier and preference that allows clients to control this value, analogous to the way other image metadata is specified.

Refs: EME-1225

Author: jamieQ

README.md

@@ -152,6 +152,7 @@ Each `.json` sidecar contains the following fields:
 | `group` | Grouping key Sentry uses to organize related snapshots. Generated from the preview name, file path, and module by default. |
 | `diff_threshold` | Allowed visual difference for this snapshot. See details below. |
 | `tags` | Optional key-value pairs used to filter and group snapshots in Sentry. |
+| `canvas_theme` | Optional `"light"` or `"dark"` value that controls the background canvas used to display the snapshot image in Sentry's web UI. |
 | `context` | Supporting metadata such as test name, simulator info, orientation, color scheme, source line, preview attributes, and any custom context you add. These fields are surfaced on the snapshot detail page in Sentry's UI. |
 
 SnapshotPreviews adds these `context` keys by default when values are available: `test_name`, `accessibility_enabled`, `simulator.device_name`, `simulator.model_identifier`, `preview.index`, `preview.display_name`, `preview.container_type_name`, `preview.container_display_name`, `preview.preferred_color_scheme`, `preview.orientation`, and `preview.line`.
@@ -162,6 +163,8 @@ Use `.snapshotGroup(...)` to override the default `group` behaviour in the Sentr
 
 Use the `.snapshotDiffThreshold(...)` view modifier from the `SnapshotPreferences` product to customize the allowed visual difference for a specific preview. For example, `.snapshotDiffThreshold(0.05)` allows up to a 5% difference for that snapshot.
 
+Use `.snapshotCanvasTheme(...)` to set the light or dark canvas used behind the image in Sentry's web UI. This is display metadata only; it does not change the rendered snapshot image.
+
 ```swift
 import SnapshotPreferences
 
@@ -171,6 +174,7 @@ import SnapshotPreferences
     .snapshotAdditionalContext(["fixture": "city-route"])
     .snapshotGroup("Navigation")
     .snapshotDiffThreshold(0.05)
+    .snapshotCanvasTheme(.dark)
 }
 ```
 
@@ -223,6 +227,7 @@ Link the `SnapshotPreferences` product to your app target to customize individua
 | `.snapshotAdditionalContext(["fixture": "loaded"])` | You want extra sidecar metadata for debugging or filtering. | Adds fields to the JSON sidecar `context` object. Repeated context modifiers merge, and later duplicate keys win. Custom keys override generated context keys. |
 | `.snapshotGroup("Checkout")` | You want to control how related snapshots are grouped in Sentry. | Overrides the top-level `group` in the JSON sidecar. Also accepts `.snapshotGroup(.module)` to group by the preview container's module name, and `.snapshotGroup(.default)` to keep the generated group. Empty or whitespace-only custom strings fall back to the generated group. Does not change exported filenames or all-image-names manifest output. |
 | `.snapshotDiffThreshold(0.05)` | A snapshot has small expected pixel differences. | Sets `diff_threshold` in the exported sidecar for this preview. `0.05` allows up to a 5% changed-pixel share before Sentry marks the image as changed. |
+| `.snapshotCanvasTheme(.dark)` | A transparent or framed image should be shown on a specific light/dark canvas in Sentry. | Sets top-level `canvas_theme` to `"light"` or `"dark"` in the JSON sidecar. Does not change the rendered snapshot image. |
 
 ### Variants
 

Sources/SnapshotPreferences/EmergeModifierFinder.swift

@@ -28,6 +28,7 @@ class EmergeModifierState: NSObject {
     tags = [:]
     additionalContext = [:]
     groupOverride = nil
+    canvasTheme = nil
   }
 
   var expansionPreference: Bool?
@@ -38,6 +39,7 @@ class EmergeModifierState: NSObject {
   var tags: [String: String] = [:]
   var additionalContext: [String: SnapshotMetadataValue] = [:]
   var groupOverride: SnapshotGroup?
+  var canvasTheme: SnapshotCanvasTheme?
 }
 
 @objc(EmergeModifierFinder)
@@ -69,5 +71,8 @@ class EmergeModifierFinder: NSObject {
       .onPreferenceChange(SnapshotGroupPreferenceKey.self, perform: { value in
         EmergeModifierState.shared.groupOverride = value
       })
+      .onPreferenceChange(SnapshotCanvasThemePreferenceKey.self, perform: { value in
+        EmergeModifierState.shared.canvasTheme = value
+      })
   }
 }

Sources/SnapshotPreferences/SnapshotMetadataPreference.swift

@@ -33,6 +33,14 @@ struct SnapshotAdditionalContextPreferenceKey: PreferenceKey {
   }
 }
 
+struct SnapshotCanvasThemePreferenceKey: PreferenceKey {
+  static var defaultValue: SnapshotCanvasTheme? = nil
+
+  static func reduce(value: inout SnapshotCanvasTheme?, nextValue: () -> SnapshotCanvasTheme?) {
+    value = nextValue() ?? value
+  }
+}
+
 extension View {
   /// Adds tags to the exported snapshot sidecar.
   ///
@@ -71,4 +79,12 @@ extension View {
   public func snapshotGroup(_ group: SnapshotGroup) -> some View {
     preference(key: SnapshotGroupPreferenceKey.self, value: group)
   }
+
+  /// Sets the top-level `canvas_theme` field in the exported snapshot sidecar.
+  ///
+  /// This controls the light or dark canvas used when displaying the snapshot image in
+  /// Sentry's web UI. It does not change the rendered snapshot image itself.
+  public func snapshotCanvasTheme(_ canvasTheme: SnapshotCanvasTheme) -> some View {
+    preference(key: SnapshotCanvasThemePreferenceKey.self, value: canvasTheme)
+  }
 }

Sources/SnapshotPreviewsCore/AppKitRenderingStrategy.swift

@@ -47,7 +47,7 @@ public class AppKitRenderingStrategy: RenderingStrategy {
     window.contentViewController = NSViewController()
     window.setContentSize(AppKitContainer.defaultSize)
     window.contentViewController = vc
-    vc.rendered = { [weak window, weak vc] mode, precision, accessibilityEnabled, appStoreSnapshot, tags, additionalContext, groupOverride in
+    vc.rendered = { [weak window, weak vc] mode, precision, accessibilityEnabled, appStoreSnapshot, tags, additionalContext, groupOverride, canvasTheme in
       DispatchQueue.main.async {
         Self.takeSnapshot(mode: mode ?? .nsView, viewController: vc, window: window) { image in
           completion(
@@ -59,7 +59,8 @@ public class AppKitRenderingStrategy: RenderingStrategy {
               appStoreSnapshot: appStoreSnapshot,
               tags: tags,
               additionalContext: additionalContext,
-              groupOverride: groupOverride))
+              groupOverride: groupOverride,
+              canvasTheme: canvasTheme))
         }
       }
     }
@@ -119,7 +120,7 @@ final class AppKitContainer: NSHostingController<EmergeModifierView>, ScrollExpa
   var heightAnchor: NSLayoutConstraint?
   var previousHeight: CGFloat?
 
-  public var rendered: ((EmergeRenderingMode?, Float?, Bool?, Bool?, [String: String], [String: SnapshotMetadataValue], SnapshotGroup?) -> Void)? {
+  public var rendered: ((EmergeRenderingMode?, Float?, Bool?, Bool?, [String: String], [String: SnapshotMetadataValue], SnapshotGroup?, SnapshotCanvasTheme?) -> Void)? {
     didSet { didCall = false }
   }
 
@@ -169,7 +170,7 @@ final class AppKitContainer: NSHostingController<EmergeModifierView>, ScrollExpa
     guard !didCall else { return }
 
     didCall = true
-    rendered?(rootView.emergeRenderingMode, rootView.precision, rootView.accessibilityEnabled, rootView.appStoreSnapshot, rootView.tags, rootView.additionalContext, rootView.groupOverride)
+    rendered?(rootView.emergeRenderingMode, rootView.precision, rootView.accessibilityEnabled, rootView.appStoreSnapshot, rootView.tags, rootView.additionalContext, rootView.groupOverride, rootView.canvasTheme)
   }
 
   override func updateViewConstraints() {

Sources/SnapshotPreviewsCore/ExpandingViewController.swift

@@ -31,7 +31,7 @@ public final class ExpandingViewController: UIHostingController<EmergeModifierVi
   private var startTime: UInt64?
   private var timer: Timer?
 
-  public var expansionSettled: ((EmergeRenderingMode?, Float?, Bool?, Bool?, [String: String], [String: SnapshotMetadataValue], SnapshotGroup?, Error?) -> Void)? {
+  public var expansionSettled: ((EmergeRenderingMode?, Float?, Bool?, Bool?, [String: String], [String: SnapshotMetadataValue], SnapshotGroup?, SnapshotCanvasTheme?, Error?) -> Void)? {
     didSet { didCall = false }
   }
 
@@ -78,7 +78,7 @@ public final class ExpandingViewController: UIHostingController<EmergeModifierVi
     guard !didCall else { return }
 
     didCall = true
-    expansionSettled?(rootView.emergeRenderingMode, rootView.precision, rootView.accessibilityEnabled, rootView.appStoreSnapshot, rootView.tags, rootView.additionalContext, rootView.groupOverride, error)
+    expansionSettled?(rootView.emergeRenderingMode, rootView.precision, rootView.accessibilityEnabled, rootView.appStoreSnapshot, rootView.tags, rootView.additionalContext, rootView.groupOverride, rootView.canvasTheme, error)
     stopAndResetTimer()
   }
 

Sources/SnapshotPreviewsCore/ModifierFinder.swift

@@ -59,6 +59,10 @@ public struct EmergeModifierView: View {
     stateMirror?.descendant("groupOverride") as? SnapshotGroup
   }
 
+  var canvasTheme: SnapshotCanvasTheme? {
+    stateMirror?.descendant("canvasTheme") as? SnapshotCanvasTheme
+  }
+
   var supportsExpansion: Bool {
     stateMirror?.descendant("expansionPreference") as? Bool ?? true
   }

Sources/SnapshotPreviewsCore/RenderingStrategy.swift

@@ -33,7 +33,8 @@ public struct SnapshotResult {
     appStoreSnapshot: Bool?,
     tags: [String: String] = [:],
     additionalContext: [String: SnapshotMetadataValue] = [:],
-    groupOverride: SnapshotGroup? = nil)
+    groupOverride: SnapshotGroup? = nil,
+    canvasTheme: SnapshotCanvasTheme? = nil)
   {
     self.image = image
     self.precision = precision
@@ -43,6 +44,7 @@ public struct SnapshotResult {
     self.tags = tags
     self.additionalContext = additionalContext
     self.groupOverride = groupOverride
+    self.canvasTheme = canvasTheme
   }
 
   public let image: Result<ImageType, Error>
@@ -53,6 +55,7 @@ public struct SnapshotResult {
   public let tags: [String: String]
   public let additionalContext: [String: SnapshotMetadataValue]
   public let groupOverride: SnapshotGroup?
+  public let canvasTheme: SnapshotCanvasTheme?
 }
 
 public protocol RenderingStrategy {
@@ -68,4 +71,3 @@ extension RenderingStrategy {
     testHandler?.perform(NSSelectorFromString("setup"))
   }
 }
-

Sources/SnapshotPreviewsCore/SwiftUIRenderingStrategy.swift

@@ -35,9 +35,9 @@ public class SwiftUIRenderingStrategy: RenderingStrategy {
     let image = renderer.nsImage
     #endif
     if let image {
-      completion(SnapshotResult(image: .success(image), precision: wrappedView.precision, accessibilityEnabled: wrappedView.accessibilityEnabled, colorScheme: colorScheme, appStoreSnapshot: wrappedView.appStoreSnapshot, tags: wrappedView.tags, additionalContext: wrappedView.additionalContext, groupOverride: wrappedView.groupOverride))
+      completion(SnapshotResult(image: .success(image), precision: wrappedView.precision, accessibilityEnabled: wrappedView.accessibilityEnabled, colorScheme: colorScheme, appStoreSnapshot: wrappedView.appStoreSnapshot, tags: wrappedView.tags, additionalContext: wrappedView.additionalContext, groupOverride: wrappedView.groupOverride, canvasTheme: wrappedView.canvasTheme))
     } else {
-      completion(SnapshotResult(image: .failure(RenderingError.failedRendering(.zero)), precision: wrappedView.precision, accessibilityEnabled: wrappedView.accessibilityEnabled, colorScheme: colorScheme, appStoreSnapshot: wrappedView.appStoreSnapshot, tags: wrappedView.tags, additionalContext: wrappedView.additionalContext, groupOverride: wrappedView.groupOverride))
+      completion(SnapshotResult(image: .failure(RenderingError.failedRendering(.zero)), precision: wrappedView.precision, accessibilityEnabled: wrappedView.accessibilityEnabled, colorScheme: colorScheme, appStoreSnapshot: wrappedView.appStoreSnapshot, tags: wrappedView.tags, additionalContext: wrappedView.additionalContext, groupOverride: wrappedView.groupOverride, canvasTheme: wrappedView.canvasTheme))
     }
   }
 }

Sources/SnapshotPreviewsCore/View+Snapshot.swift

@@ -50,33 +50,33 @@ extension View {
     a11yWrapper: ((UIViewController, UIWindow, PreviewLayout) -> UIView)? = nil,
     completion: @escaping (SnapshotResult) -> Void)
   {
-    controller.expansionSettled = { [weak controller, weak window] renderingMode, precision, accessibilityEnabled, appStoreSnapshot, tags, additionalContext, groupOverride, error in
+    controller.expansionSettled = { [weak controller, weak window] renderingMode, precision, accessibilityEnabled, appStoreSnapshot, tags, additionalContext, groupOverride, canvasTheme, error in
       guard let controller, let window, let containerVC = controller.parent else {
         return
       }
 
       if let error {
         DispatchQueue.main.async {
-          completion(SnapshotResult(image: .failure(error), precision: precision, accessibilityEnabled: accessibilityEnabled, colorScheme: _colorScheme, appStoreSnapshot: appStoreSnapshot, tags: tags, additionalContext: additionalContext, groupOverride: groupOverride))
+          completion(SnapshotResult(image: .failure(error), precision: precision, accessibilityEnabled: accessibilityEnabled, colorScheme: _colorScheme, appStoreSnapshot: appStoreSnapshot, tags: tags, additionalContext: additionalContext, groupOverride: groupOverride, canvasTheme: canvasTheme))
         }
         return
       }
 
       if async {
         DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
           let imageResult = Self.takeSnapshot(layout: layout, renderingMode: renderingMode, window: window, rootVC: containerVC, targetView: controller.view)
-          completion(SnapshotResult(image: imageResult.mapError { $0 }, precision: precision, accessibilityEnabled: accessibilityEnabled, colorScheme: _colorScheme, appStoreSnapshot: appStoreSnapshot, tags: tags, additionalContext: additionalContext, groupOverride: groupOverride))
+          completion(SnapshotResult(image: imageResult.mapError { $0 }, precision: precision, accessibilityEnabled: accessibilityEnabled, colorScheme: _colorScheme, appStoreSnapshot: appStoreSnapshot, tags: tags, additionalContext: additionalContext, groupOverride: groupOverride, canvasTheme: canvasTheme))
         }
       } else {
         DispatchQueue.main.async {
           if let a11yWrapper, let accessibilityEnabled, accessibilityEnabled {
             let a11yView = a11yWrapper(controller, window, layout)
             let result = Self.takeSnapshot(layout: .sizeThatFits, renderingMode: renderingMode, window: window, rootVC: containerVC, targetView: a11yView)
             a11yView.removeFromSuperview()
-            completion(SnapshotResult(image: result.mapError { $0 }, precision: precision, accessibilityEnabled: accessibilityEnabled, colorScheme: _colorScheme, appStoreSnapshot: appStoreSnapshot, tags: tags, additionalContext: additionalContext, groupOverride: groupOverride))
+            completion(SnapshotResult(image: result.mapError { $0 }, precision: precision, accessibilityEnabled: accessibilityEnabled, colorScheme: _colorScheme, appStoreSnapshot: appStoreSnapshot, tags: tags, additionalContext: additionalContext, groupOverride: groupOverride, canvasTheme: canvasTheme))
           } else {
             let imageResult = Self.takeSnapshot(layout: layout, renderingMode: renderingMode, window: window, rootVC: containerVC, targetView: controller.view)
-            completion(SnapshotResult(image: imageResult.mapError { $0 }, precision: precision, accessibilityEnabled: accessibilityEnabled, colorScheme: _colorScheme, appStoreSnapshot: appStoreSnapshot, tags: tags, additionalContext: additionalContext, groupOverride: groupOverride))
+            completion(SnapshotResult(image: imageResult.mapError { $0 }, precision: precision, accessibilityEnabled: accessibilityEnabled, colorScheme: _colorScheme, appStoreSnapshot: appStoreSnapshot, tags: tags, additionalContext: additionalContext, groupOverride: groupOverride, canvasTheme: canvasTheme))
           }
         }
       }

Sources/SnapshotSharedModels/SnapshotCanvasTheme.swift

@@ -0,0 +1,9 @@
+//
+//  SnapshotCanvasTheme.swift
+//
+
+/// Background canvas theme used when displaying a snapshot image in Sentry.
+public enum SnapshotCanvasTheme: String, Codable, Sendable, Equatable {
+  case light
+  case dark
+}