feat(snapshots): Add @SentrySnapshot runtime annotation (EME-1055) (#1154)

* feat(snapshots): Add @SentrySnapshot runtime annotation (EME-1055)

Introduce a new Maven artifact io.sentry:sentry-snapshots-runtime
that publishes the @SentrySnapshot annotation. Consumers apply it
alongside @Preview to override the global diff threshold on a
per-snapshot basis.

The diffThreshold parameter name aligns with the --diff-threshold
flag in sentry-cli and the diff_threshold field in the snapshot
manifest, giving consistent naming across CLI, manifest, and the
Android runtime.

A follow-up will wire the Gradle plugin's preview scanner to read
the annotation and surface the value in per-snapshot sidecar
metadata.

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

* build(craft): Register sentry-snapshots-runtime in release registry (EME-1055)

Add required first-publish metadata (name, sdkName, packageUrl,
mainDocsUrl) for the new sentry-snapshots-runtime package so Craft
can create its entry in the Sentry release registry.

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

* build(craft): Use central.sonatype.com for packageUrl (EME-1055)

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

* build(snapshots): Disable distTar packaging (EME-1055)

Only distZip is needed for local development and publishing; skip the
tar variant to avoid producing a redundant artifact.

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

* build(snapshots): Drop distTar disable line (EME-1055)

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

* build(release): Bump sentry-snapshots-runtime version too (EME-1055)

scripts/bump-version.sh previously only rewrote the plugin-build and
sentry-kotlin-compiler-plugin property files. Without this, the newly
added sentry-snapshots-runtime artifact would ship with a stale
VERSION_NAME and drift from the other published artifacts on each
release.

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

* apply runtime retention

---------

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

Author: runningcode

.craft.yml

@@ -13,3 +13,8 @@ targets:
     sdks:
       maven:io.sentry:sentry-android-gradle-plugin:
       maven:io.sentry:sentry-kotlin-compiler-plugin:
+      maven:io.sentry:sentry-snapshots-runtime:
+        name: 'io.sentry:sentry-snapshots-runtime'
+        sdkName: 'sentry.java.android.snapshots-runtime'
+        packageUrl: 'https://central.sonatype.com/artifact/io.sentry/sentry-snapshots-runtime'
+        mainDocsUrl: 'https://docs.sentry.io/platforms/android'

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Features
+
+- Add `@SentrySnapshot` runtime annotation for configuring the per-snapshot diff threshold, published as `io.sentry:sentry-snapshots-runtime` ([EME-1055](https://linear.app/getsentry/issue/EME-1055))
+
 ### Dependencies
 
 - Bump CLI from v3.3.5 to v3.4.0 ([#1156](https://github.com/getsentry/sentry-android-gradle-plugin/pull/1156))

gradle/libs.versions.toml

@@ -31,6 +31,7 @@ composeCompiler =  { id = "org.jetbrains.kotlin.plugin.compose", version = "2.1.
 
 [libraries]
 junit = { group = "junit", name = "junit", version = "4.13.2" }
+androidxAnnotation = { group = "androidx.annotation", name = "annotation", version = "1.9.1" }
 proguard = { group = "com.guardsquare", name = "proguard-gradle", version = "7.5.0" }
 # this allows us to develop against a fixed version of Gradle, as opposed to depending on the
 # locally available version. kotlin-gradle-plugin follows the same approach.

scripts/bump-version.sh

@@ -17,3 +17,7 @@ perl -pi -e "s/^$VERSION_NAME_PATTERN = .*$/$VERSION_NAME_PATTERN = $NEW_VERSION
 GRADLE_FILEPATH="sentry-kotlin-compiler-plugin/gradle.properties"
 VERSION_NAME_PATTERN="VERSION_NAME"
 perl -pi -e "s/^$VERSION_NAME_PATTERN = .*$/$VERSION_NAME_PATTERN = $NEW_VERSION/g" $GRADLE_FILEPATH
+
+GRADLE_FILEPATH="sentry-snapshots-runtime/gradle.properties"
+VERSION_NAME_PATTERN="VERSION_NAME"
+perl -pi -e "s/^$VERSION_NAME_PATTERN = .*$/$VERSION_NAME_PATTERN = $NEW_VERSION/g" $GRADLE_FILEPATH

sentry-snapshots-runtime/Makefile

@@ -0,0 +1,10 @@
+.PHONY: compile all dist
+
+compile:
+	./gradlew assemble
+
+# build distribution artifacts
+dist:
+	./gradlew distZip --no-parallel
+
+all: compile dist

sentry-snapshots-runtime/build.gradle.kts

@@ -0,0 +1,56 @@
+plugins {
+  alias(libs.plugins.kotlin)
+  id("distribution")
+  alias(libs.plugins.mavenPublish)
+  alias(libs.plugins.spotless)
+}
+
+spotless {
+  kotlin {
+    ktfmt(libs.versions.ktfmt.get()).googleStyle()
+    target("**/*.kt")
+  }
+  kotlinGradle {
+    target("**/*.kts")
+    ktfmt(libs.versions.ktfmt.get()).googleStyle()
+  }
+}
+
+val sep = File.separator
+
+distributions {
+  main {
+    contents {
+      from("build${sep}libs")
+      from("build${sep}publications${sep}maven")
+    }
+  }
+}
+
+tasks.named("distZip") {
+  dependsOn("publishToMavenLocal")
+  onlyIf { inputs.sourceFiles.isEmpty.not().also { require(it) { "No distribution to zip." } } }
+}
+
+dependencies { compileOnly(libs.androidxAnnotation) }
+
+plugins.withId("com.vanniktech.maven.publish.base") {
+  configure<PublishingExtension> {
+    repositories {
+      maven {
+        name = "mavenTestRepo"
+        url = file("${rootProject.projectDir}/../build/mavenTestRepo").toURI()
+      }
+      maven {
+        name = "mavenCentralSnapshots"
+        url = uri("https://central.sonatype.com/repository/maven-snapshots/")
+        credentials {
+          username = findProperty("mavenCentralUsername")?.toString()
+          password = findProperty("mavenCentralPassword")?.toString()
+        }
+      }
+    }
+  }
+}
+
+kotlin { jvmToolchain(11) }

sentry-snapshots-runtime/gradle.properties

@@ -0,0 +1,24 @@
+org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1536m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8 -XX:+UseParallelGC -XX:+CrashOnOutOfMemoryError
+org.gradle.caching=true
+org.gradle.parallel=true
+
+GROUP = io.sentry
+POM_ARTIFACT_ID = sentry-snapshots-runtime
+VERSION_NAME = 6.4.0
+
+# publication pom properties
+POM_NAME=Sentry Snapshots Runtime
+POM_DESCRIPTION=Runtime annotations for configuring Sentry snapshot tests
+POM_URL=https://github.com/getsentry/sentry-android-gradle-plugin
+POM_SCM_URL=https://github.com/getsentry/sentry-android-gradle-plugin
+POM_SCM_CONNECTION=scm:git:git://github.com/getsentry/sentry-android-gradle-plugin.git
+POM_SCM_DEV_CONNECTION=scm:git:ssh://git@github.com/getsentry/sentry-android-gradle-plugin.git
+
+POM_LICENCE_NAME=MIT
+POM_LICENCE_URL=https://github.com/getsentry/sentry-android-gradle-plugin/blob/main/LICENSE
+
+POM_DEVELOPER_ID=getsentry
+POM_DEVELOPER_NAME=Sentry Team and Contributors
+POM_DEVELOPER_URL=https://github.com/getsentry/
+
+RELEASE_SIGNING_ENABLED=false

sentry-snapshots-runtime/settings.gradle.kts

@@ -0,0 +1,10 @@
+rootProject.name = ("sentry-snapshots-runtime")
+
+dependencyResolutionManagement {
+  repositories {
+    google()
+    mavenCentral()
+  }
+  versionCatalogs.create("libs") { from(files("../gradle/libs.versions.toml")) }
+  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+}

sentry-snapshots-runtime/src/main/kotlin/io/sentry/snapshots/runtime/SentrySnapshot.kt

@@ -0,0 +1,22 @@
+package io.sentry.snapshots.runtime
+
+import androidx.annotation.FloatRange
+
+/**
+ * Configures how Sentry compares this preview snapshot against the baseline.
+ *
+ * Apply alongside `@Preview` on a composable to override the global diff threshold on a
+ * per-snapshot basis.
+ */
+@Retention(AnnotationRetention.RUNTIME)
+@Target(AnnotationTarget.FUNCTION)
+annotation class SentrySnapshot(
+  /**
+   * Minimum pixel-difference percentage required to report this snapshot as changed. Differences
+   * below this value are treated as unchanged.
+   *
+   * Range: `0.0`..`1.0`. Example: `0.01f` reports a change only when at least 1% of pixels differ.
+   * Defaults to `0f` (report any difference).
+   */
+  @FloatRange(from = 0.0, to = 1.0) val diffThreshold: Float = 0f
+)

settings.gradle.kts

@@ -46,3 +46,9 @@ includeBuild("sentry-kotlin-compiler-plugin") {
     substitute(module("io.sentry:sentry-kotlin-compiler-plugin")).using(project(":"))
   }
 }
+
+includeBuild("sentry-snapshots-runtime") {
+  dependencySubstitution {
+    substitute(module("io.sentry:sentry-snapshots-runtime")).using(project(":"))
+  }
+}