This page lists the changes in each Nucleus release, newest first. Every entry records the new modules, features, bug fixes, and breaking changes in that version.

v2.2.0

Released: 2026-08-03

Highlights

Window scaffold and chrome primitives. Full-window layouts without giving up native drag, caption zones, or traffic-light insets. Compose content through WindowScaffold with TitleBarPlacement.Docked or Overlay, and rebuild chrome from public APIs: Modifier.windowDragArea / noWindowDrag, WindowControls, macOS windowGlassRegion, Windows 11 WindowsBackdrop (Mica / Acrylic / MicaAlt), WindowBackground, and WindowAppearance. See Window scaffold, chrome primitives, and platform materials.
GraalVM tasks mirror the JVM pipeline. runGraalvmNative is the fast dev loop (-Ob quick-build); full optimization lives on runGraalvmNativeDistributable. New createGraalvmNativeDistributable and packageGraalvmNativeDistributionForCurrentOS match createDistributable / packageDistributionForCurrentOS. The native app folder lands under compose/binaries/<app>/graalvm-app. See Tasks & CI — public surface and output locations.
Type-safe garbage collector selection. garbageCollector = GarbageCollector.Z on the JVM path and graalvm { garbageCollector = NativeImageGarbageCollector.G1 } for native images. G1 is Oracle GraalVM + Linux only and degrades with a warning elsewhere. Heap-percent flags follow the selected collector. See Choose a garbage collector and the Gradle DSL.

New features

