fix(release): enforce macOS-compatible jpackage appVersion normalization

Map jpackage appVersion to a SemVer triplet with optional v-prefix support.

Enforce appVersion major >= 1 to satisfy macOS jpackage constraints.

Document the workaround as temporary and remove it at the first real v1.x release.

Author: Beowolve

CHANGELOG.md

@@ -7,6 +7,7 @@ The changelog is grouped by release tags (`vX.Y.Z`) and includes an `Unreleased`
 ## Unreleased
 
 ### Build and Test
+- ✅ Fixed demo jpackage app-version normalization for macOS runners by enforcing a major-version floor of `1` (for example `0.4.1-*` becomes `1.4.1` for packaging), resolving `jpackageImage` failures in the release matrix.
 - ✅ Expanded the release workflow into a multi-job pipeline with a Windows/macOS/Linux matrix for demo `jpackage` ZIP assets, and centralized final release publishing from aggregated artifacts.
 - ✅ Added `org.beryx.jlink` demo packaging baseline in `snapfx-demo` with `jlink`, `jpackageImage`, and `packageJPackageImageZip`, including jpackage-safe version normalization for git-derived dev versions and OS-specific app icon selection (`snapfx.ico`/`snapfx.icns`/`snapfx.png`).
 - ✅ Aligned release workflow build tasks and artifact upload paths with split modules (`:snapfx-demo:distZip`/`:distTar`, `snapfx-demo/build/distributions/*`, `snapfx-core/build/libs/*`).

DONE.md

@@ -289,7 +289,7 @@ SnapFX has been fully implemented with core functionality and is production-read
 - ✅ Added GitHub Actions release workflow for `v*` tags that runs build/tests and publishes GitHub Releases with distribution artifacts.
 - ✅ Aligned release workflow build tasks and artifact upload paths with split modules (`:snapfx-demo:distZip`/`:distTar`, `snapfx-demo/build/distributions/*`, `snapfx-core/build/libs/*`)
 - ✅ Extended the release workflow with a cross-platform matrix that builds demo `jpackage` ZIP assets on Windows/macOS/Linux and publishes them with OS-specific filenames.
-- ✅ Added `org.beryx.jlink` demo packaging baseline in `snapfx-demo` (`jlink`, `jpackageImage`, and `packageJPackageImageZip`) with jpackage-safe version normalization for git-derived dev versions and OS-specific app icon wiring (`snapfx.ico`/`snapfx.icns`/`snapfx.png`)
+- ✅ Added `org.beryx.jlink` demo packaging baseline in `snapfx-demo` (`jlink`, `jpackageImage`, and `packageJPackageImageZip`) with jpackage-safe version normalization for git-derived dev versions (including a temporary macOS-compatible app-version major floor `1`, planned to be removed at first `v1.x`) and OS-specific app icon wiring (`snapfx.ico`/`snapfx.icns`/`snapfx.png`)
 - ✅ Added `git-cliff` release-note generation (`cliff.toml`) and wired release workflow to publish generated notes.
 - ✅ Tracked `gradlew` as executable (`100755`) so Linux CI/release runners can execute the Gradle wrapper reliably.
 - ✅ Added `xvfb-run -a` to CI/release Gradle test execution so JavaFX tests run reliably on headless Linux runners.

ROADMAP.md

@@ -404,7 +404,8 @@ This roadmap keeps a high-level progress view plus planned/proposed work; detail
 - ✅ **Maven publish dry-run baseline (`snapfx-core`)**: `maven-publish` + optional signing wiring, `sourcesJar`/`javadocJar`, and POM metadata are in place; local `:snapfx-core:publishToMavenLocal` succeeds
 - 📋 **Maven Central**: Publish to Maven Central
 - ✅ **jlink support baseline**: `snapfx-demo` now uses `org.beryx.jlink` and provides `:snapfx-demo:jlink` runtime-image packaging
-- 🚧 **jpackage support baseline**: `snapfx-demo` now provides `:snapfx-demo:jpackageImage` and `:snapfx-demo:packageJPackageImageZip` with OS-specific app icon selection (`.ico`/`.icns`/`.png`), and release automation now publishes per-OS demo ZIP assets (Windows/macOS/Linux); installer generation/signing remains pending
+- 🚧 **jpackage support baseline**: `snapfx-demo` now provides `:snapfx-demo:jpackageImage` and `:snapfx-demo:packageJPackageImageZip` with OS-specific app icon selection (`.ico`/`.icns`/`.png`) plus macOS-compatible app-version normalization (major version floor `1`), and release automation now publishes per-OS demo ZIP assets (Windows/macOS/Linux); installer generation/signing remains pending
+- 📋 **Remove temporary macOS appVersion workaround at v1.x**: After the first real `v1.x` project release, drop the major-floor mapping so demo appVersion equals the core/project version again.
 - 📋 **Version management**: Semantic versioning
 
 **Estimated Time**: 2-3 days

STATUS.md

@@ -14,7 +14,7 @@
 
 ✅ **CI Module-Split Alignment**: Critical stability suites now run `:snapfx-core:test` with `org.snapfx...` test filters
 ✅ **Release Module-Split Alignment**: Tag release workflow now builds `:snapfx-demo` distributions explicitly and publishes artifacts from split module output paths
-✅ **Demo Runtime Packaging Baseline**: `org.beryx.jlink` now configures `:snapfx-demo:jlink`, `:snapfx-demo:jpackageImage`, and `:snapfx-demo:packageJPackageImageZip`, including OS-specific app icons (`.ico`/`.icns`/`.png`)
+✅ **Demo Runtime Packaging Baseline**: `org.beryx.jlink` now configures `:snapfx-demo:jlink`, `:snapfx-demo:jpackageImage`, and `:snapfx-demo:packageJPackageImageZip`, including OS-specific app icons (`.ico`/`.icns`/`.png`) and a temporary macOS-compatible jpackage app-version normalization (major version floor `1`, planned removal at first `v1.x` release)
 ✅ **Cross-Platform Demo Release Assets**: Tag releases now build `jpackage` demo ZIPs on Windows/macOS/Linux and publish them with deterministic OS-specific filenames (`snapfx-demo-jpackage-image-<os>-<tag>.zip`)
 
 ## Documentation Scope

snapfx-demo/build.gradle.kts

@@ -7,10 +7,17 @@ plugins {
 val javafxModules = listOf("javafx.controls")
 val javaVersion = JavaVersion.VERSION_21
 val javafxRuntimeVersion = javaVersion.majorVersion
-val normalizedJPackageVersion = Regex("""^\d+\.\d+\.\d+""")
+val normalizedJPackageVersion = Regex("""^v?(\d+)\.(\d+)\.(\d+)""")
     .find(project.version.toString())
-    ?.value
-    ?: "0.0.0"
+    ?.destructured
+    ?.let { (major, minor, patch) ->
+        // macOS jpackage requires appVersion major >= 1.
+        // TODO(v1): Remove this major-floor workaround after the first real v1.x release,
+        // so demo appVersion matches the core/project version again.
+        val appMajor = major.toIntOrNull()?.coerceAtLeast(1) ?: 1
+        "$appMajor.$minor.$patch"
+    }
+    ?: "1.0.0"
 val jpackageIconFileName = when {
     System.getProperty("os.name").lowercase().contains("win") -> "snapfx.ico"
     System.getProperty("os.name").lowercase().contains("mac") -> "snapfx.icns"