WindowScaffold + TitleBarPlacement (#412, #129) — design-system-agnostic chrome host. Docked keeps the classic bar-above-content layout; Overlay fills content to the full window height and hands the measured bar height back as top PaddingValues. Optional autoHideInFullscreen and passThroughToContent on Overlay for immersive and hit-test-through title bars (#423). See title bar placement.
Chrome primitives for custom title bars (#412) — Modifier.windowDragArea / noWindowDrag, WindowControls + WindowControlsRenderer, WindowDoubleClickAction, and LocalWindowChromeInsets so toolbars can place content around traffic lights and KDE edge padding. See chrome primitives, drag areas, and window controls.
Platform materials (#412) — Modifier.windowGlassRegion (macOS System Settings-style sidebar/content/inspector panes), WindowsBackdrop (DWM Mica / Acrylic / MicaAlt with tier pin), WindowBackground (clear colour from inside the content tree), WindowAppearance (force light/dark on native surfaces). See platform materials, macOS glass, and Windows 11 backdrops.
DecoratedWindow(transparent = true) on Tao (#419) — full-window transparency for ghost overlays. Pair with undecorated = true for borderless see-through windows. AWT is out of scope; call the Tao DecoratedWindow (e.g. via taoApplication). See transparent overlays and DecoratedWindow on Tao.
Native GTK CSD drop shadow (#422) — Linux client-side decorations use the hidden-titlebar pattern so the shadow tracks the window correctly, including during interactive moves. See DecoratedWindow notes.
AccessKit on Windows (#420) — Windows accessibility now shares the AccessKit wire path with Linux (UIA provider). AccessKit crates bumped across both platforms; Linux AT-SPI probes match Windows severity. See Accessibility.
garbageCollector on the JVM and native DSL (#408) — GarbageCollector (SERIAL, PARALLEL, G1, Z, SHENANDOAH, EPSILON) for HotSpot; NativeImageGarbageCollector (SERIAL, G1, EPSILON) for --gc=. Unset keeps JVM ergonomics / native-image Serial. See Choose a garbage collector and Gradle DSL — GraalVM.
NucleusApplicationScope implements Compose ApplicationScope (#372) — libraries scoped to plain ApplicationScope (for example ComposeNativeTray) resolve inside nucleusApplication { } without a separate overload set. See DecoratedWindow notes.

Ecosystem (separate repos)

Published around the 2.2 line; versioned independently of Nucleus:

compose-macos-26-ui — macOS 26 design system + MacosDecoratedWindow. Docs: macOS toolkit.
compose-fluent-ui — Fluent Design + FluentDecoratedWindow. Docs: Fluent toolkit.
yaru-compose-ui — Yaru / GNOME design system + YaruDecoratedWindow. Docs: Yaru toolkit.

Improvements

macOS .app bundle name consistency (#409) — every artifact (DMG, ZIP, …) ships the same bundle name derived from appName, so auto-update no longer deletes one path and fails to open another when appName != packageName.
Glitch-free Windows fullscreen toggle and macOS fullscreen transition ramp parity (#412 / #413).
macOS display-scale follow when the window hops between displays (#412). See Per-monitor HiDPI.

Bug fixes

NsView setBounds / resize on layout changes (#421) — embedded macOS native views update their frames when Compose layout changes. See Native views.
Scheme-only deep link URIs (#425 / #414) — DeepLinkHandler accepts opaque forms such as myapp:?query=… (common from xdg-open), not only scheme:// authority forms. Windows drive paths are still rejected. See Deep links — how it works.
Hot-reload gate matches the published Tao artifact name (#424 / #415).

v2.1.10

Released: 2026-07-26

Bug fixes

Resolve JDK library jars on JMOD-less JDKs (#407) — ProGuard release packaging failed on JDKs that ship without a jmods directory (Temurin 25+ after JEP 493). The task falls back to extracting the run-time image with jimage extract and passes one class root per module. JDKs that still ship jmods keep the previous path.
Stop CSD shadow tracing while the window is dragged (#393 / #383) — the Linux client-side-decoration shadow no longer leaves a trail during interactive window moves.

v2.1.9

Released: 2026-07-26

Bug fixes

Survive obfuscation for all JNI bridges and coroutines (#405) — with obfuscate = true on by default since 2.1.6, release builds crashed at runtime. The module-by-module JNI keep list is replaced by generic rules that keep the names of any dev.nucleusframework class declaring native methods plus *Bridge/*Jni objects whole, fixing UnsatisfiedLinkError in the modules the list missed (autolaunch, launcher-linux, notification-linux/macos, service-management-macos, system-info, taskbar-progress, graalvm-runtime). Dropping allowoptimization from the kotlinx.** safety rules fixes a VerifyError in ChannelsKt.trySendBlocking; shrinking stays fully active. The system-color and media-control native builds now invoke build.bat by absolute path like every other module.

CI

Microsoft JDK on Windows, Temurin elsewhere (#406) — replaces JBR as the setup-nucleus JDK. The Microsoft Build of OpenJDK is the only mainstream distribution shipping GA windows-aarch64 builds for current LTS majors, and decorated-window-jbr needs no JBR at build time since the JBR API comes from the org.jetbrains.runtime:jbr-api artifact.

v2.1.8

Released: 2026-07-26

New features

aotCache { } configuration block (#404) — exposes the AOT cache portability trade-off: compatibility = NATIVE restores the JDK default for locally-built or fleet-homogeneous deployments, and extraTrainingJvmArgs is an escape hatch for the training run. enableAotCache keeps working as a shorthand.

Bug fixes

CPU-portable AOT cache by default (#404) — the JDK 25+ AOT cache also stores machine code (i2c/c2i adapter blobs) emitted for the training machine's CPU features, and HotSpot records no ISA information for that region before JDK 27, so a cache built on a CI runner died with EXCEPTION_ILLEGAL_INSTRUCTION/SIGILL on a narrower CPU. The cache now defaults to metadata only (-XX:-AOTAdapterCaching on both the training run and the shipped launcher), keeping the class loading and linking gains and leaving the JIT untouched at runtime. compatibility = NATIVE warns at build time when the bundled runtime predates the CPU-feature validation added after JDK 26.

v2.1.7

Released: 2026-07-26

Breaking changes

GraalVM Community Edition is now the default toolchain (#403) — the auto-provisioned toolchain was Oracle GraalVM, governed by the GraalVM Free Terms and Conditions. The GFTC only allows redistributing the Program provided you do not charge your licensees any fees associated with such distribution or use, and the plugin copies GraalVM runtime libraries next to the packaged executable — so that clause silently reached every app built with Nucleus. GraalVM CE (GPLv2 + Classpath Exception) carries no such restriction and is now the default via GraalvmDistribution.COMMUNITY. Oracle GraalVM stays available behind an explicit opt-in that logs a licensing warning. -O3, --pgo and -H:AdvancedObfuscation degrade to a warning under a community toolchain, and runWithPgoInstrument is not registered at all. The distribution is embedded in the install directory and the CI cache key so an existing Oracle download is never reused, and a GRAALVM_HOME whose distribution disagrees with the DSL is ignored.

Improvements

Lazy toolchain provisioning (#403) — every toolchain provider now resolves in doFirst, so an IDE sync or gradlew tasks no longer downloads a JDK.

Bug fixes

Survive GitHub API rate limits when resolving Community Edition (#403) — a pinned version ("25.0.2") now constructs the download URL directly instead of listing releases, making the documented pin-a-version workaround work offline; the native-image build steps pass GITHUB_TOKEN so the releases API call is authenticated. Floating versions ("25", "25i1") still need the API.
Decode Mach-O cpu_type in the file's own byte order (#402) — MH_CIGAM_64 is the byte-swapped magic that every little-endian macOS dylib starts with on disk, so cpu_type was read swapped and every thin dylib reported arch=UNKNOWN. Cross-checked against lipo on 57 real dylibs: 44 decoded wrong before, all 57 are correct now. Also recognizes FAT_MAGIC_64 alongside FAT_MAGIC, and hoists the path-plus-header merge into NativeLibArchDetector.detectEntry so the strip transform shares it.
Extract the target-arch native lib, not the first match (#401) — native libs whose JAR path carries an arch but no OS token were extracted for the wrong architecture: detectInfo discarded the path-detected arch whenever the OS was UNKNOWN, and the 64-byte header buffer was too small to reach the PE machine field. An ARM64 DLL could therefore win the flattening race on an x64 target and fail to load. detectInfo now merges path and header information field by field and reads 4096 header bytes. Fixes #399.

v2.1.6

Released: 2026-07-23

New features

Advanced obfuscation for native images (#389) — graalvm { advancedObfuscation = true } passes -H:AdvancedObfuscation= (Oracle GraalVM only, gated on the resolved toolchain and warning otherwise) so the symbol names baked into the binary — stack traces, heap dumps, Class#getName, strings — are obfuscated. Reflection and JNI names from the reachability metadata are preserved automatically, so it is JNI-safe by construction. -H:+UnlockExperimentalVMOptions is passed alongside it, and --enable-sbom=export keeps the SBOM as a build artifact instead of embedding it and re-leaking the dependency list obfuscation hides.
Obfuscate-safe ProGuard rules (#389) — when proguard { obfuscate = true }, a bundled nucleus-obfuscation-safety-rules.pro is injected automatically to preserve framework names (androidx.**, kotlinx.**) while still allowing shrinking and optimization, so the Compose and Kotlin runtimes survive renaming and only the app's own packages get obfuscated. Prevents ClassNotFoundException: androidx.compose.runtime.Composer. Not injected when obfuscation is off.
Desktop-appropriate default max heap for native images (#390) — native-image's Serial GC defaults the max heap to 80% of physical RAM, far above a desktop app's norm. Nucleus now bakes -R:MaximumHeapSizePercent=25 for parity with HotSpot's MaxRAMPercentage, configurable via graalvm { maxHeapSizePercent = N } or an absolute graalvm { maxHeapSize = "2g" } (which takes precedence). Both are defaults only, still overridable at runtime with -Xmx.
--enable-native-access=ALL-UNNAMED baked into native images (#390) — native modules call System.loadLibrary from the unnamed module, which since JDK 24 (JEP 472) emits a restricted-method warning and will be blocked in a future release. The JVM run path already passed the flag; the native binary now starts clean too.
Pause the render loop while the window is minimized (#384) — each platform scene host gates its frame body on window.isMinimized before the frame-clock tick, so Compose animations park instead of recording and presenting into a hidden surface. This matters most on Windows, where ANGLE's flip-model swapchain never reports occlusion and there is no vsync back-pressure while minimized; restore re-kicks a redraw explicitly.
Jewel 0.39 and IntelliJ icons 262 (#395) — bumps Jewel to 0.39.0-262.9437.21, adds the intellij-icons-api/impl dependencies that Jewel 0.39's IntUiTheme needs, and registers the build-time initialization and reflection entries required to avoid a Method.invoke segfault under SVM.

Bug fixes

Scope JNI local refs on permanently-attached upcall threads (#387) — object-creating upcalls on permanently attached threads never had their local frame popped, leaking local refs for the life of the process. The touch path was the worst: dispatch_touch allocated three long[] per event, so a sustained touch drag grew the JNI local reference table until it overflowed and aborted the JVM. Each such upcall body is now wrapped in env.with_local_frame(...), covering the Linux touch and drop paths, macOS deep links, and the macOS/Windows accessibility action trampolines.
Clear pending JNI exceptions after accessibility and deep-link upcalls (#385) — the accessibility and deep-link native-to-JVM callbacks invoked NativeTaoBridge.dispatch* without exception_check/exception_clear, unlike every other dispatch path. A throwing Kotlin handler left the exception pending on the long-lived callback thread (AT-SPI/zbus, UIA, AppKit), making the next JNI call on that thread undefined behavior and, under panic = "abort", a process abort with an unrelated-looking crash site. The guard is now applied to all 18 upcall sites.
Migrate -H:IncludeResources to reachability-metadata globs (#389) — the deprecated option warned at build time; the resource inclusion patterns moved into the module's reachability-metadata.json with identical semantics. The blanket font and icon globs are deliberately kept: they cover resources bundled inside library JARs, such as Jewel's SVG icons, which per-root autoIncludeResources does not reach.

Improvements

Shared scene drag-and-drop extracted into TaoSceneDnD (#386) — deduplicates the three platform scene hosts into one shared file, preserving the Linux-specific behavior where has_files reflects the presence of a text/uri-list target.
Jewel-specific native-image metadata moved into decorated-window-jewel (#395) — the Jewel build-time initialization and reflection entries ship only with Jewel consumers; graalvm-runtime keeps only the generic slf4j build-time init.

v2.1.5

Released: 2026-07-21

New features

Auto-include the project's own resources in native image (#379) — GraalVM native-image builds now bundle the application's own resources automatically, not just framework and Compose resources.
Apply dependencies' ProGuard consumer rules (#380) — ProGuard now applies the META-INF/proguard keep rules shipped inside dependency JARs, so libraries that provide their own rules work without manual configuration.

Bug fixes

Tao audit hardening (#378) — native memory and lifecycle fixes, expanded test coverage, a window-host refactor, and improved logging across the Tao backend.
Reimplement the Linux CSD drop shadow via a dedicated wl_shm subsurface (#381, #382) — replaces the 2.1.0 client-side-decoration drop shadow with a Wayland subsurface that renders correctly.

v2.1.4

Released: 2026-07-19

Bug fixes

Apply TitleBarStyle color overrides to caption buttons (#377) — the Tao backend now honors title bar color overrides on the window control (caption) buttons.

CI

Cache native builds, merge per-platform artifacts, and cancel superseded runs (#375).
Tiered Tao test infrastructure (#373) — an offscreen scene harness plus a headful window suite for decorated-window-tao.

v2.1.3

Released: 2026-07-18

Bug fixes

Load GTK with RTLD_LOCAL on Linux (#368) — stops GTK symbol interposition from clobbering SQLite in the Tao backend.
Own the app/runtime directories in RPM packages (#369) — the jpackage launcher now finds its .cfg file.
Run the Windows outside-click hook on a dedicated native thread (#370) — the WH_MOUSE_LL low-level mouse hook no longer shares a thread, fixing missed outside-click detection.

v2.1.2

Released: 2026-07-17

Bug fixes

Release resize-drag native memory on Windows (#365) — the Tao backend frees the native memory allocated for a resize drag when the drag ends.

v2.1.1

Released: 2026-07-17

Bug fixes

Use an @argfile on Windows for native-image compilation (#364) — avoids the Windows command-line length limit during GraalVM native builds.

v2.1.0

Released: 2026-07-17

Highlights

Oracle GraalVM is now the recommended and default toolchain. Nucleus downloads and caches it automatically (toolchain { } — Innovation by default, channel = GraalvmChannel.LTS for LTS), and the default Tao backend builds native images on it. Oracle GraalVM (the edition formerly called Enterprise) unlocks the advanced native-image features Nucleus builds on — Profile-Guided Optimization, -O3, and ML-inferred profiles — that the Community editions do not provide. Only the deprecated AWT backend still requires a local BellSoft Liberica NIK install. No setup-graalvm step; GRAALVM_HOME still takes precedence.
Compose Hot Reload works out of the box. Apply the org.jetbrains.compose.hot-reload plugin and run hotRun; Nucleus resolves the entry point from nucleus.application.mainClass, with no ComposeHotRun configuration. hotDev without -PclassName behaves like hotRun. Hot reload was not functional in 2.0.
Built-in Profile-Guided Optimization. Record a profile with runWithPgoInstrument, commit it, and later native builds apply it automatically (--pgo). Oracle GraalVM only.

New features

Compose Hot Reload on the Tao backend. The Hot Reload dev-tools sidecar now follows Tao-backed windows, not just AWT, via a reflective bridge driven by Tao window callbacks.
Type-safe march and optimization. march is now NativeImageMarch (NATIVE / COMPATIBILITY) with a per-platform default; optimization is NativeImageOptimization (QUICK_BUILD, NONE, LEVEL_1..LEVEL_3, SIZE). New allCharsets and mlProfileInference toggles.
Oracle GraalVM on macOS. Native images on the default Tao backend build on Oracle GraalVM on macOS (arm64); the deprecated AWT backend still requires BellSoft Liberica NIK. Intel Macs fall back to Liberica NIK.
CompressionLevel.Ultra. New compression level that additionally recompresses the macOS DMG with LZMA (ULMO, ~20% smaller) and the Linux .deb with xz -9e (~25% smaller). Maximum no longer runs these post-processing steps.
Themed clear color and Linux CSD drop shadow. Tao hosts paint a themed clear color; Linux decorated windows replicate the GTK client-side-decoration drop shadow.

Improvements

Smaller native images. optimization = NativeImageOptimization.SIZE (-Os) plus automatic executable stripping on Linux and macOS reclaim tens of MB.
--enable-native-access=ALL-UNNAMED by default. Added to the default JVM args (run task and packaged launcher) so JNI native access on JDK 24+ (JEP 472) no longer warns.
Auto-download the GraalVM toolchain removes the manual NIK install previously required for native builds.
Reachability metadata repository default bumped to 1.1.4 (from 0.10.6).
ProGuard default version bumped to 7.9.1.

Bug fixes

Align Compose Hot Reload version with the Compose-bundled release and harden the Tao bridge — a version skew now stops the sidecar for that window instead of crashing the app.
Drop the native shadow on macOS popup panels in the Tao backend.

v2.0.7

Released: 2026-07-14

Bug fixes

Default march to compatibility for portable binaries (#344) — GraalVM native images now target a baseline CPU by default instead of the build machine, so distributed binaries run on older hardware.

v2.0.6

Released: 2026-07-14

Bug fixes

Bundle libjsound in native image (#341) — Java Sound now works in GraalVM native-image builds.
Run Windows WinRT toasts on a dedicated MTA thread (#342) — fixes notification delivery on Windows.

v2.0.5

Released: 2026-07-14

Bug fixes

Dispatchers.Main works without a running Tao loop (#337) — coroutine main dispatch no longer requires an active Tao event loop.

v2.0.4

Released: 2026-07-13

Bug fixes

cleanupNativeLibs works for Kotlin Multiplatform projects (#335).

v2.0.3

Released: 2026-07-13

New features

dockIconFollowsWindows (#334) — control dock-icon visibility for menu-bar / tray apps on macOS.

v2.0.2

Released: 2026-07-13

Bug fixes

Apply org.jetbrains.compose alongside Nucleus (#331) — the Nucleus plugin no longer conflicts when the JetBrains Compose plugin is applied to the same project.

v2.0.1

Released: 2026-07-13

Bug fixes

Pre-Tahoe traffic lights + macOS menu ProGuard rules (#310) — fixes window traffic-light buttons on macOS versions before Tahoe and adds the missing ProGuard rules for the macOS menu.

v2.0.0

Released: 2026-05-14

Highlights

Plugin and namespace rename. id("dev.nucleusframework"), Maven group dev.nucleusframework, Kotlin root dev.nucleusframework.*. See migrate from 1.x.
nucleusApplication { } umbrella entry point. Single-instance lock, deep-link delivery, GraalVM init, AOT training, AutoLaunch and AUMID priming — all automatic.
Tao backend (decorated-window-tao). No-AWT path driven by the Rust tao crate. Wayland-native, multi-touch, pen pressure + tilt, native popups, drag-and-drop with diagnostics, embedded NativeView for any NSView / HWND / GtkWidget.
DecoratedWindow / DecoratedDialog as NucleusApplicationScope extensions — backend-agnostic dispatch, MaterialDecoratedWindow, JewelDecoratedWindow follow the same shape. CompositionLocals bridged across the Tao scene boundary.
macOS Liquid Glass via vtool patching. LC_BUILD_VERSION set to SDK 26 on the launcher so any JDK can opt into Liquid Glass at runtime — no Xcode 26-built JDK needed. Layered .icon directories supported on macOS 26+.
GraalVM Native Image: alpha. Static bytecode analyzer for reflection metadata, CleanupGraalvmMetadataTask, per-library L1 metadata with classpath-conditional filtering. End-to-end packaging pipeline (DMG, NSIS, DEB) for native images.

v1.11.0

Released: 2026-04-13

New modules

Notification Common (nucleus.notification-common) — Unified cross-platform notification API for Linux, Windows, and macOS behind a single DSL. Supports per-notification callbacks, up to 5 action buttons, image attachments, and dismiss handling.

New features

Reactive GNOME titlebar button layout — Decorated windows on Linux now read org.gnome.desktop.wm.preferences → button-layout via GSettings (libgio dlopen) to determine which buttons to show and on which side. The layout updates reactively when the user changes it in GNOME Tweaks or via gsettings set. Falls back to the default layout on KDE and other desktop environments. New rememberLinuxButtonLayout() composable for direct access.
GraalVM reachability metadata for FileKit and dbus-java — Apps using FileKit on Linux no longer need manual reachability entries for xdg-desktop-portal file dialogs. Includes new dbus-java conditional library metadata and Linux JDK internals (UnixSystem, NativePRNG$NonBlocking, CollationData).
Windows notification shortcut policies — New ShortcutPolicy enum on WindowsNotificationCenter for finer control over Start Menu shortcut creation behavior.
NucleusApp.appName and NucleusApp.aumid properties — Expose application name and AUMID for better configuration handling.

Bug fixes

Fix macOS multicolor accent color — system-color now returns null when macOS is set to multicolor mode instead of incorrectly returning the default blue.
Fix incremental build issues in GraalVM tasks — Disable state tracking on shared output directory modifications to prevent stale builds.
Fix nullable safety in JVM application tasks — Simplify runtime classpath and JavaExec argument handling by removing unnecessary optional chaining.

Improvements

Faster native library loading — NativeLibraryLoader now uses CRC-32-based fingerprints for cache validation, eliminating unnecessary I/O during checks.

Documentation

GraalVM status updated to alpha — GraalVM Native Image support is now labeled "alpha" instead of "experimental", reflecting the centralized reachability metadata now shipped by default.
New System Tray documentation — Full documentation section for ComposeNativeTray with screenshots and demo GIFs.
Landing page rewrite — Repositioned Nucleus as a native Electron successor with performance comparisons.

v1.10.0

Released: 2026-04-12

New modules

System Info (nucleus.system-info) — Cross-platform system information module with JNI native implementations for Linux, Windows, and macOS. Exposes CPU, memory, and GPU metrics in real-time.
- GPU detection and live metrics — Temperature, usage, VRAM, clock speeds, power draw, and fan speed on all platforms
- macOS: IOKit & SMC for GPU metrics, supports Apple Silicon and discrete GPUs
- Windows: DXGI for GPU enumeration, NVIDIA NVML + AMD ADL2 + Intel IGCL for live metrics, WMI thermal zone sensors, performance data for real-time CPU frequency
- Linux: NVIDIA NVML, AMD, and Intel GPU support
- Includes a demo application (system-info-demo) with lets-plot charting for CPU temperature history

Bug fixes

Fix latest.yml not generated for MSI and Portable formats — Update YML generation was limited to NSIS; it now covers MSI and Portable installers as well
Fix releaseDate precision in latest.yml — Use millisecond precision to match the electron-builder format expected by the auto-updater

CI

Add system-info native builds to CI — Build, verify, and upload native artifacts for all platforms in build-natives, pre-merge, publish-maven, publish-plugin, test-packaging, and test-graalvm workflows
Add MSVC setup step for Windows native builds — Ensure Visual Studio compiler is available in CI for Windows JNI compilation

v1.9.1

Released: 2026-04-10

Bug fixes

Fix DMG background image corruption — Preserve TIFF background byte-for-byte instead of re-encoding; adjust DMG window size to match the image rather than padding the image

v1.9.0

Released: 2026-04-09

New features

controlButtonIconColor / controlButtonIconHoverColor — New styling properties on DecoratedWindow to customize the color of window control button icons (close, minimize, maximize) and their hover state
titleBarClickable — New property to fix click handling in macOS fullscreen mode, ensuring title bar buttons remain interactive

Bug fixes

Fix macOS resize lag in decorated windows — Remove presentsWithTransaction which caused visible lag during window resize on macOS
Fix fullscreen title bar clicks on non-notch macOS screens — Title bar buttons were unresponsive in fullscreen on Macs without a notch
Fix crashes on macOS < 26 during resize and drag — Guard against Liquid Glass APIs unavailable on older macOS versions
Fix DPI scaling for min/max window size on Windows — Apply per-axis DPI scaling to minSize/maxSize constraints, and clean up resources on window dispose
Fix stale lock files in SingleInstanceManager — Detect and clean up orphaned lock files from previous crashed instances
Fix DMG background image self-destruction — Prevent the background image from being overwritten during the dmg-assets copy phase
Fix AppImage + Maximum compression warning — Remove invalid Fast compression level and warn when Maximum is used with AppImage (unsupported by mksquashfs)
Remove unused TitleBarIcons API — Clean up deprecated API from decorated-window

v1.8.8

Released: 2026-03-31

Bug fixes

Fix macOS RTL detection — Use NSLocale instead of NSApplication for layout direction detection, which works correctly in headless and early-startup contexts

CI

Add missing Linux native verification for decorated-window-core — Ensure Linux .so files are verified in CI workflows

v1.8.7

Released: 2026-03-30

New features

Localized Window/Help menu titles — macOS native menus now display localized titles based on the system locale, with a fix for GraalVM system locale initialization
Linux native layout direction detection — Detect RTL/LTR layout direction on Linux via Pango JNI, replacing the AWT ComponentOrientation approach that failed in native image builds

Bug fixes

Gracefully handle missing platform-specific native libraries — Runtime modules no longer crash when a native library is unavailable for the current platform; they fall back silently

CI

Disable ktlint for plugin-build — Exempt plugin-build from new ktlint rules to avoid false violations

v1.8.6

Released: 2026-03-30

Bug fixes

Fix macOS input method crash in GraalVM native image — Add missing reflection entries for macOS input method classes to platform metadata

v1.8.5

Released: 2026-03-30

Improvements

CI: menu-macos native build steps — Add menu-macos native library build and verification to all CI workflows

v1.8.4

Released: 2026-03-30

New features

Native Access documentation — Guide for the Nucleus Native Access API covering lifecycle details, supported types, and unsupported features

Bug fixes

Fix DMG background generation crash — Check ImageIO.write return value to prevent FileNotFoundException when the image format is unsupported

v1.8.3

Released: 2026-03-30

Bug fixes

Fix artifact naming — Revert example packageName to simple form for clean installer artifact names

v1.8.1

Released: 2026-03-30

CI

Add global-hotkey native artifacts to publish workflows — Download global-hotkey native libraries and install libglib2.0-dev in plugin publish and Maven publish CI pipelines

v1.8.0

Released: 2026-03-28

New modules

Notification macOS (nucleus.notification-macos) — Full UserNotifications API mapping via JNI. Supports rich notifications with title, subtitle, body, sound, badge, categories with actions, and delivery scheduling. Thread safety with EDT dispatch for delegate callbacks.
Notification Linux (nucleus.notification-linux) — Full freedesktop Desktop Notifications API mapping via JNI (D-Bus org.freedesktop.Notifications). Supports notification actions, icons, urgency levels, and expiration.
Notification Windows (nucleus.notification-windows) — Full Windows Toast Notifications API via JNI (WinRT). Rich toast templates with text, images, buttons, and audio.
Launcher Linux (nucleus.launcher-linux) — Full Unity Launcher API mapping via JNI (com.canonical.Unity.LauncherEntry + com.canonical.dbusmenu). Badge count, progress bar, urgency flag, and quicklist menus with D-Bus menu support. Compatible with GNOME, KDE Plasma, and other DEs.
Launcher macOS (nucleus.launcher-macos) — Dock menu API via JNI. Custom Dock context menu items with native callbacks. Requires CRITICAL_ALERT entitlement for certain notification features.
Launcher Windows (nucleus.launcher-windows) — Windows Launcher API via JNI (WinRT/COM). Badge notifications, Jump Lists (ICustomDestinationList), overlay icons, and thumbnail toolbar buttons (ITaskbarList3) on the taskbar.
Freedesktop Icons (nucleus.freedesktop-icons) — Type-safe constants for the freedesktop Icon Naming Specification. Shared dependency between notification-linux and launcher-linux.
Global Hotkey (nucleus.global-hotkey) — Cross-platform global keyboard shortcut registration.
- Windows: Low-level keyboard hook
- macOS: Carbon API (RegisterEventHotKey)
- Linux: X11 key grabbing + Wayland portal (org.freedesktop.portal.GlobalShortcuts)
- Thread-safe registration/unregistration with synchronized init
Menu macOS (nucleus.menu-macos) — Native macOS menu bar API via JNI. Includes GraalVM reachability metadata for JNI callbacks.
SF Symbols (nucleus.sf-symbols) — Apple SF Symbols integration module.

Bug fixes

Fix global hotkey UI freeze on Linux — Make portal binding non-blocking to avoid freezing the UI thread on Wayland, then dispatch to Dispatchers.IO
Fix Dispatchers.Main crash in example — Add coroutines-swing dependency for desktop Dispatchers.Main support

CI

Add global-hotkey native builds to CI — Build, verify, and upload native artifacts for all platforms across all CI workflows

v1.7.2

Released: 2026-03-25

New features

Webview, JNA, and SQLite JNI metadata — Add missing GraalVM reachability metadata for webview, JNA, and SQLite JNI classes to L1
Companion.serializer() metadata for @Serializable classes — The static analyzer now emits reflection entries for kotlinx.serialization Companion.serializer() methods automatically

Bug fixes

Fix proxy entries in cleanupGraalvmMetadata task — Handle proxy configuration entries that could cause the cleanup task to fail

v1.7.1

Released: 2026-03-25

New features

Expanded L1 library metadata — Additional agent-captured entries for common libraries
FileKit GraalVM metadata — Add reachability metadata for FileKit along with complete JDK/JNA entries

Bug fixes

Fix configuration cache serialization for nativeImageCompile — Resolve serialization errors when Gradle configuration cache is enabled by building native-image arguments at execution time

v1.7.0

Released: 2026-03-24

New features

Static bytecode analyzer for GraalVM reflection metadata — New AnalyzeStaticMetadataTask that scans compiled bytecode to automatically detect classes requiring reflection, JNI, and resource configuration. Eliminates most manual metadata authoring:
- JNI callback detection — finds native methods and their parameter/return types
- Resource scanning — detects getResource/getResourceAsStream calls
- Class loading wrappers — identifies Class.forName, MethodHandles.Lookup.findClass patterns
- JNI superclass resolution — includes parent classes needed for field access
- Enriched class entries — adds non-native methods and fields to JNI class metadata
CleanupGraalvmMetadataTask — New Gradle task that removes entries from your manual reachability-metadata.json that are already covered by Nucleus library metadata (L1/L2/L3). Keeps manual config minimal.
File association support for GraalVM native image on macOS — Register file type associations in the native image .app bundle so macOS opens files with your application.
macOS deployment target and SDK version patching — Automatically patch the Mach-O deployment target and SDK version in GraalVM native image binaries for macOS Liquid Glass compatibility.
Per-library L1 metadata — Split the monolithic L1 metadata file into per-library files with conditional filtering, so only relevant metadata is included based on actual classpath dependencies.
JNA GraalVM metadata — Add core JNA JNI requirements to L1 metadata.
AWT drag-and-drop and file open handler metadata — Add GraalVM reachability metadata for AWT drag-and-drop classes and macOS file open handlers.
Ktor CIO, SLF4J, and common JDK resource metadata — Additional L1 entries for Ktor CIO engine, SLF4J, and commonly used JDK internal classes.

Bug fixes

Fix agent metadata duplication — Deduplicate tracing agent output against Oracle Reachability Metadata Repository and static analysis results
Fix configuration cache serialization in runWithNativeAgent — Resolve Gradle serialization errors when configuration cache is enabled
Fix Aqua LAF resource pattern — Add glob pattern for Aqua Look-and-Feel resources to prevent agent duplication on macOS
Fix unsupported class file version in NativeMethodDetector — Handle newer class file versions gracefully instead of crashing
Fix JarResourceDetector false positives — Narrow path matching to avoid detecting unrelated resources

Breaking changes

Default GraalVM config directory changed — The default directory for manual GraalVM metadata is now graalvm/ instead of resources/. Existing projects should move their reachability-metadata.json to the new location.

v1.6.5

Released: 2026-03-23

New features

File association support for GraalVM native image on macOS — Register file type associations (CFBundleDocumentTypes) in the GraalVM native image .app bundle

Bug fixes

Fix ktlint violations in configureGraalvmApplication.kt

v1.6.4

Released: 2026-03-23

Bug fixes

Fix infinite recursion in fullscreen mouse event forwarding — Prevent stack overflow when forwarding mouse events in decorated window fullscreen mode

v1.6.2

Released: 2026-03-22

New features

appName property — New top-level property in nativeDistributions {} for the human-readable application display name (installer title, .desktop Name, Start Menu entry). Separates the display name from packageName, which remains the technical identifier used for executable and package file naming.

nativeDistributions {
    appName = "My App"            // Display name (installer, .desktop, Start Menu)
    linux { packageName = "myapp" }     // Technical: executable, .deb file name
    windows { packageName = "MyApp" }   // Technical: .exe name, MSI
}

Bug fixes

Fix MSI build failing with WiX LGHT0094: File:mainExecutable not found — The JVM packaging path now sets executableName on the electron-builder task, matching what the GraalVM path already did. Without it, electron-builder fell back to a mismatched lowercase name from package.json, causing WiX to fail.
Fix Linux .deb file and launcher using Gradle project name instead of linux.packageName — executableName now resolves to the platform-specific packageName (linux.packageName, windows.packageName, macOS.packageName) instead of the Gradle project name.
Fix productName missing in electron-builder YAML — When no top-level packageName was set, productName was omitted from the generated config. It now falls back to appName, then packageName, then executableName.
Fix package.json name field ignoring platform-specific package name — The generated package.json now uses executableName (platform-specific) for the name field, so the ${name} variable in the artifact name template resolves correctly.

v1.6.0

Released: 2026-03-22

New modules

Taskbar Progress (nucleus.taskbar-progress) — Native taskbar/dock progress bar and attention requests on all platforms. Shows download progress, build status, or any long-running operation directly in the OS taskbar. See Taskbar Progress.
- Windows: ITaskbarList3 (progress value/state) + FlashWindowEx (attention)
- macOS: NSDockTile with custom NSProgressIndicator overlay + NSApplication.requestUserAttention
- Linux: D-Bus com.canonical.Unity.LauncherEntry (GNOME, KDE Plasma, and compatible DEs)
- Five states: NO_PROGRESS, INDETERMINATE, NORMAL, ERROR, PAUSED
- Attention requests: INFORMATIONAL (brief flash) and CRITICAL (until focus)
App Metadata at Runtime (NucleusApp) — New singleton in core-runtime that exposes plugin-injected metadata at runtime: appId, version, vendor, description. Populated via system properties and a generated nucleus-app.properties classpath resource. See Runtime APIs.

New features

Centralized GraalVM native-image metadata — Nucleus now ships all generic and platform-specific reflection metadata out of the box, organized in three levels:
- L1 (graalvm-runtime JAR) — Generic cross-platform reflection entries for Compose Desktop, AWT/Swing, Skiko, security providers, font managers, and more (~300+ types). Automatically picked up from the classpath by native-image.
- L2 (Oracle Reachability Metadata Repository) — Automatic resolution of metadata for all runtime classpath dependencies from the Oracle GraalVM Reachability Metadata Repository. Covers popular libraries like ktor, kotlinx.serialization, SLF4J, Logback, and many others. Enabled by default.
- L3 (plugin platform metadata) — Platform-specific AWT/Java2D/font/security metadata for macOS, Windows, and Linux, shipped inside the Gradle plugin. Written to the build directory at compile time — no per-platform when block needed in your build script.
Users no longer need to copy thousands of reflection entries from the example app. Most applications will work without any manual reflection configuration. See Centralized Reflection Metadata.
metadataRepository {} DSL — New configuration block in graalvm {} to control the Oracle Reachability Metadata Repository integration. Supports enabled, version, excludedModules, and moduleToConfigVersion. Enabled by default with version 0.10.6.
resolveReachabilityMetadata task — New Gradle task that resolves Oracle Reachability Metadata Repository entries for all runtime classpath dependencies. Runs automatically before packageGraalvmNative.
Auto-include Compose Multiplatform resources — graalvm-runtime now includes composeResources/.* in the native-image.properties resource patterns, so all Compose resources (images, strings, fonts loaded via Res.*) are included automatically.
Agent merge and deduplication — The runWithNativeAgent task now deduplicates agent output against library metadata already shipped in classpath JARs. This prevents the tracing agent from re-adding entries that Nucleus (or other libraries) already provide, keeping your app-specific config clean and minimal.
All JDK locale bundles auto-included — Locale-specific resource bundles are now part of the centralized metadata, reducing runtime MissingResourceException crashes.
UpdateLevel enum — UpdateResult.Available now carries an UpdateLevel (MAJOR, MINOR, PATCH, PRE_RELEASE) computed by comparing semantic version numbers. Allows the UI to adapt messaging based on update significance. See Auto Update.
Post-update detection — New NucleusUpdater.consumeUpdateEvent() and wasJustUpdated() methods detect that the app was just updated and return an UpdateEvent with previousVersion, newVersion, and updateLevel. Useful for "What's new" dialogs, migrations, or analytics. See Auto Update.
Default jlink modules expanded — java.net.http and jdk.accessibility are now included in the default jlink module list alongside java.base, java.desktop, java.logging, and jdk.crypto.ec. No need to add them manually.
Auto-generate main class reflection metadata — The plugin now automatically adds the application's main class to the GraalVM native-image reflection configuration, eliminating one manual step.

Bug fixes

Eliminate resize flash on DecoratedDialog (Windows) — Add native WndProc subclass for dialogs that handles WM_ERASEBKGND and WM_WINDOWPOSCHANGING to prevent white flash during dialog resize.
Fix WM_CLASS showing LambdaForm class name in GNOME under native image — Add @TargetClass substitution for XToolkit.getAWTAppClassName() that returns the real app name from NucleusApp.appId instead of the internal LambdaForm class.
Fix Linux executable alias for GraalVM native image layout — Support the native image binary directory structure when creating the executable symlink.
Align native image WM_CLASS with .desktop StartupWMClass — Ensures the GNOME taskbar icon matches the .desktop file.
High-quality Linux icon generation — Replace single-step Graphics2D resizing with Thumbnailator progressive bilinear downscaling, fixing blurry icons in DEB packages at small sizes (16x16, 32x32).
Prevent reflection fallback crash in native image — When the JNI library is loaded, return its result directly without falling through to reflection-based sun.awt.AWTAccessor access, which triggers IllegalAccessException under JPMS in native image.
Rethrow CancellationException in updater — Prevent coroutine scope leaks when update operations are cancelled.
npm 11 compatibility — Multiple fixes for ECOMPROMISED errors in parallel builds: isolated npm prefix, separate npmrc files, ensure npm prefix lib directory exists.
Fix Jewel decorated window border on Linux light mode — Use subtle semi-transparent border (Color(0x12FFFFFF)) on Linux instead of opaque Jewel borders.normal color. On GNOME/KDE, the window border now blends with the native window chrome in light mode instead of showing an obtrusive gray outline.

Breaking changes

Sample app reachability-metadata.json files drastically reduced — If you copied metadata from the example or jewel-sample apps, the source files are now nearly empty (framework entries moved to L1/L3). This is not a code-breaking change, but you should clean up your own metadata files — see the migration guide.
Removed old-format config files from samples — predefined-classes-config.json, proxy-config.json, resource-config.json, and serialization-config.json have been removed. All configuration is consolidated in reachability-metadata.json.
UpdateResult.Available signature changed — Now includes a level: UpdateLevel field. If you destructure UpdateResult.Available, add the new field.

v1.5.9

Released: 2026-03-20

New features

runGraalvmNative task — New Gradle task that builds and runs the GraalVM native image directly, without packaging into an installer. Useful for quick iteration during development.

Breaking changes

Remove release build type for GraalVM — GraalVM native-image tasks no longer have release variants (packageReleaseGraalvmNative, etc.). ProGuard is redundant with native-image's closed-world dead code elimination and harmful because it can rename classes referenced in reachability-metadata.json. See No Release Build Type.

v1.5.8

Released: 2026-03-20

New features

Automatic resource inclusion for GraalVM native-image — graalvm-runtime now ships a native-image.properties that auto-includes all .svg, .ttf, .otf resources, nucleus/native/* JNI libraries, and META-INF/services/* descriptors via glob patterns. Projects no longer need to run the tracing agent just to discover icon and font resources — they are embedded in the native binary automatically. The tracing agent is still required for reflection, JNI, resource bundles, and non-standard resources. See Automatic Resource Inclusion.

v1.5.7

Released: 2026-03-20

Bug fixes

Fix first-frame flash when starting maximized — Override state.size with the screen work area (bounds minus taskbar insets, DPI-scaled) before the Window composable, so the AWT window is created at the correct maximized dimensions from the start. The previous approach (PreSizeIfMaximized via DisposableEffect inside Window) ran too late — the first Skia frame had already rendered at the default size. Affects the JNI DecoratedWindow variant.

v1.5.6

Released: 2026-03-20

Bug fixes

Fix first-frame flash when starting maximized (superseded by v1.5.7) — Initial attempt using DisposableEffect inside Window to pre-size the AWT window.

v1.5.5

Released: 2026-03-19

New features

Add SystemNative enum value to ControlButtonsDirection — A new SystemNative variant that reads the native OS locale from JVM startup system properties (user.language, user.country, user.variant) instead of Locale.getDefault(). Unlike the System mode which reflects the current JVM default locale (mutable via Locale.setDefault()), SystemNative is immune to runtime locale overrides and always reflects the true operating system configuration. Useful for applications that temporarily change the UI locale but want control buttons to match the native system direction.

v1.5.4

Released: 2026-03-19

New features

Add controlButtonsDirection to DialogTitleBar — Propagate controlButtonsDirection through the entire DialogTitleBar chain: DialogTitleBarImpl (core), platform-specific implementations (JNI + JBR for Linux/Windows/macOS), and themed wrappers (JewelDialogTitleBar, Material 2 and Material 3 MaterialDialogTitleBar). Aligns dialog title bars with the existing TitleBar API.

v1.5.3

Released: 2026-03-19

Bug fixes

Fix control buttons global position when content and controls share the same edge — End-aligned items (control buttons) are now placed before Start-aligned items in the title bar layout. Previously, in RTL apps with LTR control buttons (or vice versa), the content would claim the edge first, pushing buttons inward. Affects all platforms.

v1.5.2

Released: 2026-03-19

Bug fixes

Sync control buttons layout direction with controlButtonsDirection — Control buttons (close, maximize, minimize) now inherit the resolved controlButtonsDirection as their LocalLayoutDirection. Previously, in RTL apps with ControlButtonsDirection.System, button internals were rendered in RTL even though the buttons were placed on the correct side. Introduces LocalControlButtonsDirection composition local, consumed by WindowControlArea and WindowsWindowControlArea.

v1.5.1

Released: 2026-03-19

Improvements

Add controlButtonsDirection to JewelTitleBar and Material 2 MaterialTitleBar — Forward the controlButtonsDirection parameter to the underlying TitleBar so consumers can control window button placement independently of the content layout direction. Material 3 MaterialTitleBar already had this parameter; Jewel and Material 2 are now aligned.

v1.5.0

Released: 2026-03-19

New features

Automatic Liquid Glass support via macOsSdkVersion — Nucleus now automatically patches the app launcher's LC_BUILD_VERSION Mach-O header to macOS SDK 26.0 using vtool, enabling Liquid Glass window decorations (larger traffic lights, rounded corners). This works with any JDK — a JDK compiled with Xcode 26 is no longer required. The run task uses a cached patched copy of the JVM, while distributable builds patch the launcher before signing. Controlled via macOS { macOsSdkVersion = "26.0" } (enabled by default, set to null to disable). Requires Xcode Command Line Tools. See macOS 26 Window Appearance.
Modifier.clientRegion() for JBR title bar hit testing — New modifier function that registers composable elements as interactive client regions within a DecoratedWindow's title bar. Client regions receive mouse events (clicks, presses) instead of triggering window dragging. Uses AWT-level mouse listeners with precise coordinate-based hit testing, replacing the old pointer-event-based customTitleBarMouseEventHandler. See Decorated Window.
decorated-window-jewel module — New module providing Jewel theme integration for DecoratedWindow. Used by the jewel-sample app.
decorated-window-material2 module — New module providing Material 2 theme color mapping for DecoratedWindow, complementing the existing Material 3 module.
decorated-window-material3 module — Renamed from decorated-window-material for clarity. Provides Material 3 color mapping for DecoratedWindow.
Decouple control buttons direction from title bar content direction — Window control buttons (close, minimize, maximize) now follow their platform-native position regardless of the title bar's layout direction.
Intercept system quit events — onCloseRequest in DecoratedWindow now intercepts macOS Cmd+Q and Dock quit events, giving the app a chance to confirm or cancel the quit.
backgroundContent slot in TitleBar — New composable slot for rendering content behind the title bar (e.g. a gradient or blurred background).
Surface notarization details on failure — Notarization errors now include the Apple submission ID and log URL for easier debugging.

Bug fixes

Fix title bar drag on Windows (decorated-window-jbr) — Window dragging via the title bar no longer occasionally fails on the first attempt when another window has focus. The new WindowMouseEventEffect approach uses AWT mouse listeners for reliable hit-test forwarding to JBR's CustomTitleBar, fixing the intermittent missed drag events. (#53)
Promote core-runtime to api scope in updater-runtime and system-color so consumers no longer need to declare it separately.
Include generic provider in publish mode detection.
Skip Flatpak packaging gracefully when flatpak CLI is missing.
Use sandboxed flag for jpackage macAppStore instead of relying on targetFormat.
Propagate DMG contents entries to universal CI build.
Compensate macOS title bar height in DMG background image.
Migrate from deprecated painterResource to ImageVector icons.
Replace deprecated Compose accessors with version catalog entries.
Add Gradle 9.4 task caching and normalization annotations across all task classes.

Deprecations

decorated-window-material renamed — Use decorated-window-material3 instead.

v1.4.8

Released: 2026-03-18

New features

Intercept system quit events via onCloseRequest — DecoratedWindow now intercepts macOS Cmd+Q and Dock quit events.
Surface notarization submission ID and Apple log on failure — Easier debugging of notarization issues.

Bug fixes

Reliable title bar drag via AWT-level clientRegion hit testing — Fixes intermittent missed drag events on Windows when another window has focus.
Promote core-runtime to api scope in updater-runtime and system-color.
Include generic provider in publish mode detection.
Skip Flatpak packaging gracefully when flatpak CLI is missing.
Use sandboxed flag for jpackage macAppStore instead of targetFormat.

v1.4.7

Released: 2026-03-11

New features

backgroundContent slot in TitleBar and MaterialTitleBar — New composable slot for rendering content behind the title bar (e.g. a gradient or blurred background).

v1.4.6

Released: 2026-03-11

Bug fixes

Fix objc_retain crash on freed NSWindow during disposal — Prevent crash when the Objective-C runtime attempts to retain an already-deallocated NSWindow reference from a JNI callback.

v1.4.5

Released: 2026-03-10

Bug fixes

Fix crash on __weak NSWindow reference from JNI thread during disposal — Prevent crash when a weak reference to NSWindow is accessed from a JNI thread after the window has been deallocated.

v1.4.4

Released: 2026-03-10

Bug fixes

Fix crash on NSWindow cleanup during fullscreen transition — Prevent crash when the window is being cleaned up while a fullscreen animation is still in progress.

v1.4.3

Released: 2026-03-10

New features

Safari-like fullscreen title bar behavior on macOS — Fullscreen title bar renders as a translucent overlay that pushes content down, matching native Safari behavior.
Executable type and version detection for GraalVM native-image builds — ExecutableType now correctly identifies GraalVM native binaries and their version.

Bug fixes

Enable redirect following in NativeHttpClient and add SSL lib to native-image resources.

v1.4.2

Released: 2026-03-10

Bug fixes

Harden fullscreen state management on Windows — Fix multiple fullscreen-related issues:
- Improve fullscreen exit state restoration and maximize handling.
- Override delegate placement on fullscreen exit with saved state.
- Restore correct placement on fullscreen exit and eliminate maximize glitch.
- Restore pointer events to content area in fullscreen mode.

v1.4.1

Released: 2026-03-10

Bug fixes

Add missing ProGuard rules for system-color, energy-manager, and linux-hidpi.
Apply macOSLargeCornerRadius to jewel-sample title bar.
Update GraalVM reachability metadata for macOS.

v1.4.0

Released: 2026-03-09

New features

Native fullscreen with sliding title bar — Platform-native fullscreen experience: Safari-like on macOS, Edge-like on Windows, Firefox-like on Linux. When the window enters fullscreen, the title bar becomes a floating overlay that slides down on hover near the top edge and slides back up when the pointer moves away. Enable with Modifier.newFullscreenControls() on TitleBar / MaterialTitleBar. See Decorated Window.
macOS large corner radius — New Modifier.macOSLargeCornerRadius() modifier applies the 26pt window corner radius used by Finder and Safari. Installs an invisible NSToolbar and repositions traffic light buttons to match Apple's native inset. See Decorated Window.
System Color module (nucleus.system-color) — Reactive detection of OS accent color and high contrast mode via JNI. Supports macOS (NSColor.controlAccentColor), Windows (DWM registry), and Linux (XDG Desktop Portal D-Bus). Composable APIs: systemAccentColor(), isSystemInHighContrast(). See System Color.
Energy Manager module (nucleus.energy-manager) — Energy management with three tiers: full efficiency mode (EcoQoS + IDLE_PRIORITY_CLASS on Windows, PRIO_DARWIN_BG + task_policy_set on macOS, nice +19/ioprio/timerslack on Linux), light efficiency mode (CPU deprioritization only, no I/O throttling), and thread-level efficiency mode. Includes screen-awake (caffeine) API to prevent display sleep (IOPMAssertion on macOS, SetThreadExecutionState on Windows, D-Bus/X11 on Linux). Coroutine helpers: withEfficiencyMode(), withLightEfficiencyMode(). See Energy Manager.
Auto-center DecoratedDialog on parent window — Dialogs are now automatically centered on their parent with reliable positioning via windowOpened event. See Decorated Window.
macOS RTL traffic-light support — Correct traffic light button positioning in right-to-left layouts. See Decorated Window.
Centralized native library loading — New NativeLibraryLoader with persistent cache replaces per-module loading logic.
Fullscreen-aware window controls — Maximize button shows exit-fullscreen icon when in fullscreen mode on Linux and Windows, with new SVG icon variants (active/inactive/dark). See Decorated Window.
AWT window background sync on macOS — Idempotent property application prevents redundant PropertyChangeEvent firings, reducing visual jitter during layout passes.
Sample CMP module (sample-cmp) — New Kotlin Multiplatform Compose sample with Android and Desktop targets.
Example app gallery — Material 3 component showcase with actions, communication, containment, selection, text inputs, typography, elevation, and color screens.

Bug fixes

Fix Windows fullscreen — Compose for Desktop does not handle fullscreen correctly on Windows (window does not cover the taskbar). Now uses native Win32 APIs for true fullscreen, matching Edge and other native Windows applications.
Eliminate white resize flash on Windows — Adjust Skiko's clear color to transparent for dark themes and synchronize DWM caption/border colors for consistent Windows 11 window chrome styling.
Skip Android configurations in CleanNativeLibsTransform — Fixes build issues when Android targets are present. (#79)
Skip ZIP stapling to preserve blockmap — Prevents breaking auto-update blockmap integrity during notarization. (#70)
Detect target arch from JDK release file for cross-building — Fixes architecture detection when cross-compiling. (#71)
Move Windows dark mode monitoring to native thread for reliability.
Correct D-Bus ReadOne variant parsing for Linux accent color.

Deprecations

appStore property deprecated — PKG distributions are now always treated as App Store builds. The appStore property is no longer needed. (#65)

v1.3.8

Released: 2026-03-02

Bug fixes

Match native macOS traffic light button spacing.

v1.3.7

Released: 2026-03-02

Bug fixes

Handle ZIP stapling by extracting .app, stapling, and re-zipping.
Remove deprecated internetEnabled DMG setting.

v1.3.6

Released: 2026-03-02

Bug fixes

Fix fullscreen button transitions and alignment.
Restore title bar appearance before fullscreen exit animation.
Fallback to default icon for GraalVM native image on Windows.
Update latest-mac.yml checksums and file sizes after notarization.
Remove xvfb-run from test-graalvm workflow (Xvfb already started by setup-nucleus).

v1.3.5

Released: 2026-03-02

Bug fixes

Add homepage to jewel-sample nativeDistributions for electron-builder DEB packaging.

v1.3.4

Released: 2026-03-02

Bug fixes

Remove xvfb-run from graalvm workflow (Xvfb already started by setup-nucleus).

v1.3.3

Released: 2026-03-02

New features

Add graalvm option to setup-nucleus composite action.
Configure Windows code signing for jewel-sample using shared certificate.

Bug fixes

Add libx11-dev and libdbus-1-dev to graalvm release Linux dependencies.
Configure jewel-sample nativeDistributions with icons, deb maintainer, and platform settings.
Use packageGraalvmDeb/Dmg/Nsis tasks instead of raw native image output.

v1.3.2

Released: 2026-03-02

No user-facing changes (tag only).

v1.3.1

Released: 2026-03-02

Bug fixes

Use packageGraalvmDeb/Dmg/Nsis tasks instead of raw native image output.
Add missing native artifact downloads and libx11-dev to publish-plugin workflow.
Pass repository to gh release commands in graalvm workflow.
Remove custom icons from jewel-sample, use default icons instead.

v1.3.0

Released: 2026-03-02

New features

GraalVM Native Image support (experimental) — Compile Compose Desktop apps into standalone native binaries with fast cold boot (~0.5 s), lower memory usage (~100–150 MB vs ~300–400 MB on JVM), and smaller bundles. New graalvm {} DSL block, runWithNativeAgent task for reflection metadata collection, and packageGraalvmNative / packageGraalvmDeb / packageGraalvmDmg / packageGraalvmNsis packaging tasks. Requires BellSoft Liberica NIK 25. See GraalVM Native Image.
New graalvm-runtime module (nucleus.graalvm-runtime) — Centralizes native-image bootstrap logic into a single GraalVmInitializer.initialize() call: Metal L&F, java.home/java.library.path setup, charset/fontmanager early init, Linux HiDPI detection, and GraalVM @TargetClass font substitutions for Windows and Linux.
Decorated Window module split — decorated-window split into decorated-window-core, decorated-window-jbr (JBR-based, same behavior as before), and decorated-window-jni (JBR-free, works with GraalVM). See Migration Guide below.
decorated-window-jni module — New JNI-based implementation of DecoratedWindow that works without JetBrains Runtime, including support for Linux via native JNI bridge. Compatible with GraalVM Native Image.
Linux HiDPI scaling support — Native GDK_SCALE handling for correct rendering on HiDPI Linux displays.
Auto-notarize macOS distributions — packageDistributionForCurrentOS now automatically notarizes on macOS when notarization credentials are configured.
Jewel Sample app — Standalone Jewel UI showcase with GraalVM native image CI, platform-specific packaging, and Windows code signing.

Bug fixes

Replace OBJC_ASSOCIATION_ASSIGN with RETAIN_NONATOMIC to prevent dangling pointer on macOS.
Resolve fontmanager loading on Linux native image.
Ensure Skiko library is extracted and loaded in GraalVM Native Image.
Use onlyIf instead of enabled for native build tasks (configuration cache compatibility).
Detect unconsumed double-clicks before triggering macOS zoom.

Documentation

GraalVM Native Image guide for Compose Desktop.
macOS 26 window appearance guide for JVM and native image.
Linux HiDPI runtime documentation.
AOT cache documentation rewrite with motivation and Project Leyden reference.
Decorated window docs update with changelog and migration guide.

CI/CD

GraalVM native-image build workflow for PR CI.
CI workflow to release Jewel Sample as GraalVM native image on tags.
Migrate detekt to 2.0.0-alpha.2 for JDK 25 support.

Migration guide: 1.2.x → 1.3.x

Decorated window: monolithic module split

The decorated-window module has been split into three modules:

Before (1.2.x)	After (1.3.x)
`nucleus.decorated-window`	`nucleus.decorated-window-core` (shared)
	`nucleus.decorated-window-jbr` (JBR implementation)
	`nucleus.decorated-window-jni` (JNI implementation, new)

Dependency update — replace:

implementation("dev.nucleusframework:nucleus.decorated-window:2.3.0")

With one of:

// JBR-based (same behavior as before)
implementation("dev.nucleusframework:nucleus.decorated-window-jbr:2.3.0")

// JNI-based (no JBR dependency, works with GraalVM)
implementation("dev.nucleusframework:nucleus.decorated-window-jni:2.3.0")

Breaking changes in TitleBarColors — the following fields have been removed:

titlePaneButtonHoveredBackground
titlePaneButtonPressedBackground
titlePaneCloseButtonHoveredBackground
titlePaneCloseButtonPressedBackground

These platform-specific button state colors are now handled internally by each module's native implementation. If you were constructing TitleBarColors explicitly with these fields, remove them.

No other code changes required — all composable APIs (DecoratedWindow, DecoratedDialog, TitleBar, DialogTitleBar), scopes, and state types are identical. No import changes needed — the package remains dev.nucleusframework.window.

See Decorated Window for full details on choosing between JBR and JNI.

v1.2.7

Released: 2026-02-22

Bug fixes

Use per-platform winCodeSign archives to fix AppX build on Windows.

v1.2.6

Released: 2026-02-22

Bug fixes

Preserve sandbox entitlements when re-signing PKG for App Store without certificate.

v1.2.5

Released: 2026-02-22

Bug fixes

Map PublishMode.Auto to "onTag" for electron-builder.

v1.2.4

Released: 2026-02-22

Bug fixes

Add decorated-window native macOS build and publish steps to CI.

v1.2.3

Released: 2026-02-21

Bug fixes

Round bottom corners of decorated window on GNOME.
Use Developer ID signing for DMG/ZIP formats to pass notarization.

v1.2.2

Released: 2026-02-20

New features

Generic publish provider — New generic provider for self-hosted update servers, alongside GitHub and S3. See Auto-Update.

v1.2.1

Released: 2026-02-20

Bug fixes

Prevent crash when no publish provider is configured in electron-builder.

v1.2.0

Released: 2026-02-20

New features

Native SSL module (nucleus.native-ssl) — Load OS-trusted certificates via JNI: macOS Keychain (SecTrustCopyAnchorCertificates), Windows Crypt32, Linux system cert paths. Aligns with JetBrains jvm-native-trusted-roots. Includes cryptographic isSelfSigned verification on macOS. See Native SSL.
Native HTTP modules (nucleus.native-http, nucleus.native-http-okhttp, nucleus.native-http-ktor) — HTTP clients that use the OS trust store out of the box, with OkHttp and Ktor adapters. See Native HTTP.
CA certificate patching — New build-time task patches the JVM's cacerts with OS-trusted certificates.
ProGuard JNI keep rules — Default ProGuard template now includes keep rules for native-ssl.

Documentation

Add native-ssl and native-http module documentation.
Update comparison with CA certificate patching and native SSL details.

v1.1.6

Released: 2026-02-20

New features

Default artifactName to ${name}-${version}-${os}-${arch}.${ext} for consistent naming.

Bug fixes

Preserve symlinks when copying app image on macOS.
Isolate app image and electron-builder cache per task.
Add PR packaging test workflow for all platforms.

v1.1.4

Released: 2026-02-19

Bug fixes

Isolate npm cache per task to prevent EPERM on parallel builds.
Resolve configuration cache serialization error for sandboxed pipeline.

v1.1.3

Released: 2026-02-19

Bug fixes

Default setup-node to true and remove npm cache workaround.

v1.1.2

Released: 2026-02-19

Bug fixes

Clean npm cache on Windows runners to prevent ECOMPROMISED errors.
Only enable sandboxed pipeline for OS-compatible store formats.

Documentation

Add TargetFormat import change note (from compose to nucleus) to migration guide.
Add ProGuard rules documentation for JNI libraries.
Add LLM documentation (llms.txt, llms-full.txt).
Add packaging tools comparison page.

v1.1.1

Released: 2026-02-19

Bug fixes

Unseal jbr-api JAR to prevent sealing violation on startup.

v1.1.0

Released: 2026-02-19

New features

Decorated Window module (nucleus.decorated-window) — Custom window decorations with native title bars, traffic light buttons on macOS, window controls on Windows (close/minimize/maximize), and GNOME/KDE styling on Linux. Replaces JNA/Unsafe with an Objective-C JNI bridge on macOS. See Decorated Window.
Material theme module (nucleus.decorated-window-material) — Automatic Material 3 color mapping for DecoratedWindow.
Darkmode Detector module (nucleus.darkmode-detector) — Reactive OS dark mode detection via JNI on macOS, Windows, and Linux (XDG Desktop Portal). Replaces the JNA-based implementation with pure JNI for smaller binaries and no external dependencies. See Darkmode Detector.
RTL layout support — Title bar respects right-to-left layout direction with dedicated toggle icons.
KDE Breeze window styling — Dedicated icon set, corner radius, and hover/pressed states matching KDE Plasma.
GNOME window styling — Rounded corners, subtle border, and inactive title bar styling matching GNOME/Adwaita.

Bug fixes

Dispatch AppKit calls to main thread in JNI bridge.
Hide border when window is maximized in any direction or fills the screen.
Use rounded border shape matching GNOME/KDE window corners.

v1.0.9

Released: 2026-02-18

Bug fixes

Flatten native lib extraction to resources root for sandboxed builds.

v1.0.8

Released: 2026-02-18

Bug fixes

Move native dylibs to Contents/Frameworks/ for sandboxed macOS builds.
Place universal-arch native libs in resources root.

v1.0.7

Released: 2026-02-18

Bug fixes

Prevent JAR filename collisions in sandboxed pipeline.
Ad-hoc sign jspawnhelper instead of stripping signature.

v1.0.6

Released: 2026-02-18

Bug fixes

Inject application-identifier for App Store signing and fix configuration cache.

v1.0.5

Released: 2026-02-17

Bug fixes

Bypass electron-builder for App Store PKG signing.
Use full installer identity for PKG signing.

v1.0.4

Released: 2026-02-17

Bug fixes

Re-sign macOS app after .cfg modification for PKG builds.
Use separate sandboxed entitlements for App Store PKG signing.

v1.0.3

Released: 2026-02-17

Bug fixes

Strip certificate prefix from PKG identity for electron-builder.

v1.0.2

Released: 2026-02-17

New features

installAndQuit() — Silent background update API that installs the update and exits without restarting.

v1.0.1

Released: 2026-02-17

Bug fixes

Resolve Gradle configuration cache serialization failures.
Derive plugin version from Git tag instead of gradle.properties.
Move installationPath to macOS-only DSL.

v1.0.0

Released: 2026-02-17

Initial release — fork of the JetBrains Compose Desktop Gradle plugin, repackaged as Nucleus with extended packaging, distribution, and runtime features.

Packaging and distribution

Electron-builder backend — DMG, PKG, NSIS, NSIS Web, AppImage, DEB, RPM, Snap, and AppX formats. Replaces jpackage for installer generation.
macOS code signing and notarization — Developer ID and App Store signing, automatic notarization via notarytool.
macOS App Sandbox — Sandboxed PKG builds with JNI library extraction, entitlements management, and provisioning profiles.
Windows code signing — SignTool integration with SHA-256 hashing.
AppX packaging — Windows Store packaging with tile assets and identity configuration.
DMG customization — Background images, icon positioning, window size, badge icons, and format selection.
Layered icons — macOS 26+ .icon directory support for dynamic tilt/depth effects.
Splash screen — Splash image support in JVM launcher.
Universal macOS binaries — CI workflow for lipo-based fat binaries (Apple Silicon + Intel).
Type-safe DSL — Enums for target formats, publish modes, and compression settings replace raw strings.
Linux packaging options — startupWMClass, debDepends, rpmRequires, debCompression, rpmCompression, after-install scripts, and architecture suffixes.
File associations — macOS CFBundleURLTypes injection and Linux/Windows file association support via electron-builder.

Runtime modules

core-runtime — Executable type detection, platform identification, SingleInstanceManager, DeepLinkHandler.
aot-runtime — AOT cache mode detection for JDK 25+ (Project Leyden). AOT cache generation task with safety timeout.
updater-runtime — Auto-update engine with GitHub and S3 providers. SHA-512 verification, progress tracking, installAndRestart(). Platform-specific install strategies: detached shell script on macOS, background PowerShell on Windows, AppImage replacement on Linux.

Build and CI

Composite actions — setup-nucleus, update-yml, and release publishing actions.
Cross-platform release workflow — macOS (arm64 + x64 + universal), Windows (x64 + arm64), Linux (x64 + arm64).
Configuration cache support — Full Gradle configuration cache compatibility.
Plugin version from Git tag — No manual version management in gradle.properties.

What's next

Migrate from 1.x — the plugin id, namespace, and API changes for the 2.0 upgrade.
Quickstart — build and run your first Nucleus app.
GraalVM Native Image — the native-image pipeline referenced throughout these notes.
Auto-update — the updater APIs mentioned across several releases.

Changelog